ibex-runtime 0.2.0

data/sig/ibex/runtime/parser.rbs

@@ -0,0 +1,926 @@
+# Generated from lib/ibex/runtime/parser.rb with RBS::Inline
+
+module Ibex
+  module Runtime
+    # Raised by the default parser error handler.
+    class ParseError < StandardError
+      attr_reader token_id: Integer?
+
+      attr_reader token_name: String?
+
+      attr_reader token_value: untyped
+
+      attr_reader expected_tokens: Array[String]
+
+      attr_reader location: untyped
+
+      attr_reader state: Integer?
+
+      attr_reader suggestions: Array[String]
+
+      attr_reader error_id: String?
+
+      # rubocop:disable Layout/LineLength
+      # @rbs (?String? message, ?token_id: Integer?, ?token_name: String?, ?token_value: untyped, ?expected_tokens: Array[String], ?location: untyped, ?state: Integer?, ?suggestions: Array[String], ?error_id: String?, ?detail: String?) -> void
+      # rubocop:enable Layout/LineLength
+      def initialize: (?String? message, ?token_id: Integer?, ?token_name: String?, ?token_value: untyped, ?expected_tokens: Array[String], ?location: untyped, ?state: Integer?, ?suggestions: Array[String], ?error_id: String?, ?detail: String?) -> void
+
+      # @rbs () -> String
+      def location_label: () -> String
+
+      private
+
+      # @rbs () -> String
+      def diagnostic_message: () -> String
+
+      # @rbs (Symbol key) -> untyped
+      def location_value: (Symbol key) -> untyped
+    end
+
+    # Raised when a configured parser-session resource budget is exhausted.
+    class ResourceLimitError < ParseError
+      attr_reader resource: Symbol
+
+      attr_reader limit: Integer
+
+      attr_reader observed: Integer
+
+      # @rbs (resource: Symbol, limit: Integer, observed: Integer, state: Integer?, location: untyped) -> void
+      def initialize: (resource: Symbol, limit: Integer, observed: Integer, state: Integer?, location: untyped) -> void
+
+      # @rbs () -> Hash[Symbol, untyped]
+      def to_h: () -> Hash[Symbol, untyped]
+    end
+
+    # Drives a table-defined LR parser without native extensions.
+    #
+    # Subclasses provide `.parser_tables`, returning `:tokens`, `:token_names`,
+    # `:actions`, `:gotos`, and `:productions`, with optional
+    # `:default_actions`, `:error_messages`, and `:recovery_sync_tokens`.
+    # Actions are represented by
+    # `[:shift, state]`, `[:reduce, production]`, `[:accept]`, or `[:error]`.
+    # Format-v2 and newer generated production entries mark their five-argument
+    # semantic methods with `location_action: true`. Format-v3 and newer
+    # composed actions additionally use `composition_action: true` for the
+    # six-argument contract carrying the lookahead location. Format-v4
+    # location-free generated methods use `values_action: true` for a
+    # one-argument values contract. Format-v5 additionally marks proven-safe
+    # zero-to-four-value methods with `positional_action: true`. V1 and
+    # unmarked application actions retain the historical two-argument
+    # contract. Markers are honored only for the generated `_ibex_action_N`
+    # Symbol shape, never for callables.
+    class Parser
+      # Keep direct singleton-hook mutation visible even when an application
+      # replaces Ruby's mutation callbacks without calling super.
+      module FastPathMutationTracker
+        # @rbs (Ibex::Runtime::Parser parser, UnboundMethod lookup) -> bool
+        def self.effective_for?: (Ibex::Runtime::Parser parser, UnboundMethod lookup) -> bool
+
+        private
+
+        # @rbs (Symbol name) -> void
+        def singleton_method_added: (Symbol name) -> void
+
+        # @rbs (Symbol name) -> void
+        def singleton_method_removed: (Symbol name) -> void
+
+        # @rbs (Symbol name) -> void
+        def singleton_method_undefined: (Symbol name) -> void
+      end
+
+      # Invalidates the generated-class hook cache when the parser class
+      # changes its own effective hook surface.
+      module FastPathClassMutationTracker
+        # @rbs (Symbol name) -> void
+        def method_added: (Symbol name) -> void
+
+        # @rbs (Symbol name) -> void
+        def method_removed: (Symbol name) -> void
+
+        # @rbs (Symbol name) -> void
+        def method_undefined: (Symbol name) -> void
+
+        # @rbs (*Module modules) -> self
+        def include: (*Module modules) -> self
+
+        # @rbs (*Module modules) -> self
+        def prepend: (*Module modules) -> self
+
+        private
+
+        # @rbs (Symbol name) -> void
+        def __ibex_invalidate_fast_path_hooks: (Symbol name) -> void
+
+        # @rbs () -> void
+        def __ibex_bump_fast_path_hook_version: () -> void
+      end
+
+      include Observation
+
+      include ParserSyncRecovery
+
+      ParseError: singleton(Ibex::Runtime::ParseError)
+
+      EOF_TOKEN: Integer
+
+      ERROR_TOKEN: Integer
+
+      GENERATED_ACTION_NAME: Regexp
+
+      NO_LOOKAHEAD: Object
+
+      RECOVERY_SHIFTS: Integer
+
+      FAST_PATH_HOOK_NAMES: Array[Symbol]
+
+      FAST_PATH_HOOK_REFERENCES: Hash[Symbol, Symbol]
+
+      ERROR_ACTION: [ :error ]
+
+      SYNC_RECOVER_ACTION: [ :sync_recover ]
+
+      CONTINUE_OUTCOME: [ :continue ]
+
+      REPAIR_PENDING_OUTCOME: [ :repair_pending ]
+
+      TERMINAL_OUTCOMES: Array[Symbol]
+
+      COMPACT_ACCEPTED: Object
+
+      EMPTY_ROW: Hash[Integer, untyped]
+
+      EMPTY_LOCATION_NAMES: Hash[Symbol, Integer]
+
+      EMPTY_LOCATIONS: Array[untyped]
+
+      EMPTY_GREEN_TRIVIA: Array[CST::GreenTrivia]
+
+      @unknown_token_id: Integer?
+
+      @unknown_token_name: String?
+
+      @push_status: :idle | :active | :finished
+
+      @driver_status: :idle | :pull | :push
+
+      @runtime_driver_thread: Thread?
+
+      @runtime_observers: Hash[Observation::Subscription, Proc]?
+
+      @runtime_event_sequence: Integer
+
+      @runtime_lookahead_token_display: untyped
+
+      @runtime_observation_mutex: Mutex
+
+      @repair_policy: RepairPolicy?
+
+      @repair_input_buffer: Array[RepairInput]?
+
+      @repair_selected: bool
+
+      @semantic_locations: Array[untyped]?
+
+      @incremental_reused_descendants: Integer
+
+      @accept_requested: bool
+
+      @semantic_error: bool
+
+      @recovery_shifts: Integer
+
+      @lookahead_location: untyped
+
+      @lookahead_value: untyped
+
+      @lookahead: untyped
+
+      @location_stack: Array[untyped]?
+
+      @racc_vstack: Array[untyped]
+
+      @vstack: Array[untyped]
+
+      @value_stack: Array[untyped]
+
+      @state_stack: Array[Integer]
+
+      @source: untyped
+
+      @yydebug_output: IO
+
+      @yydebug: bool
+
+      @green_reused_right_edge: bool
+
+      @syntax_parse_memo: CST::ParseMemo?
+
+      @green_initial_state: Integer
+
+      @green_parse_memo_valid: bool
+
+      @green_memo_stack: Array[CST::ParseMemo::Entry]
+
+      @green_token_states: Array[Symbol]
+
+      @green_cache_override: CST::NodeCache?
+
+      @syntax_only: bool
+
+      @runtime_fast_path_singleton_ancestors: Array[Module]?
+
+      @runtime_fast_path_hooks_mutated: bool
+
+      @runtime_fast_path_tracker_installed: bool
+
+      @runtime_fast_path: bool
+
+      @runtime_parser_tables: Hash[Symbol, untyped]?
+
+      @recovery_attempts: Integer
+
+      @resource_limits: ResourceLimits
+
+      @green_pending_skipped: Array[CST::GreenTrivia]
+
+      @syntax_diagnostics: Array[untyped]
+
+      @syntax_root: CST::SyntaxNode?
+
+      @green_cache: CST::NodeCache?
+
+      @green_kinds: CST::Kind?
+
+      @green_builder: CST::GreenBuilder?
+
+      @sync_recovery_observers: Array[Proc]?
+
+      @sync_recovery_token_data: Hash[String, untyped]?
+
+      @sync_recovery_context: Hash[Symbol, untyped]?
+
+      @trace_value_printer: (^(untyped) -> untyped)?
+
+      @semantic_result_location: untyped
+
+      @semantic_location_names: Hash[Symbol, Integer]?
+
+      attr_reader syntax_parse_memo: CST::ParseMemo?
+
+      attr_reader incremental_reused_descendants: Integer
+
+      # Start a syntax-only incremental session backed by a generated lexer.
+      # @rbs (CST::SourceText source_text, ?resource_limits: ResourceLimits?, ?blender: bool) ->
+      #   CST::IncrementalParseSession
+      def self.incremental_session: (CST::SourceText source_text, ?resource_limits: ResourceLimits?, ?blender: bool) -> CST::IncrementalParseSession
+
+      # @rbs (?resource_limits: ResourceLimits) -> void
+      def initialize: (?resource_limits: ResourceLimits) -> void
+
+      # @rbs () -> bool
+      def yydebug: () -> bool
+
+      # @rbs (bool enabled) -> bool
+      def yydebug=: (bool enabled) -> bool
+
+      # @rbs (IO output) -> IO
+      def yydebug_output=: (IO output) -> IO
+
+      # @rbs () -> RepairPolicy?
+      def repair_policy: () -> RepairPolicy?
+
+      # @rbs () -> ResourceLimits
+      def resource_limits: () -> ResourceLimits
+
+      # Enable bounded automatic repair for the next parser session.
+      # Assign nil to restore the compatible yacc-only behavior.
+      # @rbs (RepairPolicy? policy) -> RepairPolicy?
+      def repair_policy=: (RepairPolicy? policy) -> RepairPolicy?
+
+      # Replace the limits used by future sessions.
+      # @rbs (ResourceLimits limits) -> ResourceLimits
+      def resource_limits=: (ResourceLimits limits) -> ResourceLimits
+
+      # Pull tokens from `next_token` and parse them.
+      # @rbs () -> untyped
+      def do_parse: () -> untyped
+
+      # Parse through `next_token` and return both the semantic value and Red root.
+      # @rbs () -> CST::ParseResult
+      def parse_with_syntax: () -> CST::ParseResult
+
+      # Return the Red source-file root built by the most recent CST parse.
+      # @rbs () -> CST::SyntaxNode?
+      def syntax_root: () -> CST::SyntaxNode?
+
+      # Parse tokens yielded by `receiver.method_id`.
+      # @rbs (untyped receiver, Symbol method_id) -> untyped
+      def yyparse: (untyped receiver, Symbol method_id) -> untyped
+
+      # Supply one token to a caller-driven parser session.
+      # Returns `:need_more` after consuming it, `[:accepted, result]` after
+      # acceptance, or `[:rejected, result]` after recovery terminates.
+      # rubocop:disable Layout/LineLength
+      # @rbs (untyped token, ?untyped value, ?untyped location) -> (:need_more | [:accepted, untyped] | [:rejected, untyped])
+      # rubocop:enable Layout/LineLength
+      def push: (untyped token, ?untyped value, ?untyped location) -> (:need_more | [ :accepted, untyped ] | [ :rejected, untyped ])
+
+      # Supply EOF to a caller-driven parser session and return its result.
+      # @rbs (?location: untyped) -> untyped
+      def finish: (?location: untyped) -> untyped
+
+      # Discard a caller-driven session so this parser can accept a new one.
+      # @rbs () -> nil
+      def reset_push: () -> nil
+
+      # Override in pull parsers. Return `[token, value]`,
+      # `[token, value, location]`, `false`, or `nil`.
+      # @rbs () -> ([untyped, untyped] | [untyped, untyped, untyped] | false | nil)
+      def next_token: () -> ([ untyped, untyped ] | [ untyped, untyped, untyped ] | false | nil)
+
+      # Override to recover from syntax errors. The default raises unless a
+      # bounded automatic repair has already been selected.
+      # @rbs (Integer token_id, untyped value, Array[untyped] value_stack) -> untyped
+      def on_error: (Integer token_id, untyped value, Array[untyped] value_stack) -> untyped
+
+      # Called after an ordinary input token is shifted. Override to observe
+      # the internal token id, semantic value, and destination state.
+      # @rbs (Integer token_id, untyped value, Integer state) -> void
+      def on_shift: (Integer token_id, untyped value, Integer state) -> void
+
+      # Location-aware shift observer. The compatible hook above retains its
+      # original signature and runs first.
+      # @rbs (Integer token_id, untyped value, Integer state, untyped location) -> void
+      def on_shift_location: (Integer token_id, untyped value, Integer state, untyped location) -> void
+
+      # Called after a production's semantic action and goto are committed.
+      # Override to observe its id, RHS values, and semantic result.
+      # @rbs (Integer production_id, Array[untyped] values, untyped result) -> void
+      def on_reduce: (Integer production_id, Array[untyped] values, untyped result) -> void
+
+      # Location-aware reduction observer.
+      # @rbs (Integer production_id, Array[untyped] values, untyped result,
+      #   Array[untyped] locations, untyped result_location) -> void
+      def on_reduce_location: (Integer production_id, Array[untyped] values, untyped result, Array[untyped] locations, untyped result_location) -> void
+
+      # Called after the synthetic error token enters a recovery state.
+      # The payload describes the original error before recovery popped stacks.
+      # @rbs (Integer token_id, untyped value, Array[untyped] value_stack) -> void
+      def on_error_recover: (Integer token_id, untyped value, Array[untyped] value_stack) -> void
+
+      # Location-aware recovery observer.
+      # @rbs (Integer token_id, untyped value, Array[untyped] value_stack,
+      #   untyped location, Integer state) -> void
+      def on_error_recover_location: (Integer token_id, untyped value, Array[untyped] value_stack, untyped location, Integer state) -> void
+
+      # Called when yacc recovery discards an application token.
+      # @rbs (Integer token_id, untyped value, untyped location, Symbol reason) -> void
+      def on_discard: (Integer token_id, untyped value, untyped location, Symbol reason) -> void
+
+      # Install an opt-in value formatter for human-readable yydebug traces.
+      # @rbs ((^(untyped) -> untyped)? printer) -> (^(untyped) -> untyped)?
+      def trace_value_printer=: ((^(untyped) -> untyped)? printer) -> (^(untyped) -> untyped)?
+
+      # Called once after a repair is selected and before its edited token
+      # prefix is replayed through normal parser actions.
+      # @rbs (RepairPlan plan) -> void
+      def on_repair: (RepairPlan plan) -> void
+
+      # Return a human-readable name for an internal token id.
+      # @rbs (Integer token_id) -> String
+      def token_to_str: (Integer token_id) -> String
+
+      # Enter error recovery from a semantic action without calling `on_error`.
+      # @rbs () -> nil
+      def yyerror: () -> nil
+
+      # Leave error recovery immediately.
+      # @rbs () -> nil
+      def yyerrok: () -> nil
+
+      # Accept immediately after the current semantic action completes.
+      # @rbs () -> nil
+      def yyaccept: () -> nil
+
+      # Return token names accepted in the current parser state.
+      # @rbs () -> Array[String]
+      def expected_tokens: () -> Array[String]
+
+      # Return token names that survive all required default reductions.
+      # Semantic actions are not evaluated during this lookahead correction.
+      # @rbs () -> Array[String]
+      def expected_tokens_exact: () -> Array[String]
+
+      # Return the location of a one-based RHS position or named reference
+      # while a semantic action is running.
+      # @rbs (Integer | Symbol | String reference) -> untyped
+      def loc: (Integer | Symbol | String reference) -> untyped
+
+      # Return the synthesized span of the reduction being evaluated.
+      # @rbs () -> untyped
+      def result_loc: () -> untyped
+
+      private
+
+      alias __ibex_fast_path_on_shift on_shift
+
+      alias __ibex_fast_path_on_shift_location on_shift_location
+
+      alias __ibex_fast_path_on_reduce on_reduce
+
+      alias __ibex_fast_path_on_reduce_location on_reduce_location
+
+      alias __ibex_fast_path_token_to_str token_to_str
+
+      # Racc-generated parsers commonly define an application initializer
+      # without calling super. Complete only missing runtime state so those
+      # initializers retain values they deliberately configured.
+      # @rbs () -> void
+      def ensure_runtime_initialized!: () -> void
+
+      # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
+      # The explicit branches keep every runtime ivar typed while preserving application-owned values.
+      # @rbs (ResourceLimits resource_limits, preserve_existing: bool) -> void
+      def initialize_runtime_state: (ResourceLimits resource_limits, preserve_existing: bool) -> void
+
+      # @rbs (ResourceLimits resource_limits) -> void
+      def validate_resource_limits!: (ResourceLimits resource_limits) -> void
+
+      # Keep the two historical value-stack names as read-compatible aliases.
+      # Applications must not mutate or replace these internal arrays.
+      # @rbs (Array[untyped] values) -> void
+      def install_value_stack: (Array[untyped] values) -> void
+
+      # @rbs (Integer token_id) -> bool
+      def exact_lookahead_accepted?: (Integer token_id) -> bool
+
+      # @rbs (Integer stack_depth) -> Integer
+      def exact_lookahead_step_budget: (Integer stack_depth) -> Integer
+
+      # @rbs (Hash[Symbol, untyped] tables) -> Integer
+      def parser_state_count: (Hash[Symbol, untyped] tables) -> Integer
+
+      # @rbs (Array[Integer] stack, Integer production_id) -> bool
+      def exact_reduction_applied?: (Array[Integer] stack, Integer production_id) -> bool
+
+      # @rbs (untyped source, ?initial_state: Integer?) -> untyped
+      def drive_parser: (untyped source, ?initial_state: Integer?) -> untyped
+
+      # Generated compact tables can keep the unobserved, location-free pull
+      # loop on their frozen displacement arrays. Any extension boundary or
+      # exceptional table shape returns control to the generic driver without
+      # replaying a committed action.
+      # rubocop:disable Metrics/AbcSize, Metrics/BlockNesting, Metrics/CyclomaticComplexity
+      # rubocop:disable Metrics/MethodLength, Metrics/PerceivedComplexity
+      # Direct comparisons avoid predicate-method dispatch inside the parser loop.
+      # rubocop:disable Style/BitwisePredicate, Style/NumericPredicate
+      # @rbs (Hash[Symbol, untyped] tables) -> (Object | [:accepted, untyped] | [:done, untyped])?
+      def drive_compact_fast_parser: (Hash[Symbol, untyped] tables) -> (Object | [ :accepted, untyped ] | [ :done, untyped ])?
+
+      # @rbs (Hash[Symbol, untyped]? tables) -> bool
+      def compact_fast_driver_eligible?: (Hash[Symbol, untyped]? tables) -> bool
+
+      # @rbs () -> void
+      def start_push_session: () -> void
+
+      # @rbs () -> (:need_more | [:accepted, untyped] | [:rejected, untyped])
+      def run_push_lookahead: () -> (:need_more | [ :accepted, untyped ] | [ :rejected, untyped ])
+
+      # @rbs () { () -> untyped } -> untyped
+      def run_push_driver: () { () -> untyped } -> untyped
+
+      # @rbs () -> void
+      def ensure_driver_available_without_lock!: () -> void
+
+      # @rbs () -> void
+      def release_driver: () -> void
+
+      # @rbs () -> void
+      def finish_push_session: () -> void
+
+      # @rbs ((^() -> untyped)? source, ?initial_state: Integer?) -> void
+      def prepare_parse: ((^() -> untyped)? source, ?initial_state: Integer?) -> void
+
+      # @rbs () -> void
+      def reset_parse_recovery_state: () -> void
+
+      # @rbs (Hash[Symbol, untyped] tables, Integer? requested) -> Integer
+      def resolve_initial_state: (Hash[Symbol, untyped] tables, Integer? requested) -> Integer
+
+      # @rbs () -> Hash[Symbol, untyped]
+      def validate_parser_table_format!: () -> Hash[Symbol, untyped]
+
+      # @rbs (Hash[Symbol, untyped] tables, Integer actual) -> void
+      def validate_current_cst_tables!: (Hash[Symbol, untyped] tables, Integer actual) -> void
+
+      # Generated parser tables are deeply frozen before they can cross a
+      # Ractor boundary. Their action-marker contract only needs one scan per
+      # parser class and exact table object, including across parser instances.
+      # Mutable application tables remain intentionally uncached.
+      # @rbs (Hash[Symbol, untyped] tables) -> bool
+      def generated_action_contracts_validated?: (Hash[Symbol, untyped] tables) -> bool
+
+      # @rbs (Hash[Symbol, untyped] tables) -> void
+      def cache_generated_action_contracts!: (Hash[Symbol, untyped] tables) -> void
+
+      # Ruby 3.0-3.3 expose the main Ractor as an object instead of exposing
+      # Ractor.main?. Class instance variables cannot be read or written from
+      # another Ractor on those versions.
+      # @rbs () -> bool
+      def generated_action_contract_cache_accessible?: () -> bool
+
+      # @rbs (Hash[Symbol, untyped] tables, Integer version) -> void
+      def validate_generated_action_contracts!: (Hash[Symbol, untyped] tables, Integer version) -> void
+
+      # @rbs (Hash[Symbol, untyped] production, Integer index, Integer version) -> void
+      def validate_composition_action_contract!: (Hash[Symbol, untyped] production, Integer index, Integer version) -> void
+
+      # @rbs (Hash[Symbol, untyped] production, Integer index, Integer version) -> void
+      def validate_values_action_contract!: (Hash[Symbol, untyped] production, Integer index, Integer version) -> void
+
+      # @rbs (Hash[Symbol, untyped] production, Integer index, Integer version) -> void
+      def validate_positional_action_contract!: (Hash[Symbol, untyped] production, Integer index, Integer version) -> void
+
+      # @rbs (Hash[Symbol, untyped] production) -> bool
+      def positional_action_contract?: (Hash[Symbol, untyped] production) -> bool
+
+      # @rbs () -> untyped
+      def action_for_current_state: () -> untyped
+
+      # @rbs (untyped action) -> untyped
+      def perform: (untyped action) -> untyped
+
+      # @rbs (Integer next_state) -> [:continue]
+      def fast_shift: (Integer next_state) -> [ :continue ]
+
+      # @rbs (Hash[Symbol, untyped] production, untyped length) -> bool
+      def fast_reduction_eligible?: (Hash[Symbol, untyped] production, untyped length) -> bool
+
+      # @rbs (Integer production_id, Hash[Symbol, untyped] production, Integer length) -> [:continue]
+      def fast_reduce: (Integer production_id, Hash[Symbol, untyped] production, Integer length) -> [ :continue ]
+
+      # @rbs (Integer production_id, Hash[Symbol, untyped] production, Integer length, Symbol action) -> untyped
+      def fast_values_reduce: (Integer production_id, Hash[Symbol, untyped] production, Integer length, Symbol action) -> untyped
+
+      # @rbs (Integer next_state) -> untyped
+      def shift: (Integer next_state) -> untyped
+
+      # @rbs (Integer production_id, ?Hash[Symbol, untyped]? prefetched_production) -> untyped
+      def reduce: (Integer production_id, ?Hash[Symbol, untyped]? prefetched_production) -> untyped
+
+      # @rbs (Integer next_state, untyped result, untyped location) -> void
+      def push_reduction_result: (Integer next_state, untyped result, untyped location) -> void
+
+      # @rbs (Integer production_id, Integer length, Integer lhs, untyped result, Integer next_state) -> void
+      def trace_reduction: (Integer production_id, Integer length, Integer lhs, untyped result, Integer next_state) -> void
+
+      # @rbs (Array[Proc]? observers, Integer production_id, Hash[Symbol, untyped] production, Integer length,
+      #   Integer? pre_state, Integer? post_state, Integer next_state, untyped result,
+      #   LocationSpan? location) -> Hash[String, untyped]?
+      def build_reduce_event_data: (Array[Proc]? observers, Integer production_id, Hash[Symbol, untyped] production, Integer length, Integer? pre_state, Integer? post_state, Integer next_state, untyped result, LocationSpan? location) -> Hash[String, untyped]?
+
+      # @rbs (Integer production_id, Hash[Symbol, untyped] production, Integer length,
+      #   Integer? pre_state, Integer? post_state, Integer next_state, untyped result,
+      #   LocationSpan? location) -> Hash[String, untyped]
+      def runtime_reduce_data: (Integer production_id, Hash[Symbol, untyped] production, Integer length, Integer? pre_state, Integer? post_state, Integer next_state, untyped result, LocationSpan? location) -> Hash[String, untyped]
+
+      # @rbs (untyped result) -> [:accepted, untyped]
+      def accept_reduction: (untyped result) -> [ :accepted, untyped ]
+
+      # @rbs (Integer production_id, Hash[Symbol, untyped] production, Array[untyped] values,
+      #   Array[untyped] locations, LocationSpan? location) -> untyped
+      def reduction_value: (Integer production_id, Hash[Symbol, untyped] production, Array[untyped] values, Array[untyped] locations, LocationSpan? location) -> untyped
+
+      # @rbs (Hash[Symbol, untyped] production, Symbol action, Array[untyped] values,
+      #   Array[untyped] locations, LocationSpan? location) -> untyped
+      def values_reduction_value: (Hash[Symbol, untyped] production, Symbol action, Array[untyped] values, Array[untyped] locations, LocationSpan? location) -> untyped
+
+      # @rbs (Integer production_id, Hash[Symbol, untyped] production, Array[untyped] values,
+      #   Array[untyped] locations, LocationSpan? location) -> untyped
+      def actionless_reduction_value: (Integer production_id, Hash[Symbol, untyped] production, Array[untyped] values, Array[untyped] locations, LocationSpan? location) -> untyped
+
+      # @rbs (Hash[Symbol, untyped] production, untyped action) -> bool
+      def generated_location_action?: (Hash[Symbol, untyped] production, untyped action) -> bool
+
+      # @rbs (Hash[Symbol, untyped] production, untyped action) -> bool
+      def generated_values_action?: (Hash[Symbol, untyped] production, untyped action) -> bool
+
+      # @rbs (Hash[Symbol, untyped] production, untyped action) -> bool
+      def generated_positional_action?: (Hash[Symbol, untyped] production, untyped action) -> bool
+
+      # @rbs (Hash[Symbol, untyped] production, untyped action) -> bool
+      def generated_composition_action?: (Hash[Symbol, untyped] production, untyped action) -> bool
+
+      # @rbs (untyped action) -> bool
+      def generated_action_symbol?: (untyped action) -> bool
+
+      # @rbs () -> bool
+      def cst_enabled?: () -> bool
+
+      # @rbs (Integer token_id, untyped value, untyped location, Symbol reason) -> void
+      def capture_cst_error: (Integer token_id, untyped value, untyped location, Symbol reason) -> void
+
+      # @rbs (untyped value) -> untyped
+      def finalize_cst: (untyped value) -> untyped
+
+      # @rbs () -> nil
+      def failed_cst: () -> nil
+
+      # @rbs (ParseError error) -> nil
+      def cst_lexical_failure: (ParseError error) -> nil
+
+      # @rbs (untyped location, Symbol key) -> untyped
+      def cst_location_value: (untyped location, Symbol key) -> untyped
+
+      # @rbs (Hash[Symbol, untyped] tables) -> void
+      def prepare_green_cst: (Hash[Symbol, untyped] tables) -> void
+
+      # @rbs (Hash[Symbol, untyped] tables) -> void
+      def reset_cst_results: (Hash[Symbol, untyped] tables) -> void
+
+      # rubocop:disable Metrics/PerceivedComplexity -- generated locations have a deliberate allocation-free path.
+      # @rbs (Integer token_id, untyped value, untyped location, Integer from_state) -> void
+      def shift_green_token: (Integer token_id, untyped value, untyped location, Integer from_state) -> void
+
+      # @rbs (CST::GreenBuilder builder, CST::Kind kinds, Integer token_id, Integer from_state,
+      #   Array[CST::GreenTrivia] trailing, Array[CST::GreenTrivia] location_leading, untyped repair,
+      #   String token_text, Symbol lexer_state) -> void
+      def commit_green_token_shift: (CST::GreenBuilder builder, CST::Kind kinds, Integer token_id, Integer from_state, Array[CST::GreenTrivia] trailing, Array[CST::GreenTrivia] location_leading, untyped repair, String token_text, Symbol lexer_state) -> void
+
+      # @rbs (Integer production_id, Hash[Symbol, untyped] production, Integer length, Integer left_state) -> void
+      def reduce_green: (Integer production_id, Hash[Symbol, untyped] production, Integer length, Integer left_state) -> void
+
+      # @rbs (untyped value, untyped location) -> String
+      def green_token_text: (untyped value, untyped location) -> String
+
+      # @rbs (untyped location, Symbol key) -> Array[CST::GreenTrivia]
+      def green_location_trivia: (untyped location, Symbol key) -> Array[CST::GreenTrivia]
+
+      # @rbs (untyped value) -> untyped
+      def finalize_red_green_cst: (untyped value) -> untyped
+
+      # @rbs () -> void
+      def finalize_failed_green_cst: () -> void
+
+      # @rbs (ParseError error) -> void
+      def finalize_lexical_green_cst: (ParseError error) -> void
+
+      # @rbs () -> Array[CST::GreenTrivia]
+      def pending_green_trivia: () -> Array[CST::GreenTrivia]
+
+      # @rbs (CST::GreenNode green, CST::Kind kinds, ?file: String?) -> void
+      def install_syntax_root: (CST::GreenNode green, CST::Kind kinds, ?file: String?) -> void
+
+      # @rbs (untyped value) -> CST::ParseResult
+      def syntax_parse_result: (untyped value) -> CST::ParseResult
+
+      # @rbs () -> Array[Symbol]
+      def syntax_token_states: () -> Array[Symbol]
+
+      # @rbs (CST::GreenNode green) -> void
+      def install_parse_memo: (CST::GreenNode green) -> void
+
+      # @rbs (untyped location) -> Symbol
+      def green_lexer_state: (untyped location) -> Symbol
+
+      # @rbs (CST::NodeCache cache) { () -> untyped } -> untyped
+      def with_syntax_only: (CST::NodeCache cache) { () -> untyped } -> untyped
+
+      # @rbs (untyped source, CST::NodeCache cache) -> CST::SyntaxResult
+      def parse_syntax_token_source: (untyped source, CST::NodeCache cache) -> CST::SyntaxResult
+
+      # @rbs (CST::ReusableSubtree subtree) -> void
+      def push_reusable_green_subtree: (CST::ReusableSubtree subtree) -> void
+
+      # @rbs (Symbol type, Hash[untyped, untyped] data) -> void
+      def emit_incremental_event: (Symbol type, Hash[untyped, untyped] data) -> void
+
+      # @rbs () -> void
+      def discard_green_lookahead: () -> void
+
+      # @rbs (?report: bool) -> untyped
+      def recover: (?report: bool) -> untyped
+
+      # @rbs () -> untyped
+      def continue_recovery: () -> untyped
+
+      # @rbs () -> [:done, nil]
+      def reject_recovery_eof: () -> [ :done, nil ]
+
+      # @rbs (String token_display) -> Hash[String, untyped]
+      def runtime_discard_data: (String token_display) -> Hash[String, untyped]
+
+      # @rbs (bool report) -> untyped
+      def begin_recovery: (bool report) -> untyped
+
+      # @rbs (bool report) -> Hash[Symbol, untyped]
+      def recovery_context: (bool report) -> Hash[Symbol, untyped]
+
+      # @rbs (Hash[Symbol, untyped] context) -> [Hash[String, untyped]?, Array[Proc]?]
+      def publish_error_context: (Hash[Symbol, untyped] context) -> [ Hash[String, untyped]?, Array[Proc]? ]
+
+      # @rbs (Hash[Symbol, untyped] context, untyped repair) -> void
+      def notify_error_handler: (Hash[Symbol, untyped] context, untyped repair) -> void
+
+      # @rbs (RepairPlan repair) -> [:continue]
+      def commit_repair: (RepairPlan repair) -> [ :continue ]
+
+      # @rbs (Hash[Symbol, untyped] context, Hash[String, untyped]? token_data,
+      #   Array[Proc]? recovery_observers) -> untyped
+      # rubocop:disable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+      # Green restoration mirrors the existing state/value/location transactional fallback.
+      def fallback_recovery: (Hash[Symbol, untyped] context, Hash[String, untyped]? token_data, Array[Proc]? recovery_observers) -> untyped
+
+      # @rbs (untyped token_id, untyped token_display, untyped value, untyped location,
+      #   Integer state) -> Hash[String, untyped]
+      def runtime_original_token_data: (untyped token_id, untyped token_display, untyped value, untyped location, Integer state) -> Hash[String, untyped]
+
+      # @rbs (untyped token_id, untyped token_display, untyped value, untyped location,
+      #   Integer original_state, Hash[String, untyped]? token_data,
+      #   Array[Proc]? observers) -> [:done, nil]
+      def reject_without_recovery: (untyped token_id, untyped token_display, untyped value, untyped location, Integer original_state, Hash[String, untyped]? token_data, Array[Proc]? observers) -> [ :done, nil ]
+
+      # @rbs (untyped token_id, untyped token_display, untyped value, untyped location,
+      #   Integer original_state, Array[untyped] value_stack, Hash[String, untyped]? token_data,
+      #   String reason, Array[Proc]? observers) -> [:continue]
+      def finish_recovery: (untyped token_id, untyped token_display, untyped value, untyped location, Integer original_state, Array[untyped] value_stack, Hash[String, untyped]? token_data, String reason, Array[Proc]? observers) -> [ :continue ]
+
+      # @rbs (token_id: untyped, token_display: untyped, value: untyped,
+      #   location: untyped, state: Integer) -> Hash[String, untyped]
+      def runtime_token_data: (token_id: untyped, token_display: untyped, value: untyped, location: untyped, state: Integer) -> Hash[String, untyped]
+
+      # @rbs () -> Hash[String, untyped]
+      def runtime_current_token_data: () -> Hash[String, untyped]
+
+      # @rbs (untyped result_summary, String reason) -> void
+      def emit_accept_event: (untyped result_summary, String reason) -> void
+
+      # @rbs (String reason, Hash[String, untyped] token_data, ?observers: Array[Proc]?) -> void
+      def emit_reject_event: (String reason, Hash[String, untyped] token_data, ?observers: Array[Proc]?) -> void
+
+      # @rbs () -> bool
+      def shift_error_token: () -> bool
+
+      # @rbs () -> void
+      def ensure_stack_capacity!: () -> void
+
+      # @rbs () -> void
+      def consume_recovery_attempt!: () -> void
+
+      # @rbs () -> (RepairPlan | Object | nil)
+      def selected_repair: () -> (RepairPlan | Object | nil)
+
+      # @rbs (RepairPolicy policy) -> [Array[RepairInput], bool]
+      def repair_search_tokens: (RepairPolicy policy) -> [ Array[RepairInput], bool ]
+
+      # @rbs (RepairPlan plan) -> void
+      def apply_repair: (RepairPlan plan) -> void
+
+      # @rbs () -> RepairInput
+      def current_repair_input: () -> RepairInput
+
+      # @rbs (Array[RepairInput] source, Array[RepairEdit] edits) -> Array[RepairInput]
+      def replay_repair_edits: (Array[RepairInput] source, Array[RepairEdit] edits) -> Array[RepairInput]
+
+      # @rbs (Array[RepairInput] output, RepairInput input, Array[RepairEdit] edits) -> bool
+      def append_repair_edits: (Array[RepairInput] output, RepairInput input, Array[RepairEdit] edits) -> bool
+
+      # Retain a repair deletion in the concrete tree even though it is absent
+      # from the repaired token stream.
+      # @rbs (RepairInput input) -> void
+      def preserve_deleted_repair_input: (RepairInput input) -> void
+
+      # @rbs () -> void
+      def clear_repair_lookahead: () -> void
+
+      # @rbs (RepairEdit edit, value: untyped, location: untyped) -> RepairInput
+      def synthetic_repair_input: (RepairEdit edit, value: untyped, location: untyped) -> RepairInput
+
+      # @rbs (untyped location, Symbol kind) -> Hash[Symbol, untyped]
+      def cst_repair_location: (untyped location, Symbol kind) -> Hash[Symbol, untyped]
+
+      # @rbs (RepairPlan plan) -> String
+      def repair_trace: (RepairPlan plan) -> String
+
+      # @rbs () -> void
+      def read_lookahead: () -> void
+
+      # @rbs () -> void
+      def read_repair_lookahead: () -> void
+
+      # @rbs () -> void
+      def read_compatible_lookahead: () -> void
+
+      # @rbs () -> void
+      def materialize_compatible_lookahead: () -> void
+
+      # @rbs () -> String
+      def materialize_lookahead_token_display!: () -> String
+
+      # @rbs (untyped external_token, untyped value, untyped location) -> RepairInput
+      def repair_input: (untyped external_token, untyped value, untyped location) -> RepairInput
+
+      # @rbs (untyped token) -> RepairInput
+      def repair_input_from_external: (untyped token) -> RepairInput
+
+      # @rbs (RepairInput input) -> void
+      def enqueue_or_assign_repair_input: (RepairInput input) -> void
+
+      # @rbs (RepairInput input) -> void
+      def assign_repair_input: (RepairInput input) -> void
+
+      # @rbs () -> untyped
+      def read_external_token: () -> untyped
+
+      # @rbs (untyped external_token) -> Integer
+      def internal_token_id: (untyped external_token) -> Integer
+
+      # @rbs () -> Hash[Symbol, untyped]
+      def parser_tables: () -> Hash[Symbol, untyped]
+
+      # @rbs () -> Hash[Symbol, untyped]
+      def load_parser_tables: () -> Hash[Symbol, untyped]
+
+      # @rbs (untyped action) -> bool
+      def error_action?: (untyped action) -> bool
+
+      # @rbs (untyped configured) -> [String?, String?]
+      def configured_error_message: (untyped configured) -> [ String?, String? ]
+
+      # @rbs (String actual, Array[String] expected) -> Array[String]
+      def token_suggestions: (String actual, Array[String] expected) -> Array[String]
+
+      # @rbs (String token_name) -> String?
+      def normalized_token_word: (String token_name) -> String?
+
+      # @rbs (String left, String right) -> Integer
+      def edit_distance: (String left, String right) -> Integer
+
+      # @rbs (Integer state) -> untyped
+      def default_action: (Integer state) -> untyped
+
+      # @rbs (Hash[Symbol, untyped] tables) -> bool
+      def track_locations?: (Hash[Symbol, untyped] tables) -> bool
+
+      # @rbs (Hash[Symbol, untyped] tables) -> void
+      def initialize_runtime_fast_path: (Hash[Symbol, untyped] tables) -> void
+
+      # @rbs (?Class? singleton) -> void
+      def install_runtime_fast_path_tracker!: (?Class? singleton) -> void
+
+      # @rbs () -> void
+      def install_runtime_fast_path_class_tracker!: () -> void
+
+      # The generic driver remains authoritative whenever a public runtime
+      # extension can observe a committed shift or reduction.
+      # @rbs (Hash[Symbol, untyped] tables) -> bool
+      def runtime_fast_path_eligible?: (Hash[Symbol, untyped] tables) -> bool
+
+      # @rbs () -> bool
+      def runtime_fast_path_hooks_eligible?: () -> bool
+
+      # @rbs () -> bool?
+      def cached_runtime_fast_path_hooks_eligibility: () -> bool?
+
+      # @rbs () -> bool
+      def runtime_fast_path_class_hooks_eligible?: () -> bool
+
+      # @rbs (UnboundMethod lookup, Symbol name, Symbol reference) -> bool
+      def runtime_method_unchanged?: (UnboundMethod lookup, Symbol name, Symbol reference) -> bool
+
+      # Ruby 3.0 and 3.1 do not preserve UnboundMethod#== for an inherited
+      # method and its alias even though both still identify the same body.
+      # @rbs (Method | UnboundMethod implementation, Method | UnboundMethod expected) -> bool
+      def runtime_methods_equivalent?: (Method | UnboundMethod implementation, Method | UnboundMethod expected) -> bool
+
+      # Bypass an application-defined `method` helper while retaining Ruby's
+      # complete singleton/prepend/subclass lookup semantics.
+      # @rbs (UnboundMethod lookup, Symbol name) -> Method?
+      def runtime_core_method: (UnboundMethod lookup, Symbol name) -> Method?
+
+      # Re-check after lexer and semantic-action callbacks because those are
+      # supported points at which an application can install instrumentation.
+      # A disabled fast path never becomes active again within the session.
+      # @rbs () -> void
+      def refresh_runtime_fast_path_after_user_code!: () -> void
+
+      # Keep allocation out of the ordinary two-element lexer path. If a
+      # location first appears after values have already shifted, backfill the
+      # parallel prefix with nil exactly once.
+      # @rbs (untyped location) -> void
+      def push_location: (untyped location) -> void
+
+      # @rbs (Integer length) -> Array[untyped]
+      def pop_reduction_locations: (Integer length) -> Array[untyped]
+
+      # @rbs (untyped table, Integer row, Integer column) -> untyped
+      def table_lookup: (untyped table, Integer row, Integer column) -> untyped
+
+      # @rbs (String message) -> void
+      def trace: (String message) -> void
+
+      # @rbs (untyped value, Integer symbol_id) -> String
+      def trace_value_suffix: (untyped value, Integer symbol_id) -> String
+    end
+  end
+end