hecks 1.3.0 → 1.5.0

data/lib/hecks/runtime/command_interpreter.rb

@@ -24,15 +24,14 @@ module Hecks
 
       attr_reader :registry
 
-      # THE DECLARED ORDER, HAND-TYPED — mirrors Vocabulary::AggregateDispatchOrder
-      # (language/bluebook/vocabulary.bluebook:188-205), held equal to it by
-      # spec/vocabulary_conformance_spec.rb the same way every other vocabulary
-      # in that file is (RefusalWording::TEMPLATES, CommandRules::MUTATION_OPS,
-      # ...) rather than read live off the meta-domain at every dispatch —
-      # Runtime::RefusalWording's own doc comment gives the same reason.
+      # **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.
       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-
@@ -42,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)
+                           :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
@@ -60,21 +62,49 @@ module Hecks
       # 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
+      # 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.
-      def call(domain, aggregate, command, args, correlation = nil, route: nil, dry_run: false)
+      #
+      # `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
         attempt = 0
         begin
           ctx = Context.new(domain, aggregate, command, args)
+          ctx.invocation = invocation
           ctx.correlation = correlation
           ctx.route = route
           ctx.dry_run = dry_run
           ctx.plan = DependencyPlanning::Analyzer.call(aggregate: aggregate, command: command)
-          # RESOLVED HERE, ONCE, BEFORE HYDRATION — `Registry#repository`
+          # **Resolved here, once, before hydration** — `Registry#repository`
           # memoizes, so this and `step_hydrate`'s own read of `ctx.repository`
           # (no second fetch there any more) always name the same instance;
           # the isolation decision below (lock vs. CAS+retry) needs the
@@ -92,6 +122,16 @@ 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.
+      def step_decode_arguments(_ctx); end
+
       def step_refuse_unknown_arguments(ctx)
         step(:refuse_unknown_arguments) { refuse_unknown_arguments(ctx.domain, ctx.aggregate, ctx.command, ctx.args) }
       end
@@ -131,14 +171,14 @@ module Hecks
 
       def step_enforce_givens(ctx)
         step(:enforce_givens) do
-          # STRUCTURAL, before the declared givens — the same ordering
+          # 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.
+          # can bind the same name too, not just this pre-mutation half.
           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)
@@ -157,12 +197,12 @@ module Hecks
 
       def step_apply_mutations(ctx)
         # The state as the givens saw it — what `old` names inside an
-        # ensures. A shallow dup suffices: mutations REPLACE fields (set,
+        # ensures. A shallow dup suffices: mutations replace fields (set,
         # arithmetic via Value#with, append builds a new array), never
         # edit a held value in place.
         ctx.old_state = ctx.instance.state.dup unless ctx.command.ensures.empty?
         step(:apply_mutations) do
-          # ONE UPDATE SET OVER THE PRE-DISPATCH STATE (C4.2, docs/
+          # One update set over the pre-dispatch state (C4.2, docs/
           # semantics/bluebook-semantics.md): every effect's sources read
           # `pre` — the state as it was before this command — and its
           # target is written to the candidate; declaration order carries
@@ -180,19 +220,19 @@ 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
+      # 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
+      # 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
+      # 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 —
+      # 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`
+      # 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-
+      # `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,
@@ -219,8 +259,8 @@ module Hecks
                                               "#{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
+          # `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
@@ -228,7 +268,7 @@ module Hecks
           # 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
+          # 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`.
@@ -252,14 +292,14 @@ 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):
+          # 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. (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
@@ -275,29 +315,70 @@ module Hecks
         step(:enforce_invariants) { @rules.enforce_invariants(ctx.instance, ctx.aggregate, domain: ctx.domain) }
       end
 
-      # `dry_run:` skips this — see Dispatcher#dry_run?'s own comment. The
-      # same conditional-skip shape `step_assign_creation_attributes`
-      # already has (`return unless ctx.command.creates?`), not a new
-      # pattern: a step that does not apply this time traces nothing,
-      # rather than a caller having to branch around it.
+      # `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.
       def step_save(ctx)
-        return if ctx.dry_run
+        step(:save) { @rules.resolve_state_references(ctx.domain, ctx.aggregate, ctx.instance.state) }
+
+        if ctx.dry_run
+          step(:save) { check_dry_run_creates_duplicate(ctx) }
+          return
+        end
 
         step(:save) do
-          @rules.resolve_state_references(ctx.domain, ctx.aggregate, ctx.instance.state)
           seed_projected_fields(ctx)
           ctx.persistence_outcome = persist_instance(ctx)
           raise_for_persistence_outcome!(ctx)
         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.
+      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)
+
+        raise(AlreadyExists, RefusalWording.render_site("AlreadyExists", "creating_duplicate",
+                                                        command: ctx.command.hecks_name, aggregate: ctx.aggregate.hecks_name,
+                                                        identity: identity_reading(ctx.aggregate),
+                                                        offered: Rendering.describe(ctx.instance.id)))
+      end
+
       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
-          # ADAPTER to decide and refuse ATOMICALLY
+          # 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
@@ -316,12 +397,12 @@ module Hecks
 
       def raise_for_persistence_outcome!(ctx)
         if ctx.persistence_outcome.status == :conflicted
-          raise(AlreadyExists, RefusalWording.render("AlreadyExists", "creating_duplicate",
-                                                     command: ctx.command.hecks_name, aggregate: ctx.aggregate.hecks_name,
-                                                     identity: identity_reading(ctx.aggregate),
-                                                     offered: Rendering.describe(ctx.instance.id)))
+          raise(AlreadyExists, RefusalWording.render_site("AlreadyExists", "creating_duplicate",
+                                                          command: ctx.command.hecks_name, aggregate: ctx.aggregate.hecks_name,
+                                                          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
+          # 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.
@@ -332,26 +413,26 @@ module Hecks
         end
       end
 
-      # THE ONE-TIME, SYNCHRONOUS HALF OF `projects` (S12, ADR 0025) —
+      # 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
+      # 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
+      # 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,
+      # 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
+      # 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
+      # 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.
       def seed_projected_fields(ctx)
@@ -365,10 +446,10 @@ module Hecks
         end
       end
 
-      # A DELEGATING COMMAND EMITS NOTHING OF ITS OWN (`CommandBuilder#build`'s
+      # 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
+      # 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.
       #
@@ -384,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
@@ -397,53 +479,53 @@ module Hecks
       def hydrate_existing(repository, aggregate, command, args, route = nil)
         if route
           found = repository.find(route.aggregate) ||
-                  raise(NotFound, RefusalWording.render("NotFound", "record_missing",
-                                                        aggregate: aggregate.hecks_name,
-                                                        identity:  identity_reading(aggregate),
-                                                        offered:   Rendering.describe(route.aggregate)))
+                  raise(NotFound, RefusalWording.render_site("NotFound", "record_missing",
+                                                             aggregate: aggregate.hecks_name,
+                                                             identity:  identity_reading(aggregate),
+                                                             offered:   Rendering.describe(route.aggregate)))
           return found.dup
         end
 
         id = identity_of(aggregate, args) ||
              identity_from(aggregate, args, :id) ||
              identity_from(aggregate, args, reference_key(command)) ||
-             raise(NotFound, RefusalWording.render("NotFound", "acting_no_identity",
-                                                   command: command.hecks_name, aggregate: aggregate.hecks_name,
-                                                   identity: identity_reading(aggregate)))
+             raise(NotFound, RefusalWording.render_site("NotFound", "acting_no_identity",
+                                                        command: command.hecks_name, aggregate: aggregate.hecks_name,
+                                                        identity: identity_reading(aggregate)))
         found = repository.find(id) ||
-                raise(NotFound, RefusalWording.render("NotFound", "record_missing",
-                                                      aggregate: aggregate.hecks_name,
-                                                      identity:  identity_reading(aggregate),
-                                                      offered:   Rendering.describe(id)))
+                raise(NotFound, RefusalWording.render_site("NotFound", "record_missing",
+                                                           aggregate: aggregate.hecks_name,
+                                                           identity:  identity_reading(aggregate),
+                                                           offered:   Rendering.describe(id)))
         found.dup
       end
 
-      # WAVE 8 (equivalence-gap plan, item 1.6) — NOT done, and this
+      # 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)
+      # 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,
+      # 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
+      # `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,
+      # 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
+      # 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
+      # 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
@@ -462,7 +544,7 @@ module Hecks
       # acquired explicit effects, same as it always was — deliberately
       # isolated from the normal routing and planning path so
       # `reference_to` no longer chooses how a migrated command hydrates
-      # or persists. A real, future Wave 8 removes this once THAT wider
+      # 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
@@ -471,7 +553,7 @@ module Hecks
       # 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
+      # Requiring an empty write_set here refused every un-migrated
       # creating command that sets even one field.
       def legacy_implicit_creation?(ctx)
         ctx.route.nil? && ctx.command.creates?
@@ -479,14 +561,14 @@ module Hecks
 
       def hydrate_legacy_creation(repository, aggregate, command, args)
         id = identity_of(aggregate, args) ||
-             raise(NotFound, RefusalWording.render("NotFound", "creating_no_identity",
-                                                   command: command.hecks_name, aggregate: aggregate.hecks_name,
-                                                   identity: identity_reading(aggregate)))
+             raise(NotFound, RefusalWording.render_site("NotFound", "creating_no_identity",
+                                                        command: command.hecks_name, aggregate: aggregate.hecks_name,
+                                                        identity: identity_reading(aggregate)))
         if repository.find(id)
-          raise(AlreadyExists, RefusalWording.render("AlreadyExists", "creating_duplicate",
-                                                     command: command.hecks_name, aggregate: aggregate.hecks_name,
-                                                     identity: identity_reading(aggregate),
-                                                     offered: Rendering.describe(id)))
+          raise(AlreadyExists, RefusalWording.render_site("AlreadyExists", "creating_duplicate",
+                                                          command: command.hecks_name, aggregate: aggregate.hecks_name,
+                                                          identity: identity_reading(aggregate),
+                                                          offered: Rendering.describe(id)))
         end
 
         Instance.new(aggregate: aggregate, id: id, args: args)
@@ -500,29 +582,29 @@ module Hecks
         end
 
         id = route&.aggregate || derived ||
-             raise(NotFound, RefusalWording.render("NotFound", "creating_no_identity",
-                                                   command:   command.hecks_name,
-                                                   aggregate: aggregate.hecks_name,
-                                                   identity:  identity_reading(aggregate)))
+             raise(NotFound, RefusalWording.render_site("NotFound", "creating_no_identity",
+                                                        command:   command.hecks_name,
+                                                        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-
-        # dependent case, below. ONLY when `strategy` will NOT be ATOMIC_PUT:
+        # 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
+        # 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.
         if command.creates? && strategy != DependencyPlanning::ATOMIC_PUT && repository.find(id)
-          raise(AlreadyExists, RefusalWording.render("AlreadyExists", "creating_duplicate",
-                                                     command: command.hecks_name, aggregate: aggregate.hecks_name,
-                                                     identity: identity_reading(aggregate),
-                                                     offered: Rendering.describe(id)))
+          raise(AlreadyExists, RefusalWording.render_site("AlreadyExists", "creating_duplicate",
+                                                          command: command.hecks_name, aggregate: aggregate.hecks_name,
+                                                          identity: identity_reading(aggregate),
+                                                          offered: Rendering.describe(id)))
         end
 
         Instance.new(aggregate: aggregate, id: id, args: args)
@@ -541,37 +623,37 @@ module Hecks
         end
 
         id = route&.aggregate || derived ||
-             raise(NotFound, RefusalWording.render("NotFound", "creating_no_identity",
-                                                   command:   command.hecks_name,
-                                                   aggregate: aggregate.hecks_name,
-                                                   identity:  identity_reading(aggregate)))
+             raise(NotFound, RefusalWording.render_site("NotFound", "creating_no_identity",
+                                                        command:   command.hecks_name,
+                                                        aggregate: aggregate.hecks_name,
+                                                        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
         # 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
+        # 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 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("AlreadyExists", "creating_duplicate",
-                                                     command: command.hecks_name, aggregate: aggregate.hecks_name,
-                                                     identity: identity_reading(aggregate),
-                                                     offered: Rendering.describe(id)))
+          raise(AlreadyExists, RefusalWording.render_site("AlreadyExists", "creating_duplicate",
+                                                          command: command.hecks_name, aggregate: aggregate.hecks_name,
+                                                          identity: identity_reading(aggregate),
+                                                          offered: Rendering.describe(id)))
         end
 
         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.