This is an automated email from the ASF dual-hosted git repository.
chaokunyang pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/fory.git
The following commit(s) were added to refs/heads/main by this push:
new d89dd0c99 docs: refactor agents.md to reduce token usage (#3538)
d89dd0c99 is described below
commit d89dd0c9941375ba4ba09e94698df7516e08db20
Author: Shawn Yang <[email protected]>
AuthorDate: Mon Apr 6 13:44:34 2026 +0800
docs: refactor agents.md to reduce token usage (#3538)
## Why?
## What does this PR do?
## Related issues
## AI Contribution Checklist
- [ ] Substantial AI assistance was used in this PR: `yes` / `no`
- [ ] If `yes`, I included a completed [AI Contribution
Checklist](https://github.com/apache/fory/blob/main/AI_POLICY.md#9-contributor-checklist-for-ai-assisted-prs)
in this PR description and the required `AI Usage Disclosure`.
## Does this PR introduce any user-facing change?
- [ ] Does this PR introduce any public API change?
- [ ] Does this PR introduce any binary protocol compatibility change?
## Benchmark
---
.agents/README.md | 50 ++
.agents/ci-and-pr.md | 57 ++
.agents/docs-and-formatting.md | 34 +
.agents/languages/cpp.md | 59 ++
.agents/languages/csharp.md | 41 +
.agents/languages/dart.md | 23 +
.agents/languages/go.md | 53 ++
.agents/languages/java.md | 61 ++
.agents/languages/javascript.md | 21 +
.agents/languages/kotlin.md | 18 +
.agents/languages/python.md | 66 ++
.agents/languages/rust.md | 75 ++
.agents/languages/scala.md | 21 +
.agents/languages/swift.md | 40 +
.agents/repo-reference.md | 106 +++
.agents/skills/fory-code-review/SKILL.md | 1 +
.../references/validation-command-matrix.md | 2 +
.../skills/fory-performance-optimization/SKILL.md | 2 +-
.../references/language-command-matrix.md | 2 +
.agents/testing/integration-tests.md | 43 +
AGENTS.md | 882 +++------------------
21 files changed, 876 insertions(+), 781 deletions(-)
diff --git a/.agents/README.md b/.agents/README.md
new file mode 100644
index 000000000..eb201cd9f
--- /dev/null
+++ b/.agents/README.md
@@ -0,0 +1,50 @@
+# Agent Reference Index
+
+Load `AGENTS.md` first. Do not load every file under `.agents/` by default;
read only the files that match the task.
+
+## Shared References
+
+- `repo-reference.md`: repo layout, protocol overview, compiler notes, and
runtime map.
+- `docs-and-formatting.md`: docs, specs, markdown formatting, publishing
notes, and generated-artifact rules.
+- `ci-and-pr.md`: GitHub Actions triage, PR expectations, and commit message
format.
+- `testing/integration-tests.md`: `integration_tests/` prerequisites,
regeneration rules, and commands.
+
+## Runtime References
+
+- `languages/java.md`: Java runtime rules, module map, Maven commands, and
Java-specific debugging.
+- `languages/csharp.md`: C# rules, `dotnet` commands, and Java-driven C# xlang
validation.
+- `languages/cpp.md`: C++ rules, Bazel/arch constraints, core layout, and
debugging/profile pointers.
+- `languages/python.md`: Python/Cython modes, Bazel build variants, tests, and
debugging workflow.
+- `languages/go.md`: Go rules, `go test` workflow, and panic/debug guidance.
+- `languages/rust.md`: Rust rules, cargo workflow, and debug/backtrace
guidance.
+- `languages/swift.md`: Swift rules, lint/test workflow, and Java-driven xlang
validation.
+- `languages/javascript.md`: JavaScript/TypeScript commands and
package-manager expectations.
+- `languages/dart.md`: Dart codegen, test, and analysis commands.
+- `languages/kotlin.md`: Kotlin build/test commands and dependency on
installed Java artifacts.
+- `languages/scala.md`: Scala build/test/format commands and dependency on
installed Java artifacts.
+
+## Common Loading Recipes
+
+- Java or JVM runtime work:
+ - `AGENTS.md`
+ - `languages/java.md`
+ - `repo-reference.md`
+- Cross-language protocol or xlang work:
+ - `AGENTS.md`
+ - `docs-and-formatting.md`
+ - `testing/integration-tests.md`
+ - every touched runtime file under `languages/`
+- Performance work:
+ - `AGENTS.md`
+ - relevant runtime file under `languages/`
+ - `docs-and-formatting.md`
+ - skill-specific references if using a performance skill
+- PR review or CI triage:
+ - `AGENTS.md`
+ - `ci-and-pr.md`
+ - relevant runtime file under `languages/`
+
+## Canonicality
+
+- Treat the files in this directory as the canonical agent-specific guidance.
+- Existing skill reference matrices under `.agents/skills/` are task-focused
quick references; when they overlap with runtime rules, prefer the matching
file in `languages/` or `testing/`.
diff --git a/.agents/ci-and-pr.md b/.agents/ci-and-pr.md
new file mode 100644
index 000000000..c21a3b00e
--- /dev/null
+++ b/.agents/ci-and-pr.md
@@ -0,0 +1,57 @@
+# CI And PR Guidance
+
+Load this file when triaging GitHub Actions, preparing a pull request, or
writing commit messages.
+
+## Workflow Pointers
+
+- `ci.yml`: main CI workflow across languages
+- `build-native-*.yml`: macOS and Windows Python wheel builds
+- `build-containerized-*.yml`: Linux containerized Python wheel builds
+- `lint.yml`: formatting and lint checks
+- `pr-lint.yml`: PR title and PR-specific checks
+
+## GitHub CLI Triage
+
+```bash
+# List all checks for a PR and their status
+gh pr checks <PR_NUMBER> --repo apache/fory
+
+# View failed job logs (get the job ID from gh pr checks output)
+gh run view <RUN_ID> --repo apache/fory --job <JOB_ID> --log-failed
+
+# View full job logs
+gh run view <RUN_ID> --repo apache/fory --job <JOB_ID> --log
+```
+
+Typical flow:
+
+1. Run `gh pr checks <PR_NUMBER> --repo apache/fory`.
+2. Inspect the failed job with `gh run view ... --log-failed`.
+3. Reproduce the failure locally, fix the root cause, and rerun the relevant
checks.
+
+## Common CI Failures
+
+- Code style failures: run the relevant formatter (`clang-format`, `prettier`,
`spotless:apply`, `dotnet format`, `cargo fmt`, and so on).
+- Markdown lint failures: run `prettier --write <file>`.
+- C++ build failures: check missing dependencies, includes, and
architecture-specific Bazel flags.
+- Test failures: reproduce locally with the smallest command set that proves
the fix.
+
+## PR Expectations
+
+- PR titles must follow Conventional Commits.
+- Performance changes should use the `perf` type and include benchmark data.
+
+## Commit Message Format
+
+Use Conventional Commits with a language or area scope when it helps:
+
+```text
+feat(java): add codegen support for xlang serialization
+fix(rust): fix collection header when collection is empty
+docs(python): add docs for xlang serialization
+refactor(java): unify serialization exceptions hierarchy
+perf(cpp): optimize buffer allocation in encoder
+test(integration): add cross-language reference cycle tests
+ci: update build matrix for latest JDK versions
+chore(deps): update guava dependency to 32.0.0
+```
diff --git a/.agents/docs-and-formatting.md b/.agents/docs-and-formatting.md
new file mode 100644
index 000000000..80fb6c6d5
--- /dev/null
+++ b/.agents/docs-and-formatting.md
@@ -0,0 +1,34 @@
+# Docs And Formatting
+
+Load this file when changing documentation, public APIs, protocol specs,
benchmarks, or compiler-generated artifacts.
+
+## Source Documents
+
+- `README.md`
+- `CONTRIBUTING.md`
+- `docs/guide/DEVELOPMENT.md`
+- language guides under `docs/guide/`
+- `docs/specification/**`
+- `docs/compiler/**`
+
+## Rules
+
+- Update the relevant docs under `docs/` when important public APIs change.
+- Update `docs/specification/**` when protocol behavior changes.
+- Keep examples working and aligned with the current API and protocol behavior.
+- Provide or update working examples when adding new features or materially
changing workflows.
+- Add migration guidance when a change is breaking or materially changes
workflow.
+- Updates under `docs/guide/` and `docs/benchmarks/` are synced to
`apache/fory-site`; other website content should be changed there instead of
this repo.
+- When benchmark logic, scripts, config, or compared serializers change, rerun
the relevant benchmarks and refresh the report and plots under
`docs/benchmarks/**`.
+- Never manually edit generated code for compiler or IDL outputs; regenerate
from the source schema or IDL.
+
+## Formatting Commands
+
+- Markdown: `prettier --write <file>`
+- Repo-wide format and lint sweep: `bash ci/format.sh --all`
+
+## Documentation Expectations
+
+- Prefer precise, technically defensible claims over marketing language.
+- Keep terminology consistent with the specs and language guides.
+- If a protocol or behavior description differs between docs and code, treat
that as an issue to resolve before finishing.
diff --git a/.agents/languages/cpp.md b/.agents/languages/cpp.md
new file mode 100644
index 000000000..5bd6203a5
--- /dev/null
+++ b/.agents/languages/cpp.md
@@ -0,0 +1,59 @@
+# C++
+
+Load this file when changing `cpp/`, Cython build plumbing, or C++ xlang
behavior.
+
+## Rules
+
+- All commands must be executed within the `cpp/` directory.
+- Use C++17 in `cpp/`; do not introduce newer language features.
+- Bazel uses bzlmod via `MODULE.bazel`; prefer Bazel 8+.
+- For Bazel C++ tests, add `--config=x86_64` only on `x86_64` or `amd64`. Do
not use it on `arm64` or `aarch64`.
+- Run `clang-format` on updated C++ files.
+- When invoking a method that returns `Result`, use `FORY_TRY` unless you are
in control-flow logic that cannot use it cleanly.
+- Wrap error checks with `FORY_PREDICT_FALSE` for branch prediction.
+- Continue on trivial errors; return early only for critical errors such as
buffer overflow.
+- Put private methods last in class definitions, immediately before private
fields.
+
+## Key Paths
+
+- `cpp/fory/row`
+- `cpp/fory/meta`
+- `cpp/fory/encoder`
+- `cpp/fory/util`
+
+## Commands
+
+```bash
+# Build the C++ library
+bazel build //cpp/...
+
+# Build the Cython extension (replace X.Y with the Python version)
+bazel build //:cp_fory_so
--@rules_python//python/config_settings:python_version=X.Y
+
+# Run all C++ tests
+bazel test $(bazel query //cpp/...)
+
+# Run serialization tests
+bazel test $(bazel query //cpp/fory/serialization/...)
+
+# Run a specific test
+bazel test //cpp/fory/util:buffer_test
+
+# Format a file
+clang-format -i <file>
+```
+
+## Java-Driven Xlang Test
+
+```bash
+cd java
+mvn -T16 install -DskipTests
+cd fory-core
+FORY_CPP_JAVA_CI=1 ENABLE_FORY_DEBUG_OUTPUT=1 mvn -T16 test
-Dtest=org.apache.fory.xlang.CPPXlangTest
+```
+
+## Debugging And Profiling
+
+- See `docs/cpp_debug.md` for C++ debugging guidance.
+- Generate `compile_commands.json` with `bazel run :refresh_compile_commands`.
+- DTrace-based stack sampling is documented in `CONTRIBUTING.md`.
diff --git a/.agents/languages/csharp.md b/.agents/languages/csharp.md
new file mode 100644
index 000000000..fc52947c9
--- /dev/null
+++ b/.agents/languages/csharp.md
@@ -0,0 +1,41 @@
+# C#
+
+Load this file when changing `csharp/` or C# xlang behavior.
+
+## Rules
+
+- Run all `dotnet` commands from within `csharp/`.
+- Changes under `csharp/` must pass formatting and tests.
+- Fory C# requires .NET SDK `8.0+` and C# `12+`.
+- Use `dotnet format` to keep C# code style consistent.
+
+## Commands
+
+```bash
+# Restore
+dotnet restore Fory.sln
+
+# Build
+dotnet build Fory.sln -c Release --no-restore
+
+# Run tests
+dotnet test Fory.sln -c Release
+
+# Run a specific test
+dotnet test tests/Fory.Tests/Fory.Tests.csproj -c Release --filter
"FullyQualifiedName~ForyRuntimeTests.DynamicObjectReadDepthExceededThrows"
+
+# Format
+dotnet format Fory.sln
+
+# Format check
+dotnet format Fory.sln --verify-no-changes
+```
+
+## Java-Driven Xlang Test
+
+```bash
+cd java
+mvn -T16 install -DskipTests
+cd fory-core
+FORY_CSHARP_JAVA_CI=1 ENABLE_FORY_DEBUG_OUTPUT=1 mvn -T16 test
-Dtest=org.apache.fory.xlang.CSharpXlangTest
+```
diff --git a/.agents/languages/dart.md b/.agents/languages/dart.md
new file mode 100644
index 000000000..f23f33f43
--- /dev/null
+++ b/.agents/languages/dart.md
@@ -0,0 +1,23 @@
+# Dart
+
+Load this file when changing `dart/`.
+
+## Rules
+
+- Run Dart commands from within `dart/`.
+- Use `pub`-based tooling and generate code before testing when the build
runner outputs are involved.
+
+## Commands
+
+```bash
+# Generate code
+dart run build_runner build
+
+# Run tests
+dart test
+
+# Analyze and apply fixes
+dart analyze
+dart fix --dry-run
+dart fix --apply
+```
diff --git a/.agents/languages/go.md b/.agents/languages/go.md
new file mode 100644
index 000000000..94d47fe94
--- /dev/null
+++ b/.agents/languages/go.md
@@ -0,0 +1,53 @@
+# Go
+
+Load this file when changing `go/fory/` or Go xlang behavior.
+
+## Rules
+
+- Run Go commands from within `go/fory/`.
+- Changes under `go/` must pass formatting and tests.
+- The Go implementation focuses on reflection-based and codegen-based
serialization.
+- Set `FORY_PANIC_ON_ERROR=1` when debugging a failing Go test so you get the
full call stack.
+- Do not set `FORY_PANIC_ON_ERROR=1` when running the full Go test suite,
because some tests assert on error contents.
+
+## Key Paths
+
+- `fory.go`
+- `resolver.go`
+- `type.go`
+- `slice.go`
+- `map.go`
+- `set.go`
+- `struct.go`
+- `string.go`
+- `buffer.go`
+- `codegen/`
+- `meta/`
+
+## Commands
+
+```bash
+# Format code
+go fmt ./...
+
+# Run tests
+go test -v ./...
+
+# Run tests with race detection
+go test -race -v ./...
+
+# Build
+go build
+
+# Generate code
+go generate ./...
+```
+
+## Java-Driven Xlang Test
+
+```bash
+cd java
+mvn -T16 install -DskipTests
+cd fory-core
+FORY_GO_JAVA_CI=1 ENABLE_FORY_DEBUG_OUTPUT=1 mvn test
-Dtest=org.apache.fory.xlang.GoXlangTest
+```
diff --git a/.agents/languages/java.md b/.agents/languages/java.md
new file mode 100644
index 000000000..e55f12e22
--- /dev/null
+++ b/.agents/languages/java.md
@@ -0,0 +1,61 @@
+# Java
+
+Load this file when changing anything under `java/` or when Java drives a
cross-language validation flow.
+
+## Rules
+
+- Run all Maven commands from within `java/`.
+- Changes under `java/` must pass code style checks and tests.
+- Fory Java requires JDK `17+`.
+- `fory-core` targets Java 8 bytecode and `fory-format` targets Java 11
bytecode. Do not use newer APIs in those modules.
+- Do not use wildcard imports.
+- If you run temporary tests with `java -cp`, run `mvn -T16 install
-DskipTests` first so local Fory jars are current.
+- `WriteContext`, `ReadContext`, and `CopyContext` must stay explicit. Do not
reintroduce `ThreadLocal` or ambient runtime-context patterns.
+- Generated serializers must not retain runtime context fields. `Fory` should
stay a root-operation facade rather than accumulating serializer or convenience
state.
+- When the serializer class and constructor shape are known at the call site,
prefer direct constructor lambdas or direct instantiation over reflective
`Serializers.newSerializer(...)`.
+- For GraalVM, use `fory codegen` to generate serializers when building native
images. Do not add reflection configuration except for JDK `proxy`.
+- In Java native mode (`xlang=false`), only `Types.BOOL` through
`Types.STRING` share type IDs with xlang mode. Other native-mode type IDs
differ.
+
+## Key Modules
+
+- `fory-core`: core object-graph serialization runtime
+- `fory-format`: row-format encoding and decoding
+- `fory-extensions`: protobuf serializers and other extensions
+- `fory-simd`: SIMD-accelerated serializers and utilities
+- `fory-test-core`: shared Java test utilities
+- `testsuite`: issue-driven and complex regression coverage
+- `benchmark`: JMH benchmark suite
+
+## Commands
+
+```bash
+# Clean the build
+mvn -T16 clean
+
+# Build
+mvn -T16 package
+
+# Install
+mvn -T16 install -DskipTests
+
+# Format check
+mvn -T16 spotless:check
+
+# Apply formatting
+mvn -T16 spotless:apply
+
+# Style check
+mvn -T16 checkstyle:check
+
+# Run tests
+mvn -T16 test
+
+# Run a specific test
+mvn -T16 test -Dtest=org.apache.fory.TestClass#testMethod
+```
+
+## Debugging And IDE Notes
+
+- Set `FORY_CODE_DIR` to dump generated code.
+- Set `ENABLE_FORY_GENERATED_CLASS_UNIQUE_ID=false` when you need stable
generated class names.
+- In IntelliJ IDEA, use a JDK 11+ project SDK and disable `--release` if it
blocks `sun.misc.Unsafe` access.
diff --git a/.agents/languages/javascript.md b/.agents/languages/javascript.md
new file mode 100644
index 000000000..aa093ce86
--- /dev/null
+++ b/.agents/languages/javascript.md
@@ -0,0 +1,21 @@
+# JavaScript And TypeScript
+
+Load this file when changing `javascript/`.
+
+## Rules
+
+- Run JavaScript and TypeScript commands from within `javascript/`.
+- This implementation uses npm or yarn for package management.
+
+## Commands
+
+```bash
+# Install dependencies
+npm install
+
+# Run tests
+node ./node_modules/.bin/jest --ci --reporters=default --reporters=jest-junit
+
+# Lint TypeScript
+git ls-files -- '*.ts' | xargs -P 5 node ./node_modules/.bin/eslint
+```
diff --git a/.agents/languages/kotlin.md b/.agents/languages/kotlin.md
new file mode 100644
index 000000000..2855fc636
--- /dev/null
+++ b/.agents/languages/kotlin.md
@@ -0,0 +1,18 @@
+# Kotlin
+
+Load this file when changing `kotlin/`.
+
+## Rules
+
+- Run Kotlin Maven commands from within `kotlin/`.
+- Kotlin serializers build on the Java implementation. If Java changed and the
updated Java artifacts are not installed yet, run `cd ../java && mvn -T16
install -DskipTests` first.
+
+## Commands
+
+```bash
+# Build
+mvn clean package
+
+# Run tests
+mvn test
+```
diff --git a/.agents/languages/python.md b/.agents/languages/python.md
new file mode 100644
index 000000000..9548be2d7
--- /dev/null
+++ b/.agents/languages/python.md
@@ -0,0 +1,66 @@
+# Python
+
+Load this file when changing `python/`, Cython serialization, or Python xlang
behavior.
+
+## Rules
+
+- Run Python commands from within `python/`.
+- Changes under `python/` must pass formatting and tests.
+- Fory Python requires CPython `3.8+`.
+- Use `ENABLE_FORY_CYTHON_SERIALIZATION=0` first when debugging protocol
behavior.
+- Python mode is the pure-Python xlang implementation and is mainly for
debugging and testing.
+- Cython mode is the default high-performance implementation.
+- `ENABLE_FORY_DEBUG_OUTPUT=1` enables detailed struct serialization and
deserialization logs.
+
+## Key Paths
+
+- `pyfory/serialization.pyx`
+- `pyfory/_fory.py`
+- `pyfory/registry.py`
+- `pyfory/serializer.py`
+- `pyfory/includes`
+- `pyfory/resolver.py`
+- `pyfory/format`
+- `pyfory/buffer.pyx`
+
+## Commands
+
+```bash
+# Clean build outputs
+rm -rf build dist .pytest_cache
+bazel clean --expunge
+
+# Format and lint
+ruff format .
+ruff check --fix .
+
+# Install
+pip install -v -e .
+
+# Build the native extension on x86_64
+bazel build //:cp_fory_so
--@rules_python//python/config_settings:python_version=X.Y --config=x86_64
+
+# Build the native extension on arm64 / aarch64
+bazel build //:cp_fory_so
--@rules_python//python/config_settings:python_version=X.Y --copt=-fsigned-char
+
+# Run tests without Cython
+ENABLE_FORY_CYTHON_SERIALIZATION=0 pytest -v -s .
+
+# Run tests with Cython
+ENABLE_FORY_CYTHON_SERIALIZATION=1 pytest -v -s .
+```
+
+## Java-Driven Xlang Test
+
+```bash
+cd java
+mvn -T16 install -DskipTests
+cd fory-core
+FORY_PYTHON_JAVA_CI=1 ENABLE_FORY_CYTHON_SERIALIZATION=0
ENABLE_FORY_DEBUG_OUTPUT=1 mvn -T16 test
-Dtest=org.apache.fory.xlang.PythonXlangTest
+FORY_PYTHON_JAVA_CI=1 ENABLE_FORY_CYTHON_SERIALIZATION=1
ENABLE_FORY_DEBUG_OUTPUT=1 mvn -T16 test
-Dtest=org.apache.fory.xlang.PythonXlangTest
+```
+
+## Debugging
+
+- Generate annotated Cython output with `cython --cplus -a
pyfory/serialization.pyx`.
+- Build a debug extension with `FORY_DEBUG=true python setup.py build_ext
--inplace`.
diff --git a/.agents/languages/rust.md b/.agents/languages/rust.md
new file mode 100644
index 000000000..502bd46a5
--- /dev/null
+++ b/.agents/languages/rust.md
@@ -0,0 +1,75 @@
+# Rust
+
+Load this file when changing `rust/` or Rust xlang behavior.
+
+## Rules
+
+- Run all cargo commands from within `rust/`.
+- Changes under `rust/` must pass `clippy` and tests.
+- Use `RUST_BACKTRACE=1 FORY_PANIC_ON_ERROR=1` when debugging failing Rust
tests.
+- Add `-- --nocapture` when you need test output during debugging.
+- Do not set `FORY_PANIC_ON_ERROR=1` when running the full Rust test suite,
because some tests assert on error contents.
+
+## Key Paths
+
+- `fory/src/lib.rs`
+- `fory-core/src/fory.rs`
+- `fory-core/src/resolver/type_resolver.rs`
+- `fory-core/src/resolver/metastring_resolver.rs`
+- `fory-core/src/resolver/context.rs`
+- `fory-core/src/buffer.rs`
+- `fory-core/src/meta`
+- `fory-core/src/serializer`
+- `fory-core/src/row`
+- `fory-derive/src/object`
+- `fory-derive/src/fory_row`
+
+## Commands
+
+```bash
+# Check code
+cargo check
+
+# Build
+cargo build
+
+# Lint
+cargo clippy --all-targets --all-features -- -D warnings
+
+# Run tests
+cargo test --features tests
+
+# Run a specific test
+cargo test -p tests --test <test_file> <test_method>
+
+# Run a specific test under a subdirectory
+cargo test --test mod <dir>::<test_file>::<test_method>
+
+# Debug a specific test
+RUST_BACKTRACE=1 FORY_PANIC_ON_ERROR=1 ENABLE_FORY_DEBUG_OUTPUT=1 cargo test
--test mod <dir>::<test_file>::<test_method> -- --nocapture
+
+# Inspect generated code by the derive macro
+cargo expand --test mod <mod>::<file> > expanded.rs
+
+# Format
+cargo fmt
+
+# Check formatting
+cargo fmt --check
+
+# Build docs
+cargo doc --lib --no-deps --all-features
+
+# Run benchmarks
+cd <project_dir>/benchmarks/rust
+cargo bench
+```
+
+## Java-Driven Xlang Test
+
+```bash
+cd java
+mvn -T16 install -DskipTests
+cd fory-core
+RUST_BACKTRACE=1 FORY_PANIC_ON_ERROR=1 FORY_RUST_JAVA_CI=1
ENABLE_FORY_DEBUG_OUTPUT=1 mvn test -Dtest=org.apache.fory.xlang.RustXlangTest
+```
diff --git a/.agents/languages/scala.md b/.agents/languages/scala.md
new file mode 100644
index 000000000..03f22b70b
--- /dev/null
+++ b/.agents/languages/scala.md
@@ -0,0 +1,21 @@
+# Scala
+
+Load this file when changing `scala/`.
+
+## Rules
+
+- Run Scala commands from within `scala/`.
+- Scala serializers build on the Java implementation. If Java changed and the
updated Java artifacts are not installed yet, run `cd ../java && mvn -T16
install -DskipTests` first.
+
+## Commands
+
+```bash
+# Compile
+sbt compile
+
+# Run tests
+sbt test
+
+# Format code
+sbt scalafmt
+```
diff --git a/.agents/languages/swift.md b/.agents/languages/swift.md
new file mode 100644
index 000000000..4c1b0b6ad
--- /dev/null
+++ b/.agents/languages/swift.md
@@ -0,0 +1,40 @@
+# Swift
+
+Load this file when changing `swift/` or Swift xlang behavior.
+
+## Rules
+
+- Run Swift commands from within `swift/`.
+- Changes under `swift/` must pass lint and tests.
+- Swift lint uses `swift/.swiftlint.yml`.
+- Use `ENABLE_FORY_DEBUG_OUTPUT=1` when debugging Swift tests.
+
+## Commands
+
+```bash
+# Build package
+swift build
+
+# Run tests
+swift test
+
+# Run tests with debug output
+ENABLE_FORY_DEBUG_OUTPUT=1 swift test
+
+# Lint check
+swiftlint lint --config .swiftlint.yml
+
+# Auto-fix where supported
+swiftlint --fix --config .swiftlint.yml
+```
+
+## Java-Driven Xlang Test
+
+```bash
+cd swift
+swift build -c release --disable-automatic-resolution --product ForyXlangTests
+cd ../java
+mvn -T16 install -DskipTests
+cd fory-core
+FORY_SWIFT_JAVA_CI=1 ENABLE_FORY_DEBUG_OUTPUT=1 mvn -T16 test
-Dtest=org.apache.fory.xlang.SwiftXlangTest
+```
diff --git a/.agents/repo-reference.md b/.agents/repo-reference.md
new file mode 100644
index 000000000..2e2d55de7
--- /dev/null
+++ b/.agents/repo-reference.md
@@ -0,0 +1,106 @@
+# Repository Reference
+
+Load this file when you need repo layout, protocol context, compiler guidance,
or a quick runtime map before diving into a subsystem.
+
+## Key Directories
+
+- `docs/`: specifications, guides, compiler docs, and benchmark reports
+- `benchmarks/`: benchmark harnesses and benchmark-specific assets
+- `examples/`: usage examples and sample code
+- `compiler/`: Fory compiler, parser, IR, and code generators
+- `java/`, `csharp/`, `python/`, `cpp/`, `go/`, `rust/`, `swift/`,
`javascript/`, `dart/`, `kotlin/`, `scala/`: language implementations
+- `integration_tests/`: cross-language integration tests
+- `.github/workflows/` and `ci/`: CI configuration and helper scripts
+- `licenses/`: third-party license reports and metadata
+
+## Important Files
+
+- `AGENTS.md`: repo-wide AI guidance entry point
+- `CLAUDE.md`: compatibility shim that points back to `AGENTS.md`
+- `README.md`: project overview and quick start
+- `CONTRIBUTING.md`: contributor workflow and environment notes
+- `docs/guide/DEVELOPMENT.md`: development setup and build notes
+- `docs/cpp_debug.md`: C++ debugging guidance
+- `licenserc.toml`: license header configuration
+
+## Protocol Overview
+
+Apache Fory is a multi-language serialization framework with multiple wire
formats. Read the relevant spec before touching any protocol behavior.
+
+- Xlang serialization format: `docs/specification/xlang_serialization_spec.md`
+- Row format: `docs/specification/row_format_spec.md`
+- Java serialization format: `docs/specification/java_serialization_spec.md`
+- Type mapping: `docs/specification/xlang_type_mapping.md`
+
+## Compiler And IDL Notes
+
+- Primary references:
+ - `docs/compiler/index.md`
+ - `docs/compiler/compiler-guide.md`
+ - `docs/compiler/schema-idl.md`
+ - `docs/compiler/type-system.md`
+ - `docs/compiler/generated-code.md`
+ - `docs/compiler/protobuf-idl.md`
+ - `docs/compiler/flatbuffers-idl.md`
+- Compiler location: `compiler/`
+- Install and CLI:
+ - `cd compiler && pip install -e .`
+ - `foryc --help`
+ - `foryc schema.fdl --lang <langs> --output <dir>`
+- Never edit generated code manually. Update the source schema or IDL and
regenerate.
+- Protocol changes must update `docs/specification/**` and the relevant
cross-language tests.
+
+## Runtime Map
+
+### Java
+
+- `java/fory-core`: core object graph serialization runtime
+- `java/fory-format`: row format encoding and decoding
+- `java/fory-extensions`: optional extensions such as protobuf serializers and
zstd meta compression
+- `java/fory-simd`: SIMD-accelerated paths
+- `java/fory-test-core`: shared Java test utilities
+- `java/testsuite`: issue-driven and complex regression tests
+- `java/benchmark`: JMH benchmarks
+
+### Bazel
+
+- `MODULE.bazel`: bzlmod dependency management
+- `bazel/cython_library.bzl`: `pyx_library` support for Cython extension builds
+
+### C++
+
+- `cpp/fory/row`: row-format data structures
+- `cpp/fory/meta`: compile-time reflection utilities
+- `cpp/fory/encoder`: row encoder and decoder
+- `cpp/fory/util`: core utilities such as buffer and status types
+
+### Python
+
+- `python/pyfory/serialization.pyx`: Cython xlang serialization core
+- `python/pyfory/_fory.py`: pure-Python xlang serialization entry point
+- `python/pyfory/registry.py`: type registry and serializer dispatch
+- `python/pyfory/resolver.py`: pure-Python reference resolver
+- `python/pyfory/format`: row-format support
+- `python/pyfory/buffer.pyx`: shared buffer and string helpers
+
+### Go
+
+- `go/fory/fory.go`: entry point
+- `go/fory/resolver.go`: shared and circular reference tracking
+- `go/fory/type.go`: type resolution and dispatch
+- `go/fory/codegen`: code generation support
+
+### Rust
+
+- `rust/fory/src/lib.rs`: public entry point
+- `rust/fory-core/src/fory.rs`: core runtime entry point
+- `rust/fory-core/src/resolver/`: resolver and context state
+- `rust/fory-core/src/serializer/`: serializers
+- `rust/fory-derive/src/`: derive macros for code generation
+
+## Shared Debugging Heuristics
+
+- For protocol issues, start with the relevant spec before changing code.
+- For performance issues, profile first and verify memory-allocation behavior
and ownership boundaries.
+- For build issues, prefer clean rebuilds and explicit dependency-version
checks before assuming tool bugs.
+- For Bazel-specific build issues, use `bazel clean --expunge` when a deep
clean is needed.
diff --git a/.agents/skills/fory-code-review/SKILL.md
b/.agents/skills/fory-code-review/SKILL.md
index 173f40644..8e5896e97 100644
--- a/.agents/skills/fory-code-review/SKILL.md
+++ b/.agents/skills/fory-code-review/SKILL.md
@@ -19,6 +19,7 @@ Find the highest-value bugs, regressions, and missing
verification in Apache For
- `references/review-checklist.md`
- `references/lesson-derived-red-flags.md`
- `references/validation-command-matrix.md`
+ - matching runtime docs under `../../languages/*.md` when the patch is
language-specific
## Review Workflow
diff --git
a/.agents/skills/fory-code-review/references/validation-command-matrix.md
b/.agents/skills/fory-code-review/references/validation-command-matrix.md
index 8745de40a..d4c67cf8a 100644
--- a/.agents/skills/fory-code-review/references/validation-command-matrix.md
+++ b/.agents/skills/fory-code-review/references/validation-command-matrix.md
@@ -2,6 +2,8 @@
Use the smallest command set that proves the changed behavior. If protocol or
xlang behavior changed, call out the cross-language tests that should run even
if the author did not run them yet.
+Canonical runtime-specific rules now live under `../../../languages/*.md` and
`../../../testing/integration-tests.md`. Use this file as the review-oriented
shortcut matrix.
+
## Repo-Wide Anchors
- Format/lint sweep: `bash ci/format.sh --all`
diff --git a/.agents/skills/fory-performance-optimization/SKILL.md
b/.agents/skills/fory-performance-optimization/SKILL.md
index 879bb39ed..2bbe17f80 100644
--- a/.agents/skills/fory-performance-optimization/SKILL.md
+++ b/.agents/skills/fory-performance-optimization/SKILL.md
@@ -104,7 +104,7 @@ Deliver measurable performance improvements in Apache Fory
without protocol drif
## Use References
- Use [`references/workflow-checklist.md`](references/workflow-checklist.md)
for execution checklists and stop conditions.
-- Use
[`references/language-command-matrix.md`](references/language-command-matrix.md)
for per-language build/test/benchmark/profile commands.
+- Use
[`references/language-command-matrix.md`](references/language-command-matrix.md)
for the quick per-language verification matrix, and the canonical runtime docs
under `../../languages/*.md` for full language-specific rules.
- Use [`references/bottleneck-playbook.md`](references/bottleneck-playbook.md)
for hotspot-to-fix mapping.
- Use [`references/round-template.md`](references/round-template.md) to log
each optimization round consistently.
diff --git
a/.agents/skills/fory-performance-optimization/references/language-command-matrix.md
b/.agents/skills/fory-performance-optimization/references/language-command-matrix.md
index 6b5926f9b..59082d72e 100644
---
a/.agents/skills/fory-performance-optimization/references/language-command-matrix.md
+++
b/.agents/skills/fory-performance-optimization/references/language-command-matrix.md
@@ -2,6 +2,8 @@
Use this as the default verification matrix after performance changes. Run
commands from the language directory unless noted.
+Canonical runtime-specific rules now live under `../../../languages/*.md` and
`../../../testing/integration-tests.md`. Use this file as the quick
optimization checklist, not as the long-form source of truth.
+
## Swift
- Build: `swift build`
diff --git a/.agents/testing/integration-tests.md
b/.agents/testing/integration-tests.md
new file mode 100644
index 000000000..7a891f946
--- /dev/null
+++ b/.agents/testing/integration-tests.md
@@ -0,0 +1,43 @@
+# Integration Tests
+
+Load this file when changing `integration_tests/`, xlang behavior,
compiler-generated outputs, or cross-language compatibility.
+
+## Rules
+
+- Run all commands from within `integration_tests/`.
+- For Java-related integration tests, install the Java libraries first with
`cd ../java && mvn -T16 install -DskipTests` if Java changed. If unsure, run it.
+- On macOS, GraalVM is usually installed under
`/Library/Java/JavaVirtualMachines/graalvm-xxx`.
+- For `integration_tests/idl_tests`:
+ - Always run `cd ../java && mvn -T16 install -DskipTests` before the test if
Java changed since the last install. If unsure, run it.
+ - Always run `cd ../python && pip install -v -e .` before the test if Python
or Cython code changed. Rebuild Cython if needed.
+- Never manually edit code generated by the Fory compiler for IDL tests.
Regenerate it from the source IDL.
+
+## Main Modules
+
+- `graalvm_tests`
+- `jdk_compatibility_tests`
+- `jpms_tests`
+- `idl_tests`
+- `cpython_benchmark`
+
+## Commands
+
+```bash
+it_dir=$(pwd)
+
+# Run GraalVM tests
+cd "$it_dir/graalvm_tests" && mvn -T16 -DskipTests=true -Pnative package &&
target/main
+
+# Run JDK compatibility tests
+cd "$it_dir/jdk_compatibility_tests" && mvn -T16 test
+
+# Run JPMS tests
+cd "$it_dir/jpms_tests" && mvn -T16 test
+
+# Run Python benchmarks
+cd "$it_dir/cpython_benchmark" && pip install -r requirements.txt && python
benchmark.py
+```
+
+## Cross-Language Validation Note
+
+When a change affects xlang behavior, combine these integration checks with
the relevant Java-driven xlang tests from the language-specific files under
`.agents/languages/`.
diff --git a/AGENTS.md b/AGENTS.md
index 60967b216..8a3e1ea17 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1,782 +1,104 @@
# AGENTS.md
-This file provides comprehensive guidance to AI coding agents when working
with the Apache Fory codebase.
-
-## Core Principles
-
-While working on Fory, please remember:
-
-- **Do Not Keep Dead Weight**: Do not keep legacy, dead, or useless code,
tests, or docs unless the user explicitly requests it.
-- **Performance First**: Performance is the top priority. Never introduce code
that reduces performance without explicit justification.
-- **English Only**: Always use English in code, comments, and documentation.
-- **Meaningful Comments**: Only add comments when the code's behavior is
difficult to understand or when documenting complex algorithms.
-- **Focused Testing**: Only add tests that verify internal behaviors or fix
specific bugs; don't create unnecessary tests unless requested.
-- **No Cleanup-Sentinel Tests**: Do not add standalone tests that only assert
deleted APIs, removed fields, or cleanup-only surface constraints; prefer
behavior tests in existing focused suites.
-- **Git-Tracked Files**: When reading code, skip all files not tracked by git
by default unless generated by yourself.
-- **Cross-Language Consistency**: Maintain consistency across language
implementations while respecting language-specific idioms.
-- **No Checked Exceptions in New Code**: Do not introduce checked exceptions
in new APIs or newly added code paths; prefer unchecked propagation or explicit
result/state handling.
-- **Explicit Runtime Context Ownership**: Do not use `ThreadLocal`/ambient
runtime context patterns in Java runtime code.
`WriteContext`/`ReadContext`/`CopyContext` state must stay explicit, generated
serializers must not retain context fields, and `Fory` should stay a
root-operation facade rather than accumulating serializer/runtime convenience
state.
-- **Avoid Reflection on Fixed Bootstrap Paths**: When a serializer class and
constructor shape are known at the call site, prefer direct constructor lambdas
or direct instantiation over reflective `Serializers.newSerializer(...)`; keep
reflection for dynamic/general construction paths only.
-- **GraalVM support using fory codegen**: For GraalVM, use `fory codegen` to
generate the serializer when building a native image. Do not use GraalVM
reflect-related configuration unless for JDK `proxy`.
-- **Xlang Type System**: Java `native mode(xlang=false)` shares same type
systems between type id from `Types.BOOL~Types.STRING` with `xlang
mode(xlang=true)`, but for other types, java `native mode` has different type
ids.
-- **Remote git repository**: `[email protected]:apache/fory.git` is remote
repository, do not use other remote repository when you want to check code
under `main` branch, **`apache/main`** is the only target main branch instead
of `origin/main`
-- **Refresh remote main before compare**: before any diff/review/compare
against `apache/main`, always run `git fetch apache main` first so comparisons
use the latest remote main.
-- **PR review isolation**: when reviewing a GitHub pull request, always do the
review in a new local git worktree. Do not switch the current branch or reuse
the current worktree for that review unless the user explicitly asks for it.
-- **Contributor git repository**: A contributor should fork the
`[email protected]:apache/fory.git` repo, and git push the code changes into
their forked repo, then create a pull request from the branch in their forked
repo into `[email protected]:apache/fory.git`.
-- **Debug Test Errors**: always set environment variable
`ENABLE_FORY_DEBUG_OUTPUT` to `1` to see debug output.
-- **Never work around errors**: find out and fix root causes when tests
failed, never work around it, hack it or weaken tests to make it pass.
-
-## Documentation Sources and Change Rules
-
-- **Primary references**: `README.md`, `CONTRIBUTING.md`,
`docs/guide/DEVELOPMENT.md`, and language guides under `docs/guide/`.
-- **Protocol changes**: Read and update the relevant specs in
`docs/specification/**` and align cross-language tests.
-- **Docs publishing**: Updates under `docs/guide/` and `docs/benchmarks/` are
synced to https://github.com/apache/fory-site; other website content should be
changed in that repo.
-- **Benchmark docs refresh is mandatory**: When any benchmark
logic/script/config or compared serializer set changes, rerun the relevant
benchmarks and refresh corresponding artifacts under `docs/benchmarks/**`
(report + plots) before finalizing.
-- **Debugging docs**: C++ debugging guidance lives in `docs/cpp_debug.md`.
-- **Conflicts**: If instructions conflict, follow the most specific module
docs and call out the conflict in your response.
-
-## Build and Development Commands
-
-### Java Development
-
-- All maven commands must be executed within the `java` directory.
-- All changes to `java` must pass the code style check and tests.
-- Fory java needs JDK `17+` installed.
-- Modules target different bytecode levels (fory-core Java 8, fory-format Java
11); avoid using newer APIs in those modules.
-- Use '.\*' form of import is not allowed.
-- If you run temporary tests using `java -cp`, you must run `mvn -T16 install
-DskipTests` to get latest jars for fory java library.
-
-```bash
-# Clean the build
-mvn -T16 clean
-
-# Build
-mvn -T16 package
-
-# Install
-mvn -T16 install -DskipTests
-
-# Code format check
-mvn -T16 spotless:check
-
-# Code format
-mvn -T16 spotless:apply
-
-# Code style check
-mvn -T16 checkstyle:check
-
-# Run tests
-mvn -T16 test
-
-# Run specific tests
-mvn -T16 test -Dtest=org.apache.fory.TestClass#testMethod
-```
-
-### C# Development
-
-- All dotnet commands must be executed within the `csharp` directory.
-- All changes to `csharp` must pass formatting and tests.
-- Fory C# requires .NET SDK `8.0+` and C# `12+`.
-- Use `dotnet format` to keep C# code style consistent.
-
-```bash
-# Restore
-dotnet restore Fory.sln
-
-# Build
-dotnet build Fory.sln -c Release --no-restore
-
-# Run tests
-dotnet test Fory.sln -c Release
-
-# Run specific test
-dotnet test tests/Fory.Tests/Fory.Tests.csproj -c Release --filter
"FullyQualifiedName~ForyRuntimeTests.DynamicObjectReadDepthExceededThrows"
-
-# Format code
-dotnet format Fory.sln
-
-# Format check
-dotnet format Fory.sln --verify-no-changes
-```
-
-Run C# xlang tests:
-
-```bash
-cd java
-mvn -T16 install -DskipTests
-cd fory-core
-FORY_CSHARP_JAVA_CI=1 ENABLE_FORY_DEBUG_OUTPUT=1 mvn -T16 test
-Dtest=org.apache.fory.xlang.CSharpXlangTest
-```
-
-### C++ Development
-
-- All commands must be executed within the `cpp` directory.
-- Fory c++ use c++ 17, you must not use features from higher version of C++.
-- Bazel uses bzlmod (`MODULE.bazel`); prefer Bazel 8+.
-- For Bazel C++ tests, detect machine architecture and **only** add
`--config=x86_64` on `x86_64`/`amd64`; on `arm64`/`aarch64`, do not enable this
config.
-- When you updated the code, use `clang-format` to update the code
-- When invoking a method that returns `Result`, always use `FORY_TRY` unless
in a control flow context.
-- Wrap error checks with `FORY_PREDICT_FALSE` for branch prediction
optimization.
-- Continue on error for trivial errors; only return early for critical errors
like buffer overflow.
-- private methods should be put last in class def, before private fields.
-
-```bash
-# Build C++ library
-bazel build //cpp/...
-
-# Build Cython extensions (replace X.Y with your Python version, e.g., 3.10)
-bazel build //:cp_fory_so
--@rules_python//python/config_settings:python_version=X.Y
-
-# Run tests
-bazel test $(bazel query //cpp/...)
-
-# Run serialization tests
-bazel test $(bazel query //cpp/fory/serialization/...)
-
-# Run specific test
-bazel test //cpp/fory/util:buffer_test
-
-# format c++ code
-clang-format -i $file
-```
-
-Run C++ xlang tests:
-
-```bash
-cd java
-mvn -T16 install -DskipTests
-cd fory-core
-FORY_CPP_JAVA_CI=1 ENABLE_FORY_DEBUG_OUTPUT=1 mvn -T16 test
-Dtest=org.apache.fory.xlang.CPPXlangTest
-```
-
-### Python Development
-
-- All commands must be executed within the `python` directory.
-- All changes to `python` must pass the code style check and tests.
-- When running tests, you can use the `ENABLE_FORY_CYTHON_SERIALIZATION`
environment variable to enable or disable cython serialization.
-- When debugging protocol related issues, you should use
`ENABLE_FORY_CYTHON_SERIALIZATION=0` first to verify the behavior.
-- Fory python needs cpython `3.8+` installed although some modules such as
`fory-core` use `java8`.
-
-```bash
-# clean build
-rm -rf build dist .pytest_cache
-bazel clean --expunge
-
-# Code format
-ruff format .
-ruff check --fix .
-
-# Install
-pip install -v -e .
-
-# Build native extension when cython code changed (replace X.Y with your
Python version)
-bazel build //:cp_fory_so
--@rules_python//python/config_settings:python_version=X.Y --config=x86_64 #
For x86_64
-bazel build //:cp_fory_so
--@rules_python//python/config_settings:python_version=X.Y --copt=-fsigned-char
# For arm64 and aarch64
-
-# Run tests without cython
-ENABLE_FORY_CYTHON_SERIALIZATION=0 pytest -v -s .
-# Run tests with cython
-ENABLE_FORY_CYTHON_SERIALIZATION=1 pytest -v -s .
-```
-
-Run Python xlang tests:
-
-```bash
-cd java
-mvn -T16 install -DskipTests
-cd fory-core
-# disable fory cython for faster debugging
-FORY_PYTHON_JAVA_CI=1 ENABLE_FORY_CYTHON_SERIALIZATION=0
ENABLE_FORY_DEBUG_OUTPUT=1 mvn -T16 test
-Dtest=org.apache.fory.xlang.PythonXlangTest
-# enable fory cython
-FORY_PYTHON_JAVA_CI=1 ENABLE_FORY_CYTHON_SERIALIZATION=1
ENABLE_FORY_DEBUG_OUTPUT=1 mvn -T16 test
-Dtest=org.apache.fory.xlang.PythonXlangTest
-```
-
-### Golang Development
-
-- All commands must be executed within the `go/fory` directory.
-- All changes to `go` must pass the format check and tests.
-- Go implementation focuses on reflection-based and codegen-based
serialization.
-- Set `FORY_PANIC_ON_ERROR=1` when debugging test errors to see full callstack.
-- You must not set `FORY_PANIC_ON_ERROR=1` when running all go tests to check
whether all tests pass, some tests will check Error content, which will fail if
error just panic.
-
-```bash
-# Format code
-go fmt ./...
-
-# Run tests
-go test -v ./...
-
-# Run tests with race detection
-go test -race -v ./...
-
-# Build
-go build
-
-# Generate code (if using go:generate)
-go generate ./...
-```
-
-Run Go xlang tests:
-
-```bash
-cd java
-mvn -T16 install -DskipTests
-cd fory-core
-FORY_GO_JAVA_CI=1 ENABLE_FORY_DEBUG_OUTPUT=1 mvn test
-Dtest=org.apache.fory.xlang.GoXlangTest
-```
-
-### Rust Development
-
-- All cargo commands must be executed within the `rust` directory.
-- All changes to `rust` must pass the clippy check and tests.
-- You must set `RUST_BACKTRACE=1 FORY_PANIC_ON_ERROR=1` when debugging rust
tests to get backtrace.
-- You must add `-- --nocapture` to cargo test command when debugging tests.
-- You must not set `FORY_PANIC_ON_ERROR=1` when running all rust tests to
check whether all tests pass, some tests will check Error content, which will
fail if error just panic.
-
-```bash
-# Check code
-cargo check
-
-# Build
-cargo build
-
-# Run linter for all services.
-cargo clippy --all-targets --all-features -- -D warnings
-
-# Run tests (requires test features)
-cargo test --features tests
-
-# run specific test
-cargo test -p tests --test $test_file $test_method
-
-# run specific test under subdirectory
-cargo test --test mod $dir$::$test_file::$test_method
-
-# debug specific test under subdirectory and get backtrace
-RUST_BACKTRACE=1 FORY_PANIC_ON_ERROR=1 ENABLE_FORY_DEBUG_OUTPUT=1 cargo test
--test mod $dir$::$test_file::$test_method -- --nocapture
-
-# inspect generated code by fory derive macro
-cargo expand --test mod $mod$::$file$ > expanded.rs
-
-# Format code
-cargo fmt
-
-# Check formatting
-cargo fmt --check
-
-# Build documentation
-cargo doc --lib --no-deps --all-features
-
-# Run benchmarks
-cd $project_dir/benchmarks/rust
-cargo bench
-```
-
-Run Rust xlang tests:
-
-```bash
-cd java
-mvn -T16 install -DskipTests
-cd fory-core
-RUST_BACKTRACE=1 FORY_PANIC_ON_ERROR=1 FORY_RUST_JAVA_CI=1
ENABLE_FORY_DEBUG_OUTPUT=1 mvn test -Dtest=org.apache.fory.xlang.RustXlangTest
-```
-
-### Swift Development
-
-- All commands must be executed within the `swift` directory.
-- All changes to `swift` must pass lint and tests.
-- Swift lint uses `swift/.swiftlint.yml`.
-- Use `ENABLE_FORY_DEBUG_OUTPUT=1` when debugging Swift tests.
-
-```bash
-# Build package
-swift build
-
-# Run tests
-swift test
-
-# Run tests with debug output
-ENABLE_FORY_DEBUG_OUTPUT=1 swift test
-
-# Lint check
-swiftlint lint --config .swiftlint.yml
-
-# Auto-fix lint issues where supported
-swiftlint --fix --config .swiftlint.yml
-```
-
-Run Swift xlang tests:
-
-```bash
-cd swift
-swift build -c release --disable-automatic-resolution --product ForyXlangTests
-cd ../java
-mvn -T16 install -DskipTests
-cd fory-core
-FORY_SWIFT_JAVA_CI=1 ENABLE_FORY_DEBUG_OUTPUT=1 mvn -T16 test
-Dtest=org.apache.fory.xlang.SwiftXlangTest
-```
-
-### JavaScript/TypeScript Development
-
-- All commands must be executed within the `javascript` directory.
-- Uses npm/yarn for package management.
-
-```bash
-# Install dependencies
-npm install
-
-# Run tests
-node ./node_modules/.bin/jest --ci --reporters=default --reporters=jest-junit
-
-# Format code
-git ls-files -- '*.ts' | xargs -P 5 node ./node_modules/.bin/eslint
-```
-
-### Dart Development
-
-- All commands must be executed within the `dart` directory.
-- Uses pub for package management.
-
-```bash
-# First, generate necessary code
-dart run build_runner build
-
-# Run all tests
-dart test
-
-# Format code
-dart analyze
-dart fix --dry-run
-dart fix --apply
-```
-
-### Kotlin Development
-
-- All maven commands must be executed within the `kotlin` directory.
-- Kotlin implementation provides extra serializers for kotlin types.
-- Kotlin implementation is built on fory java, please install the java
libraries first by `cd ../java && mvn -T16 install -DskipTests`. If no code
changes after installed fory java, you can skip the installation step.
-
-```bash
-# Build
-mvn clean package
-
-# Run tests
-mvn test
-```
-
-### Scala Development
-
-- All commands must be executed within the `scala` directory.
-- Scala implementation provides extra serializers for Scala types.
-- Scala implementation is built on fory java, please install the java
libraries first by `cd ../java && mvn -T16 install -DskipTests`. If no code
changes after installed fory java, you can skip the installation step.
-
-```bash
-# Build with sbt
-sbt compile
-
-# Run tests
-sbt test
-
-# Format code
-sbt scalafmt
-```
-
-### Integration Tests
-
-- All commands must be executed within the `integration_tests` directory.
-- For java related integration tests, please install the java libraries first
by `cd ../java && mvn -T16 install -DskipTests`. If no code changes after
installed fory java, you can skip the installation step.
-- For mac, graalvm is installed at
`/Library/Java/JavaVirtualMachines/graalvm-xxx` by default.
-- For `integration_tests/idl_tests` (mandatory prerequisites):
- - Always run `cd ../java && mvn -T16 install -DskipTests` before any
`idl_tests` run **if** there were changes under `java/` since the last install.
If unsure, run it.
- - Always run `cd ../python && pip install -v -e .` (and rebuild Cython if
needed) before any `idl_tests` run **if** there were changes to Cython-related
code under `python/`. If unsure, run it.
-- You are never allowed to manual edit generated code by fory compiler for
`IDL` files, you must invoke fory compiler to regenerate code.
-
-```bash
-it_dir=$(pwd)
-# Run graalvm tests
-cd $it_dir/graalvm_tests && mvn -T16 -DskipTests=true -Pnative package &&
target/main
-
-# Run JDK compatibility tests
-cd $it_dir/jdk_compatibility_tests && mvn -T16 test
-
-# Run JPMS tests
-cd $it_dir/jpms_tests && mvn -T16 test
-
-# Run Python benchmarks
-cd $it_dir/cpython_benchmark && pip install -r requirements.txt && python
benchmark.py
-```
-
-### Documentation and Formatting
-
-- **Markdown Formatting**: When updating markdown documentation, use `prettier
--write $file` to format.
-- **API Documentation**: When updating important public APIs, update
documentation under `docs/`.
-- **Protocol Specifications**: `docs/specification/**` contains Fory protocol
specifications. Read these documents carefully before making protocol changes.
-- **User Guides**: `docs/guide/**` contains user guides for different features
and languages.
-- **Repo-wide formatting**: `bash ci/format.sh --all` runs format/lint across
languages.
-
-## Repository Structure Understanding
-
-### Git Repository
-
-Apache Fory is an open-source project hosted on GitHub.
-The git repository for Apache Fory is https://github.com/apache/fory .
-Contributors always fork the repository and create a pull request to propose
changes.
-The `origin` points to forked repository instead of the official repository.
-
-### Key Directories
-
-- **`docs/`**: Documentation, specifications, and guides
- - `docs/specification/`: Protocol specifications (critical for understanding)
- - `docs/guide/`: User guides and development guides
- - `docs/benchmarks/`: Performance benchmarks documentation
-- **`benchmarks/`**: Benchmark suites and harnesses
-- **`examples/`**: Usage examples and sample code
-- **`compiler/`**: Code generation and compiler-related utilities
-
-- **Language Implementations**:
- - `java/`: Java implementation (maven-based, multi-module)
- - `csharp/`: C# implementation (.NET SDK + source generator)
- - `python/`: Python implementation (pip/setuptools + bazel)
- - `cpp/`: C++ implementation (bazel-based)
- - `go/`: Go implementation (go modules)
- - `rust/`: Rust implementation (cargo-based)
- - `javascript/`: JavaScript/TypeScript implementation (npm-based)
- - `dart/`: Dart implementation (pub-based)
- - `kotlin/`: Kotlin implementation (maven-based)
- - `scala/`: Scala implementation (sbt-based)
-
-- **Testing and CI**:
- - `integration_tests/`: Cross-language integration tests
- - `.github/workflows/`: GitHub Actions CI/CD workflows
- - `ci/`: CI scripts and configurations
-
-- **Build Configuration**:
- - `BUILD`, `WORKSPACE`: Bazel configuration
- - `.bazelrc`, `.bazelversion`: Bazel settings
- - `MODULE.bazel`: Bazel bzlmod dependency management
- - Various `pom.xml`, `package.json`, `Cargo.toml`, etc.
-- **`licenses/`**: Third-party license reports and metadata
-
-### Important Files
-
-- **`AGENTS.md`**: This file - AI coding guidance
-- **`CLAUDE.md`**: Claude Code specific instructions
-- **`CONTRIBUTING.md`**: Contribution guidelines
-- **`README.md`**: Project overview and quick start
-- **`.gitignore`**: Git ignore patterns (includes build dirs)
-- **`licenserc.toml`**: License header configuration
-- **`docs/guide/DEVELOPMENT.md`**: Environment setup and build notes
-- **`docs/cpp_debug.md`**: C++ debugging guide
-
-## Architecture Overview
-
-Apache Fory is a blazingly-fast multi-language serialization framework that
revolutionizes data exchange between systems and languages. By leveraging JIT
compilation, code generation and zero-copy techniques, Fory delivers up to 170x
faster performance compared to other serialization frameworks while being
extremely easy to use.
-
-### Binary Protocols
-
-Fory uses binary protocols for efficient serialization and deserialization.
Fory designed and implemented multiple binary protocols for different scenarios:
-
-- **[xlang serialization
format](docs/specification/xlang_serialization_spec.md)**:
- - Cross-language serialize any object automatically, no need for IDL
definition, schema compilation and object to/from protocol conversion.
- - Support optional shared reference and circular reference, no duplicate
data or recursion error.
- - Support object polymorphism.
-- **[Row format](docs/specification/row_format_spec.md)**: A cache-friendly
binary random access format, supports skipping serialization and partial
serialization, and can convert to column-format automatically.
-- **[Java serialization
format](docs/specification/java_serialization_spec.md)**: Highly-optimized and
drop-in replacement for Java serialization.
-- **Python serialization format**: Highly-optimized and drop-in replacement
for Python pickle, which is an extension built upon **[xlang serialization
format](docs/specification/xlang_serialization_spec.md)**.
-
-**`docs/specification/**` are the specification for the Fory protocol, please
read those documents carefully and think hard and make sure you understand them
before making changes to code and documentation.
-
-### Compiler Development (FDL/IDL)
-
-- **Primary references**: `docs/compiler/index.md`,
`docs/compiler/compiler-guide.md`,
- `docs/compiler/schema-idl.md`, `docs/compiler/type-system.md`,
- `docs/compiler/generated-code.md`, `docs/compiler/protobuf-idl.md`,
- `docs/compiler/flatbuffers-idl.md`.
-- **Location**: `compiler/` contains the Fory compiler, parser, IR, and code
generators.
-- **Install & CLI**:
- - `cd compiler && pip install -e .`
- - `foryc --help`
- - `foryc schema.fdl --lang <langs> --output <dir>`
-- **Generated code**: Never edit generated files manually; update the
`.fdl`/`.proto`/`.fbs` and re-run the compiler.
-- **IDL tests**: Use `integration_tests/idl_tests/generate_idl.py` for test
codegen.
- - In `integration_tests/idl_tests`, keep package names aligned with the IDL
filename.
-- **Protocol changes**: Update `docs/specification/**` and cross-language
tests.
-- **Language targets**: FDL is the primary schema; protobuf/flatbuffers
support should remain unchanged unless explicitly requested.
-
-### Core Runtime Structure
-
-Fory serialization for every language is implemented independently to minimize
the object memory layout interoperability, object allocation, memory access
cost, thus maximize the performance. There is no code reuse between languages
except for `fory python`, which reused code from `fory c++`.
-
-#### Java
-
-- **fory-core**: Java library implementing the core object graph serialization
- - `java/fory-core/src/main/java/org/apache/fory/Fory.java`: main
serialization entry point
- - `java/fory-core/src/main/java/org/apache/fory/resolver/TypeResolver.java`:
type resolution and serializer dispatch
- - `java/fory-core/src/main/java/org/apache/fory/resolver/RefResolver.java`:
class for resolving shared/circular references when ref tracking is enabled
- - `java/fory-core/src/main/java/org/apache/fory/serializer`: serializers for
each supported type
- - `java/fory-core/src/main/java/org/apache/fory/codegen`: code generators,
provide expression abstraction and compile expression tree to java code and
byte code
- - `java/fory-core/src/main/java/org/apache/fory/builder`: build expression
tree for serialization to generate serialization code
- - `java/fory-core/src/main/java/org/apache/fory/reflect`: reflection
utilities
- - `java/fory-core/src/main/java/org/apache/fory/type`: java generics and
type inference utilities
- - `java/fory-core/src/main/java/org/apache/fory/util`: utility classes
-
-- **fory-format**: Java library implementing the core row format encoding and
decoding
- - `java/fory-format/src/main/java/org/apache/fory/format/row`: row format
data structures
- - `java/fory-format/src/main/java/org/apache/fory/format/encoder`: generate
row format encoder and decoder to encode/decode objects to/from row format
- - `java/fory-format/src/main/java/org/apache/fory/format/type`: type
inference for row format
- - `java/fory-format/src/main/java/org/apache/fory/format/vectorized`:
interoperation with apache arrow columnar format
-
-- **fory-extensions**: extension libraries for java, including:
- - Protobuf serializers for fory java native object graph protocol.
- - Meta compression based on zstd
-
-- **fory-simd**: SIMD-accelerated serialization and deserialization based on
java vector API
- - `java/fory-simd/src/main/java/org/apache/fory/util`: SIMD utilities
- - `java/fory-simd/src/main/java/org/apache/fory/serializer`: SIMD
accelerated serializers
-
-- **fory-test-core**: Core test utilities and data generators
-
-- **testsuite**: Complex test suite for issues reported by users and hard to
reproduce using simple test cases
-
-- **benchmark**: Benchmark suite based on jmh
-
-#### Bazel
-
-`bazel` dir provides build support for fory C++ and Cython:
-
-- `bazel/cython_library.bzl`: `pyx_library` rule for building Cython extensions
-
-Dependencies are managed via `MODULE.bazel` using bzlmod (Bazel 8+).
-
-#### C++
-
-- `cpp/fory/row`: Row format data structures
-- `cpp/fory/meta`: Compile-time reflection utilities for extract struct fields
information.
-- `cpp/fory/encoder`: Row format encoder and decoder
-- `cpp/fory/util`: Common utilities
- - `cpp/fory/util/buffer.h`: Buffer for reading and writing data
- - `cpp/fory/util/bit_util.h`: utilities for bit manipulation
- - `cpp/fory/util/string_util.h`: String utilities
- - `cpp/fory/util/status.h`: Status code for error handling
-
-#### Python
-
-Fory python has two implementations for the protocol:
-
-- **Python mode**: Pure python implementation based on `xlang serialization
format`, used for debugging and testing only. This mode can be enabled by
setting `ENABLE_FORY_CYTHON_SERIALIZATION=0` environment variable.
-- **Cython mode**: Cython based implementation based on `xlang serialization
format`, which is used by default and has better performance than pure python.
This mode can be enabled by setting `ENABLE_FORY_CYTHON_SERIALIZATION=1`
environment variable.
-- **Python mode** and **Cython mode** reused some code from each other to
reduce code duplication.
-- **Debug Struct Serialization**: set `ENABLE_FORY_DEBUG_OUTPUT=1` to enable
detailed struct serialization/deserialization logs while debugging protocol
behavior.
-
-Code structure:
-
-- `python/pyfory/serialization.pyx`: Core serialization logic and entry point
for cython mode based on `xlang serialization format`
-- `python/pyfory/_fory.py`: Serialization entry point for pure python mode
based on `xlang serialization format`
-- `python/pyfory/registry.py`: Type registry, resolution and serializer
dispatch for pure python mode, which is also used by cython mode. Cython mode
use a cache to reduce invocations to this module.
-- `python/pyfory/serializer.py`: Serializers for non-internal types
-- `python/pyfory/includes`: Cython headers for `c++` functions and classes.
-- `python/pyfory/resolver.py`: resolving shared/circular references when ref
tracking is enabled in pure python mode
-- `python/pyfory/format`: Fory row format encoding and decoding, arrow
columnar format interoperation
-- `python/pyfory/buffer.pyx`: Buffer for reading/writing data, string
utilities. Used by `serialization.pyx` and `python/pyfory/format` at the same
time.
-
-#### Go
-
-Fory go provides reflection-based and codegen-based serialization and
deserialization.
-
-- `go/fory/fory.go`: serialization entry point
-- `go/fory/resolver.go`: resolving shared/circular references when ref
tracking is enabled
-- `go/fory/type.go`: type system and type resolution, serializer dispatch
-- `go/fory/slice.go`: serializers for `slice` type
-- `go/fory/map.go`: serializers for `map` type
-- `go/fory/set.go`: serializers for `set` type
-- `go/fory/struct.go`: serializers for `struct` type
-- `go/fory/string.go`: serializers for `string` type
-- `go/fory/buffer.go`: Buffer for reading/writing data
-- `go/fory/codegen`: code generators, provide code generator to be invoked by
`go:generate` to generate serialization code to speed up the serialization.
-- `go/fory/meta`: Meta string compression
-
-#### Rust
-
-Fory rust provides macro-based serialization and deserialization. Fory rust
consists of:
-
-- **fory**: Main library entry point
- - `rust/fory/src/lib.rs`: main library entry point to export API to users
-- **fory-core**: Core library for serialization and deserialization
- - `rust/fory-core/src/fory.rs`: main serialization entry point
- - `rust/fory-core/src/resolver/type_resolver.rs`: type resolution and
registration
- - `rust/fory-core/src/resolver/metastring_resolver.rs`: resolver for meta
string
- - `rust/fory-core/src/resolver/context.rs`: context for reading/writing
- - `rust/fory-core/src/buffer.rs`: buffer for reading/writing data
- - `rust/fory-core/src/meta`: meta string compression, type meta encoding
- - `rust/fory-core/src/serializer`: serializers for each supported type
- - `rust/fory-core/src/row`: row format encoding and decoding
-- **fory-derive**: Rust macro-based codegen for serialization and
deserialization
- - `rust/fory-derive/src/object`: macro for serializing/deserializing structs
- - `rust/fory-derive/src/fory_row`: macro for encoding/decoding row format
-
-#### Integration Tests
-
-`integration_tests` contains integration tests with following modules:
-
-- **cpython_benchmark**: benchmark suite for fory python
-- **graalvm_tests**: test suite for fory java on graalvm.
- - Note that fory use codegen to support graalvm instead of reflection, fory
don't use `reflect-config.json` for
- serialization, this is the core advantage of compared to graalvm JDK
serialization.
-- **jdk_compatibility_tests**: test suite for fory serialization compatibility
between multiple JDK versions
-
-## Key Development Guidelines
-
-### Performance Guidelines
-
-- **Performance First**: Never introduce code that reduces performance without
explicit justification
-- **Benchmark Required After Perf Optimizations**: For every code change
expected to improve performance, run the relevant benchmark immediately after
applying the change and report the measured results (command + before/after
numbers) in your response/PR.
-- **Performance Trace Log**: For every performance-optimization round, append
the hypothesis, code change, benchmark command, before/after numbers, and
keep/revert decision to `tasks/perf_optimization_rounds.md` before moving to
the next round.
-- **Zero-Copy**: Leverage zero-copy techniques when possible
-- **JIT Compilation**: Consider JIT compilation opportunities
-- **Memory Layout**: Optimize for cache-friendly memory access patterns
-
-### Code Quality
-
-- **Public APIs**: Must be well-documented and easy to understand
-- **Error Handling**: Implement comprehensive error handling with meaningful
messages
-- **Type Safety**: Use strong typing and generics appropriately
-- **Null Safety**: Handle null values appropriately for each language
-
-### Cross-Language Considerations
-
-- **Protocol Compatibility**: Ensure serialization compatibility across
languages
-- **Type Mapping**: Understand type mapping between languages (see
`docs/specification/xlang_type_mapping.md`)
-- **Endianness**: Handle byte order correctly for cross-platform compatibility
-- **Version Compatibility**: Maintain backward compatibility when possible
-
-### Security and Compatibility
-
-- **Class registration**: Keep class registration enabled unless explicitly
requested; use custom class checkers or policies if disabling.
-- **Schema evolution**: Prefer schema-consistent mode unless compatibility is
required; update compatibility tests when changing schema rules.
-
-### Testing Strategy
-
-- **Unit Tests**: Focus on internal behavior verification
-- **Integration Tests**: Use `integration_tests/` for cross-language
compatibility
-- **Language alignment and protocol compatibility**: Run
`org.apache.fory.xlang.CPPXlangTest`, `org.apache.fory.xlang.CSharpXlangTest`,
`org.apache.fory.xlang.RustXlangTest`, `org.apache.fory.xlang.GoXlangTest`, and
`org.apache.fory.xlang.PythonXlangTest` when changing xlang or type mapping
behavior
-- **Performance Tests**: Include benchmarks for performance-critical changes
-
-### Documentation Requirements
-
-- **API Changes**: Update relevant documentation in `docs/`
-- **Protocol Changes**: Update specifications in `docs/specification/`
-- **Examples**: Provide working examples for new features
-- **Migration Guides**: Document breaking changes and migration paths
-
-## Development Workflow
-
-### Before Making Changes
-
-1. **Read Specifications**: Review relevant docs in `docs/specification/`
-2. **Understand Architecture**: Study the language-specific implementation
structure
-3. **Check Existing Tests**: Look at existing test patterns and coverage
-4. **Review Related Issues**: Check GitHub issues for context
-
-### Making Changes
-
-1. **Follow Language Conventions**: Respect each language's idioms and patterns
-2. **Maintain Performance**: Profile performance-critical changes
-3. **Add Tests**: Include appropriate tests for new functionality
-4. **Update Documentation**: Update docs for API changes
-5. **Format Code**: Use language-specific formatters before committing
-
-## Debugging Guidelines
-
-### Protocol Issues
-
-- **Use Python Mode**: Set `ENABLE_FORY_CYTHON_SERIALIZATION=0` for debugging
-- **Check Specifications**: Refer to protocol specs in `docs/specification/`
-- **Cross-Language Testing**: Use integration tests to verify compatibility
-
-### Performance Issues
-
-- **Profile First**: Use appropriate profilers for each language
-- **Memory Analysis**: Check for memory leaks and allocation patterns
-
-### Build Issues
-
-- **Clean Builds**: Use language-specific clean commands
-- **Dependency Issues**: Check version compatibility
-- **Bazel Issues**: Use `bazel clean --expunge` for deep cleaning
-
-### Language-Specific Debugging
-
-- **Java**: Set `FORY_CODE_DIR` to dump generated code;
`ENABLE_FORY_GENERATED_CLASS_UNIQUE_ID=false` keeps stable generated class
names.
-- **Python**: Use `cython --cplus -a pyfory/serialization.pyx` for annotated
output; `FORY_DEBUG=true python setup.py build_ext --inplace` for debug builds.
-- **C++**: See `docs/cpp_debug.md`; generate `compile_commands.json` with
`bazel run :refresh_compile_commands`.
-- **Crash debugging**: For macOS core dump setup, follow `CONTRIBUTING.md`.
-
-### Profiling
-
-- **C++**: DTrace-based stack sampling is documented in `CONTRIBUTING.md`.
-
-## IDE Notes
-
-- **IntelliJ IDEA**: Java modules target different bytecode levels (Java
8/11). Use a JDK 11+ project SDK and disable `--release` if it blocks
`sun.misc.Unsafe` access (see `CONTRIBUTING.md`).
-
-## CI/CD Understanding
-
-### GitHub Actions Workflows
-
-- **`ci.yml`**: Main CI workflow for all languages
-- **`build-native-*.yml`**: Mac/Window python wheel build workflows
-- **`build-containerized-*.yml`**: Containerized python wheel build workflows
for linux
-- **`lint.yml`**: Code formatting and linting
-- **`pr-lint.yml`**: PR-specific checks
-
-### Fixing GitHub CI Errors
-
-Use the GitHub CLI (`gh`) to inspect and fix CI failures:
-
-```bash
-# List all checks for a PR and their status
-gh pr checks <PR_NUMBER> --repo apache/fory
-
-# View failed job logs (get job ID from pr checks output)
-gh run view <RUN_ID> --repo apache/fory --job <JOB_ID> --log-failed
-
-# View full job logs
-gh run view <RUN_ID> --repo apache/fory --job <JOB_ID> --log
-
-# Example workflow for fixing CI errors:
-# 1. List checks to find failing jobs
-gh pr checks 2942 --repo apache/fory
-
-# 2. Get the failed job logs (RUN_ID and JOB_ID from step 1)
-gh run view 19735911308 --repo apache/fory --job 56547673283 --log-failed
-
-# 3. Fix the issues based on error messages
-# 4. Commit and push fixes
-```
-
-Common CI failures and fixes:
-
-- **Code Style Check**: Run formatters (`clang-format`, `prettier`,
`spotless:apply`, etc.)
-- **Markdown Lint**: Run `prettier --write <file>` for markdown files
-- **C++ Build Errors**: Check for missing dependencies or header includes
-- **Test Failures**: Run tests locally to reproduce and fix
-
-## PR and Benchmark Expectations
-
-- **PR titles**: Follow Conventional Commits; CI uses
`.github/workflows/pr-lint.yml` to enforce naming.
-- **Performance changes**: Use the `perf` type and include benchmark data (see
`benchmarks/java/README.md`).
-
-## Commit Message Format
-
-Use conventional commits with language scope:
-
-```
-feat(java): add codegen support for xlang serialization
-fix(rust): fix collection header when collection is empty
-docs(python): add docs for xlang serialization
-refactor(java): unify serialization exceptions hierarchy
-perf(cpp): optimize buffer allocation in encoder
-test(integration): add cross-language reference cycle tests
-ci: update build matrix for latest JDK versions
-chore(deps): update guava dependency to 32.0.0
-```
+This is the entry point for AI guidance in Apache Fory. Read this file first,
then load only the `.agents/*.md` files that match the runtimes or areas you
touch.
+
+## Load Additional Guidance On Demand
+
+- `.agents/README.md`: routing table for selective loading.
+- `.agents/repo-reference.md`: repo layout, architecture, compiler notes, and
key directories.
+- `.agents/docs-and-formatting.md`: documentation, specification, and markdown
rules.
+- `.agents/ci-and-pr.md`: CI triage, PR expectations, and commit conventions.
+- `.agents/testing/integration-tests.md`: `integration_tests/` prerequisites,
regeneration rules, and commands.
+- `.agents/languages/java.md`
+- `.agents/languages/csharp.md`
+- `.agents/languages/cpp.md`
+- `.agents/languages/python.md`
+- `.agents/languages/go.md`
+- `.agents/languages/rust.md`
+- `.agents/languages/swift.md`
+- `.agents/languages/javascript.md`
+- `.agents/languages/dart.md`
+- `.agents/languages/kotlin.md`
+- `.agents/languages/scala.md`
+- For protocol or xlang changes, load the relevant language files plus
`.agents/docs-and-formatting.md` and `.agents/testing/integration-tests.md`.
+
+## Repo-Wide Hard Rules
+
+- Do not preserve legacy, dead, or useless code, tests, or docs unless the
user explicitly requests it.
+- Ignore internal API compatibility unless the user explicitly requests it. Do
not keep shims, wrappers, or transitional paths only to preserve internal call
sites.
+- Performance is the top priority. Do not introduce regressions without
explicit justification.
+- Use English only in code, comments, and documentation.
+- Add comments only when behavior is hard to understand or an algorithm is
non-obvious.
+- Only add tests that verify internal behaviors or fix specific bugs; do not
create unnecessary tests unless requested.
+- Do not add cleanup-sentinel tests that only pin deleted APIs or removed
fields.
+- When reading code, skip files not tracked by git by default unless you
generated them yourself or the task explicitly requires them.
+- Maintain cross-language consistency while respecting language-specific
idioms.
+- Do not introduce checked exceptions in new code or new APIs.
+- Do not use `ThreadLocal` or other ambient runtime-context patterns in Java
runtime code. `WriteContext`, `ReadContext`, and `CopyContext` state must stay
explicit, generated serializers must not retain context fields, and `Fory` must
stay a root-operation facade rather than accumulating serializer/runtime
convenience state.
+- When a serializer class and constructor shape are known at the call site,
prefer direct constructor lambdas or direct instantiation over reflective
`Serializers.newSerializer(...)`. Keep reflection for dynamic or general
construction paths only.
+- For GraalVM, use `fory codegen` to generate serializers when building native
images. Do not use GraalVM reflection configuration except for JDK `proxy`.
+- In Java native mode (`xlang=false`), only `Types.BOOL` through
`Types.STRING` share type IDs with xlang mode (`xlang=true`). Other native-mode
type IDs differ.
+- Keep class registration enabled unless explicitly requested otherwise.
+- Prefer schema-consistent mode unless compatibility work requires something
else.
+- When debugging test errors, always set `ENABLE_FORY_DEBUG_OUTPUT=1` to see
debug output.
+- Never work around failures. Find and fix the root cause. Do not hack,
weaken, or bypass tests to make them pass.
+
+## Source of Truth
+
+- Primary references: `README.md`, `CONTRIBUTING.md`,
`docs/guide/DEVELOPMENT.md`, and language guides under `docs/guide/`.
+- Protocol changes require reading and updating the relevant specs in
`docs/specification/**` and aligning the relevant cross-language tests.
+- If instructions conflict, follow the most specific module docs and call out
the conflict.
+- Updates under `docs/guide/` and `docs/benchmarks/` are synced to
`apache/fory-site`; other website content belongs there.
+- When benchmark logic, scripts, configuration, or compared serializers
change, rerun the relevant benchmarks and refresh the artifacts under
`docs/benchmarks/**`.
+
+## Shared Engineering Expectations
+
+- Favor zero-copy techniques, JIT or codegen opportunities, and cache-friendly
memory access patterns in performance-critical paths.
+- Public APIs must be well-documented and easy to understand.
+- Implement comprehensive error handling with meaningful messages.
+- Use strong typing and generics appropriately.
+- Handle null values appropriately for each language.
+- Preserve protocol compatibility across languages.
+- Read and respect `docs/specification/xlang_type_mapping.md` when changing
cross-language type behavior.
+- Handle byte order correctly for cross-platform compatibility.
+
+## Git And Review Rules
+
+- Use `[email protected]:apache/fory.git` as the remote repository. Do not use
other remotes when you want to check code under `main`; `apache/main` is the
only target main branch instead of `origin/main`.
+- Treat `apache/main` as the only mainline baseline, not `origin/main`.
+- Before any diff, review, or compare work against `apache/main`, run `git
fetch apache main` so comparisons use the latest remote main.
+- When reviewing a GitHub pull request, always do the review in a new local
git worktree. Do not switch the current branch or reuse the current worktree
for that review unless the user explicitly asks for it.
+- Contributors should fork `[email protected]:apache/fory.git`, push code
changes to the fork, and open pull requests from that fork into `apache/fory`.
+
+## Shared Validation Expectations
+
+- Run the relevant tests for every touched language or subsystem before
finishing.
+- Use `integration_tests/` for cross-language compatibility validation when
behavior crosses runtimes.
+- If xlang behavior or type mapping changes, run
`org.apache.fory.xlang.CPPXlangTest`, `org.apache.fory.xlang.CSharpXlangTest`,
`org.apache.fory.xlang.RustXlangTest`, `org.apache.fory.xlang.GoXlangTest`, and
`org.apache.fory.xlang.PythonXlangTest`.
+- If Swift xlang behavior changes, run `org.apache.fory.xlang.SwiftXlangTest`
too.
+- For performance work, run the relevant benchmark immediately after each
change and report the command plus before/after numbers.
+- For performance-optimization rounds, append the hypothesis, change,
benchmark command, before/after numbers, and keep/revert decision to
`tasks/perf_optimization_rounds.md`.
+
+## Working Process
+
+1. Read the relevant specs, guides, and focused `.agents/*.md` files before
editing.
+2. Understand the affected architecture, subsystem boundaries, and existing
tests before changing behavior.
+3. Review related issues for context when the change is tied to a known bug,
regression, or feature request.
+4. Follow the language-specific rules in `.agents/languages/*.md` for the
touched runtimes.
+5. Update docs, examples, and specs when public behavior, protocol behavior,
or workflows change.
+6. Format and verify the changed areas before concluding.
+
+## Repo Map
+
+- `docs/`: specifications, guides, benchmarks, and compiler docs
+- `compiler/`: Fory compiler, parser, IR, and code generators
+- `java/`, `csharp/`, `cpp/`, `python/`, `go/`, `rust/`, `swift/`,
`javascript/`, `dart/`, `kotlin/`, `scala/`: language implementations
+- `integration_tests/`: cross-language integration coverage
+- `benchmarks/`: benchmark harnesses and reports
+- `.github/workflows/` and `ci/`: CI configuration and helper scripts
+
+## Commit And PR Expectations
+
+- PR titles must follow Conventional Commits; `.github/workflows/pr-lint.yml`
enforces this.
+- Performance changes should use the `perf` type and include benchmark data.
+- See `.agents/ci-and-pr.md` for GitHub CLI triage commands and commit message
examples.
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
