hecks 0.2.0 → 1.0.0

data/lib/hecks/runtime/registry/saga_persistence.rb

@@ -0,0 +1,142 @@
+require_relative "../saga_pending_dispatch"
+
+module Hecks
+  module Runtime
+    class Registry
+      # SAGA PERSISTENCE — no new DSL verb, no new world setting.
+      # Whatever adapter a domain's own aggregates already use for
+      # durability, its sagas use the same one, automatically: three
+      # OPTIONAL adapter methods (`save_saga`/`delete_saga`/`each_saga`),
+      # `respond_to?`-checked the same way `Ports::Persistence::AppendOnly`
+      # already treats an adapter's own optional methods
+      # (`find`/`all`/`count`/`reset!`/`events`/`record_event`).
+      module SagaPersistence
+        # Resolved and memoized per domain — the FIRST real aggregate
+        # declared in the domain's own bluebook is the resolution
+        # anchor. `Ports::Persistence::BindingPolicy.resolve` for that
+        # aggregate already falls back to a domain-level default bind
+        # (§0's `Hecksagon#bind_for`) before falling back to Memory, so
+        # this needs no separate "was a default declared" branch of its
+        # own — whatever adapter that anchor resolves to already IS the
+        # domain's own default in the normal case (every aggregate
+        # shares one adapter), and is the honest, documented fallback
+        # for the rarer domain genuinely split across more than one
+        # local adapter with no default declared.
+        #
+        # GENUINELY LAZY, GENUINELY POST-BOOT — unlike `rehydrate_sagas!`
+        # below (boot-only), this is called from live dispatch
+        # (`SagaInterpreter#checkpoint`/`#end_saga`, on every saga
+        # transition), so the FIRST call for a given domain can come from
+        # any dispatching thread, not just the boot thread. `@saga_persistence`
+        # itself is a plain Hash stood up once in `Registry#initialize` (no
+        # race on the container), but `resolve_saga_persistence` is real work
+        # (a `BindingPolicy.resolve` plus a lazy `repository` build) whose
+        # RESULT — the actual adapter instance a domain's sagas persist
+        # through — must be the SAME object for every caller: two threads
+        # racing the first lookup and each building their own adapter would
+        # silently split one domain's saga writes across two adapter
+        # instances (worse than `Dispatcher#reaction_depth`'s M20 — that bug
+        # corrupted a counter; this one can corrupt WHICH STORE a saga's
+        # state lands in). Double-checked locking against a DEDICATED mutex
+        # — never `@saga_mutex` — see `Registry#initialize`'s own comment for
+        # why reusing that one would deadlock.
+        def saga_persistence(domain)
+          key = domain.to_s
+          @saga_persistence[key] || @saga_persistence_mutex.synchronize { @saga_persistence[key] ||= resolve_saga_persistence(key) }
+        end
+
+        # WALKS EVERY LOADED DOMAIN, repopulating `saga_instances` from
+        # whatever `saga_persistence(domain)` resolves to — a real store
+        # for a domain whose adapter answers the capability, `each_saga`
+        # yielding real rows; `NULL_SAGA_STORE`'s own `each_saga` for
+        # everything else, which never yields at all, so this needs no
+        # `respond_to?` branch of its own — the SAME reason every other
+        # call site in this capability never needs one. Called once at
+        # boot (`Loader.boot`, between `verify!` and dispatcher
+        # construction) — a process that's been running has no reason to
+        # re-walk its own already-current `saga_instances`.
+        #
+        # BOOT-TIME-ONLY (OR ITS TEST-RUNNER EQUIVALENT) — this method's
+        # only callers are `Loader.run_boot_gates!` (single-threaded, before
+        # `dispatcher_for` ever exists) and `Registry#reset_runtime_state!`
+        # (single-threaded test runner — see that method's own comment).
+        # Never called from live dispatch, so `@saga_instances` mutation
+        # here has no concurrent caller to race, unlike its OTHER two write
+        # points inside `@saga_mutex.synchronize` blocks (`saga_interpreter.
+        # rb`), which genuinely do and are guarded accordingly.
+        # rubocop:disable-next Hecks/ThreadSharedIvarMutation
+        def rehydrate_sagas!
+          @hecksagons.each_key do |domain|
+            saga_persistence(domain).each_saga do |process_manager, correlation, state, memory, completed_compensations = []|
+              pending = memory.delete(SAGA_PENDING_DISPATCH_KEY)
+              @saga_instances[process_manager][correlation] =
+                { state: state, memory: memory, completed_compensations: completed_compensations || [] }
+              warn_stalled_saga(domain, process_manager, correlation, state, pending) if pending
+            end
+          end
+          self
+        end
+
+        private
+
+        # THE OTHER HALF OF THE OUTBOX-SHAPED FIX (see saga_pending_
+        # dispatch.rb) — `SAGA_PENDING_DISPATCH_KEY`, if the crashed
+        # process left it standing, means the row's own `state` was
+        # checkpointed but the dispatch cascade that justifies it may
+        # never have run. Stripped out of `memory` before it becomes
+        # this instance's LIVE `:memory` (so nothing downstream — a
+        # `given`, a `with:` mapping, the fuzzer — ever sees it), and
+        # surfaced loudly instead: a WARNING plus a `saga_log` entry,
+        # never an automatic redrive (see saga_pending_dispatch.rb for
+        # why redriving without idempotent delivery would be worse than
+        # the stall). This is real, durable crash-recovery VISIBILITY —
+        # still not the reconciliation itself, which stays a human's
+        # call until hecks has idempotent redelivery to make it safe.
+        # rubocop:disable-next Hecks/ThreadSharedIvarMutation -- same
+        # justification as `rehydrate_sagas!`'s own disable comment
+        # above: this method's ONLY caller is that boot-time-only walk,
+        # never live dispatch, so `@saga_log` has no concurrent writer
+        # to race here.
+        def warn_stalled_saga(domain, process_manager, correlation, state, pending)
+          # `.transform_keys(&:to_sym)` — Heki's own `each_saga` only
+          # symbolizes `memory`'s TOP-level keys (`SagaStore#each_saga`'s
+          # own `transform_keys`, one level deep); a value NESTED under
+          # one of those keys, like this marker, comes back with plain
+          # string keys from Heki specifically, symbol keys already from
+          # Postgres/SQLite/D1's own `symbolize_names: true` parse. Normalizing
+          # here, once, is simpler than teaching every adapter's own
+          # shallow/deep parsing convention about this one reserved key.
+          pending    = pending.transform_keys(&:to_sym)
+          dispatches = Array(pending[:dispatches]).join(", ")
+          warn "[hecks] #{domain} rehydrated #{process_manager} instance #{correlation.inspect} in state " \
+               "#{state.inspect} with a dispatch left pending from before the last crash/restart — " \
+               "#{dispatches} (on #{pending[:on].inspect}, #{pending[:from].inspect} -> #{pending[:to].inspect}) " \
+               "may or may not have actually run. hecks does not auto-redrive a pending saga dispatch (that " \
+               "needs idempotent delivery, which this pipeline doesn't have yet); reconcile this instance by hand."
+          @saga_log << { process_manager: process_manager, instance: correlation, rehydrated_stalled: true,
+                         state: state, pending: pending }
+        end
+
+        def resolve_saga_persistence(domain)
+          anchor = hecksagon(domain) && bluebook(domain)&.aggregates&.first
+          return Ports::Persistence::NULL_SAGA_STORE unless anchor
+
+          bind = Ports::Persistence::BindingPolicy.resolve(self, domain, anchor)
+          return Ports::Persistence::NULL_SAGA_STORE if adapter_class(bind.adapter) <= Ports::Persistence::RemoteRuntime
+
+          adapter = repository(domain, anchor).adapter
+          adapter.respond_to?(:save_saga) ? adapter : Ports::Persistence::NULL_SAGA_STORE
+        rescue WiringError
+          # A domain not cleanly wired for its own anchor aggregate's
+          # persistence (a test fixture binding only the aggregates it
+          # exercises, say) degrades saga persistence to the same no-op
+          # default an unbound domain gets — never raises out of a
+          # dispatch that would otherwise have succeeded. Matches this
+          # capability's own framing throughout: automatic wherever it's
+          # cleanly supported, silently absent wherever it isn't.
+          Ports::Persistence::NULL_SAGA_STORE
+        end
+      end
+    end
+  end
+end

data/lib/hecks/runtime/registry/verification.rb

@@ -0,0 +1,246 @@
+require_relative "../../bluebook/hexagon"
+
+module Hecks
+  module Runtime
+    class Registry
+      # The wiring gate: every bind names a declared aggregate, every
+      # adapter satisfies the verb its port declares, every world setting is
+      # a field the adapter admits, and the default adapter is usable at
+      # all. Included into Registry — `verify!` is what a boot calls after
+      # loading, and the smaller checks are also called piecemeal by the
+      # repository factory.
+      module Verification
+        def verify!
+          verify_default_adapter!
+          verify_singleton_port_answers!
+
+          @hecksagons.each_value do |hexagon|
+            refuse_ungoverned_roles!(hexagon)
+
+            hexagon.binds.each do |bind|
+              # A domain-level default (§0) — `persisted_by "Heki"` bare,
+              # applying to whichever aggregates don't override it — names
+              # no aggregate of its own, so there's nothing to look up in
+              # the bluebook for THIS row specifically. Still validate its
+              # own adapter/verb shape (the same reason
+              # `verify_default_adapter!` checks the framework-wide
+              # default the same way, aggregate-less). Coverage of real
+              # aggregates that only resolve THROUGH this default comes
+              # from their own dispatch-time `BindingPolicy.resolve` —
+              # deliberately not required to be exhaustive here, the same
+              # leniency this method already extended to any aggregate
+              # left out of an explicit bind list entirely (real test
+              # fixtures bind only the aggregates they exercise).
+              if bind.aggregate.nil?
+                check_verb(bind)
+                next
+              end
+
+              aggregate = bluebook(hexagon.domain)&.aggregate(bind.aggregate_name)
+              raise WiringError, "#{bind.aggregate} is bound but not declared in the bluebook" unless aggregate
+
+              check_verb(bind)
+
+              repository(hexagon.domain, aggregate)
+            end
+
+            warn_undurable_sagas!(hexagon)
+          end
+          self
+        end
+
+        def verify_default_adapter!
+          name = Ports::Persistence::DEFAULT_ADAPTER
+
+          check_verb(
+            Bluebook::Bind.new(
+              aggregate: "(default)",
+              verb:      Ports::Persistence::VERB,
+              adapter:   name
+            )
+          )
+          adapter_class(name)
+          self
+        rescue WiringError => error
+          raise WiringError,
+                "the default persistence adapter (#{name}) is not usable, so an " \
+                "aggregate with no bind could not be given one: #{error.message}"
+        end
+
+        def check_verb(bind)
+          port = port_for(bind)
+          check_answers(port, bind.adapter)
+          return if port.verb.to_s == bind.verb.to_s
+
+          raise WiringError,
+                "#{bind.adapter} implements the #{port.name} port (verb #{port.verb}) " \
+                "and cannot satisfy #{bind.verb}"
+        end
+
+        # THE METHOD CONTRACT A `.port` FILE'S `verb`/`signal` NEVER
+        # CARRIED — an adapter can name the right port, satisfy the right
+        # verb, and admit every `.world` setting `check_settings` checks,
+        # and still be missing the one method a live dispatch will
+        # actually call. `answers` is optional per port (an empty list is
+        # today's pre-existing behavior, unchecked), so this only ever
+        # tightens a port that opted in.
+        def check_answers(port, adapter_name)
+          answers = Array(port.answers)
+          return if answers.empty?
+
+          klass   = adapter_class(adapter_name)
+          missing = answers.reject { |method_name| klass.respond_to?(method_name) }
+          return if missing.empty?
+
+          raise WiringError,
+                "#{adapter_name} declares the #{port.name} port but does not respond to " \
+                "#{missing.map(&:inspect).join(', ')} — #{port.name}.port declares answers " \
+                "#{answers.map(&:inspect).join(', ')}"
+        end
+
+        # THE NINE SINGLETON PORTS' OWN GAP — `persistence`, `projection`
+        # and `loading` are per-aggregate bindings, checked above through
+        # every real `bind` a hexagon declares; a singleton port
+        # (`clock`, `authorization`, …) is never bound to an aggregate at
+        # all, so nothing above ever resolves one and nothing above ever
+        # ran `check_answers` against it. Each one's own `Ports::*.adapter`
+        # already refuses zero or multiple implementations, live, at
+        # first dispatch — that stays exactly as-is here (0 or 2+ is
+        # ambiguity, not a method-contract question, and asserting every
+        # declared port MUST have exactly one adapter would wrongly
+        # refuse a boot that simply never wires a port it doesn't use).
+        # This only ever tightens the ONE case those checks don't cover:
+        # exactly one adapter, wired, missing a method `answers` names.
+        PER_AGGREGATE_PORTS = %w[persistence projection loading].freeze
+
+        def verify_singleton_port_answers!
+          @ports.each_value do |port|
+            next if PER_AGGREGATE_PORTS.include?(port.name)
+            next if Array(port.answers).empty?
+
+            implementations = @adapters.values.select { |a| a.port == port.name }
+            next unless implementations.size == 1
+
+            check_answers(port, implementations.first.name)
+          end
+          self
+        end
+
+        def check_settings(bind, settings)
+          adapter = @adapters[bind.adapter]
+          return unless adapter
+
+          declared = settings.keys - [:adapter]
+          unknown  = declared.reject { |field| adapter.declares?(field) }
+          return if unknown.empty?
+
+          raise WiringError,
+                "#{bind.adapter} does not declare #{unknown.map(&:inspect).join(', ')} — " \
+                "it declares #{adapter.all_fields.map(&:inspect).join(', ')}. " \
+                "Add the field to the adapter, or remove it from the world."
+        end
+
+        def port_for(bind)
+          adapter = @adapters[bind.adapter]
+          raise WiringError, "unknown adapter #{bind.adapter.inspect}" unless adapter
+
+          @ports[adapter.port] ||
+            raise(WiringError, "adapter #{bind.adapter} declares unknown port #{adapter.port.inspect}")
+        end
+
+        def adapter_class(name)
+          Adapters.const_get(name)
+        rescue NameError
+          raise WiringError, "no Ruby adapter implementation for #{name.inspect} " \
+                             "(expected Hecks::Adapters::#{name})"
+        end
+
+        private
+
+        # `role` IS REAL ACCESS CONTROL ONLY WHEN GOVERNANCE CAN CHECK IT
+        # AGAINST SOMETHING — a command that declares a role but whose
+        # domain never attaches Governance would leave that role forever
+        # unchecked, exactly the defect ADR 0025 §9 names ("role gates
+        # access control by exact string equality ... Governance ...
+        # connected to none of it"). Checked here, at `verify!` — RECOVERED
+        # and MOVED, not new: this used to run per-block, at HECKSAGON
+        # build time (Bluebook::DSL::HecksagonBuilder#build), which broke
+        # the moment a domain could be split across multiple hecksagon
+        # blocks (base + an `environments/<name>.hecksagon` overlay,
+        # Runtime::Loader.boot's `environment:` — see its own comment for
+        # the recovery provenance): every block but the one declaring
+        # `uses_framework "Governance"` would be refused there, even
+        # though `Registry#add_hecksagon` merges every block for a domain
+        # into ONE Hecksagon before anything ever dispatches against it.
+        # Checking the MERGED result once, here, after every file for
+        # this domain has loaded, is both more permissive (no need to
+        # repeat `uses_framework` in every file) and strictly more
+        # correct (a check against an incomplete, not-yet-merged
+        # hecksagon can never see the real final shape).
+        #
+        # GOVERNANCE ITSELF IS EXEMPT — it cannot `uses_framework` its own
+        # aggregates, and it IS the source of truth a role check runs
+        # against, the same self-reference `CommandRules::Authorization
+        # #governance_attached?` grants it at dispatch time.
+        def refuse_ungoverned_roles!(hexagon)
+          return if hexagon.domain == "Governance"
+          return if hexagon.framework_members.include?("Governance")
+
+          bluebook_ir = bluebook(hexagon.domain)
+          return unless bluebook_ir
+
+          offender = commands_in(bluebook_ir).find { |command| !command.role.to_s.empty? }
+          return unless offender
+
+          raise WiringError,
+                "#{offender.hecks_fqn} declares role #{offender.role.inspect}, but " \
+                "#{hexagon.domain}'s hecksagon never uses_framework \"Governance\" — role is only " \
+                "real access control once Governance is attached to check it against; without that " \
+                "it is silent decoration, the exact defect this refusal exists to catch"
+        end
+
+        # Every command this domain declares, an aggregate's own AND every
+        # entity nested inside one — the same reach `refuse_role_mismatch`
+        # itself needs at dispatch time, just walked ahead of time here.
+        def commands_in(bluebook_ir)
+          bluebook_ir.aggregates.flat_map { |aggregate| aggregate.commands + aggregate.entities.flat_map(&:commands) }
+        end
+
+        # A domain that declares a `process_manager` but whose
+        # `saga_persistence` resolves to `NULL_SAGA_STORE` (no anchor
+        # aggregate, a RemoteRuntime-shaped adapter, an adapter that
+        # doesn't `respond_to?(:save_saga)`, or a rescued WiringError —
+        # see `SagaPersistence#resolve_saga_persistence`) gets sagas that
+        # advance correctly in-process and vanish on restart: no
+        # checkpoint written, nothing for `rehydrate_sagas!` to find, no
+        # compensation ever replayed. That is silent right up until the
+        # process actually dies mid-saga — the same "consistency/
+        # freshness defect applied to access control, failing open" ADR
+        # 0025 named for an unchecked `role`, here applied to saga
+        # durability instead.
+        #
+        # A WARNING, NOT A REFUSAL — unlike `refuse_ungoverned_roles!`,
+        # running sagas on a store with no `save_saga` is legitimate on
+        # purpose in a fast in-memory test/dev boot (this project's own
+        # `saga_durability_spec.rb` boots a process manager on `Memory`
+        # specifically to exercise the saga_mutex without real I/O), so
+        # refusing the boot outright would break a choice an author made
+        # deliberately. What a deploy needs is for the gap to be loud and
+        # undeniable, not for local dev/test to become impossible.
+        def warn_undurable_sagas!(hexagon)
+          bluebook_ir = bluebook(hexagon.domain)
+          return unless bluebook_ir
+          return if bluebook_ir.process_managers.empty?
+          return unless saga_persistence(hexagon.domain).equal?(Ports::Persistence::NULL_SAGA_STORE)
+
+          names = bluebook_ir.process_managers.map(&:name).join(", ")
+          warn "[hecks] #{hexagon.domain} declares process_manager(s) #{names} but its resolved " \
+               "persistence adapter has no save_saga — saga state advances correctly in-process " \
+               "and is LOST on restart (no checkpoint, no rehydration, no compensation replay). " \
+               "Bind this domain to an adapter that implements save_saga if this process_manager " \
+               "must survive a crash."
+        end
+      end
+    end
+  end
+end

data/lib/hecks/runtime/registry.rb

@@ -0,0 +1,279 @@
+require_relative "registry/verification"
+require_relative "registry/saga_persistence"
+
+module Hecks
+  module Runtime
+    class WiringError < StandardError; end
+
+    # The collections a boot gathers — bluebooks, hexagons, ports, adapters,
+    # worlds, the logs — and how a repository is resolved from them. The
+    # wiring gate lives in registry/verification.rb, saga persistence
+    # resolution in registry/saga_persistence.rb.
+    class Registry
+      include Verification
+      include SagaPersistence
+
+      attr_reader :root, :bluebooks, :hecksagons, :ports, :adapters, :worlds, :event_log,
+                  :reaction_log, :saga_log, :saga_instances, :translations, :saga_mutex,
+                  :saga_dispatch_log, :policy_dispatch_log
+
+      def initialize(root: nil)
+        @root         = root
+        @bluebooks    = {}
+        @hecksagons   = {}
+        @ports = {}
+        @adapters     = {}
+        @worlds       = {}
+        @translations = []
+        @event_log    = []
+        @reaction_log = []
+        @saga_log = []
+        # ADDITIVE, RUBY-ONLY — never merged into saga_log/reaction_log.
+        # rust/src/kernel/orchestrate.rs ports THOSE two arrays' exact
+        # shape byte-for-byte (spec/rust_conformance_spec.rb's own
+        # equality check) — a landmine found by reading that spec before
+        # touching anything, not by hitting it. These carry the raw
+        # inputs a dispatch's own argument binding was resolved from
+        # (SagaInterpreter#deliver_saga_dispatch / PolicyInterpreter#
+        # trigger_args), for Properties.dispatch_binding_fidelity's own
+        # independent re-derivation — a fact neither existing log
+        # records at all, so there is nothing here for Rust to have
+        # matched or drifted from.
+        @saga_dispatch_log   = []
+        @policy_dispatch_log = []
+        @saga_instances = Hash.new { |h, k| h[k] = {} }
+        # GUARDS `saga_instances`' OWN mutation+checkpoint sequence
+        # (`SagaInterpreter`'s 4 write points, §7) — the same shape of
+        # hazard this codebase's own prior audit already flagged for
+        # `Dispatcher#reenter`'s reaction-depth counter (M20: a
+        # thread-shared ivar with no lock, since fixed by moving it to
+        # `Thread.current`, dispatcher.rb), made meaningfully easier to
+        # hit here once a persistence write sits in the same critical
+        # section. Held across the in-memory
+        # mutation AND the checkpoint write together, never across a
+        # saga's own dispatch cascade — see `SagaInterpreter#advance_saga`'s
+        # own comment for why that distinction matters (non-reentrant
+        # Mutex, recursive re-entry is real).
+        @saga_mutex = Mutex.new
+        @repositories = {}
+        @projection_repositories = {}
+        @bluebook_builders = {}
+        # EAGER, NOT LAZY — see `#resolved_eras`'s own comment for why. Built
+        # here rather than `@resolved_eras ||= {}` on first access so there is
+        # no window, post-boot, where two concurrently dispatching threads
+        # could race creating this Hash (Hecks/ThreadSharedIvarMutation; the
+        # same shape of hazard `Dispatcher#reenter`'s `@reaction_depth` was
+        # fixed for). Every WRITE into it still only ever happens at boot,
+        # single-threaded (`EraResolver.check!`, a `:pre_verify` boot gate) —
+        # this only removes the race on standing up the container itself for
+        # a boot with no era-plugin domain at all, whose first touch would
+        # otherwise be a live dispatch's own `RepositoryFactory.build` read.
+        @resolved_eras = {}
+        # EAGER, NOT LAZY — see `#capability_graph`'s own comment for why.
+        # `CapabilityGraph.new` only stores the registry reference; there is
+        # no reason to defer it, and doing so removes the exact same
+        # first-access race `#resolved_eras` above does, while preserving the
+        # "same instance every call" identity `spec/runtime/capability_graph_
+        # spec.rb` already requires.
+        @capability_graph = CapabilityGraph.new(self)
+        # `@saga_persistence` itself is eager (see `#saga_persistence`'s own
+        # comment) — only the PER-DOMAIN resolution inside it is genuinely
+        # expensive and lazy, guarded by this dedicated mutex. NOT the same
+        # mutex as `@saga_mutex`: `checkpoint` (saga_interpreter.rb) calls
+        # `saga_persistence(domain)` from INSIDE an `@saga_mutex.synchronize`
+        # block, so reusing `@saga_mutex` here would deadlock the very first
+        # time a saga advanced (a `Mutex` is not reentrant — the exact
+        # warning `@saga_mutex`'s own comment already gives for a different
+        # reason).
+        @saga_persistence = {}
+        @saga_persistence_mutex = Mutex.new
+      end
+
+      # THE BUILDER STAYS OPEN FOR THE LIFE OF THIS REGISTRY, keyed by chapter
+      # name — see the comment on `BluebookBuilder.build`. A chapter split across
+      # several files (`language/bluebook/*.bluebook`, all `Hecks.bluebook "Bluebook"`)
+      # needs its declarations to accumulate into ONE builder rather than each
+      # file minting its own and silently discarding the one before.
+      def bluebook_builder(name)
+        @bluebook_builders[name.to_s] ||= yield
+      end
+
+      # BOOT-TIME-ONLY, SINGLE-THREADED — every `add_*` below (through
+      # `add_translation`) is called exclusively from `Hecks.collect`
+      # (hecks.rb), which is what `Hecks.bluebook`/`.hecksagon`/`.port`/
+      # `.adapter`/`.world`/`.translation` run inside while a `.bluebook`/
+      # `.hecksagon`/`.world` file is being `Kernel.load`ed — i.e. strictly
+      # during `Loader.boot`/`.boot_files`, before `dispatcher_for` ever
+      # hands this registry to a live, multi-threaded caller. Nothing
+      # downstream of boot ever calls these — verified by grepping every
+      # call site in lib/ and spec/ before writing this — so unlike
+      # `#resolved_eras`/`#capability_graph`/`#saga_persistence` (each
+      # reachable from live dispatch, and fixed for real above/in
+      # registry/saga_persistence.rb) there is no concurrent caller for
+      # `Hecks/ThreadSharedIvarMutation` to actually be warning about here.
+      # rubocop:disable Hecks/ThreadSharedIvarMutation
+      def add_bluebook(item) = @bluebooks[item.name] = item
+
+      # MERGED, NOT REPLACED — RECOVERED, not new (see Runtime::Loader
+      # .boot's own comment for the provenance). A domain's hecksagon can
+      # now load in more than one block for the same domain (base file
+      # plus an `environments/<name>.hecksagon` overlay), and the second
+      # block should ADD to what the first declared, not silently
+      # discard it.
+      def add_hecksagon(item)
+        existing = @hecksagons[item.domain]
+        @hecksagons[item.domain] = existing ? merge_hecksagons(existing, item) : item
+      end
+
+      def add_port(item) = @ports[item.name] = item
+      def add_adapter(item) = @adapters[item.name] = item
+
+      # MERGED, NOT REPLACED — the same generalization for `World` that
+      # `add_hecksagon` above recovers for `Hecksagon`: an
+      # `environments/<name>.world` overlay (or a host-owned tenancy
+      # overlay world, same mechanism) can now add or override settings
+      # for a domain a base `.world` file already declared, without
+      # restating everything the base file said. Settings merge shallow,
+      # keyed exactly the way WorldBuilder already stores them (both the
+      # bare verb key and the `"verb:adapter"` qualified key point at the
+      # same resolved hash) — an overlay's key wins over the base's same
+      # key; a key only the base declares survives untouched.
+      def add_world(item)
+        existing = @worlds[item.domain]
+        @worlds[item.domain] = existing ? merge_worlds(existing, item) : item
+      end
+
+      def add_translation(item) = @translations << item
+      # rubocop:enable Hecks/ThreadSharedIvarMutation
+
+      # {domain name => era ordinal} as resolved by the boot-time era
+      # gate. A lineage adapter writes into ITS OWN era's partition —
+      # which, for an old checkout booting a held-but-superseded shape,
+      # is not the newest one. The Hash itself is stood up in `initialize`
+      # (see that comment) — this is a plain reader, not a memoizer;
+      # `Hecks/ThreadSharedIvarMutation` is the reason there is no `||=`
+      # left here to flag.
+      attr_reader :resolved_eras
+
+      def bluebook(name)  = @bluebooks[name.to_s]
+      def hecksagon(name) = @hecksagons[name.to_s]
+      def world(name)     = @worlds[name.to_s]
+
+      def verbs = @bluebooks.values.flat_map(&:verbs).sort
+
+      def repository(domain, aggregate)
+        @repositories[[domain.to_s, aggregate.hecks_name]] ||= Ports::Persistence.repository(self, domain, aggregate)
+      end
+
+      # EVERYTHING A DISPATCH WROTE, CLEARED; NOTHING A BOOT DECLARED,
+      # TOUCHED. Bluebooks, hecksagons, ports, adapters, worlds and the
+      # resolved eras are what loading the files produced and stay as
+      # they are; the logs, the saga instances and the repositories are
+      # what running commands against them produced, and go back to
+      # exactly what a fresh boot of the same files hands out. Dropping
+      # the repositories (rather than emptying each) is deliberate: a
+      # fresh boot's own repositories are new adapter instances too, so
+      # a Memory adapter starts empty and a durable one sees whatever
+      # it persisted — the same reading either way. Sagas rehydrate off
+      # that store again, the way `Loader.boot_files` does after
+      # `verify!`.
+      #
+      # What this is for: a test runner that used to boot a runtime per
+      # test to get isolation (`Behaviors::Expectations.run_one`) — ~2s a
+      # boot, 76 chess behaviours = two and a half minutes of booting the
+      # same two files — can now boot once and reset between tests.
+      #
+      # SINGLE-THREADED CALLER, THE SAME REASON THE `add_*` CLUSTER ABOVE
+      # IS EXEMPT — `Behaviors::Expectations.run_one` is this method's ONLY
+      # caller (verified by grep before writing this), and it runs one
+      # test at a time: `Runner#run` maps over tests sequentially, and
+      # `Behaviors.rspec`'s generated examples run under RSpec's own
+      # single-threaded example loop. No production dispatch path calls
+      # this at all — a live Puma worker pool never resets a registry out
+      # from under itself mid-flight.
+      # rubocop:disable-next Hecks/ThreadSharedIvarMutation
+      def reset_runtime_state!
+        @event_log.clear
+        @reaction_log.clear
+        @saga_log.clear
+        @saga_dispatch_log.clear
+        @policy_dispatch_log.clear
+        @saga_instances.clear
+        @repositories = {}
+        @projection_repositories = {}
+        rehydrate_sagas!
+        self
+      end
+
+      # Built eagerly in `initialize` (see that comment) — this is a plain
+      # reader, not a memoizer; `spec/runtime/capability_graph_spec.rb`
+      # asserts the SAME instance comes back every call, which this still
+      # gives, just without a lazy `||=` race on standing it up.
+      attr_reader :capability_graph
+
+      def read_repository(domain, aggregate)
+        key = [domain.to_s, aggregate.hecks_name]
+        binding = Ports::Projection.binds_for(self, domain, aggregate).first
+        return repository(domain, aggregate) unless binding
+
+        projection = (@projection_repositories[key] ||= begin
+          projection = Ports::Persistence::RepositoryFactory.build(self, domain, aggregate, binding,
+                                                                   recover: true, settings_verb: Ports::Projection::VERB)
+          projection
+        end)
+        authoritative = repository(domain, aggregate)
+        projection_current?(projection, authoritative) ? projection : authoritative
+      end
+
+      def projection_current?(projection, authoritative)
+        projected_entries = projection.entries
+        source_entries = authoritative.entries
+        return false unless projected_entries.length == source_entries.length
+        return false unless projected_entries.zip(source_entries).all? do |projected, source|
+          projected.operation == source.operation && projected.id == source.id && projected.state == source.state
+        end
+
+        projected_rows = projection.all.map(&:to_h).sort_by { |row| row.fetch(:id).to_s }
+        source_rows = authoritative.all.map(&:to_h).sort_by { |row| row.fetch(:id).to_s }
+        projected_rows == source_rows
+      rescue StandardError
+        false
+      end
+
+      # RECOVERED — see `add_hecksagon`'s own comment for provenance.
+      # Concatenates every list-shaped fact; `binds` in particular is
+      # additive because an overlay REBINDING an aggregate (a new
+      # `persisted_by` for the same aggregate/verb) is meant to shadow
+      # the base's own bind at resolution time, not erase it outright —
+      # `Ports::Persistence::BindingPolicy.resolve`'s own "exactly one
+      # authoritative bind" check is what actually catches a genuine
+      # double-bind; this merge only concatenates, it does not itself
+      # decide which of two binds for the same aggregate wins.
+      def merge_hecksagons(a, b)
+        Bluebook::Hecksagon.new(
+          domain:             a.domain,
+          binds:              a.binds + b.binds,
+          subscriptions:      a.subscriptions + b.subscriptions,
+          framework_members:  a.framework_members + b.framework_members,
+          vendored_bluebooks: a.vendored_bluebooks + b.vendored_bluebooks
+        )
+      end
+
+      # RECOVERED AND GENERALIZED — see `add_world`'s own comment. `realm`/
+      # `latest` are scalars, so the overlay's value wins when present,
+      # else the base's survives; `settings` is a shallow merge keyed by
+      # verb (and `"verb:adapter"`) — an overlay entry for a key the base
+      # also declares REPLACES that key's whole resolved hash (the same
+      # all-or-nothing shape `WorldBuilder#method_missing` already builds
+      # each entry as), it does not deep-merge field by field within it.
+      def merge_worlds(a, b)
+        Bluebook::World.new(
+          domain:   a.domain,
+          realm:    b.realm || a.realm,
+          latest:   b.latest || a.latest,
+          settings: a.settings.merge(b.settings)
+        )
+      end
+    end
+  end
+end