geneva_drive 0.6.0 → 0.8.0

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

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+# Signals: external events delivered to a workflow, and the two columns on
+# step executions that let one park until a matching event arrives. Both halves
+# ship together - a signals table nobody can wait on is useless, and a waiting
+# step with nowhere to read its event from is worse - so they are one migration.
+class AddSignalsSupportToGenevaDrive < ActiveRecord::Migration[7.2]
+  include GenevaDrive::MigrationHelpers
+
+  def change
+    key_type = geneva_drive_key_type
+    adapter = connection.adapter_name.downcase
+
+    # Build reference options - we add the foreign key separately to avoid
+    # MySQL type mismatch (see below).
+    reference_options = {
+      null: false,
+      index: true
+    }
+    reference_options[:type] = key_type if key_type == :uuid
+
+    create_table :geneva_drive_signals, **geneva_drive_table_options do |t|
+      # Link to workflow (cascade delete when the workflow is deleted)
+      t.references :workflow, **reference_options
+
+      # The event name, as passed to Workflow#signal!
+      t.string :name, null: false
+
+      # Optional caller-supplied deduplication key. NULLs are distinct in
+      # unique indexes on PostgreSQL, MySQL and SQLite alike, so signals
+      # without an idempotency key always insert.
+      t.string :idempotency_key
+
+      # Lifecycle: pending -> claimed -> consumed
+      t.string :state, null: false, default: "pending"
+
+      # 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
+
+      # How many executions have attached to this signal, and how many of
+      # those attached chains have resolved cleanly. For a linear workflow
+      # both end at 1 (more claims if the step was retried); when one signal
+      # is dispatched onto several concurrent executions the pair is the
+      # progress readout of that fan-out. Counters, not the lifecycle state -
+      # the `state` column above is what says claimed or consumed.
+      t.bigint :claimed, null: false, default: 0
+      t.bigint :consumed, null: false, default: 0
+
+      t.timestamps
+    end
+
+    # Deduplication: one signal per (workflow, name, idempotency_key)
+    add_index :geneva_drive_signals, [:workflow_id, :name, :idempotency_key],
+      unique: true, name: "index_geneva_drive_signals_dedup"
+
+    # Scanning a workflow's unconsumed signals
+    add_index :geneva_drive_signals, [:workflow_id, :state]
+
+    # Add foreign key separately to avoid MySQL type mismatch (UNSIGNED vs SIGNED bigint)
+    # MySQL creates primary keys as UNSIGNED but references as SIGNED, causing FK constraint failure
+    unless adapter.include?("mysql")
+      add_foreign_key :geneva_drive_signals, :geneva_drive_workflows,
+        column: :workflow_id, on_delete: :cascade
+    end
+
+    unless column_exists?(:geneva_drive_step_executions, :signal_id)
+      # The attachment pin: which signal this execution is processing. One
+      # signal may be pinned by many executions, so this lives on the
+      # execution side. Match the primary key type (bigint or uuid) of the
+      # signals table.
+      # No foreign key constraint - SQLite rewrites the table on
+      # add_foreign_key, which can destroy data.
+      add_column :geneva_drive_step_executions, :signal_id, key_type
+      add_index :geneva_drive_step_executions, :signal_id
+    end
+
+    unless column_exists?(:geneva_drive_step_executions, :waiting_since)
+      # When the execution parked waiting for a signal, so "waiting for N
+      # days" is queryable without abusing updated_at.
+      add_column :geneva_drive_step_executions, :waiting_since, :datetime
+    end
+  end
+end

data/lib/geneva_drive/executor.rb

@@ -15,7 +15,8 @@
 class GenevaDrive::Executor
   # Valid state transitions for step executions
   STEP_TRANSITIONS = {
-    "scheduled" => %w[scheduled in_progress canceled skipped failed completed],
+    "scheduled" => %w[scheduled waiting in_progress canceled skipped failed completed],
+    "waiting" => %w[scheduled canceled skipped],
     "in_progress" => %w[in_progress completed failed canceled skipped]
   }.freeze
 
@@ -113,17 +114,23 @@ class GenevaDrive::Executor
     @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)
+    # Phase 2: Execute step block (locks released). The signal this execution
+    # is attached to (if any) is injected for the duration, so step code can
+    # read `received_signal`.
+    flow_result = @workflow.with_received_signal(@received_signal) do
+      @logger.debug("Running before_step_execution hook")
+      @workflow.before_step_execution(@step_execution)
 
-    @logger.debug("Running the actual step code")
-    flow_result = @workflow.around_step_execution(@step_execution) do
-      execute_step(step_def)
-    end
+      @logger.debug("Running the actual step code")
+      result = @workflow.around_step_execution(@step_execution) do
+        execute_step(step_def)
+      end
+
+      @logger.debug("Running after_step_execution hook")
+      @workflow.after_step_execution(@step_execution)
 
-    @logger.debug("Running after_step_execution hook")
-    @workflow.after_step_execution(@step_execution)
+      result
+    end
 
     # Phase 3: Acquire locks and handle result
     @logger.info("Finished step with outcome #{flow_result.inspect}")
@@ -320,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.
@@ -336,6 +361,22 @@ class GenevaDrive::Executor
         next nil
       end
 
+      # Steps that wait for a signal need the signal_id and waiting_since
+      # columns. Fail loudly (instead of degrading) - without them a step
+      # would run without the event it was written to react to.
+      if step_def.waits_for_signal? && !GenevaDrive::StepExecution.signal_columns?
+        error_message = "Step '#{step_execution.step_name}' declares wait_for:, but the signal_id and " \
+          "waiting_since 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]
@@ -343,6 +384,13 @@ class GenevaDrive::Executor
         next nil
       end
 
+      # The rendezvous, receiver side: skip_if has had its say (skip beats
+      # wait), so now find the signal or park. Parking ends the job without
+      # enqueueing anything - dispatch will wake us.
+      if step_def.waits_for_signal? && run_signal_gate(step_def) == :parked
+        next nil
+      end
+
       # All checks passed - transition to in_progress
       logger.debug("Step may be performed - changing state flags and proceeding to perform")
 
@@ -367,6 +415,69 @@ class GenevaDrive::Executor
     result
   end
 
+  # The receiver side of the rendezvous. Runs under the workflow and step
+  # execution locks, inside prepare_execution.
+  #
+  # An execution that already carries an attachment pin (dispatch woke it, or
+  # it inherited the pin from its predecessor) runs straight away. Otherwise
+  # the oldest matching non-consumed signal is attached, and failing that the
+  # execution parks.
+  #
+  # @param step_def [StepDefinition] the waiting step's definition
+  # @return [Symbol] :attached or :parked
+  def run_signal_gate(step_def)
+    if step_execution.signal_id.present?
+      @received_signal = step_execution.signal
+      logger.info("Step is attached to signal #{step_execution.signal_id}, proceeding")
+      return :attached
+    end
+
+    matcher = step_def.signal_matcher
+    candidate = workflow.attachable_signals.detect { |signal| matcher.matches?(signal) }
+
+    unless candidate
+      logger.info("No signal matching #{matcher} has arrived, parking step execution")
+      transition_step!("waiting")
+      step_execution.update!(waiting_since: Time.current)
+      return :parked
+    end
+
+    logger.info("Attaching signal #{candidate.id} (#{candidate.name}) to step execution")
+    candidate.claim!
+    step_execution.update!(signal_id: candidate.id)
+    @received_signal = candidate
+    :attached
+  end
+
+  # Books one clean resolution against the attached signal. Called from
+  # finalization on clean outcomes only (completion, skip, finished!), right
+  # after the step's own terminal transition and in the same transaction: a
+  # crash before commit resolves nothing and completes nothing, so replay
+  # stays coherent.
+  #
+  # The signal only flips to consumed once every chain attached to it has
+  # resolved - for a single claimant that is this very moment, and when one
+  # signal has been dispatched onto several executions it is whichever of
+  # them finishes last. Reattempts, failures and cancellations deliberately
+  # leave the signal claimed, so the retry (or resume) re-attaches to it and
+  # sees the same payload while the audit trail reads truthfully.
+  #
+  # @return [void]
+  def resolve_attached_signal!
+    return unless GenevaDrive::StepExecution.signal_columns?
+    return if step_execution.signal_id.blank?
+
+    signal = step_execution.signal
+    return unless signal
+
+    signal.record_consumption!
+    if signal.state == "consumed"
+      logger.info("Consumed signal #{signal.id} (#{signal.name}) after #{signal.consumed} clean resolution(s)")
+    else
+      logger.info("Signal #{signal.id} (#{signal.name}) stays claimed - other attached executions are unresolved")
+    end
+  end
+
   # Evaluates preconditions (cancel_if and skip_if) with instrumentation.
   #
   # @param step_def [StepDefinition]
@@ -399,6 +510,11 @@ class GenevaDrive::Executor
         if step_def.should_skip?(workflow)
           logger.info("skip_if condition matched, skipping step")
           transition_step!("skipped", outcome: "skipped")
+          # The step may have been woken by a signal and only then decided it
+          # had nothing to do (or a retry re-attached before skip_if flipped).
+          # Skipping settles that event instead of leaving it for the next
+          # waiter on the same name.
+          workflow.settle_signal_for_skipped!(step_execution)
           transition_workflow!("ready")
           workflow.schedule_next_step!
           p[:outcome] = :skipped
@@ -657,6 +773,7 @@ class GenevaDrive::Executor
   def handle_completion
     logger.info("Step completed successfully, scheduling next step")
     transition_step!("completed", outcome: "success")
+    resolve_attached_signal!
     transition_workflow!("ready")
     workflow.schedule_next_step!
   end
@@ -758,6 +875,7 @@ class GenevaDrive::Executor
     when :skip
       logger.info("Exception policy: skip!")
       transition_step!("skipped", outcome: "skipped")
+      resolve_attached_signal!
       transition_workflow!("ready")
       workflow.schedule_next_step!
     when :pause
@@ -768,6 +886,7 @@ class GenevaDrive::Executor
     when :finished
       logger.info("Exception policy: finished!")
       transition_step!("completed", outcome: "success")
+      resolve_attached_signal!
       transition_workflow!("finished")
     else
       logger.info("Exception policy: default (pause!)")
@@ -913,12 +1032,14 @@ class GenevaDrive::Executor
     when :skip
       logger.info("Processing skip signal: scheduling next step")
       transition_step!("skipped", outcome: "skipped")
+      resolve_attached_signal!
       transition_workflow!("ready")
       workflow.schedule_next_step!
 
     when :finished
       logger.info("Processing finished signal: finishing workflow")
       transition_step!("completed", outcome: "success")
+      resolve_attached_signal!
       transition_workflow!("finished")
 
     when :suspend

data/lib/geneva_drive/flow_control.rb

@@ -38,6 +38,17 @@ class GenevaDrive::StepConfigurationError < StandardError; end
 # it is rewritten on every checkpoint and copied to every successor execution.
 class GenevaDrive::CursorTooLargeError < StandardError; end
 
+# Raised when a signal payload exceeds GenevaDrive.max_signal_payload_size
+# once serialized to JSON. A payload describes the event; the data the step
+# works on belongs on the hero.
+class GenevaDrive::SignalPayloadTooLargeError < StandardError; end
+
+# Raised when a signal is delivered to a workflow that has already finished
+# or been canceled. Delivering the very same event twice (same idempotency
+# key) is a no-op rather than an error, so callers who want lenience can
+# rescue just this one class.
+class GenevaDrive::WorkflowNotOngoing < 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.
@@ -276,14 +287,43 @@ module GenevaDrive::FlowControl
       end
 
       if state == "paused"
-        # Workflow was paused (e.g., due to failed step). Resume and skip to next step.
+        # Workflow was paused (e.g., due to failed step). Resume and skip to
+        # next step. The step being skipped past may hold a signal claim on a
+        # failed execution - no further execution of it is coming, so the
+        # operator's skip is what settles that event.
+        holder = execution_holding_signal_claim(next_step_name)
         update!(state: "ready", transitioned_at: nil)
+        settle_signal_for_skipped!(holder)
       else
-        # Workflow is ready with a scheduled step - mark it as skipped
-        current_execution&.mark_skipped!(outcome: "skipped")
+        # Workflow is ready with a scheduled step - mark it as skipped. A
+        # dispatched-but-not-yet-run execution carries an attached signal;
+        # skipping it settles that signal too.
+        skipped_execution = current_execution
+        skipped_execution&.mark_skipped!(outcome: "skipped")
+        settle_signal_for_skipped!(skipped_execution)
       end
 
       schedule_next_step!
     end
   end
+
+  # Finds the execution that still holds a signal claim for a step we are
+  # about to skip past on a paused workflow: the current one if it was
+  # dispatched before the pause, otherwise the failed attempt that paused the
+  # workflow in the first place (same lookup shape resume! uses).
+  #
+  # @param step_name [String, nil] the step being skipped past
+  # @return [GenevaDrive::StepExecution, nil]
+  def execution_holding_signal_claim(step_name)
+    return nil unless GenevaDrive::StepExecution.signal_columns?
+
+    candidate = current_execution
+    return candidate if candidate&.signal_id.present?
+    return nil if step_name.blank?
+
+    step_executions
+      .where(step_name: step_name, state: "failed")
+      .order(created_at: :desc, id: :desc)
+      .first
+  end
 end

data/lib/geneva_drive/jobs/housekeeping_job.rb

@@ -33,6 +33,7 @@ class GenevaDrive::HousekeepingJob < ActiveJob::Base
     results = {
       workflows_cleaned_up: 0,
       step_executions_cleaned_up: 0,
+      signals_cleaned_up: 0,
       stuck_in_progress_recovered: 0,
       stuck_scheduled_recovered: 0
     }
@@ -40,6 +41,7 @@ class GenevaDrive::HousekeepingJob < ActiveJob::Base
     cleanup_completed_workflows!(results)
     recover_stuck_step_executions!(results)
     report_workflow_gauges!
+    report_waiting_gauges!
 
     logger.info("Completed: #{results}")
     results
@@ -89,6 +91,42 @@ class GenevaDrive::HousekeepingJob < ActiveJob::Base
     end
   end
 
+  # Reports gauges for step executions parked waiting for a signal.
+  #
+  # Waiting indefinitely is a legitimate state, not a stuck one, so the stuck
+  # sweeps ignore parked rows. These gauges are what keeps a stalled
+  # rendezvous from being silent:
+  # - `geneva_drive.waiting_step_executions` - parked rows, total and per class
+  # - `geneva_drive.waiting_overdue` - parked longer than
+  #   GenevaDrive.waiting_visibility_threshold, total and per class
+  #
+  # @return [void]
+  def report_waiting_gauges!
+    return unless GenevaDrive::StepExecution.signal_columns?
+
+    report_waiting_gauge!("geneva_drive.waiting_step_executions", GenevaDrive::StepExecution.waiting)
+
+    threshold = GenevaDrive.waiting_visibility_threshold
+    return if threshold.blank?
+
+    overdue = GenevaDrive::StepExecution.waiting.where(waiting_since: ..threshold.ago)
+    report_waiting_gauge!("geneva_drive.waiting_overdue", overdue)
+  end
+
+  # Sets one gauge per workflow class plus an untagged total for the scope.
+  #
+  # @param gauge_name [String] the Measurometer gauge name
+  # @param scope [ActiveRecord::Relation] a step execution scope
+  # @return [void]
+  def report_waiting_gauge!(gauge_name, scope)
+    counts = scope.joins(:workflow).group("#{GenevaDrive::Workflow.table_name}.type").count
+
+    Measurometer.set_gauge(gauge_name, counts.values.sum)
+    counts.each do |type, count|
+      Measurometer.set_gauge(gauge_name, count, workflow: type)
+    end
+  end
+
   # Cleans up completed/canceled workflows older than the configured threshold.
   # Uses efficient batched SQL DELETEs - step executions are deleted first via
   # INNER JOIN, then workflows. Loops until all eligible records are deleted.
@@ -114,7 +152,17 @@ class GenevaDrive::HousekeepingJob < ActiveJob::Base
       break if deleted_count < batch_size
     end
 
-    # Second pass: delete the workflows themselves
+    # Second pass: delete the signals delivered to old workflows
+    if GenevaDrive::Signal.table_available?
+      loop do
+        deleted_count = delete_signals_batch(cutoff_time, batch_size)
+        logger.info("Deleted #{deleted_count} signals")
+        results[:signals_cleaned_up] += deleted_count
+        break if deleted_count < batch_size
+      end
+    end
+
+    # Third pass: delete the workflows themselves
     loop do
       deleted_count = delete_workflows_batch(cutoff_time, batch_size)
       logger.info("Deleted #{deleted_count} workflows")
@@ -123,11 +171,43 @@ class GenevaDrive::HousekeepingJob < ActiveJob::Base
     end
 
     logger.info(
-      "Cleaned up #{results[:workflows_cleaned_up]} workflows " \
-      "and #{results[:step_executions_cleaned_up]} step executions older than #{cutoff_time}"
+      "Cleaned up #{results[:workflows_cleaned_up]} workflows, " \
+      "#{results[:step_executions_cleaned_up]} step executions and " \
+      "#{results[:signals_cleaned_up]} signals older than #{cutoff_time}"
     )
   end
 
+  # Deletes a batch of signals 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_signals_batch(cutoff_time, batch_size)
+    GenevaDrive::Signal.connection_pool.with_connection do |conn|
+      signals_table = conn.quote_table_name(GenevaDrive::Signal.table_name)
+      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 #{signals_table}
+        WHERE id IN (
+          SELECT id FROM (
+            SELECT s.id
+            FROM #{signals_table} s
+            INNER JOIN #{workflows_table} w ON w.id = s.workflow_id
+            WHERE w.state IN ('finished', 'canceled')
+            AND w.transitioned_at < ?
+            LIMIT #{limit}
+          ) AS batch_to_delete
+        )
+      SQL
+
+      conn.delete(GenevaDrive::Signal.sanitize_sql([sql, cutoff_time]))
+    end
+  end
+
   # Deletes a batch of step executions belonging to old workflows.
   #
   # @param cutoff_time [Time] workflows transitioned before this time are eligible

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

@@ -48,6 +48,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

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