saga_forge 0.1.0

data/lib/saga_forge/publisher.rb

@@ -0,0 +1,43 @@
+module SagaForge
+  # The external entry point: INSERTs join any open transaction on the
+  # engine connection; enqueues happen right after in plain code. The pending
+  # row is the obligation, the enqueue a hint, the sweeper the guarantee.
+  #
+  # Idempotency is structural: the (saga_class, correlation_id, event_name)
+  # unique index no-ops a duplicate delivery. A forward-only saga handles each
+  # event name at most once, so a second delivery is always a duplicate.
+  class Publisher
+    class << self
+      def publish(event_name, payload:)
+        if SagaForge.within_saga_execution?
+          raise UnstagedPublishError,
+            "SagaForge.publish called inside saga execution — use saga.publish (staged, delivered on commit)"
+        end
+
+        attrs_list = Router.resolve(event_name, payload)
+        return [] if attrs_list.empty?
+
+        rows = attrs_list.filter_map { |attrs| insert_row(attrs) }
+        rows.each { |row| ExecutionJob.perform_later(row.id) }
+        rows
+      end
+
+      private
+
+      # On Postgres, a failed INSERT (the unique-index violation) poisons the
+      # server-side transaction — every subsequent statement, including the
+      # caller's own COMMIT, would fail. The savepoint survives that abort for
+      # the no-op'd duplicate; it nests inside whatever transaction is already
+      # open and rolls back with its parent. The spec's "inserts join the
+      # caller's transaction" guarantee holds: a successful insert still lives
+      # and dies with the ambient transaction.
+      def insert_row(attrs)
+        ApplicationRecord.transaction(requires_new: true) do
+          Event.create!(attrs)
+        end
+      rescue ActiveRecord::RecordNotUnique
+        nil # duplicate delivery — the structural unique index no-ops it
+      end
+    end
+  end
+end

data/lib/saga_forge/railtie.rb

@@ -0,0 +1,17 @@
+require "rails/railtie"
+
+module SagaForge
+  # The router needs every saga class loaded to resolve recipients; lazy
+  # autoloading in dev would silently drop recipients. Eager-load app/sagas
+  # on each reload.
+  class Railtie < Rails::Railtie
+    initializer "saga_forge.eager_load_sagas" do |app|
+      app.config.to_prepare do
+        SagaForge::Router.reset!
+        dir = Rails.root.join("app/sagas")
+        Rails.autoloaders.main.eager_load_dir(dir.to_s) if dir.exist?
+        SagaForge::Router.compile_all!
+      end
+    end
+  end
+end

data/lib/saga_forge/retention_job.rb

@@ -0,0 +1,28 @@
+module SagaForge
+  # Prunes processed events past retention — but only for sagas already
+  # finalized: active sagas derive compensation from their history (§A.6).
+  # Finalized-ness is the persisted saga_forge_states.finalized_at, stamped
+  # atomically at commit (no constantize — robust to a since-deleted saga
+  # class, which used to leak those rows past retention forever).
+  class RetentionJob < ActiveJob::Base
+    queue_as { SagaForge.config.maintenance_queue }
+
+    # See ExecutionJob::CONCURRENCY_KEY for why this is a constant.
+    CONCURRENCY_KEY = "SagaForge::Retention"
+
+    if defined?(SolidQueue)
+      limits_concurrency key: CONCURRENCY_KEY
+    end
+
+    BATCH_SIZE = 500
+
+    def perform
+      cutoff = SagaForge.config.retention.ago
+      scope = Event.processed.where(last_processed_at: ..cutoff)
+        .left_joins(:state)
+        .where("saga_forge_states.id IS NULL OR saga_forge_states.finalized_at IS NOT NULL")
+
+      scope.in_batches(of: BATCH_SIZE) { |batch| batch.delete_all }
+    end
+  end
+end

data/lib/saga_forge/retry_policy.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+module SagaForge
+  # A single, unified description of retry behavior shared by every retry site
+  # (step failures and compensation failures).
+  #
+  # It answers the only two questions a retry site ever asks:
+  #   - retryable?(error, attempts) — should this failure be retried?
+  #   - backoff_for(attempts)       — how long until the next attempt?
+  #
+  # `attempts` is always the 1-based count of attempts made so far, *including*
+  # the one that just failed (matching Event#attempts). So on the first
+  # failure `attempts == 1`.
+  class RetryPolicy
+    attr_reader :max_attempts, :base, :cap, :jitter, :retry_on
+
+    # @param max_attempts [Integer, nil] cap on total attempts; nil = no count
+    #   cap (bounded elsewhere by the caller)
+    # @param base [Numeric, ActiveSupport::Duration] delay of the first retry
+    # @param cap [Numeric, ActiveSupport::Duration] ceiling for a single delay
+    # @param jitter [Boolean] apply equal jitter to spread retries
+    # @param retry_on [Array<Class>, nil] nil = retry any StandardError;
+    #   an array = retry only those classes (and subclasses); [] = retry nothing
+    def initialize(max_attempts: 3, base: 1, cap: 30, jitter: true, retry_on: nil)
+      @max_attempts = max_attempts
+      @base = base
+      @cap = cap
+      @jitter = jitter
+      @retry_on = retry_on
+    end
+
+    def retryable?(error, attempts)
+      within_attempt_cap?(attempts) && retryable_error?(error)
+    end
+
+    # Equal jitter: half the computed delay plus a random portion of the other
+    # half. Computed once at re-enqueue time and never persisted, so the
+    # randomness does not affect re-delivery determinism.
+    def backoff_for(attempts)
+      exponent = [attempts - 1, 0].max
+      delay = [cap.to_f, base.to_f * (2**exponent)].min
+      delay = (delay / 2) + rand(0.0..(delay / 2)) if jitter
+      delay.seconds
+    end
+
+    # Public routing predicate: would this policy handle this error at all?
+    # (independent of the attempt cap). nil retry_on = any StandardError;
+    # [] = nothing; a list = those classes and their subclasses.
+    def matches?(error)
+      retryable_error?(error)
+    end
+
+    # Single-call decision used by every retry site: the backoff Duration to
+    # retry, or nil to stop. A plain policy uses `attempts` and ignores any
+    # block (the block exists only so a CompositeRetryPolicy can supply a
+    # per-error count — see CompositeRetryPolicy#retry_backoff).
+    def retry_backoff(error, attempts:)
+      retryable?(error, attempts) ? backoff_for(attempts) : nil
+    end
+
+    # Stable per-policy identifier derived from the errors this policy
+    # *declares* (its retry_on), not the error thrown. Inside a composite this
+    # keys the policy's attempt budget (see Event#retry_budgets), so the
+    # budget is shared across every class the policy lists (and their
+    # subclasses) and is independent of the policy's position — reordering
+    # the composite does not reset counts. A catch-all (retry_on: nil) keys
+    # "*".
+    def budget_key
+      retry_on.nil? ? "*" : retry_on.map(&:name).sort.join(",")
+    end
+
+    def self.step_default
+      new(max_attempts: 3, base: 1, cap: 30, jitter: true, retry_on: nil)
+    end
+
+    # Compensations are the rollback path: giving up partway through a
+    # rollback leaves the saga in a half-undone state, which is worse than
+    # retrying for a long time. So compensations get a far more tolerant
+    # policy than steps. 10 attempts gives a tolerant window of up to ~8.5
+    # min (≈4 min typical, since equal jitter puts each wait in [d/2, d]) —
+    # enough for a DB failover or deploy restart — without retrying forever
+    # on a deterministic bug; cap (600s / 10 min) bounds any single backoff
+    # and only binds if a caller configures more attempts.
+    def self.compensation_default
+      new(max_attempts: 10, base: 1, cap: 600, jitter: true, retry_on: nil)
+    end
+
+    # Build a composite policy from an ordered list of RetryPolicy objects.
+    def self.compose(*policies)
+      CompositeRetryPolicy.new(policies)
+    end
+
+    private
+
+    def within_attempt_cap?(attempts)
+      max_attempts.nil? || attempts < max_attempts
+    end
+
+    def retryable_error?(error)
+      if retry_on.nil?
+        error.is_a?(StandardError)
+      else
+        retry_on.any? { |klass| error.is_a?(klass) }
+      end
+    end
+  end
+end

data/lib/saga_forge/router.rb

@@ -0,0 +1,70 @@
+module SagaForge
+  # Boot-time event → saga-class registry + the shared row builder used by
+  # both publish paths. Registration happens in Base.inherited; reset on
+  # code reload (railtie to_prepare).
+  #
+  # No internal locking around @classes: register/reset!/compile_all! are
+  # only ever called from the main autoloader (Base.inherited during load,
+  # railtie to_prepare during reload), and Rails' reloader interlock already
+  # serializes those against request threads.
+  class Router
+    @classes = []
+
+    class << self
+      def register(klass)
+        @classes << klass unless @classes.include?(klass)
+      end
+
+      def reset! = @classes = []
+
+      def saga_classes = @classes
+
+      # Forces every registered class to compile its Definition right now,
+      # so a broken saga (bad DSL, missing correlate_by, etc.) raises here —
+      # loudly, at boot/reload (§A.8) — instead of being silently skipped as
+      # a recipient the first time something happens to publish its event.
+      def compile_all! = saga_classes.each(&:definition)
+
+      def recipients_for(event_name)
+        event = event_name.to_sym
+        @classes.select { |k| handler_for(k, event) }
+      end
+
+      # One fully-built Event attribute hash per recipient class. Raises
+      # MissingCorrelationError before anything is inserted — atomic publish.
+      def resolve(event_name, payload)
+        payload = payload.with_indifferent_access
+        recipients_for(event_name).map do |klass|
+          {
+            saga_class: klass.name,
+            correlation_id: klass.definition.correlate(payload, event_name.to_sym),
+            event_name: event_name.to_s,
+            payload: payload,
+            status: :pending
+          }
+        end
+      end
+
+      private
+
+      # A class whose Definition never compiled (e.g. a mid-declaration DSL
+      # error) is simply not a recipient of anything — it's not this
+      # publish's problem. Only DSL/boot-time errors are swallowed here;
+      # Definition#correlate raising MissingCorrelationError for a class that
+      # DOES handle this event (i.e. a real recipient whose payload lacks the
+      # correlation key) happens later, in #resolve, and still aborts the
+      # whole publish as required.
+      #
+      # Belt-and-braces: the railtie force-compiles every registered class at
+      # boot/reload (§A.8), so a broken saga crashes loudly long before any
+      # publish reaches here — but if one somehow does, log loudly rather than
+      # skip in silence.
+      def handler_for(klass, event)
+        klass.definition.handler_for(event)
+      rescue Error => e
+        Rails.logger.error { "[saga_forge] #{klass.name} failed to compile its definition — skipped as recipient: #{e.class}: #{e.message}" }
+        nil
+      end
+    end
+  end
+end

data/lib/saga_forge/state.rb

@@ -0,0 +1,113 @@
+module SagaForge
+  # The saga's ground truth, and only the truth. current_state is always the
+  # real workflow position; stalls/failures live on Event rows.
+  class State < ApplicationRecord
+    self.table_name = "saga_forge_states"
+
+    COMPENSATING = :compensating
+    COMPENSATED = :compensated
+    CANCELLED = :cancelled
+
+    has_many :events, class_name: "SagaForge::Event",
+      foreign_key: :saga_forge_state_id, dependent: nil
+
+    scope :for_saga, ->(klass) { where(saga_class: klass.to_s) }
+    scope :in_state, ->(state) { where(current_state: state.to_s) }
+    scope :stalled, -> { where(id: Event.stalled.select(:saga_forge_state_id)) }
+    scope :suspended, -> { where(id: Event.failed.select(:saga_forge_state_id)) }
+    scope :compensating, -> { where(current_state: COMPENSATING.to_s) }
+    scope :finalized, -> { where.not(finalized_at: nil) }
+    scope :active, -> { where(finalized_at: nil) }
+
+    def history = events.ledger_order
+
+    def saga_definition = saga_class.constantize.definition
+
+    # Status-scoped: the UPDATE only touches rows still :stalled, so a
+    # concurrent redeliver_parked landing a row on :processed between our
+    # SELECT and this write can never be regressed back to :pending (a step
+    # is compensable iff it committed — Task 8's invariant). Enqueueing an id
+    # that raced ahead to :processed is harmless (ExecutionJob/Runner no-op
+    # on an already-processed row).
+    def retry_stalled!
+      if recovery_blocked?
+        Rails.logger.warn { "[saga_forge] retry_stalled! no-op on #{saga_class}##{correlation_id}: saga is #{current_state}" }
+        return false
+      end
+
+      ids = events.stalled.ledger_order.ids
+      count = Event.where(id: ids, status: :stalled)
+        .update_all(status: :pending, stall_count: 0, updated_at: Time.current)
+      enqueue_execution(ids)
+      count > 0
+    end
+
+    # Same status-scoping as retry_stalled! — see there.
+    def resume!
+      if recovery_blocked?
+        Rails.logger.warn { "[saga_forge] resume! no-op on #{saga_class}##{correlation_id}: saga is #{current_state}" }
+        return false
+      end
+
+      ids = events.failed.ledger_order.ids
+      count = Event.where(id: ids, status: :failed)
+        .update_all(status: :pending, attempts: 0, retry_budgets: {}, error: nil, updated_at: Time.current)
+      enqueue_execution(ids)
+      count > 0
+    end
+
+    # Resume-then-compensate (§A.4): a failed step's side effects may have
+    # happened, but its event never processed and its context never committed —
+    # so it implies no compensation and its compensation's guard sees nothing.
+    # Fix the code, resume!, then compensate if still desired.
+    #
+    # Returns true if this call actually transitioned the saga into
+    # :compensating, false on a no-op (already terminal/compensating) — a
+    # small deliberate API nicety for the dashboard phase.
+    def compensate!(target: COMPENSATED, reason: nil)
+      if !recovery_blocked? && events.failed.exists?
+        Rails.logger.warn do
+          "[saga_forge] compensate! on #{saga_class}##{correlation_id} with failed events — " \
+            "failed steps imply no compensation and left no context; resume!, then compensate"
+        end
+      end
+
+      transitioned = false
+      with_lock do
+        break if recovery_blocked?
+
+        context_copy = context.deep_dup
+        meta = (context_copy["__saga_forge"] || {}).merge("target" => target.to_s)
+        meta["failure_reason"] = reason if reason
+        context_copy["__saga_forge"] = meta
+        update!(current_state: COMPENSATING.to_s, version: version + 1, context: context_copy, last_active_at: Time.current)
+        transitioned = true
+      end
+      CompensationJob.perform_later(id) if transitioned
+      transitioned
+    end
+
+    def cancel!(reason:)
+      compensate!(target: CANCELLED, reason: reason)
+    end
+
+    private
+
+    # Terminal or already-compensating: resuming/retrying a parked event here
+    # would orphan it forever (no future state transition will ever redeliver
+    # it — §A.3's redelivery only fires for the saga's live current_state).
+    def recovery_blocked?
+      saga_definition.terminal?(current_state) || current_state == COMPENSATING.to_s
+    end
+
+    # ActiveJob.perform_all_later (Rails 7.1+) enqueues in one batch instead
+    # of N; the :test adapter has no #enqueue_all so it transparently falls
+    # back to per-job #enqueue/#enqueue_at in the same order — verified
+    # empirically to behave identically to a bare .each { perform_later }
+    # under perform_enqueued_jobs/assert_enqueued_jobs.
+    def enqueue_execution(ids)
+      return if ids.empty?
+      ActiveJob.perform_all_later(ids.map { |id| ExecutionJob.new(id) })
+    end
+  end
+end

data/lib/saga_forge/sweeper_job.rb

@@ -0,0 +1,80 @@
+module SagaForge
+  # The delivery guarantee (§A.2): rows are obligations, enqueues are hints.
+  # Sweeps three stranded populations; harmless double-enqueues are absorbed
+  # by ExecutionJob's processed-skip/halt/stall checks. Host-scheduled
+  # (config/recurring.yml) at config.sweep_interval cadence.
+  class SweeperJob < ActiveJob::Base
+    queue_as { SagaForge.config.maintenance_queue }
+
+    # A fixed singleton key, not per-instance: this is one recurring job, not
+    # one lock per saga — an over-long sweep must not overlap the next tick.
+    # See ExecutionJob::CONCURRENCY_KEY for why this is a constant.
+    CONCURRENCY_KEY = "SagaForge::Sweeper"
+
+    if defined?(SolidQueue)
+      limits_concurrency key: CONCURRENCY_KEY
+    end
+
+    def perform
+      sweep_aged_pending
+      sweep_stranded_compensating
+      sweep_stranded_stalled
+    end
+
+    private
+
+    def cutoff = SagaForge.config.sweep_interval.ago
+
+    def sweep_aged_pending
+      Event.pending.where(created_at: ..cutoff).find_each do |event|
+        ExecutionJob.perform_later(event.id)
+      end
+    end
+
+    # A fail!/compensate! handoff is a once-only hint (Task 6 review): a crash
+    # between the commit and the CompensationJob enqueue strands the saga in
+    # :compensating. Exhausted compensations (comp_error present) are
+    # operator-recovery-only — re-enqueueing them would re-run a broken block
+    # every sweep, forever.
+    def sweep_stranded_compensating
+      State.in_state(State::COMPENSATING).where(last_active_at: ..cutoff).find_each do |state|
+        next if state.context.dig("__saga_forge", "comp_error").present?
+        CompensationJob.perform_later(state.id)
+      end
+    end
+
+    # A crash between a commit and redeliver_parked strands a parked event the
+    # saga is now waiting on (Task 6 review): no future commit will advance the
+    # saga, so nothing else will ever re-deliver it.
+    #
+    # group_by loads all aged stalled events into memory to compile each
+    # saga_class's Definition once — acceptable at expected stalled volumes
+    # (crash-induced strandings are rare and self-limiting); switch to
+    # in_batches per saga_class if that stops being true.
+    def sweep_stranded_stalled
+      Event.stalled.where(updated_at: ..cutoff).group_by(&:saga_class).each do |saga_class, events|
+        klass = saga_class.safe_constantize
+        unless klass
+          Rails.logger.error { "[saga_forge] sweeper: #{saga_class} no longer exists; #{events.size} stalled event(s) unrecoverable" }
+          next
+        end
+        definition = klass.definition
+        states = State.where(saga_class: saga_class, correlation_id: events.map(&:correlation_id).uniq)
+          .index_by(&:correlation_id)
+        # Ledger order (§A.3) among the events already loaded in memory —
+        # re-delivery must honor the same ordering a live redeliver_parked would.
+        events.sort_by { |e| [e.created_at, e.id] }.each do |event|
+          state = states[event.correlation_id]
+          next unless state
+          next unless definition.state_for_event(event.event_name)&.to_s == state.current_state
+          # Status-scoped for the same reason as PostCommit#redeliver_parked:
+          # this event was loaded minutes ago (cutoff-aged); a live commit may
+          # have already processed it by the time the sweep gets here.
+          updated = Event.where(id: event.id, status: :stalled)
+            .update_all(status: :pending, stall_count: 0, updated_at: Time.current)
+          ExecutionJob.perform_later(event.id) if updated > 0
+        end
+      end
+    end
+  end
+end

data/lib/saga_forge/timeout_job.rb

@@ -0,0 +1,96 @@
+module SagaForge
+  # A stale timer firing late is discarded by the version fence — the same
+  # principle that powers stalling. The clock resets on each handled event
+  # because every commit bumps version and re-arms (§A.1).
+  class TimeoutJob < ActiveJob::Base
+    include Execution::PostCommit
+
+    queue_as { SagaForge.config.job_queue }
+
+    # See ExecutionJob::CONCURRENCY_KEY for why this is a constant. `*` soaks
+    # up the job's other two arguments (event_name, armed_version) — only the
+    # state matters for the lock key.
+    CONCURRENCY_KEY = ->(state_id, *) {
+      state = State.find_by(id: state_id)
+      state ? "SagaLock:#{state.saga_class}:#{state.correlation_id}" : "SagaLock:none"
+    }
+
+    if defined?(SolidQueue)
+      limits_concurrency key: CONCURRENCY_KEY
+    end
+
+    def perform(state_id, event_name, armed_version)
+      state = State.find_by(id: state_id)
+      return unless state
+      return if state.version != armed_version # stale timer — cheap pre-check
+
+      definition = state.saga_definition
+      handler = definition.handler_for(event_name)
+      return unless handler&.timeout
+
+      # Definition#validate_timeouts! guarantees on_timeout is present
+      # (:fail! or a declared state) whenever timeout: is declared — no nil
+      # case to handle here.
+      case handler.on_timeout.to_sym
+      when :fail!
+        fail_saga!(state, armed_version)
+      else
+        branch!(state, definition, handler.on_timeout, armed_version)
+      end
+    end
+
+    private
+
+    def fail_saga!(state, armed_version)
+      transitioned = false
+      state.with_lock do
+        break if state.version != armed_version # re-check under the lock
+
+        # HWIA aliasing pitfall (see CompensationRunner#record_comp_error):
+        # `context["__saga_forge"] ||= {}` would evaluate to an orphan hash
+        # never written back to context. Merge and reassign in one shot.
+        context = state.context.deep_dup
+        meta = (context["__saga_forge"] || {}).merge(
+          "failure_reason" => "timeout", "target" => "compensated"
+        )
+        context["__saga_forge"] = meta
+        state.update!(current_state: State::COMPENSATING.to_s,
+          version: state.version + 1, context: context, last_active_at: Time.current)
+        transitioned = true
+      end
+      CompensationJob.perform_later(state.id) if transitioned
+    end
+
+    # declared? is re-checked at fire time as a belt-and-braces invariant:
+    # boot validation (Definition#validate_timeouts!) can't see a state that
+    # gets removed in a later deploy while an old timer is still armed — that
+    # must scream, not silently discard.
+    def branch!(state, definition, target, armed_version)
+      target = target.to_s
+      unless definition.declared?(target)
+        raise UnknownStateError, "on_timeout: #{target} is not a declared state"
+      end
+
+      begin
+        guard_forward_only!(definition, state.saga_class, state.correlation_id, state.current_state, target)
+      rescue ForwardOnlyError => e
+        Rails.logger.error { "[saga_forge] timeout branch rejected: #{e.message}" }
+        return
+      end
+
+      transitioned = false
+      state.with_lock do
+        break if state.version != armed_version
+        now = Time.current
+        finalized = definition.terminal?(target.to_sym) ? now : nil
+        state.update!(current_state: target, version: state.version + 1,
+          last_active_at: now, finalized_at: finalized)
+        transitioned = true
+      end
+      return unless transitioned
+
+      redeliver_parked(definition, state)
+      arm_timeouts(definition, state)
+    end
+  end
+end

data/lib/saga_forge/version.rb

@@ -0,0 +1,3 @@
+module SagaForge
+  VERSION = "0.1.0"
+end

data/lib/saga_forge.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+require "zeitwerk"
+require "active_record"
+require "active_job"
+
+module SagaForge
+  Loader = Zeitwerk::Loader.for_gem.tap do |loader|
+    loader.ignore("#{__dir__}/generators")
+    loader.ignore("#{__dir__}/saga_forge/railtie.rb")
+    loader.setup
+  end
+
+  # dashboard/graph.rb defines three constants (Graph, Node, Edge) in one
+  # file, which breaks Zeitwerk's one-file-one-constant autoload convention:
+  # only the file's "primary" constant (Graph, matching the filename) gets an
+  # autoload stub, so referencing Node or Edge first raises NameError. Require
+  # it eagerly here so all three are real constants before anything uses them.
+  require_relative "saga_forge/dashboard/graph"
+
+  class Error < StandardError; end
+
+  # Boot-time definition errors
+  class AmbiguousEventError < Error; end
+  class UnknownCompensationError < Error; end
+  class MissingCorrelationError < Error; end
+  class NoTerminalStateError < Error; end
+  class DefinitionError < Error; end
+
+  # Runtime errors
+  class UnknownStateError < Error; end
+  class UnstagedPublishError < Error; end
+  class ConcurrencyConflict < Error; end # internal: version race / duplicate create
+  class ForwardOnlyError < Error; end # transition/advance re-enters a visited state
+
+  class << self
+    def config = @config ||= Configuration.new
+
+    def configure = yield(config)
+
+    def reset_configuration! = @config = Configuration.new
+
+    # External publish entry point. Raises UnstagedPublishError inside
+    # saga execution — use saga.publish there. (Publisher lands in Task 4.)
+    def publish(event_name, **payload)
+      Publisher.publish(event_name, payload: payload)
+    end
+
+    # PK type for engine tables: explicit config → host generator config → Rails default.
+    def primary_key_type
+      config.primary_key_type ||
+        Rails.application&.config&.generators&.options&.dig(:active_record, :primary_key_type) ||
+        :primary_key
+    end
+
+    # --- execution guard ---
+
+    def within_saga_execution?
+      !!ActiveSupport::IsolatedExecutionState[:saga_forge_execution]
+    end
+
+    # Encoding-safe truncation for persisting error text into JSON columns:
+    # arbitrary bytes (binary paths, HTTP bodies) must never crash the
+    # failure-recording path itself.
+    def safe_error_message(msg, limit)
+      msg.to_s.encode("UTF-8", invalid: :replace, undef: :replace, replace: "\u{FFFD}").truncate(limit)
+    end
+
+    # Wrapped around user block invocation ONLY (forward, compensation, timeout
+    # blocks). Footgun-catcher, not a sandbox.
+    def guarding_execution
+      previous = ActiveSupport::IsolatedExecutionState[:saga_forge_execution]
+      ActiveSupport::IsolatedExecutionState[:saga_forge_execution] = true
+      yield
+    ensure
+      ActiveSupport::IsolatedExecutionState[:saga_forge_execution] = previous
+    end
+  end
+end
+
+require "saga_forge/railtie"