feat(xlang): compatible read between list array field

.agents/docs-and-formatting.md

@@ -37,6 +37,10 @@ Load this file when changing documentation, public APIs, protocol specs, benchma
 - Python code, including `compiler/`, `benchmarks/`, `integration_tests/`, and `python/`:
   `python -m ruff format <changed-python-files>` and
   `python -m ruff check --fix <changed-python-files>`
+- JavaScript/TypeScript under `javascript/`: use the package's ESLint-owned formatting path
+  (`npm run lint -- --fix` when fixing style, `npm run lint -- --quiet` when checking). Do not run
+  Prettier on JavaScript or TypeScript files unless that package has an explicit Prettier config or
+  script; otherwise it creates unrelated formatting churn.
 - Repo-wide format and lint sweep: `bash ci/format.sh --all`
 
 When code changes touch `compiler/` or `benchmarks/`, format those changed source files with the

.gitignore

@@ -128,6 +128,8 @@ csharp/artifacts/
 tasks/
 benchmarks/python/proto/
 benchmarks/java/dependency-reduced-pom.xml
+benchmarks/go/go.test
+benchmarks/rust/Cargo.lock
 docs/superpowers
 test.md
 
@@ -136,4 +138,4 @@ benchmarks/dart/profile_output
 integration_tests/idl_tests/dart/.dart_tool/
 **/pubspec.lock
 
-**/tmp/*
+**/tmp/*

AGENTS.md

@@ -39,6 +39,17 @@ This is the entry point for AI guidance in Apache Fory. Read this file first, th
 - Keep task boundaries strict. Review tasks do not edit code, analysis-only tasks do not silently turn into implementation, and active-branch fixes must land in the active branch/workspace.
 - For non-trivial multi-step tasks, write the plan and progress into the canonical durable task file (use a matched skill/workflow file if it provides one, otherwise use a file under `tasks/`) and read that file after compaction before continuing.
 
+## Design Integrity Gates
+
+- Record all core design and decisions in the owning docs when they belong there, especially under `docs/guide/**` or `docs/specification/**`.
+- Do not allow implementation drift from the design document.
+- Do not compromise design decisions to make implementation easier.
+- Do not leave workaround code behind.
+- All code must have a clean owner model; the wrong owner model or abstraction is unacceptable.
+- Do not leave ugly or temporary code behind.
+- Do not leave legacy, dead, useless, or stale code, tests, or docs behind.
+- Do not leave avoidable technical debt behind.
+
 ## Repo-Wide Hard Rules
 
 - Do not preserve legacy, dead, or useless code, tests, or docs unless the user explicitly requests it.

benchmarks/javascript/benchmark.js

@@ -29,7 +29,7 @@ const core = require(path.join(JS_ROOT, "packages", "core", "dist", "index.js"))
 const protobuf = require(path.join(JS_ROOT, "node_modules", "protobufjs"));
 
 const Fory = core.default;
-const { Type } = core;
+const { BoolArray, Type } = core;
 
 const DEFAULT_DURATION_SECONDS = 3;
 const SERIALIZER_ORDER = ["fory", "protobuf", "json"];
@@ -664,6 +664,26 @@ function normalizeForyValue(datasetKey, value) {
   }
 }
 
+function normalizeForyRoundTripValue(datasetKey, value) {
+  switch (datasetKey) {
+    case "sample":
+      return {
+        ...value,
+        boolean_array: value.boolean_array instanceof BoolArray
+          ? Array.from(value.boolean_array)
+          : value.boolean_array,
+      };
+    case "samplelist":
+      return {
+        sample_list: value.sample_list.map((item) =>
+          normalizeForyRoundTripValue("sample", item)
+        ),
+      };
+    default:
+      return value;
+  }
+}
+
 function normalizeProtobufValue(datasetKey, value) {
   switch (datasetKey) {
     case "sample":
@@ -687,7 +707,10 @@ function ensureSerializationWorks(dataset) {
   const foryValue = normalizeForyValue(dataset.key, value);
   const foryBytes = dataset.forySerializer.serialize(foryValue);
   const foryRoundTrip = dataset.forySerializer.deserialize(foryBytes);
-  assert.deepStrictEqual(foryRoundTrip, foryValue);
+  assert.deepStrictEqual(
+    normalizeForyRoundTripValue(dataset.key, foryRoundTrip),
+    foryValue
+  );
 
   const protoPayload = dataset.toProto(value);
   const protoBytes = dataset.protoType.encode(dataset.protoType.create(protoPayload)).finish();

benchmarks/swift/Sources/SwiftBenchmark/BenchmarkRunner.swift

@@ -68,7 +68,7 @@ final class BenchmarkSuite {
 
     init(config: BenchmarkConfig) {
         self.config = config
-        self.fory = Fory(xlang: false, trackRef: false, compatible: true)
+        self.fory = Fory(xlang: false, ref: false, compatible: true)
         registerTypes()
     }
 

cpp/fory/serialization/struct_compatible_test.cc

@@ -33,7 +33,9 @@
 
 #include "fory/serialization/fory.h"
 #include "gtest/gtest.h"
+#include <algorithm>
 #include <cstdint>
+#include <map>
 #include <string>
 #include <vector>
 
@@ -217,6 +219,44 @@ struct ProductV2 {
   FORY_STRUCT(ProductV2, name, price, tags, attributes);
 };
 
+struct CompatibleListField {
+  std::vector<int32_t> values;
+
+  FORY_STRUCT(CompatibleListField,
+              (values, fory::F(1).list(fory::T::int32().fixed())));
+};
+
+struct CompatibleArrayField {
+  std::vector<int32_t> values;
+
+  FORY_STRUCT(CompatibleArrayField,
+              (values, fory::F(1).array(fory::T::int32())));
+};
+
+struct CompatibleNullableListField {
+  std::vector<std::optional<int32_t>> values;
+
+  FORY_STRUCT(CompatibleNullableListField,
+              (values, fory::F(1).list(fory::T::fixed())));
+};
+
+struct CompatibleNestedListField {
+  std::map<std::string, std::vector<int32_t>> values;
+
+  FORY_STRUCT(CompatibleNestedListField,
+              (values,
+               fory::F(1).map(fory::T::string(),
+                              fory::T::list(fory::T::int32().fixed()))));
+};
+
+struct CompatibleNestedArrayField {
+  std::map<std::string, std::vector<int32_t>> values;
+
+  FORY_STRUCT(CompatibleNestedArrayField,
+              (values, fory::F(1).map(fory::T::string(),
+                                      fory::T::array(fory::T::int32()))));
+};
+
 // ============================================================================
 // TESTS
 // ============================================================================
@@ -417,6 +457,85 @@ TEST(SchemaEvolutionTest, CollectionFieldEvolution) {
   EXPECT_TRUE(prod_v2.attributes.empty()); // Default empty map
 }
 
+TEST(SchemaEvolutionTest, ImmediateListFieldCanReadIntoArrayCarrier) {
+  auto writer = Fory::builder().compatible(true).xlang(true).build();
+  auto reader = Fory::builder().compatible(true).xlang(true).build();
+
+  constexpr uint32_t TYPE_ID = 1005;
+  ASSERT_TRUE(writer.register_struct<CompatibleListField>(TYPE_ID).ok());
+  ASSERT_TRUE(reader.register_struct<CompatibleArrayField>(TYPE_ID).ok());
+
+  auto bytes = writer.serialize(CompatibleListField{{1, -2, 3}});
+  ASSERT_TRUE(bytes.ok()) << bytes.error().to_string();
+  auto decoded = reader.deserialize<CompatibleArrayField>(bytes.value().data(),
+                                                          bytes.value().size());
+
+  ASSERT_TRUE(decoded.ok()) << decoded.error().to_string();
+  EXPECT_EQ(decoded.value().values, (std::vector<int32_t>{1, -2, 3}));
+}
+
+TEST(SchemaEvolutionTest, ImmediateArrayFieldCanReadIntoListCarrier) {
+  auto writer = Fory::builder().compatible(true).xlang(true).build();
+  auto reader = Fory::builder().compatible(true).xlang(true).build();
+
+  constexpr uint32_t TYPE_ID = 1006;
+  ASSERT_TRUE(writer.register_struct<CompatibleArrayField>(TYPE_ID).ok());
+  ASSERT_TRUE(reader.register_struct<CompatibleListField>(TYPE_ID).ok());
+
+  auto bytes = writer.serialize(CompatibleArrayField{{4, 5, 6}});
+  ASSERT_TRUE(bytes.ok()) << bytes.error().to_string();
+  auto decoded = reader.deserialize<CompatibleListField>(bytes.value().data(),
+                                                         bytes.value().size());
+
+  ASSERT_TRUE(decoded.ok()) << decoded.error().to_string();
+  EXPECT_EQ(decoded.value().values, (std::vector<int32_t>{4, 5, 6}));
+}
+
+TEST(SchemaEvolutionTest, NullableListElementsCannotReadIntoArrayCarrier) {
+  auto writer = Fory::builder().compatible(true).xlang(true).build();
+  auto reader = Fory::builder().compatible(true).xlang(true).build();
+
+  constexpr uint32_t TYPE_ID = 1007;
+  ASSERT_TRUE(
+      writer.register_struct<CompatibleNullableListField>(TYPE_ID).ok());
+  ASSERT_TRUE(reader.register_struct<CompatibleArrayField>(TYPE_ID).ok());
+
+  auto bytes = writer.serialize(CompatibleNullableListField{{1, 2}});
+  ASSERT_TRUE(bytes.ok()) << bytes.error().to_string();
+  std::vector<uint8_t> payload = std::move(bytes).value();
+  auto decoded =
+      reader.deserialize<CompatibleArrayField>(payload.data(), payload.size());
+
+  ASSERT_TRUE(decoded.ok()) << decoded.error().to_string();
+  EXPECT_EQ(decoded.value().values, (std::vector<int32_t>{1, 2}));
+
+  bytes = writer.serialize(CompatibleNullableListField{{1, std::nullopt}});
+  ASSERT_TRUE(bytes.ok()) << bytes.error().to_string();
+  payload = std::move(bytes).value();
+  decoded =
+      reader.deserialize<CompatibleArrayField>(payload.data(), payload.size());
+
+  ASSERT_FALSE(decoded.ok());
+}
+
+TEST(SchemaEvolutionTest, NestedListArraySchemaPairsAreNotMatched) {
+  auto writer = Fory::builder().compatible(true).xlang(true).build();
+  auto reader = Fory::builder().compatible(true).xlang(true).build();
+
+  constexpr uint32_t TYPE_ID = 1008;
+  ASSERT_TRUE(writer.register_struct<CompatibleNestedListField>(TYPE_ID).ok());
+  ASSERT_TRUE(reader.register_struct<CompatibleNestedArrayField>(TYPE_ID).ok());
+
+  auto bytes = writer.serialize(
+      CompatibleNestedListField{{{"items", std::vector<int32_t>{7, 8}}}});
+  ASSERT_TRUE(bytes.ok()) << bytes.error().to_string();
+  auto decoded = reader.deserialize<CompatibleNestedArrayField>(
+      bytes.value().data(), bytes.value().size());
+
+  ASSERT_TRUE(decoded.ok()) << decoded.error().to_string();
+  EXPECT_TRUE(decoded.value().values.empty());
+}
+
 TEST(SchemaEvolutionTest, RoundtripWithSameVersion) {
   // Sanity check: V2 -> V2 should work perfectly
   auto fory_compat = Fory::builder().compatible(true).xlang(true).build();