hecks 1.3.0 → 1.5.0

data/lib/hecks/bluebook/behaviour/command.rb

@@ -3,13 +3,16 @@ require_relative "traits"
 module Hecks
   module Bluebook
     module Behaviour
-      # WHAT A COMMAND DOES. EXTENDED, not included — a command is a
-      # CLASS, one per declared verb.
+      # **What a command does**. Extended, not included — a command is a
+      # class, one per declared verb.
       module Command
         include Indexed
 
         # Indexed once — attributes are final once absorbed, and every
         # dispatch asks this finder by name.
+        #
+        # @return [Class] self — the command class, once its attributes are
+        #   indexed
         def settle
           index_attributes(@attributes)
           self
@@ -17,8 +20,8 @@ module Hecks
 
         # The construct this verb acts upon — the construct itself, not its name.
         #
-        # A verb declared on an ENTITY always acts on that piece. It never
-        # self-references, because an element is addressed THROUGH its parent —
+        # A verb declared on an entity always acts on that piece. It never
+        # self-references, because an element is addressed through its parent —
         # which means `creates?` answers true for every one of them, and reading
         # `acts_on` off `creates?` alone would report that `LedgerEntry.Amend`
         # brings a ledger entry into being. Three of banking's commands were
@@ -26,10 +29,15 @@ module Hecks
         #
         # On an aggregate, a creating command acts on no existing root, so nil is
         # the truth: there is nothing there yet.
+        #
+        # @return [Class, Bluebook::Aggregate, nil] the entity class (a
+        #   `Bluebook::Entity` subclass) this verb acts on when declared on an
+        #   entity, the aggregate instance when declared on an aggregate and
+        #   non-creating, or `nil` for a creating command
         def acts_on
-          # FULLY QUALIFIED, and it has to be: inside `module Behaviour`
+          # Fully qualified, and it has to be: inside `module Behaviour`
           # the bare name `Entity` resolves to Behaviour::Entity — this
-          # module's SIBLING — not to the construct. Comparing a Class to
+          # module's sibling — not to the construct. Comparing a Class to
           # a Module answers nil, so the guard silently fell through and
           # every entity verb reported acting on nothing.
           return hecks_owner if hecks_owner.is_a?(Class) && hecks_owner < Bluebook::Entity
@@ -37,20 +45,27 @@ module Hecks
           creates? ? nil : hecks_owner
         end
 
+        # Whether this command creates a new root rather than acting on one.
+        #
+        # @return [Boolean] whether this command creates a new root — true when
+        #   it declares no `reference_to` back to its own owner
         def creates? = @references.nil?
 
-        # EVERY REASON THIS VERB CAN REFUSE ON A RULE — the descriptions of
-        # its givens AND its ensures, the exact text the runtime quotes
+        # Every reason this verb can refuse on a rule — the descriptions of
+        # its givens and its ensures, the exact text the runtime quotes
         # after "refused — " when a guard is not met (see
         # command_rules/admissibility.rb's GivenNotMet/EnsuresNotMet). A
         # property that asks "did the runtime only ever refuse for a rule
         # the language wrote" reads this rather than re-deriving the two
         # collections; `compact` because a rule's description is optional
         # (behavior.bluebook's Rule) and an unnamed one quotes nothing.
+        #
+        # @return [Array<String>] every named given's and ensure's own
+        #   description text, skipping unnamed rules
         def guard_descriptions = (@givens + @ensures).map(&:description).compact
 
-        # THE ARGUMENT NAME THAT ADDRESSES an instance of `aggregate_name`
-        # for THIS command — the one fact `PolicyInterpreter`'s own
+        # The argument name that addresses an instance of `aggregate_name`
+        # for this command — the one fact `PolicyInterpreter`'s own
         # `for_each` fan-out needs and, until this reading existed, had
         # to guess at (see git blame: `Behaviour::Policy
         # #fan_out_reference_key`, which hardcoded `<aggregate>_id`
@@ -58,32 +73,37 @@ module Hecks
         # addressing command as a result — `Account.Freeze`, addressed
         # by `number`/`account`, not `account_id`).
         #
-        # TWO SHAPES, the same two `CommandBuilder#reference_to` already
+        # Two shapes, the same two `CommandBuilder#reference_to` already
         # tells apart at declare time (command_builder.rb's own comment
-        # on `cross_reference` — "`as:` MEANS a named attribute... a
-        # command can point at another instance of its OWN kind"):
+        # on `cross_reference` — "`as:` means a named attribute... a
+        # command can point at another instance of its own kind"):
         #
-        #   SELF-ADDRESSING — `references == aggregate_name` (this verb
-        #   is declared ON the very aggregate it acts on, `reference_to
+        #   self-addressing — `references == aggregate_name` (this verb
+        #   is declared on the very aggregate it acts on, `reference_to
         #   Account` on a command Account itself owns). No attribute was
-        #   minted for it at all; the SAME bare key
+        #   minted for it at all; the same bare key
         #   `CommandInterpreter::ArgumentGate#reference_key` already
         #   accepts as "addressing, not describing" is reused here
         #   rather than re-derived — one door, not two.
         #
-        #   CROSS-REFERENCING — a real, declared reference-typed
-        #   attribute whose OWN target is `aggregate_name` (`customer_id`
-        #   on `Account.Open`, or whatever `as:` named it). Its NAME is
+        #   cross-referencing — a real, declared reference-typed
+        #   attribute whose own target is `aggregate_name` (`customer_id`
+        #   on `Account.Open`, or whatever `as:` named it). Its name is
         #   the key, exactly as declared — never re-derived from the
         #   target's name, because an `as:` reference's name and its
         #   target's snake case can legitimately differ (`Transfer`'s own
         #   `source`/`destination`, both `Reference<Account>`).
         #
-        # `nil` when neither shape matches — a CREATING command (nothing
+        # `nil` when neither shape matches — a creating command (nothing
         # to address yet) or one that simply never references this
         # aggregate at all. A caller minting a fan-out dispatch is
         # expected to treat `nil` as "this command cannot be addressed by
         # a row of this aggregate," not to fall back on a guess.
+        #
+        # @param aggregate_name [String, Symbol] the aggregate a fan-out dispatch is
+        #   addressing an instance of
+        # @return [String, nil] the argument name that addresses it, or nil if this command
+        #   cannot be addressed by a row of that aggregate
         def addressing_key_for(aggregate_name)
           return Naming.reference_key(aggregate_name) if references.to_s == aggregate_name.to_s
 
@@ -92,15 +112,25 @@ module Hecks
         end
       end
 
-      # A MUTATION'S OWN READINGS. Included (not extended) — Mutation is
+      # **A mutation's own readings**. Included (not extended) — Mutation is
       # a Struct, so these are instance methods.
       module Mutation
-        # An APPEND binds several fields at once, each from either a command
-        # ARGUMENT (a Symbol) or a LITERAL. It used to spell the Symbol bare
-        # and inspect the rest, which is the opposite of what a where-clause
-        # did with the same two kinds — see Hecks::Literal.
+        # An append binds several fields at once, each from either a command
+        # argument (a Symbol) or a literal. Spelled through `Literal.render`,
+        # the same self-describing form a where-clause's own value already
+        # uses, rather than a bare Symbol paired with an inspected literal —
+        # see Hecks::Literal.
+        #
+        # @return [Hash{Symbol => String}] the append's field bindings, each
+        #   value rendered through `Literal.render`
         def appended_fields = source.transform_values { |value| Literal.render(value) }
 
+        # Classifies this mutation's source for the wire, the counterpart
+        # `Assembly::Marks#classified` reads back.
+        #
+        # @return [Hash{Symbol => Object}] `{kind: "argument", name:}` for a
+        #   command argument, `{kind: "state", name:}` for a state
+        #   self-reference, or `{kind: "literal", value:}` for a literal value
         def classified_source
           if source.is_a?(Symbol)
             { kind: "argument", name: source.to_s }

data/lib/hecks/bluebook/behaviour/domain_port.rb

@@ -3,17 +3,19 @@ require_relative "traits"
 module Hecks
   module Bluebook
     module Behaviour
-      # WHAT ONE PORT OPERATION DOES.
+      # **What one port operation does**.
       module PortOperation
         include Indexed
 
-        # An operation declares no reference of its own — the OWNER is
+        # An operation declares no reference of its own — the owner is
         # what it acts for, and `identity_attribute` is how that is found.
+        #
+        # @return [nil] always `nil`
         def references = nil
 
-        # NEVER a creating command — a port operation always acts on an
+        # Never a creating command — a port operation always acts on an
         # aggregate that already exists (`operation.to`/`identity_attribute`
-        # both name where its RECEIVER comes from, never a birth). Answered
+        # both name where its receiver comes from, never a birth). Answered
         # explicitly, not derived from `references` the way `Command
         # #creates?` is (`references.nil?` would read every operation as
         # creating, since `references` above is unconditionally nil) —
@@ -21,27 +23,45 @@ module Hecks
         # `target.command.creates?` on a port operation the same way it
         # already does on an ordinary command, and correctly lift a
         # same-aggregate policy's own Event.id as the operation's receiver.
+        #
+        # @return [Boolean] always `false`
         def creates? = false
 
+        # Finds the reference-typed attribute through which this operation addresses
+        # its owning aggregate.
+        #
+        # @param owner_name [String, Symbol] the owning aggregate's name
+        # @return [Bluebook::Attribute, nil] the reference-typed attribute targeting
+        #   `owner_name`, or `nil` if this operation declares none
         def identity_attribute(owner_name)
           @attributes.find { |attribute| attribute.reference? && attribute.type.target_name == owner_name.to_s }
         end
 
-        # THE SAME READING `Command#addressing_key_for` gives, minus its
+        # The same reading `Command#addressing_key_for` gives, minus its
         # self-addressing branch — a port operation's `references` is
         # unconditionally nil (above), so it never means "this verb is
-        # declared ON the very aggregate it acts on" the way a command's
+        # declared on the very aggregate it acts on" the way a command's
         # does; a port operation's only path back to its owner is a real,
         # declared reference-typed attribute, which is exactly what
         # `identity_attribute` already finds. Needed for the identical
         # reason `Command#addressing_key_for` is: `ReactionInvocation
         # #aggregate_aliases` calls it on whatever `target.command` holds,
         # a `PortOperation` now included since a policy can trigger one.
+        #
+        # @param aggregate_name [String, Symbol] the name of the aggregate a row of which
+        #   would address this operation
+        # @return [Symbol, nil] the reference-typed attribute's name a caller passes to
+        #   address that row, or `nil` if this operation cannot be addressed by one
         def addressing_key_for(aggregate_name) = identity_attribute(aggregate_name)&.name
       end
 
-      # WHAT A PORT DOES — one finder over its declared operations.
+      # **What a port does** — one finder over its declared operations.
       module DomainPort
+        # Finds a declared operation by name.
+        #
+        # @param named [String, Symbol] the operation's declared name
+        # @return [Bluebook::PortOperation, nil] the operation, or `nil` if none is
+        #   declared by that name
         def operation(named) = @operations.find { |op| op.hecks_name == named.to_s }
       end
     end

data/lib/hecks/bluebook/behaviour/entity.rb

@@ -3,8 +3,8 @@ require_relative "traits"
 module Hecks
   module Bluebook
     module Behaviour
-      # WHAT AN ENTITY DOES. EXTENDED, not included — an entity is a
-      # CLASS, so this is singleton behaviour.
+      # **What an entity does**. Extended, not included — an entity is a
+      # class, so this is singleton behaviour.
       #
       # `settle` is the same seam an Aggregate has, reached from `absorb`
       # rather than from a constructor because a declared entity is built
@@ -17,41 +17,53 @@ module Hecks
         include Indexed
         include Owns
 
+        # The hook `absorb` calls once every declared field is assigned.
+        #
+        # @return [Class] this entity's own class (a `Bluebook::Entity` subclass), self,
+        #   once identity and indexes are derived
         def settle
           derive_identity
           index_declarations
           self
         end
 
+        # Builds every by-name index this entity answers finders through.
+        #
+        # @return [void]
         def index_declarations
           index_attributes(@attributes)
           @commands_by_name = index_by_hecks_name(@commands)
           @queries_by_name  = index_by_hecks_name(@queries)
         end
 
-        # S17, ADR 0026 — `@entities`, now genuinely NESTED entities
+        # S17, ADR 0026 — `@entities`, now genuinely nested entities
         # (Dispatch, inside Handler) rather than always `[]`. Kept as a
         # real reader rather than a hardcoded empty list for two
         # reasons at once: `Value::Coercion#for_attribute` calls
-        # `.entities` on WHATEVER OWNER it is handed — an aggregate's or
-        # an entity's own — the moment it meets ANY `list_of(...)`
+        # `.entities` on whatever owner it is handed — an aggregate's or
+        # an entity's own — the moment it meets any `list_of(...)`
         # attribute (entity-typed or not — `hydrate_entity_list`'s own
         # fallback, `return value unless entity`, only runs once
         # `.entities` has already answered) ; and `EntityInterpreter`
-        # now walks a DOTTED chain of entities one level at a time
+        # now walks a dotted chain of entities one level at a time
         # (`walk_entity_chain`) exactly the way an aggregate's own
         # `.entities` is walked for its direct children. Entity's own
         # header comment already promises it stays "structurally
         # interchangeable with an aggregate" for exactly this reason.
+        #
+        # @return [Array<Class>] this entity's own nested entities (each a `Bluebook::Entity`
+        #   subclass), or `[]` if it declares none
         def entities = @entities || []
 
-        # A piece OWNS the verbs declared on it, so they can state an
+        # A piece owns the verbs declared on it, so they can state an
         # identity — `Banking::Account.Ledger.Deposit` rather than a
         # command that cannot say what it belongs to. Separate from
-        # `settle` because `declare` stamps AFTER absorbing, once the
+        # `settle` because `declare` stamps after absorbing, once the
         # subclass that will own them exists. `@entities` too now
         # (S17, ADR 0026) — a nested entity states its own owner chain
         # exactly the way a nested command does.
+        #
+        # @return [void]
         def stamp_children = stamp(@commands, @queries, @entities)
       end
     end

data/lib/hecks/bluebook/behaviour/hexagon.rb

@@ -1,18 +1,32 @@
 module Hecks
   module Bluebook
     module Behaviour
-      # WHAT A HECKSAGON DOES — the lookups over its declared binds.
+      # **What a hecksagon does** — the lookups over its declared binds.
       module Hecksagon
         # Aggregate-specific bind wins when one was declared; otherwise
         # falls back to a domain-level default (`b.aggregate.nil?` — see
         # `HecksagonBuilder#method_missing`). Checked directly rather than
         # via `aggregate_name`/`Naming.demodulise`, which would need its own
         # nil-handling for the default row.
+        #
+        # @param aggregate_name [String, Symbol] the aggregate to find a bind for
+        # @param verb [String, Symbol] the port verb name to find a bind for
+        # @return [Bluebook::Bind, nil] the aggregate-specific bind when one is
+        #   declared, the domain-level default bind for `verb` otherwise, or
+        #   `nil` when neither exists
         def bind_for(aggregate_name, verb)
           @binds.find { |b| b.aggregate_name == aggregate_name.to_s && b.verb.to_s == verb.to_s } ||
             @binds.find { |b| b.aggregate.nil? && b.verb.to_s == verb.to_s }
         end
 
+        # Every bind for `verb`, aggregate-specific ones winning as a group over
+        # the domain-level default.
+        #
+        # @param aggregate_name [String, Symbol] the aggregate to find binds for
+        # @param verb [String, Symbol] the port verb name to find binds for
+        # @return [Array<Bluebook::Bind>] every aggregate-specific bind for
+        #   `verb` when any are declared, otherwise every domain-level default
+        #   bind for `verb`
         def binds_for(aggregate_name, verb)
           specific = @binds.select { |b| b.aggregate_name == aggregate_name.to_s && b.verb.to_s == verb.to_s }
           return specific if specific.any?
@@ -21,22 +35,34 @@ module Hecks
         end
       end
 
-      # WHAT A WORLD DOES — settings lookup, with the adapter-specific
+      # **What a world does** — settings lookup, with the adapter-specific
       # entry falling back to the verb's own.
       module World
+        # Finds the generic settings declared for a port verb.
+        #
+        # @param verb [String, Symbol] the port verb name, such as `"persistence"`
+        # @return [Hash{Symbol => Object}] the settings declared for `verb`, or
+        #   `{}` when none are declared
         def for_verb(verb) = @settings.fetch(verb.to_s, {})
 
         # The generic `verb` entry (`persisted_by("Heki") do dir :default
         # end`) only answers for the adapter it actually names — falling
         # back to it unconditionally applies one adapter's settings to an
         # unrelated one. Real, corpus-caught bug: a hecksagon binding two
-        # aggregates to two different adapters under the SAME verb (one to
+        # aggregates to two different adapters under the same verb (one to
         # Heki, one to Memory) sent Memory's lookup down Heki's generic
         # entry, then failed `check_settings` with "Memory does not
         # declare :dir" — the generic entry's own `settings[:adapter]`
         # names Heki, not Memory, so the fallback was never actually for
         # this bind. `{}` is exactly right when nothing was configured for
-        # THIS adapter — Memory, which takes no values at all.
+        # this adapter — Memory, which takes no values at all.
+        #
+        # @param verb [String, Symbol] the port verb name to find settings for
+        # @param adapter [String, Symbol] the adapter name, such as `"Heki"`, to
+        #   find settings for
+        # @return [Hash{Symbol => Object}] the adapter-qualified settings when
+        #   declared, the generic verb settings when they name this same
+        #   adapter, or `{}` otherwise
         def for_binding(verb, adapter)
           qualified = @settings["#{verb}:#{adapter.to_s.downcase}"]
           return qualified if qualified

data/lib/hecks/bluebook/behaviour/lifecycle.rb

@@ -1,27 +1,48 @@
 module Hecks
   module Bluebook
     module Behaviour
-      # WHAT A LIFECYCLE DOES. Its declared half is a field, a starting
-      # state and a transition list. Everything here READS that — which
+      # **What a lifecycle does**. Its declared half is a field, a starting
+      # state and a transition list. Everything here reads that — which
       # states exist, which transition a command takes, and how one
       # declared transition expands into the several rows the emission
       # carries when `from` names more than one source state.
       module Lifecycle
+        # Lists every state this lifecycle can be in.
+        #
+        # @return [Array<String>] every state this lifecycle can be in — the
+        #   default plus each declared transition's own target, deduplicated
         def states
           ([default] + transitions.map { |_command, t| t.target }).uniq
         end
 
+        # Finds every transition a command declares.
+        #
+        # @param command [String, Symbol] the command name to find declared
+        #   transitions for
+        # @return [Array<Bluebook::StateTransition>] every transition declared
+        #   for `command`
         def transitions_for(command)
           transitions.select { |name, _| name == command.to_s }.map { |_, t| t }
         end
 
+        # Finds the state a command moves the record to.
+        #
+        # @param command [String, Symbol] the command name to find the target
+        #   state for
+        # @param current_state [String, Symbol, nil] the record's current
+        #   state, to pick the one declared transition that admits it; `nil`
+        #   to skip that check and take the first declared transition
+        # @return [String, nil] the state `command` moves the record to, or
+        #   `nil` when `command` declares no transition at all
+        # @raise [Runtime::WiringError] if `command` declares transitions but
+        #   none of them admits `current_state`
         def target_for(command, current_state = nil)
           match_transition(command, current_state)&.target
         end
 
         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 — the emission carries them flat, so the
         # fan-out happens here rather than in whatever reads it.
         def expand(command, transition)
@@ -37,10 +58,10 @@ module Hecks
           return nil if matches.empty?
           return matches.first unless current_state
 
-          # NOT `|| matches.first` — that used to silently hand back an
-          # ARBITRARY declared transition for `command` whenever none of
+          # Not `|| matches.first` — that would silently hand back an
+          # arbitrary declared transition for `command` whenever none of
           # them actually admitted `current_state`, picking a `target`
-          # that command dispatch would in fact have refused (that
+          # that command dispatch would in fact refuse (that
           # refusal is `CommandRules::Admissibility#admissible_transition`'s
           # own job, which raises `LifecycleRefused` for exactly this
           # case rather than guessing — this module has no state subject

data/lib/hecks/bluebook/behaviour/policy.rb

@@ -1,34 +1,53 @@
 module Hecks
   module Bluebook
     module Behaviour
-      # WHAT A POLICY DOES. Its declared half is four plain fields; these
+      # **What a policy does**. Its declared half is four plain fields; these
       # are the readings taken off them.
       module Policy
-        # The BLUEBOOK's name for this construct, asked the same way of a class
+        # The bluebook's name for this construct, asked the same way of a class
         # that has crossed over and of an IR object that has not. Collapses into
         # Construct when this one crosses.
+        #
+        # @return [String] this policy's declared name
         def hecks_name = @name
 
+        # The domain-and-aggregate prefix of the triggering event's name.
+        #
+        # @return [String, nil] the part of `on_event` before its first `.`
+        #   (the `"Domain::Aggregate"` prefix), or `nil` when `on_event`
+        #   carries no dot
         def event_qualifier = Naming.qualifier(@on_event)
 
+        # The bare name of the triggering event, without its domain/aggregate
+        # prefix.
+        #
+        # @return [String] the part of `on_event` after its first `.` (the
+        #   bare event name), or the whole string when it carries no dot
         def event_name = Naming.unqualified(@on_event)
 
-        # WHETHER THIS POLICY FANS OUT — `for_each` names a query, and a
+        # Whether this policy fans out — `for_each` names a query, and a
         # non-empty one turns a single reaction into one dispatch per row
         # the query answers. Read by the interpreter that runs the fan-out
         # and by the property that checks it dispatched once per row.
+        #
+        # @return [Boolean] whether `for_each` names a query
         def fans_out? = !@for_each.to_s.empty?
 
-        # WHETHER THIS POLICY IS GUARDED — a non-empty `where` decides
+        # Whether this policy is guarded — a non-empty `where` decides
         # whether the policy fires at all, read against the triggering
         # event's own payload.
+        #
+        # @return [Boolean] whether `where` is declared and non-empty
         def guarded? = !@where.to_s.empty?
 
-        # THE STRUCTURED FORM OF `where`, derived once — the same tree
+        # The structured form of `where`, derived once — the same tree
         # `AstJson.emit_predicate` spells for every rule row, memoized
         # here because a policy is consulted once per event, not once per
         # boot. Nil when there is no `where`, exactly as the wire carries
         # it.
+        #
+        # @return [Hash, nil] the JSON-shaped boolean AST for `where`, or
+        #   `nil` when this policy is not guarded
         def where_ast
           if defined?(@where_ast)
             @where_ast
@@ -40,30 +59,36 @@ module Hecks
         # The rule-shaped reading of the guard, for `Evaluator.call_rule`
         # — a policy's `where` has no description (nothing refuses with
         # it; an unmet where is a silent skip).
+        #
+        # @return [Bluebook::Given] the guard as a rule, with no description
+        #   and its `ast` already resolved via `where_ast`
         def where_rule = @where_rule ||= Given.new(description: nil, canonical: @where, ast: where_ast)
 
-        # THE FAN-OUT QUERY'S ROUTE, split the way the runtime runs it:
+        # The fan-out query's route, split the way the runtime runs it:
         # `[query_domain, aggregate_name, query_name]`. The query runs
-        # against the triggering event's OWN domain unless `for_each`
+        # against the triggering event's own domain unless `for_each`
         # names one ("Domain::Aggregate.query"). Deliberately independent
         # of `across`/`target_domain`, which name where `trigger` fires,
         # not where the fan-out's own query runs.
+        #
+        # @param default_domain [String, Symbol] the triggering event's own
+        #   domain, used when `for_each` names no domain of its own
+        # @return [Array(String, String, String)] `[domain, aggregate_name,
+        #   query_name]` the fan-out query resolves against
         def for_each_route(default_domain)
           path, query_name = @for_each.to_s.split(".", 2)
           domain, aggregate = path.to_s.include?("::") ? path.split("::", 2) : [default_domain.to_s, path]
           [domain, aggregate, query_name]
         end
 
-        # THE ARGUMENT NAME A FAN-OUT DISPATCH mints each matched row's id
-        # under used to be minted HERE, unconditionally, as `<aggregate>
-        # _id` — a real bug: a target command declared ON the very
-        # aggregate it self-references (`Account.Freeze`) is addressed by
-        # its OWN identity field's name, not a synthetic foreign key, and
-        # every such dispatch refused. That question is not this policy's
-        # to answer at all — it depends on the TARGET COMMAND'S OWN
-        # declared shape, not on the aggregate name alone — so it now
-        # lives on `Behaviour::Command#addressing_key_for`, asked of the
-        # resolved target command by `PolicyInterpreter#addressing_key_for`.
+        # The argument name a fan-out dispatch mints each matched row's id
+        # under is not minted here — it depends on the target command's own
+        # declared shape (a target command declared on the very aggregate it
+        # self-references, such as `Account.Freeze`, is addressed by its own
+        # identity field's name, not a synthetic foreign key), not on the
+        # aggregate name alone, so it lives on
+        # `Behaviour::Command#addressing_key_for`, asked of the resolved
+        # target command by `PolicyInterpreter#addressing_key_for`.
       end
     end
   end

data/lib/hecks/bluebook/behaviour/process_manager.rb

@@ -1,13 +1,17 @@
 module Hecks
   module Bluebook
     module Behaviour
-      # WHAT A PROCESS MANAGER DOES. Its declared half is the trigger,
+      # **What a process manager does**. Its declared half is the trigger,
       # the states and the handlers; the compensation half — `saga` — is
-      # DERIVED from the handler that answers a refusal, not declared.
+      # derived from the handler that answers a refusal, not declared.
       module ProcessManager
+        # The bluebook's name for this construct.
+        #
+        # @return [String, nil] the process manager's declared name, or `nil` before it
+        #   is set
         def hecks_name = @name
 
-        # THE LEG THAT ANSWERS — selected by (event, current state), C10.3
+        # The leg that answers — selected by (event, current state), C10.3
         # (docs/semantics/bluebook-semantics.md). Two legs may answer the
         # same event from different states; which one runs is decided by
         # the state the instance is in, never by declaration order. With
@@ -17,39 +21,63 @@ module Hecks
         # selection). Build refuses two legs on one (event, state) pair
         # (`ProcessManagerBuilder#validate!`), so a stated lookup is
         # unambiguous by construction.
+        #
+        # @param event [String, Symbol] the triggering event's name
+        # @param state [String, Symbol, nil] the instance's current state; `nil` asks
+        #   declaratively, ignoring state
+        # @return [Bluebook::ProcessManagerHandler, nil] the matching handler row, or `nil`
+        #   if no declared leg answers this (event, state) pair
         def handler_for(event, state = nil)
           @handlers.find { |h| h.event_type == event.to_s && (state.nil? || h.from_state == state.to_s) }
         end
 
+        # Finds every declared leg for an event, regardless of source state.
+        #
+        # @param event [String, Symbol] the triggering event's name
+        # @return [Array<Bluebook::ProcessManagerHandler>] every handler row declared for
+        #   `event`; `[]` if none is declared
         def handlers_for(event) = @handlers.select { |h| h.event_type == event.to_s }
 
+        # Says whether any declared leg answers an event.
+        #
+        # @param event [String, Symbol] the triggering event's name
+        # @return [Boolean] whether any handler row is declared for `event`
         def handles?(event) = @handlers.any? { |h| h.event_type == event.to_s }
 
-        # WHETHER A STATE IS ONE THIS PROCEDURE DECLARES — asked of a value
+        # Whether a state is one this procedure declares — asked of a value
         # a real run left a saga instance holding (its live or rehydrated
         # state), the way `Lifecycle#states` is asked of an aggregate's
         # resting field. A rehydrated instance in a state no handler could
         # have reached is corruption the durable round-trip introduced.
+        #
+        # @param state [String, Symbol] the state to check
+        # @return [Boolean] whether `state` is one of this procedure's declared states
         def declares_state?(state) = @states.map(&:to_s).include?(state.to_s)
 
+        # Names the payload field a triggering event's instances are correlated by.
+        #
+        # @return [Symbol] the head of `correlates_by` — the part before the first `.`
         def correlation_head = @correlates_by.to_s.split(".").first.to_sym
 
         # The compensation half of a procedure, read off the handler that
-        # answers REFUSED.
+        # answers `REFUSED`.
         #
         # nil for a procedure with no answer to a refusal, which is a legitimate
         # thing to be — a hiring pipeline cannot un-interview anybody.
+        #
+        # @return [Bluebook::Saga, nil] the derived saga, or `nil` if no handler answers
+        #   `REFUSED`
         def saga
           leg = handler_for(Bluebook::ProcessManager::REFUSED)
           return nil unless leg
 
-          # `compensations` — a STATIC PREVIEW, declaration order, not
+          # `compensations` — a static preview, declaration order, not
           # one instance's own runtime history (which legs a given
           # instance actually completed is per-instance state,
           # `SagaInterpreter`'s own `completed_compensations`, not a
           # fact `Saga` — a pure declaration reading — could ever hold).
-          # Every `compensates` ANY handler's own dispatch declares,
-          # forward declaration order, THEN whatever this leg's own
+          # Every `compensates` any handler's own dispatch declares,
+          # forward declaration order, then whatever this leg's own
           # hand-written body still lists — coexistence, not replacement
           # (`ProcessManagerBuilder::HandlerBuilder#dispatch_impl`'s own
           # comment): a saga can derive some of its compensation and
@@ -60,6 +88,9 @@ module Hecks
                              to_state: leg.to_state, compensations: derived + leg.dispatches)
         end
 
+        # Says whether this procedure declares a handler for `REFUSED`.
+        #
+        # @return [Boolean] whether this procedure has a derivable saga
         def saga? = !saga.nil?
       end
     end