ibex-runtime 0.2.0 → 0.4.0

data/sig/ibex/runtime/parser_sync_recovery.rbs

@@ -7,21 +7,21 @@ module Ibex
     module ParserSyncRecovery
       ERROR_ACTION: [ :error ]
 
-      private def parser_tables: () -> Hash[Symbol, untyped]
+      private def parser_tables: () -> Hash[Symbol, Object?]
 
-      private def table_lookup: (untyped, Integer, Integer) -> untyped
+      private def table_lookup: (Object?, Integer, Integer) -> IR::runtime_action?
 
-      private def default_action: (Integer) -> untyped
+      private def default_action: (Integer) -> IR::runtime_action?
 
-      private def token_to_str: (untyped) -> String
+      private def token_to_str: (Object?) -> String
 
       private def trace: (String) -> void
 
-      private def continue_recovery: () -> untyped
+      private def continue_recovery: () -> ([ :continue ] | [ :done, nil ])
 
       private def reject_recovery_eof: () -> [ :done, nil ]
 
-      private def finish_recovery: (untyped, untyped, untyped, untyped, Integer, Array[untyped], Hash[String, untyped]?, String, Array[Proc]?) -> [ :continue ]
+      private def finish_recovery: (Object?, Object?, Object?, Object?, Integer, Array[Object?], Hash[String, Object?]?, String, Array[Proc]?) -> [ :continue ]
 
       private
 
@@ -31,21 +31,21 @@ module Ibex
       # @rbs () -> bool
       def sync_recovery_active?: () -> bool
 
-      # @rbs (Hash[Symbol, untyped] context, Hash[String, untyped]? token_data,
-      #   Array[Proc]? observers) -> untyped
-      def begin_sync_recovery: (Hash[Symbol, untyped] context, Hash[String, untyped]? token_data, Array[Proc]? observers) -> untyped
+      # @rbs (Hash[Symbol, Object?] context, Hash[String, Object?]? token_data,
+      #   Array[Proc]? observers) -> ([ :continue ] | [ :done, nil ])
+      def begin_sync_recovery: (Hash[Symbol, Object?] context, Hash[String, Object?]? token_data, Array[Proc]? observers) -> ([ :continue ] | [ :done, nil ])
 
-      # @rbs () -> untyped
-      def continue_sync_recovery: () -> untyped
+      # @rbs () -> ([ :continue ] | [ :done, nil ])
+      def continue_sync_recovery: () -> ([ :continue ] | [ :done, nil ])
 
-      # @rbs (untyped token_id) -> bool
-      def sync_token?: (untyped token_id) -> bool
+      # @rbs (Integer token_id) -> bool
+      def sync_token?: (Integer token_id) -> bool
 
       # @rbs () -> bool
       def synchronize_for_current_token: () -> bool
 
-      # @rbs (Integer state, Integer token_id) -> untyped
-      def sync_action: (Integer state, Integer token_id) -> untyped
+      # @rbs (Integer state, Integer token_id) -> IR::runtime_action
+      def sync_action: (Integer state, Integer token_id) -> IR::runtime_action
 
       # @rbs () -> [:continue]
       def finish_sync_recovery: () -> [ :continue ]

data/sig/ibex/runtime/repair.rbs

@@ -28,6 +28,8 @@ module Ibex
 
     # One immutable insertion, deletion, or replacement.
     class RepairEdit
+      type document_value = Symbol | Integer | String
+
       KINDS: Array[Symbol]
 
       attr_reader kind: Symbol
@@ -43,8 +45,8 @@ module Ibex
       # @rbs (kind: Symbol, position: Integer, token_id: Integer, token_name: String, cost: Integer) -> void
       def initialize: (kind: Symbol, position: Integer, token_id: Integer, token_name: String, cost: Integer) -> void
 
-      # @rbs () -> Hash[Symbol, untyped]
-      def to_h: () -> Hash[Symbol, untyped]
+      # @rbs () -> Hash[Symbol, document_value]
+      def to_h: () -> Hash[Symbol, document_value]
     end
 
     # Deterministically selected repair.
@@ -58,8 +60,26 @@ module Ibex
       # @rbs (edits: Array[RepairEdit], configurations: Integer) -> void
       def initialize: (edits: Array[RepairEdit], configurations: Integer) -> void
 
-      # @rbs () -> Hash[Symbol, untyped]
-      def to_h: () -> Hash[Symbol, untyped]
+      # @rbs () -> Hash[Symbol, Integer | Array[Hash[Symbol, RepairEdit::document_value]]]
+      def to_h: () -> Hash[Symbol, Integer | Array[Hash[Symbol, RepairEdit::document_value]]]
+    end
+
+    # Closed internal outcome for callers that must distinguish bounded search
+    # exhaustion from a complete search with no repair.
+    class RepairSearchResult
+      STATUSES: Array[Symbol]
+
+      attr_reader status: Symbol
+
+      attr_reader plan: RepairPlan?
+
+      attr_reader configurations: Integer
+
+      # @rbs (status: Symbol, plan: RepairPlan?, configurations: Integer) -> void
+      def initialize: (status: Symbol, plan: RepairPlan?, configurations: Integer) -> void
+
+      # @rbs () -> bool
+      def selected?: () -> bool
     end
 
     # Internal normalized input record retained while repair looks ahead.
@@ -68,12 +88,12 @@ module Ibex
 
       attr_reader token_name: String
 
-      attr_reader value: untyped
+      attr_reader value: Object?
 
-      attr_reader location: untyped
+      attr_reader location: Object?
 
-      # @rbs (token_id: Integer, token_name: String, value: untyped, location: untyped) -> void
-      def initialize: (token_id: Integer, token_name: String, value: untyped, location: untyped) -> void
+      # @rbs (token_id: Integer, token_name: String, value: Object?, location: Object?) -> void
+      def initialize: (token_id: Integer, token_name: String, value: Object?, location: Object?) -> void
 
       # @rbs () -> bool
       def eof?: () -> bool

data/sig/ibex/runtime/repair_priority_queue.rbs

@@ -4,7 +4,9 @@ module Ibex
   module Runtime
     # Minimal binary heap ordered by an immutable Array priority.
     class RepairPriorityQueue
-      @entries: Array[[ Array[untyped], untyped ]]
+      type priority = Array[untyped]
+
+      @entries: Array[[ priority, Object? ]]
 
       # @rbs () -> void
       def initialize: () -> void
@@ -12,16 +14,16 @@ module Ibex
       # @rbs () -> bool
       def empty?: () -> bool
 
-      # @rbs (Array[untyped] priority, untyped value) -> void
-      def push: (Array[untyped] priority, untyped value) -> void
+      # @rbs (priority priority, Object? value) -> void
+      def push: (priority priority, Object? value) -> void
 
-      # @rbs () -> [Array[untyped], untyped]?
-      def pop: () -> [ Array[untyped], untyped ]?
+      # @rbs () -> [priority, Object?]?
+      def pop: () -> [ priority, Object? ]?
 
       private
 
-      # @rbs ([Array[untyped], untyped] left, [Array[untyped], untyped] right) -> Integer
-      def compare: ([ Array[untyped], untyped ] left, [ Array[untyped], untyped ] right) -> Integer
+      # @rbs ([priority, Object?] left, [priority, Object?] right) -> Integer
+      def compare: ([ priority, Object? ] left, [ priority, Object? ] right) -> Integer
     end
   end
 end

data/sig/ibex/runtime/repair_search.rbs

@@ -5,30 +5,38 @@ module Ibex
     # Bounded Dijkstra search over LR state stacks. Semantic actions never run.
     # rubocop:disable Metrics/ClassLength -- queue policy and LR transitions form one bounded search invariant.
     class RepairSearch
+      type configuration_key = [ Array[Integer], Integer, Integer, bool ]
+
+      type priority = Array[untyped]
+
+      type lookup_table = Tables::action_table | Tables::goto_table
+
+      type lookup_value = IR::runtime_action | Integer?
+
       NEED_INPUT: Object
 
       LIMIT: Object
 
-      class Configuration < Struct[untyped]
-        attr_accessor stack(): untyped
+      class Configuration < Struct[Array[Integer] | Integer | Array[RepairEdit] | bool]
+        attr_accessor stack(): Array[Integer]
 
-        attr_accessor input_index(): untyped
+        attr_accessor input_index(): Integer
 
-        attr_accessor shifts(): untyped
+        attr_accessor shifts(): Integer
 
-        attr_accessor cost(): untyped
+        attr_accessor cost(): Integer
 
-        attr_accessor edits(): untyped
+        attr_accessor edits(): Array[RepairEdit]
 
-        attr_accessor goal(): untyped
+        attr_accessor goal(): bool
 
-        def self.new: (?stack: untyped, ?input_index: untyped, ?shifts: untyped, ?cost: untyped, ?edits: untyped, ?goal: untyped) -> instance
-                    | ({ ?stack: untyped, ?input_index: untyped, ?shifts: untyped, ?cost: untyped, ?edits: untyped, ?goal: untyped }) -> instance
+        def self.new: (?stack: Array[Integer], ?input_index: Integer, ?shifts: Integer, ?cost: Integer, ?edits: Array[RepairEdit], ?goal: bool) -> instance
+                    | ({ ?stack: Array[Integer], ?input_index: Integer, ?shifts: Integer, ?cost: Integer, ?edits: Array[RepairEdit], ?goal: bool }) -> instance
       end
 
       @candidate_ids: Array[Integer]
 
-      @best: Hash[Array[untyped], Array[untyped]]
+      @best: Hash[configuration_key, priority]
 
       @heap: RepairPriorityQueue
 
@@ -40,15 +48,20 @@ module Ibex
 
       @policy: RepairPolicy
 
-      @tables: Hash[Symbol, untyped]
+      @tables: Hash[Symbol, Object?]
 
-      # @rbs (Hash[Symbol, untyped] tables, RepairPolicy policy, Array[RepairInput] tokens,
+      # @rbs (Hash[Symbol, Object?] tables, RepairPolicy policy, Array[RepairInput] tokens,
       #   complete: bool) -> void
-      def initialize: (Hash[Symbol, untyped] tables, RepairPolicy policy, Array[RepairInput] tokens, complete: bool) -> void
+      def initialize: (Hash[Symbol, Object?] tables, RepairPolicy policy, Array[RepairInput] tokens, complete: bool) -> void
 
+      # Compatibility projection used by the semantic runtime path.
       # @rbs (Array[Integer] state_stack) -> (RepairPlan | Object | nil)
       def search: (Array[Integer] state_stack) -> (RepairPlan | Object | nil)
 
+      # Preserve the bounded outcome for syntax tooling and diagnostics.
+      # @rbs (Array[Integer] state_stack) -> RepairSearchResult
+      def search_result: (Array[Integer] state_stack) -> RepairSearchResult
+
       private
 
       # @rbs (Configuration configuration) -> (RepairPlan | Object | nil)
@@ -79,11 +92,14 @@ module Ibex
       # @rbs (Array[Integer] states, Integer production_id) -> Array[Integer]?
       def apply_reduction: (Array[Integer] states, Integer production_id) -> Array[Integer]?
 
-      # @rbs (Integer state, Integer token_id) -> untyped
-      def action_for: (Integer state, Integer token_id) -> untyped
+      # @rbs (Integer state, Integer token_id) -> IR::runtime_action
+      def action_for: (Integer state, Integer token_id) -> IR::runtime_action
+
+      # @rbs (Tables::action_table table, Integer row, Integer column) -> IR::runtime_action?
+      def action_table_lookup: (Tables::action_table table, Integer row, Integer column) -> IR::runtime_action?
 
-      # @rbs (untyped table, Integer row, Integer column) -> untyped
-      def table_lookup: (untyped table, Integer row, Integer column) -> untyped
+      # @rbs (Tables::goto_table table, Integer row, Integer column) -> Integer?
+      def goto_table_lookup: (Tables::goto_table table, Integer row, Integer column) -> Integer?
 
       # @rbs (Configuration source, ?stack: Array[Integer], ?input_index: Integer, ?shifts: Integer,
       #   ?cost: Integer, ?edits: Array[RepairEdit], ?goal: bool) -> Configuration
@@ -92,6 +108,9 @@ module Ibex
       # @rbs (Array[RepairEdit] edits) -> RepairPlan
       def plan: (Array[RepairEdit] edits) -> RepairPlan
 
+      # @rbs (Symbol status, ?plan: RepairPlan?) -> RepairSearchResult
+      def outcome: (Symbol status, ?plan: RepairPlan?) -> RepairSearchResult
+
       # @rbs (Integer token_id) -> String
       def token_name: (Integer token_id) -> String
 
@@ -101,8 +120,8 @@ module Ibex
       # @rbs () -> (Configuration | Object)
       def pop: () -> (Configuration | Object)
 
-      # @rbs (Configuration configuration) -> Array[untyped]
-      def priority_for: (Configuration configuration) -> Array[untyped]
+      # @rbs (Configuration configuration) -> priority
+      def priority_for: (Configuration configuration) -> priority
 
       # Prefer punctuation edits when equal-cost repairs are otherwise
       # ambiguous; inventing or discarding a word-like token is more likely to

data/sig/ibex/runtime/syntax_repair.rbs

@@ -0,0 +1,177 @@
+# Generated from lib/ibex/runtime/syntax_repair.rb with RBS::Inline
+
+module Ibex
+  module Runtime
+    type syntax_edit_document = { kind: Symbol, position: Integer, token_id: Integer, token_name: String, cost: Integer, start_byte: Integer, end_byte: Integer, original_text: String, replacement_text: String? }
+
+    # One syntax-only projection of a runtime repair edit. It intentionally
+    # carries source bytes and token identity, never an application value.
+    class SyntaxRepairEdit
+      attr_reader kind: Symbol
+
+      attr_reader position: Integer
+
+      attr_reader token_id: Integer
+
+      attr_reader token_name: String
+
+      attr_reader cost: Integer
+
+      attr_reader start_byte: Integer
+
+      attr_reader end_byte: Integer
+
+      attr_reader original_text: String
+
+      attr_reader replacement_text: String?
+
+      # @rbs (kind: Symbol, position: Integer, token_id: Integer, token_name: String, cost: Integer,
+      #   start_byte: Integer, end_byte: Integer, original_text: String, replacement_text: String?) -> void
+      # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
+      def initialize: (kind: Symbol, position: Integer, token_id: Integer, token_name: String, cost: Integer, start_byte: Integer, end_byte: Integer, original_text: String, replacement_text: String?) -> void
+
+      # @rbs () -> syntax_edit_document
+      def to_h: () -> syntax_edit_document
+    end
+
+    # One selected runtime plan plus its source-oriented edit projection.
+    class SyntaxRepairPlan
+      attr_reader runtime_plan: RepairPlan
+
+      attr_reader edits: Array[SyntaxRepairEdit]
+
+      attr_reader cost: Integer
+
+      attr_reader configurations: Integer
+
+      # @rbs (runtime_plan: RepairPlan, edits: Array[SyntaxRepairEdit]) -> void
+      # rubocop:disable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+      def initialize: (runtime_plan: RepairPlan, edits: Array[SyntaxRepairEdit]) -> void
+    end
+
+    # Immutable syntax-only repair attempt. There is deliberately no `value`.
+    class SyntaxRepairResult
+      STATUSES: Array[Symbol]
+
+      BOUNDED_STATUSES: Array[Symbol]
+
+      attr_reader status: Symbol
+
+      attr_reader bounded_status: Symbol
+
+      attr_reader reason: Symbol?
+
+      attr_reader plan: SyntaxRepairPlan?
+
+      attr_reader text_edits: Array[CST::TextEdit]
+
+      attr_reader syntax_root: CST::SyntaxNode
+
+      attr_reader diagnostics: Array[SyntaxSessionDiagnostic]
+
+      attr_reader updated_source: CST::SourceText?
+
+      attr_reader validation: SyntaxSessionResult?
+
+      # @rbs (status: Symbol, bounded_status: Symbol, reason: Symbol?, plan: SyntaxRepairPlan?,
+      #   text_edits: Array[CST::TextEdit], syntax_root: CST::SyntaxNode,
+      #   diagnostics: Array[SyntaxSessionDiagnostic], updated_source: CST::SourceText?,
+      #   validation: SyntaxSessionResult?) -> void
+      # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
+      def initialize: (status: Symbol, bounded_status: Symbol, reason: Symbol?, plan: SyntaxRepairPlan?, text_edits: Array[CST::TextEdit], syntax_root: CST::SyntaxNode, diagnostics: Array[SyntaxSessionDiagnostic], updated_source: CST::SourceText?, validation: SyntaxSessionResult?) -> void
+
+      # @rbs () -> bool
+      def accepted?: () -> bool
+
+      # @rbs () -> bool
+      def progress?: () -> bool
+
+      private
+
+      # @rbs (Symbol, Symbol, Symbol?, SyntaxRepairPlan?, Array[CST::TextEdit], CST::SourceText?,
+      #   SyntaxSessionResult?) -> void
+      # rubocop:disable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+      def validate_result_shape!: (Symbol, Symbol, Symbol?, SyntaxRepairPlan?, Array[CST::TextEdit], CST::SourceText?, SyntaxSessionResult?) -> void
+    end
+
+    # Executes one fresh syntax-only repair attempt without mutating its source
+    # SyntaxSession. Generated lexer actions retain the acknowledged trust
+    # profile; parser production actions remain suppressed.
+    class SyntaxRepairer
+      # @rbs (Class parser_class, CST::SourceText source, SyntaxSessionResult baseline,
+      #   execution_profile: Symbol, resource_limits: ResourceLimits, limits: SyntaxSessionLimits,
+      #   cancellation: CancellationToken?, policy: RepairPolicy, token_text: Hash[String, String]) -> void
+      def initialize: (Class parser_class, CST::SourceText source, SyntaxSessionResult baseline, execution_profile: Symbol, resource_limits: ResourceLimits, limits: SyntaxSessionLimits, cancellation: CancellationToken?, policy: RepairPolicy, token_text: Hash[String, String]) -> void
+
+      # @rbs () -> SyntaxRepairResult
+      def call: () -> SyntaxRepairResult
+
+      private
+
+      # @rbs (Parser parser) -> Array[[RepairPlan, Array[RepairInput]]]
+      def install_capture: (Parser parser) -> Array[[ RepairPlan, Array[RepairInput] ]]
+
+      # @rbs ([RepairPlan, Array[RepairInput]] capture, CST::SyntaxResult parsed,
+      #   Array[SyntaxSessionDiagnostic] diagnostics) -> SyntaxRepairResult
+      def build_selected: ([ RepairPlan, Array[RepairInput] ] capture, CST::SyntaxResult parsed, Array[SyntaxSessionDiagnostic] diagnostics) -> SyntaxRepairResult
+
+      # @rbs (RepairPlan plan, Array[RepairInput] inputs) -> Array[SyntaxRepairEdit]
+      def project_edits: (RepairPlan plan, Array[RepairInput] inputs) -> Array[SyntaxRepairEdit]
+
+      # @rbs (RepairInput input) -> [Integer, Integer]
+      def input_range: (RepairInput input) -> [ Integer, Integer ]
+
+      # @rbs (RepairEdit edit) -> String?
+      def replacement_text: (RepairEdit edit) -> String?
+
+      # @rbs (String name) -> String?
+      def punctuation_literal: (String name) -> String?
+
+      # @rbs (Integer start_byte, Integer end_byte) -> String
+      def original_text: (Integer start_byte, Integer end_byte) -> String
+
+      # @rbs (Array[SyntaxRepairEdit] edits) -> Array[CST::TextEdit]
+      def normalize_text_edits: (Array[SyntaxRepairEdit] edits) -> Array[CST::TextEdit]
+
+      # @rbs (Array[CST::TextEdit] edits) -> void
+      def validate_edit_limits!: (Array[CST::TextEdit] edits) -> void
+
+      # @rbs (CST::SourceText source) -> SyntaxSessionResult
+      def fresh_validation: (CST::SourceText source) -> SyntaxSessionResult
+
+      # @rbs (SyntaxSessionResult validation, CST::SourceText source) -> Symbol
+      def validation_status: (SyntaxSessionResult validation, CST::SourceText source) -> Symbol
+
+      # @rbs (SyntaxSessionResult result) -> Integer?
+      def first_diagnostic_byte: (SyntaxSessionResult result) -> Integer?
+
+      # @rbs (Symbol status, Symbol reason, CST::SyntaxResult parsed,
+      #   Array[SyntaxSessionDiagnostic] diagnostics) -> SyntaxRepairResult
+      def bounded_failure: (Symbol status, Symbol reason, CST::SyntaxResult parsed, Array[SyntaxSessionDiagnostic] diagnostics) -> SyntaxRepairResult
+
+      # @rbs (Symbol reason, CST::SyntaxResult parsed, Array[SyntaxSessionDiagnostic] diagnostics,
+      #   ?plan: SyntaxRepairPlan?) -> SyntaxRepairResult
+      def unavailable: (Symbol reason, CST::SyntaxResult parsed, Array[SyntaxSessionDiagnostic] diagnostics, ?plan: SyntaxRepairPlan?) -> SyntaxRepairResult
+
+      # @rbs (Array[Object] diagnostics) -> Array[SyntaxSessionDiagnostic]
+      def immutable_diagnostics: (Array[Object] diagnostics) -> Array[SyntaxSessionDiagnostic]
+
+      # @rbs (Object location, Symbol key) -> Object?
+      # @rbs (untyped location, Symbol key) -> untyped
+      def location_value: (Object location, Symbol key) -> Object?
+                        | (untyped location, Symbol key) -> untyped
+
+      # @rbs (RepairPolicy policy) -> RepairPolicy
+      def validate_policy: (RepairPolicy policy) -> RepairPolicy
+
+      # @rbs (Hash[String, String] value) -> Hash[String, String]
+      def validate_token_text: (Hash[String, String] value) -> Hash[String, String]
+
+      # @rbs (Symbol resource, Integer limit, Integer observed) -> void
+      def enforce_limit!: (Symbol resource, Integer limit, Integer observed) -> void
+
+      # @rbs () -> void
+      def cancellation_checkpoint!: () -> void
+    end
+  end
+end

data/sig/ibex/runtime/syntax_session.rbs

@@ -0,0 +1,186 @@
+# Generated from lib/ibex/runtime/syntax_session.rb with RBS::Inline
+
+module Ibex
+  module Runtime
+    class Parser
+      def self.syntax_execution_profile: () -> Symbol
+
+      def self.syntax_session: (String | CST::SourceText source, ?execution_profile: Symbol?, ?resource_limits: ResourceLimits?, ?limits: SyntaxSessionLimits?, ?cancellation: CancellationToken?, ?blender: bool) -> SyntaxSession
+    end
+
+    # Raised when a caller has not acknowledged the generated artifact's
+    # execution profile.
+    class SyntaxSessionTrustError < ArgumentError
+    end
+
+    # Raised cooperatively at syntax-session operation boundaries and parser
+    # observation checkpoints after cancellation is requested.
+    class SyntaxSessionCancelled < StandardError
+    end
+
+    # Raised when a syntax-service-specific resource bound is exceeded.
+    class SyntaxSessionResourceLimitError < StandardError
+      attr_reader resource: Symbol
+
+      attr_reader limit: Integer
+
+      attr_reader observed: Integer
+
+      # @rbs (resource: Symbol, limit: Integer, observed: Integer) -> void
+      def initialize: (resource: Symbol, limit: Integer, observed: Integer) -> void
+    end
+
+    # Thread-safe cooperative cancellation state for one or more operations.
+    class CancellationToken
+      # @rbs () -> void
+      def initialize: () -> void
+
+      # @rbs () -> true
+      # rubocop:disable Naming/PredicateMethod -- command mutation convention.
+      def cancel!: () -> true
+
+      # @rbs () -> bool
+      def cancelled?: () -> bool
+    end
+
+    # Immutable syntax-service bounds layered over parser ResourceLimits.
+    class SyntaxSessionLimits
+      DEFAULT_MAX_SOURCE_BYTES: Integer
+
+      DEFAULT_MAX_EDITS_PER_OPERATION: Integer
+
+      DEFAULT_MAX_INSERTED_BYTES: Integer
+
+      attr_reader max_source_bytes: Integer
+
+      attr_reader max_edits_per_operation: Integer
+
+      attr_reader max_inserted_bytes: Integer
+
+      # @rbs (?max_source_bytes: Integer, ?max_edits_per_operation: Integer,
+      #   ?max_inserted_bytes: Integer) -> void
+      def initialize: (?max_source_bytes: Integer, ?max_edits_per_operation: Integer, ?max_inserted_bytes: Integer) -> void
+
+      private
+
+      # @rbs (Object? value, Symbol name) -> void
+      def validate_positive_integer: (Object? value, Symbol name) -> void
+
+      # @rbs (Object? value, Symbol name) -> void
+      def validate_nonnegative_integer: (Object? value, Symbol name) -> void
+    end
+
+    # Immutable evidence from one completed syntax-session operation.
+    class SyntaxSessionMetrics
+      attr_reader reused_ratio: Float
+
+      attr_reader reused_tokens: Integer
+
+      attr_reader token_count: Integer
+
+      attr_reader fallback_reasons: Array[Symbol]
+
+      # @rbs (reused_ratio: Float, reused_tokens: Integer, token_count: Integer,
+      #   fallback_reasons: Array[Symbol]) -> void
+      def initialize: (reused_ratio: Float, reused_tokens: Integer, token_count: Integer, fallback_reasons: Array[Symbol]) -> void
+
+      # @rbs () -> bool
+      def fallback?: () -> bool
+    end
+
+    # Immutable, data-only copy of one parser diagnostic. Application-owned
+    # values and locations are sanitized rather than retained by identity.
+    class SyntaxSessionDiagnostic
+      attr_reader kind: Symbol
+
+      attr_reader data: Hash[String, EventSanitizer::json_value]
+
+      # @rbs (kind: Symbol, data: Hash[Object?, Object?]) -> void
+      def initialize: (kind: Symbol, data: Hash[Object?, Object?]) -> void
+
+      # @rbs () -> Hash[String, EventSanitizer::json_value]
+      def to_h: () -> Hash[String, EventSanitizer::json_value]
+    end
+
+    # Immutable public snapshot of one completed syntax-session operation.
+    class SyntaxSessionResult
+      attr_reader revision: Integer
+
+      attr_reader syntax_root: CST::SyntaxNode
+
+      attr_reader diagnostics: Array[SyntaxSessionDiagnostic]
+
+      attr_reader expected_tokens: Array[String]
+
+      attr_reader metrics: SyntaxSessionMetrics
+
+      attr_reader status: Symbol
+
+      # @rbs (revision: Integer, syntax_root: CST::SyntaxNode, diagnostics: Array[SyntaxSessionDiagnostic],
+      #   expected_tokens: Array[String], metrics: SyntaxSessionMetrics, status: Symbol) -> void
+      def initialize: (revision: Integer, syntax_root: CST::SyntaxNode, diagnostics: Array[SyntaxSessionDiagnostic], expected_tokens: Array[String], metrics: SyntaxSessionMetrics, status: Symbol) -> void
+
+      # @rbs () -> bool
+      def success?: () -> bool
+    end
+
+    # Generated-language syntax boundary backed by the existing Red/Green CST
+    # incremental engine. It does not execute parser production actions.
+    class SyntaxSession
+      TRUSTED_PROFILE: Symbol
+
+      attr_reader execution_profile: Symbol
+
+      attr_reader limits: SyntaxSessionLimits
+
+      # @rbs (Class parser_class, String | CST::SourceText source,
+      #   execution_profile: Symbol?, ?resource_limits: ResourceLimits?,
+      #   ?limits: SyntaxSessionLimits?, ?cancellation: CancellationToken?, ?blender: bool) -> void
+      def initialize: (Class parser_class, String | CST::SourceText source, execution_profile: Symbol?, ?resource_limits: ResourceLimits?, ?limits: SyntaxSessionLimits?, ?cancellation: CancellationToken?, ?blender: bool) -> void
+
+      # @rbs () -> CST::SourceText
+      def source_text: () -> CST::SourceText
+
+      # @rbs () -> SyntaxSessionResult
+      def result: () -> SyntaxSessionResult
+
+      # Apply byte-oriented edits against the current source.
+      # @rbs (Array[CST::TextEdit] edits) -> SyntaxSessionResult
+      def apply_edits: (Array[CST::TextEdit] edits) -> SyntaxSessionResult
+
+      # Propose byte edits through the existing bounded repair search, then
+      # validate them with a fresh syntax-only parse. The session is unchanged.
+      # @rbs (?policy: RepairPolicy, ?token_text: Hash[String, String]) -> SyntaxRepairResult
+      def repair: (?policy: RepairPolicy, ?token_text: Hash[String, String]) -> SyntaxRepairResult
+
+      private
+
+      # @rbs (Array[CST::TextEdit] edits) -> SyntaxSessionResult
+      def apply_edits_locked: (Array[CST::TextEdit] edits) -> SyntaxSessionResult
+
+      # @rbs (Class parser_class, Symbol? acknowledged) -> Symbol
+      def validate_execution_profile: (Class parser_class, Symbol? acknowledged) -> Symbol
+
+      # @rbs (String | CST::SourceText source) -> CST::SourceText
+      def normalize_source: (String | CST::SourceText source) -> CST::SourceText
+
+      # @rbs (Symbol resource, Integer limit, Integer observed) -> void
+      def enforce_limit!: (Symbol resource, Integer limit, Integer observed) -> void
+
+      # @rbs () -> void
+      def cancellation_checkpoint!: () -> void
+
+      # @rbs (Event event, Parser parser) -> void
+      def handle_runtime_event: (Event event, Parser parser) -> void
+
+      # @rbs () -> void
+      def reset_operation_evidence: () -> void
+
+      # @rbs (CST::SyntaxResult parsed) -> SyntaxSessionResult
+      def snapshot: (CST::SyntaxResult parsed) -> SyntaxSessionResult
+
+      # @rbs (Array[Object?] diagnostics) -> Array[SyntaxSessionDiagnostic]
+      def immutable_diagnostics: (Array[Object?] diagnostics) -> Array[SyntaxSessionDiagnostic]
+    end
+  end
+end