hecks 0.3.0 → 1.0.1

data/lib/hecks/runtime/command_interpreter.rb

@@ -9,6 +9,7 @@ require_relative "../ports/persistence/execution"
 require_relative "instance"
 require_relative "refusal_wording"
 require_relative "entity_element"
+require_relative "rebuild_sweep"
 
 module Hecks
   module Runtime
@@ -31,13 +32,23 @@ module Hecks
       # Runtime::RefusalWording's own doc comment gives the same reason.
       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.
+      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 —
       # `result` and `transition`/`old_state` default to nil until the step
       # that sets them runs, same as they were unset locals before that point.
       Context = Struct.new(:domain, :aggregate, :command, :args, :repository, :instance, :transition, :old_state,
                            :result, :correlation, :route, :plan, :strategy, :persistence_outcome, :delegated_events,
-                           :dry_run)
+                           :dry_run, :correction_bindings)
 
       def initialize(registry, rules:)
         @registry = registry
@@ -49,14 +60,34 @@ 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
+      # 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)
-        ctx = Context.new(domain, aggregate, command, args)
-        ctx.correlation = correlation
-        ctx.route = route
-        ctx.dry_run = dry_run
-        ctx.plan = DependencyPlanning::Analyzer.call(aggregate: aggregate, command: command)
-        run_dispatch_order(DISPATCH_ORDER, ctx)
-        [ctx.instance, ctx.result, ctx.plan, ctx.persistence_outcome]
+        attempt = 0
+        begin
+          ctx = Context.new(domain, aggregate, command, args)
+          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`
+          # 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
+          # repository's capabilities before a single step runs.
+          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)
+          [ctx.instance, ctx.result, ctx.plan, ctx.persistence_outcome]
+        rescue StaleWrite
+          attempt += 1
+          retry if attempt < MAX_STALE_WRITE_RETRIES
+          raise
+        end
       end
 
       private
@@ -82,7 +113,8 @@ module Hecks
       end
 
       def step_hydrate(ctx)
-        ctx.repository = @registry.repository(ctx.domain, ctx.aggregate)
+        # `ctx.repository` is resolved once, in `#call`, before the
+        # isolation decision (lock vs. CAS+retry) — not here any more.
         ctx.strategy = ctx.plan.strategy_for(capabilities: ctx.repository.capabilities)
         ctx.instance = step(:hydrate) {
           if ctx.plan.complete_state? && ctx.plan.state_independent?
@@ -99,8 +131,17 @@ module Hecks
 
       def step_enforce_givens(ctx)
         step(:enforce_givens) {
+          # 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.
+          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)
+                                declaring: ctx.aggregate, parent: ctx.instance, correction: ctx.correction_bindings)
         }
       end
 
@@ -201,7 +242,7 @@ module Hecks
       def step_enforce_ensures(ctx)
         step(:enforce_ensures) {
           @rules.enforce_ensures(ctx.instance, ctx.command, ctx.args, old: ctx.old_state,
-                                 domain: ctx.domain, parent: ctx.instance)
+                                 domain: ctx.domain, parent: ctx.instance, correction: ctx.correction_bindings || {})
         }
       end
 
@@ -219,9 +260,10 @@ module Hecks
 
         step(:save) do
           @rules.resolve_state_references(ctx.domain, ctx.aggregate, ctx.instance.state)
+          seed_projected_fields(ctx)
           ctx.persistence_outcome = if ctx.strategy == DependencyPlanning::ATOMIC_PUT
                                       # A SECOND CREATION IS NOT A FRESH ONE — see
-                                      # hydrate_legacy_creation's own comment; the
+                                      # 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
@@ -233,18 +275,63 @@ module Hecks
                                       # this strategy exists to skip.
                                       ctx.repository.atomic_put(ctx.instance, insert_only: ctx.command.creates?)
                                     else
-                                      ctx.repository.save(ctx.instance)
-                                      Ports::Persistence::Outcome.new(status: :saved, instance: ctx.instance)
+                                      # `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`.
+                                      ctx.repository.save(ctx.instance, expected_version: ctx.instance.version)
                                     end
           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)))
+          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.
+            raise(StaleWrite,
+                  "#{ctx.command.hecks_name} on #{ctx.aggregate.hecks_name} " \
+                  "(#{identity_reading(ctx.aggregate)}: #{Rendering.describe(ctx.instance.id)}) lost a race — " \
+                  "another write committed against this record after it was read")
           end
         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.
+      def seed_projected_fields(ctx)
+        return if ctx.aggregate.projected_fields.empty?
+
+        ctx.aggregate.projected_fields.each do |field|
+          value = RebuildSweep.remote_value(@registry, ctx.domain, ctx.aggregate, ctx.instance.state, field)
+          next if value.nil?
+
+          ctx.instance.state[field.name] = value
+        end
+      end
+
       # A DELEGATING COMMAND EMITS NOTHING OF ITS OWN (`CommandBuilder#build`'s
       # own guard refuses declaring `emits` alongside `delegates_to`) — its
       # result IS whatever `step_delegate_to_entity` already collected from
@@ -292,19 +379,61 @@ module Hecks
         found.dup
       end
 
-      # Transitional compatibility for live source that has not yet acquired
-      # explicit effects. It is deliberately isolated from the normal routing
-      # and planning path so `reference_to` no longer chooses how a migrated
-      # command hydrates or persists. Wave 8 removes this after the inventory is
-      # empty; frozen eras retain their own shadow parser.
+      # 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` no longer chooses 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.
+      # `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.
       def legacy_implicit_creation?(ctx)
         ctx.route.nil? && ctx.command.creates?
       end
@@ -321,7 +450,7 @@ module Hecks
                                                      offered: Rendering.describe(id)))
         end
 
-        Instance.new(aggregate: aggregate, id: id)
+        Instance.new(aggregate: aggregate, id: id, args: args)
       end
 
       def hydrate_complete_state(repository, aggregate, command, args, route, strategy)
@@ -337,9 +466,11 @@ module Hecks
                                                    aggregate: aggregate.hecks_name,
                                                    identity:  identity_reading(aggregate)))
 
-        # A SECOND CREATION IS NOT A FRESH ONE — see hydrate_legacy_creation's
-        # own comment; the same refusal, on the same terms, for the
-        # complete-state path. ONLY when `strategy` will NOT be ATOMIC_PUT:
+        # 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`
@@ -355,7 +486,7 @@ module Hecks
                                                      offered: Rendering.describe(id)))
         end
 
-        Instance.new(aggregate: aggregate, id: id)
+        Instance.new(aggregate: aggregate, id: id, args: args)
       end
 
       # A complete command may still depend on prior state: lifecycle guards
@@ -377,8 +508,8 @@ module Hecks
                                                    identity:  identity_reading(aggregate)))
         found = repository.find(id)
 
-        # A SECOND CREATION IS NOT A FRESH ONE — see hydrate_legacy_
-        # creation's own comment; the same refusal, on the same terms, for
+        # 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
@@ -398,7 +529,7 @@ module Hecks
                                                      offered: Rendering.describe(id)))
         end
 
-        found ? found.dup : Instance.new(aggregate: aggregate, id: id)
+        found ? found.dup : Instance.new(aggregate: aggregate, id: id, args: args)
       end
 
       # THE JOIN, THE DIG, AND THE READING — all shared with `EntityInterpreter`

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

@@ -116,11 +116,32 @@ module Hecks
         # parent aggregate reaching ITS OWN customer) resolves the same
         # way `account.customer.status` does for a command-level reference.
         # nil for an aggregate command — CommandInterpreter never passes it.
-        def enforce_givens(subject, command, args, domain:, declaring: nil, parent: nil)
+        # `correction:` — the `{as_name => payload}` bindings
+        # `enforce_correction_target` (above) already located, merged in
+        # LAST so an `as:` name wins the same way `old:` always wins in
+        # `enforce_ensures`, below — it is a fresh local binding a
+        # `corrects` command introduces, not a real argument/state field
+        # a caller could collide with by accident.
+        def enforce_givens(subject, command, args, domain:, declaring: nil, parent: nil, correction: {})
           state = GuardState.new(subject)
-          owner = subject.aggregate if subject.respond_to?(:aggregate)
-          attrs = dereference(domain, owner, subject).merge(args).merge(dereference(domain, command, args))
-          attrs = attrs.merge(parent: parent.state.merge(dereference(domain, parent.aggregate, parent.state))) if parent
+          # A RULE MAY ONLY READ WITHIN ITS OWN AGGREGATE BOUNDARY (S12,
+          # ADR 0025) — `subject`'s own STORED references are no longer
+          # dereferenced here at all. What used to be a live query against
+          # another aggregate's own repository is now just `subject`'s own
+          # state: a `projects :customer_status, from: :"customer.status"`
+          # field is a REGULAR stored attribute, already present in
+          # `subject`/`state` with no hydration step needed. `dereference`
+          # is still called on `command`/`args`, below — that is a
+          # DIFFERENT case the ADR explicitly keeps in bounds ("its command
+          # arguments"): a reference-typed ARGUMENT this dispatch was just
+          # handed (`Dispute`'s own `disputed_by`, say) has nothing stored
+          # to project yet, so resolving it here, once, synchronously with
+          # THIS command's own admission, is not the live-query-against-
+          # another-aggregate's-stored-state pattern the boundary rule
+          # forbids.
+          attrs = args.merge(dereference(domain, command, args))
+          attrs = attrs.merge(parent: parent.state) if parent
+          attrs = attrs.merge(correction) unless correction.empty?
           command.givens.each do |given|
             next if Bluebook::Expression::Evaluator.call(given.canonical, state, attrs)
 
@@ -130,6 +151,55 @@ module Hecks
           enforce_lifecycle_guard(declaring, command, subject) if declaring
         end
 
+        # `corrects` — CommandBuilder#corrects_impl's own comment. NOT
+        # expressible as an ordinary `given`: "has this exact record
+        # already emitted this exact event" is not a predicate over the
+        # record's OWN fields, it is a fact about the event log, so it is
+        # raised structurally here, the same way NotFound/AlreadyExists
+        # are, rather than through the expression evaluator. The build-
+        # time half — does ANYTHING in this aggregate ever emit the named
+        # event at all — is `AggregateBuilder#seal_correction_targets`;
+        # this is the dispatch-time half — has THIS record actually done
+        # so yet.
+        #
+        # ALSO LOCATES the matched event now, not just its existence, and
+        # returns a `{as_name => payload}` bindings hash — one entry per
+        # `:corrects` mutation that named an `as:` — so `given`/`ensures`
+        # on a corrects-bearing command can reference the located OLD
+        # event by that name, the same shape `enforce_ensures`'s own
+        # `old:` binding already has (CommandBuilder#corrects_impl's own
+        # comment: `as:` was stored, from the start, specifically to be
+        # wired into the evaluator once a real runtime consumer existed —
+        # this is that consumer). `.reverse.find` — the MOST RECENT
+        # matching event, if this record has somehow emitted the same
+        # correction target more than once; the prior existence-only
+        # check never had to make this choice, so it's a genuinely new
+        # one, made deliberately: `as:` reads as "the instance being
+        # corrected," which is naturally the latest fact on record, not
+        # an arbitrary one.
+        def enforce_correction_target(instance, aggregate, command, domain:)
+          bindings = {}
+          command.mutations.each do |mutation|
+            next unless mutation.op == :corrects
+
+            event_key  = "#{domain}::#{aggregate.hecks_name}"
+            event_name = mutation.target.to_s
+            corrected = @registry.event_log.reverse.find do |event|
+              event.name == event_name && event.aggregate == event_key && event.id == instance.id
+            end
+
+            unless corrected
+              raise NothingToCorrect,
+                    "#{command.hecks_name} refused — corrects #{event_name}, but " \
+                    "#{event_key} ##{instance.id} has never emitted it"
+            end
+
+            as = mutation.source[:as]
+            bindings[as.to_sym] = corrected.payload if as && !as.to_s.empty?
+          end
+          bindings
+        end
+
         # LIFECYCLE STATE AS A COMMAND GUARD (S10, ADR 0025) — `command
         # "Debit", from: "open"` checked here, folded into the SAME
         # dispatch step `given` already runs at (both are preconditions,
@@ -175,15 +245,21 @@ module Hecks
         # Not new to ensures — `given` lives under the same rule — but an
         # ensures is more likely to collide, since it typically re-reads a
         # field the command just took in to mutate it.
-        def enforce_ensures(subject, command, args, old:, domain:, parent: nil)
+        def enforce_ensures(subject, command, args, old:, domain:, parent: nil, correction: {})
           state = GuardState.new(subject)
-          owner = subject.aggregate if subject.respond_to?(:aggregate)
-          # Same merge-order reasoning as enforce_givens above: an
-          # aliased command-level reference must override its own raw
-          # id argument, not the other way round. `old` still wins over
-          # everything, unchanged.
-          attrs = dereference(domain, owner, subject).merge(args).merge(dereference(domain, command, args))
-          attrs = attrs.merge(parent: parent.state.merge(dereference(domain, parent.aggregate, parent.state))) if parent
+          # S12, ADR 0025 — same boundary reasoning as enforce_givens
+          # above: `subject`'s own stored references are no longer
+          # dereferenced here; a `projects`-maintained field is already
+          # part of `state`. `command`/`args` still dereferences — a
+          # fresh reference-typed ARGUMENT stays in bounds.
+          # `old` still wins over everything, unchanged. `correction`
+          # (an `as:`-bound corrected event, if this command declares
+          # one) wins right alongside it — a settled-record ensures can
+          # reference the correction target exactly as freely as a
+          # pre-mutation given already can.
+          attrs = args.merge(dereference(domain, command, args))
+          attrs = attrs.merge(parent: parent.state) if parent
+          attrs = attrs.merge(correction) unless correction.empty?
           attrs = attrs.merge(old: old)
           command.ensures.each do |rule|
             next if Bluebook::Expression::Evaluator.call(rule.canonical, state, attrs)
@@ -197,16 +273,23 @@ module Hecks
         # ensures` already checks at, and for the same reason: an
         # invariant is a claim about the SETTLED record, not the
         # command that produced it, so it reads no `args`/`old` at all,
-        # only the record's own (dereferenced) state. `subject` here is
+        # only the record's own state. `subject` here is
         # always the AGGREGATE's own instance — `CommandInterpreter`
         # passes its own `ctx.instance`, and `EntityInterpreter` passes
         # the PARENT record (`ctx.instance`, not the element), since an
         # entity mutation changes data inside the SAME aggregate
         # boundary the invariant guards; there is no separate "entity
         # invariant" to check the piece's own view against.
+        #
+        # NO `dereference` (S12, ADR 0025) — an invariant may only read
+        # `subject`'s own boundary, same rule `enforce_givens`/
+        # `enforce_ensures` now hold to. No invariant in the corpus has
+        # ever read across a `reference_to` (verified before this
+        # change), so this is not a migration, just closing the same
+        # capability off here that was already unused.
         def enforce_invariants(subject, aggregate, domain:)
           state = GuardState.new(subject)
-          attrs = dereference(domain, aggregate, subject)
+          attrs = {}
           aggregate.invariants.each do |invariant|
             next if Bluebook::Expression::Evaluator.call(invariant.canonical, state, attrs)
 
@@ -247,8 +330,10 @@ module Hecks
             Array(owner_instance[list_attr.name]).each do |element|
               wrapped = Instance.new(aggregate: entity, id: nil, state: element)
               element_state = GuardState.new(wrapped)
-              attrs = dereference(domain, entity, wrapped)
-                      .merge(parent: owner_instance.state.merge(dereference(domain, owner_construct, owner_instance)))
+              # NO `dereference` (S12, ADR 0025) — same boundary rule as
+              # enforce_invariants above; `parent` (the owner's own
+              # state, projected fields included) stays readable.
+              attrs = { parent: owner_instance.state }
 
               entity.invariants.each do |invariant|
                 next if Bluebook::Expression::Evaluator.call(invariant.canonical, element_state, attrs)

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

@@ -45,7 +45,13 @@ module Hecks
           # what Vocabulary::MutationOp declares — MutationApplier's own
           # `when :delegate` branch (mutation_applier.rb) never calls
           # #sign_of either, same as `remove`'s own note above.
-          MutationOp.new(name: "delegate",  sign: nil)
+          MutationOp.new(name: "delegate",  sign: nil),
+          # CommandBuilder#corrects_impl's own comment gives the full
+          # reasoning — a command amending a past event rather than
+          # acting fresh. Carries no sign, like delegate: it does no
+          # arithmetic of its own; the record's actual change, if any,
+          # is an ordinary `sets` declared alongside it.
+          MutationOp.new(name: "corrects",  sign: nil)
         ].freeze
 
         # A mutation's source is either the NAME OF AN ARGUMENT or a LITERAL, and
@@ -62,9 +68,39 @@ module Hecks
         # made. The real mistake, an absent argument, was never the one refused,
         # which is what fuzz surfaced.
         #
-        # Absent now resolves to nil. Whether it should be REFUSED instead
-        # is a separate question — the language cannot yet say which arguments are
-        # optional, and the meta-domain has plenty that are.
+        # STALE (as of the equivalence-gap plan's own audit): this used to
+        # say "the language cannot yet say which arguments are optional" —
+        # it already can, and always could once `attribute ..., optional:
+        # true` existed (`CommandBuilder#attribute_impl`,
+        # `attribute_collector.rb`): `sets` already sources correctly from
+        # an optional attribute, resolving absent to nil exactly as this
+        # method does, and REFUSING it here would be wrong, not merely
+        # undone work — `TillRoom::Till.TakeIn`'s own `note` (spec/
+        # fixtures/till.bluebook) and Banking's `CardPayment.Authorize`'s
+        # `tags` (payment_cards.bluebook) are real, live commands whose
+        # `sets` mutation is deliberately sourced from an optional
+        # attribute the caller may omit — `spec/runtime/command_rules_spec
+        # .rb`'s own "says an absent OPTIONAL argument is nil, not the
+        # name of the argument" pins exactly this as correct, not pending.
+        # The meta-domain's own self-hosted commands (Command.Declare's
+        # `role`/`goal`/`provenance`/`from`/`position`, and ~35 more sites
+        # across the language) all lean on the identical pattern — nil is
+        # the RIGHT answer for a `sets` sourced from a declared-optional
+        # attribute the caller left out, every time.
+        #
+        # The one thing that WAS still a real, narrow gap — a `sets`
+        # source Symbol naming NOTHING the command declares at all (a
+        # typo, not an optional argument) — silently resolved to nil
+        # forever the same way, indistinguishable at either build or run
+        # time from a legitimate optional absence. Closed at BUILD time
+        # instead of here: `CommandBuilder#refuse_unknown_argument_sources!`
+        # refuses it the moment the `.bluebook` file loads, mirroring
+        # `AggregateBuilder#seal_query_argument`'s identical check for a
+        # query's own where-clause argument. This function stays exactly
+        # what it always was — a pure, unconditional lookup — because by
+        # the time ANY mutation reaches it, the source has already been
+        # proven to name either a real, possibly-optional argument, or a
+        # StateRef/literal; there is nothing left here to refuse.
         def resolve_source(source, args)
           return args[source] if source.is_a?(Symbol)
 

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

@@ -37,7 +37,8 @@ module Hecks
 
           authorized =
             if caller.actor_id && governance_attached?(domain)
-              Ports::Authorization.holds_role?(registry, actor_id: caller.actor_id, role: command.role)
+              Ports::Authorization.holds_role?(registry, actor_id: caller.actor_id, role: command.role,
+                                                          as_of: caller.as_of, scope: caller.scope)
             else
               caller.role == command.role
             end

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

@@ -128,31 +128,39 @@ module Hecks
           unwrapped.to_s
         end
 
-        # A related record's OWN fields, reachable by name from `given`/
-        # `ensures` — `customer.status`, `account.customer.status` — without
+        # A COMMAND ARGUMENT's own related record, reachable by name from
+        # `given`/`ensures` — `disputed_by.status`, say, `CardPayment
+        # .Dispute`'s own fresh `Reference<Customer>` argument — without
         # teaching the pure expression evaluator anything about
         # repositories. The lookup happens HERE, once, before evaluation;
         # `Resolver#lookup` just digs into a plain Hash exactly as it
         # always has.
         #
-        # `owner` is either the declaring aggregate/entity (its OWN
-        # `reference_to`, read off `source` — the record's stored state)
-        # or the command itself (a reference-typed ARGUMENT, read off
-        # `source` — the dispatch payload). Same shape either way: every
-        # reference-typed attribute `owner` declares becomes a key in the
-        # result, named by stripping the attribute's own `_id` suffix
-        # (`customer_id` → `customer`) — a no-op for an aliased reference
-        # that already carries no suffix (`reference_to Account, as:
-        # :source` → `source`), which is why this needs no separate case
-        # for `as:`.
+        # `owner` NARROWED TO `command` ONLY (S12, ADR 0025 — "rules
+        # confined to their own aggregate boundary"): dereferencing the
+        # DECLARING aggregate/entity's own STORED `reference_to` used to
+        # be the other half of this method's job — a live query against
+        # another aggregate's own repository, every time a `given`/
+        # `ensures`/`invariant` ran. That half is gone; a cross-aggregate
+        # fact a rule needs now has to be a `projects`-maintained LOCAL
+        # field (`AggregateBuilder#projects_impl`'s own comment), already
+        # present in `subject`'s own state, no hydration needed. A
+        # reference-typed COMMAND ARGUMENT stays in bounds, though — the
+        # ADR's own boundary list names "its command arguments" as
+        # readable, and nothing is stored yet for a fresh argument to
+        # project from; resolving it once here, synchronous with THIS
+        # command's own admission, is a different shape from a live query
+        # against an ALREADY-PERSISTED reference. `enforce_givens`/
+        # `enforce_ensures` are this method's only two remaining callers,
+        # both passing `command`/`args`, never a `subject`'s own
+        # aggregate — verified before this comment was written, not
+        # assumed.
         #
-        # RECURSES into what it finds, so a chain like
-        # `account.customer.status` resolves in one pass: hydrating
-        # `account` also hydrates ITS OWN `customer_id` into a nested
-        # `customer` key. Depth-bounded rather than cycle-detected — nothing
-        # in this corpus dots more than two hops, and a bound is simpler
-        # than tracking visited (type, id) pairs for a cycle nothing here
-        # declares.
+        # RECURSES into what it finds, so a chain deeper than one hop
+        # still resolves in one pass. Depth-bounded rather than cycle-
+        # detected — nothing in this corpus dots more than two hops on a
+        # fresh argument, and a bound is simpler than tracking visited
+        # (type, id) pairs for a cycle nothing here declares.
         DEREFERENCE_DEPTH = 4
         private_constant :DEREFERENCE_DEPTH