hecks 2.8.0 → 2.9.0

data/lib/hecks/bluebook/dsl/bluebook_builder/validation.rb

@@ -2,52 +2,20 @@ module Hecks
   module Bluebook
     module DSL
       class BluebookBuilder
-        # The self.validate_*/self.correlation_*/self.event_*/self.walk_*
-        # cluster — every whole-chapter, cross-aggregate check `#build`
-        # runs once a chapter is fully assembled (reference targets, event
-        # shapes, correlation keys, query hops, projected fields,
-        # bidirectional-reference cycles), plus each one's own private
-        # helpers. Split out of bluebook_builder.rb (which keeps the DSL
-        # surface — chapter/aggregate/read_model/policy declaration,
-        # `#build`, and `self.build`) for the same reason
-        # AggregateBuilder::Sealing exists: one cohesive concern, filed by
-        # responsibility rather than by an arbitrary line count.
-        #
-        # `extend`ed onto BluebookBuilder rather than `include`d — every
-        # one of these is a pure function of its own explicit arguments
-        # (an assembled `Bluebook::Chapter`, an aggregate list, ...), never
-        # builder-instance state (no `@ivar` read anywhere in this
-        # module), and every caller reaches these as
-        # `BluebookBuilder.validate_assembled!(...)` class-level calls,
-        # `#build`'s own `self.class.validate_assembled!` included.
-        # `extend` is `include`'s class-level counterpart: the same "one
-        # class, its methods, filed across files" pattern
-        # `Runtime::Registry` already uses (`include Verification`), just
-        # turning each method into a class (singleton) method instead of
-        # an instance method, the same role `def self.foo` fills on a
-        # class that keeps its methods in one file.
+        # Whole-chapter, cross-aggregate checks that `#build` runs once a chapter is assembled.
+        # Extended onto BluebookBuilder: pure functions of their arguments, no builder state.
         module Validation
-          # Runs every whole-chapter check against one fully assembled chapter.
+          # Runs every whole-chapter check against one assembled chapter.
+          # Public so `MetaValidator.judge_deferred!` can call it with no builder instance.
           #
-          # **Every whole-chapter check, in one place** — a pure function of an
-          # assembled `Bluebook::Chapter`, callable both from `#build` (right
-          # after assembly) and from `MetaValidator.judge_deferred!` (once, on
-          # a chapter whose files have all loaded — see `#build`'s own comment
-          # for why that split exists at all). Public, not
-          # `private_class_method`'d, for exactly that second caller —
-          # `MetaValidator` needs to reach this with no builder instance in
-          # hand, only the chapter `judge_deferred!` already read back out of
-          # the registry.
-          #
-          # @param bluebook [Bluebook::Chapter] the fully assembled chapter to validate
+          # @param bluebook [Bluebook::Chapter] the assembled chapter to validate
           # @return [void]
-          # @raise [Bluebook::DSL::Malformed] if any of the reference, event-shape, `with:`,
-          #   query-hop, projected-field or provision checks below finds a violation
-          # @raise [Bluebook::DSL::ProcessManagerBuilder::InvalidProcessManager] if a process
-          #   manager's `correlates_by` resolves to something other than a scalar field
+          # @raise [Bluebook::DSL::Malformed] if any check finds a violation
+          # @raise [Bluebook::DSL::ProcessManagerBuilder::InvalidProcessManager] if a
+          #   `correlates_by` resolves to something other than a scalar field
           def validate_assembled!(bluebook)
-            # moved to the language: an attribute type is a reference to its Shape,
-            # so an undeclared value object fails reference resolution
+            # an attribute type references its Shape, so an undeclared value object
+            # fails resolution
             validate_reference_value_objects!(bluebook.aggregates)
             validate_correlation_keys!(bluebook.process_managers, bluebook.aggregates)
             validate_no_bidirectional_references!(bluebook.aggregates)
@@ -56,40 +24,18 @@ module Hecks
               validate_with_projections!(bluebook.policies, bluebook.process_managers, bluebook.aggregates)
             end
 
-            # Every hop AggregateBuilder#seal_query_field recognised and
-            # deferred gets checked for real here — the earliest point a
-            # hop can be checked, for exactly the reason
-            # validate_no_bidirectional_references! above already gives:
-            # `Bluebook.new` just stamped `hecks_owner` on every
-            # aggregate, so `Reference#resolve` finally has a chapter to
-            # walk. Before this line every target in the file (including
-            # ones declared above the aggregate doing the asking) would
-            # have resolved to nil.
+            # Hops resolve only now: `Bluebook.new` has just stamped `hecks_owner` on
+            # every aggregate.
             infer_hop_query_arguments!(bluebook)
             validate_query_hops!(bluebook)
 
-            # Same precondition, same reason: a `projects` declaration's
-            # own reference cannot resolve until every aggregate in the
-            # chapter is real and owner-stamped (S12, ADR 0025).
+            # A `projects` reference needs the same owner-stamped aggregates to resolve (ADR 0025).
             validate_projected_fields!(bluebook)
 
             validate_provisions!(bluebook)
           end
 
           # Checks every `provides` row against `Capabilities::CONTRACTS`.
-          #
-          # **What a declared capability must name**. A `provides` row is only
-          # worth trusting in place of a name check if it is checked: an
-          # unknown capability, a missing or extra key, or a verb that is
-          # not this chapter's own command/query of the right kind would
-          # otherwise wire a role check to nothing, in silence.
-          #
-          # @param bluebook [Bluebook::Chapter] the chapter whose `provides` rows to check
-          # @return [void]
-          # @raise [Bluebook::DSL::Malformed] if a row names a capability
-          #   `Capabilities::CONTRACTS` does not know, its keys do not match the
-          #   capability's contract exactly, or a verb names no real command/query
-          #   of the declared kind
           def validate_provisions!(bluebook)
             bluebook.provides.group_by(&:capability).each do |capability, rows|
               contract = Capabilities::CONTRACTS.fetch(capability) do
@@ -107,17 +53,6 @@ module Hecks
             end
           end
 
-          # Checks that one `provides` row's verb names a real command or query.
-          #
-          # @param bluebook [Bluebook::Chapter] the chapter the row was declared on
-          # @param capability [String] the capability the row belongs to, such as
-          #   `"authorization"`
-          # @param row [Bluebook::Chapter::Provision] the one declared row to check
-          # @param kind [Symbol] `:command`, `:query` or `:port_operation`, the kind of
-          #   verb this row's key must name (from `Capabilities::CONTRACTS`)
-          # @return [void]
-          # @raise [Bluebook::DSL::Malformed] if `row.verb` does not split into a real
-          #   aggregate and a member of the right kind that aggregate declares
           def validate_provided_verb!(bluebook, capability, row, kind)
             return validate_provided_port_operation!(bluebook, capability, row) if kind == :port_operation
 
@@ -129,18 +64,9 @@ module Hecks
                              "which names no #{kind} this chapter declares (spelled \"Aggregate.#{kind.capitalize}\")"
           end
 
-          # Checks the spelling of a `provides` verb that names a hecksagon port
-          # operation. The port itself is declared in the hecksagon, which attaches
-          # after this chapter is built, so all that can be checked here is that the
-          # verb has the `"Aggregate.Port.Operation"` shape and its aggregate is
-          # this chapter's; `Registry#verify!` checks the operation exists.
-          #
-          # @param bluebook [Bluebook::Chapter] the chapter the row was declared on
-          # @param capability [String] the capability the row belongs to
-          # @param row [Bluebook::Chapter::Provision] the one declared row to check
-          # @return [void]
-          # @raise [Bluebook::DSL::Malformed] if the verb is not `"Aggregate.Port.Operation"`
-          #   or names an aggregate this chapter does not declare
+          # Only the verb's shape and aggregate are checkable here: the port is declared
+          # in the hecksagon, which attaches after the chapter is built. `Registry#verify!`
+          # checks the operation.
           def validate_provided_port_operation!(bluebook, capability, row)
             aggregate_name, port, operation = row.verb.split(".", 3)
             return if bluebook.aggregate(aggregate_name) && port && operation && !operation.include?(".")
@@ -149,44 +75,13 @@ module Hecks
                              "which is not spelled \"Aggregate.Port.Operation\" over an aggregate this chapter declares"
           end
 
-          # Names of the members a `provides` verb of the given kind may address.
-          #
-          # @param aggregate [Bluebook::Aggregate] the aggregate the verb is scoped to
-          # @param kind [Symbol] `:command` or `:query`
-          # @return [Array<String>] every command's `hecks_name` when `kind` is `:command`,
-          #   else every query's declared `name`
           def provided_member_names(aggregate, kind)
             kind == :command ? aggregate.commands.map(&:hecks_name) : aggregate.queries.map(&:name)
           end
 
-          # Refuses an entity command that names itself as its own root.
-          #
-          # That is the whole of what is left here, and it needs saying plainly:
-          # the refusal message once read "references must target aggregate
-          # heads," a claim broader than what this actually checks.
-          #
-          # `CommandBuilder#reference_to` sets `references` only when the target's
-          # bare name equals the owner's ; anything else becomes a reference
-          # attribute. So on an aggregate command `references` is always a copy of
-          # that aggregate's own name, and looking it up in an index of aggregates
-          # is a tautology — that branch never refused anything and structurally
-          # could not. Verified across all eight golden chapters before deleting it.
-          #
-          # On a piece's command the owner is the entity, and an entity is not a
-          # head, so what this actually refuses is `reference_to <its own name>`
-          # written inside `entity do … end`. A piece is reached through its
-          # aggregate ; a command on one addresses the aggregate, never the piece.
-          #
-          # Reference attributes are the language's business now — offered as the
-          # head's own id and resolved as references, so `Aggregate.Reference` and
-          # `Command.Reference` refuse an undeclared head with no predicate at all.
-          #
-          # @param aggregates [Array<Bluebook::Aggregate>] the chapter's declared aggregates
-          # @return [void]
-          # @raise [Bluebook::DSL::Malformed] if an entity command's `references` names
-          #   something other than one of this chapter's own aggregate heads — which, given
-          #   how `CommandBuilder#reference_to` sets it, only happens when the entity command
-          #   names its own entity as its root
+          # Refuses an entity command that names its own entity as its root.
+          # `CommandBuilder#reference_to` sets `references` only to the owner's bare name, so on
+          # an aggregate command a head lookup is a tautology; only an entity self-reference fails.
           def validate_reference_value_objects!(aggregates)
             heads = aggregates.map(&:hecks_name)
 
@@ -207,27 +102,8 @@ module Hecks
                   "an entity command is addressed through its aggregate; #{violations.uniq.join('; ')}"
           end
 
-          # Events are first-class by convention, not by declaration (ADR
-          # 0025, "events and reactions" — "a domain event is a value
-          # object with its own attributes, not a label"). No new `event
-          # do ... end` construct exists to hand-author and keep in step
-          # with every emitting command by hand — an event's own known
-          # shape is whichever command(s) declare `emits` for its name, and
-          # this is the one thing that has to hold for that convention to
-          # mean anything: every command that emits a given name has to
-          # agree on what it carries. An event is one fact; a fact does not
-          # carry two different truths depending on who is telling it.
-          #
-          # Structural fields only (name/type/list/optional) — `pattern:`/
-          # `admits:`/`default:` are refinements on a field, not a second
-          # claim about what the payload holds, so two emitting commands
-          # are free to differ there without actually disagreeing about
-          # the event's own shape.
-          #
-          # @param aggregates [Array<Bluebook::Aggregate>] the chapter's declared aggregates
-          # @return [void]
-          # @raise [Bluebook::DSL::Malformed] if two or more commands `emits` the same event
-          #   name with different structural shapes
+          # Every command that emits a given event must agree on its structural shape
+          # (name, type, list, optional); `pattern:`/`admits:`/`default:` may differ (ADR 0025).
           def validate_event_shapes!(aggregates)
             event_emitters(aggregates).each do |event_name, pairs|
               next if pairs.size == 1
@@ -242,39 +118,10 @@ module Hecks
             end
           end
 
-          # The "expensive half" the ADR names: "with: { account: :account }
-          # projecting into a reaction that has no declared contract ...
-          # breaks at dispatch rather than at load." Checked here, now that
-          # `validate_event_shapes!` (above) guarantees at most one real
-          # shape per event name, and command references being first-class
-          # (`Naming.command_ref`) means the target side is a real
-          # resolvable command, not a string that might be a typo.
-          #
-          # **Same-chapter only, on purpose** — a `with:` whose source event or
-          # target command lives outside this chapter (an `across` policy
-          # reacting to another domain's event entirely) is silently left
-          # unchecked rather than refused: there is nothing here yet to
-          # check it against, and "unresolvable" is not the same claim as
-          # "wrong."
-          #
-          # A FOR_EACH policy's source isn't the event at all — a fan-out
-          # `with:`'s symbols read the query row `for_each` answers
-          # (FreezeAccountsOnSuspension's own comment: "`account` is the
-          # key the fan-out merges for each row"), which this has no shape
-          # for; the source half is skipped for those, the target half
-          # (does the dispatched command actually declare the field) still
-          # runs, since that half is true regardless of where the value
-          # came from.
-          #
-          # @param policies [Array<Bluebook::Policy>] every reaction hoisted onto the
-          #   chapter's own aggregates
-          # @param process_managers [Array<Bluebook::ProcessManager>] the chapter's declared
-          #   process managers
-          # @param aggregates [Array<Bluebook::Aggregate>] the chapter's declared aggregates
-          # @return [void]
-          # @raise [Bluebook::DSL::Malformed] if a policy's or a saga dispatch's `with:`
-          #   names a field its target command does not declare, or reads a source field
-          #   its event does not carry (see `check_with_spec!` for the full rule)
+          # Checks `with:` projections against the source event's shape and the target's fields.
+          # Same-chapter only: an unresolvable cross-chapter source or target is skipped.
+          # A for_each policy's source is a query row with no known shape, so only its target
+          # is checked.
           def validate_with_projections!(policies, process_managers, aggregates)
             lookup = command_lookup(aggregates)
             heads  = correlation_heads(process_managers)
@@ -299,47 +146,11 @@ module Hecks
             end
           end
 
-          # `process_manager:` is present only for a process manager's own dispatch — a
-          # saga leg's source symbol resolves against the current triggering
-          # event first, same as a policy, but falls all the way back to the
-          # saga's own memory when the current event does not carry it
-          # (`SagaInterpreter#dispatch_args`, its own last `else`) — and
-          # memory starts as the opening event's payload
-          # (`SagaInterpreter#instance = { ..., memory: event.payload }`,
-          # never updated after), never the leg's own. Settlement's own
-          # comment names exactly this: "the credit leg reads a destination
-          # no event carried" — `AccountDebited` never declares `:reference`,
-          # only `TransferRequested` (`pm.starts_on`) does, and that is
-          # where the value is genuinely still coming from.
-          # One closed sequence of per-field checks against a fixed set of
-          # legal `with:` sources (target's own attributes, correlation,
-          # emitter identity, event/memory shape) — see the comment above
-          # for why each source is legal. Extracting the loop body would
-          # mean threading ten-plus already-resolved locals (target,
-          # source_shape, memory_shape, correlation, identity_sources, ...)
-          # into a new method for no gain: each `next`/`raise` already
-          # reads as its own rule at its own site.
-          #
-          # @param command_ref [String] the dotted name of the command `with:` dispatches,
-          #   such as `"Account.Debit"` or `"Account.Piece.Move"`
-          # @param event_name [String, nil] the triggering event's name, or `nil` for a
-          #   FOR_EACH policy (whose source is a query row, not an event)
-          # @param with_spec [Array<Array(Symbol, Object)>] the declared `with:` pairs,
-          #   field name to source — a Symbol naming a field to read, or a literal value
-          # @param lookup [Hash{String => Class}] every command in the chapter, keyed by
-          #   `"owner.hecks_name"` (`command_lookup`'s own shape)
-          # @param label [String] a human-readable description of what declared this
-          #   `with:`, used only in a raised message
-          # @param aggregates [Array<Bluebook::Aggregate>] the chapter's declared aggregates
-          # @param correlation_heads [Array<Symbol>] every saga's own `correlates_by` head
-          #   in this chapter, a legal addressing key alongside a command's own attributes
-          # @param process_manager [Bluebook::ProcessManager, nil] the process manager this
-          #   `with:` dispatches from, or `nil` for a policy's own trigger
-          # @return [void]
-          # @raise [Bluebook::DSL::Malformed] if `with:` names a field the target command
-          #   does not declare, or reads a Symbol source that resolves to neither the
-          #   correlation key, the emitter's identity, nor a field the triggering event or
-          #   (for a saga leg) the starting event's shape carries
+          # Checks one `with:` spec: each key must be a field the target command accepts,
+          # and each Symbol source must be the correlation key, the emitter's identity, or a
+          # field of the event's shape. A saga leg also falls back to the opening event's shape,
+          # since saga memory starts as that payload. One closed sequence of per-field checks;
+          # splitting it threads many locals.
           # rubocop:disable-next Metrics/CyclomaticComplexity
           # rubocop:disable-next Metrics/PerceivedComplexity
           def check_with_spec!(command_ref, event_name, with_spec, lookup, label, aggregates, correlation_heads,
@@ -348,16 +159,9 @@ module Hecks
             source_shape  = event_name && event_shape_for(event_name, aggregates)
             memory_shape  = process_manager && event_shape_for(process_manager.starts_on, aggregates)
             correlation   = process_manager&.correlates_by && process_manager.correlation_head
-            # A policy's source also carries the emitter's own identity —
-            # `PolicyInterpreter#emitter_identity`, the runtime half of this.
-            # An entity command's event never declares its aggregate's
-            # identity (it arrives through `reference_to`, not an
-            # `attribute`), so before this a policy on `KnightCaptured` could
-            # not spell `with: { label: :label }` at all — "reads :label off
-            # KnightCaptured, which does not declare it" — and chess's
-            # AdvancePly grew optional, unread attributes just to survive a
-            # wholesale forward. Policies only: a saga leg's own source is
-            # `SagaInterpreter#dispatch_args`, which merges no such thing.
+            # A policy's source also carries the emitter's identity
+            # (`PolicyInterpreter#emitter_identity`); a saga leg's source
+            # (`SagaInterpreter#dispatch_args`) merges no such thing.
             identity_sources = process_manager.nil? && event_name ? event_identity_heads_for(event_name, aggregates) : []
 
             with_spec.each do |field, source|
@@ -380,34 +184,9 @@ module Hecks
             end
           end
 
-          # Decides whether `field` is a legal `with:` target on `command`.
-          #
-          # A command's own `reference_to` (bare, no `as:`) never lands in
-          # `attributes` — `CommandBuilder#reference_to`'s self-reference
-          # branch sets `command.references` instead (S2), and mints no new
-          # field at all. What addresses it is not one name but the same
-          # set `CommandInterpreter::ArgumentGate#refuse_unknown_arguments`
-          # already accepts at dispatch time — `:id`, the owning aggregate's
-          # own `identity_heads` (real corpus proof — `Account.Debit`
-          # dispatched everywhere as `number: ...`, `Account`'s own
-          # `identified_by`), and `Naming.reference_key(command.references)`
-          # (real corpus proof — `FreezeAccountsOnSuspension`'s `for_each`
-          # fan-out, whose own comment reads "`account` is the key the
-          # fan-out merges for each row it answers"). Both are simultaneously
-          # legal there, not context-dependent alternatives, so both are
-          # legal here : this mirrors that gate rather than re-deriving a
-          # narrower rule that would refuse one of two real, already-shipped
-          # dispatch conventions.
-          #
-          # @param command [Class<Bluebook::Command>] the command `with:` dispatches
-          # @param field [Symbol] the `with:` key to check
-          # @param aggregates [Array<Bluebook::Aggregate>] the chapter's declared aggregates,
-          #   searched when `field` might name `command`'s own reference key
-          # @param correlation_heads [Array<Symbol>] every saga's own `correlates_by` head
-          #   in this chapter
-          # @return [Boolean] `true` when `field` is one of `command`'s own attributes,
-          #   `:id`, a correlation head, or the identity/reference key of the aggregate
-          #   `command.references` names
+          # Mirrors `ArgumentGate#refuse_unknown_arguments`: `:id`, the owning aggregate's
+          # `identity_heads` and `Naming.reference_key(command.references)` are all legal keys
+          # beside the command's own attributes.
           def command_declares?(command, field, aggregates, correlation_heads)
             return true if command.attributes.any? { |a| a.name == field }
             return true if field == :id
@@ -420,38 +199,14 @@ module Hecks
             referenced.identity_heads.include?(field) || Naming.reference_key(command.references) == field
           end
 
-          # The fourth addressing key `ArgumentGate#refuse_unknown_arguments`
-          # accepts, alongside `:id`/`identity_heads`/`reference_key` — every
-          # saga in this domain's own `correlates_by` head, carried through
-          # every dispatch as pure passthrough (Settlement's own comment:
-          # "`reference:` carries the correlation forward... this is pure
-          # passthrough, not an addressing key"). A command declaring none of
-          # its attributes named this is not a gap; the correlation key rides
-          # through commands that never read it, same as it does at runtime.
-          #
-          # @param process_managers [Array<Bluebook::ProcessManager>] the chapter's declared
-          #   process managers
-          # @return [Array<Symbol>] the `correlation_head` of every process manager that
-          #   declares a `correlates_by`
+          # A saga's `correlates_by` head is a legal `with:` key: correlation rides
+          # through commands that never read it.
           def correlation_heads(process_managers)
             process_managers.filter_map { |pm| pm.correlates_by && pm.correlation_head }
           end
 
-          # Yields every command this chapter declares, paired with its owner's name.
-          #
-          # Every command this chapter declares, an aggregate's own and
-          # every entity nested inside one, paired with a name for what
-          # declares it — shared by `validate_event_shapes!` and
-          # `validate_with_projections!`'s own command lookup, the same
-          # reach `HecksagonBuilder#commands_in` needs one level up (S8).
-          #
-          # @param aggregates [Array<Bluebook::Aggregate>] the chapter's declared aggregates
-          # @yieldparam owner [String] the declaring aggregate's `hecks_name`, or
-          #   `"Aggregate.Entity"` for a command declared on a nested entity
-          # @yieldparam command [Class<Bluebook::Command>] the command class
-          # @return [Enumerator<Array(String, Class)>] an enumerator over the same pairs
-          #   when no block is given; otherwise the value of the underlying `each`, unused
-          #   by any caller
+          # Yields every command the chapter declares with its owner's name
+          # ("Aggregate.Entity" for entities).
           def each_command(aggregates)
             return enum_for(:each_command, aggregates) unless block_given?
 
@@ -463,116 +218,41 @@ module Hecks
             end
           end
 
-          # Groups every command in the chapter by the event name(s) it emits.
-          #
-          # **Not memoised** — caching this as `@event_emitters ||=` on the builder
-          # instance would be safe for a one-file chapter but wrong for one split
-          # across several: the first file's `build()` call would compute and cache
-          # it from whatever `@aggregates` held at that moment, and every later
-          # file's own validation would keep reading that same stale snapshot,
-          # silently missing any command a later file adds. Recomputed fresh every
-          # call instead — this walks the whole chapter once per `#build`, not a
-          # hot path worth memoising at that cost.
-          #
-          # @param aggregates [Array<Bluebook::Aggregate>] the chapter's declared aggregates
-          # @return [Hash{String => Array<Array(String, Class)>}] every event name mapped
-          #   to the `[owner, command]` pairs (`each_command`'s own shape) that `emits` it;
-          #   an unqueried event name answers `[]`
+          # Not memoised: a chapter split across files is validated once per file, and a
+          # cached index would miss the commands later files add.
           def event_emitters(aggregates)
             each_command(aggregates).with_object(Hash.new { |h, k| h[k] = [] }) do |(owner, command), index|
               command.emits.each { |event_name| index[event_name] << [owner, command] }
             end
           end
 
-          # The comparable shape of one command's attributes, value objects unwrapped.
-          #
-          # **Structural, not nominal**. Two commands on two different
-          # aggregates that both `emits "SameEvent"` are free to type a
-          # field through two different, locally-scoped wrapper value
-          # objects (e.g. one aggregate's own `value: SomeText` vs
-          # another's `value: OtherText`, exactly the per-aggregate "own
-          # text VO" convention every aggregate in this grammar already
-          # follows for everything from `RuleText` to `FieldRef`) without
-          # actually disagreeing about the event's shape — comparing
-          # `a.type` by name would flag that as a violation for no real
-          # reason: an event is one fact, and two isomorphic wrapper types
-          # tell an identical one. So a value-object type is unwrapped to
-          # its own attribute shape (recursively — a wrapper could itself
-          # wrap another) before comparing, and only a primitive type
-          # (nothing left to unwrap) or two VOs that truly differ once
-          # unwrapped still counts as a real mismatch. `owner` carries the
-          # type's `value_object` lookup — a command's own attributes only
-          # know their type's name, never the aggregate that declared it,
-          # and two sibling aggregates in one chapter each keep a
-          # same-named VO private to themselves, so the unwrap has to ask
-          # the same aggregate the field's own command belongs to, never a
-          # neighbor's.
-          #
-          # @param command [Class<Bluebook::Command>] the command whose attribute shape
-          #   to compute
-          # @param owner [Bluebook::Aggregate, nil] the aggregate whose `value_object`
-          #   lookup resolves any wrapper type by name; `nil` when the owner could not
-          #   be resolved, in which case nothing is unwrapped
-          # @return [Array<Array>] one `[name, unwrapped_type, list, optional]` tuple per
-          #   attribute, sorted; `unwrapped_type` is a type name String for a primitive
-          #   or an unresolved type, or a recursively-unwrapped Array of the same shape
-          #   for a value object
+          # The comparable shape of a command's attributes, value objects unwrapped.
+          # Structural, not nominal: aggregates may type a field with differently named
+          # wrapper value objects without disagreeing about the event. `owner` supplies the
+          # `value_object` lookup, since same-named value objects are private to each aggregate.
           def event_shape(command, owner)
             command.attributes.map { |a| [a.name, unwrap_shape(owner, a.type.to_s), a.list?, a.optional?] }.sort
           end
 
-          # Recursively unwraps a type name to a primitive or a value object's own shape.
-          #
-          # @param owner [Bluebook::Aggregate, nil] the aggregate whose `value_object`
-          #   lookup resolves `type_name`; `nil` answers `type_name` unchanged
-          # @param type_name [String] the attribute type to unwrap
-          # @param seen [Array<String>] type names already unwrapped on this path, so a
-          #   self-referential value object bottoms out on its own name instead of
-          #   recursing forever
-          # @return [String, Array<Array>] `type_name` itself when `owner` is `nil`, when
-          #   it is already a primitive, when it is already in `seen`, or when it names no
-          #   value object `owner` declares; otherwise the same `[name, unwrapped_type,
-          #   list, optional]` shape `event_shape` returns, one tuple per member
           def unwrap_shape(owner, type_name, seen = [])
-            # owner couldn't be resolved, so compare by name: nothing left to unwrap
             return type_name if owner.nil?
             return type_name if Attribute::PRIMITIVES.include?(type_name)
-            # a self-referential VO bottoms out on its own name, not an infinite unwrap
+            # a self-referential value object bottoms out on its own name
             return type_name if seen.include?(type_name)
 
             shape = owner.value_object(type_name)
-            # not this owner's own VO (a reference type, say): nothing further to unwrap
             return type_name unless shape
 
             shape.attributes.map { |a| [a.name, unwrap_shape(owner, a.type.to_s, seen + [type_name]), a.list?, a.optional?] }.sort
           end
 
-          # Finds the aggregate an `each_command` owner string names.
-          #
-          # `owner` (from `each_command`) is a plain string — the aggregate's
-          # `hecks_name` alone, or `"Aggregate.Entity"` for an entity's own
-          # command. Either way the value objects a command's fields can be
+          # The value objects a command's fields can be
           # typed with are the aggregate's own (`Entity` carries no
-          # `value_object` lookup of its own — the whole rest of this file
-          # already resolves hop/type lookups only at the aggregate level,
-          # e.g. `validate_hop_tail!`'s `target.value_object(type)`), so only
-          # the first segment ever matters here.
-          #
-          # @param owner [String] an `each_command` owner string, such as `"Game"` or
-          #   `"Game.Knight"`
-          # @param aggregates [Array<Bluebook::Aggregate>] the chapter's declared aggregates
-          # @return [Bluebook::Aggregate, nil] the aggregate whose `hecks_name` matches
-          #   `owner`'s first dotted segment, or `nil` if none does
+          # `value_object` lookup), so only the owner string's first segment matters.
           def owner_aggregate(owner, aggregates)
             aggregates.find { |a| a.hecks_name == owner.to_s.split(".").first }
           end
 
-          # The comparable attribute shape of whichever command first emits `event_name`.
-          #
-          # @param event_name [String, Symbol] the event name to look up
-          # @param aggregates [Array<Bluebook::Aggregate>] the chapter's declared aggregates
-          # @return [Array<Array>, nil] the first emitting command's `event_shape`, or `nil`
-          #   if no command in the chapter emits this event
           def event_shape_for(event_name, aggregates)
             pairs = event_emitters(aggregates).fetch(event_name.to_s, [])
             return nil if pairs.empty?
@@ -581,16 +261,8 @@ module Hecks
             event_shape(command, owner_aggregate(owner_name, aggregates))
           end
 
-          # The identity heads of the aggregate that emits `event_name` — an
-          # entity's event is stamped with its owning aggregate's identity
-          # (`Event#id` is the parent's), so an owner spelled "Game.Knight"
-          # answers Game's heads.
-          #
-          # @param event_name [String, Symbol] the event name to look up
-          # @param aggregates [Array<Bluebook::Aggregate>] the chapter's declared aggregates
-          # @return [Array<Symbol>] the emitting aggregate's own `identity_heads`, plus the
-          #   emitting entity's own `identity_heads` when the event is an entity's; `[]` if
-          #   no command in the chapter emits this event, or its owner cannot be resolved
+          # An entity's event is stamped with its owning aggregate's identity, so
+          # "Game.Knight" answers Game's heads.
           def event_identity_heads_for(event_name, aggregates)
             pairs = event_emitters(aggregates).fetch(event_name.to_s, [])
             return [] if pairs.empty?
@@ -600,57 +272,23 @@ module Hecks
             return [] unless aggregate
 
             heads = aggregate.identity_heads.map(&:to_sym)
-            # An entity's event also carries the piece's own identity — the
-            # args a piece was addressed by are the args its event announces
-            # (`Emission#emit`: `payload: args`), so `id`-shaped heads are
-            # genuinely there at runtime even though no `attribute` line on
-            # the entity command declares them.
+            # An entity's event also carries the piece's own identity: the args a piece
+            # was addressed by are its payload (`Emission#emit`).
             entity_names = owner_name.to_s.split(".").drop(1)
             entity = entity_names.reduce(aggregate) { |owner, name| owner&.entities&.find { |e| e.hecks_name == name } }
             heads + (entity ? entity.identity_heads.map(&:to_sym) : [])
           end
 
-          # Every command in the chapter, keyed by its fully dotted address.
-          #
-          # @param aggregates [Array<Bluebook::Aggregate>] the chapter's declared aggregates
-          # @return [Hash{String => Class}] `"owner.hecks_name"` (`each_command`'s owner
-          #   string joined with the command's own `hecks_name`) mapped to the command class
           def command_lookup(aggregates)
             each_command(aggregates).with_object({}) do |(owner, command), index|
               index["#{owner}.#{command.hecks_name}"] = command
             end
           end
 
-          # A reference ring is not a modelling choice, it is a missing one
-          # — a DDD aggregate is a consistency boundary precisely because
-          # something outside it can only ever point in, by id, never the
-          # other way. A caller must be able to reason about one aggregate
-          # alone ; a ring back to where it started means no aggregate in
-          # it is a boundary anyone can reason about without the rest of
-          # the ring, and the whole ring is really one aggregate wearing
-          # several names.
-          #
-          # Checked at the bluebook level, not inside `AggregateBuilder`
-          # itself, because seeing a cycle needs every end declared — an
-          # aggregate finishes building long before it can know whether
-          # some later aggregate in the same file points back at it.
-          #
-          # Acyclic within a chapter (ADR 0025, "References") — catches any
-          # ring, however long (A -> B -> C -> A), not only a direct pair
-          # (A -> B -> A), the same DFS coloring a reference graph needs
-          # for any cycle. A cross-chapter reference is unreachable here
-          # rather than unchecked: `Reference#resolve` is scoped to its
-          # own chapter by construction, so a target this chapter never
-          # declares is a dangling name, not an edge — `edges.key?` below
-          # is what keeps the walk from ever leaving this chapter's own
-          # aggregates. Self-reference stays legal (`parent.parent.name`
-          # for a hierarchy is real and safe) — excluded the same way a
-          # direct pair is.
-          #
-          # @param aggregates [Array<Bluebook::Aggregate>] the chapter's declared aggregates
-          # @return [void]
-          # @raise [Bluebook::DSL::Malformed] if the chapter's own aggregate-to-aggregate
-          #   reference graph contains a cycle
+          # A reference ring means no aggregate in it is a consistency boundary. Checked at
+          # chapter level because seeing a cycle needs every end declared (ADR 0025). Catches
+          # any ring length; self-reference stays legal, and a cross-chapter target is a
+          # dangling name, not an edge.
           def validate_no_bidirectional_references!(aggregates)
             edges = aggregates.to_h do |aggregate|
               [aggregate.hecks_name, aggregate.reference_targets.uniq.reject { |target| target == aggregate.hecks_name }]
@@ -667,14 +305,8 @@ module Hecks
                   "through a query instead of a reference pointing back"
           end
 
-          # Plain DFS with a visiting/done coloring, over the reference
-          # graph this chapter's own aggregates declare. Returns the ring
-          # itself (in the order it closes), or nil.
-          #
-          # @param edges [Hash{String => Array<String>}] each aggregate's `hecks_name`
-          #   mapped to the names of the aggregates it references
-          # @return [Array<String>, nil] the aggregate names forming a cycle, in the order
-          #   the walk closes it, or `nil` if the graph has none
+          # Plain DFS with a visiting/done coloring; returns the ring in the order it
+          # closes, or nil.
           def find_reference_cycle(edges)
             state = {}
 
@@ -686,17 +318,6 @@ module Hecks
             nil
           end
 
-          # One DFS step of `find_reference_cycle`, from `node`.
-          #
-          # @param node [String] the aggregate name to walk from
-          # @param edges [Hash{String => Array<String>}] the whole reference graph, as
-          #   `find_reference_cycle` receives it
-          # @param state [Hash{String => Symbol}] each visited node's `:visiting` or
-          #   `:done` color, mutated in place across the whole walk
-          # @param path [Array<String>] the nodes visited on the current path, mutated
-          #   in place as the walk descends and backtracks
-          # @return [Array<String>, nil] the cycle closing back on `node`, or `nil` if
-          #   no cycle is reachable from here
           def reference_cycle_from(node, edges, state, path)
             return nil if state[node] == :done
             return path[path.index(node)..] if state[node] == :visiting
@@ -718,36 +339,9 @@ module Hecks
           end
 
           # Resolves and checks every `where` hop deferred at aggregate-seal time.
-          #
-          # **The other half of a hop** — AggregateBuilder#seal_query_field
-          # recognised the head of a dotted where-field that names one of
-          # its own references and deferred it here, unable to check
-          # further: it cannot yet resolve what the reference points at.
-          # This runs once every aggregate exists in one chapter, so it
-          # can.
-          #
-          # Only `where` clauses ever reach here — a hop on ORDER BY is
-          # refused outright, immediately, back in seal_query_field
-          # itself (that answer never needed the target's shape).
-          #
-          # An entity's own queries do reach `EntityBuilder#reference_to` —
-          # tier-1 sealing (`AggregateBuilder#query_surfaces`) already
-          # recognises a hop on an entity's own field and defers it exactly
-          # like an aggregate's — but nothing walks entity queries at tier 2
-          # to check the deferral, so a bad hop, or even a well-formed one,
-          # would otherwise build silently and then match nothing at runtime
-          # (`QueryInterpreter#entity_rows` reads an element's fields by
-          # literal hash key, never follows a reference). Refused outright
-          # here instead of taught to follow the hop for real: no corpus
-          # member needs an entity query to cross a reference yet, and a
-          # named refusal beats a runtime that resolves nothing while
-          # looking like it might.
-          #
-          # @param bluebook [Bluebook::Chapter] the fully assembled chapter to check
-          # @return [void]
-          # @raise [Bluebook::DSL::Malformed] if an aggregate's `where` hop resolves to
-          #   nothing, chains too deep, or lands somewhere illegal, or if an entity's own
-          #   query hops through a reference at all
+          # An entity query that hops through a reference is refused outright: nothing follows
+          # the hop at runtime (`QueryInterpreter#entity_rows` reads fields by literal key),
+          # so it would match nothing.
           def validate_query_hops!(bluebook)
             bluebook.aggregates.each do |aggregate|
               aggregate.queries.each do |query|
@@ -762,19 +356,8 @@ module Hecks
             end
           end
 
-          # Mints an implicit query attribute for every unresolved symbolic hop comparison.
-          #
-          # The chapter-wide half of AggregateBuilder's local query-argument
-          # inference. A hop cannot resolve while its aggregate is still being
-          # built; here every Reference has an owner and target, so a symbolic
-          # comparison can inherit the type of the scalar it compares without a
-          # duplicate query-local declaration.
-          #
-          # @param bluebook [Bluebook::Chapter] the fully assembled chapter to infer
-          #   query arguments over
-          # @return [void]
-          # @raise [Bluebook::DSL::Malformed] if a hop's reference has no `declared_in`
-          #   aggregate to resolve its target through
+          # Mints an implicit query attribute for each symbolic hop comparison, typed from
+          # the scalar it compares against.
           def infer_hop_query_arguments!(bluebook)
             bluebook.aggregates.each do |aggregate|
               aggregate.queries.each do |query|
@@ -796,23 +379,6 @@ module Hecks
             end
           end
 
-          # Builds the query attribute a resolved hop plan implies for `name`.
-          #
-          # The leaf `infer_hop_query_arguments!` infers for one resolved
-          # hop plan — a pure function of `plan` and the symbolic `name`
-          # it is naming, pulled out because it is a self-contained
-          # computation with no dependency on the enclosing loop's own
-          # iteration state (it neither reads nor mutates anything about
-          # `bluebook`/`aggregate`/`query` beyond what `plan` already
-          # carries).
-          #
-          # @param name [Symbol] the symbolic comparison value the query names, and the
-          #   attribute name to mint
-          # @param plan [QuerySpecification::HopPath::Plan] the resolved hop chain whose
-          #   target's shape `name` is inferred against
-          # @return [Bluebook::Attribute, nil] a `String`-typed attribute when the tail
-          #   lands on the target's lifecycle field; otherwise an attribute copying the
-          #   resolved leaf's type and list-ness; `nil` when the tail resolves to nothing
           def inferred_hop_leaf(name, plan)
             target = plan.hops.last.target
             head, *nested = plan.tail.to_s.split(".")
@@ -827,14 +393,6 @@ module Hecks
             end
           end
 
-          # Refuses any `where` clause on an entity's own query that hops through a reference.
-          #
-          # @param aggregate [Bluebook::Aggregate] the aggregate `entity` is nested under,
-          #   named only in a raised message
-          # @param entity [Class<Bluebook::Entity>] the entity whose queries to check
-          # @return [void]
-          # @raise [Bluebook::DSL::Malformed] if any of `entity`'s queries has a `where`
-          #   clause that hops through one of the entity's own references
           def refuse_entity_query_hops!(aggregate, entity)
             entity.queries.each do |query|
               query.wheres.each do |clause|
@@ -849,27 +407,13 @@ module Hecks
             end
           end
 
-          # Resolves one `where` hop's target and checks where its tail lands.
-          #
-          # @param aggregate [Bluebook::Aggregate] the querying aggregate, named in a
-          #   raised message
-          # @param query [Bluebook::Query] the query `clause` belongs to, named in a
-          #   raised message
-          # @param clause [QuerySpecification::Common::WhereClause] the `where` clause whose
-          #   `field` hops through one of `aggregate`'s own references
-          # @return [void]
-          # @raise [Bluebook::DSL::Malformed] if the hop's target is not declared in this
-          #   chapter, the hop chain exceeds `QuerySpecification::HopPath::MAX_HOPS`, or
-          #   the resolved tail fails `validate_hop_tail!`'s own checks
           def validate_hop_clause!(aggregate, query, clause)
             plan = QuerySpecification::HopPath.plan(clause.field, aggregate.attributes)
 
             case plan.refusal
             when :unresolvable
-              # HopPath.plan pushes even an unresolved hop onto `hops`
-              # before reporting this, specifically so `target_name` —
-              # real, known at declaration, independent of whether
-              # `resolve` succeeded — is always here to name.
+              # HopPath.plan pushes even an unresolved hop onto `hops`, so `target_name`
+              # is always there.
               raise Malformed,
                     "#{aggregate.hecks_name}.#{query.hecks_name} asks about #{clause.field}, " \
                     "which hops to #{plan.hops.last.target_name}, which this chapter never " \
@@ -888,26 +432,8 @@ module Hecks
             validate_hop_tail!(aggregate, query, clause, target, plan.tail)
           end
 
-          # Checks that a resolved hop's tail lands on a real scalar field of its target.
-          #
-          # The same three-way answer seal_query_field gives for its own
-          # aggregate's fields — landing on a real scalar (fine), landing
-          # on a value object (refused by name), or naming nothing at all
-          # (refused by name) — asked instead of the hop's target aggregate,
-          # since that is whose shape the tail actually has to answer for.
-          #
-          # @param aggregate [Bluebook::Aggregate] the querying aggregate, named in a
-          #   raised message
-          # @param query [Bluebook::Query] the query `clause` belongs to, named in a
-          #   raised message
-          # @param clause [QuerySpecification::Common::WhereClause] the `where` clause the
-          #   hop was resolved from, named in a raised message
-          # @param target [Bluebook::Aggregate] the aggregate the hop resolved to
-          # @param tail [String] the dotted field path remaining after the hop, such as
-          #   `"status"` or `"amount.currency"`
-          # @return [void]
-          # @raise [Bluebook::DSL::Malformed] if `tail` lands on a value object rather
-          #   than a scalar, or names no field `target` declares
+          # Same three-way answer as `seal_query_field` (scalar, value object, or
+          # nothing), asked of the hop's target.
           def validate_hop_tail!(aggregate, query, clause, target, tail)
             name, *nested = tail.to_s.split(".")
             attribute = target.attributes.find { |candidate| candidate.name.to_s == name }
@@ -933,30 +459,8 @@ module Hecks
                   "not exist matches nothing and refuses nothing"
           end
 
-          # Checks that an ordered comparator over a hopped field lands on a number.
-          #
-          # A where hop with an ordered comparator is legitimate ("client
-          # whose balance > 500") — AggregateBuilder#seal_ordered_comparator
-          # already deferred this exact check for the same reason every
-          # other hop check is deferred, and this is where it gets asked,
-          # against the hop's target instead of the querying aggregate.
-          #
-          # @param aggregate [Bluebook::Aggregate] the querying aggregate, named in a
-          #   raised message
-          # @param query [Bluebook::Query] the query `clause` belongs to, named in a
-          #   raised message
-          # @param clause [QuerySpecification::Common::WhereClause] the `where` clause
-          #   whose `op` and `field` are named in a raised message
-          # @param target [Bluebook::Aggregate] the aggregate the hop resolved to, named
-          #   in a raised message
-          # @param attribute [Bluebook::Attribute, nil] the tail's root attribute on
-          #   `target`, or `nil` when the tail lands on the lifecycle field
-          # @param nested [Array<String>] the tail's remaining dotted segments past
-          #   `attribute`, `[]` for a bare field
-          # @return [void]
-          # @raise [Bluebook::DSL::Malformed] if `clause.op` is one of
-          #   `AggregateBuilder::ORDERED_COMPARATORS` and the field it lands on, after
-          #   `attribute`/`nested`, is not numeric
+          # An ordered comparator over a hopped field must land on a number; the check
+          # `AggregateBuilder#seal_ordered_comparator` deferred.
           def validate_hop_comparator!(aggregate, query, clause, target, attribute, nested)
             return unless AggregateBuilder::ORDERED_COMPARATORS.include?(clause.op.to_s.to_sym)
             return if attribute &&
@@ -970,26 +474,9 @@ module Hecks
                   "anything else the adapters answer differently or not at all"
           end
 
-          # The target half of `projects` validation (S12, ADR 0025) —
-          # `AggregateBuilder#seal_projected_fields` already checked the
-          # local half at declare time (the reference names a real
-          # `reference_to` on this aggregate); this checks the reference
-          # actually resolves to a real aggregate in this chapter, and
-          # that aggregate really declares `remote_field` as a scalar.
-          #
-          # Reuses `QuerySpecification::HopPath` rather than re-deriving
-          # hop resolution a second way — `"reference/remote_field"` is
-          # the same single-hop shape a query's own `/`-spelled hop
-          # resolves, even though `projects`'s own DSL spelling is dotted
-          # (`from: :"customer.status"`): two constructs, two spellings,
-          # one resolution primitive. A single hop can never reach
-          # HopPath::MAX_HOPS, so :too_deep is structurally unreachable
-          # here and is not special-cased.
-          #
-          # @param bluebook [Bluebook::Chapter] the fully assembled chapter to check
-          # @return [void]
-          # @raise [Bluebook::DSL::Malformed] if any aggregate's `projects` field fails
-          #   `validate_projected_field!`'s own checks
+          # Checks each `projects` reference resolves to an aggregate declaring
+          # `remote_field` as a scalar. A single hop never reaches HopPath::MAX_HOPS, so
+          # :too_deep is not special-cased.
           def validate_projected_fields!(bluebook)
             bluebook.aggregates.each do |aggregate|
               aggregate.projected_fields.each { |field| validate_projected_field!(aggregate, field) }
@@ -997,22 +484,8 @@ module Hecks
           end
 
           # Checks that one `projects` field's reference resolves to a real scalar.
-          #
-          # A linear decision tree of validation rules over one resolved
-          # hop plan, each already explained by its own comment above
-          # (the lifecycle fallback, the chained-projection fallback, the
-          # final scalar check) — a fixed, closed sequence "resolve, then
-          # check each way this could legitimately or illegitimately
-          # land," not several unrelated concerns. Splitting it would
-          # scatter `plan`/`target`/`remote_attribute` across new methods
-          # that would each need most of them anyway.
-          #
-          # @param aggregate [Bluebook::Aggregate] the aggregate that declared `field`
-          # @param field [Bluebook::ProjectedField] the declared `projects` field to check
-          # @return [void]
-          # @raise [Bluebook::DSL::Malformed] if `field.reference` hops to an aggregate
-          #   this chapter never declares, or `field.remote_field` names nothing on the
-          #   target, or names something other than a scalar
+          # One closed sequence over a single hop plan; splitting it scatters `plan`/`target`/
+          # `remote_attribute` across methods that each need most of them.
           # rubocop:disable-next Metrics/AbcSize
           def validate_projected_field!(aggregate, field)
             plan = QuerySpecification::HopPath.plan("#{field.reference}/#{field.remote_field}", aggregate.attributes)
@@ -1027,30 +500,13 @@ module Hecks
             target = plan.hops.last.target
             remote_attribute = target.attributes.find { |candidate| candidate.name.to_s == plan.tail }
 
-            # The worked example itself (ADR 0025) reads through a
-            # lifecycle field — banking's Customer.status is `lifecycle
-            # :status`, never a plain `attribute` — the same fallback
-            # validate_hop_tail! already gives a query's own hop tail. A
-            # lifecycle field is always a plain string by construction ;
-            # nothing further to check once it matches by name.
+            # A lifecycle field is a plain string by construction, so a name match is enough (as in
+            # `validate_hop_tail!`).
             return if remote_attribute.nil? && target.lifecycle&.field.to_s == plan.tail
 
-            # A projection may chain through another projection (S12, ADR
-            # 0025's own boundary rule, followed through) — `target`'s
-            # own projected fields live in `projected_fields`, a
-            # separate list from `attributes`, so a match there is
-            # invisible to the check above even though it names a real,
-            # always-current, stored field. `Transfer.projects
-            # :source_customer_status, from: :"source.customer_status"`
-            # reads Account's own already-projected `customer_status`
-            # this way — Account is one hop from Customer, Transfer is
-            # one hop from Account, and neither aggregate needs to know
-            # about the other's target two hops away. A projected
-            # field's remote value is always a scalar by construction
-            # (`RebuildSweep.remote_value` never copies a reference, a
-            # value object, or a list), so nothing further to check once
-            # it matches by name — same reasoning the lifecycle
-            # fallback just above already applies.
+            # A projection may chain through another projection; `projected_fields` is
+            # separate from `attributes`, and a projected value is always a scalar by
+            # construction, so a name match is enough.
             return if remote_attribute.nil? && target.projected_fields.any? { |f| f.name.to_s == plan.tail }
 
             unless remote_attribute
@@ -1067,45 +523,14 @@ module Hecks
                   "value, never a reference, a value object, or a list"
           end
 
-          # Decides whether a declared attribute is a plain, single scalar value.
-          #
-          # @param target [Bluebook::Aggregate] the aggregate `attribute` is declared on,
-          #   whose `value_object` lookup resolves `attribute`'s type
-          # @param attribute [Bluebook::Attribute] the attribute to check
-          # @return [Boolean] `true` when `attribute` is not a list, not a reference, and
-          #   its type names no value object `target` declares
           def projectable_scalar?(target, attribute)
             !attribute.list? && !attribute.reference? && target.value_object(attribute.type).nil?
           end
 
-          # `correlates_by` names a scalar, now checked rather than trusted.
-          #
-          # ProcessManagerBuilder#validate! already refuses a bare, undotted
-          # spelling — a syntactic guarantee that the declaration cannot leave
-          # the question open. It cannot go further: a process manager is built
-          # in isolation, before this chapter's aggregates exist to check
-          # against. Here, with the whole document assembled, the dotted path
-          # is walked for real — against whichever command actually emits an
-          # event this process manager reacts to — so a path that still lands
-          # on a value object is refused before the runtime ever has to decide
-          # what a non-scalar correlation key even means: a saga keys off this
-          # value directly, and a value object carries no guaranteed-stable
-          # identity to key on the way a scalar does.
-          #
-          # A command that does not declare the path's first segment at all is
-          # silently skipped, not refused — correlation has two other fallback
-          # tiers below the payload dig (a correlation stamp, then the emitting
-          # aggregate's own reference key; saga_interpreter/correlation.rb), so
-          # an absent field is not this check's business. Only a field that
-          # resolves, and resolves to something other than a scalar, is.
-          #
-          # @param process_managers [Array<Bluebook::ProcessManager>] the chapter's
-          #   declared process managers
-          # @param aggregates [Array<Bluebook::Aggregate>] the chapter's declared aggregates
-          # @return [void]
-          # @raise [Bluebook::DSL::ProcessManagerBuilder::InvalidProcessManager] if a
-          #   process manager's `correlates_by` path resolves, on any command that emits
-          #   an event it reacts to, to something other than a scalar
+          # `correlates_by` must land on a scalar: the dotted path is walked against each
+          # command that emits an event the process manager reacts to. A command lacking the
+          # first segment is skipped, since correlation has fallback tiers
+          # (saga_interpreter/correlation.rb).
           def validate_correlation_keys!(process_managers, aggregates)
             process_managers.each do |pm|
               next unless pm.correlates_by
@@ -1118,15 +543,6 @@ module Hecks
             end
           end
 
-          # Finds why a process manager's `correlates_by` path is not a scalar, if it isn't.
-          #
-          # @param process_manager [Bluebook::ProcessManager] the process manager whose
-          #   `correlates_by` to check
-          # @param aggregates [Array<Bluebook::Aggregate>] the chapter's declared aggregates
-          # @return [String, nil] the reason the path is not a scalar, on the first
-          #   emitting command whose first segment resolves; `nil` if every command that
-          #   emits a reacted-to event either omits the first segment, or resolves to
-          #   a scalar
           def correlation_key_violation(process_manager, aggregates)
             head, *rest = process_manager.correlates_by.to_s.split(".")
             events = reacted_events(process_manager)
@@ -1142,12 +558,6 @@ module Hecks
             nil
           end
 
-          # The demodulised names of every event a process manager reacts to.
-          #
-          # @param process_manager [Bluebook::ProcessManager] the process manager whose
-          #   `starts_on`, `ends_on` and handler event types to collect
-          # @return [Array<String>] the unique demodulised event names, `REFUSED` (the
-          #   compensation trigger, not a real event) excluded
           def reacted_events(process_manager)
             ([process_manager.starts_on, process_manager.ends_on] + process_manager.handlers.map(&:event_type))
               .compact
@@ -1156,13 +566,6 @@ module Hecks
               .uniq
           end
 
-          # Every command across the chapter that emits one of the given events.
-          #
-          # @param events [Array<String>] the demodulised event names to match against
-          #   each command's own `emits`
-          # @param aggregates [Array<Bluebook::Aggregate>] the chapter's declared aggregates
-          # @return [Array<Array(Bluebook::Aggregate, Class)>] one `[aggregate, command]`
-          #   pair per matching command, an aggregate's own or one of its entities'
           def emitting_commands(events, aggregates)
             aggregates.flat_map do |aggregate|
               commands = aggregate.commands + aggregate.entities.flat_map(&:commands)
@@ -1171,16 +574,6 @@ module Hecks
             end
           end
 
-          # Decides whether one command attribute can serve as a correlation key.
-          #
-          # @param owner [Bluebook::Aggregate] the aggregate whose `value_object` lookup
-          #   resolves `attribute`'s type, for `walk_scalar`
-          # @param attribute [Bluebook::Attribute] the command attribute the correlation
-          #   path's first segment named
-          # @param segments [Array<String>] the path's remaining dotted segments, `[]` for
-          #   a bare field
-          # @return [String, nil] why `attribute` cannot serve as a correlation key, or
-          #   `nil` if it can — see `walk_scalar` for what a non-`nil` reason means
           def list_or_scalar_violation(owner, attribute, segments)
             if attribute.list?
               return "#{attribute.name} is a list — a correlation key must name one instance's own field, " \
@@ -1190,23 +583,8 @@ module Hecks
             walk_scalar(owner, attribute.type.to_s, segments)
           end
 
-          # Walks the remaining dotted segments through nested value objects.
-          # `type_name` starts as the head attribute's own declared type ; each
-          # step either bottoms out at a real scalar (nil — no violation) or
-          # names why it cannot: still a value object with no more path left,
-          # a value object this domain never declared, a field that value
-          # object does not have, or a segment left over after already
-          # reaching a scalar.
-          #
-          # @param owner [Bluebook::Aggregate] the aggregate whose `value_object` lookup
-          #   resolves each stepped-into type name
-          # @param type_name [String] the type to check or step into
-          # @param segments [Array<String>] the dotted path segments remaining to walk
-          # @return [String, nil] `nil` when the walk bottoms out cleanly on a scalar;
-          #   otherwise why it cannot: `type_name` is a value object with no segments
-          #   left, `type_name` is already a scalar with segments left over, `type_name`
-          #   names no value object `owner` declares, the next segment names no field of
-          #   that value object, or that field is a list
+          # Walks the remaining dotted segments through nested value objects; nil means the walk
+          # bottomed out on a scalar, otherwise the string says why it cannot.
           def walk_scalar(owner, type_name, segments)
             if segments.empty?
               return nil if Attribute::PRIMITIVES.include?(type_name)