ibex 0.2.0 → 0.3.0

data/lib/ibex/generation_manifest.rb

@@ -6,7 +6,11 @@ require "json"
 
 module Ibex
   # Deterministic description of one published parser generation.
+  # rubocop:disable Metrics/ModuleLength -- manifest schema validation is kept in one auditable unit.
   module GenerationManifest
+    # @rbs!
+    #   type json_value = String | Integer | Float | bool | nil | Array[json_value] | Hash[String, json_value]
+
     SCHEMA_VERSION = 1 #: Integer
     IDENTIFIER = "generation" #: String
     ROOT_KEYS = %w[ibex_manifest schema_version input options artifacts].freeze #: Array[String]
@@ -16,7 +20,7 @@ module Ibex
 
     module_function
 
-    # @rbs (ArtifactSet artifacts, source_records: Array[GenerationInput], options: Hash[String, untyped]) -> String
+    # @rbs (ArtifactSet artifacts, source_records: Array[GenerationInput], options: Hash[String, Object?]) -> String
     def render(artifacts, source_records:, options:)
       files = source_records.map(&:to_h)
       document = {
@@ -34,24 +38,26 @@ module Ibex
     end
 
     # Validate the manifest shape and, by default, every published artifact digest.
-    # @rbs (String source, ?verify_artifacts: bool) -> Hash[String, untyped]
+    # @rbs (String source, ?verify_artifacts: bool) -> Hash[String, json_value]
     def validate(source, verify_artifacts: true)
-      document = JSON.parse(source)
+      document = JSON.parse(source) #: Object?
       validate_document(document)
-      verify_entries(document.fetch("artifacts")) if verify_artifacts
-      document
+      document_hash = document #: Hash[String, json_value]
+      artifacts = document_hash.fetch("artifacts") #: Array[Object?]
+      verify_entries(artifacts) if verify_artifacts
+      document_hash
     rescue JSON::ParserError, KeyError, TypeError, ArgumentError => e
       raise Ibex::Error, "(manifest):1:1: invalid generation manifest: #{e.message}"
     end
 
-    # @rbs (String path, ?verify_artifacts: bool) -> Hash[String, untyped]
+    # @rbs (String path, ?verify_artifacts: bool) -> Hash[String, json_value]
     def validate_file(path, verify_artifacts: true)
       validate(File.binread(path), verify_artifacts: verify_artifacts)
     rescue SystemCallError, ArgumentError => e
       raise Ibex::Error, "#{path}:1:1: cannot read generation manifest: #{e.message}"
     end
 
-    # @rbs (Artifact artifact) -> Hash[String, untyped]
+    # @rbs (Artifact artifact) -> Hash[String, json_value]
     def artifact_entry(artifact)
       {
         "kind" => artifact.kind.to_s,
@@ -62,19 +68,20 @@ module Ibex
     end
     private_class_method :artifact_entry
 
-    # @rbs (Array[Hash[String, untyped]] files) -> String
+    # @rbs (Array[Hash[String, json_value]] files) -> String
     def input_digest(files)
       digest = Digest::SHA256.new
       files.each do |entry|
-        digest << entry.fetch("path") << "\0"
-        digest << entry.fetch("sha256") << "\0"
-        digest << entry.fetch("bytesize").to_s << "\0"
+        path = entry.fetch("path") # @type var path: String
+        sha256 = entry.fetch("sha256") # @type var sha256: String
+        bytesize = entry.fetch("bytesize") # @type var bytesize: Integer
+        digest << path << "\0" << sha256 << "\0" << bytesize.to_s << "\0"
       end
       digest.hexdigest
     end
     private_class_method :input_digest
 
-    # @rbs (Hash[String, untyped] value) -> Hash[String, untyped]
+    # @rbs (Hash[String, Object?] value) -> Hash[String, Object?]
     def sorted_hash(value)
       value.keys.sort.to_h do |key|
         child = value.fetch(key)
@@ -84,7 +91,7 @@ module Ibex
     end
     private_class_method :sorted_hash
 
-    # @rbs (untyped document) -> void
+    # @rbs (Object? document) -> void
     def validate_document(document)
       raise TypeError, "document must be an object" unless document.is_a?(Hash)
 
@@ -100,14 +107,14 @@ module Ibex
     end
     private_class_method :validate_document
 
-    # @rbs (Hash[untyped, untyped] document) -> void
+    # @rbs (Hash[Object?, Object?] document) -> void
     def validate_identity(document)
       raise TypeError, "unsupported manifest identifier" unless document["ibex_manifest"] == IDENTIFIER
       raise TypeError, "unsupported schema_version" unless document["schema_version"] == SCHEMA_VERSION
     end
     private_class_method :validate_identity
 
-    # @rbs (untyped input) -> void
+    # @rbs (Object? input) -> void
     def validate_input(input)
       raise TypeError, "input must be an object" unless input.is_a?(Hash)
 
@@ -125,13 +132,13 @@ module Ibex
     end
     private_class_method :validate_input
 
-    # @rbs (Array[untyped] entries, String label, ?require_kind: bool) -> void
+    # @rbs (Array[Object?] entries, String label, ?require_kind: bool) -> void
     def validate_entries(entries, label, require_kind: false)
       entries.each { |entry| validate_entry(entry, label, require_kind) }
     end
     private_class_method :validate_entries
 
-    # @rbs (untyped entry, String label, bool require_kind) -> void
+    # @rbs (Object? entry, String label, bool require_kind) -> void
     def validate_entry(entry, label, require_kind)
       raise TypeError, "#{label} must be an object" unless entry.is_a?(Hash)
 
@@ -146,7 +153,7 @@ module Ibex
     end
     private_class_method :validate_entry
 
-    # @rbs (untyped path, String label) -> void
+    # @rbs (Object? path, String label) -> void
     def validate_path(path, label)
       raise TypeError, "#{label} path must be a non-empty string" unless path.is_a?(String) && !path.empty?
       return unless path.include?("\0") || path.match?(/[[:cntrl:]]/)
@@ -155,7 +162,7 @@ module Ibex
     end
     private_class_method :validate_path
 
-    # @rbs (untyped kind, String label) -> void
+    # @rbs (Object? kind, String label) -> void
     def validate_kind(kind, label)
       return if kind.is_a?(String) && !kind.empty?
 
@@ -163,7 +170,7 @@ module Ibex
     end
     private_class_method :validate_kind
 
-    # @rbs (untyped digest, String label) -> void
+    # @rbs (Object? digest, String label) -> void
     def validate_digest(digest, label)
       return if digest.is_a?(String) && digest.match?(/\A[0-9a-f]{64}\z/)
 
@@ -171,7 +178,7 @@ module Ibex
     end
     private_class_method :validate_digest
 
-    # @rbs (Hash[untyped, untyped] value, Array[String] expected, String label) -> void
+    # @rbs (Hash[Object?, Object?] value, Array[String] expected, String label) -> void
     def exact_keys!(value, expected, label)
       keys = value.keys
       raise TypeError, "#{label} keys must be strings" unless keys.all?(String)
@@ -183,18 +190,22 @@ module Ibex
     end
     private_class_method :exact_keys!
 
-    # @rbs (Array[untyped] entries) -> void
+    # @rbs (Array[Object?] entries) -> void
     def verify_entries(entries)
       entries.each do |entry|
-        path = entry.fetch("path")
+        entry_hash = entry #: Hash[String, json_value]
+        path = entry_hash.fetch("path") #: String
         source = File.binread(path)
-        raise TypeError, "artifact bytesize mismatch for #{path}" unless source.bytesize == entry.fetch("bytesize")
+        bytesize = entry_hash.fetch("bytesize") #: Integer
+        sha256 = entry_hash.fetch("sha256") #: String
+        raise TypeError, "artifact bytesize mismatch for #{path}" unless source.bytesize == bytesize
         raise TypeError, "artifact digest mismatch for #{path}" unless
-          Digest::SHA256.hexdigest(source) == entry.fetch("sha256")
+          Digest::SHA256.hexdigest(source) == sha256
       end
     rescue SystemCallError => e
       raise TypeError, "cannot read artifact: #{e.message}"
     end
     private_class_method :verify_entries
   end
+  # rubocop:enable Metrics/ModuleLength
 end

data/lib/ibex/generation_transaction.rb

@@ -37,7 +37,7 @@ module Ibex
       @lock_sleeper = lock_sleeper
       @locks = [] #: Array[File]
       @locked_paths = [] #: Array[String]
-      @records = [] #: Array[Hash[Symbol, untyped]]
+      @records = [] #: Array[Hash[Symbol, Object?]]
       @committed = false
       @temporary_sequence = 0
     end

data/lib/ibex/generation_transaction_recovery.rb

@@ -57,14 +57,14 @@ module Ibex
       failures
     end
 
-    # @rbs (Hash[Symbol, untyped] record) -> void
+    # @rbs (Hash[Symbol, Object?] record) -> void
     def rollback_record(record)
-      target = record.fetch(:target)
+      target = record.fetch(:target) #: String
       if record.fetch(:backed_up)
         if record.fetch(:installed)
-          File.rename(record.fetch(:backup), target)
+          File.rename(record.fetch(:backup).to_s, target)
         else
-          File.unlink(record.fetch(:backup))
+          File.unlink(record.fetch(:backup).to_s)
         end
         record[:backup] = nil
         record[:backed_up] = false

data/lib/ibex/generation_transaction_validation.rb

@@ -170,9 +170,9 @@ module Ibex
             "(generation):1:1: cannot revalidate artifact target #{phase}: #{e.message}"
     end
 
-    # @rbs (Hash[Symbol, untyped] record, Array[String] sources, String phase) -> void
+    # @rbs (Hash[Symbol, Object?] record, Array[String] sources, String phase) -> void
     def validate_current_target!(record, sources, phase)
-      artifact = record.fetch(:artifact)
+      artifact = record.fetch(:artifact) #: Artifact
       current = resolved_target(artifact.path, validate_links: false)
       unless current == record.fetch(:target)
         raise GenerationTransaction::SourceChanged,

data/lib/ibex/grammar_tests.rb

@@ -182,7 +182,7 @@ module Ibex
         raise Ibex::Error, "(test):1:1: invalid grammar test process result: #{e.message}"
       end
 
-      # @rbs (IR::grammar_test test, untyped document) -> Result
+      # @rbs (IR::grammar_test test, Object? document) -> Result
       def build_result(test, document)
         unless document.is_a?(Hash) && %w[accept reject error].include?(document["actual"])
           raise Ibex::Error, "(test):1:1: grammar test process returned an invalid case result"

data/lib/ibex/ir/automaton_ir.rb

@@ -16,7 +16,7 @@ module Ibex
         freeze
       end
 
-      # @rbs (Grammar grammar) -> Hash[Symbol, untyped]
+      # @rbs (Grammar grammar) -> Hash[Symbol, Object?]
       def to_h(grammar)
         { production: @production, dot: @dot,
           lookaheads: @lookaheads.map do |id|
@@ -50,7 +50,7 @@ module Ibex
         freeze
       end
 
-      # @rbs (Grammar grammar) -> Hash[Symbol, untyped]
+      # @rbs (Grammar grammar) -> Hash[Symbol, Object?]
       def to_h(grammar)
         { id: @id, items: @items.map { |item| item.to_h(grammar) },
           transitions: named_keys(@transitions, grammar), actions: named_keys(@actions, grammar),
@@ -59,7 +59,7 @@ module Ibex
 
       private
 
-      # @rbs (Hash[Integer, untyped] values, Grammar grammar) -> Hash[String, untyped]
+      # @rbs (Hash[Integer, Object?] values, Grammar grammar) -> Hash[String, Object?]
       def named_keys(values, grammar)
         values.to_h do |symbol_id, value|
           symbol = grammar.symbol_by_id(symbol_id) || raise(Ibex::Error, "missing grammar symbol id #{symbol_id}")
@@ -77,42 +77,55 @@ module Ibex
       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,
-      #   ?entry_states: Hash[String, Integer]?) -> void
+      #   ?algorithm: String, ?grammar_digest: String?, ?entry_states: Hash[String, Integer]?,
+      #   ?entry_construction: String) -> void
       def initialize(grammar:, states:, conflict_summary:, algorithm: "lalr1", grammar_digest: nil,
-                     schema_version: SCHEMA_VERSION, entry_states: nil)
-        unless SUPPORTED_SCHEMA_VERSIONS.include?(schema_version)
-          raise Ibex::Error, "unsupported automaton schema_version #{schema_version.inspect}"
-        end
+                     entry_states: nil, entry_construction: "shared")
+        initialize_current(
+          grammar: grammar, states: states, conflict_summary: conflict_summary, algorithm: algorithm,
+          grammar_digest: grammar_digest, entry_states: entry_states, entry_construction: entry_construction
+        )
+      end
 
-        grammar = Migration.to_v2(grammar) if schema_version >= 2 && grammar.schema_version != schema_version
-        raise Ibex::Error, "automaton migration did not produce a grammar" unless grammar.is_a?(Grammar)
-        unless grammar.schema_version == schema_version
-          raise Ibex::Error,
-                "automaton schema_version #{schema_version} requires Grammar IR v#{schema_version}, " \
-                "got v#{grammar.schema_version}"
+      # @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:, states:, conflict_summary:, algorithm:, grammar_digest:, entry_states:,
+                             entry_construction:)
+        unless grammar.schema_version == SCHEMA_VERSION
+          raise Ibex::Error, "automaton requires the current Grammar IR format"
         end
 
         @algorithm = algorithm.freeze
         @grammar = grammar
-        @grammar_digest = (grammar_digest || digest_for(grammar)).freeze
+        expected_digest = digest_for(grammar)
+        if grammar_digest && grammar_digest != expected_digest
+          raise Ibex::Error,
+                "(ir):1:1: $.grammar_digest does not match the embedded grammar; expected #{expected_digest.inspect}"
+        end
+        @grammar_digest = (grammar_digest || expected_digest).freeze
         @states = states.freeze
         @entry_states = IR.deep_freeze(entry_states || { grammar.start => 0 })
         validate_entry_states
         @conflict_summary = IR.deep_freeze(conflict_summary)
-        @schema_version = schema_version
+        @schema_version = SCHEMA_VERSION
+        @entry_construction = validate_entry_construction(entry_construction)
+        validate_parser_contract
         freeze
       end
+      private :initialize_current
 
-      # @rbs () -> Hash[Symbol, untyped]
+      # @rbs () -> Hash[Symbol, Object?]
       def to_h
         value = { ibex_ir: "automaton", schema_version: @schema_version, algorithm: @algorithm,
                   grammar_digest: @grammar_digest, grammar: @grammar.to_h,
                   states: @states.map { |state| state.to_h(@grammar) },
-                  conflict_summary: @conflict_summary } #: Hash[Symbol, untyped]
+                  conflict_summary: @conflict_summary } #: Hash[Symbol, Object?]
         value[:entry_states] = @entry_states unless @entry_states == { @grammar.start => 0 }
+        value[:entry_construction] = @entry_construction
         value
       end
 
@@ -137,6 +150,35 @@ module Ibex
         require "digest"
         "sha256:#{Digest::SHA256.hexdigest(IR::Serialize.dump(grammar))}"
       end
+
+      # @rbs (String value) -> String
+      def validate_entry_construction(value)
+        raise Ibex::Error, "entry construction must be shared or isolated" unless %w[shared isolated].include?(value)
+
+        value.dup.freeze
+      end
+
+      # @rbs () -> void
+      def validate_parser_contract
+        contract = @grammar.parser_contract
+        validate_parser_algorithm(contract)
+        validate_parser_entries(contract)
+      end
+
+      # @rbs (ParserContract contract) -> void
+      def validate_parser_algorithm(contract)
+        selected_algorithm = { "lalr1" => :lalr, "ielr1" => :ielr }.fetch(@algorithm, @algorithm.to_sym)
+        return unless contract.algorithm.explicit && contract.algorithm.value != selected_algorithm
+
+        raise Ibex::Error, "automaton algorithm conflicts with the embedded parser contract"
+      end
+
+      # @rbs (ParserContract contract) -> void
+      def validate_parser_entries(contract)
+        return unless contract.entries.explicit && contract.entries.value.to_s != @entry_construction
+
+        raise Ibex::Error, "automaton entry construction conflicts with the embedded parser contract"
+      end
     end
   end
 end

data/lib/ibex/ir/grammar_ir.rb

@@ -1,11 +1,16 @@
 # frozen_string_literal: true
 
+require_relative "parser_contract"
+
 module Ibex
   module IR
-    SCHEMA_VERSION = 2
-    SUPPORTED_SCHEMA_VERSIONS = [1, 2].freeze #: Array[Integer]
+    # 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 = 1
+    SUPPORTED_SCHEMA_VERSIONS = [SCHEMA_VERSION].freeze #: Array[Integer]
 
-    # @rbs (untyped value) -> untyped
+    # @rbs (Object? value) -> Object?
     def deep_freeze(value)
       case value
       when Array then value.each { |item| deep_freeze(item) }
@@ -52,13 +57,13 @@ module Ibex
       # @rbs () -> bool
       def nonterminal? = @kind == :nonterminal
 
-      # @rbs (?schema_version: Integer) -> Hash[Symbol, untyped]
-      def to_h(schema_version: SCHEMA_VERSION)
+      # @rbs () -> Hash[Symbol, Object?]
+      def to_h
         value = { id: @id, name: @name, kind: @kind, reserved: @reserved,
-                  prec: @precedence, loc: @location } #: Hash[Symbol, untyped]
+                  prec: @precedence, loc: @location } #: Hash[Symbol, Object?]
         value[:display_name] = @display_name if @display_name
         value[:semantic_type] = @semantic_type if @semantic_type
-        value[:doc] = @documentation if schema_version >= 2
+        value[:doc] = @documentation
         value
       end
     end
@@ -82,11 +87,11 @@ module Ibex
         freeze
       end
 
-      # @rbs (?schema_version: Integer) -> Hash[Symbol, untyped]
-      def to_h(schema_version: SCHEMA_VERSION)
+      # @rbs () -> Hash[Symbol, Object?]
+      def to_h
         value = { code: @code, loc: @location, named_refs: @named_refs,
-                  context_length: @context_length } #: Hash[Symbol, untyped]
-        value[:composition] = @composition if schema_version >= 2
+                  context_length: @context_length } #: Hash[Symbol, Object?]
+        value[:composition] = @composition
         value
       end
     end
@@ -98,13 +103,13 @@ module Ibex
       attr_reader :rhs #: Array[Integer]
       attr_reader :action #: Action?
       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], ?documentation: String?, ?expansion: production_expansion?,
+      #   origin: Hash[Symbol, Object?], ?documentation: String?, ?expansion: production_expansion?,
       #   ?node: node_annotation?) -> void
       def initialize(id:, lhs:, rhs:, action:, precedence_override:, origin:, documentation: nil, expansion: nil,
                      node: nil)
@@ -120,15 +125,13 @@ module Ibex
         freeze
       end
 
-      # @rbs (?schema_version: Integer) -> Hash[Symbol, untyped]
-      def to_h(schema_version: SCHEMA_VERSION)
-        value = { id: @id, lhs: @lhs, rhs: @rhs, action: @action&.to_h(schema_version: schema_version),
-                  prec_override: @precedence_override, origin: @origin } #: Hash[Symbol, untyped]
-        if schema_version >= 2
-          value[:doc] = @documentation
-          value[:expansion] = @expansion
-          value[:node] = @node if @node
-        end
+      # @rbs () -> Hash[Symbol, Object?]
+      def to_h
+        value = { id: @id, lhs: @lhs, rhs: @rhs, action: @action&.to_h,
+                  prec_override: @precedence_override, origin: @origin } #: Hash[Symbol, Object?]
+        value[:doc] = @documentation
+        value[:expansion] = @expansion
+        value[:node] = @node if @node
         value
       end
     end
@@ -145,7 +148,7 @@ module Ibex
         freeze
       end
 
-      # @rbs () -> Hash[Symbol, untyped]
+      # @rbs () -> Hash[Symbol, Object?]
       def to_h
         { code: @code, loc: @location }
       end
@@ -174,25 +177,47 @@ module Ibex
       attr_reader :warnings #: Array[grammar_warning]
       attr_reader :schema_version #: Integer
       attr_reader :source_provenance #: source_provenance?
-      attr_reader :migration #: migration_metadata?
+      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, ?source_provenance: source_provenance?,
-      #   ?migration: migration_metadata?, ?parser_parameters: Array[parser_parameter],
+      #   ?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]?) -> void
+      #   ?mode: grammar_mode, ?starts: Array[String]?, ?parser_contract: ParserContract,
+      #   ?source_provenance: source_provenance?) -> void
       # rubocop:disable Metrics/AbcSize, Metrics/ParameterLists
-      # Immutable versioned IR is constructed from explicit public fields.
+      # Immutable current IR is constructed from explicit public fields.
       def initialize(class_name:, superclass:, start:, expect:, options:, symbols:, productions:, user_code:,
-                     conversions:, warnings:, user_code_chunks: nil, schema_version: SCHEMA_VERSION,
-                     source_provenance: nil, migration: nil, expect_rr: nil, parser_parameters: [], value_printers: [],
-                     grammar_tests: [], recovery: nil, lexer: nil, mode: :default, starts: nil)
+                     conversions:, warnings:, user_code_chunks: nil,
+                     source_provenance: nil, expect_rr: nil, parser_parameters: [], value_printers: [],
+                     grammar_tests: [], recovery: nil, lexer: nil, mode: :default, starts: nil,
+                     parser_contract: ParserContract.new)
+        initialize_current(
+          class_name: class_name, superclass: superclass, start: start, expect: expect, options: options,
+          symbols: symbols, productions: productions, user_code: user_code, conversions: conversions,
+          warnings: warnings, user_code_chunks: user_code_chunks,
+          source_provenance: source_provenance, expect_rr: expect_rr,
+          parser_parameters: parser_parameters, value_printers: value_printers, grammar_tests: grammar_tests,
+          recovery: recovery, lexer: lexer, mode: mode, starts: starts, parser_contract: parser_contract
+        )
+      end
+
+      # @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:, superclass:, start:, expect:, options:, symbols:, productions:, user_code:,
+                             conversions:, warnings:, user_code_chunks:, source_provenance:, expect_rr:,
+                             parser_parameters:, value_printers:, grammar_tests:, recovery:, lexer:, mode:, starts:,
+                             parser_contract:)
         validate_mode(mode)
         normalized_starts = validate_starts(start, starts, mode)
+        validate_current_metadata(parser_contract)
 
         @class_name = class_name.freeze
         @superclass = superclass&.freeze
@@ -214,14 +239,15 @@ module Ibex
         validate_user_code_chunks
         @conversions = IR.deep_freeze(conversions)
         @warnings = IR.deep_freeze(warnings)
-        @schema_version = schema_version
+        @schema_version = SCHEMA_VERSION
         @source_provenance = IR.deep_freeze(source_provenance)
-        @migration = IR.deep_freeze(migration)
+        @parser_contract = IR.deep_freeze(parser_contract)
         @symbols_by_name = @symbols.to_h { |symbol| [symbol.name, symbol] }.freeze
         @symbols_by_id = @symbols.to_h { |symbol| [symbol.id, symbol] }.freeze
         freeze
       end
       # rubocop:enable Metrics/AbcSize, Metrics/ParameterLists
+      private :initialize_current
 
       # @rbs (String name) -> GrammarSymbol?
       def symbol(name) = @symbols_by_name[name]
@@ -232,14 +258,14 @@ module Ibex
       # @rbs () -> Array[GrammarSymbol]
       def nonterminals = @symbols.select(&:nonterminal?)
 
-      # @rbs () -> Hash[Symbol, untyped]
+      # @rbs () -> Hash[Symbol, Object?]
       def to_h
         value = { ibex_ir: "grammar", schema_version: @schema_version, class_name: @class_name, superclass: @superclass,
                   start: @start, expect: @expect, options: @options,
-                  symbols: @symbols.map { |symbol| symbol.to_h(schema_version: @schema_version) },
-                  productions: @productions.map { |production| production.to_h(schema_version: @schema_version) },
+                  symbols: @symbols.map(&:to_h),
+                  productions: @productions.map(&:to_h),
                   user_code: @user_code, conversions: @conversions,
-                  warnings: @warnings } #: Hash[Symbol, untyped]
+                  warnings: @warnings } #: Hash[Symbol, Object?]
         append_optional_metadata(value)
         value
       end
@@ -262,30 +288,28 @@ module Ibex
         values
       end
 
-      # @rbs (Hash[Symbol, untyped] value) -> void
+      # @rbs (Hash[Symbol, Object?] value) -> void
       def append_optional_metadata(value)
         append_parser_metadata(value)
         append_recovery_metadata(value)
         value[:user_code_chunks] = @user_code_chunks.transform_values { |chunks| chunks.map(&:to_h) } \
           unless @user_code_chunks.empty?
-        return unless @schema_version >= 2
-
         value[:source_provenance] = @source_provenance
-        value[:migration] = @migration
+        value[:parser_contract] = @parser_contract.to_h
       end
 
-      # @rbs (Hash[Symbol, untyped] value) -> void
+      # @rbs (Hash[Symbol, Object?] value) -> void
       def append_parser_metadata(value)
         value[:expect_rr] = @expect_rr unless @expect_rr.nil?
         value[:mode] = @mode if @mode == :extended
         value[:starts] = @starts if @starts.length > 1
         value[:params] = @parser_parameters unless @parser_parameters.empty?
         value[:printers] = @value_printers unless @value_printers.empty?
-        value[:tests] = @grammar_tests unless @grammar_tests.empty? || @schema_version < 2
-        value[:lexer] = @lexer.to_h if @lexer && @schema_version >= 2
+        value[:tests] = @grammar_tests unless @grammar_tests.empty?
+        value[:lexer] = @lexer.to_h if @lexer
       end
 
-      # @rbs (Hash[Symbol, untyped] value) -> void
+      # @rbs (Hash[Symbol, Object?] value) -> void
       def append_recovery_metadata(value)
         return if @recovery[:sync_tokens].empty? && @recovery[:on_error_reduce].empty?
 
@@ -300,6 +324,13 @@ module Ibex
           raise Ibex::Error, "(ir):1:1: user-code chunks do not match the concatenated #{name} section"
         end
       end
+
+      # @rbs (ParserContract parser_contract) -> void
+      def validate_current_metadata(parser_contract)
+        return if parser_contract.is_a?(ParserContract)
+
+        raise ArgumentError, "parser_contract must be a ParserContract"
+      end
     end
   end
 end

data/lib/ibex/ir/lexer_ir.rb

@@ -32,7 +32,7 @@ module Ibex
         freeze
       end
 
-      # @rbs () -> Hash[Symbol, untyped]
+      # @rbs () -> Hash[Symbol, lexer_rule_document_value]
       def to_h
         {
           id: @id, state: @state, kind: @kind, token: @token, pattern: @pattern,
@@ -41,15 +41,15 @@ module Ibex
       end
     end
 
-    # Independently versioned lexer contract embedded by Grammar IR v2.
+    # Independently versioned lexer contract embedded by the current Grammar IR.
     class Lexer
       attr_reader :states #: Array[String]
       attr_reader :rules #: Array[LexerRule]
-      attr_reader :warnings #: Array[Hash[Symbol, untyped]]
+      attr_reader :warnings #: Array[lexer_warning]
       attr_reader :schema_version #: Integer
       attr_reader :source_provenance #: source_provenance?
 
-      # @rbs (states: Array[String], rules: Array[LexerRule], warnings: Array[Hash[Symbol, untyped]],
+      # @rbs (states: Array[String], rules: Array[LexerRule], warnings: Array[lexer_warning],
       #   ?schema_version: Integer, ?source_provenance: source_provenance?) -> void
       def initialize(states:, rules:, warnings:, schema_version: LEXER_SCHEMA_VERSION, source_provenance: nil)
         raise ArgumentError, "lexer states must start with INITIAL" unless states.first == "INITIAL"
@@ -63,7 +63,7 @@ module Ibex
         freeze
       end
 
-      # @rbs () -> Hash[Symbol, untyped]
+      # @rbs () -> Hash[Symbol, lexer_document_value]
       def to_h
         {
           ibex_ir: "lexer", schema_version: @schema_version, initial_state: "INITIAL",