ibex 0.1.0 → 0.3.0

data/lib/ibex/frontend/token_adapter/rule_state.rb

@@ -15,6 +15,7 @@ module Ibex
         # @rbs @delimiters: DelimiterTracker
         # @rbs @lhs_column: Integer?
         # @rbs @rule_seen: bool?
+        # @rbs @node_annotation: bool?
 
         # @rbs () -> void
         def initialize
@@ -28,12 +29,20 @@ module Ibex
         def classify(token, remaining, last_external:, previous_external:)
           external = if token.type == :identifier
                        classify_identifier(token, remaining, last_external, previous_external)
+                     elsif token.type == :node
+                       @node_annotation = true
+                       :NODE
+                     elsif token.type == :inline
+                       classify_inline
+                     elsif token.type == :empty
+                       :EMPTY
                      elsif SCALAR_TYPES.key?(token.type)
                        SCALAR_TYPES.fetch(token.type)
                      else
                        classify_punctuation(token)
                      end
           @delimiters.observe(token, external, last_external)
+          @node_annotation = false if token.type == :")" && @node_annotation
           external
         end
 
@@ -60,21 +69,35 @@ module Ibex
 
         private
 
+        # @rbs () -> external_token
+        def classify_inline
+          reset_rule_boundary if @state == :rule_rhs && @delimiters.empty?
+          :INLINE
+        end
+
         # @rbs (Token token, Array[Token] remaining, external_token? last_external,
         #   external_token? previous_external) -> external_token
         def classify_identifier(token, remaining, last_external, previous_external)
+          return :IDENTIFIER if @node_annotation
           return rule_lhs(token) if @state == :rules_lhs
           return :IDENTIFIER unless @state == :rule_rhs
           return :IDENTIFIER if named_reference_name?(last_external, previous_external)
 
+          classify_rhs_identifier(token, remaining)
+        end
+
+        # @rbs (Token token, Array[Token] remaining) -> external_token
+        def classify_rhs_identifier(token, remaining)
           value = string_value(token)
-          return :IDENTIFIER if value == "end" && @delimiters.open_kind == :separated
+          return :IDENTIFIER if value == "end" && @delimiters.open_kind
           return finish_rules if value == "end"
 
           following = remaining.first
           return :IDENTIFIER unless following
-          return start_rule(token) if rule_boundary?(token, following)
+          return start_rule(token) if rule_boundary?(token, following) ||
+                                      parameterized_rule_boundary?(token, remaining)
           return separated_terminal(token) if separated_list_call?(token, following)
+          return :PARAMETERIZED_REFERENCE if parameterized_call?(token, following)
 
           :IDENTIFIER
         end
@@ -105,6 +128,26 @@ module Ibex
           @delimiters.empty? && following.type == :":" && token.location.column <= lhs_column
         end
 
+        # @rbs (Token token, Array[Token] remaining) -> bool
+        def parameterized_rule_boundary?(token, remaining)
+          lhs_column = @lhs_column
+          opening = remaining.first
+          return false unless lhs_column && @delimiters.empty? && token.location.column <= lhs_column
+          return false unless opening&.type == :"(" && adjacent?(token, opening)
+
+          parameter_definition_tail?(remaining.drop(1))
+        end
+
+        # @rbs (Array[Token] tail) -> bool
+        def parameter_definition_tail?(tail)
+          closing = tail.index { |entry| entry.type == :")" }
+          return false unless closing && tail[closing + 1]&.type == :":"
+
+          formals = tail.take(closing)
+          !formals.empty? && formals.length.odd? &&
+            formals.each_with_index.all? { |entry, index| entry.type == (index.even? ? :identifier : :",") }
+        end
+
         # @rbs (Token token) -> external_token
         def start_rule(token)
           @rule_seen = true
@@ -129,6 +172,21 @@ module Ibex
           string_value(token) == "separated_list" ? :SEPARATED_LIST : :SEPARATED_NONEMPTY_LIST
         end
 
+        # @rbs (Token token, Token following) -> bool
+        def parameterized_call?(token, following)
+          following.type == :"(" && adjacent?(token, following)
+        end
+
+        # @rbs (Token left, Token right) -> bool
+        def adjacent?(left, right)
+          left_span = left.span
+          right_span = right.span
+          return left_span.end_byte == right_span.start_byte if left_span && right_span
+
+          left.location.line == right.location.line &&
+            left.location.column + string_value(left).length == right.location.column
+        end
+
         # @rbs (Token token) -> external_token
         def classify_punctuation(token)
           @state = :rule_rhs if @state == :rule_colon && token.type == :":"

data/lib/ibex/frontend/token_adapter.rb

@@ -15,11 +15,11 @@ module Ibex
       # @rbs @rules: RuleState?
       # @rbs @last_external: external_token?
 
-      # @rbs (Array[Token] tokens) -> void
-      def initialize(tokens)
+      # @rbs (Array[Token] tokens, ?extended: bool) -> void
+      def initialize(tokens, extended: false)
         @tokens = tokens
         @index = 0
-        @declarations = DeclarationState.new
+        @declarations = DeclarationState.new(extended: extended)
         @classifier = @declarations
       end
 
@@ -60,6 +60,21 @@ module Ibex
         @declarations.extended_pragma?
       end
 
+      # @rbs () -> bool
+      def cst_pragma?
+        @declarations.cst_pragma?
+      end
+
+      # @rbs () -> Location?
+      def extended_pragma_location
+        @declarations.extended_pragma_location
+      end
+
+      # @rbs () -> Location?
+      def cst_pragma_location
+        @declarations.cst_pragma_location
+      end
+
       # @rbs () -> parser_section
       def section
         rules = @rules

data/lib/ibex/frontend.rb

@@ -2,18 +2,30 @@
 
 require_relative "error"
 require_relative "tables"
-require_relative "runtime"
+require "ibex/runtime"
+require_relative "frontend/source_span"
 require_relative "frontend/source_cursor"
+require_relative "frontend/source_document"
+require_relative "frontend/diagnostic"
 require_relative "frontend/action_scanner"
 require_relative "frontend/lexer"
+require_relative "frontend/lexer_recovery"
 require_relative "frontend/ast"
+require_relative "frontend/parser_configuration_support"
+require_relative "frontend/rule_documentation"
+require_relative "frontend/token_adapter/declaration_document_state"
 require_relative "frontend/token_adapter/declaration_state"
 require_relative "frontend/token_adapter/delimiter_tracker"
 require_relative "frontend/token_adapter/rule_state"
 require_relative "frontend/token_adapter"
 require_relative "frontend/generated_parser_base"
 require_relative "frontend/generated_parser"
+require_relative "frontend/diagnostic_recovery"
 require_relative "frontend/parser"
+require_relative "frontend/formatter"
+require_relative "frontend/resolution"
+require_relative "frontend/source_loader"
+require_relative "frontend/resolver"
 require_relative "frontend/dsl"
 
 module Ibex
@@ -23,6 +35,6 @@ module Ibex
     #   type token_value = String | Integer | user_code_token | nil
     #   type external_token = Symbol | String
     #   type parser_section = :declarations | :rules | :user_code
-    #   type delimiter_kind = :group | :separated
+    #   type delimiter_kind = :group | :separated | :parameter
   end
 end

data/lib/ibex/fuzz.rb

@@ -0,0 +1,219 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+require_relative "samples"
+require_relative "table_simulation"
+require_relative "delta_reducer"
+
+module Ibex
+  # @rbs!
+  #   type fuzz_outcome = Symbol | [Symbol, String, String]
+  #   type fuzz_mismatch = {
+  #     tokens: Array[String],
+  #     kind: Symbol,
+  #     sentence: Integer,
+  #     outcomes: Hash[Symbol, fuzz_outcome],
+  #     bounds: Hash[Symbol, Integer]
+  #   }
+  #   type fuzz_budget = {
+  #     message: String,
+  #     bounds: Hash[Symbol, Integer],
+  #     ?tokens: Array[String],
+  #     ?phase: String
+  #   }
+
+  # Bounded grammar-derived differential fuzzing without semantic execution.
+  class Fuzz
+    ALGORITHMS = %i[slr lalr ielr lr1].freeze #: Array[Symbol]
+    DEFAULT_MAX_ACTIONS = 100_000 #: Integer
+    DEFAULT_MAX_STACK = 10_000 #: Integer
+
+    class Mismatch < Ibex::Error
+      attr_reader :details #: fuzz_mismatch
+
+      # @rbs (fuzz_mismatch details) -> void
+      def initialize(details)
+        @details = IR.deep_freeze(details)
+        super("(fuzz):1:1: differential mismatch for #{details[:tokens].inspect}")
+      end
+    end
+
+    class BudgetExceeded < Ibex::Error
+      attr_reader :details #: fuzz_budget
+
+      # @rbs (fuzz_budget details) -> void
+      def initialize(details)
+        @details = IR.deep_freeze(details)
+        super("(fuzz):1:1: configured budget was exhausted: #{details[:message]}")
+      end
+    end
+
+    # @rbs (IR::Grammar grammar, ?seed: Integer, ?count: Integer, ?max_tokens: Integer,
+    #   ?max_depth: Integer, ?max_expansions: Integer, ?max_actions: Integer, ?max_stack: Integer,
+    #   ?coverage_guided: bool, ?path_length: Integer, ?algorithms: Array[Symbol],
+    #   ?ielr_strategy: Symbol, ?automata: Hash[Symbol, IR::Automaton]?, ?against: (^(Array[String]) -> Symbol)?,
+    #   ?against_description: Hash[Symbol, Object?]?) -> void
+    # rubocop:disable Metrics/ParameterLists
+    def initialize(grammar, seed: 0, count: 100, max_tokens: 32, max_depth: 16,
+                   max_expansions: Samples::DEFAULT_MAX_EXPANSIONS, max_actions: DEFAULT_MAX_ACTIONS,
+                   max_stack: DEFAULT_MAX_STACK, coverage_guided: false, path_length: 2,
+                   algorithms: ALGORITHMS, ielr_strategy: :partition, automata: nil,
+                   against: nil, against_description: nil)
+      raise ArgumentError, "count must be positive" unless count.positive?
+      raise ArgumentError, "algorithms must not be empty" if algorithms.empty?
+      unless LALR::Builder::IELR_STRATEGIES.include?(ielr_strategy.to_sym)
+        raise ArgumentError, "unknown IELR construction strategy #{ielr_strategy.inspect}"
+      end
+
+      @grammar = grammar
+      @seed = seed
+      @count = count
+      @random = Random.new(seed ^ 0x1BE)
+      @max_tokens = max_tokens
+      @max_depth = max_depth
+      @max_expansions = max_expansions
+      @max_actions = max_actions
+      @max_stack = max_stack
+      @coverage_guided = coverage_guided
+      @path_length = path_length
+      @algorithms = algorithms.map(&:to_sym).freeze
+      @ielr_strategy = ielr_strategy.to_sym
+      @automata = automata || build_automata
+      @against = against
+      @against_description = against_description
+    end
+    # rubocop:enable Metrics/ParameterLists
+
+    # @rbs () -> Hash[Symbol, Object?]
+    def run
+      sentences = generate_sentences
+      mutation_count = 0
+      sentences.each_with_index do |tokens, index|
+        compare!(tokens, kind: :generated, sentence: index)
+        mutations(tokens).each do |mutation|
+          compare!(mutation, kind: :mutation, sentence: index)
+          mutation_count += 1
+        end
+      end
+      successful_report(sentences.length, mutation_count)
+    rescue Ibex::Error => e
+      raise if e.is_a?(Mismatch) || e.is_a?(BudgetExceeded) || !budget_error?(e)
+
+      raise BudgetExceeded.new(
+        message: e.message,
+        bounds: { max_expansions: @max_expansions, max_actions: @max_actions, max_stack: @max_stack }
+      )
+    end
+
+    # Minimize one observed mismatch without changing its kind or outcomes.
+    # @rbs (Mismatch mismatch, ?max_trials: Integer) -> DeltaReducer::Result
+    def minimize(mismatch, max_trials: 1_000)
+      details = mismatch.details
+      original = details[:tokens]
+      kind = details[:kind].to_sym
+      sentence = details[:sentence]
+      outcomes = details[:outcomes]
+      DeltaReducer.new(max_trials: max_trials).minimize(original) do |candidate|
+        mismatch_reproduced?(candidate, kind: kind, sentence: sentence, outcomes: outcomes)
+      end
+    end
+
+    private
+
+    # @rbs () -> Array[Array[String]]
+    def generate_sentences
+      Samples.new(
+        @grammar, seed: @seed, max_tokens: @max_tokens, max_depth: @max_depth,
+                  max_expansions: @max_expansions, strategy: @coverage_guided ? :coverage : :random,
+                  path_length: @path_length
+      ).generate(count: @count)
+    end
+
+    # @rbs (Integer sentence_count, Integer mutation_count) -> untyped
+    def successful_report(sentence_count, mutation_count)
+      report = {
+        ibex_report: "fuzz", schema_version: 1, seed: @seed,
+        bounds: {
+          sentences: @count, max_tokens: @max_tokens, max_depth: @max_depth,
+          max_expansions: @max_expansions, max_actions: @max_actions, max_stack: @max_stack
+        },
+        strategy: @coverage_guided ? "coverage" : "random",
+        path_length: @path_length,
+        ielr_strategy: @ielr_strategy.to_s,
+        algorithms: @algorithms.map(&:to_s),
+        generated_sentences: sentence_count,
+        mutated_sentences: mutation_count,
+        result: "no_difference_within_bounds"
+      }
+      report[:external] = @against_description if @against_description
+      IR.deep_freeze(report)
+    end
+
+    # @rbs () -> Hash[Symbol, IR::Automaton]
+    def build_automata
+      @algorithms.to_h do |algorithm|
+        builder = LALR::Builder.new(
+          @grammar,
+          algorithm: algorithm,
+          ielr_strategy: @ielr_strategy
+        )
+        [algorithm, builder.build]
+      end
+    end
+
+    # @rbs (Array[String] tokens, kind: Symbol, sentence: Integer) -> void
+    def compare!(tokens, kind:, sentence:)
+      outcomes = @algorithms.to_h do |algorithm|
+        automaton = @automata.fetch(algorithm)
+        simulator = TableSimulation::Simulator.new(
+          automaton, max_steps: @max_actions, max_stack: @max_stack
+        )
+        [algorithm, simulator.simulate(tokens).status]
+      rescue Ibex::Error => e
+        if budget_error?(e)
+          raise BudgetExceeded.new(
+            message: e.message, tokens: tokens,
+            bounds: { max_actions: @max_actions, max_stack: @max_stack }
+          )
+        end
+        [algorithm, [:failure, e.class.name, e.message]]
+      end
+      outcomes[:external] = @against.call(tokens) if @against
+      values = outcomes.values.uniq
+      return if values.length == 1 && (kind != :generated || values.first == :accepted)
+
+      raise Mismatch.new(tokens: tokens, kind: kind, sentence: sentence, outcomes: outcomes,
+                         bounds: { max_actions: @max_actions, max_stack: @max_stack })
+    end
+
+    # @rbs (Array[String] tokens) -> Array[Array[String]]
+    def mutations(tokens)
+      terminals = @grammar.terminals.reject(&:reserved).map(&:name)
+      replacement = terminals.fetch(@random.rand(terminals.length))
+      index = tokens.empty? ? 0 : @random.rand(tokens.length)
+      inserted = tokens.dup.insert(index, replacement)
+      return [inserted] if tokens.empty?
+
+      deleted = tokens.dup.tap { |items| items.delete_at(index) }
+      replaced = tokens.dup.tap { |items| items[index] = replacement }
+      [inserted, deleted, replaced].uniq
+    end
+
+    # @rbs (Array[String] tokens, kind: Symbol, sentence: Integer,
+    #   outcomes: Hash[Symbol, fuzz_outcome]) -> bool
+    def mismatch_reproduced?(tokens, kind:, sentence:, outcomes:)
+      compare!(tokens, kind: kind, sentence: sentence)
+      false
+    rescue Mismatch => e
+      e.details[:kind].to_sym == kind &&
+        e.details[:outcomes] == outcomes
+    end
+
+    # @rbs (Ibex::Error error) -> bool
+    def budget_error?(error)
+      error.message.match?(
+        /simulation exceeded|(?:limit|maximum|budget).*(?:exceed|exhaust)|exceed.*(?:limit|maximum|budget)/i
+      )
+    end
+  end
+end

data/lib/ibex/generation_input.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+require "digest"
+
+module Ibex
+  # Digest and identity of source bytes actually consumed by one generation.
+  class GenerationInput
+    attr_reader :path #: String
+    attr_reader :sha256 #: String
+    attr_reader :bytesize #: Integer
+    attr_reader :dev #: Integer
+    attr_reader :ino #: Integer
+    attr_reader :access_paths #: Array[String]
+
+    # @rbs (String path, String source, ?access_path: String) -> void
+    def initialize(path, source, access_path: path)
+      @path = File.realpath(path).freeze
+      stat = File.stat(@path)
+      @sha256 = Digest::SHA256.hexdigest(source).freeze
+      @bytesize = source.bytesize
+      @dev = stat.dev
+      @ino = stat.ino
+      @access_paths = [File.expand_path(access_path)] #: Array[String]
+    end
+
+    # Record another lexical path that supplied these canonical bytes.
+    # @rbs (String path) -> void
+    def add_access_path(path)
+      expanded = File.expand_path(path)
+      @access_paths << expanded unless @access_paths.include?(expanded)
+    end
+
+    # @rbs () -> Hash[String, String | Integer]
+    def to_h
+      { "path" => @path, "sha256" => @sha256, "bytesize" => @bytesize }
+    end
+
+    # Detect content changes even when size and timestamps are preserved.
+    # @rbs () -> bool
+    def current?
+      source = File.binread(@path)
+      stat = File.stat(@path)
+      lexical_paths_current? && stat.dev == @dev && stat.ino == @ino &&
+        source.bytesize == @bytesize && Digest::SHA256.hexdigest(source) == @sha256
+    rescue SystemCallError
+      false
+    end
+
+    private
+
+    # @rbs () -> bool
+    def lexical_paths_current?
+      @access_paths.all? { |path| File.realpath(path) == @path }
+    end
+  end
+end

data/lib/ibex/generation_manifest.rb

@@ -0,0 +1,211 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+require "digest"
+require "json"
+
+module Ibex
+  # Deterministic description of one published parser generation.
+  # rubocop:disable Metrics/ModuleLength -- manifest schema validation is kept in one auditable unit.
+  module GenerationManifest
+    # @rbs!
+    #   type json_value = String | Integer | Float | bool | nil | Array[json_value] | Hash[String, json_value]
+
+    SCHEMA_VERSION = 1 #: Integer
+    IDENTIFIER = "generation" #: String
+    ROOT_KEYS = %w[ibex_manifest schema_version input options artifacts].freeze #: Array[String]
+    INPUT_KEYS = %w[root sha256 files].freeze #: Array[String]
+    FILE_KEYS = %w[path sha256 bytesize].freeze #: Array[String]
+    ARTIFACT_KEYS = %w[kind path sha256 bytesize].freeze #: Array[String]
+
+    module_function
+
+    # @rbs (ArtifactSet artifacts, source_records: Array[GenerationInput], options: Hash[String, Object?]) -> String
+    def render(artifacts, source_records:, options:)
+      files = source_records.map(&:to_h)
+      document = {
+        "ibex_manifest" => IDENTIFIER,
+        "schema_version" => SCHEMA_VERSION,
+        "input" => {
+          "root" => files.fetch(0).fetch("path"),
+          "sha256" => input_digest(files),
+          "files" => files
+        },
+        "options" => sorted_hash(options),
+        "artifacts" => artifacts.map { |artifact| artifact_entry(artifact) }
+      }
+      "#{JSON.pretty_generate(document)}\n"
+    end
+
+    # Validate the manifest shape and, by default, every published artifact digest.
+    # @rbs (String source, ?verify_artifacts: bool) -> Hash[String, json_value]
+    def validate(source, verify_artifacts: true)
+      document = JSON.parse(source) #: Object?
+      validate_document(document)
+      document_hash = document #: Hash[String, json_value]
+      artifacts = document_hash.fetch("artifacts") #: Array[Object?]
+      verify_entries(artifacts) if verify_artifacts
+      document_hash
+    rescue JSON::ParserError, KeyError, TypeError, ArgumentError => e
+      raise Ibex::Error, "(manifest):1:1: invalid generation manifest: #{e.message}"
+    end
+
+    # @rbs (String path, ?verify_artifacts: bool) -> Hash[String, json_value]
+    def validate_file(path, verify_artifacts: true)
+      validate(File.binread(path), verify_artifacts: verify_artifacts)
+    rescue SystemCallError, ArgumentError => e
+      raise Ibex::Error, "#{path}:1:1: cannot read generation manifest: #{e.message}"
+    end
+
+    # @rbs (Artifact artifact) -> Hash[String, json_value]
+    def artifact_entry(artifact)
+      {
+        "kind" => artifact.kind.to_s,
+        "path" => File.expand_path(artifact.path),
+        "sha256" => Digest::SHA256.hexdigest(artifact.content),
+        "bytesize" => artifact.content.bytesize
+      }
+    end
+    private_class_method :artifact_entry
+
+    # @rbs (Array[Hash[String, json_value]] files) -> String
+    def input_digest(files)
+      digest = Digest::SHA256.new
+      files.each do |entry|
+        path = entry.fetch("path") # @type var path: String
+        sha256 = entry.fetch("sha256") # @type var sha256: String
+        bytesize = entry.fetch("bytesize") # @type var bytesize: Integer
+        digest << path << "\0" << sha256 << "\0" << bytesize.to_s << "\0"
+      end
+      digest.hexdigest
+    end
+    private_class_method :input_digest
+
+    # @rbs (Hash[String, Object?] value) -> Hash[String, Object?]
+    def sorted_hash(value)
+      value.keys.sort.to_h do |key|
+        child = value.fetch(key)
+        normalized = child.is_a?(Hash) ? sorted_hash(child) : child
+        [key, normalized]
+      end
+    end
+    private_class_method :sorted_hash
+
+    # @rbs (Object? document) -> void
+    def validate_document(document)
+      raise TypeError, "document must be an object" unless document.is_a?(Hash)
+
+      exact_keys!(document, ROOT_KEYS, "document")
+      validate_identity(document)
+      validate_input(document.fetch("input"))
+      artifacts = document.fetch("artifacts")
+      raise TypeError, "options must be an object" unless document.fetch("options").is_a?(Hash)
+      raise TypeError, "artifacts must be an array" unless artifacts.is_a?(Array)
+      raise TypeError, "artifacts must not be empty" if artifacts.empty?
+
+      validate_entries(artifacts, "artifact", require_kind: true)
+    end
+    private_class_method :validate_document
+
+    # @rbs (Hash[Object?, Object?] document) -> void
+    def validate_identity(document)
+      raise TypeError, "unsupported manifest identifier" unless document["ibex_manifest"] == IDENTIFIER
+      raise TypeError, "unsupported schema_version" unless document["schema_version"] == SCHEMA_VERSION
+    end
+    private_class_method :validate_identity
+
+    # @rbs (Object? input) -> void
+    def validate_input(input)
+      raise TypeError, "input must be an object" unless input.is_a?(Hash)
+
+      exact_keys!(input, INPUT_KEYS, "input")
+
+      files = input.fetch("files")
+      raise TypeError, "input files must be a non-empty array" unless files.is_a?(Array) && !files.empty?
+
+      validate_entries(files, "input file")
+      expected = input_digest(files)
+      root = input.fetch("root")
+      raise TypeError, "input root must be a non-empty string" unless root.is_a?(String) && !root.empty?
+      raise TypeError, "input digest mismatch" unless input.fetch("sha256") == expected
+      raise TypeError, "input root mismatch" unless root == files.fetch(0).fetch("path")
+    end
+    private_class_method :validate_input
+
+    # @rbs (Array[Object?] entries, String label, ?require_kind: bool) -> void
+    def validate_entries(entries, label, require_kind: false)
+      entries.each { |entry| validate_entry(entry, label, require_kind) }
+    end
+    private_class_method :validate_entries
+
+    # @rbs (Object? entry, String label, bool require_kind) -> void
+    def validate_entry(entry, label, require_kind)
+      raise TypeError, "#{label} must be an object" unless entry.is_a?(Hash)
+
+      exact_keys!(entry, require_kind ? ARTIFACT_KEYS : FILE_KEYS, label)
+      validate_path(entry.fetch("path"), label)
+      validate_kind(entry.fetch("kind"), label) if require_kind
+      validate_digest(entry.fetch("sha256"), label)
+      bytesize = entry.fetch("bytesize")
+      return if bytesize.is_a?(Integer) && bytesize >= 0
+
+      raise TypeError, "#{label} bytesize must be non-negative"
+    end
+    private_class_method :validate_entry
+
+    # @rbs (Object? path, String label) -> void
+    def validate_path(path, label)
+      raise TypeError, "#{label} path must be a non-empty string" unless path.is_a?(String) && !path.empty?
+      return unless path.include?("\0") || path.match?(/[[:cntrl:]]/)
+
+      raise TypeError, "#{label} path must not contain control characters"
+    end
+    private_class_method :validate_path
+
+    # @rbs (Object? kind, String label) -> void
+    def validate_kind(kind, label)
+      return if kind.is_a?(String) && !kind.empty?
+
+      raise TypeError, "#{label} kind must be a non-empty string"
+    end
+    private_class_method :validate_kind
+
+    # @rbs (Object? digest, String label) -> void
+    def validate_digest(digest, label)
+      return if digest.is_a?(String) && digest.match?(/\A[0-9a-f]{64}\z/)
+
+      raise TypeError, "#{label} digest must be SHA-256"
+    end
+    private_class_method :validate_digest
+
+    # @rbs (Hash[Object?, Object?] value, Array[String] expected, String label) -> void
+    def exact_keys!(value, expected, label)
+      keys = value.keys
+      raise TypeError, "#{label} keys must be strings" unless keys.all?(String)
+
+      extras = keys - expected
+      missing = expected - keys
+      raise TypeError, "#{label} has unknown property #{extras.fetch(0)}" unless extras.empty?
+      raise KeyError, "#{label} is missing #{missing.fetch(0)}" unless missing.empty?
+    end
+    private_class_method :exact_keys!
+
+    # @rbs (Array[Object?] entries) -> void
+    def verify_entries(entries)
+      entries.each do |entry|
+        entry_hash = entry #: Hash[String, json_value]
+        path = entry_hash.fetch("path") #: String
+        source = File.binread(path)
+        bytesize = entry_hash.fetch("bytesize") #: Integer
+        sha256 = entry_hash.fetch("sha256") #: String
+        raise TypeError, "artifact bytesize mismatch for #{path}" unless source.bytesize == bytesize
+        raise TypeError, "artifact digest mismatch for #{path}" unless
+          Digest::SHA256.hexdigest(source) == sha256
+      end
+    rescue SystemCallError => e
+      raise TypeError, "cannot read artifact: #{e.message}"
+    end
+    private_class_method :verify_entries
+  end
+  # rubocop:enable Metrics/ModuleLength
+end