Pin protobuf field and enum value numbers in a sidecar artifact

Field and enum value numbers were assigned sequentially in definition
order, so reordering or removing a field renumbered everything after it —
breaking wire compatibility with previously serialized data.

`schema_artifacts:dump` now reads and writes a `proto_field_numbers.yaml`
sidecar artifact:

- Existing numbers stay fixed even if field order changes; new fields get
  the next available numbers.
- `schema.proto` keeps the public GraphQL field names while the sidecar
  stores private `name_in_index` overrides.
- A field renamed with `field.renamed_from` reuses its existing number
  under the new public name.
- Enum value numbers are pinned in an `enums` section; removed values keep
  their numbers reserved so they are never reused (`0` remains the
  generated `*_UNSPECIFIED` value).
- Mappings are validated: collisions raise clear errors, and non-integer
  numbers are rejected instead of letting `Integer()` silently truncate.

`configure_proto_field_number_mappings` allows tests and advanced callers
to seed mappings without an artifact file.

Author: jwils

elasticgraph-proto_ingestion/README.md

@@ -71,7 +71,10 @@ ElasticGraph.define_schema do |schema|
 end
 ```
 
-After running `bundle exec rake schema_artifacts:dump`, ElasticGraph will generate `schema.proto`.
+After running `bundle exec rake schema_artifacts:dump`, ElasticGraph will generate:
+
+- `schema.proto`
+- `proto_field_numbers.yaml`
 
 ## Schema Definition Options
 
@@ -92,6 +95,45 @@ ElasticGraph.define_schema do |schema|
 end
 ```
 
+### Stable Field Numbers
+
+`schema_artifacts:dump` automatically reads and writes `proto_field_numbers.yaml`
+in the schema artifacts directory. Existing numbers stay fixed even if field order
+changes, and new fields get the next available numbers. Field numbers follow protobuf's
+rules: they must be between 1 and 536,870,911, and the protobuf-reserved 19000-19999
+range is never allocated and is rejected in mappings.
+
+`schema.proto` always uses the public GraphQL field names. When a field uses a
+different `name_in_index`, the sidecar YAML stores that override privately:
+
+```yaml
+messages:
+  Widget:
+    fields:
+      id: 1
+      display_name:
+        field_number: 2
+        name_in_index: displayName
+```
+
+If a field is renamed with `field.renamed_from`, `elasticgraph-proto_ingestion` reuses the
+existing field number under the new public field name.
+
+### Stable Enum Value Numbers
+
+Enum value numbers are pinned the same way, in an `enums` section of the sidecar. Existing
+values keep their numbers when other values are added or removed, new values get the next
+available numbers, and removed values keep their numbers reserved so they are never reused
+(number `0` is always the generated `*_UNSPECIFIED` value):
+
+```yaml
+enums:
+  WidgetColor:
+    values:
+      RED: 1
+      BLUE: 2
+```
+
 ## Type Mappings
 
 The generated `schema.proto` uses these built-in scalar mappings:

elasticgraph-proto_ingestion/lib/elastic_graph/proto_ingestion.rb

@@ -11,5 +11,8 @@ module ElasticGraph
   module ProtoIngestion
     # The name of the generated Protocol Buffers schema file.
     PROTO_SCHEMA_FILE = "schema.proto"
+
+    # The name of the generated proto field-number mapping file.
+    PROTO_FIELD_NUMBERS_FILE = "proto_field_numbers.yaml"
   end
 end

elasticgraph-proto_ingestion/lib/elastic_graph/proto_ingestion/schema_definition/api_extension.rb

@@ -74,6 +74,18 @@ def proto_schema_artifacts(package_name: "elasticgraph")
           nil
         end
 
+        # Configures proto field-number mappings directly from a hash.
+        # Useful for tests and advanced use cases where mappings are sourced outside artifacts.
+        # When artifacts are dumped, mappings from the existing `proto_field_numbers.yaml` artifact
+        # are loaded automatically; this method does not need to be called in that case.
+        #
+        # @param proto_field_number_mappings [Hash]
+        # @return [void]
+        def configure_proto_field_number_mappings(proto_field_number_mappings)
+          proto_ingestion_state.field_number_mappings = proto_field_number_mappings
+          nil
+        end
+
         private
 
         # Returns this gem's state container. Centralizes the Steep cast that's needed because

elasticgraph-proto_ingestion/lib/elastic_graph/proto_ingestion/schema_definition/proto_ingestion_state.rb

@@ -14,10 +14,12 @@ module SchemaDefinition
       # @private
       class ProtoIngestionState
         # @dynamic package_name, package_name=
-        attr_accessor :package_name
+        # @dynamic field_number_mappings, field_number_mappings=
+        attr_accessor :package_name, :field_number_mappings
 
         def initialize
           @package_name = "elasticgraph"
+          @field_number_mappings = {}
         end
       end
     end

elasticgraph-proto_ingestion/lib/elastic_graph/proto_ingestion/schema_definition/results_extension.rb

@@ -20,6 +20,15 @@ def proto_schema
           @proto_schema ||= protobuf_schema_generator.to_proto
         end
 
+        # Returns proto field-number mappings suitable for artifact storage.
+        #
+        # @return [Hash]
+        def proto_field_number_mappings
+          # Ensure generation has occurred before reading mappings from the generator.
+          proto_schema
+          protobuf_schema_generator.field_number_mappings_for_artifact
+        end
+
         private
 
         def protobuf_schema_generator
@@ -37,7 +46,8 @@ def protobuf_schema_generator
 
             Schema.new(
               state: extension_state,
-              package_name: ingestion_state.package_name
+              package_name: ingestion_state.package_name,
+              proto_field_number_mappings: ingestion_state.field_number_mappings
             )
           end
         end