ibex 0.1.0 → 0.3.0

data/lib/ibex/table_artifact/validator/tables.rb

@@ -0,0 +1,238 @@
+# frozen_string_literal: true
+
+module Ibex
+  module TableArtifact
+    class TableValidator
+      include ValidationSupport
+
+      # @rbs!
+      #   private def integer_array: (ValidationSupport::json_value value, String path,
+      #     allow_nil: false, minimum: Integer?) -> Array[Integer]
+      #                            | (ValidationSupport::json_value value, String path,
+      #     allow_nil: true, minimum: Integer?) -> Array[Integer?]
+
+      # @rbs (Hash[String, ValidationSupport::json_value] data, state_count: Integer, production_count: Integer,
+      #   terminal_ids: Set[Integer], nonterminal_ids: Set[Integer], representation: String) -> void
+      def initialize(data, state_count:, production_count:, terminal_ids:, nonterminal_ids:, representation:)
+        @data = data
+        @state_count = state_count
+        @production_count = production_count
+        @terminal_ids = terminal_ids
+        @nonterminal_ids = nonterminal_ids
+        @representation = representation
+      end
+
+      # @rbs () -> void
+      def validate!
+        record(@data, "$.payload.tables", %w[actions gotos default_actions])
+        validate_actions(@data.fetch("actions"))
+        validate_gotos(@data.fetch("gotos"))
+        validate_defaults(@data.fetch("default_actions"))
+      end
+
+      private
+
+      # @rbs (ValidationSupport::json_value table) -> void
+      def validate_actions(table)
+        invalid("$.payload.tables.actions", "must be an object") unless table.is_a?(Hash)
+        table_data = table #: Hash[String, ValidationSupport::json_value]
+        encoding = table_data["encoding"]
+        expected = @representation == "compact" ? "signed-row-displacement-v1" : "signed-sparse-rows-v1"
+        invalid("$.payload.tables.actions.encoding", "does not match table representation") unless encoding == expected
+        case encoding
+        when "signed-sparse-rows-v1" then validate_sparse_actions(table_data)
+        when "signed-row-displacement-v1" then validate_compact_actions(table_data)
+        else invalid("$.payload.tables.actions.encoding", "is unsupported")
+        end
+      end
+
+      # @rbs (Hash[String, ValidationSupport::json_value] table) -> void
+      def validate_sparse_actions(table)
+        record(table, "$.payload.tables.actions", %w[encoding rows])
+        rows = array(table.fetch("rows"), "$.payload.tables.actions.rows")
+        invalid("$.payload.tables.actions.rows", "must contain one row per state") unless rows.length == @state_count
+        rows.each_with_index do |row, state|
+          token_ids = array(row, "$.payload.tables.actions.rows[#{state}]").map.with_index do |cell, index|
+            path = "$.payload.tables.actions.rows[#{state}][#{index}]"
+            cell = record(cell, path, %w[token_id code])
+            token_id = integer(cell.fetch("token_id"), "#{path}.token_id", minimum: 0)
+            invalid("#{path}.token_id", "must reference a terminal") unless @terminal_ids.include?(token_id)
+            validate_token_action(cell.fetch("code"), token_id, "#{path}.code")
+            token_id
+          end
+          sorted_unique!(token_ids, "$.payload.tables.actions.rows[#{state}]")
+        end
+      end
+
+      # @rbs (Hash[String, ValidationSupport::json_value] table) -> void
+      def validate_compact_actions(table)
+        keys = %w[encoding row_count column_count offsets codes checks]
+        record(table, "$.payload.tables.actions", keys)
+        enum(table.fetch("encoding"), "$.payload.tables.actions.encoding", ["signed-row-displacement-v1"])
+        validate_row_count(table, "$.payload.tables.actions")
+        column_count = nullable_integer(table.fetch("column_count"), "$.payload.tables.actions.column_count",
+                                        minimum: 1)
+        rows = validate_displacement(table, value_key: "codes", path: "$.payload.tables.actions") do |column, code,
+                                                                                                         cell_path|
+          invalid(cell_path, "column must reference a terminal") unless @terminal_ids.include?(column)
+          invalid(cell_path, "column exceeds column_count") if column_count && column >= column_count
+          validate_token_action(code, column, "#{cell_path}.code")
+        end
+        validate_canonical_displacement(
+          table, rows, value_key: "codes", width_key: "column_count", width: column_count, dense: false,
+                       path: "$.payload.tables.actions"
+        )
+      end
+
+      # @rbs (ValidationSupport::json_value table) -> void
+      def validate_gotos(table)
+        invalid("$.payload.tables.gotos", "must be an object") unless table.is_a?(Hash)
+        table_data = table #: Hash[String, ValidationSupport::json_value]
+        encoding = table_data["encoding"]
+        expected = @representation == "compact" ? "row-displacement-v1" : "sparse-rows-v1"
+        invalid("$.payload.tables.gotos.encoding", "does not match table representation") unless encoding == expected
+        case encoding
+        when "sparse-rows-v1" then validate_sparse_gotos(table_data)
+        when "row-displacement-v1" then validate_compact_gotos(table_data)
+        else invalid("$.payload.tables.gotos.encoding", "is unsupported")
+        end
+      end
+
+      # @rbs (Hash[String, ValidationSupport::json_value] table) -> void
+      def validate_sparse_gotos(table)
+        record(table, "$.payload.tables.gotos", %w[encoding rows])
+        rows = array(table.fetch("rows"), "$.payload.tables.gotos.rows")
+        invalid("$.payload.tables.gotos.rows", "must contain one row per state") unless rows.length == @state_count
+        rows.each_with_index do |row, state|
+          symbol_ids = array(row, "$.payload.tables.gotos.rows[#{state}]").map.with_index do |cell, index|
+            path = "$.payload.tables.gotos.rows[#{state}][#{index}]"
+            cell = record(cell, path, %w[symbol_id state])
+            symbol_id = integer(cell.fetch("symbol_id"), "#{path}.symbol_id", minimum: 0)
+            invalid("#{path}.symbol_id", "must reference a nonterminal") unless @nonterminal_ids.include?(symbol_id)
+            validate_state(cell.fetch("state"), "#{path}.state")
+            symbol_id
+          end
+          sorted_unique!(symbol_ids, "$.payload.tables.gotos.rows[#{state}]")
+        end
+      end
+
+      # @rbs (Hash[String, ValidationSupport::json_value] table) -> void
+      def validate_compact_gotos(table)
+        keys = %w[encoding row_count dense_width offsets values checks]
+        record(table, "$.payload.tables.gotos", keys)
+        enum(table.fetch("encoding"), "$.payload.tables.gotos.encoding", ["row-displacement-v1"])
+        validate_row_count(table, "$.payload.tables.gotos")
+        dense_width = nullable_integer(table.fetch("dense_width"), "$.payload.tables.gotos.dense_width", minimum: 1)
+        rows = validate_displacement(table, value_key: "values", path: "$.payload.tables.gotos") do |column, state,
+                                                                                                         cell_path|
+          invalid(cell_path, "column must reference a nonterminal") unless @nonterminal_ids.include?(column)
+          invalid(cell_path, "column exceeds dense_width") if dense_width && column >= dense_width
+          validate_state(state, "#{cell_path}.state")
+        end
+        validate_canonical_displacement(
+          table, rows, value_key: "values", width_key: "dense_width", width: dense_width, dense: true,
+                       path: "$.payload.tables.gotos"
+        )
+      end
+
+      # @rbs (Hash[String, ValidationSupport::json_value] table, String path) -> void
+      def validate_row_count(table, path)
+        count = integer(table.fetch("row_count"), "#{path}.row_count", minimum: 1)
+        invalid("#{path}.row_count", "must equal state_count") unless count == @state_count
+      end
+
+      # @rbs (Hash[String, ValidationSupport::json_value] table, value_key: String, path: String)
+      #   { (Integer, ValidationSupport::json_value, String) -> void } -> Array[Hash[Integer, ValidationSupport::json_value]]
+      def validate_displacement(table, value_key:, path:)
+        offsets = integer_array(table.fetch("offsets"), "#{path}.offsets", allow_nil: false, minimum: 0)
+        invalid("#{path}.offsets", "must contain one offset per state") unless offsets.length == @state_count
+        minimum = value_key == "codes" ? nil : 0
+        values = integer_array(table.fetch(value_key), "#{path}.#{value_key}", allow_nil: true, minimum: minimum)
+        checks = integer_array(table.fetch("checks"), "#{path}.checks", allow_nil: true, minimum: 0)
+        invalid(path, "#{value_key} and checks must have equal length") unless values.length == checks.length
+
+        rows = Array.new(@state_count) { {} } #: Array[Hash[Integer, ValidationSupport::json_value]]
+        checks.each_index do |index|
+          row = checks[index]
+          value = values[index]
+          invalid("#{path}[#{index}]", "value and check occupancy must match") unless row.nil? == value.nil?
+          next unless row
+
+          invalid("#{path}.checks[#{index}]", "references a missing state") unless row.between?(0, @state_count - 1)
+          column = index - offsets.fetch(row)
+          invalid("#{path}[#{index}]", "has a negative column") if column.negative?
+          yield(column, value, "#{path}[#{index}]")
+          rows.fetch(row)[column] = value
+        end
+        rows
+      end
+
+      # @rbs (Hash[String, ValidationSupport::json_value] table,
+      #   Array[Hash[Integer, ValidationSupport::json_value]] rows, value_key: String,
+      #   width_key: String, width: Integer?, dense: bool, path: String) -> void
+      def validate_canonical_displacement(table, rows, value_key:, width_key:, width:, dense:, path:)
+        canonical = Tables::Compact.build(rows, dense: dense)
+        expected = [canonical.offsets, canonical.values, canonical.checks]
+        actual = [table.fetch("offsets"), table.fetch(value_key), table.fetch("checks")]
+        invalid(path, "must use the canonical minimal row-displacement layout") unless actual == expected
+
+        expected_width = if width_key == "column_count"
+                           rows.flat_map(&:keys).max.to_i + 1
+                         else
+                           canonical.dense_width
+                         end
+        expected_width = nil if expected_width && (@state_count * expected_width) > Tables::Compact::DENSE_CELL_LIMIT
+        invalid("#{path}.#{width_key}", "does not match the canonical table width") unless width == expected_width
+      end
+
+      # @rbs skip
+      def integer_array(value, path, allow_nil:, minimum:)
+        array(value, path).map.with_index do |item, index|
+          next if allow_nil && item.nil?
+
+          integer(item, "#{path}[#{index}]", minimum: minimum)
+        end
+      end
+
+      # @rbs (ValidationSupport::json_value defaults) -> void
+      def validate_defaults(defaults)
+        values = array(defaults, "$.payload.tables.default_actions")
+        unless values.length == @state_count
+          invalid("$.payload.tables.default_actions",
+                  "must contain one entry per state")
+        end
+        values.each_with_index do |code, state|
+          next if code.nil?
+
+          path = "$.payload.tables.default_actions[#{state}]"
+          code = integer(code, path)
+          invalid(path, "must be an error or reduction") if code >= 0
+        end
+      end
+
+      # @rbs (ValidationSupport::json_value code, Integer token_id, String path) -> void
+      def validate_token_action(code, token_id, path)
+        code = integer(code, path)
+        invalid(path, "accept is only valid for $eof") if code.zero? && !token_id.zero?
+        invalid(path, "$eof cannot be shifted") if token_id.zero? && code.positive?
+        validate_action_code(code, path)
+      end
+
+      # @rbs (ValidationSupport::json_value code, String path) -> void
+      def validate_action_code(code, path)
+        code = integer(code, path)
+        return if [0, -1].include?(code)
+        return validate_state(code - 1, path) if code.positive?
+
+        production = -2 - code
+        invalid(path, "references a missing production") unless production.between?(0, @production_count - 1)
+      end
+
+      # @rbs (ValidationSupport::json_value state, String path) -> void
+      def validate_state(state, path)
+        state = integer(state, path, minimum: 0)
+        invalid(path, "references a missing state") unless state.between?(0, @state_count - 1)
+      end
+    end
+  end
+end

data/lib/ibex/table_artifact/validator.rb

@@ -0,0 +1,253 @@
+# frozen_string_literal: true
+
+require_relative "validator/support"
+require_relative "validator/tables"
+require_relative "validator/metadata"
+
+module Ibex
+  module TableArtifact
+    # Closed structural and referential validation for untrusted sidecars.
+    class Validator
+      include ValidationSupport
+
+      ROOT_KEYS = %w[artifact_type schema_version identity payload cost].freeze #: Array[String]
+      PAYLOAD_KEYS = %w[
+        table_format source state_count symbols tokens entry_states tables productions cst recovery semantic_actions
+      ].freeze #: Array[String]
+
+      class << self
+        # @rbs (Hash[String, ValidationSupport::json_value] data) -> true
+        def validate!(data)
+          new(data).validate!
+        end
+      end
+
+      # @rbs (Hash[String, ValidationSupport::json_value] data) -> void
+      def initialize(data)
+        @data = data
+      end
+
+      # rubocop:disable Naming/PredicateMethod -- bang denotes fail-fast validation.
+      # @rbs () -> true
+      def validate!
+        record(@data, "$", ROOT_KEYS)
+        payload = record(@data.fetch("payload"), "$.payload", PAYLOAD_KEYS)
+        validate_root_identity
+        representation = validate_table_format(payload.fetch("table_format"))
+        validate_source(payload.fetch("source"))
+        state_count = integer(payload.fetch("state_count"), "$.payload.state_count", minimum: 1)
+        symbols = validate_symbols(payload.fetch("symbols"))
+        validate_tokens(payload.fetch("tokens"), symbols)
+        validate_entries(payload.fetch("entry_states"), symbols, state_count)
+        productions = validate_productions(payload.fetch("productions"), symbols)
+        tables = payload.fetch("tables") #: Hash[String, ValidationSupport::json_value]
+        TableValidator.new(
+          tables,
+          state_count: state_count,
+          production_count: productions.length,
+          terminal_ids: symbol_ids(symbols, "terminal"),
+          nonterminal_ids: symbol_ids(symbols, "nonterminal"),
+          representation: representation
+        ).validate!
+        MetadataValidator.new(payload, symbols: symbols, productions: productions).validate!
+        validate_cost(@data.fetch("cost"), payload)
+        true
+      end
+      # rubocop:enable Naming/PredicateMethod
+
+      private
+
+      # @rbs () -> void
+      def validate_root_identity
+        invalid("$.artifact_type", "is unsupported") unless @data.fetch("artifact_type") == ARTIFACT_TYPE
+        invalid("$.schema_version", "is unsupported") unless @data.fetch("schema_version") == SCHEMA_VERSION
+        identity_keys = %w[
+          grammar_digest automaton_digest payload_digest cst_metadata_digest recovery_metadata_digest
+        ]
+        identity = record(@data.fetch("identity"), "$.identity", identity_keys)
+        identity.each { |key, value| digest(value, "$.identity.#{key}") }
+        expected = Serializer.digest(@data.fetch("payload"))
+        invalid("$.identity.payload_digest", "does not match the canonical payload") unless
+          identity.fetch("payload_digest") == expected
+        payload = @data.fetch("payload")
+        validate_named_digest(identity, payload, "cst_metadata", "cst")
+        validate_named_digest(identity, payload, "recovery_metadata", "recovery")
+      end
+
+      # @rbs (ValidationSupport::json_value data) -> String
+      def validate_table_format(data)
+        path = "$.payload.table_format"
+        keys = %w[family version representation action_encoding goto_encoding]
+        data = record(data, path, keys)
+        enum(data.fetch("family"), "#{path}.family", ["ibex-runtime-parser-table"])
+        invalid("#{path}.version", "must be 6") unless integer(data.fetch("version"), "#{path}.version") == 6
+        representation = enum(data.fetch("representation"), "#{path}.representation", %w[plain compact]) #: String
+        expected = if representation == "compact"
+                     %w[signed-row-displacement-v1 row-displacement-v1]
+                   else
+                     %w[signed-sparse-rows-v1 sparse-rows-v1]
+                   end
+        actual = [data.fetch("action_encoding"), data.fetch("goto_encoding")]
+        invalid(path, "encodings do not match representation") unless actual == expected
+        representation
+      end
+
+      # @rbs (ValidationSupport::json_value data) -> void
+      def validate_source(data)
+        source = record(data, "$.payload.source", %w[grammar_digest automaton_digest])
+        source.each { |key, value| digest(value, "$.payload.source.#{key}") }
+        identity = @data.fetch("identity")
+        invalid("$.payload.source", "must match root identity") unless
+          source.fetch("grammar_digest") == identity.fetch("grammar_digest") &&
+          source.fetch("automaton_digest") == identity.fetch("automaton_digest")
+      end
+
+      # @rbs (ValidationSupport::json_value data) -> Array[Hash[String, ValidationSupport::json_value]]
+      def validate_symbols(data)
+        symbols = array(data, "$.payload.symbols") #: Array[Hash[String, ValidationSupport::json_value]]
+        invalid("$.payload.symbols", "must not be empty") if symbols.empty?
+        names = [] #: Array[String]
+        symbols.each_with_index do |symbol, index|
+          path = "$.payload.symbols[#{index}]"
+          record(symbol, path, %w[id name kind display_name])
+          invalid("#{path}.id", "must be contiguous and ordered") unless symbol.fetch("id") == index
+          names << string(symbol.fetch("name"), "#{path}.name")
+          enum(symbol.fetch("kind"), "#{path}.kind", %w[terminal nonterminal])
+          nullable_string(symbol.fetch("display_name"), "#{path}.display_name")
+        end
+        invalid("$.payload.symbols", "names must be unique") unless names.uniq.length == names.length
+        symbols
+      end
+
+      # @rbs (ValidationSupport::json_value data, Array[Hash[String, ValidationSupport::json_value]] symbols) -> void
+      def validate_tokens(data, symbols)
+        tokens = array(data, "$.payload.tokens") #: Array[Hash[String, ValidationSupport::json_value]]
+        expected = symbols.select { |symbol| symbol.fetch("kind") == "terminal" }.map do |symbol|
+          symbol.slice("id", "name", "display_name")
+        end
+        tokens.each_with_index do |token, index|
+          record(token, "$.payload.tokens[#{index}]", %w[id name display_name])
+        end
+        invalid("$.payload.tokens", "must exactly index terminal symbols") unless tokens == expected
+        token_id = tokens.first&.fetch("id")
+        invalid("$.payload.tokens", "token id 0 must be $eof") unless token_id.is_a?(Integer) && token_id.zero? &&
+                                                                      tokens.first.fetch("name") == "$eof"
+      end
+
+      # @rbs (ValidationSupport::json_value data,
+      #   Array[Hash[String, ValidationSupport::json_value]] symbols, Integer state_count) -> void
+      def validate_entries(data, symbols, state_count)
+        entries = array(data, "$.payload.entry_states") #: Array[Hash[String, ValidationSupport::json_value]]
+        invalid("$.payload.entry_states", "must not be empty") if entries.empty?
+        names = entries.map.with_index do |entry, index|
+          path = "$.payload.entry_states[#{index}]"
+          record(entry, path, %w[name state])
+          name = string(entry.fetch("name"), "#{path}.name")
+          symbol = symbols.find { |candidate| candidate.fetch("name") == name }
+          invalid("#{path}.name", "must reference a nonterminal") unless symbol&.fetch("kind") == "nonterminal"
+          state = integer(entry.fetch("state"), "#{path}.state", minimum: 0)
+          invalid("#{path}.state", "references a missing state") unless state < state_count
+          name
+        end
+        invalid("$.payload.entry_states", "names must be unique") unless names.uniq.length == names.length
+      end
+
+      # @rbs (ValidationSupport::json_value data,
+      #   Array[Hash[String, ValidationSupport::json_value]] symbols) -> Array[Hash[String, ValidationSupport::json_value]]
+      def validate_productions(data, symbols)
+        productions = array(data, "$.payload.productions") #: Array[Hash[String, ValidationSupport::json_value]]
+        nonterminals = symbol_ids(symbols, "nonterminal")
+        productions.each_with_index do |production, index|
+          path = "$.payload.productions[#{index}]"
+          record(production, path, %w[id lhs rhs rhs_length action_slot])
+          invalid("#{path}.id", "must be contiguous and ordered") unless production.fetch("id") == index
+          lhs = integer(production.fetch("lhs"), "#{path}.lhs", minimum: 0)
+          invalid("#{path}.lhs", "must reference a nonterminal") unless nonterminals.include?(lhs)
+          rhs = array(production.fetch("rhs"), "#{path}.rhs")
+          rhs.each_with_index do |symbol_id, rhs_index|
+            symbol_id = integer(symbol_id, "#{path}.rhs[#{rhs_index}]", minimum: 0)
+            invalid("#{path}.rhs[#{rhs_index}]", "references a missing symbol") unless symbol_id < symbols.length
+          end
+          invalid("#{path}.rhs_length", "must match rhs") unless production.fetch("rhs_length") == rhs.length
+          slot = nullable_integer(production.fetch("action_slot"), "#{path}.action_slot", minimum: 0)
+          invalid("#{path}.action_slot", "must equal production id") if slot && slot != index
+        end
+        productions
+      end
+
+      # @rbs (ValidationSupport::json_value data, Hash[String, ValidationSupport::json_value] payload) -> void
+      def validate_cost(data, payload)
+        path = "$.cost"
+        keys = %w[
+          canonical_payload_bytes action_cells goto_cells lookup_cost recognition_cost measurement bounded_by_max_steps
+        ]
+        data = record(data, path, keys)
+        bytes = integer(data.fetch("canonical_payload_bytes"), "#{path}.canonical_payload_bytes", minimum: 1)
+        unless bytes == Serializer.compact(payload).bytesize
+          invalid("#{path}.canonical_payload_bytes",
+                  "does not match payload")
+        end
+        action_cells = integer(data.fetch("action_cells"), "#{path}.action_cells", minimum: 0)
+        goto_cells = integer(data.fetch("goto_cells"), "#{path}.goto_cells", minimum: 0)
+        tables = payload.fetch("tables") #: Hash[String, ValidationSupport::json_value]
+        actions = tables.fetch("actions") #: Hash[String, ValidationSupport::json_value]
+        gotos = tables.fetch("gotos") #: Hash[String, ValidationSupport::json_value]
+        invalid("#{path}.action_cells", "does not match actions") unless action_cells == occupied(actions, "codes")
+        invalid("#{path}.goto_cells", "does not match gotos") unless goto_cells == occupied(gotos, "values")
+        expected_lookup, expected_recognition = expected_costs(payload)
+        invalid("#{path}.lookup_cost", "does not match table representation") unless
+          data.fetch("lookup_cost") == expected_lookup
+        invalid("#{path}.recognition_cost", "does not match table representation") unless
+          data.fetch("recognition_cost") == expected_recognition
+        enum(data.fetch("measurement"), "#{path}.measurement", ["not-measured"])
+        invalid("#{path}.bounded_by_max_steps", "must be true") unless boolean(data.fetch("bounded_by_max_steps"),
+                                                                               "#{path}.bounded_by_max_steps")
+      end
+
+      # @rbs (Hash[String, ValidationSupport::json_value] payload) -> [String, String]
+      def expected_costs(payload)
+        table_format = payload.fetch("table_format") #: Hash[String, ValidationSupport::json_value]
+        compact = table_format.fetch("representation") == "compact"
+        lookup = compact ? "O(1) row-displacement probe" : "O(log row width) binary search"
+        recognition = if compact
+                        "O(input tokens + reductions)"
+                      else
+                        "O((input tokens + reductions) * log maximum row width)"
+                      end
+        [lookup, "#{recognition}; lexer, recovery search, and semantic actions excluded"]
+      end
+
+      # @rbs (Hash[String, ValidationSupport::json_value] table, String values_key) -> Integer
+      def occupied(table, values_key)
+        if table.key?("rows")
+          rows = table.fetch("rows") #: Array[Array[ValidationSupport::json_value]]
+          return rows.sum(&:length)
+        end
+
+        values = table.fetch(values_key) #: Array[ValidationSupport::json_value]
+        values.compact.length
+      end
+
+      # @rbs (Array[Hash[String, ValidationSupport::json_value]] symbols, String kind) -> Set[Integer]
+      def symbol_ids(symbols, kind)
+        symbols.filter_map do |symbol|
+          next unless symbol.fetch("kind") == kind
+
+          symbol.fetch("id") #: Integer
+        end.to_set
+      end
+
+      # @rbs (Hash[String, ValidationSupport::json_value] identity,
+      #   Hash[String, ValidationSupport::json_value] payload, String identity_name,
+      #   String payload_name) -> void
+      def validate_named_digest(identity, payload, identity_name, payload_name)
+        expected = Serializer.digest(payload.fetch(payload_name))
+        path = "$.identity.#{identity_name}_digest"
+        return if identity.fetch("#{identity_name}_digest") == expected
+
+        invalid(path,
+                "does not match payload #{payload_name}")
+      end
+    end
+  end
+end

data/lib/ibex/table_artifact.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+require "digest"
+require "json"
+require "set"
+require_relative "error"
+require_relative "ir"
+require_relative "tables"
+require_relative "runtime/table_format"
+require_relative "codegen/cst_metadata"
+require_relative "table_artifact/serializer"
+require_relative "table_artifact/validator"
+require_relative "table_artifact/document"
+require_relative "table_artifact/cst_projection"
+require_relative "table_artifact/builder"
+require_relative "table_artifact/executor"
+
+module Ibex
+  # Experimental data-only authority for executable parser tables.
+  module TableArtifact
+    # @rbs!
+    #   interface _Reader
+    #     def read: (Integer length) -> String?
+    #   end
+
+    ARTIFACT_TYPE = "ibex.parser-table" #: String
+    SCHEMA_VERSION = 1 #: Integer
+    DEFAULT_MAX_BYTES = 16 * 1024 * 1024 #: Integer
+
+    class ValidationError < Ibex::Error; end
+
+    class << self
+      # @rbs (IR::Automaton automaton, ?representation: Symbol | String, ?cst_trivia: Symbol | String?,
+      #   ?omit_action_call: bool?) -> Document
+      def build(automaton, representation: :compact, cst_trivia: nil, omit_action_call: nil)
+        Builder.new(
+          automaton,
+          representation: representation,
+          cst_trivia: cst_trivia,
+          omit_action_call: omit_action_call
+        ).build
+      end
+
+      # @rbs (String | _Reader source, ?max_bytes: Integer) -> Document
+      def load(source, max_bytes: DEFAULT_MAX_BYTES)
+        bytes = read_bounded(source, max_bytes)
+        unless bytes.dup.force_encoding(Encoding::UTF_8).valid_encoding?
+          raise ValidationError, "table artifact must be UTF-8 JSON"
+        end
+
+        Document.new(JSON.parse(bytes))
+      rescue JSON::ParserError => e
+        raise ValidationError, "invalid table artifact JSON: #{e.message}"
+      end
+
+      private
+
+      # @rbs (untyped source, Integer max_bytes) -> String
+      def read_bounded(source, max_bytes)
+        raise ArgumentError, "max_bytes must be positive" unless max_bytes.is_a?(Integer) && max_bytes.positive?
+
+        bytes = if source.respond_to?(:read)
+                  read_from(source, max_bytes)
+                else
+                  String(source)
+                end
+        raise ValidationError, "table artifact exceeds #{max_bytes} bytes" if bytes.bytesize > max_bytes
+
+        bytes
+      end
+
+      # @rbs (_Reader source, Integer max_bytes) -> String
+      def read_from(source, max_bytes)
+        bytes = +"".b
+        loop do
+          chunk = source.read((max_bytes + 1) - bytes.bytesize)
+          break if chunk.nil?
+          raise ValidationError, "table artifact reader must return strings" unless chunk.is_a?(String)
+          break if chunk.empty?
+
+          bytes << chunk
+          break if bytes.bytesize > max_bytes
+        end
+        bytes
+      end
+    end
+  end
+end

data/lib/ibex/table_simulation/result.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+require "json"
+
+module Ibex
+  module TableSimulation
+    # Final immutable simulation document.
+    class Result
+      # @rbs!
+      #   type step_document = Hash[String, Step::document_value]
+      #   type document_value = String | Integer | Array[String] | Array[step_document]
+
+      IDENTIFIER = "table-simulation" #: String
+      SCHEMA_VERSION = 1 #: Integer
+
+      attr_reader :grammar_digest #: String
+      attr_reader :algorithm #: String
+      attr_reader :tokens #: Array[String]
+      attr_reader :status #: Symbol
+      attr_reader :steps #: Array[Step]
+
+      # @rbs (grammar_digest: String, algorithm: String, tokens: Array[String], status: Symbol,
+      #   steps: Array[Step]) -> void
+      def initialize(grammar_digest:, algorithm:, tokens:, status:, steps:)
+        raise ArgumentError, "simulation status must be accepted or error" unless %i[accepted error].include?(status)
+
+        @grammar_digest = grammar_digest.dup.freeze
+        @algorithm = algorithm.dup.freeze
+        @tokens = tokens.map { |token| token.dup.freeze }.freeze
+        @status = status
+        @steps = steps.dup.freeze
+        freeze
+      end
+
+      # @rbs () -> Hash[String, document_value]
+      def to_h
+        {
+          "ibex_table_simulation" => IDENTIFIER,
+          "schema_version" => SCHEMA_VERSION,
+          "grammar_digest" => @grammar_digest,
+          "algorithm" => @algorithm,
+          "tokens" => @tokens,
+          "status" => @status.to_s,
+          "steps" => @steps.map(&:to_h)
+        }
+      end
+
+      # @rbs (*Object?) -> String
+      def to_json(*)
+        "#{JSON.pretty_generate(to_h)}\n"
+      end
+    end
+  end
+end