Add elasticgraph-proto_ingestion schema artifacts

Fills in the `elasticgraph-proto_ingestion` gem with the Protocol Buffers
schema artifact generation logic.

Running `schema_artifacts:dump` emits:

- `schema.proto` — the generated Protobuf schema for the indexed types
- `proto_field_numbers.yaml` — a sidecar that reserves field numbers and enum
  value numbers so they stay wire-stable as the schema evolves (including
  across field renames, and reserving removed values so numbers are not reused)

Capabilities:

- Maps built-in ElasticGraph scalars to proto types, with `proto_field` to
  configure custom scalars.
- Generates messages for object/interface/union types and enums (with a
  zero-valued `*_UNSPECIFIED` entry), escaping proto reserved words and
  wrapping nested lists so the output stays valid.
- `proto_enum_mappings` reuses enum values already maintained elsewhere.

The generator emits `proto3` by default and can emit `proto2` via
`syntax: :proto2` (which labels every field `optional`/`repeated`). Arbitrary
file-level headers (e.g. `option` declarations) can be injected verbatim via
`headers:`, so language-specific options can be set without baking any
particular convention into the gem.

Author: jwils

elasticgraph-proto_ingestion/README.md

@@ -1,6 +1,9 @@
 # ElasticGraph::ProtoIngestion
 
 An ElasticGraph extension that supports ingesting Protocol Buffer data into ElasticGraph.
+Currently it generates Protocol Buffers schema artifacts from ElasticGraph schemas: it emits
+`proto3` by default and can emit `proto2`, and supports arbitrary file-level headers (such
+as `option` declarations).
 
 ## Dependency Diagram
 
@@ -15,3 +18,209 @@ graph LR;
     elasticgraph-proto_ingestion --> elasticgraph-support;
     class elasticgraph-support otherEgGemStyle;
 ```
+
+## Usage
+
+First, add `elasticgraph-proto_ingestion` to your `Gemfile`, alongside the other ElasticGraph gems:
+
+```diff
+diff --git a/Gemfile b/Gemfile
+index 4a5ef1e..5c16c2b 100644
+--- a/Gemfile
++++ b/Gemfile
+@@ -8,6 +8,7 @@ gem "elasticgraph-query_registry", *elasticgraph_details
+
+ # Can be elasticgraph-elasticsearch or elasticgraph-opensearch based on the datastore you want to use.
+ gem "elasticgraph-opensearch", *elasticgraph_details
++gem "elasticgraph-proto_ingestion", *elasticgraph_details
+
+ gem "httpx", "~> 1.3"
+
+```
+
+Next, update your `Rakefile` so that `ElasticGraph::ProtoIngestion::SchemaDefinition::APIExtension` is
+included in the schema-definition extension modules:
+
+```diff
+diff --git a/Rakefile b/Rakefile
+index 2943335..26633c3 100644
+--- a/Rakefile
++++ b/Rakefile
+@@ -3,5 +3,6 @@
+ require "elastic_graph/json_ingestion/schema_definition/api_extension"
+ require "elastic_graph/local/rake_tasks"
++require "elastic_graph/proto_ingestion/schema_definition/api_extension"
+ require "elastic_graph/query_registry/rake_tasks"
+ require "rspec/core/rake_task"
+ require "standard/rake"
+@@ -16,6 +17,7 @@ ElasticGraph::Local::RakeTasks.new(
+   # Determines casing of field names. Can be either `:camelCase` or `:snake_case`.
+   tasks.schema_element_name_form = :camelCase
+   tasks.schema_definition_extension_modules << ElasticGraph::JSONIngestion::SchemaDefinition::APIExtension
++  tasks.schema_definition_extension_modules << ElasticGraph::ProtoIngestion::SchemaDefinition::APIExtension
+
+   # Customizes the names of fields generated by ElasticGraph.
+   tasks.schema_element_name_overrides = {
+```
+
+Then opt into proto generation from your schema definition:
+
+```ruby
+# in config/schema/protobuf.rb
+
+ElasticGraph.define_schema do |schema|
+  schema.proto_schema_artifacts package_name: "myapp.events.v1"
+end
+```
+
+After running `bundle exec rake schema_artifacts:dump`, ElasticGraph will generate:
+
+- `schema.proto`
+- `proto_field_numbers.yaml`
+
+## Schema Definition Options
+
+### Protobuf Syntax (`proto2` / `proto3`)
+
+`proto_schema_artifacts` emits `proto3` by default. Pass `syntax: :proto2` to emit a proto2 file
+instead (every field is then labeled `optional` or `repeated`). This is useful when the generated
+messages need to reference proto2 types — for example, `protoc` forbids a `proto3` message from
+referencing a `proto2` enum:
+
+```ruby
+# in config/schema/protobuf.rb
+
+ElasticGraph.define_schema do |schema|
+  schema.proto_schema_artifacts package_name: "myapp.events.v1", syntax: :proto2
+end
+```
+
+### Custom Headers
+
+Pass `headers:` an array of strings to inject file-level lines (such as `option` declarations)
+verbatim, as a contiguous section immediately after the `package` declaration. This lets you set
+language-specific options without the gem baking in any particular convention:
+
+```ruby
+# in config/schema/protobuf.rb
+
+ElasticGraph.define_schema do |schema|
+  schema.proto_schema_artifacts(
+    package_name: "myapp.events.v1",
+    headers: [
+      %(option java_package = "com.myapp.events";),
+      "option java_multiple_files = true;"
+    ]
+  )
+end
+```
+
+produces:
+
+```text
+syntax = "proto3";
+
+package myapp.events.v1;
+
+option java_package = "com.myapp.events";
+option java_multiple_files = true;
+
+// ...messages...
+```
+
+### Custom Scalar Types
+
+Built-in ElasticGraph scalar types are automatically mapped to proto scalar types.
+For custom scalar types, use `proto_field` to define the proto scalar type:
+
+```ruby
+# in config/schema/money.rb
+
+ElasticGraph.define_schema do |schema|
+  schema.scalar_type "Money" do |t|
+    t.mapping type: "long"
+    t.json_schema type: "integer"
+    t.proto_field type: "int64"
+  end
+end
+```
+
+### Sourcing Enum Values From Existing Protobuf Mappings
+
+If your project already maintains GraphQL-to-proto enum mappings (for example in tests),
+you can reuse them for proto schema generation:
+
+```ruby
+# in config/schema/proto_enum_mappings.rb
+
+ElasticGraph.define_schema do |schema|
+  schema.proto_enum_mappings(
+    SalesEg::ProtoEnumMappings::PROTO_ENUMS_BY_GRAPHQL_ENUM
+  ) if defined?(SalesEg::ProtoEnumMappings)
+end
+```
+
+When a mapping exists for an enum, `elasticgraph-proto_ingestion` uses the mapped proto enum(s)
+as the source of enum values (respecting `exclusions`, `expected_extras`, and `name_transform`).
+
+### 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.
+
+`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 Type | Protobuf Type |
+|-------------------|------------|
+| `Boolean`         | `bool`     |
+| `Cursor`          | `string`   |
+| `Date`            | `string`   |
+| `DateTime`        | `string`   |
+| `Float`           | `double`   |
+| `ID`              | `string`   |
+| `Int`             | `int32`    |
+| `JsonSafeLong`    | `int64`    |
+| `LocalTime`       | `string`   |
+| `LongString`      | `int64`    |
+| `String`          | `string`   |
+| `TimeZone`        | `string`   |
+| `Untyped`         | `string`   |
+
+Additionally:
+- List types become `repeated` fields.
+- Nested list types generate wrapper messages so the output remains valid `proto3`.
+- Enum types generate `enum` definitions whose values are prefixed with the enum type name in `UPPER_SNAKE_CASE`, including a zero-valued `*_UNSPECIFIED` entry.

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

@@ -6,7 +6,11 @@
 #
 # frozen_string_literal: true
 
+require "elastic_graph/errors"
 require "elastic_graph/proto_ingestion"
+require "elastic_graph/proto_ingestion/schema_definition/factory_extension"
+require "elastic_graph/proto_ingestion/schema_definition/schema"
+require "elastic_graph/proto_ingestion/schema_definition/state_extension"
 
 module ElasticGraph
   module ProtoIngestion
@@ -16,10 +20,114 @@ module ProtoIngestion
     module SchemaDefinition
       # Module designed to be extended onto an {ElasticGraph::SchemaDefinition::API} instance
       # to enable protobuf schema artifact generation.
-      #
-      # @note The protobuf schema artifact generation logic has not been implemented yet, so
-      #   extending this module is currently a no-op.
       module APIExtension
+        # Maps built-in ElasticGraph scalar types to proto field types.
+        PROTO_TYPES_BY_BUILT_IN_SCALAR_TYPE = {
+          "Boolean" => "bool",
+          "Cursor" => "string",
+          "Date" => "string",
+          "DateTime" => "string",
+          "Float" => "double",
+          "ID" => "string",
+          "Int" => "int32",
+          "JsonSafeLong" => "int64",
+          "LocalTime" => "string",
+          "LongString" => "int64",
+          "String" => "string",
+          "TimeZone" => "string",
+          "Untyped" => "string"
+        }.freeze
+
+        # Wires up the protobuf extensions when this module is extended onto an API instance.
+        #
+        # @param api [ElasticGraph::SchemaDefinition::API] the API instance to extend
+        # @return [void]
+        # @api private
+        def self.extended(api)
+          api.state.extend(StateExtension)
+          api.factory.extend(FactoryExtension)
+
+          api.on_built_in_types do |type|
+            if type.is_a?(SchemaElements::ScalarTypeExtension)
+              # Use the reverted (original) type name so that built-in scalars renamed via
+              # `type_name_overrides` still resolve to their proto field types.
+              type.proto_field type: PROTO_TYPES_BY_BUILT_IN_SCALAR_TYPE.fetch(type.type_ref.with_reverted_override.name)
+            end
+          end
+        end
+
+        # Configures protobuf artifact generation behavior.
+        #
+        # @param package_name [String] proto package name to emit
+        # @param syntax [Symbol] `:proto3` (default) or `:proto2`
+        # @param headers [Array<String>] file-level header lines (e.g. `option` declarations) rendered
+        #   verbatim after the `package` declaration
+        # @return [void]
+        #
+        # @example Set the proto package name
+        #   ElasticGraph.define_schema do |schema|
+        #     schema.proto_schema_artifacts package_name: "myapp.events.v1"
+        #   end
+        #
+        # @example Emit proto2 with custom file-level options
+        #   ElasticGraph.define_schema do |schema|
+        #     schema.proto_schema_artifacts(
+        #       package_name: "myapp.events.v1",
+        #       syntax: :proto2,
+        #       headers: [
+        #         %(option java_package = "com.myapp.events";),
+        #         "option java_multiple_files = true;"
+        #       ]
+        #     )
+        #   end
+        def proto_schema_artifacts(package_name: "elasticgraph", syntax: :proto3, headers: [])
+          if !package_name.is_a?(String) || package_name.empty?
+            raise Errors::SchemaError, "`package_name` must be a non-empty String"
+          end
+          unless Schema::SUPPORTED_SYNTAXES.include?(syntax.to_s)
+            raise Errors::SchemaError, "`syntax` must be one of #{Schema::SUPPORTED_SYNTAXES.inspect}, got: #{syntax.inspect}"
+          end
+          if !headers.is_a?(Array) || headers.any? { |header| !header.is_a?(String) }
+            raise Errors::SchemaError, "`headers` must be an Array of Strings"
+          end
+
+          protobuf_state.proto_schema_package_name = package_name
+          protobuf_state.proto_schema_syntax = syntax
+          protobuf_state.proto_schema_headers = headers
+          nil
+        end
+
+        # Registers mappings from GraphQL enum names to protobuf enum classes and transform options.
+        # This is intended to support reusing enum mappings already maintained by applications
+        # (for example in schema/proto consistency tests).
+        #
+        # @param proto_enums_by_graphql_enum [Hash]
+        # @return [void]
+        def proto_enum_mappings(proto_enums_by_graphql_enum)
+          protobuf_state.proto_enums_by_graphql_enum = proto_enums_by_graphql_enum
+          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)
+          protobuf_state.proto_field_number_mappings = proto_field_number_mappings
+          nil
+        end
+
+        private
+
+        # Returns the API's `state` narrowed to include this gem's `StateExtension`. Centralizes
+        # the Steep cast that's needed because Steep can't see the `extend(StateExtension)` applied
+        # at runtime in `extended`.
+        def protobuf_state
+          state # : ElasticGraph::SchemaDefinition::State & StateExtension
+        end
       end
     end
   end