hecks 1.3.0 → 1.5.0

data/lib/hecks/bluebook/meta_validator/judge.rb

@@ -3,34 +3,35 @@ module Hecks
     module MetaValidator
       # Offers every declaration in a built bluebook to the meta-domain.
       #
-      # This used to be one hand-written branch per category, and the cost of that
-      # shape was fourteen verbs the language declared and the judge never offered
-      # — among them `Command.Argument` and `ValueObject.Field`, so a command's own
-      # arguments and a value object's own fields were NEVER judged. Every rule
-      # hanging off them was decoration. Nothing went red, because a branch that
-      # does not exist cannot fail.
+      # There are no hand-written branches, one per category: that shape's
+      # real cost is any verb the language declares that the judge never
+      # offers — a branch nobody wrote for it — going undetected, since a
+      # branch that does not exist cannot fail. `Command.Argument` and
+      # `ValueObject.Field` were both admitted that way once, undetected;
+      # every rule hanging off them was decoration until offered for real.
       #
-      # So there are no branches. The judge WALKS: it reads the plan the language
-      # makes of itself (Plan), and for each node offers the creating command, then
-      # each list through the command that appends to it, then each child. A verb
-      # in the plan with no offer is now impossible — there is no branch left in
-      # which to forget one, and spec/judge_coverage_spec holds it to that.
+      # So instead the judge walks: it reads the plan the language makes of
+      # itself (Plan), and for each node offers the creating command, then
+      # each list through the command that appends to it, then each child. A
+      # verb in the plan with no offer is now impossible — there is no
+      # branch left in which to forget one, and spec/judge_coverage_spec
+      # holds it to that.
       #
-      # What is NOT uniform lives in Readings, and only where the IR's SHAPE
+      # What is not uniform lives in Readings, and only where the IR's shape
       # differs from the language's. Naming differences do not appear at all: the
       # language spells its fields as the IR spells them.
       #
-      # Only the DISPATCH half of the round trip lives here. Reconstruction is the
+      # Only the dispatch half of the round trip lives here. Reconstruction is the
       # experiment's business ; judging does not need it.
       class Judge
         include Readings
 
-        # Children offered BEFORE the parent's own lists, IN THIS ORDER. An
+        # Children offered before the parent's own lists, in this order. An
         # attribute's type is offered as the id of the thing it names, so the
         # value objects have to exist before anything that can name one — an
-        # aggregate's own attributes, AND an entity's own (M13: an entity is its
+        # aggregate's own attributes, and an entity's own (M13: an entity is its
         # own root, repeating the aggregate's whole shape one level down, so its
-        # attributes resolve against the SAME value-object pool). ValueObject
+        # attributes resolve against the same value-object pool). ValueObject
         # first, Entity second, so an entity's own attributes are never offered
         # before the value objects they may reference exist — a self-hosting
         # casualty found live: the meta-grammar's own Handler/Dispatch/Member/
@@ -43,7 +44,7 @@ module Hecks
         # see `detail_node`'s own use of this constant, below.
         EAGER_CHILDREN = { "Aggregate" => %w[ValueObject Entity] }.freeze
 
-        # Categories an ENTITY declares as well as an aggregate. The IR reuses
+        # Categories an entity declares as well as an aggregate. The IR reuses
         # Command and Query for a piece's own commands and queries, so the
         # language reuses Command and Query — and the plan cannot express a second
         # parent, because a category's parent is derived from the one `*_id` argument
@@ -52,15 +53,17 @@ module Hecks
 
         attr_reader :refusals
 
-        # THE RECORDS SURVIVE THE VERDICT.
+        # **The records survive the verdict**.
         #
-        # Judging a bluebook and HOLDING one differ by exactly this: whether anyone
+        # Judging a bluebook and holding one differ by exactly this: whether anyone
         # keeps the runtime the declarations were dispatched into. Nobody did, so
         # `spec/round_trip_spec` reached the records by `Judge.allocate` and four
         # `instance_variable_set` calls. Reading the chapter back is the point now,
         # not a curiosity, so the runtime is simply readable.
         attr_reader :runtime
 
+        # @param bluebook [Object] a built bluebook chapter graph, as
+        #   `MetaValidator.call` receives it
         def initialize(bluebook)
           @bluebook = bluebook
           @refusals = []
@@ -71,7 +74,7 @@ module Hecks
 
         private
 
-        # ABSENT is not EMPTY. The rules read "if you declare it, declare
+        # Absent is not empty. The rules read "if you declare it, declare
         # something" — a description never given is legal. Passing "" for a nil
         # turns every one of them into "you must declare it".
         #
@@ -85,7 +88,7 @@ module Hecks
           { value: text.to_s }
         end
 
-        # A REFERENCE IS AN ID, AND AN ID IS A SCALAR.
+        # A reference is an ID, and an ID is a scalar.
         #
         # Every other field goes to the meta-domain as a one-field value object,
         # because that is what it is. A reference is not: it carries the id of a
@@ -105,31 +108,45 @@ module Hecks
           yield
         rescue Runtime::GivenNotMet, Runtime::InvariantViolation,
                Runtime::TypeMismatch, Runtime::NotFound => e
-          # NotFound is a VERDICT, not noise. An attribute's type is a reference to
-          # its value object, so "no ValueObject with id …" IS the rule `attributes
+          # NotFound is a verdict, not noise. An attribute's type is a reference to
+          # its value object, so "no ValueObject with id …" is the rule `attributes
           # must use value-object types` refusing.
           @refusals << "#{label}: #{e.message}"
         rescue Runtime::UnknownVerb
           nil
         end
 
+        # QualityControl BUG#125 — every dispatch the judge makes into the
+        # meta-domain goes through here, and only here, so this is the one
+        # place `Runtime::Value.judge_bootstrapping` needs to wrap: it tells
+        # `Value::Coercion#check_scalar_shapes` this construction is the
+        # language's own self-hosted grammar walk, not a real domain's
+        # command, so a String-typed meta-grammar field (`Normalise`'s
+        # `position`, a `RuleText` — `appends`' generic walk-index handling
+        # collides with that field's own name, see the flag's own comment
+        # in coercion.rb) may still arrive as the raw Integer `appends`
+        # hands it. Scoped to exactly this method: nothing outside a judge's
+        # own dispatch ever runs inside it, so an ordinary domain command
+        # (a real caller's own PieceId, Money, …) is never affected.
         def send_to(verb, label, to: nil, **payload)
-          offer(label) { @runtime.dispatch(verb, to: to, with: args(payload)) }
+          Runtime::Value.judge_bootstrapping do
+            offer(label) { @runtime.dispatch(verb, to: to, with: args(payload)) }
+          end
         end
 
-        # THE RECEIVER, SPELLED THE WAY A REAL CALLER ADDRESSES IT.
+        # The receiver, spelled the way a real caller addresses it.
         #
         # `receiver` is an internal accumulator — it tracks the aggregate this
-        # walk is inside AND, once it crosses into a real entity-owned category
+        # walk is inside and, once it crosses into a real entity-owned category
         # (Member/Handler/Dispatch — S17, ADR 0026), every entity hop on top of
         # it. But `Routing.envelope`/`parse_envelope_hash` do not want that
         # shape restated when there is no entity to route to: a plain aggregate
         # command is addressed by its bare id (`Facade::Handle#dispatch` — "to:
         # @id" — and `CommandRequest`'s own header: "aggregate command: { to:
         # "record-id", ... }"), never `{aggregate:, entities: []}` — that hash
-        # is the ENTITY route's own shape, degenerate with nothing in it.
+        # is the entity route's own shape, degenerate with nothing in it.
         #
-        # So THIS is the one place `receiver` turns into a `to:` value: bare
+        # So this is the one place `receiver` turns into a `to:` value: bare
         # when there is no entity hop (the overwhelming common case — every
         # category but those three), the full envelope only when there
         # genuinely is one.
@@ -144,19 +161,19 @@ module Hecks
           detail_node("Bluebook", @bluebook, nil, 0)
         end
 
-        # DECLARED BEFORE DETAILED, for every set of siblings.
+        # Declared before detailed, for every set of siblings.
         #
-        # A node used to be offered whole — declared, then its lists, then its
-        # children — one sibling at a time. Which means an aggregate's attributes
-        # were offered before its later siblings existed, and an attribute that
-        # POINTS AT another aggregate could only resolve if that aggregate happened
-        # to be declared earlier in the file. Banking survives on luck: Customer is
-        # written above Account.
+        # Offering a node whole — declared, then its lists, then its children
+        # — one sibling at a time would mean an aggregate's attributes are
+        # offered before its later siblings exist, so an attribute that
+        # points at another aggregate could only resolve if that aggregate
+        # happens to be declared earlier in the file: banking would survive
+        # on luck, Customer written above Account.
         #
         # So siblings are declared in one pass and detailed in a second. It is the
         # same ordering the walk already used one level down — value objects before
         # the attributes that name them — lifted to the level above, and it is what
-        # lets a reference be a REFERENCE rather than a string nobody can check.
+        # lets a reference be a reference rather than a string nobody can check.
         def declare_node(category, node, parent_id, index, extra = {}, receiver: nil)
           plan = @plan.category(category)
           return unless plan
@@ -169,34 +186,34 @@ module Hecks
           return unless plan
 
           id = identify(category, parent_id, node, index)
-          # `extra` is the CUMULATIVE identity of every entity-owned
-          # ancestor above this node (Handler's own `event_type` AND
+          # `extra` is the cumulative identity of every entity-owned
+          # ancestor above this node (Handler's own `event_type` and
           # ProcessManager's own `bluebook`/`name`, by the time Dispatch
           # is reached — S17, ADR 0026's two-level chain). `identity`
-          # adds THIS node's own on top — computed for EVERY category,
+          # adds this node's own on top — computed for every category,
           # entity-owned or not, because a node need not be entity-owned
-          # itself to OWN one (ValueObject isn't, and Member still needs
-          # its `aggregate:`/`name:`) — it is simply what THIS node's own
+          # itself to own one (ValueObject isn't, and Member still needs
+          # its `aggregate:`/`name:`) — it is simply what this node's own
           # `identified_by` resolves to, the same fields `identify` two
-          # lines up already derives the joined id FROM.
+          # lines up already derives the joined id from.
           #
-          # `own` is the SUBSET actually spent on a dispatch payload —
-          # only when THIS category is itself entity-owned, since an
+          # `own` is the subset actually spent on a dispatch payload —
+          # only when this category is itself entity-owned, since an
           # ordinary category (Command's own "Rule"/"Argument", offered
-          # through the SAME `extra` SLOT for a DIFFERENT reason, see
+          # through the same `extra` slot for a different reason, see
           # `within_entity` below) locates the record it attaches to
           # through the parent id `id:` already carries, and merging
-          # unrecognized `aggregate:`/`entity_id:` into THEIR payload
+          # unrecognized `aggregate:`/`entity_id:` into their payload
           # would have the runtime refuse them for an argument they
           # never declared.
           identity     = extra.merge(node_identity(plan, category, node, index, parent_id))
           receiver   ||= { aggregate: id, entities: [] }
           eager, later = children_of(category).partition { |child| eager?(category, child) }
-          # ORDERED AS `EAGER_CHILDREN` DECLARES, not as `children_of` happens to
+          # Ordered as `EAGER_CHILDREN` declares, not as `children_of` happens to
           # list them — `children_of` reads `@plan.names`, whose own order is an
           # accident of which .bluebook file registered which category first,
           # never a promise about which of two eager children exists before the
-          # other. `EAGER_CHILDREN`'s own array IS that promise (ValueObject
+          # other. `EAGER_CHILDREN`'s own array is that promise (ValueObject
           # before Entity), so the walk keeps only what this parent actually
           # has, in the order the constant states — see that constant's own
           # comment for the bug this exact reordering fixes.
@@ -204,12 +221,12 @@ module Hecks
 
           eager.each { |child| walk_all(child, node, id, entity_child_extra(child, identity), receiver: receiver) }
           setters(plan, category, node, receiver)
-          # BEFORE `appends`, not after — the same reason `EAGER_CHILDREN`
-          # walks an aggregate's OWN entities before its OWN attributes
+          # Before `appends`, not after — the same reason `EAGER_CHILDREN`
+          # walks an aggregate's own entities before its own attributes
           # (M13): a piece nested inside a piece (Handler's own
           # `dispatches, list_of(Dispatch)` — S17, ADR 0026) must exist
           # before this piece's own attribute list can reference it as a
-          # HELD entity, the same way `Account#ledger` needs Account's own
+          # held entity, the same way `Account#ledger` needs Account's own
           # entities walked eagerly. `nest_entities` is a no-op for every
           # category but "Entity" (its own early return), so reordering it
           # ahead of `appends` costs nothing for anything else that walks
@@ -221,11 +238,11 @@ module Hecks
           sealers(plan, category, receiver)
         end
 
-        # WHAT A CHILD'S OWN `extra` STARTS FROM. An entity-owned child's
-        # own dotted dispatch needs every ANCESTOR's identity, which is
+        # What a child's own `extra` starts from. An entity-owned child's
+        # own dotted dispatch needs every ancestor's identity, which is
         # exactly `identity` — already accumulated one level at a time by
         # `detail_node` itself (regardless of whether each ancestor is
-        # ITSELF entity-owned — ValueObject contributes its own `aggregate:
+        # itself entity-owned — ValueObject contributes its own `aggregate:
         # `/`name:` to Member's payload despite being an ordinary top-
         # level category), so there is nothing left to re-derive here. An
         # ordinary child (one with a real top-level aggregate of its own
@@ -234,15 +251,15 @@ module Hecks
           @plan.category(child)&.entity_owned ? identity : {}
         end
 
-        # ONE NODE'S OWN IDENTITY, read off its own declaration — S17,
+        # One node's own identity, read off its own declaration — S17,
         # ADR 0026. Three cases, the same three `identify`/`identity_part`
         # already resolve one level up, unified here because a chain now
         # walks more than one level (Handler -> Dispatch) and each level
-        # needs the SAME three answered about itself, not just the first:
+        # needs the same three answered about itself, not just the first:
         #
         #   the parent link   (plan.parent_key)   -> `parent_id`, the id
         #                     the walk already carries in from one level up
-        #   a walk-minted one (POSITION)           -> the walk INDEX itself ;
+        #   a walk-minted one (`POSITION`)         -> the walk index itself ;
         #                     never a stored field (Member's own header:
         #                     "position is not a mint — it is read straight
         #                     out of the source file")
@@ -251,12 +268,12 @@ module Hecks
         #                     (Handler's own `event_type`, Dispatch's own
         #                     `command_name`)
         #
-        # `carried` still decides bare-vs-wrapped the normal way ; POSITION
+        # `carried` still decides bare-vs-wrapped the normal way ; `POSITION`
         # is the one case with no verb to ask `carried` about (`plan.
         # declare` is always nil for an entity-owned category — Plan#read's
         # own comment says why), so it is minted straight as a value object,
         # matching exactly what `declare`'s own field loop already mints a
-        # POSITION field as.
+        # `POSITION` field as.
         def node_identity(plan, category, node, index, parent_id)
           plan.identity_paths.each_with_object({}) do |path, fields|
             head = path.to_s.split(".").first
@@ -271,9 +288,9 @@ module Hecks
           end
         end
 
-        # THE FULL DOTTED PREFIX a category's own verbs hang off — the
+        # The full dotted prefix a category's own verbs hang off — the
         # plain name for an ordinary category (its own top-level
-        # aggregate reaches every verb bare), or its PARENT's own prefix
+        # aggregate reaches every verb bare), or its parent's own prefix
         # with this category's name appended, for an entity-owned one.
         # Dispatch's own parent, Handler, is itself entity-owned (S17,
         # ADR 0026's two-level chain — `ProcessManager.Handler.Dispatch`),
@@ -284,9 +301,9 @@ module Hecks
           "#{dotted_prefix(@plan.category(plan.parent))}.#{plan.name}"
         end
 
-        # ENTITY-OWNED categories have no top-level aggregate for the runtime
+        # Entity-owned categories have no top-level aggregate for the runtime
         # to route a bare verb into any more — `Member`'s own "Pair" reaches
-        # the runtime as `ValueObject.Member.Pair`, and a NESTED one
+        # the runtime as `ValueObject.Member.Pair`, and a nested one
         # (`Dispatch`, inside `Handler`) reaches it as `ProcessManager.
         # Handler.Dispatch.Bind` — the dotted shape `EntityInterpreter#call`
         # already splits any real entity's own verb into, one hop per
@@ -312,12 +329,12 @@ module Hecks
           end
         end
 
-        # A piece's commands and queries, addressed under the PIECE so two commands
+        # A piece's commands and queries, addressed under the piece so two commands
         # of the same name on an aggregate and on one of its entities cannot collide,
         # while `aggregate` still names the aggregate the reference resolves
         # against and `entity_id` says which piece declared it. `entity_id`
-        # keeps its own `_id` — an EXPLICIT `as:` on `reference_to Entity`,
-        # never touched by ADR 0025's rename (only the DEFAULT, un-aliased
+        # keeps its own `_id` — an explicit `as:` on `reference_to Entity`,
+        # never touched by ADR 0025's rename (only the default, un-aliased
         # mint dropped the suffix; `aggregate` did precisely because
         # `Command#reference_to Aggregate`/`Query#reference_to Aggregate`
         # carry no `as:` of their own).
@@ -333,26 +350,26 @@ module Hecks
           end
         end
 
-        # AN ENTITY MAY NEST FURTHER ENTITIES — S17, ADR 0026's own words:
+        # An entity may nest further entities — S17, ADR 0026's own words:
         # "That is what `entity` is for, and `entity` is declared by the
         # language and used zero times in it." `Dispatch`, inside
-        # `Handler`, is the first real use. The GENERIC "Entity" category
+        # `Handler`, is the first real use. The generic "Entity" category
         # cannot express this through `children_of`/`EAGER_CHILDREN` the
         # way Aggregate's own entities/value_objects can — there is only
-        # ONE "Entity" Plan category, describing what ANY entity looks
+        # one "Entity" Plan category, describing what any entity looks
         # like, not one per nesting level — so this recurses by hand,
         # the same special case `within_entity` (above) already is for
         # Command/Query.
         #
         # `owner` is the field this repurposes — `entity.bluebook`
         # declares it (`attribute :owner, EntityText`) and it has held
-        # exactly one value since ADR 0025's rename: the SAME id
-        # `aggregate` already carries, kept as a wrapped-text COPY,
+        # exactly one value since ADR 0025's rename: the same id
+        # `aggregate` already carries, kept as a wrapped-text copy,
         # never read back anywhere else in this codebase (grep finds no
-        # second reference). For a NESTED entity, the two finally
-        # diverge — `aggregate` stays the ROOT (Dispatch resolves
+        # second reference). For a nested entity, the two finally
+        # diverge — `aggregate` stays the root (Dispatch resolves
         # exactly the way any other Entity record does, by its root
-        # aggregate), and `owner` becomes THIS entity's own DIRECT
+        # aggregate), and `owner` becomes this entity's own direct
         # parent (Handler, not ProcessManager) — which is exactly the
         # fact `Reconstruction#direct_entities` needs to tell a
         # root-level entity apart from a nested one sharing the same
@@ -367,13 +384,14 @@ module Hecks
                    })
         end
 
-        # WHERE IT SITS AMONG ITS SIBLINGS IS A FACT ABOUT THE WALK, not about the
+        # Where it sits among its siblings is a fact about the walk, not about the
         # node : a command does not know it is the third command on its aggregate.
         # The walk knows, so the walk supplies it, and every other field still
-        # comes from the node. Declaration order used to survive only because the
-        # meta store happened to iterate in insertion order — an accident that an
-        # ask ordered any other way would have taken away, and Reconstruction is
-        # the one reader that must have the SOURCE'S order rather than a stable one.
+        # comes from the node. Without this, declaration order would survive only
+        # because the meta store happens to iterate in insertion order — an
+        # accident that an ask ordered any other way would take away, and
+        # Reconstruction is the one reader that must have the source's order
+        # rather than a stable one.
         # `private` above has no effect on a constant; kept here anyway,
         # beside the method that reads it, for the narrative.
         # rubocop:disable-next Lint/UselessConstantScoping
@@ -416,7 +434,7 @@ module Hecks
           plan.appends.each do |list_name, append|
             rows_for(category, list_name, node).each_with_index do |row, index|
               chosen = append_for(category, list_name, append, row, node)
-              # `position` IS THE WALK INDEX here exactly as it is in `declare` —
+              # `position` is the walk index here exactly as it is in `declare` —
               # an appended element that names its position (ValueObject.Member,
               # S17) is ordered by where the walk found it, never by a field the
               # row happens to hold.
@@ -436,15 +454,15 @@ module Hecks
           end
         end
 
-        # WHICH AGGREGATE OWNS THE VALUE OBJECTS an attribute's TYPE may
+        # Which aggregate owns the value objects an attribute's type may
         # resolve against. An aggregate owns its own — `id` already names
         # it. An entity never has value objects of its own (Entity
         # deliberately never answers `value_object` — see entity.rb's own
-        # comment on why); its attributes read the SAME pool its
+        # comment on why); its attributes read the same pool its
         # enclosing aggregate declares, one level up the construct tree
         # no matter how many entities deep this attribute is nested —
         # `parent_id` names it because `detail_node`/`nest_entities`
-        # thread the ROOT aggregate's id down as `parent_id` at every
+        # thread the root aggregate's id down as `parent_id` at every
         # entity level, never the direct (possibly entity) parent.
         def owning_aggregate_ref(category, id, parent_id)
           category == "Entity" ? parent_id : id
@@ -455,30 +473,30 @@ module Hecks
           plan.sealers.each { |verb| send_to("Bluebook::#{verb_for(plan, verb)}", id, to: address(receiver)) }
         end
 
-        # An aggregate's or an entity's attribute names its value object by TYPE,
+        # An aggregate's or an entity's attribute names its value object by type,
         # and the language models that as a reference — so the type is offered as
         # the value object's own id. This is the rule "attributes must use
         # value-object types", enforced by reference resolution rather than by a
-        # predicate — for a HEAD's own attributes, aggregate or entity alike: an
+        # predicate — for a head's own attributes, aggregate or entity alike: an
         # entity is its own root, repeating the aggregate's whole shape one level
         # down (entity.rb's own words), and an undeclared type on an entity's
         # attribute must fail the same reference resolution an aggregate's own
         # does, not go unchecked because only "Aggregate.attributes" was ever
         # asked.
-        # An attribute's type is offered as the ID OF THE THING IT NAMES, so the
+        # An attribute's type is offered as the ID of the thing it names, so the
         # language resolves it as a reference and "the type is declared" costs no
         # predicate. Three kinds, three ids: a value object and an entity both hang
         # off this aggregate, so they share its prefix; another aggregate's head
         # hangs off the chapter.
         def cell(category, list_name, row, field, id, append, aggregate_id)
           value = row_value(row, field)
-          # A default keeps its TYPE by being written as a literal — 0.0 rather than
+          # A default keeps its type by being written as a literal — 0.0 rather than
           # "0.0" — because the language holds it as text and text alone forgets.
           return encode_literal(value) if field == :default
           return value unless field == :type
-          # A REFERENCE names another head WHEREVER it is written — on a head, on
+          # A reference names another head wherever it is written — on a head, on
           # a command, on a piece, on an ask — so it is offered as that head's
-          # id in all four. Only a HEAD's own attributes additionally qualify
+          # id in all four. Only a head's own attributes additionally qualify
           # an ordinary type into a value object's id ; a command argument's
           # type is text and stays text.
           return points_at(row, id) if append.verb == "Reference"
@@ -487,7 +505,7 @@ module Hecks
           Naming.identity([owning_aggregate_id(aggregate_id, value), value])
         end
 
-        # A HEAD'S OWN ATTRIBUTES — an aggregate's, or an entity's (its own root,
+        # A head's own attributes — an aggregate's, or an entity's (its own root,
         # one level down). Every other "attributes" list belongs to something that
         # is not a head at all (a command's arguments, a value object's own
         # fields), and a type written there is a name, not a reference — the same
@@ -496,27 +514,27 @@ module Hecks
           list_name.to_s == "attributes" && %w[Aggregate Entity].include?(category)
         end
 
-        # `id` NAMES THE ATTRIBUTE'S OWN AGGREGATE, not necessarily the
+        # `id` names the attribute's own aggregate, not necessarily the
         # value object's — Wave 7's own translation.bluebook/translation_
         # aggregate.bluebook split proved the difference live:
         # TranslationAggregate's own `was`/every rename-rule's own `from`/
-        # `to`/... all deliberately reuse the SIBLING "Translation"
+        # `to`/... all deliberately reuse the sibling "Translation"
         # aggregate's own `TranslationName` (that file's own header:
         # "the shared TranslationName every non-identity field below
         # uses"), a real, intentional cross-aggregate reuse — not the
-        # local-only ownership every OTHER real domain in this corpus
+        # local-only ownership every other real domain in this corpus
         # happens to have used until now.
         #
         # `id` (already `Naming.identity([chapter, aggregate])`-joined)
-        # only ever composes with the LOCAL aggregate for real, non-
+        # only ever composes with the local aggregate for real, non-
         # entity-owned attributes — an entity's own `id` never matches
-        # any TOP-LEVEL aggregate here, so `local` stays nil and this
+        # any top-level aggregate here, so `local` stays nil and this
         # returns `id` unchanged, exactly the prior behavior. Same for
-        # every attribute whose type IS locally declared (the overwhelming
+        # every attribute whose type is locally declared (the overwhelming
         # common case, Banking's own Customer/Account included) — this
-        # only ever changes the answer when the local aggregate does NOT
+        # only ever changes the answer when the local aggregate does not
         # declare `value` itself, falling back to the first (declaration-
-        # order) OTHER aggregate in the SAME chapter that does.
+        # order) other aggregate in the same chapter that does.
         def owning_aggregate_id(id, value)
           local = @bluebook.aggregates.find { |aggregate| Naming.identity([@bluebook.name, aggregate.name]) == id }
           return id unless local
@@ -549,13 +567,13 @@ module Hecks
         #   Reference  its type is Reference<X>, another aggregate's head
         #   Holds      its type names an entity this aggregate declares
         #
-        # NOTHING IS SKIPPED any more. Reference and Holds did not exist, so the
+        # Nothing is skipped any more. Reference and Holds did not exist, so the
         # walk dropped both kinds and the meta-domain silently did not contain
         # Account#customer_id or Account#ledger.
-        # Each alternate carries its OWN map, read from the language. Borrowing the
+        # Each alternate carries its own map, read from the language. Borrowing the
         # primary's map dispatched `type:` where Reference declares `points_at:`,
         # and the payload gate caught it — which is the gate paying for itself.
-        # `reference_to` can be written in FOUR places — on a head, a command, a
+        # `reference_to` can be written in four places — on a head, a command, a
         # piece, an ask — and each keeps its own list of attributes, so each
         # needs the Reference alternate. Only a head can hold a piece, so Holds
         # stays where it was.
@@ -573,7 +591,7 @@ module Hecks
 
         def reference_row?(row) = row.respond_to?(:reference?) && row.reference?
 
-        # Only a HEAD declares pieces, and now that every attribute list reaches
+        # Only a head declares pieces, and now that every attribute list reaches
         # this, the node may be a command, a piece or an ask — none of which
         # answer `entities` at all.
         def entity_row?(row, node)
@@ -582,7 +600,7 @@ module Hecks
           Array(node.entities).any? { |entity| entity.hecks_name == row.type.to_s }
         end
 
-        # A RECORD'S ID IS ITS DECLARED IDENTITY, JOINED — the same join the runtime
+        # A record's ID is its declared identity, joined — the same join the runtime
         # does, off the same declaration, because there is only one way to name a
         # thing and it should be written once.
         #
@@ -602,14 +620,14 @@ module Hecks
           Naming.identity(plan.identity_paths.map { |path| identity_part(plan, path, parent_id, node, index, category) })
         end
 
-        # "owner_id" is a SECOND reserved head, beside `position` : it names
-        # whichever record is walking THIS one right now, aggregate or entity
+        # "owner_id" is a second reserved head, beside `position` : it names
+        # whichever record is walking this one right now, aggregate or entity
         # alike, without saying which — Command and Query read it so an
         # entity's verbs are the entity's own. It is never a declared
         # attribute (declaring one for a field that names two different types
         # would be a lie about which), so it cannot be read through
         # `field_value` ; it is read the same way `plan.parent_key` already is,
-        # because it IS that fact, spelled for the walk's immediate parent
+        # because it is that fact, spelled for the walk's immediate parent
         # rather than for one specific kind of one.
         # `private` above has no effect on a constant; kept here anyway,
         # beside the method that reads it, for the narrative.
@@ -640,8 +658,8 @@ module Hecks
 
         # Command -> commands, ValueObject -> value_objects, Query -> queries.
         # Convention, not a table : the IR names a collection after what it holds.
-        # The pluraliser lives in Naming because there used to be two of them and
-        # one was wrong — see Naming.plural.
+        # The pluraliser lives in Naming, kept to exactly one implementation — a
+        # second one risks disagreeing with it — see Naming.plural.
         def collection_reader(category) = Naming.plural(Naming.snake(category))
       end
     end