hecks 1.3.0 → 1.4.0

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
@@ -70,11 +70,11 @@ 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`.
         def check_piece_invariants(owner_construct, owner_state, key)
           owner_construct.entities.each do |entity|
@@ -99,23 +99,23 @@ 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:
@@ -150,11 +150,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
@@ -183,21 +183,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,7 +206,7 @@ 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
@@ -239,14 +239,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.
         #
@@ -298,17 +298,17 @@ 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.
         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.

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

@@ -1,3 +1,5 @@
+require_relative "../nondeterministic"
+
 module Hecks
   module Fuzzing
     module Properties
@@ -12,11 +14,11 @@ 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.
@@ -44,10 +46,10 @@ 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
@@ -72,56 +74,41 @@ 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.
         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,61 +3,61 @@ 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
+      #   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,
+      # 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
+      # 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_
+      # **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.
@@ -117,14 +117,14 @@ 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.

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,17 +18,17 @@ 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
+        # 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
+        # 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
@@ -59,16 +59,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
@@ -112,7 +112,7 @@ 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
@@ -128,24 +128,24 @@ module Hecks
           aggregate&.query(query_path)
         end
 
-        # A QUERY'S OWN ROWS — unlike #eligible_rows (a ReadModel's
+        # 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.
@@ -173,7 +173,7 @@ 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