geneva_drive 0.7.0 → 0.9.0

data/lib/geneva_drive/json_column.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+# JSON encoding for columns the database does not type as JSON itself.
+#
+# PostgreSQL and MySQL both hand Rails a real JSON attribute, so a Hash
+# assigned to one is encoded by the adapter and comes back decoded. MariaDB
+# has no JSON type - see GenevaDrive::MigrationHelpers#geneva_drive_json_column
+# for why - so the column is plain LONGTEXT, Rails types it as text, and a Hash
+# written to it would be stored as `#inspect` output. Encoding it here keeps
+# the models writing and reading the same Ruby values everywhere.
+#
+# The branch is on the column, not on the adapter, deliberately: an install
+# that already ran the old migration against MariaDB has a LONGTEXT column and
+# gets the encoding too, without needing its column rewritten first.
+#
+# @api private
+module GenevaDrive::JsonColumn
+  extend ActiveSupport::Concern
+
+  class_methods do
+    # Whether the column holds JSON as text rather than as a JSON type, and so
+    # needs encoding and decoding here. Lazily detected: never touches the
+    # database at class definition time, since the column may not exist yet.
+    #
+    # @param name [String, Symbol] the column name
+    # @return [Boolean]
+    def json_column_as_text?(name)
+      name = name.to_s
+      @_json_column_as_text ||= {}
+      return @_json_column_as_text[name] if @_json_column_as_text.key?(name)
+
+      @_json_column_as_text[name] = begin
+        column = table_exists? && columns_hash[name]
+        column ? column.type == :text : false
+      rescue ActiveRecord::ActiveRecordError
+        false
+      end
+    end
+
+    # Clears the cached detection. Call after migrating in-process.
+    #
+    # @return [void]
+    def reset_json_column_cache!
+      remove_instance_variable(:@_json_column_as_text) if defined?(@_json_column_as_text)
+    end
+
+    # Prepares an already-serialized value for writing to the column.
+    #
+    # @param name [String, Symbol] the column name
+    # @param value [Object, nil] a JSON-safe Ruby value
+    # @return [Object, nil] the value, encoded to a JSON string where needed
+    def encode_json_column(name, value)
+      return value unless json_column_as_text?(name)
+      return nil if value.nil?
+
+      JSON.generate(value)
+    end
+
+    # Reverses {encode_json_column} for a value read off the column.
+    #
+    # @param name [String, Symbol] the column name
+    # @param raw [Object, nil] the raw attribute value
+    # @return [Object, nil] the decoded value
+    def decode_json_column(name, raw)
+      return raw unless json_column_as_text?(name)
+      return nil if raw.nil?
+      return raw unless raw.is_a?(String)
+
+      JSON.parse(raw)
+    end
+  end
+end

data/lib/geneva_drive/migration_helpers.rb

@@ -9,13 +9,17 @@
 #
 #     def change
 #       create_table :geneva_drive_workflows, **geneva_drive_table_options do |t|
-#         t.references :hero, polymorphic: true, type: geneva_drive_key_type
+#         t.references :hero, polymorphic: true, type: geneva_drive_hero_key_type
 #         # ...
 #       end
 #     end
 #   end
 #
 module GenevaDrive::MigrationHelpers
+  UUID_SQL_TYPE = /uuid|char\(36\)|varchar\(36\)/
+  # SQLite reports `id: :string` as a bare "varchar", without a length
+  STRING_SQL_TYPE = /char|text|clob/
+
   # Detects the appropriate key type for GenevaDrive tables.
   # Returns :uuid if the schema predominantly uses UUIDs, otherwise :bigint.
   #
@@ -25,13 +29,39 @@ module GenevaDrive::MigrationHelpers
       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\)/) }
+      uuid_count = id_columns.count { |col| col.sql_type.downcase.match?(UUID_SQL_TYPE) }
       other_count = id_columns.size - uuid_count
 
       (uuid_count > other_count) ? :uuid : :bigint
     end
   end
 
+  # Detects the column type for `hero_id` on the workflows table. Unlike
+  # {#geneva_drive_key_type}, this also recognizes string primary keys of any
+  # length (`varchar`, `char(n)`, `text`), so that heroes with string ids do not
+  # get a `hero_id` that casts their ids to integers.
+  #
+  # Returns :uuid if the schema predominantly uses UUIDs, :string if it predominantly
+  # uses UUIDs and string ids taken together, otherwise :bigint.
+  #
+  # @return [Symbol] :uuid, :string or :bigint
+  def geneva_drive_hero_key_type
+    @_geneva_drive_hero_key_type ||= begin
+      sql_types = _geneva_drive_app_id_columns.map { |col| col.sql_type.downcase }
+      uuid_count = sql_types.count { |t| t.match?(UUID_SQL_TYPE) }
+      string_count = sql_types.count { |t| !t.match?(UUID_SQL_TYPE) && t.match?(STRING_SQL_TYPE) }
+      integer_count = sql_types.size - uuid_count - string_count
+
+      if uuid_count > string_count + integer_count
+        :uuid
+      elsif uuid_count + string_count > integer_count
+        :string # a string column holds UUIDs just as well
+      else
+        :bigint
+      end
+    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
@@ -48,6 +78,33 @@ module GenevaDrive::MigrationHelpers
     options
   end
 
+  # Column type and options for a column that holds a JSON document.
+  #
+  # PostgreSQL gets jsonb and MySQL gets its native json. MariaDB gets neither:
+  # it has no JSON type at all, `json` there being an alias for LONGTEXT with an
+  # auto-generated CHECK constraint named after the column. Two things go wrong
+  # with that alias. The schema dump comes back as `t.text` plus
+  # `t.check_constraint name: "cursor"`, and loading that dump re-emits the
+  # constraint name unquoted - `cursor` is reserved in MariaDB, so the load dies
+  # on a syntax error, which takes out `db:schema:load` and every parallel test
+  # worker with it. And because Rails types the column as text either way, a
+  # Hash assigned to it is written out as `#inspect` rather than JSON, which the
+  # very same CHECK constraint then rejects. Asking for plain LONGTEXT and doing
+  # the JSON encoding in the model (see GenevaDrive::JsonColumn) sidesteps both.
+  #
+  # @return [Array(Symbol, Hash)] the column type and its options
+  def geneva_drive_json_column
+    adapter = connection.adapter_name.downcase
+
+    if adapter.include?("postgresql")
+      [:jsonb, {}]
+    elsif connection.respond_to?(:mariadb?) && connection.mariadb?
+      [:text, {limit: 4_294_967_295}]
+    else
+      [:json, {}]
+    end
+  end
+
   private
 
   # Collects the id column from every application table (excludes system
@@ -69,7 +126,7 @@ module GenevaDrive::MigrationHelpers
   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\)/)
+      next unless col.sql_type.downcase.match?(UUID_SQL_TYPE)
       col.default_function
     end
 

data/lib/geneva_drive/removed_step_definition.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+# A gravestone left in place of a step that has been taken out of a workflow.
+#
+# Deleting a `step` outright is not safe while workflows are in flight: an
+# execution row already scheduled for that name finds no definition when its
+# job runs, and the workflow pauses with StepNotDefinedError. Declaring
+# `removed_step :name` in the position the step used to occupy keeps the name
+# resolvable, so those executions are skipped instead of stranding the
+# workflow, while scheduling never spools a new execution for it again.
+#
+# A removed step holds nothing but a name - no block, no wait, no conditions.
+# There is nothing left to configure about a step that does not run.
+#
+# @api private
+class GenevaDrive::RemovedStepDefinition < GenevaDrive::StepDefinition
+  # Creates a gravestone for a step that no longer exists.
+  #
+  # The parent is handed a callable that never runs: a removed step is
+  # intercepted by the executor before it would be performed.
+  #
+  # @param name [String, Symbol] the name of the step that was removed
+  # @param call_location [Array<String, Integer>, nil] source location of the removed_step call
+  def initialize(name:, call_location: nil)
+    super(name: name, callable: :__removed_step_never_runs, call_location: call_location)
+  end
+
+  # Returns true to mark this as a gravestone rather than a runnable step.
+  #
+  # @return [Boolean]
+  def removed?
+    true
+  end
+end

data/lib/geneva_drive/signal.rb

@@ -25,6 +25,8 @@
 #   workflow.signal!(:payment_confirmed, payload: {amount_cents: 12_500})
 #
 class GenevaDrive::Signal < ActiveRecord::Base
+  include GenevaDrive::JsonColumn
+
   self.table_name = "geneva_drive_signals"
 
   # Signal lifecycle states as enum with string values.
@@ -109,7 +111,7 @@ class GenevaDrive::Signal < ActiveRecord::Base
         end
       end
 
-      serialized
+      encode_json_column(:payload, serialized)
     end
   end
 
@@ -119,7 +121,7 @@ class GenevaDrive::Signal < ActiveRecord::Base
   #
   # @return [Object, nil] the payload
   def payload
-    raw = self[:payload]
+    raw = self.class.decode_json_column(:payload, self[:payload])
     return nil if raw.nil?
 
     value = ActiveJob::Arguments.deserialize([raw]).first

data/lib/geneva_drive/step_collection.rb

@@ -65,30 +65,54 @@ class GenevaDrive::StepCollection
     ordered_steps[position]
   end
 
-  # Returns the next step after the given step name.
+  # Returns the next runnable step after the given step name.
+  #
+  # Steps declared with `removed_step` are stepped over: they hold a position
+  # in the sequence so that executions scheduled before their removal still
+  # resolve, but no execution is ever scheduled for one.
+  #
+  # A nil current_name means "the beginning", so the first runnable step is
+  # returned - which is how the first step of a workflow is chosen.
   #
   # @param current_name [String, Symbol, nil] the current step name
-  # @return [StepDefinition, nil] the next step or nil if at end
+  # @return [StepDefinition, nil] the next runnable step or nil if at end
   def next_after(current_name)
-    return first if current_name.nil?
+    return ordered_steps.find { |s| !s.removed? } if current_name.nil?
 
     current_index = ordered_steps.index { |s| s.name == current_name.to_s }
     return nil unless current_index
 
-    self[current_index + 1]
+    ordered_steps[(current_index + 1)..].find { |s| !s.removed? }
   end
 
-  # Returns the step before the given step name in the ordered sequence.
+  # Returns the previous runnable step before the given step name in the
+  # ordered sequence. Removed steps are stepped over, for the same reason
+  # {#next_after} steps over them.
   #
   # @param current_name [String, Symbol, nil] the current step name
-  # @return [StepDefinition, nil] the previous step or nil if at beginning
+  # @return [StepDefinition, nil] the previous runnable step or nil if at beginning
   def previous_before(current_name)
     return nil if current_name.nil?
 
     current_index = find_index { |s| s.name == current_name.to_s }
     return nil unless current_index && current_index > 0
 
-    self[current_index - 1]
+    ordered_steps[0...current_index].reverse_each.find { |s| !s.removed? }
+  end
+
+  # Returns the steps that can actually run, in order, with `removed_step`
+  # gravestones filtered out.
+  #
+  # @return [Array<StepDefinition>] the runnable step definitions
+  def runnable
+    ordered_steps.reject(&:removed?)
+  end
+
+  # Returns the `removed_step` gravestones, in order.
+  #
+  # @return [Array<StepDefinition>] the removed step definitions
+  def removed
+    ordered_steps.select(&:removed?)
   end
 
   # Checks if a step exists with the given name.

data/lib/geneva_drive/step_definition.rb

@@ -131,6 +131,15 @@ class GenevaDrive::StepDefinition
     false
   end
 
+  # Returns whether this step is a gravestone left by `removed_step`.
+  # Removed steps keep their name resolvable for executions scheduled before
+  # the step was taken out, but are never scheduled and never run.
+  #
+  # @return [Boolean] false for standard steps
+  def removed?
+    false
+  end
+
   # Whether this step parks until a matching signal arrives.
   #
   # @return [Boolean]

data/lib/geneva_drive/step_execution.rb

@@ -20,6 +20,7 @@ class GenevaDrive::StepExecution < ActiveRecord::Base
 
   require_relative "step_execution/metadata_accessor"
   include MetadataAccessor
+  include GenevaDrive::JsonColumn
 
   # Step execution states as enum with string values
   # Provides: scheduled?, in_progress?, etc. predicates
@@ -162,7 +163,7 @@ class GenevaDrive::StepExecution < ActiveRecord::Base
         end
       end
 
-      serialized
+      encode_json_column(:cursor, serialized)
     end
   end
 
@@ -250,7 +251,7 @@ class GenevaDrive::StepExecution < ActiveRecord::Base
   def cursor_value
     return nil unless self.class.resumable_columns?
     return nil if cursor.blank?
-    ActiveJob::Arguments.deserialize([cursor]).first
+    ActiveJob::Arguments.deserialize([self.class.decode_json_column(:cursor, cursor)]).first
   end
 
   # Sets the cursor value for resumable steps.

data/lib/geneva_drive/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module GenevaDrive
-  VERSION = "0.7.0"
+  VERSION = "0.9.0"
 end

data/lib/geneva_drive/workflow.rb

@@ -206,6 +206,92 @@ class GenevaDrive::Workflow < ActiveRecord::Base
       step_def
     end
 
+    # Marks a step as removed, leaving a gravestone in the position the step
+    # used to occupy.
+    #
+    # Deleting a `step` outright is unsafe while workflows are in flight.
+    # Executions scheduled under the old name find no definition when their
+    # job runs, and the workflow pauses with {StepNotDefinedError} - stuck
+    # until an operator intervenes. The gem cannot recover from this on its
+    # own: it knows the step is gone, but not whether the work it did still
+    # needs doing, and not which of the remaining steps would have run had it
+    # executed. Only the author of the removal knows that.
+    #
+    # `removed_step` is how that knowledge gets written down. Declaring it
+    # where the step used to be says "this step no longer needs to happen,
+    # carry on past it", and the gem can then act without guessing:
+    #
+    # - Executions already scheduled for the name resolve, are skipped, and
+    #   the workflow proceeds to the next runnable step.
+    # - Scheduling never spools a new execution for the name again.
+    # - `before_step:` / `after_step:` references to it keep working.
+    #
+    # Ship the `removed_step`, let in-flight workflows drain past it, then
+    # delete the line once {.removed_steps_in_flight} comes back empty.
+    #
+    # A removed step takes a name and nothing else. There is nothing to
+    # configure about a step that does not run.
+    #
+    # @param name [String, Symbol] the name of the step that was removed
+    # @return [RemovedStepDefinition] the gravestone
+    #
+    # @example Taking a step out of a live workflow
+    #   class PaymentWorkflow < GenevaDrive::Workflow
+    #     step :authorize do
+    #       # ...
+    #     end
+    #
+    #     removed_step :capture_payment
+    #
+    #     step :send_receipt do
+    #       # ...
+    #     end
+    #   end
+    def removed_step(name)
+      raise ArgumentError, "removed_step requires a step name" if name.nil?
+
+      caller_loc = caller_locations(1, 1).first
+      call_location = caller_loc ? [caller_loc.path, caller_loc.lineno] : nil
+
+      step_name = prepare_step_registration!(name, {})
+
+      step_def = GenevaDrive::RemovedStepDefinition.new(
+        name: step_name,
+        call_location: call_location
+      )
+
+      _step_definitions << step_def
+
+      step_def
+    end
+
+    # Returns the names of this workflow's removed steps that step execution
+    # rows still reference, so a `removed_step` gravestone is only deleted
+    # once nothing can land on it any more.
+    #
+    # Each name maps to the number of rows still referencing it. An empty
+    # hash means every in-flight workflow has drained past the removal and
+    # the `removed_step` lines can go.
+    #
+    # Rows belonging to finished and canceled workflows are ignored - they
+    # will never execute again.
+    #
+    # @return [Hash{String => Integer}] removed step names to referencing row counts
+    #
+    # @example
+    #   PaymentWorkflow.removed_steps_in_flight
+    #   # => {"capture_payment" => 3}
+    def removed_steps_in_flight
+      removed_names = steps.removed.map(&:name)
+      return {} if removed_names.empty?
+
+      GenevaDrive::StepExecution
+        .where(step_name: removed_names)
+        .where(workflow_id: where.not(state: %w[finished canceled]).select(:id))
+        .group(:step_name)
+        .count
+    end
+
     # Defines a blanket cancellation condition for the workflow.
     # Checked before every step execution.
     #
@@ -226,8 +312,8 @@ class GenevaDrive::Workflow < ActiveRecord::Base
       _cancel_conditions << block if block_given?
     end
 
-    # Sets job options for step execution jobs.
-    # Options are passed to ActiveJob's set method.
+    # Sets job options for step execution jobs. See GenevaDrive::JobOptions
+    # for the keys allowed, and the dispatcher for how they are applied.
     #
     # @param options [Hash] job options (queue, priority, etc.)
     # @return [void]
@@ -566,6 +652,73 @@ class GenevaDrive::Workflow < ActiveRecord::Base
 
     # No scheduled execution exists - create one for the next step
     step_def = steps.named(next_step_name)
+
+    # The step this workflow is pointed at can be gone from the code - that is
+    # what paused it in the first place if it paused with StepNotDefinedError.
+    # Say so plainly instead of dying on nil deeper in create_step_execution,
+    # and name the way out.
+    unless step_def
+      raise GenevaDrive::StepNotDefinedError.new(
+        "Cannot resume #{self.class.name} ##{id}: step '#{next_step_name}' is no longer defined in " \
+        "#{self.class.name}. Pick the step to continue from with resume_at!(:step_name) - the steps " \
+        "still defined are #{steps.runnable.map(&:name).join(", ")} - or cancel! the workflow. To stop " \
+        "future removals from stranding workflows this way, leave a removed_step :#{next_step_name} " \
+        "gravestone in place of the deleted step.",
+        step_execution: nil,
+        workflow: self
+      )
+    end
+
+    create_step_execution(step_def, wait: nil)
+  end
+
+  # Resumes a paused workflow at a specific step, instead of at whatever step
+  # it was pointed at when it paused.
+  #
+  # This is the operator's escape hatch for a workflow stranded on a step that
+  # no longer exists - the step was deleted without leaving a
+  # {GenevaDrive::Workflow.removed_step} gravestone, so the workflow paused
+  # with {StepNotDefinedError} and plain {#resume!} has nowhere to go.
+  #
+  # Where to land is deliberately a human decision. A deleted step's position
+  # in the sequence says nothing about whether the steps that follow it were
+  # ever meant to run: a `capture_payment` that normally ends the workflow by
+  # calling `finished!` sits directly before `refund`, and nothing in the
+  # database distinguishes "carry on" from "stop here". Only the person who
+  # removed the step knows which, so this method asks them.
+  #
+  # Any stray scheduled execution is canceled first, so the workflow continues
+  # from the named step and nowhere else.
+  #
+  # @param step_name [String, Symbol] the step to continue from
+  # @return [StepExecution] the created step execution
+  # @raise [InvalidStateError] if the workflow is not paused
+  # @raise [StepNotDefinedError] if the named step is not defined, or is a removed_step
+  #
+  # @example Continue a stranded workflow past a deleted step
+  #   workflow = GenevaDrive::Workflow.find(id)
+  #   workflow.resume_at!(:send_receipt)
+  def resume_at!(step_name)
+    raise GenevaDrive::InvalidStateError, "Cannot resume a #{state} workflow" unless state == "paused"
+
+    step_def = steps.named(step_name.to_s)
+
+    if step_def.nil? || step_def.removed?
+      reason = step_def ? "a removed_step" : "not defined"
+      raise GenevaDrive::StepNotDefinedError.new(
+        "Cannot resume #{self.class.name} ##{id} at '#{step_name}': that step is #{reason} in " \
+        "#{self.class.name}. The steps it can be resumed at are #{steps.runnable.map(&:name).join(", ")}.",
+        step_execution: nil,
+        workflow: self
+      )
+    end
+
+    logger.info("Resuming paused workflow at step #{step_def.name.inspect} (was pointed at #{next_step_name.inspect})")
+
+    with_lock do
+      update!(state: "ready", current_step_name: nil, transitioned_at: nil)
+    end
+
     create_step_execution(step_def, wait: nil)
   end
 
@@ -920,7 +1073,7 @@ class GenevaDrive::Workflow < ActiveRecord::Base
   #
   # @return [void]
   def log_workflow_created
-    step_count = self.class.step_definitions.size
+    step_count = steps.runnable.size
     logger.info("Created workflow with #{step_count} step(s) defined")
   end
 
@@ -928,7 +1081,10 @@ class GenevaDrive::Workflow < ActiveRecord::Base
   #
   # @return [StepExecution, nil] the created step execution
   def schedule_first_step!
-    first_step = self.class.step_definitions.first
+    # next_after(nil) means "from the beginning" and honours both the
+    # before_step:/after_step: ordering and removed_step gravestones, neither
+    # of which the raw _step_definitions array knows about.
+    first_step = steps.next_after(nil)
     unless first_step
       logger.info("No steps defined, finishing workflow immediately")
       return finish_workflow!
@@ -948,7 +1104,7 @@ class GenevaDrive::Workflow < ActiveRecord::Base
     signal
   end
 
-  # Enqueues the PerformStepJob for an execution that dispatch just flipped
+  # Enqueues the step job 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.
   #
@@ -961,15 +1117,7 @@ class GenevaDrive::Workflow < ActiveRecord::Base
     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)
+      dispatch_step_job(execution_id, job_options, logger: workflow_logger)
     end
   end
 
@@ -981,6 +1129,18 @@ class GenevaDrive::Workflow < ActiveRecord::Base
   # @return [StepExecution] the same execution (rescheduled if a signal matched)
   def rendezvous_waiting_execution!(step_execution)
     step_def = step_execution.step_definition
+
+    # The step was removed while this execution sat parked. It waits for an
+    # event that nothing will ever match now, so release it here rather than
+    # leaving it parked for good.
+    if step_def&.removed?
+      logger.info("Step #{step_execution.step_name} was parked but is now a removed_step — releasing it and continuing")
+
+      step_execution.mark_skipped!
+      settle_signal_for_skipped!(step_execution)
+      return schedule_next_step!
+    end
+
     matcher = step_def&.signal_matcher
 
     if matcher
@@ -1022,12 +1182,9 @@ class GenevaDrive::Workflow < ActiveRecord::Base
     # PerformStepJob sets `enqueue_after_transaction_commit = :never` -- without it,
     # ActiveJob/SolidQueue would see the transaction as "open" and defer the queue
     # INSERT to a second "after commit" that never fires (the double-deferral bug).
+    # SidekiqDispatcher bypasses Sidekiq's transactional push for the same reason.
     run_after_commit do
-      job = GenevaDrive::PerformStepJob
-        .set(**job_options)
-        .perform_later(execution_id)
-
-      workflow_logger.debug("Enqueued job #{job.job_id} for step execution #{execution_id}")
+      dispatch_step_job(execution_id, job_options, logger: workflow_logger)
     end
 
     step_execution
@@ -1077,15 +1234,7 @@ class GenevaDrive::Workflow < ActiveRecord::Base
       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)
+        dispatch_step_job(successor_id, job_options, logger: workflow_logger)
       end
 
       successor
@@ -1133,17 +1282,9 @@ class GenevaDrive::Workflow < ActiveRecord::Base
       # without it, ActiveJob/SolidQueue would see the transaction as "open" and defer
       # the queue INSERT to a second "after commit" that never fires (the double-deferral
       # bug). See the extensive comment in PerformStepJob for the full explanation.
+      # SidekiqDispatcher bypasses Sidekiq's transactional push for the same reason.
       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 step execution #{execution_id}")
-
-        # Update job_id for debugging purposes (this is a separate transaction)
-        GenevaDrive::StepExecution
-          .where(id: execution_id)
-          .update_all(job_id: job.job_id)
+        dispatch_step_job(execution_id, job_options, logger: workflow_logger)
       end
 
       step_execution
@@ -1179,6 +1320,26 @@ class GenevaDrive::Workflow < ActiveRecord::Base
     nil
   end
 
+  # Hands a step execution to the configured dispatcher (GenevaDrive.dispatcher)
+  # and writes the returned job id onto the execution, so that the job can be
+  # found from the row. Always called from inside run_after_commit.
+  #
+  # @param execution_id [Integer, String] the step execution to perform
+  # @param job_options [Hash] merged, validated job options
+  # @param logger [Logger] the workflow logger captured before the commit
+  # @return [void]
+  def dispatch_step_job(execution_id, job_options, logger:)
+    job_id = GenevaDrive.dispatcher.enqueue_step(execution_id, job_options, workflow_class_name: self.class.name)
+
+    logger.debug("Enqueued step job with job_id=#{job_id} for step execution #{execution_id}")
+
+    # A separate statement, outside any transaction - the job may already be running.
+    # resume! re-enqueues an existing execution, so this overwrites the old job's id.
+    GenevaDrive::StepExecution
+      .where(id: execution_id)
+      .update_all(job_id: job_id)
+  end
+
   # Runs a block either after all transactions commit or immediately.
   #
   # The behavior depends on GenevaDrive.enqueues_deferred?, which checks:
@@ -1192,7 +1353,7 @@ class GenevaDrive::Workflow < ActiveRecord::Base
   # In tests (enqueue_after_commit = false), or inside a
   # without_deferred_enqueues block, the block runs immediately.
   #
-  # @yield the block to run (typically contains perform_later call)
+  # @yield the block to run (typically hands a step to the dispatcher)
   # @return [void]
   def run_after_commit(&block)
     if GenevaDrive.enqueues_deferred?