geneva_drive 0.5.0 → 0.6.0

data/lib/geneva_drive/exception_policy.rb

@@ -85,6 +85,9 @@ class GenevaDrive::ExceptionPolicy
   #   Each entry can be an Exception subclass or any object responding to #===.
   attr_reader :exception_matchers
 
+  # @return [Symbol] when to report the exception via Rails.error.report (:always, :never, or :terminal_only)
+  attr_reader :report
+
   # @return [Proc, nil] the handler block (imperative mode)
   attr_reader :handler
 
@@ -93,7 +96,10 @@ class GenevaDrive::ExceptionPolicy
   # Valid terminal_action values
   VALID_TERMINAL_ACTIONS = %i[pause! cancel! skip!].freeze
 
-  # @overload initialize(action, matching: nil, wait: nil, max_reattempts: nil, terminal_action: :pause!)
+  # Valid report values
+  VALID_REPORT_OPTIONS = %i[always never terminal_only].freeze
+
+  # @overload initialize(action, matching: nil, wait: nil, max_reattempts: nil, terminal_action: :pause!, report: :always)
   #   Declarative mode — specify action and options.
   #   @param action [Symbol] the flow control action (:pause!, :cancel!, :reattempt!, :skip!)
   #   @param matching [Class, String, #===, Array<Class, String, #===>, nil] exception classes
@@ -104,12 +110,19 @@ class GenevaDrive::ExceptionPolicy
   #   @param wait [ActiveSupport::Duration, nil] wait time before reattempt
   #   @param max_reattempts [Integer, nil] max consecutive reattempts (nil = unlimited)
   #   @param terminal_action [Symbol] what to do when max_reattempts is exceeded (:pause!, :cancel!, or :skip!)
+  #   @param report [Symbol] when to report the exception to +Rails.error.report+.
+  #     - +:always+ (default) — report every exception regardless of what action is taken
+  #     - +:never+ — never report; the exception is expected and handled by the policy
+  #     - +:terminal_only+ — suppress reports while the step is being reattempted, but
+  #       report when reattempts are exhausted and the +terminal_action+ fires
   #
-  # @overload initialize(matching: nil, &block)
+  # @overload initialize(matching: nil, report: :always, &block)
   #   Imperative mode — block receives exception, runs in workflow context.
   #   Must call a flow control method (reattempt!, cancel!, pause!, skip!).
-  #   Can be combined with +matching:+ to target specific exception classes.
+  #   Can be combined with +matching:+ and +report:+ to target specific exception classes
+  #   and control error reporting.
   #   @param matching [Class, String, #===, Array<Class, String, #===>, nil] exception classes
+  #   @param report [Symbol] when to report the exception (+:always+, +:never+, or +:terminal_only+)
   #   @yield [error] the exception that was raised
   #
   # @example Blanket reattempt policy
@@ -126,7 +139,18 @@ class GenevaDrive::ExceptionPolicy
   #
   # @example Imperative policy with exception matching
   #   ExceptionPolicy.new(matching: Timeout::Error) { |error| reattempt!(wait: error.retry_after) }
-  def initialize(action = nil, wait: nil, max_reattempts: nil, terminal_action: :pause!, matching: nil, &block)
+  #
+  # @example Suppress error reporting for expected exceptions
+  #   ExceptionPolicy.new(:reattempt!, matching: RateLimitError, report: :never)
+  #
+  # @example Only report when reattempts are exhausted
+  #   ExceptionPolicy.new(:reattempt!, matching: Net::OpenTimeout, max_reattempts: 5, report: :terminal_only)
+  def initialize(action = nil, wait: nil, max_reattempts: nil, terminal_action: :pause!, matching: nil, report: :always, &block)
+    @report = report
+    unless VALID_REPORT_OPTIONS.include?(@report)
+      raise ArgumentError,
+        "report: must be one of #{VALID_REPORT_OPTIONS.join(", ")}, got #{@report.inspect}"
+    end
     if block
       if action || wait || max_reattempts || terminal_action != :pause!
         raise ArgumentError,
@@ -191,8 +215,10 @@ class GenevaDrive::ExceptionPolicy
   # in the workflow context and translates the resulting flow control signal
   # into a result.
   #
-  # The returned Hash always contains +:action+ (Symbol without +!+) and
-  # +:error+ (the original exception). Reattempt results also include +:wait+.
+  # The returned Hash always contains +:action+ (Symbol without +!+),
+  # +:error+ (the original exception), and +:report+ (the reporting mode).
+  # Reattempt results also include +:wait+. When the terminal action fires
+  # (reattempt limit exceeded), +:terminal+ is set to +true+.
   #
   # @param error [Exception] the exception that was raised
   # @param reattempt_count [Integer] consecutive reattempts so far for this step
@@ -241,9 +267,9 @@ class GenevaDrive::ExceptionPolicy
     end
 
     if signal.is_a?(GenevaDrive::FlowControlSignal)
-      {action: signal.action, wait: signal.options[:wait], error: error}
+      {action: signal.action, wait: signal.options[:wait], error: error, report: @report}
     else
-      {action: :pause, error: error}
+      {action: :pause, error: error, report: @report}
     end
   end
 
@@ -256,9 +282,9 @@ class GenevaDrive::ExceptionPolicy
   def apply_declarative(error, reattempt_count)
     if action == :reattempt! && max_reattempts && reattempt_count >= max_reattempts
       terminal = terminal_action.to_s.chomp("!").to_sym
-      {action: terminal, error: error}
+      {action: terminal, error: error, report: @report, terminal: true}
     else
-      {action: action.to_s.chomp("!").to_sym, wait: wait, error: error}
+      {action: action.to_s.chomp("!").to_sym, wait: wait, error: error, report: @report}
     end
   end
 

data/lib/geneva_drive/executor.rb

@@ -25,7 +25,14 @@ class GenevaDrive::Executor
     "performing" => %w[ready performing canceled paused finished]
   }.freeze
 
+  # Result of a resumable step interrupting itself mid-iteration: the current
+  # execution completes with outcome "continued" and a successor execution is
+  # created to carry on from the persisted cursor. `wait` optionally delays
+  # the successor.
+  Interruption = Struct.new(:wait)
+
   # Executes a step execution with full flow control and exception handling.
+  # Handles both regular steps and resumable (cursor-iterating) steps.
   #
   # @param step_execution [GenevaDrive::StepExecution] the step to execute
   # @param logger [Logger, nil] optional base logger to inject into the workflow.
@@ -33,28 +40,39 @@ class GenevaDrive::Executor
   #   with workflow and step-specific tags added on top. This allows callers
   #   (background jobs, controllers, etc.) to pass in a logger that already
   #   has appropriate context tags (e.g., job_id, request_id).
+  # @param interruptible [Boolean] whether resumable steps respect interruption
+  #   conditions (max_iterations, max_runtime, shutdown, external pause/cancel).
+  #   Test helpers pass false to run a resumable step to completion in one call.
+  # @param max_iterations [Integer, nil] overrides the step definition's
+  #   max_iterations for this execution (used by the run_iterations test helper)
   # @return [void]
   #
   # @example Execute with a pre-tagged logger from a background job
   #   logger = Rails.logger.tagged("job_id=#{job_id}")
   #   GenevaDrive::Executor.execute!(step_execution, logger: logger)
-  def self.execute!(step_execution, logger: nil)
-    new.call(step_execution, logger: logger)
+  def self.execute!(step_execution, logger: nil, interruptible: true, max_iterations: nil)
+    new.call(step_execution, logger: logger, interruptible: interruptible, max_iterations: max_iterations)
   end
 
   # Performs the step execution.
   #
   # @param step_execution [GenevaDrive::StepExecution] the step to execute
   # @param logger [Logger, nil] optional base logger to inject into the workflow
+  # @param interruptible [Boolean] whether resumable steps respect interruption conditions
+  # @param max_iterations [Integer, nil] per-execution override of the step's max_iterations
   # @return [void]
-  def call(step_execution, logger: nil)
+  def call(step_execution, logger: nil, interruptible: true, max_iterations: nil)
     @step_execution = step_execution
     @workflow = step_execution.workflow
+    @interruptible = interruptible
+    @max_iterations_override = max_iterations
 
     # Build the full logger chain (base -> workflow -> step tags) and inject
     # it so step code calling `logger` gets the fully-tagged step execution
     # logger. Falls back to Rails.logger if no logger is provided.
     step_logger = build_step_logger(logger || Rails.logger, step_execution)
+    Rails.error.set_context(geneva_drive: error_context)
+
     @workflow.with_logger(step_logger) do
       step_execution.with_logger(step_logger) do
         execute_with_logger(step_execution)
@@ -62,6 +80,23 @@ class GenevaDrive::Executor
     end
   end
 
+  # Checks if a resumable step should be interrupted at a checkpoint.
+  # Called by IterableStep during checkpoint!.
+  #
+  # @param iterations [Integer, nil] iterations completed so far in this execution
+  # @return [Boolean]
+  def should_interrupt?(iterations: nil)
+    # If interruption is disabled (e.g., in tests), never interrupt
+    return false unless @interruptible
+
+    max_iterations = @max_iterations_override || (@step_definition.respond_to?(:max_iterations) ? @step_definition.max_iterations : nil)
+    return true if max_iterations && iterations && iterations >= max_iterations
+    return true if max_runtime_exceeded?
+    return true if job_should_exit?
+    return true if workflow_interrupted?
+    false
+  end
+
   private
 
   # Executes the step with the current logger configuration.
@@ -75,6 +110,9 @@ class GenevaDrive::Executor
     step_def = prepare_execution
     return unless step_def
 
+    @step_definition = step_def
+    @start_time = Time.current
+
     # Phase 2: Execute step block (locks released)
     @logger.debug("Running before_step_execution hook")
     @workflow.before_step_execution(@step_execution)
@@ -94,6 +132,20 @@ class GenevaDrive::Executor
 
   attr_reader :step_execution, :workflow, :logger
 
+  # Builds execution context to attach to Error Monitoring reports.
+  #
+  # @return [Hash]
+  def error_context
+    {
+      workflow_id: workflow.id,
+      workflow_class: workflow.class.name,
+      step_execution_id: step_execution.id,
+      step_name: step_execution.step_name,
+      hero_type: workflow.hero_type,
+      hero_id: workflow.hero_id
+    }.compact
+  end
+
   # Builds a fully-tagged logger for the step execution.
   # Adds workflow tags and step execution tags to the base logger.
   #
@@ -118,16 +170,19 @@ class GenevaDrive::Executor
 
   # Executes the step block with instrumentation.
   #
+  # For resumable steps, the block receives an IterableStep and runs inside a
+  # catch(:interrupt) so that checkpoints (and skip_to!) can interrupt the
+  # iteration. An interrupt is normalized into an {Interruption} result.
+  #
   # @param step_def [StepDefinition]
-  # @return [Symbol, FlowControlSignal, Hash] the execution result
+  # @return [Symbol, FlowControlSignal, Hash, Interruption] the execution result
   def execute_step(step_def)
     payload = instrumentation_payload
     payload[:step_name] = step_def.name
 
     ActiveSupport::Notifications.instrument("step.geneva_drive", payload) do |p|
       result = catch(:flow_control) do
-        step_def.execute_in_context(workflow)
-        :completed
+        run_step_code(step_def)
       rescue => e
         logger.error("Encountered #{e.class}, cleaning up and re-raising")
         # Don't transition here - just capture the error info
@@ -136,15 +191,47 @@ class GenevaDrive::Executor
 
       p[:outcome] = case result
       when :completed then :completed
+      when GenevaDrive::Executor::Interruption then :interrupted
       when GenevaDrive::FlowControlSignal then result.action
       when Hash then :exception
       end
       p[:exception] = result[:error] if result.is_a?(Hash)
+      p[:wait] = result.wait if result.is_a?(GenevaDrive::Executor::Interruption)
 
       result
     end
   end
 
+  # Runs the user's step code, handling the resumable interrupt channel.
+  #
+  # @param step_def [StepDefinition]
+  # @return [Symbol, Interruption] :completed, or an Interruption for resumable steps
+  def run_step_code(step_def)
+    unless step_def.resumable?
+      step_def.execute_in_context(workflow)
+      return :completed
+    end
+
+    iter = GenevaDrive::IterableStep.new(
+      step_def.name,
+      step_execution.cursor_value,
+      execution: step_execution,
+      resumed: step_execution.resuming?,
+      interrupter: self
+    )
+
+    # catch(:interrupt) returns:
+    # - :completed if the block finishes normally
+    # - nil if throw :interrupt (immediate successor)
+    # - Duration/Numeric if throw :interrupt, wait (delayed successor)
+    result = catch(:interrupt) do
+      step_def.execute_in_context(workflow, iter)
+      :completed
+    end
+
+    (result == :completed) ? :completed : Interruption.new(result)
+  end
+
   # Finalizes execution with instrumentation.
   #
   # @param flow_result [Symbol, FlowControlSignal, Hash]
@@ -166,11 +253,13 @@ class GenevaDrive::Executor
   #
   # @return [Hash]
   def instrumentation_payload
-    {
+    payload = {
       execution_id: step_execution.id,
       workflow_id: workflow.id,
       workflow_class: workflow.class.name
     }
+    payload[:resumable] = true if resumable_step?
+    payload
   end
 
   # Phase 1: Validates states and transitions to executing.
@@ -231,6 +320,22 @@ class GenevaDrive::Executor
         next nil
       end
 
+      # Resumable steps need the cursor and continues_from_id columns. Fail
+      # loudly (instead of degrading) - without cursor persistence an
+      # interrupted iteration would silently restart from the beginning.
+      if step_def.resumable? && !GenevaDrive::StepExecution.resumable_columns?
+        error_message = "Step '#{step_execution.step_name}' is a resumable_step, but the cursor and " \
+          "continues_from_id columns are missing from geneva_drive_step_executions. " \
+          "Run `bin/rails generate geneva_drive:install` and migrate."
+        logger.error(error_message)
+
+        step_execution.update!(error_message: error_message)
+        transition_step!("failed", outcome: "failed")
+        transition_workflow!("paused")
+        exception_to_raise = GenevaDrive::StepConfigurationError.new(error_message)
+        next nil
+      end
+
       # Evaluate preconditions with instrumentation
       precondition_result = evaluate_preconditions(step_def)
       if precondition_result[:abort]
@@ -250,6 +355,8 @@ class GenevaDrive::Executor
       # completion, so that resume! on a failed step will retry it.
       workflow.update!(current_step_name: step_def.name)
 
+      logger.info("Resuming from cursor: #{step_execution.cursor_value.inspect}") if step_execution.resuming?
+
       step_def
     rescue => e
       exception_to_raise = handle_prepare_exception(e)
@@ -331,13 +438,23 @@ class GenevaDrive::Executor
         logger.warn(
           "Workflow #{workflow.id} state unexpectedly changed during execution: #{workflow.state}"
         )
-        transition_step!("canceled", outcome: "canceled")
+        if flow_result.is_a?(Interruption) && workflow.paused?
+          # A resumable step was interrupted because the workflow got paused
+          # externally mid-iteration. Preserve the cursor handoff: complete
+          # this execution with the "workflow_paused" marker so resume! can
+          # create a successor that continues from the cursor.
+          transition_step!("completed", outcome: "workflow_paused")
+        else
+          transition_step!("canceled", outcome: "canceled")
+        end
         next
       end
 
       case flow_result
       when :completed
         handle_completion
+      when Interruption
+        handle_continuation(wait: flow_result.wait)
       when GenevaDrive::FlowControlSignal
         handle_flow_control_signal(flow_result)
       when Hash
@@ -467,10 +584,26 @@ class GenevaDrive::Executor
   # @param step_def [StepDefinition]
   # @return [Hash] captured exception context
   def capture_exception(error, step_def)
-    Rails.error.report(error)
     {type: :exception, error: error, step_def: step_def}
   end
 
+  # Reports an exception via Rails.error.report based on the resolved policy's
+  # report setting. Called after policy resolution so that expected exceptions
+  # (e.g. rate limiting) can suppress error reporting.
+  #
+  # @param error [Exception]
+  # @param result [Hash] the policy result with :report and optional :terminal keys
+  # @return [void]
+  def report_exception(error, result)
+    case result[:report]
+    when :never
+      return
+    when :terminal_only
+      return unless result[:terminal]
+    end
+    Rails.error.report(error)
+  end
+
   # Handles exceptions that occur during pre-condition evaluation (cancel_if, skip_if).
   # Builds a resolution policy, applies it, and returns the original exception
   # to be re-raised after the transaction commits.
@@ -480,9 +613,9 @@ class GenevaDrive::Executor
   # @return [Exception] the original exception to be re-raised
   def handle_precondition_exception(error, step_def)
     logger.error("Pre-condition evaluation failed: #{error.class} - #{error.message}")
-    Rails.error.report(error)
 
     result = apply_resolution_policy(error, step_def)
+    report_exception(error, result)
     apply_policy_result(result, reattempt_reason: "precondition")
 
     error
@@ -497,7 +630,6 @@ class GenevaDrive::Executor
   # @return [Exception] the original exception to be re-raised
   def handle_prepare_exception(error)
     logger.error("Unexpected exception during prepare_execution: #{error.class} - #{error.message}")
-    Rails.error.report(error)
 
     # Try to get step_def for policy resolution, but it may not be available yet
     step_def = begin
@@ -512,7 +644,9 @@ class GenevaDrive::Executor
     combined = build_resolution_policy(step_def)
     count = consecutive_reattempt_count(step_def&.name || step_execution.step_name)
     result = combined.apply(error, reattempt_count: count, workflow: workflow)
-    apply_prepare_policy_result(result || {action: :pause, error: error})
+    result ||= {action: :pause, error: error}
+    report_exception(error, result)
+    apply_prepare_policy_result(result)
 
     error
   end
@@ -527,6 +661,20 @@ class GenevaDrive::Executor
     workflow.schedule_next_step!
   end
 
+  # Handles a resumable step interrupting itself mid-iteration: completes the
+  # current execution with outcome "continued" and creates a successor
+  # execution that carries on from the persisted cursor.
+  #
+  # @param wait [ActiveSupport::Duration, Numeric, nil] optional delay before the successor runs
+  # @return [void]
+  def handle_continuation(wait: nil)
+    wait_msg = wait ? " (continuing after #{wait.inspect})" : ""
+    logger.info("Resumable step interrupted at cursor #{step_execution.cursor_value.inspect}#{wait_msg}")
+    transition_step!("completed", outcome: "continued")
+    transition_workflow!("ready")
+    workflow.create_successor_execution!(step_execution, wait: wait)
+  end
+
   # Handles a captured exception based on the resolved exception policy.
   # Returns the original exception to be re-raised after the transaction commits.
   #
@@ -537,6 +685,7 @@ class GenevaDrive::Executor
     step_def = context[:step_def]
 
     result = apply_resolution_policy(error, step_def)
+    report_exception(error, result)
     apply_policy_result(result, reattempt_reason: "exception_policy")
 
     error
@@ -594,7 +743,13 @@ class GenevaDrive::Executor
       transition_step!("completed", outcome: "reattempted")
       write_reattempt_metadata(reattempt_reason, error: error)
       transition_workflow!("ready")
-      workflow.reschedule_current_step!(wait: result[:wait])
+      if resumable_step?
+        # Resumable steps continue from the persisted cursor via a successor
+        # execution instead of a fresh (cursor-less) execution.
+        workflow.create_successor_execution!(step_execution, wait: result[:wait])
+      else
+        workflow.reschedule_current_step!(wait: result[:wait])
+      end
     when :cancel
       logger.info("Exception policy: cancel!")
       step_execution.update!(error_attributes_for(error))
@@ -633,7 +788,11 @@ class GenevaDrive::Executor
     when :reattempt
       logger.info("Prepare exception policy: reattempt!")
       transition_workflow!("ready")
-      workflow.reschedule_current_step!(wait: result[:wait])
+      if resumable_step?
+        workflow.create_successor_execution!(step_execution, wait: result[:wait])
+      else
+        workflow.reschedule_current_step!(wait: result[:wait])
+      end
     when :cancel
       logger.info("Prepare exception policy: cancel!")
       transition_workflow!("canceled")
@@ -726,16 +885,30 @@ class GenevaDrive::Executor
 
     when :pause
       logger.info("Processing pause signal: pausing workflow")
-      transition_step!("canceled", outcome: "canceled")
+      if resumable_step?
+        # Complete with the "workflow_paused" marker so the cursor is
+        # preserved and resume! can continue from it via a successor.
+        transition_step!("completed", outcome: "workflow_paused")
+      else
+        transition_step!("canceled", outcome: "canceled")
+      end
       transition_workflow!("paused")
 
     when :reattempt
       wait_msg = signal.options[:wait] ? " after #{signal.options[:wait].inspect}" : ""
       logger.info("Processing reattempt signal: rescheduling step#{wait_msg}")
+      if resumable_step? && signal.options[:rewind]
+        logger.info("Rewinding cursor for reattempt")
+        step_execution.update!(cursor: nil)
+      end
       transition_step!("completed", outcome: "reattempted")
       write_reattempt_metadata("flow_control")
       transition_workflow!("ready")
-      workflow.reschedule_current_step!(wait: signal.options[:wait])
+      if resumable_step?
+        workflow.create_successor_execution!(step_execution, wait: signal.options[:wait])
+      else
+        workflow.reschedule_current_step!(wait: signal.options[:wait])
+      end
 
     when :skip
       logger.info("Processing skip signal: scheduling next step")
@@ -747,8 +920,58 @@ class GenevaDrive::Executor
       logger.info("Processing finished signal: finishing workflow")
       transition_step!("completed", outcome: "success")
       transition_workflow!("finished")
+
+    when :suspend
+      # Only reachable from resumable steps: FlowControl#suspend! raises
+      # when called from a non-resumable step.
+      wait = signal.options[:wait]
+      logger.info("Processing suspend signal: completing and creating successor")
+      transition_step!("completed", outcome: "continued")
+      transition_workflow!("ready")
+      workflow.create_successor_execution!(step_execution, wait: wait)
     end
   end
+
+  # Whether the step being executed is a resumable (cursor-iterating) step.
+  # Falls back to looking up the step definition when called before
+  # prepare_execution has completed (e.g. from precondition handling).
+  #
+  # @return [Boolean]
+  def resumable_step?
+    step_def = @step_definition || begin
+      step_execution.step_definition
+    rescue
+      nil
+    end
+    !!step_def&.resumable?
+  end
+
+  # Checks if max runtime has been exceeded for the current execution.
+  #
+  # @return [Boolean]
+  def max_runtime_exceeded?
+    max_runtime = @step_definition.respond_to?(:max_runtime) ? @step_definition.max_runtime : nil
+    return false unless max_runtime
+    return false unless @start_time
+    Time.current - @start_time > max_runtime
+  end
+
+  # Checks if the job should exit (e.g., Sidekiq shutdown).
+  #
+  # @return [Boolean]
+  def job_should_exit?
+    Thread.current[:geneva_drive_should_exit] ||
+      (defined?(Sidekiq) && Sidekiq.const_defined?(:CLI) &&
+       Sidekiq::CLI.instance&.stopping?)
+  end
+
+  # Checks if the workflow has been externally paused or canceled.
+  #
+  # @return [Boolean]
+  def workflow_interrupted?
+    workflow.reload
+    workflow.paused? || workflow.canceled?
+  end
 end
 
 # Raised when an invalid state transition is attempted.

data/lib/geneva_drive/flow_control.rb

@@ -5,7 +5,7 @@
 #
 # @api private
 class GenevaDrive::FlowControlSignal
-  # @return [Symbol] the action to take (:cancel, :pause, :reattempt, :skip, :finished)
+  # @return [Symbol] the action to take (:cancel, :pause, :reattempt, :skip, :finished, :suspend)
   attr_reader :action
 
   # @return [Hash] additional options for the flow control action
@@ -33,6 +33,11 @@ class GenevaDrive::InvalidStateError < StandardError; end
 #   raise StepConfigurationError, "Step requires either a block or method name"
 class GenevaDrive::StepConfigurationError < StandardError; end
 
+# Raised when a resumable step cursor exceeds GenevaDrive.max_cursor_size
+# once serialized to JSON. The cursor is a position marker, not a payload -
+# it is rewritten on every checkpoint and copied to every successor execution.
+class GenevaDrive::CursorTooLargeError < StandardError; end
+
 # Base class for errors that occur during step execution.
 # These errors are raised after recovery actions have been performed,
 # so the workflow/step states are already updated when the exception propagates.
@@ -130,16 +135,24 @@ module GenevaDrive::FlowControl
   # Reschedules the current step for another attempt.
   # Useful for handling temporary failures or rate limiting.
   #
+  # For resumable steps, by default continues from the current cursor position.
+  # Use `rewind: true` to restart the step from the beginning.
+  #
   # @param wait [ActiveSupport::Duration, nil] optional delay before retry
+  # @param rewind [Boolean] if true, resets cursor to beginning (resumable steps only)
   # @return [void]
   # @raise [UncaughtThrowError] if called outside of step execution context
   #
   # @example Retry after rate limit
   #   reattempt!(wait: 5.minutes)
-  def reattempt!(wait: nil)
+  #
+  # @example Retry resumable step from the beginning
+  #   reattempt!(rewind: true)
+  def reattempt!(wait: nil, rewind: false)
     wait_msg = wait ? " with wait #{wait.inspect}" : ""
-    logger.info("Flow control: reattempt! called from step#{wait_msg}")
-    throw :flow_control, GenevaDrive::FlowControlSignal.new(:reattempt, wait: wait)
+    rewind_msg = rewind ? " (rewinding cursor)" : ""
+    logger.info("Flow control: reattempt! called from step#{wait_msg}#{rewind_msg}")
+    throw :flow_control, GenevaDrive::FlowControlSignal.new(:reattempt, wait: wait, rewind: rewind)
   end
 
   # Skips the current step and proceeds to the next one.
@@ -168,6 +181,33 @@ module GenevaDrive::FlowControl
     throw :flow_control, GenevaDrive::FlowControlSignal.new(:finished)
   end
 
+  # Suspends the current resumable step and re-enqueues for later continuation.
+  # The step will resume from its current cursor position.
+  #
+  # This is primarily for use within resumable steps when you need to explicitly
+  # yield control (e.g., to respect rate limits or system load).
+  #
+  # @param wait [ActiveSupport::Duration, nil] optional delay before re-enqueue
+  # @return [void]
+  # @raise [UncaughtThrowError] if called outside of step execution context
+  #
+  # @example Suspend for rate limiting
+  #   suspend!(wait: 5.minutes)
+  #
+  # @example Suspend to yield control
+  #   suspend!
+  def suspend!(wait: nil)
+    executing_step = current_step_name && steps.named(current_step_name)
+    unless executing_step&.resumable?
+      raise GenevaDrive::InvalidStateError,
+        "suspend! can only be called from inside a resumable_step (it continues from the persisted cursor)"
+    end
+
+    wait_msg = wait ? " with wait #{wait.inspect}" : ""
+    logger.info("Flow control: suspend! called from step#{wait_msg}")
+    throw :flow_control, GenevaDrive::FlowControlSignal.new(:suspend, wait: wait)
+  end
+
   private
 
   # Pauses the workflow from outside a step execution.