ibex 0.2.0 → 0.3.0

data/sig/ibex/codegen/action_method_source.rbs

@@ -11,8 +11,8 @@ module Ibex
       # @rbs (IR::Grammar grammar, ?generated_action_abi: GeneratedActionABI::Cache?) -> void
       def initialize: (IR::Grammar grammar, ?generated_action_abi: GeneratedActionABI::Cache?) -> void
 
-      # @rbs (IR::Production production, Hash[Symbol, untyped] step, Integer index) -> String
-      def composed_fragment_method_source: (IR::Production production, Hash[Symbol, untyped] step, Integer index) -> String
+      # @rbs (IR::Production production, IR::action_composition_step step, Integer index) -> String
+      def composed_fragment_method_source: (IR::Production production, IR::action_composition_step step, Integer index) -> String
 
       # @rbs (IR::Production production, Integer index) -> String
       def composed_fragment_name: (IR::Production production, Integer index) -> String
@@ -43,8 +43,8 @@ module Ibex
       # @rbs (Array[String] lines, production: IR::Production) -> void
       def append_direct_parameter_values: (Array[String] lines, production: IR::Production) -> void
 
-      # @rbs (Hash[Symbol, untyped] step) -> String
-      def composed_semantic_code: (Hash[Symbol, untyped] step) -> String
+      # @rbs (IR::action_composition_step step) -> String
+      def composed_semantic_code: (IR::action_composition_step step) -> String
 
       # @rbs (String source, Array[IR::named_ref] named_refs) -> void
       def append_named_values: (String source, Array[IR::named_ref] named_refs) -> void

data/sig/ibex/codegen/explain.rbs

@@ -4,7 +4,21 @@ module Ibex
   module Codegen
     type explain_selection = { state: IR::AutomatonState, conflict: IR::conflict, conflict_index: Integer }
 
-    type explain_entry = { state: IR::AutomatonState, conflict: IR::conflict, example: IR::counterexample }
+    type explain_entry = { state: IR::AutomatonState, conflict: IR::conflict, example: LALR::search_counterexample }
+
+    type explain_token = { name: String, display_name: String?, label: String, ?query: String }
+
+    type explain_alternative = { kind: String, ?state: Integer, ?production: Integer }
+
+    type explain_search = { status: String, explored: Integer, exhausted: bool, bounds: Hash[Symbol, Integer] }
+
+    type explain_tree_node = { ?symbol: explain_token, ?token: explain_token, ?production: Integer, ?children: Array[explain_tree] }
+
+    type explain_tree = untyped
+
+    type explain_interpretation = Hash[Symbol, untyped]
+
+    type string_value = String | Integer | Symbol
 
     # Renders a selected conflict explanation from Automaton IR and counterexamples.
     # rubocop:disable Metrics/ClassLength -- inline contracts and two stable output formats stay near selection policy.
@@ -15,8 +29,8 @@ module Ibex
       #   ?max_configurations: Integer) -> void
       def initialize: (IR::Automaton automaton, ?state: Integer?, ?token: String?, ?max_tokens: Integer, ?max_configurations: Integer) -> void
 
-      # @rbs () -> Hash[Symbol, untyped]
-      def to_h: () -> Hash[Symbol, untyped]
+      # @rbs () -> Hash[Symbol, Object?]
+      def to_h: () -> Hash[Symbol, Object?]
 
       # @rbs () -> String
       def render_text: () -> String
@@ -35,26 +49,32 @@ module Ibex
       # @rbs () -> Array[explain_selection]
       def selected_conflicts: () -> Array[explain_selection]
 
-      # @rbs (explain_entry entry) -> Hash[Symbol, untyped]
-      def conflict_document: (explain_entry entry) -> Hash[Symbol, untyped]
+      # @rbs (explain_entry entry) -> Hash[Symbol, Object?]
+      def conflict_document: (explain_entry entry) -> Hash[Symbol, Object?]
+
+      # @rbs (LALR::search_counterexample example) -> String
+      def witness_kind: (LALR::search_counterexample example) -> String
+
+      # @rbs (LALR::search_outcome outcome) -> explain_search
+      def search_document: (LALR::search_outcome outcome) -> explain_search
 
-      # @rbs (IR::conflict conflict) -> Array[Hash[Symbol, untyped]]
-      def conflict_alternatives: (IR::conflict conflict) -> Array[Hash[Symbol, untyped]]
+      # @rbs (IR::conflict conflict) -> Array[explain_alternative]
+      def conflict_alternatives: (IR::conflict conflict) -> Array[explain_alternative]
 
-      # @rbs (IR::interpretation interpretation) -> Hash[Symbol, untyped]
-      def interpretation_document: (IR::interpretation interpretation) -> Hash[Symbol, untyped]
+      # @rbs (IR::interpretation interpretation) -> explain_interpretation
+      def interpretation_document: (IR::interpretation interpretation) -> explain_interpretation
 
-      # @rbs (untyped tree) -> untyped
-      def tree_document: (untyped tree) -> untyped
+      # @rbs (explain_tree tree) -> explain_tree
+      def tree_document: (explain_tree tree) -> explain_tree
 
-      # @rbs (Hash[Symbol, untyped] value) -> Hash[Symbol, untyped]
-      def string_values: (Hash[Symbol, untyped] value) -> Hash[Symbol, untyped]
+      # @rbs (Hash[Symbol, string_value] value) -> Hash[Symbol, string_value]
+      def string_values: (Hash[Symbol, string_value] value) -> Hash[Symbol, string_value]
 
-      # @rbs (String name) -> Hash[Symbol, untyped]
-      def symbol_reference: (String name) -> Hash[Symbol, untyped]
+      # @rbs (String name) -> explain_token
+      def symbol_reference: (String name) -> explain_token
 
-      # @rbs (IR::GrammarSymbol symbol, ?query: String?) -> Hash[Symbol, untyped]
-      def token_reference: (IR::GrammarSymbol symbol, ?query: String?) -> Hash[Symbol, untyped]
+      # @rbs (IR::GrammarSymbol symbol, ?query: String?) -> explain_token
+      def token_reference: (IR::GrammarSymbol symbol, ?query: String?) -> explain_token
 
       # @rbs (Array[String] lines, explain_entry entry, Integer number) -> void
       def append_conflict: (Array[String] lines, explain_entry entry, Integer number) -> void
@@ -63,17 +83,17 @@ module Ibex
       def append_midrule_origins: (Array[String] lines, IR::conflict conflict) -> void
 
       # @rbs (Array[String] lines, IR::AutomatonState state, IR::conflict conflict,
-      #   IR::counterexample example) -> void
-      def append_witness_steps: (Array[String] lines, IR::AutomatonState state, IR::conflict conflict, IR::counterexample example) -> void
+      #   LALR::search_counterexample example) -> void
+      def append_witness_steps: (Array[String] lines, IR::AutomatonState state, IR::conflict conflict, LALR::search_counterexample example) -> void
 
-      # @rbs (Array[String] lines, IR::counterexample example) -> void
-      def append_interpretations: (Array[String] lines, IR::counterexample example) -> void
+      # @rbs (Array[String] lines, LALR::search_counterexample example) -> void
+      def append_interpretations: (Array[String] lines, LALR::search_counterexample example) -> void
 
-      # @rbs (Hash[Symbol, untyped] alternative) -> String
-      def alternative_text: (Hash[Symbol, untyped] alternative) -> String
+      # @rbs (explain_alternative alternative) -> String
+      def alternative_text: (explain_alternative alternative) -> String
 
-      # @rbs (Array[String] lines, untyped tree, String prefix, String connector) -> void
-      def append_tree: (Array[String] lines, untyped tree, String prefix, String connector) -> void
+      # @rbs (Array[String] lines, explain_tree tree, String prefix, String connector) -> void
+      def append_tree: (Array[String] lines, explain_tree tree, String prefix, String connector) -> void
 
       # @rbs (IR::GrammarSymbol symbol, ?query: String?) -> String
       def token_label: (IR::GrammarSymbol symbol, ?query: String?) -> String

data/sig/ibex/codegen/generated_action_abi.rbs

@@ -6,6 +6,10 @@ module Ibex
     # action's declared inputs.
     # rubocop:disable Metrics/ModuleLength -- ABI proof and source rewriting must evolve together.
     module GeneratedActionABI
+      type ripper_token = [ [ Integer, Integer ], Symbol, String, Integer ]
+
+      type sexp_value = Symbol | String | Integer | nil | Array[sexp_value]
+
       LEGACY_PARAMETERS: Array[String]
 
       SIMPLE_POSITIONAL_READ: Regexp
@@ -76,26 +80,26 @@ module Ibex
       # @rbs (String source, Array[String] parameters) -> String?
       def self?.simple_indexed_positional_action_source: (String source, Array[String] parameters) -> String?
 
-      # @rbs (Array[untyped] tokens, Array[String] parameters) -> String?
-      def self?.rewrite_positional_values: (Array[untyped] tokens, Array[String] parameters) -> String?
+      # @rbs (Array[ripper_token] tokens, Array[String] parameters) -> String?
+      def self?.rewrite_positional_values: (Array[ripper_token] tokens, Array[String] parameters) -> String?
 
-      # @rbs (Array[untyped] tokens, Integer index, Array[String] parameters) -> [String, Integer]?
-      def self?.positional_value_reference: (Array[untyped] tokens, Integer index, Array[String] parameters) -> [ String, Integer ]?
+      # @rbs (Array[ripper_token] tokens, Integer index, Array[String] parameters) -> [String, Integer]?
+      def self?.positional_value_reference: (Array[ripper_token] tokens, Integer index, Array[String] parameters) -> [ String, Integer ]?
 
-      # @rbs (Array[untyped] tokens, Integer index) -> bool
-      def self?.receiver_before_value?: (Array[untyped] tokens, Integer index) -> bool
+      # @rbs (Array[ripper_token] tokens, Integer index) -> bool
+      def self?.receiver_before_value?: (Array[ripper_token] tokens, Integer index) -> bool
 
       # @rbs (String source) -> bool
       def self?.references_legacy_parameter?: (String source) -> bool
 
-      # @rbs (untyped node, ?untyped parent, ?Integer? child_index) -> bool
-      def self?.read_only_value_references?: (untyped node, ?untyped parent, ?Integer? child_index) -> bool
+      # @rbs (sexp_value node, ?sexp_value parent, ?Integer? child_index) -> bool
+      def self?.read_only_value_references?: (sexp_value node, ?sexp_value parent, ?Integer? child_index) -> bool
 
       # @rbs (untyped node) -> bool
       def self?.value_reference?: (untyped node) -> bool
 
-      # @rbs (untyped parent, Integer? child_index) -> bool
-      def self?.safe_value_reference?: (untyped parent, Integer? child_index) -> bool
+      # @rbs (sexp_value? parent, Integer? child_index) -> bool
+      def self?.safe_value_reference?: (sexp_value? parent, Integer? child_index) -> bool
     end
   end
 end

data/sig/ibex/codegen/rbs.rbs

@@ -5,6 +5,8 @@ module Ibex
     # Generates an RBS declaration for the public surface of a generated parser.
     # rubocop:disable Metrics/ClassLength -- one generator owns the complete parser signature.
     class RBS
+      type syntax_definition = { name: String, kind: Integer, fields: Hash[String, CSTMetadata::field_slot] }
+
       @generated_action_abi: GeneratedActionABI::Cache
 
       @omit_action_call: bool
@@ -29,20 +31,20 @@ module Ibex
       # @rbs (Array[String] lines) -> void
       def append_syntax_contract: (Array[String] lines) -> void
 
-      # @rbs () -> Hash[String, Hash[Symbol, untyped]]
-      def syntax_node_definitions: () -> Hash[String, Hash[Symbol, untyped]]
+      # @rbs () -> Hash[String, syntax_definition]
+      def syntax_node_definitions: () -> Hash[String, syntax_definition]
 
-      # @rbs (Hash[String, untyped] left, Hash[String, untyped] right) -> Hash[String, untyped]
-      def merge_syntax_fields: (Hash[String, untyped] left, Hash[String, untyped] right) -> Hash[String, untyped]
+      # @rbs (Hash[String, CSTMetadata::field_slot] left, Hash[String, CSTMetadata::field_slot] right) -> Hash[String, CSTMetadata::field_slot]
+      def merge_syntax_fields: (Hash[String, CSTMetadata::field_slot] left, Hash[String, CSTMetadata::field_slot] right) -> Hash[String, CSTMetadata::field_slot]
 
-      # @rbs (Array[String] lines, Hash[Symbol, untyped] definition) -> void
-      def append_syntax_node_contract: (Array[String] lines, Hash[Symbol, untyped] definition) -> void
+      # @rbs (Array[String] lines, syntax_definition definition) -> void
+      def append_syntax_node_contract: (Array[String] lines, syntax_definition definition) -> void
 
       # @rbs (String node_name, Integer index) -> String
       def syntax_field_type: (String node_name, Integer index) -> String
 
-      # @rbs (Array[String] lines, Hash[String, untyped] fields) -> void
-      def append_repetition_contracts: (Array[String] lines, Hash[String, untyped] fields) -> void
+      # @rbs (Array[String] lines, Hash[String, CSTMetadata::field_slot] fields) -> void
+      def append_repetition_contracts: (Array[String] lines, Hash[String, CSTMetadata::field_slot] fields) -> void
 
       # @rbs () -> Hash[String, IR::node_annotation]
       def ast_node_definitions: () -> Hash[String, IR::node_annotation]
@@ -86,8 +88,8 @@ module Ibex
       # @rbs (Array[String] lines, IR::Production production) -> void
       def append_composed_fragment_signatures: (Array[String] lines, IR::Production production) -> void
 
-      # @rbs (IR::Production production, Hash[Symbol, untyped] plan, Integer slot, Integer step_index) -> String
-      def composition_slot_type: (IR::Production production, Hash[Symbol, untyped] plan, Integer slot, Integer step_index) -> String
+      # @rbs (IR::Production production, IR::action_composition_plan plan, Integer slot, Integer step_index) -> String
+      def composition_slot_type: (IR::Production production, IR::action_composition_plan plan, Integer slot, Integer step_index) -> String
 
       # @rbs (IR::Production production) -> bool
       def action_method?: (IR::Production production) -> bool

data/sig/ibex/codegen/report.rbs

@@ -4,17 +4,17 @@ module Ibex
   module Codegen
     # Renders a human-readable state and conflict report from Automaton IR.
     module Report
-      private def append_state: (Array[String] lines, IR::AutomatonState state, IR::Grammar grammar, Array[IR::counterexample] examples, Hash[Integer, String] labels) -> void
+      private def append_state: (Array[String] lines, IR::AutomatonState state, IR::Grammar grammar, Array[LALR::search_counterexample] examples, Hash[Integer, String] labels) -> void
 
-      private def self.append_state: (Array[String] lines, IR::AutomatonState state, IR::Grammar grammar, Array[IR::counterexample] examples, Hash[Integer, String] labels) -> void
+      private def self.append_state: (Array[String] lines, IR::AutomatonState state, IR::Grammar grammar, Array[LALR::search_counterexample] examples, Hash[Integer, String] labels) -> void
 
-      private def append_counterexample: (Array[String] lines, IR::counterexample example, IR::Grammar grammar, Hash[Integer, String] labels) -> void
+      private def append_counterexample: (Array[String] lines, LALR::search_counterexample example, IR::Grammar grammar, Hash[Integer, String] labels) -> void
 
-      private def self.append_counterexample: (Array[String] lines, IR::counterexample example, IR::Grammar grammar, Hash[Integer, String] labels) -> void
+      private def self.append_counterexample: (Array[String] lines, LALR::search_counterexample example, IR::Grammar grammar, Hash[Integer, String] labels) -> void
 
-      private def append_tree: (Array[String] lines, untyped tree, String indentation, IR::Grammar grammar, Hash[Integer, String] labels) -> void
+      private def append_tree: (Array[String] lines, Object? tree, String indentation, IR::Grammar grammar, Hash[Integer, String] labels) -> void
 
-      private def self.append_tree: (Array[String] lines, untyped tree, String indentation, IR::Grammar grammar, Hash[Integer, String] labels) -> void
+      private def self.append_tree: (Array[String] lines, Object? tree, String indentation, IR::Grammar grammar, Hash[Integer, String] labels) -> void
 
       private def format_item: (IR::AutomatonItem item, IR::Grammar grammar, Hash[Integer, String] labels) -> String
 
@@ -28,17 +28,17 @@ module Ibex
 
       private def self.symbol_name: (Hash[Integer, String] labels, Integer id) -> String
 
-      private def tree_label: (IR::Grammar grammar, Hash[Integer, String] labels, untyped value) -> untyped
+      private def tree_label: (IR::Grammar grammar, Hash[Integer, String] labels, Object? value) -> Object?
 
-      private def self.tree_label: (IR::Grammar grammar, Hash[Integer, String] labels, untyped value) -> untyped
+      private def self.tree_label: (IR::Grammar grammar, Hash[Integer, String] labels, Object? value) -> Object?
 
-      private def display_conflict: (IR::conflict conflict, IR::Grammar grammar, Hash[Integer, String] labels) -> Hash[Symbol, untyped]
+      private def display_conflict: (IR::conflict conflict, IR::Grammar grammar, Hash[Integer, String] labels) -> Hash[Symbol, Object?]
 
-      private def self.display_conflict: (IR::conflict conflict, IR::Grammar grammar, Hash[Integer, String] labels) -> Hash[Symbol, untyped]
+      private def self.display_conflict: (IR::conflict conflict, IR::Grammar grammar, Hash[Integer, String] labels) -> Hash[Symbol, Object?]
 
-      private def format_value: (untyped value) -> String
+      private def format_value: (Object? value) -> String
 
-      private def self.format_value: (untyped value) -> String
+      private def self.format_value: (Object? value) -> String
 
       # @rbs (IR::Automaton automaton, ?max_tokens: Integer, ?max_configurations: Integer) -> String
       def self?.render: (IR::Automaton automaton, ?max_tokens: Integer, ?max_configurations: Integer) -> String

data/sig/ibex/codegen/ruby.rbs

@@ -19,8 +19,6 @@ module Ibex
 
       include RubySyntax
 
-      EMBEDDED_RUNTIME_SOURCES: Array[String]
-
       @automaton: IR::Automaton
 
       @grammar: IR::Grammar
@@ -60,12 +58,17 @@ module Ibex
 
       private
 
+      # @rbs () -> void
+      def reject_foreign_actions: () -> void
+
+      # Kept local so the generic generator does not load the optional Bison
+      # importer and its IR validation graph.
+      # @rbs () -> String
+      def foreign_action_sentinel: () -> String
+
       # @rbs (Array[String] lines) -> void
       def append_runtime: (Array[String] lines) -> void
 
-      # @rbs (String relative_path) -> String
-      def embedded_source: (String relative_path) -> String
-
       # @rbs (Array[String] lines) -> void
       def append_tables: (Array[String] lines) -> void
 
@@ -84,20 +87,20 @@ module Ibex
       # @rbs () -> bool
       def shareable_parser_tables?: () -> bool
 
-      # @rbs () -> Hash[Symbol, untyped]
-      def cst_metadata: () -> Hash[Symbol, untyped]
+      # @rbs () -> CSTMetadata::metadata
+      def cst_metadata: () -> CSTMetadata::metadata
 
-      # @rbs (untyped value) -> String
-      def deep_frozen_literal: (untyped value) -> String
+      # @rbs (Object? value) -> String
+      def deep_frozen_literal: (Object? value) -> String
 
-      # @rbs (untyped table) -> String
-      def table_literal: (untyped table) -> String
+      # @rbs (Object? table) -> String
+      def table_literal: (Object? table) -> String
 
-      # @rbs (Array[Integer?] values) -> String
-      def packed_integers_literal: (Array[Integer?] values) -> String
+      # @rbs (Array[untyped] values) -> String
+      def packed_integers_literal: (Array[untyped] values) -> String
 
-      # @rbs (Array[Integer?] values) -> String
-      def packed_signed_integers_literal: (Array[Integer?] values) -> String
+      # @rbs (Array[untyped] values) -> String
+      def packed_signed_integers_literal: (Array[untyped] values) -> String
 
       # @rbs () -> String
       def token_ids_literal: () -> String

data/sig/ibex/codegen/ruby_actions.rbs

@@ -23,17 +23,17 @@ module Ibex
       # @rbs (Array[String] lines, IR::Production production) -> void
       def append_composed_action_method: (Array[String] lines, IR::Production production) -> void
 
-      # @rbs (Array[String] lines, IR::Production production, Hash[Symbol, untyped] step, Integer index) -> void
-      def append_composed_fragment_method: (Array[String] lines, IR::Production production, Hash[Symbol, untyped] step, Integer index) -> void
+      # @rbs (Array[String] lines, IR::Production production, IR::action_composition_step step, Integer index) -> void
+      def append_composed_fragment_method: (Array[String] lines, IR::Production production, IR::action_composition_step step, Integer index) -> void
 
       # @rbs (IR::Production production, Integer index) -> String
       def composed_fragment_name: (IR::Production production, Integer index) -> String
 
-      # @rbs (Array[String] lines, IR::Production production, Hash[Symbol, untyped] plan) -> void
-      def append_composed_orchestrator: (Array[String] lines, IR::Production production, Hash[Symbol, untyped] plan) -> void
+      # @rbs (Array[String] lines, IR::Production production, IR::action_composition_plan plan) -> void
+      def append_composed_orchestrator: (Array[String] lines, IR::Production production, IR::action_composition_plan plan) -> void
 
-      # @rbs (Array[String] lines, IR::Production production, Hash[Symbol, untyped] step, Integer index) -> void
-      def append_composed_step: (Array[String] lines, IR::Production production, Hash[Symbol, untyped] step, Integer index) -> void
+      # @rbs (Array[String] lines, IR::Production production, IR::action_composition_step step, Integer index) -> void
+      def append_composed_step: (Array[String] lines, IR::Production production, IR::action_composition_step step, Integer index) -> void
 
       # @rbs (Array[String] lines, IR::Production production) -> void
       def append_compiled_action_method: (Array[String] lines, IR::Production production) -> void

data/sig/ibex/codegen/ruby_syntax.rbs

@@ -4,22 +4,24 @@ module Ibex
   module Codegen
     # Generates typed Red syntax views from @node metadata.
     module RubySyntax
+      type syntax_definition = Hash[Symbol, untyped]
+
       private
 
       # @rbs (Array[String] lines) -> void
       def append_syntax: (Array[String] lines) -> void
 
-      # @rbs () -> Hash[String, Hash[Symbol, untyped]]
-      def syntax_node_definitions: () -> Hash[String, Hash[Symbol, untyped]]
+      # @rbs () -> Hash[String, syntax_definition]
+      def syntax_node_definitions: () -> Hash[String, syntax_definition]
 
-      # @rbs (Hash[String, untyped] left, Hash[String, untyped] right) -> Hash[String, untyped]
-      def merge_syntax_fields: (Hash[String, untyped] left, Hash[String, untyped] right) -> Hash[String, untyped]
+      # @rbs (Hash[String, CSTMetadata::field_slot] left, Hash[String, CSTMetadata::field_slot] right) -> Hash[String, CSTMetadata::field_slot]
+      def merge_syntax_fields: (Hash[String, CSTMetadata::field_slot] left, Hash[String, CSTMetadata::field_slot] right) -> Hash[String, CSTMetadata::field_slot]
 
-      # @rbs (Array[String] lines, Hash[Symbol, untyped] definition) -> void
-      def append_syntax_node: (Array[String] lines, Hash[Symbol, untyped] definition) -> void
+      # @rbs (Array[String] lines, syntax_definition definition) -> void
+      def append_syntax_node: (Array[String] lines, syntax_definition definition) -> void
 
-      # @rbs (Array[String] lines, Hash[String, untyped] fields) -> void
-      def append_repetition_accessors: (Array[String] lines, Hash[String, untyped] fields) -> void
+      # @rbs (Array[String] lines, Hash[String, CSTMetadata::field_slot] fields) -> void
+      def append_repetition_accessors: (Array[String] lines, Hash[String, CSTMetadata::field_slot] fields) -> void
     end
   end
 end

data/sig/ibex/configuration/analysis_grammar.rbs

@@ -0,0 +1,13 @@
+# Generated from lib/ibex/configuration/analysis_grammar.rb with RBS::Inline
+
+module Ibex
+  module Configuration
+    # Produces an immutable Grammar IR view suitable for an explicitly
+    # noncanonical analysis algorithm. The source-owned contract remains the
+    # authority; callers must report the override through Configuration::Value.
+    module AnalysisGrammar
+      # @rbs (IR::Grammar grammar, Symbol algorithm) -> IR::Grammar
+      def self?.for_algorithm: (IR::Grammar grammar, Symbol algorithm) -> IR::Grammar
+    end
+  end
+end

data/sig/ibex/configuration/explanation.rbs

@@ -0,0 +1,195 @@
+# Generated from lib/ibex/configuration/explanation.rb with RBS::Inline
+
+module Ibex
+  module Configuration
+    # One observed configuration source and how it participated in selection.
+    class Evidence
+      STATUSES: Array[Symbol]
+
+      SOURCES: Array[Symbol]
+
+      attr_reader key: Key
+
+      attr_reader source: Symbol
+
+      attr_reader value: config_value
+
+      attr_reader status: Symbol
+
+      attr_reader location: Location?
+
+      attr_reader reason: String
+
+      # @rbs (Key key, source: Symbol, value: config_value, status: Symbol, reason: String,
+      #   ?location: Location?) -> void
+      def initialize: (Key key, source: Symbol, value: config_value, status: Symbol, reason: String, ?location: Location?) -> void
+
+      # @rbs () -> Hash[String, json_value]
+      def to_h: () -> Hash[String, json_value]
+
+      private
+
+      # @rbs (config_value value) -> (String | Integer | bool | nil)
+      def json_value: (config_value value) -> (String | Integer | bool | nil)
+    end
+
+    # Whether an input can prove the historical source of a selected setting.
+    class Recording
+      STATES: Array[Symbol]
+
+      attr_reader state: Symbol
+
+      attr_reader reason: String
+
+      # @rbs (Symbol state, String reason) -> void
+      def initialize: (Symbol state, String reason) -> void
+
+      # @rbs () -> Hash[String, String]
+      def to_h: () -> Hash[String, String]
+    end
+
+    # Canonical, static input facts used to build a configuration report.
+    class Input
+      KINDS: Array[Symbol]
+
+      attr_reader kind: Symbol
+
+      attr_reader path: String
+
+      attr_reader files: Array[String]
+
+      attr_reader schema_version: Integer?
+
+      attr_reader grammar_values: Hash[String, config_value]
+
+      attr_reader grammar_locations: Hash[String, Location]
+
+      attr_reader evidence: Hash[String, Array[Evidence]]
+
+      attr_reader recordings: Hash[String, Recording]
+
+      # @rbs (kind: Symbol, path: String, ?files: Array[String], ?schema_version: Integer?,
+      #   ?grammar_values: Hash[String, config_value], ?grammar_locations: Hash[String, Location],
+      #   ?evidence: Hash[String, Array[Evidence]], ?recordings: Hash[String, Recording]) -> void
+      def initialize: (kind: Symbol, path: String, ?files: Array[String], ?schema_version: Integer?, ?grammar_values: Hash[String, config_value], ?grammar_locations: Hash[String, Location], ?evidence: Hash[String, Array[Evidence]], ?recordings: Hash[String, Recording]) -> void
+
+      # @rbs () -> Hash[String, json_value]
+      def to_h: () -> Hash[String, json_value]
+
+      private
+
+      # @rbs (Symbol kind, String path, Array[String] files, Integer? schema_version,
+      #   Hash[String, config_value] grammar_values, Hash[String, Location] grammar_locations,
+      #   Hash[String, Array[Evidence]] evidence, Hash[String, Recording] recordings) -> void
+      def assign_input: (Symbol kind, String path, Array[String] files, Integer? schema_version, Hash[String, config_value] grammar_values, Hash[String, Location] grammar_locations, Hash[String, Array[Evidence]] evidence, Hash[String, Recording] recordings) -> void
+
+      # @rbs (Array[String] files, String path) -> void
+      def validate_files!: (Array[String] files, String path) -> void
+
+      # @rbs (Symbol kind, Integer? schema_version) -> void
+      def validate_schema_version!: (Symbol kind, Integer? schema_version) -> void
+
+      # @rbs (Hash[String, config_value] values, Hash[String, Location] locations,
+      #   Hash[String, Array[Evidence]] evidence, Hash[String, Recording] recordings) -> void
+      def validate_entries!: (Hash[String, config_value] values, Hash[String, Location] locations, Hash[String, Array[Evidence]] evidence, Hash[String, Recording] recordings) -> void
+
+      # @rbs (*Hash[Object?, Object?] values) -> void
+      def validate_fact_hashes!: (*Hash[Object?, Object?] values) -> void
+
+      # @rbs (Hash[String, config_value] values, Hash[String, Location] locations) -> void
+      def validate_locations!: (Hash[String, config_value] values, Hash[String, Location] locations) -> void
+
+      # @rbs (Hash[String, Array[Evidence]] evidence) -> void
+      def validate_evidence!: (Hash[String, Array[Evidence]] evidence) -> void
+
+      # @rbs (Hash[String, Recording] recordings) -> void
+      def validate_recordings!: (Hash[String, Recording] recordings) -> void
+
+      # @rbs (Hash[String, config_value] values) -> Hash[String, config_value]
+      def immutable_values: (Hash[String, config_value] values) -> Hash[String, config_value]
+    end
+
+    # A fixed-contract mismatch retained as structured report data.
+    class ConflictRecord
+      attr_reader key: Key
+
+      attr_reader declared: Value
+
+      attr_reader requested: Value
+
+      # @rbs (Conflict conflict) -> void
+      def initialize: (Conflict conflict) -> void
+
+      # @rbs () -> Hash[String, json_value]
+      def to_h: () -> Hash[String, json_value]
+
+      # @rbs () -> String
+      def message: () -> String
+
+      private
+
+      # @rbs (Value value) -> Hash[String, json_value]
+      def selection: (Value value) -> Hash[String, json_value]
+    end
+
+    # The effective value and all accepted or rejected evidence for one key.
+    class Explanation
+      attr_reader value: Value
+
+      attr_reader evidence: Array[Evidence]
+
+      attr_reader recording: Recording
+
+      # @rbs (Value value, evidence: Array[Evidence], recording: Recording) -> void
+      def initialize: (Value value, evidence: Array[Evidence], recording: Recording) -> void
+
+      # @rbs () -> Hash[String, json_value]
+      def to_h: () -> Hash[String, json_value]
+    end
+
+    # Deterministic, static-no-user-code explanation of every registered setting.
+    class Report
+      attr_reader input: Input
+
+      attr_reader explanations: Array[Explanation]
+
+      attr_reader conflicts: Array[ConflictRecord]
+
+      # @rbs (Input input, ?cli: Hash[String, config_value]) -> void
+      def initialize: (Input input, ?cli: Hash[String, config_value]) -> void
+
+      # @rbs () -> bool
+      def success?: () -> bool
+
+      # @rbs () -> Hash[String, json_value]
+      def to_h: () -> Hash[String, json_value]
+
+      # Deterministic JSON independent of caller hash insertion order.
+      # @rbs () -> String
+      def dump: () -> String
+
+      # @rbs () -> String
+      def render_text: () -> String
+
+      private
+
+      # @rbs (Key key, Hash[String, config_value] cli) -> Value
+      def resolve_key: (Key key, Hash[String, config_value] cli) -> Value
+
+      # @rbs (Value value, Hash[String, config_value] cli, ?conflict: ConflictRecord?) -> Explanation
+      def explanation: (Value value, Hash[String, config_value] cli, ?conflict: ConflictRecord?) -> Explanation
+
+      # @rbs (Key key, config_value raw, conflicting: bool) -> Evidence
+      def cli_evidence: (Key key, config_value raw, conflicting: bool) -> Evidence
+
+      # @rbs (config_value value) -> String
+      def display: (config_value value) -> String
+
+      # @rbs (Location location) -> String
+      def location_label: (Location location) -> String
+
+      # @rbs (Explanation entry) -> Array[String]
+      def render_explanation: (Explanation entry) -> Array[String]
+    end
+  end
+end