hecks 5.0.0 → 7.0.0

data/lib/hecks/runtime/registry.rb

@@ -7,6 +7,9 @@ require_relative "registry/read_repository"
 require_relative "registry/verification"
 require_relative "registry/saga_persistence"
 require_relative "registry/world_defaults"
+require_relative "registry/world_names"
+require_relative "registry/context_maps"
+require_relative "registry/adapter_capabilities"
 require_relative "outbox"
 require_relative "../naming"
 
@@ -24,13 +27,21 @@ module Hecks
       include Verification
       include SagaPersistence
       include WorldDefaults
+      include WorldNames
+      include AdapterCapabilities
       include Providers
       include Merging
+      include ContextMaps
       include ReadRepository
 
       # The thread-local key under which open reaction collections are kept.
       REACTION_SINKS = :hecks_reaction_sinks
 
+      # Guards every registry's reaction log and its outcome index, which dispatching threads all
+      # append to. One lock serves every registry: each hold is a single append, so the contention
+      # is negligible.
+      REACTION_LOCK = Mutex.new
+
       attr_reader :root, :saga_mutex
 
       # What a boot gathers, and what a dispatch produces; each is held by `Declarations` or
@@ -38,7 +49,7 @@ module Hecks
       def_delegators :@declared, :bluebooks, :hecksagons, :ports, :adapters, :worlds, :translations,
                      :bluebook_sources, :pending_privacy_markings
       def_delegators :@state, :event_log, :reaction_log, :saga_log, :saga_instances,
-                     :saga_dispatch_log, :policy_dispatch_log
+                     :saga_dispatch_log, :policy_dispatch_log, :cross_domain_log
 
       # @param root [String, nil] the booting project's root directory, the base
       #   a shared ports/adapters root and a `.world`'s own relative paths resolve
@@ -47,7 +58,8 @@ module Hecks
         @root         = root
         # Recorded at hecksagon-build time (AggregateModule#mark_sensitive), Loader.boot's
         # post-dispatch step turns each pending privacy marking into a real Privacy::Marking.Mark,
-        # idempotently. `resolved_eras` and `superseded_eras` are eager, not lazy, so no two
+        # idempotently. `resolved_eras`, `superseded_eras` and `unminted_eras` are eager, not lazy,
+        # so no two
         # dispatching threads race to create them; all writes still happen at boot,
         # single-threaded (EraResolver.check!).
         @declared     = Declarations.empty
@@ -58,6 +70,7 @@ module Hecks
         @saga_mutex   = Mutex.new
         @repositories = {}
         @projection_repositories = {}
+        @saga_persistence = {}
         # Eager: CapabilityGraph.new only stores the registry reference, and eager
         # construction avoids the same first-access race as `resolved_eras` while
         # keeping one instance per registry.
@@ -65,7 +78,6 @@ module Hecks
         # Guards only the lazy per-domain resolution inside @saga_persistence. Must not reuse
         # @saga_mutex: checkpoint calls saga_persistence(domain) from inside
         # @saga_mutex.synchronize, and Mutex is not reentrant.
-        @saga_persistence = {}
         @saga_persistence_mutex = Mutex.new
         @outbox = Outbox::Relay.new(self)
       end
@@ -74,10 +86,10 @@ module Hecks
       # a Dispatcher attaches the interpreters that let it deliver (see Runtime::Outbox).
       attr_reader :outbox
 
-      # Stays open for the life of the registry, keyed by chapter name, so a chapter split
+      # Stays open for the life of the registry, keyed by bluebook name, so a bluebook split
       # across several files (language/bluebook/*.bluebook) accumulates into one builder.
       #
-      # @param name [String, Symbol] the chapter name the builder accumulates
+      # @param name [String, Symbol] the bluebook name the builder accumulates
       #   declarations for
       # @yield the block that mints a fresh builder, called only the first time
       #   `name` is asked for
@@ -91,33 +103,32 @@ module Hecks
       # Boot-time-only, single-threaded: every add_* below runs from Hecks.collect while a
       # .bluebook/.hecksagon/.world file is being Kernel.loaded, strictly during Loader.boot,
       # before dispatcher_for hands this registry to a live, multi-threaded caller.
-      # rubocop:disable Hecks/ThreadSharedIvarMutation
-      # Registers a loaded chapter, keyed by its own declared name.
+      # Registers a loaded bluebook, keyed by its own declared name.
       #
-      # @param item [Bluebook::Chapter] the loaded, judged chapter
-      # @return [Bluebook::Chapter] `item`, unchanged
-      def add_bluebook(item) = @declared.bluebooks[item.name] = item
+      # @param item [Bluebook::Declaration] the loaded, judged bluebook
+      # @return [Bluebook::Declaration] `item`, unchanged
+      def add_bluebook(item) = @declared.store(:bluebooks, item.name, item)
 
-      # Drops a chapter and the open builder and source record that accumulated it, so the
-      # chapter can be loaded again from nothing.
+      # Drops a bluebook and the open builder and source record that accumulated it, so the
+      # bluebook can be loaded again from nothing.
       #
-      # @param name [String, Symbol] the chapter name to forget
+      # @param name [String, Symbol] the bluebook name to forget
       # @return [void]
-      def forget_chapter(name)
-        @declared.bluebooks.delete(name.to_s)
-        @declared.bluebook_builders.delete(name.to_s)
-        @declared.bluebook_sources.delete(name.to_s)
+      def forget_bluebook(name)
+        @declared.remove(:bluebooks, name.to_s)
+        @declared.remove(:bluebook_builders, name.to_s)
+        @declared.remove(:bluebook_sources, name.to_s)
       end
 
-      # Tracks which .bluebook file(s) contributed to a chapter name (a boot-time loading
+      # Tracks which .bluebook file(s) contributed to a bluebook name (a boot-time loading
       # fact, never Rust-mirrored) so refuse_cross_package_bluebook_merge! can catch two
       # unrelated packages accumulating into the same name by coincidence.
       #
-      # @param name [String, Symbol] the chapter name the file contributed to
+      # @param name [String, Symbol] the bluebook name the file contributed to
       # @param path [String] the `.bluebook` file that declared it
-      # @return [Array<String>] every path recorded for that chapter, `path` last
+      # @return [Array<String>] every path recorded for that bluebook, `path` last
       def record_bluebook_source(name, path)
-        (@declared.bluebook_sources[name.to_s] ||= []) << path
+        @declared.record_source(name.to_s, path)
       end
 
       # Merges into any wiring already registered for the domain rather than replacing it,
@@ -127,39 +138,47 @@ module Hecks
       # @return [void]
       def add_hecksagon(item)
         existing = @declared.hecksagons[item.domain]
-        @declared.hecksagons[item.domain] = existing ? merge_hecksagons(existing, item) : item
+        @declared.store(:hecksagons, item.domain, existing ? merge_hecksagons(existing, item) : item)
         mark_bounded(item.domain) if item.bounded?
       end
 
       # Marks `name` as a bounded context — called automatically by `attaches`, and by
       # `add_hecksagon` when the block itself declared `bounded`.
-      # A bounded chapter wraps in its own module (no Object shortcut)
+      # A bounded bluebook wraps in its own module (no Object shortcut)
       # and must have a `translates` ACL or boot refuses.
       #
-      # @param name [String, Symbol] the chapter name to mark bounded
+      # @param name [String, Symbol] the bluebook name to mark bounded
       # @return [void]
       def mark_bounded(name)
-        @declared.bounded_chapters[name.to_s] = true
+        @declared.store(:bounded_bluebooks, name.to_s, true)
       end
 
       # Says whether `name` is a bounded context — attached via `attaches`, or a consumer
-      # chapter that declared `bounded` on its own hecksagon.
+      # bluebook that declared `bounded` on its own hecksagon.
       #
-      # @param name [String, Symbol] the chapter name to check
-      # @return [Boolean] whether that chapter is bounded
-      def bounded?(name) = @declared.bounded_chapters[name.to_s] ? true : false
+      # @param name [String, Symbol] the bluebook name to check
+      # @return [Boolean] whether that bluebook is bounded
+      def bounded?(name) = @declared.bounded_bluebooks[name.to_s] ? true : false
 
       # Registers a loaded port, keyed by its own declared name.
       #
       # @param item [Bluebook::Port, Bluebook::DomainPort] the loaded port
       # @return [Bluebook::Port, Bluebook::DomainPort] `item`, unchanged
-      def add_port(item) = @declared.ports[item.name] = item
+      def add_port(item) = @declared.store(:ports, item.name, item)
 
       # Registers a loaded adapter, keyed by its own declared name.
       #
       # @param item [Bluebook::Adapter] the loaded, judged adapter
       # @return [Bluebook::Adapter] `item`, unchanged
-      def add_adapter(item) = @declared.adapters[item.name] = item
+      def add_adapter(item) = @declared.store(:adapters, item.name, item)
+
+      # Finds the plugin adapters that say they answer a query.
+      #
+      # @param question [String] the qualified query, such as `"Calendar::Event.Occurrences"`
+      # @return [Array<Bluebook::Adapter>] every loaded plugin naming it, by name
+      def plugins_answering(question)
+        adapters.values.select { |adapter| adapter.answered_queries.include?(question) }.sort_by(&:name)
+      end
 
       # Merges into any world already registered for the domain, the same shape as
       # add_hecksagon. Settings merge shallow, keyed by verb (and "verb:adapter"); an
@@ -170,7 +189,7 @@ module Hecks
       # @return [void]
       def add_world(item)
         existing = @declared.worlds[item.domain]
-        @declared.worlds[item.domain] = existing ? merge_worlds(existing, item) : item
+        @declared.store(:worlds, item.domain, existing ? merge_worlds(existing, item) : item)
       end
 
       # Registers a loaded translation.
@@ -178,7 +197,7 @@ module Hecks
       # @param item [Bluebook::Translation] the loaded, judged translation
       # @return [Array<Bluebook::Translation>] every translation registered so far,
       #   `item` last
-      def add_translation(item) = @declared.translations << item
+      def add_translation(item) = @declared.append(:translations, item)
 
       # Declares one attribute of a domain's aggregate sensitive, called from a terminal
       # has_<category>(readable_by:). Recorded, not dispatched: Loader.boot's
@@ -193,20 +212,22 @@ module Hecks
       # @param readable_by [String] the Governance role a read must hold, unredacted
       # @return [void]
       def add_pending_privacy_marking(domain:, attribute_path:, category:, readable_by:)
-        @declared.pending_privacy_markings << { domain: domain, attribute_path: attribute_path,
-                                                category: category, readable_by: readable_by }
+        @declared.append(:pending_privacy_markings, { domain: domain, attribute_path: attribute_path,
+                                                      category: category, readable_by: readable_by })
       end
-      # rubocop:enable Hecks/ThreadSharedIvarMutation
 
       # `resolved_eras` is {domain name => era ordinal} resolved by the boot-time era gate;
       # `superseded_eras` is the domain name -> the ordinal that superseded this boot's own era,
-      # for an old checkout only. Stood up eagerly; plain readers, not memoizers.
-      def_delegators :@declared, :resolved_eras, :superseded_eras
+      # for an old checkout only. `unminted_eras` is the domain name -> the latest held ordinal, set
+      # when this boot's shape matches no held era and no mint was requested: the copy reads and
+      # refuses writes. `behind_eras` is the same, for a shape a recorded move or edge leads to from
+      # the latest held era. Stood up eagerly; plain readers, not memoizers.
+      def_delegators :@declared, :resolved_eras, :superseded_eras, :unminted_eras, :behind_eras
 
-      # Finds a loaded chapter by name.
+      # Finds a loaded bluebook by name.
       #
-      # @param name [String, Symbol] the chapter's declared name
-      # @return [Bluebook::Chapter, nil] the chapter, or nil if none is registered
+      # @param name [String, Symbol] the bluebook's declared name
+      # @return [Bluebook::Declaration, nil] the bluebook, or nil if none is registered
       #   under `name`
       def bluebook(name)  = @declared.bluebooks[name.to_s]
 
@@ -224,10 +245,23 @@ module Hecks
       #   registered under `name`
       def world(name)     = @declared.worlds[name.to_s]
 
-      # Every verb every loaded chapter declares, sorted.
+      # The first bluebook loaded: a one-domain boot's own bluebook.
       #
-      # @return [Array<String>] every declared verb, across every loaded chapter
-      def verbs = @declared.bluebooks.values.flat_map(&:verbs).sort
+      # @return [Bluebook::Declaration, nil] the first loaded bluebook, or nil when none loaded
+      def first_bluebook = @declared.bluebooks.values.first
+
+      # The name of the first bluebook loaded: a one-domain boot's own domain.
+      #
+      # @return [String, nil] the name, or nil when none loaded
+      def first_domain_name = first_bluebook&.name
+
+      # Every verb every loaded bluebook declares, sorted.
+      #
+      # @return [Array<String>] every declared verb, across every loaded bluebook
+      def verbs
+        declarations = @declared.bluebooks.values
+        declarations.flat_map(&:verbs).sort
+      end
 
       # Resolves and memoizes `aggregate`'s authoritative repository.
       #
@@ -253,10 +287,8 @@ module Hecks
       # @param record [Hash{Symbol => Object}] the reaction's outcome
       # @param event [String, Integer, nil] identity of the event instance the reaction answered
       # @return [void]
-      # rubocop:disable-next Hecks/ThreadSharedIvarMutation
       def log_reaction(record, event: nil)
-        @state.reaction_log << record
-        @state.reaction_events[record] = event if event
+        REACTION_LOCK.synchronize { @state.log_reaction(record, event) }
         Array(Thread.current[REACTION_SINKS]).each { |sink| sink << record }
       end
 
@@ -285,17 +317,16 @@ module Hecks
       # what booting the files produced (bluebooks, hecksagons, ports, adapters, worlds,
       # resolved eras) untouched.
       #
-      # Repositories are dropped, not emptied, so a fresh Memory adapter starts empty while
-      # a durable one still sees what it persisted. Single-threaded caller only
+      # Repositories are dropped from the registry's maps, so a fresh Memory adapter starts empty
+      # while a durable one still sees what it persisted. Single-threaded caller only
       # (Behaviors::Expectations.run_one runs one test at a time).
       #
       # @return [Runtime::Registry] self
-      # rubocop:disable-next Hecks/ThreadSharedIvarMutation
       def reset_runtime_state!
         @state.clear
-        @repositories = {}
-        @projection_repositories = {}
-        @outbox.log.clear
+        @repositories.clear
+        @projection_repositories.clear
+        @outbox.clear_log
         rehydrate_sagas!
         self
       end

data/lib/hecks/runtime/row_sweep.rb

@@ -0,0 +1,104 @@
+require_relative "../naming"
+require_relative "errors"
+require_relative "query_interpreter"
+require_relative "refusal_wording"
+
+module Hecks
+  module Runtime
+    # One command sent once per row a declared query answers: what a `for_each` policy and a
+    # bulk run (ADR 0125) share. It reads the rows, says which key of the command addresses a
+    # row, and records one row's delivery or refusal; who sends the command is the caller's.
+    class RowSweep
+      # @param registry [Runtime::Registry] the booted registry the query and command resolve in
+      def initialize(registry)
+        @registry = registry
+      end
+
+      # Runs a declared query and answers its rows.
+      #
+      # @param domain [String] the domain the query's aggregate belongs to
+      # @param aggregate [Bluebook::Aggregate] the aggregate declaring the query
+      # @param query_name [String] the query's name
+      # @param args [Hash{Symbol => Object}] the query's arguments
+      # A query that declares `cursor` answers one page per ask, so every page is read: a sweep
+      # reaches every row the query selects, not only its first `limit`.
+      #
+      # @return [Array<Hash{Symbol => Object}>] each row's state with `:id` merged in
+      def rows(domain, aggregate, query_name, args)
+        interpreter = QueryInterpreter.new(@registry)
+        return Array(interpreter.call(domain, aggregate, query_name, args)) unless aggregate.query(query_name)&.cursor
+
+        every_page(interpreter, domain, aggregate, query_name, args)
+      end
+
+      # The rows of every page of a cursor query, in query order.
+      def every_page(interpreter, domain, aggregate, query_name, args)
+        rows = []
+        after = args[:after]
+        loop do
+          page = interpreter.page(domain, aggregate, query_name, args.merge(after: after))
+          rows.concat(page[:rows])
+          after = page[:after]
+          return rows unless after
+        end
+      end
+
+      # The loaded aggregate a query belongs to.
+      #
+      # @param domain [String] the domain the aggregate belongs to
+      # @param aggregate_name [String] the aggregate's name
+      # @param verb [String] the spelling a refusal names, such as the policy's `for_each`
+      # @return [Bluebook::Aggregate] the aggregate
+      # @raise [Runtime::UnknownVerb] if the domain or aggregate is not loaded
+      def query_aggregate(domain, aggregate_name, verb:)
+        bluebook = @registry.bluebook(domain) ||
+                   raise(UnknownVerb, RefusalWording.render_site("UnknownVerb", "no_domain", domain: domain, verb: verb))
+        bluebook.aggregate(aggregate_name) ||
+          raise(UnknownVerb, RefusalWording.render_site("UnknownVerb", "no_aggregate",
+                                                        domain: domain, aggregate: aggregate_name))
+      end
+
+      # Resolves `target` back to its declared command and asks it how a row of `aggregate_name`
+      # addresses it. Raises rather than guessing: an unaddressable target is an authoring mistake.
+      #
+      # @param target [String] the command's verb, `"Domain::Aggregate.Command"`
+      # @param aggregate_name [String] the aggregate whose rows are swept
+      # @param label [String] how a refusal names `target`
+      # @return [Symbol] the argument a row's id fills
+      # @raise [Runtime::UnknownVerb] if `target` names no declared command
+      # @raise [ArgumentError] if the command cannot be addressed by a row of `aggregate_name`
+      def addressing_key_for(target, aggregate_name, label: "the target")
+        key = target_command(target, label: label).addressing_key_for(aggregate_name)
+        return key if key
+
+        raise ArgumentError,
+              "#{target} cannot be addressed by a row of #{aggregate_name} — it declares no self-reference to " \
+              "#{aggregate_name} and no reference-typed attribute targeting it"
+      end
+
+      # The declared command `target` names.
+      #
+      # @param target [String] the command's verb, `"Domain::Aggregate.Command"`
+      # @param label [String] how a refusal names `target`
+      # @return [Bluebook::Command] the command
+      # @raise [Runtime::UnknownVerb] if `target` names no declared command
+      def target_command(target, label: "the target")
+        domain, aggregate_name, command_name = Naming.split_verb(target)
+        command = @registry.bluebook(domain)&.aggregate(aggregate_name)&.command(command_name)
+        command or raise UnknownVerb, "#{label} #{target.inspect} does not resolve to a declared command"
+      end
+
+      # Sends one row and records how it went: `delivered: true`, or the refusal's message.
+      #
+      # @param record [Hash{Symbol => Object}] the row's record so far, such as `{ for_row: id }`
+      # @yield sends the command for this row
+      # @return [Hash{Symbol => Object}] `record` with `delivered:` and, when refused, `reason:`
+      def deliver(record)
+        yield
+        record.merge(delivered: true)
+      rescue *DOMAIN_REFUSALS => e
+        record.merge(delivered: false, reason: e.message)
+      end
+    end
+  end
+end

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

@@ -16,8 +16,9 @@ module Hecks
         def record_compensation(leg, spec, ledger)
           return unless spec.compensates && !ledger.recorded
 
-          resolved = dispatch_args(leg.process_manager, spec.compensates, leg.event, leg.instance, leg.correlation)
-          leg.instance[:completed_compensations] << { command_name: spec.compensates.command_name, args: resolved }
+          compensates = spec.compensates
+          resolved = dispatch_args(leg.process_manager, compensates, leg.event, leg.instance, leg.correlation)
+          leg.instance[:completed_compensations] << { command_name: compensates.command_name, args: resolved }
           checkpoint_leg(leg)
           ledger.recorded = true
         end
@@ -44,7 +45,7 @@ module Hecks
         # failure — `compensation_failed: true` tags a refused compensation
         # distinctly rather than as an ordinary failed delivery.
         def deliver_derived_compensation(leg, entry)
-          record = { process_manager: leg.process_manager.name, instance: leg.correlation,
+          record = { process_manager: leg.saga_name, instance: leg.correlation,
                      dispatch: entry[:command_name] }
           attempts = 0
           loop do
@@ -61,6 +62,8 @@ module Hecks
         # One try. Answers nil once the compensation has settled (delivered or refused), or the
         # crash that stopped it.
         def compensate_once(leg, entry, record)
+          return refuse_compensation_at_depth_ceiling(record) if @dispatcher.reaction_depth_reached?
+
           reenter_command(leg, entry[:command_name], entry[:args], explicit: true, source_receiver: nil)
           @registry.saga_log << record.merge(delivered: true, compensation: true)
           nil
@@ -72,6 +75,14 @@ module Hecks
           e
         end
 
+        # A compensation is a reaction like any other: past the cascade limit it is recorded
+        # undelivered, never run.
+        def refuse_compensation_at_depth_ceiling(record)
+          @registry.saga_log << record.merge(delivered: false, compensation: true, compensation_failed: true,
+                                             reason: "reaction depth #{@dispatcher.max_reaction_depth} reached")
+          nil
+        end
+
         def log_compensation_retry(record, error, attempt)
           @registry.saga_log << record.merge(delivered: false, reason: error.message, compensation: true,
                                              defect: true, error_class: error.class.name,
@@ -79,7 +90,7 @@ module Hecks
         end
 
         def abandon_compensation(leg, entry, record, error, attempt)
-          warn "[hecks] defect compensating saga #{leg.process_manager.name} — instance #{leg.correlation.inspect} " \
+          warn "[hecks] defect compensating saga #{leg.saga_name} — instance #{leg.correlation.inspect} " \
                "dispatching #{entry[:command_name]} after #{attempt} attempts: #{error.class}: #{error.message}"
           @registry.saga_log << record.merge(delivered: false, reason: error.message, compensation: true,
                                              defect: true, error_class: error.class.name, compensation_failed: true)

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

@@ -29,10 +29,19 @@ module Hecks
         # Strings respond to `[]`, so test for Hash/Value explicitly rather than
         # `respond_to?(:[])`.
         def payload_correlation(process_manager, event)
-          path = process_manager.correlates_by.to_s.split(".")
-          path.reduce(event.payload) do |held, segment|
-            held.is_a?(Hash) || held.is_a?(Value) ? held[segment.to_sym] : held
+          path = own_correlation_path(process_manager, event)
+          held = path.reduce(event.payload) do |current, segment|
+            current.is_a?(Hash) || current.is_a?(Value) ? current[segment.to_sym] : current
           end
+          sole_field_scalar(held)
+        end
+
+        # A path ending at a single-field value object reads that object's one field, so a bare
+        # `Thing.id` keys by the same scalar `Thing.id.value` does.
+        def sole_field_scalar(held)
+          return held unless held.is_a?(Value)
+
+          Value.materialize_unwrapped(held)
         end
 
         # The stamp `deliver_saga_dispatch` puts on its own event, for legs whose command
@@ -42,6 +51,19 @@ module Hecks
           event.correlation && event.correlation[process_manager.correlation_head.to_s]
         end
 
+        # `Message.id` (what a bare `correlates_by Message` resolves to) names the emitting
+        # aggregate's own id: the path is walked without its leading aggregate name.
+        def own_correlation_path(process_manager, event)
+          path = process_manager.correlates_by.to_s.split(".")
+          path.size > 1 && path.first == emitting_aggregate_name(event) ? path.drop(1) : path
+        end
+
+        # The emitting aggregate's bare name, without its domain module.
+        def emitting_aggregate_name(event)
+          _domain, bare_name = event.aggregate.to_s.split("::", 2)
+          bare_name
+        end
+
         def self_identified?(process_manager, event)
           domain, bare_name = event.aggregate.to_s.split("::", 2)
           return false unless bare_name
@@ -49,6 +71,10 @@ module Hecks
           construct = @registry.bluebook(domain)&.aggregate(bare_name)
           return false unless construct
 
+          head, *rest = process_manager.correlates_by.to_s.split(".")
+          # The emitting aggregate's own id, spelled with its name: `Message.id`.
+          return rest == ["id"] if head == bare_name
+
           construct.identity_heads.map(&:to_s).include?(process_manager.correlation_head.to_s)
         end
       end

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

@@ -17,9 +17,9 @@ module Hecks
         # Delivers one command a saga leg dispatches: resolves its arguments, logs the inputs they
         # were bound from, then runs the checkpoint/dispatch/compensation ledger protocol with the
         # retries a crash gets.
-        # rubocop:disable-next Metrics/ParameterLists -- spec/runtime/reaction_invocation_spec.rb calls it by name
-        def deliver_saga_dispatch(process_manager, spec, event, instance, correlation, domain)
-          leg    = Leg.new(process_manager, event, domain, correlation, nil, instance)
+        def deliver_saga_dispatch(process_manager, spec, event, instance, correlation, domain, dispatch_key: nil)
+          leg = Leg.new(process_manager, event, domain, correlation, nil, instance)
+          leg.dispatch_key = dispatch_key
           args   = dispatch_args(process_manager, spec, event, instance, correlation)
           record = { process_manager: process_manager.name, instance: correlation, dispatch: spec.command_name }
 
@@ -36,8 +36,8 @@ module Hecks
           process_manager = leg.process_manager
           @registry.saga_dispatch_log << { process_manager: process_manager.name, instance: leg.correlation,
                                            dispatch: spec.command_name,
-                                           on: leg.event.name, correlation_head: process_manager.correlation_head,
-                                           event_payload: leg.event.payload,
+                                           on: leg.event_name, correlation_head: process_manager.correlation_head,
+                                           event_payload: leg.event_payload,
                                            memory: Value.materialize(leg.instance[:memory]),
                                            with_spec: spec.with_spec, args: args }
         end
@@ -83,7 +83,7 @@ module Hecks
         def reenter_dispatch(leg, spec, args)
           reenter_command(leg, spec.command_name, args,
                           explicit:        ReactionInvocation.projection_declared?(spec),
-                          source_receiver: { aggregate: leg.event.aggregate, identity: leg.event.id })
+                          source_receiver: leg.event_source)
         end
 
         # A refusal by the target is a recorded outcome, and the leg
@@ -95,14 +95,16 @@ module Hecks
           nil
         end
 
-        # Dispatches `command_name` through the dispatcher, stamped with this saga's correlation.
+        # Dispatches `command_name` through the dispatcher, stamped with this saga's correlation
+        # and, for a leg's own dispatch, its `dispatch_key`.
         def reenter_command(leg, command_name, projected, explicit:, source_receiver:)
-          head = leg.process_manager.correlation_head
+          head = leg.correlation_head
           verb = qualified(command_name, leg.domain)
           invocation = ReactionInvocation.build(registry: @registry, verb: verb, projected: projected,
                                                 explicit: explicit, passthrough: [head],
                                                 source_receiver: source_receiver)
-          @dispatcher.reenter(verb, saga_correlation: { head.to_s => leg.correlation }, **invocation)
+          stamp = { head.to_s => leg.correlation }
+          @dispatcher.reenter(verb, saga_correlation: stamp, dispatch_key: leg.dispatch_key, **invocation)
         end
 
         # Unlike a refusal, a crash isn't a domain decision, so it
@@ -117,7 +119,7 @@ module Hecks
         # `defect_compensated: true` tags an exhausted retry distinctly, so the log never
         # misrepresents a crash as a decision the domain made.
         def abandon_dispatch(leg, spec, record, error, attempt)
-          warn "[hecks] defect in saga #{leg.process_manager.name} — instance #{leg.correlation.inspect} " \
+          warn "[hecks] defect in saga #{leg.saga_name} — instance #{leg.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)
@@ -137,7 +139,7 @@ module Hecks
         # `command_name`'s shape — unlike a policy's explicit `target_domain`
         # (set by `across`), a saga's `dispatch`/`compensates` has no such
         # field, and every command a saga fires lands inside its own
-        # bluebook chapter.
+        # bluebook.
         def qualified(command_name, domain)
           "#{domain}::#{command_name}"
         end

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

@@ -38,7 +38,7 @@ module Hecks
         end
 
         def end_saga(process_manager, event, domain)
-          return unless event.name == process_manager.ends_on
+          return unless process_manager.ending_events.include?(event.name)
 
           correlation = saga_correlation(process_manager, event)
           return if correlation.to_s.empty?