hecks 1.0.2 → 1.1.0

data/lib/hecks/runtime/dependency_planning.rb

@@ -31,6 +31,10 @@ module Hecks
         end
       end
 
+      # Walks a canonical expression's parsed nodes (the same AST
+      # Bluebook::Expression::Evaluator evaluates) and collects the
+      # dotted paths it reads — used by Analyzer to classify a
+      # given/ensures/invariant rule's dependencies without evaluating it.
       module ExpressionReads
         module_function
 
@@ -59,6 +63,13 @@ module Hecks
         end
       end
 
+      # Static, correctness-first dependency analysis for one command:
+      # walks its mutations, lifecycle transitions, and given/ensures/
+      # invariant rules to derive a Plan (read_set/write_set/
+      # complete_state?/state_independent?) describing what the command
+      # touches without executing it. `Analyzer.call` is what
+      # CommandInterpreter and EntityInterpreter both consult before
+      # choosing a dispatch strategy.
       class Analyzer
         STATEFUL_MUTATIONS = %i[append increment decrement multiply clamp remove].freeze
 
@@ -101,11 +112,11 @@ module Hecks
           # 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
+          aggregate.projected_fields.each { |field| @owner_fields << field.name } if aggregate.respond_to?(:projected_fields)
           if root_aggregate.respond_to?(:projected_fields)
-            root_aggregate.projected_fields.each { |field| @root_owner_fields << field.name }
+            root_aggregate.projected_fields.each do |field|
+              @root_owner_fields << field.name
+            end
           end
           @payload_fields = command.attributes.to_set(&:name)
           @state_reads = Set.new
@@ -210,9 +221,7 @@ module Hecks
           lifecycle = aggregate.lifecycle
           return unless lifecycle
 
-          if command.from
-            state_reads << lifecycle.field
-          end
+          state_reads << lifecycle.field if command.from
 
           return if lifecycle.transitions_for(command.hecks_name).empty?
 
@@ -223,8 +232,8 @@ module Hecks
         def analyze_rules(rules, phase:)
           rules.each do |rule|
             ExpressionReads.paths(rule.canonical).each { |path| classify_path(path, phase) }
-          rescue ArgumentError => error
-            unresolved << "expression #{rule.canonical.inspect} could not be analyzed: #{error.message}"
+          rescue ArgumentError => e
+            unresolved << "expression #{rule.canonical.inspect} could not be analyzed: #{e.message}"
           end
         end
 
@@ -249,7 +258,6 @@ module Hecks
           name = head.to_sym
 
           if name == :parent
-            parent_field = nested.to_s.split(".", 2).first
             # `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
@@ -257,18 +265,9 @@ module Hecks
             # 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
-            end
+            resolve_nested_state_read!(path, nested, root_owner_fields, "does not name parent aggregate state")
           elsif name == :old
-            old_field = nested.to_s.split(".", 2).first
-            if old_field.empty? || !owner_fields.include?(old_field.to_sym)
-              unresolved << "#{path} does not name prior aggregate state"
-            else
-              state_reads << old_field.to_sym
-            end
+            resolve_nested_state_read!(path, nested, owner_fields, "does not name prior aggregate state")
           elsif payload_fields.include?(name)
             payload_reads << name
           elsif owner_fields.include?(name)
@@ -278,6 +277,19 @@ module Hecks
           end
         end
 
+        # Shared shape behind the `:parent`/`:old` branches above: read the
+        # nested field name, check it against the given owner field set
+        # (deliberately different sets for `parent`/`old` — see the caller),
+        # and either record it as a state read or refuse with `message`.
+        def resolve_nested_state_read!(path, nested, field_set, message)
+          field = nested.to_s.split(".", 2).first
+          if field.empty? || !field_set.include?(field.to_sym)
+            unresolved << "#{path} #{message}"
+          else
+            state_reads << field.to_sym
+          end
+        end
+
         # A partial mutation must preserve every untouched field on the
         # correctness path. Those prior values are real reads even when no rule
         # names them. A deterministic write needs no preservation read.

data/lib/hecks/runtime/dispatcher.rb

@@ -9,10 +9,18 @@ require_relative "query_interpreter"
 require_relative "read_model_interpreter"
 require_relative "policy_interpreter"
 require_relative "saga_interpreter"
+require_relative "outbox"
 require_relative "../naming"
 
 module Hecks
   module Runtime
+    # The runtime's single dispatch entry point for one booted registry:
+    # routes a "Domain::Aggregate.Command"-shaped verb to the right
+    # sub-interpreter (command, entity, port operation, query, read
+    # model), then runs every policy and saga reaction the resulting
+    # events trigger. Also the door reactions dispatch back through
+    # (#reenter), and the one place reaction-cascade depth is tracked, to
+    # keep a policy/saga loop from re-triggering itself without bound.
     class Dispatcher
       MAX_REACTION_DEPTH = 5
 
@@ -48,8 +56,19 @@ module Hecks
         @read_models = ReadModelInterpreter.new(registry)
         @policies = PolicyInterpreter.new(registry, door: self)
         @sagas    = SagaInterpreter.new(registry, door: self)
+        # THE RELAY IS THE REGISTRY'S, NOT THIS DISPATCHER'S — the
+        # interpreters enqueue through `@registry.outbox` from inside
+        # the save transaction, and this dispatcher drains through the
+        # same object, so there is exactly one relay per registry no
+        # matter how many dispatchers front it. What it borrows from
+        # here is the pair of interpreters a consumer runs through.
+        @registry.outbox.attach(policies: @policies, sagas: @sagas)
       end
 
+      # `runtime.outbox.rows`, `.rows(status: "claimed")`, `.redrive!`,
+      # `.log` — see `Runtime::Outbox`.
+      def outbox = @registry.outbox
+
       def events = @registry.event_log
 
       def reactions = @registry.reaction_log
@@ -63,7 +82,7 @@ module Hecks
         domain, aggregate_name, command_name = parse(verb)
         aggregate = resolve_aggregate(domain, aggregate_name, verb)
 
-        instance, announced, execution_plan, persistence_outcome =
+        instance, announced, execution_plan, persistence_outcome, outbox_rows =
           if command_name.include?(".")
             head, sub = command_name.split(".", 2)
             port = aggregate.port(head)
@@ -83,7 +102,7 @@ module Hecks
                           raise(UnknownVerb, RefusalWording.render("UnknownVerb", "port_no_operation",
                                                                    port: head, operation: sub.inspect))
               route, args = port_invocation(aggregate, operation, to: to, with: with, legacy: legacy_args)
-              [nil, @port_ops.call(domain, aggregate, operation, args, route: route), nil, nil]
+              [nil, @port_ops.call(domain, aggregate, operation, args, route: route), nil, nil, :enqueue]
             else
               entity_depth = command_name.split(".").size - 1
               route = Routing.envelope(to, entity_depth: entity_depth)
@@ -109,14 +128,30 @@ module Hecks
         # `announced` events within this very call, and finds the
         # correlation already there because it was never absent.
 
-        announced.each { |event| @policies.react(event, domain) }
-
-        announced.each { |event| @sagas.advance(event, domain) }
+        react(announced, domain, aggregate, outbox_rows)
 
         Result.new(verb: verb, instance: instance, events: announced,
                    execution_plan: execution_plan, persistence_outcome: persistence_outcome)
       end
 
+      # EVERYTHING OWED BECAUSE `announced` COMMITTED — policies first,
+      # then sagas, the order this method always ran them in. The
+      # command/entity interpreters hand back the outbox rows they
+      # enqueued inside the save transaction (`Interpreting#
+      # run_dispatch_order`); a port operation saves nothing, so its
+      # rows are enqueued here, after the fact (`:enqueue`) — durable
+      # still, just not transactional with anything, because there is
+      # nothing for them to be transactional with. `nil` rows mean the
+      # repository has no outbox: react directly, exactly as before.
+      def react(announced, domain, aggregate, outbox_rows)
+        return if announced.empty?
+
+        repository = @registry.repository(domain, aggregate)
+        outbox_rows = outbox.enqueue(repository, announced, domain) if outbox_rows == :enqueue
+        outbox.deliver(outbox_rows, announced, domain, repository)
+      end
+      private :react
+
       # "IF THIS WERE DISPATCHED RIGHT NOW, WOULD IT SUCCEED" — the same
       # pipeline #dispatch itself runs (arguments coerced, givens checked,
       # mutations applied IN MEMORY, ensures checked against the settled
@@ -180,8 +215,7 @@ module Hecks
         route, args = port_invocation(aggregate, operation, to: to, with: with, legacy: legacy_args)
         announced = @port_ops.call(domain, aggregate, operation, args, route: route)
 
-        announced.each { |event| @policies.react(event, domain) }
-        announced.each { |event| @sagas.advance(event, domain) }
+        react(announced, domain, aggregate, :enqueue)
 
         announced
       end

data/lib/hecks/runtime/entity_element.rb

@@ -63,6 +63,14 @@ module Hecks
       # which element it means, so re-deriving `wants` from `args` would be
       # redundant at best and wrong if `args` no longer carries that identity
       # at all.
+      # Locate, then copy-before-mutate, in that order — see the "ONE
+      # LEVEL DEEPER" comment below on why the copy has to happen exactly
+      # where it does (aliasing the adapter's own record otherwise).
+      # Splitting resolution from the copy/write-back would separate two
+      # halves of one aliasing-safety invariant across method boundaries.
+      # rubocop:disable-next Metrics/AbcSize
+      # rubocop:disable-next Metrics/CyclomaticComplexity
+      # rubocop:disable-next Metrics/PerceivedComplexity
       def element_of(root_aggregate, owner, entity, command_name, container, args, routed_identity = nil)
         entity_name = entity.hecks_name
         list_attr = owner.attributes.find { |a| a.list? && a.type.to_s == entity_name } ||
@@ -158,32 +166,43 @@ module Hecks
       # method's own fixture (TaggedList.Bump, a VO-typed `count` with
       # `default: 0`) raised exactly this TypeMismatch on its first
       # real run.
-      def apply_to_element(rules, aggregate, entity, element, mutation, args)
+      # A case dispatching over a closed, declared set of mutation ops —
+      # deliberately kept byte-for-byte parallel to its aggregate-level
+      # twin, MutationApplier#apply (see this method's own comment
+      # above and each branch's "own entity-scoped twin" cross-reference):
+      # extracting the near-duplicate increment/decrement/multiply
+      # shape here without doing the same there would break that
+      # intentional mirroring, which is what lets the two be diffed
+      # against each other when one gets a fix the other needs too.
+      # rubocop:disable-next Metrics/AbcSize
+      # `pre` — the element as it was before this command (C4.2): every
+      # read below goes through it, every write lands on `element`.
+      def apply_to_element(rules, aggregate, entity, element, mutation, args, pre = element)
         case mutation.op
         when :set
           value = rules.resolve_source(mutation.source, args)
           attribute = entity.attribute(mutation.target)
           element[mutation.target] = attribute ? Value.for_attribute(aggregate, attribute, value) : value
         when :append
-          element[mutation.target] = appended_to_element(aggregate, entity, element, mutation, args)
+          element[mutation.target] = appended_to_element(aggregate, entity, pre, mutation, args)
         when :remove
-          element[mutation.target] = removed_from_element(rules, aggregate, entity, element, mutation, args)
+          element[mutation.target] = removed_from_element(rules, aggregate, entity, pre, mutation, args)
         when :increment, :decrement
           attribute = entity.attribute(mutation.target)
           amount    = rules.resolve_source(mutation.source, args)
-          current   = element[mutation.target]
+          current   = pre[mutation.target]
           amount    = Value.for_attribute(aggregate, attribute, amount) if attribute && current.is_a?(Value)
           result    = rules.arithmetic(current, amount, mutation.target, rules.sign_of(mutation.op))
           element[mutation.target] = rewrap_arithmetic_result(aggregate, attribute, current, result)
         when :multiply
           attribute = entity.attribute(mutation.target)
           amount    = rules.resolve_source(mutation.source, args)
-          current   = element[mutation.target]
+          current   = pre[mutation.target]
           amount    = Value.for_attribute(aggregate, attribute, amount) if attribute && current.is_a?(Value)
           result    = rules.multiply(current, amount, mutation.target)
           element[mutation.target] = rewrap_arithmetic_result(aggregate, attribute, current, result)
         when :clamp
-          element[mutation.target] = rules.clamp(element[mutation.target], mutation.source, mutation.target)
+          element[mutation.target] = rules.clamp(pre[mutation.target], mutation.source, mutation.target)
         else
           # The aggregate-level twin's own backstop
           # (MutationApplier#apply), for the same reason: applying

data/lib/hecks/runtime/entity_interpreter.rb

@@ -14,6 +14,13 @@ require_relative "command_interpreter/argument_gate"
 
 module Hecks
   module Runtime
+    # Interprets a command dispatched against a nested entity (a dotted
+    # verb like "Handler.Dispatch.Bind") rather than an aggregate root
+    # directly: walks the entity chain off the parent aggregate, applies
+    # the command's own DISPATCH_ORDER of steps against the located
+    # element, then saves and emits through the same parent record a
+    # plain aggregate command would. CommandInterpreter's sibling for
+    # entity-owned commands.
     class EntityInterpreter
       include Interpreting
       # THE SAME PAYLOAD GATE aggregate commands and port operations already
@@ -61,9 +68,14 @@ module Hecks
       # targets, so every step written before this ADR (enforce_givens,
       # apply_mutations, advance_lifecycle, element_identity, ...) reads
       # exactly as it always has. Only `locate_element` walks the chain.
+      # `:chain` shadows Enumerable#chain on purpose — every read is
+      # `ctx.chain` fetching the field (an Array of entities), never
+      # `ctx.chain(other)` combining enumerables. Verified before disabling
+      # this cop for it.
+      # rubocop:disable-next Lint/StructNewOverride
       Context = Struct.new(:domain, :aggregate, :entity, :entity_name, :command, :command_name,
                            :args, :repository, :instance, :chain, :element, :view, :transition,
-                           :old_element, :result, :route, :plan, :persistence_outcome, :dry_run)
+                           :old_element, :result, :route, :plan, :persistence_outcome, :dry_run, :outbox_rows)
 
       def initialize(registry, rules:)
         @registry = registry
@@ -111,7 +123,7 @@ module Hecks
           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]
+          [ctx.instance, ctx.result, ctx.plan, ctx.persistence_outcome, ctx.outbox_rows]
         rescue StaleWrite
           attempt += 1
           retry if attempt < MAX_STALE_WRITE_RETRIES
@@ -149,10 +161,10 @@ module Hecks
       # `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) {
+        step(:refuse_unknown_arguments) do
           refuse_unknown_arguments(ctx.domain, ctx.aggregate, ctx.command, ctx.args,
                                    extra_identity_heads: ctx.chain.flat_map(&:identity_heads))
-        }
+        end
       end
 
       # No `aggregate:` exemption to pass — that kwarg exists only for a
@@ -180,15 +192,15 @@ module Hecks
       def step_hydrate_parent(ctx)
         # `ctx.repository` is resolved once, in `#call`, before the
         # isolation decision — not here any more.
-        ctx.instance = step(:hydrate_parent) {
+        ctx.instance = step(:hydrate_parent) do
           parent(ctx.repository, ctx.aggregate, ctx.entity_name, ctx.command_name, ctx.args, ctx.route)
-        }
+        end
       end
 
       def step_locate_element(ctx)
-        ctx.element = step(:locate_element) {
+        ctx.element = step(:locate_element) do
           EntityElement.locate_chain(ctx.aggregate, ctx.chain, ctx.instance, ctx.args, ctx.command_name, ctx.route)
-        }
+        end
         # `view` was hydrated ONCE, here, into its OWN state hash
         # (Value.hydrate builds a fresh Hash — never aliased with `element`)
         # — exactly right for enforce_givens, which must read pre-mutation.
@@ -197,9 +209,9 @@ module Hecks
       end
 
       def step_enforce_givens(ctx)
-        step(:enforce_givens) {
+        step(:enforce_givens) do
           @rules.enforce_givens(ctx.view, ctx.command, ctx.args, domain: ctx.domain, declaring: ctx.entity, parent: ctx.instance)
-        }
+        end
       end
 
       def step_admissible_transition(ctx)
@@ -208,11 +220,12 @@ module Hecks
 
       def step_apply_mutations(ctx)
         ctx.old_element = ctx.element.dup unless ctx.command.ensures.empty?
-        step(:apply_mutations) {
-          ctx.command.mutations.each { |mutation|
-            EntityElement.apply_to_element(@rules, ctx.aggregate, ctx.entity, ctx.element, mutation, ctx.args)
-          }
-        }
+        step(:apply_mutations) do
+          pre = ctx.element.dup # C4.2 — the update set reads the element as it was
+          ctx.command.mutations.each do |mutation|
+            EntityElement.apply_to_element(@rules, ctx.aggregate, ctx.entity, ctx.element, mutation, ctx.args, pre)
+          end
+        end
       end
 
       def step_advance_lifecycle(ctx)

data/lib/hecks/runtime/errors.rb

@@ -5,8 +5,34 @@ module Hecks
   module Runtime
     class UnknownVerb < StandardError; end
     class EnsuresNotMet < StandardError; end
-    class GivenNotMet < StandardError; end
-    class NotFound    < StandardError; end
+
+    # `detail` — the failing comparison's own resolved operands, "left: X,
+    # right: Y" — set only when the given's TOP-LEVEL shape is a bare
+    # comparison (`Evaluator.comparison_detail`'s own comment has the full
+    # scoping); nil otherwise. Deliberately NOT folded into `#message`:
+    # that string is pinned byte-for-byte across this corpus's own specs
+    # (`raise_error(GivenNotMet, "...")`, command_rules_spec.rb and every
+    # domain that vendors this gem) as CONTRACT, so changing its shape by
+    # default would be a breaking change for every one of them. Riding on
+    # `#detailed_message` instead (Ruby 3.2+, what irb/a Rails console's
+    # own unhandled-exception banner already calls to show more than
+    # `#message`) means the detail actually reaches a human staring at a
+    # live refusal, without moving the string anything else asserts on.
+    class GivenNotMet < StandardError
+      attr_reader :detail
+
+      def initialize(message = nil, detail: nil)
+        super(message)
+        @detail = detail
+      end
+
+      def detailed_message(highlight: false, **opts)
+        base = super
+        detail ? "#{base} (#{detail})" : base
+      end
+    end
+
+    class NotFound < StandardError; end
     class LifecycleRefused < StandardError; end
     class TypeMismatch < StandardError; end
     # An argument the command does not declare. Sibling of TypeMismatch : that one

data/lib/hecks/runtime/instance.rb

@@ -3,6 +3,12 @@ require_relative "identity"
 
 module Hecks
   module Runtime
+    # One aggregate (or entity) record's runtime state: the declared
+    # attributes hydrated with defaults, plus the identity (`id`) and,
+    # for a CAS-capable adapter, the optimistic-concurrency `version`
+    # stamped on it. `[]`/`[]=`/method_missing give state-field access;
+    # `to_h` is the wire/storage shape with `id` merged in last so a
+    # same-named declared attribute can never clobber it.
     class Instance
       attr_reader :aggregate, :id
       attr_accessor :state
@@ -46,12 +52,12 @@ module Hecks
       end
 
       def self.defaults(aggregate)
-        state = aggregate.attributes.each_with_object({}) do |attr, acc|
+        state = aggregate.attributes.to_h do |attr|
           # FROZEN, like a list that has had something appended to it.
           # An untouched list is the easiest one to miss and the easiest
           # to mutate: nothing has replaced it yet, so a caller pushing
           # into it writes straight into the aggregate's own state.
-          acc[attr.name] = attr.list? ? Freezer.deep([]) : default_for(aggregate, attr)
+          [attr.name, attr.list? ? Freezer.deep([]) : default_for(aggregate, attr)]
         end
         state[aggregate.lifecycle.field.to_sym] = aggregate.lifecycle.default if aggregate.lifecycle
         state
@@ -64,7 +70,7 @@ module Hecks
         return nil unless aggregate.respond_to?(:value_object)
 
         value_object = aggregate.value_object(attribute.type)
-        return nil unless value_object && value_object.attributes.all? { |field| !field.default.nil? }
+        return nil unless value_object&.attributes&.all? { |field| !field.default.nil? }
 
         Value.build(value_object, {}, aggregate)
       end

data/lib/hecks/runtime/interpreting.rb

@@ -40,8 +40,35 @@ module Hecks
       # has to guard ITSELF at the top of its own handler and skip tracing
       # when it does not fire, rather than the caller branching around it —
       # see CommandInterpreter#step_assign_creation_attributes.
+      # THE COMMIT BOUNDARY. Every step up to `save` runs as before;
+      # `save`, `emit`, and the outbox enqueue that follows them run
+      # inside ONE `repository.transaction` — so the aggregate row, its
+      # journal entry, the recorded event, and the outbox rows naming
+      # who is owed a reaction commit together or not at all. No new
+      # step is added to the vocabulary's dispatch order (the step list
+      # is a pinned contract, `spec/vocabulary_conformance_spec.rb`);
+      # the enqueue is a consequence of `emit`, not a step of its own.
+      # A context without a repository (port operations — nothing to
+      # save) or with no `:save` in its order runs plainly.
       def run_dispatch_order(order, ctx)
-        order.each { |name| send(:"step_#{name}", ctx) }
+        split = order.index(:save)
+        return order.each { |name| send(:"step_#{name}", ctx) } unless split && ctx.respond_to?(:repository) && ctx.repository
+
+        order[0...split].each { |name| send(:"step_#{name}", ctx) }
+        ctx.repository.transaction do
+          order[split..].each { |name| send(:"step_#{name}", ctx) }
+          enqueue_outbox(ctx)
+        end
+      end
+
+      # Rows for the events this dispatch just emitted, written while
+      # the save's transaction is still open. `nil` (no outbox on this
+      # repository) tells the dispatcher to react directly, the
+      # pre-outbox path; a dry run emits nothing and enqueues nothing.
+      def enqueue_outbox(ctx)
+        return if ctx.dry_run || !ctx.respond_to?(:outbox_rows=)
+
+        ctx.outbox_rows = @registry.outbox.enqueue(ctx.repository, Array(ctx.result), ctx.domain)
       end
 
       # THE CONCURRENCY-CONTROL SPLIT — see docs/decisions/ (concurrency
@@ -72,7 +99,7 @@ module Hecks
           next unless normalized.key?(attribute.name)
 
           Value.refuse_object_reference(command, attribute, normalized[attribute.name])
-          normalized[attribute.name] = Value.for_attribute(aggregate, attribute, normalized[attribute.name])
+          normalized[attribute.name] = Value.for_attribute(aggregate, attribute, normalized[attribute.name], argument: true)
         end
       end
 

data/lib/hecks/runtime/loader.rb

@@ -8,6 +8,12 @@ require_relative "registry"
 
 module Hecks
   module Runtime
+    # The boot entry point: loads a bluebook directory (or an explicit
+    # file list) into a fresh Registry, runs every registered boot gate
+    # (era checks, saga rehydration, …), and hands back the Dispatcher
+    # (or RemoteDispatcher, for a domain declaring `dispatched_by
+    # ("Lambda")`) bound to it — installing the `Widget::Item.Add(...)`
+    # facade sugar unless the caller opts out.
     class Loader
       # `install_facade:` defaults on — every ordinary caller wants
       # `Widget::Item.Add(...)` sugar. A caller that only ever dispatches
@@ -45,9 +51,24 @@ module Hecks
 
         run_boot_gates!(registry, directory)
         dispatcher = dispatcher_for(registry)
+        redrive_outbox!(dispatcher)
         install_facade ? bind_runtime(dispatcher) : dispatcher
       end
 
+      # THE OUTBOX'S BOOT-TIME RECONCILIATION — after the dispatcher
+      # exists (a row's consumer runs through its interpreters, so this
+      # cannot be a plain registry gate the way saga rehydration is) and
+      # after saga rehydration (a redriven row may advance a saga, which
+      # must already be in memory). `pending` rows are redriven —
+      # provably never started; `claimed` rows are surfaced, never
+      # auto-redriven — see `Runtime::Outbox`. A remote dispatcher has
+      # no local stores to scan.
+      def self.redrive_outbox!(dispatcher)
+        return unless dispatcher.respond_to?(:outbox)
+
+        dispatcher.outbox.redrive!
+      end
+
       # THE EXPLICIT-FILE FORM — `paths` names the exact bluebook/hecksagon/
       # world files to boot, in place, wherever they actually live. `boot`
       # above only ever takes a directory and globs it; that is the right