hecks 1.4.0 → 1.5.1

data/lib/hecks/runtime/entity_element.rb

@@ -33,6 +33,9 @@ module Hecks
       UNMATCHABLE = Object.new.freeze
       private_constant :UNMATCHABLE
 
+      # Walks `chain`, one hop per entry, and returns the located element (or
+      # `instance` itself, when `chain` is empty).
+      #
       # **One hop per chain entry**. `container` starts as `instance` (the root
       # aggregate record) and becomes each just-located element in turn —
       # Dispatch's own element is found inside the Handler element
@@ -52,6 +55,22 @@ module Hecks
       # split's own consequence: an entity's own identity may arrive via
       # `to:` rather than duplicated into `args`, so each hop is offered
       # its routed identity ahead of falling back to `args`.
+      #
+      # @param root_aggregate [Bluebook::Aggregate] the root aggregate record's
+      #   own construct, held constant across every hop for coercion
+      # @param chain [Array<Bluebook::Entity>] the entity chain to walk, root-first
+      # @param instance [Runtime::Instance] the root aggregate record to walk from
+      # @param args [Hash{String, Symbol => Object}] the offered command arguments,
+      #   read for each hop's own identity when `route` does not supply it
+      # @param command_name [String] the command name, quoted in a refusal
+      # @param route [Runtime::Routing::Envelope, nil] the call's resolved routing
+      #   envelope, if any; its own `entities` supply each hop's identity first
+      # @return [Runtime::Instance, Hash{Symbol => Object}] the located element;
+      #   `instance` itself, unchanged, when `chain` is empty
+      # @raise [Runtime::UnknownVerb] if a hop's owner declares no list attribute
+      #   for that entity
+      # @raise [Runtime::NotFound] if a hop's identity is absent from `args`, or no
+      #   element matches it
       def locate_chain(root_aggregate, chain, instance, args, command_name, route = nil)
         container = instance
         owner     = root_aggregate
@@ -81,6 +100,24 @@ module Hecks
       # rubocop:disable-next Metrics/CyclomaticComplexity
       # rubocop:disable-next Metrics/PerceivedComplexity
       # rubocop:disable-next Metrics/MethodLength
+      #
+      # @param root_aggregate [Bluebook::Aggregate] the root aggregate record's own
+      #   construct, used for value-object coercion
+      # @param owner [Bluebook::Aggregate, Bluebook::Entity] the construct whose own
+      #   attribute declares the list `entity` is searched in
+      # @param entity [Bluebook::Entity] the entity type being located
+      # @param command_name [String] the command name, quoted in a refusal
+      # @param container [Runtime::Instance, Hash{Symbol => Object}] the record or
+      #   element holding the list to search
+      # @param args [Hash{String, Symbol => Object}] the offered command arguments,
+      #   read for the element's own identity when `routed_identity` is nil
+      # @param routed_identity [String, nil] the routing envelope's own identity
+      #   string for this hop, matched directly instead of deriving one from `args`
+      # @return [Hash{Symbol => Object}] a fresh copy of the located element; the
+      #   owning list inside `container` is replaced with a fresh copy too
+      # @raise [Runtime::UnknownVerb] if `owner` declares no list attribute for `entity`
+      # @raise [Runtime::NotFound] if an identity part is absent from `args`
+      #   (`routed_identity` nil only), or no element matches
       def element_of(root_aggregate, owner, entity, command_name, container, args, routed_identity = nil)
         entity_name = entity.hecks_name
         list_attr = owner.attributes.find { |a| a.list? && a.type.to_s == entity_name } ||
@@ -173,6 +210,12 @@ module Hecks
       # that does not name its fields is refused when the bluebook loads ("an
       # entity says what it is known by", "an identity part names something"),
       # so by the time a dispatch arrives here there is always a path to dig.
+      #
+      # @param entity [Bluebook::Entity] the entity type whose identity paths
+      #   are read
+      # @param element [Hash{Symbol => Object}] the stored element to read an
+      #   identity off
+      # @return [String] the element's identity, joined from its declared parts
       def element_identity(entity, element)
         parts = entity.identity_paths.map do |path|
           head = path.to_s.split(".").first.to_sym
@@ -215,8 +258,32 @@ module Hecks
       # intentional mirroring, which is what lets the two be diffed
       # against each other when one gets a fix the other needs too.
       # rubocop:disable-next Metrics/AbcSize, Metrics/CyclomaticComplexity
+      # Applies one declared mutation to an entity element, in place.
+      #
       # `pre` — the element as it was before this command (C4.2): every
       # read below goes through it, every write lands on `element`.
+      #
+      # @param rules [Runtime::CommandRules] the shared rules engine `resolve_source`/
+      #   `arithmetic`/`multiply`/`clamp`/`sign_of` are read through
+      # @param aggregate [Bluebook::Aggregate] the root aggregate, for value-object
+      #   coercion
+      # @param entity [Bluebook::Entity] the entity type `element` is an instance of
+      # @param element [Hash{Symbol => Object}] the element to mutate; written in place
+      # @param mutation [Bluebook::Mutation] the declared mutation to apply
+      # @param args [Hash{String, Symbol => Object}] the offered command arguments,
+      #   a mutation's source may read from
+      # @param pre [Hash{Symbol => Object}] the element as it stood before this
+      #   command; every read goes through this, every write lands on `element`
+      # @return [void]
+      # @raise [Runtime::TypeMismatch] if a mutation's own value cannot be coerced,
+      #   or an arithmetic op's operands are not numeric or compatible value objects
+      # @raise [Runtime::InvariantViolation] if a coerced or arithmetic-derived value
+      #   object breaks one of its own invariants
+      # @raise [Runtime::AlreadyExists] if an `:append` mints a nested entity whose
+      #   identity collides with an existing element
+      # @raise [Bluebook::Expression::EvaluationError] if an arithmetic op's product
+      #   does not fit a signed 64-bit Integer, or is a non-finite Float
+      # @raise [Runtime::WiringError] if `mutation.op` names no handled mutation kind
       def apply_to_element(rules, aggregate, entity, element, mutation, args, pre = element)
         case mutation.op
         when :set
@@ -269,22 +336,47 @@ module Hecks
         end
       end
 
+      # Rewraps a plain-Numeric arithmetic result into `attribute`'s own declared
+      # value-object type, when the arithmetic itself ran unwrapped.
+      #
       # `MutationApplier#rewrap_arithmetic_result`'s own entity-scoped
       # twin, byte-for-byte the same fix — see that method's own
       # comment for the full "phantom-field asymmetric wrapping" story.
       # A no-op whenever `current` was already a Value (the arithmetic
       # call already returned one) or the mutation targets no declared
       # attribute at all.
+      #
+      # @param aggregate [Bluebook::Aggregate] the root aggregate, for value-object
+      #   coercion
+      # @param attribute [Bluebook::Attribute, nil] the mutated field's own declared
+      #   attribute; a no-op when nil (targets no declared attribute)
+      # @param current [Object] the field's pre-mutation value, as read off `pre`
+      # @param result [Object] the arithmetic op's own result
+      # @return [Runtime::Value, Object] `result` unchanged when already a `Value`,
+      #   `current` is a `Value`, or `attribute` is nil; otherwise `result` coerced
+      #   into `attribute`'s own declared type
       def rewrap_arithmetic_result(aggregate, attribute, current, result)
         return result if current.is_a?(Value) || attribute.nil? || result.is_a?(Value)
 
         Value.for_attribute(aggregate, attribute, result)
       end
 
+      # Resolves an `:append` mutation's own field source against the offered
+      # arguments, falling back to the element's own current field.
+      #
       # `MutationApplier#resolve_append_source`'s own entity-scoped
       # twin — a caller-supplied arg first, falling back to the
       # element's own current field (never the parent instance's) when
       # it isn't one.
+      #
+      # @param source [Symbol, Object] the mutation's own field source: a Symbol
+      #   names a command argument or, failing that, an element field; anything
+      #   else is returned as is
+      # @param element [Hash{Symbol => Object}] the element to fall back to reading
+      #   from
+      # @param args [Hash{String, Symbol => Object}] the offered command arguments
+      # @return [Object, nil] the named argument's value; failing that, the named
+      #   element field's value; `source` itself when it is not a Symbol
       def resolve_element_append_source(source, element, args)
         return source unless source.is_a?(Symbol)
         return args[source] if args.key?(source)
@@ -314,6 +406,20 @@ module Hecks
       # every declared attribute the append mapping doesn't name gets its
       # own default the same way a fresh aggregate's own attributes
       # already do (`Instance.defaults`), whichever branch built `fields`.
+      #
+      # @param aggregate [Bluebook::Aggregate] the root aggregate, for value-object
+      #   coercion
+      # @param entity [Bluebook::Entity] the entity type `element`'s mutated list
+      #   attribute belongs to
+      # @param element [Hash{Symbol => Object}] the element being appended to, read
+      #   as the source for a field the mutation's own map does not supply directly
+      # @param mutation [Bluebook::Mutation] the declared `:append` mutation
+      # @param args [Hash{String, Symbol => Object}] the offered command arguments
+      # @return [Array] `element[mutation.target]`'s existing elements, frozen deep,
+      #   with the newly built element (a `Runtime::Value`, or a Hash for an entity
+      #   or untyped element) appended last
+      # @raise [Runtime::AlreadyExists] if the appended element is a nested entity
+      #   whose identity collides with an existing one
       def appended_to_element(aggregate, entity, element, mutation, args)
         fields       = mutation.source.transform_values { |source| resolve_element_append_source(source, element, args) }
         element_type = entity.attribute(mutation.target)&.type
@@ -389,6 +495,15 @@ module Hecks
       # what "the default" means. Additive only — a key `fields` already
       # holds (the append mapping, an auto-minted identity, a lifecycle
       # default) is never overwritten.
+      #
+      # @param aggregate [Bluebook::Aggregate] the root aggregate, for value-object
+      #   coercion
+      # @param entity [Bluebook::Entity] the entity type whose declared attributes
+      #   are defaulted
+      # @param fields [Hash{Symbol => Object}] the element fields already resolved;
+      #   written in place
+      # @return [Hash{Symbol => Object}] `fields`, with every declared attribute it
+      #   did not already hold filled with its own default
       def fill_declared_defaults(aggregate, entity, fields)
         entity.attributes.each do |attribute|
           next if fields.key?(attribute.name)
@@ -404,6 +519,18 @@ module Hecks
       # the list this targets is itself entity-typed — see
       # `list_element_match?`, below, which both this and
       # `MutationApplier#removed` now share.
+      #
+      # @param rules [Runtime::CommandRules] the shared rules engine `resolve_source`
+      #   is read through
+      # @param aggregate [Bluebook::Aggregate] the root aggregate, for value-object
+      #   coercion
+      # @param entity [Bluebook::Entity] the entity type `element`'s mutated list
+      #   attribute belongs to
+      # @param element [Hash{Symbol => Object}] the element being removed from
+      # @param mutation [Bluebook::Mutation] the declared `:remove` mutation
+      # @param args [Hash{String, Symbol => Object}] the offered command arguments
+      # @return [Array] `element[mutation.target]`'s existing elements, with any
+      #   matching the resolved remove target left out
       def removed_from_element(rules, aggregate, entity, element, mutation, args)
         value     = rules.resolve_source(mutation.source, args)
         attribute = entity.attribute(mutation.target)
@@ -443,6 +570,17 @@ module Hecks
       # "matches" means — the same reasoning this file's own header
       # gives for centralizing `locate_chain`/`element_of` once rather
       # than twice.
+      #
+      # @param aggregate [Bluebook::Aggregate] the root aggregate, to resolve
+      #   whether `attribute`'s own type is an entity
+      # @param attribute [Bluebook::Attribute, nil] the list attribute `element`
+      #   belongs to
+      # @param element [Object] the stored list element to check: a Hash for an
+      #   entity-typed list, a `Runtime::Value` otherwise
+      # @param value [Object] the `remove:` target to match `element` against
+      # @return [Boolean] whole-value equality for a non-entity-typed list;
+      #   identity-field equality for an entity-typed one with a single identity
+      #   head; false for a composite or absent identity
       def list_element_match?(aggregate, attribute, element, value)
         entity = attribute&.list? ? Value.find_entity(aggregate, attribute.type.to_s) : nil
         return element == value unless entity
@@ -453,24 +591,27 @@ module Hecks
         element.is_a?(Hash) && element[head] == value
       end
 
-      # BUG#13 (PR #549) — the same check #hydrate gives every creating
+      # Refuses a caller-supplied or composite identity that already names an
+      # element on `current`.
+      #
+      # BUG#13 — the same check #hydrate gives every creating
       # aggregate command (`repository.find(id)`,
-      # `command_interpreter.rb`), one level down. Originally lived in
-      # `MutationApplier` (mutation_applier.rb), called only from
+      # `command_interpreter.rb`), one level down. Shared with
+      # `MutationApplier` (mutation_applier.rb), called from
       # `#entity_element` — an aggregate's own entity list (`Workspace.
-      # boards`, `Ledger.entries`). Moved here (BUG#145) so `#appended_
+      # boards`, `Ledger.entries`) — and, moved here (BUG#145), from `#appended_
       # to_element`, above — an entity's own nested entity list one hop
-      # further in (`Board.cards`) — can share it too, rather than
-      # reimplementing it a second time the same way `#list_element_
+      # further in (`Board.cards`) — so neither call site reimplements
+      # it a second time, the same way `#list_element_
       # match?` already avoids that split for `remove:`.
       #
       # Reached, at the aggregate-owned call site, only on the two
       # branches that do not auto-mint: a caller-supplied identity (the
       # field is already in the append's own field map) or a composite
       # one (`entity.identified_by` is nil for those — Runtime::
-      # Identified#derive_identity). Neither used to check the sibling
+      # Identified#derive_identity). Without this, neither checks the sibling
       # list at all: a second LogVisit with the same date+sequence, or a
-      # second IssueKey with the same serial, appended a silent
+      # second IssueKey with the same serial, would append a silent
       # duplicate — worse than an ordinary duplicate row, because
       # `EntityElement#element_of`'s own `find_index` always matches the
       # first match, so the second becomes permanently unaddressable by
@@ -491,6 +632,18 @@ module Hecks
       # hops up). Used for that naming purpose only (`owner.hecks_name`) —
       # never for `Value`/namespace resolution, which is why an `Entity`
       # (not just an `Aggregate`) is a valid thing to pass here.
+      #
+      # @param owner [Bluebook::Aggregate, Bluebook::Entity] the construct named
+      #   in a refusal as what the duplicate "already exists on"
+      # @param entity [Bluebook::Entity] the entity type being checked for a
+      #   colliding identity
+      # @param current [Array<Hash>, Object] the entity's own existing elements;
+      #   coerced through `Array()`, so a single element or nil is also accepted
+      # @param fields [Hash{Symbol => Object}] the new element's own fields, whose
+      #   identity heads are checked against every element in `current`
+      # @return [void]
+      # @raise [Runtime::AlreadyExists] if `current` already holds an element
+      #   whose identity heads match `fields`'s own
       def check_entity_collision(owner, entity, current, fields)
         heads = entity.identity_heads
         return if heads.empty?

data/lib/hecks/runtime/entity_interpreter.rb

@@ -24,8 +24,8 @@ module Hecks
     class EntityInterpreter
       include Interpreting
       # The same payload gate aggregate commands and port operations already
-      # run — bug audit H1 (docs/audits/2026-08-10-main-bug-audit.md): this
-      # class used to run neither refuse_unknown_arguments nor
+      # run — bug audit H1 (docs/audits/2026-08-10-main-bug-audit.md): without
+      # this, this class runs neither refuse_unknown_arguments nor
       # refuse_absent_arguments, on a comment claiming "an entity inherits
       # its aggregate's own gate." Nothing on the entity dispatch path ever
       # ran one — confirmed live, `LedgerEntry.Reverse` accepted an
@@ -83,7 +83,19 @@ module Hecks
       # reads the declaring command — after `to:` is parsed, before the
       # facts are.
       Resolution = Data.define(:entity_names, :chain, :command_name, :command) do
+        # Resolves a dotted entity verb against `aggregate` into the entity
+        # chain it walks and the command it names.
+        #
         # Refuses UnknownVerb for an unknown entity or command.
+        #
+        # @param aggregate [Bluebook::Aggregate] the root aggregate the dotted verb
+        #   is resolved against
+        # @param dotted [String, Symbol] the entity verb, with the leading
+        #   "Domain::Aggregate." already stripped (e.g. `"Handler.Dispatch.Bind"`)
+        # @return [EntityInterpreter::Resolution] the resolved entity names, chain,
+        #   command name and command class
+        # @raise [Runtime::UnknownVerb] if `dotted` names no entity, or the located
+        #   entity declares no such command
         def self.of(aggregate, dotted)
           *entity_names, command_name = dotted.to_s.split(".")
           if entity_names.empty?
@@ -119,6 +131,9 @@ module Hecks
         private_class_method :walk
       end
 
+      # @param registry [Runtime::Registry] the booted registry this interpreter reads
+      # @param rules [Runtime::CommandRules] the shared rules engine (admissibility,
+      #   references, arithmetic, authorization, emission) dispatch runs through
       def initialize(registry, rules:)
         @registry = registry
         @rules    = rules
@@ -136,6 +151,26 @@ module Hecks
       # `resolution` is #resolve's answer; `invocation` the
       # `Runtime::Invocation` `Dispatcher` built — `ctx.args` is its
       # `to_args`, `ctx.route` its `target`.
+      #
+      # @param domain [String, Symbol] the domain `aggregate` belongs to
+      # @param aggregate [Bluebook::Aggregate] the root aggregate owning the entity
+      #   chain the command targets
+      # @param resolution [EntityInterpreter::Resolution] the resolved entity chain
+      #   and command, as `Resolution.of` builds it
+      # @param invocation [Runtime::Invocation] the invocation `Dispatcher` built for
+      #   this call
+      # @param dry_run [Boolean] whether to run every step through validation without
+      #   saving, emitting or enqueueing
+      # @return [Array(Runtime::Instance, Array<Runtime::Event>,
+      #   Runtime::DependencyPlanning::Plan, Ports::Persistence::Execution,
+      #   Array<Runtime::Outbox::Row>)] the settled parent aggregate instance, emitted
+      #   events, execution plan, persistence outcome and outbox rows — the last
+      #   three nil on a dry run, which skips save/emit/outbox
+      # @raise [StandardError] any class in `Runtime::DOMAIN_REFUSALS` when a
+      #   given/ensures/invariant/authorization/admissibility rule refuses
+      # @raise [Runtime::StaleWrite] if concurrent writers beat this one through every
+      #   retry (`MAX_STALE_WRITE_RETRIES`)
+      # @raise [Runtime::WiringError] if the aggregate's repository cannot be resolved
       def call(domain, aggregate, resolution, invocation, dry_run: false)
         chain        = resolution.chain
         entity       = chain.last
@@ -239,7 +274,7 @@ module Hecks
       # command's `corrects` names even exist" is checked here too, once,
       # before the entity's own `given`s.
       #
-      # **Admissibility is checked against the parent/root, not the entity** —
+      # Admissibility is checked against the parent/root, not the entity —
       # deliberately `ctx.instance`/`ctx.aggregate` (the parent aggregate
       # record and the root aggregate construct), never `ctx.view`/
       # `ctx.entity` (the entity's own pre-mutation view/construct). This
@@ -399,12 +434,12 @@ module Hecks
       end
 
       # `locate_chain`/`element_of`/`element_identity`/`apply_to_element` and
-      # their own helpers used to live here — moved to `Runtime::EntityElement`
-      # (see that file's own header) so `CommandInterpreter`'s own
-      # `delegate_to_entity` step can locate and mutate the same element the
-      # same way, against an aggregate record already held in memory. `call`,
-      # above, and every `step_*` method reach them through that module now;
-      # nothing about the steps themselves changed.
+      # their own helpers live in `Runtime::EntityElement`
+      # (see that file's own header), shared rather than kept here, so
+      # `CommandInterpreter`'s own `delegate_to_entity` step can locate and
+      # mutate the same element the same way, against an aggregate record
+      # already held in memory. `call`, above, and every `step_*` method
+      # reach them through that module.
     end
   end
 end

data/lib/hecks/runtime/errors.rb

@@ -2,6 +2,10 @@ require_relative "value/invariant_violation"
 require_relative "../vocabulary"
 
 module Hecks
+  # What runs a booted domain: dispatch, the command/entity/query/policy/saga
+  # interpreters, the registry a boot assembles, and the errors below —
+  # everything downstream of a `.bluebook`/`.hecksagon`/`.world` declaration.
+  # See `lib/hecks/runtime.rb` for the module's own facade and boot entry points.
   module Runtime
     class UnknownVerb < StandardError; end
     class EnsuresNotMet < StandardError; end
@@ -21,11 +25,21 @@ module Hecks
     class GivenNotMet < StandardError
       attr_reader :detail
 
+      # @param message [String, nil] the refusal text, pinned byte-for-byte across specs
+      # @param detail [String, nil] the failing comparison's resolved operands ("left: X,
+      #   right: Y"), or nil when the given's top-level shape is not a bare comparison
       def initialize(message = nil, detail: nil)
         super(message)
         @detail = detail
       end
 
+      # Renders `message` with `detail` appended, for a human reading an unhandled refusal.
+      #
+      # @param highlight [Boolean] unused; accepted for compatibility with `Exception#
+      #   detailed_message`'s own signature
+      # @param opts [Hash] unused; accepted for compatibility with `Exception#
+      #   detailed_message`'s own signature
+      # @return [String] `message`, with `" (#{detail})"` appended when `detail` is present
       def detailed_message(highlight: false, **opts)
         base = super
         detail ? "#{base} (#{detail})" : base
@@ -119,10 +133,10 @@ module Hecks
     #
     # Everything else is a defect : a NoMethodError in an interpreter, a
     # NameError from a missing constant, a TypeError from a bad assumption. A
-    # blanket `rescue StandardError` used to fold both into one line —
-    # `delivered: false, reason: "..."` — so a crash in the runtime was
-    # indistinguishable from a rule doing its job, and read as normal operation
-    # in the log.
+    # blanket `rescue StandardError` would fold both into one line —
+    # `delivered: false, reason: "..."` — making a crash in the runtime
+    # indistinguishable from a rule doing its job, reading as normal
+    # operation in the log.
     #
     # UnknownVerb is one of these, and deliberately : a cross-domain policy
     # (`across "Notifications"`) fires in deployments where that domain is not

data/lib/hecks/runtime/event.rb

@@ -11,20 +11,25 @@ module Hecks
     # one correlating on a different field. Absent for any event no saga
     # dispatch caused, which is most of them.
     Event = Struct.new(:name, :aggregate, :id, :payload, :occurred_at, :correlation, keyword_init: true) do
+      # Freezes the event deep, so nothing about it can change after it happens.
+      #
       # An emitted event is a record of something that happened, and a
       # mutable audit trail is not one. The payload — the domain fact the
       # event carries — is frozen through on emission: freezing the Hash
       # alone would leave every value in it editable in place, which is
       # the shape all four previous freezing bugs had.
       #
-      # The whole event, not just its payload. Correlation used to be
-      # merged onto already-emitted events by `Dispatcher#dispatch`, which
-      # is what kept an event writable after it had happened; it is set at
-      # construction now, because it is part of the transaction and known
-      # from `dispatch`'s own argument before anything is emitted.
+      # The whole event, not just its payload. Correlation is set at
+      # construction rather than merged in here by `Dispatcher#dispatch`
+      # after the event already exists, because it is part of the
+      # transaction and known from `dispatch`'s own argument before
+      # anything is emitted — that is what keeps an event immutable once
+      # it exists.
       #
       # The log stays appendable: new events are still recorded. It is
       # each event that stops changing once it exists.
+      #
+      # @return [void]
       def emit!
         Freezer.deep(payload)
         Freezer.deep(correlation)

data/lib/hecks/runtime/identity.rb

@@ -23,19 +23,38 @@ module Hecks
     module Identity
       module_function
 
+      # Reads one key off `hash` by whichever of its Symbol/String spelling
+      # is actually present, favoring the Symbol spelling.
+      #
       # A hash read that decides which spelling of a key answers by
       # presence, never by `||` — a bare `||` treats a genuinely-held
       # `false` the same as an absent key and falls through to the other
       # spelling, landing on `nil` instead of the real, stored answer.
+      #
+      # @param hash [Hash] the hash to read, potentially keyed by either spelling
+      # @param key [String, Symbol] the key to look up
+      # @return [Object, nil] the value under `key.to_sym` if that key is present,
+      #   otherwise the value under `key` as given; nil if neither is a key of `hash`
       def hash_lookup(hash, key)
         sym = key.to_sym
         hash.key?(sym) ? hash[sym] : hash[key]
       end
 
+      # Digs `path`'s fields out of `held`, past the head a caller already
+      # consumed to look `held` up.
+      #
       # The head names the attribute and is consumed by whoever looked the value
       # up; what is left is the walk down into it. A path with no fields to walk
       # — an aggregate that declares no identity and falls back to `id` — hands
       # back what it was given, because there is nothing declared to dig for.
+      #
+      # @param path [String, Symbol] the dotted identity path (`"number.value"`) or a
+      #   bare head (`:id`); only the segments after the head are walked
+      # @param held [Object] the value already looked up for the path's head — a
+      #   `Runtime::Value`, a Hash, or a plain scalar
+      # @return [Object, nil] `held` unchanged when `path` has no fields past its head;
+      #   otherwise the value found by walking those fields, or nil when a segment
+      #   is missing or the value being dug into is not a Hash
       def scalar(path, held)
         _head, *fields = path.to_s.split(".")
         return held if fields.empty?
@@ -45,6 +64,9 @@ module Hecks
         end
       end
 
+      # Derives `construct`'s identity string from `args`, joining every
+      # declared identity part in declaration order.
+      #
       # The identity is the join of its parts, in declaration order. Shared by
       # `CommandInterpreter` (an aggregate acting on itself) and
       # `EntityInterpreter` (a piece addressed through its aggregate) — a piece
@@ -59,23 +81,49 @@ module Hecks
       # rather than half of one. Half an identity names nothing, and joining what
       # did arrive would silently name a different record on every dispatch — the
       # precise failure that minting an id caused, arrived at by another road.
+      #
+      # @param construct [Bluebook::Aggregate, Bluebook::Entity] the construct whose
+      #   `identity_paths` are resolved
+      # @param args [Hash{Symbol => Object}] the offered payload to resolve each
+      #   identity path against
+      # @param value_owner [Bluebook::Aggregate, Bluebook::Entity] the construct whose
+      #   namespace a value-object identity part is coerced against; `construct` itself
+      #   unless the caller passes the owning aggregate for an entity
+      # @return [String, nil] the joined identity string, or nil when `construct`
+      #   declares no identity path or any resolved part is nil or blank
       def of(construct, args, value_owner: construct)
         paths = construct.identity_paths
         return nil if paths.empty?
 
         parts = paths.map { |path| from(construct, args, path, value_owner: value_owner) }
         # A blank part names nothing, the same as an absent one — an ID is a
-        # scalar, and "" is not a fact about anything. This used to check only
-        # `nil?`, so a canonical text extracted as "" (an expression whose
-        # source did not survive extraction) resolved to a real, empty-string
+        # scalar, and "" is not a fact about anything. Checking only `nil?`
+        # would let a canonical text extracted as "" (an expression whose
+        # source did not survive extraction) resolve to a real, empty-string
         # identity — a record addressable by an id no caller could have meant.
         return nil if parts.any? { |part| part.nil? || (part.respond_to?(:empty?) && part.empty?) }
 
         Naming.identity(parts)
       end
 
+      # Resolves one identity path (or a bare head such as `:id`) against `args`.
+      #
       # A path digs into the value object that carries the identity, so what is
       # stored is the scalar inside it rather than the object serialised whole.
+      #
+      # @param construct [Bluebook::Aggregate, Bluebook::Entity] the construct `key` is
+      #   checked against when it is a bare head
+      # @param args [Hash{Symbol => Object}] the offered payload to resolve `key` against
+      # @param key [String, Symbol, nil] the identity path to resolve, dotted
+      #   (`"number.value"`) or bare (`:id`); nil resolves to nil
+      # @param value_owner [Bluebook::Aggregate, Bluebook::Entity] the construct whose
+      #   namespace a value-object head is coerced against; `construct` itself unless
+      #   the caller passes the owning aggregate for an entity
+      # @return [String, Object, nil] the resolved identity text — a String once dug
+      #   through a dotted path or coerced through a declared value-object attribute;
+      #   the raw `args[key]` value, unconverted, when the bare head names no declared
+      #   identity attribute of `construct`; nil when `key` is nil, absent from `args`,
+      #   or a dotted walk finds nothing
       def from(construct, args, key, value_owner: construct)
         return nil unless key
 
@@ -127,12 +175,21 @@ module Hecks
         Value.materialize_unwrapped(Value.for_attribute(value_owner, attribute, raw)).to_s
       end
 
+      # Renders `construct`'s identity paths for a refusal message.
+      #
       # How an identity reads when the runtime has to name it in a refusal — the
       # paths as they were declared, so the message quotes the bluebook back.
+      #
+      # @param construct [Bluebook::Aggregate, Bluebook::Entity] the construct whose
+      #   declared identity paths are rendered
+      # @return [String] `construct`'s identity paths, comma-separated, exactly as declared
       def reading(construct)
         construct.identity_paths.join(", ")
       end
 
+      # Resolves the best identity string available for `construct` from `args`,
+      # without raising, for use as a lock key only.
+      #
       # Best-effort, for a lock key only — `Runtime::AggregateLock`'s own
       # per-record striping needs some id to key on before dispatch has run
       # far enough to hydrate for real, so this walks the identical chain
@@ -143,6 +200,17 @@ module Hecks
       # from the raw, pre-normalized payload this runs against" — the
       # caller locks by aggregate type alone in that case (coarser, still
       # correct, just less concurrent).
+      #
+      # @param construct [Bluebook::Aggregate, Bluebook::Entity] the construct being
+      #   located for the lock key
+      # @param args [Hash{Symbol => Object}] the raw, pre-normalized payload to resolve
+      #   an identity from
+      # @param route [Runtime::Routing::Envelope, nil] the call's resolved routing
+      #   envelope, if any; its own `aggregate` identity is tried first
+      # @param reference_key [Symbol, nil] the command's reference-key fallback,
+      #   tried last if given
+      # @return [String, Object, nil] the best-effort identity to lock by, or nil
+      #   when nothing resolves (the caller then locks by aggregate type alone)
       def best_effort(construct, args, route = nil, reference_key: nil)
         route&.aggregate ||
           of(construct, args) ||