geneva_drive 0.6.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a4a73216fcf8355550c3b5e26e76eee14468eb301e8eb315a979bc8f34bdb670
-  data.tar.gz: a9b9cc0d8998f6c479806158dd12725774431e7dba8486c5781ed68f238175b5
+  metadata.gz: 1738e58c5f40199781a27c2345b20657e63ccc0c5a8b28010c2ac820774c2c2f
+  data.tar.gz: f729ef68e929f39fa26b09108f446a9b53ec13013d22d89f22d788b5ac0988e3
 SHA512:
-  metadata.gz: b77f44d451d256d081af6d7b30d62bcaa46bfd41b0606cdcd1d07529e18db7ff5e2d1753d52f6bd24f600f92b7e14587146072a53e46e1052728c760cf6ded78
-  data.tar.gz: 9bdd9f474cd8370ebcc77b4126617833a249b6e1237ed8021463b66d082db63e17bc024fa8718ec3aee1d031731c72b3a9c90903d2ce40ced2f01eb0b1c421ef
+  metadata.gz: 87a29981a0278755e146cebf6e5e8d7075832665335b54511d5c24734a44040c62e9b2f9ae8fcd2558941d5f8cfe9eefc588efef65db09dc131d6602e2089d40
+  data.tar.gz: 9dcbb2ca84072315438dcacfd78d5463563b0ef6f5a940a5ccd12afcef7d2f10fb40cd710ce4bd5ba72142941242ec709f92e4d33927d15ce146538eed93834f

data/CHANGELOG.md

@@ -1,6 +1,8 @@
 # Changelog
 
-## [Unreleased]
+## [0.7.0]
+
+- Add signals: external events delivered to a workflow instance with `workflow.signal!(:payment_confirmed, payload: {...}, idempotency_key: event["id"])`, and a step primitive that parks until one arrives with `step :capture, wait_for: :payment_confirmed`. Signals are rows in a new `geneva_drive_signals` table, persisted before any processing, so arrival order does not matter: a signal that lands before its waiting step exists is buffered and claimed when the step runs, and one that lands after the step parked wakes it immediately. Both sides of the rendezvous run under the workflow row lock, so no signal can slip through the gap, and delivery is one transaction: the insert, the waking of parked executions and every counter bump land together or not at all, so a crashed `signal!` leaves nothing half-delivered (the job enqueue stays after-commit, with the existing stuck-scheduled housekeeping sweep as its backstop). Waiting is a first-class step execution state (`waiting`) that holds no queue slot and no timer — nothing polls. Matching is by name - `wait_for:` also takes a `GenevaDrive::SignalMatcher`, whose optional block narrows by payload and is evaluated on the workflow the signal was sent to (so `hero` is in scope), or any other object responding to `#matches?(signal)`. Matchers are plain reusable objects, so a rule can live in a constant and be shared across steps. Signals move `pending` → `claimed` → `consumed`, consumed only once every attached execution chain has finished cleanly — where skipping counts as finishing, so any flavor of skip (`skip_if:` at wake, `skip!` in a step, an exception policy, or an operator `skip!` on a ready or paused workflow) settles the signal that step was delivered, while skips of steps that never attached leave buffered signals alone — and in the same transaction as the step's own completion, so a reattempt or a `resume!` re-reads the same payload and the audit trail never claims an event was handled when it was not. Two counters on the row, `claimed` and `consumed`, count attachments and clean resolutions (with `claimed?` / `consumed?` reading those counters rather than the lifecycle state). Redelivery is deduplicated by a unique index on `(workflow_id, name, idempotency_key)` — the duplicate call returns the original row flagged `duplicate_delivery?` without dispatching. Payloads go through ActiveJob serializers, come back with indifferent access, and are bounded by `GenevaDrive.max_signal_payload_size` (128 KB, `nil` disables). `signal!` on a finished or canceled workflow raises `GenevaDrive::WorkflowNotOngoing` unless it is a redelivery of a known event; on a paused workflow the row is buffered and delivered by `resume!`. Timeouts are deliberately out of scope for now; waiting is instead made loud through `waiting_since` and two housekeeping gauges (`geneva_drive.waiting_step_executions`, `geneva_drive.waiting_overdue` past `GenevaDrive.waiting_visibility_threshold`, 7 days by default), with `skip!` and `cancel!` as operator escape hatches. Needs one new installer migration (the signals table plus two columns on step executions); until it runs everything else is unaffected and executing a `wait_for:` step raises a configuration error pointing at the missing migration. Test helpers: `assert_waiting_for_signal`, `assert_signal_state`, and the step-driving helpers now raise instead of spinning on a parked execution. Mixing up `wait:` and `wait_for:` now raises `StepConfigurationError` at class load in both directions, which also tightens `wait:` to reject Strings (previously `wait: "later"` silently meant zero seconds).
 
 ## [0.6.0]
 

data/MANUAL.md

@@ -679,6 +679,179 @@ test "keeps its place across interruptions" do
 end
 ```
 
+## Waiting for Signals
+
+Some steps cannot finish on their own. A payment needs the provider's webhook, a contract needs a countersignature, a shipment needs the carrier to scan the parcel. The usual Rails answer is to poll — schedule the step, check whether the thing happened, `reattempt!(wait: 5.minutes)` if it did not — and that works, but it burns a worker slot on every check and it puts a floor under how fast the workflow can react.
+
+A **signal** inverts that. It is an event record addressed to one workflow instance:
+
+```ruby
+# app/controllers/payment_webhooks_controller.rb
+workflow = OrderFulfillmentWorkflow.ongoing.for_hero(order).first
+workflow.signal!(:payment_confirmed,
+  payload: {amount_cents: event["amount"]},
+  idempotency_key: event["id"])
+```
+
+And a step declares that it waits for one with `wait_for:`:
+
+```ruby
+class OrderFulfillmentWorkflow < GenevaDrive::Workflow
+  step :reserve_stock do
+    hero.reserve_stock!
+  end
+
+  step :capture_payment, wait_for: :payment_confirmed do
+    hero.capture!(received_signal.payload[:amount_cents])
+  end
+
+  step :ship do
+    ShippingLabel.create!(order: hero)
+  end
+end
+```
+
+When `:capture_payment` runs and no matching signal has arrived, its execution parks in the `waiting` state and the job ends. Nothing is enqueued, nothing polls, and the parked row costs nothing until `signal!` wakes it. When the webhook lands, `signal!` wakes the execution and enqueues its job again.
+
+Signals need one migration — it creates the `geneva_drive_signals` table and adds two columns to `geneva_drive_step_executions` — so re-run `bin/rails generate geneva_drive:install` on an existing installation to pick it up. Until then everything else keeps working, and executing a step that declares `wait_for:` fails with a configuration error pointing at the missing migration.
+
+### Arrival Order Does Not Matter
+
+The signal row is written before anything is dispatched, which is what makes the timing irrelevant. There are exactly two places where sender and receiver meet, and both run under the workflow row lock:
+
+- When the waiting step's job runs, it looks for a matching unconsumed signal. Found: attach and run. Not found: park.
+- When `signal!` is called, it looks for parked executions. Found: attach, reschedule, enqueue. Not found: the row simply sits there.
+
+So a webhook that arrives while the workflow is still three steps away from the waiter is not lost and not early — it is buffered, and claimed when the waiting step finally runs. A webhook that arrives a week after the step parked wakes it immediately.
+
+Delivery is one database transaction: the signal row, the waking of the parked execution and the bookkeeping around it either all land or none of them do. If `signal!` raises, nothing was written and the sender can simply try again.
+
+> [!IMPORTANT]
+> `signal!` is an instance method: you find the workflow the way you find anything in Rails, usually `SomeWorkflow.ongoing.for_hero(record).first`. Delivering a brand-new event to a workflow that has already finished or been canceled raises `GenevaDrive::WorkflowNotOngoing` rather than silently doing nothing.
+
+### Deduplicating Redelivery
+
+Webhook providers redeliver. Pass an `idempotency_key:` — the provider's event id is the natural choice — and the second delivery becomes a database-level no-op that returns the row the first one wrote:
+
+```ruby
+signal = workflow.signal!(:payment_confirmed, idempotency_key: event["id"])
+Rails.logger.info("Ignoring redelivered #{event["id"]}") if signal.duplicate_delivery?
+```
+
+Redelivering the very event that finished the workflow is also a no-op, not an error — that specific case is what the deduplication is for. Signals sent without an idempotency key never deduplicate: two calls make two rows, the older one is delivered first, and the newer one stays in the table as an auditable record of what arrived.
+
+### Narrowing What Counts as a Match
+
+`wait_for: :document_signed` is shorthand for `wait_for: GenevaDrive::SignalMatcher.new(:document_signed)`, which matches on name alone. Give the matcher a block and it also has to like the payload:
+
+```ruby
+class ContractWorkflow < GenevaDrive::Workflow
+  # The block receives the payload and runs on the workflow the signal was
+  # sent to, so `hero` and the workflow's own methods are in scope.
+  step :await_countersignature,
+    wait_for: GenevaDrive::SignalMatcher.new(:document_signed) { |payload|
+      payload[:document_id] == hero.contract_id
+    } do
+    hero.mark_countersigned!
+  end
+end
+```
+
+A matcher is a plain object with no ties to the step that uses it, so a rule worth repeating can live in a constant and be shared across steps and workflows:
+
+```ruby
+SETTLED = GenevaDrive::SignalMatcher.new(:payment_confirmed) { |payload| payload[:amount_cents].to_i > 0 }
+
+step :capture_payment, wait_for: SETTLED do
+  hero.capture!
+end
+```
+
+Anything responding to `#matches?(signal)` works too, and owns the whole predicate — which is how a single step waits on either of two names:
+
+```ruby
+class PaymentSettled
+  def initialize(min_cents:) = @min_cents = min_cents
+
+  def matches?(signal)
+    %w[payment_confirmed payment_captured].include?(signal.name) &&
+      signal.payload[:amount_cents].to_i >= @min_cents
+  end
+end
+
+step :capture_payment, wait_for: PaymentSettled.new(min_cents: 100) do
+  hero.capture!
+end
+```
+
+Payloads are serialized with ActiveJob serializers, so `Date`, `Time` and ActiveRecord objects survive the round trip. Hashes come back with indifferent access, because a webhook sender produces string keys and a Ruby caller produces symbols and a matcher should not have to care. The serialized payload is limited to 128 KB (`GenevaDrive.max_signal_payload_size`, `nil` disables) — a payload describes the event; the data your workflow works on belongs on the hero.
+
+> [!WARNING]
+> Matchers run at the gate *and* inside `signal!`, in the sender's process. Keep them cheap and free of side effects, exactly like `skip_if:`. A matcher that raises during `signal!` raises to whoever sent the signal — and because `signal!` is a single transaction, the delivery rolls back whole: no signal row is recorded, nothing is attached or woken, no counter moves. The sender (or the webhook provider's retry) re-delivers once the matcher is fixed.
+
+### How Waiting Composes
+
+- `wait: 2.days, wait_for: :payment_confirmed` means "no earlier than two days from now, and only once signaled". A signal arriving during the delay is buffered and claimed when the step finally runs.
+- `skip_if:` is evaluated before waiting, so "wait for the signature — unless the contract was pre-signed" skips immediately instead of parking forever. Both `skip_if:` and `cancel_if` are re-evaluated when a signal wakes the step; a parked workflow does not re-check them while it sleeps. A step skipped at wake consumes the signal that woke it, so the next waiter does not inherit a stale event.
+- `resumable_step` accepts `wait_for:`. The wait happens once, at the start of the chain, and `received_signal` stays the same across every successor execution.
+- A reattempt — yours or an exception policy's — re-reads the *same* signal. Reattempting means "process this event again", not "wait for another event".
+
+The signal itself moves through `pending` → `claimed` → `consumed`. It is claimed when an execution attaches to it, and consumed once every attached execution has finished cleanly, in the same transaction as the step's own completion. A step that fails, pauses, or gets canceled leaves its signal claimed, so the retry picks up the same payload and the audit trail does not claim an event was handled when it was not.
+
+Skipping counts as finishing: skipping a step that was delivered a signal consumes that signal, whether the skip came from `skip_if:`, from `skip!` inside the step, from an exception policy, or from an operator calling `workflow.skip!` on a ready or paused workflow. Moving past a step deliberately settles the event it was given. Skipping a step that never attached — one still parked, or one whose `skip_if:` fired before it ever looked for a signal — leaves buffered signals exactly as they were.
+
+Two counters on the row make that legible: `signal.claimed` counts attachments (a step that failed and was retried attaches twice), and `signal.consumed` counts cleanly resolved ones. In a linear workflow they end at one apiece. The predicates `signal.claimed?` and `signal.consumed?` read those counters, so they answer "was this event ever picked up" and "was it ever handled" — which is not the same question as `signal.state`, and is usually the one worth asking.
+
+> [!NOTE]
+> Two sequential steps waiting on `:payment_confirmed` need two signals. The first step consumes the first signal, so the second step parks until another one arrives.
+
+### Getting Unstuck
+
+There is no `timeout:` option. Waiting forever is a legitimate state — a contract may genuinely sit unsigned for months — so instead of a timer, waiting is made loud: a distinct `waiting` state, a `waiting_since` timestamp, and two housekeeping gauges, `geneva_drive.waiting_step_executions` and `geneva_drive.waiting_overdue` (parked longer than `GenevaDrive.waiting_visibility_threshold`, seven days by default). Alert on the overdue gauge.
+
+When something does stall, three escape hatches already exist:
+
+- `workflow.skip!` abandons the wait and moves to the next step.
+- `workflow.cancel!` gives up on the workflow.
+- The queue is already a clock: schedule a job that signals a deadline, and let the step decide.
+
+```ruby
+# Send the workflow its own deadline; the step reads it off the payload
+class ContractDeadlineJob < ApplicationJob
+  def perform(contract)
+    workflow = ContractWorkflow.ongoing.for_hero(contract).first
+    workflow&.signal!(:document_signed,
+      payload: {timed_out: true},
+      idempotency_key: "deadline-#{workflow.id}")
+  end
+end
+
+step :await_countersignature, wait_for: :document_signed do
+  cancel! if received_signal.payload[:timed_out]
+  hero.mark_countersigned!
+end
+```
+
+### Testing Waiting Steps
+
+The step-driving helpers refuse to spin on a parked execution — they raise and tell you which signal is missing, because a test that hangs on a rendezvous is far worse than one that fails:
+
+```ruby
+test "captures once the payment is confirmed" do
+  workflow = OrderFulfillmentWorkflow.create!(hero: order)
+  perform_next_step(workflow)                    # :reserve_stock
+  perform_next_step(workflow)                    # :capture_payment parks
+
+  assert_waiting_for_signal(workflow, :payment_confirmed)
+
+  workflow.signal!(:payment_confirmed, payload: {amount_cents: 12_500})
+  speedrun_workflow(workflow)
+
+  assert_signal_state(workflow, :payment_confirmed, :consumed)
+  assert workflow.finished?
+end
+```
+
 ## Exception Handling
 
 ### Default Behavior
@@ -1080,6 +1253,7 @@ Step executions have their own state machine:
 | State | Meaning |
 |-------|---------|
 | `scheduled` | Waiting to run |
+| `waiting` | Parked until a matching signal arrives |
 | `in_progress` | Currently executing |
 | `completed` | Finished successfully |
 | `failed` | Exception occurred |
@@ -1980,6 +2154,7 @@ end
 | State | Meaning |
 |-------|---------|
 | `scheduled` | Waiting to run |
+| `waiting` | Parked until a matching signal arrives |
 | `in_progress` | Currently executing |
 | `completed` | Finished successfully |
 | `failed` | Exception occurred |
@@ -1993,6 +2168,7 @@ A resumable step interrupted mid-iteration completes its execution with outcome
 | Option | Type | Description |
 |--------|------|-------------|
 | `wait:` | Duration | Delay before step executes |
+| `wait_for:` | Symbol, String, `SignalMatcher`, matcher object | Park until a matching signal arrives |
 | `job_options:` | Hash | Options passed to Active Job's `set` method for this step |
 | `skip_if:` | Proc, Symbol, Boolean | Condition to skip step |
 | `on_exception:` | Symbol | Exception handler (`:pause!`, `:cancel!`, `:reattempt!`, `:skip!`) |

data/README.md

@@ -8,6 +8,8 @@ GenevaDrive provides a clean DSL for defining multi-step workflows that execute
 
 - **Hero-oriented**: Workflows are associated with a polymorphic "hero" (the subject of the workflow)
 - **Step-based execution**: Define workflows as a series of steps with optional wait times
+- **Resumable steps**: Iterate over large collections with a database-checkpointed cursor, surviving interruptions
+- **Signals**: Steps can park until an external event arrives (`wait_for:`), woken by `workflow.signal!` from a webhook or controller
 - **Durable**: Steps are persisted to the database, surviving process restarts
 - **Idempotent**: Database constraints ensure each step runs exactly once
 - **Flow control**: Methods like `cancel!`, `pause!`, `skip!`, `reattempt!`, and `finished!`

data/lib/generators/geneva_drive/install/install_generator.rb

@@ -65,6 +65,11 @@ module GenevaDrive
           "add_resumable_step_support.rb",
           "db/migrate/add_resumable_step_support_to_geneva_drive_step_executions.rb"
         )
+
+        migration_template(
+          "add_signals_support.rb",
+          "db/migrate/add_signals_support_to_geneva_drive.rb"
+        )
       end
 
       # Creates the initializer file.

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

@@ -0,0 +1,94 @@
+# 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. 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
+
+      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}")
@@ -336,6 +343,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 +366,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 +397,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 +492,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 +755,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 +857,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 +868,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 +1014,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