hecks 0.3.0 → 1.0.1

data/lib/hecks/runtime/dependency_planning.rb

@@ -62,13 +62,51 @@ module Hecks
       class Analyzer
         STATEFUL_MUTATIONS = %i[append increment decrement multiply clamp remove].freeze
 
-        def self.call(aggregate:, command:) = new(aggregate, command).call
-
-        def initialize(aggregate, command)
+        # `root_aggregate:` — Wave 8's own audit surfaced a real bug here,
+        # not merely a missing feature: for an ENTITY-owned command,
+        # `EntityInterpreter` calls this with `aggregate:` set to the
+        # ENTITY itself (`element_interpreter.rb`'s own `Analyzer.call
+        # (aggregate: entity, command:)`), so `owner_fields` was always
+        # the entity's own attribute set. A `given`/`ensures` reading
+        # `parent.X` legitimately means the ROOT aggregate's own field —
+        # a genuinely different owner — but `classify_path`'s `:parent`
+        # branch checked that read against `owner_fields` (the entity's),
+        # which can never contain a root-level field, so every entity
+        # command with a real, legitimate `parent.*` read was refused as
+        # unresolved regardless of correctness. Defaults to `aggregate`
+        # (a no-op) for the plain-aggregate case — `CommandInterpreter`'s
+        # own call site never needed to change.
+        def self.call(aggregate:, command:, root_aggregate: aggregate) = new(aggregate, command, root_aggregate).call
+
+        def initialize(aggregate, command, root_aggregate = aggregate)
           @aggregate = aggregate
           @command = command
           @owner_fields = aggregate.attributes.to_set(&:name)
           @owner_fields << aggregate.lifecycle.field.to_sym if aggregate.lifecycle
+          @root_owner_fields = root_aggregate.attributes.to_set(&:name)
+          @root_owner_fields << root_aggregate.lifecycle.field.to_sym if root_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.
+          # Applies to BOTH `owner_fields` and `root_owner_fields` — an
+          # entity's own `parent.*` read can name the root aggregate's
+          # projected field just as easily as one of its real attributes
+          # (`Banking::Withdrawal.Dispute`'s own `parent.account_customer_
+          # status`, ATMCard's projected field, is a real, live example).
+          if aggregate.respond_to?(:projected_fields)
+            aggregate.projected_fields.each { |field| @owner_fields << field.name }
+          end
+          if root_aggregate.respond_to?(:projected_fields)
+            root_aggregate.projected_fields.each { |field| @root_owner_fields << field.name }
+          end
           @payload_fields = command.attributes.to_set(&:name)
           @state_reads = Set.new
           @payload_reads = Set.new
@@ -101,7 +139,7 @@ module Hecks
 
         private
 
-        attr_reader :aggregate, :command, :owner_fields, :payload_fields,
+        attr_reader :aggregate, :command, :owner_fields, :root_owner_fields, :payload_fields,
                     :state_reads, :payload_reads, :writes, :known_writes, :unresolved
 
         # A fresh Instance supplies these values without reading a stored
@@ -190,13 +228,36 @@ module Hecks
           end
         end
 
+        # KNOWN, HARMLESS GAP: `corrects ..., as: :name`'s bound name
+        # (admissibility.rb's `enforce_correction_target`/`enforce_givens`/
+        # `enforce_ensures`) isn't special-cased here the way `:old`/
+        # `:parent` are — a given/ensures referencing it falls through to
+        # `unresolved` below (its own field lookup finds no owner/payload
+        # match), same net effect as any other not-yet-optimized command:
+        # `complete_state?` comes back false, so dispatch takes the safe
+        # `hydrate_existing` path instead of the `ATOMIC_PUT` fast path.
+        # Not a correctness bug — `as:`'s runtime binding (a plain `attrs`
+        # merge, exactly like `old:`'s) resolves and evaluates correctly
+        # regardless of what this STATIC analysis concludes — just a real,
+        # deliberately-left optimization gap: closing it would mean
+        # threading "which names this command declares as correction
+        # bindings" into the Analyzer, which doesn't have that per-command
+        # context today. Worth doing alongside `:old`/`:parent`'s own
+        # handling someday, not attempted here.
         def classify_path(path, phase)
           head, nested = path.split(".", 2)
           name = head.to_sym
 
           if name == :parent
             parent_field = nested.to_s.split(".", 2).first
-            if parent_field.empty? || !owner_fields.include?(parent_field.to_sym)
+            # `root_owner_fields` — NOT `owner_fields`. For an entity-owned
+            # command `owner_fields` is the ENTITY's own attribute set;
+            # `parent.X` always means the ROOT aggregate's own field, a
+            # genuinely different owner (`root_aggregate:`'s own header,
+            # above, has the full bug this fixes). Identical for a plain
+            # aggregate command, where root_aggregate defaults to aggregate
+            # itself and the two sets are the same set.
+            if parent_field.empty? || !root_owner_fields.include?(parent_field.to_sym)
               unresolved << "#{path} does not name parent aggregate state"
             else
               state_reads << parent_field.to_sym

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

data/lib/hecks/runtime/entity_interpreter.rb

@@ -10,11 +10,25 @@ require_relative "routing"
 require_relative "dependency_planning"
 require_relative "../ports/persistence/execution"
 require_relative "entity_element"
+require_relative "command_interpreter/argument_gate"
 
 module Hecks
   module Runtime
     class EntityInterpreter
       include Interpreting
+      # THE SAME PAYLOAD GATE aggregate commands and port operations already
+      # run — bug audit H1 (docs/audits/2026-08-10-main-bug-audit.md): this
+      # class used to run NEITHER refuse_unknown_arguments NOR
+      # refuse_absent_arguments, on a comment claiming "an entity inherits
+      # its aggregate's own gate." Nothing on the entity dispatch path ever
+      # ran one — confirmed live, `LedgerEntry.Reverse` accepted an
+      # unrecognized `bogus_arg:` outright, and dispatching it with no
+      # `narrative:` silently overwrote the stored narrative with `nil`
+      # (`sets :narrative`'s bare self-referential form reads `args[:narrative]`
+      # unconditionally). See `step_refuse_unknown_arguments`/
+      # `step_refuse_absent_arguments`, below, for how the shared gate is
+      # reused rather than reimplemented.
+      include CommandInterpreter::ArgumentGate
 
       attr_reader :registry
 
@@ -23,13 +37,17 @@ module Hecks
       # spec/vocabulary_conformance_spec.rb the same way CommandInterpreter's
       # own DISPATCH_ORDER is; see that constant's doc comment for why this is
       # hand-typed rather than read live off the meta-domain at every dispatch.
-      # Shorter than the aggregate order for the same reasons the declaration
-      # itself gives : no refuse_unknown_arguments/refuse_absent_arguments (an
-      # entity inherits its aggregate's own gate) and no
-      # assign_creation_attributes (an entity is never created through this
+      # `refuse_unknown_arguments`/`refuse_absent_arguments` now lead it, same
+      # position `AggregateDispatchOrder` holds them at (H1, above) — the only
+      # remaining difference from the aggregate order is no
+      # `assign_creation_attributes` (an entity is never created through this
       # path).
       DISPATCH_ORDER = Hecks::Vocabulary.symbols("EntityDispatchOrder")
 
+      # Same safety valve as `CommandInterpreter::MAX_STALE_WRITE_RETRIES` —
+      # see that constant's own comment.
+      MAX_STALE_WRITE_RETRIES = 5
+
       # `instance` is the PARENT aggregate record (what gets saved and
       # returned) ; `element`/`view` are the entity piece itself — `view`
       # wraps `element` as it stood at `locate_element`, pre-mutation, and
@@ -56,6 +74,10 @@ module Hecks
       # comment for the shared reasoning (Dispatcher#dry_run?'s own entry
       # point). `step_save`/`step_emit` are the only two steps here that
       # read it either.
+      # RETRIES THE WHOLE METHOD BODY on `StaleWrite` — same reasoning as
+      # `CommandInterpreter#call`'s own retry: a fresh `ctx`, a fresh
+      # `step_hydrate_parent`/`step_locate_element` re-reading current
+      # state.
       def call(domain, aggregate, dotted, legacy_args, route: nil, with: nil, dry_run: false)
         *entity_names, command_name = dotted.to_s.split(".")
         if entity_names.empty?
@@ -70,13 +92,31 @@ module Hecks
                                                            entity: entity.hecks_name, command: command_name.inspect))
 
         args = Routing.payload(command, with: with, legacy: legacy_args)
-        ctx = Context.new(domain, aggregate, entity, entity_names.join("."), command, command_name, args)
-        ctx.chain = chain
-        ctx.route = route
-        ctx.dry_run = dry_run
-        ctx.plan = DependencyPlanning::Analyzer.call(aggregate: entity, 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, entity, entity_names.join("."), command, command_name, args)
+          ctx.chain = chain
+          ctx.route = route
+          ctx.dry_run = dry_run
+          # `root_aggregate:` — `entity` is the immediate owner (what
+          # `owner_fields` inside the Analyzer means), but a `parent.X`
+          # read inside this command's own given/ensures means the ROOT
+          # aggregate's own field, not the entity's — `aggregate` here IS
+          # that root (this method's own first parameter, never the
+          # entity). See DependencyPlanning::Analyzer.call's own header
+          # for the bug this closes.
+          ctx.plan = DependencyPlanning::Analyzer.call(aggregate: entity, command: command, root_aggregate: aggregate)
+          # RESOLVED HERE, ONCE — see CommandInterpreter#call's own comment;
+          # `step_hydrate_parent` reads `ctx.repository` without re-fetching.
+          ctx.repository = @registry.repository(domain, aggregate)
+          lock_id = Identity.best_effort(aggregate, args, route)
+          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
@@ -100,6 +140,31 @@ module Hecks
         end
       end
 
+      # `extra_identity_heads:` — every entity `ctx.chain` walks through, not
+      # just the root aggregate `ArgumentGate` already knows about. A
+      # two-hop dispatch (`Handler.Dispatch.Bind`) is addressed by BOTH
+      # hops' own identity, each read straight out of `args` by
+      # `EntityElement#element_of` — refusing those as unknown would refuse
+      # every legitimate nested-entity dispatch there is, the same reasoning
+      # `ArgumentGate#refuse_unknown_arguments`'s own header gives for `:id`/
+      # the root's `identity_heads`.
+      def step_refuse_unknown_arguments(ctx)
+        step(:refuse_unknown_arguments) {
+          refuse_unknown_arguments(ctx.domain, ctx.aggregate, ctx.command, ctx.args,
+                                   extra_identity_heads: ctx.chain.flat_map(&:identity_heads))
+        }
+      end
+
+      # No `aggregate:` exemption to pass — that kwarg exists only for a
+      # port operation's own self-address (`ArgumentGate#refuse_absent_
+      # arguments`'s own comment); an entity command's chain identity never
+      # reaches `command.attributes` in the first place (resolved as
+      # addressing above, not as a declared fact), so there is nothing here
+      # for the exemption to need to strip.
+      def step_refuse_absent_arguments(ctx)
+        step(:refuse_absent_arguments) { refuse_absent_arguments(ctx.command, ctx.args) }
+      end
+
       def step_normalize_args(ctx)
         ctx.args = step(:normalize_args) { normalize_args(ctx.aggregate, ctx.command, ctx.args) }
       end
@@ -113,7 +178,8 @@ module Hecks
       end
 
       def step_hydrate_parent(ctx)
-        ctx.repository = @registry.repository(ctx.domain, ctx.aggregate)
+        # `ctx.repository` is resolved once, in `#call`, before the
+        # isolation decision — not here any more.
         ctx.instance = step(:hydrate_parent) {
           parent(ctx.repository, ctx.aggregate, ctx.entity_name, ctx.command_name, ctx.args, ctx.route)
         }
@@ -184,8 +250,20 @@ module Hecks
 
         step(:save) do
           @rules.resolve_state_references(ctx.domain, ctx.aggregate, ctx.instance.state)
-          ctx.repository.save(ctx.instance)
-          ctx.persistence_outcome = Ports::Persistence::Outcome.new(status: :saved, instance: ctx.instance)
+          # `expected_version:` — see CommandInterpreter#step_save's own
+          # comment: nil for a repository that isn't CAS-capable, or an
+          # instance never read from storage, either of which falls
+          # through to a plain save inside `AppendOnly#save`.
+          ctx.persistence_outcome = ctx.repository.save(ctx.instance, expected_version: ctx.instance.version)
+          if ctx.persistence_outcome.status == :stale
+            # NOT a `RefusalWording.render` call — see
+            # `CommandInterpreter#step_save`'s identical branch and
+            # `Runtime::StaleWrite`'s own comment.
+            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
 

data/lib/hecks/runtime/errors.rb

@@ -51,6 +51,28 @@ module Hecks
     # itself, not whether the caller actually holds `policy`. See
     # Runtime::TenantScope.
     class Unauthorized < StandardError; end
+    # `corrects` names a past event this record must have already emitted
+    # (CommandBuilder#corrects_impl's own comment) — a fact the expression
+    # evaluator cannot check (it is not a predicate over the record's OWN
+    # fields, it is "did this exact record ever announce this"), so it is
+    # raised structurally, the same way AlreadyExists/NotFound are, rather
+    # than being expressible as an ordinary `given`. Raised by
+    # `CommandRules::Admissibility#enforce_correction_target`.
+    class NothingToCorrect < StandardError; end
+
+    # A RUNTIME FAULT, NOT A DOMAIN REFUSAL — deliberately absent from
+    # `DOMAIN_REFUSALS` below and from `vocabulary.bluebook`'s own
+    # `DomainRefusal` list. Raised when an optimistic-concurrency CAS write
+    # (`AppendOnly#save`'s `expected_version:`) finds the stored version has
+    # moved since this instance was read — someone else's write committed
+    # in between. `CommandInterpreter#call`/`EntityInterpreter#call` catch
+    # this themselves and retry the whole dispatch from a fresh hydrate, so
+    # `enforce_givens` re-evaluates against the now-current state; a caller
+    # only ever sees this escape when every retry is exhausted under
+    # sustained contention — an operational condition (many concurrent
+    # writers hammering one aggregate), not a business rule a domain author
+    # declared. See docs/decisions/ (concurrency-control ADR).
+    class StaleWrite < StandardError; end
 
     # A Lambda-routed domain's own refusal (rust/host, `Runtime::
     # RemoteDispatcher`), carrying Rust's own refusal text verbatim —

data/lib/hecks/runtime/identity.rb

@@ -23,6 +23,15 @@ module Hecks
     module Identity
       module_function
 
+      # A hash read that decides which spelling of a key answers by
+      # PRESENCE, never by `||` — a bare `||` treats a genuinely-held
+      # `false` the same as an absent key and falls through to the other
+      # spelling, landing on `nil` instead of the real, stored answer.
+      def hash_lookup(hash, key)
+        sym = key.to_sym
+        hash.key?(sym) ? hash[sym] : hash[key]
+      end
+
       # The head names the ATTRIBUTE and is consumed by whoever looked the value
       # up; what is left is the walk down into it. A path with no fields to walk
       # — an aggregate that declares no identity and falls back to `id` — hands
@@ -32,7 +41,7 @@ module Hecks
         return held if fields.empty?
 
         fields.reduce(Value.materialize(held)) do |dug, field|
-          dug.is_a?(Hash) ? (dug[field.to_sym] || dug[field]) : nil
+          dug.is_a?(Hash) ? hash_lookup(dug, field) : nil
         end
       end
 
@@ -83,7 +92,7 @@ module Hecks
           # arrived whole has to be opened.
           return held.to_s unless held.is_a?(Hash)
 
-          return rest.reduce(held) { |h, f| h.is_a?(Hash) ? (h[f.to_sym] || h[f]) : nil }&.to_s
+          return rest.reduce(held) { |h, f| h.is_a?(Hash) ? hash_lookup(h, f) : nil }&.to_s
         end
 
         # Coerced against the identity ATTRIBUTE only when the caller actually
@@ -123,6 +132,25 @@ module Hecks
       def reading(construct)
         construct.identity_paths.join(", ")
       end
+
+      # BEST-EFFORT, FOR A LOCK KEY ONLY — `Runtime::AggregateLock`'s own
+      # per-record striping needs SOME id to key on before dispatch has run
+      # far enough to hydrate for real, so this walks the identical chain
+      # `CommandInterpreter#hydrate_existing`/`#hydrate_prior_or_initial`
+      # and `EntityInterpreter#parent` already use to locate the real
+      # record — but wrapped to never raise. Choosing which Mutex to hold
+      # must never itself become a crash. `nil` means "could not resolve
+      # from the raw, pre-normalized payload this runs against" — the
+      # caller locks by aggregate type alone in that case (coarser, still
+      # correct, just less concurrent).
+      def best_effort(construct, args, route = nil, reference_key: nil)
+        route&.aggregate ||
+          of(construct, args) ||
+          from(construct, args, :id) ||
+          (reference_key && from(construct, args, reference_key))
+      rescue StandardError
+        nil
+      end
     end
   end
 end

data/lib/hecks/runtime/instance.rb

@@ -1,16 +1,34 @@
 require_relative "value"
+require_relative "identity"
 
 module Hecks
   module Runtime
     class Instance
       attr_reader :aggregate, :id
       attr_accessor :state
-
-      def initialize(aggregate:, id:, state: nil)
+      # OUT-OF-BAND ADAPTER BOOKKEEPING, NOT DOMAIN STATE — the optimistic-
+      # concurrency version a CAS-capable adapter (Postgres today) stamps
+      # on a record it reads/writes, so a later `save` can assert "commit
+      # only if nobody has written since". Deliberately absent from
+      # `to_h`/`[]`/`[]=`/`method_missing` : a domain author never declares
+      # this, a `given`/`ensures`/`invariant` can never read it, and no
+      # adapter that doesn't understand it (Memory, Heki) ever sets it —
+      # `nil` there just means "no CAS attempted", which is exactly what a
+      # plain `save` already does. See docs/decisions/ (concurrency-control
+      # ADR) for the full mechanism.
+      attr_accessor :version
+
+      # `args:` — THE ORIGINAL COMMAND PAYLOAD, offered only by a fresh
+      # creation (`CommandInterpreter#hydrate_legacy_creation`/
+      # `#hydrate_complete_state`/`#hydrate_prior_or_initial`, each already
+      # holding it when they mint a brand-new record). See
+      # `materialize_identity!` for why a composite identity needs it.
+      def initialize(aggregate:, id:, state: nil, args: nil)
         @aggregate = aggregate
         @id        = id
         @state     = state ? self.class.hydrate_with_defaults(aggregate, state) : self.class.defaults(aggregate)
-        materialize_identity!
+        @version   = nil
+        materialize_identity!(args)
       end
 
       # Loading existing state runs the same default-fill a fresh instance
@@ -103,7 +121,29 @@ module Hecks
 
       private
 
-      def materialize_identity!
+      # M17 — a COMPOSITE identity (`identity_heads.size > 1`, e.g.
+      # `identified_by :branch_code, :box_number`) has no single
+      # `identified_by` to fall back to `:id` for — `@aggregate.identified_by`
+      # is nil the moment there is more than one head (`Behaviour::Identified
+      # #derive_identity`), so the single-head branch below never runs for
+      # it at all. A creating command that declares those heads as ordinary
+      # attributes but doesn't ALSO `sets` them (redundant with the identity
+      # the command's own args already named) used to persist every head as
+      # nil — the id correctly named the record, but the record's own
+      # attributes forgot what named it.
+      #
+      # Filled from `args`, never from splitting `@id` back apart — the
+      # same reason the single-head branch below won't guess a multi-path
+      # identifier from its joined string: `@id` is a display key, not a
+      # reversible serialization, and a composite's own separator can
+      # collide with a part's own text. `args` is only offered by a FRESH
+      # creation (`Instance.new`'s own `args:` comment); an existing record
+      # read back from storage has no args to lean on, and doesn't need
+      # one since a correctly-persisted record already carries its own
+      # heads.
+      def materialize_identity!(args = nil)
+        return materialize_composite_identity!(args) if @aggregate.identity_heads.size > 1
+
         identity  = @aggregate.identified_by || :id
         attribute = @aggregate.attribute(identity)
         return unless attribute && @state[identity].nil?
@@ -115,6 +155,21 @@ module Hecks
 
         @state[identity] = Value.from_identifier(@aggregate, attribute, @id)
       end
+
+      def materialize_composite_identity!(args)
+        return unless args
+
+        @aggregate.identity_paths.each do |path|
+          head = path.to_s.split(".").first.to_sym
+          attribute = @aggregate.attribute(head)
+          next unless attribute && @state[head].nil?
+
+          raw = Identity.from(@aggregate, args, path, value_owner: @aggregate)
+          next if raw.nil?
+
+          @state[head] = Value.from_identifier(@aggregate, attribute, raw)
+        end
+      end
     end
   end
 end

data/lib/hecks/runtime/interpreting.rb

@@ -1,4 +1,5 @@
 require_relative "value"
+require_relative "aggregate_lock"
 
 module Hecks
   module Runtime
@@ -43,6 +44,26 @@ module Hecks
         order.each { |name| send(:"step_#{name}", ctx) }
       end
 
+      # THE CONCURRENCY-CONTROL SPLIT — see docs/decisions/ (concurrency
+      # control ADR) for the full mechanism. A repository that declares
+      # `:optimistic_concurrency` (Postgres today) already closes the
+      # lost-update gap itself, via `step_save`'s CAS + `#call`'s own
+      # `StaleWrite` retry loop — an extra in-process lock here would be
+      # pointless overhead, not incorrect, so it's skipped for clarity.
+      # Every other repository (Heki, Memory — confirmed process-local
+      # data, never a second process writing the same store) gets a
+      # striped `Mutex` held for the WHOLE dispatch-order run, so a second
+      # thread's own hydrate can't start until the first thread's save has
+      # landed. `lock_key_id` is best-effort (`Identity.best_effort`) —
+      # `nil` still locks correctly, just coarser (by aggregate type).
+      def run_dispatch_order_with_isolation(order, ctx, lock_key_id:)
+        if ctx.repository.capabilities.include?(:optimistic_concurrency)
+          run_dispatch_order(order, ctx)
+        else
+          AggregateLock.for(ctx.domain, ctx.aggregate, lock_key_id).synchronize { run_dispatch_order(order, ctx) }
+        end
+      end
+
       # Every declared attribute present in the payload passes the reference
       # gate, then coercion — the same walk whether the command acts on an
       # aggregate or on one of its entity's elements.

data/lib/hecks/runtime/loader.rb

@@ -1,8 +1,9 @@
 require_relative "../facade/surface"
 require_relative "../ports/loading"
+require_relative "../ports/persistence"
 require_relative "dispatcher"
 require_relative "remote_dispatcher"
-require_relative "era_check"
+require_relative "boot_gates"
 require_relative "registry"
 
 module Hecks
@@ -42,20 +43,7 @@ module Hecks
           loading.load_domain(directory, environment: environment)
         end
 
-        # The era gate runs BEFORE verify! builds repositories: minting an
-        # era (Postgres) must have created its partition and head views
-        # before any adapter opens them, and a refused era must refuse
-        # before any adapter touches data.
-        EraCheck.check!(registry, directory)
-        registry.verify!
-        # AFTER verify! (conservative — any wiring error surfaces first,
-        # not strictly required since resolution only needs the
-        # hecksagon binds, already loaded), BEFORE the dispatcher is
-        # built — repopulates `saga_instances` from whatever durable
-        # store each domain's own adapter answers with (§2-§4), so a
-        # process manager mid-flight at the last shutdown/crash/cold-
-        # start doesn't start this boot looking like it never began.
-        registry.rehydrate_sagas!
+        run_boot_gates!(registry, directory)
         dispatcher = dispatcher_for(registry)
         install_facade ? bind_runtime(dispatcher) : dispatcher
       end
@@ -95,13 +83,66 @@ module Hecks
           loading.load_selected(files, environment: environment)
         end
 
-        EraCheck.check!(registry, directory)
-        registry.verify!
-        registry.rehydrate_sagas!
+        run_boot_gates!(registry, directory)
         dispatcher = dispatcher_for(registry)
         install_facade ? bind_runtime(dispatcher) : dispatcher
       end
 
+      # ADR 0031 — replaces two previously-hardcoded, unconditional calls
+      # with a per-boot `BootGates` instance holding exactly the gates THIS
+      # registry's own bound adapters have a capability for. Ordering is
+      # preserved: era-checking (when a persistence plugin contributes one)
+      # still runs before `verify!`, saga rehydration still runs after
+      # (conservative — see `SagaPersistence#rehydrate_sagas!`'s own
+      # comment).
+      #
+      # ADR 0033 — this loader no longer names `EraCheck`, or any other
+      # era-specific class, at all. Every LOADED persistence plugin
+      # (`Ports::Persistence.each_plugin` — nothing here if nothing was
+      # ever `require`d) is asked to contribute its own `:pre_verify`/
+      # `:post_verify` gates generically; `:saga_rehydration` is the one
+      # gate core still registers directly, because ADR 0031 already
+      # proved it's not era-specific.
+      def self.run_boot_gates!(registry, directory)
+        gates = BootGates.new
+        Ports::Persistence.each_plugin { |plugin| plugin.contribute_boot_gates(registry, gates) }
+        check_compute_rules_backstop!(registry)
+
+        gates.run!(:pre_verify, registry, directory)
+        registry.verify!
+
+        gates.register(:saga_rehydration, ->(reg, _dir) { reg.rehydrate_sagas! }, phase: :post_verify) if
+          registry.hecksagons.each_key.any? { |domain| registry.saga_persistence(domain) != Ports::Persistence::NULL_SAGA_STORE }
+        gates.run!(:post_verify, registry, directory)
+        gates
+      end
+
+      # The one piece of the old, era-owned `check_compute_rules!` core
+      # still carries — deliberately thinner. `registry.translations` is
+      # plain `Bluebook::Translation`/`TranslationAggregate`/
+      # `TranslationCompute`/`TranslationRekey` data (`bluebook/
+      # translation.rb`, core, no era-specific class involved), so this
+      # needs nothing plugin-specific to ask "does anything declare a
+      # compute/rekey rule at all." A LOADED persistence plugin (e.g. the
+      # era plugin's own `:era_compute_rules` gate, registered above) runs
+      # the real, adapter-aware version of this check and refuses by name
+      # ("...is bound to Memory") long before this ever would; this only
+      # fires when nothing did, because nothing was loaded to.
+      def self.check_compute_rules_backstop!(registry)
+        return if Ports::Persistence.plugins_loaded?
+
+        registry.translations.each do |translation|
+          translation.aggregates.each do |aggregate|
+            next if aggregate.computes.empty? && aggregate.rekeys.empty?
+
+            raise WiringError,
+                  "cannot boot #{translation.domain}::#{aggregate.name}: a compute/rekey rule is declared, but no " \
+                  "persistence plugin that can interpret it is loaded (e.g. require " \
+                  "\"hecks/ports/persistence/plugins/era\")"
+          end
+        end
+      end
+
       # `RemoteDispatcher` for a domain routed through Lambda,
       # `Dispatcher` otherwise — the ONE place this decision gets
       # made, so everything built on top (`Handle`, `AggregateDoor`,