hecks 1.3.0 → 1.5.0

data/lib/hecks/runtime/command_rules/admissibility.rb

@@ -11,7 +11,7 @@ module Hecks
       # Whether a command may run at all: its declared givens, and the
       # lifecycle transition it asks for.
       module Admissibility
-        # WRAPS `subject` so a guard can read a DECLARED-but-storage-absent
+        # Wraps `subject` so a guard can read a declared-but-storage-absent
         # optional attribute as nil, not "cannot resolve." `Instance
         # #hydrate_with_defaults` deliberately leaves one absent rather
         # than nil-filled — "an attribute with no default stays absent,
@@ -25,10 +25,10 @@ module Hecks
         # exact behavior, zero risk to a path this bug was never measured
         # against.
         #
-        # NIL IS NOT THE ONLY OUTCOME, though. The Item.Promote fix above
-        # covered an OPTIONAL field — the honest case, where absence is
+        # NIL is not the only outcome, though. The Item.Promote fix above
+        # covered an optional field — the honest case, where absence is
         # exactly what optional means. It also, as a side effect, let a
-        # NON-optional field predating a record read nil the same way,
+        # non-optional field predating a record read nil the same way,
         # which is the `ne:`/array-`in:` bug class applied to rule
         # evaluation: a predicate silently answers against a value nobody
         # ever wrote (ADR 0025, "Added attributes and absence"). `[]`
@@ -37,17 +37,19 @@ module Hecks
         # identifying the field, so a rule that reads it fails loud
         # instead of quietly wrong.
         class GuardState
+          # @param instance [Runtime::Instance] the record a `given`/`ensures`/
+          #   `invariant` rule reads state from
           def initialize(instance)
             @instance = instance
             @declared = instance.respond_to?(:aggregate) ? instance.aggregate.attributes.to_h { |a| [a.name, a] } : {}
-            # S12, ADR 0025 — a SEPARATE index, the same reason
+            # S12, ADR 0025 — a separate index, the same reason
             # `Aggregate#projected_fields` is a separate IR collection
             # rather than folded into `attributes` (see that field's
             # own comment): a projected field's absence means
             # something different from an ordinary attribute's, so it
             # needs its own refusal below, not `AttributeAbsent`'s.
-            # `projects` is AGGREGATE-scoped only — an entity's own
-            # `instance.aggregate` answers the ENTITY construct here
+            # `projects` is aggregate-scoped only — an entity's own
+            # `instance.aggregate` answers the entity construct here
             # (EntityInterpreter's own subject), which declares no
             # `projected_fields` of its own, hence the extra guard
             # `@declared` above does not need.
@@ -55,8 +57,23 @@ module Hecks
             @projected = owner.respond_to?(:projected_fields) ? owner.projected_fields.to_h { |f| [f.name, f] } : {}
           end
 
+          # Reports whether `name` is a declared attribute, a projected field, or
+          # a key `instance`'s own state actually holds.
+          #
+          # @param name [String, Symbol] the field name to check
+          # @return [Boolean] true if `name` is readable one of those three ways
           def key?(name) = @declared.key?(name.to_sym) || @projected.key?(name.to_sym) || @instance.key?(name)
 
+          # Reads one field, the way a `given`/`ensures`/`invariant` rule expects
+          # absence to read.
+          #
+          # @param name [String, Symbol] the field name to read
+          # @return [Object, nil] the stored value; nil for a declared, optional
+          #   attribute the record predates
+          # @raise [Runtime::AttributeAbsent] if `name` is a declared, non-optional
+          #   attribute the record's own state does not hold
+          # @raise [Runtime::ProjectionAbsent] if `name` is a `projects` field the
+          #   record's own state does not hold
           def [](name)
             return @instance[name] if @instance.key?(name)
 
@@ -67,17 +84,17 @@ module Hecks
             return nil if attribute.nil? || attribute.optional?
 
             raise AttributeAbsent,
-                  RefusalWording.render("AttributeAbsent", "absent_read",
-                                        aggregate: @instance.aggregate.hecks_name, field: name)
+                  RefusalWording.render_site("AttributeAbsent", "absent_read",
+                                             aggregate: @instance.aggregate.hecks_name, field: name)
           end
 
           private
 
           def raise_projection_absent(projected)
             raise ProjectionAbsent,
-                  RefusalWording.render("ProjectionAbsent", "absent_read",
-                                        aggregate: @instance.aggregate.hecks_name, field: projected.name,
-                                        reference: projected.reference, remote_field: projected.remote_field)
+                  RefusalWording.render_site("ProjectionAbsent", "absent_read",
+                                             aggregate: @instance.aggregate.hecks_name, field: projected.name,
+                                             reference: projected.reference, remote_field: projected.remote_field)
           end
         end
         private_constant :GuardState
@@ -89,54 +106,74 @@ module Hecks
         # `Instance`); a `subject` with no `.aggregate` just hydrates
         # nothing from state, same as GuardState degrades above.
         #
-        # MERGE ORDER MATTERS, and it is NOT "args always win": an
+        # Merge order matters, and it is not "args always win": an
         # unaliased command-level reference dereferences under a
         # different name than the argument holds (`account_id` the arg,
         # `account` the hydrated key — no collision, order is moot). An
-        # ALIASED one (`reference_to Customer, as: :customer`) hydrates
-        # under the SAME name the argument itself holds — `customer` is
+        # aliased one (`reference_to Customer, as: :customer`) hydrates
+        # under the same name the argument itself holds — `customer` is
         # both the raw id an arg puts there and the key `customer.status`
         # expects to dig into. If `args` merged last, the raw id (a
         # String) would win and `.status` on a String is where a fuzzer
         # found this — TypeError, not a refusal. Command-level
-        # dereferencing is the one thing that is SUPPOSED to override
+        # dereferencing is the one thing that is supposed to override
         # its own source argument for exactly this reason; args still
-        # wins over stored OWNER state (unchanged from before this fix).
-        # `parent:` is an entity command's OWN parent aggregate record
-        # (EntityInterpreter's `ctx.instance` — "the PARENT aggregate
+        # wins over stored owner state.
+        # `parent:` is an entity command's own parent aggregate record
+        # (EntityInterpreter's `ctx.instance` — "the parent aggregate
         # record", its own doc comment) — the entity's containment, not a
         # declared reference attribute, so it doesn't come from
         # `dereference`'s attribute scan the way `owner`'s do. Hydrated
-        # the same shape regardless: the parent's own state, MERGED so
+        # the same shape regardless: the parent's own state, merged so
         # the dereferenced hash wins over the raw reference it replaces
-        # (ADR 0025 dropped the `_id` suffix that used to keep the two
+        # (ADR 0025 drops the `_id` suffix that once kept the two
         # apart by name, so `parent.state.merge(dereference(...))` is
-        # now load-bearing, not redundant) — plus ITS OWN references
+        # load-bearing, not redundant) — plus its own references
         # dereferenced one level in, so `parent.customer.status` (a
-        # parent aggregate reaching ITS OWN customer) resolves the same
+        # parent aggregate reaching its own customer) resolves the same
         # way `account.customer.status` does for a command-level reference.
         # nil for an aggregate command — CommandInterpreter never passes it.
         # `correction:` — the `{as_name => payload}` bindings
         # `enforce_correction_target` (above) already located, merged in
-        # LAST so an `as:` name wins the same way `old:` always wins in
+        # last so an `as:` name wins the same way `old:` always wins in
         # `enforce_ensures`, below — it is a fresh local binding a
         # `corrects` command introduces, not a real argument/state field
         # a caller could collide with by accident.
+        #
+        # @param subject [Runtime::Instance] the pre-mutation record a `given` is
+        #   checked against
+        # @param command [Class] the command class (`Bluebook::Command` subclass)
+        #   whose declared `givens` are checked
+        # @param args [Hash{String, Symbol => Object}] the offered command arguments,
+        #   readable by a given
+        # @param domain [String, Symbol] the domain a reference-typed argument is
+        #   dereferenced in
+        # @param declaring [Bluebook::Aggregate, Bluebook::Entity, nil] the construct
+        #   `command` is declared on; also checks `enforce_lifecycle_guard` when given
+        # @param parent [Runtime::Instance, nil] an entity command's own parent
+        #   aggregate record, readable as `parent.*`; nil for an aggregate command
+        # @param correction [Hash{Symbol => Object}] the `{as_name => payload}`
+        #   bindings a `corrects` command's located old event offers
+        # @return [void]
+        # @raise [Runtime::GivenNotMet] if a declared `given` does not hold
+        # @raise [Runtime::LifecycleRefused] if `declaring` is given and the command's
+        #   own `from:` guard refuses the record's current lifecycle state
+        # @raise [Bluebook::Expression::EvaluationError] if a given's own rule cannot
+        #   be evaluated (an unresolvable field, a bad comparison)
         def enforce_givens(subject, command, args, domain:, declaring: nil, parent: nil, correction: {})
           state = GuardState.new(subject)
-          # A RULE MAY ONLY READ WITHIN ITS OWN AGGREGATE BOUNDARY (S12,
-          # ADR 0025) — `subject`'s own STORED references are no longer
-          # dereferenced here at all. What used to be a live query against
-          # another aggregate's own repository is now just `subject`'s own
-          # state: a `projects :customer_status, from: :"customer.status"`
-          # field is a REGULAR stored attribute, already present in
+          # A rule may only read within its own aggregate boundary (S12,
+          # ADR 0025) — `subject`'s own stored references are no longer
+          # dereferenced here at all: a `projects :customer_status, from:
+          # :"customer.status"` field is just `subject`'s own
+          # field, a regular stored attribute, already present in
           # `subject`/`state` with no hydration step needed. `dereference`
           # is still called on `command`/`args`, below — that is a
-          # DIFFERENT case the ADR explicitly keeps in bounds ("its command
-          # arguments"): a reference-typed ARGUMENT this dispatch was just
+          # different case the ADR explicitly keeps in bounds ("its command
+          # arguments"): a reference-typed argument this dispatch was just
           # handed (`Dispute`'s own `disputed_by`, say) has nothing stored
           # to project yet, so resolving it here, once, synchronously with
-          # THIS command's own admission, is not the live-query-against-
+          # this command's own admission, is not the live-query-against-
           # another-aggregate's-stored-state pattern the boundary rule
           # forbids.
           attrs = args.merge(dereference(domain, command, args))
@@ -154,42 +191,90 @@ module Hecks
           enforce_lifecycle_guard(declaring, command, subject) if declaring
         end
 
-        # `corrects` — CommandBuilder#corrects_impl's own comment. NOT
+        # `corrects` — CommandBuilder#corrects_impl's own comment. Not
         # expressible as an ordinary `given`: "has this exact record
         # already emitted this exact event" is not a predicate over the
-        # record's OWN fields, it is a fact about the event log, so it is
+        # record's own fields, it is a fact about the event log, so it is
         # raised structurally here, the same way NotFound/AlreadyExists
         # are, rather than through the expression evaluator. The build-
-        # time half — does ANYTHING in this aggregate ever emit the named
+        # time half — does anything in this aggregate ever emit the named
         # event at all — is `AggregateBuilder#seal_correction_targets`;
-        # this is the dispatch-time half — has THIS record actually done
+        # this is the dispatch-time half — has this record actually done
         # so yet.
         #
-        # ALSO LOCATES the matched event now, not just its existence, and
+        # Also locates the matched event now, not just its existence, and
         # returns a `{as_name => payload}` bindings hash — one entry per
         # `:corrects` mutation that named an `as:` — so `given`/`ensures`
-        # on a corrects-bearing command can reference the located OLD
+        # on a corrects-bearing command can reference the located old
         # event by that name, the same shape `enforce_ensures`'s own
         # `old:` binding already has (CommandBuilder#corrects_impl's own
         # comment: `as:` was stored, from the start, specifically to be
         # wired into the evaluator once a real runtime consumer existed —
-        # this is that consumer). `.reverse.find` — the MOST RECENT
+        # this is that consumer). `.reverse.find` — the most recent
         # matching event, if this record has somehow emitted the same
         # correction target more than once; the prior existence-only
         # check never had to make this choice, so it's a genuinely new
         # one, made deliberately: `as:` reads as "the instance being
         # corrected," which is naturally the latest fact on record, not
         # an arbitrary one.
+        # Reads the durable event history a `corrects` mutation is judged against.
+        #
         # C9.2 (docs/semantics/bluebook-semantics.md) — a correction target
-        # is judged against the record's DURABLE history: the events the
+        # is judged against the record's durable history: the events the
         # aggregate's own store recorded (`AppendOnly#events`), which
         # survive a restart the way the Rust kernel's persisted
         # `emitted_<event>` flag does. The in-process log is the fallback
         # only for an adapter that records no readable history.
+        #
+        # @param domain [String, Symbol] the domain `aggregate` belongs to
+        # @param aggregate [Bluebook::Aggregate] the aggregate whose repository is read
+        # @return [Array<Runtime::Event>] the aggregate's own durably recorded events
+        #   if its repository keeps a readable log, otherwise the registry's in-process
+        #   event log
         def correction_history(domain, aggregate)
           @registry.repository(domain, aggregate).events || @registry.event_log
         end
 
+        # Locates each `:corrects` mutation's own already-emitted target event, and
+        # binds every `as:`-named one for `given`/`ensures` to reference.
+        #
+        # `corrects` — CommandBuilder#corrects_impl's own comment. Not
+        # expressible as an ordinary `given`: "has this exact record
+        # already emitted this exact event" is not a predicate over the
+        # record's own fields, it is a fact about the event log, so it is
+        # raised structurally here, the same way NotFound/AlreadyExists
+        # are, rather than through the expression evaluator. The build-
+        # time half — does anything in this aggregate ever emit the named
+        # event at all — is `AggregateBuilder#seal_correction_targets`;
+        # this is the dispatch-time half — has this record actually done
+        # so yet.
+        #
+        # Also locates the matched event now, not just its existence, and
+        # returns a `{as_name => payload}` bindings hash — one entry per
+        # `:corrects` mutation that named an `as:` — so `given`/`ensures`
+        # on a corrects-bearing command can reference the located old
+        # event by that name, the same shape `enforce_ensures`'s own
+        # `old:` binding already has (CommandBuilder#corrects_impl's own
+        # comment: `as:` was stored, from the start, specifically to be
+        # wired into the evaluator once a real runtime consumer existed —
+        # this is that consumer). `.reverse.find` — the most recent
+        # matching event, if this record has somehow emitted the same
+        # correction target more than once; the prior existence-only
+        # check never had to make this choice, so it's a genuinely new
+        # one, made deliberately: `as:` reads as "the instance being
+        # corrected," which is naturally the latest fact on record, not
+        # an arbitrary one.
+        #
+        # @param instance [Runtime::Instance] the record being corrected
+        # @param aggregate [Bluebook::Aggregate] the aggregate `instance` belongs to
+        # @param command [Class] the command class (`Bluebook::Command` subclass)
+        #   whose `:corrects` mutations are located
+        # @param domain [String, Symbol] the domain `aggregate` belongs to
+        # @return [Hash{Symbol => Object}] the located event's payload, keyed by
+        #   each `:corrects` mutation's own `as:` name; empty for a mutation with
+        #   no `as:`
+        # @raise [Runtime::NothingToCorrect] if a `:corrects` mutation names an
+        #   event `instance` has never emitted
         def enforce_correction_target(instance, aggregate, command, domain:)
           bindings = {}
           command.mutations.each do |mutation|
@@ -213,15 +298,25 @@ module Hecks
           bindings
         end
 
-        # LIFECYCLE STATE AS A COMMAND GUARD (S10, ADR 0025) — `command
-        # "Debit", from: "open"` checked here, folded into the SAME
+        # Lifecycle state as a command guard (S10, ADR 0025) — `command
+        # "Debit", from: "open"` checked here, folded into the same
         # dispatch step `given` already runs at (both are preconditions,
         # evaluated before any mutation) rather than earning its own
-        # DISPATCH_ORDER entry. A GUARD, never a transition: it names no
+        # DISPATCH_ORDER entry. A guard, never a transition: it names no
         # target state and `step_advance_lifecycle` never sees it — see
         # `admissible_transition`, right below, for the transition this
-        # is deliberately NOT reusing (its own `StateTransition#target`
+        # is deliberately not reusing (its own `StateTransition#target`
         # is required, and a guard-only command has none to give it).
+        #
+        # @param declaring [Bluebook::Aggregate, Bluebook::Entity] the construct
+        #   whose lifecycle field is checked
+        # @param command [Class] the command class (`Bluebook::Command` subclass)
+        #   whose `from:` guard is checked
+        # @param subject [Runtime::Instance] the pre-mutation record to read the
+        #   current lifecycle state off
+        # @return [void]
+        # @raise [Runtime::LifecycleRefused] if `command` declares `from:` and the
+        #   record's current lifecycle state is not one of them
         def enforce_lifecycle_guard(declaring, command, subject)
           return unless command.from
 
@@ -229,49 +324,68 @@ module Hecks
           current   = Value.scalar(subject[lifecycle.field]).to_s
           return if Array(command.from).include?(current)
 
-          # ROUTED THROUGH RefusalWording's OWN "transition_blocked"
-          # TEMPLATE — the same one #admissible_transition, right below,
+          # Routed through RefusalWording's own "transition_blocked"
+          # template — the same one #admissible_transition, right below,
           # already raises LifecycleRefused through for the same
-          # refusal class. This used to hand-roll its own wording
+          # refusal class, rather than hand-rolling its own wording
           # inline ("...only runs from..." vs. the template's "...moves
-          # it only from...") — two shapes for one refusal kind, so
+          # it only from..."), two shapes for one refusal kind, so
           # anything string-matching a LifecycleRefused message (a
-          # property, a spec, a caller) had to know both existed rather
-          # than one.
+          # property, a spec, a caller) would have to know both existed
+          # rather than one.
           raise LifecycleRefused,
-                RefusalWording.render("LifecycleRefused", "transition_blocked",
-                                      command: command.hecks_name, field: lifecycle.field,
-                                      current: Rendering.describe(current),
-                                      allowed: Array(command.from).map(&:inspect).join(" or "))
+                RefusalWording.render_site("LifecycleRefused", "transition_blocked",
+                                           command: command.hecks_name, field: lifecycle.field,
+                                           current: Rendering.describe(current),
+                                           allowed: Array(command.from))
         end
 
-        # The far side of the contract: evaluated against the SETTLED record
+        # The far side of the contract: evaluated against the settled record
         # — after mutations and the lifecycle move, before anything persists
         # — with `old` carrying the state as the givens saw it. Injected into
         # the attrs at evaluation time only; the payload gate never sees it.
         #
-        # `old` — and every dispatch ARGUMENT — wins over a same-named STATE
+        # `old` — and every dispatch argument — wins over a same-named state
         # field in expression scope (Resolver#fetch checks attrs first). An
         # ensures naming a field the command also takes as an argument (or,
         # on an entity, a field that doubles as the addressing argument
-        # element_of reads) will read the ARGUMENT, not the settled value.
+        # element_of reads) will read the argument, not the settled value.
         # Not new to ensures — `given` lives under the same rule — but an
         # ensures is more likely to collide, since it typically re-reads a
         # field the command just took in to mutate it.
+        #
+        # @param subject [Runtime::Instance] the settled, post-mutation record an
+        #   `ensures` is checked against
+        # @param command [Class] the command class (`Bluebook::Command` subclass)
+        #   whose declared `ensures` are checked
+        # @param args [Hash{String, Symbol => Object}] the offered command arguments,
+        #   readable by an ensures unless `subject` shares the same field name
+        # @param old [Hash{Symbol => Object}, nil] the pre-mutation state, readable
+        #   as `old.*`; nil when `command` declares no ensures (dup skipped upstream)
+        # @param domain [String, Symbol] the domain a reference-typed argument is
+        #   dereferenced in
+        # @param parent [Runtime::Instance, nil] an entity command's own parent
+        #   aggregate record, readable as `parent.*`; nil for an aggregate command
+        # @param correction [Hash{Symbol => Object}] the `{as_name => payload}`
+        #   bindings a `corrects` command's located old event offers
+        # @return [void]
+        # @raise [Runtime::EnsuresNotMet] if a declared `ensures` does not hold
+        # @raise [Bluebook::Expression::EvaluationError] if an ensures's own rule
+        #   cannot be evaluated (an unresolvable field, a bad comparison)
         def enforce_ensures(subject, command, args, old:, domain:, parent: nil, correction: {})
           state = GuardState.new(subject)
           # S12, ADR 0025 — same boundary reasoning as enforce_givens
           # above: `subject`'s own stored references are no longer
           # dereferenced here; a `projects`-maintained field is already
           # part of `state`. `command`/`args` still dereferences — a
-          # fresh reference-typed ARGUMENT stays in bounds.
+          # fresh reference-typed argument stays in bounds.
           # `old` still wins over everything, unchanged. `correction`
           # (an `as:`-bound corrected event, if this command declares
           # one) wins right alongside it — a settled-record ensures can
           # reference the correction target exactly as freely as a
           # pre-mutation given already can.
           # C2.3 (docs/semantics/bluebook-semantics.md) — an ensures reads
-          # the SETTLED STATE first: an argument that shares a field's
+          # the settled state first: an argument that shares a field's
           # name does not shadow the candidate here (it does in a given,
           # C2.2), so `sets :note` + `ensures { note == ... }` judges what
           # landed, and `old.<field>` remains the pre-state.
@@ -286,25 +400,37 @@ module Hecks
           end
         end
 
-        # THE AGGREGATE BOUNDARY, checked after every command, before
+        # The aggregate boundary, checked after every command, before
         # save (S10, ADR 0025 — "Rules") — the same point `enforce_
         # ensures` already checks at, and for the same reason: an
-        # invariant is a claim about the SETTLED record, not the
+        # invariant is a claim about the settled record, not the
         # command that produced it, so it reads no `args`/`old` at all,
         # only the record's own state. `subject` here is
-        # always the AGGREGATE's own instance — `CommandInterpreter`
+        # always the aggregate's own instance — `CommandInterpreter`
         # passes its own `ctx.instance`, and `EntityInterpreter` passes
-        # the PARENT record (`ctx.instance`, not the element), since an
-        # entity mutation changes data inside the SAME aggregate
+        # the parent record (`ctx.instance`, not the element), since an
+        # entity mutation changes data inside the same aggregate
         # boundary the invariant guards; there is no separate "entity
         # invariant" to check the piece's own view against.
         #
-        # NO `dereference` (S12, ADR 0025) — an invariant may only read
+        # No `dereference` (S12, ADR 0025) — an invariant may only read
         # `subject`'s own boundary, same rule `enforce_givens`/
         # `enforce_ensures` now hold to. No invariant in the corpus has
-        # ever read across a `reference_to` (verified before this
-        # change), so this is not a migration, just closing the same
-        # capability off here that was already unused.
+        # ever read across a `reference_to` (verified by grep), so this
+        # is not a migration, just closing the same capability off here
+        # that was already unused.
+        #
+        # @param subject [Runtime::Instance] the settled aggregate record an
+        #   invariant is checked against
+        # @param aggregate [Bluebook::Aggregate] the aggregate whose declared
+        #   `invariants` are checked
+        # @param domain [String, Symbol] the domain `aggregate` belongs to, passed
+        #   through to `check_entity_invariants`
+        # @return [void]
+        # @raise [Runtime::InvariantViolation] if a declared invariant does not hold,
+        #   on `aggregate` itself or any of its entities
+        # @raise [Bluebook::Expression::EvaluationError] if an invariant's own rule
+        #   cannot be evaluated (an unresolvable field, a bad comparison)
         def enforce_invariants(subject, aggregate, domain:)
           state = GuardState.new(subject)
           attrs = {}
@@ -317,20 +443,20 @@ module Hecks
           check_entity_invariants(aggregate, subject, domain: domain)
         end
 
-        # A PIECE'S OWN SHAPE RULE, checked against EVERY INSTANCE the
+        # A piece's own shape rule, checked against every instance the
         # aggregate holds — not a separate boundary from the aggregate's
         # own invariants just above (same two checkpoints: after every
-        # mutation, before save), just a WIDER one: the aggregate's own
+        # mutation, before save), just a wider one: the aggregate's own
         # consistency includes each of its pieces individually looking
         # right, the same way `ValueObject#invariants` already checks
-        # each of ITS OWN instances one construct up. RECURSES into
+        # each of its own instances one construct up. Recurses into
         # nested pieces (S17, ADR 0026 — Dispatch inside Handler) the
         # same way `check_entity_invariants`'s own caller recurses
         # nowhere else needs to, since a piece's `entities` are already
         # exactly as reachable as an aggregate's.
         #
-        # `list_attr` reuses the EXACT lookup `EntityInterpreter#
-        # element_of` already makes to locate a SINGLE addressed
+        # `list_attr` reuses the exact lookup `EntityInterpreter#
+        # element_of` already makes to locate a single addressed
         # element by identity — this reads every element instead, but
         # the "which field on the owner holds this piece's own
         # instances" question is the identical one. A piece declaring
@@ -338,6 +464,17 @@ module Hecks
         # matching list attribute) is a static-analysis gap for a
         # future gate, not a runtime concern here — `next` past it
         # rather than raising mid-enforcement for an unrelated command.
+        #
+        # @param owner_construct [Bluebook::Aggregate, Bluebook::Entity] the
+        #   construct whose nested entities are checked
+        # @param owner_instance [Runtime::Instance] the settled record holding
+        #   `owner_construct`'s own entity lists
+        # @param domain [String, Symbol] the domain `owner_construct` belongs to
+        # @return [void]
+        # @raise [Runtime::InvariantViolation] if a declared entity invariant does
+        #   not hold, on any element or its own nested entities
+        # @raise [Bluebook::Expression::EvaluationError] if an invariant's own rule
+        #   cannot be evaluated (an unresolvable field, a bad comparison)
         def check_entity_invariants(owner_construct, owner_instance, domain:)
           owner_construct.entities.each do |entity|
             next if entity.invariants.empty?
@@ -348,7 +485,7 @@ module Hecks
             Array(owner_instance[list_attr.name]).each do |element|
               wrapped = Instance.new(aggregate: entity, id: nil, state: element)
               element_state = GuardState.new(wrapped)
-              # NO `dereference` (S12, ADR 0025) — same boundary rule as
+              # No `dereference` (S12, ADR 0025) — same boundary rule as
               # enforce_invariants above; `parent` (the owner's own
               # state, projected fields included) stays readable.
               attrs = { parent: owner_instance.state }
@@ -364,6 +501,20 @@ module Hecks
           end
         end
 
+        # Finds the lifecycle transition `command` admits from `subject`'s current
+        # state, if `declaring` declares a lifecycle and `command` moves it.
+        #
+        # @param declaring [Bluebook::Aggregate, Bluebook::Entity] the construct
+        #   whose lifecycle is checked
+        # @param command [Class] the command class (`Bluebook::Command` subclass)
+        #   to find a declared transition for
+        # @param subject [Runtime::Instance] the pre-mutation record to read the
+        #   current lifecycle state off
+        # @return [Bluebook::StateTransition, nil] the admitted transition, or nil
+        #   when `declaring` has no lifecycle or `command` declares no transition
+        # @raise [Runtime::LifecycleRefused] if `command` declares one or more
+        #   transitions, each constrained by its own `from:`, and none admits the
+        #   record's current lifecycle state
         def admissible_transition(declaring, command, subject)
           lifecycle = declaring.lifecycle
           return nil unless lifecycle
@@ -379,7 +530,7 @@ module Hecks
           # default `Object#to_s` instead of unwrapping the inner
           # scalar first -- `current` came back as a raw object-pointer
           # string (`"#<Hecks::Runtime::Value:0x...>"`) that could
-          # never match any declared `from` state, so EVERY transition
+          # never match any declared `from` state, so every transition
           # on a VO-typed lifecycle field refused unconditionally, and
           # when it refused the message leaked the pointer too.
           # Confirmed live via `Plan::Task.Complete` (status defaults to
@@ -399,10 +550,10 @@ module Hecks
 
           allowed = candidates.flat_map { |t| Array(t.from) }.uniq
           raise LifecycleRefused,
-                RefusalWording.render("LifecycleRefused", "transition_blocked",
-                                      command: command.hecks_name, field: lifecycle.field,
-                                      current: Rendering.describe(current),
-                                      allowed: allowed.map(&:inspect).join(" or "))
+                RefusalWording.render_site("LifecycleRefused", "transition_blocked",
+                                           command: command.hecks_name, field: lifecycle.field,
+                                           current: Rendering.describe(current),
+                                           allowed: allowed)
         end
       end
     end