geneva_drive 0.7.0 → 0.9.0

data/bin/md2html

@@ -42,6 +42,98 @@ class SyntaxHighlightingHTML < Redcarpet::Render::HTML
   end
 end
 
+# GitHub-Flavored Markdown alerts: `> [!NOTE]` etc. Redcarpet emits these
+# as ordinary blockquotes, so we post-process the HTML to spot the marker,
+# strip it, and rewrite the blockquote with an alert class + title.
+# GitHub knows exactly these five and matches them case-sensitively —
+# `[!note]` or `[!FOO]` stay literal text there, and so must they here.
+GFM_ALERT_TYPES = %w[NOTE TIP IMPORTANT WARNING CAUTION].freeze
+# Only spaces/tabs and one line ending may follow the marker. `\s*` would
+# swallow the blank line separating the marker from a following paragraph.
+GFM_ALERT_PATTERN = /\A\[!(#{GFM_ALERT_TYPES.join("|")})\][ \t]*\r?\n?/
+
+# The marker opens the text of a paragraph. GitHub insists it sit alone on the
+# blockquote's first line; we are laxer and also accept body text trailing it
+# on the same line, rather than leaving a half-parsed `[!NOTE]` on the page.
+def alert_marker_of(child)
+  return nil unless child.element? && child.name == "p"
+  first_text = child.children.first
+  return nil unless first_text&.text?
+  match = first_text.content.match(GFM_ALERT_PATTERN)
+  match && match[1]
+end
+
+# Take the marker out of the paragraph it introduces and keep everything else,
+# element children included — that is the whole point: an alert whose body
+# opens with `**bold**` has the marker and a <strong> in the same <p>, so we
+# may only edit that leading text node, never replace the paragraph.
+def strip_alert_marker!(paragraph)
+  first_text = paragraph.children.first
+  first_text.content = first_text.content.sub(GFM_ALERT_PATTERN, "") if first_text&.text?
+
+  # A marker line ending in two spaces is a Markdown hard break, so Redcarpet
+  # leaves a <br> where the marker was. Drop that leading padding, otherwise
+  # the alert body opens with a blank line.
+  while (node = paragraph.children.first)
+    blank_text = node.text? && node.content.strip.empty?
+    break unless blank_text || (node.element? && node.name == "br")
+    node.remove
+  end
+
+  # The marker was alone on its line: the paragraph has nothing left to say.
+  paragraph.remove if paragraph.children.empty?
+end
+
+def transform_gfm_alerts(html_body)
+  doc = Nokogiri::HTML::DocumentFragment.parse(html_body)
+  doc.css("blockquote").each do |bq|
+    # Redcarpet collapses adjacent blockquotes into one, so a single
+    # <blockquote> may carry several `[!TYPE]` markers. Partition its
+    # children into segments, each introduced by a marker (or the
+    # untagged preamble before any marker).
+    segments = [[nil, []]]
+    bq.children.to_a.each do |child|
+      marker = alert_marker_of(child)
+      if marker
+        segments << [marker, [child]]
+      else
+        segments.last[1] << child
+      end
+    end
+    segments.reject! do |_, nodes|
+      nodes.all? { |n| n.text? && n.content.strip.empty? }
+    end
+
+    # Nothing to do if no markers appeared at all.
+    next if segments.all? { |type, _| type.nil? }
+
+    prev = bq
+    segments.each_with_index do |(type, children), i|
+      new_bq = Nokogiri::XML::Node.new("blockquote", bq.document)
+      children.each { |c| new_bq.add_child(c) }
+
+      if type
+        first_p = new_bq.children.find(&:element?)
+        strip_alert_marker!(first_p) if first_p && first_p.name == "p"
+
+        title = Nokogiri::XML::Node.new("p", bq.document)
+        title["class"] = "markdown-alert-title"
+        title.content = type.capitalize
+        new_bq.prepend_child(title)
+        new_bq["class"] = "markdown-alert markdown-alert-#{type.downcase}"
+      end
+
+      if i == 0
+        bq.replace(new_bq)
+      else
+        prev.add_next_sibling(new_bq)
+      end
+      prev = new_bq
+    end
+  end
+  doc.to_html
+end
+
 def build_toc(html_body)
   doc = Nokogiri::HTML::DocumentFragment.parse(html_body)
   headings = doc.css("h1, h2")
@@ -82,6 +174,11 @@ def html_template(title, content, toc: "")
       --table-border: #dfe2e5;
       --blockquote-color: #6a737d;
       --blockquote-border: #dfe2e5;
+      --alert-note: #0969da;
+      --alert-tip: #1a7f37;
+      --alert-important: #8250df;
+      --alert-warning: #9a6700;
+      --alert-caution: #cf222e;
       --toc-width: 280px;
     }
 
@@ -247,6 +344,22 @@ def html_template(title, content, toc: "")
       margin-bottom: 0;
     }
 
+    /* GitHub-Flavored Markdown alerts (> [!NOTE] etc.) */
+    .markdown-alert {
+      color: var(--text-color);
+      padding: 0.5em 1em;
+    }
+    .markdown-alert-title {
+      font-weight: 600;
+      margin: 0 0 0.25em;
+      color: var(--alert-accent, inherit);
+    }
+    .markdown-alert-note      { border-left-color: var(--alert-note);      --alert-accent: var(--alert-note); }
+    .markdown-alert-tip       { border-left-color: var(--alert-tip);       --alert-accent: var(--alert-tip); }
+    .markdown-alert-important { border-left-color: var(--alert-important); --alert-accent: var(--alert-important); }
+    .markdown-alert-warning   { border-left-color: var(--alert-warning);   --alert-accent: var(--alert-warning); }
+    .markdown-alert-caution   { border-left-color: var(--alert-caution);   --alert-accent: var(--alert-caution); }
+
     /* Horizontal rules */
     hr {
       border: 0;
@@ -444,6 +557,7 @@ def convert_markdown_to_html(input_path, output_path = nil, toc: true)
   })
 
   html_body = markdown.render(markdown_content)
+  html_body = transform_gfm_alerts(html_body)
   toc_html = toc ? build_toc(html_body) : ""
   html_document = html_template(title, html_body, toc: toc_html)
 

data/lib/generators/geneva_drive/install/templates/add_resumable_step_support.rb

@@ -5,15 +5,11 @@ class AddResumableStepSupportToGenevaDriveStepExecutions < ActiveRecord::Migrati
 
   def change
     unless column_exists?(:geneva_drive_step_executions, :cursor)
-      # Cursor for resumable steps. Use database-native JSON type:
-      # - PostgreSQL: jsonb (indexed, efficient, supports containment queries)
-      # - MySQL 5.7+: json (native validation and storage)
-      # - SQLite: json (Rails handles as TEXT with serialization)
-      if connection.adapter_name.downcase.include?("postgresql")
-        add_column :geneva_drive_step_executions, :cursor, :jsonb
-      else
-        add_column :geneva_drive_step_executions, :cursor, :json
-      end
+      # Cursor for resumable steps. Database-native JSON where there is one -
+      # jsonb on PostgreSQL, json on MySQL and SQLite - and plain LONGTEXT on
+      # MariaDB, which has no JSON type. See geneva_drive_json_column.
+      cursor_type, cursor_options = geneva_drive_json_column
+      add_column :geneva_drive_step_executions, :cursor, cursor_type, **cursor_options
     end
 
     unless column_exists?(:geneva_drive_step_executions, :continues_from_id)

data/lib/generators/geneva_drive/install/templates/add_signals_support.rb

@@ -34,16 +34,11 @@ class AddSignalsSupportToGenevaDrive < ActiveRecord::Migration[7.2]
       # Lifecycle: pending -> claimed -> consumed
       t.string :state, null: false, default: "pending"
 
-      # Serialized payload. Use the database-native JSON type, same flavor
-      # logic as the resumable step cursor:
-      # - PostgreSQL: jsonb
-      # - MySQL 5.7+: json
-      # - SQLite: json (Rails handles as TEXT with serialization)
-      if adapter.include?("postgresql")
-        t.jsonb :payload
-      else
-        t.json :payload
-      end
+      # Serialized payload, same flavour logic as the resumable step cursor:
+      # jsonb on PostgreSQL, json on MySQL and SQLite, plain LONGTEXT on
+      # MariaDB, which has no JSON type. See geneva_drive_json_column.
+      payload_type, payload_options = geneva_drive_json_column
+      t.column :payload, payload_type, **payload_options
 
       t.datetime :claimed_at
       t.datetime :consumed_at

data/lib/generators/geneva_drive/install/templates/create_workflows_migration.rb

@@ -12,7 +12,7 @@ class CreateGenevaDriveWorkflows < ActiveRecord::Migration[7.2]
 
       # Polymorphic association to the hero of the workflow (optional)
       t.string :hero_type
-      t.column :hero_id, geneva_drive_key_type
+      t.column :hero_id, geneva_drive_hero_key_type
 
       # State machine
       t.string :state, null: false, default: "ready", index: true

data/lib/generators/geneva_drive/install/templates/initializer.rb.tt

@@ -1,5 +1,20 @@
 # frozen_string_literal: true
 
+# How step jobs reach your queue.
+# - :active_job (the default) enqueues GenevaDrive::PerformStepJob through
+#   Active Job, onto whatever adapter the app uses.
+# - :sidekiq pushes GenevaDrive::SidekiqPerformStepJob, a plain Sidekiq::Job,
+#   straight through Sidekiq::Client - for apps that write Sidekiq jobs rather
+#   than Active Job ones. Schedule GenevaDrive::SidekiqHousekeepingJob then.
+#   Supports Sidekiq 7.3 and later 7.x, and 8.x.
+#
+<% if GenevaDrive::SidekiqDispatcher.recommended? -%>
+# Active Job was set up for Sidekiq when this file was generated.
+GenevaDrive.dispatcher = :sidekiq
+<% else -%>
+# GenevaDrive.dispatcher = :active_job
+<% end -%>
+
 # How long to keep completed/canceled workflows before automatic deletion.
 # Set to nil to disable automatic cleanup.
 # When enabled, finished and canceled workflows older than this threshold
@@ -7,12 +22,12 @@
 #
 # GenevaDrive.delete_completed_workflows_after = 30.days
 
-# How long a step execution can be in "executing" state before being
+# How long a step execution can be in "in_progress" state before being
 # considered stuck. This typically happens when a worker process crashes
 # mid-execution. The HousekeepingJob will recover these based on the
 # stuck_recovery_action setting.
 #
-# GenevaDrive.stuck_executing_threshold = 1.hour
+# GenevaDrive.stuck_in_progress_threshold = 1.hour
 
 # How long a step execution can be past its scheduled_for time while
 # still in "scheduled" state before being considered stuck. This can
@@ -39,6 +54,22 @@
 #
 # GenevaDrive.max_cursor_size = 128.kilobytes
 
+# Maximum size in bytes of a signal payload once serialized to JSON.
+# A payload describes an event (an order id, an amount, a decision), not the
+# data the step is going to work on - that belongs on the hero. Exceeding the
+# limit raises GenevaDrive::SignalPayloadTooLargeError from Workflow#signal!,
+# before anything is persisted. Set to nil to disable the check.
+#
+# GenevaDrive.max_signal_payload_size = 128.kilobytes
+
+# How long a step execution may sit in the "waiting" state before
+# housekeeping counts it in the geneva_drive.waiting_overdue gauge.
+# Waiting indefinitely is legitimate, so this is not a timeout - it keeps
+# a stalled rendezvous from going unnoticed. Alert on the overdue gauge.
+# Set to nil to disable the gauge.
+#
+# GenevaDrive.waiting_visibility_threshold = 7.days
+
 # Whether to defer job enqueueing until after the database transaction commits.
 # In production this ensures step execution records are visible to job workers
 # before the job runs. In test environments (the default when Rails.env.test?)

data/lib/geneva_drive/dispatchers/active_job_dispatcher.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+# Enqueues step jobs through Active Job, onto whatever adapter the app uses.
+# This is the default dispatcher.
+#
+# GenevaDrive calls the dispatcher from an `after_all_transactions_commit`
+# callback, once the step execution row is visible to other connections.
+# PerformStepJob opts out of Active Job's own transaction deferral for that
+# reason - see the comment there.
+#
+# @see GenevaDrive.dispatcher
+class GenevaDrive::ActiveJobDispatcher
+  # Enqueues the job that performs a step execution.
+  #
+  # @param step_execution_id [Integer, String] the step execution to perform
+  # @param job_options [Hash] validated `queue`, `priority`, `wait`, `wait_until`
+  # @param workflow_class_name [String, nil] unused here
+  # @return [String, nil] the Active Job job_id, or nil if the enqueue was aborted
+  def enqueue_step(step_execution_id, job_options, workflow_class_name: nil)
+    job = GenevaDrive::PerformStepJob.set(**job_options).perform_later(step_execution_id)
+    # perform_later returns false, not nil, when a callback aborts the enqueue
+    return nil unless job
+    job.job_id
+  end
+
+  # Every key GenevaDrive::JobOptions allows maps onto Active Job's `set`.
+  #
+  # @param options [Hash{Symbol=>Object}]
+  # @param context [String]
+  # @return [void]
+  def validate_job_options!(options, context:)
+  end
+end

data/lib/geneva_drive/dispatchers/sidekiq_dispatcher.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+# Pushes step jobs straight to Sidekiq as GenevaDrive::SidekiqPerformStepJob,
+# a plain Sidekiq::Job, for apps that use Sidekiq without Active Job.
+#
+# Pushes go through a fresh Sidekiq::Client, never `perform_async`, so that
+# `Sidekiq.transactional_push!` cannot defer them a second time from inside
+# GenevaDrive's own after-commit callback - see PerformStepJob for why that
+# loses jobs. Client middleware still runs.
+#
+# @example config/initializers/geneva_drive.rb
+#   GenevaDrive.dispatcher = :sidekiq
+#
+# @see GenevaDrive.dispatcher
+class GenevaDrive::SidekiqDispatcher
+  # 7.3 and later 7.x, and 8.x - the versions CI runs. 9.0 stays out until tested.
+  SUPPORTED_SIDEKIQ_VERSIONS = Gem::Requirement.new(">= 7.3", "< 9")
+
+  # @return [Boolean] whether the loaded Sidekiq is a supported version
+  def self.supported_sidekiq_version?
+    SUPPORTED_SIDEKIQ_VERSIONS.satisfied_by?(Gem::Version.new(::Sidekiq::VERSION))
+  end
+
+  # Whether the install generator should write `GenevaDrive.dispatcher = :sidekiq`
+  # into the initializer it creates: a supported Sidekiq is loaded, and the app
+  # has pointed Active Job at Sidekiq. An unset adapter does not count - the
+  # generator runs in development, and production may well use another backend.
+  #
+  # @param adapter [Symbol, String, Object, nil] Active Job's configured adapter
+  # @return [Boolean]
+  def self.recommended?(adapter = Rails.application&.config&.active_job&.queue_adapter)
+    return false unless defined?(::Sidekiq::Client) && supported_sidekiq_version?
+
+    adapter.to_s == "sidekiq" || adapter.class.name.to_s.end_with?("SidekiqAdapter")
+  end
+
+  # @param job_class [Class, nil] a Sidekiq::Job that performs step executions,
+  #   GenevaDrive::SidekiqPerformStepJob by default
+  # @raise [LoadError] if Sidekiq is not loaded
+  # @raise [ArgumentError] if the loaded Sidekiq is not a supported version
+  def initialize(job_class: nil)
+    unless defined?(::Sidekiq::Client)
+      raise LoadError, "GenevaDrive::SidekiqDispatcher needs the sidekiq gem. Add it to your Gemfile."
+    end
+
+    unless self.class.supported_sidekiq_version?
+      raise ArgumentError,
+        "GenevaDrive::SidekiqDispatcher supports Sidekiq #{SUPPORTED_SIDEKIQ_VERSIONS}, " \
+        "but Sidekiq #{::Sidekiq::VERSION} is loaded. Use GenevaDrive.dispatcher = :active_job with this Sidekiq."
+    end
+
+    @job_class = job_class
+  end
+
+  # @return [Class] the Sidekiq::Job class step jobs are pushed as
+  def job_class
+    @job_class || GenevaDrive::SidekiqPerformStepJob
+  end
+
+  # Pushes the job that performs a step execution.
+  #
+  # @param step_execution_id [Integer, String] the step execution to perform
+  # @param job_options [Hash] validated `queue`, `wait`, `wait_until`
+  # @param workflow_class_name [String, nil] added to the job's tags, for the Web UI
+  # @return [String, nil] the jid, or nil if client middleware stopped the push
+  def enqueue_step(step_execution_id, job_options, workflow_class_name: nil)
+    item = {"class" => job_class, "args" => [step_execution_id]}
+    item["queue"] = job_options[:queue].to_s if job_options[:queue]
+
+    if (at = run_at(job_options))
+      item["at"] = at.to_f
+    end
+
+    if workflow_class_name
+      class_tags = Array(job_class.get_sidekiq_options["tags"])
+      item["tags"] = (class_tags + [workflow_class_name]).uniq
+    end
+
+    ::Sidekiq::Client.new.push(item)
+  end
+
+  # Sidekiq has queues with weights, not job priorities. Rejecting
+  # `priority:` keeps it from being ignored without anyone noticing.
+  #
+  # @param options [Hash{Symbol=>Object}]
+  # @param context [String]
+  # @return [void]
+  # @raise [GenevaDrive::StepConfigurationError] if `priority` is given
+  def validate_job_options!(options, context:)
+    return if options[:priority].nil?
+
+    raise GenevaDrive::StepConfigurationError,
+      "#{context} sets job_options[:priority], but Sidekiq has no job priority - it has queues with weights. " \
+      "Put the steps that must run first on a queue with a higher weight, e.g. `queue: :workflows_urgent`."
+  end
+
+  private
+
+  # Workflow already drops an overdue wait_until; this also covers callers that
+  # pass a time in the past, which would otherwise wait for the scheduled-set poller.
+  def run_at(job_options)
+    at = if job_options[:wait_until]
+      job_options[:wait_until]
+    elsif job_options[:wait]
+      Time.current + job_options[:wait]
+    end
+    return nil unless at
+
+    at = at.respond_to?(:to_time) ? at.to_time : Time.at(at.to_f)
+    (at > Time.current) ? at : nil
+  end
+end

data/lib/geneva_drive/engine.rb

@@ -1,3 +1,16 @@
 class GenevaDrive::Engine < ::Rails::Engine
   isolate_namespace GenevaDrive
+
+  # Sidekiq fires :quiet on TSTP (what Enterprise rolling restarts send first)
+  # and at the start of every shutdown. Resumable steps then checkpoint and
+  # hand off to a successor execution instead of being killed mid-iteration
+  # when the shutdown timeout runs out. Installed whichever dispatcher is in
+  # use - Active Job on the Sidekiq adapter needs it just as much.
+  initializer "geneva_drive.sidekiq_lifecycle" do
+    if defined?(::Sidekiq) && ::Sidekiq.respond_to?(:configure_server)
+      ::Sidekiq.configure_server do |config|
+        config.on(:quiet) { GenevaDrive.request_exit! }
+      end
+    end
+  end
 end

data/lib/geneva_drive/executor.rb

@@ -327,6 +327,24 @@ class GenevaDrive::Executor
         next nil
       end
 
+      # A step declared with `removed_step` is a gravestone: scheduling stopped
+      # spooling executions for it, but one scheduled before the removal was
+      # deployed can still arrive here. The author of the removal has already
+      # said this step no longer needs to happen, so skip it and move on rather
+      # than pausing the workflow the way an undeclared removal does.
+      if step_def.removed?
+        logger.info("Step '#{step_execution.step_name}' is declared removed_step — skipping it and continuing")
+
+        transition_step!("skipped", outcome: "skipped")
+        # The execution may have been carrying a signal when the step was
+        # removed under it; settle it here rather than leaving it claimed
+        # forever, exactly as a skip_if skip does.
+        workflow.settle_signal_for_skipped!(step_execution)
+        transition_workflow!("ready")
+        workflow.schedule_next_step!
+        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.
@@ -1061,11 +1079,13 @@ class GenevaDrive::Executor
 
   # Checks if the job should exit (e.g., Sidekiq shutdown).
   #
+  # The process-wide flag is raised by Sidekiq's :quiet event (see the
+  # engine). Asking Sidekiq::CLI directly does not work: the CLI has no
+  # stopping? of its own, only its launcher does.
+  #
   # @return [Boolean]
   def job_should_exit?
-    Thread.current[:geneva_drive_should_exit] ||
-      (defined?(Sidekiq) && Sidekiq.const_defined?(:CLI) &&
-       Sidekiq::CLI.instance&.stopping?)
+    Thread.current[:geneva_drive_should_exit] || GenevaDrive.exit_requested?
   end
 
   # Checks if the workflow has been externally paused or canceled.

data/lib/geneva_drive/job_options.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-# Validation helper for Active Job option hashes passed through the workflow DSL
+# Validation helper for step job option hashes passed through the workflow DSL
 # (`set_step_job_options`, `step(job_options: ...)`, and `workflow.step_job_options=`).
 #
 # Active Job itself silently ignores unknown keys in `set` — a typo like
@@ -8,7 +8,9 @@
 # priority. This helper enforces the known key set so misconfigurations surface
 # at definition time, or at assignment time for per-instance overrides.
 #
-# The allowed keys mirror what `ActiveJob::Core#set` actually consumes.
+# The allowed keys mirror what `ActiveJob::Core#set` actually consumes. The
+# configured dispatcher then gets a say: the Sidekiq one rejects `priority`,
+# which Sidekiq has no notion of.
 #
 # @api private
 module GenevaDrive::JobOptions
@@ -25,7 +27,8 @@ module GenevaDrive::JobOptions
   #   (e.g. "Step 'foo'" or "MyWorkflow.step_job_options")
   # @return [Hash{Symbol=>Object}] symbolized copy safe to pass to `.set`
   # @raise [GenevaDrive::StepConfigurationError] if options can't be coerced to
-  #   a Hash, contains unknown keys, or has values of the wrong type
+  #   a Hash, contains unknown keys, has values of the wrong type, or uses a
+  #   key the configured dispatcher cannot honour
   def self.validate!(options, context:)
     hash = begin
       options.to_h
@@ -44,6 +47,7 @@ module GenevaDrive::JobOptions
     end
 
     symbolized.each { |k, v| validate_value!(k, v, context) }
+    GenevaDrive.dispatcher.validate_job_options!(symbolized, context: context)
     symbolized
   end
 

data/lib/geneva_drive/jobs/perform_step_job.rb

@@ -13,6 +13,8 @@
 #   PerformStepJob.perform_now(step_execution.id)
 #
 class GenevaDrive::PerformStepJob < ActiveJob::Base
+  include GenevaDrive::StepExecutionLookup
+
   # == CRITICAL: Prevent double-deferral of job enqueueing ==
   #
   # GenevaDrive already defers job enqueueing using `ActiveRecord.after_all_transactions_commit`
@@ -83,39 +85,4 @@ class GenevaDrive::PerformStepJob < ActiveJob::Base
     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/jobs/sidekiq_housekeeping_job.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require "sidekiq"
+
+# Sidekiq job that runs GenevaDrive's housekeeping, for apps that schedule
+# periodic work with Sidekiq Enterprise or sidekiq-cron rather than an
+# Active Job backend. It runs the same code as HousekeepingJob, in-process.
+#
+# @example Sidekiq Enterprise periodic jobs
+#   Sidekiq.configure_server do |config|
+#     config.periodic do |mgr|
+#       mgr.register("*/15 * * * *", "GenevaDrive::SidekiqHousekeepingJob")
+#     end
+#   end
+#
+# @example sidekiq-cron
+#   Sidekiq::Cron::Job.create(
+#     name: "GenevaDrive housekeeping",
+#     cron: "*/15 * * * *",
+#     class: "GenevaDrive::SidekiqHousekeepingJob"
+#   )
+class GenevaDrive::SidekiqHousekeepingJob
+  include ::Sidekiq::Job
+
+  # The next scheduled run is the retry.
+  sidekiq_options queue: "default", retry: false, tags: ["geneva_drive"]
+
+  # @return [Hash] summary of actions taken, as returned by HousekeepingJob
+  def perform
+    GenevaDrive::HousekeepingJob.perform_now
+  end
+end

data/lib/geneva_drive/jobs/sidekiq_perform_step_job.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require "sidekiq"
+
+# Sidekiq job that executes a scheduled step execution - the native
+# counterpart of PerformStepJob, pushed by GenevaDrive::SidekiqDispatcher.
+#
+# Retries are off because exception policies decide reattempts, each as a new
+# step execution. The step's exception is still raised, so error handlers report it.
+class GenevaDrive::SidekiqPerformStepJob
+  include ::Sidekiq::Job
+  include GenevaDrive::StepExecutionLookup
+
+  sidekiq_options queue: "default", retry: false, tags: ["geneva_drive"]
+
+  # @param step_execution_id [Integer, String] the ID of the step execution
+  # @return [void]
+  def perform(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
+
+    # So that Sidekiq's own log lines for this job carry the workflow and step
+    ::Sidekiq::Context.with(
+      geneva_drive_workflow_id: step_execution.workflow_id,
+      geneva_drive_step: step_execution.step_name,
+      geneva_drive_step_execution_id: step_execution.id
+    ) do
+      GenevaDrive::Executor.execute!(step_execution)
+    end
+  end
+end

data/lib/geneva_drive/jobs/step_execution_lookup.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+# Finds the step execution a job was enqueued for, retrying briefly when it is
+# not visible yet. Shared by PerformStepJob and SidekiqPerformStepJob.
+#
+# @api private
+module GenevaDrive::StepExecutionLookup
+  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
+  #      the dispatcher is only called after the step execution row is committed
+  #   2. Both dispatchers pushing synchronously from that callback, rather than
+  #      deferring a second time into a callback that may never fire
+  #
+  # However, this retry handles additional edge cases:
+  #   - Database replication lag (read replica hasn't caught up with the writer)
+  #   - Future code paths that might enqueue 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