hecks 2.7.0 → 2.9.0

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

@@ -4,35 +4,19 @@ module Hecks
   module Bluebook
     module Behaviour
       # What an aggregate does, as opposed to what it holds.
-      #
-      # The holding half — the field list, the readers, the emission — is
-      # the same list the language already declares in
-      # `language/bluebook/aggregate.bluebook`, said a second and third
-      # time in Ruby. This half is not: derived identity, the name
-      # indexes, the owner stamping and the finders are decisions about
-      # how the declared shape is used, and no grammar states them.
-      #
-      # Split so the holding half can be generated from the language
-      # without any of this being in the blast radius of a regeneration.
-      # Everything here is hand-written and permanent.
-      #
-      # The three traits are shared with Entity (and, for `Indexed`,
-      # with Command and PortOperation) — see behaviour/traits.rb on why
-      # they are one module rather than four copies.
+      # Hand-written, so regenerating the declared field list never touches it.
       module Aggregate
         include Identified
         include Indexed
         include Owns
 
-        # An aggregate is a member of its chapter's namespace — "Pizzas::Pizza" —
-        # where everything else is declared on its owner and joins with ".".
+        # An aggregate joins its chapter's namespace with "::" ("Pizzas::Pizza");
+        # everything else joins its owner 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.
+        # The hook the generated constructor calls once every declared field is assigned.
         #
         # @return [Bluebook::Aggregate] self, once identity is derived, every
         #   declaration is indexed and its commands, value objects, entities and
@@ -40,8 +24,7 @@ module Hecks
         def settle
           derive_identity
           index_declarations
-          # An entity stamps its own commands and queries when it is
-          # declared, so the chain closes downward from here.
+          # An entity stamps its own commands and queries when declared.
           stamp(@commands, @value_objects, @entities, @queries)
           self
         end
@@ -56,10 +39,7 @@ module Hecks
           @commands_by_name      = index_by_hecks_name(@commands)
           @queries_by_name       = index_by_hecks_name(@queries)
           @ports_by_name         = @ports.to_h { |port| [port.name, port] }
-          # S12, ADR 0025 — keyed by symbol, the same convention
-          # `Indexed#attribute` already uses; `GuardState` asks for one
-          # by name at every dispatch, the rebuild sweep walks all of
-          # them once per pass.
+          # Keyed by symbol, like `Indexed#attribute` (ADR 0025).
           @projected_fields_by_name = @projected_fields.to_h { |field| [field.name, field] }
         end
 
@@ -70,11 +50,7 @@ module Hecks
         #   `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
-        # path) and the declared name is `hecks_name`. This finder is on its way
-        # 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.
+        # Finds a value object by declared name; `name` on the class is the constant path.
         #
         # @param named [String, Symbol] the value object's declared name
         # @return [Class, nil] the value object class (a `Bluebook::ValueObject`
@@ -88,14 +64,9 @@ module Hecks
         #   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
-        # boundary between the domain and its adapters, in hexagonal terms,
-        # is exactly what a `.hecksagon` file already is for every other
-        # port (persistence, projection, ...). So this attaches after the
-        # aggregate already exists and is registered — `HecksagonBuilder`
-        # 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.
+        # Attaches a port declared in the hecksagon, after the aggregate exists.
+        # `HecksagonBuilder` stamps each operation's reference attributes with
+        # `declared_in = self` before calling it.
         #
         # @param port [Bluebook::DomainPort] the aggregate-scoped port to attach
         # @return [void]

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

@@ -1,10 +1,7 @@
 module Hecks
   module Bluebook
     module Behaviour
-      # **What an attribute does**. The declared half — name, type, list,
-      # default, optional, pattern, admits — is what the language states
-      # in `aggregate.bluebook`'s own `Field`. These are the questions
-      # readers ask about that shape, which no declaration states.
+      # **What an attribute does**: the questions readers ask about its declared shape.
       module Attribute
         # Says whether this attribute was declared `list`.
         #
@@ -21,16 +18,8 @@ module Hecks
         # @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?
-        #
-        # Required is the default and by far the common case — a command takes
-        # the arguments it declares, and all of them — so the exception is what
-        # gets marked. Marking the other way would annotate almost every
-        # attribute in the corpus to say nothing.
-        #
-        # 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.
+        # May this fact be left out? Required is the default; only a command enforces
+        # this, since aggregate and value object attributes are not caller payloads.
         #
         # @return [Boolean] whether a command may omit this attribute from its payload
         def optional? = @optional

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

@@ -3,22 +3,15 @@ require_relative "traits"
 module Hecks
   module Bluebook
     module Behaviour
-      # **What a chapter does**. The declared half is the roll-call of what a
-      # bluebook holds; these are the finders over it, plus `verbs` — the
-      # chapter's own list of every dispatchable name, which is derived
-      # from the aggregates rather than declared anywhere.
+      # What a chapter does. The declared half is the roll-call of what a
+      # bluebook holds; these are the finders over it, plus `verbs`.
       module Chapter
         include Owns
 
-        # The hook the generated constructor calls. Three things a
-        # declaration does not state: that a chapter is the root of the
-        # owner chain (nothing declares it, it is what having no owner
-        # 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.
+        # Marks this chapter the root of the owner chain, attaches the ports
+        # table (filled later by a `.hecksagon`), and stamps ownership.
         #
-        # @return [Bluebook::Chapter] self, once root marking, the ports table and ownership
-        #   stamping are all set up
+        # @return [Bluebook::Chapter] self
         def settle
           @hecks_root    = true
           @ports         = []
@@ -47,11 +40,7 @@ module Hecks
         #   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 resolves a capability's provider from what a
-        # chapter declares, rather than from the chapter's own name
-        # (`Registry#authorization_provider_for`).
+        # What this chapter declared it provides for one capability.
         #
         # @param capability [String, Symbol] the capability's name, such as
         #   `Bluebook::Capabilities::AUTHORIZATION`
@@ -80,9 +69,8 @@ module Hecks
           local && "#{name}::#{local}"
         end
 
-        # 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.
+        # A port attaches after the chapter already exists, once its
+        # hecksagon is built — the same way an aggregate's own ports do.
         #
         # @param port [Bluebook::DomainPort] the operations-shaped port to attach
         # @return [void]
@@ -91,33 +79,20 @@ module Hecks
           @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.
+        # A translated reaction also attaches after the chapter already
+        # exists: which foreign domain's event it reacts to is a wiring
+        # decision, not a fact the domain states about its own model.
+        #
+        # @param policy [Bluebook::Policy] the translated reaction to attach
+        # @return [Array<Bluebook::Policy>] this chapter's policies, with `policy` appended
         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
-        # scope list equal to this and have that mean something.
-        #
-        # Recurses into entities, not just an aggregate's own direct
-        # commands — `Dispatcher#dispatch` already routes a dotted
-        # `Domain::Aggregate.Entity.Command` verb to `EntityInterpreter`
-        # (a command_name with a "." in it), so a verb this method left
-        # out was never "not a verb," only one this list forgot to name.
-        # Ported from the same recursive shape `spec/judge_coverage_spec.rb`
-        # 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.
+        # as `Dispatcher#dispatch` takes it. Derived from the aggregates,
+        # never declared, and recurses into entities since a command can be
+        # nested arbitrarily deep.
         #
         # @return [Array<String>] every command verb reachable on this chapter, spelled
         #   `"Domain::Aggregate.command"` or, nested, `"Domain::Aggregate.Entity.command"`

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

@@ -3,13 +3,11 @@ 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 per verb.
       module Command
         include Indexed
 
-        # Indexed once — attributes are final once absorbed, and every
-        # dispatch asks this finder by name.
+        # Indexes the attributes once; they are final once absorbed.
         #
         # @return [Class] self — the command class, once its attributes are
         #   indexed
@@ -21,25 +19,15 @@ 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 —
-        # 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
-        # about to say exactly that, and nothing would have contradicted them.
-        #
-        # On an aggregate, a creating command acts on no existing root, so nil is
-        # the truth: there is nothing there yet.
+        # self-references, so `creates?` is true for it and cannot decide this alone.
+        # A creating command on an aggregate acts on nothing yet, so nil.
         #
         # @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
-          # 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.
+          # Fully qualified: a bare `Entity` here resolves to Behaviour::Entity, not the construct.
           return hecks_owner if hecks_owner.is_a?(Class) && hecks_owner < Bluebook::Entity
 
           creates? ? nil : hecks_owner
@@ -51,54 +39,18 @@ module Hecks
         #   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
-        # 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.
+        # Every reason this verb can refuse on a rule: the descriptions of its givens and
+        # ensures, as the runtime quotes them after "refused — ". Unnamed rules are skipped.
         #
         # @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
-        # `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`
-        # unconditionally and refused every dispatch to a self-
-        # addressing command as a result — `Account.Freeze`, addressed
-        # by `number`/`account`, not `account_id`).
-        #
-        # 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"):
-        #
-        #   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
-        #   `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
-        #   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>`).
+        # The argument name that addresses an instance of `aggregate_name` for this command.
         #
-        # `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.
+        # Self-addressing commands (`references == aggregate_name`) use the bare reference
+        # key. Cross-referencing ones use the declared reference attribute's own name, never
+        # re-derived from the target, since `as:` names can differ.
         #
         # @param aggregate_name [String, Symbol] the aggregate a fan-out dispatch is
         #   addressing an instance of
@@ -112,14 +64,10 @@ module Hecks
         end
       end
 
-      # **A mutation's own readings**. Included (not extended) — Mutation is
-      # a Struct, so these are instance methods.
+      # **A mutation's own readings**. Included, not extended: Mutation is a Struct.
       module Mutation
-        # 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.
+        # An append binds several fields at once, each from a command argument (a Symbol)
+        # or a literal, spelled through `Literal.render`.
         #
         # @return [Hash{Symbol => String}] the append's field bindings, each
         #   value rendered through `Literal.render`

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

@@ -13,16 +13,8 @@ module Hecks
         # @return [nil] always `nil`
         def references = nil
 
-        # 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
-        # explicitly, not derived from `references` the way `Command
-        # #creates?` is (`references.nil?` would read every operation as
-        # creating, since `references` above is unconditionally nil) —
-        # needed so `ReactionInvocation#source_receiver_for` can call
-        # `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.
+        # A port operation always acts on an existing aggregate. Answered explicitly
+        # because `references.nil?` would read every operation as creating.
         #
         # @return [Boolean] always `false`
         def creates? = false
@@ -37,16 +29,8 @@ module Hecks
           @attributes.find { |attribute| attribute.reference? && attribute.type.target_name == owner_name.to_s }
         end
 
-        # 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
-        # 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.
+        # Like `Command#addressing_key_for` without the self-addressing branch: the
+        # reference attribute is the only path back to the owner.
         #
         # @param aggregate_name [String, Symbol] the name of the aggregate a row of which
         #   would address this operation

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

@@ -6,12 +6,8 @@ module Hecks
       # **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
-      # by subclassing rather than by `new`. The traits are the same
-      # ones, which is the whole point of them being traits: an entity's
-      # identity is derived exactly as an aggregate's is, and was written
-      # out twice before anyone could see that.
+      # `settle` is reached from `absorb` rather than a constructor, because a declared
+      # entity is built by subclassing.
       module Entity
         include Identified
         include Indexed
@@ -36,32 +32,16 @@ module Hecks
           @queries_by_name  = index_by_hecks_name(@queries)
         end
 
-        # 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(...)`
-        # 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
-        # (`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.
+        # Nested entities, structurally interchangeable with an aggregate's `entities`:
+        # `Value::Coercion#for_attribute` and `EntityInterpreter` both read it (ADR 0026).
         #
         # @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
-        # 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
-        # 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.
+        # Stamps this entity as owner of its commands, queries and nested entities, so
+        # verbs read `Banking::Account.Ledger.Deposit`. Separate from `settle` because
+        # `declare` stamps after the owning subclass exists.
         #
         # @return [void]
         def stamp_children = stamp(@commands, @queries, @entities)

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

@@ -1,32 +1,26 @@
 module Hecks
   module Bluebook
     module Behaviour
-      # **What a hecksagon does** — the lookups over its declared binds.
+      # Lookups over a hecksagon's 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.
+        # Finds the bind for an aggregate and verb, falling back to the domain-level default.
         #
-        # @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
+        # The default row is matched with `b.aggregate.nil?` rather than via
+        # `aggregate_name`, which would need its own nil handling.
+        #
+        # @param aggregate_name [String, Symbol]
+        # @param verb [String, Symbol]
+        # @return [Bluebook::Bind, nil]
         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.
+        # Every bind for `verb`; aggregate-specific ones win as a group over the 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`
+        # @param aggregate_name [String, Symbol]
+        # @param verb [String, Symbol]
+        # @return [Array<Bluebook::Bind>]
         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?
@@ -35,34 +29,22 @@ module Hecks
         end
       end
 
-      # **What a world does** — settings lookup, with the adapter-specific
-      # entry falling back to the verb's own.
+      # Settings lookup for a world, with adapter-specific entries falling back to the verb's own.
       module World
-        # Finds the generic settings declared for a port verb.
+        # The 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
+        # @param verb [String, Symbol] such as `"persistence"`
+        # @return [Hash{Symbol => Object}] empty 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
-        # 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.
+        # The generic verb entry only answers for the adapter it names. Falling back to it
+        # unconditionally would apply one adapter's settings (Heki's `dir`) to another
+        # (Memory), which then fails `check_settings`.
         #
-        # @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
+        # @param verb [String, Symbol]
+        # @param adapter [String, Symbol] such as `"Heki"`
+        # @return [Hash{Symbol => Object}] the adapter-qualified settings, else the generic
+        #   ones when they name this adapter, else `{}`
         def for_binding(verb, adapter)
           qualified = @settings["#{verb}:#{adapter.to_s.downcase}"]
           return qualified if qualified

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

@@ -1,50 +1,37 @@
 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
-      # 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.
+      # Readings over a lifecycle's field, starting state and transition list.
       module Lifecycle
-        # Lists every state this lifecycle can be in.
+        # 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
+        # @return [Array<String>] the default plus each transition's target, deduplicated
         def states
           ([default] + transitions.map { |_command, t| t.target }).uniq
         end
 
-        # Finds every transition a command declares.
+        # 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`
+        # @param command [String, Symbol]
+        # @return [Array<Bluebook::StateTransition>]
         def transitions_for(command)
           transitions.select { |name, _| name == command.to_s }.map { |_, t| t }
         end
 
-        # Finds the state a command moves the record to.
+        # 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`
+        # @param command [String, Symbol]
+        # @param current_state [String, Symbol, nil] picks the transition that admits it;
+        #   `nil` takes the first declared transition
+        # @return [String, nil] `nil` when `command` declares no transition
+        # @raise [Runtime::WiringError] if transitions are declared but none 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
-        # than one source state — the emission carries them flat, so the
-        # fan-out happens here rather than in whatever reads it.
+        # A transition whose `from` names several states becomes one row per source state.
         def expand(command, transition)
           sources = transition.from.nil? ? [nil] : Array(transition.from)
 
@@ -58,20 +45,8 @@ module Hecks
           return nil if matches.empty?
           return matches.first unless current_state
 
-          # 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 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
-          # to build that refusal message from, only the two bare
-          # values callers passed in). Zero production callers reach
-          # this branch today (both real dispatch paths that check a
-          # transition go through `admissible_transition`, not
-          # `target_for`/`match_transition`), so this raise is a
-          # backstop, not a live behaviour change — same shape as
-          # `CommandRules::Arithmetic#sign_of`'s own fix.
+          # No `|| matches.first`: that would return a target command dispatch refuses.
+          # `CommandRules::Admissibility#admissible_transition` owns the real refusal.
           matches.find { |t| applies_from?(t, current_state) } ||
             raise(Runtime::WiringError,
                   "no transition for #{command.inspect} admits state #{current_state.inspect} " \