hecks 1.2.0 → 1.4.0

data/lib/hecks/bluebook/dsl/port_operation_builder.rb

@@ -14,31 +14,34 @@ module Hecks
         include AttributeCollector
         include WordGate
 
-        # `to:` — THE SANCTIONED REPLACEMENT for `reference_to` inside an
-        # operation body, added here rather than left as a documented-but-
-        # unbuilt promise: reference_to_impl's own refusal message has told
-        # authors to "pass the receiving aggregate in to:" since #335, but
-        # no `to:` argument existed anywhere in DomainPort's own grammar
-        # (domain_port.bluebook) for operation/tells/asks to receive it —
-        # confirmed by grep across every lib/hecks/language file, not
-        # assumed.
+        # `to:` — the sanctioned replacement for `reference_to` inside an
+        # operation body: `reference_to_impl`'s own refusal message tells
+        # authors to "pass the receiving aggregate in to:", and this is
+        # the argument DomainPort's own grammar (domain_port.bluebook)
+        # gives operation/tells/asks to receive it.
         #
-        # GENUINE ROUTING METADATA, NOT AN ATTRIBUTE — matching
+        # **Genuine routing metadata, not an attribute** — matching
         # rust/parser/src/parse/domain_port.rs's own header comment ("The
         # receiving aggregate is routing metadata supplied by to:, not an
         # operation attribute"), which anticipated this shape before either
         # side actually built it. Stored separately (below, threaded to
         # PortOperation as `to:`) rather than reusing reference_to_impl's
         # own attribute-adding path — Dispatcher#port_invocation
-        # (lib/hecks/runtime/dispatcher.rb) is the ONE place that resolves
+        # (lib/hecks/runtime/dispatcher.rb) is the one place that resolves
         # routing at dispatch time; it gained a second, purely additive
-        # branch for this (falls back to a plain attribute NAMED for the
+        # branch for this (falls back to a plain attribute named for the
         # owning aggregate's own identified_by field, the same "declare
         # only external facts with attribute" the refusal message
         # describes) rather than folding `to:` into identity_attribute's
         # existing Reference-attribute scan, which every operation already
         # in the corpus (Banking, pizzas, lifeadelics' own vendored
         # PaymentGateway) still relies on unchanged.
+        #
+        # @param name [String] the operation's name
+        # @param to [Symbol, String, Module, nil] the aggregate the operation routes to; stored
+        #   demodulised, and nil when the operation names none
+        # @param owner [String, nil] name of the aggregate the enclosing port is declared on
+        # @param direction [Symbol] `:inbound` for `operation`/`tells`, `:outbound` for `asks`
         def initialize(name, to: nil, owner: nil, direction: :inbound)
           @name      = name
           @to        = to && Naming.demodulise(to)
@@ -47,23 +50,33 @@ module Hecks
           @emits     = []
         end
 
-        # ALWAYS an attribute, never the self-reference `CommandBuilder`
+        # Refuses `reference_to` inside an operation body, except while shadow-parsing, where it
+        # adds the reference attribute frozen era text declared.
+        #
+        # Always an attribute, never the self-reference `CommandBuilder`
         # spells — a port operation has no `creates?`/`acts_on` distinction
         # to protect, so there is nothing for the self-reference branch to be
-        # FOR here. `reference_to Payment, as: :payment_id` reads the same
+        # for here. `reference_to Payment, as: :payment_id` reads the same
         # even though the target happens to equal the owning aggregate.
-        # RENAMED FROM `reference_to` — item #13's full metaprogrammed
-        # dispatch (slice 4b). Bootstrap-reachable, in
-        # GenericDispatch::BOOTSTRAP_CALLS_FALLBACK.
+        # Answers the `reference_to` word through the table's `calls:`
+        # column — item #13's full metaprogrammed dispatch (slice 4b).
+        # Bootstrap-reachable, in `GenericDispatch::BOOTSTRAP_CALLS_FALLBACK`.
         #
-        # DISABLED, #335 — kept only for MetaValidator's own shadow-parsing
+        # Disabled, #335 — kept only for MetaValidator's own shadow-parsing
         # pass (the self-hosted grammar's own KeywordSeed/ArgumentSeed rows
         # for "reference_to" in this context are themselves declared using
         # this construct, one level up — deleting the Ruby method would
         # break the language describing itself, not just old domain
-        # authors). Every REAL domain author reaches `to:` instead, above —
+        # authors). Every real domain author reaches `to:` instead, above —
         # a genuinely different mechanism now, not a relocated spelling of
         # this one (see `to:`'s own comment).
+        #
+        # @param type [Symbol, String, Module] the referenced aggregate, written as a bare constant
+        # @param as [Symbol, nil] the attribute's name; nil derives it from the target, as in
+        #   `:payment_id` under shadow-parsing
+        # @return [nil] nothing useful; the reference lands in `attributes`
+        # @raise [Bluebook::DSL::Malformed] always outside shadow-parsing, since routing belongs
+        #   in `to:`; under shadow-parsing, if the attribute name is already declared
         def reference_to_impl(type, as: nil)
           unless MetaValidator.shadow_parsing?
             raise Malformed,
@@ -74,9 +87,13 @@ module Hecks
           add_reference!(type, as: as)
         end
 
+        # Names one event an inbound operation records once the external fact has arrived.
+        #
+        # @param event_name [String, Symbol] the event's name, such as `"PaymentSettled"`
+        # @return [Array<String>] every event named so far, this one last
         def emits(event_name) = @emits << event_name.to_s
 
-        # THE TWO HALVES OF AN `asks`. An outbound call has exactly two
+        # The two halves of an `asks`. An outbound call has exactly two
         # endings and the chapter names both — `answers` for what came back,
         # `refuses` for what the outside said instead. They are separate words
         # rather than two `emits` because a reader has to be able to tell them
@@ -87,6 +104,12 @@ module Hecks
         # kind-driven coerce-and-assign with nothing else, now executed
         # by `GenericDispatch`.
 
+        # Assembles the operation, refusing words that belong to the other direction.
+        #
+        # @return [Bluebook::PortOperation] the operation with its attributes, events and routing
+        # @raise [Bluebook::DSL::Malformed] if an inbound operation declares no `emits` or
+        #   declares `answers`/`refuses`, or an outbound one declares `emits` or lacks either
+        #   `answers` or `refuses`
         def build
           outbound = @direction == :outbound
           refuse_wrong_words!(outbound)
@@ -96,7 +119,7 @@ module Hecks
             direction: @direction, answers: @answers, refuses: @refuses, to: @to
           )
 
-          # AN INBOUND OPERATION STILL HAS TO SAY SOMETHING. Only inbound: an
+          # An inbound operation still has to say something. Only inbound: an
           # `asks` says it with `answers`/`refuses` instead, and
           # `refuse_wrong_words!` above has already insisted on both.
           if !outbound && @emits.empty?
@@ -110,7 +133,7 @@ module Hecks
 
         private
 
-        # THE ONE PLACE a reference attribute actually gets added — both
+        # The one place a reference attribute actually gets added — both
         # `to:` (initialize, above) and reference_to_impl's own shadow-
         # parsing branch call this, so there is exactly one real
         # implementation of "carry a Reference-typed external fact,"
@@ -120,7 +143,7 @@ module Hecks
           attribute_impl(as || default_reference_name(target), Reference.new(target))
         end
 
-        # EACH DIRECTION REFUSES THE OTHER'S WORDS. `emits` on an `asks` looks
+        # **Each direction refuses the other's words**. `emits` on an `asks` looks
         # right and is not: it would name one ending and leave the other
         # nowhere. `answers` on a `tells` is worse — there is no channel back
         # to an inbound caller at all, so it would read as a promise the
@@ -147,10 +170,21 @@ module Hecks
           end
         end
 
+        # Evaluates one operation block against a fresh builder and returns what it built.
+        #
         # `private` above (scoping the instance methods between it and here)
         # doesn't reach a singleton method — correctly so: `.build` is this
         # builder's real public entry point (DomainPortBuilder calls it),
         # never meant to be private.
+        #
+        # @param name [String] the operation's name
+        # @param to [Symbol, String, Module, nil] the aggregate the operation routes to, or nil
+        # @param owner [String, nil] name of the aggregate the enclosing port is declared on
+        # @param direction [Symbol] `:inbound` for `operation`/`tells`, `:outbound` for `asks`
+        # @yield the operation body, evaluated with the builder as `self`; may be omitted
+        # @return [Bluebook::PortOperation] the built operation
+        # @raise [Bluebook::DSL::Malformed] if the body uses the other direction's words, omits
+        #   the ones its own direction requires, or uses a word the grammar does not admit
         # rubocop:disable-next Lint/IneffectiveAccessModifier
         def self.build(name, to: nil, owner: nil, direction: :inbound, &block)
           builder = new(name, to: to, owner: owner, direction: direction)

data/lib/hecks/bluebook/dsl/process_manager_builder.rb

@@ -7,7 +7,7 @@ module Hecks
       # correlates its instances (`correlates_by`), and the `transition`-
       # declared state machine whose `dispatch`es (each optionally paired
       # with its own per-dispatch `compensates`) become its handlers. States
-      # are DERIVED from the transitions rather than declared separately
+      # are derived from the transitions rather than declared separately
       # (S7, ADR 0025).
       class ProcessManagerBuilder
         GRAMMAR_CONTEXT = "ProcessManager".freeze
@@ -21,13 +21,13 @@ module Hecks
           @handlers = []
         end
 
-        # `starts_on Transfer::TransferRequested` — BARE CONSTANT
-        # ACCEPTED (ADR 0025, S6 — "events first-class"), resolved
+        # `starts_on Transfer::TransferRequested` — bare constant
+        # accepted (ADR 0025, S6 — "events first-class"), resolved
         # through `ConstShim` the same way `on_impl`/`transition_impl`
         # resolve an event reference — but through `Naming.
-        # event_name_ref`, NOT `Naming.event_ref` (that method's own
+        # event_name_ref`, not `Naming.event_ref` (that method's own
         # header has the full account: `SagaInterpreter` matches
-        # `pm.starts_on`/`pm.ends_on` against a BARE `event.name`, never
+        # `pm.starts_on`/`pm.ends_on` against a bare `event.name`, never
         # a "." qualified one). A plain String still passes through
         # unchanged, both for `shadow_parse` and for any corpus site a
         # future pass hasn't migrated yet.
@@ -45,7 +45,7 @@ module Hecks
         # kind-driven coerce-and-assign with nothing else, executed by
         # `GenericDispatch`.
         #
-        # `starts_on`/`ends_on` USED TO be table-driven the same way,
+        # `starts_on`/`ends_on` used to be table-driven the same way,
         # until ADR 0025 S6 gave each a second, `kind: "constant"`
         # ArgumentSeed row (`starts_on Transfer::TransferRequested`) —
         # `GenericDispatch::COERCE_BY_KIND` only knows `"text"`/
@@ -54,25 +54,25 @@ module Hecks
         # (`arguments.size == 1` below), so both words are hand-written
         # again, `calls:`-routed like `transition` already is.
 
-        # ONE STATE-MACHINE VOCABULARY (S7, ADR 0025 — "events and
-        # reactions"): the SAME word `Lifecycle#transition` already
+        # One state-machine vocabulary (S7, ADR 0025 — "events and
+        # reactions"): the same word `Lifecycle#transition` already
         # carries, one level over — `transition "AccountDebited" =>
         # "awaiting_credit", from: "requested" do ... end` replaces `on
         # "AccountDebited", transition: { "requested" => "awaiting_
         # credit" } do ... end`. Same bare rocket-pair argument shape
-        # (not a NAMED `transition:` kwarg wrapping a second Hash), same
+        # (not a named `transition:` kwarg wrapping a second Hash), same
         # `from:` — including the array form Lifecycle's own commands
         # could already take and a process manager's own events could
-        # not — and the states a procedure runs on are DERIVED from the
+        # not — and the states a procedure runs on are derived from the
         # transitions that name them, the same way `Behaviour::Lifecycle
         # #states` already derives an aggregate's ; `state "x"` lines
         # duplicated exactly what the transition list already said,
         # and could drift from it (`validate!`'s own "undeclared state"
         # check existed only because they could).
         #
-        # `starts_on`/`ends_on` are NOT unified into this — verified
+        # `starts_on`/`ends_on` are not unified into this — verified
         # against the real corpus rather than assumed: Settlement's own
-        # `ends_on "TransferSettled"` names an event NONE of its own
+        # `ends_on "TransferSettled"` names an event none of its own
         # transitions ever handle (`Transfer.Settle`'s own emission, a
         # full step downstream of the transition that dispatches it),
         # so "the terminal state's own event" is not a fact the
@@ -81,15 +81,15 @@ module Hecks
         # cover the case, which is not less vocabulary than keeping the
         # one that already says it correctly.
         #
-        # EXPANDS IMMEDIATELY, unlike `Lifecycle#transition` (which
+        # Expands immediately, unlike `Lifecycle#transition` (which
         # defers to `Behaviour::Lifecycle#expand`, called at emission
         # time) — `ProcessManager`'s own IR constructor takes `states:`/
         # `handlers:` exactly as it always has, so the runtime
         # (`Behaviour::ProcessManager`, `SagaInterpreter`, saga
         # persistence/rehydration) needs no change at all: what changed
-        # is how the DECLARATION reaches that same shape, not the shape
+        # is how the declaration reaches that same shape, not the shape
         # a real run ever sees or persists.
-        # RENAMED FROM `transition` — item #13's full metaprogrammed
+        # Renamed from `transition` — item #13's full metaprogrammed
         # dispatch (slice 4c). Not bootstrap-reachable (checked
         # directly — no core/attached chapter declares a ProcessManager
         # of its own).
@@ -97,9 +97,9 @@ module Hecks
           mapping = mapping.dup
           from    = mapping.delete(:from)
 
-          # ALWAYS REQUIRED, unlike `Lifecycle#transition`'s own `from:`
+          # Always required, unlike `Lifecycle#transition`'s own `from:`
           # — an aggregate's unconstrained transition is admitted from
-          # ANY current state (`Behaviour::Lifecycle#applies_from?`
+          # any current state (`Behaviour::Lifecycle#applies_from?`
           # returns true for a nil `from`), a reading `SagaInterpreter#
           # advance_saga`'s own admission check does not share: it tests
           # `instance[:state] == handler.from_state` by plain equality,
@@ -120,14 +120,14 @@ module Hecks
           handler.instance_eval(&block) if block
 
           mapping.each do |event_type, target|
-            # BARE CONSTANT ACCEPTED (ADR 0025, S6 — "events first-
+            # Bare constant accepted (ADR 0025, S6 — "events first-
             # class"), `transition Account::AccountDebited => "state"` —
-            # `Naming.event_name_ref`, NOT the DOTTED `Naming.event_ref`
+            # `Naming.event_name_ref`, not the dotted `Naming.event_ref`
             # transform `PolicyBuilder#on_impl` uses (that method's own
             # header has the full account, found live wiring a real
             # migrated corpus site into `bin/model_check` for the first
             # time: `SagaInterpreter#advance_saga` matches `handler.
-            # event_type` against a BARE `event.name`, never a "."
+            # event_type` against a bare `event.name`, never a "."
             # qualified one — a policy's own cross-aggregate match
             # works differently, splitting the qualifier apart from the
             # name rather than comparing the whole string). Writing the
@@ -163,12 +163,12 @@ module Hecks
 
         private
 
-        # ONE DECLARED TRANSITION IS SEVERAL ROWS when `from` names more
+        # One declared transition is several rows when `from` names more
         # than one source state — `Behaviour::Lifecycle#expand`'s own
         # comment, the identical fan-out, one level over: a
         # `ProcessManagerHandler` only ever carries a single `from_state`,
         # so a `from: [...]` transition mints one row per source, each
-        # carrying the SAME dispatches.
+        # carrying the same dispatches.
         def expand(event_type, transition, dispatches)
           sources = transition.from.nil? ? [nil] : Array(transition.from)
 
@@ -182,12 +182,12 @@ module Hecks
           end
         end
 
-        # DERIVED, not declared (S7) — every state this procedure ever
+        # Derived, not declared (S7) — every state this procedure ever
         # runs on is already named by some transition's own `from_state`
         # or `to_state`; a state nothing transitions into or out of is
         # not a state this procedure has, the same reading
         # `Behaviour::Lifecycle#states` already gives an aggregate's own
-        # field. FIRST-SEEN ORDER, walking declaration order — `begin_
+        # field. First-seen order, walking declaration order — `begin_
         # saga`'s own `pm.states.first` is what a fresh instance starts
         # in, so the order has to survive the derivation, not just the
         # membership.
@@ -201,15 +201,15 @@ module Hecks
                                          "nothing would tie its events to one instance"
           end
 
-          # THE FIELD, NAMED — never the value object that carries it. A bare
+          # **The field, named** — never the value object that carries it. A bare
           # `correlates_by :end_to_end` reads whatever the payload holds under
-          # that key AS the correlation key, and what a non-scalar key even
+          # that key as the correlation key, and what a non-scalar key even
           # is stays open (the object itself? its serialised text?).
           # Requiring the dotted spelling —
           # `:"end_to_end.value"` — makes every correlates_by name a scalar
           # by construction, the same discipline `identified_by` already
           # holds a head to. This is a syntactic check, not a type check: it
-          # does not know or care whether the field IS a value object, only
+          # does not know or care whether the field is a value object, only
           # that the declaration cannot leave that question open.
           unless @correlates_by.to_s.include?(".")
             raise InvalidProcessManager, "#{@name} correlates_by #{@correlates_by.inspect}, which names a whole " \
@@ -231,7 +231,7 @@ module Hecks
         end
 
         # C10.3 — a leg is selected by (event, current state), so two
-        # legs answering the SAME event from the SAME state would leave
+        # legs answering the same event from the same state would leave
         # the runtime to pick by declaration order, silently. Refused
         # here, where the declaration can still be read whole. (`from:
         # [...]` fan-out counts: `transition E => "a", from: ["x", "y"]`
@@ -253,7 +253,7 @@ module Hecks
           end
         end
 
-        # THE BODY OF ONE `transition ... do ... end` block — collects the
+        # The body of one `transition ... do ... end` block — collects the
         # `dispatch` calls (each optionally opening its own `compensates`
         # via the nested `DispatchBuilder`) that fire when this transition
         # is taken.
@@ -266,17 +266,17 @@ module Hecks
 
           def initialize = @dispatches = []
 
-          # THE COMMAND ITSELF (ADR 0025, "events and reactions" — command
+          # The command itself (ADR 0025, "events and reactions" — command
           # references become first-class), same shape and same reasons
           # as `PolicyBuilder#trigger`'s own header — bare constant live,
           # quoted text only under shadow-parsing (S0a's bridge; frozen
           # era text still writes `dispatch "Banking::Account.Debit"`).
           #
-          # RENAMED FROM `dispatch` — item #13's full metaprogrammed
+          # Renamed from `dispatch` — item #13's full metaprogrammed
           # dispatch (slice 4), same reasoning as trigger_impl above.
           #
-          # AN OPTIONAL BLOCK OPENS `compensates` ON THIS DISPATCH
-          # SPECIFICALLY — per-dispatch saga compensation, replacing a
+          # An optional block opens `compensates` on this dispatch
+          # specifically — per-dispatch saga compensation, replacing a
           # hand-written list at the saga's own `on :refused` leg. Real,
           # live bug this closes: `examples/banking/bluebook/transfers_
           # and_payments.bluebook`'s own `Settlement` saga wrote a
@@ -315,9 +315,9 @@ module Hecks
             spec
           end
 
-          # THE NESTED SCOPE `dispatch ... do ... end` OPENS — one word
+          # The nested scope `dispatch ... do ... end` opens — one word
           # only (`compensates`), the compensating half of the dispatch it
-          # sits inside. Its own `compensates_impl` builds a SECOND
+          # sits inside. Its own `compensates_impl` builds a second
           # `DispatchSpec`, shape-identical to `HandlerBuilder#dispatch_
           # impl`'s own — a compensation takes the exact same two
           # arguments (a bare command constant, an optional `with:`)

data/lib/hecks/bluebook/dsl/query_builder.rb

@@ -29,7 +29,7 @@ module Hecks
         # exactly like any other. No "acts on itself" case to
         # distinguish here the way a command's own reference_to has —
         # a query has no root of its own to act on, only parameters.
-        # RENAMED FROM `reference_to` — item #13's full metaprogrammed
+        # Renamed from `reference_to` — item #13's full metaprogrammed
         # dispatch (slice 4b). Bootstrap-reachable, in
         # GenericDispatch::BOOTSTRAP_CALLS_FALLBACK.
         def reference_to_impl(type, as: nil, optional: false)
@@ -69,14 +69,14 @@ module Hecks
 
         private
 
-        # A block parameter names one of the OWNER's (the aggregate or entity
+        # A block parameter names one of the owner's (the aggregate or entity
         # this query is declared on) own already-declared attributes —
         # `query "ForDecision" do |decision| where decision: :decision end`
         # on Submission, whose own `attribute :decision, DecisionRef` already
         # says what `decision` is. Restating `attribute :decision, DecisionRef`
         # a second time inside the query was pure duplication; this derives
         # the same type from the owner instead. Only fills in a name the block
-        # body did NOT already declare explicitly (checked AFTER instance_eval
+        # body did not already declare explicitly (checked after instance_eval
         # runs, so an existing bluebook still spelling it out both ways keeps
         # working unchanged — this only removes the need to, never refuses
         # the choice to). A block parameter matching nothing on the owner is
@@ -90,8 +90,8 @@ module Hecks
             owner_attr = owner_attributes.find { |a| a.name == param_name }
             next unless owner_attr
 
-            # `Attribute.new` DIRECTLY, not the public `attribute(...)` DSL
-            # entry — `owner_attr.type` is already SPELLED (a demodulised
+            # `Attribute.new` directly, not the public `attribute(...)` DSL
+            # entry — `owner_attr.type` is already spelled (a demodulised
             # String, `Attribute#spell`'s own doing), not a bareword the
             # bluebook author typed, so it must not run through
             # `AttributeCollector#attribute`'s quoted-type refusal (ADR

data/lib/hecks/bluebook/dsl/read_model_builder.rb

@@ -23,7 +23,7 @@ module Hecks
           @description = value
         end
 
-        # RENAMED FROM `reference_to` — item #13's full metaprogrammed
+        # Renamed from `reference_to` — item #13's full metaprogrammed
         # dispatch (slice 4b). Bootstrap-reachable, in
         # GenericDispatch::BOOTSTRAP_CALLS_FALLBACK.
         def reference_to_impl(type, as: nil)
@@ -34,13 +34,13 @@ module Hecks
         end
 
         # Order-independent. `many:` is decided by comparing the included type
-        # against the reference target, so this used to REFUSE an include
+        # against the reference target, so this used to refuse an include
         # declared before the reference — a rule guarding an implementation
         # limitation rather than a truth about read models. The includes are
         # collected raw and resolved at build, when the reference is known, so
         # there is no rule left to enforce.
-        # RENAMED FROM `include`/`group_by` — item #13's full
-        # metaprogrammed dispatch (slice 4c). `include` IS bootstrap-
+        # Renamed from `include`/`group_by` — item #13's full
+        # metaprogrammed dispatch (slice 4c). `include` is bootstrap-
         # reachable (every core chapter's own `read_model` names which
         # aggregates it includes with it — a first grep dismissed this
         # as `Module#include` noise and was wrong; the cold-boot test
@@ -48,13 +48,13 @@ module Hecks
         # BOOTSTRAP_CALLS_FALLBACK; `group_by` is not (no core read_model
         # groups). The class-level `include WordGate` this file's own
         # class body uses is `Module#include`, a different receiver,
-        # unaffected by renaming this INSTANCE method either way.
+        # unaffected by renaming this instance method either way.
         def include_impl(type, as: nil)
           @includes ||= []
           @includes << [Naming.demodulise(type), as]
         end
 
-        # `on:` (ADR 0055) — OVERRIDES of `QuerySpecification::Common::DSL`'s
+        # `on:` (ADR 0055) — overrides of `QuerySpecification::Common::DSL`'s
         # shared `where_impl`/`order_by_impl`/`limit_impl`/`offset_impl`,
         # scoped to `ReadModelBuilder` alone rather than added to the shared
         # module `Query` also mixes in: a plain `query` has no
@@ -63,10 +63,10 @@ module Hecks
         # means a `Query`'s own `where(..., on: X)` gets Ruby's own loud
         # `unknown keyword: :on` instead of quietly doing nothing.
         #
-        # `on:` names the target by TYPE (`on: Character`), resolved the
+        # `on:` names the target by type (`on: Character`), resolved the
         # same way `reference_to`/`include` already resolve their own type
         # argument (`Naming.demodulise`) — not by the include's own `as:`
-        # alias. A read model that `include`s the SAME type twice under two
+        # alias. A read model that `include`s the same type twice under two
         # different `as:` has no way to say which one `on:` means today; no
         # real corpus read model does this, so it's a real, deliberate scope
         # limit (see ADR 0055), not an oversight.
@@ -77,14 +77,14 @@ module Hecks
         # `status: "disputed"` captured as `**kwargs` (GenericDispatch's own
         # `builder.send(calls, *args, **kwargs, &block)`), and Ruby stops
         # auto-converting a bare `**hash` call into a plain positional Hash
-        # THE MOMENT a method declares any real keyword parameter — so a
+        # the moment a method declares any real keyword parameter — so a
         # `(clauses, on: nil)` signature raised "wrong number of arguments
         # (given 0, expected 1)" on every ordinary `where(field: value)`
         # call, never reaching `on:` at all. `**rest` sidesteps this: Ruby
         # still auto-splits `on:` into the declared keyword and gathers
-        # every OTHER key into `rest` regardless of how the caller wrote it.
+        # every other key into `rest` regardless of how the caller wrote it.
         #
-        # `QuerySpecification::Common::WhereClause` etc — FULLY QUALIFIED,
+        # `QuerySpecification::Common::WhereClause` etc — fully qualified,
         # not the bare names `dsl.rb`'s own shared `where_impl` gets away
         # with. That file is lexically nested inside `Common` itself, so
         # `WhereClause` resolves directly; this class is nested inside
@@ -92,7 +92,7 @@ module Hecks
         # `QuerySpecification::Common` at all — a bare `WhereClause` here
         # falls through to `const_missing` and, mid-bluebook-load, that's
         # `ConstShim`, which resolves it against the self-hosted grammar
-        # domain's OWN unrelated `WhereClause` construct instead (a `Module`,
+        # domain's own unrelated `WhereClause` construct instead (a `Module`,
         # not this `Struct`) — found directly by reproducing "undefined
         # method `new' for module WhereClause" against a real corpus load,
         # not guessed.
@@ -120,18 +120,18 @@ module Hecks
           @offset = QuerySpecification::Common::OffsetSpec.new(value: value, target: resolve_target(on))
         end
 
-        # NAMES which of the eligible head's own fields to nest its rows
+        # Names which of the eligible head's own fields to nest its rows
         # under — one level per field, the leaf being that row with the
         # named fields removed (they're already spent, as the keys that
         # reached it). The same "exactly one many-side head" rule
         # `seal_query_options` already enforces for where/order_by/etc
         # applies here too (`seal_group_by`) — grouping is a question
-        # about ONE collection's own rows, same as those are.
+        # about one collection's own rows, same as those are.
         def group_by_impl(*fields)
           # Hash rows, `{field:}`, not bare symbols — same shape
           # `aggregate_heads` already uses for exactly the reason it
           # does: the language's own self-hosted grammar (`projection
-          # .bluebook`'s `GroupByField`) has to have SOMETHING to read a
+          # .bluebook`'s `GroupByField`) has to have something to read a
           # `field:` off of when `Judge` walks this list generically: a
           # bare `Symbol` has no attribute of its own to read.
           @group_by = fields.map { |field| { field: field.to_sym } }
@@ -139,23 +139,23 @@ module Hecks
 
         # `count` -- a bare row count over the eligible many-side head's
         # own rows (after `where`/`order_by`/`limit`/`offset` apply, the
-        # same rows `group_by` itself would nest) -- ANSWERS "how many
-        # match", not "which ones". A sibling REDUCTION to `group_by`,
+        # same rows `group_by` itself would nest) -- answers "how many
+        # match", not "which ones". A sibling reduction to `group_by`,
         # not a filter: `seal_aggregation` refuses combining it with
         # `group_by` or with `median`, the same "exactly one many-side
         # head" rule `seal_group_by` already enforces for the same
         # reason -- a bare marker, so `@count` is left unset (nil, not
-        # false) rather than defaulted, matching the "ABSENT is not
-        # EMPTY" reading `Lifecycle`'s own optional fields already rely
+        # false) rather than defaulted, matching the "absent is not
+        # empty" reading `Lifecycle`'s own optional fields already rely
         # on for the Judge's setter dispatch (Behaviour::ReadModel#
         # count?, ReadModelInterpreter#aggregation_target).
         # `count` — item #13's full metaprogrammed dispatch, slice 1
-        # (whole-project table-unification survey): the ONLY Keyword row
+        # (whole-project table-unification survey): the only Keyword row
         # filling `count` — a bare marker, now stored as literal `true`
         # by `GenericDispatch` off that same table fact.
 
-        # `median(field)` -- the median VALUE of one numeric field
-        # across the eligible many-side head's own rows. EVEN COUNT: the
+        # `median(field)` -- the median value of one numeric field
+        # across the eligible many-side head's own rows. Even count: the
         # average of its two middle values (the standard definition,
         # not "the lower of the two") -- see
         # Runtime::ReadModelInterpreter#median for where that lands and
@@ -168,16 +168,16 @@ module Hecks
         # same shape as `count`, above (a bare, kind-driven coerce-and-
         # assign).
 
-        # `reference_to` is now OPTIONAL — a read model with no root is a
-        # BULK one: every `include`d head reads its own aggregate whole
+        # `reference_to` is now optional — a read model with no root is a
+        # bulk one: every `include`d head reads its own aggregate whole
         # (no FK match against a root that doesn't exist), and dispatch
-        # takes no id argument at all. This used to be REQUIRED, on the
+        # takes no id argument at all. This used to be required, on the
         # assumption a read model was always "one root record's own
         # cross-aggregate view" — true of every real corpus report so
         # far, but not a truth about read models themselves: `group_by`'s
-        # own real use (nesting an aggregate's OWN whole table by its own
+        # own real use (nesting an aggregate's own whole table by its own
         # field values) has no root to speak of. Still needs to describe
-        # SOMETHING — zero includes AND no reference is refused.
+        # something — zero includes and no reference is refused.
         def build
           if !@reference_target && Array(@includes).empty?
             raise Malformed,
@@ -213,18 +213,18 @@ module Hecks
         # (the "one" side, the reference target itself, is a single row;
         # ordering, paging, or tenant-scoping one row means nothing). ADR
         # 0055 gave `where`/`order_by`/`limit`/`offset` an `on:` to name
-        # WHICH many-side collection they mean, so this asks two questions
+        # which many-side collection they mean, so this asks two questions
         # now instead of one:
         #
         #   1. Does every declared `on:` actually name a many-side included
         #      aggregate? Checked regardless of how many many-side heads
         #      exist — a typo refuses immediately, not only once ambiguity
         #      would otherwise bite.
-        #   2. Is there still an UNTARGETED option declared (including
+        #   2. Is there still an untargeted option declared (including
         #      `authorize`'s own `tenant:`, which has no `on:` of its own —
         #      a real, deliberate scope limit, see ADR 0055)? An untargeted
         #      option still needs exactly one many-side head to mean
-        #      anything unambiguous — the ORIGINAL rule, unchanged, and
+        #      anything unambiguous — the original rule, unchanged, and
         #      still worded the same way (`spec/runtime/
         #      read_model_interpreter_spec.rb`'s existing refusal regex
         #      still matches).
@@ -246,7 +246,7 @@ module Hecks
         end
 
         # Question 1 of `seal_query_options`'s own two, split out to keep
-        # both under the same "one job per method" shape every OTHER seal in
+        # both under the same "one job per method" shape every other seal in
         # this file already holds to (each raises its own one Malformed, for
         # its own one reason).
         def validate_declared_targets!(many)
@@ -275,7 +275,7 @@ module Hecks
         end
 
         # Same shape as `seal_query_options`, same reason — `group_by`
-        # answers a question about ONE collection's own rows, so zero or
+        # answers a question about one collection's own rows, so zero or
         # several many-side heads leaves it with no unambiguous target.
         def seal_group_by
           return unless @group_by&.any?
@@ -289,10 +289,10 @@ module Hecks
                 "own rows; name which one by including only it"
         end
 
-        # `count`/`median` are the OTHER two reductions a read model may
+        # `count`/`median` are the other two reductions a read model may
         # declare over its one eligible collection — same "exactly one
         # many-side head" rule as `seal_group_by`, plus a rule
-        # `seal_group_by` doesn't need: a read model reports ONE shape,
+        # `seal_group_by` doesn't need: a read model reports one shape,
         # so `count` and `median` cannot both be declared, and neither
         # may combine with `group_by` (nesting rows and reducing them to
         # a scalar are answers to different questions ; a caller asking