hecks 1.4.0 → 1.5.0

data/lib/hecks/query_specification/common/null_policy.rb

@@ -22,7 +22,8 @@ module Hecks
         # `field DESC, id DESC`.
         #
         # @param records [Array<Object>] the rows to order, already in identity order
-        # @param direction [Symbol, String] `desc` sorts descending; anything else ascending
+        # @param direction [Symbol, String] `desc` in any letter case sorts descending;
+        #   anything else ascending
         # @param policy [NullSemantics, nil] where nulls go: mode `first` or `last`; `nil` or
         #   any other mode (`native`) puts nulls first ascending and last descending
         # @yield reads the sort key out of one record
@@ -32,16 +33,17 @@ module Hecks
         # @return [Array<Object>] a new Array holding every record in the requested order
         # @raise [ArgumentError] if two non-nil keys cannot be compared with each other
         def order(records, direction:, policy: nil, &key)
+          descending = direction.to_s.downcase == "desc"
           null_rows, valued_rows = records.partition { |record| key.call(record).nil? }
           sorted = valued_rows.each_with_index.sort_by { |record, index| [key.call(record), index] }.map(&:first)
-          if direction.to_s == "desc"
+          if descending
             sorted.reverse!
             null_rows.reverse!
           end
           case policy&.mode.to_s
           when "first" then null_rows + sorted
           when "last" then sorted + null_rows
-          else direction.to_s == "desc" ? sorted + null_rows : null_rows + sorted
+          else descending ? sorted + null_rows : null_rows + sorted
           end
         end
 

data/lib/hecks/rendering.rb

@@ -17,6 +17,12 @@ module Hecks
   module Rendering
     module_function
 
+    # Renders a value the way it should read inside a refusal message.
+    #
+    # @param value [Object] the value to render
+    # @return [String] `"nil"` for nil, JSON for a Hash/Array or a duck-typed value
+    #   object (unwrapped to its bare scalar when it has exactly one field), or
+    #   `value.inspect` for anything else
     def describe(value)
       case value
       when nil then "nil"

data/lib/hecks/router/namespace_installer.rb

@@ -12,6 +12,13 @@ module Hecks
       # to the router, pinned to this specific FQN version rather than
       # the router's default resolution.
       class OptionsProxy
+        # @param router [Router] router to dispatch resolved calls through
+        # @param realm [String, nil] realm segment of the FQN this proxy pins
+        # @param domain [String] domain segment of the FQN this proxy pins
+        # @param aggregate [String, nil] aggregate segment, or nil for a domain-level query
+        # @param options [Hash{Symbol => Object}] the `.options(...)` call's keywords; only
+        #   `:version` is accepted
+        # @raise [ArgumentError] if `options` has a key other than `:version`
         def initialize(router:, realm:, domain:, aggregate:, options:)
           unknown = options.keys - [:version]
           raise ArgumentError, "unknown router options: #{unknown.join(', ')}" unless unknown.empty?
@@ -45,10 +52,16 @@ module Hecks
         end
       end
 
+      # @param router [Router] router whose current routes get Ruby constants and methods
       def initialize(router)
         @router = router
       end
 
+      # Installs every current-version route as a namespace constant/method,
+      # plus the aggregate `find`/`all`/`count`/`events`/`repository` door and
+      # short `Aggregate.verb` shortcuts.
+      #
+      # @return [self]
       def install!
         current_entries.each { |entry| install_namespace_entry(entry) }
         install_shortcuts!

data/lib/hecks/router.rb

@@ -9,31 +9,60 @@ module Hecks
 
     attr_reader :register
 
+    # Loads a project's bluebooks and builds a router over them, without
+    # installing any Ruby namespace shortcuts.
+    #
+    # @param root [String] project root to discover bluebooks under
+    # @return [Router] the built router
     def self.load(root) = new(Bluebook::ProjectLoader.load(root))
 
     # Install one project router for ordinary application calls. The explicit
     # `Router.load` API remains useful for tests and embedded hosts.
+    #
+    # @param root [String] project root to discover bluebooks under
+    # @return [Router] the booted router, also stored as `.default`
     def self.boot(root)
       router = load(root)
       router.install_namespace!
       @default = router
     end
 
+    # The process-wide router `.boot` installed.
+    #
+    # @return [Router] the router `.boot` installed
+    # @raise [NotBooted] if `.boot` has not been called yet
     def self.default
       @default || raise(NotBooted, "no project router is booted — call Hecks::Router.boot(root) first")
     end
 
+    # (see #dispatch)
     def self.dispatch(address, **args) = default.dispatch(address, **args)
+    # (see #query)
     def self.query(address, **args)    = default.query(address, **args)
 
+    # @param register [Bluebook::ProjectRegister, Bluebook::ProjectLoader] the FQN
+    #   catalogue to resolve addresses against
     def initialize(register)
       @register = register
     end
 
+    # Lists every routed FQN entry.
+    #
+    # @return [Array<Bluebook::ProjectRegister::Entry>] every routed FQN entry
     def available = register.entries.values
 
+    # Installs Ruby namespace constants and shortcut methods for every
+    # current-version route.
+    #
+    # @return [NamespaceInstaller] the installer that performed the install
     def install_namespace! = NamespaceInstaller.new(self).install!
 
+    # Resolves an address to its routed FQN entry.
+    #
+    # @param address [String] a fully-qualified command or query address, realm included
+    # @return [Bluebook::ProjectRegister::Entry] the routed entry
+    # @raise [UnknownAddress] if `address` has no realm, or names no known route
+    # @raise [Fqn::Invalid] if `address` is not a well-formed FQN
     def resolve(address)
       fqn = Fqn.parse(address)
       raise UnknownAddress, "router addresses require a realm: #{address.inspect}" unless fqn.realm
@@ -43,6 +72,19 @@ module Hecks
       raise UnknownAddress, "no Bluebook route for #{address.inspect}"
     end
 
+    # Dispatches a command to its resolved aggregate.
+    #
+    # @param address [String] a fully-qualified command address, realm included
+    # @param args [Hash] command facts, plus the dispatcher's optional `:to`, `:with`,
+    #   and `:saga_correlation` keys
+    # @return [Runtime::Dispatcher::Result] the dispatch result
+    # @raise [UnknownAddress] if `address` has no realm, or names no known route
+    # @raise [WrongVerbKind] if `address` names a query
+    # @raise [Runtime::UnknownVerb] if the resolved verb names something undeclared
+    # @raise [StandardError] any class in `Runtime::DOMAIN_REFUSALS` when the domain refuses
+    #   the call
+    # @raise [Runtime::StaleWrite] if concurrent writers beat this one through every retry
+    # @raise [Runtime::WiringError] if the aggregate's repository cannot be resolved
     def dispatch(address, **args)
       entry = resolve(address)
       raise WrongVerbKind, "#{address.inspect} names a query; use #query" unless entry.command?
@@ -50,6 +92,19 @@ module Hecks
       entry.dispatcher.dispatch_flat(local_verb(entry), args)
     end
 
+    # Queries a resolved aggregate, entity, or read model.
+    #
+    # @param address [String] a fully-qualified query address, realm included
+    # @param args [Hash{Symbol => Object}] the query's declared arguments
+    # @return [Array<Hash>] one row Hash per match; see `Runtime::Dispatcher#query`
+    #   for the exact shape per address kind
+    # @raise [UnknownAddress] if `address` has no realm, or names no known route
+    # @raise [WrongVerbKind] if `address` names a command
+    # @raise [Runtime::UnknownVerb] if the resolved verb names something undeclared
+    # @raise [Runtime::NotFound] if a read model's root reference names no record
+    # @raise [Runtime::TypeMismatch] if an argument cannot be coerced to its declared type
+    # @raise [KeyError] if a rooted read model is asked without its reference argument
+    # @raise [Runtime::WiringError] if the aggregate's repository cannot be resolved
     def query(address, **args)
       entry = resolve(address)
       raise WrongVerbKind, "#{address.inspect} names a command; use #dispatch" unless entry.query?

data/lib/hecks/runtime/aggregate_lock.rb

@@ -29,12 +29,21 @@ module Hecks
       @locks = {}
 
       class << self
+        # Returns the Mutex striped to one record, creating it on first use.
+        #
         # `AggregateLock.for(domain, aggregate, id).synchronize { ... }`
         # `id: nil` — identity could not be resolved yet (see
         # `Identity.best_effort`) — locks by aggregate type alone, coarser
         # (every record of this aggregate serializes against every other)
         # but still correct: it can only ever make dispatch more
         # conservative than a resolved id would.
+        #
+        # @param domain [String] the domain the aggregate belongs to
+        # @param aggregate [Bluebook::Aggregate] the aggregate being dispatched
+        # @param id [String, nil] the resolved record id, or nil to stripe by aggregate type
+        #   alone
+        # @return [Mutex] the mutex for this `[domain, aggregate, id]` key, held for the full
+        #   hydrate-through-save critical section
         def for(domain, aggregate, id = nil)
           key = id.nil? ? [domain.to_s, aggregate.hecks_name] : [domain.to_s, aggregate.hecks_name, id.to_s]
           @registry_lock.synchronize { @locks[key] ||= Mutex.new }

data/lib/hecks/runtime/boot_gates.rb

@@ -20,19 +20,37 @@ module Hecks
     # Sharing a primitive between them is deferred until a third consumer
     # actually wants it (0031's own Rejected Alternatives).
     class BootGates
+      # @return [void]
       def initialize
         @gates = Hash.new { |h, k| h[k] = [] }
       end
 
+      # Adds a gate to `phase`, run in registration order alongside any other gate there.
+      #
+      # @param name [Symbol] the gate's name, checked by `registered?`
+      # @param gate [Proc, Method] the gate; called as `gate.call(registry, directory)`
+      # @param phase [Symbol] the phase this gate runs under, such as `:pre_verify` or
+      #   `:post_verify`
+      # @return [Hecks::Runtime::BootGates] self, for chaining
       def register(name, gate, phase:)
         @gates[phase] << [name, gate]
         self
       end
 
+      # Reports whether a gate named `name` has been registered, under any phase.
+      #
+      # @param name [Symbol] the gate name to look for, across every phase
+      # @return [Boolean] true if a gate named `name` was registered under any phase
       def registered?(name)
         @gates.values.flatten(1).any? { |registered_name, _gate| registered_name == name }
       end
 
+      # Runs every gate registered under `phase`, in registration order.
+      #
+      # @param phase [Symbol] the phase to run, such as `:pre_verify` or `:post_verify`
+      # @param registry [Runtime::Registry] the booted registry, passed to each gate
+      # @param directory [String] the boot directory, passed to each gate
+      # @return [void]
       def run!(phase, registry, directory)
         @gates[phase].each { |pair| pair.last.call(registry, directory) }
       end

data/lib/hecks/runtime/caller.rb

@@ -37,8 +37,34 @@ module Hecks
 
       module_function
 
+      # The ambient caller bound by the innermost enclosing `as` block on this thread.
+      #
+      # @return [Runtime::Caller::Current, nil] the bound caller, or nil when no `as`
+      #   block is on the stack for this thread
       def current = Thread.current[:hecks_caller]
 
+      # Binds the ambient caller for the duration of the block, restoring whatever
+      # caller (if any) was bound before, even if the block raises.
+      #
+      # `actor_id`, `as_of` and `scope` are each optional, self-asserted facts about
+      # the caller rather than derived from the command — see `Current`'s own header
+      # above for why each stays here instead of becoming a command-level DSL
+      # construct.
+      #
+      # @param role [String] the role the caller states it holds, checked by string
+      #   equality against the command's declared `role`
+      # @param actor_id [String, nil] who the caller is; when given, lets
+      #   `CommandRules::Authorization` check a real Governance `RoleAssignment`
+      #   instead of the bare role-string comparison
+      # @param as_of [Integer, nil] Unix epoch seconds the caller asserts as "now",
+      #   filled at the door from `Ports::Clock.now`; nil leaves a `RoleAssignment`'s
+      #   `starts_at` unchecked
+      # @param scope [String, nil] the scope the caller states it is acting in,
+      #   checked against the matching `RoleAssignment`'s own `scope`; nil skips
+      #   that check
+      # @yield the code that should see `role`/`actor_id`/`as_of`/`scope` as the
+      #   ambient caller
+      # @return [Object] the block's result
       def as(role:, actor_id: nil, as_of: nil, scope: nil)
         previous = Thread.current[:hecks_caller]
         Thread.current[:hecks_caller] = Current.new(
@@ -49,11 +75,17 @@ module Hecks
         Thread.current[:hecks_caller] = previous
       end
 
+      # Clears the ambient caller for the duration of the block, restoring
+      # whatever caller (if any) was bound before, even if the block raises.
+      #
       # A reaction is the system acting, not the caller who happened to be
       # on the stack when the triggering command ran — `Dispatcher#reenter`
       # clears the ambient caller around a reaction's own dispatch so a
       # triggering caller's role can neither satisfy nor block a reaction
       # command it has nothing to do with.
+      #
+      # @yield the code that should see no ambient caller bound
+      # @return [Object] the block's result
       def without
         previous = Thread.current[:hecks_caller]
         Thread.current[:hecks_caller] = nil

data/lib/hecks/runtime/capability_graph.rb

@@ -14,6 +14,8 @@ module Hecks
     # adapter names the port it implements, and neither can point at a third
     # port. There is no edge for a cycle to be made of.
     class CapabilityGraph
+      # @param registry [Runtime::Registry] the booted registry to read ports and adapters from
+      # @return [void]
       def initialize(registry)
         @registry = registry
       end
@@ -21,6 +23,9 @@ module Hecks
       # { port name => [adapter name, ...] }, for every port the registry
       # declares — including the ports nothing implements, so a caller can
       # tell "declared, unfulfilled" from "never declared at all".
+      #
+      # @return [Hash{String => Array<String>}] each declared port's name mapped to the names
+      #   of every adapter bound to it (empty when none are)
       def fulfillments
         @fulfillments ||= @registry.ports.each_key.to_h { |name| [name, adapters_for(name)] }
       end
@@ -28,10 +33,16 @@ module Hecks
       # The ports with zero adapters bound — the gap `Runtime::WiringError`
       # would otherwise only surface at the moment something tries to dispatch
       # through one.
+      #
+      # @return [Array<String>] the names of every declared port with no adapter bound to it
       def unfulfilled
         fulfillments.select { |_, adapters| adapters.empty? }.keys
       end
 
+      # Reports the port-dependency cycles this registry has — always none; see the module
+      # header for why no port model here can express one.
+      #
+      # @return [Array] always empty
       def cycles = []
 
       private

data/lib/hecks/runtime/command_interpreter/argument_gate.rb

@@ -10,10 +10,10 @@ module Hecks
       module ArgumentGate
         private
 
-        # Anything else used to ride along in the payload untouched —
-        # normalize_args walks the declared attributes, so a name the command
-        # never had was simply never looked at. A misspelled argument did
-        # nothing, in silence.
+        # Without this check, anything else would ride along in the payload
+        # untouched — normalize_args walks only the declared attributes, so
+        # a name the command never had is simply never looked at, and a
+        # misspelled argument would do nothing, in silence.
         #
         # The keys that are legitimately not attributes are the ones that address
         # the aggregate rather than describe it : `id`, whatever the aggregate is
@@ -49,12 +49,13 @@ module Hecks
         # until fuzz went looking : a name the command never declared was refused,
         # while a name it did declare could simply be left out.
         #
-        # `Customer.Register` without its `name` used to be refused — but by
-        # accident, and with a lie for a message. `then_set :name, to: :name` found
-        # nothing to resolve, passed the literal symbol on, and coercion reported
-        # `name is a PersonName — pass its fields as an object`, which describes a
-        # mistake the caller did not make. The real mistake — an argument simply
-        # missing — was never the one named, and nothing refused it on purpose.
+        # Refusing `Customer.Register` for a missing `name` needs to be
+        # deliberate, not an accident with a lie for a message. Without this
+        # check, `then_set :name, to: :name` finds nothing to resolve, passes
+        # the literal symbol on, and coercion reports `name is a PersonName —
+        # pass its fields as an object`, which describes a mistake the caller
+        # did not make. The real mistake — an argument simply missing — is
+        # never the one named unless this refuses it on purpose.
         #
         # No command attribute anywhere in the corpus carries a default — checked,
         # all eight chapters, zero — so there is no optional argument for this to
@@ -65,16 +66,17 @@ module Hecks
         # (`CommandBuilder#reference_to`'s bare self-reference mints no
         # attribute to be absent) — but `PortOperationBuilder#reference_to`
         # always mints one (this file's own header on `PortOperation`: "no
-        # creates?/acts_on distinction to protect"), because an operation
-        # historically had no other way to say which record it addressed.
-        # `to:` is that other way now (`Dispatcher#port_invocation`
-        # promotes the identity attribute's own value out of the payload
-        # and into routing) — which left the attribute still declared,
-        # still non-optional, and now never present in `args` at all: every
-        # operation with an identity attribute refused its own well-formed
-        # calls, dispatched exactly the way `to:` intends. Exempted here on
-        # the same terms an aggregate command's self-address always was —
-        # an address, not a fact the operation still needs handed back.
+        # creates?/acts_on distinction to protect"), because an operation had
+        # no other way to say which record it addressed before `to:` existed.
+        # `to:` is that way now (`Dispatcher#port_invocation` promotes the
+        # identity attribute's own value out of the payload and into
+        # routing) — which leaves the attribute still declared, still
+        # non-optional, and never present in `args` at all: without this
+        # exemption, every operation with an identity attribute would refuse
+        # its own well-formed calls, dispatched exactly the way `to:`
+        # intends. Exempted here on the same terms an aggregate command's
+        # self-address always was — an address, not a fact the operation
+        # still needs handed back.
         def refuse_absent_arguments(command, args, aggregate: nil)
           given    = args.keys.map(&:to_sym)
           exempt   = aggregate && command.respond_to?(:identity_attribute) &&
@@ -92,7 +94,7 @@ module Hecks
                                            declared: declared_names(command))
         end
 
-        # **A command that declares nothing still has to say so**. `Account
+        # A command that declares nothing still has to say so. `Account
         # .Freeze` is `reference_to Account` and no attributes at all, so
         # `{declared}` rendered empty and the sentence trailed off mid-
         # clause : "Freeze does not declare standing — it takes ". Read

data/lib/hecks/runtime/command_interpreter/mutation_applier.rb

@@ -165,9 +165,9 @@ module Hecks
                                      fields)
                     end
 
-          # Frozen, like every other value the domain hands back. An
-          # appended list used to come back mutable, so a caller could
-          # push straight into an aggregate's own state after the
+          # Frozen, like every other value the domain hands back — without
+          # this, an appended list would come back mutable, letting a
+          # caller push straight into an aggregate's own state after the
           # dispatch had finished.
           Freezer.deep(Array(instance[mutation.target]) + [element])
         end
@@ -197,11 +197,11 @@ module Hecks
 
         # Vendored fix, not (yet) upstream hecks (migration plan
         # task 9): #apply's `:increment`/`:decrement`/`:multiply`
-        # branches used to wrap `amount` into a `Value` unconditionally
+        # branches wrapping `amount` into a `Value` unconditionally
         # whenever the target attribute existed, never checking whether
         # `current` (the field's own existing value, read straight off
-        # `instance[mutation.target]`) was also wrapped -- the two sides
-        # of the same arithmetic call could disagree on Value-ness. On a
+        # `instance[mutation.target]`) was also wrapped, would let the two
+        # sides of the same arithmetic call disagree on Value-ness. On a
         # phantom-created field this is the common case, not an edge
         # one: `Instance.defaults`/`#default_for` leaves a VO-typed
         # attribute with no declared `default:` genuinely absent (nil),
@@ -276,16 +276,15 @@ module Hecks
           held.max.to_i + 1
         end
 
-        # Moved to `EntityElement.check_entity_collision` (entity_element.rb)
-        # — BUG#145. Used to live here, called only from `#entity_element`
-        # above (an aggregate's own entity list, e.g. `Workspace.boards`).
+        # The entity-collision check lives in `EntityElement.check_entity_collision`
+        # (entity_element.rb) — BUG#145 — shared by both `#entity_element` above
+        # (an aggregate's own entity list, e.g. `Workspace.boards`) and
         # `EntityElement#appended_to_element`'s own nested-entity branch (an
-        # entity's own entity list one hop further in, e.g. `Board.cards`)
-        # needs the exact same guard — see that method's own call site and
-        # comment for why a caller-supplied nested identity was silently
-        # duplicating before this moved. Pure relocation, not a behavior
-        # change here: the check's own doc comment (heads/composite/
-        # auto-mint reasoning) now lives with the code, in entity_element.rb.
+        # entity's own entity list one hop further in, e.g. `Board.cards`),
+        # which needs the exact same guard against a caller-supplied nested
+        # identity silently duplicating. See that method's own call site and
+        # comment; the check's own doc comment (heads/composite/auto-mint
+        # reasoning) lives with the code, in entity_element.rb.
       end
     end
   end

data/lib/hecks/runtime/command_interpreter.rb

@@ -31,7 +31,7 @@ module Hecks
       # both directions.
       DISPATCH_ORDER = Hecks::Vocabulary.symbols("AggregateDispatchOrder")
 
-      # **A last-resort safety valve, not the normal outcome path** — see
+      # A last-resort safety valve, not the normal outcome path — see
       # `Runtime::StaleWrite`'s own comment. Two concurrent writers
       # against one aggregate resolve through exactly one retry in the
       # ordinary case (the loser's retried hydrate reads the winner's now-
@@ -41,14 +41,17 @@ module Hecks
       # two-writer case.
       MAX_STALE_WRITE_RETRIES = 5
 
-      # Every cross-step local `call` used to thread through its own literal
-      # sequence, held in one place now that the sequence is data-driven —
+      # Every cross-step local held in one place, now that the sequence is
+      # data-driven rather than `call`'s own literal method-call sequence —
       # `result` and `transition`/`old_state` default to nil until the step
-      # that sets them runs, same as they were unset locals before that point.
+      # that sets them runs, the same as unset locals would be before that point.
       Context = Struct.new(:domain, :aggregate, :command, :args, :repository, :instance, :transition, :old_state,
                            :result, :correlation, :route, :plan, :strategy, :persistence_outcome, :pending_delegation,
                            :dry_run, :correction_bindings, :outbox_rows, :invocation)
 
+      # @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
@@ -69,6 +72,27 @@ module Hecks
       # `invocation` — the `Runtime::Invocation` `Dispatcher` built for this
       # call. `ctx.args` is `invocation.to_args` (the same Hash routing
       # always handed this method), `ctx.route` its `target`.
+      #
+      # @param domain [String, Symbol] the domain `aggregate` belongs to
+      # @param aggregate [Bluebook::Aggregate] the aggregate the command acts on
+      # @param command [Class] the command class (`Bluebook::Command` subclass) to dispatch
+      # @param invocation [Runtime::Invocation] the invocation `Dispatcher` built for
+      #   this call
+      # @param correlation [Hash{Symbol => Object}, nil] correlation head => value,
+      #   stamped on every emitted event when a saga leg causes this dispatch; nil
+      #   otherwise
+      # @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 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, command, invocation, correlation = nil, dry_run: false)
         args    = invocation.to_args
         route   = invocation.target
@@ -273,9 +297,9 @@ module Hecks
           # `ensures`/`enforce_invariants`/`save` steps still run after
           # this one. The target's emission is parked and performed by
           # `step_emit`, after the parent committed — where every other
-          # command's events are emitted too. (Before this, the entity
-          # leg's events were on the event log and in the adapter before
-          # the parent could refuse.)
+          # command's events are emitted too. (Without parking it here, the
+          # entity leg's events would be on the event log and in the adapter
+          # before the parent could refuse.)
           ctx.pending_delegation = [target_command, target_args]
         end
       end
@@ -350,7 +374,7 @@ module Hecks
 
       def persist_instance(ctx)
         if ctx.strategy == DependencyPlanning::ATOMIC_PUT
-          # **A second creation is not a fresh one** — see
+          # A second creation is not a fresh one — see
           # hydrate_complete_state's own comment; the
           # same refusal, on the same terms, for the
           # complete-state path. `insert_only:` asks the
@@ -441,8 +465,9 @@ module Hecks
           # `:delegate` mutation.
           if ctx.pending_delegation
             target_command, target_args = ctx.pending_delegation
-            # The same dispatch, so the same correlation — a saga-driven
-            # door's events used to lose their stamp here.
+            # The same dispatch, so the same correlation — without
+            # threading `ctx.correlation` through, a saga-driven door's
+            # events would lose their stamp here.
             next @rules.emit(target_command, ctx.domain, ctx.aggregate, ctx.instance, target_args, ctx.repository,
                              ctx.correlation)
           end
@@ -562,7 +587,7 @@ module Hecks
                                                         aggregate: aggregate.hecks_name,
                                                         identity:  identity_reading(aggregate)))
 
-        # **A second creation is not a fresh one** — `creates?` on an identity
+        # A second creation is not a fresh one — `creates?` on an identity
         # a record already exists under refuses (`AlreadyExists`) rather
         # than silently overwriting it, the same refusal `hydrate_prior_
         # or_initial`'s own body gives for its own complete-but-state-
@@ -604,7 +629,7 @@ module Hecks
                                                         identity:  identity_reading(aggregate)))
         found = repository.find(id)
 
-        # **A second creation is not a fresh one** — see hydrate_complete_
+        # A second creation is not a fresh one — see hydrate_complete_
         # state's own comment; the same refusal, on the same terms, for
         # a complete-but-state-dependent command (one with a `given`
         # reading its own prior state, which is what routes here instead
@@ -614,10 +639,10 @@ module Hecks
         # prior state this branch exists to supply), so only a genuine
         # creation reusing an already-occupied identity is a duplicate.
         # `SafeDepositBox.Rent` is exactly this shape — `given("box is
-        # vacant")` makes it state-dependent, so a second Rent used to
-        # silently hydrate the existing box as "prior state" and refuse
-        # for the wrong reason (not vacant) instead of the right one
-        # (already exists).
+        # vacant")` makes it state-dependent, so without this check a
+        # second Rent would silently hydrate the existing box as "prior
+        # state" and refuse for the wrong reason (not vacant) instead of
+        # the right one (already exists).
         if found && command.creates?
           raise(AlreadyExists, RefusalWording.render_site("AlreadyExists", "creating_duplicate",
                                                           command: command.hecks_name, aggregate: aggregate.hecks_name,
@@ -628,7 +653,7 @@ module Hecks
         found ? found.dup : Instance.new(aggregate: aggregate, id: id, args: args)
       end
 
-      # **The join, the dig, and the reading** — all shared with `EntityInterpreter`
+      # The join, the dig, and the reading — all shared with `EntityInterpreter`
       # now, in `Runtime::Identity`, rather than kept as two copies that could
       # only ever drift. See that module for the reasoning ; these three stay
       # here, at the old names, purely so nothing below has to change.