hecks 2.6.0 → 2.8.0

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

@@ -1,344 +0,0 @@
-require_relative "../../bluebook/expression/resolver"
-require_relative "../invalid_value_generator"
-require_relative "../value_generator"
-require_relative "../../runtime/errors"
-require_relative "../../runtime/value"
-require_relative "../../naming"
-
-module Hecks
-  module Fuzzing
-    class SequenceGenerator
-      # Turn a picked entry into a corpus step: generate its arguments,
-      # occasionally malform exactly one of them, shape its identity, and
-      # dispatch it for real.
-      module StepBuilder
-        private
-
-        def build_query_step(runtime, entry)
-          args = args_for(entry[:query].attributes, entry[:aggregate])
-          bind_to_written_row!(args, entry)
-          safe_call { runtime.query(entry[:verb], **symbolize(args)) }
-          { "query" => entry[:verb], "args" => args }
-        end
-
-        # 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
-        # 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
-        # here (this is the one place in the whole generator where the
-        # 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]
-          args  = model.reference_target.nil? ? {} : { model.reference_name.to_s => pick_known(model.reference_target) }
-
-          safe_call { runtime.query(entry[:verb], **symbolize(args)) }
-          { "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
-        # 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`
-        # 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 —
-        # 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
-        # then the dry-run coin (`{"dry_run": verb}` instead of
-        # `{"verb": verb}` — `Dispatcher#dry_run?` here, the same door on
-        # both replay sides). Order matters for the seed contract: every
-        # draw comes from the one `Random.new(seed)`, so the sequence of
-        # draws per step is what makes a seed reproducible. Both are
-        # off by default and draw nothing when off.
-        def build_command_step(runtime, catalog, entry)
-          args = args_for(entry[:command].attributes, entry[:aggregate])
-          add_identity!(args, entry)
-          steer_grant!(args, entry, catalog)
-          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_flat(entry[:verb], symbolize(args)) } }
-              if outcome
-                record_outcome(catalog, entry, args)
-                harvest_written_rows(runtime, catalog)
-                @event_count += outcome.events.length
-              end
-              { "verb" => entry[:verb], "args" => args }
-            end
-          step.merge!(caller) if caller
-          step["adversarial"] = mutations unless mutations.empty?
-          step
-        end
-
-        # No RNG draw at all when the fraction is zero — the same "off is
-        # byte-identical" contract `adversarial?` keeps.
-        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
-        # later, so the generator's inline dispatch and both replays see
-        # one caller.
-        def as_caller(caller, &)
-          return yield unless caller
-
-          Hecks.as_caller(role: caller["role"], actor_id: caller["actor_id"], &)
-        end
-
-        def args_for(attributes, aggregate)
-          args = attributes.each_with_object({}) do |attribute, built|
-            # 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
-            # exist at all.
-            next if attribute.optional? && @random.rand < SequenceGenerator::OPTIONAL_OMITTED_PROBABILITY
-
-            if attribute.list?
-              value = list_value_for(attribute, aggregate)
-              # 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::
-              # Collection.ReplaceColumns`' own `columns`, `list_of(Column)`)
-              # 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
-              # top-level argument like any other, not an entity mutation.
-              next if value.nil?
-
-              built[attribute.name.to_s] = value
-            else
-              built[attribute.name.to_s] = ValueGenerator.value_for(attribute, aggregate, random: @random, known_ids: @known_ids)
-            end
-          end
-
-          malform(args, attributes, aggregate)
-        end
-
-        # 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
-        # (`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
-        # declare time — the same fact `command_builder.rb`'s own comment
-        # on `resolve_bare_set!` names). 0-3 elements — enough to exercise a
-        # genuinely non-trivial replace without generating pathologically
-        # large payloads every time. `nil`, not `[]`, when the element type
-        # isn't a declared value object at all (an entity-typed list) — see
-        # `args_for`'s own comment on why that case still skips rather than
-        # guesses.
-        def list_value_for(attribute, aggregate)
-          value_object = Runtime::Value.value_object_for(aggregate, attribute.type.to_s)
-          return nil unless value_object
-
-          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
-        # 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.
-        def malform(args, attributes, aggregate)
-          return args if args.empty? || @random.rand >= MALFORMED_ARGUMENT_PROBABILITY
-
-          case @random.rand(3)
-          when 0 then corrupt_one(args, attributes, aggregate)
-          when 1 then drop_one(args, aggregate)
-          else        args.merge([InvalidValueGenerator.undeclared_argument(random: @random)].to_h)
-          end
-        end
-
-        # 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
-        # be reproducible is a real question, but it is not one a payload fuzzer
-        # can ask.
-        def drop_one(args, aggregate)
-          identity  = (aggregate.identified_by || :id).to_s
-          droppable = args.keys - [identity, "id"]
-          return args if droppable.empty?
-
-          args.reject { |name, _| name == droppable.sample(random: @random) }
-        end
-
-        def corrupt_one(args, attributes, aggregate)
-          named = attributes.reject(&:list?).select { |attribute| args.key?(attribute.name.to_s) }
-          return args if named.empty?
-
-          attribute = named.sample(random: @random)
-          args.merge(attribute.name.to_s => InvalidValueGenerator.corrupt(attribute, aggregate, random: @random))
-        end
-
-        def add_identity!(args, entry)
-          aggregate = entry[:aggregate]
-          parent_key = (aggregate.identified_by || :id).to_s
-
-          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
-            # 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
-            # the legacy addressing `EntityElement#locate_chain` reads
-            # (`args[head]` per identity path); the routed `to: {
-            # aggregate:, entities: [...] }` spelling is an adversarial
-            # shape layered on top (adversary.rb), never the default.
-            scalars = [parent_scalar]
-            names   = []
-            entry[:chain].each do |piece|
-              names << piece.hecks_name
-              scalar = pick_entity_known(entity_pool_key(aggregate.hecks_name, names, scalars))
-              args[(piece.identified_by || :id).to_s] = identity_shaped(piece, piece.identified_by, scalar, aggregate)
-              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
-            # 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
-            # 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?`
-            # 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.
-            unless composite_identity?(aggregate)
-              args[parent_key] ||= identity_shaped(aggregate, aggregate.identified_by, ValueGenerator.random_id(@random),
-                                                   aggregate)
-            end
-          else
-            scalar = pick_known(aggregate.hecks_name)
-            args[parent_key] = identity_shaped(aggregate, aggregate.identified_by, scalar, aggregate)
-          end
-        end
-
-        # 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
-        # (`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-
-        # generated command attributes.
-        def composite_identity?(aggregate) = aggregate.identified_by.nil? && aggregate.identity_paths.size > 1
-
-        # A bare scalar id, shaped to match whatever `construct` itself
-        # declares that identity field as. `Account::LedgerEntry` is addressed
-        # by `sequence`, and `sequence` is declared as a value-object-typed
-        # attribute (`LedgerSequence`), not a plain identifier — a fuzz run
-        # that skipped this wrapping and dispatched a bare `"1"` had every
-        # such step refused at the type gate (a bare scalar against a
-        # value-object-typed identity is a TypeMismatch, not a NotFound), so
-        # the wrapping is what lets a fuzz step address the record at
-        # all. Left as a bare scalar when the construct declares no such
-        # attribute at all — the default `:id` case, which really is untyped.
-        def identity_shaped(construct, key, scalar, aggregate)
-          return scalar unless key
-
-          attribute = construct.attribute(key)
-          return scalar unless attribute
-
-          value_object = aggregate.value_object(attribute.type.to_s)
-          return scalar unless value_object
-
-          field = value_object.attributes.first
-          return scalar unless field
-
-          { field.name.to_s => coerce_scalar(field.type.to_s, scalar) }
-        end
-
-        def coerce_scalar(type_name, scalar)
-          case type_name
-          when "Integer" then scalar.to_i
-          when "Float"   then scalar.to_f
-          else scalar.to_s
-          end
-        end
-
-        def symbolize(args) = args.transform_keys(&:to_sym)
-
-        # 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
-        # its wording is pinned by the corpus.
-        #
-        # EvaluationError sits alongside the declared refusals deliberately : a
-        # payload the interpreter cannot read is the domain declining it, and
-        # bin/run already records exactly those in a corpus's refusals —
-        # `positive? expects a number, got "lots"` is one of banking's. Anything
-        # else still propagates and fails spec/fuzzing, which is what says the
-        # generator built a step that breaks the interpreter for reasons that have
-        # nothing to do with the domain declining a payload.
-        def safe_call
-          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
-end

data/lib/hecks/fuzzing/sequence_generator.rb

@@ -1,311 +0,0 @@
-require "fileutils"
-require "tmpdir"
-require_relative "isolated_boot"
-require_relative "invalid_value_generator"
-require_relative "value_generator"
-require_relative "sequence_generator/catalog"
-require_relative "sequence_generator/picker"
-require_relative "sequence_generator/step_builder"
-require_relative "sequence_generator/outcome_tracker"
-require_relative "sequence_generator/query_binding"
-require_relative "sequence_generator/adversary"
-
-module Hecks
-  module Fuzzing
-    # A random-but-valid sequence of dispatches and queries, in the exact
-    # `{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
-    # 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
-    # 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
-    # weights later steps toward acting on what already exists.
-    #
-    # One concern per file beside this one: what the domain offers
-    # (sequence_generator/catalog.rb), which step to try next (picker.rb),
-    # how a step is built and dispatched (step_builder.rb), what a
-    # success taught us (outcome_tracker.rb), which stored values a query is
-    # asked about (query_binding.rb), and — opt-in, `adversarial:` — the
-    # argument shapes real Ruby/Rust divergences were found through
-    # (adversary.rb).
-    class SequenceGenerator
-      include Catalog
-      include Picker
-      include StepBuilder
-      include OutcomeTracker
-      include QueryBinding
-      include Adversary
-
-      # Creating commands are always eligible ; weighting them heavier (not
-      # exclusively — a domain with only one or two aggregates would starve
-      # everything else) makes a sequence reach an actionable state sooner
-      # instead of spending its early budget refusing "acts on nothing yet."
-      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.
-      MALFORMED_ARGUMENT_PROBABILITY = 0.12
-
-      # 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
-      # one outcome worth reaching (a stored record carrying a null, then
-      # 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
-      # never once compared a nullable field. Four query bugs shipped in
-      # exactly that blind spot (`ne:` with an empty string, array `in:`,
-      # `ne:` against a null, `in` on a numeric field); the adapter
-      # agreement gate had the identical hole and found a fourth bug the
-      # hour it was closed.
-      OPTIONAL_OMITTED_PROBABILITY = 0.5
-
-      # 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
-      # the generating end rather than the scoring end.
-      UNEXERCISED_WEIGHT = 4
-
-      # `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
-      # output is byte-for-byte what it was before the option existed;
-      # any positive value is just as deterministic per seed, since every
-      # choice the mutation makes comes from the same `Random.new(seed)`.
-      #
-      # `role_draw:` / `dry_run:` — two more opt-in fractions with the
-      # identical contract (adversary.rb's `caller_draw!`, step_builder.rb's
-      # `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`.
-      #
-      # `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 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
-      # 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
-
-      # @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)
-
-          raise ArgumentError, "#{name}: must be a fraction between 0.0 and 1.0, got #{fraction.inspect}"
-        end
-
-        @domain_path         = domain_path
-        @seed                = seed
-        @step_count          = steps
-        @adapter             = adapter
-        @adversarial         = adversarial.to_f
-        @role_draw           = role_draw.to_f
-        @dry_run             = dry_run.to_f
-        restart_random(seed)
-        @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] = [] }
-        # "Domain::Aggregate" => the rows this sequence has stored that a
-        # query filters on (query_binding.rb).
-        @written_rows        = Hash.new { |h, k| h[k] = [] }
-        # 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
-        # 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)
-          @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)
-            restart_random(@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
-        restart_random(Integer(spec.fetch("seed")))
-        @favor = Array(spec["favor"])
-        (limit - used).times { steps << attempt_step(runtime, catalog) }
-        limit
-      end
-
-      # Both random streams start over together, so a prefix replay draws the
-      # same query bindings the prefix seed's own generation did.
-      def restart_random(seed)
-        @random         = Random.new(seed)
-        @binding_random = Random.new(seed + QueryBinding::BINDING_SEED_OFFSET)
-      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]
-        @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
-end