hecks 2.7.0 → 2.9.0

data/lib/hecks/fuzzing/replay.rb

@@ -1,930 +0,0 @@
-require "fileutils"
-require "tmpdir"
-require_relative "isolated_boot"
-require_relative "self_consistency"
-require_relative "../query_specification/common/comparators"
-require_relative "../query_specification/common/where_clause"
-require_relative "../query_specification/field_path"
-require_relative "../ports/query/in_memory"
-
-module Hecks
-  module Fuzzing
-    # A step list, replayed in-process against a fresh boot — the same
-    # copy-to-tmp-and-reset preamble SequenceGenerator#call uses, and the
-    # same observable surface bin/run prints (instances, events,
-    # refusals, reactions, sagas, queries), but returned as data rather
-    # than JSON on stdout.
-    #
-    # Not what SequenceGenerator itself dispatches through while
-    # generating — that inline execution feeds the picker's own
-    # known_ids tracking and stays exactly as it is. This exists for
-    # everything else that needs "given a step list, boot fresh and tell
-    # me what happened": bin/fuzz recomputing a shrink candidate's true
-    # event count (removing a step changes what the sequence actually
-    # produces, so a shrunk candidate cannot reuse the original claim),
-    # and the declared-property checks in properties.rb. Both want it
-    # in-process — a property or a shrink-candidate check is a question
-    # this boot can answer itself, and paying for a subprocess and a
-    # second boot to ask it would be ~100x the cost for nothing.
-    #
-    # Refuses the same way SequenceGenerator's own safe_call does: a
-    # DOMAIN_REFUSAL or an EvaluationError is the domain declining a
-    # step, recorded and not fatal to the replay. Anything else
-    # propagates — a step that breaks the interpreter is a defect, not
-    # an observation to fold quietly into the history.
-    module Replay
-      module_function
-
-      # The ad hoc filter's own comparator roster — read directly from
-      # QuerySpecification::Common::COMPARATORS (the same nine names
-      # Vocabulary::QueryComparator declares), never re-typed. A
-      # declared bluebook query never sees an `op:` outside this set —
-      # `admits: "Vocabulary::QueryComparator"` refuses one at declare
-      # time — but a `"filter"`-shaped query step (below) has no
-      # declare-time gate at all, so this method gates it here instead.
-      #
-      # Not rust/src/kernel/query_comparators.rs's own ground truth —
-      # that hand-maintained Rust enum is missing `none_in_state` (the
-      # 9th comparator, added after the enum was written) and has
-      # already drifted; do not treat it as authoritative until item #9
-      # of the whole-project table-unification survey closes that gap.
-      FILTER_COMPARATORS = Hecks::QuerySpecification::Common::COMPARATORS.map(&:to_s).freeze
-
-      # The two classes `#enforce_givens`/`#enforce_lifecycle_guard`
-      # themselves ever raise — see Admissibility's own doc comment,
-      # `command_rules/admissibility.rb`. Any other DOMAIN_REFUSAL a step
-      # raises (TypeMismatch, EnsuresNotMet, InvariantViolation, ...)
-      # proves the guard itself did not fire, since it runs first in
-      # DISPATCH_ORDER.
-      GUARD_REFUSAL_CLASSES = [Runtime::GivenNotMet, Runtime::LifecycleRefused].freeze
-
-      # One tightly ordered loop over steps, with several "oracle" snapshots
-      # (reaction_mark, fan_out_snapshot, guard_check, mutation_trace) that
-      # must be taken at very specific points relative to dispatch — see
-      # fan_out_snapshot's own comment above for the real bug this exact
-      # before/after ordering fixes. Splitting this into smaller methods
-      # would mean threading five-plus oracle-state locals across method
-      # boundaries as parameters/return values, and
-      # would let a future editor silently reorder a snapshot relative to
-      # `dispatch` without any single method looking wrong — the ordering
-      # invariant is only visible with the whole sequence in one place.
-      # rubocop:disable-next Metrics/AbcSize
-      # rubocop:disable-next Metrics/CyclomaticComplexity
-      # rubocop:disable-next Metrics/MethodLength
-      # rubocop:disable-next Metrics/PerceivedComplexity
-      # `self_consistency:` — off by default, same "existing callers see no
-      # change" contract `adapter:` already has. `bin/qa_sweep` is the one
-      # real caller that opts in (gated by `QualityControlDials::
-      # SELF_CONSISTENCY_CHECKS`/`--self-consistency`): `bin/fuzz`,
-      # `Properties.check`'s own callers, and every existing spec keep
-      # calling this with no second axis of comparison at all, exactly as
-      # before. Computed here, not by a caller reading `runtime` back out
-      # afterward — `runtime` and the whole `IsolatedBoot` tmp directory
-      # go out of scope the moment this method returns (see this file's
-      # own header), so `Hecks::Fuzzing::SelfConsistency.check` has to run
-      # while both are still alive, against the exact same repositories
-      # this replay's own dispatch loop just wrote to.
-      #
-      # `database:`/`schema:` — only meaningful, and required, for
-      # `adapter: :postgres_era` — see `IsolatedBoot#rebind_to_postgres_era!`'s
-      # own header for why that one mode takes caller-owned connection
-      # identity rather than a shared default the way `:postgres` does.
-      # Forwarded straight through, unchanged, exactly like `adapter:`
-      # itself already was.
-      #
-      # @param domain_path [String] filesystem path to the domain directory to replay
-      # @param steps [Array<Hash>] the step list to dispatch, any-keyed (normalized to
-      #   String keys internally)
-      # @param adapter [Symbol] persistence adapter to boot the copy with
-      # @param database [String, nil] PostgresEra database name; required, only meaningful
-      #   when `adapter: :postgres_era`
-      # @param schema [String, nil] PostgresEra schema name; required, only meaningful
-      #   when `adapter: :postgres_era`
-      # @param self_consistency [Boolean] whether to run `SelfConsistency.check` against
-      #   this replay's own runtime before returning
-      # @return [Hash] the replay history: `:instances`, `:events`, `:refusals`,
-      #   `:reactions`, `:sagas`, `:saga_instances`, `:queries`, `:dry_runs`,
-      #   `:dry_run_traces`, `:fan_outs`, `:guard_checks`, `:mutation_traces`,
-      #   `:outbox_traces`, `:saga_dispatches`, `:policy_dispatches`, `:bluebook`,
-      #   `:bluebooks`, and (when `self_consistency:` is true) `:self_consistency`
-      def call(domain_path, steps, adapter: :memory, database: nil, schema: nil, self_consistency: false)
-        # See isolated_boot.rb's own header: resets data/ and rebinds
-        # persistence to the chosen adapter (Memory by default), since a
-        # Postgres-bound domain's real store lives outside the copied
-        # directory and cannot be reached by resetting data/ alone.
-        IsolatedBoot.call(domain_path, adapter: adapter, database: database, schema: schema) do |copy|
-          runtime = Hecks.boot(copy)
-
-          refusals        = []
-          queries         = []
-          dry_runs        = []
-          dry_run_traces  = []
-          fan_outs        = []
-          guard_checks    = []
-          mutation_traces = []
-          outbox_traces   = []
-
-          # Every aggregate a `for_each` could ever query, resolved once —
-          # `[domain, aggregate_name]` pairs, gleaned from every loaded
-          # bluebook's own fanning-out policies. Empty for every domain
-          # with no `for_each` at all (every example this corpus ships
-          # today), so the snapshot below costs nothing until a domain
-          # actually declares one.
-          fan_out_targets = runtime.registry.bluebooks.each_with_object({}) do |(domain, bluebook), targets|
-            bluebook.policies.select(&:fans_out?).each do |policy|
-              query_domain, aggregate_name, = policy.for_each_route(domain)
-              targets[[query_domain, aggregate_name]] ||= runtime.registry.bluebook(query_domain)&.aggregate(aggregate_name)
-            end
-          end
-
-          steps.each do |step|
-            step = step.transform_keys(&:to_s)
-            args = (step["args"] || {}).transform_keys(&:to_sym)
-
-            if (question = step["query"])
-              # **The ad hoc, single-comparator filter** — a "query" step whose
-              # own value is a Hash, not a name: `{aggregate:, field:, op:,
-              # value:}`, the same wire shape kernel/cli.rs's new object-
-              # form "query" step reads on the Rust side (that file's own
-              # header explains why this shape exists at all: it bypasses
-              # the bluebook query DSL entirely, so it needs no generated
-              # per-domain codegen to prove for real). Answered here by
-              # calling `Ports::Query::InMemory` directly — the real
-              # production comparator engine, not a second, hand-rewritten
-              # copy of it — against the raw repository, never through
-              # `runtime.query`, which only ever resolves a named, declared
-              # ask.
-              if question.is_a?(Hash)
-                begin
-                  rows = run_filter(runtime, question)
-                  queries << { query: question, rows: rows, instances_at: snapshot_instances(runtime) }
-                rescue StandardError => e
-                  refusals << { verb: filter_label(question), error: e.message, kind: refusal_kind(e) }
-                end
-                next
-              end
-
-              # **The query oracle** — two independent engines, each run and
-              # caught on its own, never a single shared `begin`/`rescue`
-              # wrapping both calls. A shared begin/rescue meant `runtime.
-              # query` raising (native refuses) short-circuited before
-              # `runtime.reference_query` ever ran at all — the entry
-              # recorded only `error:`, with no `reference_rows` and no
-              # record of what the reference interpreter would have
-              # answered — and `runtime.reference_query` raising instead
-              # (reference refuses, native already succeeded) landed in the
-              # same rescue, discarding the native `rows` this begin block
-              # had already computed and recording the whole ask as an
-              # ordinary refusal. Either way, "one engine refused and the
-              # other did not" — a real divergence, exactly the shape a
-              # differential oracle exists to catch — read as "refused,
-              # nothing to compare" and vanished. Each engine's own
-              # success/failure is captured here independently instead, so
-              # `Properties.query_answers_match_reference` can tell "both
-              # refused" (fine) apart from "one refused, the other did not"
-              # (a finding) rather than having every refusal-shaped run
-              # skipped uniformly.
-              native_rows = native_error = nil
-              begin
-                native_rows = runtime.query(question, **args)
-              rescue *Runtime::DOMAIN_REFUSALS, Bluebook::Expression::EvaluationError => e
-                native_error = e
-              end
-
-              # Read-model asks (bare domain form, no "::") have no
-              # reference twin at all — never attempted, not "attempted and
-              # agreed."
-              has_reference = question.include?("::")
-              reference_rows = reference_error = nil
-              if has_reference
-                begin
-                  reference_rows = runtime.reference_query(question, **args)
-                rescue *Runtime::DOMAIN_REFUSALS, Bluebook::Expression::EvaluationError => e
-                  reference_error = e
-                end
-              end
-
-              entry = { query: question, args: args, rows: native_rows, instances_at: snapshot_instances(runtime) }
-              entry[:error] = native_error.message if native_error
-              if has_reference
-                entry[:reference_rows]  = reference_rows
-                entry[:reference_error] = reference_error.message if reference_error
-              end
-              queries << entry
-
-              refusals << { verb: question, error: native_error.message, kind: refusal_kind(native_error) } if native_error
-              next
-            end
-
-            # `{"dry_run": verb, "args": …}` — `Dispatcher#dry_run?`: the command
-            # evaluated hypothetically, nothing saved or emitted, no reaction.
-            # Recorded, never a refusal: a refused dry run is an answer.
-            #
-            # `dry_runs` stays exactly `{verb:, ok:, error?:}` — the same
-            # shape it always had, and the same shape `kernel/cli.rs`'s own
-            # `dry_run` answers (`{"verb", "ok"}` or `{"verb", "ok": false,
-            # "error"}`, that function's own doc comment) — `spec/rust_
-            # conformance_spec.rb` compares this array against the compiled
-            # binary's own verbatim, so it can never carry a key Rust's own
-            # answer does not. The role-gated binding (`as_step_caller`,
-            # the same `role:`/`actor_id:` a real dispatch gets below) still
-            # applies to the dry-run call itself — only what gets recorded
-            # about it is unchanged.
-            #
-            # `dry_run_traces` — a separate, parallel array (same order,
-            # not merged into `dry_runs` above) carrying `before:`/`after:`
-            # snapshots of the whole observable store (every instance, the
-            # event count) on either side of the hypothetical call, so
-            # `Properties.dry_runs_leave_no_trace` can hold `Dispatcher
-            # #dry_run?`'s own contract to the store rather than trusting
-            # it. Ruby's own oracle data — Rust has nothing to compare it
-            # against, so it stays out of the compared surface entirely.
-            if (hypothetical = step["dry_run"])
-              before = { instances: snapshot_instances(runtime), events: runtime.events.size }
-              entry  = { verb: hypothetical }
-              begin
-                as_step_caller(step) { runtime.dry_run?(hypothetical, **args) }
-                entry[:ok] = true
-              rescue *Runtime::DOMAIN_REFUSALS, Bluebook::Expression::EvaluationError => e
-                entry.merge!(ok: false, error: e.message)
-              end
-              after = { instances: snapshot_instances(runtime), events: runtime.events.size }
-              dry_runs << entry
-              dry_run_traces << entry.merge(before: before, after: after)
-              next
-            end
-
-            begin
-              # **The fan-out oracle's own low-water mark** — taken before
-              # dispatch, so any reaction this one step's own announced
-              # events produce (`reaction_log` grows in place, the same
-              # Array `runtime.reactions` already exposes) can be sliced
-              # out after, and matched against an independent recomputation
-              # of what a `for_each` policy should have fanned out over —
-              # the query oracle's own shape (two engines, compared, never
-              # one graded against itself), aimed at fan-out instead of a
-              # named ask.
-              reaction_mark = runtime.reactions.size
-
-              # **The outbox oracle's own low-water marks** — taken before
-              # dispatch, same idiom as `reaction_mark` right above:
-              # `saga_log_mark` slices `runtime.sagas` (a single flat
-              # array, safe to index into directly) the identical way
-              # `reaction_mark` already slices `runtime.reactions`.
-              # `outbox_before_ids` is a set of delivery_ids, not a
-              # size — `runtime.outbox.rows` concatenates every bound
-              # repository's own array in a fixed per-store order
-              # (`Outbox::Relay#rows`, `stores.flat_map`), so a row a
-              # different step's dispatch enqueues into an
-              # earlier-iterated store would land in the middle of
-              # that concatenated list, not at its tail — a plain
-              # "grew from N to M, take the tail" slice (the shape
-              # `reaction_mark`/`saga_log_mark` both get away with,
-              # since `reaction_log`/`saga_log` are each already one
-              # flat array irrespective of domain) would silently miss
-              # or misattribute rows the moment more than one
-              # repository has an outbox. `delivery_id` is unique per
-              # store by construction (`Row#to_h`'s own header;
-              # `hecks_outbox`'s `UNIQUE` column in the Postgres/Sqlite
-              # DDL, `outbox_enqueue`'s own de-dup check in Memory), so
-              # membership in this set is exactly "existed before this
-              # step's own dispatch ran."
-              saga_log_mark      = runtime.sagas.size
-              outbox_before_ids  = runtime.outbox.rows.map(&:delivery_id)
-
-              # The snapshot a `for_each` query would have seen — taken
-              # before this step's own dispatch, not after. The real
-              # `deliver_for_each` runs its query synchronously, inside
-              # this same dispatch, before this call even returns — so an
-              # oracle that re-reads the live repository after `dispatch`
-              # answers sees whatever the fan-out's own dispatched
-              # commands already mutated (an Account a `Review` leg just
-              # moved out of "open," say), not what the query actually
-              # matched. A measured bug, not a hypothetical one — this
-              # exact ordering is what `spec/fuzzing/fan_out_spec.rb`'s
-              # own adversarial run against a live `for_each` policy
-              # caught the first time this shipped without it.
-              fan_out_snapshot = fan_out_targets.each_with_object({}) do |((fdomain, faggregate_name), aggregate), snap|
-                next unless aggregate
-
-                snap[[fdomain, faggregate_name]] =
-                  runtime.registry.repository(fdomain, aggregate).all.to_h { |record| [record.id, record.state.dup] }
-              end
-
-              # **The guard oracle's own pre-dispatch read** — same idiom,
-              # same placement, same reason as fan_out_snapshot right
-              # above: `Admissibility#enforce_givens` (which itself calls
-              # `#enforce_lifecycle_guard` when `declaring:` is passed)
-              # is called a second time here, independently, against the
-              # record exactly as CommandInterpreter#hydrate's own acting
-              # branch would find it (`repository.find(id).dup` — the
-              # identical three-tier id fallback, Identity.of/.from,
-              # reproduced read-only) — before this step's real dispatch
-              # can mutate anything a cross-aggregate given dereferences
-              # (`customer.status`). A pure predicate read, side-effect
-              # free, so calling it twice changes nothing this step
-              # itself observes.
-              guard_check = build_guard_check(runtime, step["verb"], args)
-
-              # **The mutation oracle's own pre-dispatch read** — same
-              # idiom again: an entity-dispatched command's own
-              # `append`/`remove`/`multiply`/`clamp` mutations (S17's
-              # fixture, spec/fixtures/entity_list_mutations, now a real
-              # bootable domain) act on the entity's own attributes, so
-              # the element addressed by this step's own identity args
-              # is snapshotted before dispatch, materialized to plain
-              # data — `nil` for anything out of scope (an aggregate-
-              # level command, an entity command with no mutations at
-              # all, or one whose identity args don't resolve).
-              mutation_trace = build_mutation_trace(runtime, step["verb"], args)
-
-              # `role:`/`actor_id:` — optional per-step keys, absent on every
-              # one of the 231 existing `spec/corpus/*.json` steps (their own
-              # unwrapped `runtime.dispatch` call, unchanged, so nothing
-              # already pinned changes behavior). Binds the same ambient
-              # caller `refuse_role_mismatch` reads (`Hecks.as_caller`,
-              # `Runtime::Caller.as`) for exactly the one dispatch this
-              # step makes, then unbinds — mirrors `Caller.as`'s own
-              # `ensure`-restore, so back-to-back steps with different (or
-              # no) `role:` never leak into each other. `actor_id:` is the
-              # sibling `kernel/cli.rs` already read (its own comment on
-              # the key): with it, a Governance-attached domain runs the
-              # real `holds_role?` lookup instead of the string fallback.
-              result = as_step_caller(step) { runtime.dispatch_flat(step["verb"], args) }
-
-              fan_outs.concat(fan_out_findings(runtime, fan_out_snapshot, result.events, runtime.reactions[reaction_mark..]))
-
-              # **The outbox oracle's own capture** — every outbox row this
-              # step's own dispatch newly wrote (across every bound
-              # repository, including any a reaction cascade touched —
-              # `outbox_before_ids` was taken before `dispatch`, which
-              # is the same call that runs the whole cascade
-              # synchronously, `reenter` included), paired with the
-              # `reaction_log`/`saga_log` rows that same dispatch
-              # produced. Skipped entirely when empty — a step whose
-              # own aggregate has no outbox enqueues nothing here, and
-              # there is nothing for `Properties.outbox_rows_match_
-              # reactions` to check for it (its own reactions, if any,
-              # went through the direct, pre-outbox path instead).
-              outbox_new_rows = runtime.outbox.rows.reject { |row| outbox_before_ids.include?(row.delivery_id) }
-              if outbox_new_rows.any?
-                outbox_traces << { verb: step["verb"], rows: outbox_new_rows.map(&:to_h),
-                                    reactions: runtime.reactions[reaction_mark..].dup,
-                                    sagas: runtime.sagas[saga_log_mark..].dup }
-              end
-
-              guard_checks << guard_check.merge(actual_refused: false, actual_kind: nil) if guard_check
-              # After — only on success ; a refused step mutated nothing,
-              # so there is no "after" to compare (and #build_mutation_
-              # trace already skipped anything with no mutations to
-              # trace in the first place).
-              mutation_traces << mutation_trace.merge(after: read_mutation_after(runtime, mutation_trace)) if mutation_trace
-            rescue *Runtime::DOMAIN_REFUSALS, Bluebook::Expression::EvaluationError => e
-              # `kind:` — the raised class, not re-derived from the message.
-              # `GivenNotMet`/`EnsuresNotMet` share their exact wording
-              # ("<command> refused — <description>") with four other
-              # refusal templates (Vocabulary's own LifecycleRefused/
-              # TypeMismatch/Unauthorized entries) — a property that told
-              # a guard refusal apart by pattern-matching the string alone
-              # would misread every one of those as a guard, or a guard as
-              # one of those. The class is unambiguous where the string
-              # is not.
-              refusals << { verb: step["verb"], error: e.message, kind: refusal_kind(e) }
-              # Only a refusal raised by the guard itself counts here —
-              # measured, not assumed: a step whose args were simply
-              # incomplete (AbsentArgument, from normalize_args — which
-              # runs before enforce_givens in DISPATCH_ORDER) never
-              # reached the guard at all, and this oracle's own first
-              # live run against real generated pizzas data caught
-              # exactly that case as a false positive (a malformed-args
-              # step the generator deliberately produces, `amount:`
-              # dropped entirely) before this comment existed. Whether a
-              # refusal from a stage after enforce_givens (TypeMismatch
-              # on a mutation, EnsuresNotMet, InvariantViolation) proves
-              # the guard passed can't be told apart from a same-shaped
-              # refusal from a stage before it by class alone (TypeMismatch
-              # can come from either), so anything that isn't one of the
-              # two guard classes is left out of guard_checks entirely —
-              # inconclusive, not a claimed pass.
-              if guard_check && GUARD_REFUSAL_CLASSES.include?(e.class)
-                guard_checks << guard_check.merge(actual_refused: true,
-                                                  actual_kind:    e.class.name)
-              end
-            end
-          end
-
-          instances = snapshot_instances(runtime)
-
-          events = runtime.events.map do |event|
-            { name: event.name, aggregate: event.aggregate, id: event.id, payload: event.payload }
-          end
-
-          # The live process-manager store, materialised to inert data —
-          # `{ pm_name => { correlation => { state:, memory: } } }`, the
-          # same shape SagaInterpreter#checkpoint hands its persistence
-          # adapter (state plus a `Value.materialize`d memory, which is
-          # exactly what `deep_copy` there serialises). Captured here
-          # because Replay returns the history, not the runtime, and the
-          # runtime goes out of scope with the boot — so the saga-durability
-          # property (Properties.sagas_rehydrate_cleanly) reads this rather
-          # than reaching into a store the Memory rebind leaves as the
-          # no-op NULL_SAGA_STORE. Materialised, not raw, so the history
-          # stays plain data and the round-trip check sees exactly the
-          # bytes a real adapter would have persisted.
-          saga_instances = runtime.registry.saga_instances.each_with_object({}) do |(pm_name, conversations), out|
-            out[pm_name] = conversations.each_with_object({}) do |(correlation, instance), rows|
-              rows[correlation] = { state: instance[:state], memory: Runtime::Value.materialize(instance[:memory]) }
-            end
-          end
-
-          # The booted chapter rides along — the boot already happened, and
-          # properties.rb's lifecycle/saga checks need the declared IR
-          # (state sets, handler graphs) beside the history it produced.
-          # Free: no second boot, just the object the first one already
-          # built.
-          #
-          # `bluebook:` (singular) stays the first-loaded chapter — every
-          # existing property scopes itself to "only what we have the
-          # grammar for" against exactly this one, deliberately (see
-          # lifecycle_values_are_declared's own comment). `bluebooks:`
-          # (plural) is the full map, keyed by domain name — a domain
-          # under fuzz commonly composes more than one bluebook (banking
-          # alone loads Banking + Governance + Identity), and a refusal
-          # or an event can legitimately come from any of them, not only
-          # whichever one happened to load first. A property that needs
-          # to resolve a verb back to its own declaring bluebook — not
-          # "the" bluebook — reads this instead.
-          history = { instances: instances, events: events, refusals: refusals,
-                      reactions: runtime.reactions, sagas: runtime.sagas, saga_instances: saga_instances,
-                      queries: queries, dry_runs: dry_runs, dry_run_traces: dry_run_traces,
-                      fan_outs: fan_outs, guard_checks: guard_checks,
-                      mutation_traces: mutation_traces, outbox_traces: outbox_traces,
-                      saga_dispatches: runtime.saga_dispatches, policy_dispatches: runtime.policy_dispatches,
-                      bluebook: runtime.registry.bluebooks.values.first,
-                      bluebooks: runtime.registry.bluebooks.dup }
-
-          # `runtime` is still live here — this is the one and only place
-          # it is. See `SelfConsistency`'s own header for why this needs
-          # to happen now, against the same registry/repositories this
-          # replay's own dispatch loop just populated, not a second boot.
-          history[:self_consistency] = SelfConsistency.check(runtime, history) if self_consistency
-
-          history
-        end
-      end
-
-      # Runs the block with this step's `role:`/`actor_id:` bound as the
-      # ambient caller, if it declares one.
-      #
-      # A step with no `role:` dispatches exactly as every corpus step
-      # always has — bare, no caller bound at all (`Caller.current` nil,
-      # so `refuse_role_mismatch` returns before checking anything).
-      #
-      # @param step [Hash] a String-keyed step hash, read for `"role"`/`"actor_id"`
-      # @yield the step's own dispatch or dry-run call
-      # @return [Object] whatever the block returns
-      def as_step_caller(step, &)
-        return yield unless step["role"]
-
-        Hecks.as_caller(role: step["role"], actor_id: step["actor_id"], &)
-      end
-
-      # The guard oracle's own resolution — "which record, if any, is
-      # this step about, and would enforce_givens/enforce_lifecycle_guard
-      # have refused it against that record's pre-dispatch state" —
-      # reproduced read-only from already-public pieces
-      # (Naming.split_verb, registry.bluebook/.aggregate/.command,
-      # Runtime::Identity.of/.from, repository.find), the exact same
-      # three-tier fallback CommandInterpreter#hydrate's own acting
-      # branch uses, minus its creating/duplicate-checking logic (a
-      # creating command has no pre-existing record to snapshot, and
-      # every real target this closes — Debit/CloseAccount/Credit/
-      # FreezeAccount — already acts on one).
-      #
-      # `nil` for anything out of scope: an entity/port verb (a dotted
-      # command_name — EntityInterpreter's own enforce_givens call,
-      # `parent:`-shaped, is a different call signature this does not
-      # reproduce), a creating command, an unresolvable id, or a command
-      # that declares neither `givens` nor `from` at all (nothing to
-      # check — logging a guaranteed, tautological pass would be noise,
-      # not a finding, the same reason `aggregation_matches_recompute`
-      # skips a read model with no count/median declared).
-      #
-      # Never lets a resolution surprise (a malformed verb, a dangling
-      # reference) become the step's own real dispatch outcome — this
-      # is a separate, best-effort read, not part of the step's own
-      # control flow.
-      # Every persisted record, keyed the way `query_eligible_rows`/
-      # `#eligible_rows` (properties.rb) already expect. Called once per
-      # query step (see `call`, above), not only once at the very end,
-      # because a query asked at step 1 of a script whose later steps go on
-      # to create more records needs to be checked, by every property that
-      # independently recomputes "the eligible rows," against the state as
-      # of that query — not the final snapshot after the whole replay.
-      # Found live:
-      # `Banking.accounts_by_kind`, asked as literally the first step of a
-      # 3-step script, correctly answered against zero accounts (none
-      # existed yet) while `group_by_matches_recompute`'s own independent
-      # recompute claimed "1 eligible row" — the one account the script's
-      # later two steps went on to create. Each query step now carries
-      # its own `instances_at:` snapshot, taken at the moment it ran, so
-      # every property that recomputes against "the eligible rows" reads
-      # the state as that query actually saw it, not a shared final one.
-      #
-      # @param runtime [Runtime::Dispatcher, Runtime::RemoteDispatcher] the booted runtime
-      #   to read every persisted record from
-      # @return [Hash{String => Hash}] every persisted record's state, keyed by
-      #   `"Domain::Aggregate#id"`
-      def snapshot_instances(runtime)
-        instances = {}
-        runtime.registry.bluebooks.each do |domain_name, bluebook|
-          bluebook.aggregates.each do |aggregate|
-            runtime.registry.repository(domain_name, aggregate).all.each do |record|
-              instances["#{domain_name}::#{aggregate.name}##{record.id}"] = record.state
-            end
-          end
-        end
-        instances
-      end
-
-      # One early-return chain resolving "which record, if any" (see the
-      # long comment above), feeding a two-stage guard replay
-      # (enforce_givens then admissible_transition) that must run in that
-      # order to mirror the real DISPATCH_ORDER. Splitting the resolution
-      # out would still require passing domain_name/aggregate_name/
-      # aggregate/command/record back in, for no gain — every early
-      # return already reads as "nothing to check" at its own site.
-      # rubocop:disable-next Metrics/AbcSize
-      # rubocop:disable-next Metrics/CyclomaticComplexity
-      # rubocop:disable-next Metrics/PerceivedComplexity
-      #
-      # @param runtime [Runtime::Dispatcher, Runtime::RemoteDispatcher] the booted runtime
-      #   to resolve the step's own verb and record against
-      # @param verb [String] the step's own command verb
-      # @param args [Hash{Symbol => Object}] the step's own args, symbol-keyed
-      # @return [Hash, nil] `{verb:, domain:, aggregate:, command:, id:, recomputed_refused:,
-      #   recomputed_kind:}` if there was a record and a guard to check; nil for anything
-      #   out of scope (an entity/port verb, a creating command, an unresolvable id, or a
-      #   command with nothing to check)
-      def build_guard_check(runtime, verb, args)
-        domain_name, aggregate_name, command_name = Naming.split_verb(verb)
-        return nil unless command_name && !command_name.include?(".")
-
-        aggregate = runtime.registry.bluebook(domain_name)&.aggregate(aggregate_name)
-        command   = aggregate&.command(command_name)
-        return nil unless aggregate && command && !command.creates?
-
-        # Nothing to check, genuinely — not "nothing THIS reproduces yet".
-        # A transition-only guard (no per-command `from:`, no `given`,
-        # only an aggregate `lifecycle do transition ... end` block
-        # naming this command — `Admit`/`Reject`'s own shape) still
-        # counts as something to check now that `admissible_transition`
-        # is reproduced below; skipping it here would just move the
-        # exact gap that call was added to close one line earlier.
-        has_transition = aggregate.lifecycle&.transitions_for(command.hecks_name)&.any?
-        return nil if command.givens.empty? && !command.from && !has_transition
-
-        reference_key = command.references.to_s.empty? ? nil : Naming.reference_key(command.references)
-        id = Runtime::Identity.of(aggregate, args) ||
-             Runtime::Identity.from(aggregate, args, :id) ||
-             (reference_key && Runtime::Identity.from(aggregate, args, reference_key))
-        return nil unless id
-
-        record = runtime.registry.repository(domain_name, aggregate).find(id)
-        return nil unless record
-
-        rules = Runtime::CommandRules.new(runtime.registry)
-        recomputed_kind = begin
-          rules.enforce_givens(record.dup, command, args, domain: domain_name, declaring: aggregate)
-
-          # A second, separate DISPATCH_ORDER step — `enforce_givens`
-          # (just above) only ever checks a per-command `from:` clause
-          # (its own trailing `enforce_lifecycle_guard(declaring, ...)
-          # if declaring` call) — the aggregate's own `lifecycle do
-          # transition "X" => Y, from: Z end` block is a wholly separate
-          # method (`admissible_transition`), called as its own later
-          # DISPATCH_ORDER step (`:enforce_givens` then
-          # `:admissible_transition` — Vocabulary.symbols
-          # ("AggregateDispatchOrder")), not reached from inside
-          # `enforce_givens` at all. Missing this call meant a command
-          # declared with no per-command `from:` of its own — every real
-          # transition-guarded command in this corpus, `Admit`/`Reject`
-          # included — always recomputed "admitted" no matter the
-          # record's actual state, because the one check that would
-          # have refused it was never run. Found live: `Expression::
-          # Expression.Admit`, fuzzed against `lib/hecks/grammar`
-          # (a domain the property's own hand-verification — Banking,
-          # Pizzas — never happened to exercise a transition-guarded,
-          # no-per-command-`from:` command against). Called only when
-          # `enforce_givens` didn't already refuse, mirroring the real
-          # pipeline's own "first refusal wins" order exactly.
-          rules.admissible_transition(aggregate, command, record.dup)
-          nil
-        rescue *GUARD_REFUSAL_CLASSES => e
-          e.class.name
-        end
-
-        { verb: verb, domain: domain_name, aggregate: aggregate_name, command: command_name, id: id,
-          recomputed_refused: !recomputed_kind.nil?, recomputed_kind: recomputed_kind }
-      rescue StandardError
-        nil
-      end
-
-      # The mutation oracle's own pre-dispatch read — scoped, on
-      # purpose, to entity-dispatched commands only (a dotted
-      # command_name): the one place `append`/`remove`/`multiply`/
-      # `clamp` are known to act on an entity's own attributes
-      # (spec/fixtures/entity_list_mutations' own TaggedList — `tags`
-      # a value-object list, `count` a VO-typed scalar), never on
-      # another nested entity list — so this never needs to reproduce
-      # `MutationApplier#entity_element`'s own auto-mint/collision logic
-      # (item 1's own fix) at all. An aggregate-level command whose own
-      # mutation appends an entity (`Board.AddList`, `SafeDepositBox.
-      # LogVisit`) is a different, already-covered case — item 1's own
-      # collision property, not this one.
-      #
-      # `nil` for anything out of scope: an aggregate-level command, an
-      # entity command with no mutations at all, or one whose identity
-      # args (parent or element) don't resolve.
-      # Same shape as build_guard_check just above: one early-return chain
-      # resolving the entity/element this step's args address (see the
-      # comment above), each step depending on the previous one's
-      # resolved value. Threading those locals out to smaller methods
-      # would cost more than the cop gains.
-      # rubocop:disable-next Metrics/AbcSize
-      # rubocop:disable-next Metrics/CyclomaticComplexity
-      # rubocop:disable-next Metrics/PerceivedComplexity
-      #
-      # @param runtime [Runtime::Dispatcher, Runtime::RemoteDispatcher] the booted runtime
-      #   to resolve the step's own verb and record against
-      # @param verb [String] the step's own command verb
-      # @param args [Hash{Symbol => Object}] the step's own args, symbol-keyed
-      # @return [Hash, nil] `{verb:, domain:, aggregate:, command:, parent_id:, list_attr:,
-      #   element_wants:, before:, args:}` if this is an entity-dispatched command with
-      #   mutations acting on a resolvable element; nil for anything out of scope
-      def build_mutation_trace(runtime, verb, args)
-        domain_name, aggregate_name, command_name = Naming.split_verb(verb)
-        return nil unless command_name&.include?(".")
-
-        aggregate = runtime.registry.bluebook(domain_name)&.aggregate(aggregate_name)
-        return nil unless aggregate
-
-        entity_name, entity_command_name = command_name.split(".", 2)
-        entity  = aggregate.entities.find { |candidate| candidate.hecks_name == entity_name }
-        command = entity&.command(entity_command_name)
-        return nil unless command&.mutations&.any?
-
-        reference_key = command.references.to_s.empty? ? nil : Naming.reference_key(command.references)
-        parent_id = Runtime::Identity.of(aggregate, args) ||
-                    Runtime::Identity.from(aggregate, args, :id) ||
-                    (reference_key && Runtime::Identity.from(aggregate, args, reference_key))
-        return nil unless parent_id
-
-        record = runtime.registry.repository(domain_name, aggregate).find(parent_id)
-        return nil unless record
-
-        list_attr = aggregate.attributes.find { |a| a.list? && a.type.to_s == entity.hecks_name }
-        return nil unless list_attr
-
-        wants = entity.identity_paths.map do |path|
-          head = path.to_s.split(".").first.to_sym
-          raw  = args[head]
-          return nil if raw.nil?
-
-          [head, Runtime::Value.for_attribute(aggregate, entity.attribute(head), raw)]
-        end
-
-        element = Array(record.state[list_attr.name]).find { |el| wants.all? { |head, want| el[head] == want } }
-        return nil unless element
-
-        { verb: verb, domain: domain_name, aggregate: aggregate_name, command: command_name,
-          parent_id: parent_id, list_attr: list_attr.name, element_wants: wants,
-          before: Runtime::Value.materialize(element), args: args }
-      rescue StandardError
-        nil
-      end
-
-      # Re-reads the same entity element, after dispatch, for comparison against
-      # `trace[:before]`.
-      #
-      # The same element, re-located, after dispatch — by identity, not
-      # position (an append could have changed the array's own length
-      # or order relative to it). `nil` if it somehow vanished (not
-      # expected for any op this fixture declares — none of them
-      # remove the acted-on element itself — but a property comparing
-      # against `nil` fails loudly rather than crashing this replay).
-      #
-      # @param runtime [Runtime::Dispatcher, Runtime::RemoteDispatcher] the booted runtime
-      #   dispatch just ran against
-      # @param trace [Hash] the mutation trace `build_mutation_trace` built for this step,
-      #   read for `:domain`, `:aggregate`, `:parent_id`, `:list_attr`, `:element_wants`
-      # @return [Hash, nil] the element's materialized state after dispatch, or nil if
-      #   the parent record, its aggregate, or the element itself can no longer be found
-      def read_mutation_after(runtime, trace)
-        aggregate = runtime.registry.bluebook(trace[:domain])&.aggregate(trace[:aggregate])
-        return nil unless aggregate
-
-        record = runtime.registry.repository(trace[:domain], aggregate).find(trace[:parent_id])
-        return nil unless record
-
-        element = Array(record.state[trace[:list_attr]]).find do |el|
-          trace[:element_wants].all? { |head, want| el[head] == want }
-        end
-        element && Runtime::Value.materialize(element)
-      rescue StandardError
-        nil
-      end
-
-      # The fan-out oracle — one finding per (event, for_each policy) this
-      # step's own announced events could have triggered, independent of
-      # `PolicyInterpreter#deliver_for_each`: the same `where` evaluator
-      # every given/ensures already runs through, but the query answered
-      # by `Ports::Query::InMemory.holds?` directly against the live
-      # repository (`Replay.run_filter`'s own idiom), never by calling
-      # `QueryInterpreter` — sharing that call would make this oracle
-      # blind to exactly the code the fan-out feature adds.
-      #
-      # `expected_row_ids` is `nil` when `where` did not hold — no dispatch
-      # is the claim, not "dispatched to zero rows," so a property
-      # comparing this against the reaction log needs to tell the two
-      # apart. Recomputed once per event, not once per policy-and-event,
-      # because a `Chapter` de-duplicates on nothing this loop cannot
-      # cheaply repeat.
-      #
-      # @param runtime [Runtime::Dispatcher, Runtime::RemoteDispatcher] the booted runtime
-      # @param snapshot [Hash{Array(String, String) => Hash}] the pre-dispatch `for_each`
-      #   query snapshot, keyed by `[query_domain, aggregate_name]`
-      # @param announced [Array<Runtime::Event>] the events this step's own dispatch produced
-      # @param reactions_since [Array<Hash>] the reaction-log rows this step's own
-      #   dispatch appended
-      # @return [Array<Hash>] one `{policy:, on:, expected_row_ids:, actual_row_ids:}`
-      #   finding per (event, fanning-out policy) pair
-      def fan_out_findings(runtime, snapshot, announced, reactions_since)
-        announced.each_with_object([]) do |event, findings|
-          # `event.aggregate` is domain-qualified ("Banking::Account" —
-          # see command_rules/emission.rb's own Event.new) — the same
-          # source `PolicyInterpreter#policies_for` reads, split the
-          # same two ways: `Naming.demodulise` for the emitting
-          # aggregate's bare name, plain `split("::")` for the domain.
-          domain = event.aggregate.to_s.split("::").first
-          bluebook = runtime.registry.bluebook(domain)
-          next unless bluebook
-
-          emitting = Naming.demodulise(event.aggregate)
-
-          bluebook.policies.each do |policy|
-            next unless policy.fans_out? && policy.event_name == event.name
-            next unless policy.event_qualifier.nil? || policy.event_qualifier == emitting
-
-            findings << fan_out_finding(runtime, snapshot, policy, event, domain, reactions_since)
-          end
-        end
-      end
-
-      # Builds one fan-out finding, comparing one `for_each` policy's independently
-      # recomputed expected rows against what actually reacted for one event.
-      #
-      # @param runtime [Runtime::Dispatcher, Runtime::RemoteDispatcher] the booted runtime
-      # @param snapshot [Hash{Array(String, String) => Hash}] the pre-dispatch `for_each`
-      #   query snapshot, keyed by `[query_domain, aggregate_name]`
-      # @param policy [Bluebook::Policy] the fanning-out policy this event could trigger
-      # @param event [Runtime::Event] the announced event being checked
-      # @param domain [String] the emitting event's own domain name
-      # @param reactions_since [Array<Hash>] the reaction-log rows this step's own
-      #   dispatch appended
-      # @return [Hash{Symbol => Object}] `{policy: String, on: String,
-      #   expected_row_ids: Array<String>, nil, actual_row_ids: Array}`
-      def fan_out_finding(runtime, snapshot, policy, event, domain, reactions_since)
-        payload = event.payload.transform_keys(&:to_sym)
-        held = policy.where.to_s.empty? ||
-               Bluebook::Expression::Evaluator.call(policy.where, {}, payload)
-
-        expected = held ? expected_fan_out_rows(runtime, snapshot, policy, domain, payload) : nil
-
-        actual = reactions_since.select { |r| r[:policy] == policy.name && r[:on] == event.name }
-                                .filter_map { |r| r[:for_row] }
-
-        { policy: policy.name, on: event.name, expected_row_ids: expected, actual_row_ids: actual }
-      end
-
-      # The independent recomputation — `policy.for_each`'s declared query,
-      # answered against the pre-dispatch snapshot (see the snapshot's
-      # own comment at its capture site: the real fan-out's query runs
-      # synchronously, before its own dispatched commands can mutate
-      # anything the query would have matched, so this has to read the
-      # same "before" state or it grades the wrong moment). Comparators
-      # are `Ports::Query::InMemory.holds?`, never `QueryInterpreter` —
-      # sharing that call would make this oracle blind to exactly the
-      # code the fan-out feature adds. A `Symbol` where-value binds to
-      # the triggering event's own payload (the same binding
-      # `OpenForCustomer`'s `customer_id: :customer_id` relies on); a
-      # literal is compared as declared.
-      #
-      # @param runtime [Runtime::Dispatcher, Runtime::RemoteDispatcher] the booted runtime
-      #   to resolve the target query against
-      # @param snapshot [Hash{Array(String, String) => Hash}] the pre-dispatch `for_each`
-      #   query snapshot, keyed by `[query_domain, aggregate_name]`
-      # @param policy [Bluebook::Policy] the fanning-out policy whose `for_each` route
-      #   names the target query
-      # @param domain [String] the emitting event's own domain name, resolved through
-      #   `policy.for_each_route`
-      # @param payload [Hash] the triggering event's own payload, symbol-keyed; binds any
-      #   `Symbol` where-value
-      # @return [Array<String>] matching row ids, as strings, sorted; `[]` if the target
-      #   query cannot be resolved
-      def expected_fan_out_rows(runtime, snapshot, policy, domain, payload)
-        query_domain, aggregate_name, query_name = policy.for_each_route(domain)
-        aggregate = runtime.registry.bluebook(query_domain)&.aggregate(aggregate_name)
-        query = aggregate&.query(query_name)
-        return [] unless query
-
-        rows = snapshot[[query_domain, aggregate_name]] || {}
-        matched = rows.select do |_id, state|
-          query.wheres.all? do |clause|
-            held = Ports::Query::InMemory.comparable(QuerySpecification::FieldPath.dig(state, clause.field))
-            Ports::Query::InMemory.holds?(clause, held, payload)
-          end
-        end
-
-        matched.keys.map(&:to_s).sort
-      end
-
-      # Names the outcome class a recorded refusal row should carry.
-      #
-      # The outcome class a recorded refusal row names (C8.2/C8.3,
-      # docs/semantics/bluebook-semantics.md): a domain refusal is its own
-      # class; an evaluation fault — the language refusing to interpret a
-      # broken rule or input — is `"Fault"`, the same word the Rust kernel
-      # emits (`Refusal::Fault`), never a refusal class and never a raw
-      # Ruby exception name.
-      #
-      # @param error [StandardError] the raised error a step's refusal was rescued as
-      # @return [String] `"Fault"` for an evaluation fault, otherwise `error`'s own class name
-      def refusal_kind(error)
-        error.is_a?(Bluebook::Expression::EvaluationError) ? "Fault" : error.class.name
-      end
-
-      # Answers one ad hoc filter step for real — the mirror image of
-      # kernel/cli.rs's own `run_filter`, deliberately calling the exact
-      # same production module that method's Rust port stands in for
-      # (`Ports::Query::InMemory`, lib/hecks/ports/query/in_memory.rb)
-      # rather than re-deriving comparator behavior by hand. `field` walks
-      # through `QuerySpecification::FieldPath.dig` (the same reading a
-      # declared where-clause gets), `comparable`/`holds?` are the same
-      # two calls `InMemory.execute` itself makes per candidate record —
-      # this is that method's own filter/select step, inlined, because
-      # there is no declared `Query` object here to hand `execute` (an ad
-      # hoc filter has no `order_by`/`limit`/`offset` at all, so nothing
-      # about `execute`'s own ordering/paging logic even applies).
-      # Sorted by id ascending regardless — `Ports::Query::Ordering`'s own
-      # header explains why an ask with no declared order still needs
-      # this tier ("the identity tier is what makes an ask total").
-      #
-      # @param runtime [Runtime::Dispatcher, Runtime::RemoteDispatcher] the booted runtime
-      #   to filter against
-      # @param filter [Hash] the ad hoc filter step's own Hash value: String-keyed
-      #   `"aggregate"`, `"field"`, `"op"`, `"value"`
-      # @return [Array<Hash>] matching records, sorted by id ascending, each `{id:}`
-      #   merged with the record's own state
-      # @raise [Bluebook::Expression::EvaluationError] if `op` names no known comparator,
-      #   or `"aggregate"` names no loaded aggregate
-      def run_filter(runtime, filter)
-        aggregate_ref = filter["aggregate"].to_s
-        field         = filter["field"].to_s
-        op            = filter["op"].to_s
-        value         = filter["value"]
-
-        # A malformed ad-hoc ask is a fault (C8.3), not a bare RuntimeError.
-        unless FILTER_COMPARATORS.include?(op)
-          raise Bluebook::Expression::EvaluationError, "unknown query comparator #{op.inspect}"
-        end
-
-        domain_name, aggregate_name = aggregate_ref.split("::", 2)
-        aggregate = runtime.registry.bluebook(domain_name)&.aggregate(aggregate_name)
-        raise Bluebook::Expression::EvaluationError, "unknown aggregate #{aggregate_ref.inspect}" unless aggregate
-
-        clause  = QuerySpecification::Common::WhereClause.new(field: field, op: op, value: value)
-        records = runtime.registry.repository(domain_name, aggregate).all
-        matched = records.select do |record|
-          held = Ports::Query::InMemory.comparable(QuerySpecification::FieldPath.dig(record, field))
-          Ports::Query::InMemory.holds?(clause, held, {})
-        end
-
-        matched.sort_by { |record| record.id.to_s }.map { |record| { id: record.id }.merge(record.state) }
-      end
-
-      # Builds the `refusals` entry's own "verb" column for a refused ad hoc filter.
-      #
-      # There is no real verb to report (a filter step carries none), so this
-      # builds the same descriptive label kernel/cli.rs's own `filter_label`
-      # builds from the same three raw fields, tolerant of any of them being
-      # missing (Ruby's own nil-to-"" interpolation) the same way that Rust
-      # port is.
-      #
-      # @param filter [Hash] the ad hoc filter step's own Hash value, read for
-      #   `"aggregate"`, `"field"`, `"op"`
-      # @return [String] a descriptive label such as `"filter Banking::Account.status eq"`
-      def filter_label(filter) = "filter #{filter['aggregate']}.#{filter['field']} #{filter['op']}"
-    end
-  end
-end