hecks 1.3.0 → 1.4.0

data/lib/hecks/fuzzing/sequence_generator/step_builder.rb

@@ -20,17 +20,17 @@ module Hecks
           { "query" => entry[:verb], "args" => args }
         end
 
-        # A REPORT ASK — the bare domain form `entry[:verb]` already carries
+        # A report ask — the bare domain form `entry[:verb]` already carries
         # ("Domain.report_name", no "::"), so `Dispatcher#query` routes it
         # to the read model rather than an aggregate query. A `ReadModel`
         # has no declared `.attributes` the way a `Query` does — its own
-        # argument surface is exactly ONE key, `reference_name`, and ONLY
+        # argument surface is exactly one key, `reference_name`, and only
         # for a rooted model (`read_model_actionable?` already gated a
         # rootless one straight into eligibility with nothing to supply).
-        # A BARE scalar, not `identity_shaped` — `ReadModelInterpreter#
-        # refuse_object_reference` explicitly REJECTS a Hash/Value offered
+        # A bare scalar, not `identity_shaped` — `ReadModelInterpreter#
+        # refuse_object_reference` explicitly rejects a Hash/Value offered
         # here (this is the one place in the whole generator where the
-        # subject's own identity must NOT be wrapped the way a command
+        # subject's own identity must not be wrapped the way a command
         # argument's would be).
         def build_read_model_step(runtime, entry)
           model = entry[:model]
@@ -40,20 +40,20 @@ module Hecks
           { "query" => entry[:verb], "args" => args }
         end
 
-        # THE ADVERSARIAL LAYER SITS HERE, AND ONLY HERE — after the step's
-        # arguments and identity are fully built, BEFORE the one real
+        # The adversarial layer sits here, and only here — after the step's
+        # arguments and identity are fully built, before the one real
         # dispatch this generator makes to learn what the step did, and
         # before the step is returned as corpus data. That ordering is
         # the whole contract: the mutated `args` are what this generator's
         # own inline dispatch sees (so `known_ids` tracking reflects what
-        # actually happened), AND they are the bytes `Fuzzing::Replay`
+        # actually happened), and they are the bytes `Fuzzing::Replay`
         # later hands Ruby's runtime and the bytes `JSON.generate({steps:
         # ...})` hands the compiled Rust binary — one step, one payload,
         # both engines. Nothing downstream of this method can tell a
         # mutated step from an ordinary one except by reading the
         # `"adversarial"` metadata it carries (see adversary.rb).
         #
-        # TWO MORE DRAWS SIT RIGHT AFTER THE MUTATION, IN A FIXED ORDER —
+        # Two more draws sit right after the mutation, in a fixed order —
         # a caller (`caller_draw!`, adversary.rb: `role:`/`actor_id:` on
         # the step, bound around this one dispatch exactly the way
         # `Fuzzing::Replay` and `kernel/cli.rs` will later bind it) and
@@ -70,13 +70,14 @@ module Hecks
           mutations = adversarial_mutations!(args, entry, catalog)
           caller, caller_note = caller_draw!(entry, catalog)
           mutations << caller_note if caller_note
+          @state_before = state_before(runtime, entry, args)
 
           step =
             if dry_run_draw?
               safe_call { as_caller(caller) { runtime.dry_run?(entry[:verb], **symbolize(args)) } }
               { "dry_run" => entry[:verb], "args" => args }
             else
-              outcome = safe_call { as_caller(caller) { runtime.dispatch(entry[:verb], **symbolize(args)) } }
+              outcome = safe_call { as_caller(caller) { runtime.dispatch_flat(entry[:verb], symbolize(args)) } }
               if outcome
                 record_outcome(catalog, entry, args)
                 @event_count += outcome.events.length
@@ -93,7 +94,7 @@ module Hecks
         def dry_run_draw? = @dry_run.positive? && @random.rand < @dry_run
 
         # `Hecks.as_caller` for exactly this block, or a bare yield — the
-        # SAME binding `Fuzzing::Replay` makes from the step's own keys
+        # same binding `Fuzzing::Replay` makes from the step's own keys
         # later, so the generator's inline dispatch and both replays see
         # one caller.
         def as_caller(caller, &)
@@ -104,7 +105,7 @@ module Hecks
 
         def args_for(attributes, aggregate)
           args = attributes.each_with_object({}) do |attribute, built|
-            # AN OPTIONAL ARGUMENT IS SOMETIMES NOT GIVEN, and that is an
+            # An optional argument is sometimes not given, and that is an
             # ordinary payload rather than a damaged one — see
             # OPTIONAL_OMITTED_PROBABILITY for why this cannot live in
             # `malform` below and what it was costing while it did not
@@ -113,13 +114,13 @@ module Hecks
 
             if attribute.list?
               value = list_value_for(attribute, aggregate)
-              # A list-of-ENTITY command attribute has no real example
+              # A list-of-entity command attribute has no real example
               # anywhere in this repo's domains — every entity-owned list is
               # populated via a per-element append command instead, never a
               # whole-list command argument — so `list_value_for` (below)
               # answers `nil` for one rather than guessing at an entity's own
               # shape, and this step still skips it exactly as it always
-              # has. A list-of-VALUE-OBJECT attribute (`ConsoleSettings::
+              # has. A list-of-value-object attribute (`ConsoleSettings::
               # Collection.ReplaceColumns`' own `columns`, `list_of(Column)`)
               # is the real, previously-unfuzzable case this now covers —
               # `sets :columns` imports the owner aggregate's own declared
@@ -137,9 +138,9 @@ module Hecks
           malform(args, attributes, aggregate)
         end
 
-        # A `list_of` ATTRIBUTE'S OWN VALUE — an array of independently
+        # A `list_of` attribute's own value — an array of independently
         # generated elements, each shaped exactly the way a bare (non-list)
-        # attribute of the SAME declared element type already is
+        # attribute of the same declared element type already is
         # (`ValueGenerator.value_for`), since `list_of(X)`'s own element
         # coercion is `X`'s ordinary shape repeated, not a different one
         # (`Attribute#type` is already unwrapped from `list_of(...)` at
@@ -157,12 +158,12 @@ module Hecks
           Array.new(@random.rand(0..3)) { ValueGenerator.value_for(attribute, aggregate, random: @random, known_ids: @known_ids) }
         end
 
-        # ONE MALFORMATION AT A TIME, and usually none. A step whose payload is
+        # One malformation at a time, and usually none. A step whose payload is
         # wrong in three ways only ever proves which check runs first ; wrong in
         # exactly one way names the check that fired. And the rate stays low on
         # purpose — a corrupted step is almost always refused, a sequence of
         # refusals reaches no state at all, and bin/fuzz already counts those as
-        # SILENT rather than scoring them.
+        # silent rather than scoring them.
         def malform(args, attributes, aggregate)
           return args if args.empty? || @random.rand >= MALFORMED_ARGUMENT_PROBABILITY
 
@@ -173,12 +174,12 @@ module Hecks
           end
         end
 
-        # NEVER THE IDENTITY. A creating command with no id auto-mints one, and
+        # Never the identity. A creating command with no id auto-mints one, and
         # a minted id is deliberately unreproducible — a random hex, never a
         # guessable counter — so dropping it manufactures a step whose outcome
         # cannot be replayed and says nothing about the runtime's behaviour.
         # Every step in the hand-written corpus
-        # supplies an id for the same reason. Whether an auto-minted id OUGHT to
+        # supplies an id for the same reason. Whether an auto-minted id ought to
         # be reproducible is a real question, but it is not one a payload fuzzer
         # can ask.
         def drop_one(args, aggregate)
@@ -204,11 +205,11 @@ module Hecks
           if entry[:entity]
             parent_scalar = pick_known(aggregate.hecks_name)
             args[parent_key] = identity_shaped(aggregate, aggregate.identified_by, parent_scalar, aggregate)
-            # ONE IDENTITY PER HOP, each drawn from the pool its OWN
+            # One identity per hop, each drawn from the pool its own
             # parent-plus-hops landed elements in (`entity_pool_key`) —
             # a depth-1 chain draws exactly what it always did; a
             # `Board.Card` chain draws a Board under this Workspace, then
-            # a Card under THAT Board. Flat args, one head per hop, is
+            # a Card under that Board. Flat args, one head per hop, is
             # the legacy addressing `EntityElement#locate_chain` reads
             # (`args[head]` per identity path); the routed `to: {
             # aggregate:, entities: [...] }` spelling is an adversarial
@@ -222,19 +223,19 @@ module Hecks
               scalars << scalar
             end
           elsif entry[:command].creates?
-            # A COMPOSITE IDENTITY (`identified_by` answering nil with MORE
-            # THAN ONE declared path — Behaviour::Identified's own "a
+            # A composite identity (`identified_by` answering nil with more
+            # than one declared path — Behaviour::Identified's own "a
             # composite has no single head" comment) supplies every one of
             # its parts as its own ordinary, individually-declared command
             # attribute already — `RoleAssignment::Assign` takes actor_id/
             # role_name/starts_at directly, `args_for` (above) already
             # generated all three. Forcing a synthetic top-level `id` here
-            # too — this codebase's own fallback for the SINGLE-key and the
+            # too — this codebase's own fallback for the single-key and the
             # genuinely untyped (`identity_paths.empty?`, no `identified_by`
             # declared at all) cases — hands a composite creating command
             # an argument it never declared at all, refused every time as
             # unknown before this check existed (a creating `Assign`/`Grant`
-            # step was never anything BUT refused). `identity_paths.empty?`
+            # step was never anything but refused). `identity_paths.empty?`
             # is the untyped default (falls all the way back to a minted
             # `:id` the runtime itself never declared as an attribute
             # either), which still needs exactly the old minting behavior.
@@ -248,9 +249,9 @@ module Hecks
           end
         end
 
-        # TRUE ONLY FOR A GENUINE MULTI-FIELD IDENTITY — `identified_by`
+        # True only for a genuine multi-field identity — `identified_by`
         # returns nil both for a real composite (`identity_paths.size > 1`)
-        # and for the untyped default with NO identity declared at all
+        # and for the untyped default with no identity declared at all
         # (`identity_paths.size == 0`, Behaviour::Identified's own
         # `Array(@identified_by)` fallback) ; only the first of those two
         # has its own parts already sitting in `args` as real, individually-
@@ -294,7 +295,7 @@ module Hecks
 
         # A step the runtime declines is not a generator failure — it simply did
         # not take effect, so nothing is recorded and the sequence carries on. The
-        # step still goes into the corpus, because a REFUSAL IS AN ANSWER, and
+        # step still goes into the corpus, because a refusal is an answer, and
         # its wording is pinned by the corpus.
         #
         # EvaluationError sits alongside the declared refusals deliberately : a
@@ -305,10 +306,36 @@ module Hecks
         # generator built a step that breaks the interpreter for reasons that have
         # nothing to do with the domain declining a payload.
         def safe_call
-          yield
-        rescue *Hecks::Runtime::DOMAIN_REFUSALS, Hecks::Bluebook::Expression::EvaluationError
+          result = yield
+          @last_outcome = "ok"
+          result
+        rescue *Hecks::Runtime::DOMAIN_REFUSALS, Hecks::Bluebook::Expression::EvaluationError => e
+          @last_outcome = e.class.name.split("::").last
           nil
         end
+
+        # Where the addressed aggregate stood just before this dispatch — its
+        # lifecycle value, or `exists`/`absent` when it declares none. Read
+        # straight off the repository, never through dispatch, and draws
+        # nothing from the RNG, so it changes no generated byte. An identity
+        # an adversarial mutation mangled past resolving is `?`.
+        def state_before(runtime, entry, args)
+          aggregate = entry[:aggregate]
+          symbolic  = symbolize(args)
+          id = Runtime::Identity.of(aggregate, symbolic) || Runtime::Identity.from(aggregate, symbolic, :id)
+          return "absent" unless id
+
+          record = runtime.registry.repository(entry[:verb].split("::").first, aggregate).find(id)
+          return "absent" unless record
+
+          lifecycle = aggregate.lifecycle
+          return "exists" unless lifecycle
+
+          key = record.state.key?(lifecycle.field) ? lifecycle.field : lifecycle.field.to_s
+          record.state[key].to_s
+        rescue StandardError
+          "?"
+        end
       end
     end
   end

data/lib/hecks/fuzzing/sequence_generator.rb

@@ -15,13 +15,13 @@ module Hecks
     # `{name, note, steps}` shape `spec/corpus/*.json` already uses — so a
     # generated sequence replays as a corpus member, completely unchanged.
     # Boots a throwaway copy of
-    # the domain and DISPATCHES each candidate step for real as it builds the
+    # the domain and dispatches each candidate step for real as it builds the
     # sequence (not just synthesizing plausible-looking JSON) : the only way to
     # know whether a step actually reached a new state, or which id an
     # auto-minted entity landed on, is to run it and watch what happened.
     #
     # Single-call fuzzing mostly misses the bugs this project has actually
-    # found — they needed STATE first (a saga leg acting on a transfer that
+    # found — they needed state first (a saga leg acting on a transfer that
     # already exists, a reference pointing at a customer already registered).
     # So this tracks what it has created as it goes, the same way
     # spec/banking_state_machine_spec.rb's hand-written generator does, and
@@ -47,18 +47,18 @@ module Hecks
       CREATING_WEIGHT = 2
 
       # How often a payload is deliberately the wrong shape. Low, because a
-      # refused step reaches no new state and a sequence of them is SILENT.
+      # refused step reaches no new state and a sequence of them is silent.
       MALFORMED_ARGUMENT_PROBABILITY = 0.12
 
-      # HOW OFTEN AN OPTIONAL ARGUMENT IS SIMPLY NOT GIVEN — a fair coin,
+      # How often an optional argument is simply not given — a fair coin,
       # because that is exactly what `optional:` means: present or absent,
       # both legal, neither the interesting case.
       #
-      # This is NOT a malformation and must not be filed as one. `malform`
-      # drops an argument too, but a dropped REQUIRED argument is refused,
-      # a refusal writes no record, and bin/fuzz counts it SILENT — so the
+      # This is not a malformation and must not be filed as one. `malform`
+      # drops an argument too, but a dropped required argument is refused,
+      # a refusal writes no record, and bin/fuzz counts it silent — so the
       # one outcome worth reaching (a stored record carrying a null, then
-      # QUERIED) was unreachable from that path by construction. Until
+      # queried) was unreachable from that path by construction. Until
       # this existed no generated history contained a null at all, which
       # meant `query_answers_match_reference` — the differential that
       # diffs every native adapter against the reference interpreter — had
@@ -72,11 +72,11 @@ module Hecks
       # How strongly an unexercised verb is preferred over one this sequence has
       # already dispatched. Random picking revisits the same handful of verbs and
       # leaves whole commands untouched for a whole run — which is the same
-      # "reached no interesting state" problem the SILENT count reports, seen from
+      # "reached no interesting state" problem the silent count reports, seen from
       # the generating end rather than the scoring end.
       UNEXERCISED_WEIGHT = 4
 
-      # `adversarial:` — the fraction of generated COMMAND steps (0.0..1.0)
+      # `adversarial:` — the fraction of generated command steps (0.0..1.0)
       # that get one deliberately adversarial argument mutation
       # (adversary.rb — the shapes BUG#7–#16 were found through). `0.0`,
       # the default, draws nothing extra from the seeded RNG, so a seed's
@@ -89,22 +89,49 @@ module Hecks
       # `dry_run_draw?`): `0.0` draws nothing, so every pinned seed is
       # byte-for-byte what it was; `bin/qa_sweep` reads them from
       # `QualityControlDials::ROLE_DRAW_PROBABILITY`/`DRY_RUN_FRACTION`.
-      def self.generate(domain_path, seed:, steps:, adapter: :memory, adversarial: 0.0, role_draw: 0.0, dry_run: 0.0)
-        new(domain_path, seed: seed, steps: steps, adapter: adapter, adversarial: adversarial,
-            role_draw: role_draw, dry_run: dry_run).call
+      #
+      # `prefix:` / `favor:` — the two levers `CoverageCampaign` pulls
+      # (coverage_campaign.rb has the why). `prefix:` is `{ "seed", "steps",
+      # "favor", "prefix" }`: re-generate that seed's first `steps` attempts
+      # (itself recursively prefixed) before this seed's own randomness
+      # starts, so a seed can begin from state an earlier seed reached.
+      # `favor:` names verbs the picker weights up. `nil`/`[]`, the
+      # defaults, draw nothing extra and change nothing: every pinned seed
+      # is byte-for-byte what it was.
+      def self.generate(domain_path, seed:, steps:, **)
+        new(domain_path, seed: seed, steps: steps, **).call
+      end
+
+      # The same generation, with what it reached — `coverage` is
+      # `[[attempt_index, tuple], ...]` (`coverage_tuple`), `verbs` every
+      # verb the booted catalog offered, so a campaign can tell a verb it
+      # never hit from one that does not exist.
+      Trace = Struct.new(:steps, :coverage, :verbs, keyword_init: true)
+
+      def self.trace(domain_path, seed:, steps:, **)
+        generator = new(domain_path, seed: seed, steps: steps, **)
+        Trace.new(steps: generator.call, coverage: generator.coverage, verbs: generator.verbs)
       end
 
-      # How many EVENTS the generated sequence actually produced — not
+      # How strongly a `favor:` verb is preferred when it is eligible —
+      # the same order of magnitude as an unexercised verb, so favor
+      # steers without drowning out what this sequence has not touched.
+      FAVOR_WEIGHT = 4
+
+      attr_reader :coverage, :verbs
+
+      # How many events the generated sequence actually produced — not
       # steps, not successful dispatches, but the sum of every Result#events
       # length across the run. This is the count bin/fuzz declares as the
       # script's own `expectations.events` claim: whatever was achieved
-      # DURING generation becomes the claim a fresh replay of the same
+      # during generation becomes the claim a fresh replay of the same
       # script is held to. Zero means the sequence never
       # reached an interesting state — a fuzzer-effectiveness fact, not a
       # replay one.
       attr_reader :event_count
 
-      def initialize(domain_path, seed:, steps:, adapter: :memory, adversarial: 0.0, role_draw: 0.0, dry_run: 0.0)
+      def initialize(domain_path, seed:, steps:, adapter: :memory, adversarial: 0.0, role_draw: 0.0, dry_run: 0.0,
+                     prefix: nil, favor: [])
         { adversarial: adversarial, role_draw: role_draw, dry_run: dry_run }.each do |name, fraction|
           next if fraction.is_a?(Numeric) && fraction.between?(0, 1)
 
@@ -122,41 +149,102 @@ module Hecks
         @known_ids           = Hash.new { |h, k| h[k] = [] }
         @entity_known_ids    = Hash.new { |h, k| h[k] = [] }
         @appended_identities = Hash.new { |h, k| h[k] = [] }
-        # ROLE => [actor ids] this sequence's own successful
+        # Role => [actor ids] this sequence's own successful
         # `Governance::RoleAssignment.Assign` steps granted — what the
         # `actor_known` caller shape draws from (adversary.rb).
         @granted             = Hash.new { |h, k| h[k] = [] }
         @precedence_caller   = nil
         @exercised           = Set.new
         @event_count         = 0
+        @prefix              = prefix
+        @favor               = Array(favor)
+        @own_favor           = @favor
+        @coverage            = []
+        @verbs               = []
+        @attempt             = 0
       end
 
       def call
         # Real leftover data from ordinary use (bin/console, whatever) lives
         # under the example's data/ — a generator that boots against it
         # starts from state its own known_ids tracking doesn't know about.
-        # IsolatedBoot resets that AND rebinds persistence to Memory, since
+        # IsolatedBoot resets that and rebinds persistence to Memory, since
         # a Postgres-bound domain's real store lives outside the copied
         # directory entirely and `rm_rf`ing data/ alone cannot reach it —
         # see isolated_boot.rb's own header.
         IsolatedBoot.call(@domain_path, adapter: @adapter) do |copy|
           runtime = Hecks.boot(copy)
           catalog = build_catalog(runtime)
-          Array.new(@step_count) { attempt_step(runtime, catalog) }.compact
+          @verbs  = catalog.values_at(:creating, :instance, :entity_commands, :queries, :entity_queries, :read_models)
+                           .flatten.map { |entry| entry[:verb] }.uniq
+
+          steps = []
+          if @prefix
+            realize_prefix(runtime, catalog, @prefix, prefix_limit(@prefix), steps)
+            @random = Random.new(@seed)
+            @favor  = @own_favor
+          end
+          @step_count.times { steps << attempt_step(runtime, catalog) }
+          steps.compact
         end
       end
 
       private
 
+      # A prefix is the first `limit` attempts of another seed's generation,
+      # re-run for real: its own nested prefix first (capped the same way it
+      # was capped when that seed was generated), then that seed's own
+      # `Random.new(seed)` and favor for the rest. Same inputs, same
+      # catalog, same draws — the same steps, and the same known ids and
+      # exercised verbs carried forward into this seed.
+      #
+      # The prefix is on top of this seed's own budget, not out of it. A
+      # spliced seed still makes all `steps` attempts of its own after the
+      # prefix; a prefix is capped at `steps` attempts, so a spliced
+      # sequence is at most twice as long as an unspliced one. Taking the
+      # prefix out of the budget (the first version of this) left a spliced
+      # seed replaying state already seen with almost nothing left to
+      # explore from it — measured: fewer distinct tuples than unguided.
+      def realize_prefix(runtime, catalog, spec, limit, steps)
+        return 0 unless limit.positive?
+
+        inner = spec["prefix"]
+        used  = inner ? realize_prefix(runtime, catalog, inner, [prefix_limit(inner), limit].min, steps) : 0
+        @random = Random.new(Integer(spec.fetch("seed")))
+        @favor  = Array(spec["favor"])
+        (limit - used).times { steps << attempt_step(runtime, catalog) }
+        limit
+      end
+
+      def prefix_limit(spec) = Integer(spec.fetch("steps")).clamp(0, @step_count)
+
       def attempt_step(runtime, catalog)
+        index = @attempt
+        @attempt += 1
         entry = pick(catalog)
         return nil unless entry
 
         @exercised << entry[:verb]
-        if entry[:query]      then build_query_step(runtime, entry)
-        elsif entry[:model]   then build_read_model_step(runtime, entry)
-        else                       build_command_step(runtime, catalog, entry)
-        end
+        @state_before = "-"
+        step =
+          if entry[:query]    then build_query_step(runtime, entry)
+          elsif entry[:model] then build_read_model_step(runtime, entry)
+          else                     build_command_step(runtime, catalog, entry)
+          end
+        @coverage << [index, coverage_tuple(entry, step)]
+        step
+      end
+
+      # `verb | kind | state before | mutation | outcome` — see
+      # CoverageCampaign's header for why the unit is this and not the
+      # verb. `state` is the addressed aggregate's lifecycle value (or
+      # `exists`/`absent` for one without a lifecycle) read just before
+      # dispatch; `mutation` names every adversarial mutation and its shape;
+      # `outcome` is `ok` or the refusal class `safe_call` rescued.
+      def coverage_tuple(entry, step)
+        kind     = %w[verb query dry_run].find { |key| step.key?(key) }
+        mutation = Array(step["adversarial"]).map { |m| [m["mutation"], m["shape"]].compact.join(":") }.join("+")
+        [entry[:verb], kind, @state_before, mutation.empty? ? "-" : mutation, @last_outcome].join(" | ")
       end
     end
   end

data/lib/hecks/fuzzing/shrinker.rb

@@ -0,0 +1,197 @@
+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.
+    #
+    # The caller owns "same finding". `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.
+    #
+    # 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
+
+      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
+
+      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
+
+      # 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).
+      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
+
+      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
+
+      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
+
+      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
+
+      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
+
+      # 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.
+      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
+
+      def reproduces?(original_signature, divergences)
+        !divergences.empty? && original_signature.subset?(signature(divergences))
+      end
+
+      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
+
+        def initialize(budget)
+          @budget = budget
+          @used   = 0
+        end
+
+        def exhausted? = !@budget.nil? && @used >= @budget
+
+        def try
+          @used += 1
+          yield
+        end
+      end
+    end
+  end
+end