hecks 1.3.0 → 1.5.0

data/lib/hecks/fuzzing/properties/lifecycle_and_replay.rb

@@ -1,3 +1,5 @@
+require_relative "../nondeterministic"
+
 module Hecks
   module Fuzzing
     module Properties
@@ -12,14 +14,18 @@ module Hecks
       # trustworthy in the first place.
       module LifecycleAndReplay
         # Every lifecycle field a replay leaves an instance holding is one
-        # of the aggregate's OWN declared states — the full set, not just
+        # of the aggregate's own declared states — the full set, not just
         # `Lifecycle#states`' default+targets (see ModelCheck.full_states'
         # own comment on that hole). The tie to M2 is direct: the model
-        # checker proves which states a domain's OWN declarations can ever
-        # produce ; this proves a REAL RUN never produced anything else —
+        # checker proves which states a domain's own declarations can ever
+        # produce ; this proves a real run never produced anything else —
         # a coercion bug, a stale string surviving a rename, a default
         # that drifted from the declared set, would all show up here as a
         # value nothing upstream would have predicted.
+        #
+        # @param history [Hash] a replayed history, as returned by `Fuzzing::Replay.call`
+        # @return [true, String] true if every instance's lifecycle field holds a declared
+        #   state; otherwise a semicolon-joined message naming each offending instance
         def lifecycle_values_are_declared(history)
           bluebook = history.fetch(:bluebook)
           declared = {}
@@ -44,14 +50,19 @@ module Hecks
         end
 
         # Every saga advance a replay actually logged moved along an edge
-        # the process manager DECLARED — `(from, to)` pairs that appear in
+        # the process manager declared — `(from, to)` pairs that appear in
         # `saga_log` with `advanced: true` must be a `(handler.from_state,
         # handler.to_state)` pair some handler on that PM declares
-        # (compensation edges included ; a REFUSED-triggered advance is a
+        # (compensation edges included ; a refused-triggered advance is a
         # handler like any other). A saga that advanced along a pair no
         # handler names would mean the runtime moved state the language
         # never authorized — the same trust ModelCheck's static reachability
         # rests on, checked here against what a run actually did.
+        #
+        # @param history [Hash] a replayed history as returned by `Replay.call`
+        # @return [true, String] true if every logged advance matches a declared
+        #   handler edge; otherwise a message naming the process manager and pair
+        #   that does not
         def saga_advances_follow_declared_handlers(history)
           bluebook = history.fetch(:bluebook)
           edges = Hash.new { |h, k| h[k] = [] }
@@ -72,56 +83,50 @@ module Hecks
           offenders.empty? || offenders.join("; ")
         end
 
-        # THE FOUNDATIONAL ONE. `Hecks::Runtime` mints nothing — every
+        # The foundational one. `Hecks::Runtime` mints nothing — every
         # identity is declared and derived, never invented (see
-        # command_interpreter.rb's own "NOTHING IS MINTED" — a random hex,
+        # command_interpreter.rb's own "nothing is minted" — a random hex,
         # a counter, anything not reproducible from the payload, was
         # refused out of the runtime specifically because it broke this).
-        # So the SAME steps, replayed against a FRESH boot, must produce
-        # BYTE-IDENTICAL events, refusals, and instances — any drift here
+        # So the same steps, replayed against a fresh boot, must produce
+        # byte-identical events, refusals, and instances — any drift here
         # is nondeterminism the runtime promised not to have: a wall-clock
         # read that leaked into compared state, a Hash iteration order a
         # comparison depended on, anything. Two independent replays, not a
-        # cached one compared to itself, so a bug that corrupts the FIRST
+        # cached one compared to itself, so a bug that corrupts the first
         # run's own bookkeeping cannot pass by agreeing with itself.
+        #
+        # @param domain_path [String] path to the domain directory to boot, such as
+        #   `"examples/pizzas"`
+        # @param steps [Array<Hash>] the step list to replay twice
+        # @param adapter [Symbol] persistence adapter to boot with (`:memory`,
+        #   `:postgres`, or `:postgres_era`)
+        # @return [true, String] true if both replays produce identical histories
+        #   (after stripping declared nondeterministic fields); otherwise a message
+        #   naming the step count that diverged
         def replay_is_deterministic(domain_path, steps, adapter: :memory)
           first  = Replay.call(domain_path, steps, adapter: adapter)
           second = Replay.call(domain_path, steps, adapter: adapter)
 
-          # `:event_uid`/`:delivery_id` — `Runtime::Outbox::Fanout#rows_for`'s
-          # OWN `SecureRandom.uuid`, minted fresh per enqueue specifically so
-          # it stays OFF `Event#to_h` (that file's own comment: the domain's
-          # own events stay mintless; this is Ruby-only relay bookkeeping,
-          # never part of what a replay claims the DOMAIN produced) — so two
-          # otherwise-identical replays legitimately carry two different
-          # uuids here, the same reason `:bluebook`/`:bluebooks` (live
-          # object identities, not values) are excluded below.
-          #
-          # `row[:event][:occurred_at]` — the outbox row's own `event:` field
-          # is `Outbox.serialize_event`'s `event.to_h.merge(correlation:...)`,
-          # the FULL `Event#to_h`, unlike `history[:events]` (this file's own
-          # `events = runtime.events.map { {name:, aggregate:, id:, payload:}
-          # }`, above) which has ALWAYS deliberately left `occurred_at` OFF
-          # the compared surface for exactly this reason: a wall-clock read,
-          # never reproducible byte-for-byte between two independent
-          # replaying processes a second apart. Stripped here the same way,
-          # for the one place it newly reappears.
-          #
-          # Both stripped from each `outbox_traces` row before comparing
-          # rather than dropping `outbox_traces` wholesale: everything else
-          # on a row (status, consumer, kind, the event's own name/
-          # aggregate/id/payload) IS reproducible from the steps alone and
+          # What leaves this comparison, and why, is declared once in
+          # `Nondeterministic::FIELDS`: the `outbox_row` group (per-enqueue
+          # uuids), the `event` group on each row's full `Event#to_h`
+          # (`occurred_at`, which `history[:events]` never carried), and the
+          # `history` group (live IR objects). Stripped per `outbox_traces`
+          # row rather than dropping `outbox_traces` wholesale: everything
+          # else on a row (status, consumer, kind, the event's own name/
+          # aggregate/id/payload) is reproducible from the steps alone and
           # stays checked.
           strip_outbox_nondeterminism = lambda do |history|
             traces = Array(history[:outbox_traces]).map do |trace|
               trace.merge(rows: trace[:rows].map do |row|
-                row.except(:event_uid, :delivery_id).merge(event: row[:event].except(:occurred_at))
+                Nondeterministic.strip(row, :outbox_row).merge(event: Nondeterministic.strip(row[:event], :event))
               end)
             end
             history.merge(outbox_traces: traces)
           end
 
-          comparable = ->(history) { strip_outbox_nondeterminism.call(history).except(:bluebook, :bluebooks) }
+          comparable = ->(history) { Nondeterministic.strip(strip_outbox_nondeterminism.call(history), :history) }
           return true if comparable.call(first) == comparable.call(second)
 
           "two replays of the same #{steps.length} steps produced different histories"

data/lib/hecks/fuzzing/properties/outbox.rb

@@ -3,65 +3,73 @@ require_relative "../../bluebook/expression/evaluator"
 module Hecks
   module Fuzzing
     module Properties
-      # THE TRANSACTIONAL OUTBOX'S OWN CONTRACT (`Runtime::Outbox`, that
+      # The transactional outbox's own contract (`Runtime::Outbox`, that
       # file's own header), held to the history a replay actually produced
       # rather than trusted. Two facts, each independently checkable from
       # `history[:outbox_traces]` (`Replay#call`'s own before/after
       # capture, one entry per step whose dispatch enqueued at least one
       # row):
       #
-      #   1. "DELIVERY IS INLINE BY DEFAULT" — a row THIS replay's own
+      # ## The two checks
+      #
+      #   1. "delivery is inline by default" — a row this replay's own
       #      dispatch enqueued must not still be `pending`/`claimed` once
-      #      that SAME call returns (nothing here ever simulates a
+      #      that same call returns (nothing here ever simulates a
       #      crash), and must not be `failed` either — `deliver_row`'s
       #      own rescue only reaches `failed` for a genuine defect in the
-      #      RELAY's own consumer resolution (a row naming a policy/
+      #      relay's own consumer resolution (a row naming a policy/
       #      process_manager `run_consumer`'s own independent registry
       #      lookup cannot find — `WiringError`), never an ordinary
       #      domain refusal (`PolicyInterpreter#deliver`/`SagaInterpreter#
-      #      advance` both rescue those THEMSELVES, recording `delivered:
+      #      advance` both rescue those themselves, recording `delivered:
       #      false` on the reaction/saga log and letting `run_consumer`
       #      return normally). Both checked for every row, `saga:` and
       #      `policy:` alike.
       #
-      #   2. A `policy:` ROW SPECIFICALLY — `PolicyInterpreter#deliver`
+      #   2. A `policy:` row specifically — `PolicyInterpreter#deliver`
       #      returns `nil` (no `reaction_log` entry appended at all)
-      #      EXACTLY when its own `where` (or, for a fan-out policy, the
-      #      SAME `where`, gating the whole `for_each`) does not hold;
-      #      every OTHER outcome (delivered, refused, a defect,
+      #      exactly when its own `where` (or, for a fan-out policy, the
+      #      same `where`, gating the whole `for_each`) does not hold;
+      #      every other outcome (delivered, refused, a defect,
       #      reaction-depth-reached) is still a non-nil record `#react`
-      #      appends. So a `delivered` policy row with NO matching
-      #      `reaction_log` entry is legitimate ONLY when that policy's
-      #      own `where`, independently RE-EVALUATED here against the
+      #      appends. So a `delivered` policy row with no matching
+      #      `reaction_log` entry is legitimate only when that policy's
+      #      own `where`, independently re-evaluated here against the
       #      row's own recorded event, genuinely does not hold. A
-      #      `for_each` policy's own fan-out correctness (how MANY rows
+      #      `for_each` policy's own fan-out correctness (how many rows
       #      it should have dispatched to) is `fanout_dispatches_once_
       #      per_matching_row`'s job, not this one's.
       #
-      # A `saga:` ROW HAS NO EQUIVALENT SECOND CHECK, DELIBERATELY — this
-      # was the first shape this property shipped with, and it was WRONG,
-      # caught live against `examples/banking` before this comment
-      # existed: `Fanout.sagas`' own `listens?` (starts_on/ends_on/
-      # handler_for matching the event NAME alone) says nothing about
-      # whether a CORRELATION resolves or a LIVE INSTANCE exists, and
+      # ## Why a `saga:` row is exempt from check 2
+      #
+      # Deliberately: `Fanout.sagas`' own `listens?` (starts_on/ends_on/
+      # handler_for matching the event name alone) says nothing about
+      # whether a correlation resolves or a live instance exists, and
       # `begin_saga`/`end_saga` (saga_interpreter.rb) both have silent,
-      # perfectly ordinary no-op paths that append NOTHING to `saga_log`
+      # perfectly ordinary no-op paths that append nothing to `saga_log`
       # — `begin_saga` when an instance under that correlation already
-      # exists, `end_saga` when NO live instance exists to end (an
+      # exists, `end_saga` when no live instance exists to end (an
       # `AccountOpened` fired by opening an account directly, bypassing
       # the onboarding flow whose `ends_on` names that same event,
       # reproduces this exactly: `Fanout.listens?` enqueues the row
-      # because the event NAME matches `ends_on`, `end_saga` finds
+      # because the event name matches `ends_on`, `end_saga` finds
       # nothing under that correlation to delete, and neither logs a
       # word). A `saga:` row draining to `delivered` with zero matching
-      # `saga_log` entries is therefore NOT a finding — only check 1
+      # `saga_log` entries is therefore not a finding — only check 1
       # applies to it.
       #
-      # NOT A GRAMMAR CONSTRUCT — `FEATURE_COVERAGE`'s own `dry_runs_
-      # leave_no_trace` precedent: the outbox is a runtime door
-      # (`Runtime::Outbox`), not a word a bluebook declares, so there is
-      # no feature string here to claim.
+      # ## Not a grammar construct
+      #
+      # `FEATURE_COVERAGE`'s own `dry_runs_leave_no_trace` precedent: the
+      # outbox is a runtime door (`Runtime::Outbox`), not a word a
+      # bluebook declares, so there is no feature string here to claim.
       module Outbox
+        # Checks every outbox row a replay's history recorded against the
+        # outbox's own contract (see this file's own header).
+        #
+        # @param history [Hash] a replayed history, as returned by `Fuzzing::Replay.call`
+        # @return [true, String] true if every outbox row satisfies the contract; otherwise
+        #   a semicolon-joined message naming each offending row
         def outbox_rows_match_reactions(history)
           bluebooks = history.fetch(:bluebooks, {})
 
@@ -72,6 +80,17 @@ module Hecks
           offenders.empty? || offenders.join("; ")
         end
 
+        # Checks one outbox row against the outbox's own contract.
+        #
+        # @param row [Hash] one `Runtime::Outbox::Row#to_h` entry, `trace[:rows]`'s shape:
+        #   at least `:status`, `:delivery_id`, `:consumer`, `:event`, and (when failed)
+        #   `:error`
+        # @param trace [Hash] this row's outbox trace entry, one of `history[:outbox_traces]`,
+        #   carrying `:rows` and `:reactions`
+        # @param bluebooks [Hash{String => Bluebook::Chapter}] every loaded domain,
+        #   keyed by domain name
+        # @return [Array<String>] zero or one offending message naming what this row got
+        #   wrong; empty when the row is fine or its status names no check
         def outbox_row_offenders(row, trace, bluebooks)
           on = row.dig(:event, :name)
 
@@ -90,9 +109,20 @@ module Hecks
           end
         end
 
+        # Checks one delivered `policy:` outbox row for a missing `reaction_log` entry.
+        #
         # See this file's own header for why a `saga:` row is exempt: its
         # own `listens?` gives no such guarantee, unlike a policy's single,
         # deterministic `where` gate.
+        #
+        # @param row [Hash] the delivered outbox row being checked
+        # @param on [String] the row's event name, `row.dig(:event, :name)`
+        # @param trace [Hash] this row's outbox trace entry, carrying `:reactions`
+        # @param bluebooks [Hash{String => Bluebook::Chapter}] every loaded domain,
+        #   keyed by domain name
+        # @return [Array<String>] zero or one offending message; empty when the row is
+        #   not a policy row, the policy is undeclared or fans out, or the policy's
+        #   `where` does not independently re-evaluate true
         def outbox_delivered_policy_offenders(row, on, trace, bluebooks)
           kind, fqn = row[:consumer].to_s.split(":", 2)
           return [] unless kind == "policy"
@@ -101,11 +131,14 @@ module Hecks
           return [] if trace[:reactions].any? { |entry| entry[:policy] == name && entry[:on] == on }
 
           policy = bluebooks[home]&.policies&.find { |candidate| candidate.name == name }
-          return [] unless policy # nothing declared under this name — inconclusive, not a claimed mismatch
-          return [] if policy.fans_out? # fan-out row count is fanout_dispatches_once_per_matching_row's job
+          # Nothing declared under this name — inconclusive, not a claimed mismatch.
+          return [] unless policy
+          # Fan-out row count is fanout_dispatches_once_per_matching_row's job.
+          return [] if policy.fans_out?
 
           held = independently_re_evaluate_policy_where(policy, row[:event])
-          return [] if held != true # false, or inconclusive (the where itself raised) — never a claimed mismatch
+          # False, or inconclusive (the where itself raised) — never a claimed mismatch.
+          return [] if held != true
 
           ["outbox row #{row[:delivery_id]} (#{row[:consumer]} on #{on}) drained as delivered, but no matching " \
            "reaction_log entry exists and the policy's own where clause independently re-evaluates true — " \
@@ -117,17 +150,22 @@ module Hecks
         # with itself (the same rule `resolve_dispatch_binding`'s own
         # comment states). `Evaluator.call` (the raw-string entry, parsed
         # and cached — never `call_rule`, which needs the policy's own
-        # BUILD-TIME `where_rule` AST, an object this history has no
+        # build-time `where_rule` AST, an object this history has no
         # reason to carry) is the exact same call `Replay#fan_out_finding`
         # already makes for the identical fact one property over
         # (`policy.where.to_s.empty? || Evaluator.call(policy.where, {},
         # payload)`), reused rather than re-derived a second, slightly
         # different way. `rescue`d to `nil`, not `false`: a where clause
         # that cannot be re-evaluated from the row's own recorded payload
-        # alone is INCONCLUSIVE, not proof either way — the same "never a
+        # alone is inconclusive, not proof either way — the same "never a
         # claimed pass or a claimed mismatch from a resolution this replay
         # cannot actually reproduce" discipline `build_guard_check`'s own
         # rescue clause already follows.
+        #
+        # @param policy [Bluebook::Policy] the policy whose `where` clause is re-evaluated
+        # @param event [Hash] the outbox row's own recorded event, read for `:payload`
+        # @return [Boolean, nil] whether `policy`'s `where` holds against `event`'s payload,
+        #   or nil if the where clause cannot be re-evaluated from it
         def independently_re_evaluate_policy_where(policy, event)
           return true if policy.where.to_s.empty?
 

data/lib/hecks/fuzzing/properties/querying.rb

@@ -10,7 +10,7 @@ module Hecks
       # (#query_for_verb, #query_eligible_rows, #resolve_hop_clause) other
       # property modules in this directory also call.
       module Querying
-        # THE QUERY ORACLE — differential testing within the one runtime,
+        # The query oracle — differential testing within the one runtime,
         # the shape the retired cross-runtime harness should always have
         # been. Every generated ask was answered twice at the same instant
         # (Replay records both): once through whatever the aggregate is
@@ -18,23 +18,27 @@ module Hecks
         # a SQL binding would compile it), once through the reference
         # interpreter's own evaluation. The two are separate, live
         # implementations of the same comparator vocabulary, and they have
-        # drifted before — an adapter that ACCEPTS what the reference says
+        # drifted before — an adapter that accepts what the reference says
         # matches nothing, or orders what it refuses to order, shows up
         # here as a finding no self-referential adapter spec could see.
-        # M23 — `Replay` now runs the native and reference engines
-        # INDEPENDENTLY (each in its own begin/rescue — see that file's own
-        # comment at the capture site), so this property can tell apart what
-        # used to be indistinguishable: "both engines refused" (fine — the
-        # ask was genuinely bad, nothing to compare) from "one refused and
-        # the other did not" (a real divergence — the two engines disagree
-        # about whether the ask was even VALID, never mind what it answers).
-        # `native_refused`/`reference_refused` are read by KEY PRESENCE, not
-        # truthiness — `Replay` only ever adds `:error`/`:reference_error`
-        # to an entry when that side actually raised, so an absent key is an
-        # unambiguous "this side answered." A read-model ask (no reference
-        # twin attempted at all, `asked[:query]` without "::") is skipped
-        # entirely, same as always — there is no second engine to disagree
-        # with.
+        # M23 — `Replay` runs the native and reference engines independently
+        # (each in its own begin/rescue — see that file's own comment at the
+        # capture site), so this property can tell apart "both engines
+        # refused" (fine — the ask was genuinely bad, nothing to compare)
+        # from "one refused and the other did not" (a real divergence — the
+        # two engines disagree about whether the ask was even valid, never
+        # mind what it answers). `native_refused`/`reference_refused` are
+        # read by key presence, not truthiness — `Replay` only ever adds
+        # `:error`/`:reference_error` to an entry when that side actually
+        # raised, so an absent key is an unambiguous "this side answered." A
+        # read-model ask (no reference twin attempted at all, `asked[:query]`
+        # without "::") is skipped entirely, same as always — there is no
+        # second engine to disagree with.
+        #
+        # @param history [Hash] a replayed history as returned by `Replay.call`
+        # @return [true, String] true if every native/reference query answer, and every
+        #   refusal of one, agrees; otherwise a message naming the offending query, its
+        #   args, and how the two engines disagreed
         def query_answers_match_reference(history)
           offenders = history.fetch(:queries).filter_map do |asked|
             next unless asked[:query].is_a?(String) && asked[:query].include?("::")
@@ -59,16 +63,16 @@ module Hecks
           offenders.empty? || offenders.join("; ")
         end
 
-        # THE SAME "TWO ENGINES, COMPARED" SHAPE query_answers_match_reference
+        # The same "two engines, compared" shape query_answers_match_reference
         # already uses, aimed squarely at Query#options' offset/limit pair —
-        # but recomputed from history[:instances] directly, a THIRD,
+        # but recomputed from history[:instances] directly, a third,
         # independent computation, rather than comparing QueryInterpreter's
         # own native and reference paths against each other (which could
         # share the identical bug neither implementation happened to hit —
-        # see #4's own fix, which touched BOTH #interpret and
+        # see #4's own fix, which touched both #interpret and
         # #reference_interpret at once). `order_by` declared alongside
         # `offset` or `limit` names a genuinely paged query. Ports::Query::
-        # Ordering.apply is the SAME engine QueryInterpreter#ordered calls,
+        # Ordering.apply is the same engine QueryInterpreter#ordered calls,
         # reused here rather than re-derived, so this oracle cannot drift
         # from what "in order" means without the interpreter drifting the
         # identical way — only the offset-then-limit .drop/.first slice
@@ -83,6 +87,11 @@ module Hecks
         # `skipped`/`expected` across method boundaries as params/returns
         # for a sequence that's only ever computed once, in this order.
         # rubocop:disable-next Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+        #
+        # @param history [Hash] a replayed history as returned by `Replay.call`
+        # @return [true, String] true if every paged query's real answer matches an
+        #   independent order/offset/limit recomputation over its eligible rows;
+        #   otherwise a message naming the query, its args, and the two answers
         def paging_offset_partitions_correctly(history)
           bluebooks = history.fetch(:bluebooks)
 
@@ -112,13 +121,20 @@ module Hecks
           offenders.empty? || offenders.join("; ")
         end
 
-        # THE DECLARED Query ITSELF, resolved from a replayed verb — the
+        # The declared Query itself, resolved from a replayed verb — the
         # same shape #command_for_verb resolves a command by, one
         # construct over. Entity-level queries (a dotted query_path) are
         # out of scope here — paging on an entity's own list has no real
         # corpus site yet, and the "one many-side head, one aggregate,
         # no FK-join" shape #query_eligible_rows assumes doesn't hold for
         # one.
+        #
+        # @param bluebooks [Hash{String => Bluebook::Chapter}] every loaded domain,
+        #   keyed by domain name
+        # @param verb [String] the asked verb, `"Domain::Aggregate.Query"`
+        # @return [Bluebook::Query, nil] the declared query, or nil if `verb` names an
+        #   entity-level query path, or a domain, aggregate, or query not found among
+        #   `bluebooks`
         def query_for_verb(bluebooks, verb)
           domain, aggregate_name, query_path = Naming.split_verb(verb)
           return nil unless query_path && !query_path.include?(".")
@@ -128,27 +144,42 @@ module Hecks
           aggregate&.query(query_path)
         end
 
-        # A QUERY'S OWN ROWS — unlike #eligible_rows (a ReadModel's
+        # Independently recomputes which of an aggregate's own stored rows a
+        # query's `wheres` admit.
+        #
+        # A query's own rows — unlike #eligible_rows (a ReadModel's
         # reduced/grouped many-side head, possibly FK-joined against a
-        # root), a Query always asks about its OWN owning aggregate
+        # root), a Query always asks about its own owning aggregate
         # directly ; no join, no reference_target. `id:` merged in the
         # same way #eligible_rows' own rows are, since a stable sort
         # (Ordering.apply's own `identity:`) and the real answer's own
         # `record.state.merge(id: record.id)` both need it.
-        # `bluebooks:` — needed ONLY to recognise and resolve a `/` HOP
+        # `bluebooks:` — needed only to recognise and resolve a `/` hop
         # clause (`engagement/client/status`, hop_chain.bluebook's own
-        # PricedAboveViaEngagement): a hop's head names one of the OWNING
+        # PricedAboveViaEngagement): a hop's head names one of the owning
         # aggregate's declared references, and only the declaration graph
         # can say which attribute that is and which aggregate it targets.
         # A local clause never consults it. Latent gap this closed, found
         # by the fuzzer itself the first time a generated sequence ever
-        # built a full hop chain AND had its paged query answer a row
+        # built a full hop chain and had its paged query answer a row
         # (seed 1, the moment scalar_value_objects.bluebook joined the
         # fixtures corpus and shifted every seeded draw): the recompute
-        # dug `engagement/client/status` as a LOCAL dotted path, found
+        # dug `engagement/client/status` as a local dotted path, found
         # nil, and declared every genuinely-eligible row ineligible — a
         # false property violation against a correct runtime answer,
         # reproducible on an untouched main with this same 4-step script.
+        #
+        # @param instances [Hash{String => Hash}] `history[:instances]`, or an
+        #   `:instances_at` snapshot from a replayed query entry
+        # @param domain [String] the domain name the target aggregate belongs to
+        # @param aggregate_name [String] the target aggregate's own declared name
+        # @param wheres [Array<QuerySpecification::Common::WhereClause>] the clauses
+        #   every returned row must satisfy
+        # @param args [Hash] the query's own call args, for a clause whose value is a
+        #   Symbol naming one
+        # @param bluebooks [Hash{String => Bluebook::Chapter}] every loaded domain, keyed
+        #   by domain name; needed only to resolve a `/` hop clause
+        # @return [Array<Hash>] each admitted row's own state, merged with its `id:`
         def query_eligible_rows(instances, domain, aggregate_name, wheres, args, bluebooks: {})
           aggregate = bluebooks[domain]&.aggregate(aggregate_name)
           prefix = "#{domain}::#{aggregate_name}#"
@@ -166,6 +197,9 @@ module Hecks
           end
         end
 
+        # Resolves one hop of a `/`-chained clause into a local `in` clause against
+        # the target aggregate's own ids.
+        #
         # `Runtime::ReferenceHop#fold`, independently restated over the
         # replay's own `:instances_at` snapshot instead of live
         # repositories — the same shape every other recompute in this
@@ -173,13 +207,27 @@ module Hecks
         # would be checking the runtime against itself). One hop peels
         # off the head (`HopPath.next_hop`, the identical one-step
         # primitive the live fold uses), the inner clause recurses
-        # through `query_eligible_rows` against the TARGET's own
+        # through `query_eligible_rows` against the target's own
         # snapshot rows (so a multi-hop tail resolves hop by hop, exactly
         # as the live path's own recursion does), and the ids that
         # answered fold back as the same local `in` membership clause the
         # live fold builds. A clause with no `/`, or one whose head this
         # aggregate's declarations cannot resolve, passes through
         # untouched and evaluates locally as it always did.
+        #
+        # @param instances [Hash{String => Hash}] `history[:instances]`, or an
+        #   `:instances_at` snapshot from a replayed query entry
+        # @param domain [String] the domain name `aggregate` belongs to
+        # @param aggregate [Bluebook::Aggregate, nil] the aggregate `clause` is
+        #   evaluated against; nil skips hop resolution entirely
+        # @param clause [QuerySpecification::Common::WhereClause] the clause to resolve
+        # @param args [Hash] the query's own call args, passed through to the inner
+        #   hop's own `query_eligible_rows` recursion
+        # @param bluebooks [Hash{String => Bluebook::Chapter}] every loaded domain, keyed
+        #   by domain name
+        # @return [QuerySpecification::Common::WhereClause] `clause` unchanged if it has
+        #   no resolvable hop head; otherwise a local `in` clause over the matching
+        #   target ids
         def resolve_hop_clause(instances, domain, aggregate, clause, args, bluebooks)
           return clause unless aggregate && QuerySpecification::HopPath.hop_head?(clause.field, aggregate.attributes)
 
@@ -194,9 +242,15 @@ module Hecks
           QuerySpecification::Common::WhereClause.new(field: hop.attribute.name, op: "in", value: ids)
         end
 
+        # Resolves a declared limit/offset value against the query's own call args.
+        #
         # `QueryInterpreter#resolve_query_value`, reproduced: a declared
         # limit/offset is either a literal or a Symbol naming an argument
         # the caller supplied.
+        #
+        # @param value [Integer, Symbol] the declared limit/offset value
+        # @param args [Hash] the query's own call args
+        # @return [Object] `value` unchanged if not a Symbol; otherwise `args[value]`
         def resolve_paging_value(value, args)
           value.is_a?(Symbol) ? args[value] : value
         end