hecks 1.4.0 → 1.5.0

data/lib/hecks/fuzzing/self_consistency.rb

@@ -15,9 +15,11 @@ module Hecks
     # compare it against. This module asks a different question of one
     # engine at a time: does it agree with itself?
     #
-    # Three checks, run on the same already-generated sequence and its
-    # resulting live state — no second fuzzing pass, no re-dispatch
-    # through the command layer:
+    # ## Three checks
+    #
+    # Run on the same already-generated sequence and its resulting live
+    # state — no second fuzzing pass, no re-dispatch through the command
+    # layer:
     #
     #   1. `check_rehydration`   — does reloading an aggregate from its
     #      own durable journal reproduce exactly the state a live dispatch
@@ -29,30 +31,31 @@ module Hecks
     #   3. `check_value_object_round_trip` — does every value object the
     #      sequence actually built survive `to_json` then rebuilt back?
     #
-    # **The rehydration path, found, not guessed**. hecks is not event-sourced
-    # at the aggregate level — there is no `AccountOpened`-shaped log a
-    # `CommandInterpreter` folds to rebuild state. What there is, real and
-    # already shipping, is `Ports::Persistence::AppendOnly` (lib/hecks/
-    # ports/persistence/append_only.rb): every adapter accepts the same
-    # `Entry` stream (`operation`, `id`, the full state after that
-    # command — not a delta) and answers `#entries`; `#recover!` — "an
-    # append is durable before a projection is attempted; replaying the
-    # log restores a snapshot/table after a crash in that small window" —
-    # is called on every repository this runtime ever builds
-    # (`RepositoryFactory.build`'s own `recover: true` default). That is
-    # the production cold-rehydration path. Reusing `#recover!` directly
-    # against the live adapter would prove nothing, though: `Fuzzing::
-    # Replay` runs against `Adapters::Memory` (`IsolatedBoot`'s own
-    # default), and Memory's own `Entry#state` is a shallow `instance.
-    # state.dup` — the exact same `Runtime::Value` objects a command
-    # produced ride along unchanged, so folding them straight back through
-    # Memory's own `#project` is a tautology that can never fail (`Value#
-    # for_attribute`'s own `value.is_a?(self) && value.type_name == ...`
-    # branch passes an already-typed value straight through, no
-    # rebuilding at all).
+    # ## The rehydration path, found, not guessed
+    #
+    # hecks is not event-sourced at the aggregate level — there is no
+    # `AccountOpened`-shaped log a `CommandInterpreter` folds to rebuild
+    # state. What there is, real and already shipping, is
+    # `Ports::Persistence::AppendOnly` (lib/hecks/ports/persistence/
+    # append_only.rb): every adapter accepts the same `Entry` stream
+    # (`operation`, `id`, the full state after that command — not a
+    # delta) and answers `#entries`; `#recover!` — "an append is durable
+    # before a projection is attempted; replaying the log restores a
+    # snapshot/table after a crash in that small window" — is called on
+    # every repository this runtime ever builds (`RepositoryFactory
+    # .build`'s own `recover: true` default). That is the production
+    # cold-rehydration path. Reusing `#recover!` directly against the
+    # live adapter would prove nothing, though: `Fuzzing::Replay` runs
+    # against `Adapters::Memory` (`IsolatedBoot`'s own default), and
+    # Memory's own `Entry#state` is a shallow `instance.state.dup` — the
+    # exact same `Runtime::Value` objects a command produced ride along
+    # unchanged, so folding them straight back through Memory's own
+    # `#project` is a tautology that can never fail (`Value#for_attribute`
+    # 's own `value.is_a?(self) && value.type_name == ...` branch passes
+    # an already-typed value straight through, no rebuilding at all).
     #
-    # So `cold_read`, below, feeds the same entries through `Adapters::
-    # Heki` instead — a real, already-shipped, disk-backed adapter
+    # So `fold!`, below, feeds the same entries through `Adapters::Heki`
+    # instead — a real, already-shipped, disk-backed adapter
     # (examples/banking's own `persisted_by("Heki")`), in a throwaway
     # directory. Writing forces every value through `JSON.generate`
     # (Heki's own journal line, its own compressed snapshot); reading
@@ -76,6 +79,11 @@ module Hecks
       # could hand `Runtime::Instance` undecoded state and the codec's
       # guarantee would have a bypass in exactly the check that exists to
       # compare stored state against live state.
+      #
+      # @param aggregate [Bluebook::Aggregate] the aggregate this store holds
+      # @param settings [Hash] adapter settings, forwarded to `Adapters::Heki.new`
+      # @param root [String, nil] the directory this store reads/writes under
+      # @return [Adapters::Heki] a fresh, codec-boundary-guarded Heki instance
       def guarded_heki(**) = Ports::Persistence::CodecBoundary.guard!(Adapters::Heki.new(**))
 
       # The whole pass — called once, with the runtime still live (inside
@@ -87,6 +95,14 @@ module Hecks
       # below, run and collected — kept as three independently callable
       # methods (not fused into one shared fold) so a spec proving one
       # check can fire never has to reason about the other two.
+      #
+      # @param runtime [Runtime::Dispatcher, Runtime::RemoteDispatcher] the still-live
+      #   booted runtime this replay just dispatched through
+      # @param history [Hash] the replayed history `Replay.call` is about to return
+      # @return [Hash{Symbol => Array<Hash>}] the five checks' own findings, keyed
+      #   `:rehydration`, `:idempotency`, `:value_object_round_trip`,
+      #   `:saga_rehydration`, `:saga_redelivery_idempotency` — each value an empty
+      #   Array when that check found nothing
       def check(runtime, history)
         { rehydration: check_rehydration(runtime), idempotency: check_idempotency(runtime),
           value_object_round_trip: check_value_object_round_trip(history),
@@ -95,6 +111,12 @@ module Hecks
       end
 
       # Check 1 — rehydrate-from-journal == live state.
+      #
+      # @param runtime [Runtime::Dispatcher, Runtime::RemoteDispatcher] the still-live
+      #   booted runtime this replay just dispatched through
+      # @return [Array<Hash>] one divergence Hash (`:field`, `:domain`, `:aggregate`,
+      #   `:live`, `:rehydrated`) per aggregate whose cold-read state disagrees with its
+      #   live state; empty when every touched aggregate rehydrates cleanly
       def check_rehydration(runtime)
         each_touched_repository(runtime).filter_map do |domain_name, aggregate, repository, entries|
           live = snapshot(repository)
@@ -115,6 +137,12 @@ module Hecks
       # replay-specific bug (leaked state between applications, a
       # double-applied effect) that a single, one-shot cold read could
       # never see, even one that already agrees with live state.
+      #
+      # @param runtime [Runtime::Dispatcher, Runtime::RemoteDispatcher] the still-live
+      #   booted runtime this replay just dispatched through
+      # @return [Array<Hash>] one divergence Hash (`:field`, `:domain`, `:aggregate`,
+      #   `:once`, `:twice`) per aggregate whose second fold disagrees with its first;
+      #   empty when every touched aggregate folds idempotently
       def check_idempotency(runtime)
         each_touched_repository(runtime).filter_map do |domain_name, aggregate, repository, entries|
           Dir.mktmpdir("hecks-self-consistency") do |tmp|
@@ -162,6 +190,12 @@ module Hecks
       # positive `nil` already produced once — `instances` and `events`
       # alone already reach every value object a generated sequence
       # actually persisted or announced.
+      #
+      # @param history [Hash] a replayed history as returned by `Replay.call`
+      # @return [Array<Hash>] one divergence Hash (`:field`, `:type`, `:original`, and
+      #   either `:rehydrated` or `:error`) per value object whose `to_json`-then-`build`
+      #   round trip disagrees with (or raises on) the original; empty when every value
+      #   object found round-trips cleanly
       def check_value_object_round_trip(history)
         bluebooks = history[:bluebooks] || {}
         seen = {}.compare_by_identity
@@ -235,6 +269,14 @@ module Hecks
       # not the settled snapshot this history exists to describe), so
       # there is no ground truth to compare it against here. Written as an
       # empty array on the way in and never read back on the way out.
+      #
+      # @param runtime [Runtime::Dispatcher, Runtime::RemoteDispatcher] the still-live
+      #   booted runtime this replay just dispatched through
+      # @param history [Hash] a replayed history as returned by `Replay.call`
+      # @return [Array<Hash>] one divergence Hash (`:field`, `:domain`,
+      #   `:process_manager`, `:live`, `:rehydrated`) per process manager whose cold-read
+      #   saga instances disagree with the ones this replay persisted; empty when every
+      #   process manager with persisted instances rehydrates cleanly
       def check_saga_rehydration(runtime, history)
         saga_instances = history[:saga_instances] || {}
         each_domain_process_manager(runtime).filter_map do |domain_name, process_manager|
@@ -325,6 +367,14 @@ module Hecks
       # the redelivered event name (the ordinary, expected case once a
       # saga has moved past the leg that produced its own current
       # checkpoint) is exactly what this proves stays put.
+      #
+      # @param runtime [Runtime::Dispatcher, Runtime::RemoteDispatcher] the still-live
+      #   booted runtime this replay just dispatched through
+      # @param history [Hash] a replayed history as returned by `Replay.call`
+      # @return [Array<Hash>] one divergence Hash (`:field`, `:domain`,
+      #   `:process_manager`, `:correlation`, `:on`, `:before`, `:after`) per correlation
+      #   whose redelivered event visibly changed state/memory on a rehydrated
+      #   checkpoint; empty when every redelivered correlation stayed put
       def check_saga_idempotency(runtime, history)
         saga_instances = history[:saga_instances] || {}
         interpreter    = Runtime::SagaInterpreter.new(runtime.registry, door: runtime)
@@ -375,19 +425,25 @@ module Hecks
       # comment). This check has no Ruby side to spare — it is asking the
       # Rust binary whether it agrees with itself, so `emitted_*` fields
       # are exactly as real a fact to compare as any other. Stripping them
-      # here (an earlier version of this method did) silently deleted
-      # them from the returned seed-round-trip result while leaving them
-      # present on the original `seed_instances` a caller passes in — an
-      # asymmetric comparison that reported every record carrying one as
-      # a rehydration divergence, unconditionally, on every domain that
-      # has one at all. Found live against `examples/banking`
-      # (`Banking::Account`'s own `corrects` reaction) while this
-      # integration was being written, by comparing this method's own
-      # answer against the compiled binary's raw stdout for the identical
-      # seed call: the raw round trip preserved `emitted_fee_applied`
-      # correctly; only this method's own stripping dropped it. `spec/
-      # self_consistency_rust_spec.rb`'s own "banking" example pins the
-      # regression against a real domain going forward.
+      # here would silently delete them from the returned seed-round-trip
+      # result while leaving them present on the original `seed_instances`
+      # a caller passes in — an asymmetric comparison that would report
+      # every record carrying one as a rehydration divergence,
+      # unconditionally, on every domain that has one at all. Confirmed
+      # live against `examples/banking` (`Banking::Account`'s own
+      # `corrects` reaction) by comparing this method's own answer against
+      # the compiled binary's raw stdout for the identical seed call: the
+      # raw round trip preserves `emitted_fee_applied` correctly. `spec/
+      # self_consistency_rust_spec.rb`'s own "banking" example pins this
+      # against a real domain going forward.
+      #
+      # @param binary [String] path to the compiled Rust conformance binary
+      # @param _differ [Object] a `RustConformanceHelpers`-including instance, unused here
+      # @param seed_instances [Hash] the `"instances"` shape to seed the fresh invocation
+      #   with, in place of replaying `steps`
+      # @return [Hash] the fresh invocation's own `"instances"`, or a
+      #   `{"__self_consistency_error__" => String}` Hash if the binary exited nonzero or
+      #   the binary itself reported an `"error"`
       def rust_seed_round_trip(binary, _differ, seed_instances)
         stdout, status = Open3.capture2(binary, stdin_data: JSON.generate({ "steps" => [], "seed" => seed_instances }))
         return { "__self_consistency_error__" => "rust binary exited #{status.exitstatus}: #{stdout}" } \
@@ -404,6 +460,13 @@ module Hecks
       # state, unchanged. `live_instances` is `rust_output["instances"]`
       # — the exact same value `bin/qa_sweep`'s own differential compare
       # already diffed against Ruby, reused here rather than re-derived.
+      #
+      # @param binary [String] path to the compiled Rust conformance binary
+      # @param differ [Object] a `RustConformanceHelpers`-including instance, forwarded to
+      #   `rust_seed_round_trip` unused
+      # @param live_instances [Hash] the prior invocation's own `"instances"` output
+      # @return [Array<Hash>] a single divergence Hash (`:field`, `:live`, `:rehydrated`)
+      #   if seeding with `live_instances` fails to reproduce it; empty otherwise
       def check_rust_rehydration(binary, differ, live_instances)
         rehydrated = rust_seed_round_trip(binary, differ, live_instances)
         return [] if rehydrated == live_instances
@@ -416,6 +479,14 @@ module Hecks
       # same "replay it again, byte for byte" claim `check_idempotency`
       # proves for Ruby, aimed at the one rehydration door this compiled
       # binary actually has.
+      #
+      # @param binary [String] path to the compiled Rust conformance binary
+      # @param differ [Object] a `RustConformanceHelpers`-including instance, forwarded to
+      #   `rust_seed_round_trip` unused
+      # @param live_instances [Hash] the prior invocation's own `"instances"` output to
+      #   seed the first round trip with
+      # @return [Array<Hash>] a single divergence Hash (`:field`, `:once`, `:twice`) if a
+      #   second seed round trip disagrees with the first; empty otherwise
       def check_rust_idempotency(binary, differ, live_instances)
         once  = rust_seed_round_trip(binary, differ, live_instances)
         twice = rust_seed_round_trip(binary, differ, once)
@@ -432,6 +503,12 @@ module Hecks
       # finding a "clean, nothing touched" report would mean anything
       # for. Mirrors `Replay#snapshot_instances`' own
       # `bluebooks.each { aggregates.each { repository(...) } }` walk.
+      #
+      # @param runtime [Runtime::Dispatcher, Runtime::RemoteDispatcher] the still-live
+      #   booted runtime this replay just dispatched through
+      # @return [Array<Array(String, Bluebook::Aggregate, Ports::Persistence::AppendOnly,
+      #   Array<Ports::Persistence::Entry>)>] one `[domain_name, aggregate, repository,
+      #   entries]` tuple per aggregate with at least one journal entry
       def each_touched_repository(runtime)
         found = []
         runtime.registry.bluebooks.each do |domain_name, bluebook|
@@ -446,6 +523,12 @@ module Hecks
         found
       end
 
+      # Materializes a repository's own stored records, keyed by id, for comparing
+      # against a cold read of the same aggregate.
+      #
+      # @param repository [Ports::Persistence::AppendOnly] the repository to read
+      # @return [Hash{String => Object}] every stored record's id (stringified) mapped to
+      #   its materialized state
       def snapshot(repository)
         repository.all.to_h { |record| [record.id.to_s, Runtime::Value.materialize(record.state)] }
       end
@@ -461,6 +544,11 @@ module Hecks
       # identical to "ran and found nothing," which is deliberate: neither
       # check has a positive "passed" artifact to report either way (see
       # this file's own header on why silence is never a claimed pass).
+      #
+      # @param runtime [Runtime::Dispatcher, Runtime::RemoteDispatcher] the still-live
+      #   booted runtime this replay just dispatched through
+      # @return [Array<Array(String, Bluebook::ProcessManager)>] one `[domain_name,
+      #   process_manager]` tuple per process manager any loaded bluebook declares
       def each_domain_process_manager(runtime)
         found = []
         runtime.registry.bluebooks.each do |domain_name, bluebook|
@@ -472,6 +560,11 @@ module Hecks
       # The live-side ground truth, key-shape-normalized (see `deep_
       # stringify_keys`'s own comment) so it compares fairly against a
       # real Heki round trip's own shallow-symbolize convention.
+      #
+      # @param persisted [Hash{String, Symbol => Hash}] `history[:saga_instances]`'s own
+      #   per-process-manager entry, keyed by correlation, each holding `:state`/`:memory`
+      # @return [Hash{String => Hash}] the same rows, keyed by stringified correlation,
+      #   with `:memory` recursively string-keyed
       def normalize_saga_rows(persisted)
         persisted.each_with_object({}) do |(correlation, saga), rows|
           rows[correlation.to_s] = { state: saga[:state], memory: deep_stringify_keys(saga[:memory]) }
@@ -482,8 +575,16 @@ module Hecks
       # `@store`/`@saga_store`, so `#each_saga` is forced back through
       # `read_snapshot`/`replay_journal`, real bytes off real disk, not
       # whatever the writer that just wrote them still holds in its own
-      # process memory (the same reason `fold!`, above, opens a second
+      # process memory (the same reason `fold!`, below, opens a second
       # `Adapters::Heki` instance rather than reading its own writer back).
+      #
+      # @param anchor [Bluebook::Aggregate] any aggregate of the owning domain, used only
+      #   to open a `Heki` store at the right domain/root
+      # @param tmp [String] the throwaway directory the saga store was written into
+      # @param domain_name [String] the owning domain's name, threaded into the store's
+      #   own `settings`
+      # @return [Hash{String => Hash}] every persisted correlation's `:state`/`:memory`,
+      #   with `:memory` recursively string-keyed
       def cold_read_saga_rows(anchor, tmp, domain_name)
         reader = guarded_heki(aggregate: anchor, root: tmp, settings: { domain: domain_name })
         reader.each_saga.with_object({}) do |(_pm, correlation, state, memory, _completed), rows|
@@ -513,6 +614,10 @@ module Hecks
       # key, a changed value, a missing field) — exactly the kind (b)'s
       # own seeded fixture in `spec/fuzzing/self_consistency_saga_spec.rb`
       # proves this still catches.
+      #
+      # @param value [Object] any value; only Hash and Array are recursed into
+      # @return [Object] `value` with every Hash key (at every nesting level) replaced by
+      #   its own `to_s`; anything else is returned unchanged
       def deep_stringify_keys(value)
         case value
         when Hash  then value.each_with_object({}) { |(k, v), h| h[k.to_s] = deep_stringify_keys(v) }
@@ -540,6 +645,17 @@ module Hecks
       # "hand-rolled approximation" this check exists to avoid; `send` on
       # an interpreter sharing this same `runtime`'s own registry is the
       # real thing, not a copy of it.
+      #
+      # @param runtime [Runtime::Dispatcher, Runtime::RemoteDispatcher] the still-live
+      #   booted runtime this replay just dispatched through
+      # @param interpreter [Runtime::SagaInterpreter] the interpreter whose (private)
+      #   `saga_correlation` re-derives this conversation's own correlation
+      # @param process_manager [Bluebook::ProcessManager] the process manager whose saga
+      #   log is walked
+      # @param correlation [Object] the correlation identifier to match, as
+      #   `saga_correlation` produces it — typically a String
+      # @return [Runtime::Event, nil] the real domain event this correlation's current
+      #   checkpoint last advanced on, or nil if it was only ever `begin_saga`'d
       def last_advancing_event(runtime, interpreter, process_manager, correlation)
         entry = runtime.registry.saga_log.reverse_each.find do |row|
           row[:process_manager] == process_manager.name && row[:instance] == correlation &&
@@ -560,6 +676,21 @@ module Hecks
       # fix) belongs right where it guards `interpreter.advance`, not in
       # a helper a reader would have to jump to just to see what is and
       # isn't being restored around that one call.
+      #
+      # @param runtime [Runtime::Dispatcher, Runtime::RemoteDispatcher] the still-live
+      #   booted runtime this replay just dispatched through
+      # @param interpreter [Runtime::SagaInterpreter] the interpreter to redeliver through
+      # @param domain_name [String] the owning domain's name
+      # @param process_manager [Bluebook::ProcessManager] the process manager under test
+      # @param anchor [Bluebook::Aggregate] any aggregate of the owning domain, used only
+      #   to open a `Heki` store at the right domain/root
+      # @param correlation [Object] the conversation's own correlation identifier
+      # @param saga [Hash] this correlation's persisted `:state`/`:memory`
+      # @param redelivery [Runtime::Event] the real domain event to redeliver
+      # @return [Hash, nil] a divergence Hash (`:field`, `:domain`, `:process_manager`,
+      #   `:correlation`, `:on`, `:before`, `:after`) if the redelivery visibly changed
+      #   state/memory; nil if it left the checkpoint unchanged, or if the cold-read
+      #   checkpoint could not be found at all
       def check_one_saga_redelivery(runtime, interpreter, domain_name, process_manager, anchor,
                                     correlation, saga, redelivery)
         # rubocop:disable-next Metrics/BlockLength
@@ -621,6 +752,13 @@ module Hecks
       # second time" — `writer` already holds everything the first fold
       # wrote, so a second fold re-applies the identical operations on
       # top, and the two cold reads either agree (idempotent) or don't.
+      #
+      # @param writer [Adapters::Heki] the open store to append `entries` into
+      # @param tmp [String] the throwaway directory `writer` was opened against
+      # @param aggregate [Bluebook::Aggregate] the aggregate `entries` belongs to
+      # @param entries [Array<Ports::Persistence::Entry>] the journal entries to fold in
+      # @return [Hash{String => Object}] every stored record's id (stringified) mapped to
+      #   its materialized state, read back cold
       def fold!(writer, tmp, aggregate, entries)
         entries.each do |entry|
           writer.append(entry)
@@ -655,6 +793,17 @@ module Hecks
       # answer — identity, not `Value#==`, is the right notion of
       # "already found" here (two different value objects that happen to
       # hold equal fields are still two separate round trips to prove).
+      #
+      # @param node [Object] the value to walk; a `Runtime::Value` is recorded and
+      #   recursed into by field, a Hash or Array is recursed into by value/element,
+      #   anything else is ignored
+      # @param found [Array<Array(Runtime::Value, Bluebook::Aggregate, nil)>] accumulator
+      #   this method appends `[value, aggregate]` pairs to, in place
+      # @param seen [Hash] a `compare_by_identity` Hash used as a found-by-identity set,
+      #   mutated in place
+      # @param aggregate [Bluebook::Aggregate, nil] the aggregate `node` belongs to, carried
+      #   along unchanged for every value found beneath it
+      # @return [void]
       def walk_value_objects(node, found, seen, aggregate)
         case node
         when Runtime::Value

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

@@ -8,6 +8,8 @@ module Hecks
       # The argument shapes the Ruby/Rust divergences were actually found
       # through, injected on purpose, on every domain.
       #
+      # ## Why these shapes
+      #
       # Ten bugs in one QA session (BUG#7–#16, `QualityControl`'s own
       # ledger) clustered in a handful of mechanisms — and several were
       # only ever reachable because one domain happened to declare the
@@ -16,7 +18,7 @@ module Hecks
       # but-null `to:` was misread as a routing envelope (BUG#16), a blank
       # creating identity minted a phantom aggregate in Rust (BUG#15), a
       # single-field closed-set argument offered as bare `null` refused
-      # with different KINDS on the two engines (BUG#14). No other domain
+      # with different kinds on the two engines (BUG#14). No other domain
       # in the rotation could ever have found any of those, because
       # nothing generated ever produced the shape. This module produces
       # them — for a configurable fraction of command steps, chosen and
@@ -24,15 +26,19 @@ module Hecks
       # already draws from, so `generate(domain, seed:, steps:,
       # adversarial:)` stays exactly as reproducible per seed as it was.
       #
-      # **Opt-in, by construction**. `adversarial: 0.0` (the default) returns
-      # before drawing a single random number, so every pinned seed in
-      # spec/fuzzing, spec/rust_conformance_fuzz_spec.rb, bin/fuzz and
-      # bin/generate produces byte-for-byte what it produced before this
-      # module existed. `bin/qa_sweep` turns it on (reading
+      # ## Opt-in, by construction
+      #
+      # `adversarial: 0.0` (the default) returns before drawing a single
+      # random number, so every pinned seed in spec/fuzzing,
+      # spec/rust_conformance_fuzz_spec.rb, bin/fuzz and bin/generate
+      # produces byte-for-byte what it produced before this module
+      # existed. `bin/qa_sweep` turns it on (reading
       # `QualityControlDials::ADVERSARIAL_FRACTION`) — that script is the
       # one place a mutated step's own divergence is a finding rather than
       # a red CI gate.
       #
+      # ## When it applies
+      #
       # One mutation per step, applied in `StepBuilder#build_command_step`
       # after the arguments and identity are built and before the step's
       # own inline dispatch — so the generator's own `known_ids` tracking

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

@@ -122,7 +122,7 @@ module Hecks
               # 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, 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

data/lib/hecks/fuzzing/sequence_generator.rb

@@ -98,6 +98,26 @@ module Hecks
       # `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
@@ -108,6 +128,15 @@ module Hecks
       # 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)
@@ -130,6 +159,19 @@ module Hecks
       # 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|
@@ -164,6 +206,11 @@ module Hecks
         @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