hecks 2.6.0 → 2.8.0

data/lib/hecks/fuzzing/shrinker.rb

@@ -1,309 +0,0 @@
-module Hecks
-  module Fuzzing
-    # A failing step list, made small enough to read.
-    #
-    # `bin/fuzz` always shrank its findings; `bin/qa_sweep` — the loop that
-    # actually finds the bugs — never did, so the ledger filled with
-    # demonstrations like "seed 25, 25 steps, step 16" and a human cut
-    # BUG#40 down to its four real steps by hand. This is `bin/fuzz`'s
-    # shrinker lifted out of that script so both callers share it, and
-    # made cheaper at the same time: a sweep's candidate check can cost a
-    # Rust subprocess (or a real Postgres round trip), where `bin/fuzz`'s
-    # only ever cost an in-process replay.
-    #
-    # ## Ownership of "same finding"
-    #
-    # The caller owns it. `call` is handed a block that
-    # answers true when a candidate step list still reproduces what the
-    # original did — `bin/fuzz` compares its own verdict signature,
-    # `bin/qa_sweep` compares `Shrinker.signature` of one mode's
-    # divergences. This module never replays anything itself, so it has
-    # no idea which engine, adapter or comparison it is minimizing for.
-    #
-    # ## Two passes, in order
-    #
-    #   1. Steps, chunks first. Removing one step at a time (what
-    #      `bin/fuzz` did) costs O(n²) candidate checks on a sequence
-    #      where most steps are irrelevant. Delta-debugging style: try
-    #      removing halves, then quarters, … then single steps, keeping
-    #      any removal that still reproduces; a single-step pass repeats
-    #      until it changes nothing, so the result is 1-minimal (no one
-    #      remaining step can be dropped).
-    #   2. Arguments, inside each surviving step. Unchanged from `bin/fuzz`
-    #      (spec/bin_fuzz_spec.rb pins its accumulation contract): drop
-    #      one key at a time from the step's current args, keep it dropped
-    #      only while the finding still reproduces.
-    #
-    # ## Budget
-    #
-    # A budget, because a sweep has other targets waiting. `budget:` caps
-    # how many candidate checks one call may spend (nil = unbounded, the
-    # `bin/fuzz` behaviour). When it runs out the best candidate found so
-    # far is returned — every accepted candidate reproduced, so a partial
-    # shrink is still a correct, just less small, demonstration.
-    module Shrinker
-      Result = Struct.new(:steps, :attempts, :exhausted, keyword_init: true)
-
-      module_function
-
-      # Shrinks `steps` to the smallest step list the block still accepts as
-      # reproducing the original finding — pass 1 (steps), then pass 2
-      # (arguments), as this module's own header describes.
-      #
-      # @param steps [Array<Hash>] the step list to shrink, each step a command,
-      #   query, or read-model hash as `SequenceGenerator` produces
-      # @param budget [Integer, nil] maximum candidate checks to spend; nil for
-      #   unbounded
-      # @yield [candidate] tests whether a candidate step list still reproduces
-      #   the finding being shrunk
-      # @yieldparam candidate [Array<Hash>] a step-dropped or argument-trimmed
-      #   copy of `steps`
-      # @yieldreturn [Boolean] true if `candidate` still reproduces the finding
-      # @return [Fuzzing::Shrinker::Result] `steps:` the shrunk step list,
-      #   `attempts:` how many candidate checks were spent, `exhausted:` whether
-      #   the budget ran out before shrinking finished
-      # @raise [ArgumentError] if no block is given
-      def call(steps, budget: nil, &reproduces)
-        raise ArgumentError, "Shrinker.call needs a block answering whether a candidate reproduces" unless reproduces
-
-        meter   = Meter.new(budget)
-        current = drop_steps(steps.dup, meter, &reproduces)
-        current = drop_arguments(current, meter, &reproduces)
-        Result.new(steps: current, attempts: meter.used, exhausted: meter.exhausted?)
-      end
-
-      # Runs pass 1 of the shrink: delta-debugging removal of step chunks,
-      # halving the chunk size each full pass until single steps are tried
-      # and nothing more can be dropped.
-      #
-      # @param steps [Array<Hash>] the step list to shrink
-      # @param meter [Fuzzing::Shrinker::Meter] the shared budget meter
-      # @yield [candidate] tests whether a candidate step list still reproduces
-      #   the finding being shrunk
-      # @yieldparam candidate [Array<Hash>] `steps` with one chunk removed
-      # @yieldreturn [Boolean] true if `candidate` still reproduces the finding
-      # @return [Array<Hash>] the smallest step list pass 1 could reach, or the
-      #   best found so far if the budget ran out first
-      def drop_steps(steps, meter, &reproduces)
-        current = steps
-        chunk = [current.length / 2, 1].max
-        loop do
-          changed = false
-          index = 0
-          while index < current.length
-            return current if meter.exhausted?
-
-            candidate = current[0...index] + (current[(index + chunk)..] || [])
-            if candidate.empty?
-              index += chunk
-              next
-            end
-
-            if meter.try { reproduces.call(candidate) }
-              current = candidate
-              changed = true
-            else
-              index += chunk
-            end
-          end
-
-          if chunk > 1
-            chunk = [chunk / 2, 1].max
-          elsif !changed
-            break
-          end
-        end
-        current
-      end
-
-      # Runs pass 2 of the shrink: drops one argument key at a time from
-      # each surviving step's args, keeping the drop only while the
-      # finding still reproduces.
-      #
-      # See the module header's pass 2 — `args` is read by whichever
-      # spelling the step actually carries (`key?` first, never `||`,
-      # which cannot tell a stored `false` from an absent key).
-      #
-      # @param steps [Array<Hash>] the step list, already step-shrunk by `drop_steps`
-      # @param meter [Fuzzing::Shrinker::Meter] the shared budget meter
-      # @yield [candidate] tests whether a candidate step list still reproduces
-      #   the finding being shrunk
-      # @yieldparam candidate [Array<Hash>] `steps` with one step's one argument
-      #   key dropped
-      # @yieldreturn [Boolean] true if `candidate` still reproduces the finding
-      # @return [Array<Hash>] `steps` with every argument key `drop_arguments`
-      #   accepted dropped
-      def drop_arguments(steps, meter, &reproduces)
-        steps.each_index do |position|
-          original = args_of(steps[position])
-          next unless original.is_a?(Hash)
-
-          original.each_key do |key|
-            return steps if meter.exhausted?
-
-            step      = steps[position]
-            trimmed   = args_of(step).reject { |name, _| name == key }
-            candidate = steps.map(&:dup)
-            candidate[position] = step.merge("args" => trimmed)
-            steps = candidate if meter.try { reproduces.call(candidate) }
-          end
-        end
-        steps
-      end
-
-      # Reads a step's argument hash, whichever key spelling it uses.
-      #
-      # @param step [Hash] one step, string- or symbol-keyed
-      # @return [Hash, nil] the step's `"args"` value if the step is string-keyed,
-      #   else its `:args` value (nil if neither key is present)
-      def args_of(step)
-        step.key?("args") ? step["args"] : step[:args]
-      end
-
-      # Which finding this is, as a set of stable strings — the identity a
-      # shrink candidate has to keep. The `field` alone is too loose for
-      # the comparisons that carry lists: "refusals differ" on a 3-step
-      # candidate could be a different refusal split than the one the
-      # original seed found, and a shrinker that accepted it would hand
-      # back a demonstration of the wrong bug. So:
-      #
-      #   refusals/queries/dry_runs/reactions — the field plus every verb
-      #     (or query) named in the symmetric difference of the two sides;
-      #   instances — the field plus the aggregate of every top-level key
-      #     whose two sides disagree (the `#id` suffix dropped);
-      #   a crash/process finding — the field plus the exception class
-      #     leading its detail;
-      #   anything else (a property name, a self-consistency axis) — the
-      #     field, which already names the finding.
-      #
-      # `reproduces?` holds when a candidate's signature contains the
-      # original's: removing steps may add a second divergence, but it
-      # must never lose the one being demonstrated.
-      LIST_FIELDS = %w[refusals queries dry_runs reactions].freeze
-
-      CRASH_FIELDS = %w[crash process generator_crash].freeze
-
-      # Computes which finding a set of divergences is — the stable identity
-      # a shrink candidate has to keep. See this method's own preceding
-      # comment for what each field kind contributes.
-      #
-      # @param divergences [Array<Hash>] divergence entries, each at least
-      #   `{field:, detail:}` plus whichever mode-specific keys carry the two
-      #   compared sides
-      # @return [Set<String>] stable identity strings: each divergence's `field`,
-      #   plus `detail_keys`' own per-field detail strings
-      def signature(divergences)
-        divergences.each_with_object(Set.new) do |divergence, keys|
-          field = divergence[:field].to_s
-          keys << field
-          keys.merge(detail_keys(field, divergence))
-        end
-      end
-
-      # Extracts the finer-grained identity strings one divergence's field
-      # contributes beyond the field name itself.
-      #
-      # @param field [String] the divergence's `field`, stringified
-      # @param divergence [Hash] the divergence entry `field` came from
-      # @return [Array<String>] extra identity strings for `field`'s own kind
-      #   (list, `instances`, or crash/process); empty for any other field
-      def detail_keys(field, divergence)
-        left, right = divergence.except(:field, :detail).values.select { |v| v.is_a?(Array) || v.is_a?(Hash) }
-        if LIST_FIELDS.include?(field) then list_keys(field, left, right)
-        elsif field == "instances"     then instance_keys(left, right)
-        elsif CRASH_FIELDS.include?(field) && divergence[:detail]
-          ["#{field}:#{divergence[:detail].to_s[/\A\w+(?:::\w+)*/]}"]
-        else []
-        end
-      end
-
-      # Names the rows present on one side of a list-field divergence and not
-      # the other.
-      #
-      # @param field [String] the divergence's field name, prefixed onto each key
-      # @param left [Array, nil] one side's list; a non-Array yields no keys
-      # @param right [Array, nil] the other side's list; a non-Array yields no keys
-      # @return [Array<String>] `"field:name"` for every row in the symmetric
-      #   difference of `left` and `right`; empty unless both are arrays
-      def list_keys(field, left, right)
-        return [] unless left.is_a?(Array) && right.is_a?(Array)
-
-        ((left - right) + (right - left)).map { |row| "#{field}:#{named(row)}" }
-      end
-
-      # Names the top-level keys the two sides of an `instances` divergence
-      # disagree on.
-      #
-      # Instance keys are `Aggregate#id` on the wire — the id is whatever
-      # the generator minted, so it names the record, not the finding;
-      # keeping it would pin every creating step.
-      #
-      # @param left [Hash, nil] one side's instance snapshot; a non-Hash yields no keys
-      # @param right [Hash, nil] the other side's instance snapshot; a non-Hash
-      #   yields no keys
-      # @return [Array<String>] `"instances:Aggregate"` for every top-level key
-      #   the two sides disagree on, its `#id` suffix dropped; empty unless both
-      #   are hashes
-      def instance_keys(left, right)
-        return [] unless left.is_a?(Hash) && right.is_a?(Hash)
-
-        (left.keys | right.keys).reject { |key| left[key] == right[key] }
-                                .map { |key| "instances:#{key.to_s.split('#').first}" }
-      end
-
-      # Checks that a candidate's own divergences still demonstrate the
-      # finding being shrunk.
-      #
-      # @param original_signature [Set<String>] the finding's own signature, as
-      #   returned by `signature`
-      # @param divergences [Array<Hash>] the candidate's own divergence entries,
-      #   in `signature`'s own shape
-      # @return [Boolean] true if `divergences` is non-empty and its signature is
-      #   a superset of `original_signature`
-      def reproduces?(original_signature, divergences)
-        !divergences.empty? && original_signature.subset?(signature(divergences))
-      end
-
-      # Names one row from a list-field divergence, for `list_keys`.
-      #
-      # @param row [Object] one item from a list-field divergence's array;
-      #   typically a Hash carrying a `verb`, `query`, or `policy` key (string
-      #   or symbol)
-      # @return [String] `row`'s `verb`/`query`/`policy` value, stringified, if
-      #   `row` is a Hash carrying one of those keys; otherwise `row.to_s`
-      def named(row)
-        return row.to_s unless row.is_a?(Hash)
-
-        key = [%w[verb query policy], %i[verb query policy]].flatten.find { |name| row.key?(name) }
-        (key ? row[key] : row).to_s
-      end
-
-      # Counts candidate checks against the budget.
-      class Meter
-        attr_reader :used
-
-        # @param budget [Integer, nil] maximum candidate checks to allow; nil for unbounded
-        def initialize(budget)
-          @budget = budget
-          @used   = 0
-        end
-
-        # Reports whether this meter's budget has been fully spent.
-        #
-        # @return [Boolean] true if a budget is set and every allotted check has
-        #   been used
-        def exhausted? = !@budget.nil? && @used >= @budget
-
-        # Spends one candidate check against the budget and runs the block.
-        #
-        # @yield runs the candidate check being counted
-        # @yieldreturn [Object] the block's own result
-        # @return [Object] whatever the block returns
-        def try
-          @used += 1
-          yield
-        end
-      end
-    end
-  end
-end

data/lib/hecks/fuzzing/structural_skips.rb

@@ -1,53 +0,0 @@
-module Hecks
-  module Fuzzing
-    # What each query verb the differential comparison skipped was hiding.
-    #
-    # `Differential.manifest_partition` drops a named query or read model
-    # from both sides of the Ruby/Rust comparison only when the binary's own
-    # manifest.json declares it `generated: false`. The drop is correct, but
-    # a sweep that dropped every `offset`/`cursor` ask would still read as
-    # "agreed across all steps". `bin/qa_sweep` therefore logs one Check per
-    # sweep naming every skipped verb and the construct family that caused
-    # it, and marks it Surprised when a family is outside
-    # `QualityControlDials::STRUCTURAL_REFUSAL_BOUNDARY`.
-    #
-    # The construct comes straight from the manifest entry, written by the
-    # generator branch that made the skip (`Projector::SkipReason`), rather
-    # than guessed from the Ruby declaration's `to_h` keys, which is coarser
-    # than codegen's own decision and can drift from it.
-    module StructuralSkips
-      module_function
-
-      # Attributes each skipped verb to the construct family its manifest
-      # entry names.
-      #
-      # One entry per skipped verb: `{ verb:, constructs: [...] }`, sorted by
-      # verb so the printed observation is stable across seeds and runs. A
-      # verb the manifest doesn't declare answers `unknown`, which no
-      # boundary admits.
-      #
-      # @param gaps [Fuzzing::RustGapManifest] the binary's not-generated manifest entries
-      # @param verbs [Array<String>] the skipped query/read-model verbs to attribute
-      # @return [Array<Hash{Symbol => Object}>] one `{ verb: String, constructs: Array<String> }`
-      #   per verb, in sorted-verb order
-      def attribute(gaps, verbs)
-        verbs.sort.map do |verb|
-          entry = gaps.not_generated(verb)
-          { verb: verb, constructs: entry ? [entry.fetch("construct")] : %w[unknown] }
-        end
-      end
-
-      # Selects the attributed entries whose constructs are not all inside `boundary`.
-      #
-      # @param attributed [Array<Hash{Symbol => Object}>] entries as returned by `attribute`
-      # @param boundary [Array<String, Symbol>] the construct families the documented codegen
-      #   boundary admits
-      # @return [Array<Hash{Symbol => Object}>] the subset of `attributed` naming an
-      #   unadmitted construct, or no construct at all
-      def outside_boundary(attributed, boundary)
-        admitted = boundary.map(&:to_s)
-        attributed.select { |entry| entry[:constructs].empty? || (entry[:constructs] - admitted).any? }
-      end
-    end
-  end
-end

data/lib/hecks/fuzzing/sweep_depth.rb

@@ -1,61 +0,0 @@
-module Hecks
-  module Fuzzing
-    # How hard one sweep fuzzes, as a function of `Target.clean_streak`
-    # (qa/bluebook/quality_control.bluebook — that attribute's own comment
-    # says what the streak means). The sibling of `RotationPriority`: the
-    # ledger holds the number, `QualityControlDials::WIDENING_TIERS` holds
-    # the policy, and this module is where the two meet — a pure function
-    # of both, nothing else read.
-    #
-    # Why this is not in `bin/qa_sweep` any more. It was — `WIDENING_TIERS`
-    # and `widen_for_streak` lived at the top of that script, which meant
-    # policy data lived in a script (unlike every other dial, which lives
-    # in the bluebook a human edits and reviews) and duplicated itself as
-    # prose in SKILL.md. Now the table is a dial, this is the one reader,
-    # and `bin/qa_sweep` calls it the way it already calls
-    # `RotationPriority.pick`.
-    #
-    # **Pure, deliberately** — the same discipline `RotationPriority` keeps:
-    # same streak in, same `[seeds, steps]` out, every time, which is what
-    # lets a human predict what a given sweep is about to do before it
-    # runs one. `tiers:` defaults to the dial but is a plain argument, so
-    # a unit spec can pass its own table with no ledger boot at all and a
-    # `bin/qa_sweep` run against a ledger that declares no dials (an
-    # isolated spec's own fixture) can fall back the same way it already
-    # does for `ADVERSARIAL_FRACTION`.
-    module SweepDepth
-      module_function
-
-      # The fallback table, for a boot with no `QualityControlDials` at all
-      # — the same shape and the same three rows the dial ships with, so a
-      # dial-less ledger fuzzes exactly as a dialled one does by default.
-      # Never read when the dial exists; `bin/qa_sweep` passes the dial in.
-      DEFAULT_TIERS = [
-        { upto: 4,               seeds: 10, steps: 25 },
-        { upto: 19,              seeds: 25, steps: 50 },
-        { upto: Float::INFINITY, seeds: 50, steps: 100 }
-      ].freeze
-
-      # `[seeds, steps]` for one streak. The first row whose `upto` the
-      # streak does not exceed wins — rows are read in order, so the table
-      # must be ascending, and the last row's `Float::INFINITY` is what
-      # makes it the ceiling rather than a gap.
-      #
-      # @param streak [Integer] `Target.clean_streak`, the number of consecutive clean sweeps
-      # @param tiers [Array<Hash{Symbol => Numeric}>] ascending `{ upto:, seeds:, steps: }` rows;
-      #   defaults to `DEFAULT_TIERS`
-      # @return [Array(Integer, Integer)] `[seeds, steps]` for the first row `streak` fits under
-      # @raise [ArgumentError] if `streak` is negative
-      # @raise [ArgumentError] if no row in `tiers` covers `streak` (the last row must declare
-      #   `upto: Float::INFINITY`)
-      def for_streak(streak, tiers: DEFAULT_TIERS)
-        raise ArgumentError, "streak must not be negative" if streak.negative?
-
-        tier = tiers.find { |row| streak <= row[:upto] }
-        raise ArgumentError, "no tier covers a streak of #{streak} — the last row must be upto: Float::INFINITY" unless tier
-
-        [tier[:seeds], tier[:steps]]
-      end
-    end
-  end
-end

data/lib/hecks/fuzzing/target_capabilities.rb

@@ -1,255 +0,0 @@
-module Hecks
-  module Fuzzing
-    # What a sweep target can actually be checked for, read off the
-    # filesystem — never off a stored list.
-    #
-    # `bin/qa_sweep` does not decide its comparison modes with inline
-    # conditionals — "is there a Cargo feature named after this directory?
-    # then `:differential`, else `:ruby_only`", a separate hand-typed abort
-    # for `--persistence-parity` ("does any .hecksagon bind PostgresEra?"),
-    # and so on for every further mode the practice adds (era boundary,
-    # concurrency, a WASM front) — because each such inline `if` is a
-    # policy decision hiding in a script. This module is those decisions
-    # as data: `MODE_REQUIREMENTS` says which capabilities each mode
-    # needs, `infer` says which capabilities a target's own directory
-    # actually has, and `resolve` is the one rule that joins them —
-    # `modes_to_run = enabled ∩ eligible`.
-    #
-    # ## Inference decides; a stored list only records
-    #
-    # `Target.capabilities` (qa/bluebook/quality_control.bluebook, once
-    # PR-1's era lands) is written by the runner from exactly this
-    # inference at release time so `Target.EligibleFor(mode)` can audit
-    # the rotation from the ledger alone — but the runner re-infers every
-    # sweep, because a stored list that lags yesterday's Cargo feature is
-    # precisely the "quiet divergence" (the chapter's own opening comment)
-    # this whole practice exists to hunt. Nothing here ever reads the
-    # ledger.
-    #
-    # ## Regex provenance
-    #
-    # Every regex is one the harness already owned, moved here rather than
-    # re-derived, and each one's provenance is named beside it so a
-    # future edit to the original site is a visible drift, not a silent
-    # one: the Cargo feature line (`RustConformanceHelpers#build_rust_for`),
-    # the PostgresEra binding (`bin/qa_sweep`'s old `POSTGRES_ERA_BINDING`),
-    # the translations glob (`IsolatedBoot#strip_translations!`).
-    module TargetCapabilities
-      module_function
-
-      # `RustConformanceHelpers#build_rust_for`'s own test, scoped to the
-      # `[features]` table the way `bin/project_rust`'s Cargo sync scopes
-      # its own lookup (a `[package] name = "rust"` line must never read
-      # as a feature named `rust`).
-      FEATURES_TABLE = /^\[features\](?:\n(?!\[).*)*$/
-
-      # `bin/qa_sweep`'s former `POSTGRES_ERA_BINDING` — both spellings
-      # `IsolatedBoot#rewrite_bindings!` has to catch: aggregate-scoped
-      # (`Directory::Member.persisted_by("PostgresEra")`) and the bare
-      # domain-level default (`persisted_by "PostgresEra"`).
-      POSTGRES_ERA_BINDING = /persisted_by\s*\(?\s*"PostgresEra"/
-
-      # A local variable assigned the bare literal `"PostgresEra"` on a line of
-      # its own (`adapter = "PostgresEra"`). Only the whole-line literal counts:
-      # a ternary or any other right-hand side is not a PostgresEra binding.
-      POSTGRES_ERA_VARIABLE = /^\s*([a-z_]\w*)\s*=\s*"PostgresEra"\s*(?:#.*)?$/
-
-      # `HecksagonBuilder#uses_framework "X"` — captures which member a
-      # hecksagon attaches, whatever its name. Whether that member answers
-      # a role check is then read off its own declaration (`provides
-      # "authorization"`, via `Framework.providers_of`), the same rule
-      # `Registry#authorization_provider_for` applies at runtime — never a
-      # match on the literal "Governance".
-      FRAMEWORK_ATTACHED = /uses_framework\s*\(?\s*"([^"]+)"/
-
-      # A command-level `role "..."` — the only construct
-      # `refuse_role_mismatch` ever has anything to check a caller against.
-      ROLE_GATED = /^\s*role\s+"/
-
-      # `authorize :vault_access, tenant: :branch_code`
-      # (examples/banking/bluebook/safe_deposit_boxes.bluebook) — the one
-      # `tenant:` spelling the corpus has.
-      TENANT_SCOPED = /\btenant:/
-
-      PROCESS_MANAGER = /^\s*process_manager\s+"/
-
-      # Which capabilities each mode needs before it can say anything true
-      # about a target. An empty list means "any target at all" — every
-      # domain boots under Memory, so Ruby-only properties and the
-      # self-consistency pass are always answerable. `ruby_only` is listed
-      # requirement-free on purpose and then excluded by `resolve` whenever
-      # `differential` resolved too: they are the same seat, and a compiled
-      # Rust binary is strictly the better occupant (item 1 of the
-      # detection plan folded the Ruby-only property battery into the
-      # differential seat, so nothing is lost by the exclusion).
-      #
-      # The four `false`-by-default modes in `QualityControlDials::MODES`
-      # (`adapter_parity_postgres`, `era_boundary`, `concurrency`,
-      # `wasm_front`) are named here with their requirements even though
-      # nothing runs them yet — so `resolved modes:` can already say, per
-      # target, which of them would be eligible the day a human flips the
-      # dial, and so flipping it is a one-line data change rather than a
-      # code change plus a data change.
-      MODE_REQUIREMENTS = {
-        differential:               %w[rust],
-        ruby_only:                  [],
-        self_consistency:           [],
-        properties_in_differential: %w[rust],
-        structural_skip_report:     %w[rust],
-        adapter_parity_sqlite:      %w[sqlite],
-        persistence_parity:         %w[postgres_era],
-        adapter_parity_postgres:    %w[postgres_era],
-        era_boundary:               %w[translations postgres_era],
-        concurrency:                %w[postgres_era],
-        wasm_front:                 %w[rust]
-      }.freeze
-
-      # Which of those modes `bin/qa_sweep` can actually run today.
-      # `MODE_REQUIREMENTS` above says what a mode needs; this says what
-      # exists to do it, and the two are not the same. Conflating them is
-      # how `qa/settings.yml` came to enable `wasm_front` and
-      # `adapter_parity_postgres` with nothing behind either — no seat, no
-      # check folded into the seed loop, no `MODE_EXPECTATIONS` entry — while
-      # `resolved modes:` still printed them per target, so the sweep
-      # advertised coverage it never performed. A mode named in
-      # `MODE_REQUIREMENTS` but absent here is one this practice wants and has
-      # not built: `bin/qa_sweep` refuses to start when a dial or `--modes`
-      # enables it, rather than resolving it into a line nobody can act on.
-      # `spec/qa_sweep_runnable_modes_spec.rb` keeps this list honest from
-      # both sides by grepping the runner itself.
-      RUNNABLE_MODES = %i[differential ruby_only self_consistency properties_in_differential
-                          structural_skip_report adapter_parity_sqlite persistence_parity
-                          era_boundary concurrency].freeze
-
-      # Modes that name a separate, expensive pass of their own rather than
-      # an extra check folded into the ordinary per-seed loop —
-      # `bin/qa_sweep` runs these only when asked by name (`--modes
-      # persistence_parity`, or its older alias `--persistence-parity`) or
-      # as `--all`'s own second wave, never silently inside a plain
-      # single-target sweep (the seed cap `PERSISTENCE_PARITY_SEED_CAP`
-      # exists because that pass pays for real Postgres I/O per dispatch).
-      DEFERRED_MODES = %i[persistence_parity adapter_parity_postgres era_boundary concurrency].freeze
-
-      # Reads a target directory to find out which capabilities it actually has.
-      #
-      # Sorted, plain strings — comma-joined by the runner into the
-      # `Target.Release(capabilities:)` value object and printed verbatim
-      # on the `resolved modes:` line, so the same spelling is what a
-      # human reads, what `--all` parses back, and what the ledger stores.
-      #
-      # @param domain_path [String] filesystem path to the target domain's directory
-      # @param rust_dir [String] path to the Rust project root, checked for a matching
-      #   Cargo feature; defaults to this repo's own `rust/` directory
-      # @return [Array<String>] the target's capabilities, sorted; a subset of
-      #   `sqlite`, `rust`, `postgres_era`, `translations`, `governance`, `role_gated`,
-      #   `tenant`, `sagas`
-      def infer(domain_path, rust_dir: File.expand_path("../../../rust", __dir__))
-        capabilities = %w[sqlite]
-        capabilities << "rust" if rust_feature?(domain_path, rust_dir)
-        capabilities << "postgres_era" if postgres_era_bound?(domain_path)
-        capabilities << "translations" if Dir.glob(File.join(domain_path, "**", "translations", "*.bluebook")).any?
-        capabilities << "governance" if authorization_attached?(domain_path)
-        capabilities << "role_gated" if any_file?(domain_path, "*.bluebook", ROLE_GATED)
-        capabilities << "tenant" if any_file?(domain_path, "*.bluebook", TENANT_SCOPED)
-        capabilities << "sagas" if any_file?(domain_path, "*.bluebook", PROCESS_MANAGER)
-        capabilities.sort
-      end
-
-      # Answers whether `mode` can run against a target with `capabilities`.
-      #
-      # @param mode [Symbol, String] a key of `MODE_REQUIREMENTS`, such as `:differential`
-      # @param capabilities [Array<String>] the target's capabilities, as `infer` returns
-      # @return [Boolean] whether `capabilities` covers every capability `mode` requires
-      # @raise [ArgumentError] if `mode` names no entry in `MODE_REQUIREMENTS`
-      def eligible?(mode, capabilities)
-        required = MODE_REQUIREMENTS.fetch(mode.to_sym) { raise ArgumentError, "unknown sweep mode #{mode.inspect}" }
-        (required - capabilities).empty?
-      end
-
-      # The one rule. `enabled` is whatever the dial (or `--modes`) turned
-      # on, in the dial's own declaration order — that order is preserved
-      # so the printed line reads the same way the dial does. Then the
-      # single exclusion named on `MODE_REQUIREMENTS`.
-      #
-      # @param enabled [Array<Symbol, String>] modes turned on, in the dial's own
-      #   declaration order
-      # @param capabilities [Array<String>] the target's capabilities, as `infer` returns
-      # @return [Array<Symbol>] `enabled`'s eligible modes, in `enabled`'s order, with
-      #   `:ruby_only` dropped whenever `:differential` is also eligible
-      def resolve(enabled, capabilities)
-        resolved = enabled.map(&:to_sym).select { |mode| eligible?(mode, capabilities) }
-        resolved.delete(:ruby_only) if resolved.include?(:differential)
-        resolved
-      end
-
-      # Answers whether `rust_dir`'s Cargo.toml declares a feature named after
-      # `domain_path`'s own directory.
-      #
-      # @param domain_path [String] filesystem path to the target domain's directory;
-      #   its basename, lowercased, is the feature name looked up
-      # @param rust_dir [String] path to the Rust project root (holds `Cargo.toml`)
-      # @return [Boolean] whether a matching Cargo feature is declared; false if
-      #   `rust_dir` has no `Cargo.toml`
-      def rust_feature?(domain_path, rust_dir)
-        cargo_toml = File.join(rust_dir, "Cargo.toml")
-        return false unless File.file?(cargo_toml)
-
-        feature  = File.basename(domain_path).downcase
-        features = File.read(cargo_toml)[FEATURES_TABLE] || ""
-        features.match?(/^#{Regexp.escape(feature)}\s*=\s*\[\]/)
-      end
-
-      # Answers whether any `.hecksagon` under `domain_path` binds PostgresEra,
-      # either with the literal name or through a local variable that the same
-      # file assigned `"PostgresEra"` and then passed to `persisted_by`.
-      #
-      # @param domain_path [String] filesystem path to the target domain's directory
-      # @return [Boolean] whether a PostgresEra `persisted_by` binding is found
-      def postgres_era_bound?(domain_path)
-        Dir.glob(File.join(domain_path, "**", "*.hecksagon")).any? do |path|
-          text = File.read(path)
-          text.match?(POSTGRES_ERA_BINDING) || postgres_era_variable_bound?(text)
-        end
-      end
-
-      # Answers whether `text` passes a variable assigned `"PostgresEra"` to `persisted_by`.
-      #
-      # @param text [String] the contents of one `.hecksagon` file
-      # @return [Boolean] whether some `persisted_by` call names such a variable
-      def postgres_era_variable_bound?(text)
-        text.scan(POSTGRES_ERA_VARIABLE).flatten.any? do |name|
-          text.match?(/persisted_by\s*\(?\s*#{Regexp.escape(name)}(?!\w)/)
-        end
-      end
-
-      # Answers whether any `.hecksagon` under `domain_path` attaches a member
-      # that provides authorization.
-      #
-      # The capability label stays "governance" — it is the value
-      # `bin/qa_sweep` writes into the QualityControl ledger's
-      # `Target.capabilities`, and renaming it is a ledger change, not
-      # part of dropping the name check.
-      #
-      # @param domain_path [String] filesystem path to the target domain's directory
-      # @return [Boolean] whether the domain attaches a member that provides the
-      #   `Bluebook::Capabilities::AUTHORIZATION` capability
-      def authorization_attached?(domain_path)
-        attached = Dir.glob(File.join(domain_path, "**", "*.hecksagon"))
-                      .flat_map { |path| File.read(path).scan(FRAMEWORK_ATTACHED).flatten }.uniq
-        providers = Framework.providers_of(Bluebook::Capabilities::AUTHORIZATION)
-        attached.intersect?(providers)
-      end
-
-      # Answers whether any file under `domain_path` matching `glob` contains `pattern`.
-      #
-      # @param domain_path [String] filesystem path to the target domain's directory
-      # @param glob [String] a `Dir.glob` pattern relative to `domain_path`, such as
-      #   `"*.bluebook"`
-      # @param pattern [Regexp] the pattern each matching file's contents is tested against
-      # @return [Boolean] whether any matching file's contents match `pattern`
-      def any_file?(domain_path, glob, pattern)
-        Dir.glob(File.join(domain_path, "**", glob)).any? { |path| File.read(path).match?(pattern) }
-      end
-    end
-  end
-end