ibex-runtime 0.2.0 → 0.4.0

data/lib/ibex/runtime/syntax_session.rb

@@ -0,0 +1,416 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+require_relative "event_sanitizer" unless defined?(Ibex::Runtime::EventSanitizer)
+
+module Ibex
+  module Runtime
+    # Syntax-session additions to the frozen Parser signature surface.
+    # @rbs!
+    #   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:, limit:, observed:)
+        @resource = resource
+        @limit = limit
+        @observed = observed
+        super("syntax session resource limit exceeded: #{resource} is #{observed}, configured maximum is #{limit}")
+      end
+    end
+
+    # Thread-safe cooperative cancellation state for one or more operations.
+    class CancellationToken
+      # @rbs () -> void
+      def initialize
+        @mutex = Mutex.new #: Mutex
+        @cancelled = false #: bool
+      end
+
+      # @rbs () -> true
+      # rubocop:disable Naming/PredicateMethod -- command mutation convention.
+      def cancel!
+        @mutex.synchronize { @cancelled = true }
+        true
+      end
+      # rubocop:enable Naming/PredicateMethod
+
+      # @rbs () -> bool
+      def cancelled?
+        @mutex.synchronize { @cancelled }
+      end
+    end
+
+    # Immutable syntax-service bounds layered over parser ResourceLimits.
+    class SyntaxSessionLimits
+      DEFAULT_MAX_SOURCE_BYTES = 16 * 1024 * 1024 #: Integer
+      DEFAULT_MAX_EDITS_PER_OPERATION = 1_024 #: Integer
+      DEFAULT_MAX_INSERTED_BYTES = 4 * 1024 * 1024 #: 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: DEFAULT_MAX_SOURCE_BYTES,
+        max_edits_per_operation: DEFAULT_MAX_EDITS_PER_OPERATION,
+        max_inserted_bytes: DEFAULT_MAX_INSERTED_BYTES
+      )
+        validate_positive_integer(max_source_bytes, :max_source_bytes)
+        validate_positive_integer(max_edits_per_operation, :max_edits_per_operation)
+        validate_nonnegative_integer(max_inserted_bytes, :max_inserted_bytes)
+        @max_source_bytes = max_source_bytes
+        @max_edits_per_operation = max_edits_per_operation
+        @max_inserted_bytes = max_inserted_bytes
+        freeze
+      end
+
+      private
+
+      # @rbs (Object? value, Symbol name) -> void
+      def validate_positive_integer(value, name)
+        return if value.is_a?(Integer) && value.positive?
+
+        raise ArgumentError, "#{name} must be a positive Integer"
+      end
+
+      # @rbs (Object? value, Symbol name) -> void
+      def validate_nonnegative_integer(value, name)
+        return if value.is_a?(Integer) && value >= 0
+
+        raise ArgumentError, "#{name} must be a nonnegative Integer"
+      end
+    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:, reused_tokens:, token_count:, fallback_reasons:)
+        unless reused_ratio.is_a?(Float) && reused_ratio.finite? && reused_ratio.between?(0.0, 1.0)
+          raise ArgumentError, "reused_ratio must be a finite Float in 0.0..1.0"
+        end
+        unless reused_tokens.is_a?(Integer) && reused_tokens >= 0
+          raise ArgumentError, "reused_tokens must be a nonnegative Integer"
+        end
+        unless token_count.is_a?(Integer) && token_count >= 0
+          raise ArgumentError, "token_count must be a nonnegative Integer"
+        end
+        unless fallback_reasons.is_a?(Array) && fallback_reasons.all?(Symbol)
+          raise ArgumentError, "fallback_reasons must contain only Symbols"
+        end
+
+        @reused_ratio = reused_ratio
+        @reused_tokens = reused_tokens
+        @token_count = token_count
+        @fallback_reasons = fallback_reasons.dup.freeze
+        freeze
+      end
+
+      # @rbs () -> bool
+      def fallback?
+        !@fallback_reasons.empty?
+      end
+    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:, data:)
+        raise ArgumentError, "diagnostic kind must be a Symbol" unless kind.is_a?(Symbol)
+        raise ArgumentError, "diagnostic data must be a Hash" unless data.is_a?(Hash)
+
+        @kind = kind
+        @data = EventSanitizer.data(data)
+        freeze
+      end
+
+      # @rbs () -> Hash[String, EventSanitizer::json_value]
+      def to_h
+        @data
+      end
+    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:, syntax_root:, diagnostics:, expected_tokens:, metrics:, status:)
+        raise ArgumentError, "revision must be a nonnegative Integer" unless revision.is_a?(Integer) && revision >= 0
+        unless diagnostics.is_a?(Array) && diagnostics.all?(SyntaxSessionDiagnostic)
+          raise ArgumentError, "diagnostics must contain only SyntaxSessionDiagnostic values"
+        end
+        unless expected_tokens.is_a?(Array) && expected_tokens.all?(String)
+          raise ArgumentError, "expected_tokens must contain only Strings"
+        end
+        unless metrics.is_a?(SyntaxSessionMetrics)
+          raise ArgumentError, "metrics must be an Ibex::Runtime::SyntaxSessionMetrics"
+        end
+        raise ArgumentError, "status must be :ok or :syntax_error" unless %i[ok syntax_error].include?(status)
+
+        @revision = revision
+        @syntax_root = syntax_root
+        @diagnostics = diagnostics.dup.freeze
+        @expected_tokens = expected_tokens.map { |token| token.dup.freeze }.freeze
+        @metrics = metrics
+        @status = status
+        freeze
+      end
+
+      # @rbs () -> bool
+      def success?
+        @status == :ok
+      end
+    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 = :trusted_application_code #: 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(
+        parser_class,
+        source,
+        execution_profile:,
+        resource_limits: nil,
+        limits: nil,
+        cancellation: nil,
+        blender: true
+      )
+        @execution_profile = validate_execution_profile(parser_class, execution_profile)
+        @limits = limits || SyntaxSessionLimits.new #: SyntaxSessionLimits
+        unless @limits.is_a?(SyntaxSessionLimits)
+          raise ArgumentError, "limits must be an Ibex::Runtime::SyntaxSessionLimits"
+        end
+        unless cancellation.nil? || cancellation.is_a?(CancellationToken)
+          raise ArgumentError, "cancellation must be an Ibex::Runtime::CancellationToken or nil"
+        end
+
+        @cancellation = cancellation #: CancellationToken?
+        @parser_class = parser_class #: Class
+        @resource_limits = resource_limits || ResourceLimits.new #: ResourceLimits
+        @mutex = Mutex.new #: Mutex
+        @revision = 0 #: Integer
+        @operation_expected_tokens = [] #: Array[String]
+        @operation_fallback_reasons = [] #: Array[Symbol]
+
+        source_text = normalize_source(source)
+        enforce_limit!(:source_bytes, @limits.max_source_bytes, source_text.bytesize)
+        cancellation_checkpoint!
+        event_observer = ->(event, parser) { handle_runtime_event(event, parser) } #: Proc
+        @incremental = CST::IncrementalParseSession.new(
+          parser_class,
+          source_text,
+          resource_limits: @resource_limits,
+          blender: blender,
+          event_observer: event_observer
+        ) #: CST::IncrementalParseSession
+        @result = snapshot(@incremental.result) #: SyntaxSessionResult
+      rescue ResourceLimitError => e
+        raise SyntaxSessionResourceLimitError.new(resource: e.resource, limit: e.limit, observed: e.observed), cause: e
+      end
+
+      # @rbs () -> CST::SourceText
+      def source_text
+        @mutex.synchronize { @incremental.source_text }
+      end
+
+      # @rbs () -> SyntaxSessionResult
+      def result
+        @mutex.synchronize { @result }
+      end
+
+      # Apply byte-oriented edits against the current source.
+      # @rbs (Array[CST::TextEdit] edits) -> SyntaxSessionResult
+      def apply_edits(edits)
+        @mutex.synchronize { apply_edits_locked(edits) }
+      end
+
+      # 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.new, token_text: {})
+        @mutex.synchronize do
+          SyntaxRepairer.new(
+            @parser_class, @incremental.source_text, @result,
+            execution_profile: @execution_profile, resource_limits: @resource_limits,
+            limits: @limits, cancellation: @cancellation, policy: policy, token_text: token_text
+          ).call
+        end
+      end
+
+      private
+
+      # @rbs (Array[CST::TextEdit] edits) -> SyntaxSessionResult
+      def apply_edits_locked(edits)
+        raise ArgumentError, "edits must be an Array" unless edits.is_a?(Array)
+
+        cancellation_checkpoint!
+        enforce_limit!(:edits_per_operation, @limits.max_edits_per_operation, edits.length)
+        normalized = CST::TextEdit.normalize(edits)
+        inserted_bytes = normalized.sum { |edit| edit.insert_text.bytesize }
+        enforce_limit!(:inserted_bytes, @limits.max_inserted_bytes, inserted_bytes)
+        next_source = @incremental.source_text.apply(normalized)
+        enforce_limit!(:source_bytes, @limits.max_source_bytes, next_source.bytesize)
+        return @result if normalized.empty?
+
+        reset_operation_evidence
+        parsed = @incremental.edit(normalized)
+        @revision += 1
+        @result = snapshot(parsed)
+      rescue ResourceLimitError => e
+        raise SyntaxSessionResourceLimitError.new(resource: e.resource, limit: e.limit, observed: e.observed), cause: e
+      end
+
+      # @rbs (Class parser_class, Symbol? acknowledged) -> Symbol
+      def validate_execution_profile(parser_class, acknowledged)
+        unless parser_class.is_a?(Class) && parser_class <= Parser
+          raise ArgumentError, "parser_class must inherit from Ibex::Runtime::Parser"
+        end
+
+        profile = parser_class.syntax_execution_profile
+        unless profile == TRUSTED_PROFILE
+          raise SyntaxSessionTrustError,
+                "declarative syntax artifacts are not available; generated parser profile was #{profile.inspect}"
+        end
+        return profile if acknowledged == profile
+
+        raise SyntaxSessionTrustError,
+              "syntax_session executes generated lexer actions; " \
+              "pass execution_profile: #{profile.inspect} to acknowledge it"
+      end
+
+      # @rbs (String | CST::SourceText source) -> CST::SourceText
+      def normalize_source(source)
+        return source if source.is_a?(CST::SourceText)
+        raise ArgumentError, "source must be a String or Ibex::Runtime::CST::SourceText" unless source.is_a?(String)
+        unless source.encoding.ascii_compatible?
+          raise Encoding::CompatibilityError, "syntax session source must use an ASCII-compatible encoding"
+        end
+
+        CST::SourceText.new(source)
+      end
+
+      # @rbs (Symbol resource, Integer limit, Integer observed) -> void
+      def enforce_limit!(resource, limit, observed)
+        return unless observed > limit
+
+        raise SyntaxSessionResourceLimitError.new(resource: resource, limit: limit, observed: observed)
+      end
+
+      # @rbs () -> void
+      def cancellation_checkpoint!
+        return unless @cancellation&.cancelled?
+
+        raise SyntaxSessionCancelled, "syntax session operation was cancelled"
+      end
+
+      # @rbs (Event event, Parser parser) -> void
+      def handle_runtime_event(event, parser)
+        cancellation_checkpoint!
+        case event.type
+        when :error
+          parser.expected_tokens.each do |token|
+            @operation_expected_tokens << token unless @operation_expected_tokens.include?(token)
+          end
+        when :cst_fallback
+          @operation_fallback_reasons << event.data.fetch("reason").to_s.to_sym
+        end
+      end
+
+      # @rbs () -> void
+      def reset_operation_evidence
+        @operation_expected_tokens = [] #: Array[String]
+        @operation_fallback_reasons = [] #: Array[Symbol]
+      end
+
+      # @rbs (CST::SyntaxResult parsed) -> SyntaxSessionResult
+      def snapshot(parsed)
+        token_count = @incremental.token_memo.tokens.length
+        reused_tokens = if @incremental.last_full_fallback?
+                          0
+                        else
+                          @incremental.last_relex_result&.reused_count.to_i
+                        end
+        metrics = SyntaxSessionMetrics.new(
+          reused_ratio: parsed.reused_ratio,
+          reused_tokens: reused_tokens,
+          token_count: token_count,
+          fallback_reasons: @operation_fallback_reasons
+        )
+        SyntaxSessionResult.new(
+          revision: @revision,
+          syntax_root: parsed.syntax_root,
+          diagnostics: immutable_diagnostics(parsed.diagnostics),
+          expected_tokens: @operation_expected_tokens,
+          metrics: metrics,
+          status: parsed.diagnostics.empty? ? :ok : :syntax_error
+        )
+      end
+
+      # @rbs (Array[Object?] diagnostics) -> Array[SyntaxSessionDiagnostic]
+      def immutable_diagnostics(diagnostics)
+        diagnostics.map do |diagnostic|
+          if diagnostic.is_a?(ParseError)
+            SyntaxSessionDiagnostic.new(
+              kind: :parse_error,
+              data: {
+                message: diagnostic.message,
+                token_id: diagnostic.token_id,
+                token_name: diagnostic.token_name,
+                expected_tokens: diagnostic.expected_tokens,
+                location: EventSanitizer.location(diagnostic.location)
+              }
+            )
+          else
+            data = diagnostic.is_a?(Hash) ? diagnostic : { message: diagnostic.to_s }
+            SyntaxSessionDiagnostic.new(kind: :syntax_error, data: data)
+          end
+        end.freeze
+      end
+    end
+  end
+end

data/lib/ibex/runtime/table_format.rb

@@ -6,6 +6,6 @@ module Ibex
     # Current parser-table shape emitted by the generator.
     PARSER_TABLE_FORMAT_VERSION = 6 #: Integer
     # Parser-table shapes this runtime can execute.
-    SUPPORTED_PARSER_TABLE_FORMAT_VERSIONS = [1, 2, 3, 4, 5, PARSER_TABLE_FORMAT_VERSION].freeze #: Array[Integer]
+    SUPPORTED_PARSER_TABLE_FORMAT_VERSIONS = [PARSER_TABLE_FORMAT_VERSION].freeze #: Array[Integer]
   end
 end

data/lib/ibex/runtime/version.rb

@@ -2,6 +2,6 @@
 
 module Ibex
   module Runtime
-    VERSION = "0.2.0"
+    VERSION = "0.4.0"
   end
 end

data/lib/ibex/runtime.rb

@@ -11,14 +11,15 @@ require_relative "runtime/observation"
 require_relative "runtime/cst"
 require_relative "runtime/ast_data"
 require_relative "runtime/resource_limits"
+require_relative "runtime/syntax_session"
 require_relative "runtime/repair"
 require_relative "runtime/repair_priority_queue"
 require_relative "runtime/repair_search"
+require_relative "runtime/syntax_repair"
 require_relative "runtime/parser_sync_recovery"
 require_relative "runtime/parser"
 require_relative "runtime/lexer_input"
 require_relative "runtime/generated_lexer"
-require_relative "runtime/jsonl_tracer"
 require_relative "runtime/event_jsonl_tracer"
 
 module Ibex

data/lib/ibex/tables/compact.rb

@@ -6,8 +6,6 @@ module Ibex
     # Encodes nonnegative integer arrays into compact generated-source
     # literals. Zero represents nil; positive values are offset by one.
     module PackedIntegers
-      module_function
-
       # @rbs (Array[Integer?] values) -> String
       def encode(values)
         encoded = values.map do |value|
@@ -58,6 +56,12 @@ module Ibex
           value.even? ? value / 2 : -((value + 1) / 2)
         end
       end
+
+      module_function :encode
+      module_function :decode
+      module_function :decode_required
+      module_function :encode_signed
+      module_function :decode_signed
     end
 
     # Sparse table represented by per-row offsets and ownership checks.
@@ -65,17 +69,17 @@ module Ibex
       DENSE_CELL_LIMIT = 1_000_000 #: Integer
 
       attr_reader :offsets #: Array[Integer]
-      attr_reader :values #: Array[untyped]
+      attr_reader :values #: Array[Object?]
       attr_reader :checks #: Array[Integer?]
       attr_reader :row_count #: Integer
-      attr_reader :dense_values #: Array[untyped]?
+      attr_reader :dense_values #: Array[Object?]?
       attr_reader :dense_width #: Integer?
 
       class << self
-        # @rbs (Array[Hash[Integer, untyped]] rows, ?dense: bool) -> Compact
+        # @rbs (Array[Hash[Integer, Object?]] rows, ?dense: bool) -> Compact
         def build(rows, dense: true)
           offsets = Array.new(rows.length, 0)
-          values = [] #: Array[untyped]
+          values = [] #: Array[Object?]
           checks = [] #: Array[Integer?]
           next_offsets = {} #: Hash[Array[Integer], Integer]
           rows.each_index.sort_by { |row| [-rows[row].length, row] }.each do |row|
@@ -121,7 +125,7 @@ module Ibex
         end
       end
 
-      # @rbs (offsets: Array[Integer], values: Array[untyped], checks: Array[Integer?],
+      # @rbs (offsets: Array[Integer], values: Array[Object?], checks: Array[Integer?],
       #   row_count: Integer, ?dense_width: Integer?) -> void
       def initialize(offsets:, values:, checks:, row_count:, dense_width: nil)
         @offsets = offsets.freeze
@@ -136,7 +140,7 @@ module Ibex
       # Keep predicate dispatch out of this lookup because every parser action
       # and goto crosses it.
       # rubocop:disable Style/NumericPredicate
-      # @rbs (Integer row, Integer column) -> untyped
+      # @rbs (Integer row, Integer column) -> Object?
       def lookup(row, column)
         return nil if row < 0 || row >= @row_count || column < 0
 
@@ -147,11 +151,11 @@ module Ibex
       end
       # rubocop:enable Style/NumericPredicate
 
-      # @rbs (Integer row) -> Hash[Integer, untyped]
+      # @rbs (Integer row) -> Hash[Integer, Object?]
       def row(row)
         return {} unless row.between?(0, @row_count - 1)
 
-        result = {} #: Hash[Integer, untyped]
+        result = {} #: Hash[Integer, Object?]
         @checks.each_index do |index|
           next unless @checks[index] == row
 
@@ -162,13 +166,13 @@ module Ibex
 
       private
 
-      # @rbs (Integer? dense_width) -> Array[untyped]?
+      # @rbs (Integer? dense_width) -> Array[Object?]?
       def dense_layout(dense_width)
         return nil unless dense_width
         raise ArgumentError, "compact dense width must be positive" unless dense_width.positive?
         return nil if (@row_count * dense_width) > DENSE_CELL_LIMIT
 
-        dense = Array.new(@row_count * dense_width) #: Array[untyped]
+        dense = Array.new(@row_count * dense_width) #: Array[Object?]
         @checks.each_index do |index|
           row = @checks[index]
           next unless row

data/lib/ibex/tables/compact_actions.rb

@@ -12,27 +12,24 @@ module Ibex
       ERROR_CODE = -1 #: Integer
       SHIFT_BASE = 1 #: Integer
       REDUCE_BASE = -2 #: Integer
-      LEGACY_ERROR_CODE = 1 #: Integer
-      LEGACY_SHIFT_BASE = 2 #: Integer
-      LEGACY_REDUCE_BASE = 3 #: Integer
-      private_constant :LEGACY_ERROR_CODE, :LEGACY_SHIFT_BASE, :LEGACY_REDUCE_BASE
 
       attr_reader :codes #: Array[Integer?]
       attr_reader :dense_codes #: Array[Integer?]?
       attr_reader :column_count #: Integer?
 
       class << self
-        # @rbs (Array[Hash[Integer, untyped]] rows) -> CompactActions
+        # @rbs (Array[Hash[Integer, IR::runtime_action]] rows) -> CompactActions
         def build(rows)
           packed_rows = rows.map do |row|
             row.transform_values { |action| pack(action) }
           end
           layout = Compact.build(packed_rows, dense: false)
+          codes = layout.values #: Array[Integer?]
           column_count = rows.flat_map(&:keys).max.to_i + 1
           column_count = nil if (rows.length * column_count) > Compact::DENSE_CELL_LIMIT
           new(
             offsets: layout.offsets,
-            codes: layout.values,
+            codes: codes,
             checks: layout.checks,
             row_count: layout.row_count,
             encoding: :signed,
@@ -42,10 +39,14 @@ module Ibex
 
         # @rbs (String offsets, String codes, String checks, row_count: Integer,
         #   ?encoding: Symbol, ?column_count: Integer?) -> CompactActions
-        def packed(offsets, codes, checks, row_count:, encoding: :legacy, column_count: nil)
+        def packed(offsets, codes, checks, row_count:, encoding: :signed, column_count: nil)
+          unless encoding == :signed
+            raise ArgumentError, "unknown compact action encoding #{encoding.inspect}; expected :signed"
+          end
+
           new(
             offsets: PackedIntegers.decode_required(offsets),
-            codes: encoding == :signed ? PackedIntegers.decode_signed(codes) : PackedIntegers.decode(codes),
+            codes: PackedIntegers.decode_signed(codes),
             checks: PackedIntegers.decode(checks),
             row_count: row_count,
             encoding: encoding,
@@ -53,60 +54,71 @@ module Ibex
           )
         end
 
-        # @rbs (untyped action) -> Integer?
+        # @rbs (IR::runtime_action? action) -> Integer?
         def pack(action)
           return unless action
 
           case action.fetch(0)
           when :accept then ACCEPT_CODE
           when :error then ERROR_CODE
-          when :shift then SHIFT_BASE + action.fetch(1)
-          when :reduce then REDUCE_BASE - action.fetch(1)
+          when :shift
+            state = action.fetch(1) #: Integer
+            SHIFT_BASE + state
+          when :reduce
+            production = action.fetch(1) #: Integer
+            REDUCE_BASE - production
           else raise ArgumentError, "unknown compact parser action #{action.inspect}"
           end
         end
 
-        # @rbs (Integer? code) -> untyped
+        # @rbs (Integer? code) -> IR::runtime_action?
         def unpack(code)
           return unless code
-          return [:accept].freeze if code == ACCEPT_CODE
-          return [:error].freeze if code == ERROR_CODE
-          return [:shift, code - SHIFT_BASE].freeze if code.positive?
-
-          [:reduce, REDUCE_BASE - code].freeze
-        end
 
-        # Convert codes emitted before signed compact actions without changing
-        # their generated table literals.
-        # @rbs (Integer? code) -> Integer?
-        def legacy_to_signed(code)
-          return unless code
-          return ACCEPT_CODE if code == ACCEPT_CODE
-          return ERROR_CODE if code == LEGACY_ERROR_CODE
-          return SHIFT_BASE + ((code - LEGACY_SHIFT_BASE) / 2) if code.even?
+          if code == ACCEPT_CODE
+            accept = [:accept].freeze #: [:accept]
+            return accept
+          end
+          if code == ERROR_CODE
+            error = [:error].freeze #: [:error]
+            return error
+          end
+          if code.positive?
+            shift = [:shift, code - SHIFT_BASE].freeze #: [:shift, Integer]
+            return shift
+          end
 
-          REDUCE_BASE - ((code - LEGACY_REDUCE_BASE) / 2)
+          [:reduce, REDUCE_BASE - code].freeze #: [:reduce, Integer]
         end
       end
 
       # @rbs (offsets: Array[Integer], codes: Array[Integer?], checks: Array[Integer?],
       #   row_count: Integer, ?encoding: Symbol, ?column_count: Integer?) -> void
-      def initialize(offsets:, codes:, checks:, row_count:, encoding: :legacy, column_count: nil)
-        codes = codes.map { |code| self.class.legacy_to_signed(code) } if encoding == :legacy
-        unless %i[legacy signed].include?(encoding)
-          raise ArgumentError, "unknown compact action encoding #{encoding.inspect}"
+      def initialize(offsets:, codes:, checks:, row_count:, encoding: :signed, column_count: nil)
+        unless encoding == :signed
+          raise ArgumentError, "unknown compact action encoding #{encoding.inspect}; expected :signed"
         end
 
         @codes = codes.freeze
         @column_count = column_count
         @dense_codes = dense_action_layout(offsets, codes, checks, row_count, column_count)
-        decoded_cache = {} #: Hash[Integer, untyped]
+        decoded_cache = {} #: Hash[Integer, IR::runtime_action]
         decoded = codes.map do |code|
-          code.nil? ? nil : decoded_cache[code] ||= self.class.unpack(code)
+          next unless code
+
+          unpacked = self.class.unpack(code) #: IR::runtime_action
+          decoded_cache[code] ||= unpacked
         end
         super(offsets: offsets, values: decoded, checks: checks, row_count: row_count)
       end
 
+      # @rbs (Integer row) -> Hash[Integer, IR::runtime_action]
+      # rubocop:disable Lint/UselessMethodDefinition -- narrows the inherited row contract for typed parser actions.
+      def row(row)
+        super #: Hash[Integer, IR::runtime_action]
+      end
+      # rubocop:enable Lint/UselessMethodDefinition
+
       private
 
       # @rbs (Array[Integer] offsets, Array[Integer?] codes, Array[Integer?] checks,