hecks 1.3.0 → 1.5.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,15 +114,15 @@ 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 —
+              # is the real case this covers —
               # `sets :columns` imports the owner aggregate's own declared
               # `list_of` attribute onto the command verbatim (Command
               # Builder#resolve_bare_set!), so it is a required, ordinary
@@ -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,91 @@ 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.
+      #
+      # Generates one random-but-valid step sequence for `domain_path`, dispatching
+      # each step for real against a throwaway boot as it builds it.
+      #
+      # @param domain_path [String] path to the domain directory to boot
+      # @param seed [Integer] RNG seed; every draw this run makes is reproducible
+      #   from it
+      # @param steps [Integer] number of generation attempts to make
+      # @param adapter [Symbol] persistence adapter to boot with (default `:memory`)
+      # @param adversarial [Float] fraction of command steps to mutate adversarially
+      #   (default `0.0`, drawing nothing extra)
+      # @param role_draw [Float] fraction of gated commands to draw a caller for
+      #   (default `0.0`, drawing nothing extra)
+      # @param dry_run [Float] fraction of command steps dispatched as dry runs
+      #   (default `0.0`, drawing nothing extra)
+      # @param prefix [Hash, nil] another seed's own generation spec to replay
+      #   first (`{"seed" =>, "steps" =>, "favor" =>, "prefix" =>}`), or `nil`
+      # @param favor [Array<String>, Array<Symbol>] verbs the picker weights up
+      # @return [Array<Hash>] the generated step list, each a command, query, or
+      #   read-model step
+      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)
+
+      # Generates one sequence exactly like `.generate`, but also returns the
+      # coverage and verb data a campaign needs, which `.generate` discards.
+      #
+      # @param domain_path [String] path to the domain directory to boot
+      # @param seed [Integer] RNG seed; every draw this run makes is reproducible
+      #   from it
+      # @param steps [Integer] number of generation attempts to make
+      # @return [Hecks::Fuzzing::SequenceGenerator::Trace] the generated steps,
+      #   the coverage tuples reached, and every verb the booted catalog offered
+      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)
+      # @param domain_path [String] path to the domain directory to boot
+      # @param seed [Integer] RNG seed; every draw this run makes is reproducible
+      #   from it
+      # @param steps [Integer] number of generation attempts `#call` will make
+      # @param adapter [Symbol] persistence adapter to boot with
+      # @param adversarial [Float] fraction of command steps to mutate adversarially
+      # @param role_draw [Float] fraction of gated commands to draw a caller for
+      # @param dry_run [Float] fraction of command steps dispatched as dry runs
+      # @param prefix [Hash, nil] another seed's own generation spec to replay
+      #   first, or `nil`
+      # @param favor [Array<String>, Array<Symbol>] verbs the picker weights up
+      # @raise [ArgumentError] if `adversarial`, `role_draw`, or `dry_run` is not a
+      #   Numeric between 0.0 and 1.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 +191,107 @@ 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
 
+      # Runs the generation this instance was configured for, against a fresh,
+      # isolated boot of `@domain_path`.
+      #
+      # @return [Array<Hash>] the generated step list, each a command, query, or
+      #   read-model step; a picker miss that produced no step is dropped
       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