hecks 2.8.0 → 3.0.0

data/lib/hecks/runtime/command_interpreter.rb

@@ -13,10 +13,8 @@ require_relative "rebuild_sweep"
 
 module Hecks
   module Runtime
-    # The dispatch pipeline for a command on an aggregate head. The payload
-    # gate lives in command_interpreter/argument_gate.rb, the mutation walk
-    # in command_interpreter/mutation_applier.rb; what stays here is the
-    # order of the steps and how a record is addressed.
+    # The dispatch pipeline for a command on an aggregate head; the argument
+    # gate and mutation walk are mixed in from their own files.
     class CommandInterpreter
       include Interpreting
       include ArgumentGate
@@ -24,27 +22,17 @@ module Hecks
 
       attr_reader :registry
 
-      # **The declared order** — Vocabulary::AggregateDispatchOrder
-      # (language/bluebook/vocabulary.bluebook), read off the generated table
-      # (lib/hecks/vocabulary.rb) rather than typed here. spec/vocabulary_
-      # conformance_spec.rb holds every step to a real `step_<name>` handler,
-      # both directions.
+      # Read off the generated table (lib/hecks/vocabulary.rb), not typed here.
+      # spec/vocabulary_conformance_spec.rb holds every step to a real
+      # `step_<name>` handler, both directions.
       DISPATCH_ORDER = Hecks::Vocabulary.symbols("AggregateDispatchOrder")
 
-      # 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-
-      # committed state and its own `given` refuses for real, raising
-      # `GivenNotMet`, not `StaleWrite`) — this cap exists for pathological
-      # contention (many concurrent writers on one hot aggregate), not the
-      # two-writer case.
+      # A cap for pathological contention (many concurrent writers on one hot
+      # aggregate) — the ordinary two-writer race resolves in a single retry.
       MAX_STALE_WRITE_RETRIES = 5
 
-      # 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, the same as unset locals would be before that point.
+      # Every cross-step local held in one place; fields default to nil until
+      # the step that sets them runs.
       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)
@@ -57,42 +45,18 @@ module Hecks
         @rules    = rules
       end
 
-      # `dry_run:` — Dispatcher#dry_run?'s own entry point. Every step up
-      # through enforce_ensures/enforce_invariants runs exactly as a real
-      # dispatch would (givens checked, mutations applied to `ctx.instance`
-      # in memory); `step_save`/`step_emit` are the only two that read this
-      # flag, each skipping its own real work — see their own comments.
-      # Retries the whole method body on `StaleWrite` — a fresh `ctx`, a
-      # fresh `step_hydrate` re-reading current state, so `enforce_givens`
-      # re-evaluates against reality rather than the snapshot that just
-      # went stale. See `MAX_STALE_WRITE_RETRIES`/`Runtime::StaleWrite`
-      # for why exhaustion is a pathological-contention signal, not the
-      # expected shape of a two-writer race.
-      #
-      # `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`.
+      # Dispatches `command` against `aggregate` through the declared step
+      # order, retrying once per concurrent-write conflict.
       #
       # @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
+      # @param invocation [Runtime::Invocation] the invocation built for this call
+      # @param correlation [Hash, nil] saga correlation stamped on emitted events, if any
+      # @param dry_run [Boolean] validate every step without saving, emitting or enqueueing
+      # @return [Array] the settled instance, events, plan, persistence outcome, and outbox rows
+      # @raise [StandardError] a domain refusal (Runtime::DOMAIN_REFUSALS) when a rule refuses
+      # @raise [Runtime::StaleWrite, Runtime::WiringError] every retry loses, or resolve fails
       def call(domain, aggregate, command, invocation, correlation = nil, dry_run: false)
         args    = invocation.to_args
         route   = invocation.target
@@ -104,11 +68,8 @@ module Hecks
           ctx.route = route
           ctx.dry_run = dry_run
           ctx.plan = DependencyPlanning::Analyzer.call(aggregate: aggregate, command: command)
-          # **Resolved here, once, before hydration** — `Registry#repository`
-          # memoizes, so this and `step_hydrate`'s own read of `ctx.repository`
-          # (no second fetch there) always name the same instance;
-          # the isolation decision below (lock vs. CAS+retry) needs the
-          # repository's capabilities before a single step runs.
+          # Resolved once here, before hydration: `Registry#repository` memoizes,
+          # and the isolation decision below needs its capabilities up front.
           ctx.repository = @registry.repository(domain, aggregate)
           lock_id = Identity.best_effort(aggregate, args, route, reference_key: reference_key(command))
           run_dispatch_order_with_isolation(DISPATCH_ORDER, ctx, lock_key_id: lock_id)
@@ -122,14 +83,9 @@ module Hecks
 
       private
 
-      # **A no-op, and untraced** — Vocabulary::AggregateDispatchOrder's
-      # decode_arguments. Routing (`Runtime::Routing`) has already handed
-      # `call` a decoded argument hash by the time any step runs, so there is
-      # nothing left to decode here yet; like a conditional step that does
-      # not fire, it records nothing in `trace`. Declared so the Rust
-      # kernel's generated step enum carries the step its generated decoder
-      # will move into (roadmap D2), and so a typed Invocation (I2) has a
-      # step to be consumed at.
+      # No-op: `Routing` has already handed `call` a decoded argument hash,
+      # so there is nothing left to decode here yet. Kept as a step so the
+      # generated step enum has a slot to move the real decoder into later.
       def step_decode_arguments(_ctx); end
 
       def step_refuse_unknown_arguments(ctx)
@@ -171,14 +127,9 @@ module Hecks
 
       def step_enforce_givens(ctx)
         step(:enforce_givens) do
-          # Structural, before the declared givens — the same ordering
-          # NotFound/AlreadyExists already get at hydration: "does the
-          # fact this command's corrects names even exist" is not a
-          # domain rule an author wrote, it is a precondition for the
-          # domain rules to mean anything at all. Also locates the
-          # correction target itself, if `as:` named one — carried on
-          # `ctx` so `step_enforce_ensures` (the settled-record half)
-          # can bind the same name too, not just this pre-mutation half.
+          # Structural check before the declared givens (same ordering as
+          # NotFound/AlreadyExists at hydration). Also locates the correction
+          # target, if `as:` named one, so `step_enforce_ensures` can reuse it.
           ctx.correction_bindings = @rules.enforce_correction_target(ctx.instance, ctx.aggregate, ctx.command, domain: ctx.domain)
           @rules.enforce_givens(ctx.instance, ctx.command, ctx.args, domain: ctx.domain,
                                 declaring: ctx.aggregate, parent: ctx.instance, correction: ctx.correction_bindings)
@@ -220,61 +171,20 @@ module Hecks
         step(:advance_lifecycle) { ctx.instance[ctx.aggregate.lifecycle.field] = ctx.transition.target }
       end
 
-      # The synchronous cousin of a policy's own `trigger` — see
-      # `CommandBuilder#delegates_to`'s own comment for the full reasoning.
-      # Runs after this command's own mutations/lifecycle (so a delegating
-      # command could in principle still guard with its own `given`s first,
-      # though the real use in `domain/chess` declares none) and before
-      # `enforce_ensures`/`enforce_invariants`/`save`, so a refusal here
-      # raises a real, unrescued exception and nothing from either side —
-      # this command's own state, the target element's — has been saved
-      # yet. `ctx.instance` is the same in-memory record `step_hydrate`
-      # loaded and `step_save` will persist; `EntityElement.locate_chain`
-      # mutates it in place exactly the way `EntityInterpreter`'s own
-      # `step_locate_element`/`step_apply_mutations` mutate their own
-      # freshly-loaded copy — the only difference is which already-in-
-      # memory record gets handed in.
-      #
-      # Reimplements the entity command pipeline's own order (givens,
-      # transition, mutations, ensures, emit) inline, deliberately — see
-      # the comment above on why this must run strictly between this
-      # command's own mutations and its ensures/invariants/save. Splitting
-      # it would scatter that exact ordering across method boundaries and
-      # force threading element/view/transition/old_element/settled
-      # through as parameters — the `with:` bug documented just below is
-      # exactly the kind of ordering/plumbing mistake that shape invites.
-      # rubocop:disable-next Metrics/AbcSize
+      # The synchronous cousin of a policy's own `trigger` (see
+      # `CommandBuilder#delegates_to`). Runs between this command's own
+      # mutations and its ensures/invariants/save, so a refusal here leaves
+      # nothing committed on either side. Reimplements the entity pipeline
+      # (givens, transition, mutations, ensures, emit) inline, to keep that
+      # exact ordering in one place rather than threading state through
+      # method boundaries as parameters.
       def step_delegate_to_entity(ctx)
         delegation = ctx.command.mutations.find { |mutation| mutation.op == :delegate }
         return unless delegation
 
         step(:delegate_to_entity) do
-          entity_name, _dot, command_name = delegation.target.to_s.rpartition(".")
-          entity = ctx.aggregate.entities.find { |e| e.hecks_name == entity_name } ||
-                   raise(WiringError, "#{ctx.command.hecks_name} delegates_to #{entity_name}." \
-                                      "#{command_name}, but #{ctx.aggregate.hecks_name} has no " \
-                                      "entity named #{entity_name.inspect}")
-          target_command = entity.command(command_name) ||
-                           raise(WiringError, "#{ctx.command.hecks_name} delegates_to " \
-                                              "#{entity_name}.#{command_name}, which " \
-                                              "#{entity_name} declares no such command")
-
-          # `with:` remaps, it does not enumerate — starting from a copy
-          # of this command's own already-resolved args (`ctx.args`) and
-          # overlaying the explicit mapping on top means ambient context
-          # the caller never had to think about (the aggregate's own
-          # identity, addressed the ordinary way to reach `MoveKnight` at
-          # all) flows through to the target untouched, the same as it
-          # always would for a caller dispatching the entity command
-          # directly. Confirmed necessary, not a defensive guess: a real
-          # downstream domain's own AdvancePly-on-Moved policy silently
-          # failed to re-locate its own aggregate (`reaction_log`: "no
-          # Game with label.value ..."), because the emitted event's
-          # payload — built from `target_args` alone — never carried
-          # `label` at all when `with:` named only `id`/`to`.
-          target_args = ctx.args.merge(
-            delegation.source.to_h { |target_key, source_key| [target_key.to_sym, ctx.args[source_key]] }
-          )
+          entity, target_command, command_name = resolve_delegation_target(ctx, delegation)
+          target_args = mapped_and_gated_delegation_args(ctx, delegation, entity, target_command)
 
           element = EntityElement.locate_chain(ctx.aggregate, [entity], ctx.instance, target_args, command_name)
           view = Instance.new(aggregate: entity, id: EntityElement.element_identity(entity, element).to_s, state: element)
@@ -292,18 +202,52 @@ module Hecks
           settled = Instance.new(aggregate: entity, id: view.id, state: element)
           @rules.enforce_ensures(settled, target_command, target_args, old: old_element, domain: ctx.domain, parent: ctx.instance)
 
-          # Not emitted here — C7.2 (docs/semantics/bluebook-semantics.md):
-          # a refused command records nothing, and the parent's own
-          # `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. (Without parking it here, the
-          # entity leg's events would be on the event log and in the adapter
-          # before the parent could refuse.)
+          # Not emitted here — C7.2: a refused command records nothing, and
+          # the parent's own ensures/invariants/save steps still run after
+          # this one. Parked and emitted by `step_emit`, after the parent
+          # commits, alongside every other command's events.
           ctx.pending_delegation = [target_command, target_args]
         end
       end
 
+      # The entity and command a `delegates_to` mutation names, resolved once so
+      # `step_delegate_to_entity` can read them as plain locals.
+      def resolve_delegation_target(ctx, delegation)
+        entity_name, _dot, command_name = delegation.target.to_s.rpartition(".")
+        entity = ctx.aggregate.entities.find { |e| e.hecks_name == entity_name } ||
+                 raise(WiringError, "#{ctx.command.hecks_name} delegates_to #{entity_name}." \
+                                    "#{command_name}, but #{ctx.aggregate.hecks_name} has no " \
+                                    "entity named #{entity_name.inspect}")
+        target_command = entity.command(command_name) ||
+                         raise(WiringError, "#{ctx.command.hecks_name} delegates_to " \
+                                            "#{entity_name}.#{command_name}, which " \
+                                            "#{entity_name} declares no such command")
+        [entity, target_command, command_name]
+      end
+
+      # Builds the target command's own args, then runs the same argument gate
+      # `EntityInterpreter` runs before a direct dispatch of that command — evaluated
+      # against the target command's own declared attributes and the already
+      # `with:`-mapped args, not the delegating command's. Without this, a `with:`
+      # mapping that omits one of the target's required attributes would silently
+      # mutate and persist state that was never validated at all.
+      # `extra_identity_heads:` exempts the entity's own identity field (e.g. `id`),
+      # which locates the element but is never a declared attribute.
+      def mapped_and_gated_delegation_args(ctx, delegation, entity, target_command)
+        # `with:` remaps, it does not enumerate — starting from a copy of this command's
+        # own resolved args and overlaying the explicit mapping means ambient context the
+        # caller never named (the aggregate's own identity) still flows through to the
+        # target, the same as a direct dispatch of the entity command would get.
+        target_args = ctx.args.merge(
+          delegation.source.to_h { |target_key, source_key| [target_key.to_sym, ctx.args[source_key]] }
+        )
+
+        refuse_unknown_arguments(ctx.domain, ctx.aggregate, target_command, target_args,
+                                 extra_identity_heads: entity.identity_heads)
+        refuse_absent_arguments(target_command, target_args)
+        normalize_args(ctx.aggregate, target_command, target_args)
+      end
+
       def step_enforce_ensures(ctx)
         step(:enforce_ensures) do
           @rules.enforce_ensures(ctx.instance, ctx.command, ctx.args, old: ctx.old_state,
@@ -315,33 +259,10 @@ module Hecks
         step(:enforce_invariants) { @rules.enforce_invariants(ctx.instance, ctx.aggregate, domain: ctx.domain) }
       end
 
-      # `dry_run:` skips the write half of this step — see Dispatcher#
-      # dry_run?'s own comment — but not `resolve_state_references`.
-      # BUG#127: that check is validation, not persistence — it asks
-      # whether the settled in-memory state names a reference target that
-      # actually exists, the same question a real dispatch answers before
-      # it ever writes anything. Skipping it under `dry_run:` made
-      # `dry_run?` disagree with what a real dispatch immediately after it
-      # would do: it answered `true` ("would succeed") for a command whose
-      # real dispatch refuses with NotFound. Only the persist/raise-on-
-      # conflict tail is genuinely persistence-only and stays behind the
-      # early return.
-      #
-      # BUG#132 — a second validation-not-persistence check hid in that
-      # same persist/raise-on-conflict tail: `persist_instance`'s own
-      # ATOMIC_PUT branch (below) is where `hydrate_complete_state`'s
-      # comment says a `creates?` command's duplicate check is
-      # deliberately deferred to, for a strategy this fast — a read
-      # (`repository.find`) any earlier, before the real write, would be
-      # exactly the extra read `insert_only:` exists to avoid paying on
-      # every real dispatch. But that means the check never ran at all under
-      # `dry_run:` — not eagerly (hydration skips it for this exact
-      # strategy, on purpose) and not deferred (this whole branch returns
-      # first). `Roster::Roster.Open` against an already-open name is
-      # this shape: `dry_run?` answered `true` for a real dispatch
-      # immediately after it that refuses `AlreadyExists`. Under
-      # `dry_run:` there is no write to race, so paying for that one read
-      # is safe here — and only here.
+      # `dry_run:` skips persistence, but not `resolve_state_references` or
+      # the ATOMIC_PUT duplicate check (`check_dry_run_creates_duplicate`) —
+      # both are validation, not persistence, and a real dispatch would
+      # refuse on either before ever writing.
       def step_save(ctx)
         step(:save) { @rules.resolve_state_references(ctx.domain, ctx.aggregate, ctx.instance.state) }
 
@@ -357,11 +278,9 @@ module Hecks
         end
       end
 
-      # See `step_save`'s own BUG#132 comment: the only path, real or dry,
-      # able to catch a `creates?` command reusing an already-occupied
-      # identity when `strategy` is `ATOMIC_PUT` — `hydrate_complete_
-      # state` deliberately skips this exact case (its own comment), and
-      # a dry run never reaches `persist_instance`'s matching branch.
+      # The only path, real or dry, that catches a `creates?` command reusing
+      # an occupied identity under ATOMIC_PUT — `hydrate_complete_state`
+      # deliberately defers this exact check to here.
       def check_dry_run_creates_duplicate(ctx)
         return unless ctx.strategy == DependencyPlanning::ATOMIC_PUT && ctx.command.creates?
         return unless ctx.repository.find(ctx.instance.id)
@@ -374,23 +293,15 @@ module Hecks
 
       def persist_instance(ctx)
         if ctx.strategy == DependencyPlanning::ATOMIC_PUT
-          # 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
-          # adapter to decide and refuse atomically
-          # (never writing a `creates?` command over an
-          # identity that already names a record) rather
-          # than this interpreter reading the record
-          # first to check — a `repository.find` before
-          # every atomic_put would be exactly the read
-          # this strategy exists to skip.
+          # `insert_only:` asks the adapter to refuse atomically rather than
+          # this interpreter reading the record first to check — a
+          # `repository.find` before every atomic_put would be exactly the
+          # read this strategy exists to skip.
           ctx.repository.atomic_put(ctx.instance, insert_only: ctx.command.creates?)
         else
-          # `expected_version:` is `ctx.instance.version` — nil for a
-          # brand-new record (never read from storage) or when the
-          # repository isn't CAS-capable, either of which falls straight
-          # through to a plain, unconditional save inside `AppendOnly#save`.
+          # `expected_version:` is nil for a brand-new record or a
+          # non-CAS repository, either of which falls through to a
+          # plain, unconditional save inside `AppendOnly#save`.
           ctx.repository.save(ctx.instance, expected_version: ctx.instance.version)
         end
       end
@@ -402,10 +313,9 @@ module Hecks
                                                           identity: identity_reading(ctx.aggregate),
                                                           offered: Rendering.describe(ctx.instance.id)))
         elsif ctx.persistence_outcome.status == :stale
-          # Not a `RefusalWording.render` call — this is not a declared
-          # vocabulary refusal, just a plain, informative message. See
-          # `Runtime::StaleWrite`'s own comment: caught by `#call`'s
-          # retry loop, re-raised only once retries are exhausted.
+          # Not a declared vocabulary refusal, just a plain, informative
+          # message — caught by `#call`'s retry loop, re-raised only once
+          # retries are exhausted.
           raise(StaleWrite,
                 "#{ctx.command.hecks_name} on #{ctx.aggregate.hecks_name} " \
                 "(#{identity_reading(ctx.aggregate)}: #{Rendering.describe(ctx.instance.id)}) lost a race — " \
@@ -413,28 +323,12 @@ module Hecks
         end
       end
 
-      # The one-time, synchronous half of `projects` (S12, ADR 0025) —
-      # `RebuildSweep` (`runtime/rebuild_sweep.rb`) is deliberately the
-      # only thing that keeps a projected field current against a
-      # target that changes after this record was written — no reactive
-      # `Policy#for_each` keeping it live in real time, that stays
-      # deferred, same as that file's own header explains. But without
-      # some synchronous population, a projected field never gets an
-      # initial value at all until an operator remembers to run a
-      # sweep by hand — every acting command reading it (`given
-      # ("customer is active") { customer_status == "active" }`, say)
-      # would refuse a freshly created, genuinely active record for no
-      # real reason, which is not the eventual-consistency tradeoff the
-      # ADR accepts, just a bug. So: every time a record with `projects`
-      # fields is about to save — creating or acting, either can be the
-      # first time a referenced record resolves — read each one once,
-      # here, using the exact same `RebuildSweep.remote_value` a sweep
-      # itself would compute. This is still eventually consistent in
-      # the sense the ADR means: a change on the target side after this
-      # save still needs a sweep to reach here. It is only ever
-      # synchronous with this record's own write, never a live read
-      # triggered by a `given`/`ensures`/`invariant` mid-dispatch — the
-      # boundary rule those enforce holds exactly as before.
+      # The one-time, synchronous half of `projects` (ADR 0025); `RebuildSweep`
+      # is what keeps a projected field current afterward. Without seeding it
+      # here, a freshly created record would read a nil projected field until
+      # an operator ran a sweep, refusing commands that depend on it for no
+      # real reason. Uses the same `RebuildSweep.remote_value` a sweep
+      # computes, and runs only at save time, never as a live read mid-dispatch.
       def seed_projected_fields(ctx)
         return if ctx.aggregate.projected_fields.empty?
 
@@ -446,16 +340,11 @@ module Hecks
         end
       end
 
-      # A delegating command emits nothing of its own (`CommandBuilder#build`'s
-      # own guard refuses declaring `emits` alongside `delegates_to`) — its
-      # result is the target entity command's own `emits`, parked by
-      # `step_delegate_to_entity` and emitted here, after save (C7.2), not
-      # a second, empty call into `@rules.emit` for a command with no
-      # announced events at all.
-      #
-      # `dry_run:` skips this too, same reasoning as `step_save` — nothing
-      # was committed, so `ctx.result` stays nil and `Dispatcher#dry_run?`
-      # never reads it (its own return value is just whether this raised).
+      # A delegating command emits nothing of its own; its result is the
+      # target entity command's own `emits`, parked by
+      # `step_delegate_to_entity` and emitted here, after save (C7.2).
+      # `dry_run:` skips this too — nothing was committed, so `ctx.result`
+      # stays nil.
       def step_emit(ctx)
         return if ctx.dry_run
 
@@ -500,61 +389,12 @@ module Hecks
         found.dup
       end
 
-      # Wave 8 (equivalence-gap plan, item 1.6) — not done, and this
-      # comment now says precisely how far it got, corrected from an
-      # earlier version of itself that briefly (same PR, never released)
-      # claimed the inventory was empty and deleted this method outright.
-      # A full corpus audit (`DependencyPlanning::Analyzer.call` against
-      # every `creates?`-true command in all 5 example domains — banking,
-      # pizzas, chess, compliance, roster) found and fixed 4 real
-      # authoring bugs (`Statement.Generate`, `CreatePizza`, `Chess::
-      # Game.Start`, `Roster.Open` — each declared an attribute and
-      # never `sets` it, so the field silently stayed nil on every
-      # created record regardless of what a caller sent), plus a real
-      # `DependencyPlanning::Analyzer` bug for entity-owned commands
-      # (`root_aggregate:`, that class's own header) that surfaced one
-      # more live corpus bug of its own (`payment_cards.bluebook`'s own
-      # `Withdrawal.Dispute`, which never actually checked whether the
-      # card was retired) — all real, all kept.
-      #
-      # Deleting this method on that basis turned out to be wrong,
-      # caught by running the full suite rather than trusting the
-      # audit's own scope: the 5 example domains are nowhere near the
-      # whole inventory of `creates?`-true commands this fallback
-      # actually carries. Dozens of separate, purpose-built spec
-      # fixtures across the suite (`spec/fixtures/*.bluebook`, and
-      # inline `Hecks.bluebook` blocks declared directly inside
-      # individual spec files — governance, mutation ops, ports,
-      # routing, tenant isolation, sagas, and more) declare their own
-      # small `creates?`-true commands the same incomplete way, and
-      # rely on this exact fallback to create anything at all. Deleting
-      # it produced 218 failures across specs with nothing to do with
-      # Wave 8's own subject — confirmed, not guessed, by actually
-      # running `bundle exec rspec` after the deletion, not merely by
-      # extrapolating from the one audited inventory. `spec/fixtures/
-      # till.bluebook`'s own `Till.OpenTill` (missing `sets :number`,
-      # the identical bug shape as the 4 fixed above) was fixed
-      # alongside the four real corpus ones as one instance of this — but
-      # it was one of many, not the last one, and finding the rest is
-      # real, separate, much larger follow-up work this pass does not
-      # attempt: a suite-wide audit of every declared bluebook fixture,
-      # not just the 5 example domains the plan's own text named.
-      #
-      # Transitional compatibility for live source that has not yet
-      # acquired explicit effects, same as it always was — deliberately
-      # isolated from the normal routing and planning path so
-      # `reference_to` does not choose how a migrated command hydrates
-      # or persists. A real, future Wave 8 removes this once that wider
-      # inventory is empty, not before.
-      #
-      # `ctx.plan.complete_state?` already claimed every command whose
-      # plan is fully resolved in the two branches above `step_hydrate`
-      # tries first, so reaching this check already means the plan is
-      # incomplete — an un-migrated command still routes here on
-      # `creates?` alone, the same as the old `hydrate` did, regardless
-      # of whether it happens to have any mutations (`write_set`).
-      # Requiring an empty write_set here refused every un-migrated
-      # creating command that sets even one field.
+      # Transitional compatibility for a command that has not yet acquired
+      # explicit effects — isolated from the normal routing/planning path so
+      # `reference_to` does not choose how a migrated command hydrates. An
+      # un-migrated command routes here on `creates?` alone, regardless of
+      # whether it has any mutations; requiring an empty write_set here would
+      # wrongly exclude one that sets fields.
       def legacy_implicit_creation?(ctx)
         ctx.route.nil? && ctx.command.creates?
       end
@@ -587,19 +427,10 @@ module Hecks
                                                         aggregate: aggregate.hecks_name,
                                                         identity:  identity_reading(aggregate)))
 
-        # 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-
-        # dependent case, below. Only when `strategy` will not be ATOMIC_PUT:
-        # an atomic-put-capable adapter enforces this itself, atomically,
-        # via `insert_only:` in step_save (no read here, no race with the
-        # write) — but `strategy_for` already fell back to a plain `save`
-        # for an adapter with no atomic_put capability at all (Heki, today),
-        # and a plain `save` never refuses an overwrite on its own. Skipping
-        # this check for that case silently dropped the refusal instead of
-        # deferring it — the very "no such call — no such check" gap Wave
-        # 8 exists to close everywhere else.
+        # `creates?` on an occupied identity refuses (`AlreadyExists`), except
+        # under ATOMIC_PUT: that adapter enforces the same refusal itself,
+        # atomically, via `insert_only:` in `step_save` — reading here too
+        # would race the write for nothing.
         if command.creates? && strategy != DependencyPlanning::ATOMIC_PUT && repository.find(id)
           raise(AlreadyExists, RefusalWording.render_site("AlreadyExists", "creating_duplicate",
                                                           command: command.hecks_name, aggregate: aggregate.hecks_name,
@@ -610,11 +441,9 @@ module Hecks
         Instance.new(aggregate: aggregate, id: id, args: args)
       end
 
-      # A complete command may still depend on prior state: lifecycle guards
-      # are the common case. Read once so an existing record is checked against
-      # its real state; when no record exists, the aggregate's declared defaults
-      # are the prior state. Completeness, not a reference marker, proves that
-      # initializing that missing record is safe.
+      # A complete command may still depend on prior state (lifecycle guards
+      # are the common case) — read once, so an existing record is checked
+      # against its real state rather than assumed defaults.
       def hydrate_prior_or_initial(repository, aggregate, command, args, route)
         derived = identity_of(aggregate, args)
         if route && derived && route.aggregate.to_s != derived.to_s
@@ -629,20 +458,10 @@ module Hecks
                                                         identity:  identity_reading(aggregate)))
         found = repository.find(id)
 
-        # 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
-        # of hydrate_complete_state). Gated on `command.creates?`: a
-        # non-creating command's own complete payload legitimately means
-        # "act on whatever this identity already holds" (`found` is the
-        # 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 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).
+        # Same refusal as `hydrate_complete_state`, for a complete-but-state-
+        # dependent command (one with a `given` on its own prior state).
+        # Gated on `creates?`: a non-creating command's complete payload just
+        # means "act on whatever this identity already holds".
         if found && command.creates?
           raise(AlreadyExists, RefusalWording.render_site("AlreadyExists", "creating_duplicate",
                                                           command: command.hecks_name, aggregate: aggregate.hecks_name,
@@ -653,10 +472,9 @@ 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`
-      # 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.
+      # Shared with `EntityInterpreter`, in `Runtime::Identity`, rather than
+      # kept as two copies that could only ever drift; these three stay here,
+      # under their old names, so nothing below has to change.
       def identity_of(aggregate, args)   = Identity.of(aggregate, args)
       def identity_from(aggregate, args, key) = Identity.from(aggregate, args, key)
       def identity_reading(construct)    = Identity.reading(construct)