hecks 0.2.0 → 0.3.0

data/lib/hecks/runtime/remote_dispatcher.rb

@@ -0,0 +1,143 @@
+require_relative "dispatcher"
+require_relative "instance"
+require_relative "event"
+require_relative "errors"
+require_relative "../naming"
+require_relative "../adapters/driven/lambda/client"
+require_relative "../ports/persistence/binding_policy"
+require_relative "../ports/persistence/remote_runtime"
+
+module Hecks
+  module Runtime
+    # THE WRITE-SIDE HALF OF LAMBDA ROUTING — `Runtime::Loader.boot`
+    # constructs this INSTEAD OF `Dispatcher` when the booted domain's
+    # own `.world` declares Lambda routing (see loader.rb's own
+    # `dispatcher_class_for`). Matches `Dispatcher`'s public shape
+    # closely enough that everything built ON TOP of a dispatcher —
+    # `Handle`, `AggregateDoor`, `Facade::Surface` — needs no changes
+    # at all: `Handle#run`'s entire contract is
+    # `@dispatcher.dispatch("#{fqn}.#{command}", **identity, **args).instance.state`,
+    # and both classes answer that identically.
+    #
+    # READS DELEGATE, WRITES DON'T. `query`/`reference_query` hand off
+    # to a REAL `Dispatcher` built over the SAME registry — since that
+    # registry's own repositories are ALREADY Lambda-backed
+    # (`Adapters::Lambda`, `persisted_by("Lambda")`, Phase 2's other
+    # half), the inherited query machinery (`QueryInterpreter`,
+    # `Ports::Query::InMemory.execute`) works completely unchanged, no
+    # query logic duplicated here. `dispatch` can't delegate the same
+    # way: command validation (givens, constraints) has to actually
+    # run in Rust for a Lambda-routed domain, not get pre-checked here
+    # against incomplete local state and then merely persisted.
+    class RemoteDispatcher
+      Result = Struct.new(:verb, :instance, :events, keyword_init: true) do
+        def id    = instance.id
+        def state = instance.to_h
+      end
+
+      attr_reader :registry
+
+      def initialize(registry, region: "us-east-1")
+        @registry = registry
+        # `File.basename(registry.root)`, not `bluebooks.keys.first` —
+        # matches `Adapters::Lambda`'s own function-name resolution
+        # exactly (see its own comment on why: one merged Lambda per
+        # deploy, not one per attached chapter, and `root` is the one
+        # signal every bluebook in this registry shares regardless of
+        # which one attached it) — INCLUDING that same adapter's own
+        # `ENV["DOMAIN_NAME"]`-first fix: `root` is always `/var/task`
+        # inside a deployed Lambda, giving "task" instead of the real
+        # domain name (a real, live AccessDeniedException on
+        # "hecks-task" caught this).
+        @client = Adapters::Lambda::Client.new(domain: ENV["DOMAIN_NAME"] || File.basename(registry.root), region: region)
+        # READ-SIDE DELEGATE ONLY (see class comment) — never dispatched
+        # through; a real Dispatcher's own `query`/`reference_query`
+        # already resolve generically via `registry.repository(...)`,
+        # so building one here reuses that instead of duplicating it.
+        @local = Dispatcher.new(registry)
+      end
+
+      def dispatch(verb, saga_correlation: nil, **args)
+        domain, aggregate_name, = Naming.split_verb(verb) ||
+                                  raise(UnknownVerb,
+                                        RefusalWording.render("UnknownVerb", "not_fully_qualified", verb: verb.inspect))
+        aggregate = @registry.bluebook(domain)&.aggregate(aggregate_name) ||
+                    raise(UnknownVerb,
+                          RefusalWording.render("UnknownVerb", "no_aggregate", domain: domain, aggregate: aggregate_name.inspect))
+
+        # NOT EVERY AGGREGATE IN A LAMBDA-ROUTED DOMAIN IS ITSELF
+        # LAMBDA-BOUND — Member's real name->email rekey carries a
+        # `compute` rule (era_check.rb's own `check_compute_rules!`),
+        # which can only ever run against Postgres, permanently. Its
+        # OWN `.hecksagon` bind stays "Postgres" even when
+        # `dispatched_by("Lambda")` is on for everything else — checked
+        # here by real CAPABILITY (`Ports::Persistence::RemoteRuntime`,
+        # §1), not by comparing the adapter's own name to the string
+        # "Lambda" — a bind resolves to whatever adapter CLASS actually
+        # backs it, and only a class shaped like "the real interpreter
+        # lives behind a call boundary" forwards here; anything else
+        # (Postgres, Memory, any future local adapter) falls through to
+        # the real local Dispatcher instead of being forwarded to a
+        # Lambda that has no way to represent its lineage history at
+        # all.
+        adapter_name = Ports::Persistence::BindingPolicy.resolve(@registry, domain, aggregate).adapter
+        return @local.dispatch(verb, saga_correlation: saga_correlation, **args) unless @registry.adapter_class(adapter_name) <= Ports::Persistence::RemoteRuntime
+
+        response = @client.dispatch(verb, args)
+
+        refusal = response.fetch("refusals", []).find { |r| r["verb"] == verb }
+        raise RemoteRefusal, "#{verb} refused: #{refusal['error']}" if refusal
+
+        # THIS STEP'S OWN mutations — `mutations` is one entry per
+        # replayed step (rust/host's rehydrate-and-replay design,
+        # Phase 1), so `.last` is exactly the step just dispatched.
+        # Matched by fully-qualified aggregate name, not just "the
+        # first mutation" — a command whose reaction ALSO mutates a
+        # different aggregate (a policy, a saga leg) puts more than
+        # one mutation in the same step, and the direct effect of
+        # THIS verb is the one this dispatch's own caller expects
+        # `.instance` to be.
+        fqn = "#{domain}::#{aggregate.hecks_name}"
+        mutation = response.fetch("mutations", []).last&.find { |m| m["aggregate"] == fqn } ||
+                   raise(WiringError,
+                         "#{verb} was accepted but rust/host reported no mutation for #{fqn} — response: #{response.inspect}")
+
+        instance = Instance.new(aggregate: aggregate, id: mutation["id"],
+                                state: JSON.parse(JSON.generate(mutation["state"]), symbolize_names: true))
+
+        Result.new(verb: verb, instance: instance, events: step_events(response))
+      end
+
+      def query(verb, **args)           = @local.query(verb, **args)
+      def reference_query(verb, **args) = @local.reference_query(verb, **args)
+
+      # THE FULL DOMAIN'S EVENT HISTORY, on every call — `{"read":
+      # true}` replays the whole journal (Phase 1's `dispatch::read`),
+      # so its own `events` array already IS the complete log, the
+      # same thing `@registry.event_log` would answer for a local
+      # dispatch. Not cached: `AggregateDoor.events`/`Handle#events`
+      # are not called in this codebase's own hot paths today: if that
+      # changes, caching belongs here, not in every caller.
+      def events
+        @client.read.fetch("events", []).map { |e| build_event(e) }
+      end
+
+      private
+
+      def step_events(response)
+        response.fetch("events", []).map { |e| build_event(e) }
+      end
+
+      # Rust's own event JSON (kernel/cli.rs's `event_to_json`) carries
+      # `name`/`aggregate`/`id`/`payload` only — no `occurred_at`
+      # (nothing in the kernel tracks wall-clock time; every
+      # replay is deterministic and timestamp-free by design). `nil`
+      # here, not a synthesized `Time.now` that would silently lie
+      # about when something actually happened.
+      def build_event(json)
+        Event.new(name: json["name"], aggregate: json["aggregate"], id: json["id"],
+                  payload: JSON.parse(JSON.generate(json["payload"]), symbolize_names: true), occurred_at: nil)
+      end
+    end
+  end
+end

data/lib/hecks/runtime/routing.rb

@@ -0,0 +1,96 @@
+require_relative "errors"
+require_relative "refusal_wording"
+
+module Hecks
+  module Runtime
+    # The invocation address is not part of a command's domain payload.
+    # Aggregate commands carry one receiver identity; entity commands carry
+    # the aggregate receiver followed by one identity for every entity hop.
+    module Routing
+      Envelope = Struct.new(:aggregate, :entities, keyword_init: true) do
+        def initialize(aggregate:, entities: [])
+          super(aggregate: aggregate.to_s, entities: Array(entities).map(&:to_s).freeze)
+          freeze
+        end
+      end
+
+      module_function
+
+      def envelope(to, entity_depth: 0)
+        return nil if to.nil?
+
+        aggregate, entities = if to.is_a?(Hash)
+                                hash = to.transform_keys(&:to_sym)
+                                unknown = hash.keys - %i[aggregate entity entities]
+                                unless unknown.empty?
+                                  raise TypeMismatch, "to: does not recognize #{unknown.sort.join(', ')}"
+                                end
+
+                                [hash[:aggregate], entity_identities(hash)]
+                              else
+                                [to, []]
+                              end
+
+        if aggregate.nil? || aggregate.to_s.empty?
+          raise TypeMismatch, "to: must name the receiving aggregate identity"
+        end
+        if entities.size != entity_depth
+          raise TypeMismatch,
+                "to: for an entity command needs #{entity_depth} entity " \
+                "#{entity_depth == 1 ? 'identity' : 'identities'} after the aggregate — got #{entities.size}"
+        end
+        if entities.any? { |identity| identity.nil? || identity.to_s.empty? }
+          raise TypeMismatch, "to: contains a blank entity identity"
+        end
+
+        Envelope.new(aggregate: aggregate, entities: entities)
+      end
+
+      # `with:` is deliberately strict. Compatibility-only calls still pass
+      # loose keyword arguments through the old addressing gate, but a caller
+      # choosing the explicit envelope cannot smuggle receiver identity back
+      # into the payload.
+      def payload(command, with:, legacy:)
+        if with && !legacy.empty?
+          raise TypeMismatch, "dispatch takes command facts in with:, not both with: and loose keyword arguments"
+        end
+
+        return legacy unless with
+        unless with.is_a?(Hash)
+          raise TypeMismatch, "with: must be a hash of command facts"
+        end
+
+        offered = with.transform_keys(&:to_sym)
+        declared = command.attributes.map { |attribute| attribute.name.to_sym }
+        unknown = (offered.keys - declared).sort
+        unless unknown.empty?
+          reading = declared.empty? ? "none" : declared.join(", ")
+          raise UnknownArgument,
+                RefusalWording.render("UnknownArgument", "unknown_args",
+                                      command: command.hecks_name, unknown: unknown.join(", "),
+                                      declared: reading)
+        end
+
+        absent = command.attributes.reject(&:optional?).map { |attribute| attribute.name.to_sym } - offered.keys
+        unless absent.empty?
+          reading = declared.empty? ? "none" : declared.join(", ")
+          raise AbsentArgument,
+                RefusalWording.render("AbsentArgument", "absent_args",
+                                      command: command.hecks_name, absent: absent.sort.join(", "),
+                                      declared: reading)
+        end
+
+        offered
+      end
+
+      def entity_identities(hash)
+        if hash.key?(:entities) && hash.key?(:entity)
+          raise TypeMismatch, "to: takes entity: or entities:, not both"
+        end
+
+        hash.key?(:entities) ? Array(hash[:entities]) : Array(hash[:entity])
+      end
+      private_class_method :entity_identities
+    end
+  end
+end

data/lib/hecks/runtime/saga_interpreter/correlation.rb

@@ -0,0 +1,97 @@
+require_relative "../value"
+
+module Hecks
+  module Runtime
+    class SagaInterpreter
+      # How a saga decides WHICH CONVERSATION an event belongs to — three
+      # tiers, each one a lesson.
+      module Correlation
+        private
+
+        # A DOTTED PATH NAMES THE SCALAR FIELD, rather than asking a value object
+        # to stand in for one. `correlates_by :end_to_end` would key a saga on
+        # the whole ExternalTransfer::EndToEndReference — and what a non-scalar
+        # correlation key even IS is representation-dependent (the object
+        # itself? its serialised text?). `:"end_to_end.value"` reads the one
+        # field with a single unambiguous rendering.
+        def saga_correlation(pm, event)
+          path  = pm.correlates_by.to_s.split(".")
+          # A LATER EVENT MAY ALREADY HOLD THE SCALAR. `reference.value` digs a
+          # value object's field out of a FRESH declaration (TransferRequested's
+          # `reference` IS a TransferReference) — but a downstream event this
+          # same value was smuggled through as a passthrough argument
+          # (AccountDebited's `reference:`, resolved by `dispatch_args` to the
+          # bare correlation string) carries it as a scalar already, with
+          # nothing left to dig. `"xfer-1".respond_to?(:[])` is true — String
+          # has its OWN `[]` (substring indexing) — so checking for keyed
+          # lookup explicitly, rather than "responds to `[]` at all", is what
+          # stops the second segment from being read as a symbol index into a
+          # string that has already arrived.
+          value = path.reduce(event.payload) do |held, segment|
+            held.is_a?(Hash) || held.is_a?(Value) ? held[segment.to_sym] : held
+          end
+          return value unless value.to_s.empty?
+
+          # THE STAMP — `deliver_saga_dispatch` marks its own event before this
+          # saga's next step ever asks, for a leg whose command declares
+          # NEITHER the correlation field itself nor the emitting aggregate's
+          # own reference key (the two tiers above). command_interpreter/
+          # argument_gate.rb names the old payload-only lookup "the weakest
+          # part of the gate" : a correlation key arriving on a command only
+          # because `correlation_keys` widens the undeclared-argument
+          # allow-list domain-wide. This is the additive fix — a leg that
+          # carries nothing correlation-shaped at all still correlates,
+          # because the saga that dispatched it already knows the answer.
+          # Keyed by `correlation_head`
+          # rather than a bare scalar so an event stamped by one saga cannot be
+          # misread by an unrelated one correlating on a different field.
+          stamped = event.correlation && event.correlation[pm.correlation_head.to_s]
+          return stamped unless stamped.nil? || stamped.to_s.empty?
+
+          # A SELF-REFERENCING LEG carries the correlation forward under its
+          # own emitting record's identity — `event.id`, not a field dug back
+          # out of the payload. This used to read `event.payload[own_key]`
+          # (`own_key` the aggregate's own reference-key convention, "wire",
+          # "transfer"), which only ever held a value because LEGACY dispatch
+          # left the self-addressing key riding along in the payload
+          # unfiltered. Routing separated from payload (`to:`/`with:`, the
+          # facade's own `Handle#run` always uses it) closed exactly that
+          # leak — correctly, since an addressing key is not a fact the
+          # payload should carry — which left this tier reading an empty
+          # Hash for any self-referencing leg with no OTHER declared
+          # attributes (`OnboardingCase.Clear`, `.Decline` — no `attribute`
+          # lines at all): the saga silently stopped advancing, forever, for
+          # exactly the leg this tier exists to correlate.
+          #
+          # `event.id` says the identical thing this tier always meant —
+          # "the record that just emitted this event, by its own identity" —
+          # and unlike a payload dig it is populated by the record itself,
+          # not by which dispatch convention the caller happened to use.
+          #
+          # GATED, still — a manually-dispatched command on a wholly
+          # UNRELATED aggregate can share an event NAME this pm happens to
+          # handle (`Drawer.Take` also emits "Taken", the same name a
+          # SAGA-DISPATCHED leg uses) with nothing this saga should read as
+          # its own conversation. What makes a leg genuinely
+          # self-referencing — the one fact worth trusting `event.id`
+          # for — is that `correlates_by`'s own head field IS this event's
+          # OWN aggregate's declared identity, not merely a same-shaped
+          # name: `OnboardingCase.identity_heads` really does include
+          # `:reference`, `correlates_by :"reference.value"`'s own head ;
+          # `Drawer.identity_heads` is `[:number]`, nowhere close.
+          self_identified?(pm, event) ? event.id : nil
+        end
+
+        def self_identified?(pm, event)
+          domain, bare_name = event.aggregate.to_s.split("::", 2)
+          return false unless bare_name
+
+          construct = @registry.bluebook(domain)&.aggregate(bare_name)
+          return false unless construct
+
+          construct.identity_heads.map(&:to_s).include?(pm.correlation_head.to_s)
+        end
+      end
+    end
+  end
+end

data/lib/hecks/runtime/saga_interpreter.rb

@@ -0,0 +1,301 @@
+require "json"
+require_relative "saga_interpreter/correlation"
+require_relative "../bluebook/process_manager"
+require_relative "errors"
+require_relative "reaction_invocation"
+require_relative "value"
+
+module Hecks
+  module Runtime
+    class SagaInterpreter
+      include Correlation
+
+      # The trigger lives on the declaration it triggers, not on the runtime that
+      # notices it — see ProcessManager::REFUSED.
+      REFUSED = Bluebook::ProcessManager::REFUSED
+
+      # A crash gets this many extra attempts before the procedure gives up
+      # and treats it as something to compensate for — see
+      # `deliver_saga_dispatch`'s own comment for why a crash isn't unwound
+      # on the first failure the way a domain refusal is.
+      MAX_DEFECT_RETRIES = 3
+
+      attr_reader :registry
+
+      def initialize(registry, door:)
+        @registry = registry
+        @door     = door
+      end
+
+      def advance(event, domain)
+        bluebook = @registry.bluebook(domain)
+        return unless bluebook
+
+        bluebook.process_managers.each do |pm|
+          begin_saga(pm, event, domain)
+          advance_saga(pm, event, domain)
+          end_saga(pm, event, domain)
+        end
+      end
+
+      private
+
+      # THE CHECKPOINT WRITE, shared by every mutation site below —
+      # holds `saga_mutex` across BOTH the in-memory Hash mutation and
+      # the persistence write (§7), not just the Hash mutation alone:
+      # two threads racing the SAME (process_manager, correlation) key
+      # could otherwise interleave their writes out of order, silently
+      # reordering a saga's own transition history — worse for the
+      # adapters with no locking of their own (Heki) than for Postgres.
+      # `deep_copy` guards against the exact shape of bug PR #175 itself
+      # already found once (over-freezing a live, still-mutated Hash) —
+      # never hand a persistence adapter the SAME object `advance_saga`/
+      # `unwind` go on to mutate in place; round-tripping through JSON
+      # is also what guarantees the value is safe for every adapter that
+      # itself calls `JSON.generate` on it.
+      def checkpoint(pm, correlation, instance, domain)
+        @registry.saga_persistence(domain).save_saga(
+          process_manager: pm.name, correlation: correlation,
+          state: instance[:state], memory: deep_copy(instance[:memory])
+        )
+      end
+
+      def deep_copy(hash) = JSON.parse(JSON.generate(hash), symbolize_names: true)
+
+      def begin_saga(pm, event, domain)
+        return unless event.name == pm.starts_on
+
+        correlation = saga_correlation(pm, event)
+        if correlation.to_s.empty?
+          @registry.saga_log << { process_manager: pm.name, on: event.name,
+                                  born: false, reason: "no #{pm.correlates_by} in the payload" }
+          return
+        end
+
+        created = @registry.saga_mutex.synchronize do
+          next false if @registry.saga_instances[pm.name].key?(correlation)
+
+          instance = { state: pm.states.first, memory: event.payload }
+          @registry.saga_instances[pm.name][correlation] = instance
+          checkpoint(pm, correlation, instance, domain)
+          true
+        end
+        return unless created
+
+        @registry.saga_log << { process_manager: pm.name, on: event.name,
+                                instance: correlation, born: true, state: pm.states.first }
+      end
+
+      # THE MUTEX COVERS ONLY THE STATE-CHECK-AND-MUTATE-AND-CHECKPOINT
+      # STEP, never the dispatch cascade that follows — `deliver_saga_
+      # dispatch` calls `@door.reenter`, which can recursively re-enter
+      # THIS SAME interpreter (a saga's own leg triggering another saga,
+      # or itself again) on the SAME thread, and `Mutex` is not
+      # reentrant: holding it across that call would deadlock the
+      # thread against itself the moment any real chain did that.
+      def advance_saga(pm, event, domain)
+        handler = pm.handler_for(event.name)
+        return unless handler
+
+        correlation = saga_correlation(pm, event)
+        return if correlation.to_s.empty?
+
+        record   = { process_manager: pm.name, on: event.name, instance: correlation }
+        instance = nil
+
+        advanced = @registry.saga_mutex.synchronize do
+          instance = @registry.saga_instances[pm.name][correlation]
+          unless instance
+            @registry.saga_log << record.merge(advanced: false, reason: "no conversation remembers #{correlation.inspect}")
+            next false
+          end
+          unless instance[:state] == handler.from_state
+            @registry.saga_log << record.merge(advanced: false,
+                                               reason:   "in #{instance[:state].inspect}, not #{handler.from_state.inspect}")
+            next false
+          end
+
+          instance[:state] = handler.to_state
+          checkpoint(pm, correlation, instance, domain)
+          true
+        end
+        return unless advanced
+
+        @registry.saga_log << record.merge(advanced: true, from: handler.from_state, to: handler.to_state)
+
+        handler.dispatches.each do |spec|
+          deliver_saga_dispatch(pm, spec, event, instance, correlation, domain)
+        end
+      end
+
+      def deliver_saga_dispatch(pm, spec, event, instance, correlation, domain)
+        args   = dispatch_args(pm, spec, event, instance, correlation)
+        record = { process_manager: pm.name, instance: correlation, dispatch: spec.command_name }
+
+        # THE RAW INPUTS `args` WAS RESOLVED FROM, captured alongside the
+        # result — never re-derived from history[:saga_instances] later
+        # (that only ever holds the FINAL memory, after every step has
+        # run; this dispatch's own memory, at the moment it actually
+        # fired, is a different fact for a saga whose memory keeps
+        # changing). `spec.with_spec.empty?` skipped: nothing declared
+        # to check, a tautological pass, the same reason a command with
+        # no givens/from is skipped by lifecycle_guard_and_given_
+        # violations_are_refused.
+        unless spec.with_spec.to_a.empty?
+          @registry.saga_dispatch_log << { process_manager: pm.name, instance: correlation, dispatch: spec.command_name,
+                                            on: event.name, correlation_head: pm.correlation_head,
+                                            event_payload: event.payload, memory: Value.materialize(instance[:memory]),
+                                            with_spec: spec.with_spec, args: args }
+        end
+
+        if @door.reaction_depth_reached?
+          # THE CEILING IS NOT A DOMAIN DECISION EITHER — same reasoning as a
+          # crash, below — but unlike a crash there is nothing ambiguous
+          # about it: the leg unambiguously did not run, so it unwinds
+          # exactly like a refusal instead of stranding the instance for a
+          # human to notice. `unwind`'s own state guard (it moves to its
+          # `to_state` before its dispatches run) is what keeps this from
+          # looping if the ceiling is still in effect when the compensating
+          # leg tries to dispatch — that leg's own attempt hits this same
+          # branch, calls `unwind` again, and finds the instance already
+          # past `from_state`.
+          @registry.saga_log << record.merge(delivered: false,
+                                             reason:    "reaction depth #{@door.max_reaction_depth} reached")
+          unwind(pm, event, instance, correlation, domain)
+          return
+        end
+
+        attempt = 0
+        begin
+          invocation = ReactionInvocation.build(
+            registry:        @registry,
+            verb:            qualified(spec.command_name, domain),
+            projected:       args,
+            explicit:        ReactionInvocation.projection_declared?(spec),
+            passthrough:     [pm.correlation_head],
+            source_receiver: { aggregate: event.aggregate, identity: event.id }
+          )
+          @door.reenter(qualified(spec.command_name, domain),
+                        saga_correlation: { pm.correlation_head.to_s => correlation }, **invocation)
+          @registry.saga_log << record.merge(delivered: true)
+        rescue *DOMAIN_REFUSALS => error
+          # Same rule as the policy interpreter : a refusal by the target is
+          # a recorded outcome, and the leg that raised it UNWINDS — see
+          # `unwind`'s own comment for why the procedure runs its
+          # compensation here rather than leaving the money (or whatever
+          # else a leg moved) sitting out.
+          @registry.saga_log << record.merge(delivered: false, reason: error.message)
+          unwind(pm, event, instance, correlation, domain)
+        rescue StandardError => error
+          # A DEFECT, not a refusal — see PolicyInterpreter#deliver's own
+          # comment for the full reasoning: the same DOMAIN_REFUSALS split,
+          # and the same "the triggering command already succeeded and
+          # persisted by the time this runs" fact that makes catching it
+          # here safe rather than reckless.
+          #
+          # UNLIKE a refusal, a crash is not a decision the domain made, so
+          # it does not unwind on the first failure — MAX_DEFECT_RETRIES
+          # gives a transient failure (a DB timeout, a race, a cold start)
+          # a chance to clear on its own, retrying the identical dispatch,
+          # before this is treated as something to compensate for. Every
+          # attempt is recorded distinguishably (`defect: true`, the
+          # error's own class); only once retries are exhausted is it
+          # warned to STDERR and unwound — tagged `defect_compensated:
+          # true` rather than folded into an ordinary refusal's shape, so
+          # the log never misrepresents a crash as a decision the domain
+          # made. Compensating a genuinely stuck leg beats leaving it for a
+          # human to find; misrepresenting *why* it compensated is what the
+          # tag is for.
+          attempt += 1
+          if attempt <= MAX_DEFECT_RETRIES
+            @registry.saga_log << record.merge(delivered: false, reason: error.message,
+                                               defect: true, error_class: error.class.name,
+                                               attempt: attempt, retrying: true)
+            retry
+          end
+
+          warn "[hecks] defect in saga #{pm.name} — instance #{correlation.inspect} " \
+               "dispatching #{spec.command_name} after #{attempt} attempts: #{error.class}: #{error.message}"
+          @registry.saga_log << record.merge(delivered: false, reason: error.message, defect: true,
+                                             error_class: error.class.name, defect_compensated: true)
+          unwind(pm, event, instance, correlation, domain)
+        end
+      end
+
+      # A refused leg UNWINDS — the procedure runs the leg declared `on :refused`,
+      # which is where the compensation lives. So does a leg that hit the
+      # reaction-depth ceiling, and so does a leg that crashed and stayed
+      # crashing through MAX_DEFECT_RETRIES — see `deliver_saga_dispatch`'s own
+      # comments for why each of those is safe to route here.
+      #
+      # Until this existed a refusal was RECORDED and nothing else happened. The
+      # wire's thousand was taken from the source, refused by the destination, and
+      # sat nowhere until a human dispatched the reversal by hand ; banking's
+      # settlement left a debit standing with no credit and no reversal at all.
+      # Both bluebooks had written the compensating leg. Nothing armed it.
+      #
+      # A compensation that is itself refused does NOT unwind again, and needs no
+      # flag to stop it: the state moves to the compensating leg's to_state BEFORE
+      # its dispatches run, so a second refusal finds the instance no longer in
+      # from_state and records that instead. The check is the guard.
+      def unwind(pm, event, instance, correlation, domain)
+        handler = pm.handler_for(REFUSED)
+        return unless handler && instance
+
+        record = { process_manager: pm.name, on: REFUSED, instance: correlation }
+
+        # Same non-reentrancy reasoning as `advance_saga`'s own comment —
+        # the mutex covers only the check-and-mutate-and-checkpoint step.
+        advanced = @registry.saga_mutex.synchronize do
+          unless instance[:state] == handler.from_state
+            @registry.saga_log << record.merge(advanced: false,
+                                               reason:   "in #{instance[:state].inspect}, not #{handler.from_state.inspect}")
+            next false
+          end
+
+          instance[:state] = handler.to_state
+          checkpoint(pm, correlation, instance, domain)
+          true
+        end
+        return unless advanced
+
+        @registry.saga_log << record.merge(advanced: true, from: handler.from_state, to: handler.to_state)
+
+        handler.dispatches.each do |spec|
+          deliver_saga_dispatch(pm, spec, event, instance, correlation, domain)
+        end
+      end
+
+      def dispatch_args(pm, spec, event, instance, correlation)
+        ReactionInvocation.resolve_mapping(
+          with_spec: spec.with_spec,
+          scopes:    [["current event payload", event.payload], ["opening event memory", instance[:memory]]],
+          bindings:  { pm.correlation_head => correlation },
+          label:     "#{pm.name}'s dispatch #{spec.command_name}"
+        )
+      end
+
+      def qualified(command_name, domain)
+        command_name.include?("::") ? command_name : "#{domain}::#{command_name}"
+      end
+
+      def end_saga(pm, event, domain)
+        return unless event.name == pm.ends_on
+
+        correlation = saga_correlation(pm, event)
+        return if correlation.to_s.empty?
+
+        ended = @registry.saga_mutex.synchronize do
+          next false unless @registry.saga_instances[pm.name].delete(correlation)
+
+          @registry.saga_persistence(domain).delete_saga(process_manager: pm.name, correlation: correlation)
+          true
+        end
+        return unless ended
+
+        @registry.saga_log << { process_manager: pm.name, on: event.name,
+                                instance: correlation, ended: true }
+      end
+    end
+  end
+end