saga_forge 0.1.0

data/lib/saga_forge/definition.rb

@@ -0,0 +1,268 @@
+module SagaForge
+  # Immutable boot-compiled metadata for one saga class: the chain, the
+  # event→state stall table, handler registry, compensation catalog.
+  class Definition
+    START = :__start__
+
+    Handler = Struct.new(:state, :event, :block, :compensate, :timeout, :on_timeout, :retry_policy)
+
+    attr_reader :klass, :handlers_by_event, :states, :terminal_states, :compensations, :start_event
+
+    def self.compile(klass) = new(klass).freeze
+
+    def initialize(klass)
+      @klass = klass
+      @handlers_by_event = {}
+      @compensations = {}
+      @terminal_states = []
+      during_states = []
+      start_decls = []
+
+      klass.declarations.each do |d|
+        case d[:kind]
+        when :start
+          start_decls << d
+          register_handler(START, d)
+        when :during
+          during_states << d[:state] unless during_states.include?(d[:state])
+          register_handler(d[:state], d)
+        when :finish
+          @terminal_states << d[:state] unless @terminal_states.include?(d[:state])
+        when :compensation
+          @compensations[d[:name]] = d[:block]
+        end
+      end
+
+      validate_shape!(start_decls)
+      @start_event = start_decls.first[:event]
+      @states = during_states + @terminal_states
+      @successors = build_successors(during_states)
+      validate_compensations!
+      validate_timeouts!
+      deep_freeze!
+    end
+
+    def handler_for(event) = @handlers_by_event[event.to_sym]
+
+    def state_for_event(event) = handler_for(event)&.state
+
+    def events = @handlers_by_event.keys
+
+    def events_for_state(state) = @handlers_by_event.values.select { |h| h.state == state.to_sym }.map(&:event)
+
+    def successor_of(state) = @successors.fetch(state.to_sym)
+
+    def terminal?(state)
+      s = state.to_sym
+      @terminal_states.include?(s) || %i[compensated cancelled].include?(s)
+    end
+
+    def declared?(state)
+      s = state.to_sym
+      @states.include?(s) || terminal?(s)
+    end
+
+    def correlate(payload, event_name)
+      correlator = klass.correlator
+      value = (correlator.arity == 1) ? correlator.call(payload) : correlator.call(payload, event_name)
+      if value.nil?
+        raise MissingCorrelationError, "#{klass} registered #{event_name.inspect} but correlate_by returned nil"
+      end
+      value.to_s
+    end
+
+    # handler override → class default → step_default. (Compensation blocks
+    # use RetryPolicy.compensation_default — see CompensationRunner, Task 8.)
+    def retry_policy_for(handler)
+      override = handler.retry_policy
+      policy =
+        case override
+        when nil then nil
+        when Hash then RetryPolicy.new(**override)
+        when Array then CompositeRetryPolicy.new(override)
+        else override
+        end
+      policy || klass.default_retry_policy || RetryPolicy.step_default
+    end
+
+    def to_mermaid
+      lines = ["stateDiagram-v2"]
+      chain = [START] + @states.reject { |s| @terminal_states.include?(s) } + [@terminal_states.first]
+      chain.each_cons(2) do |from, to|
+        events_from = (from == START) ? [@start_event] : events_for_state(from)
+        label = events_from.join(" / ")
+        from_name = (from == START) ? "[*]" : from
+        lines << "    #{from_name} --> #{to}: #{label}"
+      end
+      @terminal_states.each { |t| lines << "    #{t} --> [*]" }
+      jump_targets.each { |(from, to)| lines << "    #{from} --> #{to}: jump" }
+      lines.join("\n")
+    end
+
+    # Best-effort literal scan for `transition_to :sym` in handler blocks
+    # (jumps are opaque Ruby; unresolvable ones are simply not drawn). Each
+    # match is attributed to a handler only if the match's line falls within
+    # that handler's EXACT block extent (via RubyVM::InstructionSequence's
+    # code_location), so two sagas sharing one file never cross-attribute a
+    # jump. Anything we can't precisely locate is simply not drawn — a wrong
+    # edge is worse than a missing one.
+    def jump_targets
+      scan_handlers(/transition_to[\s(]+:(\w+)/).filter_map do |(state, captures)|
+        target = captures.first
+        next unless declared?(target)
+        from = (state == START) ? "[*]" : state
+        [from, target.to_sym]
+      end.uniq
+    end
+
+    # Structured graph (chain + jump), the sibling of to_mermaid.
+    def to_graph
+      nodes = [SagaForge::Dashboard::Node.new(id: START.to_s, label: "start", kind: :start)]
+      (@states - @terminal_states).each do |s|
+        nodes << SagaForge::Dashboard::Node.new(id: s.to_s, label: s.to_s, kind: :state)
+      end
+      # Only @terminal_states.first is on the chain below (build_successors
+      # picks it as the chain's sink too). Additional terminals are only
+      # wired in when a handler literally `transition_to`s them (jump_targets,
+      # below) — the normal multi-terminal pattern. A terminal reached only
+      # by a computed/conditional transition, or not reached at all, has no
+      # edge and renders as an isolated node: that's deliberate, not a bug —
+      # it's the same best-effort honesty jump_targets already carries (a
+      # wrong edge is worse than a missing one).
+      @terminal_states.each do |s|
+        nodes << SagaForge::Dashboard::Node.new(id: s.to_s, label: s.to_s, kind: :terminal)
+      end
+
+      edges = []
+      chain = [START] + (@states - @terminal_states) + [@terminal_states.first]
+      chain.each_cons(2) do |from, to|
+        label = (from == START) ? @start_event.to_s : events_for_state(from).join(" / ")
+        edges << SagaForge::Dashboard::Edge.new(from: from.to_s, to: to.to_s, kind: :chain, label: label)
+      end
+      jump_targets.each do |(from, to)|
+        from_id = (from == "[*]") ? START.to_s : from.to_s
+        edges << SagaForge::Dashboard::Edge.new(from: from_id, to: to.to_s, kind: :jump, label: "jump")
+      end
+
+      nodes.each(&:freeze)
+      edges.each(&:freeze)
+      SagaForge::Dashboard::Graph.new(nodes.freeze, edges.freeze).freeze
+    end
+
+    private
+
+    # Shared block-extent scanner for jump_targets. Yields, for
+    # every line within every handler's EXACT block extent, the handler's
+    # state paired with whatever String#scan produces for that regex (the
+    # full match, or its capture groups) — so two sagas sharing one file
+    # never cross-attribute a match. Anything we can't precisely locate is
+    # simply not scanned — a wrong edge is worse than a missing one.
+    def scan_handlers(regex)
+      return [] unless defined?(RubyVM::InstructionSequence)
+
+      matches = []
+      @handlers_by_event.each_value do |h|
+        extent = block_extent(h.block)
+        next unless extent
+        file, first_lineno, last_lineno = extent
+        next unless File.exist?(file)
+
+        lines = File.readlines(file)
+        (first_lineno..last_lineno).each do |lineno|
+          line = lines[lineno - 1]
+          next unless line
+          line.scan(regex) { |m| matches << [h.state, m] }
+        end
+      end
+      matches
+    end
+
+    # [file, first_lineno, last_lineno] for a handler's block, or nil if the
+    # exact extent can't be determined (no iseq, or no code_location — older
+    # Ruby / non-MRI).
+    def block_extent(block)
+      return nil unless block
+      iseq = RubyVM::InstructionSequence.of(block)
+      return nil unless iseq
+      code_location = iseq.to_a[4].is_a?(Hash) ? iseq.to_a[4][:code_location] : nil
+      return nil unless code_location
+      first_lineno, _first_col, last_lineno, _last_col = code_location
+      [iseq.path, first_lineno, last_lineno]
+    rescue TypeError, ArgumentError
+      nil
+    end
+
+    def register_handler(state, d)
+      event = d[:event]
+      if (existing = @handlers_by_event[event])
+        if state == START && existing.state == START
+          raise DefinitionError, "#{klass} declares start_with more than once"
+        end
+        raise AmbiguousEventError,
+          "#{klass} registers #{event.inspect} under both #{existing.state.inspect} and #{state.inspect}"
+      end
+      @handlers_by_event[event] = Handler.new(
+        state:, event:, block: d[:block], compensate: d[:compensate],
+        timeout: d[:timeout], on_timeout: d[:on_timeout], retry_policy: d[:retry_policy]
+      )
+    end
+
+    def validate_shape!(start_decls)
+      raise DefinitionError, "#{klass} needs exactly one start_with (found #{start_decls.size})" unless start_decls.size == 1
+      raise NoTerminalStateError, "#{klass} declares no finish_with" if @terminal_states.empty?
+      raise MissingCorrelationError, "#{klass} is missing correlate_by" if klass.correlator.nil?
+    end
+
+    def build_successors(during_states)
+      chain = [START] + during_states + [@terminal_states.first]
+      chain.each_cons(2).to_h
+    end
+
+    def validate_compensations!
+      @handlers_by_event.each_value do |h|
+        next if h.compensate.nil? || @compensations.key?(h.compensate)
+        raise UnknownCompensationError,
+          "#{klass} handler for #{h.event.inspect} compensates with undeclared #{h.compensate.inspect}"
+      end
+    end
+
+    # timeout:/on_timeout: are a pair: neither makes sense without the other.
+    # A resolvable on_timeout is checked now (boot) so a typo'd or stale
+    # target screams at compile time, not months later when a timer fires
+    # (TimeoutJob's fire-time declared? check is belt-and-braces for state
+    # removed in a later deploy while old timers are still armed).
+    def validate_timeouts!
+      @handlers_by_event.each_value do |h|
+        if h.timeout && h.on_timeout.nil?
+          raise DefinitionError,
+            "#{klass} handler for #{h.event.inspect} declares timeout: without on_timeout:"
+        end
+        if h.on_timeout && h.timeout.nil?
+          raise DefinitionError,
+            "#{klass} handler for #{h.event.inspect} declares on_timeout: without timeout:"
+        end
+        next unless h.timeout
+
+        target = h.on_timeout.to_sym
+        next if target == :fail!
+        next if declared?(target)
+        raise DefinitionError,
+          "#{klass} handler for #{h.event.inspect} declares on_timeout: #{h.on_timeout.inspect} — not a declared state"
+      end
+    end
+
+    # Definition.compile freezes the Definition object itself, but that's
+    # shallow: the memoized @definition is shared process-wide, so a stray
+    # mutation of one of its collections (or a Handler struct) would
+    # permanently corrupt boot metadata for every saga instance. Freeze
+    # everything reachable.
+    def deep_freeze!
+      @handlers_by_event.each_value(&:freeze)
+      @handlers_by_event.freeze
+      @compensations.freeze
+      @states.freeze
+      @terminal_states.freeze
+      @successors.freeze
+    end
+  end
+end

data/lib/saga_forge/event.rb

@@ -0,0 +1,16 @@
+module SagaForge
+  # The ledger: inbound rows only, append-only, mutable status.
+  class Event < ApplicationRecord
+    self.table_name = "saga_forge_events"
+
+    belongs_to :state, class_name: "SagaForge::State",
+      foreign_key: :saga_forge_state_id, optional: true
+
+    enum :status, {pending: 0, processed: 1, stalled: 2, failed: 3}
+
+    scope :for_instance, ->(saga_class, correlation_id) {
+      where(saga_class: saga_class.to_s, correlation_id: correlation_id.to_s)
+    }
+    scope :ledger_order, -> { order(:created_at, :id) }
+  end
+end

data/lib/saga_forge/execution/compensation_facade.rb

@@ -0,0 +1,21 @@
+module SagaForge
+  module Execution
+    # Yielded to compensation blocks: context is the snapshot (§A.4).
+    # No transition verbs — rollback has one direction.
+    class CompensationFacade
+      attr_reader :correlation_id, :current_state, :context, :staged_publishes
+
+      def initialize(correlation_id:, current_state:, context:)
+        @correlation_id = correlation_id
+        @current_state = current_state
+        @context = context
+        @staged_publishes = []
+      end
+
+      def publish(event_name, **payload)
+        @staged_publishes.concat(Router.resolve(event_name, payload))
+        nil
+      end
+    end
+  end
+end

data/lib/saga_forge/execution/facade.rb

@@ -0,0 +1,45 @@
+module SagaForge
+  module Execution
+    # The `saga` object yielded to forward blocks (§A.1 verbs). Everything is
+    # staged in memory; the Runner commits it.
+    class Facade
+      # Verb semantics: last verb call wins — calling transition_to twice
+      # simply overwrites @outcome with whatever ran last, and the block
+      # keeps executing. fail! is the one exception: it both records its
+      # outcome AND throws :saga_forge_fail, short-circuiting the rest of
+      # the block immediately. Every other verb is just a plain method call
+      # with no control-flow effect.
+      attr_reader :correlation_id, :current_state, :context, :outcome, :staged_publishes
+
+      def initialize(definition:, correlation_id:, current_state:, context:)
+        @definition = definition
+        @correlation_id = correlation_id
+        @current_state = current_state
+        @context = context
+        @staged_publishes = []
+        @outcome = nil
+      end
+
+      def transition_to(state)
+        unless @definition.declared?(state)
+          raise UnknownStateError, "transition_to #{state.inspect} — undeclared state"
+        end
+        @outcome = [:transition_to, state.to_sym]
+        nil
+      end
+
+      def fail!(reason: nil)
+        @outcome = [:fail, reason]
+        throw :saga_forge_fail
+      end
+
+      # Staged publish (§A.2): resolve recipients NOW (call-site stack trace,
+      # MissingCorrelationError surfaces under the block's retry policy),
+      # hold fully-built rows; the Runner inserts them inside its commit.
+      def publish(event_name, **payload)
+        @staged_publishes.concat(Router.resolve(event_name, payload))
+        nil
+      end
+    end
+  end
+end

data/lib/saga_forge/execution/post_commit.rb

@@ -0,0 +1,53 @@
+module SagaForge
+  module Execution
+    # Shared post-commit effects (§A.1 arming, §A.3 re-delivery): entering
+    # (or staying in) a state re-delivers any events parked for it and arms
+    # its timeout-declaring handlers. Both Runner (after a normal commit) and
+    # TimeoutJob (after a live timeout branch transition) land here — neither
+    # needs anything but (definition, state): saga_class/correlation_id/
+    # current_state/version/id off the state row.
+    module PostCommit
+      def redeliver_parked(definition, state)
+        names = definition.events_for_state(state.current_state).map(&:to_s)
+        return if names.empty?
+        Event.stalled.for_instance(state.saga_class, state.correlation_id)
+          .where(event_name: names).ledger_order.each do |parked|
+          # Status-scoped: only flip rows still :stalled. A racing commit
+          # (another redeliver_parked, or this same row processed in the
+          # meantime) can move a row to :processed between the SELECT above
+          # and this write — the scope makes that race lose cleanly instead
+          # of regressing a committed row back to :pending.
+          updated = Event.where(id: parked.id, status: :stalled)
+            .update_all(status: :pending, stall_count: 0, updated_at: Time.current)
+          ExecutionJob.perform_later(parked.id) if updated > 0
+        end
+      end
+
+      def arm_timeouts(definition, state)
+        current = state.current_state.to_sym
+        definition.events_for_state(current).each do |event_name|
+          handler = definition.handler_for(event_name)
+          next unless handler.timeout
+          TimeoutJob.set(wait: handler.timeout)
+            .perform_later(state.id, event_name.to_s, state.version)
+        end
+      end
+
+      # Forward-only: a saga never re-enters a state it has resided in, so it
+      # handles each event name at most once (the invariant structural dedup
+      # relies on). Visited = every processed event's registered state, plus
+      # the current state. Covers fall-through, transition_to, AND timeout
+      # branches. Raises ForwardOnlyError on a re-entry.
+      def guard_forward_only!(definition, saga_class, correlation_id, current, next_state)
+        visited = Event.processed
+          .for_instance(saga_class, correlation_id)
+          .pluck(:event_name)
+          .filter_map { |name| definition.state_for_event(name)&.to_s }
+        visited << current.to_s
+        return unless visited.include?(next_state)
+        raise ForwardOnlyError,
+          "#{saga_class}##{correlation_id}: advance to #{next_state} re-enters a visited state — sagas are forward-only"
+      end
+    end
+  end
+end

data/lib/saga_forge/execution/runner.rb

@@ -0,0 +1,240 @@
+module SagaForge
+  module Execution
+    # Processes one pending ledger row through the §A.4 pipeline.
+    # Returns [:done] | [:respin] | [:retry, seconds].
+    class Runner
+      include PostCommit
+
+      ERROR_MESSAGE_LIMIT = 10_000
+      BACKTRACE_LINES = 50
+
+      attr_reader :event
+
+      def initialize(event)
+        @event = event
+      end
+
+      def call
+        return [:done] unless event.pending?
+        return [:done] if halted?
+
+        saga_class = event.saga_class.constantize
+        definition = saga_class.definition
+        state_row = State.find_by(saga_class: event.saga_class, correlation_id: event.correlation_id)
+        current = state_row&.current_state&.to_sym || Definition::START
+
+        return discard_terminal!(current) if definition.terminal?(current)
+
+        expected = definition.state_for_event(event.event_name)
+        return stall! if expected != current
+
+        execute!(definition, state_row, current)
+      end
+
+      private
+
+      # Poison-pill halt (§A.3): derived from the ledger at job entry.
+      def halted?
+        Event.failed.for_instance(event.saga_class, event.correlation_id).exists?
+      end
+
+      # Atomic increment (not read-modify-write): concurrent deliveries outside
+      # Solid Queue's serialization must not lose updates (§A.3 — correctness
+      # never depends on the concurrency-limit nicety).
+      def stall!
+        Event.where(id: event.id).update_all("stall_count = stall_count + 1")
+        count = event.reload.stall_count
+        if count >= SagaForge.config.stall_budget
+          event.update!(status: :stalled)
+          [:done]
+        else
+          [:respin]
+        end
+      end
+
+      def discard_terminal!(current)
+        event.update!(status: :processed, last_processed_at: Time.current, error: {"discarded" => "terminal state #{current}"})
+        Rails.logger.info { "[saga_forge] discarded #{event.event_name} for terminal #{event.saga_class}##{event.correlation_id}" }
+        [:done]
+      end
+
+      def execute!(definition, state_row, current)
+        handler = definition.handler_for(event.event_name)
+        entry_version = state_row&.version || 0
+        context = (state_row&.context || {}).deep_dup.with_indifferent_access
+
+        facade = Facade.new(
+          definition: definition,
+          correlation_id: event.correlation_id,
+          current_state: current,
+          context: context
+        )
+
+        begin
+          catch(:saga_forge_fail) do
+            SagaForge.guarding_execution do
+              handler.block.call(facade, event.payload.with_indifferent_access)
+            end
+          end
+        rescue => error
+          return handle_error(error, definition, handler)
+        end
+
+        state_row = commit!(definition, state_row, current, entry_version, facade)
+        after_commit_effects(definition, state_row, facade)
+        [:done]
+      rescue ConcurrencyConflict
+        [:retry, SagaForge.config.stall_wait]
+      rescue ForwardOnlyError => e
+        record_forward_violation(e)
+        [:done]
+      end
+
+      # Routes BLOCK errors through the resolved retry policy (§A.5):
+      # handler override -> class default -> RetryPolicy.step_default. Retryable
+      # -> event stays pending with bumped attempts/budgets, [:retry, backoff].
+      # Exhausted or unmatched -> event failed with captured error, [:done];
+      # nothing escapes to ActiveJob's dead-letter path.
+      #
+      # Structural warning: this hook is for BLOCK errors only. ConcurrencyConflict
+      # (raised only from commit!, and itself a SagaForge::Error subclass) is
+      # deliberately caught by the method-level `rescue ConcurrencyConflict`
+      # on execute! — which sits AFTER this hook in the call chain, catching
+      # only what commit! raises, never what the block raises. Do not
+      # restructure this so ConcurrencyConflict could reach a generic
+      # `rescue => error` here — that would burn retry-policy budget on a
+      # version race, which isn't a block failure. Likewise, the fail! verb
+      # unwinds via `throw :saga_forge_fail`, not a raised exception, so it
+      # never reaches handle_error and must never be routed through
+      # retry-policy logic either.
+      #
+      # The whole read-decide-write sequence runs under a row lock (like
+      # stall!'s atomic increment): two concurrent deliveries reading
+      # event.attempts from stale in-memory state would otherwise both count
+      # as "attempt 1", letting a saga burn more attempts than the policy's
+      # max_attempts bounds. with_lock reloads the row before the block runs,
+      # so attempts/retry_budgets read inside are fresh as of lock acquisition.
+      def handle_error(error, definition, handler)
+        policy = definition.retry_policy_for(handler)
+
+        event.with_lock do
+          return [:done] unless event.pending? # another delivery already resolved this row
+
+          attempts = event.attempts + 1
+          budgets = (event.retry_budgets || {}).dup
+          updates = {attempts: attempts}
+
+          backoff = policy.retry_backoff(error, attempts: attempts) do |budget_key|
+            budgets[budget_key] = budgets.fetch(budget_key, 0) + 1
+            updates[:retry_budgets] = budgets
+            budgets[budget_key]
+          end
+
+          if backoff
+            event.update!(**updates)
+            [:retry, backoff]
+          else
+            event.update!(**updates, status: :failed, error: {
+              "class" => error.class.name,
+              "message" => SagaForge.safe_error_message(error.message, ERROR_MESSAGE_LIMIT),
+              "backtrace" => Array(error.backtrace).first(BACKTRACE_LINES).map { |l| SagaForge.safe_error_message(l, 500) }
+            })
+            Rails.logger.error { "[saga_forge] #{event.saga_class}##{event.correlation_id} #{event.event_name} failed: #{error.class}" }
+            [:done]
+          end
+        end
+      end
+
+      def commit!(definition, state_row, current, entry_version, facade)
+        failing = facade.outcome.is_a?(Array) && facade.outcome.first == :fail
+        next_state = resolve_next_state(definition, current, facade.outcome)
+        unless next_state == State::COMPENSATING.to_s
+          guard_forward_only!(definition, event.saga_class, event.correlation_id, current, next_state)
+        end
+        @inserted_rows = []
+
+        State.transaction do
+          if state_row.nil?
+            begin
+              state_row = State.create!(
+                saga_class: event.saga_class, correlation_id: event.correlation_id,
+                current_state: next_state, version: entry_version, context: {}
+              )
+            rescue ActiveRecord::RecordNotUnique
+              raise ConcurrencyConflict, "duplicate start for #{event.saga_class}##{event.correlation_id}"
+            end
+          end
+          state_row.lock!
+          raise ConcurrencyConflict, "version moved" if state_row.version != entry_version
+
+          context = facade.context
+          if failing
+            # NOTE: `context["__saga_forge"] ||= {}` would look right but isn't:
+            # HashWithIndifferentAccess#[]= stores its own converted copy
+            # internally, while the assignment *expression* always evaluates
+            # to the literal right-hand object Ruby wrote (a core `[]=`
+            # semantic) — so a `meta = (context[k] ||= {})` alias points at
+            # an orphan hash that never lands back in `context`. Merge and
+            # reassign in one shot instead.
+            meta = (context["__saga_forge"] || {}).merge(
+              "failure_reason" => facade.outcome.last,
+              "target" => "compensated"
+            )
+            context["__saga_forge"] = meta
+          end
+
+          now = Time.current
+          finalized = definition.terminal?(next_state.to_sym) ? now : nil
+          state_row.update!(
+            current_state: next_state, version: entry_version + 1, context: context,
+            last_active_at: now, finalized_at: finalized
+          )
+          event.update!(status: :processed, saga_forge_state_id: state_row.id, error: nil, last_processed_at: now)
+
+          unless failing # fail! discards staged publishes (§A.1)
+            # Staged rows can collide benignly now that dedup is structural:
+            # two producers publishing the same event to the same recipient,
+            # or a redelivery, hit the (saga,correlation,event) unique index.
+            # Each insert gets its own savepoint so a duplicate rolls back to
+            # the savepoint instead of poisoning this commit's transaction
+            # (Postgres abort-on-error), exactly as Publisher#insert_row does.
+            @inserted_rows = facade.staged_publishes.filter_map do |attrs|
+              ApplicationRecord.transaction(requires_new: true) { Event.create!(attrs) }
+            rescue ActiveRecord::RecordNotUnique
+              nil
+            end
+          end
+        end
+        state_row
+      end
+
+      def resolve_next_state(definition, current, outcome)
+        case outcome
+        in nil then definition.successor_of(current).to_s
+        in [:transition_to, target] then target.to_s
+        in [:fail, _] then State::COMPENSATING.to_s
+        end
+      end
+
+      def record_forward_violation(error)
+        event.update!(status: :failed, error: {
+          "class" => error.class.name,
+          "message" => SagaForge.safe_error_message(error.message, ERROR_MESSAGE_LIMIT)
+        })
+        Rails.logger.error { "[saga_forge] #{event.saga_class}##{event.correlation_id} #{event.event_name} rejected: #{error.message}" }
+      end
+
+      def after_commit_effects(definition, state_row, facade)
+        @inserted_rows.each { |row| ExecutionJob.perform_later(row.id) }
+
+        if state_row.current_state == State::COMPENSATING.to_s
+          CompensationJob.perform_later(state_row.id)
+          return
+        end
+
+        redeliver_parked(definition, state_row)
+        arm_timeouts(definition, state_row)
+      end
+    end
+  end
+end

data/lib/saga_forge/execution_job.rb

@@ -0,0 +1,41 @@
+module SagaForge
+  # One job per ledger row; the row id is the only argument (§A.4).
+  class ExecutionJob < ActiveJob::Base
+    queue_as { SagaForge.config.job_queue }
+
+    NOT_FOUND_RETRIES = 5
+    NOT_FOUND_WAIT = 2.seconds
+
+    # Extracted to a constant (rather than inlined into the limits_concurrency
+    # call) so it's unit-testable without Solid Queue loaded: declaring
+    # limits_concurrency is inert without the adapter active (it just sets
+    # class_attributes — see ActiveJob::ConcurrencyControls), but *loading*
+    # Solid Queue this late (after Combustion has already booted the test
+    # app) doesn't retroactively install its ActiveJob extension. See
+    # test/concurrency_controls_test.rb.
+    CONCURRENCY_KEY = ->(event_row_id) {
+      event = Event.find_by(id: event_row_id)
+      event ? "SagaLock:#{event.saga_class}:#{event.correlation_id}" : "SagaLock:none"
+    }
+
+    if defined?(SolidQueue)
+      limits_concurrency key: CONCURRENCY_KEY
+    end
+
+    def perform(event_row_id)
+      event = Event.find_by(id: event_row_id)
+      unless event
+        # Pre-commit race from an external publish inside a caller's
+        # transaction: brief bounded retry, then silent discard (§A.2).
+        retry_job(wait: NOT_FOUND_WAIT) if executions < NOT_FOUND_RETRIES
+        return
+      end
+
+      outcome, arg = Execution::Runner.new(event).call
+      case outcome
+      when :respin then retry_job(wait: SagaForge.config.stall_wait)
+      when :retry then retry_job(wait: arg)
+      end
+    end
+  end
+end