perf: optimize compatible mode read performance

.agents/languages/cpp.md

@@ -16,6 +16,7 @@ Load this file when changing `cpp/`, Cython build plumbing, or C++ xlang behavio
 - Put private methods last in class definitions, immediately before private fields.
 - Do not redesign alias-based or low-level public type shapes to add convenience methods unless the user explicitly asks for that API change.
 - For cross-language feature ports, match protocol behavior but use idiomatic C++ ownership and layering instead of mirroring Java structure literally.
+- Compatible scalar, list-array, and binary/uint8-array adaptations are immediate-field-only. Recursive matched-field comparison for collection elements, array elements, map keys, and map values must require exact nullability, ref tracking, generic arity, and type shape except documented user-type family normalization.
 
 ## Key Paths
 

.agents/languages/csharp.md

@@ -9,6 +9,7 @@ Load this file when changing `csharp/` or C# xlang behavior.
 - C# code must build without compiler or analyzer warnings. Treat warnings as blockers in project, test, and generated code.
 - Fory C# requires .NET SDK `8.0+` and C# `12+`.
 - Use `dotnet format` to keep C# code style consistent.
+- Compatible scalar, list-array, and binary/uint8-array adaptations are immediate-field-only. Recursive matched-field comparison for collection elements, array elements, map keys, and map values must require exact nullability, ref tracking, generic arity, and type shape except documented user-type family normalization.
 - When extending C# tests from Java references, prioritize xlang spec behavior and the public C# contract before adding complex Java-specific parity cases.
 
 ## Commands

.agents/languages/dart.md

@@ -17,6 +17,9 @@ Load this file when changing `dart/`.
 - Codegen must support private fields through same-library `part` generation. If generated file naming changes from `*.fory.dart`, update builder config, source `part` directives, analysis exclusions, docs, CI snippets, and stale artifacts together.
 - Keep generated Dart outputs (`*.fory.dart`) and Dart `pubspec.lock` files untracked in this repo.
 - For generated numeric or xlang changes, test root values and generated required/nullable fields across schema-consistent and compatible serializers, metadata type IDs, rejection paths, and every affected encoding mode.
+- Compatible scalar conversion is immediate-field-only. Recursive compatible schema comparison for list elements, typed-array elements, map keys, and map values must reject scalar mismatches instead of applying top-level scalar conversion.
+- Generated compatible struct reads must consume per-remote-field read descriptors built before field dispatch. Exact doubled cases read directly from local field metadata and must not receive remote compatible metadata; compatible scalar cases use preclassified scalar read descriptors instead of layout-wide scalar source arrays or hot schema/type-pair eligibility helpers.
+- Generated struct serializers should use serializer-owned field descriptors for runtime resolver decisions and emit direct field-specific write/read code for static schemas. Do not route generated hot writes through generic field-info value helpers such as `writeGeneratedStructFieldInfoValue`.
 - Dart xlang or runtime ownership changes need local Dart package tests plus the Java-driven `DartXlangTest`; package-only smoke tests are not enough.
 - When claiming non-VM Dart support, prove a relevant non-VM compile path such as `dart compile js` against active runtime or example code.
 

.agents/languages/java.md

@@ -128,6 +128,9 @@ Load this file when changing anything under `java/` or when Java drives a cross-
   `ObjectInstantiators.getObjectInstantiator(TypeResolver, Class)` or bypass the runtime-scoped owner; format
   builders without a Fory runtime context may use the base `ObjectInstantiators.getObjectInstantiator(Class)`
   construction default.
+- Compatible scalar, list-array, and binary/uint8 adapters are immediate-field-only. For matched
+  nested field metadata, classify schema pairs before generated dispatch and require exact
+  nullable/ref/generic/type shape, except for user-defined type-family normalization.
 - Root codegen and builder classes that still need Unsafe on JDK8-24 must route symbolic Unsafe
   access through a helper with a Java 25 replacement. Do not leave `_JDKAccess.unsafe()` or
   `sun.misc.Unsafe` references in JDK25-visible classes outside matching `java25` replacements.
@@ -230,9 +233,13 @@ Load this file when changing anything under `java/` or when Java drives a cross-
 - Source-generated constructor serializers must own their constructor metadata at generation time
   and call constructors directly. They must not depend on runtime `ObjectInstantiator` constructor-field
   metadata or varargs constructor calls.
-- Java annotation-processor static serializers do not own ordinary-class constructor metadata.
-  Reject ordinary non-record final fields instead of generating descriptor-based final-field
-  mutation; records and Kotlin KSP primary-constructor serializers are the constructor-owned paths.
+- Java annotation-processor static serializers must support the same Java class surface as normal
+  Fory object serialization when compatible-read static generation needs it. Ordinary classes that
+  cannot be assigned directly should allocate through generated-subclass-owned
+  `ObjectInstantiator` state and write private, inaccessible, or final fields through
+  generated-subclass-owned cached `FieldAccessor`s. Do not add constructor-binding APIs, per-read
+  reflective lookup, descriptor-based varargs constructor calls, or shared-parent argument buffers.
+  Records and Kotlin KSP primary-constructor serializers remain constructor-owned paths.
 - Generated JVM copy code may direct-copy immutable scalar values, but Java `Collection`/`Map`
   subclasses must be copied through `CopyContext.copyObject(...)` so collection/map serializers own
   concrete type, comparator, wrapper, and reference behavior.

.agents/languages/javascript.md

@@ -12,6 +12,9 @@ Load this file when changing `javascript/`.
 - Runtime value carriers such as decimal or reduced-precision numeric types belong under the core `types/` ownership boundary, with imports, exports, and codegen externals updated together.
 - Keep `TypeInfo` as schema metadata. Compatibility-sensitive decisions belong on `TypeResolver` or explicit operations, not as retained resolver state on metadata objects.
 - Normalize optional boolean config values at config construction; do not carry `null` through runtime paths when it means `false`.
+- Regenerated compatible read serializers are remote-schema-specific. After classification marks a field as direct, compatible scalar, or skip, generated JavaScript should emit straight-line remote-field-order code. Do not add an outer matched-id switch unless the current regenerated shape cannot preserve those semantics.
+- Compatible scalar codegen must decide the exact remote/local scalar pair before emitting source. Generate the concrete `reader.readXxx()` call plus inline trivial conversions such as boolean-to-string or numeric widening, and keep helpers only for semantic validation such as range checks, exactness checks, decimal parsing/formatting, and string-to-bool. Do not call a generic hot-path converter that redispatches on `remoteTypeId`, `localTypeId`, field descriptors, or field names.
+- Compatible scalar conversion is immediate-field-only. Recursive schema comparison for collection elements, array elements, map keys, and map values must reject scalar mismatches instead of applying the top-level scalar conversion matrix.
 
 ## Commands
 

.agents/languages/python.md

@@ -18,6 +18,7 @@ Load this file when changing `python/`, Cython serialization, or Python xlang be
 - For wheel or extension pipeline changes, derive extension-module paths from current build targets, packaging config, or wheel payload discovery rather than historical module names.
 - Keep new Python test names compact and behavior-focused; avoid sentence-length names that restate setup details already obvious from the test body.
 - `ENABLE_FORY_DEBUG_OUTPUT=1` enables detailed struct serialization and deserialization logs.
+- Compatible scalar, list-array, and binary/uint8-array adaptations are immediate-field-only. Recursive matched-field comparison for collection elements, array elements, map keys, and map values must require exact nullability, ref tracking, generic arity, and type shape except documented user-type family normalization.
 
 ## Key Paths
 

.agents/languages/rust.md

@@ -15,6 +15,7 @@ Load this file when changing `rust/` or Rust xlang behavior.
 - Runtime carriers belong in `types/`, and schema or type-hash helpers belong with metadata hashing rather than generic wire/type-id modules.
 - If breakage is explicitly acceptable during a Rust module refactor, rewire macros, tests, and sibling crates directly to the new boundaries instead of adding compatibility re-exports.
 - For panic-safety in hot paths, preserve TLS context reuse. Add scoped guards or owned fallbacks rather than per-call context allocation, and reset reused contexts at entry and successful exit.
+- Compatible scalar, list-array, and binary/uint8-array adaptations are immediate-field-only. Keep recursive matched-field shape classification owned by `fory-core/src/meta/type_meta.rs`; collection elements, array elements, map keys, and map values must require exact nullability, ref tracking, generic arity, and type shape except documented user-type family normalization.
 
 ## Key Paths
 
@@ -77,5 +78,5 @@ cargo bench
 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
+RUST_BACKTRACE=1 FORY_RUST_JAVA_CI=1 ENABLE_FORY_DEBUG_OUTPUT=1 mvn test -Dtest=org.apache.fory.xlang.RustXlangTest
 ```

.agents/languages/swift.md

@@ -12,6 +12,7 @@ Load this file when changing `swift/` or Swift xlang behavior.
 - Prefer the user-requested or existing Foundation public value type when it is the intended Swift surface; do not invent Fory-prefixed wrappers only to avoid import ambiguity.
 - Preserve distinct temporal semantics. Timestamp values and day-only local dates should have protocol-accurate helper names and no stale aliases after a refactor.
 - When temporal or public-type refactors touch generated Swift code, sweep message fields, union payloads, macros, xlang harnesses, and integration fixtures together.
+- Compatible scalar, list-array, and binary/uint8-array adaptations are immediate-field-only. Recursive matched-field comparison for collection elements, array elements, map keys, and map values must require exact nullability, ref tracking, generic arity, and type shape except documented user-type family normalization.
 
 ## Commands
 

.agents/testing/integration-tests.md

@@ -7,6 +7,9 @@ Load this file when changing `integration_tests/`, xlang behavior, compiler-gene
 - 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`.
+- Do not set `FORY_PANIC_ON_ERROR` for normal tests, CI reproduction, or xlang validation. It is
+  only for focused debugging. Verification commands should omit it, while test harnesses must not
+  filter it when the user command provides it.
 - 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.

AGENTS.md

@@ -90,6 +90,9 @@ This is the entry point for AI guidance in Apache Fory. Read this file first, th
 - 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.
+- Do not set `FORY_PANIC_ON_ERROR` for normal tests, CI reproduction, or xlang validation.
+  It is a focused debug knob only; omit it from verification commands, but do not filter it
+  from test harnesses when the user command provides it.
 - Never work around failures. Find and fix the root cause. Do not hack, weaken, or bypass tests to make them pass.
 
 ## Source of Truth
@@ -131,6 +134,7 @@ This is the entry point for AI guidance in Apache Fory. Read this file first, th
 ## Shared Validation Expectations
 
 - Run the relevant tests for every touched language or subsystem before finishing.
+- A formatter-only pass after successful tests does not invalidate those test results. Do not rerun tests solely because formatting ran after the tests already passed.
 - When multiple independent language test suites are required, run them concurrently when the environment has enough resources instead of running them one by one; keep each language's logs and results separate, and rerun any failed suite with focused diagnostics.
 - Run applicable test commands in a subagent with a thinking budget one level lower than the main task budget, using medium when the current budget is unclear, unless the change is docs-only or the user explicitly asks to run them locally.
 - Reuse the same test subagent for repeated runs within one task and subsystem so it keeps failure context; create a fresh subagent when switching unrelated subsystems or when prior context may be stale or misleading.

benchmarks/cpp/README.md

@@ -73,6 +73,15 @@ Examples:
 ./run.sh --data struct --serializer fory --duration 5
 ```
 
+## Schema Mismatch Mode
+
+Set `FORY_BENCH_SCHEMA_MISMATCH=1` to run the Fory-only compatible-read
+schema-mismatch mode. This mode is off by default. When enabled, run with
+`--serializer fory`; protobuf and MessagePack benchmark modes fail with a
+configuration error. Fory serialization uses the normal v1 benchmark structs,
+and Fory deserialization uses v2 structs registered with the same Fory type IDs
+where one int32 field is widened to int64.
+
 ## Building
 
 ```bash