fix(xlang): close field tag validation gaps (#3984)

## Why?

PR #3982 established the signed-int32 field-tag protocol range.
Follow-up integration checks found a
small set of validation ownership, exact-schema coverage, and
documentation gaps that were not part
of the squash-merged boundary.

This PR completes those paths without changing the field-tag wire format
introduced by #3982.

## What does this PR do?

- Rejects duplicate Java native TypeDef tags across the complete
inheritance hierarchy.
- Validates Go field tags before public registration mutates resolver
state while continuing to
  ignore unexported fields.
- Keeps Rust protocol metadata equality independent from local
compatible-reader dispatch state.
- Adds causal C++ remote-compatible and oversized-tag decoder coverage.
- Adds an exact-schema cross-language fixture for tags `15`, `65551`,
and `536870911` across all
  supported peers, including normal concrete Java test discovery.
- Runs Kotlin's maximum tag through a real KSP-generated serializer,
descriptor, and round trip.
- Documents the exact field-tag range, uniqueness, stability, and
extended encoding rules in the
  protocol, compiler, and runtime schema guides.

## Related issues

Follow-up to #3982.

## 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?

Invalid duplicate or out-of-range field-tag schemas are now rejected
consistently at their owning
registration or metadata boundary. Existing valid schemas and wire bytes
are unchanged.

## Test

- Java native TypeDef, Go registration, C++ metadata, Rust metadata
equality, and Kotlin KSP/static
  serializer tests passed.
- Exact-schema and compatible Java-driven field-tag cases passed against
C++, C#, Dart, Go,
  JavaScript, Python, Rust, Scala, and Swift in both Java codegen modes.
- Dart IDL regeneration, compilation, and Java/Dart semantic round trips
passed.
- Java Spotless, Rust fmt/clippy, Go formatting, C++ formatting,
Markdown Prettier, and full diff
  checks passed.

## Benchmark

The production changes in this follow-up are Java remote native-TypeDef
miss validation, Go
registration-time validation, and Rust `FieldInfo` equality. None is
reached by the steady-state
serialize/deserialize benchmark loops from #3982, so those paired
results remain the causal hot-path
evidence. Every measured runtime/path stayed below the `+1.0%`
regression ceiling; the largest
positive paired medians were C++ deserialize at `+0.858%` and Java
static serialize at `+0.779%`.

Author: chaokunyang

.github/workflows/ci.yml

@@ -559,7 +559,7 @@ jobs:
             ~/.swiftpm
             ~/Library/Caches/org.swift.swiftpm
             swift/.build
-          key: ${{ runner.os }}-${{ runner.arch }}-swiftpm-xlang-release-${{ steps.swift-package-cache.outputs.toolchain }}-${{ hashFiles('swift/Package.resolved', 'swift/Package.swift', 'swift/Sources/**') }}
+          key: ${{ runner.os }}-${{ runner.arch }}-swiftpm-xlang-release-${{ steps.swift-package-cache.outputs.toolchain }}-${{ hashFiles('swift/Package.resolved', 'swift/Package.swift', 'swift/Sources/**', 'swift/Tests/ForyXlangTests/**') }}
           restore-keys: |
             ${{ runner.os }}-${{ runner.arch }}-swiftpm-xlang-release-${{ steps.swift-package-cache.outputs.toolchain }}-
       - name: Prebuild Swift xlang peer for cache reuse

cpp/fory/serialization/struct_test.cc

@@ -146,6 +146,20 @@ struct MaximumFieldTagStruct {
   FORY_STRUCT(MaximumFieldTagStruct, (value, fory::F(536870911)));
 };
 
+struct HighTagCompatibleWriter {
+  std::string removed;
+  int32_t shared;
+
+  FORY_STRUCT(HighTagCompatibleWriter, (removed, fory::F(65551)),
+              (shared, fory::F(536870911)));
+};
+
+struct HighTagCompatibleReader {
+  int32_t shared = 0;
+
+  FORY_STRUCT(HighTagCompatibleReader, (shared, fory::F(536870911)));
+};
+
 struct SignedToUnsignedWriter {
   int32_t value;
 
@@ -1403,6 +1417,12 @@ TEST(StructComprehensiveTest, FieldTagRange) {
   invalid.field_id = 536870912;
   EXPECT_FALSE(invalid.to_bytes().ok());
 
+  Buffer invalid_wire;
+  invalid_wire.write_uint8(static_cast<uint8_t>((3u << 6) | (15u << 2)));
+  invalid_wire.write_var_uint32(536870912u - 15u);
+  invalid_wire.write_uint8(static_cast<uint8_t>(TypeId::INT32));
+  EXPECT_FALSE(FieldInfo::from_bytes(invalid_wire).ok());
+
   TypeMeta duplicate;
   duplicate.type_id = static_cast<uint32_t>(TypeId::COMPATIBLE_STRUCT);
   duplicate.user_type_id = 632;
@@ -1412,6 +1432,21 @@ TEST(StructComprehensiveTest, FieldTagRange) {
   EXPECT_FALSE(duplicate.to_bytes().ok());
 }
 
+TEST(StructComprehensiveTest, CompatibleHighTagsRead) {
+  auto writer =
+      Fory::builder().xlang(true).compatible(true).track_ref(false).build();
+  auto reader =
+      Fory::builder().xlang(true).compatible(true).track_ref(false).build();
+  ASSERT_TRUE(writer.register_struct<HighTagCompatibleWriter>(633).ok());
+  ASSERT_TRUE(reader.register_struct<HighTagCompatibleReader>(633).ok());
+
+  auto encoded = writer.serialize(HighTagCompatibleWriter{"skip", 42});
+  ASSERT_TRUE(encoded.ok()) << encoded.error().to_string();
+  auto decoded = reader.deserialize<HighTagCompatibleReader>(*encoded);
+  ASSERT_TRUE(decoded.ok()) << decoded.error().to_string();
+  EXPECT_EQ(decoded->shared, 42);
+}
+
 TEST(StructComprehensiveTest, NonPrimitiveFieldsSortByFieldIdentifier) {
   auto fields = TypeMeta::sort_field_infos({
       make_test_field_info("string_value", 20,

cpp/fory/serialization/xlang_test_main.cc

@@ -137,6 +137,17 @@ struct SimpleStruct {
               (f7, fory::F(65551)), f8, (last, fory::F(536870911)));
 };
 
+struct ExactFieldTags {
+  int32_t first;
+  int32_t second;
+  int32_t last;
+  bool operator==(const ExactFieldTags &other) const {
+    return first == other.first && second == other.second && last == other.last;
+  }
+  FORY_STRUCT(ExactFieldTags, (first, fory::F(15)), (second, fory::F(65551)),
+              (last, fory::F(536870911)));
+};
+
 struct EvolvingOverrideStruct {
   std::string f1;
   bool operator==(const EvolvingOverrideStruct &other) const {
@@ -938,6 +949,7 @@ namespace {
 void run_test_buffer(const std::string &data_file);
 void run_test_buffer_var(const std::string &data_file);
 void run_test_murmur_hash3(const std::string &data_file);
+void run_test_exact_field_tags(const std::string &data_file);
 void run_test_string_serializer(const std::string &data_file);
 void run_test_cross_language_serializer(const std::string &data_file);
 void run_test_simple_struct(const std::string &data_file);
@@ -1030,6 +1042,8 @@ int main(int argc, char **argv) {
       run_test_cross_language_serializer(data_file);
     } else if (case_name == "test_simple_struct") {
       run_test_simple_struct(data_file);
+    } else if (case_name == "test_exact_field_tags") {
+      run_test_exact_field_tags(data_file);
     } else if (case_name == "test_named_simple_struct") {
       run_test_simple_named_struct(data_file);
     } else if (case_name == "test_struct_evolving_override") {
@@ -1570,6 +1584,21 @@ void run_test_simple_struct(const std::string &data_file) {
   write_file(data_file, out);
 }
 
+void run_test_exact_field_tags(const std::string &data_file) {
+  auto fory = build_fory(false, true);
+  ensure_ok(fory.register_struct<ExactFieldTags>(104),
+            "register ExactFieldTags");
+  auto bytes = read_file(data_file);
+  Buffer buffer = make_buffer(bytes);
+  auto value = read_next<ExactFieldTags>(fory, buffer);
+  if (!(value == ExactFieldTags{39, 40, 41})) {
+    fail("ExactFieldTags mismatch");
+  }
+  std::vector<uint8_t> out;
+  append_serialized(fory, value, out);
+  write_file(data_file, out);
+}
+
 void run_test_simple_named_struct(const std::string &data_file) {
   auto bytes = read_file(data_file);
   auto fory = build_fory(true, true);

csharp/tests/Fory.XlangPeer/Program.cs

@@ -194,6 +194,7 @@ private static byte[] ExecuteCase(string caseName, byte[] input)
             "test_string_serializer" => CaseStringSerializer(input),
             "test_cross_language_serializer" => CaseCrossLanguageSerializer(input),
             "test_simple_struct" => CaseSimpleStruct(input),
+            "test_exact_field_tags" => CaseExactFieldTags(input),
             "test_named_simple_struct" => CaseNamedSimpleStruct(input),
             "test_struct_evolving_override" => CaseStructEvolvingOverride(input),
             "test_list" => CaseList(input),
@@ -461,6 +462,13 @@ private static byte[] CaseSimpleStruct(byte[] input)
         return RoundTripSingle<SimpleStruct>(input, fory);
     }
 
+    private static byte[] CaseExactFieldTags(byte[] input)
+    {
+        ForyRuntime fory = BuildFory(compatible: false);
+        fory.Register<ExactFieldTags>(104);
+        return RoundTripSingle<ExactFieldTags>(input, fory);
+    }
+
     private static byte[] CaseNamedSimpleStruct(byte[] input)
     {
         ForyRuntime fory = BuildFory(compatible: true);
@@ -1282,6 +1290,17 @@ public sealed class SimpleStruct
     public int Last { get; set; }
 }
 
+[ForyStruct]
+public sealed class ExactFieldTags
+{
+    [ForyField(15)]
+    public int First { get; set; }
+    [ForyField(65551)]
+    public int Second { get; set; }
+    [ForyField(536870911)]
+    public int Last { get; set; }
+}
+
 [ForyStruct]
 public sealed class EvolvingOverrideStruct
 {

dart/packages/fory-test/lib/entity/xlang_test_models.dart

@@ -79,6 +79,20 @@ class SimpleStruct {
   int last = 0;
 }
 
+@ForyStruct()
+class ExactFieldTags {
+  ExactFieldTags();
+
+  @ForyField(id: 15, type: Int32Type())
+  int first = 0;
+
+  @ForyField(id: 65551, type: Int32Type())
+  int second = 0;
+
+  @ForyField(id: 536870911, type: Int32Type())
+  int last = 0;
+}
+
 @ForyStruct()
 class EvolvingOverrideStruct {
   EvolvingOverrideStruct();

dart/packages/fory-test/test/cross_lang_test/xlang_test_main.dart

@@ -491,6 +491,11 @@ void _runCase(String caseName) {
       _registerSimpleById(fory);
       _roundTripFory(fory);
       return;
+    case 'test_exact_field_tags':
+      final fory = _newFory();
+      registerXlangType(fory, ExactFieldTags, id: 104);
+      _roundTripFory(fory);
+      return;
     case 'test_named_simple_struct':
       final fory = _newFory(compatible: true);
       _registerSimpleByName(fory);

docs/compiler/schema-idl.md

@@ -976,6 +976,11 @@ Fields define the properties of a message.
 field_type field_name = field_number;
 ```
 
+`field_number` is the field tag ID. It must be unique within the message and
+satisfy `0 <= field_number < 2^29` (`0` through `536870911`). Keep
+assigned field numbers stable and reserve removed numbers instead of reusing
+them for different fields.
+
 ### With Modifiers
 
 ```protobuf
@@ -1149,22 +1154,22 @@ Use `ref(thread_safe=false)` in Fory IDL (or
 
 ## Field Numbers
 
-Each field must have a unique positive integer identifier:
+Each field must have a unique tag ID in the protocol range:
 
 ```protobuf
 message Example {
-    string first = 1;
-    string second = 2;
-    string third = 3;
+    string first = 0;
+    string second = 1;
+    string third = 2;
 }
 ```
 
 **Rules and best practices:**
 
 - Numbers must be unique within a message.
-- Numbers must be positive integers.
+- Numbers must satisfy `0 <= field_number < 2^29` (`0` through `536870911`).
 - Gaps are allowed and are useful when fields are removed.
-- Prefer sequential numbering from `1`.
+- Prefer sequential numbering.
 - Never reuse a removed field number for a different field.
 
 ## Type System

docs/object-serialization/cpp/schema-metadata.md

@@ -59,8 +59,9 @@ FORY_STRUCT(DataV2, id, (timestamp, fory::F().tagged()), version);
 FORY_STRUCT(Counter, FORY_PROPERTY(value, fory::F().varint()));
 ```
 
-`fory::F(id)` uses explicit id-based field identity. IDs must be
-non-negative:
+`fory::F(id)` uses explicit id-based field identity. Configured IDs must be
+unique within the complete struct schema and satisfy `0 <= id < 2^29` (`0`
+through `536870911`):
 
 ```cpp
 FORY_STRUCT(DataV2, (id, fory::F(0)), (timestamp, fory::F(1).tagged()),

docs/object-serialization/csharp/schema-metadata.md

@@ -23,7 +23,7 @@ This page covers schema metadata for C# generated serializers.
 
 ## `[ForyStruct]` and `[ForyField]`
 
-Use `[ForyStruct]` to enable source-generated serializers. Use `[ForyField]` to assign an optional stable non-negative field id or to override the Fory schema type used for a field.
+Use `[ForyStruct]` to enable source-generated serializers. Use `[ForyField]` to assign an optional stable field ID or to override the Fory schema type used for a field. Configured IDs must be unique within the complete struct schema and satisfy `0 <= id < 2^29` (`0` through `536870911`).
 
 External-type serialization puts `Target` on a local abstract serializer
 declaration. Its properties own the field names, IDs, schema descriptors,
@@ -77,6 +77,7 @@ public sealed class Metrics
 ```
 
 `Id` is optional. When it is omitted, compatible mode still matches the field by name.
+Once assigned, keep an ID stable and do not reuse it for a different field.
 
 ```csharp
 using Apache.Fory;

docs/object-serialization/dart/schema-metadata.md

@@ -69,6 +69,7 @@ String name = '';
 ```
 
 Once a payload is shared across services, never reuse an `id` for a different field.
+Configured IDs must satisfy `0 <= id < 2^29` (`0` through `536870911`).
 
 An ordinary child has one flattened field namespace. IDs must therefore be
 unique across all fields included from its child, superclass, and