hecks 0.3.0 → 1.0.0

data/lib/hecks/runtime/aggregate_lock.rb

@@ -0,0 +1,45 @@
+module Hecks
+  module Runtime
+    # A PROCESS-WIDE, STRIPED MUTEX REGISTRY — the concurrency-control
+    # mechanism for every adapter that does NOT declare
+    # `:optimistic_concurrency` (Heki, Memory today; see
+    # `CommandInterpreter#call`/`EntityInterpreter#call`, which choose
+    # between this and Postgres's CAS+retry purely off
+    # `repository.capabilities`).
+    #
+    # WHY A LOCK SUFFICES HERE AND CAS IS NOT NEEDED: both adapters hold
+    # process-local data. `Adapters::Memory.tenant_capable?`'s own comment
+    # states the confirmed fact this relies on — two `Runtime.boot` calls
+    # get two entirely separate adapter instances; there is never a SECOND
+    # PROCESS writing the same Heki file or the same Memory Hash, only
+    # possibly other THREADS within this one process. A `Mutex` held for
+    # the full hydrate-through-save critical section closes the identical
+    # lost-update gap CAS closes for Postgres, with no schema, no version
+    # column, and no retry loop — the second thread simply doesn't start
+    # its own hydrate until the first thread's save has landed.
+    #
+    # STRIPED, NOT ONE GLOBAL LOCK: keyed by `[domain, aggregate.hecks_name,
+    # id]`, so two dispatches against two DIFFERENT records never block
+    # each other. The registry Hash itself is guarded by its own top-level
+    # Mutex only for the moment a new per-key Mutex is created — two
+    # threads locking DIFFERENT keys for the first time never wait on one
+    # another beyond that brief creation window.
+    module AggregateLock
+      @registry_lock = Mutex.new
+      @locks = {}
+
+      class << self
+        # `AggregateLock.for(domain, aggregate, id).synchronize { ... }`
+        # `id: nil` — identity could not be resolved yet (see
+        # `Identity.best_effort`) — locks by aggregate TYPE alone, coarser
+        # (every record of this aggregate serializes against every other)
+        # but still correct: it can only ever make dispatch MORE
+        # conservative than a resolved id would.
+        def for(domain, aggregate, id = nil)
+          key = id.nil? ? [domain.to_s, aggregate.hecks_name] : [domain.to_s, aggregate.hecks_name, id.to_s]
+          @registry_lock.synchronize { @locks[key] ||= Mutex.new }
+        end
+      end
+    end
+  end
+end

data/lib/hecks/runtime/boot_gates.rb

@@ -0,0 +1,41 @@
+module Hecks
+  module Runtime
+    # A boot's own small set of phase-tagged, conditionally-present gates —
+    # ADR 0031. Registration is instance-scoped, ONE PER `Loader.boot`
+    # CALL, never a module-level singleton: a process that boots more than
+    # one registry in its lifetime (every spec suite does) must never let
+    # one boot's capability profile leak into the next boot's gate list.
+    #
+    # A gate is anything `.call(registry, directory)`-able — an existing
+    # module method handed over as a `Method` object (`EraCheck.method
+    # (:check_lineage!)`) needs no wrapper; a bare block does. Phases run
+    # in the order `run!` is called, gates within a phase in registration
+    # order — today exactly one gate per phase, so ordering among
+    # same-phase gates has never been exercised.
+    #
+    # This is deliberately NOT the same registry `Hecks::Projector` uses
+    # (ADR 0027) — that one is a process-wide, static IR-in/artifact-out
+    # registry with no bindings and no live-state mutation; this one is
+    # per-boot and gates real I/O (a Postgres mint, a saga-store read).
+    # Sharing a primitive between them is deferred until a third consumer
+    # actually wants it (0031's own Rejected Alternatives).
+    class BootGates
+      def initialize
+        @gates = Hash.new { |h, k| h[k] = [] }
+      end
+
+      def register(name, gate, phase:)
+        @gates[phase] << [name, gate]
+        self
+      end
+
+      def registered?(name)
+        @gates.values.flatten(1).any? { |registered_name, _gate| registered_name == name }
+      end
+
+      def run!(phase, registry, directory)
+        @gates[phase].each { |pair| pair.last.call(registry, directory) }
+      end
+    end
+  end
+end

data/lib/hecks/runtime/caller.rb

@@ -19,15 +19,31 @@ module Hecks
       # `CommandRules::Authorization` check a real Governance
       # `RoleAssignment` instead, once the command's domain has Governance
       # attached — see that module's own header for the full split.
-      Current = Struct.new(:role, :actor_id, keyword_init: true)
+      #
+      # `as_of` and `scope` are BOTH optional too, and both self-asserted
+      # by the caller rather than derived from the command — deliberately:
+      # `as_of` is filled at the door from `Ports::Clock.now`, never
+      # inside the interpreter (see `Ports::Clock`'s own header), so
+      # there is no other place to source it from. `scope` stays here
+      # rather than becoming a command-level DSL construct on purpose —
+      # a scope check that lived in the bluebook would put an
+      # authorization concern inside the domain declaration itself; this
+      # keeps it an application-boundary fact instead, the same shape
+      # `role`/`actor_id` already are. The tradeoff: a caller states what
+      # scope it is acting in, and `holds_role?` verifies a live grant
+      # exists for THAT scope — it does not independently confirm the
+      # scope matches whatever the command's own target data belongs to.
+      Current = Struct.new(:role, :actor_id, :as_of, :scope, keyword_init: true)
 
       module_function
 
       def current = Thread.current[:hecks_caller]
 
-      def as(role:, actor_id: nil)
+      def as(role:, actor_id: nil, as_of: nil, scope: nil)
         previous = Thread.current[:hecks_caller]
-        Thread.current[:hecks_caller] = Current.new(role: role.to_s, actor_id: actor_id&.to_s)
+        Thread.current[:hecks_caller] = Current.new(
+          role: role.to_s, actor_id: actor_id&.to_s, as_of: as_of, scope: scope&.to_s
+        )
         yield
       ensure
         Thread.current[:hecks_caller] = previous

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

@@ -19,8 +19,19 @@ module Hecks
         # the aggregate rather than describe it : `id`, whatever the aggregate is
         # identified by, and the reference key of the root a command reaches
         # through. Refusing those would refuse every dispatch there is.
-        def refuse_unknown_arguments(domain, aggregate, command, args)
-          addressing = [:id, *aggregate.identity_heads, reference_key(command)] + correlation_keys(domain)
+        #
+        # `extra_identity_heads:` — EntityInterpreter's own callers only. An
+        # entity dispatch addresses not just the root aggregate but every
+        # entity ALONG THE CHAIN it walks to reach the piece the command
+        # actually belongs to (`Handler.Dispatch.Bind` is two hops), and each
+        # hop's own `identity_heads` is addressing the same way the root's
+        # are — `element_of` (entity_element.rb) reads them straight out of
+        # `args` to find the element, never as a fact the command itself
+        # declares. `[]` for a plain aggregate/port-operation dispatch, which
+        # has no chain to add.
+        def refuse_unknown_arguments(domain, aggregate, command, args, extra_identity_heads: [])
+          addressing = [:id, *aggregate.identity_heads, *extra_identity_heads, reference_key(command)] +
+                       correlation_keys(domain)
           known      = (command.attributes.map(&:name) + addressing).compact.map(&:to_sym)
           # SORTED. Payload order is whatever the caller happened to write, and
           # refusal wording is contract — pinned byte-for-byte by the corpus, so

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

@@ -71,6 +71,18 @@ module Hecks
           # never through this method.
           when :delegate
             nil
+          # `corrects` — CommandBuilder#corrects_impl's own comment gives
+          # the full reasoning for storing it as a mutation at all. A REAL
+          # no-op here too: it targets no field on THIS instance either —
+          # its own event name, and whether THIS record has actually
+          # emitted it, is checked once, up front, by
+          # CommandRules::Admissibility#enforce_correction_target, not
+          # here. Whatever field this correction actually changes is an
+          # ORDINARY declared (or, for `reverses: true`, derived — see
+          # AggregateBuilder#seal_correction_targets) mutation of its own,
+          # applied by one of the branches above like any other.
+          when :corrects
+            nil
           else
             # Every declared op has a `when` above — this is not a real
             # runtime path today, only a backstop against the day one

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,6 +32,16 @@ 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
@@ -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,6 +131,12 @@ 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.
+          @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)
         }
@@ -219,6 +257,7 @@ 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
@@ -233,18 +272,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
@@ -321,7 +405,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)
@@ -355,7 +439,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
@@ -398,7 +482,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

@@ -118,9 +118,23 @@ module Hecks
         # nil for an aggregate command — CommandInterpreter never passes it.
         def enforce_givens(subject, command, args, domain:, declaring: nil, parent: nil)
           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
           command.givens.each do |given|
             next if Bluebook::Expression::Evaluator.call(given.canonical, state, attrs)
 
@@ -130,6 +144,32 @@ 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.
+        def enforce_correction_target(instance, aggregate, command, domain:)
+          command.mutations.each do |mutation|
+            next unless mutation.op == :corrects
+
+            event_key  = "#{domain}::#{aggregate.hecks_name}"
+            event_name = mutation.target.to_s
+            next if @registry.event_log.any? do |event|
+              event.name == event_name && event.aggregate == event_key && event.id == instance.id
+            end
+
+            raise NothingToCorrect,
+                  "#{command.hecks_name} refused — corrects #{event_name}, but " \
+                  "#{event_key} ##{instance.id} has never emitted it"
+          end
+        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,
@@ -177,13 +217,14 @@ module Hecks
         # field the command just took in to mutate it.
         def enforce_ensures(subject, command, args, old:, domain:, parent: nil)
           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.
+          attrs = args.merge(dereference(domain, command, args))
+          attrs = attrs.merge(parent: parent.state) if parent
           attrs = attrs.merge(old: old)
           command.ensures.each do |rule|
             next if Bluebook::Expression::Evaluator.call(rule.canonical, state, attrs)
@@ -197,16 +238,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 +295,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

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
 

data/lib/hecks/runtime/dependency_planning.rb

@@ -69,6 +69,20 @@ module Hecks
           @command = command
           @owner_fields = aggregate.attributes.to_set(&:name)
           @owner_fields << aggregate.lifecycle.field.to_sym if aggregate.lifecycle
+          # `projects` FIELDS (S12, ADR 0025) ARE OWNER STATE TOO — a
+          # `given`/`ensures` reading one (e.g. `customer_status ==
+          # "active"`) is reading this record's own stored field, same
+          # as any attribute, even though nothing here WRITES it via a
+          # declared mutation (`CommandInterpreter#seed_projected_fields`
+          # populates it outside this analysis entirely). Left out of
+          # `known_writes` deliberately: `add_preservation_reads` then
+          # correctly treats it as a prior-state read that must survive
+          # a partial mutation, which is exactly right — a projected
+          # field's freshness comes from the interpreter reseeding it on
+          # save, not from anything a caller-supplied write set carries.
+          if aggregate.respond_to?(:projected_fields)
+            aggregate.projected_fields.each { |field| @owner_fields << field.name }
+          end
           @payload_fields = command.attributes.to_set(&:name)
           @state_reads = Set.new
           @payload_reads = Set.new

data/lib/hecks/runtime/dispatcher.rb

@@ -256,15 +256,30 @@ module Hecks
       # is cleared for the reaction's own dispatch, so a triggering
       # caller's role can neither satisfy nor block a reaction command it
       # has nothing to do with (Runtime::Caller.without).
+      #
+      # `Thread.current[:hecks_reaction_depth]`, not a plain ivar — this
+      # `Dispatcher` instance is a single object shared by every thread
+      # dispatching through it (a Puma worker pool, say), so a plain ivar
+      # here is exactly the known Puma-concurrency bug class: two
+      # concurrent top-level dispatches on different threads would
+      # increment/decrement the SAME counter, letting one thread's nested
+      # reaction depth leak into another thread's unrelated dispatch. A
+      # `Mutex` is not the answer either — a reaction cascade re-enters
+      # `reenter` on the SAME thread (see `SagaInterpreter#advance_saga`'s
+      # own comment on why a non-reentrant `Mutex` can't guard this).
+      # `Thread.current`-backed, saved/restored around the call with a
+      # plain local + `ensure`, is the same idiom `Runtime::Caller`
+      # (`caller.rb`) already established for exactly this shape of
+      # per-thread ambient state.
       def reenter(verb, saga_correlation: nil, **args)
-        depth = @reaction_depth.to_i
-        @reaction_depth = depth + 1
+        depth = Thread.current[:hecks_reaction_depth].to_i
+        Thread.current[:hecks_reaction_depth] = depth + 1
         Caller.without { dispatch(verb, saga_correlation: saga_correlation, **args) }
       ensure
-        @reaction_depth = depth
+        Thread.current[:hecks_reaction_depth] = depth
       end
 
-      def reaction_depth_reached? = @reaction_depth.to_i >= MAX_REACTION_DEPTH
+      def reaction_depth_reached? = Thread.current[:hecks_reaction_depth].to_i >= MAX_REACTION_DEPTH
       def max_reaction_depth      = MAX_REACTION_DEPTH
 
       private