hecks 2.6.0 → 2.8.0

data/lib/hecks/fuzzing/era_boundary.rb

@@ -1,154 +0,0 @@
-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
-    # question; this one asks a single, unconditional question of a
-    # 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
-    # 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
-    # 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
-    # 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
-    # connection walking straight through the era write-fence — fixed by
-    # refusing that connection outright, `Lineage#check_fence_applies!`).
-    # Both are "a fork happened and nothing said so" — this module is the
-    # automatic version of the question `bin/merge_tail`'s own diagnostic
-    # line already answers by hand, run as an ordinary sweep Check instead
-    # of only when a human remembers to ask.
-    #
-    # ## 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
-    # 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
-    # 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
-    # reported `checked: false` with the reason — an operational note this
-    # mode's own caller surfaces once, never a crash and never silently
-    # "clean".
-    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, 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 failed("no bluebook in #{directory}") unless bluebook
-
-        first = bluebook.aggregates.first
-        return not_applicable("#{bluebook.name} declares no aggregates") unless first
-
-        adapter_name = Hecks::Ports::Persistence::BindingPolicy.resolve(registry, bluebook.name, first).adapter
-        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)
-        begin
-          lineage = Hecks::Adapters::PostgresEra::Lineage.new(db, bluebook.name)
-          lineage.ensure_base!
-          eras = lineage.eras
-          # `bin/merge_tail`'s own arithmetic, restated read-only: every
-          # ancestor era (every ordinal strictly before the head's own) may
-          # still hold post-cut writes the head has never interleaved.
-          breakdown = if eras.size > 1
-                        (1...eras.last[:ordinal]).map do |ordinal|
-                          { ordinal: ordinal, diverged: lineage.diverged_count(ordinal) }
-                        end
-                      else
-                        []
-                      end
-          { checked: true, era_count: eras.size, breakdown: breakdown, diverged_total: breakdown.sum { |b| b[:diverged] } }
-        ensure
-          db.close
-        end
-      rescue StandardError => e
-        # 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
-
-      # 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 }
-
-      # 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)
-        registry = Hecks::Runtime::Registry.new(root: File.dirname(directory))
-        Hecks.with_registry(registry) do
-          loading.load_library
-          loading.load_project(loading.shared_root(nil, directory))
-          loading.load_domain(directory)
-        end
-        [registry, directory]
-      end
-    end
-  end
-end

data/lib/hecks/fuzzing/form_census.rb

@@ -1,285 +0,0 @@
-require "json"
-require_relative "../corpus"
-
-module Hecks
-  module Fuzzing
-    # 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
-    # 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
-    # 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
-    # first run of each.
-    #
-    # **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
-    # be read, and added to, at a glance.
-    module FormCensus
-      # A `given`'s own lookup path crossing at least two references —
-      # `member.sponsor.standing`, `source.customer.status`: the
-      # `CommandRules::References#dereference` recursion, walked only
-      # on a fresh command argument (S12, ADR 0025) and hydrated one
-      # repository lookup per hop.
-      TWO_HOP_GIVEN_PATH_LENGTH = 3
-
-      FORMS = {
-        "composite_id"       => ->(a) { (a["identified_by"] || []).size >= 2 },
-        "has_entity"         => ->(a) { entities(a).any? },
-        "two_entities"       => ->(a) { entities(a).size >= 2 },
-        "composite_piece"    => ->(a) { entities(a).any? { |piece| (piece["identified_by"] || []).size >= 2 } },
-        "multi_emit"         => ->(a) { commands(a).any? { |verb| (verb["emits"] || []).size >= 2 } },
-        "lifecycle"          => ->(a) { !a["lifecycle"].nil? },
-        "piece_lifecycle"    => ->(a) { entities(a).any? { |piece| !piece["lifecycle"].nil? } },
-        "has_query"          => ->(a) { queries(a).any? },
-        "list_attr"          => ->(a) { attributes(a).any? { |held| held["list"] } },
-        "reference_attr"     => ->(a) { attributes(a).any? { |held| reference?(held) } },
-        "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
-        # 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
-        # own recursion (`DEREFERENCE_DEPTH`); `multi_hop_where` is a
-        # `/`-chain `HopPath` walks for real and `rust/project/queries.
-        # rb` structurally refuses (D2 of the equivalence-gap plan);
-        # `revalued_reference` is ADR 0037 Finding 5's exact trigger — a
-        # 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) }
-      }.freeze
-
-      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-
-      # 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|
-          (verb["attributes"] || []).any? { |held| references.include?(held["name"].to_s) && !reference?(held) }
-        end
-      end
-
-      # 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
-          return true if node["op"] == "lookup" && Array(node["path"]).size >= TWO_HOP_GIVEN_PATH_LENGTH
-
-          node.each_value.any? { |child| deep_lookup?(child) }
-        when Array
-          node.any? { |child| deep_lookup?(child) }
-        else
-          false
-        end
-      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
-      # 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|
-            covered[pair_key(left, right)] << name
-          end
-        end
-      end
-
-      # `[[\"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 — 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)
-        Hecks::Corpus.bluebook_files(domain_path)
-      end
-
-      # 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,
-      # 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)
-        raise ArgumentError, "#{domain_path} has no bluebook/*.bluebook (or *.bluebook) to measure" if files.nil?
-
-        registry = Hecks::Runtime::Registry.new(root: File.expand_path(domain_path))
-        Hecks.with_registry(registry) do
-          Kernel.load(File.join(root, "lib/hecks/ports/persistence.port"))
-          Kernel.load(File.join(root, "lib/hecks/ports/extraction.port"))
-          Kernel.load(File.join(root, "lib/hecks/adapters/driven/memory.adapter"))
-          Kernel.load(File.join(root, "lib/hecks/adapters/driven/prism.adapter"))
-          files.each { |file| Kernel.load(file) }
-        end
-
-        chapter_name = registry.bluebooks.keys.first
-        exported = JSON.parse(JSON.generate(Hecks::Projector::Exporter.call(registry).fetch(chapter_name)))
-        aggregates_in(exported)
-      end
-    end
-  end
-end

data/lib/hecks/fuzzing/generated_domain_check.rb

@@ -1,171 +0,0 @@
-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