ibex 0.1.0 → 0.3.0

data/lib/ibex/ir/lexer_ir.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module Ibex
+  module IR
+    LEXER_SCHEMA_VERSION = 1
+    SUPPORTED_LEXER_SCHEMA_VERSIONS = [LEXER_SCHEMA_VERSION].freeze #: Array[Integer]
+
+    # One normalized, state-scoped lexer rule.
+    class LexerRule
+      attr_reader :id #: Integer
+      attr_reader :state #: String
+      attr_reader :kind #: Symbol
+      attr_reader :token #: String?
+      attr_reader :pattern #: String
+      attr_reader :pattern_kind #: Symbol
+      attr_reader :options #: String
+      attr_reader :action #: String?
+      attr_reader :location #: location
+
+      # @rbs (id: Integer, state: String, kind: Symbol, token: String?, pattern: String, pattern_kind: Symbol,
+      #   options: String, action: String?, location: location) -> void
+      def initialize(id:, state:, kind:, token:, pattern:, pattern_kind:, options:, action:, location:)
+        @id = id
+        @state = state.freeze
+        @kind = kind
+        @token = token&.freeze
+        @pattern = pattern.freeze
+        @pattern_kind = pattern_kind
+        @options = options.freeze
+        @action = action&.freeze
+        @location = IR.deep_freeze(location)
+        freeze
+      end
+
+      # @rbs () -> Hash[Symbol, lexer_rule_document_value]
+      def to_h
+        {
+          id: @id, state: @state, kind: @kind, token: @token, pattern: @pattern,
+          pattern_kind: @pattern_kind, options: @options, action: @action, loc: @location
+        }
+      end
+    end
+
+    # 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[lexer_warning]
+      attr_reader :schema_version #: Integer
+      attr_reader :source_provenance #: source_provenance?
+
+      # @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"
+        raise ArgumentError, "lexer states must be unique" unless states.uniq.length == states.length
+
+        @states = states.map(&:freeze).freeze
+        @rules = rules.freeze
+        @warnings = IR.deep_freeze(warnings)
+        @schema_version = schema_version
+        @source_provenance = IR.deep_freeze(source_provenance)
+        freeze
+      end
+
+      # @rbs () -> Hash[Symbol, lexer_document_value]
+      def to_h
+        {
+          ibex_ir: "lexer", schema_version: @schema_version, initial_state: "INITIAL",
+          states: @states, rules: @rules.map(&:to_h), warnings: @warnings,
+          source_provenance: @source_provenance
+        }
+      end
+    end
+  end
+end

data/lib/ibex/ir/parser_contract.rb

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+require_relative "../location"
+
+module Ibex
+  module IR
+    # Root-owned parser configuration persisted by the current Grammar IR.
+    class ParserContract
+      # @rbs!
+      #   type definition = { configuration: String, values: Array[Symbol] }
+      #   type entry_location = { file: String?, line: Integer, column: Integer }
+      #   type entry_value = String? | bool | entry_location?
+
+      DEFINITIONS = {
+        algorithm: {
+          configuration: "parser.algorithm", values: %i[slr lalr ielr lr1].freeze
+        }.freeze,
+        entries: {
+          configuration: "parser.entries", values: %i[shared isolated].freeze
+        }.freeze,
+        cst_trivia: {
+          configuration: "cst.trivia", values: %i[leading balanced drop].freeze
+        }.freeze
+      }.freeze #: Hash[Symbol, definition]
+
+      # One specified or explicitly unspecified contract field.
+      class Entry
+        attr_reader :key #: Symbol
+        attr_reader :value #: Symbol?
+        attr_reader :location #: Location?
+        attr_reader :explicit #: bool
+
+        # @rbs (Symbol key, ?value: Symbol?, ?location: Location?, ?explicit: bool) -> void
+        def initialize(key, value: nil, location: nil, explicit: false)
+          definition = DEFINITIONS.fetch(key) { raise ArgumentError, "unknown parser contract key #{key.inspect}" }
+          validate_state!(key, definition.fetch(:values), value, location, explicit)
+
+          @key = key
+          @value = value
+          @location = location
+          @explicit = explicit
+          freeze
+        end
+
+        # @rbs () -> Hash[Symbol, entry_value]
+        def to_h
+          { value: @value&.to_s, explicit: @explicit, loc: serialized_location }
+        end
+
+        private
+
+        # @rbs (Symbol key, Array[Symbol] allowed, Symbol? value, Location? location, bool explicit) -> void
+        def validate_state!(key, allowed, value, location, explicit)
+          raise ArgumentError, "explicit must be boolean" unless [true, false].include?(explicit)
+
+          if explicit
+            raise ArgumentError, "#{key} must be one of #{allowed.join(', ')}" unless allowed.include?(value)
+            unless location.is_a?(Location) && location.file && !location.file.empty?
+              raise ArgumentError, "explicit #{key} requires a source location with a file"
+            end
+
+            return
+          end
+
+          raise ArgumentError, "unspecified #{key} cannot carry a value" unless value.nil?
+          raise ArgumentError, "unspecified #{key} cannot carry a source location" unless location.nil?
+        end
+
+        # @rbs () -> entry_location?
+        def serialized_location
+          location = @location
+          return unless location
+
+          { file: location.file, line: location.line, column: location.column }
+        end
+      end
+
+      attr_reader :algorithm #: Entry
+      attr_reader :entries #: Entry
+      attr_reader :cst_trivia #: Entry
+
+      # @rbs (?algorithm: Entry?, ?entries: Entry?, ?cst_trivia: Entry?) -> void
+      def initialize(algorithm: nil, entries: nil, cst_trivia: nil)
+        @algorithm = normalize_entry(:algorithm, algorithm)
+        @entries = normalize_entry(:entries, entries)
+        @cst_trivia = normalize_entry(:cst_trivia, cst_trivia)
+        freeze
+      end
+
+      # @rbs () -> Hash[Symbol, Hash[Symbol, entry_value]]
+      def to_h
+        {
+          algorithm: @algorithm.to_h,
+          entries: @entries.to_h,
+          cst_trivia: @cst_trivia.to_h
+        }
+      end
+
+      # Values supplied to the typed resolver; unspecified fields are absent.
+      # @rbs () -> Hash[String, Symbol]
+      def configuration_values
+        specified_entries.to_h do |entry|
+          value = entry.value || raise("explicit parser contract entry is missing its value")
+          [DEFINITIONS.fetch(entry.key).fetch(:configuration), value]
+        end
+      end
+
+      # Source locations supplied to the typed resolver.
+      # @rbs () -> Hash[String, Location]
+      def configuration_locations
+        specified_entries.to_h do |entry|
+          location = entry.location || raise("explicit parser contract entry is missing its location")
+          [DEFINITIONS.fetch(entry.key).fetch(:configuration), location]
+        end
+      end
+
+      private
+
+      # @rbs (Symbol key, Entry? entry) -> Entry
+      def normalize_entry(key, entry)
+        entry ||= Entry.new(key)
+        raise ArgumentError, "#{key} must be a ParserContract::Entry" unless entry.is_a?(Entry)
+        raise ArgumentError, "#{key} entry has key #{entry.key.inspect}" unless entry.key == key
+
+        entry
+      end
+
+      # @rbs () -> Array[Entry]
+      def specified_entries
+        [@algorithm, @entries, @cst_trivia].select(&:explicit)
+      end
+    end
+  end
+end

data/lib/ibex/ir/serialize.rb

@@ -4,38 +4,83 @@ require "json"
 
 module Ibex
   module IR
-    # Stable JSON serialization for versioned pipeline IR.
+    # Stable JSON serialization for the current pipeline IR.
+    # rubocop:disable Metrics/ModuleLength -- explicit fields keep serialization changes auditable.
+    # rubocop:disable Lint/SelfAssignment -- RBS inline assertions narrow schema-decoded values in place.
     module Serialize
       # @rbs!
-      #   private def validate_version: (untyped data) -> untyped
-      #   private def self.validate_version: (untyped data) -> untyped
-      #   private def load_grammar: (untyped data) -> untyped
-      #   private def self.load_grammar: (untyped data) -> untyped
-      #   private def load_automaton: (untyped data) -> untyped
-      #   private def self.load_automaton: (untyped data) -> untyped
-      #   private def load_state: (untyped state, untyped grammar) -> untyped
-      #   private def self.load_state: (untyped state, untyped grammar) -> untyped
-      #   private def symbol_keyed: (untyped values, untyped grammar, ?actions: untyped) -> untyped
-      #   private def self.symbol_keyed: (untyped values, untyped grammar, ?actions: untyped) -> untyped
-      #   private def normalize_action: (untyped value) -> untyped
-      #   private def self.normalize_action: (untyped value) -> untyped
-      #   private def load_production: (untyped production) -> untyped
-      #   private def self.load_production: (untyped production) -> untyped
-      #   private def load_user_code_chunks: (untyped chunks) -> untyped
-      #   private def self.load_user_code_chunks: (untyped chunks) -> untyped
-      #   private def symbolize: (untyped value) -> untyped
-      #   private def self.symbolize: (untyped value) -> untyped
-
-      # @rbs (Grammar | Automaton value) -> String
+      #   private def validate_version: (Hash[String, IR::serialized_value] data) -> void
+      #   private def self.validate_version: (Hash[String, IR::serialized_value] data) -> void
+      #   private def load_grammar: (Hash[String, IR::serialized_value] data) -> Grammar
+      #   private def self.load_grammar: (Hash[String, IR::serialized_value] data) -> Grammar
+      #   private def load_symbols: (Hash[String, IR::serialized_value] data) -> Array[GrammarSymbol]
+      #   private def self.load_symbols: (Hash[String, IR::serialized_value] data) -> Array[GrammarSymbol]
+      #   private def load_productions: (Hash[String, IR::serialized_value] data) -> Array[Production]
+      #   private def self.load_productions: (Hash[String, IR::serialized_value] data) -> Array[Production]
+      #   private def empty_chunks: () -> Hash[String, IR::serialized_value]
+      #   private def self.empty_chunks: () -> Hash[String, IR::serialized_value]
+      #   private def empty_parameters: () -> Array[IR::serialized_value]
+      #   private def self.empty_parameters: () -> Array[IR::serialized_value]
+      #   private def empty_printers: () -> Array[IR::serialized_value]
+      #   private def self.empty_printers: () -> Array[IR::serialized_value]
+      #   private def empty_tests: () -> Array[IR::serialized_value]
+      #   private def self.empty_tests: () -> Array[IR::serialized_value]
+      #   private def empty_recovery: () -> Hash[String, IR::serialized_value]
+      #   private def self.empty_recovery: () -> Hash[String, IR::serialized_value]
+      #   private def load_automaton: (Hash[String, IR::serialized_value] data) -> Automaton
+      #   private def self.load_automaton: (Hash[String, IR::serialized_value] data) -> Automaton
+      #   private def load_lexer: (Hash[String, IR::serialized_value] data) -> Lexer
+      #   private def self.load_lexer: (Hash[String, IR::serialized_value] data) -> Lexer
+      #   private def load_state: (Hash[String, IR::serialized_value] state, Grammar grammar) -> AutomatonState
+      #   private def self.load_state: (Hash[String, IR::serialized_value] state, Grammar grammar) -> AutomatonState
+      #   private def symbol_keyed: (Hash[String, IR::serialized_value] values, Grammar grammar,
+      #     ?actions: bool) -> Hash[Integer, IR::serialized_value]
+      #   private def self.symbol_keyed: (Hash[String, IR::serialized_value] values, Grammar grammar,
+      #     ?actions: bool) -> Hash[Integer, IR::serialized_value]
+      #   private def normalize_action: (Hash[String, IR::serialized_value] value) -> parser_action?
+      #   private def self.normalize_action: (Hash[String, IR::serialized_value] value) -> parser_action?
+      #   private def load_production: (Hash[String, IR::serialized_value] production) -> Production
+      #   private def self.load_production: (Hash[String, IR::serialized_value] production) -> Production
+      #   private def load_user_code_chunks: (Hash[String,
+      #     Array[Hash[String, IR::serialized_value]]] chunks) -> user_code_chunks
+      #   private def self.load_user_code_chunks: (Hash[String,
+      #     Array[Hash[String, IR::serialized_value]]] chunks) -> user_code_chunks
+      #   private def load_symbol_metadata: (Hash[String, IR::serialized_value] symbol, String field) -> String?
+      #   private def self.load_symbol_metadata: (Hash[String, IR::serialized_value] symbol, String field) -> String?
+      #   private def load_grammar_tests: (Array[Hash[String, IR::serialized_value]] tests) -> Array[grammar_test]
+      #   private def self.load_grammar_tests: (Array[Hash[String, IR::serialized_value]] tests) -> Array[grammar_test]
+      #   private def symbol_source_position: (Hash[String, IR::serialized_value] symbol) -> String
+      #   private def self.symbol_source_position: (Hash[String, IR::serialized_value] symbol) -> String
+      #   private def load_parser_contract: (IR::serialized_value value) -> IR::serialized_value
+      #   private def self.load_parser_contract: (IR::serialized_value value) -> IR::serialized_value
+      #   private def symbolize: (IR::serialized_value value) -> IR::serialized_value
+      #   private def self.symbolize: (IR::serialized_value value) -> IR::serialized_value
+
+      # @rbs (Grammar | Automaton | Lexer value) -> String
       def dump(value)
-        "#{JSON.pretty_generate(value.to_h)}\n"
+        normalize = lambda do |entry|
+          case entry
+          when String
+            normalized = entry.dup.force_encoding(Encoding::UTF_8)
+            normalized.valid_encoding? ? normalized : normalized.scrub
+          when Array
+            entry.map { |child| normalize.call(child) }
+          when Hash
+            entry.to_h { |key, child| [normalize.call(key), normalize.call(child)] }
+          else
+            entry
+          end
+        end
+        "#{JSON.pretty_generate(normalize.call(value.to_h))}\n"
       end
       module_function :dump
 
-      # @rbs (String source) -> (Grammar | Automaton)
+      # @rbs (String source) -> (Grammar | Automaton | Lexer)
       def load(source)
-        data = JSON.parse(source)
-        type = data.fetch("ibex_ir") { raise Ibex::Error, "(ir):1:1: missing ibex_ir discriminator" }
+        data = JSON.parse(source) #: Hash[String, IR::serialized_value]
+        type = data.fetch("ibex_ir") #: String
+        return load_lexer(data) if type == "lexer"
+
         validate_version(data)
         return load_grammar(data) if type == "grammar"
         return load_automaton(data) if type == "automaton"
@@ -46,45 +91,140 @@ module Ibex
       end
       module_function :load
 
-      # @rbs skip
       private
 
       # @rbs skip
       def validate_version(data)
         version = data["schema_version"]
-        return if version == SCHEMA_VERSION
+        return if SUPPORTED_SCHEMA_VERSIONS.include?(version)
 
-        raise Ibex::Error, "(ir):1:1: unsupported schema_version #{version.inspect}; expected #{SCHEMA_VERSION}"
+        expected = SUPPORTED_SCHEMA_VERSIONS.join(", ")
+        raise Ibex::Error,
+              "(ir):1:1: unsupported schema_version #{version.inspect}; expected the current format (#{expected})"
       end
 
+      # rubocop:disable Metrics/AbcSize -- explicit current Grammar IR field mapping is the loader contract.
       # @rbs skip
       def load_grammar(data)
-        empty_chunks = {} #: Hash[String, untyped]
-        symbols = data.fetch("symbols").map do |symbol|
+        data = data #: Hash[String, IR::serialized_value]
+        data.fetch("schema_version") #: Integer
+        Grammar.new(
+          class_name: data.fetch("class_name"), superclass: data["superclass"], start: data.fetch("start"),
+          expect: data.fetch("expect"), options: symbolize(data.fetch("options")), symbols: load_symbols(data),
+          mode: (data["mode"] || "default").to_sym, starts: data["starts"], expect_rr: data["expect_rr"],
+          parser_parameters: symbolize(data.fetch("params", empty_parameters)),
+          value_printers: symbolize(data.fetch("printers", empty_printers)),
+          grammar_tests: load_grammar_tests(data.fetch("tests", empty_tests)),
+          lexer: data["lexer"] && load_lexer(data.fetch("lexer")),
+          recovery: symbolize(data.fetch("recovery", empty_recovery)),
+          productions: load_productions(data),
+          user_code: data.fetch("user_code"), conversions: data.fetch("conversions"),
+          warnings: symbolize(data.fetch("warnings")),
+          user_code_chunks: load_user_code_chunks(data.fetch("user_code_chunks", empty_chunks)),
+          source_provenance: symbolize(data["source_provenance"]),
+          parser_contract: load_parser_contract(data.fetch("parser_contract"))
+        )
+      end
+      # rubocop:enable Metrics/AbcSize
+
+      # @rbs skip
+      def load_symbols(data)
+        symbols_data = data.fetch("symbols") #: Array[Hash[String, IR::serialized_value]]
+        symbols_data.map do |symbol|
           GrammarSymbol.new(id: symbol.fetch("id"), name: symbol.fetch("name"), kind: symbol.fetch("kind"),
                             reserved: symbol.fetch("reserved"), precedence: symbolize(symbol["prec"]),
-                            location: symbolize(symbol["loc"]))
+                            location: symbolize(symbol["loc"]),
+                            display_name: load_symbol_metadata(symbol, "display_name"),
+                            semantic_type: load_symbol_metadata(symbol, "semantic_type"),
+                            documentation: symbol["doc"])
         end
-        productions = data.fetch("productions").map { |production| load_production(production) }
-        Grammar.new(class_name: data.fetch("class_name"), superclass: data["superclass"], start: data.fetch("start"),
-                    expect: data.fetch("expect"), options: symbolize(data.fetch("options")), symbols: symbols,
-                    productions: productions, user_code: data.fetch("user_code"),
-                    conversions: data.fetch("conversions"), warnings: symbolize(data.fetch("warnings")),
-                    user_code_chunks: load_user_code_chunks(data.fetch("user_code_chunks", empty_chunks)))
+      end
+
+      # @rbs skip
+      def load_productions(data)
+        productions_data = data.fetch("productions") #: Array[Hash[String, IR::serialized_value]]
+        productions_data.map { |production| load_production(production) }
+      end
+
+      # @rbs skip
+      def empty_chunks
+        value = {} #: Hash[String, IR::serialized_value]
+        value.freeze
+      end
+
+      # @rbs skip
+      def empty_parameters
+        value = [] #: Array[IR::serialized_value]
+        value.freeze
+      end
+
+      # @rbs skip
+      def empty_printers
+        value = [] #: Array[IR::serialized_value]
+        value.freeze
+      end
+
+      # @rbs skip
+      def empty_tests
+        value = [] #: Array[IR::serialized_value]
+        value.freeze
+      end
+
+      # @rbs skip
+      def empty_recovery
+        value = { "sync_tokens" => [], "on_error_reduce" => [] } #: Hash[String, IR::serialized_value]
+        value.freeze
       end
 
       # @rbs skip
       def load_automaton(data)
-        grammar = load_grammar(data.fetch("grammar"))
-        states = data.fetch("states").map { |state| load_state(state, grammar) }
-        Automaton.new(grammar: grammar, states: states, conflict_summary: symbolize(data.fetch("conflict_summary")),
-                      algorithm: data.fetch("algorithm"), grammar_digest: data.fetch("grammar_digest"))
+        data = data #: Hash[String, IR::serialized_value]
+        grammar_data = data.fetch("grammar") #: Hash[String, IR::serialized_value]
+        grammar = load_grammar(grammar_data)
+        states_data = data.fetch("states") #: Array[Hash[String, IR::serialized_value]]
+        states = states_data.map { |state| load_state(state, grammar) }
+        data.fetch("schema_version") #: Integer
+        Automaton.new(
+          grammar: grammar, states: states, conflict_summary: symbolize(data.fetch("conflict_summary")),
+          algorithm: data.fetch("algorithm"), grammar_digest: data.fetch("grammar_digest"),
+          entry_states: data["entry_states"], entry_construction: data.fetch("entry_construction")
+        )
+      end
+
+      # @rbs skip
+      def load_lexer(data)
+        data = data #: Hash[String, IR::serialized_value]
+        version = data.fetch("schema_version") #: Integer
+        unless SUPPORTED_LEXER_SCHEMA_VERSIONS.include?(version)
+          expected = SUPPORTED_LEXER_SCHEMA_VERSIONS.join(", ")
+          raise Ibex::Error,
+                "(ir):1:1: unsupported lexer schema_version #{version.inspect}; " \
+                "expected the current lexer format (#{expected})"
+        end
+        rules_data = data.fetch("rules") #: Array[Hash[String, IR::serialized_value]]
+        rules = rules_data.map do |rule|
+          LexerRule.new(
+            id: rule.fetch("id"), state: rule.fetch("state"), kind: rule.fetch("kind").to_sym,
+            token: rule["token"], pattern: rule.fetch("pattern"), pattern_kind: rule.fetch("pattern_kind").to_sym,
+            options: rule.fetch("options"), action: rule["action"], location: symbolize(rule.fetch("loc"))
+          )
+        end
+        Lexer.new(
+          states: data.fetch("states"), rules: rules, warnings: symbolize(data.fetch("warnings")),
+          schema_version: version, source_provenance: symbolize(data["source_provenance"])
+        )
       end
 
       # @rbs skip
       def load_state(state, grammar)
-        items = state.fetch("items").map do |item|
-          lookaheads = item.fetch("lookaheads").map { |name| grammar.symbol(name).id }
+        state = state #: Hash[String, IR::serialized_value]
+        items_data = state.fetch("items") #: Array[Hash[String, IR::serialized_value]]
+        items = items_data.map do |item|
+          lookahead_names = item.fetch("lookaheads") #: Array[String]
+          lookaheads = lookahead_names.map do |name|
+            symbol = grammar.symbol(name) || raise(Ibex::Error, "(ir):1:1: unknown symbol #{name.inspect}")
+            symbol.id
+          end
           AutomatonItem.new(production: item.fetch("production"), dot: item.fetch("dot"), lookaheads: lookaheads)
         end
         AutomatonState.new(id: state.fetch("id"), items: items,
@@ -97,13 +237,16 @@ module Ibex
 
       # @rbs skip
       def symbol_keyed(values, grammar, actions: false)
+        values = values #: Hash[String, IR::serialized_value]
         values.to_h do |name, value|
-          [grammar.symbol(name).id, actions ? normalize_action(value) : value]
+          symbol = grammar.symbol(name) || raise(Ibex::Error, "(ir):1:1: unknown symbol #{name.inspect}")
+          [symbol.id, actions ? normalize_action(value) : value]
         end
       end
 
       # @rbs skip
       def normalize_action(value)
+        value = value #: IR::serialized_value
         return nil unless value
 
         action = symbolize(value)
@@ -113,19 +256,24 @@ module Ibex
 
       # @rbs skip
       def load_production(production)
+        production = production #: Hash[String, IR::serialized_value]
         action_data = production["action"]
+        action_data = action_data #: Hash[String, IR::serialized_value] if action_data
         action = if action_data
                    Action.new(code: action_data.fetch("code"), location: symbolize(action_data["loc"]),
                               named_refs: symbolize(action_data.fetch("named_refs")),
-                              context_length: action_data.fetch("context_length"))
+                              context_length: action_data.fetch("context_length"),
+                              composition: symbolize(action_data["composition"]))
                  end
         Production.new(id: production.fetch("id"), lhs: production.fetch("lhs"), rhs: production.fetch("rhs"),
                        action: action, precedence_override: production["prec_override"],
-                       origin: symbolize(production.fetch("origin")))
+                       origin: symbolize(production.fetch("origin")), documentation: production["doc"],
+                       expansion: symbolize(production["expansion"]), node: symbolize(production["node"]))
       end
 
       # @rbs skip
       def load_user_code_chunks(chunks)
+        chunks = chunks #: Hash[String, Array[Hash[String, IR::serialized_value]]]
         chunks.to_h do |name, values|
           loaded = values.map do |value|
             UserCodeChunk.new(code: value.fetch("code"), location: symbolize(value.fetch("loc")))
@@ -134,21 +282,91 @@ module Ibex
         end
       end
 
+      # @rbs skip
+      def load_symbol_metadata(symbol, field)
+        symbol = symbol #: Hash[String, IR::serialized_value]
+        value = symbol[field]
+        return nil if value.nil?
+
+        position = symbol_source_position(symbol)
+        raise Ibex::Error, "#{position}: #{field} must be a String or null" unless value.is_a?(String)
+        raise Ibex::Error, "#{position}: #{field} must not be empty" if value.strip.empty?
+        raise Ibex::Error, "#{position}: #{field} must be a single line" if value.match?(/[\r\n]/)
+        raise Ibex::Error, "#{position}: #{field} must not contain control characters" if
+          value.match?(/[[:cntrl:]]/)
+
+        value
+      end
+
+      # @rbs skip
+      def symbol_source_position(symbol)
+        location = symbol["loc"]
+        return "(ir):1:1" unless location.is_a?(Hash)
+
+        file = location["file"]
+        line = location["line"]
+        column = location["column"]
+        return "(ir):1:1" unless file.is_a?(String) && line.is_a?(Integer) && column.is_a?(Integer)
+
+        "#{file}:#{line}:#{column}"
+      end
+
+      # @rbs skip
+      def load_grammar_tests(tests)
+        tests = tests #: Array[IR::serialized_value]
+        symbolize(tests).map { |test| test.merge(expectation: test.fetch(:expectation).to_sym) }
+      end
+
+      # @rbs skip
+      def load_parser_contract(value)
+        value = value #: Hash[String, IR::serialized_value]
+
+        entries = ParserContract::DEFINITIONS.keys.to_h do |key|
+          entry = value.fetch(key.to_s)
+          location = entry["loc"]
+          loaded_location = if location
+                              Location.new(
+                                file: location.fetch("file"), line: location.fetch("line"),
+                                column: location.fetch("column")
+                              )
+                            end
+          [
+            key,
+            ParserContract::Entry.new(
+              key, value: entry["value"]&.to_sym, explicit: entry.fetch("explicit"), location: loaded_location
+            )
+          ]
+        end
+        ParserContract.new(**entries)
+      end
+
+      # Parsed IR values are recursively heterogeneous until schema validation narrows them.
       # @rbs skip
       def symbolize(value)
+        value = value #: IR::serialized_value
         case value
         when Array then value.map { |item| symbolize(item) }
         when Hash then value.to_h { |key, item| [key.to_sym, symbolize(item)] }
         else value
         end
       end
-      module_function :validate_version, :load_grammar, :load_automaton, :load_state, :symbol_keyed,
-                      :normalize_action, :load_production, :load_user_code_chunks, :symbolize
+      module_function :validate_version, :load_grammar, :load_symbols, :load_productions,
+                      :empty_chunks, :empty_parameters, :empty_printers, :empty_tests, :empty_recovery,
+                      :load_automaton, :load_lexer, :load_state, :symbol_keyed,
+                      :normalize_action, :load_production, :load_user_code_chunks, :load_symbol_metadata,
+                      :symbol_source_position, :load_grammar_tests,
+                      :load_parser_contract, :symbolize
 
       class << self
-        private :validate_version, :load_grammar, :load_automaton, :load_state, :symbol_keyed,
-                :normalize_action, :load_production, :load_user_code_chunks, :symbolize
+        private :validate_version, :load_grammar, :load_symbols, :load_productions,
+                :empty_chunks, :empty_parameters, :empty_printers, :empty_tests, :empty_recovery,
+                :load_automaton, :load_lexer, :load_state, :symbol_keyed,
+                :normalize_action, :load_production, :load_user_code_chunks, :load_symbol_metadata,
+                :symbol_source_position, :load_grammar_tests,
+                :load_parser_contract, :symbolize
       end
     end
+    # rubocop:enable Lint/SelfAssignment
+    # rubocop:enable Metrics/ModuleLength
   end
 end