hecks 1.3.0 → 1.4.0

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

@@ -1,11 +1,11 @@
 module Hecks
   module Fuzzing
     module Properties
-      # A DRY RUN LEAVES NO TRACE — `Dispatcher#dry_run?`'s whole contract
+      # **A dry run leaves no trace** — `Dispatcher#dry_run?`'s whole contract
       # ("the command evaluated hypothetically, nothing saved or emitted,
       # no reaction"), held to the store rather than trusted: `Replay`
       # snapshots every instance and the event count on either side of
-      # each `{"dry_run": …}` step, in a SEPARATE `dry_run_traces` array
+      # each `{"dry_run": …}` step, in a separate `dry_run_traces` array
       # (same order as `history[:dry_runs]`, never merged into it — that
       # array stays the exact `{verb:, ok:, error?:}` shape the compiled
       # Rust binary's own `dry_run` answers, so `spec/rust_conformance_
@@ -37,7 +37,7 @@ module Hecks
       # Dispatch-binding and mutation-recomputation properties: a saga/
       # policy dispatch is bound to the value its own with_spec names, and a
       # command's append/remove/multiply/clamp mutations land on the same
-      # after-state an independent recomputation of the SAME rule produces.
+      # after-state an independent recomputation of the same rule produces.
 
       # Holds dispatch_binding_fidelity and mutations_match_recompute, plus
       # the independently-written re-derivations (#resolve_dispatch_binding,
@@ -49,17 +49,17 @@ module Hecks
         # are not claimable feature strings at all — see FEATURE_COVERAGE's
         # own comment on this entry). history[:saga_dispatches]/[:policy_dispatches]
         # (Registry#saga_dispatch_log/#policy_dispatch_log — additive,
-        # Ruby-only, NEVER touching saga_log/reaction_log, the byte-for-
+        # Ruby-only, never touching saga_log/reaction_log, the byte-for-
         # byte shape spec/rust_conformance_spec.rb holds Rust to) each
-        # carry the RAW inputs a dispatch's own args were resolved from,
+        # carry the raw inputs a dispatch's own args were resolved from,
         # captured live at the moment the resolution actually ran — a
         # saga's own memory keeps changing across a run, so re-deriving
-        # from history[:saga_instances]'s FINAL memory (the only other
+        # from history[:saga_instances]'s final memory (the only other
         # place it would be visible) would grade the wrong moment,
         # lifecycle_guard_and_given_violations_are_refused's own false
         # positive one item earlier, in a different shape.
         #
-        # #resolve_dispatch_binding/#resolve_trigger_binding are SEPARATE,
+        # #resolve_dispatch_binding/#resolve_trigger_binding are separate,
         # independently-written re-derivations of SagaInterpreter#
         # dispatch_args/PolicyInterpreter#trigger_args's own resolution —
         # never calling either method again, which would only ever agree
@@ -99,8 +99,8 @@ module Hecks
 
         # SagaInterpreter#dispatch_args's own 4-branch resolution,
         # reproduced independently: a literal, the correlation key itself,
-        # the CURRENT triggering event's own payload, or — the fallback —
-        # the saga's own carried memory (seeded from the STARTING event's
+        # the current triggering event's own payload, or — the fallback —
+        # the saga's own carried memory (seeded from the starting event's
         # payload, at begin_saga).
         def resolve_dispatch_binding(entry)
           entry[:with_spec].to_h do |key, value|
@@ -116,7 +116,7 @@ module Hecks
         # PolicyInterpreter#trigger_args's own 2-branch resolution — a
         # policy holds no correlation and no memory, so `payload` (the
         # triggering event's own payload, already merged with a fan-out
-        # row's id when there is one) is the WHOLE source.
+        # row's id when there is one) is the whole source.
         def resolve_trigger_binding(entry)
           entry[:with_spec].to_h do |key, value|
             resolved = value.is_a?(Symbol) ? entry[:payload][value] : value
@@ -137,32 +137,77 @@ module Hecks
         #
         # `history[:mutation_traces]` (Replay's own bounded, additive
         # extension — see #build_mutation_trace's own comment) carries a
-        # per-step before/after snapshot of the ENTITY ELEMENT an
+        # per-step before/after snapshot of the entity element an
         # entity-dispatched command's own mutations acted on, materialized
         # to plain data, plus the step's own raw args — the delta
         # `aggregation_matches_recompute` never had to ask for, because
-        # count/median are pure functions of FINAL state and a mutation
+        # count/median are pure functions of final state and a mutation
         # is not (the same "captured live, not re-derived from final
         # state" lesson item 8's own saga_dispatch_log already learned).
         #
         # #recompute_append/#recompute_remove/#recompute_multiply/
-        # #recompute_clamp are SEPARATE, independently-written
-        # reproductions of MutationApplier#appended/#removed and
+        # #recompute_clamp/#recompute_set are separate, independently-
+        # written reproductions of EntityElement#appended_to_element/
+        # #removed_from_element/#apply_to_element's own `:set` branch and
         # CommandRules::Arithmetic#multiply/#clamp — never calling either
-        # again, which would only ever agree with itself. `:set`/
-        # `:increment`/`:decrement` are out of scope on purpose (the four
-        # "vendored, not yet upstream" ops this item exists for); a
-        # command mixing them with a recomputable op still gets the
-        # recomputable one checked.
+        # again, which would only ever agree with itself. Every one of
+        # these five reproduces the entity-scoped applier specifically
+        # (`EntityElement#apply_to_element`, entity_element.rb), never
+        # the aggregate-level `MutationApplier#apply` (mutation_applier.rb)
+        # — `build_mutation_trace` (replay.rb) only ever captures an
+        # entity-owned command's own mutation in the first place (that
+        # method's own `command_name&.include?(".")` guard), so there is
+        # no aggregate-level trace for this property to ever compare
+        # against `owner_for_verb`'s own comment draws the identical
+        # aggregate/owner distinction for `:append`. `:increment`/
+        # `:decrement` remain out of scope (CommandRules::Arithmetic#
+        # arithmetic's own VO-vs-scalar branching and INT64_RANGE overflow
+        # checks are a materially larger reproduction than the other five
+        # ops combined — scoped out of this pass, not forgotten; see
+        # docs/decisions/0056); a command mixing them with a recomputable
+        # op still gets the recomputable one checked.
+        #
+        # `:set` closes a real, separate gap from the other four — this is
+        # not "the fifth op of a symmetrical set." `self_consistency.rb`'s
+        # own rehydration/idempotency checks (lib/hecks/fuzzing/
+        # self_consistency.rb) can never catch a bug in `EntityElement#
+        # apply_to_element`'s `:set` branch (entity_element.rb) no matter
+        # how much they run: both the "live" state they snapshot and the
+        # "rehydrated" state they fold from `Ports::Persistence::
+        # AppendOnly`'s own journal trace back to the same single
+        # `step_apply_mutations` call (entity_interpreter.rb) — the
+        # journal holds the full POST-mutation state, not a delta (that
+        # file's own header), so a wrong `:set` result is already baked
+        # into both sides of that comparison before either one runs. A
+        # Ruby/Rust differential check is subject to the identical
+        # structural blind spot whenever Rust's own generated `:set`
+        # handling was derived from — and so shares — the same
+        # misunderstanding Ruby's implementation has. `#recompute_set`
+        # is a genuinely third computation, independent of both: it
+        # re-derives the expected value from the mutation's own declared
+        # `source` (an argument or a literal — matching `apply_to_
+        # element`'s own `resolve_source`, which unlike the aggregate-
+        # level `apply` never special-cases a `StateRef` source at all)
+        # and the step's own captured `args`, then compares against what
+        # the real dispatch actually stored — closing exactly the class
+        # of bug the self-consistency and (whenever Rust's codegen shares
+        # a ruby-derived misunderstanding) differential checks cannot see.
+        # `spec/fuzzing/mutation_set_self_correctness_spec.rb` proves this
+        # concretely: a defect planted directly in `EntityElement#apply_
+        # to_element`'s `:set` branch leaves `SelfConsistency.check`
+        # completely clean while `mutations_match_recompute` names it.
         #
         # `:unrecomputable` (never compared, never a finding) covers the
         # generator's own deliberate arg-malforming (`StepBuilder#malform`)
         # landing a non-Numeric amount/non-2-element bounds where
-        # multiply/clamp need one — the SAME shape `guard_check`'s own
+        # multiply/clamp need one — the same shape `guard_check`'s own
         # AbsentArgument false positive taught: a step whose raw material
         # doesn't fit the op's own contract is inconclusive, not a claimed
-        # mismatch.
-        RECOMPUTABLE_MUTATION_OPS = %i[append remove multiply clamp].freeze
+        # mismatch. `#recompute_set` returns it for the same reason,
+        # whenever `Value.for_attribute`'s own coercion door raises on the
+        # resolved raw source (malformed fuzzer input, never a real
+        # corpus shape).
+        RECOMPUTABLE_MUTATION_OPS = %i[append remove multiply clamp set].freeze
 
         def mutations_match_recompute(history)
           bluebooks = history.fetch(:bluebooks)
@@ -196,12 +241,12 @@ module Hecks
 
         # `command_for_verb`'s own root-aggregate half (Guards) —
         # re-derived independently rather than read off `entry[:domain]`/
-        # `entry[:aggregate]` (present on a REAL `build_mutation_trace`
+        # `entry[:aggregate]` (present on a real `build_mutation_trace`
         # entry, but not on every hand-built fixture this property is
         # tested against) so this works from `entry[:verb]` alone, the
         # one field every entry always carries. BUG#5's fix needs the
-        # ROOT aggregate specifically — `Value.for_attribute` resolves a
-        # value-object TYPE against the root's own namespace only, the
+        # root aggregate specifically — `Value.for_attribute` resolves a
+        # value-object type against the root's own namespace only, the
         # same reason `EntityElement#locate_chain` threads `root_aggregate`
         # through every hop separately from each hop's own `owner`.
         def aggregate_for_verb(bluebooks, verb)
@@ -211,7 +256,7 @@ module Hecks
           bluebooks[domain_name]&.aggregate(aggregate_name)
         end
 
-        # `mutation.target`'s own DECLARING construct — the root
+        # `mutation.target`'s own declaring construct — the root
         # aggregate for an aggregate-owned command (`AddSlot`'s own
         # `:slots`), or the entity a dot-shaped command belongs to
         # (`Board.AddCard`'s own `:cards`, declared on `Board`, not on
@@ -242,50 +287,110 @@ module Hecks
           when :remove   then recompute_remove(current, mutation.source, args)
           when :multiply then recompute_multiply(current, resolve_mutation_source(mutation.source, args))
           when :clamp    then recompute_clamp(current, mutation.source)
+          when :set      then recompute_set(mutation.source, args, aggregate, owner, mutation.target)
           end
         end
 
+        # `EntityElement#apply_to_element`'s own `:set` branch (entity_
+        # element.rb), reproduced independently — not `MutationApplier#
+        # apply`'s aggregate-level twin (mutation_applier.rb), a
+        # different method with a different shape: `build_mutation_trace`
+        # (replay.rb) only ever captures an entity-owned command's own
+        # mutation (`command_name&.include?(".")`, that method's own
+        # header), so `mutations_match_recompute` can only ever be
+        # checking `apply_to_element`'s branch, never `apply`'s — the
+        # same distinction `owner_for_verb`'s own comment already draws
+        # for `:append`. Confirmed by reading `apply_to_element` directly:
+        # its own `:set` branch resolves the source through `rules.
+        # resolve_source` unconditionally (no `StateRef` branch at all —
+        # unlike the aggregate-level `apply`, an entity-owned `sets` has
+        # no declared corpus site using `state(:x)` today, so this
+        # reproduces what ships, not a hypothetical), reads the
+        # attribute off `entity.attribute(mutation.target)` (the owning
+        # entity, `owner` here — `Board`, never `Workspace`), and coerces
+        # through `Value.for_attribute(aggregate, attribute, value)`
+        # (the root aggregate, for value-object namespace resolution
+        # only — `value_object_for(aggregate, attribute.type)` — the
+        # same aggregate/owner split `owner_for_verb`'s own comment
+        # explains for `recompute_append`). An earlier version of this
+        # method mirrored `MutationApplier#apply`'s `:set` branch instead
+        # (StateRef-aware, coerced against `aggregate.attribute` rather
+        # than `owner.attribute`) and false-positived on every real
+        # entity-owned `sets` in the corpus — `NestedPieces::Workspace.
+        # Board.Label` (`sets :label`) has no `:label` attribute on
+        # `Workspace` at all, so `Value.for(aggregate, :label, raw)`
+        # silently passed the raw, uncoerced String through instead of
+        # wrapping it as `BoardLabel`, and the comparison below then
+        # disagreed with the real, correctly-coerced `after` state on
+        # every single run — caught immediately by running this against
+        # `qa/stress_domains/nested_pieces` before this comment existed,
+        # not by inspection alone.
+        #
+        # Reusing `Value.for_attribute` for the coercion step, rather
+        # than re-deriving it, is the same "coercion is its own already-
+        # guaranteed door" reasoning `GUARANTEED_BY_CONSTRUCTION` states
+        # and `#coerce_recompute_append_arg` already leans on for BUG#5 —
+        # what this property exists to check is the source resolution and
+        # routing (did the right raw value, from the right source, land
+        # on the right target?), not whether `Value.for_attribute` itself
+        # coerces correctly (a separate, already-enforced concern).
+        # Rescued broadly: a `:set` mutation trace is only ever captured
+        # after a real, already-admitted dispatch (`Replay#build_
+        # mutation_trace`'s own header), so a raise here means this
+        # recomputation resolved the wrong raw material, not that the
+        # real dispatch was itself malformed — `:unrecomputable`, not a
+        # crash, the same discipline every other branch in this method
+        # already follows for the generator's own deliberate malforming.
+        def recompute_set(source, args, aggregate, owner, target)
+          raw = resolve_mutation_source(source, args)
+          attribute = owner&.attribute(target)
+          coerced = attribute ? Runtime::Value.for_attribute(aggregate, attribute, raw) : raw
+          Runtime::Value.materialize(coerced)
+        rescue StandardError
+          :unrecomputable
+        end
+
         # `EntityElement#appended_to_element`'s own field-mapping half,
-        # reproduced: the field map resolved the SAME two-tier way
+        # reproduced: the field map resolved the same two-tier way
         # (`MutationApplier#resolve_append_source` — a caller-supplied
         # arg, or the entity's own current field), then appended. (An
-        # entity-dispatched command's own mutations DO reach here —
+        # entity-dispatched command's own mutations do reach here —
         # `#build_mutation_trace`'s own comment describing them as never
         # reaching "the entity_element branch" means `MutationApplier#
-        # appended`'s own AGGREGATE-level entity_element fallback
+        # appended`'s own aggregate-level entity_element fallback
         # specifically, which really is unreached from here; entity-owned
         # append dispatches go through `EntityElement#appended_to_element`
-        # instead, and DO reach this method.)
+        # instead, and do reach this method.)
         #
         # BUG#5 — an entity-owned `:append` whose target field is itself
         # value-object-typed (`Board.AddCard`'s own `sets :cards, append:
         # { sequence: :sequence }`, `CardSequence`-typed). A caller-
-        # supplied arg reaches the REAL applier (`EntityElement#
+        # supplied arg reaches the real applier (`EntityElement#
         # appended_to_element`) already coerced: `Interpreting#
         # coerce_declared_arguments` runs `Value.for_attribute` over
-        # EVERY arg the acting command itself declares, BEFORE dispatch
+        # every arg the acting command itself declares, before dispatch
         # ever reaches a mutation applier at all — independent of, and
         # earlier than, anything `appended_to_element`'s own value_object
-        # check does. `before_scope[source]` (the entity's OWN current
+        # check does. `before_scope[source]` (the entity's own current
         # field) needs no such re-coercion here: it's already the
-        # MATERIALIZED shape `build_mutation_trace` snapshotted it in
+        # materialized shape `build_mutation_trace` snapshotted it in
         # (`Value.materialize`, same as `entry[:after]`), not a raw value
         # sitting behind a live `Value`.
         #
-        # BUG#12 — `owner`/`target` (new here) let this ALSO reproduce
+        # BUG#12 — `owner`/`target` (new here) let this also reproduce
         # `EntityElement#fill_declared_defaults`'s own entity-nested-in-
         # entity fallback (`appended_to_element`'s `else` branch, when
         # the appended element is itself an entity — `Card`, nested
         # inside `Board` — not a value object): `owner.attribute(target)
         # &.type` names the appended element's own type; when that names
         # an entity of `aggregate` rather than a value object, every one
-        # of ITS OWN declared attributes `fields` doesn't already hold
+        # of its own declared attributes `fields` doesn't already hold
         # gets `Instance.default_for`'s own default — reused, not
         # reimplemented, for the identical "never agree with itself"
         # reason BUG#5's own coercion re-derivation above already gives:
         # `Instance.default_for` is pre-existing, independently-tested
         # machinery (an ordinary aggregate's own creation already runs
-        # through it via `Instance.defaults`), not the NEW glue
+        # through it via `Instance.defaults`), not the new glue
         # (`fill_declared_defaults` itself) this property exists to
         # catch a drift in.
         def recompute_append(current, source_map, before_scope, args, aggregate, command, owner = aggregate, target = nil)
@@ -305,8 +410,8 @@ module Hecks
         # isn't an entity nested directly under `owner` (a value object,
         # or nothing declared at all — `owner.attribute` answering `nil`
         # for a target the DSL itself would already have refused at
-        # build time). `owner.entities`, NOT `aggregate.entities` — a
-        # piece nested inside a piece is a child of the OWNING entity
+        # build time). `owner.entities`, not `aggregate.entities` — a
+        # piece nested inside a piece is a child of the owning entity
         # (`Card` is `Board.entities`, never `Workspace.entities`), the
         # same distinction `EntityElement#appended_to_element`'s own fix
         # draws.
@@ -335,8 +440,8 @@ module Hecks
         # `Interpreting#coerce_declared_arguments`'s own coercion,
         # reproduced independently (never calling it again, the same
         # "never agree with itself" rule this whole module's header
-        # comment gives) — a raw arg is coerced ONLY when its own name
-        # (`source`) is one of the ACTING COMMAND's own declared
+        # comment gives) — a raw arg is coerced only when its own name
+        # (`source`) is one of the acting command's own declared
         # attributes, exactly the condition that method checks before a
         # real dispatch ever coerces it either. `command.attribute(source)`
         # answering `nil` (a source that names no declared attribute —
@@ -367,7 +472,7 @@ module Hecks
         # reproduced on plain materialized data instead of a real Value:
         # a single-numeric-field Hash (the VO-typed case — ListCount, one
         # Integer field) scales that field ; a bare Numeric scales itself.
-        # `current ||= 0` — the SAME phantom-field fallback #multiply
+        # `current ||= 0` — the same phantom-field fallback #multiply
         # itself already gives (unaffected by this session's #clamp fix,
         # since #multiply never needed one).
         def recompute_multiply(current, amount)
@@ -387,8 +492,8 @@ module Hecks
         end
 
         # `CommandRules::Arithmetic#clamp`'s own two branches, reproduced
-        # the same way #recompute_multiply is — including THIS SESSION'S
-        # OWN `current ||= 0` fix (command_rules/arithmetic.rb), the one
+        # the same way #recompute_multiply is — including this session's
+        # own `current ||= 0` fix (command_rules/arithmetic.rb), the one
         # arithmetic op that didn't have it until now. `mutation.source`
         # is always a literal `[min, max]`, never an argument reference
         # (MutationApplier's own comment on why `resolve_source` is
@@ -411,18 +516,18 @@ module Hecks
         end
 
         # `CommandRules::Arithmetic#resolve_source`, reproduced: a
-        # mutation's source is either the NAME OF AN ARGUMENT or a
-        # LITERAL, told apart by type.
+        # mutation's source is either the name of an argument or a
+        # literal, told apart by type.
         def resolve_mutation_source(source, args)
           source.is_a?(Symbol) ? args[source] : source
         end
 
-        # A generated step's own `args` arrive with STRING keys on every
+        # A generated step's own `args` arrive with string keys on every
         # nested Hash (the wire/JSON shape `spec/corpus/*.json` already
         # uses) while `history[:mutation_traces]`' own materialized
-        # before/after state carries SYMBOL keys throughout (Runtime::
+        # before/after state carries symbol keys throughout (Runtime::
         # Value.materialize's own convention) — two hashes holding the
-        # identical fact compare UNEQUAL by Ruby's own `Hash#==` unless
+        # identical fact compare unequal by Ruby's own `Hash#==` unless
         # both sides are normalized the same way first. Recursive, since
         # an appended/removed element can itself nest a value object
         # (RemoveTag's own `Tag` argument, `{"key"=>..., "value"=>...}`).

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.
@@ -92,14 +92,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 +107,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
@@ -138,27 +138,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,25 +166,25 @@ 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.
@@ -230,7 +230,7 @@ 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
@@ -241,16 +241,16 @@ module Hecks
           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,14 +258,14 @@ 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.
         def effective_guard_descriptions(bluebooks, verb, command)
           own = command.guard_descriptions
@@ -296,9 +296,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 +306,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 +316,27 @@ 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.
         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]