geneva_drive 0.4.0 → 0.6.0

data/lib/geneva_drive/jobs/housekeeping_job.rb

@@ -20,7 +20,7 @@
 #   # config/initializers/geneva_drive.rb
 #   GenevaDrive.delete_completed_workflows_after = 30.days
 #   GenevaDrive.stuck_in_progress_threshold = 1.hour
-#   GenevaDrive.stuck_scheduled_threshold = 1.hour
+#   GenevaDrive.stuck_scheduled_threshold = 15.minutes
 #   GenevaDrive.stuck_recovery_action = :reattempt # or :cancel
 #
 class GenevaDrive::HousekeepingJob < ActiveJob::Base
@@ -39,6 +39,7 @@ class GenevaDrive::HousekeepingJob < ActiveJob::Base
 
     cleanup_completed_workflows!(results)
     recover_stuck_step_executions!(results)
+    report_workflow_gauges!
 
     logger.info("Completed: #{results}")
     results
@@ -46,45 +47,144 @@ class GenevaDrive::HousekeepingJob < ActiveJob::Base
 
   private
 
+  # Reports workflow count gauges to Measurometer.
+  # For each state present in the workflows table (e.g. ready, paused,
+  # performing, finished, canceled), sets:
+  # - A total gauge `geneva_drive.<state>` without tags (summed across all classes)
+  # - Per-workflow-class gauges `geneva_drive.<state>` tagged with `workflow: ClassName`
+  #
+  # Additionally emits a normalized `geneva_drive.paused_ratio` gauge per
+  # workflow class — a float in `0.0..1.0` equal to that class's `paused` count
+  # divided by that class's total population (all states). This is easier to
+  # alert on than absolute paused counts (50 paused of 50 is a fire; 50 of
+  # 500,000 is noise). All gauges are derived from a single grouped query.
+  #
+  # @return [void]
+  def report_workflow_gauges!
+    counts = GenevaDrive::Workflow.group(:state, :type).count
+
+    counts.each_with_object(Hash.new(0)) { |((state, _type), count), totals| totals[state] += count }
+      .each do |state, total|
+        Measurometer.set_gauge("geneva_drive.#{state}", total)
+      end
+
+    counts.each do |(state, type), count|
+      Measurometer.set_gauge("geneva_drive.#{state}", count, workflow: type)
+    end
+
+    # Per-class paused ratio (paused ÷ total population), deliberately bounded 0..1.
+    # Both accumulators default to 0 so a class with no paused workflows yields a clean 0.0.
+    totals_by_type = Hash.new(0)
+    paused_by_type = Hash.new(0)
+    counts.each do |(state, type), count|
+      totals_by_type[type] += count
+      paused_by_type[type] += count if state == "paused"
+    end
+
+    totals_by_type.each do |type, total|
+      # A type only appears here when it has >= 1 row, so total is always >= 1.
+      # Guard against division by zero anyway as belt-and-suspenders.
+      next if total.zero?
+      Measurometer.set_gauge("geneva_drive.paused_ratio", paused_by_type[type].to_f / total, workflow: type)
+    end
+  end
+
   # Cleans up completed/canceled workflows older than the configured threshold.
-  # Uses delete_all for efficiency - step executions are deleted via dependent: :destroy
-  # or a separate bulk delete for performance.
+  # Uses efficient batched SQL DELETEs - step executions are deleted first via
+  # INNER JOIN, then workflows. Loops until all eligible records are deleted.
   #
   # @param results [Hash] results hash to update
   # @return [void]
   def cleanup_completed_workflows!(results)
     threshold = GenevaDrive.delete_completed_workflows_after
-    return unless threshold
+    if threshold.blank?
+      logger.info("GenevaDrive.delete_completed_workflows_after is set to nil, so no old workflows will be deleted from the DB for now")
+      return
+    end
 
+    # Fix cutoff time at start to ensure cleanup completes deterministically
     cutoff_time = threshold.ago
     batch_size = GenevaDrive.housekeeping_batch_size
 
-    # Find workflows eligible for cleanup
-    workflows_to_delete = GenevaDrive::Workflow
-      .where(state: %w[finished canceled])
-      .where("transitioned_at < ?", cutoff_time)
-      .limit(batch_size)
+    # First pass: delete all step executions for old workflows using INNER JOIN
+    loop do
+      deleted_count = delete_step_executions_batch(cutoff_time, batch_size)
+      logger.info("Deleted #{deleted_count} step executions")
+      results[:step_executions_cleaned_up] += deleted_count
+      break if deleted_count < batch_size
+    end
 
-    workflow_ids = workflows_to_delete.pluck(:id)
-    return if workflow_ids.empty?
+    # Second pass: delete the workflows themselves
+    loop do
+      deleted_count = delete_workflows_batch(cutoff_time, batch_size)
+      logger.info("Deleted #{deleted_count} workflows")
+      results[:workflows_cleaned_up] += deleted_count
+      break if deleted_count < batch_size
+    end
 
-    # Delete step executions first (more efficient than dependent: :destroy for bulk)
-    step_exec_count = GenevaDrive::StepExecution
-      .where(workflow_id: workflow_ids)
-      .delete_all
+    logger.info(
+      "Cleaned up #{results[:workflows_cleaned_up]} workflows " \
+      "and #{results[:step_executions_cleaned_up]} step executions older than #{cutoff_time}"
+    )
+  end
 
-    # Then delete workflows
-    workflow_count = GenevaDrive::Workflow
-      .where(id: workflow_ids)
-      .delete_all
+  # Deletes a batch of step executions belonging to old workflows.
+  #
+  # @param cutoff_time [Time] workflows transitioned before this time are eligible
+  # @param batch_size [Integer] maximum records to delete in this batch
+  # @return [Integer] number of records deleted
+  def delete_step_executions_batch(cutoff_time, batch_size)
+    GenevaDrive::StepExecution.connection_pool.with_connection do |conn|
+      step_executions_table = conn.quote_table_name(GenevaDrive::StepExecution.table_name)
+      workflows_table = conn.quote_table_name(GenevaDrive::Workflow.table_name)
+      limit = batch_size.to_i
 
-    results[:workflows_cleaned_up] = workflow_count
-    results[:step_executions_cleaned_up] = step_exec_count
+      # MySQL doesn't support LIMIT in subqueries with IN, so we wrap it in another SELECT
+      # Also, MySQL doesn't handle bind parameters for LIMIT properly, so we interpolate directly
+      sql = <<~SQL.squish
+        DELETE FROM #{step_executions_table}
+        WHERE id IN (
+          SELECT id FROM (
+            SELECT se.id
+            FROM #{step_executions_table} se
+            INNER JOIN #{workflows_table} w ON w.id = se.workflow_id
+            WHERE w.state IN ('finished', 'canceled')
+            AND w.transitioned_at < ?
+            LIMIT #{limit}
+          ) AS batch_to_delete
+        )
+      SQL
 
-    logger.info(
-      "Cleaned up #{workflow_count} workflows " \
-      "and #{step_exec_count} step executions older than #{cutoff_time}"
-    )
+      conn.delete(GenevaDrive::StepExecution.sanitize_sql([sql, cutoff_time]))
+    end
+  end
+
+  # Deletes a batch of old workflows.
+  #
+  # @param cutoff_time [Time] workflows transitioned before this time are eligible
+  # @param batch_size [Integer] maximum records to delete in this batch
+  # @return [Integer] number of records deleted
+  def delete_workflows_batch(cutoff_time, batch_size)
+    GenevaDrive::Workflow.connection_pool.with_connection do |conn|
+      workflows_table = conn.quote_table_name(GenevaDrive::Workflow.table_name)
+      limit = batch_size.to_i
+
+      # MySQL doesn't support LIMIT in subqueries with IN, so we wrap it in another SELECT
+      # Also, MySQL doesn't handle bind parameters for LIMIT properly, so we interpolate directly
+      sql = <<~SQL.squish
+        DELETE FROM #{workflows_table}
+        WHERE id IN (
+          SELECT id FROM (
+            SELECT id FROM #{workflows_table}
+            WHERE state IN ('finished', 'canceled')
+            AND transitioned_at < ?
+            LIMIT #{limit}
+          ) AS batch_to_delete
+        )
+      SQL
+
+      conn.delete(GenevaDrive::Workflow.sanitize_sql([sql, cutoff_time]))
+    end
   end
 
   # Recovers stuck step executions.
@@ -100,48 +200,62 @@ class GenevaDrive::HousekeepingJob < ActiveJob::Base
   end
 
   # Recovers step executions stuck in "in_progress" state.
+  # Loops until all eligible records are processed.
   #
   # @param results [Hash] results hash to update
   # @return [void]
   def recover_stuck_in_progress!(results)
-    threshold = GenevaDrive.stuck_in_progress_threshold
+    # Fix cutoff time at start to ensure recovery completes deterministically
+    cutoff_time = GenevaDrive.stuck_in_progress_threshold.ago
     batch_size = GenevaDrive.housekeeping_batch_size
-    cutoff_time = threshold.ago
 
-    stuck_executions = GenevaDrive::StepExecution
-      .in_progress
-      .where("started_at < ?", cutoff_time)
-      .limit(batch_size)
-
-    stuck_executions.find_each do |step_execution|
-      recover_step_execution!(step_execution)
-      results[:stuck_in_progress_recovered] += 1
-    rescue => e
-      logger.error("Failed to recover step execution #{step_execution.id}: #{e.message}")
-      Rails.error.report(e)
+    loop do
+      stuck_executions = GenevaDrive::StepExecution
+        .in_progress
+        .where("started_at < ?", cutoff_time)
+        .order(started_at: :asc)
+        .limit(batch_size)
+        .to_a
+
+      break if stuck_executions.empty?
+
+      stuck_executions.each do |step_execution|
+        recover_step_execution!(step_execution)
+        results[:stuck_in_progress_recovered] += 1
+      rescue => e
+        logger.error("Failed to recover step execution #{step_execution.id}: #{e.message}")
+        Rails.error.report(e)
+      end
     end
   end
 
   # Recovers step executions stuck in "scheduled" state past their scheduled_for time.
+  # Loops until all eligible records are processed.
   #
   # @param results [Hash] results hash to update
   # @return [void]
   def recover_stuck_scheduled!(results)
-    threshold = GenevaDrive.stuck_scheduled_threshold
+    # Fix cutoff time at start to ensure recovery completes deterministically
+    cutoff_time = GenevaDrive.stuck_scheduled_threshold.ago
     batch_size = GenevaDrive.housekeeping_batch_size
-    cutoff_time = threshold.ago
 
-    stuck_executions = GenevaDrive::StepExecution
-      .scheduled
-      .where("scheduled_for < ?", cutoff_time)
-      .limit(batch_size)
-
-    stuck_executions.find_each do |step_execution|
-      recover_step_execution!(step_execution)
-      results[:stuck_scheduled_recovered] += 1
-    rescue => e
-      logger.error("Failed to recover step execution #{step_execution.id}: #{e.message}")
-      Rails.error.report(e)
+    loop do
+      stuck_executions = GenevaDrive::StepExecution
+        .scheduled
+        .where("scheduled_for < ?", cutoff_time)
+        .order(scheduled_for: :asc)
+        .limit(batch_size)
+        .to_a
+
+      break if stuck_executions.empty?
+
+      stuck_executions.each do |step_execution|
+        recover_step_execution!(step_execution)
+        results[:stuck_scheduled_recovered] += 1
+      rescue => e
+        logger.error("Failed to recover step execution #{step_execution.id}: #{e.message}")
+        Rails.error.report(e)
+      end
     end
   end
 
@@ -167,6 +281,9 @@ class GenevaDrive::HousekeepingJob < ActiveJob::Base
 
   # Reattempts a stuck step execution by marking it as completed and scheduling a retry.
   #
+  # Resumable step executions carry a cursor; those are continued via a
+  # successor execution so recovery does not restart the iteration from zero.
+  #
   # @param step_execution [GenevaDrive::StepExecution]
   # @param workflow [GenevaDrive::Workflow]
   # @return [void]
@@ -184,7 +301,12 @@ class GenevaDrive::HousekeepingJob < ActiveJob::Base
         )
 
         workflow.update!(state: "ready") if workflow.performing?
-        workflow.reschedule_current_step!
+
+        if step_execution.step_definition&.resumable? && GenevaDrive::StepExecution.resumable_columns?
+          workflow.create_successor_execution!(step_execution)
+        else
+          workflow.reschedule_current_step!
+        end
       end
     end
   end

data/lib/geneva_drive/jobs/perform_step_job.rb

@@ -13,6 +13,59 @@
 #   PerformStepJob.perform_now(step_execution.id)
 #
 class GenevaDrive::PerformStepJob < ActiveJob::Base
+  # == CRITICAL: Prevent double-deferral of job enqueueing ==
+  #
+  # GenevaDrive already defers job enqueueing using `ActiveRecord.after_all_transactions_commit`
+  # in Workflow#create_step_execution and Workflow#enqueue_scheduled_execution. By the time
+  # `perform_later` is called, all step execution data has been committed and is visible.
+  #
+  # Without this setting, a dangerous double-deferral race condition can occur on Rails 7.2+
+  # with queue adapters like SolidQueue that opt into `enqueue_after_transaction_commit`:
+  #
+  #   1. Workflow completes a step inside a transaction (with_lock)
+  #   2. Transaction commits -> `after_all_transactions_commit` callback fires
+  #   3. Inside the callback, `perform_later` is called
+  #   4. ActiveJob checks `current_transaction.open?` -- which may return true because
+  #      the transaction has committed but is not yet cleaned up on the Ruby side
+  #   5. ActiveJob defers the INSERT into the queue backend to "after this transaction commits"
+  #   6. But this transaction is ALREADY past its commit phase -- the deferred INSERT is lost
+  #   7. The StepExecution gets a job_id (UUID generated by ActiveJob constructor) but
+  #      no corresponding job row exists in the queue backend (e.g. solid_queue_jobs)
+  #   8. The step hangs in "scheduled" state until HousekeepingJob recovers it (default: 15 min)
+  #
+  # The geneva_drive_step_executions table functions as a transactional outbox: it is the
+  # committed source of truth for what work needs to happen. HousekeepingJob periodically
+  # scans for step executions stuck in "scheduled" state and re-enqueues them, so the
+  # system _does_ self-heal. But that recovery only kicks in after `stuck_scheduled_threshold`
+  # (default: 15 minutes), which is far too slow for a workflow engine that is supposed to be
+  # the reliable scheduler at the heart of the application. Losing a job enqueue means a
+  # step that should run in milliseconds instead waits an hour. ActiveJob `perform_later`
+  # is the closest thing Rails gives us to a reliable "schedule this work" primitive, so
+  # we take stringent measures to ensure the INSERT into the queue backend actually lands
+  # every single time -- the outbox recovery is a safety net, not the primary mechanism.
+  #
+  # By setting `:never`, `perform_later` writes the job row synchronously when called,
+  # which is safe because we are already outside any application transaction
+  # (the `after_all_transactions_commit` callback guarantees this).
+  #
+  # We _extremely deliberately_ deviate from the `:default` value here. The `:default`
+  # setting tells ActiveJob to ask the queue adapter whether to defer (via the adapter's
+  # `enqueue_after_transaction_commit?` method). Adapters like SolidQueue return `true`,
+  # which re-enables the double-deferral. We MUST override this to `:never` because
+  # GenevaDrive handles its own transaction-awareness via `after_all_transactions_commit`.
+  #
+  # This is timing-dependent and intermittent -- under normal conditions the transaction
+  # may be fully cleaned up before `perform_later` checks `current_transaction.open?`,
+  # so the INSERT happens immediately. Under load, during deploys (connection pool churn),
+  # or with specific timing, the transaction is still on the stack and the INSERT is
+  # silently deferred into the void.
+  #
+  # The `respond_to?` guard ensures compatibility with Rails versions before 7.2 that
+  # do not have this class attribute. Rails 8.0 deprecated `:never` in favor of `false`.
+  if respond_to?(:enqueue_after_transaction_commit=)
+    self.enqueue_after_transaction_commit = (Rails::VERSION::MAJOR >= 8) ? false : :never
+  end
+
   queue_as :default
 
   # Performs the step execution.
@@ -20,14 +73,49 @@ class GenevaDrive::PerformStepJob < ActiveJob::Base
   # @param step_execution_id [Integer, String] the ID of the step execution
   # @return [void]
   def perform(step_execution_id)
-    step_execution = GenevaDrive::StepExecution.find_by(id: step_execution_id)
+    step_execution = find_step_execution(step_execution_id)
 
     unless step_execution
       logger.warn("StepExecution #{step_execution_id} not found, skipping")
       return
     end
 
-    step_execution.logger.debug("PerformStepJob starting execution")
-    GenevaDrive::Executor.execute!(step_execution)
+    logger.debug("PerformStepJob starting execution for step #{step_execution_id}")
+    GenevaDrive::Executor.execute!(step_execution, logger: logger)
+  end
+
+  private
+
+  # Retries the step execution lookup briefly to handle the (unlikely) case where
+  # the job is picked up before the step execution's transaction is visible to this
+  # database connection.
+  #
+  # This is a defense-in-depth measure. The primary protection against visibility
+  # issues is the combination of:
+  #   1. `after_all_transactions_commit` in Workflow#create_step_execution, which ensures
+  #      `perform_later` is only called after the step execution row is committed
+  #   2. `enqueue_after_transaction_commit = :never` (above), which ensures the queue
+  #      adapter INSERT happens synchronously, not deferred into a dead callback
+  #
+  # However, this retry handles additional edge cases:
+  #   - Database replication lag (read replica hasn't caught up with the writer)
+  #   - Future code paths that might call perform_later inside a transaction
+  #   - Any other visibility delay between the commit and the job worker's read
+  #
+  # The 500ms total window (5 x 100ms) is generous enough to handle typical
+  # replication lag while being short enough to fail fast if the record truly
+  # doesn't exist (e.g. it was already deleted by cleanup).
+  #
+  # @param id [Integer, String] the step execution ID to look up
+  # @param attempts [Integer] maximum number of lookup attempts
+  # @param delay [Float] seconds to sleep between attempts
+  # @return [GenevaDrive::StepExecution, nil] the step execution or nil if not found
+  def find_step_execution(id, attempts: 5, delay: 0.1)
+    attempts.times do |i|
+      record = GenevaDrive::StepExecution.find_by(id: id)
+      return record if record
+      sleep(delay) if i < attempts - 1
+    end
+    nil
   end
 end

data/lib/geneva_drive/migration_helpers.rb

@@ -21,31 +21,66 @@ module GenevaDrive::MigrationHelpers
   #
   # @return [Symbol] :uuid or :bigint
   def geneva_drive_key_type
-    tables = connection.tables.reject { |t| t.start_with?("schema_", "ar_") }
-    return :bigint if tables.empty?
-
-    uuid_count = 0
-    other_count = 0
-
-    tables.each do |table_name|
-      columns = connection.columns(table_name)
-      id_column = columns.find { |c| c.name == "id" }
-      next unless id_column
-
-      if id_column.sql_type.downcase.match?(/uuid|char\(36\)|varchar\(36\)/)
-        uuid_count += 1
-      else
-        other_count += 1
-      end
-    end
+    @_geneva_drive_key_type ||= begin
+      id_columns = _geneva_drive_app_id_columns
+      return :bigint if id_columns.empty?
+
+      uuid_count = id_columns.count { |col| col.sql_type.downcase.match?(/uuid|char\(36\)|varchar\(36\)/) }
+      other_count = id_columns.size - uuid_count
 
-    (uuid_count > other_count) ? :uuid : :bigint
+      (uuid_count > other_count) ? :uuid : :bigint
+    end
   end
 
   # Returns options hash for create_table based on detected primary key type.
+  # When UUIDs are detected, includes the most common default function from
+  # existing tables so that new tables match the application's convention
+  # (e.g. uuid_generate_v7 instead of gen_random_uuid).
   #
-  # @return [Hash] options for create_table (e.g., `{id: :uuid}` or `{}`)
+  # @return [Hash] options for create_table (e.g., `{id: :uuid, default: "uuid7()"}` or `{}`)
   def geneva_drive_table_options
-    (geneva_drive_key_type == :uuid) ? {id: :uuid} : {}
+    return {} unless geneva_drive_key_type == :uuid
+
+    options = {id: :uuid}
+    if (default_function = _geneva_drive_dominant_uuid_default)
+      options[:default] = default_function
+    end
+    options
+  end
+
+  private
+
+  # Collects the id column from every application table (excludes system
+  # tables and GenevaDrive's own tables so the quorum reflects the
+  # application's convention, not our own).
+  #
+  # @return [Array<ActiveRecord::ConnectionAdapters::Column>]
+  def _geneva_drive_app_id_columns
+    tables = connection.tables.reject { |t| t.start_with?("schema_", "ar_", "geneva_drive_") }
+    tables.filter_map do |table_name|
+      connection.columns(table_name).find { |c| c.name == "id" }
+    end
+  end
+
+  # Finds the most common non-nil default among UUID primary key columns.
+  # Returns nil when there is no clear dominant default (or no defaults at all).
+  #
+  # @return [String, nil] a SQL default expression string, or nil
+  def _geneva_drive_dominant_uuid_default
+    id_columns = _geneva_drive_app_id_columns
+    uuid_defaults = id_columns.filter_map do |col|
+      next unless col.sql_type.downcase.match?(/uuid|char\(36\)|varchar\(36\)/)
+      col.default_function
+    end
+
+    return nil if uuid_defaults.empty?
+
+    # Pick the most frequently occurring default function
+    tally = uuid_defaults.tally
+    winner, count = tally.max_by { |_fn, c| c }
+
+    # Only use it if it's a clear majority (more than any other single default)
+    runner_up_count = tally.reject { |fn, _| fn == winner }.values.max || 0
+    (count > runner_up_count) ? winner : nil
   end
 end

data/lib/geneva_drive/resumable_step_definition.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+# Metadata about a resumable step definition in a workflow.
+# Extends StepDefinition with cursor-based iteration support.
+#
+# Resumable steps can iterate over large collections with checkpointing,
+# allowing them to be suspended and resumed across job executions.
+#
+# @api private
+class GenevaDrive::ResumableStepDefinition < GenevaDrive::StepDefinition
+  # @return [Proc] the block to execute (receives IterableStep)
+  attr_reader :block
+
+  # @return [Integer, nil] maximum number of iterations before auto-suspend
+  attr_reader :max_iterations
+
+  # @return [ActiveSupport::Duration, nil] maximum runtime before auto-suspend
+  attr_reader :max_runtime
+
+  # Creates a new resumable step definition.
+  #
+  # @param name [String, Symbol] the step name
+  # @param max_iterations [Integer, nil] maximum iterations before auto-suspend
+  # @param max_runtime [ActiveSupport::Duration, nil] maximum runtime before auto-suspend
+  # @param options [Hash] additional options (same as StepDefinition)
+  # @param block [Proc] the block to execute (required, receives IterableStep)
+  # @raise [StepConfigurationError] if configuration is invalid
+  def initialize(name:, max_iterations: nil, max_runtime: nil, **options, &block)
+    @block = block
+    @max_iterations = max_iterations
+    @max_runtime = max_runtime
+
+    # Pass a dummy callable to parent since we use block instead
+    super(name: name, callable: block, **options)
+
+    validate_resumable!
+  end
+
+  # Returns true to indicate this step supports resumable iteration.
+  #
+  # @return [Boolean]
+  def resumable?
+    true
+  end
+
+  # Executes the step block with an IterableStep in the workflow context.
+  #
+  # @param workflow [GenevaDrive::Workflow] the workflow instance
+  # @param iterable_step [GenevaDrive::IterableStep] the iteration context
+  # @return [Object] the result of the step execution
+  def execute_in_context(workflow, iterable_step)
+    workflow.instance_exec(iterable_step, &@block)
+  end
+
+  private
+
+  # Validates resumable-specific configuration.
+  #
+  # @raise [StepConfigurationError] if configuration is invalid
+  def validate_resumable!
+    validate_block!
+    validate_max_iterations!
+    validate_max_runtime!
+  end
+
+  # Validates that the block is present.
+  #
+  # @raise [StepConfigurationError] if block is missing
+  def validate_block!
+    return if @block.is_a?(Proc)
+
+    raise GenevaDrive::StepConfigurationError,
+      "Resumable step '#{@name}' requires a block"
+  end
+
+  # Validates the max_iterations value.
+  #
+  # @raise [StepConfigurationError] if max_iterations is invalid
+  def validate_max_iterations!
+    return if @max_iterations.nil?
+    return if @max_iterations.is_a?(Integer) && @max_iterations.positive?
+
+    raise GenevaDrive::StepConfigurationError,
+      "Resumable step '#{@name}' has invalid max_iterations: must be a positive integer"
+  end
+
+  # Validates the max_runtime value.
+  #
+  # @raise [StepConfigurationError] if max_runtime is invalid
+  def validate_max_runtime!
+    return if @max_runtime.nil?
+    return if @max_runtime.respond_to?(:to_i) && @max_runtime.to_i.positive?
+
+    raise GenevaDrive::StepConfigurationError,
+      "Resumable step '#{@name}' has invalid max_runtime: must be a positive duration"
+  end
+end