hecks 1.4.0 → 1.5.0

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

@@ -37,6 +37,8 @@ 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] } : {}
@@ -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)
 
@@ -101,7 +118,7 @@ module Hecks
         # found this — TypeError, not a refusal. Command-level
         # 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).
+        # 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
@@ -109,9 +126,9 @@ module Hecks
         # `dereference`'s attribute scan the way `owner`'s do. Hydrated
         # 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
         # way `account.customer.status` does for a command-level reference.
@@ -122,14 +139,34 @@ module Hecks
         # `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
+          # 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
@@ -180,16 +217,64 @@ module Hecks
         # 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
         # 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|
@@ -222,6 +307,16 @@ module Hecks
         # `admissible_transition`, right below, for the transition this
         # 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
 
@@ -232,12 +327,12 @@ module Hecks
           # 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_site("LifecycleRefused", "transition_blocked",
                                            command: command.hecks_name, field: lifecycle.field,
@@ -258,6 +353,25 @@ module Hecks
         # 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
@@ -302,9 +416,21 @@ module Hecks
         # 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 = {}
@@ -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?
@@ -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

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

@@ -279,6 +279,9 @@ module Hecks
           bounded(current * amount, "multiply", current, amount, "*")
         end
 
+        # Bounds an attribute's current value into `[min, max]`, on a bare number or on
+        # the one numeric field the wrapping value object carries.
+        #
         # Vendored addition, not (yet) upstream hecks (migration plan
         # task 4, i106): bound the current value into `[min, max]` -- no
         # "amount" to combine, so it does not go through
@@ -286,6 +289,15 @@ module Hecks
         # it clamps whichever single numeric field the wrapping value
         # object carries (a synthesised wrapper always carries exactly
         # one, per Part 3a's auto-synthesis).
+        #
+        # @param current [Numeric, Runtime::Value, nil] the attribute's pre-dispatch value; nil
+        #   (never set) counts as 0
+        # @param bounds [Array<Numeric>] the two-element `[min, max]` range to clamp into
+        # @param target [Symbol, String] name of the attribute, used only to word a refusal
+        # @return [Numeric, Runtime::Value] the clamped value: a `Runtime::Value` when
+        #   `current` is one, otherwise a bare number the caller re-wraps
+        # @raise [Runtime::TypeMismatch] if `current` is a value object with no single
+        #   numeric field, or is neither numeric nor a value object
         def clamp(current, bounds, target)
           min, max = bounds
           # The same `current ||= 0` #arithmetic/#multiply both give a
@@ -294,11 +306,11 @@ module Hecks
           # attribute with no declared `default:` (genuinely absent,
           # `Instance.defaults`/`#default_for`) hit TypeMismatch on the
           # first clamp. (#arithmetic/#multiply's own absent-current gap
-          # was a real, separate bug this comment used to describe wrong —
-          # they did not "silently treat the same absent field as zero";
-          # they raised too, blaming a perfectly valid `amount` for not
-          # being an Integer when it was one, just still Money-wrapped.
-          # Fixed alongside this one — see #unwrap_single_numeric_field.)
+          # is a real, separate bug: they do not silently treat an absent
+          # field as zero; they raise too, blaming a perfectly valid
+          # `amount` for not being an Integer when it is one, just still
+          # Money-wrapped. Fixed alongside this one — see
+          # #unwrap_single_numeric_field.)
           current ||= 0
           if current.is_a?(Value)
             fields = current.to_h

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

@@ -23,6 +23,15 @@ module Hecks
         # Shared by CommandInterpreter and EntityInterpreter — an entity command
         # can declare a reference-typed attribute the same way an aggregate
         # command can, even though nothing in the real corpus does yet.
+        #
+        # @param domain [String, Symbol] the domain the referenced aggregate is
+        #   resolved in
+        # @param command [Class] the command or port-operation class (`Bluebook::Command`
+        #   or `PortOperation` subclass) whose reference-typed attributes are checked
+        # @param args [Hash{Symbol => Object}] the offered, already-coerced argument values
+        # @return [void]
+        # @raise [Runtime::NotFound] if a reference-typed argument names an identity that
+        #   does not exist in its target aggregate's repository
         def resolve_references(domain, command, args)
           command.attributes.each do |attribute|
             next unless attribute.reference?
@@ -41,6 +50,20 @@ module Hecks
         # Structural references are checked again against the settled state.
         # This is what makes a `has_many` declared on an aggregate honest even
         # when a command supplies its list through an ordinary typed argument.
+        #
+        # @param domain [String, Symbol] the domain the referenced aggregate is
+        #   resolved in
+        # @param construct [Bluebook::Aggregate, Bluebook::Entity] the construct
+        #   whose reference-typed attributes are checked against `state`
+        # @param state [Hash{Symbol => Object}] the settled, post-mutation state to
+        #   check every reference and relationship cardinality against
+        # @return [void]
+        # @raise [Runtime::TypeMismatch] if a required `has_one`/`belongs_to`
+        #   relationship holds nil
+        # @raise [Runtime::NotFound] if a reference-typed field names an identity
+        #   that does not exist in its target aggregate's repository
+        # @raise [Runtime::Unauthorized] if a referenced record belongs to a
+        #   different tenant than `construct`'s own record
         def resolve_state_references(domain, construct, state)
           own_tenant_field = tenant_field_for(construct)
 
@@ -73,6 +96,14 @@ module Hecks
         # checking only command arguments would let a required relationship be
         # persisted as nil. `has_many` admits zero members, so its empty list is
         # already a valid cardinality and needs no presence refusal.
+        #
+        # @param construct [Bluebook::Aggregate, Bluebook::Entity] the construct
+        #   `attribute` is declared on, named in a refusal
+        # @param attribute [Bluebook::Attribute] the reference-typed attribute to check
+        # @param held [Object, nil] the field's settled value
+        # @return [void]
+        # @raise [Runtime::TypeMismatch] if `attribute` declares a required (non-optional,
+        #   non-list) `has_one`/`belongs_to` relationship and `held` is nil
         def validate_relationship_cardinality(construct, attribute, held)
           return if attribute.relationship.nil? || attribute.list?
           return unless held.nil? && !attribute.optional?
@@ -84,15 +115,31 @@ module Hecks
         end
 
         # The reference resolves itself — through the chapter's own IR, so the
-        # bluebook's declared heads are the index. This used to regex the target's
-        # name out of "Reference<Customer>" and then search
-        # `registry.bluebook(domain).aggregates` for it — and later reached the
-        # target through Ruby's constant tree, a class thrown away for its `.ir`
-        # the moment it was found.
+        # bluebook's declared heads are the index, rather than regexing the
+        # target's name out of "Reference<Customer>" and searching
+        # `registry.bluebook(domain).aggregates` for it, or reaching the
+        # target through Ruby's constant tree, a class thrown away for its
+        # `.ir` the moment it was found.
+        #
+        # @param attribute [Bluebook::Attribute] the reference-typed attribute to resolve
+        # @return [Bluebook::Aggregate, nil] the target aggregate the reference names,
+        #   or nil if it cannot be resolved
+        # @raise [Bluebook::DSL::Malformed] if the reference does not know which
+        #   aggregate declares it
         def referenced_aggregate(attribute)
           attribute.type.resolve
         end
 
+        # Refuses a reference-typed value whose target identity does not exist.
+        #
+        # @param domain [String, Symbol] the domain `target` is resolved in
+        # @param target [Bluebook::Aggregate] the referenced aggregate
+        # @param held [Object, Array<Object>] the offered value: a single reference,
+        #   or, when `list:` is true, an Array of them
+        # @param list [Boolean] whether `held` is list-shaped
+        # @return [void]
+        # @raise [Runtime::NotFound] if any referenced identity does not exist in
+        #   `target`'s repository
         def validate_reference_values(domain, target, held, list:)
           values = list ? Array(held) : [held]
           values.each do |value|
@@ -132,6 +179,22 @@ module Hecks
         # — one change, both interpreters covered, no new vocabulary step
         # to keep in sync with `Vocabulary::AggregateDispatchOrder`/
         # `EntityDispatchOrder`.
+        #
+        # @param domain [String, Symbol] the domain `target` is resolved in
+        # @param construct [Bluebook::Aggregate, Bluebook::Entity] the construct
+        #   `attribute` is declared on, named in a refusal
+        # @param attribute [Bluebook::Attribute] the reference-typed attribute being
+        #   checked
+        # @param target [Bluebook::Aggregate] the referenced aggregate
+        # @param held [Object, Array<Object>] the offered value: a single reference,
+        #   or, when `attribute.list?` is true, an Array of them
+        # @param state [Hash{Symbol => Object}] `construct`'s own settled state, read
+        #   for its own tenant field's value
+        # @param own_tenant_field [Symbol, nil] `construct`'s own declared tenant field;
+        #   a no-op if nil or absent from `state`
+        # @return [void]
+        # @raise [Runtime::Unauthorized] if a referenced record's own tenant field
+        #   disagrees with `construct`'s
         def enforce_tenant_boundary(domain, construct, attribute, target, held, state, own_tenant_field)
           return unless own_tenant_field && state.key?(own_tenant_field)
 
@@ -172,11 +235,19 @@ module Hecks
         # (`Entity.queries` is always empty in the real corpus), so this
         # answers `nil` for every entity without needing to special-case
         # one.
+        #
+        # @param construct [Bluebook::Aggregate, Bluebook::Entity] the construct
+        #   whose declared queries are searched
+        # @return [Symbol, nil] the tenant-scoping field name, or nil if `construct`
+        #   declares no query with `authorize policy, tenant: :field`
         def tenant_field_for(construct)
           authorization = construct.queries.filter_map(&:authorization).find(&:tenant)
           authorization&.tenant&.to_sym
         end
 
+        # Renders a reference-typed value as the plain string key its target
+        # record is looked up by.
+        #
         # `value` is the referenced record's own id, exactly as `Identity.of`
         # would build it for that record — a bare scalar for a single-field
         # identity (the overwhelming common case; Banking's own plain
@@ -184,18 +255,23 @@ module Hecks
         # materialize_unwrapped` is a no-op passthrough here), or a
         # `Naming.identity`-joined string for a compound one
         # (`belongs_to Translation, as: :translation_ref` — Translation's
-        # own `identified_by :domain, :from, :to`, three fields). Before
-        # this, plain `value.to_s` on that compound case's own coerced
-        # Value hit Ruby's default `Object#to_s` (a raw, run-to-run-random
-        # memory address) instead of joining the record's real id — found
-        # live via bin/fuzz on the self-hosted "translation" domain
-        # (replay_is_deterministic), the same class of gap `Identity.from`
+        # own `identified_by :domain, :from, :to`, three fields). Without
+        # `materialize_unwrapped`, plain `value.to_s` on that compound case's
+        # own coerced Value would hit Ruby's default `Object#to_s` (a raw,
+        # run-to-run-random memory address) instead of joining the record's
+        # real id — found live via bin/fuzz on the self-hosted "translation"
+        # domain (replay_is_deterministic), the same class of gap `Identity.from`
         # already had for a compound `identified_by`'s own bare (undotted)
         # attribute paths. `materialize_unwrapped` recurses a multi-
         # attribute value object to a plain Hash keyed by attribute name,
         # in declaration order — `Naming.identity` on `.values` reproduces
         # the identical join `Identity.of` itself would produce for the
         # same fields.
+        #
+        # @param value [Object] the offered reference value: a `Runtime::Value`, a
+        #   scalar, or anything `Value.materialize_unwrapped` can open
+        # @return [String] the key to look the referenced record up by; empty when
+        #   `value` names no id
         def reference_key(value)
           unwrapped = Value.materialize_unwrapped(value)
           return Naming.identity(unwrapped.values).to_s if unwrapped.is_a?(Hash)
@@ -203,8 +279,8 @@ module Hecks
           unwrapped.to_s
         end
 
-        # A command argument's own related record, reachable by name from
-        # `given`/`ensures` — `disputed_by.status`, say, `CardPayment
+        # Hydrates a command argument's own related record, reachable by name
+        # from `given`/`ensures` — `disputed_by.status`, say, `CardPayment
         # .Dispute`'s own fresh `Reference<Customer>` argument — without
         # teaching the pure expression evaluator anything about
         # repositories. The lookup happens here, once, before evaluation;
@@ -213,23 +289,21 @@ module Hecks
         #
         # `owner` narrowed to `command` only (S12, ADR 0025 — "rules
         # confined to their own aggregate boundary"): dereferencing the
-        # declaring aggregate/entity's own stored `reference_to` used to
-        # be the other half of this method's job — a live query against
-        # another aggregate's own repository, every time a `given`/
-        # `ensures`/`invariant` ran. That half is gone; a cross-aggregate
-        # fact a rule needs now has to be a `projects`-maintained local
-        # field (`AggregateBuilder#projects_impl`'s own comment), already
-        # present in `subject`'s own state, no hydration needed. A
-        # reference-typed command argument stays in bounds, though — the
-        # ADR's own boundary list names "its command arguments" as
-        # readable, and nothing is stored yet for a fresh argument to
-        # project from; resolving it once here, synchronous with this
-        # command's own admission, is a different shape from a live query
-        # against an already-persisted reference. `enforce_givens`/
+        # declaring aggregate/entity's own stored `reference_to` is not part
+        # of this method's job — a cross-aggregate fact a rule needs has to
+        # be a `projects`-maintained local field (`AggregateBuilder#
+        # projects_impl`'s own comment), already present in `subject`'s own
+        # state, no hydration needed, rather than a live query against
+        # another aggregate's own repository on every `given`/`ensures`/
+        # `invariant` run. A reference-typed command argument stays in
+        # bounds, though — the ADR's own boundary list names "its command
+        # arguments" as readable, and nothing is stored yet for a fresh
+        # argument to project from; resolving it once here, synchronous
+        # with this command's own admission, is a different shape from a
+        # live query against an already-persisted reference. `enforce_givens`/
         # `enforce_ensures` are this method's only two remaining callers,
         # both passing `command`/`args`, never a `subject`'s own
-        # aggregate — verified before this comment was written, not
-        # assumed.
+        # aggregate — verified by grep, not assumed.
         #
         # Recurses into what it finds, so a chain deeper than one hop
         # still resolves in one pass. Depth-bounded rather than cycle-
@@ -239,6 +313,22 @@ module Hecks
         DEREFERENCE_DEPTH = 4
         private_constant :DEREFERENCE_DEPTH
 
+        # Hydrates `owner`'s own reference-typed attributes into the records they name.
+        #
+        # @param domain [String, Symbol] the domain a referenced aggregate is
+        #   resolved in
+        # @param owner [Class, Bluebook::Aggregate, Bluebook::Entity, nil] the
+        #   construct whose reference-typed attributes are dereferenced; nil (or a
+        #   depth of zero) short-circuits to an empty Hash
+        # @param source [Hash{Symbol => Object}] the offered payload to read each
+        #   reference-typed attribute's raw id from
+        # @param depth [Integer] how many more hops to recurse into a resolved
+        #   reference's own reference-typed fields
+        # @return [Hash{Symbol => Object}] one entry per resolved reference-typed
+        #   attribute, keyed by the attribute name with a trailing `_id` stripped,
+        #   valued at the referenced record's state merged with its own dereferenced
+        #   references; an attribute with no id, an unresolvable target, or no
+        #   matching record contributes nothing
         def dereference(domain, owner, source, depth: DEREFERENCE_DEPTH)
           return {} if depth <= 0 || owner.nil?
 

data/lib/hecks/runtime/dependency_planning.rb

@@ -17,12 +17,28 @@ module Hecks
         :unresolved_dependencies,
         keyword_init: true
       ) do
+        # Reports whether every owner field this command could touch is a known,
+        # deterministic write.
+        #
+        # @return [Boolean] `complete_state`
         def complete_state? = complete_state
+
+        # Reports whether the command needs no prior state at all (implies `complete_state?`).
+        #
+        # @return [Boolean] `state_independent`
         def state_independent? = state_independent
 
+        # Chooses the dispatch strategy this plan's proof and the adapter's own
+        # capabilities together allow.
+        #
         # Capability negotiation is correctness-first: an optimization is
         # selected only when both the semantic proof and adapter capability
         # are present. This is planning data only; no runtime path calls it yet.
+        #
+        # @param capabilities [Array<String, Symbol>] the repository's declared capabilities
+        # @return [Symbol] `DependencyPlanning::ATOMIC_PUT` when the plan is complete,
+        #   state-independent, and the adapter declares that capability;
+        #   `DependencyPlanning::TRANSACTIONAL_FALLBACK` otherwise
         def strategy_for(capabilities: [])
           return TRANSACTIONAL_FALLBACK unless complete_state? && state_independent?
           return TRANSACTIONAL_FALLBACK unless capabilities.map(&:to_sym).include?(ATOMIC_PUT)
@@ -38,13 +54,27 @@ module Hecks
       module ExpressionReads
         module_function
 
+        # Finds every dotted path a canonical expression reads, without evaluating it.
+        #
         # Read the same parsed canonical-expression nodes the evaluator uses.
         # A generic Struct walk keeps this additive when the expression grammar
         # gains a composed node; only Lookup nodes carry domain dependencies.
+        #
+        # @param canonical [String] the canonical expression text, such as a rule's `canonical`
+        # @return [Array<String>] the dotted paths the expression reads
         def paths(canonical)
           collect(Bluebook::Expression::Evaluator.parse(canonical), Set.new)
         end
 
+        # Walks one parsed expression node, collecting the dotted paths it reads.
+        #
+        # @param node [Object] a node from `Bluebook::Expression::Evaluator.parse` — a
+        #   `Bluebook::Expression::Resolver::Lookup`, a `Bluebook::Expression::Resolver::
+        #   BlockPredicate`, a `Struct` composed of further nodes, an `Array` of them, or any
+        #   other value (a literal), which contributes no paths
+        # @param bound_names [Set<String>] names locally bound by an enclosing block
+        #   predicate's own parameter, excluded from the result rather than reported as reads
+        # @return [Array<String>] the dotted paths read under `node`, excluding `bound_names`
         def collect(node, bound_names)
           case node
           when Bluebook::Expression::Resolver::Lookup
@@ -87,8 +117,20 @@ module Hecks
         # unresolved regardless of correctness. Defaults to `aggregate`
         # (a no-op) for the plain-aggregate case — `CommandInterpreter`'s
         # own call site never needed to change.
+        #
+        # @param aggregate [Bluebook::Aggregate, Bluebook::Entity] the construct the command
+        #   is dispatched against; an entity for an entity-owned command
+        # @param command [Bluebook::Command] the command to analyze
+        # @param root_aggregate [Bluebook::Aggregate] the owning aggregate a `parent.*` read
+        #   resolves against; defaults to `aggregate` for a plain-aggregate command
+        # @return [Hecks::Runtime::DependencyPlanning::Plan] the derived, frozen plan
         def self.call(aggregate:, command:, root_aggregate: aggregate) = new(aggregate, command, root_aggregate).call
 
+        # @param aggregate [Bluebook::Aggregate, Bluebook::Entity] the construct the command
+        #   is dispatched against
+        # @param command [Bluebook::Command] the command to analyze
+        # @param root_aggregate [Bluebook::Aggregate] the owning aggregate `parent.*` reads
+        #   resolve against; defaults to `aggregate`
         def initialize(aggregate, command, root_aggregate = aggregate)
           @aggregate = aggregate
           @command = command
@@ -126,6 +168,9 @@ module Hecks
           @unresolved = Set.new
         end
 
+        # Runs the analysis and derives the command's dependency plan.
+        #
+        # @return [Hecks::Runtime::DependencyPlanning::Plan] the derived, frozen plan
         def call
           analyze_initial_state
           analyze_mutations