ibex 0.1.0 → 0.3.0

data/sig/ibex/generation_input.rbs

@@ -0,0 +1,37 @@
+# Generated from lib/ibex/generation_input.rb with RBS::Inline
+
+module Ibex
+  # Digest and identity of source bytes actually consumed by one generation.
+  class GenerationInput
+    attr_reader path: String
+
+    attr_reader sha256: String
+
+    attr_reader bytesize: Integer
+
+    attr_reader dev: Integer
+
+    attr_reader ino: Integer
+
+    attr_reader access_paths: Array[String]
+
+    # @rbs (String path, String source, ?access_path: String) -> void
+    def initialize: (String path, String source, ?access_path: String) -> void
+
+    # Record another lexical path that supplied these canonical bytes.
+    # @rbs (String path) -> void
+    def add_access_path: (String path) -> void
+
+    # @rbs () -> Hash[String, String | Integer]
+    def to_h: () -> Hash[String, String | Integer]
+
+    # Detect content changes even when size and timestamps are preserved.
+    # @rbs () -> bool
+    def current?: () -> bool
+
+    private
+
+    # @rbs () -> bool
+    def lexical_paths_current?: () -> bool
+  end
+end

data/sig/ibex/generation_manifest.rbs

@@ -0,0 +1,70 @@
+# Generated from lib/ibex/generation_manifest.rb with RBS::Inline
+
+module Ibex
+  # Deterministic description of one published parser generation.
+  # rubocop:disable Metrics/ModuleLength -- manifest schema validation is kept in one auditable unit.
+  module GenerationManifest
+    type json_value = String | Integer | Float | bool | nil | Array[json_value] | Hash[String, json_value]
+
+    SCHEMA_VERSION: Integer
+
+    IDENTIFIER: String
+
+    ROOT_KEYS: Array[String]
+
+    INPUT_KEYS: Array[String]
+
+    FILE_KEYS: Array[String]
+
+    ARTIFACT_KEYS: Array[String]
+
+    # @rbs (ArtifactSet artifacts, source_records: Array[GenerationInput], options: Hash[String, Object?]) -> String
+    def self?.render: (ArtifactSet artifacts, source_records: Array[GenerationInput], options: Hash[String, Object?]) -> String
+
+    # Validate the manifest shape and, by default, every published artifact digest.
+    # @rbs (String source, ?verify_artifacts: bool) -> Hash[String, json_value]
+    def self?.validate: (String source, ?verify_artifacts: bool) -> Hash[String, json_value]
+
+    # @rbs (String path, ?verify_artifacts: bool) -> Hash[String, json_value]
+    def self?.validate_file: (String path, ?verify_artifacts: bool) -> Hash[String, json_value]
+
+    # @rbs (Artifact artifact) -> Hash[String, json_value]
+    def self?.artifact_entry: (Artifact artifact) -> Hash[String, json_value]
+
+    # @rbs (Array[Hash[String, json_value]] files) -> String
+    def self?.input_digest: (Array[Hash[String, json_value]] files) -> String
+
+    # @rbs (Hash[String, Object?] value) -> Hash[String, Object?]
+    def self?.sorted_hash: (Hash[String, Object?] value) -> Hash[String, Object?]
+
+    # @rbs (Object? document) -> void
+    def self?.validate_document: (Object? document) -> void
+
+    # @rbs (Hash[Object?, Object?] document) -> void
+    def self?.validate_identity: (Hash[Object?, Object?] document) -> void
+
+    # @rbs (Object? input) -> void
+    def self?.validate_input: (Object? input) -> void
+
+    # @rbs (Array[Object?] entries, String label, ?require_kind: bool) -> void
+    def self?.validate_entries: (Array[Object?] entries, String label, ?require_kind: bool) -> void
+
+    # @rbs (Object? entry, String label, bool require_kind) -> void
+    def self?.validate_entry: (Object? entry, String label, bool require_kind) -> void
+
+    # @rbs (Object? path, String label) -> void
+    def self?.validate_path: (Object? path, String label) -> void
+
+    # @rbs (Object? kind, String label) -> void
+    def self?.validate_kind: (Object? kind, String label) -> void
+
+    # @rbs (Object? digest, String label) -> void
+    def self?.validate_digest: (Object? digest, String label) -> void
+
+    # @rbs (Hash[Object?, Object?] value, Array[String] expected, String label) -> void
+    def self?.exact_keys!: (Hash[Object?, Object?] value, Array[String] expected, String label) -> void
+
+    # @rbs (Array[Object?] entries) -> void
+    def self?.verify_entries: (Array[Object?] entries) -> void
+  end
+end

data/sig/ibex/generation_transaction.rbs

@@ -0,0 +1,82 @@
+# Generated from lib/ibex/generation_transaction.rb with RBS::Inline
+
+module Ibex
+  # Publishes a rendered ArtifactSet with rollback and a manifest-last marker.
+  class GenerationTransaction
+    include GenerationTransactionRecovery
+
+    include GenerationTransactionValidation
+
+    class SourceChanged < Ibex::Error
+    end
+
+    class Error < Ibex::Error
+      attr_reader rollback_failed: bool
+
+      attr_reader recovery_artifacts: Array[String]
+
+      # @rbs (String message, ?rollback_failed: bool, ?recovery_artifacts: Array[String]) -> void
+      def initialize: (String message, ?rollback_failed: bool, ?recovery_artifacts: Array[String]) -> void
+    end
+
+    # rubocop:disable Layout/LineLength
+    # @rbs (ArtifactSet artifacts, ?warning: ^(String) -> void, ?stability_check: ^() -> bool, ?source_records: Array[GenerationInput], ?lock_sleeper: ^(Float) -> void) -> void
+    def initialize: (ArtifactSet artifacts, ?warning: ^(String) -> void, ?stability_check: ^() -> bool, ?source_records: Array[GenerationInput], ?lock_sleeper: ^(Float) -> void) -> void
+
+    # @rbs () -> void
+    def commit: () -> void
+
+    private
+
+    # @rbs () -> void
+    def prepare_records: () -> void
+
+    # @rbs (Artifact artifact, String target) -> Integer
+    def target_mode: (Artifact artifact, String target) -> Integer
+
+    # @rbs () -> void
+    def acquire_locks: () -> void
+
+    # @rbs (File lock, String path) -> void
+    def acquire_lock: (File lock, String path) -> void
+
+    # @rbs (String target) -> String
+    def lock_path: (String target) -> String
+
+    # @rbs () -> void
+    def stage_records: () -> void
+
+    # @rbs () -> void
+    def backup_records: () -> void
+
+    # @rbs (String directory, String suffix) -> File
+    def create_temporary_file: (String directory, String suffix) -> File
+
+    # @rbs (String target, String directory) -> String
+    def create_backup_link: (String target, String directory) -> String
+
+    # @rbs (String directory, String suffix) { (String) -> void } -> void
+    def with_temporary_path: (String directory, String suffix) { (String) -> void } -> void
+
+    # @rbs (Symbol group) -> void
+    def install_group: (Symbol group) -> void
+
+    # @rbs (Artifact artifact) -> Symbol
+    def publication_group: (Artifact artifact) -> Symbol
+
+    # @rbs () -> void
+    def sync_directories!: () -> void
+
+    # @rbs () -> void
+    def cleanup_success: () -> void
+
+    # @rbs (Exception error) -> void
+    def report_post_commit_failure: (Exception error) -> void
+
+    # @rbs (String message) -> void
+    def warn_best_effort: (String message) -> void
+
+    # @rbs () -> void
+    def release_locks: () -> void
+  end
+end

data/sig/ibex/generation_transaction_recovery.rbs

@@ -0,0 +1,36 @@
+# Generated from lib/ibex/generation_transaction_recovery.rb with RBS::Inline
+
+module Ibex
+  # Failure recovery and best-effort cleanup for GenerationTransaction.
+  module GenerationTransactionRecovery
+    private
+
+    # @rbs (Exception cause) -> bot
+    def handle_failure: (Exception cause) -> bot
+
+    # @rbs (Exception cause, Array[String] rollback, Array[String] cleanup, Array[String] sync) -> bool
+    def source_change_clean?: (Exception cause, Array[String] rollback, Array[String] cleanup, Array[String] sync) -> bool
+
+    # rubocop:disable Layout/LineLength
+    # @rbs (Exception cause, Array[String] rollback, Array[String] cleanup, Array[String] sync, Array[String] recovery) -> Array[String]
+    def failure_details: (Exception cause, Array[String] rollback, Array[String] cleanup, Array[String] sync, Array[String] recovery) -> Array[String]
+
+    # @rbs () -> Array[String]
+    def recovery_artifacts: () -> Array[String]
+
+    # @rbs () -> Array[String]
+    def rollback: () -> Array[String]
+
+    # @rbs (Hash[Symbol, Object?] record) -> void
+    def rollback_record: (Hash[Symbol, Object?] record) -> void
+
+    # @rbs (preserve_backups: bool) -> Array[String]
+    def cleanup_artifacts: (preserve_backups: bool) -> Array[String]
+
+    # @rbs (String path, Array[String] failures) -> void
+    def remove_artifact: (String path, Array[String] failures) -> void
+
+    # @rbs () -> Array[String]
+    def sync_directories_best_effort: () -> Array[String]
+  end
+end

data/sig/ibex/generation_transaction_validation.rbs

@@ -0,0 +1,65 @@
+# Generated from lib/ibex/generation_transaction_validation.rb with RBS::Inline
+
+module Ibex
+  # Canonical target, source, symlink, and lock identity checks for generation.
+  module GenerationTransactionValidation
+    private def lock_path: (String) -> String
+
+    private
+
+    # Follow a final symlink while preserving the symlink path itself during publication.
+    # @rbs (String path, ?Hash[String, bool] seen, ?validate_links: bool) -> String
+    def resolved_target: (String path, ?Hash[String, bool] seen, ?validate_links: bool) -> String
+
+    # @rbs (String expanded, bool validate_links) -> String
+    def existing_target: (String expanded, bool validate_links) -> String
+
+    # @rbs (String target) -> void
+    def validate_existing_target!: (String target) -> void
+
+    # @rbs () -> void
+    def validate_source_boundaries!: () -> void
+
+    # @rbs (Array[String] lock_paths) -> void
+    def validate_lock_boundaries!: (Array[String] lock_paths) -> void
+
+    # @rbs (String path, File lock) -> void
+    def validate_lock_identity!: (String path, File lock) -> void
+
+    # @rbs () -> Array[String]
+    def protected_generation_paths: () -> Array[String]
+
+    # @rbs () -> Array[File::Stat]
+    def protected_generation_stats: () -> Array[File::Stat]
+
+    # @rbs (File::Stat path_stat, File::Stat lock_stat) -> bool
+    def stable_lock_identity?: (File::Stat path_stat, File::Stat lock_stat) -> bool
+
+    # @rbs (File::Stat left, File::Stat right) -> bool
+    def same_inode?: (File::Stat left, File::Stat right) -> bool
+
+    # @rbs (String left, String right) -> bool
+    def paths_alias?: (String left, String right) -> bool
+
+    # Reject target names that collide on common case-insensitive or
+    # normalization-insensitive filesystems, even when the current filesystem
+    # would permit both names.
+    # @rbs (String path) -> [String, String]
+    def portable_target_key: (String path) -> [ String, String ]
+
+    # @rbs (String phase) -> void
+    def ensure_sources_stable!: (String phase) -> void
+
+    # @rbs (String phase) -> void
+    def validate_active_locks!: (String phase) -> void
+
+    # @rbs (String phase) -> void
+    def validate_current_targets!: (String phase) -> void
+
+    # @rbs (Hash[Symbol, Object?] record, Array[String] sources, String phase) -> void
+    def validate_current_target!: (Hash[Symbol, Object?] record, Array[String] sources, String phase) -> void
+
+    # @rbs () -> void
+    def validate_locked_targets!: () -> void
+  end
+end

data/sig/ibex/grammar_tests.rbs

@@ -0,0 +1,93 @@
+# Generated from lib/ibex/grammar_tests.rb with RBS::Inline
+
+module Ibex
+  # Executes grammar-declared source examples against one generated parser.
+  module GrammarTests
+    DEFAULT_TIMEOUT: ::Integer
+
+    RESULT_MARKER: ::String
+
+    class Result < Struct[Symbol | String? | IR::location | Array[Integer]]
+      attr_accessor expectation(): Symbol
+
+      attr_accessor actual(): Symbol
+
+      attr_accessor error_class(): String?
+
+      attr_accessor error_message(): String?
+
+      attr_accessor location(): IR::location
+
+      attr_accessor production_ids(): Array[Integer]
+
+      def self.new: (?expectation: Symbol, ?actual: Symbol, ?error_class: String?, ?error_message: String?, ?location: IR::location, ?production_ids: Array[Integer]) -> instance
+                  | ({ ?expectation: Symbol, ?actual: Symbol, ?error_class: String?, ?error_message: String?, ?location: IR::location, ?production_ids: Array[Integer] }) -> instance
+    end
+
+    class Result
+      # @rbs () -> bool
+      def passed?: () -> bool
+    end
+
+    class ProductionCoverage < Struct[Array[Integer] | Integer]
+      attr_accessor covered_ids(): Array[Integer]
+
+      attr_accessor missing_ids(): Array[Integer]
+
+      attr_accessor production_count(): Integer
+
+      def self.new: (?covered_ids: Array[Integer], ?missing_ids: Array[Integer], ?production_count: Integer) -> instance
+                  | ({ ?covered_ids: Array[Integer], ?missing_ids: Array[Integer], ?production_count: Integer }) -> instance
+    end
+
+    class ProductionCoverage
+      # @rbs () -> Float
+      def percentage: () -> Float
+
+      # @rbs (Integer minimum) -> bool
+      def meets?: (Integer minimum) -> bool
+
+      # @rbs () -> bool
+      def complete?: () -> bool
+    end
+
+    # Runs all examples in one isolated process while creating a fresh parser
+    # instance for every case.
+    class Runner
+      CHILD_RUNNER: ::String
+
+      @automaton: IR::Automaton
+
+      @timeout: Integer
+
+      # @rbs (IR::Automaton automaton, ?timeout: Integer) -> void
+      def initialize: (IR::Automaton automaton, ?timeout: Integer) -> void
+
+      # @rbs () -> Array[Result]
+      def run: () -> Array[Result]
+
+      # @rbs (Array[Result] results) -> ProductionCoverage
+      def production_coverage: (Array[Result] results) -> ProductionCoverage
+
+      private
+
+      # @rbs () -> String
+      def generated_parser: () -> String
+
+      # @rbs (String parser_path, String runner_path) -> Array[Result]
+      def execute_child: (String parser_path, String runner_path) -> Array[Result]
+
+      # @rbs (Integer pid) -> Process::Status
+      def wait_for_child: (Integer pid) -> Process::Status
+
+      # @rbs (Process::Status status, String errors) -> bot
+      def raise_child_failure: (Process::Status status, String errors) -> bot
+
+      # @rbs (String output) -> Array[Result]
+      def decode_results: (String output) -> Array[Result]
+
+      # @rbs (IR::grammar_test test, Object? document) -> Result
+      def build_result: (IR::grammar_test test, Object? document) -> Result
+    end
+  end
+end

data/sig/ibex/ir/automaton_ir.rbs

@@ -13,8 +13,8 @@ module Ibex
       # @rbs (production: Integer, dot: Integer, lookaheads: Array[Integer]) -> void
       def initialize: (production: Integer, dot: Integer, lookaheads: Array[Integer]) -> void
 
-      # @rbs (Grammar grammar) -> Hash[Symbol, untyped]
-      def to_h: (Grammar grammar) -> Hash[Symbol, untyped]
+      # @rbs (Grammar grammar) -> Hash[Symbol, Object?]
+      def to_h: (Grammar grammar) -> Hash[Symbol, Object?]
     end
 
     # A deterministic LALR automaton state.
@@ -38,13 +38,13 @@ module Ibex
       #   ?conflicts: Array[conflict]) -> void
       def initialize: (id: Integer, items: Array[AutomatonItem], transitions: Hash[Integer, Integer], actions: Hash[Integer, parser_action], gotos: Hash[Integer, Integer], ?default_action: parser_action?, ?conflicts: Array[conflict]) -> void
 
-      # @rbs (Grammar grammar) -> Hash[Symbol, untyped]
-      def to_h: (Grammar grammar) -> Hash[Symbol, untyped]
+      # @rbs (Grammar grammar) -> Hash[Symbol, Object?]
+      def to_h: (Grammar grammar) -> Hash[Symbol, Object?]
 
       private
 
-      # @rbs (Hash[Integer, untyped] values, Grammar grammar) -> Hash[String, untyped]
-      def named_keys: (Hash[Integer, untyped] values, Grammar grammar) -> Hash[String, untyped]
+      # @rbs (Hash[Integer, Object?] values, Grammar grammar) -> Hash[String, Object?]
+      def named_keys: (Hash[Integer, Object?] values, Grammar grammar) -> Hash[String, Object?]
     end
 
     # Immutable LALR automaton and its source grammar.
@@ -57,21 +57,46 @@ module Ibex
 
       attr_reader states: Array[AutomatonState]
 
+      attr_reader entry_states: Hash[String, Integer]
+
       attr_reader conflict_summary: conflict_summary
 
       attr_reader schema_version: Integer
 
+      attr_reader entry_construction: String
+
       # @rbs (grammar: Grammar, states: Array[AutomatonState], conflict_summary: conflict_summary,
-      #   ?algorithm: String, ?grammar_digest: String?, ?schema_version: Integer) -> void
-      def initialize: (grammar: Grammar, states: Array[AutomatonState], conflict_summary: conflict_summary, ?algorithm: String, ?grammar_digest: String?, ?schema_version: Integer) -> void
+      #   ?algorithm: String, ?grammar_digest: String?, ?entry_states: Hash[String, Integer]?,
+      #   ?entry_construction: String) -> void
+      def initialize: (grammar: Grammar, states: Array[AutomatonState], conflict_summary: conflict_summary, ?algorithm: String, ?grammar_digest: String?, ?entry_states: Hash[String, Integer]?, ?entry_construction: String) -> void
 
-      # @rbs () -> Hash[Symbol, untyped]
-      def to_h: () -> Hash[Symbol, untyped]
+      # @rbs (grammar: Grammar, states: Array[AutomatonState], conflict_summary: conflict_summary,
+      #   algorithm: String, grammar_digest: String?, entry_states: Hash[String, Integer]?,
+      #   entry_construction: String) -> void
+      def initialize_current: (grammar: Grammar, states: Array[AutomatonState], conflict_summary: conflict_summary, algorithm: String, grammar_digest: String?, entry_states: Hash[String, Integer]?, entry_construction: String) -> void
+
+      # @rbs () -> Hash[Symbol, Object?]
+      def to_h: () -> Hash[Symbol, Object?]
 
       private
 
+      # @rbs () -> void
+      def validate_entry_states: () -> void
+
       # @rbs (Grammar grammar) -> String
       def digest_for: (Grammar grammar) -> String
+
+      # @rbs (String value) -> String
+      def validate_entry_construction: (String value) -> String
+
+      # @rbs () -> void
+      def validate_parser_contract: () -> void
+
+      # @rbs (ParserContract contract) -> void
+      def validate_parser_algorithm: (ParserContract contract) -> void
+
+      # @rbs (ParserContract contract) -> void
+      def validate_parser_entries: (ParserContract contract) -> void
     end
   end
 end

data/sig/ibex/ir/grammar_ir.rbs

@@ -2,10 +2,15 @@
 
 module Ibex
   module IR
+    # Grammar IR has one active wire format.  A future incompatible format
+    # change may advance this number, but the runtime never treats old
+    # formats as an alternate compatibility surface.
     SCHEMA_VERSION: ::Integer
 
-    # @rbs (untyped value) -> untyped
-    def self?.deep_freeze: (untyped value) -> untyped
+    SUPPORTED_SCHEMA_VERSIONS: Array[Integer]
+
+    # @rbs (Object? value) -> Object?
+    def self?.deep_freeze: (Object? value) -> Object?
 
     # An interned terminal or nonterminal.
     class GrammarSymbol
@@ -21,9 +26,15 @@ module Ibex
 
       attr_reader location: location?
 
+      attr_reader display_name: String?
+
+      attr_reader semantic_type: String?
+
+      attr_reader documentation: String?
+
       # @rbs (id: Integer, name: String, kind: Symbol, ?reserved: bool, ?precedence: precedence?,
-      #   ?location: location?) -> void
-      def initialize: (id: Integer, name: String, kind: Symbol, ?reserved: bool, ?precedence: precedence?, ?location: location?) -> void
+      #   ?location: location?, ?display_name: String?, ?semantic_type: String?, ?documentation: String?) -> void
+      def initialize: (id: Integer, name: String, kind: Symbol, ?reserved: bool, ?precedence: precedence?, ?location: location?, ?display_name: String?, ?semantic_type: String?, ?documentation: String?) -> void
 
       # @rbs () -> bool
       def terminal?: () -> bool
@@ -31,8 +42,8 @@ module Ibex
       # @rbs () -> bool
       def nonterminal?: () -> bool
 
-      # @rbs () -> Hash[Symbol, untyped]
-      def to_h: () -> Hash[Symbol, untyped]
+      # @rbs () -> Hash[Symbol, Object?]
+      def to_h: () -> Hash[Symbol, Object?]
     end
 
     # Opaque Ruby semantic action metadata.
@@ -45,11 +56,14 @@ module Ibex
 
       attr_reader context_length: Integer
 
-      # @rbs (code: String, location: location, ?named_refs: Array[named_ref], ?context_length: Integer) -> void
-      def initialize: (code: String, location: location, ?named_refs: Array[named_ref], ?context_length: Integer) -> void
+      attr_reader composition: action_composition?
 
-      # @rbs () -> Hash[Symbol, untyped]
-      def to_h: () -> Hash[Symbol, untyped]
+      # @rbs (code: String, location: location, ?named_refs: Array[named_ref], ?context_length: Integer,
+      #   ?composition: action_composition?) -> void
+      def initialize: (code: String, location: location, ?named_refs: Array[named_ref], ?context_length: Integer, ?composition: action_composition?) -> void
+
+      # @rbs () -> Hash[Symbol, Object?]
+      def to_h: () -> Hash[Symbol, Object?]
     end
 
     # A normalized BNF production using symbol ids.
@@ -64,14 +78,21 @@ module Ibex
 
       attr_reader precedence_override: Integer?
 
-      attr_reader origin: Hash[Symbol, untyped]
+      attr_reader origin: Hash[Symbol, Object?]
+
+      attr_reader documentation: String?
+
+      attr_reader expansion: production_expansion?
+
+      attr_reader node: node_annotation?
 
       # @rbs (id: Integer, lhs: Integer, rhs: Array[Integer], action: Action?, precedence_override: Integer?,
-      #   origin: Hash[Symbol, untyped]) -> void
-      def initialize: (id: Integer, lhs: Integer, rhs: Array[Integer], action: Action?, precedence_override: Integer?, origin: Hash[Symbol, untyped]) -> void
+      #   origin: Hash[Symbol, Object?], ?documentation: String?, ?expansion: production_expansion?,
+      #   ?node: node_annotation?) -> void
+      def initialize: (id: Integer, lhs: Integer, rhs: Array[Integer], action: Action?, precedence_override: Integer?, origin: Hash[Symbol, Object?], ?documentation: String?, ?expansion: production_expansion?, ?node: node_annotation?) -> void
 
-      # @rbs () -> Hash[Symbol, untyped]
-      def to_h: () -> Hash[Symbol, untyped]
+      # @rbs () -> Hash[Symbol, Object?]
+      def to_h: () -> Hash[Symbol, Object?]
     end
 
     # One opaque user-code block and the location of its first code line.
@@ -83,8 +104,8 @@ module Ibex
       # @rbs (code: String, location: location) -> void
       def initialize: (code: String, location: location) -> void
 
-      # @rbs () -> Hash[Symbol, untyped]
-      def to_h: () -> Hash[Symbol, untyped]
+      # @rbs () -> Hash[Symbol, Object?]
+      def to_h: () -> Hash[Symbol, Object?]
     end
 
     # Immutable normalized grammar exchanged between pipeline stages.
@@ -95,8 +116,24 @@ module Ibex
 
       attr_reader start: String
 
+      attr_reader starts: Array[String]
+
+      attr_reader mode: grammar_mode
+
       attr_reader expect: Integer
 
+      attr_reader expect_rr: Integer?
+
+      attr_reader parser_parameters: Array[parser_parameter]
+
+      attr_reader value_printers: Array[value_printer]
+
+      attr_reader grammar_tests: Array[grammar_test]
+
+      attr_reader lexer: Lexer?
+
+      attr_reader recovery: recovery_policy
+
       attr_reader options: grammar_options
 
       attr_reader symbols: Array[GrammarSymbol]
@@ -113,11 +150,30 @@ module Ibex
 
       attr_reader schema_version: Integer
 
-      # @rbs (class_name: String, superclass: String?, start: String, expect: Integer, options: grammar_options,
+      attr_reader source_provenance: source_provenance?
+
+      attr_reader parser_contract: ParserContract
+
+      # @rbs (class_name: String, superclass: String?, start: String, expect: Integer, ?expect_rr: Integer?,
+      #   options: grammar_options,
       #   symbols: Array[GrammarSymbol], productions: Array[Production], user_code: Hash[String, String],
       #   conversions: Hash[String, String], warnings: Array[grammar_warning], ?user_code_chunks: user_code_chunks?,
-      #   ?schema_version: Integer) -> void
-      def initialize: (class_name: String, superclass: String?, start: String, expect: Integer, options: grammar_options, symbols: Array[GrammarSymbol], productions: Array[Production], user_code: Hash[String, String], conversions: Hash[String, String], warnings: Array[grammar_warning], ?user_code_chunks: user_code_chunks?, ?schema_version: Integer) -> void
+      #   ?parser_parameters: Array[parser_parameter],
+      #   ?value_printers: Array[value_printer], ?grammar_tests: Array[grammar_test],
+      #   ?recovery: recovery_policy?, ?lexer: Lexer?,
+      #   ?mode: grammar_mode, ?starts: Array[String]?, ?parser_contract: ParserContract,
+      #   ?source_provenance: source_provenance?) -> void
+      # rubocop:disable Metrics/AbcSize, Metrics/ParameterLists
+      # Immutable current IR is constructed from explicit public fields.
+      def initialize: (class_name: String, superclass: String?, start: String, expect: Integer, options: grammar_options, symbols: Array[GrammarSymbol], productions: Array[Production], user_code: Hash[String, String], conversions: Hash[String, String], warnings: Array[grammar_warning], ?expect_rr: Integer?, ?user_code_chunks: user_code_chunks?, ?parser_parameters: Array[parser_parameter], ?value_printers: Array[value_printer], ?grammar_tests: Array[grammar_test], ?recovery: recovery_policy?, ?lexer: Lexer?, ?mode: grammar_mode, ?starts: Array[String]?, ?parser_contract: ParserContract, ?source_provenance: source_provenance?) -> void
+
+      # @rbs (class_name: String, superclass: String?, start: String, expect: Integer, options: grammar_options,
+      #   symbols: Array[GrammarSymbol], productions: Array[Production], user_code: Hash[String, String],
+      #   conversions: Hash[String, String], warnings: Array[grammar_warning], user_code_chunks: user_code_chunks?,
+      #   source_provenance: source_provenance?, expect_rr: Integer?, parser_parameters: Array[parser_parameter],
+      #   value_printers: Array[value_printer], grammar_tests: Array[grammar_test], recovery: recovery_policy?,
+      #   lexer: Lexer?, mode: grammar_mode, starts: Array[String]?, parser_contract: ParserContract) -> void
+      def initialize_current: (class_name: String, superclass: String?, start: String, expect: Integer, options: grammar_options, symbols: Array[GrammarSymbol], productions: Array[Production], user_code: Hash[String, String], conversions: Hash[String, String], warnings: Array[grammar_warning], user_code_chunks: user_code_chunks?, source_provenance: source_provenance?, expect_rr: Integer?, parser_parameters: Array[parser_parameter], value_printers: Array[value_printer], grammar_tests: Array[grammar_test], recovery: recovery_policy?, lexer: Lexer?, mode: grammar_mode, starts: Array[String]?, parser_contract: ParserContract) -> void
 
       # @rbs (String name) -> GrammarSymbol?
       def symbol: (String name) -> GrammarSymbol?
@@ -131,13 +187,31 @@ module Ibex
       # @rbs () -> Array[GrammarSymbol]
       def nonterminals: () -> Array[GrammarSymbol]
 
-      # @rbs () -> Hash[Symbol, untyped]
-      def to_h: () -> Hash[Symbol, untyped]
+      # @rbs () -> Hash[Symbol, Object?]
+      def to_h: () -> Hash[Symbol, Object?]
 
       private
 
+      # @rbs (grammar_mode mode) -> void
+      def validate_mode: (grammar_mode mode) -> void
+
+      # @rbs (String start, Array[String]? starts, grammar_mode mode) -> Array[String]
+      def validate_starts: (String start, Array[String]? starts, grammar_mode mode) -> Array[String]
+
+      # @rbs (Hash[Symbol, Object?] value) -> void
+      def append_optional_metadata: (Hash[Symbol, Object?] value) -> void
+
+      # @rbs (Hash[Symbol, Object?] value) -> void
+      def append_parser_metadata: (Hash[Symbol, Object?] value) -> void
+
+      # @rbs (Hash[Symbol, Object?] value) -> void
+      def append_recovery_metadata: (Hash[Symbol, Object?] value) -> void
+
       # @rbs () -> void
       def validate_user_code_chunks: () -> void
+
+      # @rbs (ParserContract parser_contract) -> void
+      def validate_current_metadata: (ParserContract parser_contract) -> void
     end
   end
 end