feat: make generate enum use id for wire format (#3576)

## Why?



## What does this PR do?

make generate enum use id for wire format
- java
- python
- c++
- swift
- javascript

## 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`.
- [ ] If `yes`, my PR description includes the required `ai_review`
summary and screenshot evidence of the final clean AI review results
from both fresh reviewers on the current PR diff or current HEAD after
the latest code changes.



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

Author: chaokunyang

.github/workflows/release-javascript.yaml

@@ -0,0 +1,140 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
+name: Publish JavaScript
+run-name: "JavaScript Release: ${{ github.ref_name }}"
+
+on:
+  push:
+    tags: ['v*']
+
+permissions:
+  contents: read
+  id-token: write
+
+concurrency:
+  group: release-javascript-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  publish-npm:
+    runs-on: ubuntu-latest
+    if: github.repository == 'apache/fory'
+    steps:
+      - uses: actions/checkout@v5
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          registry-url: 'https://registry.npmjs.org'
+
+      - name: Upgrade npm for trusted publishing
+        run: npm i -g npm@latest
+
+      - name: Verify Node/npm versions
+        shell: bash
+        run: |
+          set -euo pipefail
+          echo "Node: $(node --version)"
+          echo "npm: $(npm --version)"
+          REQUIRED="11.5.1"
+          CURRENT="$(npm --version)"
+          if [[ "$(printf '%s\n' "$REQUIRED" "$CURRENT" | sort -V | head -n1)" != "$REQUIRED" ]]; then
+            echo "npm version must be >= $REQUIRED for trusted publishing. current=$CURRENT"
+            exit 1
+          fi
+
+      - name: Bump javascript version
+        shell: bash
+        run: |
+          set -euo pipefail
+          VERSION="${{ github.ref_name }}"
+          VERSION="${VERSION#v}"
+          python ci/release.py bump_version -l javascript -version "$VERSION"
+
+      - name: Install dependencies
+        shell: bash
+        working-directory: javascript
+        run: npm install
+
+      - name: Build packages
+        shell: bash
+        working-directory: javascript
+        run: npm run build
+
+      - name: Prepare npm for trusted publishing
+        shell: bash
+        run: |
+          set -euo pipefail
+          npm config set registry https://registry.npmjs.org/
+          npm config delete //registry.npmjs.org/:_authToken || true
+          npm config get registry
+
+      - name: Verify repository metadata for provenance
+        shell: bash
+        run: |
+          set -euo pipefail
+          node <<'EOF'
+          const fs = require("node:fs");
+
+          const expected = "git@github.com:apache/fory.git";
+          const files = [
+            "javascript/packages/core/package.json",
+            "javascript/packages/hps/package.json"
+          ];
+
+          for (const file of files) {
+            const json = JSON.parse(fs.readFileSync(file, "utf8"));
+            const actual = json?.repository ?? "";
+            if (actual !== expected) {
+              console.error(
+                `Repository URL mismatch in ${file}: expected "${expected}", got "${actual}"`
+              );
+              process.exit(1);
+            }
+          }
+
+          console.log("repository metadata verified for all publishable packages");
+          EOF
+
+      - name: Publish @apache-fory/hps
+        shell: bash
+        working-directory: javascript/packages/hps
+        run: |
+          set -euo pipefail
+          TAG="latest"
+          if echo "${{ github.ref_name }}" | grep -qE '[-]'; then
+            TAG="next"
+          fi
+          npm publish --access public --tag "$TAG" --provenance
+        env:
+          NODE_AUTH_TOKEN: ""
+          NPM_TOKEN: ""
+
+      - name: Publish @apache-fory/core
+        shell: bash
+        working-directory: javascript/packages/core
+        run: |
+          set -euo pipefail
+          TAG="latest"
+          if echo "${{ github.ref_name }}" | grep -qE '[-]'; then
+            TAG="next"
+          fi
+          npm publish --access public --tag "$TAG" --provenance
+        env:
+          NODE_AUTH_TOKEN: ""
+          NPM_TOKEN: ""

ci/release.py

@@ -177,7 +177,7 @@ def bump_version(**kwargs):
             bump_python_version(new_version)
         elif lang == "javascript":
             _bump_version(
-                "javascript/packages/fory",
+                "javascript/packages/core",
                 "package.json",
                 _normalize_js_version(new_version),
                 _update_js_version,

compiler/fory_compiler/generators/java.py

@@ -366,18 +366,14 @@ def generate_enum_file(self, enum: Enum) -> GeneratedFile:
             lines.append(f"package {java_package};")
             lines.append("")
 
-        # Enum declaration
-        lines.append(f"public enum {enum.name} {{")
-
-        # Enum values (strip prefix for scoped enums)
-        for i, value in enumerate(enum.values):
-            comma = "," if i < len(enum.values) - 1 else ";"
-            stripped_name = self.strip_enum_prefix(enum.name, value.name)
-            lines.append(f"    {stripped_name}{comma}")
-
-        lines.append("}")
+        lines.append("import org.apache.fory.annotation.ForyEnumId;")
         lines.append("")
 
+        # Enum declaration
+        lines.extend(
+            self.generate_enum_declaration(enum, f"public enum {enum.name} {{")
+        )
+
         # Build file path
         path = self.get_java_package_path()
         if path:
@@ -531,7 +527,7 @@ def generate_outer_class_file(self, outer_classname: str) -> GeneratedFile:
         for message in self.schema.messages:
             self.collect_message_imports(message, imports)
         for enum in self.schema.enums:
-            pass  # Enums don't need special imports
+            self.collect_enum_imports(imports)
         for union in self.schema.unions:
             self.collect_union_imports(union, imports)
 
@@ -604,12 +600,19 @@ def collect_message_imports(self, message: Message, imports: Set[str]):
         if self.has_array_field_recursive(message):
             imports.add("java.util.Arrays")
 
+        for nested_enum in message.nested_enums:
+            self.collect_enum_imports(imports)
+
         # Collect imports from nested messages
         for nested_msg in message.nested_messages:
             self.collect_message_imports(nested_msg, imports)
         for nested_union in message.nested_unions:
             self.collect_union_imports(nested_union, imports)
 
+    def collect_enum_imports(self, imports: Set[str]):
+        """Collect imports required by generated Java enums."""
+        imports.add("org.apache.fory.annotation.ForyEnumId")
+
     def collect_union_imports(self, union: Union, imports: Set[str]):
         """Collect imports for a union and its cases."""
         imports.add("org.apache.fory.type.union.Union")
@@ -635,15 +638,30 @@ def has_array_field_recursive(self, message: Message) -> bool:
 
     def generate_nested_enum(self, enum: Enum) -> List[str]:
         """Generate a nested enum as a static inner class."""
-        lines = []
-        lines.append(f"public static enum {enum.name} {{")
+        return self.generate_enum_declaration(
+            enum, f"public static enum {enum.name} {{"
+        )
+
+    def generate_enum_declaration(self, enum: Enum, header: str) -> List[str]:
+        """Generate a Java enum declaration with stable Fory enum ids."""
+        lines = [header]
 
-        # Enum values (strip prefix for scoped enums)
         for i, value in enumerate(enum.values):
             comma = "," if i < len(enum.values) - 1 else ";"
             stripped_name = self.strip_enum_prefix(enum.name, value.name)
-            lines.append(f"    {stripped_name}{comma}")
+            lines.append(f"    {stripped_name}({value.value}){comma}")
 
+        lines.append("")
+        lines.append("    private final int id;")
+        lines.append("")
+        lines.append(f"    {enum.name}(int id) {{")
+        lines.append("        this.id = id;")
+        lines.append("    }")
+        lines.append("")
+        lines.append("    @ForyEnumId")
+        lines.append("    public int getId() {")
+        lines.append("        return id;")
+        lines.append("    }")
         lines.append("}")
         lines.append("")
         return lines

compiler/fory_compiler/tests/test_generated_code.py

@@ -543,6 +543,32 @@ def test_java_repeated_float16_generation_uses_float16_list():
     assert "private Float16List vals;" in java_output
 
 
+def test_java_enum_generation_uses_fory_enum_ids():
+    schema = parse_fdl(
+        dedent(
+            """
+            package gen;
+
+            enum Status {
+                UNKNOWN = 4096;
+                OK = 8192;
+            }
+            """
+        )
+    )
+    java_output = render_files(generate_files(schema, JavaGenerator))
+    assert "import org.apache.fory.annotation.ForyEnumId;" in java_output
+    assert "public enum Status {" in java_output
+    assert "UNKNOWN(4096)," in java_output
+    assert "OK(8192);" in java_output
+    assert "private final int id;" in java_output
+    assert "Status(int id) {" in java_output
+    assert "this.id = id;" in java_output
+    assert "@ForyEnumId" in java_output
+    assert "public int getId() {" in java_output
+    assert "return id;" in java_output
+
+
 def test_go_bfloat16_generation():
     idl = dedent(
         """

compiler/fory_compiler/tests/test_package_options.py

@@ -494,9 +494,15 @@ def test_outer_classname_generates_single_file(self):
         assert "myapp/DescriptorProtos.java" == outer_file.path
 
         # Check content
+        assert "import org.apache.fory.annotation.ForyEnumId;" in outer_file.content
         assert "public final class DescriptorProtos" in outer_file.content
         assert "private DescriptorProtos()" in outer_file.content
         assert "public static enum Status" in outer_file.content
+        assert "UNKNOWN(0)," in outer_file.content
+        assert "ACTIVE(1);" in outer_file.content
+        assert "private final int id;" in outer_file.content
+        assert "@ForyEnumId" in outer_file.content
+        assert "public int getId()" in outer_file.content
         assert "public static class User" in outer_file.content
         assert "public static class Order" in outer_file.content
 
@@ -606,6 +612,12 @@ def test_without_outer_classname_generates_separate_files(self):
         assert "Status.java" in file_names
         assert "User.java" in file_names
         assert "MyappForyRegistration.java" in file_names
+        status_file = next(f for f in files if f.path.endswith("Status.java"))
+        assert "import org.apache.fory.annotation.ForyEnumId;" in status_file.content
+        assert "UNKNOWN(0);" in status_file.content
+        assert "private final int id;" in status_file.content
+        assert "@ForyEnumId" in status_file.content
+        assert "public int getId()" in status_file.content
 
 
 class TestJavaMultipleFiles:

cpp/fory/serialization/enum_serializer.h

@@ -37,14 +37,35 @@ namespace serialization {
 
 /// Serializer specialization for enum types.
 ///
-/// Writes the enum ordinal (underlying integral value) to match the xlang
-/// specification for value-based enums.
+/// Writes enum values using xlang-compatible uint32 wire ids. Registered enums
+/// with contiguous zero-based values keep ordinal encoding; enums with sparse
+/// non-negative declared values preserve those declared values on the wire.
 template <typename E>
 struct Serializer<E, std::enable_if_t<std::is_enum_v<E>>> {
   static constexpr TypeId type_id = TypeId::ENUM;
 
   using Metadata = meta::EnumMetadata<E>;
   using OrdinalType = typename Metadata::OrdinalType;
+  using EnumInfo = meta::EnumInfo<E>;
+
+  static constexpr bool supports_explicit_wire_values() {
+    if constexpr (!EnumInfo::defined) {
+      return true;
+    }
+    for (std::size_t i = 0; i < EnumInfo::size; ++i) {
+      const auto raw = static_cast<OrdinalType>(EnumInfo::values[i]);
+      if constexpr (std::is_signed_v<OrdinalType>) {
+        if (raw < 0) {
+          return false;
+        }
+      }
+      using Unsigned = std::make_unsigned_t<OrdinalType>;
+      if (static_cast<Unsigned>(raw) != static_cast<Unsigned>(i)) {
+        return true;
+      }
+    }
+    return false;
+  }
 
   static inline void write_type_info(WriteContext &ctx) {
     // Use compile-time type lookup for faster enum type info writing
@@ -72,6 +93,24 @@ struct Serializer<E, std::enable_if_t<std::is_enum_v<E>>> {
   }
 
   static inline void write_data(E value, WriteContext &ctx) {
+    if constexpr (supports_explicit_wire_values()) {
+      if constexpr (EnumInfo::defined) {
+        if (!EnumInfo::contains(value)) {
+          ctx.set_error(Error::unknown_enum("Unknown enum value"));
+          return;
+        }
+      }
+      const auto raw_value = static_cast<OrdinalType>(value);
+      if constexpr (std::is_signed_v<OrdinalType>) {
+        if (raw_value < 0) {
+          ctx.set_error(
+              Error::unknown_enum("Negative enum values are not supported"));
+          return;
+        }
+      }
+      ctx.write_var_uint32(static_cast<uint32_t>(raw_value));
+      return;
+    }
     OrdinalType ordinal{};
     if (!Metadata::to_ordinal(value, &ordinal)) {
       ctx.set_error(Error::unknown_enum("Unknown enum value"));
@@ -111,6 +150,25 @@ struct Serializer<E, std::enable_if_t<std::is_enum_v<E>>> {
     if (FORY_PREDICT_FALSE(ctx.has_error())) {
       return E{};
     }
+    if constexpr (supports_explicit_wire_values()) {
+      if (raw_ordinal >
+          static_cast<uint32_t>(std::numeric_limits<OrdinalType>::max())) {
+        ctx.set_error(Error::unknown_enum(
+            "Invalid enum value: " +
+            std::to_string(static_cast<unsigned long long>(raw_ordinal))));
+        return E{};
+      }
+      const auto value = static_cast<E>(static_cast<OrdinalType>(raw_ordinal));
+      if constexpr (EnumInfo::defined) {
+        if (!EnumInfo::contains(value)) {
+          ctx.set_error(Error::unknown_enum(
+              "Invalid enum value: " +
+              std::to_string(static_cast<unsigned long long>(raw_ordinal))));
+          return E{};
+        }
+      }
+      return value;
+    }
     OrdinalType ordinal = static_cast<OrdinalType>(raw_ordinal);
     E value{};
     if (!Metadata::from_ordinal(ordinal, &value)) {