hecks 1.4.0 → 1.5.0

data/lib/hecks/bluebook/attribute.rb

@@ -51,6 +51,21 @@ module Hecks
       # The wire carries the name, not the members. A reader resolves it
       # against the IR it holds, so the members are declared once and
       # copied nowhere — which is the same reason `admits` exists at all.
+      #
+      # @param name [Symbol, String] the attribute's name
+      # @param type [Module, Bluebook::Reference, String, Symbol] the bare constant naming
+      #   a primitive or a value object, a `reference_to`-built Reference, or already-spelled
+      #   text
+      # @param list [Boolean] whether this attribute holds a list of values rather than one
+      # @param default [Object, nil] the value a new record starts with when none is given
+      # @param optional [Boolean] whether a command may omit this attribute
+      # @param pattern [String, nil] a regex source the value must match; shared-engine
+      #   subset only (`PatternSubset`)
+      # @param admits [String, nil] an already-declared closed set's aggregate-qualified
+      #   name, such as `"Vocabulary::QueryComparator"`, that the value must belong to
+      # @param relationship [Symbol, nil] the DSL word that minted this attribute
+      #   (`:reference_to`, `:has_many`, `:has_one` or `:belongs_to`), or `nil` for an
+      #   ordinary attribute
       def initialize(name:, type:, list: false, default: nil, optional: false, pattern: nil,
                      admits: nil, relationship: nil)
         @name     = name.to_sym
@@ -77,7 +92,7 @@ module Hecks
       # built against somebody else's aggregate — silently, with no refusal —
       # and the attribute stops meaning what the file plainly says.
       #
-      # DEMODULISED, so both paths spell it the same: `:Target` and
+      # Demodulised, so both paths spell it the same: `:Target` and
       # `QualityControl::Target` are both "Target". A plain class stays itself —
       # `String` demodulises to "String" — so the ordinary case is untouched.
       # This does not undo the constant leak; it makes the leak unable to change
@@ -91,8 +106,7 @@ module Hecks
       private :spell
 
       # Held because a declared vocabulary pins it — spec/vocabulary_conformance
-      # holds `Primitive`'s members to this list. The `primitive?` predicate that
-      # used to read it had no caller anywhere and is gone.
+      # holds `Primitive`'s members to this list.
       PRIMITIVES = Hecks::Vocabulary.fetch("Primitive")
 
       # `type` is spelled, never handed over. A Reference renders as

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

@@ -26,11 +26,17 @@ module Hecks
 
         # An aggregate is a member of its chapter's namespace — "Pizzas::Pizza" —
         # where everything else is declared on its owner and joins with ".".
+        #
+        # @return [String] the literal string `"::"`
         def hecks_separator = "::"
 
         # The hook the generated constructor calls once every declared
         # field is assigned. Nothing here is derivable from the
         # declaration, which is exactly why it is not generated.
+        #
+        # @return [Bluebook::Aggregate] self, once identity is derived, every
+        #   declaration is indexed and its commands, value objects, entities and
+        #   queries are stamped as owned by it
         def settle
           derive_identity
           index_declarations
@@ -40,6 +46,10 @@ module Hecks
           self
         end
 
+        # Builds every by-name finder index `settle` needs — attributes, value
+        # objects, commands, queries, ports and projected fields.
+        #
+        # @return [void]
         def index_declarations
           index_attributes(@attributes)
           @value_objects_by_name = index_by_hecks_name(@value_objects)
@@ -53,6 +63,11 @@ module Hecks
           @projected_fields_by_name = @projected_fields.to_h { |field| [field.name, field] }
         end
 
+        # Finds a declared `projects` field by its declared name.
+        #
+        # @param named [String, Symbol] the projected field's declared name
+        # @return [Bluebook::ProjectedField, nil] the field named `named`, or
+        #   `nil` if none is declared under that name
         def projected_field(named) = @projected_fields_by_name[named.to_sym]
 
         # A value object is a class now, so `name` is Ruby's answer (the constant
@@ -60,7 +75,17 @@ module Hecks
         # out — once an attribute's type is the class there is nothing to find —
         # but every consumer still asks by type string, so it stays until they
         # stop.
+        #
+        # @param named [String, Symbol] the value object's declared name
+        # @return [Class, nil] the value object class (a `Bluebook::ValueObject`
+        #   subclass) named `named`, or `nil` if none is declared under that name
         def value_object(named) = @value_objects_by_name[named.to_s]
+
+        # Finds a port attached to this aggregate by its declared name.
+        #
+        # @param named [String, Symbol] the port's declared name
+        # @return [Bluebook::DomainPort, nil] the port named `named`, or `nil` if
+        #   none is attached under that name
         def port(named)         = @ports_by_name[named.to_s]
 
         # A port is declared in the hecksagon, not the bluebook — the
@@ -71,11 +96,18 @@ module Hecks
         # calls it once per `port` declaration, having already stamped each
         # operation's reference attributes with `declared_in = self`, since
         # nothing upstream of a hecksagon load does that for it.
+        #
+        # @param port [Bluebook::DomainPort] the aggregate-scoped port to attach
+        # @return [void]
         def add_port(port)
           @ports << port
           @ports_by_name[port.name] = port
         end
 
+        # Names the table, file or key persistence adapters store this aggregate
+        # under.
+        #
+        # @return [String] the aggregate's name, snake-cased
         def storage_name = Naming.snake(@name)
       end
     end

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

@@ -6,8 +6,19 @@ module Hecks
       # in `aggregate.bluebook`'s own `Field`. These are the questions
       # readers ask about that shape, which no declaration states.
       module Attribute
+        # Says whether this attribute was declared `list`.
+        #
+        # @return [Boolean] whether this attribute holds a list of values rather than one
         def list?      = @list
+
+        # Says whether this attribute holds a single value rather than a list.
+        #
+        # @return [Boolean] whether this attribute holds a single value rather than a list
         def scalar?    = !@list
+
+        # Says whether this attribute's type is another aggregate reached via `reference_to`.
+        #
+        # @return [Boolean] whether this attribute's type is a `reference_to` another aggregate
         def reference? = @type.is_a?(Reference)
 
         # May this fact be left out?
@@ -20,6 +31,8 @@ module Hecks
         # Only a command enforces this. An aggregate's own attributes are filled
         # by the commands that set them, and a value object's by its
         # constructor ; neither is a payload anyone hands in.
+        #
+        # @return [Boolean] whether a command may omit this attribute from its payload
         def optional? = @optional
       end
     end

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

@@ -16,6 +16,9 @@ module Hecks
         # means), the ports table — which a `.hecksagon` fills later, so
         # the bluebook cannot declare it — and stamping its own children,
         # the same act an Aggregate performs one level down.
+        #
+        # @return [Bluebook::Chapter] self, once root marking, the ports table and ownership
+        #   stamping are all set up
         def settle
           @hecks_root    = true
           @ports         = []
@@ -24,23 +27,54 @@ module Hecks
           self
         end
 
+        # Finds a declared aggregate by name.
+        #
+        # @param named [String, Symbol] the aggregate's declared name
+        # @return [Bluebook::Aggregate, nil] the aggregate, or `nil` if none is declared
+        #   by that name
         def aggregate(named)  = @aggregates.find { |a| a.name == named.to_s }
+
+        # Finds a declared read model by its own name or by the query name it answers.
+        #
+        # @param named [String, Symbol] the read model's declared name, or its query name
+        # @return [Bluebook::ReadModel, nil] the read model, or `nil` if none matches
         def read_model(named) = @read_models.find { |model| model.name == named.to_s || model.query_name == named.to_s }
+
+        # Finds a port declared at this chapter's root by name.
+        #
+        # @param named [String, Symbol] the port's declared name
+        # @return [Bluebook::DomainPort, nil] the port, or `nil` if none is declared
+        #   by that name
         def port(named)       = @ports_by_name[named.to_s]
 
         # What this chapter declared it provides — `{ key => local verb }`
         # for one capability, or nil when it declares none. Read by
-        # everything that used to recognise the Governance chapter by its
-        # name (`Registry#authorization_provider_for`).
+        # everything that resolves a capability's provider from what a
+        # chapter declares, rather than from the chapter's own name
+        # (`Registry#authorization_provider_for`).
+        #
+        # @param capability [String, Symbol] the capability's name, such as
+        #   `Bluebook::Capabilities::AUTHORIZATION`
+        # @return [Hash{Symbol => String}, nil] each declared key mapped to its local verb,
+        #   or `nil` if this chapter declares no `provides` row for that capability
         def provision(capability)
           rows = @provides.select { |row| row.capability == capability.to_s }
           rows.empty? ? nil : rows.to_h { |row| [row.key.to_sym, row.verb] }
         end
 
+        # Says whether this chapter declares that it provides a capability.
+        #
+        # @param capability [String, Symbol] the capability's name
+        # @return [Boolean] whether this chapter declares a `provides` row for that capability
         def provides?(capability) = !provision(capability).nil?
 
         # The declared verb for `key`, qualified with this chapter's own
         # name — the spelling `Dispatcher#dispatch`/`#query` take.
+        #
+        # @param capability [String, Symbol] the capability's name
+        # @param key [String, Symbol] the provided key to resolve
+        # @return [String, nil] the verb qualified as `"ChapterName::verb"`, or `nil` if this
+        #   chapter provides no such capability or key
         def provided_verb(capability, key)
           local = provision(capability)&.fetch(key.to_sym, nil)
           local && "#{name}::#{local}"
@@ -49,11 +83,27 @@ module Hecks
         # A port is declared in the hecksagon, not the bluebook — so it
         # attaches after the chapter already exists, the same way an
         # aggregate's own ports do.
+        #
+        # @param port [Bluebook::DomainPort] the operations-shaped port to attach
+        # @return [void]
         def add_port(port)
           @ports << port
           @ports_by_name[port.name] = port
         end
 
+        # A TRANSLATED REACTION IS ALSO DECLARED IN THE HECKSAGON —
+        # `HecksagonBuilder#translates` builds an ordinary `Policy` (same
+        # shape, same `PolicyInterpreter` runtime, as one written inside a
+        # `policy` block in this chapter's own `.bluebook`) and attaches it
+        # here, after the chapter already exists, the same reasoning
+        # `add_port` gives one method up. Kept out of the bluebook itself
+        # on purpose: which FOREIGN domain's event this chapter reacts to
+        # is a wiring/context-mapping decision, not a fact the domain
+        # states about its own model.
+        def add_policy(policy)
+          @policies << policy
+        end
+
         # Every dispatchable name this chapter answers to, spelled exactly
         # as Dispatcher#dispatch takes it. Derived from the aggregates,
         # never declared — which is why Projections::OIDC can hold its own
@@ -68,6 +118,9 @@ module Hecks
         # already proved out for the meta-domain's own grammar (S17, ADR
         # 0026) — entities nest arbitrarily deep (`Dispatch`, inside
         # `Handler`), so one flat level isn't enough.
+        #
+        # @return [Array<String>] every command verb reachable on this chapter, spelled
+        #   `"Domain::Aggregate.command"` or, nested, `"Domain::Aggregate.Entity.command"`
         def verbs
           @aggregates.flat_map { |agg| aggregate_verbs(agg) }
         end

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

@@ -10,6 +10,9 @@ module Hecks
 
         # 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
@@ -26,6 +29,11 @@ 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`
           # the bare name `Entity` resolves to Behaviour::Entity — this
@@ -37,6 +45,10 @@ 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
@@ -47,6 +59,9 @@ module Hecks
         # 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`
@@ -84,6 +99,11 @@ module Hecks
         # 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
 
@@ -96,11 +116,21 @@ module Hecks
       # 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.
+        # 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

@@ -9,6 +9,8 @@ module Hecks
 
         # 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
@@ -21,8 +23,16 @@ 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
@@ -37,11 +47,21 @@ module Hecks
         # 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.
       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

@@ -17,12 +17,19 @@ 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)
@@ -43,6 +50,9 @@ module Hecks
         # `.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
@@ -52,6 +62,8 @@ module Hecks
         # 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

@@ -8,11 +8,25 @@ module Hecks
         # `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?
@@ -24,6 +38,11 @@ module Hecks
       # **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
@@ -37,6 +56,13 @@ module Hecks
         # 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.
+        #
+        # @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

@@ -7,14 +7,35 @@ module Hecks
       # 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
@@ -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
+          # 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

@@ -7,21 +7,37 @@ module Hecks
         # 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
         # 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 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
@@ -29,6 +45,9 @@ module Hecks
         # 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,6 +59,9 @@ 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:
@@ -48,6 +70,11 @@ module Hecks
         # 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]
@@ -55,15 +82,13 @@ module Hecks
         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`.
+        # 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