hecks 1.3.0 → 1.5.0

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

@@ -2,8 +2,8 @@ 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`
+        # 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
@@ -17,25 +17,34 @@ module Hecks
         # 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 — checked before splitting it out), 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
+        # 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, matching what `def self.foo` already made
-        # every one of these before the split.
+        # an instance method, the same role `def self.foo` fills on a
+        # class that keeps its methods in one file.
         module Validation
-          # EVERY WHOLE-CHAPTER CHECK, IN ONE PLACE — the battery `#build`
-          # used to run inline, now a pure function of an assembled
-          # `Bluebook::Chapter` so `MetaValidator.judge_deferred!` can run
-          # it too, 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.
+          # Runs every whole-chapter check against one fully assembled chapter.
+          #
+          # **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
+          # @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
           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
@@ -49,12 +58,12 @@ module Hecks
 
             # 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
+            # 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
+            # ones declared above the aggregate doing the asking) would
             # have resolved to nil.
             infer_hop_query_arguments!(bluebook)
             validate_query_hops!(bluebook)
@@ -63,29 +72,99 @@ module Hecks
             # own reference cannot resolve until every aggregate in the
             # chapter is real and owner-stamped (S12, 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
+                raise Malformed, "#{bluebook.name} provides #{capability.inspect}, which is no capability the " \
+                                 "language knows — known: #{Capabilities::CONTRACTS.keys.sort.join(', ')}"
+              end
+
+              keys = rows.map { |row| row.key.to_sym }
+              unless keys.sort == contract.keys.sort
+                raise Malformed, "#{bluebook.name} provides #{capability.inspect} with #{keys.join(', ')}, but " \
+                                 "#{capability} needs exactly #{contract.keys.join(', ')}"
+              end
+
+              rows.each { |row| validate_provided_verb!(bluebook, capability, row, contract.fetch(row.key.to_sym)) }
+            end
           end
 
-          # AN ENTITY COMMAND MAY NOT NAME ITSELF AS ITS ROOT.
+          # Checks that one `provides` row's verb names a real command or query.
           #
-          # That is the whole of what is left here, and it needs saying plainly
-          # because the sentence this used to raise — "references must target
-          # aggregate heads" — was never what it checked.
+          # @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` or `:query`, 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)
+            aggregate_name, member = row.verb.split(".", 2)
+            aggregate = bluebook.aggregate(aggregate_name)
+            return if aggregate && member && provided_member_names(aggregate, kind).include?(member)
+
+            raise Malformed, "#{bluebook.name} provides #{capability.inspect} #{row.key}: #{row.verb.inspect}, " \
+                             "which names no #{kind} this chapter declares (spelled \"Aggregate.#{kind.capitalize}\")"
+          end
+
+          # Names of the members a `provides` verb of the given kind may address.
           #
-          # `CommandBuilder#reference_to` sets `references` ONLY when the target's
+          # @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
+          # 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
+          # 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
+          # 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
+          # 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
+          # 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
           def validate_reference_value_objects!(aggregates)
             heads = aggregates.map(&:hecks_name)
 
@@ -106,22 +185,27 @@ module Hecks
                   "an entity command is addressed through its aggregate; #{violations.uniq.join('; ')}"
           end
 
-          # EVENTS ARE FIRST-CLASS BY CONVENTION, NOT BY DECLARATION (ADR
+          # 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
+          # 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
+          # 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
           def validate_event_shapes!(aggregates)
             event_emitters(aggregates).each do |event_name, pairs|
               next if pairs.size == 1
@@ -136,29 +220,39 @@ module Hecks
             end
           end
 
-          # THE "EXPENSIVE HALF" the ADR names: "with: { account: :account }
+          # 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
+          # (`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
+          # **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
+          # 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
+          # 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)
           def validate_with_projections!(policies, process_managers, aggregates)
             lookup = command_lookup(aggregates)
             heads  = correlation_heads(process_managers)
@@ -184,11 +278,11 @@ module Hecks
           end
 
           # `process_manager:` is present only for a process manager's own dispatch — a
-          # saga leg's source symbol resolves against the CURRENT triggering
+          # 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
+          # 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
+          # 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
@@ -203,6 +297,27 @@ module Hecks
           # 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
           # 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,
@@ -211,7 +326,7 @@ 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 —
+            # 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
@@ -243,15 +358,17 @@ module Hecks
             end
           end
 
-          # A command's OWN `reference_to` (bare, no `as:`) never lands in
+          # 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`
+          # 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)`
+          # `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
@@ -259,6 +376,16 @@ module Hecks
           # 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
           def command_declares?(command, field, aggregates, correlation_heads)
             return true if command.attributes.any? { |a| a.name == field }
             return true if field == :id
@@ -271,23 +398,38 @@ module Hecks
             referenced.identity_heads.include?(field) || Naming.reference_key(command.references) == field
           end
 
-          # THE FOURTH addressing key `ArgumentGate#refuse_unknown_arguments`
+          # 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
+          # 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`
           def correlation_heads(process_managers)
             process_managers.filter_map { |pm| pm.correlates_by && pm.correlation_head }
           end
 
-          # Every command this chapter declares, an aggregate's own AND
+          # 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
           def each_command(aggregates)
             return enum_for(:each_command, aggregates) unless block_given?
 
@@ -299,70 +441,116 @@ module Hecks
             end
           end
 
-          # NOT MEMOISED — this used to be `@event_emitters ||=` on the
-          # builder instance, which is 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.
+          # 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 `[]`
           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
 
-          # STRUCTURAL, NOT NOMINAL. Two commands on two different
+          # 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
+          # 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
+          # `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
+          # 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,
+          # 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
+          # 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
           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 = [])
-            return type_name if owner.nil? # owner couldn't be resolved -- compare by name, same as before this unwrap existed
+            # 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
             return type_name if seen.include?(type_name)
 
             shape = owner.value_object(type_name)
-            return type_name unless shape # not this owner's own VO (a reference type, say) -- nothing further to unwrap
+            # 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
 
-          # `owner` (from `each_command`) is a plain STRING — the aggregate's
+          # 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
-          # typed with are the AGGREGATE's own (`Entity` carries no
+          # command. Either way 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
           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?
@@ -372,9 +560,15 @@ module Hecks
           end
 
           # The identity heads of the aggregate that emits `event_name` — an
-          # entity's event is stamped with its OWNING aggregate's identity
+          # 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
           def event_identity_heads_for(event_name, aggregates)
             pairs = event_emitters(aggregates).fetch(event_name.to_s, [])
             return [] if pairs.empty?
@@ -384,7 +578,7 @@ module Hecks
             return [] unless aggregate
 
             heads = aggregate.identity_heads.map(&:to_sym)
-            # AN ENTITY'S EVENT ALSO CARRIES THE PIECE'S OWN IDENTITY — the
+            # 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
@@ -394,15 +588,20 @@ module Hecks
             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 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
+          # 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
@@ -414,18 +613,22 @@ module Hecks
           # 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") — widened
-          # from the direct pair (A -> B -> A) this used to catch alone to
-          # any ring, however long (A -> B -> C -> 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 the
-          # direct-pair check already excluded 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
           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 }]
@@ -443,8 +646,13 @@ module Hecks
           end
 
           # Plain DFS with a visiting/done coloring, over the reference
-          # graph THIS chapter's own aggregates declare. Returns the ring
+          # 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
           def find_reference_cycle(edges)
             state = {}
 
@@ -456,6 +664,17 @@ 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
@@ -464,7 +683,8 @@ module Hecks
             path.push(node)
 
             edges[node].each do |target|
-              next unless edges.key?(target) # a name this chapter never declares is dangling, not an edge
+              # a name this chapter never declares is dangling, not an edge
+              next unless edges.key?(target)
 
               found = reference_cycle_from(target, edges, state, path)
               return found if found
@@ -475,31 +695,37 @@ module Hecks
             nil
           end
 
-          # THE OTHER HALF OF A HOP — AggregateBuilder#seal_query_field
-          # recognised the HEAD of a dotted where-field that names one of
+          # 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.
+          # 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
+          # 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 DID reach `EntityBuilder#reference_to`
-          # (added after this comment first claimed otherwise — S9, ADR
-          # 0025) without ever reaching HERE: 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 ever walked entity queries at tier 2
-          # to check the deferral — a bad hop, or even a well-formed one,
-          # built silently and then matched nothing at runtime
+          # 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
           def validate_query_hops!(bluebook)
             bluebook.aggregates.each do |aggregate|
               aggregate.queries.each do |query|
@@ -514,11 +740,19 @@ 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
           def infer_hop_query_arguments!(bluebook)
             bluebook.aggregates.each do |aggregate|
               aggregate.queries.each do |query|
@@ -540,13 +774,23 @@ module Hecks
             end
           end
 
-          # THE LEAF `infer_hop_query_arguments!` INFERS for one resolved
+          # 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(".")
@@ -561,6 +805,14 @@ 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|
@@ -575,6 +827,18 @@ 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)
 
@@ -602,11 +866,26 @@ module Hecks
             validate_hop_tail!(aggregate, query, clause, target, plan.tail)
           end
 
-          # The same three-way answer seal_query_field gives for its OWN
+          # 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,
+          # (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
           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 }
@@ -632,11 +911,30 @@ module Hecks
                   "not exist matches nothing and refuses nothing"
           end
 
-          # A WHERE hop with an ordered comparator is legitimate ("client
+          # 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.
+          # 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
           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 &&
@@ -650,10 +948,10 @@ module Hecks
                   "anything else the adapters answer differently or not at all"
           end
 
-          # THE TARGET HALF of `projects` validation (S12, ADR 0025) —
+          # 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
+          # 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.
           #
@@ -665,13 +963,20 @@ module Hecks
           # 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
           def validate_projected_fields!(bluebook)
             bluebook.aggregates.each do |aggregate|
               aggregate.projected_fields.each { |field| validate_projected_field!(aggregate, field) }
             end
           end
 
-          # A linear decision tree of validation rules over ONE resolved
+          # 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
@@ -679,6 +984,13 @@ module Hecks
           # 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
           # rubocop:disable-next Metrics/AbcSize
           def validate_projected_field!(aggregate, field)
             plan = QuerySpecification::HopPath.plan("#{field.reference}/#{field.remote_field}", aggregate.attributes)
@@ -693,17 +1005,17 @@ 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
+            # 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.
             return if remote_attribute.nil? && target.lifecycle&.field.to_s == plan.tail
 
-            # A PROJECTION MAY CHAIN THROUGH ANOTHER PROJECTION (S12, ADR
+            # 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
+            # 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
@@ -733,14 +1045,21 @@ 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.
+          # `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
+          # 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
@@ -757,6 +1076,14 @@ module Hecks
           # 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
           def validate_correlation_keys!(process_managers, aggregates)
             process_managers.each do |pm|
               next unless pm.correlates_by
@@ -769,6 +1096,15 @@ 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)
@@ -784,6 +1120,12 @@ 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
@@ -792,6 +1134,13 @@ 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)
@@ -800,6 +1149,16 @@ 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, " \
@@ -816,6 +1175,16 @@ module Hecks
           # 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
           def walk_scalar(owner, type_name, segments)
             if segments.empty?
               return nil if Attribute::PRIMITIVES.include?(type_name)