ibex 0.2.0 → 0.4.0

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

@@ -7,6 +7,10 @@ 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
 
@@ -29,7 +33,7 @@ module Ibex
         freeze
       end
 
-      # @rbs () -> Hash[String, untyped]
+      # @rbs () -> Hash[String, document_value]
       def to_h
         {
           "ibex_table_simulation" => IDENTIFIER,
@@ -42,7 +46,7 @@ module Ibex
         }
       end
 
-      # @rbs (*untyped) -> String
+      # @rbs (*Object?) -> String
       def to_json(*)
         "#{JSON.pretty_generate(to_h)}\n"
       end

data/lib/ibex/table_simulation/step.rb

@@ -5,6 +5,8 @@ module Ibex
   module TableSimulation
     # One immutable parser-table action.
     class Step
+      # @rbs! type document_value = String | Integer | nil
+
       attr_reader :sequence #: Integer
       attr_reader :state #: Integer
       attr_reader :token_id #: Integer
@@ -38,7 +40,7 @@ module Ibex
         freeze
       end
 
-      # @rbs () -> Hash[String, untyped]
+      # @rbs () -> Hash[String, document_value]
       def to_h
         {
           "sequence" => @sequence,

data/lib/ibex/tables.rb

@@ -8,11 +8,25 @@ module Ibex
   # Parser table construction and row-displacement compression.
   module Tables
     # @rbs!
+    #   type action_table = Array[Hash[Integer, IR::runtime_action]] | CompactActions
+    #   type goto_table = Array[Hash[Integer, Integer]] | Compact
     #   private def runtime_action: (IR::parser_action action) -> IR::runtime_action
     #   private def self.runtime_action: (IR::parser_action action) -> IR::runtime_action
 
+    # @rbs skip
     TableSet = Struct.new(:actions, :gotos, :default_actions, keyword_init: true)
 
+    # @rbs!
+    #   class TableSet < Struct[Object?]
+    #     attr_accessor actions: action_table
+    #     attr_accessor gotos: goto_table
+    #     attr_accessor default_actions: Array[IR::runtime_action?]
+    #     def self.new: (?actions: action_table, ?gotos: goto_table,
+    #       ?default_actions: Array[IR::runtime_action?]) -> instance
+    #                    | ({ ?actions: action_table, ?gotos: goto_table,
+    #       ?default_actions: Array[IR::runtime_action?] }) -> instance
+    #   end
+
     # @rbs (IR::Automaton automaton, ?format: Symbol | String) -> TableSet
     def build(automaton, format: :compact)
       action_rows = automaton.states.map do |state|

data/lib/ibex/verifiable_generation_bundle.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+require_relative "artifact_set"
+require_relative "generation_manifest"
+require_relative "generation_transaction"
+require_relative "table_artifact"
+require_relative "verification_report"
+
+module Ibex
+  # Explicitly renders and publishes one manifest-bound verification bundle.
+  class VerifiableGenerationBundle
+    # rubocop:disable Metrics/ParameterLists -- persisted artifact paths and verification bounds are explicit inputs.
+    # @rbs (IR::Automaton automaton, wrapper_path: String, wrapper_source: String,
+    #   table_path: String, report_path: String, manifest_path: String,
+    #   source_records: Array[GenerationInput], ?manifest_options: Hash[String, Object?],
+    #   ?wrapper_mode: Integer?, ?representation: Symbol | String, ?cst_trivia: Symbol | String?,
+    #   ?omit_action_call: bool?, ?strict: bool, ?max_states: Integer, ?max_items: Integer) -> void
+    def initialize(automaton, wrapper_path:, wrapper_source:, table_path:, report_path:, manifest_path:,
+                   source_records:, manifest_options: {}, wrapper_mode: nil, representation: :compact,
+                   cst_trivia: nil, omit_action_call: nil, strict: false,
+                   max_states: VerificationReport::DEFAULT_MAX_STATES,
+                   max_items: VerificationReport::DEFAULT_MAX_ITEMS)
+      @automaton = automaton
+      @wrapper_path = wrapper_path
+      @wrapper_source = wrapper_source
+      @table_path = table_path
+      VerificationReport::LogicalPath.table(table_path)
+      if source_records.length > VerificationReport::LogicalPath::MAX_INPUT_FILES
+        raise ArgumentError,
+              "verification reports support at most #{VerificationReport::LogicalPath::MAX_INPUT_FILES} input files"
+      end
+      @report_path = report_path
+      @manifest_path = manifest_path
+      @source_records = source_records
+      @manifest_options = manifest_options
+      @wrapper_mode = wrapper_mode
+      @representation = representation
+      @cst_trivia = cst_trivia
+      @omit_action_call = omit_action_call
+      @strict = strict
+      @max_states = max_states
+      @max_items = max_items
+    end
+    # rubocop:enable Metrics/ParameterLists
+
+    # Render table, wrapper, and report before the non-cyclic manifest marker.
+    # @rbs () -> ArtifactSet
+    def render
+      canonical_automaton = VerificationReport.canonical_automaton(
+        @automaton, source_records: @source_records
+      )
+      table = TableArtifact.build(
+        canonical_automaton, representation: @representation, cst_trivia: @cst_trivia,
+                             omit_action_call: @omit_action_call
+      )
+      artifacts = ArtifactSet.new
+      artifacts.add(kind: :parser_table, path: @table_path, content: table.dump)
+      artifacts.add(kind: :parser, path: @wrapper_path, content: @wrapper_source, mode: @wrapper_mode)
+      report = VerificationReport.render(
+        canonical_automaton, table: table, source_records: @source_records, table_path: @table_path,
+                             strict: @strict, max_states: @max_states, max_items: @max_items
+      )
+      artifacts.add(kind: :verification_report, path: @report_path, content: report)
+      manifest = GenerationManifest.render(
+        artifacts, source_records: @source_records, options: @manifest_options
+      )
+      artifacts.add(kind: :manifest, path: @manifest_path, content: manifest)
+      artifacts
+    end
+
+    # @rbs (?warning: ^(String) -> void, ?stability_check: ^() -> bool) -> ArtifactSet
+    def publish(warning: ->(_message) {}, stability_check: -> { @source_records.all?(&:current?) })
+      artifacts = render
+      GenerationTransaction.new(
+        artifacts, warning: warning, stability_check: stability_check, source_records: @source_records
+      ).commit
+      artifacts
+    end
+
+    # @rbs (String manifest_path) -> Hash[String, VerificationReport::Validator::json_value]
+    def self.validate_file(manifest_path)
+      VerificationReport.validate_bundle_file(manifest_path)
+    end
+  end
+end

data/lib/ibex/verification_report/builder.rb

@@ -0,0 +1,159 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+require "digest"
+require_relative "../ir"
+require_relative "../verify"
+require_relative "../version"
+
+module Ibex
+  module VerificationReport
+    # Builds deterministic evidence from an Automaton IR verification run.
+    class Builder
+      # @rbs!
+      #   type json_value = String | Integer | Float | bool | nil | Array[json_value] | Hash[String, json_value]
+
+      # @rbs (IR::Automaton automaton, table: TableArtifact::Document,
+      #   source_records: Array[GenerationInput], table_path: String, strict: bool,
+      #   max_states: Integer, max_items: Integer) -> void
+      def initialize(automaton, table:, source_records:, table_path:, strict:, max_states:, max_items:)
+        raise ArgumentError, "source_records must not be empty" if source_records.empty?
+        if source_records.length > LogicalPath::MAX_INPUT_FILES
+          raise ArgumentError, "verification reports support at most #{LogicalPath::MAX_INPUT_FILES} input files"
+        end
+        raise ArgumentError, "max_states must be positive" unless max_states.is_a?(Integer) && max_states.positive?
+        raise ArgumentError, "max_items must be positive" unless max_items.is_a?(Integer) && max_items.positive?
+
+        @automaton = CanonicalIR.new(automaton, source_records: source_records).build
+        @table = table
+        @source_records = source_records
+        @table_path = LogicalPath.table(table_path)
+        @strict = strict
+        @max_states = max_states
+        @max_items = max_items
+      end
+
+      # @rbs () -> String
+      def render
+        validate_table_identity!
+        document = {
+          "ibex_report" => IDENTIFIER,
+          "schema_version" => SCHEMA_VERSION,
+          "checker" => { "name" => "ibex.verify", "version" => Ibex::VERSION },
+          "profile" => @strict ? "strict" : "default",
+          "bounds" => bounds.transform_keys(&:to_s),
+          "input" => input_identity,
+          "ir" => ir_identity,
+          "table" => table_identity,
+          "outcome" => verification_outcome,
+          "excluded_trust" => EXCLUDED_TRUST
+        }
+        document["evidence_digest"] = TableArtifact::Serializer.digest(document)
+        TableArtifact::Serializer.dump(document)
+      end
+
+      private
+
+      # @rbs () -> Hash[Symbol, Integer]
+      def bounds
+        { max_states: @max_states, max_items: @max_items }
+      end
+
+      # @rbs () -> Array[String]
+      def requested_checks
+        Verify::Verifier::DEFAULT_CHECKS + (@strict ? Verify::Verifier::STRICT_CHECKS : [])
+      end
+
+      # @rbs () -> Hash[String, json_value]
+      def verification_outcome
+        result = Verify::Verifier.new(
+          @automaton, strict: @strict, max_states: @max_states, max_items: @max_items
+        ).verify
+        {
+          "status" => result.valid? ? "pass" : "violations",
+          "requested_checks" => requested_checks,
+          "executed_checks" => result.checks,
+          "violations" => result.violations.map { |violation| stringify_keys(violation.to_h) },
+          "exhaustion" => nil
+        }
+      rescue Verify::BudgetExceeded => e
+        {
+          "status" => "exhausted",
+          "requested_checks" => requested_checks,
+          "executed_checks" => [],
+          "violations" => [],
+          "exhaustion" => { "kind" => "reference_collection_budget", "message" => e.message }
+        }
+      end
+
+      # @rbs () -> Hash[String, json_value]
+      def input_identity
+        files = @source_records.map.with_index do |record, index|
+          {
+            "logical_path" => LogicalPath.input(record.path, index),
+            "sha256" => prefixed_digest(record.sha256),
+            "bytesize" => record.bytesize
+          }
+        end
+        { "digest" => TableArtifact::Serializer.digest(files), "files" => files }
+      end
+
+      # @rbs () -> Hash[String, json_value]
+      def ir_identity
+        {
+          "identity_scope" => IR_IDENTITY_SCOPE,
+          "grammar" => {
+            "schema_version" => @automaton.grammar.schema_version,
+            "digest" => grammar_digest
+          },
+          "automaton" => {
+            "schema_version" => @automaton.schema_version,
+            "algorithm" => @automaton.algorithm,
+            "digest" => automaton_digest
+          }
+        }
+      end
+
+      # @rbs () -> Hash[String, json_value]
+      def table_identity
+        {
+          "logical_path" => @table_path,
+          "artifact_type" => TableArtifact::ARTIFACT_TYPE,
+          "schema_version" => TableArtifact::SCHEMA_VERSION,
+          "representation" => @table.payload.dig("table_format", "representation"),
+          "artifact_digest" => prefixed_digest(Digest::SHA256.hexdigest(@table.dump)),
+          "payload_digest" => @table.identity.fetch("payload_digest")
+        }
+      end
+
+      # @rbs () -> void
+      def validate_table_identity!
+        identity = @table.identity
+        return if identity.fetch("grammar_digest") == grammar_digest &&
+                  identity.fetch("automaton_digest") == automaton_digest
+
+        raise ArgumentError, "table artifact does not match the supplied Automaton IR"
+      end
+
+      # @rbs () -> String
+      def grammar_digest
+        @grammar_digest ||= "sha256:#{Digest::SHA256.hexdigest(IR::Serialize.dump(@automaton.grammar))}"
+      end
+
+      # @rbs () -> String
+      def automaton_digest
+        @automaton_digest ||= "sha256:#{Digest::SHA256.hexdigest(IR::Serialize.dump(@automaton))}"
+      end
+
+      # @rbs (String digest) -> String
+      def prefixed_digest(digest)
+        digest.start_with?("sha256:") ? digest : "sha256:#{digest}"
+      end
+
+      # @rbs (Hash[Symbol, String] value) -> Hash[String, String]
+      def stringify_keys(value)
+        value.to_h { |key, child| [key.to_s, child] }
+      end
+    end
+  end
+end