hecks 1.3.0 → 1.5.0

data/lib/hecks/fuzzing/era_boundary.rb

@@ -2,20 +2,22 @@ require "hecks/ports/persistence/plugins/era"
 
 module Hecks
   module Fuzzing
-    # THE FORK-LOSS CLASS, AS A CHECK — not a fuzz. Every other mode in
-    # this file generates a sequence and compares two answers to the SAME
+    # **The fork-loss class, as a check** — not a fuzz. Every other mode in
+    # this file generates a sequence and compares two answers to the same
     # question; this one asks a single, unconditional question of a
-    # target's own REAL, already-configured `PostgresEra` ledger:
+    # target's own real, already-configured `PostgresEra` ledger:
     # does any ancestor era still hold writes nobody has merged forward?
     #
-    # THE BUG THIS TARGETS, NAMED EXACTLY. Minting a new era (an attribute
+    # ## The bug this targets, named exactly
+    #
+    # Minting a new era (an attribute
     # or aggregate addition — `StorageShape.project`, lib/hecks/ports/
     # persistence/plugins/era/storage_shape.rb) advances the readable head
-    # to a NEW partition; an OLD checkout, or a process that boots slower
+    # to a new partition; an old checkout, or a process that boots slower
     # than the mint, can keep writing into the era it still believes is
     # current. Those writes are not lost — `Lineage#diverged_count`
     # (postgres_era/lineage/tail_merge.rb) can always find them — but
-    # nothing EVER asked it automatically. The practice's own ledger found
+    # nothing ever asked it automatically. The practice's own ledger found
     # exactly this live, twice: once as an operational gap this session's
     # Step 0 recovered by hand (`bin/merge_tail`, three conflicting
     # records, three eras deep), and once as BUG#24 (a superuser
@@ -26,15 +28,17 @@ module Hecks
     # line already answers by hand, run as an ordinary sweep Check instead
     # of only when a human remembers to ask.
     #
-    # THE TARGET'S REAL DATABASE, READ-ONLY, NEVER A DISPOSABLE ONE — every
+    # ## Connection and safety
+    #
+    # The target's real database, read-only, never a disposable one — every
     # other Postgres-touching mode here (`persistence_parity`,
     # `adapter_parity_sqlite`) owns a throwaway schema for the exact
     # reason it must never look at what a real deployment actually holds;
-    # this check exists FOR what a real deployment actually holds, so it
+    # this check exists for what a real deployment actually holds, so it
     # connects the same way `bin/merge_tail` itself does — the target's
     # own `.world` binding — and never writes anything: `eras`/
     # `diverged_count` are both plain `SELECT`s, and `ensure_base!` only
-    # ever provisions (`CREATE TABLE IF NOT EXISTS`) when THIS connection
+    # ever provisions (`CREATE TABLE IF NOT EXISTS`) when this connection
     # is the database's own provisioning owner, the identical idempotent
     # call every ordinary boot already makes. A target with no real,
     # reachable database configured (nothing provisioned locally, say) is
@@ -44,21 +48,39 @@ module Hecks
     module EraBoundary
       module_function
 
+      # Reports whether any ancestor `PostgresEra` era still holds writes the
+      # head has never merged forward, for one target's real database.
+      #
       # `{ checked: true, diverged_total:, breakdown: [{ordinal:, diverged:}] }`
-      # or `{ checked: false, reason: "..." }` — the caller decides what a
-      # `false` means (an operational note, not a finding); a `true` with
+      # or `{ checked: false, kind:, reason: "..." }`. A `true` with
       # `diverged_total.positive?` is the finding this module exists to
       # surface: real post-cut writes an ancestor era is still holding.
+      #
+      # `kind:` distinguishes the two different reasons `checked: false` can
+      # occur — without it, `bin/qa_sweep` would log a refused connection
+      # and a `Lineage` defect exactly like an audit that ran and found
+      # nothing, counting either toward `sweep.made` and the target's clean
+      # streak. `:not_applicable` is a target with no lineage to audit at
+      # all; `:error` is the audit failing to run, which the caller
+      # surfaces as a finding rather than holding.
+      #
+      # @param domain_path [String] filesystem path to the target domain's bluebook
+      #   directory, or a directory containing one
+      # @return [Hash{Symbol => Object}] on success, `{checked: true, era_count: Integer,
+      #   breakdown: Array<Hash{ordinal: Integer, diverged: Integer}>, diverged_total: Integer}`;
+      #   otherwise `{checked: false, kind: Symbol, reason: String}`
       def diverged_ancestor_writes(domain_path)
         registry, directory = load_registry(domain_path)
         bluebook = registry.bluebooks.values.first
-        return unchecked("no bluebook in #{directory}") unless bluebook
+        return failed("no bluebook in #{directory}") unless bluebook
 
         first = bluebook.aggregates.first
-        return unchecked("#{bluebook.name} declares no aggregates") unless first
+        return not_applicable("#{bluebook.name} declares no aggregates") unless first
 
         adapter_name = Hecks::Ports::Persistence::BindingPolicy.resolve(registry, bluebook.name, first).adapter
-        return unchecked("#{bluebook.name} is bound to #{adapter_name}, not PostgresEra") unless adapter_name == "PostgresEra"
+        unless adapter_name == "PostgresEra"
+          return not_applicable("#{bluebook.name} is bound to #{adapter_name}, not PostgresEra")
+        end
 
         settings = registry.world(bluebook.name)&.for_binding(Hecks::Ports::Persistence::VERB, adapter_name) || {}
         db = Hecks::Adapters::PostgresEra.connect_for(bluebook.name, settings)
@@ -81,14 +103,41 @@ module Hecks
           db.close
         end
       rescue StandardError => e
-        unchecked("#{e.class}: #{e.message}")
+        # Could not audit is not the same as nothing to audit — a refused
+        # connection, a `Lineage` defect, malformed `.world` settings. Each
+        # of these answers `:error`, not the benign `:not_applicable` shape,
+        # so `bin/qa_sweep` surfaces it as a finding rather than holding it
+        # as a clean audit.
+        failed("#{e.class}: #{e.message}")
       end
 
-      def unchecked(reason) = { checked: false, reason: reason }
+      # Builds the `checked: false` result for a target with no PostgresEra
+      # lineage to audit — no ancestor era can carry post-cut writes when
+      # there is no lineage at all. Not a finding, and not evidence of
+      # anything either: the caller logs no Check at all.
+      #
+      # @param reason [String] human-readable explanation of why no lineage applies
+      # @return [Hash{Symbol => Object}] `{checked: false, kind: :not_applicable, reason: String}`
+      def not_applicable(reason) = { checked: false, kind: :not_applicable, reason: reason }
+
+      # Builds the `checked: false` result for an audit that could not run
+      # — reported as a finding, never held.
+      #
+      # @param reason [String] human-readable explanation of what failed, typically
+      #   `"#{exception.class}: #{exception.message}"`
+      # @return [Hash{Symbol => Object}] `{checked: false, kind: :error, reason: String}`
+      def failed(reason) = { checked: false, kind: :error, reason: reason }
 
-      # THE SAME LOAD `bin/merge_tail` ITSELF PERFORMS (that script's own
-      # top half) — a fresh `Registry`, never the ledger's own (this asks
-      # about the SWEPT TARGET's lineage, not QualityControl's own).
+      # Boots a fresh registry for the domain at `domain_path` — the same
+      # load `bin/merge_tail` itself performs (that script's own top half),
+      # never the ledger's own registry (this asks about the swept target's
+      # lineage, not QualityControl's own).
+      #
+      # @param domain_path [String] filesystem path to the target domain's bluebook
+      #   directory, or a directory containing one
+      # @return [Array(Runtime::Registry, String)] the booted registry and the resolved
+      #   bluebook directory path
+      # @raise [Errno::ENOENT] if `domain_path` names no existing domain directory
       def load_registry(domain_path)
         loading = Hecks::Ports::Loading.bootstrap
         directory = loading.bluebook_directory(domain_path)

data/lib/hecks/fuzzing/form_census.rb

@@ -1,27 +1,28 @@
 require "json"
+require_relative "../corpus"
 
 module Hecks
   module Fuzzing
-    # WHAT AN AGGREGATE CAN EXHIBIT, AND WHICH PAIRS IT PUTS TOGETHER.
+    # What an aggregate can exhibit, and which pairs it puts together.
     #
     # Extracted from `spec/combination_coverage_spec.rb`'s own pairwise
     # table so it has exactly two consumers that can never drift: that
     # spec (the golden corpus, held to every pair) and `bin/qa_domain_
-    # novelty` (a CANDIDATE stress domain, measured against every path
+    # novelty` (a candidate stress domain, measured against every path
     # the QA ledger already sweeps — see that script's own header for why
     # a new domain has to name the pair no existing target meets before
     # it earns a place in the rotation).
     #
-    # THE UNIT IS ONE AGGREGATE. Two forms in the same chapter but
+    # **The unit is one aggregate**. Two forms in the same chapter but
     # different heads never meet at dispatch; two forms on one head do
     # — that spec's own header has the four defects that argument came
     # from. Each entry below is a form the language declares and a
     # runtime has to handle, chosen because it has produced a defect or
     # sits one step from one; adding one here is how a new form joins
-    # BOTH gates at once, and it will name its own uncovered pairs on the
+    # both gates at once, and it will name its own uncovered pairs on the
     # first run of each.
     #
-    # ONE FLAT TABLE, ON PURPOSE — each entry is an independent boolean
+    # **One flat table, on purpose** — each entry is an independent boolean
     # check against the same string-keyed aggregate IR hash (the shape
     # `spec/golden/ir/*.json` carries and `Projector::Exporter.call`
     # round-trips to through JSON), laid out so every declared form can
@@ -48,7 +49,7 @@ module Hecks
         "closed_set"         => ->(a) { (a["value_objects"] || []).any? { |shape| shape["closed_set"] } },
         "has_default"        => ->(a) { attributes(a).any? { |held| !held["default"].nil? } },
         "has_optional"       => ->(a) { commands(a).any? { |verb| (verb["attributes"] || []).any? { |held| held["optional"] } } },
-        # THE REFERENCE-HOP FAMILY (ANGLE-2, qa/bluebook ledger) — the
+        # The reference-hop family (angle-2, qa/bluebook ledger) — the
         # forms `qa/stress_domains/referral_chain` exists for, absent
         # from the census until that domain named them. Each is one
         # step from a catalogued gap: `two_hop_given` is `dereference`'s
@@ -59,6 +60,19 @@ module Hecks
         # command redeclaring the aggregate's own reference field under
         # a non-reference type, so only `resolve_state_references` (never
         # ported) can catch a dangling id.
+        # A retroactive correction, and a role-gated command — both are
+        # declared forms this census could not see, on aggregates it was
+        # already measuring: `examples/banking` has carried `corrects`
+        # mutations and `role`-bearing commands the whole time, and
+        # `qa/stress_domains/corrections` exists for the first. Three
+        # stress domains' own NOTES.md record `bin/qa_domain_novelty`
+        # answering "no new pair" for a domain whose whole point was a
+        # shape this table did not name (case_escalation's is the
+        # bluntest: "read that as a gap in the census, not in this
+        # domain"). Entity commands count for both — BUG#30-33 and
+        # BUG#31 were all entity-level `corrects`.
+        "corrects"           => ->(a) { every_command(a).any? { |verb| corrects?(verb) } },
+        "role_gated"         => ->(a) { every_command(a).any? { |verb| !verb["role"].to_s.empty? } },
         "two_hop_given"      => ->(a) { two_hop_given?(a) },
         "multi_hop_where"    => ->(a) { multi_hop_where?(a) },
         "revalued_reference" => ->(a) { revalued_reference?(a) }
@@ -66,25 +80,80 @@ module Hecks
 
       module_function
 
+      # Reads an aggregate IR hash's own declared entities.
+      #
+      # @param aggregate [Hash] a string-keyed aggregate IR hash
+      # @return [Array<Hash>] the aggregate's own declared entities ("pieces"); `[]`
+      #   if it declares none
       def entities(aggregate)   = aggregate["entities"] || []
+
+      # Reads an aggregate IR hash's own declared commands.
+      #
+      # @param aggregate [Hash] a string-keyed aggregate IR hash
+      # @return [Array<Hash>] the aggregate's own declared commands; `[]` if it
+      #   declares none
       def commands(aggregate)   = aggregate["commands"] || []
+
+      # One aggregate's commands, its pieces' included — a form carried by
+      # an entity command is carried by the aggregate that owns it, the
+      # same way `composite_piece`/`piece_lifecycle` already read pieces.
+      #
+      # @param aggregate [Hash] a string-keyed aggregate IR hash
+      # @return [Array<Hash>] `aggregate`'s own commands, plus every entity's own
+      def every_command(aggregate) = commands(aggregate) + entities(aggregate).flat_map { |piece| commands(piece) }
+
+      # Answers whether a command IR hash declares a `corrects` mutation.
+      #
+      # @param verb [Hash] a string-keyed command IR hash
+      # @return [Boolean] true if `verb` declares a `corrects` mutation
+      def corrects?(verb) = (verb["mutations"] || []).any? { |change| change["op"].to_s == "corrects" }
+
+      # Reads an aggregate IR hash's own declared attributes.
+      #
+      # @param aggregate [Hash] a string-keyed aggregate IR hash
+      # @return [Array<Hash>] the aggregate's own declared attributes; `[]` if it
+      #   declares none
       def attributes(aggregate) = aggregate["attributes"] || []
+
+      # Reads an aggregate IR hash's own declared queries.
+      #
+      # @param aggregate [Hash] a string-keyed aggregate IR hash
+      # @return [Array<Hash>] the aggregate's own declared queries; `[]` if it
+      #   declares none
       def queries(aggregate)    = aggregate["queries"] || []
+
+      # Answers whether an attribute IR hash's own declared type is a reference.
+      #
+      # @param attribute [Hash] a string-keyed attribute IR hash
+      # @return [Boolean] true if `attribute`'s own declared type is a reference
       def reference?(attribute) = attribute["type"].to_s.start_with?("Reference<")
 
+      # Answers whether any of an aggregate's own commands crosses a two-hop given.
+      #
+      # @param aggregate [Hash] a string-keyed aggregate IR hash
+      # @return [Boolean] true if any command's own given crosses at least two
+      #   references (`TWO_HOP_GIVEN_PATH_LENGTH`)
       def two_hop_given?(aggregate)
         commands(aggregate).any? { |verb| (verb["givens"] || []).any? { |given| deep_lookup?(given["ast"]) } }
       end
 
       # A `where` whose field crosses two `/` — `member/sponsor/standing`.
+      #
+      # @param aggregate [Hash] a string-keyed aggregate IR hash
+      # @return [Boolean] true if any query's own where clause crosses at least
+      #   two `/` hops
       def multi_hop_where?(aggregate)
         queries(aggregate).any? { |query| (query["wheres"] || []).any? { |where| where["field"].to_s.count("/") >= 2 } }
       end
 
       # A command attribute sharing a name with one of the aggregate's
-      # own reference-typed attributes while carrying a DIFFERENT, non-
+      # own reference-typed attributes while carrying a different, non-
       # reference type — `attribute :member, Handle` against
       # `reference_to Member`.
+      #
+      # @param aggregate [Hash] a string-keyed aggregate IR hash
+      # @return [Boolean] true if any command redeclares one of the aggregate's
+      #   own reference-typed attribute names under a non-reference type
       def revalued_reference?(aggregate)
         references = attributes(aggregate).select { |held| reference?(held) }.to_set { |held| held["name"].to_s }
         commands(aggregate).any? do |verb|
@@ -94,6 +163,11 @@ module Hecks
 
       # Walks a given's own exported AST for any `lookup` whose path is
       # long enough to have crossed two references.
+      #
+      # @param node [Hash, Array, Object] an AST node (or subtree) from an
+      #   exported given's `"ast"`
+      # @return [Boolean] true if any `lookup` node's own path is at least
+      #   `TWO_HOP_GIVEN_PATH_LENGTH` long
       def deep_lookup?(node)
         case node
         when Hash
@@ -108,21 +182,39 @@ module Hecks
       end
 
       # Every form, answered for one aggregate — the table above, applied.
+      #
+      # @param aggregate [Hash] a string-keyed aggregate IR hash
+      # @return [Hash{String => Boolean}] every `FORMS` name mapped to whether
+      #   `aggregate` exhibits it
       def properties(aggregate)
         FORMS.transform_values { |form| form.call(aggregate) }
       end
 
       # Every unordered pair of forms, each rendered "left + right" in
       # alphabetical order — the key both gates' excuse tables use.
+      #
+      # @return [Array<String>] every unordered pair of `FORMS` names, as
+      #   `"left + right"`
       def pairs
         FORMS.keys.combination(2).map { |pair| pair_key(*pair) }
       end
 
+      # Renders two form names as one sorted pair key.
+      #
+      # @param left [String] a form name
+      # @param right [String] a form name
+      # @return [String] `left`/`right`, alphabetically ordered, joined as
+      #   `"left + right"`
       def pair_key(left, right) = [left, right].sort.join(" + ")
 
       # `held` is `[[aggregate_name, properties], ...]`. Answers which
-      # pairs are met on ONE aggregate, and by which — a Hash from pair
+      # pairs are met on one aggregate, and by which — a Hash from pair
       # key to the names carrying it, so a caller can say who.
+      #
+      # @param held [Array<Array(String, Hash)>] `[aggregate_name, properties]`
+      #   pairs, `properties` as returned by `#properties`
+      # @return [Hash{String => Array<String>}] every met pair key mapped to the
+      #   aggregate names that carry it
       def covered_pairs(held)
         held.each_with_object(Hash.new { |h, k| h[k] = [] }) do |(name, shows), covered|
           shows.select { |_, present| present }.keys.combination(2).each do |left, right|
@@ -134,33 +226,42 @@ module Hecks
       # `[[\"Chapter::Aggregate\", properties], ...]` for every aggregate
       # a string-keyed chapter IR declares — the same walk the golden
       # spec makes over `spec/golden/ir/*.json`.
+      #
+      # @param chapter_ir [Hash] a string-keyed chapter IR hash, with `"name"` and
+      #   `"aggregates"`
+      # @return [Array<Array(String, Hash)>] `["Chapter::Aggregate", properties]`
+      #   pairs, one per declared aggregate, `properties` as returned by
+      #   `#properties`
       def aggregates_in(chapter_ir)
         (chapter_ir["aggregates"] || []).map do |aggregate|
           ["#{chapter_ir['name']}::#{aggregate['name']}", properties(aggregate)]
         end
       end
 
-      # WHERE A DOMAIN PATH KEEPS ITS BLUEBOOKS — `<domain>/bluebook/*.
-      # bluebook` (every example and stress domain), or the directory
-      # itself (`qa/bluebook`, the ledger's own `Target.path`): the same
-      # two shapes `bin/model_check`'s `bluebook_in` reads. `nil` when
-      # neither holds a bluebook.
+      # Where a domain path keeps its bluebooks — see
+      # `Hecks::Corpus.bluebook_files`, the one definition every corpus
+      # walk shares. `nil` when neither shape holds a bluebook.
+      #
+      # @param domain_path [String] path to a domain directory
+      # @return [Array<String>, nil] the domain's own `.bluebook` file paths, or
+      #   `nil` if it holds none
       def bluebook_files(domain_path)
-        [File.join(domain_path, "bluebook"), domain_path].each do |dir|
-          files = Dir[File.join(dir, "*.bluebook")]
-          return files unless files.empty?
-        end
-        nil
+        Hecks::Corpus.bluebook_files(domain_path)
       end
 
-      # THE SAME CENSUS OVER A DOMAIN ON DISK, booted the lightweight
+      # The same census over a domain on disk, booted the lightweight
       # way `bin/model_check` and `Hecks::Codemod.load_bluebook` already
       # do (ports and the two in-process adapters, no `Hecks.boot`, no
-      # live database, no `.hecksagon`: the census reads declared SHAPE,
+      # live database, no `.hecksagon`: the census reads declared shape,
       # and a framework chapter a `.hecksagon` would attach is not this
       # domain's own). Only the domain's own chapter is measured — the
       # first bluebook loaded, the same "target chapter is always first"
       # fact `bin/project_rust` relies on.
+      # @param domain_path [String] path to a domain directory
+      # @return [Array<Array(String, Hash)>] `["Chapter::Aggregate", properties]`
+      #   pairs, one per aggregate declared on `domain_path`'s own first-loaded
+      #   chapter (see `Hecks::Projector::Exporter.call`)
+      # @raise [ArgumentError] if `domain_path` has no bluebook files to measure
       def census(domain_path)
         root = File.expand_path("../../..", __dir__)
         files = bluebook_files(domain_path)

data/lib/hecks/fuzzing/generated_domain_check.rb

@@ -0,0 +1,171 @@
+require "json"
+require_relative "isolated_boot"
+require_relative "sequence_generator"
+require_relative "replay"
+require_relative "shrinker"
+require_relative "differential"
+
+module Hecks
+  module Fuzzing
+    # **One generated domain, checked** — the child-process half of
+    # `bin/qa_generated_domains` (one domain per process: every generated
+    # domain is named `QaGenerated`, see DomainGenerator's header).
+    #
+    # The same comparisons `bin/qa_sweep` runs on a rotation target, over
+    # sequences generated against a domain nobody wrote: with a compiled
+    # binary, `Differential.diff` (Ruby vs Rust, self-consistency, declared
+    # properties); without one, a Ruby-only replay (properties,
+    # self-consistency, an interpreter crash). A domain that does not even
+    # boot is `invalid` — a generator defect, not a finding, reported apart.
+    #
+    # `match:` is how domain-level shrinking asks "does this smaller domain
+    # still show the same finding?": only a divergence in the same mode
+    # whose `Shrinker.signature` contains the original's counts. Verb names
+    # survive a removal that did not touch them, so the signature does too.
+    module GeneratedDomainCheck
+      DIFFERENTIAL_MODES = %i[differential self_consistency properties_in_differential].freeze
+
+      module_function
+
+      # Checks one generated domain over up to `seeds` generated sequences, stopping
+      # at the first divergence found.
+      #
+      # @param domain_path [String] path to the generated domain directory
+      # @param seeds [Integer] maximum number of seeds to try before declaring clean
+      # @param steps [Integer] steps to generate per seed
+      # @param adversarial [Float] fraction of command steps to mutate adversarially
+      # @param binary [String, nil] path to a compiled Rust conformance binary to
+      #   diff against, or `nil` for a Ruby-only check
+      # @param differ [Object, nil] duck-typed comparison helper answering
+      #   `RustConformanceHelpers`' interface (adapter-defined; constructed ad hoc
+      #   by callers such as bin/qa_generated_domains), or `nil`
+      # @param match [Hash, nil] `{"mode" =>, "signature" =>}` from a parent
+      #   domain's own finding — only a divergence matching it counts, for
+      #   domain-level shrinking; `nil` accepts the first divergence found
+      # @param shrink_budget [Integer] step-level shrink attempts to spend on a
+      #   found finding; `0` skips shrinking
+      # @return [Hash] `{"status" => "invalid", "error" =>}` if the domain does not
+      #   boot; `{"status" => "clean", "seeds_run" =>}` if no seed diverged;
+      #   otherwise a finding merged with `{"status" => "found", "seeds_run" =>}`
+      #   (see `#finding`), plus `"shrunk_steps"` when `shrink_budget` is positive
+      def run(domain_path, seeds:, steps:, adversarial:, binary: nil, differ: nil, match: nil, shrink_budget: 0)
+        error = boot_error(domain_path)
+        return { "status" => "invalid", "error" => error } if error
+
+        (1..seeds).each do |seed|
+          finding = check_seed(domain_path, seed, steps, adversarial, binary, differ, match)
+          next unless finding
+
+          finding["shrunk_steps"] = shrink(domain_path, finding, binary, differ, shrink_budget) if shrink_budget.positive?
+          return finding.merge("status" => "found", "seeds_run" => seed)
+        end
+        { "status" => "clean", "seeds_run" => seeds }
+      end
+
+      # Boots `domain_path` in an isolated copy, to find out whether it boots at all.
+      #
+      # @param domain_path [String] path to the domain directory to boot
+      # @return [String, nil] `nil` if the boot succeeds; otherwise the raising
+      #   exception's class and first message line
+      def boot_error(domain_path)
+        IsolatedBoot.call(domain_path) { |copy| Hecks.boot(copy) }
+        nil
+      rescue StandardError, ScriptError => e
+        "#{e.class}: #{e.message.lines.first&.strip}"
+      end
+
+      # Generates one sequence for `seed` and checks it for a divergence.
+      #
+      # @param domain_path [String] path to the domain directory
+      # @param seed [Integer] RNG seed for `SequenceGenerator.generate`
+      # @param steps [Integer] steps to generate
+      # @param adversarial [Float] fraction of command steps to mutate adversarially
+      # @param binary [String, nil] path to a compiled Rust conformance binary, or
+      #   `nil` for a Ruby-only check
+      # @param differ [Object, nil] duck-typed comparison helper answering
+      #   `RustConformanceHelpers`' interface (adapter-defined), or `nil`
+      # @param match [Hash, nil] `{"mode" =>, "signature" =>}` a divergence must
+      #   match to count, or `nil` to accept the first one found
+      # @return [Hash, nil] a finding (see `#finding`) if a matching divergence was
+      #   found, or if generation itself crashed; `nil` if the sequence was clean
+      def check_seed(domain_path, seed, steps, adversarial, binary, differ, match)
+        sequence = SequenceGenerator.generate(domain_path, seed: seed, steps: steps, adversarial: adversarial)
+      rescue StandardError => e
+        finding(seed, :generator, [{ field: "generator_crash", detail: "#{e.class}: #{e.message}" }], [], match)
+      else
+        outcomes(domain_path, sequence, binary, differ).each do |mode, divergences|
+          found = finding(seed, mode, divergences, sequence, match)
+          return found if found
+        end
+        nil
+      end
+
+      # Runs the comparison appropriate to whether a compiled binary is available:
+      # `Differential.diff` against Rust when `binary` is given, otherwise a
+      # Ruby-only replay checked for property and self-consistency divergences.
+      #
+      # @param domain_path [String] path to the domain directory
+      # @param sequence [Array<Hash>] the generated step sequence to replay
+      # @param binary [String, nil] path to a compiled Rust conformance binary, or
+      #   `nil` for a Ruby-only check
+      # @param differ [Object, nil] duck-typed comparison helper answering
+      #   `RustConformanceHelpers`' interface (adapter-defined), or `nil`
+      # @return [Hash{Symbol => Array<Hash>}] one divergence list per mode checked;
+      #   `{ruby_only: [{field: "crash", detail:}]}` if the Ruby-only replay itself
+      #   raised
+      def outcomes(domain_path, sequence, binary, differ)
+        return Differential.diff(differ, domain_path, sequence, binary, modes: DIFFERENTIAL_MODES) if binary
+
+        history = Replay.call(domain_path, sequence, self_consistency: true)
+        { ruby_only:        Differential.property_divergences(history),
+          self_consistency: Differential.self_consistency_divergences(history) }
+      rescue StandardError => e
+        { ruby_only: [{ field: "crash", detail: "#{e.class}: #{e.message}" }] }
+      end
+
+      # Builds a reported finding from a mode's divergences, unless `divergences`
+      # is empty or `match` names a different signature.
+      #
+      # @param seed [Integer] the seed that produced `sequence`
+      # @param mode [Symbol] the comparison mode the divergences came from
+      # @param divergences [Array<Hash>] divergence entries for `mode`
+      # @param sequence [Array<Hash>] the generated step sequence
+      # @param match [Hash, nil] `{"mode" =>, "signature" =>}` the finding must
+      #   match, or `nil` to accept any
+      # @return [Hash, nil] `{"seed" =>, "mode" =>, "signature" =>, "steps" =>,
+      #   "divergences" =>}` if `divergences` is non-empty and matches `match`;
+      #   `nil` otherwise
+      def finding(seed, mode, divergences, sequence, match)
+        return nil if divergences.empty?
+
+        signature = Shrinker.signature(divergences)
+        return nil if match && !(match["mode"] == mode.to_s && Set.new(match["signature"]).subset?(signature))
+
+        { "seed" => seed, "mode" => mode.to_s, "signature" => signature.to_a.sort, "steps" => sequence,
+          "divergences" => JSON.parse(JSON.generate(divergences)) }
+      end
+
+      # The step-level half of shrinking, in this same process: the domain
+      # is already as small as the parent could make it.
+      #
+      # @param domain_path [String] path to the (already domain-shrunk) domain
+      #   directory
+      # @param found [Hash] the finding to shrink, as returned by `#finding`
+      # @param binary [String, nil] path to a compiled Rust conformance binary, or
+      #   `nil` for a Ruby-only check
+      # @param differ [Object, nil] duck-typed comparison helper answering
+      #   `RustConformanceHelpers`' interface (adapter-defined), or `nil`
+      # @param budget [Integer] step-level shrink attempts to spend
+      # @return [Array<Hash>] the smallest step list found that still reproduces
+      #   `found`'s divergence signature
+      def shrink(domain_path, found, binary, differ, budget)
+        original = Set.new(found["signature"])
+        mode = found["mode"].to_sym
+        Shrinker.call(found["steps"], budget: budget) do |candidate|
+          divergences = outcomes(domain_path, candidate, binary, differ)[mode] || []
+          Shrinker.reproduces?(original, divergences)
+        end.steps
+      end
+    end
+  end
+end