hecks 1.3.0 → 1.5.0

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

@@ -12,18 +12,18 @@ module Hecks
       # verb-to-declaration lookups (#command_for_verb,
       # #effective_guard_descriptions) each resolves a refusal against.
       module Guards
-        # `Query#options`' OTHER HALF — TenantScope.apply's own contract
+        # `Query#options`' other half — TenantScope.apply's own contract
         # (tenant_scope.rb), independently restated as a property rather
         # than exercised only through whatever the generator happens to
-        # try. NOT closed by the generator here on purpose: SafeDepositBox.
+        # try. Not closed by the generator here on purpose: SafeDepositBox.
         # Rented — the only real corpus query declaring `authorize` at
-        # all — declares ZERO attributes of its own, so StepBuilder#args_for
+        # all — declares zero attributes of its own, so StepBuilder#args_for
         # always hands it `{}` and TenantScope.apply refuses every
         # generated attempt, unconditionally (confirmed: no successful ask
         # against an authorize-bearing query reaches this property via the
         # standard battery today). Extending the generator to invent a
         # `tenant:` value ran into a separate, real finding along the way —
-        # SafeDepositBox is COMPOSITE-identified (`identified_by` is nil
+        # SafeDepositBox is composite-identified (`identified_by` is nil
         # for it — Runtime::Identified#derive_identity), so the generator's
         # existing `known_ids` pool (keyed by `aggregate.identified_by ||
         # "id"`) tracks a stray, never-real scalar for it rather than its
@@ -37,10 +37,10 @@ module Hecks
         # where a `tenant:` arg came from.
         #
         # Two claims, matching TenantScope.apply's own two branches: every
-        # SUCCESSFUL answer's own tenant field agrees with the tenant arg
+        # successful answer's own tenant field agrees with the tenant arg
         # given (the WhereClause TenantScope injects is a Symbol reference
-        # into args, resolved dynamically — this checks the OUTCOME, not
-        # re-deriving that resolution) ; every ask MISSING a required
+        # into args, resolved dynamically — this checks the outcome, not
+        # re-deriving that resolution) ; every ask missing a required
         # tenant: refuses with the declared wording, never succeeds. A
         # refusal for an unrelated reason with the tenant arg present is
         # not this property's claim either way — skipped, not graded.
@@ -54,6 +54,11 @@ module Hecks
         # branches shares logic with the others beyond that shared setup.
         # rubocop:disable-next Metrics/CyclomaticComplexity
         # rubocop:disable-next Metrics/PerceivedComplexity
+        #
+        # @param history [Hash] a replayed history as returned by `Replay.call`
+        # @return [true, String] true if every tenant-scoped query answer, and every
+        #   refusal of one, agrees with `TenantScope.apply`'s own contract; otherwise a
+        #   message naming the offending query, its args, and what it should have done
         def authorize_scopes_or_refuses(history)
           bluebooks = history.fetch(:bluebooks)
 
@@ -92,14 +97,14 @@ module Hecks
           offenders.empty? || offenders.join("; ")
         end
 
-        # EVERY GIVEN/ENSURES REFUSAL A RUN ACTUALLY RAISED NAMES A RULE
-        # THE COMMAND ACTUALLY DECLARES. `GivenNotMet`/`EnsuresNotMet` both
+        # Every given/ensures refusal a run actually raised names a rule
+        # the command actually declares. `GivenNotMet`/`EnsuresNotMet` both
         # quote their guard's own `description` verbatim
         # (command_rules/admissibility.rb: `"#{command.hecks_name} refused
-        # — #{given.description}"`) — the SAME text `behavior.bluebook`'s
+        # — #{given.description}"`) — the same text `behavior.bluebook`'s
         # own `Rule`/Command.Ensure hold as `Rule#description`, so a
         # refusal whose quoted text is not among the refusing command's
-        # OWN `guard_descriptions` (Behaviour::Command, both givens and
+        # own `guard_descriptions` (Behaviour::Command, both givens and
         # ensures) is either a stale message surviving a renamed rule, a
         # rule firing against the wrong command's own guard set, or the
         # wording drifting out from under the declaration it is supposed
@@ -107,7 +112,7 @@ module Hecks
         # guards, some through a cross-aggregate dereference) are exactly
         # the surface this exists to hold to its word.
         #
-        # `kind:` is what tells a guard refusal apart from the FOUR other
+        # `kind:` is what tells a guard refusal apart from the four other
         # `RefusalWording` templates sharing the identical "X refused — Y"
         # shape (LifecycleRefused/transition_blocked, both TypeMismatch
         # object-reference templates, Unauthorized/role_mismatch) — see
@@ -116,6 +121,14 @@ module Hecks
         # those; the raised class does not.
         GUARD_REFUSAL_KINDS = %w[Hecks::Runtime::GivenNotMet Hecks::Runtime::EnsuresNotMet].freeze
 
+        # Checks that every given/ensures refusal a run actually raised names a rule
+        # the refusing command actually declares.
+        #
+        # @param history [Hash] a replayed history as returned by `Replay.call`
+        # @return [true, String] true if every guard refusal's quoted description matches
+        #   a `given`/`ensures` the refusing command (or its delegation target) declares;
+        #   otherwise a message naming the refusal and the declared descriptions it does
+        #   not match
         def guard_refusals_are_declared(history)
           bluebooks = history.fetch(:bluebooks)
 
@@ -138,27 +151,27 @@ module Hecks
           offenders.empty? || offenders.join("; ")
         end
 
-        # ANGLE-8's OWN WRITE-SIDE HALF. `authorize_scopes_or_refuses`
+        # Angle-8's own write-side half. `authorize_scopes_or_refuses`
         # (above) enforces `TenantScope.apply`'s boundary, and that
-        # boundary exists ONLY for queries/read models — `authorize
+        # boundary exists only for queries/read models — `authorize
         # policy, tenant: field` is a word `QuerySpecification::Common::
         # DSL#authorize_impl` grants to `QueryBuilder`/`ReadModelBuilder`
         # alone; `CommandBuilder` never includes that module, so no
         # bluebook can declare it on a command at all (confirmed by
-        # reading the grammar directly, not inferred). A WRITE that
+        # reading the grammar directly, not inferred). A write that
         # carries a `reference_to` from one tenant-scoped record into
-        # another's is checked by NOTHING at dispatch time: `TenantScope`
+        # another's is checked by nothing at dispatch time: `TenantScope`
         # never runs for a command, and no runtime `given`/`ensures`
         # anywhere in this corpus reads a cross-aggregate tenant field
         # either. `qa/stress_domains/tenant_ledger` exists to give this
         # property a real place to fire.
         #
-        # THE RULE: an aggregate's own declared TENANT FIELD is whichever
-        # field one of ITS OWN queries names in `authorize policy, tenant:
+        # The rule: an aggregate's own declared tenant field is whichever
+        # field one of its own queries names in `authorize policy, tenant:
         # :field` — the exact same declaration `authorize_scopes_or_
         # refuses` reads off a query above, reused here to name a field
-        # on the AGGREGATE ITSELF that stores the tenant it belongs to.
-        # For every STORED record (`history[:instances]` — a refused
+        # on the aggregate itself that stores the tenant it belongs to.
+        # For every stored record (`history[:instances]` — a refused
         # dispatch never writes one, so "a refusal is correct behaviour,
         # not a finding" holds by construction, the same way `history
         # [:instances]` already guarantees this for `stored_records_
@@ -166,30 +179,36 @@ module Hecks
         # tenant field, walk every `reference_to`-typed attribute it
         # carries (`Bluebook::Reference` — "a reference IS the id",
         # value/coercion.rb's own header, so the stored value is always a
-        # plain id, never a nested payload) pointing at ANOTHER aggregate
-        # that ALSO declares a tenant field: if the referenced record's
+        # plain id, never a nested payload) pointing at another aggregate
+        # that also declares a tenant field: if the referenced record's
         # own tenant value disagrees with the referencing record's own
         # tenant value, the write crossed a tenant boundary and nothing
         # refused it — a finding.
         #
-        # A DANGLING/UNRESOLVABLE REFERENCE IS SKIPPED — a different,
+        # A dangling/unresolvable reference is skipped — a different,
         # existence-shaped property's claim, not this one's (the same
         # "inconclusive, not a claimed pass" restraint `lifecycle_guard_
         # and_given_violations_are_refused` already documents for a
         # differently-shaped case). Comparison goes through `Ports::
-        # Query::InMemory.comparable` (the SAME normalization `authorize_
+        # Query::InMemory.comparable` (the same normalization `authorize_
         # scopes_or_refuses` already applies to a query row's own tenant
         # field, just above) rather than `Runtime::Value#==` directly —
-        # two single-attribute value objects with the SAME scalar but
-        # DIFFERENT declared names (`LedgerRegion`/`TransferRegion`, this
+        # two single-attribute value objects with the same scalar but
+        # different declared names (`LedgerRegion`/`TransferRegion`, this
         # domain's own pair — a value object is always declared inside
         # the aggregate that owns it, so two independently tenant-scoped
-        # aggregates can never share one) compare UNEQUAL under `Value#==`
+        # aggregates can never share one) compare unequal under `Value#==`
         # (`type_name` is part of that equality) despite meaning the
         # identical tenant, which would make every same-tenant write a
         # false positive.
         # rubocop:disable-next Metrics/CyclomaticComplexity
         # rubocop:disable-next Metrics/PerceivedComplexity
+        #
+        # @param history [Hash] a replayed history as returned by `Replay.call`
+        # @return [true, String] true if every stored record's `reference_to` attribute
+        #   points at a record sharing the same tenant value (or has no resolvable
+        #   target, or neither side declares a tenant field); otherwise a message naming
+        #   the referencing record, the reference, and the tenant mismatch
         def commands_respect_tenant_scope(history)
           bluebooks = history.fetch(:bluebooks)
           instances = history.fetch(:instances)
@@ -230,27 +249,31 @@ module Hecks
           offenders.empty? || offenders.join("; ")
         end
 
-        # THE FIELD AN AGGREGATE'S OWN QUERY NAMES AS TENANT-SCOPING —
+        # The field an aggregate's own query names as tenant-scoping —
         # shared by `commands_respect_tenant_scope` above for both sides
         # of a `reference_to`. `nil` for an aggregate with no `authorize
         # ..., tenant:` on any of its own queries — not every aggregate
         # is tenant-scoped, and one that isn't has nothing for this
         # property to check either side of.
+        #
+        # @param aggregate [Bluebook::Aggregate] the aggregate to look up
+        # @return [Symbol, nil] the tenant field name, or nil if no query on the
+        #   aggregate declares `authorize ..., tenant:`
         def tenant_field_for(aggregate)
           authorization = aggregate.queries.filter_map(&:authorization).find(&:tenant)
           authorization&.tenant&.to_sym
         end
 
-        # A DECLARED PROCESS MANAGER'S OWN COMMAND — `command.hecks_name`,
+        # A declared process manager's own command — `command.hecks_name`,
         # or an entity's own if the verb's second component is itself
         # dotted (`Aggregate.Entity.Command`, the same two shapes
         # `Dispatcher#dispatch` itself branches on). Shared by the guard
         # property above and available for anything else that needs to go
         # from a replayed verb back to its declaration.
         #
-        # RESOLVED AGAINST `bluebooks` (the FULL map, `history[:bluebooks]`
+        # Resolved against `bluebooks` (the full map, `history[:bluebooks]`
         # — every loaded domain, keyed by name), never a single assumed
-        # bluebook: a verb names its OWN domain (`Naming.split_verb`'s
+        # bluebook: a verb names its own domain (`Naming.split_verb`'s
         # first element), and that domain is not always the one Replay
         # happens to expose as `history[:bluebook]`. A fuzz run against
         # `lib/hecks/grammar` (Expression + Translation, in load
@@ -258,15 +281,23 @@ module Hecks
         # refusal read as "no declared command resolves that verb" purely
         # because `history[:bluebook]` was Expression, not Translation; the
         # refusal was real, this property's own domain resolution was not.
-        # A DELEGATING DOOR REFUSES WITH ITS TARGET'S OWN WORDS. `delegates_to`
+        # A delegating door refuses with its target's own words. `delegates_to`
         # (CommandBuilder#delegates_to_impl) hands the whole dispatch to one
         # entity command, and that command's given is what refuses — raised
         # back through the door, in the door's name (chess: `Game.MoveKnight
         # refused — "it is that color's turn"`, a given Knight.Move declares
         # and MoveKnight, a pure passthrough, never could). Read the door's
         # own guards first, then every delegation target's; an offence is
-        # only a description NEITHER declares. Found live mining chess's
+        # only a description neither declares. Found live mining chess's
         # history: every refused move through a door read as undeclared.
+        #
+        # @param bluebooks [Hash{String => Bluebook::Chapter}] every loaded domain,
+        #   keyed by domain name
+        # @param verb [String] the dispatched verb, `"Domain::Aggregate.Command"` or
+        #   `"Domain::Aggregate.Entity.Command"`
+        # @param command [Bluebook::Command] the command `verb` resolves to
+        # @return [Array<String>] `command`'s own declared given/ensures descriptions,
+        #   plus every `delegate`d command's, in that order
         def effective_guard_descriptions(bluebooks, verb, command)
           own = command.guard_descriptions
           delegated = command.mutations.select { |m| m.op == :delegate }.flat_map do |delegation|
@@ -277,6 +308,14 @@ module Hecks
           own + delegated
         end
 
+        # Resolves a dispatched verb back to the declared command it names.
+        #
+        # @param bluebooks [Hash{String => Bluebook::Chapter}] every loaded domain,
+        #   keyed by domain name
+        # @param verb [String] the dispatched verb, `"Domain::Aggregate.Command"` or
+        #   `"Domain::Aggregate.Entity.Command"`
+        # @return [Bluebook::Command, nil] the declared command, or nil if `verb`'s
+        #   domain, aggregate, entity, or command is not found among `bluebooks`
         def command_for_verb(bluebooks, verb)
           domain, aggregate_name, command_path = Naming.split_verb(verb)
           return nil unless command_path
@@ -296,9 +335,9 @@ module Hecks
           end
         end
 
-        # `guard_refusals_are_declared`'s OWN OPPOSITE DIRECTION. That
+        # `guard_refusals_are_declared`'s own opposite direction. That
         # property is passive and one-directional — for a refusal that
-        # ALREADY HAPPENED, is the quoted text real declared text? It says
+        # already happened, is the quoted text real declared text? It says
         # nothing about a guard that should have refused and silently did
         # not — a call site that stopped calling enforce_givens/enforce_
         # lifecycle_guard would never appear in history[:refusals] at all,
@@ -306,7 +345,7 @@ module Hecks
         #
         # This one calls Admissibility#enforce_givens (which itself folds
         # in #enforce_lifecycle_guard whenever `declaring:` is passed)
-        # DIRECTLY, against Replay's own pre-dispatch snapshot
+        # directly, against Replay's own pre-dispatch snapshot
         # (history[:guard_checks], one bounded, additive extension — see
         # that file's own comment at the capture site) — an independent
         # recomputation, not grading production against itself, the same
@@ -316,27 +355,32 @@ module Hecks
         # could mutate anything a cross-aggregate given dereferences) is
         # compared against `actual_refused` (GivenNotMet/LifecycleRefused
         # specifically — Replay's own comment on GUARD_REFUSAL_CLASSES
-        # explains why ANY other refusal class, or an outright success,
+        # explains why any other refusal class, or an outright success,
         # both count as "the guard did not fire," since enforce_givens
-        # runs FIRST in DISPATCH_ORDER).
+        # runs first in DISPATCH_ORDER).
         #
         # Aggregate#preconditions closes for free alongside this — a
         # no-block `given` reference (CommandBuilder#given) pushes the
-        # SAME Given struct object `enforce_givens` already iterates
+        # same Given struct object `enforce_givens` already iterates
         # command.givens for, so there is no separate runtime path a
         # property could exercise beyond what this already reaches.
         # Entity#preconditions closes the identical way, one level down
         # (ADR 0028) — a piece's own bare `given` reference pushes the
-        # SAME Given struct onto ITS OWN referencing command's givens,
+        # same Given struct onto its own referencing command's givens,
         # so LedgerEntry's own Amend/Reverse (banking) already exercise
         # this through the exact mechanism above, no separate path.
         #
         # Real targets: Account.Debit/CloseAccount (`from:` guards),
         # Credit/Debit (the named-once `given("customer is active")`
         # precondition) — FreezeAccount deliberately references the
-        # DIFFERENT named precondition `"customer is not closed"` instead
+        # different named precondition `"customer is not closed"` instead
         # (a suspended customer must still be freezable), so it is not a
-        # `"customer is active"` example, just the same MECHANISM.
+        # `"customer is active"` example, just the same mechanism.
+        #
+        # @param history [Hash] a replayed history as returned by `Replay.call`
+        # @return [true, String] true if every recomputed `enforce_givens`/
+        #   `enforce_lifecycle_guard` check agrees with what the real dispatch did;
+        #   otherwise a message naming the verb and the disagreement
         def lifecycle_guard_and_given_violations_are_refused(history)
           offenders = history.fetch(:guard_checks).filter_map do |check|
             next if check[:recomputed_refused] == check[:actual_refused]

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

@@ -14,11 +14,11 @@ module Hecks
       # (#check_piece_invariants, #eligible_rows, #nest_rows,
       # #recompute_median) each leans on.
       module InvariantsAndAggregation
-        # EVERY STORED RECORD STILL SATISFIES ITS OWN AGGREGATE'S DECLARED
-        # INVARIANTS — Admissibility#enforce_invariants (command_rules/
-        # admissibility.rb) checks these AFTER every command's mutations,
-        # BEFORE save, the same point `ensures` is checked. Nothing until
-        # now re-checked a record AFTER a whole replay finished, independent
+        # Every stored record still satisfies its own aggregate's declared
+        # invariants — Admissibility#enforce_invariants (command_rules/
+        # admissibility.rb) checks these after every command's mutations,
+        # before save, the same point `ensures` is checked. Nothing until
+        # now re-checked a record after a whole replay finished, independent
         # of whichever call site was supposed to have refused a violation
         # in the first place — a record failing its own declared invariant
         # here is proof a violating write landed anyway: the call site
@@ -27,9 +27,9 @@ module Hecks
         #
         # `history[:instances]` entries are already plain, symbol-keyed
         # state Hashes (Replay.call's own `record.state`) — called against
-        # Evaluator.call the SAME way ValueObject::Builder#build already
+        # Evaluator.call the same way ValueObject::Builder#build already
         # does for a VO's own invariants (value/coercion.rb), no GuardState
-        # wrapper needed the way enforce_invariants' own LIVE call uses one
+        # wrapper needed the way enforce_invariants' own live call uses one
         # (GuardState exists for `parent.`/projected-field dereferencing
         # mid-dispatch; a stored record's own scalar fields need none of
         # that to re-check a same-aggregate invariant against itself).
@@ -39,8 +39,8 @@ module Hecks
         #
         # Entity#invariants (round 7) closes here too, not for free —
         # `stored_records_satisfy_declared_invariants` only ever checked
-        # the AGGREGATE's own flat state; a piece's own invariant is
-        # checked against every ELEMENT of a `list_of` field, a genuinely
+        # the aggregate's own flat state; a piece's own invariant is
+        # checked against every element of a `list_of` field, a genuinely
         # different walk `check_piece_invariants` below makes,
         # independently of `Admissibility#check_entity_invariants` (the
         # live enforcement path this property exists to catch drifting
@@ -49,6 +49,11 @@ module Hecks
         #
         # Real target: SafeDepositBox's own Visit — `invariant("a written
         # note is not blank") { !note || !note.text.to_s.empty? }`.
+        #
+        # @param history [Hash] a replayed history as returned by `Replay.call`
+        # @return [true, String] true if every stored record satisfies its own
+        #   (and its own entities') declared invariants; otherwise a message
+        #   naming the record and the invariant it violates
         def stored_records_satisfy_declared_invariants(history)
           bluebooks = history.fetch(:bluebooks)
 
@@ -70,12 +75,18 @@ module Hecks
           offenders.empty? || offenders.join("; ")
         end
 
-        # A PIECE'S OWN INVARIANT, checked against every element a
-        # `list_of` field holds — the SAME lookup `Admissibility#
+        # A piece's own invariant, checked against every element a
+        # `list_of` field holds — the same lookup `Admissibility#
         # check_entity_invariants` makes (`owner.attributes.find { |a|
         # a.list? && a.type.to_s == entity.hecks_name }`), independently
-        # reapplied here against a STORED record's own plain Hash state
+        # reapplied here against a stored record's own plain Hash state
         # rather than a live `Instance`.
+        # @param owner_construct [Bluebook::Aggregate, Bluebook::Entity] the
+        #   construct whose own `list_of` entities to check
+        # @param owner_state [Hash] `owner_construct`'s own stored state
+        # @param key [String] the top-level record key, for the message
+        # @return [String, nil] a message naming the first violating piece found,
+        #   at any nesting depth; `nil` if every piece satisfies its invariants
         def check_piece_invariants(owner_construct, owner_state, key)
           owner_construct.entities.each do |entity|
             next if entity.invariants.empty?
@@ -99,29 +110,33 @@ module Hecks
           nil
         end
 
-        # A SAGA INSTANCE'S OWN CHECKPOINT SURVIVES BEING WRITTEN AND READ
-        # BACK — the durability contract `SagaInterpreter#checkpoint` makes
+        # A saga instance's own checkpoint survives being written and read
+        # back — the durability contract `SagaInterpreter#checkpoint` makes
         # (`state:` plus a `deep_copy`d `memory:`, handed to whatever
         # adapter answers `save_saga`) and `Registry#rehydrate_sagas!`
         # promises to restore on the next boot (`each_saga` yielding
         # `[pm, correlation, state, memory]` back into `saga_instances`).
-        # `Replay` captures the LIVE store already materialised the same
+        # `Replay` captures the live store already materialised the same
         # way `checkpoint` itself does (`Value.materialize`, not raw
         # `Runtime::Value`s — see its own comment); this property pushes
-        # that captured memory through the SAME `JSON.generate` then
+        # that captured memory through the same `JSON.generate` then
         # `JSON.parse(symbolize_names: true)` round-trip `checkpoint`'s own
         # `deep_copy` performs (mirrored here rather than called — a
         # private instance method with no registry to hand it) and checks
         # it comes back byte-identical. A memory holding anything that
         # round-trip cannot carry faithfully — a bare Symbol leaf, a
         # non-JSON type a future field introduces — is corruption the
-        # durable path would introduce on a REAL restart, caught here
+        # durable path would introduce on a real restart, caught here
         # without needing one.
         #
         # `declares_state?` (Behaviour::ProcessManager) is the other half:
         # a live or rehydrated instance sitting in a state the procedure
         # never declares is the saga-durability twin of
         # `lifecycle_values_are_declared` above.
+        # @param history [Hash] a replayed history as returned by `Replay.call`
+        # @return [true, String] true if every saga instance holds a declared
+        #   state and its own memory survives a checkpoint round-trip; otherwise a
+        #   message naming the process manager, correlation, and problem
         def sagas_rehydrate_cleanly(history)
           bluebook = history.fetch(:bluebook)
           process_managers = bluebook.process_managers.to_h { |pm| [pm.name, pm] }
@@ -150,11 +165,11 @@ module Hecks
           offenders.empty? || offenders.join("; ")
         end
 
-        # A `for_each` POLICY DISPATCHES EXACTLY ONCE PER ROW ITS DECLARED
-        # QUERY ANSWERS — never once for the triggering event regardless of
+        # A `for_each` policy dispatches exactly once per row its declared
+        # query answers — never once for the triggering event regardless of
         # row count, never skipping a matched row, never firing on a row a
-        # concurrent mutation only made match AFTER the fact. `Replay`
-        # computes the expected row-id set INDEPENDENTLY, at the same
+        # concurrent mutation only made match after the fact. `Replay`
+        # computes the expected row-id set independently, at the same
         # instant the real dispatch runs (`Replay.expected_fan_out_rows`,
         # the query oracle's own shape aimed at fan-out: two engines
         # compared, never one graded against itself), and records it
@@ -163,6 +178,10 @@ module Hecks
         # dispatch is the claim then, not "dispatched to zero rows," and a
         # policy that dispatched anyway despite a failing guard is as real
         # a finding as a row it skipped.
+        # @param history [Hash] a replayed history as returned by `Replay.call`
+        # @return [true, String] true if every fan-out finding's actual dispatches
+        #   match its independently computed expected row set; otherwise a message
+        #   naming the policy, event, and disagreement
         def fanout_dispatches_once_per_matching_row(history)
           offenders = history.fetch(:fan_outs).filter_map do |finding|
             expected = finding[:expected_row_ids]
@@ -183,21 +202,21 @@ module Hecks
           offenders.empty? || offenders.join("; ")
         end
 
-        # A `count`/`median` REPORT'S REDUCED SCALAR MATCHES THE SAME
-        # REDUCTION DONE INDEPENDENTLY, over the SAME eligible rows —
+        # A `count`/`median` report's reduced scalar matches the same
+        # reduction done independently, over the same eligible rows —
         # `ReadModelInterpreter#project`'s own FK-join (root first, then
         # each many-side head matched against it) and `#median` (odd →
         # the true middle, even → the average of the two middles as a
         # Float, empty → `nil`; `count` is the filtered length, empty →
         # `0`), reproduced here in plain Ruby against `history[:instances]`
         # rather than a live registry — `FieldPath.dig` +
-        # `Ports::Query::InMemory.comparable`/`.holds?` are the SAME two
+        # `Ports::Query::InMemory.comparable`/`.holds?` are the same two
         # calls the interpreter itself makes to read a field and judge a
         # `where`, called here rather than re-derived, so this oracle
         # cannot drift from what "read a field" or "a clause holds" mean
         # without the interpreter drifting the identical way.
         #
-        # Only a report whose `:query` is answered by the SAME bluebook
+        # Only a report whose `:query` is answered by the same bluebook
         # `history[:bluebook]` carries (the bare `Domain.report_name`
         # form, `domain == bluebook.name`) is checked — the same "only
         # what we have the grammar for" scope `lifecycle_values_are_declared`
@@ -206,11 +225,15 @@ module Hecks
         # ("only a report answered by this bluebook, only a count/median
         # report, only one with a reduced many-side head") each gating the
         # next, ending in one independent recomputation compared against
-        # the live answer. The guards are what make this oracle SCOPED
+        # the live answer. The guards are what make this oracle scoped
         # correctly, not incidental complexity — narrower than "every
         # branch reads as its own precondition."
         # rubocop:disable-next Metrics/CyclomaticComplexity
         # rubocop:disable-next Metrics/PerceivedComplexity
+        # @param history [Hash] a replayed history as returned by `Replay.call`
+        # @return [true, String] true if every eligible count/median report answer
+        #   matches an independent recomputation; otherwise a message naming the
+        #   query and the disagreement
         def aggregation_matches_recompute(history)
           bluebook = history.fetch(:bluebook)
 
@@ -239,14 +262,14 @@ module Hecks
         end
 
         # `aggregation_matches_recompute`'s own shape, extended from
-        # reducing a many-side head to a scalar (count/median) to NESTING
+        # reducing a many-side head to a scalar (count/median) to nesting
         # it — `ReadModelInterpreter#group_by_target`/`#nest`, reproduced
         # here in plain Ruby against `history[:instances]` the same way
         # `eligible_rows` already reproduces the FK-join and `where`
         # narrowing count/median share. `Value.materialize_unwrapped` is
-        # the SAME call `#project` makes before nesting (a single-field
+        # the same call `#project` makes before nesting (a single-field
         # value object recurses to its bare scalar — a real grouping key
-        # has to BE one) — called here rather than re-derived, so this
+        # has to be one) — called here rather than re-derived, so this
         # oracle cannot drift from what "the group key" means without the
         # interpreter drifting the identical way.
         #
@@ -257,6 +280,11 @@ module Hecks
         # of count/median, nest_rows in place of recompute_median.
         # rubocop:disable-next Metrics/CyclomaticComplexity
         # rubocop:disable-next Metrics/PerceivedComplexity
+        #
+        # @param history [Hash] a replayed history as returned by `Replay.call`
+        # @return [true, String] true if every eligible group_by report answer matches
+        #   an independent recompute; otherwise a semicolon-joined message naming each
+        #   offending query
         def group_by_matches_recompute(history)
           bluebook = history.fetch(:bluebook)
 
@@ -290,6 +318,11 @@ module Hecks
         # per `group_by` field in declared order, leaf is the row with
         # every grouped field stripped (already spent, as the keys that
         # reached it).
+        # @param rows [Array<Hash>] materialized, symbol-keyed rows to nest
+        # @param fields [Array<Symbol>] the `group_by` fields, in declared order
+        # @return [Hash] one level of nesting per field, in order; the leaf under
+        #   each key path is the first row in that group with every grouped field
+        #   stripped
         def nest_rows(rows, fields)
           field, *rest = fields
           rows.group_by { |row| row[field] }.transform_values do |group|
@@ -298,17 +331,27 @@ module Hecks
           end
         end
 
-        # THE ELIGIBLE ROWS a `count`/`median` head reduces — every
+        # The eligible rows a `count`/`median` head reduces — every
         # instance of the reduced head's own aggregate, FK-matched against
         # the report's root reference (if it has one; a rootless report has
         # none to match) exactly the way `ReadModelInterpreter#reference_fields`
         # finds the matching attribute, then narrowed by the report's own
-        # `where` clauses via the SAME `InMemory.holds?` the interpreter's
+        # `where` clauses via the same `InMemory.holds?` the interpreter's
         # `execute` calls.
+        # @param bluebook [Bluebook::Chapter] the bluebook the report belongs to
+        # @param instances [Hash] the snapshot to read rows from (`history[:instances]`
+        #   shape, or the query's own `instances_at`)
+        # @param domain [String] the domain name the reduced aggregate belongs to
+        # @param model [Bluebook::ReadModel] the report being recomputed
+        # @param reduced_head [Hash] the many-side aggregate head being reduced, from
+        #   `model.aggregate_heads`
+        # @param args [Hash] the query's own arguments, for FK matching and `where`
+        #   evaluation
+        # @return [Array<Hash>] every eligible row's own state, `id:` merged in
         def eligible_rows(bluebook, instances, domain, model, reduced_head, args)
           aggregate = bluebook.aggregate(reduced_head[:aggregate])
           prefix = "#{domain}::#{reduced_head[:aggregate]}#"
-          # `id:` MERGED IN, the same `record.to_h` (`@state.merge(id:
+          # `id:` merged in, the same `record.to_h` (`@state.merge(id:
           # @id)`) every live head row carries — count/median never read
           # it, but group_by_matches_recompute's own independent nesting
           # does, the same way ReadModelInterpreter#row(record) = record.
@@ -337,6 +380,11 @@ module Hecks
         # → the average of the two middle values, as a Float; empty → nil,
         # never zero, so a caller cannot mistake "nothing to average" for
         # "averaged to zero."
+        # @param rows [Array<Hash>] eligible rows, as returned by `#eligible_rows`
+        # @param field [Symbol] the field to average
+        # @return [Object, Float, nil] the true middle value for an odd count, the
+        #   Float average of the two middle values for an even count, or `nil` for
+        #   an empty `rows`
         def recompute_median(rows, field)
           values = rows.map { |state| Ports::Query::InMemory.comparable(QuerySpecification::FieldPath.dig(state, field)) }
                        .compact.sort