hecks 1.3.0 → 1.5.0

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

@@ -2,37 +2,68 @@ require_relative "word_gate"
 module Hecks
   module Bluebook
     module DSL
-      # Parses a top-level `.port` file's `Hecks.port "Name" do verb "x";
-      # signal :effect end` body into a `Port` — the adapter-facing shape (one
-      # verb, one signal, an optional method contract in `answers`) a domain
-      # calls OUT through, as opposed to `DomainPortBuilder`'s own inbound/
-      # outbound operations.
+      # Parses a `verb "x"; signal :effect` port body into a `Port` — the
+      # adapter-facing shape (one verb, one signal, an optional method
+      # contract in `answers`) a domain calls out through, as opposed to
+      # `DomainPortBuilder`'s own inbound/outbound operations.
+      #
+      # `Hecks.port` (lib/hecks.rb) parses a top-level `.port` file through
+      # `DomainPortBuilder`, whose bare-verb branch builds the identical
+      # `Port`; this builder is the reference shape `spec/dsl_spec.rb` holds
+      # that branch to.
       class PortBuilder
         GRAMMAR_CONTEXT = "Port".freeze
 
         include WordGate
 
+        # @param name [String] the port's name, as written after `Hecks.port`
         def initialize(name)
           @name    = name
           @signal  = :reply
           @answers = []
         end
 
+        # Names the verb a domain's aggregates call this port by when a hecksagon binds it.
+        #
+        # @param value [String, Symbol] the verb, such as `"asked_by"` or `"persisted_by"`
+        # @return [String] the verb as stored
         def verb(value)   = @verb = value.to_s
+
+        # Sets whether the domain waits for a value back; a port left unset signals `:reply`.
+        #
+        # @param value [Symbol, String] `:reply` when the adapter answers with a value,
+        #   `:effect` when it is called only for its effect
+        # @return [Symbol] the signal as stored
         def signal(value) = @signal = value.to_sym
 
-        # THE METHOD CONTRACT — the fact a `.port` file's `verb`/`signal`
-        # never carried: what an adapter must actually RESPOND TO for a
+        # Declares one method an adapter bound to this port must respond to.
+        #
+        # **The method contract** — the fact a `.port` file's `verb`/`signal`
+        # never carried: what an adapter must actually respond to for a
         # dispatch to reach it without a bare `NoMethodError`. Declared the
         # same repeatable way `AdapterBuilder#field`/`#secret` already are,
         # so `verify!` can check it with `respond_to?` at boot instead of
         # the runtime discovering it live.
+        #
+        # @param name [Symbol, String] the method name, such as `:ask`
+        # @return [Array<Symbol>] every method declared so far, this one last
         def answers(name) = @answers << name.to_sym
 
+        # Assembles the collected verb, signal and method contract, judged by the port language.
+        #
+        # @return [Bluebook::Port] the port, returned once the language accepts it
+        # @raise [Bluebook::DSL::Malformed] if the port language refuses the declaration
         def build
           MetaValidator.call_port(Port.new(name: @name, verb: @verb, signal: @signal, answers: @answers))
         end
 
+        # Evaluates a port block against a fresh builder and returns what it built.
+        #
+        # @param name [String] the port's name
+        # @yield the port body, evaluated with the builder as `self`; may be omitted
+        # @return [Bluebook::Port] the judged port
+        # @raise [Bluebook::DSL::Malformed] if the port language refuses the declaration, or
+        #   the block uses a word the `Port` grammar does not admit
         def self.build(name, &block)
           builder = new(name)
           builder.instance_eval(&block) if block

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

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

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

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