geneva_drive 0.5.0 → 0.7.0

data/lib/geneva_drive/workflow.rb

@@ -22,6 +22,9 @@
 class GenevaDrive::Workflow < ActiveRecord::Base
   self.table_name = "geneva_drive_workflows"
 
+  require_relative "workflow/metadata_accessor"
+  include MetadataAccessor
+
   # Workflow states as enum with string values
   # Provides: ready?, performing?, etc. predicates
   # Provides: ready, performing, etc. scopes
@@ -40,6 +43,11 @@ class GenevaDrive::Workflow < ActiveRecord::Base
     foreign_key: :workflow_id,
     inverse_of: :workflow,
     dependent: :delete_all
+  has_many :signals,
+    class_name: "GenevaDrive::Signal",
+    foreign_key: :workflow_id,
+    inverse_of: :workflow,
+    dependent: :delete_all
 
   # Class-inheritable attributes for DSL
   class_attribute :_step_definitions, instance_writer: false, default: []
@@ -68,6 +76,7 @@ class GenevaDrive::Workflow < ActiveRecord::Base
     # @param name [String, Symbol, nil] the step name (auto-generated if nil)
     # @param options [Hash] step options
     # @option options [ActiveSupport::Duration, nil] :wait delay before execution
+    # @option options [Hash] :job_options options passed to Active Job's set method
     # @option options [Proc, Symbol, Boolean, nil] :skip_if condition for skipping
     # @option options [Symbol, GenevaDrive::ExceptionPolicy, Proc, Array<GenevaDrive::ExceptionPolicy>] :on_exception
     #   exception handling policy. Accepts:
@@ -119,24 +128,7 @@ class GenevaDrive::Workflow < ActiveRecord::Base
       call_location = caller_loc ? [caller_loc.path, caller_loc.lineno] : nil
       block_location = block&.source_location
 
-      # Duplicate parent's array only if we haven't already (avoid mutating inherited definitions)
-      if _step_definitions.equal?(superclass._step_definitions)
-        self._step_definitions = _step_definitions.dup
-      end
-      # Invalidate cached step collection since we're adding a step
-      @steps = nil
-
-      step_name = (name || generate_step_name).to_s
-
-      # Check for duplicate step names
-      if _step_definitions.any? { |s| s.name == step_name }
-        raise GenevaDrive::StepConfigurationError,
-          "Step '#{step_name}' is already defined in #{self.name}"
-      end
-
-      # Validate positioning references exist
-      validate_step_positioning_reference!(step_name, options[:before_step], :before_step)
-      validate_step_positioning_reference!(step_name, options[:after_step], :after_step)
+      step_name = prepare_step_registration!(name, options)
 
       step_def = GenevaDrive::StepDefinition.new(
         name: step_name,
@@ -151,6 +143,69 @@ class GenevaDrive::Workflow < ActiveRecord::Base
       step_def
     end
 
+    # Defines a resumable step that can iterate over large collections.
+    # The block receives an IterableStep object for cursor-based iteration
+    # that survives job restarts.
+    #
+    # @param name [String, Symbol, nil] the step name (auto-generated if nil)
+    # @param options [Hash] step options
+    # @option options [Integer, nil] :max_iterations interrupt after N iterations
+    # @option options [ActiveSupport::Duration, nil] :max_runtime interrupt after duration
+    # @option options [ActiveSupport::Duration, nil] :wait delay before execution
+    # @option options [Proc, Symbol, Boolean, nil] :skip_if condition for skipping
+    # @option options [Symbol] :on_exception exception handler (:pause!, :cancel!, :reattempt!, :skip!)
+    # @option options [String, Symbol, nil] :before_step position before this step
+    # @option options [String, Symbol, nil] :after_step position after this step
+    # @yield [iter] the step implementation receiving an IterableStep object
+    # @yieldparam iter [GenevaDrive::IterableStep] cursor management object
+    # @return [void]
+    #
+    # @example Iterate over records with automatic checkpointing
+    #   resumable_step :process_users do |iter|
+    #     iter.iterate_over_records(hero.users) do |user|
+    #       process(user)
+    #     end
+    #   end
+    #
+    # @example Manual cursor control
+    #   resumable_step :sync_pages do |iter|
+    #     page = iter.cursor || 1
+    #     loop do
+    #       response = Api.fetch(page: page)
+    #       break if response.empty?
+    #       response.each { |item| process(item) }
+    #       page += 1
+    #       iter.set!(page)
+    #     end
+    #   end
+    #
+    # @example With iteration limits
+    #   resumable_step :bulk_import, max_iterations: 10_000 do |iter|
+    #     iter.iterate_over_records(records) { |r| import(r) }
+    #   end
+    def resumable_step(name = nil, **options, &block)
+      raise ArgumentError, "resumable_step requires a block" unless block_given?
+
+      # Capture source locations before any other operations
+      caller_loc = caller_locations(1, 1).first
+      call_location = caller_loc ? [caller_loc.path, caller_loc.lineno] : nil
+      block_location = block.source_location
+
+      step_name = prepare_step_registration!(name, options)
+
+      step_def = GenevaDrive::ResumableStepDefinition.new(
+        name: step_name,
+        call_location: call_location,
+        block_location: block_location,
+        **options,
+        &block
+      )
+
+      _step_definitions << step_def
+
+      step_def
+    end
+
     # Defines a blanket cancellation condition for the workflow.
     # Checked before every step execution.
     #
@@ -180,8 +235,9 @@ class GenevaDrive::Workflow < ActiveRecord::Base
     # @example Set queue for workflow steps
     #   set_step_job_options queue: :workflows, priority: 10
     def set_step_job_options(**options)
+      validated = GenevaDrive::JobOptions.validate!(options, context: "#{name || "Workflow"}.set_step_job_options")
       # Merge with parent's options
-      self._step_job_options = _step_job_options.merge(options)
+      self._step_job_options = _step_job_options.merge(validated)
     end
 
     # Allows the workflow to continue even if the hero is deleted.
@@ -205,21 +261,25 @@ class GenevaDrive::Workflow < ActiveRecord::Base
     # Policies are checked when a step raises an exception and the step itself
     # does not have an explicit `on_exception:` override.
     #
-    # @overload on_exception(action, *exception_matchers, wait: nil, max_reattempts: nil)
+    # @overload on_exception(action, *exception_matchers, wait: nil, max_reattempts: nil, report: :always)
     #   Declarative mode — specify an action symbol.
     #   @param action [Symbol] :pause!, :cancel!, :reattempt!, or :skip!
     #   @param exception_matchers [Array<Class>] optional exception classes to match
     #   @param wait [ActiveSupport::Duration, nil] wait before reattempt
     #   @param max_reattempts [Integer, nil] max consecutive reattempts
+    #   @param report [Symbol] when to report the exception to +Rails.error.report+
+    #     (+:always+, +:never+, or +:terminal_only+). See {ExceptionPolicy} for details.
     #
-    # @overload on_exception(*exception_matchers, action:, wait: nil, max_reattempts: nil)
+    # @overload on_exception(*exception_matchers, action:, wait: nil, max_reattempts: nil, report: :always)
     #   Declarative mode with exception classes as leading args and action as keyword.
     #   @param exception_matchers [Array<Class>] exception classes to match
     #   @param action [Symbol] :pause!, :cancel!, :reattempt!, or :skip!
+    #   @param report [Symbol] when to report the exception (+:always+, +:never+, or +:terminal_only+)
     #
-    # @overload on_exception(*exception_matchers, &block)
+    # @overload on_exception(*exception_matchers, report: :always, &block)
     #   Imperative mode — block receives exception, runs in workflow context.
     #   @param exception_matchers [Array<Class>] optional exception classes to match
+    #   @param report [Symbol] when to report the exception (+:always+, +:never+, or +:terminal_only+)
     #   @yield [error] the exception that was raised
     #
     # @example Blanket default for all exceptions
@@ -233,7 +293,15 @@ class GenevaDrive::Workflow < ActiveRecord::Base
     #   on_exception RateLimitError do |error|
     #     reattempt! wait: error.retry_after.seconds
     #   end
-    def on_exception(*args, action: nil, wait: nil, max_reattempts: nil, terminal_action: :pause!, &block)
+    #
+    # @example Suppress reporting for expected rate limits
+    #   on_exception RateLimitError, report: :never do |error|
+    #     reattempt! wait: error.retry_after.seconds
+    #   end
+    #
+    # @example Report only when reattempts are exhausted
+    #   on_exception Timeout::Error, action: :reattempt!, max_reattempts: 5, report: :terminal_only
+    def on_exception(*args, action: nil, wait: nil, max_reattempts: nil, terminal_action: :pause!, report: :always, &block)
       # Separate exception classes from a leading action symbol
       if args.first.is_a?(Symbol)
         raise ArgumentError, "Cannot pass both a positional action and action: keyword" if action
@@ -258,10 +326,10 @@ class GenevaDrive::Workflow < ActiveRecord::Base
       end
 
       policy = if block
-        GenevaDrive::ExceptionPolicy.new(&block)
+        GenevaDrive::ExceptionPolicy.new(report: report, &block)
       else
         raise ArgumentError, "Either an action or a block is required" unless action
-        GenevaDrive::ExceptionPolicy.new(action, wait: wait, max_reattempts: max_reattempts, terminal_action: terminal_action)
+        GenevaDrive::ExceptionPolicy.new(action, wait: wait, max_reattempts: max_reattempts, terminal_action: terminal_action, report: report)
       end
 
       policy.exception_matchers.concat(exception_matchers)
@@ -314,6 +382,36 @@ class GenevaDrive::Workflow < ActiveRecord::Base
 
     private
 
+    # Shared bookkeeping for registering a step definition: copy-on-write of
+    # the inherited definitions array, cache invalidation, name generation,
+    # duplicate-name check, and positioning validation.
+    #
+    # @param name [String, Symbol, nil] the requested step name
+    # @param options [Hash] the step options (read for before_step/after_step)
+    # @return [String] the resolved step name
+    def prepare_step_registration!(name, options)
+      # Duplicate parent's array only if we haven't already (avoid mutating inherited definitions)
+      if _step_definitions.equal?(superclass._step_definitions)
+        self._step_definitions = _step_definitions.dup
+      end
+      # Invalidate cached step collection since we're adding a step
+      @steps = nil
+
+      step_name = (name || generate_step_name).to_s
+
+      # Check for duplicate step names
+      if _step_definitions.any? { |s| s.name == step_name }
+        raise GenevaDrive::StepConfigurationError,
+          "Step '#{step_name}' is already defined in #{self.name}"
+      end
+
+      # Validate positioning references exist
+      validate_step_positioning_reference!(step_name, options[:before_step], :before_step)
+      validate_step_positioning_reference!(step_name, options[:after_step], :after_step)
+
+      step_name
+    end
+
     # Validates that a positioning reference (before_step/after_step) exists.
     #
     # @param step_name [String] the step being defined
@@ -428,22 +526,249 @@ class GenevaDrive::Workflow < ActiveRecord::Base
       update!(state: "ready", transitioned_at: nil)
     end
 
-    # Look for a scheduled execution to resume
+    # A scheduled execution preserved by pause! takes precedence - re-enqueue it
     scheduled_execution = current_execution
     if scheduled_execution
-      enqueue_scheduled_execution(scheduled_execution)
-    else
-      # No scheduled execution exists - create one for the next step
-      step_def = steps.named(next_step_name)
-      create_step_execution(step_def, wait: nil)
+      # A parked execution is not re-enqueued: it is waiting for an event, not
+      # for a clock. Re-run the rendezvous instead, which delivers any signal
+      # that arrived while the workflow was paused.
+      return rendezvous_waiting_execution!(scheduled_execution) if scheduled_execution.waiting?
+
+      return enqueue_scheduled_execution(scheduled_execution)
+    end
+
+    # Resumable-step continuations need the cursor/continues_from_id columns
+    if GenevaDrive::StepExecution.resumable_columns?
+      # Check for a resumable step that was paused mid-iteration. Only the most
+      # recent marker row counts, and only while it has not been consumed yet
+      # (creating a successor consumes it - the successor's presence marks that).
+      paused_resumable_execution = step_executions
+        .where(outcome: "workflow_paused", state: "completed")
+        .order(created_at: :desc, id: :desc)
+        .first
+
+      if paused_resumable_execution && paused_resumable_execution.successor.nil?
+        logger.info("Resuming from resumable execution #{paused_resumable_execution.id}, cursor: #{paused_resumable_execution.cursor_value.inspect}")
+        return create_successor_execution!(paused_resumable_execution)
+      end
+
+      # A resumable step that failed (pausing the workflow) resumes from its
+      # persisted cursor instead of redoing the whole iteration.
+      failed_execution = step_executions
+        .where(step_name: next_step_name, state: "failed")
+        .order(created_at: :desc, id: :desc)
+        .first
+      if failed_execution && failed_execution.cursor.present? && failed_execution.successor.nil?
+        logger.info("Retrying failed resumable execution #{failed_execution.id} from cursor: #{failed_execution.cursor_value.inspect}")
+        return create_successor_execution!(failed_execution)
+      end
+    end
+
+    # No scheduled execution exists - create one for the next step
+    step_def = steps.named(next_step_name)
+    create_step_execution(step_def, wait: nil)
+  end
+
+  # Delivers an external event to this workflow.
+  #
+  # The signal row is persisted first and dispatched second, which is what
+  # makes arrival order irrelevant: a signal that lands before the waiting
+  # step's execution even exists simply sits in the table until that step's
+  # gate picks it up, and a signal that lands while a step is already parked
+  # wakes it immediately.
+  #
+  # Pass an +idempotency_key+ (a webhook's event id, typically) to make
+  # redelivery a no-op: the second call returns the row the first one wrote,
+  # flagged {GenevaDrive::Signal#duplicate_delivery?}, without dispatching.
+  #
+  # On a paused workflow the row is persisted but not dispatched - waking a
+  # step while the workflow is paused would only get its execution canceled.
+  # {#resume!} performs the rendezvous instead.
+  #
+  # @param signal_name [Symbol, String] the event name
+  # @param payload [Object] data describing the event, serialized through ActiveJob
+  # @param idempotency_key [String, nil] deduplication key, scoped to (workflow, name)
+  # @return [GenevaDrive::Signal] the persisted signal
+  # @raise [ArgumentError] if the signal name is blank
+  # @raise [WorkflowNotOngoing] if the workflow is finished or canceled and this is a new event
+  # @raise [SignalPayloadTooLargeError] if the payload exceeds GenevaDrive.max_signal_payload_size
+  #
+  # @example Deliver a webhook event
+  #   workflow = OrderFulfillmentWorkflow.ongoing.for_hero(order).first
+  #   workflow.signal!(:payment_confirmed,
+  #     payload: {amount_cents: 12_500},
+  #     idempotency_key: event["id"])
+  def signal!(signal_name, payload: {}, idempotency_key: nil, **unknown_options)
+    if unknown_options.any?
+      raise ArgumentError,
+        "Unknown options passed to signal!: #{unknown_options.keys.join(", ")}"
+    end
+
+    if signal_name.blank?
+      raise ArgumentError, "signal! requires a signal name"
+    end
+
+    name = signal_name.to_s
+    dedup_key = idempotency_key&.to_s
+
+    # Serialize (and bound) before anything is persisted.
+    serialized_payload = GenevaDrive::Signal.serialize_payload(payload)
+
+    signal = nil
+    duplicate = false
+
+    # One transaction covers the lot: the INSERT, the waiting-execution scan,
+    # and every attach, flip and counter bump. Taking the lock before writing
+    # anything is what makes delivery all-or-nothing - insert first and
+    # dispatch second, and a crash in between would leave a pending signal
+    # sitting next to a waiting execution with nothing left to introduce them.
+    with_lock do
+      # with_lock reloads; the terminal check belongs inside it
+      unless ongoing?
+        existing = dedup_key && signals.find_by(name: name, idempotency_key: dedup_key)
+        unless existing
+          raise GenevaDrive::WorkflowNotOngoing,
+            "Cannot deliver signal #{name.inspect} to a #{state} workflow"
+        end
+
+        logger.info("Signal #{name.inspect} redelivered to #{state} workflow, returning existing row")
+        signal = existing
+        duplicate = true
+        next
+      end
+
+      begin
+        # A savepoint so that hitting the dedup index does not poison the
+        # transaction - the caller's, if they had one open, or ours.
+        transaction(requires_new: true) do
+          record = signals.new(name: name, idempotency_key: dedup_key, state: "pending")
+          record[:payload] = serialized_payload
+          record.save!
+          signal = record
+        end
+      rescue ActiveRecord::RecordNotUnique
+        signal = signals.find_by!(name: name, idempotency_key: dedup_key)
+        logger.info("Signal #{name.inspect} is a duplicate delivery of signal #{signal.id}, not dispatching")
+        duplicate = true
+        next
+      end
+
+      logger.info("Received signal #{name.inspect} as signal #{signal.id}")
+
+      if paused?
+        logger.info("Workflow is paused, buffering signal #{signal.id} until resume!")
+      else
+        wake_executions_matching!(signal)
+      end
     end
+
+    signal.duplicate_delivery! if duplicate
+    signal
   end
 
   # Returns the current active step execution, if any.
+  # Includes scheduled, waiting and in_progress states.
   #
   # @return [StepExecution, nil] the current execution
   def current_execution
-    step_executions.where(state: %w[scheduled in_progress]).first
+    step_executions.where(state: %w[scheduled waiting in_progress]).first
+  end
+
+  # Signals that may still be attached to an execution, oldest first, each
+  # pointing back at this workflow instance.
+  #
+  # Matcher blocks are instance_exec'd on `signal.workflow`, and `inverse_of:`
+  # only primes records loaded straight off the association - a scoped
+  # relation would hand each signal a freshly loaded workflow, which would
+  # then see none of the caller's unsaved state.
+  #
+  # @return [Array<GenevaDrive::Signal>]
+  # @api private
+  public def attachable_signals
+    signals.attachable.map { |signal| adopt_signal(signal) }
+  end
+
+  # Wakes every parked step execution whose matcher accepts the given signal.
+  #
+  # Runs under the workflow row lock - the same lock create_step_execution
+  # and the Executor take - so whichever of dispatch and the gate commits
+  # second sees the other's write and no signal can slip through the gap.
+  #
+  # @param signal [GenevaDrive::Signal] the signal to deliver
+  # @return [Array<StepExecution>] the executions that were woken
+  # @api private
+  public def dispatch_signal!(signal)
+    return [] unless GenevaDrive::StepExecution.signal_columns?
+
+    with_lock { wake_executions_matching!(signal) }
+  end
+
+  # Settles the signal attached to an execution we are deliberately moving
+  # past, wherever the skip came from: `skip_if` firing at wake, flow control
+  # inside the step, an exception policy, or an operator calling `skip!`.
+  #
+  # Consumption follows attachment. A skip in any flavor says "we are done
+  # with this step", so an event that was delivered to it is spent by that
+  # decision - leaving it claimed would hand a stale event to the next waiter
+  # for the same name, which is exactly what consume-once-per-event forbids.
+  # An execution that never attached has nothing to settle, so buffered
+  # signals a step never reached are left alone.
+  #
+  # Must be called with the workflow lock held, so the settle rides the same
+  # transaction as the skip itself.
+  #
+  # @param step_execution [StepExecution, nil] the execution being skipped past
+  # @return [GenevaDrive::Signal, nil] the settled signal, if there was one
+  # @api private
+  public def settle_signal_for_skipped!(step_execution)
+    return unless GenevaDrive::StepExecution.signal_columns?
+    return if step_execution.nil? || step_execution.signal_id.blank?
+
+    signal = step_execution.signal
+    return unless signal && signal.state == "claimed"
+
+    logger.info("Skipping past step #{step_execution.step_name}, settling attached signal #{signal.id} (#{signal.name})")
+    signal.record_consumption!(resolved_step_names: [step_execution.step_name])
+    signal
+  end
+
+  # The body of dispatch, for callers that already hold the workflow lock
+  # (`signal!` holds it across the whole delivery so the rows land atomically).
+  #
+  # @param signal [GenevaDrive::Signal] the signal to deliver
+  # @return [Array<StepExecution>] the executions that were woken
+  # @api private
+  public def wake_executions_matching!(signal)
+    return [] unless GenevaDrive::StepExecution.signal_columns?
+    return [] if paused? || !ongoing?
+
+    # Matcher blocks run on signal.workflow, so point the signal at this very
+    # instance instead of letting it load a second copy from the database.
+    adopt_signal(signal)
+    woken = []
+
+    step_executions.where(state: "waiting").order(created_at: :asc, id: :asc).each do |execution|
+      step_def = execution.step_definition
+      # A step whose definition is gone (class removed, step renamed) can
+      # never match - the matcher lives on the definition.
+      next unless step_def&.waits_for_signal?
+      next unless step_def.signal_matcher.matches?(signal)
+
+      signal.claim!
+      execution.update!(
+        signal_id: signal.id,
+        state: "scheduled",
+        scheduled_for: Time.current,
+        waiting_since: nil
+      )
+      woken << [execution, step_def]
+    end
+
+    woken.each do |execution, step_def|
+      enqueue_woken_execution(execution, step_def)
+    end
+
+    woken.map(&:first)
   end
 
   # Returns all step executions in chronological order.
@@ -525,6 +850,30 @@ class GenevaDrive::Workflow < ActiveRecord::Base
     yield
   end
 
+  # Returns per-instance step job options stored in metadata.
+  # These are merged with the class-level options when enqueuing step jobs,
+  # with instance options taking precedence.
+  #
+  # @return [Hash] symbolized job options (e.g. `{ queue: :high, priority: 5 }`)
+  def step_job_options
+    (read_metadata("step_job_options") || {}).symbolize_keys
+  end
+
+  # Sets per-instance step job options in metadata.
+  # Stored as part of the workflow's metadata column so they persist and
+  # survive across step boundaries.
+  #
+  # @param options [Hash, nil] job options to store
+  # @return [void]
+  def step_job_options=(options)
+    if options.present?
+      validated = GenevaDrive::JobOptions.validate!(options, context: "#{self.class.name}#step_job_options=")
+      write_metadata("step_job_options", validated.stringify_keys)
+    else
+      write_metadata("step_job_options", nil)
+    end
+  end
+
   # Transitions the workflow to a new state.
   #
   # @param new_state [String] the target state
@@ -542,6 +891,17 @@ class GenevaDrive::Workflow < ActiveRecord::Base
 
   private
 
+  # Returns class-level step job options merged with per-instance and step overrides.
+  # Instance options take precedence over class options; step options take final precedence.
+  #
+  # @param step_definition [StepDefinition, nil] step whose job options should override defaults
+  # @return [Hash] merged job options
+  def merged_step_job_options(step_definition)
+    self.class._step_job_options
+      .merge(step_job_options)
+      .merge(step_definition&.job_options || {})
+  end
+
   # Validates that no other ongoing workflow exists for the same (type, hero).
   # Mirrors the database unique index on (type, hero_type, hero_id) for ongoing workflows.
   #
@@ -578,6 +938,64 @@ class GenevaDrive::Workflow < ActiveRecord::Base
     create_step_execution(first_step, wait: first_step.wait)
   end
 
+  # Points a signal's workflow association at this instance, so matcher
+  # blocks - which are instance_exec'd on it - see the live object.
+  #
+  # @param signal [GenevaDrive::Signal]
+  # @return [GenevaDrive::Signal] the same signal
+  def adopt_signal(signal)
+    signal.association(:workflow).target = self
+    signal
+  end
+
+  # Enqueues the PerformStepJob for an execution that dispatch just flipped
+  # from waiting to scheduled. Uses the same enqueue discipline (merged job
+  # options, after-commit deferral, job_id writeback) as create_step_execution.
+  #
+  # @param step_execution [StepExecution] the woken execution
+  # @param step_definition [StepDefinition] its step definition
+  # @return [void]
+  def enqueue_woken_execution(step_execution, step_definition)
+    job_options = merged_step_job_options(step_definition)
+    execution_id = step_execution.id
+    workflow_logger = logger
+
+    run_after_commit do
+      job = GenevaDrive::PerformStepJob
+        .set(**job_options)
+        .perform_later(execution_id)
+
+      workflow_logger.debug("Enqueued PerformStepJob with job_id=#{job.job_id} for woken step execution #{execution_id}")
+
+      GenevaDrive::StepExecution
+        .where(id: execution_id)
+        .update_all(job_id: job.job_id)
+    end
+  end
+
+  # Re-runs the rendezvous for a step execution that is parked waiting for a
+  # signal. Signals that arrived while the workflow was paused are delivered
+  # here, on resume.
+  #
+  # @param step_execution [StepExecution] the parked execution
+  # @return [StepExecution] the same execution (rescheduled if a signal matched)
+  def rendezvous_waiting_execution!(step_execution)
+    step_def = step_execution.step_definition
+    matcher = step_def&.signal_matcher
+
+    if matcher
+      candidate = attachable_signals.detect { |signal| matcher.matches?(signal) }
+      if candidate
+        logger.info("Resuming into a matching signal #{candidate.id} (#{candidate.name}) for step #{step_execution.step_name}")
+        dispatch_signal!(candidate)
+        return step_execution.reload
+      end
+    end
+
+    logger.info("Step #{step_execution.step_name} stays parked - no matching signal has arrived yet")
+    step_execution
+  end
+
   # Enqueues a job for an existing scheduled execution.
   #
   # If the execution is overdue (scheduled_for is in the past), runs immediately.
@@ -593,7 +1011,7 @@ class GenevaDrive::Workflow < ActiveRecord::Base
     logger.info("Enqueuing job for step #{step_execution.step_name} to run #{wait_msg}")
 
     # Capture values for the callback
-    job_options = self.class._step_job_options.dup
+    job_options = merged_step_job_options(step_execution.step_definition)
     job_options[:wait_until] = wait_until if wait_until
     execution_id = step_execution.id
     workflow_logger = logger
@@ -615,6 +1033,65 @@ class GenevaDrive::Workflow < ActiveRecord::Base
     step_execution
   end
 
+  # Creates a successor step execution that continues a resumable step from
+  # the cursor persisted on the given execution. Used by the Executor when a
+  # resumable step interrupts itself, by resume! for workflows paused
+  # mid-iteration, and by housekeeping recovery of stuck resumable steps.
+  #
+  # The successor is enqueued with the same merged job options (class,
+  # per-instance, per-step) as any other execution of the step.
+  #
+  # @param predecessor [StepExecution] the execution to continue from
+  # @param wait [ActiveSupport::Duration, Numeric, nil] optional delay
+  # @return [StepExecution] the new successor execution
+  # @api private
+  public def create_successor_execution!(predecessor, wait: nil)
+    scheduled_for = wait ? wait.from_now : Time.current
+
+    with_lock do
+      # Cancel any stray scheduled or parked executions - the successor is the
+      # one execution that should run next (same as create_step_execution).
+      cancel_stray_executions!
+
+      successor_attributes = {
+        step_name: predecessor.step_name,
+        state: "scheduled",
+        scheduled_for: scheduled_for,
+        continues_from_id: predecessor.id,
+        cursor: predecessor.cursor
+      }
+      # Carry the attachment pin across the chain so successors never re-park
+      # and received_signal stays stable for the whole iteration.
+      if GenevaDrive::StepExecution.signal_columns?
+        successor_attributes[:signal_id] = predecessor.signal_id
+      end
+
+      successor = step_executions.create!(**successor_attributes)
+
+      # next_step_name points to the step that's scheduled to run next
+      update!(next_step_name: predecessor.step_name)
+
+      job_options = merged_step_job_options(predecessor.step_definition)
+      job_options[:wait_until] = scheduled_for if wait
+      successor_id = successor.id
+      workflow_logger = logger
+
+      run_after_commit do
+        job = GenevaDrive::PerformStepJob
+          .set(**job_options)
+          .perform_later(successor_id)
+
+        workflow_logger.debug("Enqueued PerformStepJob with job_id=#{job.job_id} for successor execution ##{successor_id}")
+
+        GenevaDrive::StepExecution
+          .where(id: successor_id)
+          .update_all(job_id: job.job_id)
+      end
+
+      successor
+    end
+  end
+
   # Creates a step execution and enqueues the job after transaction commits.
   # Any existing scheduled step executions are canceled first.
   # In-progress step executions are left alone - they're being executed.
@@ -629,15 +1106,7 @@ class GenevaDrive::Workflow < ActiveRecord::Base
     scheduled_for = wait ? wait.from_now : Time.current
 
     with_lock do
-      # Cancel any scheduled step executions (not in_progress - those are being executed).
-      # Safe to use update_all since we hold the workflow lock, blocking any executor
-      # that would try to start these steps.
-      canceled_count = step_executions.scheduled.update_all(
-        state: "canceled",
-        outcome: "canceled",
-        canceled_at: Time.current
-      )
-      logger.debug("Canceled #{canceled_count} previously scheduled step execution(s)") if canceled_count > 0
+      cancel_stray_executions!
 
       step_execution = step_executions.create!(
         step_name: step_definition.name,
@@ -649,7 +1118,7 @@ class GenevaDrive::Workflow < ActiveRecord::Base
       update!(next_step_name: step_definition.name)
 
       # Capture values for the after_commit callback
-      job_options = self.class._step_job_options.dup
+      job_options = merged_step_job_options(step_definition)
       job_options[:wait_until] = scheduled_for if wait
       execution_id = step_execution.id
       workflow_logger = logger
@@ -681,6 +1150,26 @@ class GenevaDrive::Workflow < ActiveRecord::Base
     end
   end
 
+  # Cancels any scheduled or parked step executions so that the execution
+  # about to be created is the only one that will run. In-progress executions
+  # are left alone - they are being executed.
+  #
+  # Safe to use update_all because the caller holds the workflow lock, which
+  # blocks any executor that would try to start these steps. Parked executions
+  # are swept for the same reason: no legitimate path creates a new execution
+  # past one that is waiting.
+  #
+  # @return [Integer] the number of executions canceled
+  def cancel_stray_executions!
+    canceled_count = step_executions.where(state: %w[scheduled waiting]).update_all(
+      state: "canceled",
+      outcome: "canceled",
+      canceled_at: Time.current
+    )
+    logger.debug("Canceled #{canceled_count} previously scheduled step execution(s)") if canceled_count > 0
+    canceled_count
+  end
+
   # Finishes the workflow.
   #
   # @return [nil]
@@ -737,6 +1226,33 @@ class GenevaDrive::Workflow < ActiveRecord::Base
     @tagged_logger = previous_tagged_logger
   end
 
+  # The signal that woke the step currently executing, or nil when the step
+  # does not declare +wait_for:+. Available inside step bodies only.
+  #
+  # @return [GenevaDrive::Signal, nil]
+  #
+  # @example Read the payload of the event that woke the step
+  #   step :capture, wait_for: :payment_confirmed do
+  #     hero.capture!(received_signal.payload[:amount_cents])
+  #   end
+  public attr_reader :received_signal
+
+  # Temporarily makes a signal available to step code as +received_signal+
+  # for the duration of the block. Injected by the Executor the same way the
+  # tagged logger is.
+  #
+  # @param signal [GenevaDrive::Signal, nil] the attached signal
+  # @yield the block to execute with the signal in scope
+  # @return [Object] the result of the block
+  # @api private
+  public def with_received_signal(signal)
+    previous_received_signal = @received_signal
+    @received_signal = signal
+    yield
+  ensure
+    @received_signal = previous_received_signal
+  end
+
   # Returns the Logger properly tagged to this Workflow
   #
   # @return [Logger]