hecks 2.9.0 → 3.0.1

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

@@ -0,0 +1,77 @@
+module Hecks
+  module Fuzzing
+    class SequenceGenerator
+      # Which step to try next: eligibility (what is possible from the
+      # state so far) and weighting (what is likely to reach somewhere
+      # new).
+      module Picker
+        private
+
+        def pick(catalog)
+          rest = catalog[:queries].dup
+          catalog[:instance].each { |entry| rest << entry if actionable?(catalog, entry) }
+          catalog[:entity_commands].each { |entry| rest << entry if actionable?(catalog, entry) }
+          catalog[:entity_queries].each { |entry| rest << entry if @known_ids[entry[:aggregate].hecks_name].any? }
+          catalog[:read_models].each { |entry| rest << entry if read_model_actionable?(entry) }
+
+          makers = catalog[:creating].select { |entry| satisfiable?(catalog, entry) }
+          pool   = rest + makers.flat_map { |entry| [entry] * creating_weight(rest.size) }
+          pool  += deep_entity_bias(rest) if adversarial?
+
+          steer(pool).sample(random: @random)
+        end
+
+        # Weights up entity commands two or more hops deep; adversarial mode only,
+        # and eligibility still decides what is possible.
+        def deep_entity_bias(rest)
+          deep = rest.select { |entry| (entry[:chain] || []).size >= Adversary::DEEP_ENTITY_DEPTH }
+          deep * Adversary::DEEP_ENTITY_WEIGHT
+        end
+
+        # While the store is empty, creation matches everything else combined, so a
+        # run does not spend its budget querying nothing.
+        def creating_weight(rest_size)
+          return CREATING_WEIGHT if @known_ids.each_value.any?(&:any?)
+
+          [rest_size, CREATING_WEIGHT].max
+        end
+
+        def actionable?(catalog, entry)
+          @known_ids[entry[:aggregate].hecks_name].any? && satisfiable?(catalog, entry)
+        end
+
+        # A rootless report is always eligible; a rooted one needs an instance of its
+        # `reference_target`, or the ask is refused.
+        def read_model_actionable?(entry)
+          entry[:model].reference_target.nil? || @known_ids[entry[:model].reference_target].any?
+        end
+
+        # A command whose references point at nothing that exists is refused, so it
+        # is withheld until they do. A target no creating command can make (a
+        # cross-domain reference) is exempt, or the domain would starve.
+        def satisfiable?(catalog, entry)
+          entry[:command].attributes.select(&:reference?).all? do |attribute|
+            target = attribute.type.target_name.to_s
+            !catalog[:creatable].include?(target) || @known_ids[target].any?
+          end
+        end
+
+        # Weights up verbs this sequence has not dispatched yet. Only likelihood
+        # changes; a verb gated behind missing state stays out of the pool.
+        def steer(pool)
+          fresh = pool.reject { |entry| @exercised.include?(entry[:verb]) }
+          steered = fresh.empty? ? pool : pool + (fresh * UNEXERCISED_WEIGHT)
+          favor(steered)
+        end
+
+        # Weights up the `favor:` verbs when eligible, never making one eligible.
+        def favor(pool)
+          return pool if @favor.empty?
+
+          favored = pool.uniq.select { |entry| @favor.include?(entry[:verb]) }
+          pool + (favored * SequenceGenerator::FAVOR_WEIGHT)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,109 @@
+require_relative "../../query_specification/field_path"
+require_relative "../../runtime/value"
+
+module Hecks
+  module Fuzzing
+    class SequenceGenerator
+      # Query arguments drawn from rows the sequence has already written, so a
+      # query can match a stored row instead of a fresh word that matches nothing.
+      #
+      # After each effective command, the compared fields of every aggregate a
+      # query filters on are read back from the repository as one row per record.
+      # The choice uses its own `Random` (`restart_random`); drawing from `@random`
+      # would shift every later step of every seed.
+      module QueryBinding
+        # How often a query step takes its arguments from a written row; the
+        # rest of the time the generated miss is kept.
+        BOUND_QUERY_PROBABILITY = 0.75
+
+        # Comparators taking one scalar operand; `in` and `none_in_state` do not.
+        BINDABLE_OPERATORS = %i[eq ne lt lte gt gte].freeze
+
+        # Keeps the binding stream apart from `@random`, which is seeded with the bare seed.
+        BINDING_SEED_OFFSET = 0x9e3779b1
+
+        private
+
+        # `{"Domain::Aggregate" => {domain:, aggregate:, fields: [String]}}`
+        # for every aggregate some query filters on, where `fields` is the
+        # union of the stored fields those queries compare.
+        def build_query_bindings(runtime)
+          runtime.registry.bluebooks.each_with_object({}) do |(domain_name, bluebook), bindings|
+            bluebook.aggregates.each do |aggregate|
+              fields = aggregate.queries.flat_map { |query| bound_fields(query).values }.uniq
+              next if fields.empty?
+
+              bindings["#{domain_name}::#{aggregate.hecks_name}"] =
+                { domain: domain_name, aggregate: aggregate, fields: fields }
+            end
+          end
+        end
+
+        # `{parameter name => stored field}` for each `where` clause whose
+        # operand is one of the query's own parameters. A clause on a literal,
+        # or aimed at another aggregate's field (`target`), binds nothing.
+        def bound_fields(query)
+          query.wheres.each_with_object({}) do |clause, fields|
+            next unless clause.value.is_a?(Symbol) && clause.target.nil?
+            next unless BINDABLE_OPERATORS.include?(clause.op.to_sym)
+
+            fields[clause.value.to_s] ||= clause.field.to_s
+          end
+        end
+
+        # Remembers the compared fields of every stored record of every
+        # aggregate a query filters on, as one row per distinct record shape.
+        def harvest_written_rows(runtime, catalog)
+          catalog[:query_bindings].each do |key, binding|
+            repository = runtime.registry.repository(binding[:domain], binding[:aggregate])
+            repository.all.each do |record|
+              row = binding[:fields].to_h { |field| [field, written_value(field_of(record, field))] }.compact
+              @written_rows[key] << row unless row.empty? || @written_rows[key].include?(row)
+            end
+          end
+        end
+
+        def field_of(record, field) = QuerySpecification::FieldPath.dig(record.state, field)
+
+        # A stored value as the JSON-shaped argument a step carries: string
+        # keys, nested values opened. `nil` for anything a query argument
+        # cannot be (a missing value, a list, a timestamp object).
+        def written_value(value)
+          case value
+          when Runtime::Value then written_value(value.to_h)
+          when Hash           then value.to_h { |key, inner| [key.to_s, written_value(inner)] }
+          when String, Integer, Float, true, false then value
+          end
+        end
+
+        # Replaces the generated arguments of a query step with a remembered
+        # row's, most of the time. Only a parameter the step already carries
+        # is replaced, so an optional argument left out, or a required one a
+        # malformation dropped, stays that way.
+        def bind_to_written_row!(args, entry)
+          return if entry[:entity]
+
+          rows   = @written_rows[entry[:verb].split(".").first]
+          params = bound_fields(entry[:query]).select { |param, _| args.key?(param) }
+          return if rows.empty? || params.empty?
+          return unless @binding_random.rand < BOUND_QUERY_PROBABILITY
+
+          row = rows.select { |candidate| params.values.any? { |field| candidate.key?(field) } }
+                    .sample(random: @binding_random)
+          params.each do |param, field|
+            args[param] = shaped_like(args[param], row[field]) if row&.key?(field)
+          end
+        end
+
+        # A single-field value object is written `{"value" => x}` but may be
+        # asked with the bare `x`; keeps whichever spelling the generator
+        # already chose for this argument.
+        def shaped_like(current, written)
+          return written unless written.is_a?(Hash) && written.size == 1 && !current.is_a?(Hash)
+
+          written.values.first
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,237 @@
+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. Its only argument is `reference_name`, on a rooted model.
+        # The id stays a bare scalar: `ReadModelInterpreter#refuse_object_reference`
+        # rejects a wrapped identity.
+        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 mutation happens here, after the args and identity are
+        # built and before the one inline dispatch, so the dispatch, the corpus
+        # step and both replay engines all see the same mutated payload.
+        #
+        # The caller draw and then the dry-run coin follow the mutation. The order
+        # is part of the seed contract; both 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
+
+        # Draws nothing when the fraction is zero, like `adversarial?`.
+        def dry_run_draw? = @dry_run.positive? && @random.rand < @dry_run
+
+        # Runs the block under `Hecks.as_caller`, the binding `Fuzzing::Replay` makes
+        # from the step's keys, or yields bare when there is no 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|
+            # Omitting an optional argument is an ordinary payload, not a malformation
+            # (see OPTIONAL_OMITTED_PROBABILITY).
+            next if attribute.optional? && @random.rand < SequenceGenerator::OPTIONAL_OMITTED_PROBABILITY
+
+            if attribute.list?
+              value = list_value_for(attribute, aggregate)
+              # `list_value_for` answers nil for a list of entities (those are
+              # populated by per-element append commands), so the step skips it.
+              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
+
+        # An array of 0-3 independently generated elements shaped like the bare
+        # element type. `nil`, not `[]`, when the element type is not a value object.
+        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
+
+        # At most one malformation per step, so the check that fired is identifiable.
+        # The rate stays low because refused steps reach no state.
+        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 drops the identity: an auto-minted id is unreproducible, so the
+        # step's outcome could not be replayed.
+        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, drawn from that hop's pool (`entity_pool_key`), as
+            # flat args, which is what `EntityElement#locate_chain` reads.
+            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's parts are already generated as the command's own
+            # attributes; a synthetic `id` would be refused as an undeclared argument.
+            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 multi-field identity: `identified_by` is also nil for the
+        # untyped default, whose parts are not in `args`.
+        def composite_identity?(aggregate) = aggregate.identified_by.nil? && aggregate.identity_paths.size > 1
+
+        # Shapes a bare scalar id like the construct's identity field. A
+        # value-object-typed identity given a bare scalar is a TypeMismatch, so it
+        # must be wrapped; the untyped default `:id` stays bare.
+        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 declined step is not a generator failure: nothing is recorded, the
+        # sequence carries on, and the step still enters the corpus as a refusal.
+        #
+        # EvaluationError counts as a refusal (an unreadable payload); any other
+        # error propagates and fails spec/fuzzing.
+        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
+
+        # The addressed aggregate's lifecycle value before this dispatch, or
+        # `exists`/`absent`; `?` when a mutation mangled the identity. Draws nothing from the RNG.
+        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

@@ -0,0 +1,189 @@
+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 `{name, note, steps}`
+    # shape of `spec/corpus/*.json`, so a generated sequence replays as a corpus member.
+    # Each step is dispatched for real against a throwaway boot while the sequence is built.
+    class SequenceGenerator
+      include Catalog
+      include Picker
+      include StepBuilder
+      include OutcomeTracker
+      include QueryBinding
+      include Adversary
+
+      # Creating commands are always eligible; weighting them up reaches an actionable
+      # state sooner without starving domains that have few aggregates.
+      CREATING_WEIGHT = 2
+
+      # Low, because a refused step reaches no new state and a run of them is silent.
+      MALFORMED_ARGUMENT_PROBABILITY = 0.12
+
+      # A fair coin: an optional argument is legal present or absent. Separate from
+      # `malform`, whose dropped required argument is refused and so never stores a null.
+      OPTIONAL_OMITTED_PROBABILITY = 0.5
+
+      # Preference for a verb this sequence has not yet dispatched, so whole commands
+      # are not left untouched for a run.
+      UNEXERCISED_WEIGHT = 4
+
+      # Generates a random-but-valid step sequence for `domain_path`, dispatching each
+      # step against a throwaway boot. Fractions at `0.0` draw nothing from the RNG.
+      #
+      # @param seed [Integer] RNG seed; every draw is reproducible from it
+      # @param steps [Integer] number of generation attempts
+      # @param adversarial [Float] fraction of command steps mutated adversarially
+      # @param role_draw [Float] fraction of gated commands given a drawn caller
+      # @param dry_run [Float] fraction of command steps dispatched as dry runs
+      # @param prefix [Hash, nil] `{"seed", "steps", "favor", "prefix"}` replayed first
+      # @param favor [Array<String>] verbs the picker weights up
+      # @return [Array<Hash>] the generated steps
+      def self.generate(domain_path, seed:, steps:, **)
+        new(domain_path, seed: seed, steps: steps, **).call
+      end
+
+      # Coverage tuples reached (`[[attempt_index, tuple], ...]`) and every verb the
+      # booted catalog offered, so a campaign can tell an unhit verb from a missing one.
+      Trace = Struct.new(:steps, :coverage, :verbs, keyword_init: true)
+
+      # Generates one sequence like `.generate`, also returning the coverage tuples and
+      # verbs a campaign needs.
+      #
+      # @return [Trace] the generated steps, coverage tuples reached, and catalog verbs
+      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
+
+      # Weight of a `favor:` verb; comparable to UNEXERCISED_WEIGHT so favor steers
+      # without drowning out untouched verbs.
+      FAVOR_WEIGHT = 4
+
+      attr_reader :coverage, :verbs
+
+      # Sum of every `Result#events` length across the run; hecks fuzz declares it as the
+      # script's `expectations.events` claim. Zero means no interesting state was reached.
+      attr_reader :event_count
+
+      # Takes the same keywords as `.generate`, plus `adapter:` (default `:memory`).
+      #
+      # @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" => stored rows a query filters on (query_binding.rb).
+        @written_rows        = Hash.new { |h, k| h[k] = [] }
+        # Role => actor ids granted by this sequence's own `RoleAssignment.Assign` steps.
+        @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 against a fresh, isolated boot of the domain.
+      #
+      # @return [Array<Hash>] the generated steps; a picker miss is dropped
+      def call
+        # Leftover data under the example's data/ would start the run from state
+        # known_ids does not track; IsolatedBoot resets it and rebinds persistence to Memory.
+        IsolatedBoot.call(@domain_path, adapter: @adapter) do |copy|
+          runtime = Hecks.boot(copy, environment: nil)
+          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
+
+      # Re-runs the first `limit` attempts of another seed's generation (its own prefix
+      # first), carrying its known ids and exercised verbs into this seed. The prefix is
+      # on top of this seed's budget: taking it out of the budget left too little to explore.
+      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 streams restart together so a prefix replay draws the same query bindings.
+      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.
+      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