geneva_drive 0.4.0 → 0.6.0

data/MANUAL.md

@@ -1,6 +1,8 @@
-# GenevaDrive Manual
+# Introduction
 
-GenevaDrive provides durable, multi-step workflows for Rails applications. We built it because the prevailing "durable function" approach — where you write an `async` function and expect the runtime to persist it mid-execution — is fundamentally broken. The graph of steps and the code that executes each step must live in separate universes. GenevaDrive delivers on that architecture.
+GenevaDrive provides durable, multi-step workflows for Rails applications. The graph of steps and the code that executes each step live in separate universes — the structure is defined at class load time, the behavior runs later via ActiveJob. GenevaDrive delivers on that architecture.
+
+# Part I — Why GenevaDrive Exists
 
 ## The Problem with Long-Running Processes
 
@@ -12,115 +14,11 @@ Imagine you need to onboard a new user. You send a welcome email, wait three day
 - **Idempotency is hard to get right.** If a job runs twice due to a queue hiccup, you might send two welcome emails or charge a credit card twice.
 - **ActiveJob does not provide a stable ID.** Retried jobs can create duplicate job IDs even though the jobs are distinct. You cannot use the job ID as an idempotency key.
 
-## The problem with "durable functions"
-
-There is a rather popular approach to building durable execution systems based on the concept of "durable functions". Systems like [Temporal](https://temporal.io) and [absurd](https://lucumr.pocoo.org/2025/11/3/absurd-workflows/) as well as [Vercel Workflows](https://vercel.com/docs/workflow) take that concept quite far. It seems neat on the surface, yet deeply flawed in nature.
-
-The assumption made with those "durable functions" is that it is possible to _pretend that you have a marshalable stack._ For example, this section in a workflow function:
-
-```js
-let step = 0;
-while (step++ < 20) {
-  const { newMessages, finishReason } = await ctx.step("iteration", async () => {
-    return await singleStep(messages);
-  });
-  messages.push(...newMessages);
-  if (finishReason !== "tool-calls") {
-    break;
-  }
-}
-```
-
-can only work if `step` gets marshaled and reinstated if the function gets resumed. Async generators (and Fibers in Ruby, and - in general - any systems based on continuations or coroutines) allow suspension and resumption, but none allow proper _serialization and revival._ If you try to encode a durable function, consisting of multiple steps, as a suspendable and resumable workflow, you essentially have 3 ways to do it:
-
-* Make your function restartable from the very beginning (idempotent)
-* Use a serializable system stack frame, which - usually - comes down to serializing a VM image upon suspension
-* Make the user write functions that only - and ever - use special facilities for accessing transients (current time, database connections, heavy resources)
-
-Most "workflow engines" do their utmost to maintain the guise of resumable functions _while not providing them._ The fact that you have to wait on a Fiber to receive an HTTP result is not very useful if the only program that can receive that result is the very process which has started that HTTP request.
-
-### Why no modern runtime provides stack serialization
-
-The fundamental issue is that no mainstream runtime — V8, SpiderMonkey, YARV, the JVM, the CLR — provides the ability to serialize an executing call stack to bytes and revive it later. This is not an oversight. It is a deliberate engineering decision driven by hard constraints.
-
-A call stack contains pointers: return addresses, references to heap objects, handles to file descriptors and sockets, pointers into native libraries. Serializing a pointer is meaningless — the memory address 0x7fff5fbff8c0 on one machine means nothing on another, or even on the same machine after a restart. To serialize a stack, you must either:
-
-1. **Replace all pointers with symbolic references** that can be resolved at revival time. This requires a complete indirection layer over every memory access — a performance catastrophe for general-purpose code.
-2. **Serialize the entire heap along with the stack**, effectively snapshotting the whole process. This is what Smalltalk images did.
-3. **Restrict the language** so that stacks never contain non-serializable values. This means no closures over native resources, no FFI, no direct system calls.
-
-Modern runtimes chose speed over serializability. JavaScript engines like V8 perform aggressive JIT compilation that inlines functions, eliminates stack frames, and stores values in machine registers. The "stack" you think exists in your `async` function is a fiction maintained for debugging — the actual execution state is scattered across registers, hidden classes, inline caches, and optimized machine code that has no stable representation.
-
-### Systems that actually solved this
-
-True stack serialization is not impossible. It has been done — just not in environments optimized for raw speed.
-
-**Smalltalk images** are the canonical example. A Smalltalk system serializes its entire object memory, including all activation records (stack frames), to a single file. You can save an image mid-computation, quit, restart days later, and continue exactly where you left off. This works because Smalltalk controls everything: the object format, the bytecode interpreter, the garbage collector. There are no opaque pointers to external resources — or if there are, the image-saving mechanism explicitly handles them.
-
-**Erlang/OTP** takes a different approach: processes are so lightweight and isolated that you simply design for crash recovery. A process dies, its supervisor restarts it, and it reconstructs its state from durable storage. There's no pretense that you can freeze and thaw a running computation — you design for restart from the beginning.
-
-**Scheme continuations** (particularly in implementations like Chez Scheme or Gambit) can capture delimited continuations and, in some implementations, serialize them. But these implementations pay the cost: they maintain a CPS-transformed representation that is inherently slower than direct-style execution.
-
-**[Seaside](https://seaside.st/)** deserves special mention. This Smalltalk web framework, developed in the early 2000s, used continuations to model web application control flow. You could write a multi-page wizard as a single method with `call:` and `answer:` — the framework would suspend execution while waiting for user input and resume it when the response arrived. [Wee](https://github.com/mneumann/wee), a Ruby port inspired by Seaside's ideas, attempted the same trick using Ruby's `callcc`. Both frameworks demonstrated genuine continuation-based web development. But they also demonstrated its limits: Seaside required either keeping all session continuations in memory (scaling poorly) or relying on Smalltalk's image persistence (requiring the same VM instance to handle subsequent requests). Wee suffered from Ruby 1.8's notorious continuation memory leaks and remained a curiosity rather than a production tool.
-
-The fundamental problem with continuation-based web frameworks is process affinity. A suspended continuation exists in the memory of a specific process on a specific machine. When the user submits the next form, that exact process must handle the request — no load balancer can route it elsewhere, no autoscaler can spin up a fresh instance to handle the load, no deployment can replace the running code. This is incompatible with modern elastic infrastructure. Kubernetes doesn't care that your user's shopping cart continuation lives in pod `web-7f8d9c-xk2p4` — when traffic spikes, it will route requests wherever capacity exists. When you deploy, it will terminate old pods and start new ones. Your continuations die with them.
-
-### The problem of transient resources
-
-Even if you could serialize a continuation, you would face the problem of transient resources. A continuation captures the call stack, but the call stack contains references to objects that cannot meaningfully survive process boundaries.
-
-Consider a database transaction. Your step opens a connection, begins a transaction, inserts a row, and then — mid-transaction — suspends to wait for user confirmation:
-
-```ruby
-step :reserve_inventory do
-  ActiveRecord::Base.transaction do
-    hero.line_items.each { |item| Inventory.decrement!(item.sku, item.quantity) }
-    # Suspend here, wait for payment confirmation...
-    yield  # In a hypothetical continuation-based system
-    hero.update!(reserved_at: Time.current)
-  end
-end
-```
-
-What happens when you try to revive this continuation on a different machine, or even the same machine after a restart? The `ActiveRecord::Base.connection` object holds a socket to a PostgreSQL server. That socket is gone. You could theoretically reconnect — some systems use lazy connection resolution for exactly this reason — but reconnecting gives you a *new* connection. The transaction you started? It was rolled back the moment the original connection died. The `BEGIN` you issued exists only in the logs. The row locks you held have been released. Some other process may have already modified the rows you thought you had locked.
-
-There is no way to "re-enter" a transaction. Transactions are not addressable resources you can resume — they are ephemeral states of a connection that exist only as long as that connection lives. The same applies to file handles, HTTP connections mid-request, mutex locks, and any other resource that represents a relationship with an external system. A serialized continuation that references such resources is not a suspended computation — it is a lie about the state of the world.
-
-The lesson from these systems is clear: serializable execution state requires either total control over the runtime environment or acceptance of significant performance overhead. You cannot bolt it onto V8 or Ruby's YARV after the fact.
-
-### Why modern developers won't build this
-
-Building a marshalable stack VM is a multi-year, multi-million-dollar undertaking. It requires:
-
-- Deep expertise in compiler construction, garbage collection, and runtime systems
-- Willingness to sacrifice raw performance for serializability
-- Long-term maintenance commitment as the underlying platform evolves
-
-The JavaScript ecosystem optimizes for different goals: startup time, peak throughput, memory efficiency on mobile devices. Google, Mozilla, and Apple compete on V8, SpiderMonkey, and JavaScriptCore benchmarks. No one is competing on "ability to serialize a running function to disk."
-
-The developers building "durable function" frameworks are, by and large, application developers — skilled in their domain, but not runtime engineers. They are building atop V8, not replacing it. They cannot make V8 serialize its internal state because V8 was never designed to expose that state. The best they can do is replay: run the function again from the start, skip the steps that already completed, and hope the interleaving of side effects is deterministic. This is not serialization. It is simulation.
-
-### Pretending is denial
-
-When a framework claims to offer "durable functions" without true stack serialization, it is engaging in denial — not about the laws of physics, but about the semantics of their own system.
-
-Consider what happens when a "durable function" resumes. The framework:
-
-1. Loads the function definition
-2. Starts executing from the beginning
-3. Intercepts calls to "step" functions and returns cached results instead of re-executing
-
-This only works if the control flow between steps is perfectly deterministic. But JavaScript (and Ruby, and Python) are not deterministic languages. The order of object keys, the behavior of `Math.random()`, the resolution of race conditions in `Promise.all()` — all of these can vary between runs. If your loop counter depends on a hash iteration order that changed between Node versions, your "resumed" function takes a different path than the original.
-
-The frameworks paper over this with restrictions: don't use randomness, don't depend on time, don't read from external systems except through blessed APIs. But these restrictions are invisible until you violate them. You write what looks like normal code, you test it, it works — and then six months later, after a Node upgrade, a resumed workflow takes a wrong turn and corrupts your data.
-
-Honesty requires admitting what the system actually provides. If execution state is not truly serialized, don't pretend it is. Make the boundaries explicit. Make the steps explicit. Make the user acknowledge, at every step boundary, that they are persisting state to a database. GenevaDrive takes this position.
-
-### The DAG alternative
+## The DAG Approach
 
-Instead, it is useful to look at workflow systems in terms of _DAGs_ (directed acyclic graphs). In that vision, the code driving the DAG and the code driving the nodes in that DAG is strictly separate, and runs in different domains. While the DAG definition code is "single use" and runs during the orchestration, the actual code of the nodes _is_ required to be explicitly restartable, and is required to be explicitly idempotent. There is no pretense that "this function being wrapped in this callback will cleanly resume", and there is way less possibility to "accidentally" call something non-idempotent when defining the nodes.
+Instead of pretending that a function can be suspended, serialized, and resumed — which no mainstream runtime actually supports — GenevaDrive models workflows as DAGs (directed acyclic graphs). The code driving the DAG and the code driving each node are strictly separate and run in different domains.
 
-A geneva_drive workflow is a DAG with a single permitted input and a single permitted output per node, nothing more. It explicitly ditches the illusion of a marshalable VM universe in favor of clarity, cohesion with the host environment (UNIX system running Ruby running Rails) and deliberately picks clarity over pretense of magic.
+A GenevaDrive workflow is a DAG with a single permitted input and a single permitted output per node. It explicitly ditches the illusion of a marshalable VM universe in favor of clarity, cohesion with the host environment (UNIX system running Ruby running Rails) and deliberately picks clarity over pretense of magic.
 
 ```ruby
 class OrderFulfillmentWorkflow < GenevaDrive::Workflow  # DAG context — definition time
@@ -158,6 +56,38 @@ GenevaDrive addresses these challenges with a small set of guarantees:
 
 ---
 
+# Part II — Getting Started
+
+## Installation and Setup
+
+### Adding the Gem
+
+```bash
+bundle add geneva_drive
+bin/rails generate geneva_drive:install
+bin/rails db:migrate
+```
+
+The generator creates the migration required for geneva_drive to operate - you need to run all of them. When updating the gem, rerun the generator to add any migrations you may need to run as migrations get added as the gem evolves.
+
+### Database Tables
+
+GenevaDrive uses a two-table design:
+
+- **`geneva_drive_workflows`** — The workflow records. Each row represents one workflow instance with its current state, hero association, and progress tracking.
+- **`geneva_drive_step_executions`** — The idempotency keys. Each row represents one attempt to execute a step, with timing, outcome, and error information.
+
+This separation keeps the workflows table clean while maintaining a complete audit trail in step executions.
+
+### UUID Primary Keys
+
+If your application uses UUID primary keys, the migrations will detect this and also use UUIDs for the foreign keys and the primary keys of the geneva_drive resources.
+
+Note that you don't want to mix integer IDs and UUIDs in the same application. geneva_drive uses a polymorphic relation for the `hero` of the workflow, which has a typed `hero_id` column. You will thus want either all of your models to be used as heroes to have UUID primary keys or bigint primary keys, but not mix the two.
+
+> [!WARNING]
+> If you are using UUIDs, we also strongly recommend adopting a lexicographically ordered UUID flavour, at least for the geneva_drive tables. Such flavours include [UUIDv7](https://github.com/seouri/rails-uuid-pk) and [tou](https://github.com/cheddar-me/tou) - you will want your primary keys to be pre-sorted for using the admin effectively, as well as for efficient `find_each` usage with the geneva_drive tables.
+
 ## Core Concepts
 
 ### Workflows
@@ -249,6 +179,8 @@ end
 
 ---
 
+# Part III — Defining Workflows
+
 ## Defining Steps
 
 ### Named Steps
@@ -342,22 +274,30 @@ The loop bodies execute once when Ruby loads the class. Each iteration adds a ne
 
 ### Instance Methods as Steps
 
-For complex steps, you can define instance methods and reference them with `step def`:
+The step definition can be a block, but if you give the step the same name as an instance method of your workflow that method will be called instead:
 
 ```ruby
 class DataExportWorkflow < GenevaDrive::Workflow
-  step def gather_records
-    hero.update!(export_data: hero.exportable_records.to_json)
+  step :anonymize_records
+  
+  def anonymize_records
+    Anonymizer.process_arel(hero.records)
   end
+end
+```
+
+Since `def` in modern Rubies returns the name of the method you define as a `Symbol` you can use the `step def` shorthand as well. Together with "endless methods" this can give you a very compact description:
+
+```ruby
+class DataExportWorkflow < GenevaDrive::Workflow
+  step def gather_records = hero.update!(export_data: hero.exportable_records.to_json)
 
   step def write_to_storage
     Storage.write(hero.export_path, hero.export_data)
     hero.update!(exported_at: Time.current)
   end
 
-  step def notify_user
-    ExportMailer.complete(hero).deliver_later
-  end
+  step def notify_user = ExportMailer.complete(hero).deliver_later
 end
 ```
 
@@ -385,7 +325,58 @@ end
 
 The referenced step must already be defined — you can only insert before or after steps that appear earlier in the class body.
 
----
+## Conditional Execution
+
+### Skipping Steps with `skip_if:`
+
+You can declare conditions that cause a step to be skipped without entering the step body:
+
+```ruby
+class NotificationWorkflow < GenevaDrive::Workflow
+  step :send_email, skip_if: -> { hero.email_unsubscribed? } do
+    NotificationMailer.notify(hero).deliver_later
+  end
+
+  step :send_sms, skip_if: :sms_disabled? do
+    SmsService.notify(hero)
+  end
+
+  private
+
+  def sms_disabled?
+    !hero.sms_enabled? || hero.phone.blank?
+  end
+end
+```
+
+The `skip_if` option accepts a lambda, a symbol (method name), or a boolean. The condition is evaluated before the step executes.
+
+For a complete example showing conditional steps in context, see the [User Onboarding Workflow](#user-onboarding-workflow) in the appendix.
+
+### Blanket Cancellation with `cancel_if`
+
+When certain conditions should cancel the entire workflow regardless of which step is running, use `cancel_if`:
+
+```ruby
+class EngagementWorkflow < GenevaDrive::Workflow
+  cancel_if { hero.deactivated? }
+  cancel_if { hero.unsubscribed? }
+
+  step :send_week_1_email do
+    EngagementMailer.week_1(hero).deliver_later
+  end
+
+  step :send_week_2_email, wait: 7.days do
+    EngagementMailer.week_2(hero).deliver_later
+  end
+
+  step :send_week_4_email, wait: 14.days do
+    EngagementMailer.week_4(hero).deliver_later
+  end
+end
+```
+
+GenevaDrive evaluates `cancel_if` conditions before every step. If any condition returns true, the workflow cancels immediately.
 
 ## Flow Control
 
@@ -451,9 +442,48 @@ When a workflow is paused, it stays paused until you explicitly resume it:
 
 ```ruby
 workflow = FraudReviewWorkflow.find(id)
-workflow.resume!  # Schedules the next step
+workflow.resume!  # Re-enqueues the scheduled step
+```
+
+### How Pause and Resume Work
+
+When you call `pause!` externally on a workflow that's waiting for a scheduled step, GenevaDrive preserves the scheduled step execution rather than canceling it. This provides better timeline visibility — you can see that a step was scheduled, became overdue during the pause period, and when it eventually ran.
+
+**Pause behavior:**
+- The workflow transitions from `ready` to `paused`
+- The scheduled step execution remains in `scheduled` state
+- If the scheduled time passes while paused, the execution becomes "overdue" (visible in the timeline)
+
+**Resume behavior:**
+- The workflow transitions from `paused` back to `ready`
+- If a scheduled execution exists:
+  - If still in the future → a job is enqueued with remaining wait time
+  - If overdue (scheduled time has passed) → a job is enqueued to run immediately
+- If no scheduled execution exists (executor canceled it while paused) → a new execution is created
+
+```ruby
+# Timeline example:
+# T+0h: step_one completes, step_two scheduled for T+2h
+# T+1h: pause! called (step_two still scheduled for T+2h)
+# T+3h: resume! called (step_two is overdue, runs immediately)
+
+workflow = WaitingWorkflow.create!(hero: user)
+perform_next_step(workflow)           # step_one runs, step_two scheduled
+
+# Later...
+workflow.pause!                        # step_two stays scheduled
+workflow.step_executions.last.state   # => "scheduled"
+
+# Much later (after scheduled time passed)...
+workflow.resume!                       # step_two re-enqueued to run now
 ```
 
+This behavior means:
+- Multiple pause/resume cycles reuse the same step execution (no duplicates)
+- The scheduled_for timestamp shows when the step was originally intended to run
+- Overdue steps are clearly visible — their scheduled_for is in the past
+- The executor guards against duplicate execution, so multiple jobs for the same step are safe
+
 ### Reattempting Steps
 
 Use `reattempt!` to retry the current step, optionally after a delay:
@@ -516,134 +546,138 @@ class OrderFulfillmentWorkflow < GenevaDrive::Workflow
 end
 ```
 
----
-
-## Workflow States
-
-### State Machine Diagram
-
-```mermaid
-stateDiagram-v2
-    [*] --> ready: create
-    ready --> performing: step starts
-    performing --> ready: step completes / reattempt
-    performing --> finished: last step completes / finished!
-    performing --> canceled: cancel!
-    performing --> paused: pause! / exception
-    paused --> ready: resume!
-```
-
-A workflow begins in `ready` state. When a step starts executing, it transitions to `performing`. Upon step completion, it returns to `ready` (unless it was the last step, in which case it transitions to `finished`).
-
-### Step Execution States
-
-Step executions have their own state machine:
-
-| State | Meaning |
-|-------|---------|
-| `scheduled` | Waiting to run |
-| `in_progress` | Currently executing |
-| `completed` | Finished successfully |
-| `failed` | Exception occurred |
-| `canceled` | Canceled before execution |
-| `skipped` | Skipped via `skip_if` or `skip!` |
-
----
+## Resumable Steps
 
-## Conditional Execution
+A regular step must finish within a single job execution. When a step has to churn through a large collection — sending a campaign to 200 000 subscribers, syncing a paginated API, backfilling a table — that single execution becomes a liability: a deploy, a worker restart, or a queue timeout loses all progress. Resumable steps solve this with **cursor-based iteration**: the step periodically checkpoints its position into the database, and can be interrupted and continued in a later job execution from exactly where it left off.
 
-### Skipping Steps with `skip_if:`
+Resumable steps store their state in two extra columns on `geneva_drive_step_executions` (`cursor` and `continues_from_id`), added by the installer migrations — re-run `bin/rails generate geneva_drive:install` on an existing installation to pick them up. Until the migration runs, everything else keeps working: regular steps, pause/resume and housekeeping are unaffected, and executing an actual `resumable_step` fails with a configuration error pointing at the missing migration.
 
-You can declare conditions that cause a step to be skipped without entering the step body:
+Define one with `resumable_step`. The block receives an `IterableStep` object (API-compatible with Rails 8.1's `ActiveJob::Continuation::Step`):
 
 ```ruby
-class NotificationWorkflow < GenevaDrive::Workflow
-  step :send_email, skip_if: -> { hero.email_unsubscribed? } do
-    NotificationMailer.notify(hero).deliver_later
+class CampaignWorkflow < GenevaDrive::Workflow
+  step :prepare do
+    hero.update!(status: "sending")
   end
 
-  step :send_sms, skip_if: :sms_disabled? do
-    SmsService.notify(hero)
+  resumable_step :send_notifications do |iter|
+    iter.iterate_over_records(hero.subscribers) do |subscriber|
+      CampaignMailer.notify(hero, subscriber).deliver_later
+    end
   end
 
-  private
-
-  def sms_disabled?
-    !hero.sms_enabled? || hero.phone.blank?
+  step :finalize do
+    hero.update!(status: "sent")
   end
 end
 ```
 
-The `skip_if` option accepts a lambda, a symbol (method name), or a boolean. The condition is evaluated before the step executes.
-
-For a complete example showing conditional steps in context, see the [User Onboarding Workflow](#user-onboarding-workflow) in the appendix.
+### The Cursor
 
-### Blanket Cancellation with `cancel_if`
+The cursor is a value persisted on the step execution after every checkpoint. It is whatever your iteration needs to pick up where it stopped: a record ID, a page number, an opaque API token, a date. Cursors are serialized with ActiveJob serializers, so anything ActiveJob can serialize works — including `Date` and `Time` — without manual conversion.
 
-When certain conditions should cancel the entire workflow regardless of which step is running, use `cancel_if`:
+The cursor is a position marker, not a place to store the data being processed: it is rewritten on every checkpoint and copied to every successor execution. To keep that write path cheap, the serialized JSON is limited to 128 KB by default — exceeding it raises `GenevaDrive::CursorTooLargeError`. The limit is configurable in the initializer via `GenevaDrive.max_cursor_size` (`nil` disables the check).
 
 ```ruby
-class EngagementWorkflow < GenevaDrive::Workflow
-  cancel_if { hero.deactivated? }
-  cancel_if { hero.unsubscribed? }
-
-  step :send_week_1_email do
-    EngagementMailer.week_1(hero).deliver_later
-  end
-
-  step :send_week_2_email, wait: 7.days do
-    EngagementMailer.week_2(hero).deliver_later
-  end
-
-  step :send_week_4_email, wait: 14.days do
-    EngagementMailer.week_4(hero).deliver_later
+resumable_step :process_records do |iter|
+  hero.records.where("id > ?", iter.cursor || 0).find_each do |record|
+    process(record)
+    iter.set!(record.id)   # persist cursor, check for interruption
   end
 end
 ```
 
-GenevaDrive evaluates `cancel_if` conditions before every step. If any condition returns true, the workflow cancels immediately.
+The `IterableStep` API:
 
----
+| Method | Effect |
+|--------|--------|
+| `iter.cursor` | Current cursor value (`nil` on first run) |
+| `iter.set!(value)` | Set the cursor, persist it, check for interruption |
+| `iter.advance!` | Increment an integer cursor by 1 (integers only) |
+| `iter.checkpoint!` | Persist cursor and check for interruption |
+| `iter.resumed?` | `true` when continuing from a previous execution |
+| `iter.skip_to!(value, wait: nil)` | Set the cursor and suspend immediately; `wait:` delays the continuation |
 
-## The Asynchronous Execution Model
+Helpers for common iteration shapes:
 
-### Key Assumptions
+```ruby
+# ActiveRecord relation, one record at a time (find_each under the hood)
+iter.iterate_over_records(hero.subscribers) { |subscriber| ... }
 
-GenevaDrive steps execute asynchronously via ActiveJob. This has important implications:
+# ActiveRecord relation in batches, yielding relations for bulk operations
+iter.iterate_over_subrelations(hero.subscribers, batch_size: 500) do |batch|
+  batch.update_all(notified_at: Time.current)
+end
 
-- **Every step runs on a different machine/process/thread.** Don't assume anything about the execution environment between steps.
-- **Instance variables don't persist between steps.** Each step gets a freshly-loaded workflow instance.
-- **The workflow is always loaded fresh from the database.** Any changes you make to the workflow or hero are persisted and reloaded.
-- **Steps may be separated by seconds or months.** A `wait: 30.days` step means exactly what it says.
+# Stable in-memory arrays, index used as cursor
+iter.iterate_over(items) { |item| ... }
+```
 
-### No Shared State Between Steps
+### Chained Executions
 
-> [!WARNING]
-> Instance variables do not persist between steps. Store data in the database.
+When a resumable step is interrupted, the current step execution **completes** (with outcome `continued`) and a successor execution is created, linked to its predecessor via `continues_from_id` and carrying the cursor forward. There is no special "suspended" state — each execution is a normal record with a clear start and end, so the full history of a long iteration is visible as a chain:
 
 ```ruby
-# WRONG - @data won't exist in next step
-step :fetch do
-  @data = ExternalApi.fetch(hero.external_id)
-end
+workflow.step_executions.where(step_name: "send_notifications").order(:created_at)
+# => chunk 1 (completed/continued), chunk 2 (completed/continued), ..., chunk N (completed/success)
+```
 
-step :process do
-  process(@data)  # @data is nil here!
-end
+A step is interrupted when any of these happen:
 
-# RIGHT - persist to the hero or another record
-step :fetch do
-  hero.update!(external_data: ExternalApi.fetch(hero.external_id))
-end
+- `max_iterations:` is reached (`resumable_step :import, max_iterations: 10_000`)
+- `max_runtime:` is exceeded (`resumable_step :import, max_runtime: 5.minutes`)
+- The job queue signals shutdown (e.g. Sidekiq stopping)
+- The workflow is paused or canceled externally
+- The step calls `skip_to!` or `suspend!` explicitly
 
-step :process do
-  process(hero.external_data)
+```ruby
+# Suspend explicitly, e.g. to respect a rate limit
+resumable_step :sync_api do |iter|
+  page = iter.cursor || 1
+  loop do
+    response = ExternalApi.fetch(page: page)
+    suspend!(wait: response.retry_after) if response.rate_limited?
+    break if response.empty?
+    response.items.each { |item| process(item) }
+    page += 1
+    iter.set!(page)
+  end
 end
 ```
 
-You will almost never have the same `self` between steps. Treat each step as an independent unit that reads from and writes to the database.
+### Flow Control and Errors in Resumable Steps
 
----
+All flow control works inside resumable steps, with cursor-aware semantics:
+
+- `pause!` completes the current execution keeping the cursor; `resume!` continues from it.
+- `reattempt!` continues from the cursor by default; `reattempt!(rewind: true)` clears the cursor and starts the iteration over.
+- `cancel!`, `skip!` and `finished!` behave as in regular steps.
+
+Exception policies (`on_exception:` on the step, class-level `on_exception`, `max_reattempts:`, `terminal_action:`, `report:`) apply exactly as for regular steps. A `:reattempt!` policy continues from the last checkpoint, so a transient failure halfway through a large collection does not redo the completed portion. When an unhandled exception pauses the workflow, `resume!` also retries the failed step from its last checkpoint.
+
+Housekeeping recovery is cursor-aware too: a resumable execution stuck `in_progress` (dead worker) is recovered by continuing from its persisted cursor, not by restarting the iteration.
+
+### Writing Restart-Safe Iterations
+
+The cursor marks the last *checkpointed* position, and one item may be re-processed if execution stops between doing the work and checkpointing. Make each iteration idempotent (e.g. guard with a uniqueness constraint or a state flag on the processed record) rather than assuming exactly-once delivery.
+
+### Testing Resumable Steps
+
+`speedrun_workflow` and `speedrun_current_step` run resumable steps to completion with interruption checks disabled, following the execution chain across explicit suspensions. To exercise partial progress, use `run_iterations`:
+
+```ruby
+test "keeps its place across interruptions" do
+  workflow = CampaignWorkflow.create!(hero: campaign)
+  perform_next_step(workflow)             # :prepare
+
+  run_iterations(workflow, count: 3)      # three iterations, then interrupt
+  assert_cursor(workflow, 3)
+  assert_step_has_successor(workflow, :send_notifications)
+
+  speedrun_workflow(workflow)             # run the rest
+  assert workflow.finished?
+end
+```
 
 ## Exception Handling
 
@@ -657,9 +691,9 @@ step :risky_operation do
 end
 ```
 
-### Configuring Exception Policy
+### Step-Level Exception Policy
 
-You can change how a step handles exceptions using `on_exception`:
+Use `on_exception:` on a step to control what happens when that step raises:
 
 ```ruby
 class ResilientApiWorkflow < GenevaDrive::Workflow
@@ -669,20 +703,66 @@ class ResilientApiWorkflow < GenevaDrive::Workflow
 end
 ```
 
-Available exception handlers:
+Available actions:
 
 - `:pause!` — (default) Pause the workflow for manual review
 - `:cancel!` — Cancel the workflow
-- `:reattempt!` — Retry the step
+- `:reattempt!` — Retry the step (creates a new step execution)
 - `:skip!` — Skip the step and continue to the next
 
+### Class-Level Exception Policy
+
+Declare `on_exception` at the class level to set a default for all steps. Steps without an explicit `on_exception:` override inherit this policy:
+
+```ruby
+class ResilientWorkflow < GenevaDrive::Workflow
+  on_exception :reattempt!, max_reattempts: 5
+
+  step :fetch_data do
+    ExternalApi.fetch(hero)  # Inherits reattempt! policy
+  end
+
+  step :send_email, on_exception: :skip! do
+    Mailer.deliver(hero)  # Step-level overrides class-level
+  end
+end
+```
+
+You can declare multiple class-level policies to handle different exception types:
+
+```ruby
+class OAuthWorkflow < GenevaDrive::Workflow
+  # Specific: only matches OAuth2::Error and its subclasses
+  on_exception OAuth2::Error, action: :reattempt!, wait: 15.seconds
+
+  # Specific: cancel on permanent client errors
+  on_exception Google::Apis::ClientError, action: :cancel!
+
+  # Blanket: everything else gets reattempted
+  on_exception :reattempt!, max_reattempts: 3
+
+  step :sync do
+    GoogleCalendar.sync(hero)
+  end
+end
+```
+
+#### Precedence Rules
+
+When a step raises an exception, GenevaDrive resolves the policy in this order:
+
+1. **Step-level single policy** — if the step has an explicit `on_exception:` with a single policy (symbol, `ExceptionPolicy`, or Proc), use it unconditionally
+2. **Step-level composable array** — if the step has an array of policies, walk them (specific match first, blanket fallback). If no policy in the array matches, continue to step 3
+3. **Class-level specific** — walk class-level policies (most recently defined first); use the first one whose exception class filter matches
+4. **Class-level blanket** — use the most recently defined policy with no exception class filter
+5. **Default** — pause the workflow
+
 ### Limiting Reattempts
 
-When using `on_exception: :reattempt!`, you can limit the number of consecutive reattempts before the workflow pauses. This prevents infinite retry loops when an error is persistent rather than transient.
+When using `:reattempt!`, limit consecutive reattempts with `max_reattempts:`. This prevents infinite retry loops when an error is persistent:
 
 ```ruby
 class ExternalApiWorkflow < GenevaDrive::Workflow
-  # Will pause after 5 consecutive failures
   step :sync_to_crm, on_exception: :reattempt!, max_reattempts: 5 do
     CrmApi.sync(hero)
   end
@@ -691,30 +771,244 @@ end
 
 The `max_reattempts:` option:
 
-- **Defaults to 100** when `on_exception: :reattempt!` is used — a safety net against infinite loops
-- **Set to `nil`** to disable the limit and allow unlimited reattempts
+- **Defaults to 100** when `:reattempt!` is used — a safety net against infinite loops
+- **Set to `nil`** to disable the limit entirely
 - **Only counts consecutive reattempts** — if the step succeeds, the count resets
 - **Does not affect manual `reattempt!` calls** — only automatic exception handling respects this limit
 
-When the limit is exceeded, GenevaDrive logs a warning and pauses the workflow, storing the original exception for debugging:
+When the limit is exceeded, GenevaDrive logs a warning and pauses the workflow by default. Use `terminal_action:` to change this behavior:
 
 ```ruby
-# Unlimited reattempts (explicit opt-out of the safety limit)
-step :polling_step, on_exception: :reattempt!, max_reattempts: nil do
-  check_external_status!
+# Cancel the workflow instead of pausing when reattempts are exhausted
+step :flaky_api, on_exception: :reattempt!, max_reattempts: 10, terminal_action: :cancel! do
+  FlakyService.call(hero)
 end
+```
 
-# Custom limit
-step :flaky_api, on_exception: :reattempt!, max_reattempts: 10 do
-  FlakyService.call(hero)
+`terminal_action:` accepts `:pause!` (default), `:cancel!`, or `:skip!`.
+
+### Reusable Exception Policies
+
+For policies shared across multiple workflows, create an `ExceptionPolicy` object:
+
+```ruby
+# Store in a constant or module for reuse
+TRANSIENT_RETRY = GenevaDrive::ExceptionPolicy.new(
+  :reattempt!,
+  wait: 30.seconds,
+  max_reattempts: 5,
+  terminal_action: :cancel!
+)
+
+class OrderWorkflow < GenevaDrive::Workflow
+  step :charge_card, on_exception: TRANSIENT_RETRY do
+    PaymentGateway.charge(hero)
+  end
+end
+
+class ShippingWorkflow < GenevaDrive::Workflow
+  step :book_courier, on_exception: TRANSIENT_RETRY do
+    CourierApi.book(hero)
+  end
+end
+```
+
+Use the `matching:` keyword to create policies that target specific exception classes. This is especially useful when composing multiple policies into an array (see [Composable Step-Level Policies](#composable-step-level-policies)):
+
+```ruby
+# Targets a specific exception class
+TIMEOUT_RETRY = GenevaDrive::ExceptionPolicy.new(
+  :reattempt!,
+  matching: Net::OpenTimeout,
+  wait: 10.seconds,
+  max_reattempts: 5
+)
+
+# Targets multiple exception classes
+OAUTH_CANCEL = GenevaDrive::ExceptionPolicy.new(
+  :cancel!,
+  matching: [OAuth2::Error, "Faraday::ConnectionFailed"]
+)
+```
+
+`matching:` accepts a class, a string (resolved lazily via `safe_constantize` — the class doesn't need to be loaded at definition time), or an array of either. A policy without `matching:` is a blanket policy that matches any exception.
+
+You can also pass an `ExceptionPolicy` to the class-level `on_exception`. Exception class filters are set on the policy after creation:
+
+```ruby
+class ApiWorkflow < GenevaDrive::Workflow
+  on_exception Timeout::Error, action: :reattempt!, wait: 10.seconds, max_reattempts: 3
+  on_exception :cancel!  # Everything else cancels
+
+  step :call_api do
+    SlowApi.call(hero)
+  end
 end
 ```
 
-This option only makes sense with `on_exception: :reattempt!` — specifying `max_reattempts:` with other exception handlers will raise a `StepConfigurationError`.
+### Composable Step-Level Policies
+
+Sometimes a single action isn't enough — you want transient errors reattempted, fatal errors to cancel, and everything else to skip. Pass an array of `ExceptionPolicy` objects to `on_exception:` to route different exception types to different actions on a single step:
+
+```ruby
+class CalendarSyncWorkflow < GenevaDrive::Workflow
+  step :sync_events, on_exception: [
+    GenevaDrive::ExceptionPolicy.new(:reattempt!, matching: Net::OpenTimeout, wait: 10.seconds, max_reattempts: 5),
+    GenevaDrive::ExceptionPolicy.new(:cancel!,    matching: OAuth2::Error),
+    GenevaDrive::ExceptionPolicy.new(:skip!)  # blanket fallback for anything else
+  ] do
+    GoogleCalendar.sync(hero)
+  end
+
+  step :send_confirmation do
+    CalendarMailer.synced(hero).deliver_later
+  end
+end
+```
+
+Each policy in the array can use the `matching:` keyword to target specific exception classes. When an exception is raised, GenevaDrive walks the array in two passes:
+
+1. **Specific policies** (those with `matching:`) are checked first, in definition order. The first match wins.
+2. **Blanket policy** (the first policy without `matching:`) acts as a catchall fallback.
+3. **Fall through** — if no policy in the array matches, resolution continues at the class level (and ultimately falls back to `:pause!`).
+
+This means you can combine a step-level array with a class-level policy for layered exception handling:
+
+```ruby
+class RobustApiWorkflow < GenevaDrive::Workflow
+  on_exception :pause!  # class-level fallback
+
+  step :call_api, on_exception: [
+    GenevaDrive::ExceptionPolicy.new(:reattempt!, matching: Timeout::Error, max_reattempts: 3)
+    # No blanket fallback — unmatched exceptions fall through to class-level :pause!
+  ] do
+    SlowApi.call(hero)
+  end
+end
+```
+
+#### Global Reattempt Cap
+
+When multiple policies in the array have `max_reattempts:`, GenevaDrive enforces the *minimum* across all of them as a global cap on consecutive reattempts. This prevents runaway retries when different exception types alternate:
+
+```ruby
+step :sync, on_exception: [
+  GenevaDrive::ExceptionPolicy.new(:reattempt!, matching: Timeout::Error, max_reattempts: 10),
+  GenevaDrive::ExceptionPolicy.new(:reattempt!, matching: RateLimitError, max_reattempts: 3, terminal_action: :cancel!)
+] do
+  ExternalApi.sync(hero)
+end
+```
+
+Here the global cap is 3. Even if every failure is a `Timeout::Error` (whose individual policy allows 10), the step stops reattempting after 3 consecutive failures. When the cap is hit, the `terminal_action` of the *matched* policy applies — so if the 4th failure is a `Timeout::Error`, the workflow pauses (the default), but if it's a `RateLimitError`, the workflow cancels.
+
+> [!TIP]
+> Store reusable policy arrays as frozen constants so you can share them across workflows:
+>
+> ```ruby
+> module ExceptionPolicies
+>   EXTERNAL_API = [
+>     GenevaDrive::ExceptionPolicy.new(:reattempt!, matching: Net::OpenTimeout, max_reattempts: 5),
+>     GenevaDrive::ExceptionPolicy.new(:cancel!, matching: OAuth2::Error),
+>     GenevaDrive::ExceptionPolicy.new(:pause!)  # blanket fallback
+>   ].freeze
+> end
+>
+> class SyncWorkflow < GenevaDrive::Workflow
+>   step :sync, on_exception: ExceptionPolicies::EXTERNAL_API do
+>     ExternalApi.sync(hero)
+>   end
+> end
+> ```
+
+### Imperative Exception Handlers
+
+For full control, pass a block to `on_exception`. The block receives the exception and runs in the workflow context — you must call a flow control method (`reattempt!`, `cancel!`, `pause!`, or `skip!`):
+
+```ruby
+class SmartRetryWorkflow < GenevaDrive::Workflow
+  on_exception RateLimitError do |error|
+    reattempt! wait: error.retry_after.seconds
+  end
+
+  on_exception do |error|
+    if error.message.include?("temporary")
+      reattempt!
+    else
+      cancel!
+    end
+  end
+
+  step :call_api do
+    ExternalApi.call(hero)
+  end
+end
+```
+
+If the block returns without calling a flow control method, the workflow pauses.
+
+Imperative handlers cannot be combined with `max_reattempts:`, `wait:`, or `terminal_action:` — manage that logic inside the block.
+
+### Controlling Error Reporting
+
+When a step raises an exception, GenevaDrive reports it to your error tracker via `Rails.error.report`. This is the right default — you want visibility into failures. But some exceptions are expected and handled: rate limits, transient timeouts, throttling responses. Reporting these on every reattempt floods your error tracker with noise and obscures the errors that actually need attention.
+
+The `report:` option controls when `Rails.error.report` is called. It accepts three values:
+
+- `:always` — (default) Report every exception, regardless of what the policy does with it. This is the safest choice and preserves the behavior you're used to.
+- `:never` — Never report the exception. Use this for errors that are fully expected and handled — rate limits, throttles, circuit breaker trips. The exception still triggers the policy action (reattempt, skip, etc.), but your error tracker stays clean.
+- `:terminal_only` — Suppress reports while the step is being reattempted, but report when reattempts are exhausted and the `terminal_action` fires. This is the sweet spot for transient errors: you don't care about individual retries, but you want to know when the retries give up.
+
+Use `report:` on both class-level `on_exception` and on `ExceptionPolicy` objects:
+
+```ruby
+class CalendarSyncWorkflow < GenevaDrive::Workflow
+  # Rate limits are expected — never report them
+  on_exception Pecorino::Throttle::Throttled, report: :never do |error|
+    reattempt!(wait: error.retry_after.clamp(10, 600).seconds)
+  end
+
+  # Transient timeouts: only report when we give up
+  on_exception Net::OpenTimeout,
+    action: :reattempt!,
+    wait: 10.seconds,
+    max_reattempts: 5,
+    terminal_action: :cancel!,
+    report: :terminal_only
+
+  step :sync_events do
+    GoogleCalendar.sync(hero)
+  end
+end
+```
+
+The same option works on `ExceptionPolicy` objects for reusable policies and composable arrays:
+
+```ruby
+RATE_LIMIT_POLICY = GenevaDrive::ExceptionPolicy.new(
+  :reattempt!,
+  matching: RateLimitError,
+  wait: 30.seconds,
+  max_reattempts: 10,
+  terminal_action: :pause!,
+  report: :terminal_only
+)
+
+step :call_api, on_exception: [
+  RATE_LIMIT_POLICY,
+  GenevaDrive::ExceptionPolicy.new(:reattempt!, matching: Timeout::Error, report: :never, max_reattempts: 3),
+  GenevaDrive::ExceptionPolicy.new(:pause!)  # blanket fallback, reports by default
+] do
+  ExternalApi.call(hero)
+end
+```
+
+> [!IMPORTANT]
+> The `report:` option only controls `Rails.error.report`. The exception is still re-raised after the executor commits its state transitions — your background job framework (Sidekiq, SolidQueue, etc.) will see it. If your error tracker also hooks into the job framework's error handler, you may need to configure that separately.
 
 ### Manual Exception Handling
 
-For granular control, handle exceptions within the step:
+For the most granular control, handle exceptions directly within the step using standard Ruby `rescue`:
 
 ```ruby
 class PaymentWorkflow < GenevaDrive::Workflow
@@ -731,6 +1025,8 @@ class PaymentWorkflow < GenevaDrive::Workflow
 end
 ```
 
+This bypasses the exception policy entirely — the step catches the error before GenevaDrive sees it.
+
 For a complete example showing granular exception handling, see the [Payment Processing Workflow](#payment-processing-workflow) in the appendix.
 
 ### Recovering Paused Workflows
@@ -740,19 +1036,204 @@ Find and resume paused workflows from the console:
 ```ruby
 GenevaDrive::Workflow.paused.each do |workflow|
   puts "#{workflow.class.name} ##{workflow.id}: next step is #{workflow.next_step_name}"
-  puts "  Error: #{workflow.step_executions.failed.last&.error_message}"
+
+  # Check if there's a scheduled execution (externally paused)
+  if (scheduled = workflow.current_execution)
+    overdue = scheduled.scheduled_for < Time.current
+    puts "  Scheduled step: #{scheduled.step_name} (#{overdue ? 'overdue' : 'future'})"
+    puts "  Originally scheduled for: #{scheduled.scheduled_for}"
+  end
+
+  # Check if there's a failed execution (paused due to exception)
+  if (failed = workflow.step_executions.failed.last)
+    puts "  Failed step: #{failed.step_name}"
+    puts "  Error: #{failed.error_message}"
+  end
 end
 
 # Resume a specific workflow
 workflow = GenevaDrive::Workflow.find(id)
-workflow.resume!
+workflow.resume!  # Re-enqueues existing scheduled step or creates new one
+```
+
+## Workflow States
+
+### State Machine Diagram
+
+```mermaid
+stateDiagram-v2
+    [*] --> ready: create
+    ready --> performing: step starts
+    performing --> ready: step completes / reattempt
+    performing --> finished: last step completes / finished!
+    performing --> canceled: cancel!
+    performing --> paused: pause! / exception
+    paused --> ready: resume!
 ```
 
+A workflow begins in `ready` state. When a step starts executing, it transitions to `performing`. Upon step completion, it returns to `ready` (unless it was the last step, in which case it transitions to `finished`).
+
+### Step Execution States
+
+Step executions have their own state machine:
+
+| State | Meaning |
+|-------|---------|
+| `scheduled` | Waiting to run |
+| `in_progress` | Currently executing |
+| `completed` | Finished successfully |
+| `failed` | Exception occurred |
+| `canceled` | Canceled before execution |
+| `skipped` | Skipped via `skip_if` or `skip!` |
+
 ---
 
-## Working with Heroes
+# Part IV — Tips and Recommendations
+
+## Keep Workflows Short-Lived
+
+A GenevaDrive workflow should be a one-off process with a clear beginning and end — not a long-running loop that retries forever. The best workflows are created, execute their steps over hours or days, reach `finished` (or `canceled`), and are eventually cleaned up by the housekeeping job. If you need a recurring process for a hero, create a new workflow on a schedule rather than building an immortal one.
+
+### Why one-off workflows are better
+
+**Code changes between deploys.** A workflow definition is a Ruby class. When you deploy new code, the class may have different steps, different logic, different wait times. A workflow that was created before the deploy still carries its original step pointer — it will execute the steps as they existed when it was defined. If you keep a single workflow alive for months, it accumulates an increasingly stale relationship with your codebase. A fresh workflow always runs the latest code.
+
+**Step executions are append-only history.** Each step attempt creates a `StepExecution` record. This history is the audit trail for what happened and when. A workflow that runs for two weeks and processes three steps has a concise, readable history. A workflow that has been alive for six months and has reattempted the same polling step 4,000 times has an audit trail that is effectively noise. The step execution table becomes a dumping ground rather than a useful record.
+
+**Terminal states tell you what succeeded and what didn't.** GenevaDrive's state machine is designed around the assumption that workflows end. A `finished` workflow is one that completed all its steps successfully. A `canceled` workflow is one that was stopped deliberately. A `paused` workflow is one that needs attention. These states are meaningful precisely because they are final. A workflow that never finishes — because it is designed to loop forever — can never be `finished`, which means you lose the ability to distinguish "working as intended" from "stuck." Your monitoring and alerting becomes guesswork.
+
+### The cron pattern
+
+Instead of building a workflow that loops endlessly, create a cron job that periodically creates a new workflow for each eligible hero:
+
+```ruby
+# app/jobs/create_billing_check_workflows_job.rb
+class CreateBillingCheckWorkflowsJob < ApplicationJob
+  def perform
+    Account.active.find_each do |account|
+      # Only create if no ongoing workflow exists for this hero
+      next if BillingCheckWorkflow.ongoing.exists?(hero: account)
+      BillingCheckWorkflow.create!(hero: account)
+    end
+  end
+end
+```
+
+Schedule this job with your cron adapter:
+
+```ruby
+# With Solid Queue recurring tasks
+billing_check:
+  class: CreateBillingCheckWorkflowsJob
+  schedule: every day at 6am
+
+# With GoodJob cron
+GoodJob::Cron.schedule(
+  cron: "0 6 * * *",
+  class: "CreateBillingCheckWorkflowsJob"
+)
+```
+
+Each invocation creates a fresh workflow that runs the current code, produces a clean execution history, and terminates with a clear outcome.
+
+### Compare the two approaches
+
+**The immortal workflow (don't do this):**
+
+```ruby
+class BillingCheckWorkflow < GenevaDrive::Workflow
+  step :check_billing do
+    if hero.payment_overdue?
+      BillingMailer.overdue(hero).deliver_later
+    end
+    reattempt!(wait: 1.day)  # Loop forever
+  end
+end
+```
+
+This workflow never finishes. You cannot tell from its state whether it is working correctly or stuck. Its step execution history grows without bound. When you deploy new billing logic, existing workflows keep running the old code path. And if you need to change the check interval from daily to hourly, you must somehow update every running workflow instance.
+
+**The one-off workflow (do this instead):**
+
+```ruby
+class BillingCheckWorkflow < GenevaDrive::Workflow
+  step :check_payment_status do
+    skip! unless hero.payment_overdue?
+    hero.update!(last_overdue_notice_at: Time.current)
+  end
+
+  step :send_overdue_notice, skip_if: -> { hero.last_overdue_notice_at.nil? } do
+    BillingMailer.overdue(hero).deliver_later
+  end
+
+  step :schedule_followup, skip_if: -> { hero.last_overdue_notice_at.nil? } do
+    hero.update!(followup_needed: true)
+  end
+end
+```
+
+Each day, the cron job creates a new `BillingCheckWorkflow` for each account. It runs, does its work, finishes. Tomorrow's workflow will use tomorrow's code. The execution history for each workflow is three steps long. You can query `BillingCheckWorkflow.where(hero: account).finished` to see every successful check, and `BillingCheckWorkflow.where(hero: account).paused` to find the ones that hit problems.
+
+### The partial index allows coexistence
+
+You might wonder: if a cron job creates a new workflow every day, won't old workflows collide with new ones?
+
+No. GenevaDrive maintains a partial unique index on `(type, hero_type, hero_id)` that only covers **ongoing** workflows — those not in `finished` or `canceled` state. This means:
+
+- Only one `BillingCheckWorkflow` for a given account can be `ready`, `performing`, or `paused` at any time.
+- Once a workflow reaches `finished` or `canceled`, it drops out of the index entirely.
+- The next cron run can create a fresh workflow for the same hero without conflict.
+
+This is the designed-for pattern. Yesterday's finished workflow and today's active workflow coexist in the database. The unique index prevents accidental duplicates (two active workflows for the same hero), while the housekeeping job eventually cleans up old finished workflows after your configured retention period.
+
+```ruby
+# This works because yesterday's workflow already finished
+account = Account.find(42)
+BillingCheckWorkflow.where(hero: account).finished.count  # => 30 (last month)
+BillingCheckWorkflow.ongoing.where(hero: account).count    # => 1 (today's)
+```
+
+The short-lived workflow pattern works _with_ the library's design rather than against it. Workflows start, do their work, and end. The database tells you exactly which ones succeeded and which ones didn't. New code applies immediately. History stays readable. This is the intended way to use GenevaDrive.
+
+## The Asynchronous Execution Model
+
+### Key Assumptions
+
+GenevaDrive steps execute asynchronously via ActiveJob. This has important implications:
+
+- **Every step runs on a different machine/process/thread.** Don't assume anything about the execution environment between steps.
+- **Instance variables don't persist between steps.** Each step gets a freshly-loaded workflow instance.
+- **The workflow is always loaded fresh from the database.** Any changes you make to the workflow or hero are persisted and reloaded.
+- **Steps may be separated by seconds or months.** A `wait: 30.days` step means exactly what it says.
+
+### No Shared State Between Steps
+
+> [!WARNING]
+> Instance variables do not persist between steps. Store data in the database.
+
+```ruby
+# WRONG - @data won't exist in next step
+step :fetch do
+  @data = ExternalApi.fetch(hero.external_id)
+end
+
+step :process do
+  process(@data)  # @data is nil here!
+end
+
+# RIGHT - persist to the hero or another record
+step :fetch do
+  hero.update!(external_data: ExternalApi.fetch(hero.external_id))
+end
+
+step :process do
+  process(hero.external_data)
+end
+```
+
+You will almost never have the same `self` between steps. Treat each step as an independent unit that reads from and writes to the database.
 
-### Choosing the Right Hero
+## Choosing the Right Hero
 
 Make the hero the specific business object being processed, not the user who owns it. This keeps workflows focused and allows multiple concurrent workflows for the same user.
 
@@ -767,7 +1248,7 @@ InvoiceWorkflow.create!(hero: user, invoice_id: invoice.id)
 
 If you're processing a subscription renewal, the hero is the `Subscription`. If you're processing an order, the hero is the `Order`. The more specific your hero, the easier it is to reason about workflow state.
 
-### Associating Workflows from the Hero
+## Associating Workflows from the Hero
 
 GenevaDrive uses STI (Single Table Inheritance) combined with a polymorphic `hero` association. This means a single hero can have multiple different workflow types associated with it, each representing a distinct process the hero is going through.
 
@@ -819,126 +1300,133 @@ class User < ApplicationRecord
 end
 ```
 
-### Workflows Without Heroes
-
-Some workflows don't operate on a specific record — system maintenance, batch jobs, or scheduled reports:
-
-```ruby
-class SystemMaintenanceWorkflow < GenevaDrive::Workflow
-  may_proceed_without_hero!
-
-  step :cleanup_temp_files do
-    TempFileService.cleanup_older_than(7.days)
-  end
+## When Heroes Disappear
 
-  step :vacuum_database do
-    ActiveRecord::Base.connection.execute("VACUUM ANALYZE")
-  end
+If the hero is deleted while the workflow is running, GenevaDrive cancels the workflow automatically. This is the right default — in practice, the vast majority of workflows make no sense without their hero. If an admin manually deletes a user, the onboarding workflow for that user should not keep sending emails into the void.
 
-  step :notify_ops do
-    OpsMailer.maintenance_complete.deliver_later
-  end
-end
+If a step tries to access a nil hero, it raises, and the workflow pauses. This is also correct — it surfaces the problem to an operator rather than silently continuing with broken assumptions.
 
-# Create without a hero
-SystemMaintenanceWorkflow.create!
-```
+For the extremely rare case where a workflow must continue after the hero has been deleted from the database, the `may_proceed_without_hero!` escape hatch exists. You will almost never need it.
 
-### When Heroes Disappear
+---
 
-If the hero is deleted while the workflow is running, GenevaDrive cancels the workflow. This prevents steps from failing with `RecordNotFound` errors.
+# Part V — Operations
 
-If your workflow needs to continue after the hero is deleted (for example, a GDPR erasure workflow), declare it explicitly:
+## ActiveJob Integration
 
-```ruby
-class DataErasureWorkflow < GenevaDrive::Workflow
-  may_proceed_without_hero!
+### How Steps Are Scheduled
 
-  step :archive_for_compliance do
-    ComplianceArchive.store(hero)
-  end
+When a step completes, GenevaDrive creates a new `StepExecution` record and enqueues a `PerformStepJob`. The job runs after the transaction commits (using `after_all_transactions_commit`), ensuring the step execution record is visible to the job worker.
 
-  step :delete_from_primary do
-    hero.destroy!  # Hero no longer exists after this
-  end
+If a step specifies `wait:`, GenevaDrive passes the delay to ActiveJob's `set(wait_until:)`. This means your queue adapter handles the scheduling — GenevaDrive doesn't implement its own timer.
 
-  step :purge_from_backups do
-    # hero is nil here, but we stored the ID we need
-    BackupService.purge(id: @archived_hero_id)
-  end
-end
-```
+### Recommended Queue Adapters
 
-For an example of a workflow that handles data deletion carefully, see the [Data Retention Workflow](#data-retention-workflow) in the appendix.
+We recommend using a queue adapter that co-commits with your database:
 
----
+- **Solid Queue** — Built for Rails, uses your existing database
+- **GoodJob** — PostgreSQL-based, with excellent admin UI
+- **Gouda** — Another PostgreSQL option with simple semantics
 
-## Installation and Setup
+Co-committing matters because GenevaDrive relies on transactional guarantees. When a step completes and schedules the next step, both the state change and the job enqueue should be atomic. With co-committing adapters, if the transaction rolls back, the job is never enqueued.
 
-### Adding the Gem
+With non-transactional adapters (Sidekiq, Resque), there's a small window where the job is enqueued but the transaction hasn't committed. GenevaDrive handles this gracefully — the job will see the step execution in the wrong state and skip it — but you may see occasional log warnings.
 
-```bash
-bundle add geneva_drive
-bin/rails generate geneva_drive:install
-bin/rails db:migrate
-```
+### Inline Enqueueing for Bulk Operations
 
-The generator creates two migrations: one for workflows and one for step executions.
+When creating many workflows at once, you may want to batch the job inserts for efficiency. Libraries like BulkEnqueue or native adapter bulk methods can significantly reduce database round-trips. However, GenevaDrive's default behavior of deferring job enqueueing to `after_all_transactions_commit` interferes with bulk enqueueing:
 
-### Database Tables
+1. `BulkEnqueue.in_bulk { }` starts, buffer is set
+2. For each workflow:
+   - Workflow and step execution created in transaction
+   - `after_all_transactions_commit` callback is **registered** (not executed)
+   - Transaction commits
+3. Bulk block ends, flushes **empty** buffer, clears buffer
+4. **Now** `after_all_transactions_commit` callbacks fire
+5. Jobs are enqueued individually (buffer already cleared)
 
-GenevaDrive uses a two-table design:
+Use `GenevaDrive.with_inline_enqueue` to temporarily disable deferred enqueueing:
 
-- **`geneva_drive_workflows`** — The workflow records. Each row represents one workflow instance with its current state, hero association, and progress tracking.
-- **`geneva_drive_step_executions`** — The idempotency keys. Each row represents one attempt to execute a step, with timing, outcome, and error information.
+```ruby
+BulkEnqueue.in_bulk do
+  GenevaDrive.with_inline_enqueue do
+    drafts.each do |draft|
+      DeliverBriefWorkflow.create!(hero: draft)
+    end
+  end
+end
+```
 
-This separation keeps the workflows table clean while maintaining a complete audit trail in step executions.
+Inside the block, jobs are enqueued immediately (inline) rather than being deferred to `after_all_transactions_commit`. This allows bulk enqueueing libraries to capture and batch the job inserts.
 
-### UUID Primary Keys
+> [!WARNING]
+> **Only use `with_inline_enqueue` if you have a co-committing, database-backed ActiveJob adapter** (SolidQueue, GoodJob, Gouda) running on the same database as your application. With these adapters, the job INSERT and workflow records are written in the same transaction, guaranteeing atomicity.
+>
+> If you use a non-transactional adapter (Redis-based Sidekiq, Resque, etc.), do **not** use this in production — jobs may be picked up before their associated records are committed, causing "record not found" errors.
 
-If your application uses UUID primary keys, the migrations will detect this and also use UUIDs for the foreign keys and the primary keys of the geneva_drive resources.
+The method is thread-safe and won't affect other concurrent requests.
 
-Note that you don't want to mix integer IDs and UUIDs in the same application.
+### Custom Job Options
 
----
+You can override the Active Job settings used to enqueue a workflow's step jobs at three levels: for the entire workflow class, for an individual step, or for a specific workflow instance. All three accept the same keys that Active Job's `set` method understands: `:queue`, `:priority`, `:wait`, and `:wait_until`. Unknown keys are rejected at configuration time so that typos surface immediately instead of silently falling back to defaults.
 
-## ActiveJob Integration
+```ruby
+class HighPriorityWorkflow < GenevaDrive::Workflow
+  set_step_job_options queue: :critical, priority: 0
 
-### How Steps Are Scheduled
+  step :urgent_action, job_options: {queue: :urgent, priority: -1} do
+    UrgentService.process!(hero)
+  end
+end
+```
 
-When a step completes, GenevaDrive creates a new `StepExecution` record and enqueues a `PerformStepJob`. The job runs after the transaction commits (using `after_all_transactions_commit`), ensuring the step execution record is visible to the job worker.
+Options merge from lowest to highest precedence: **class defaults** (`set_step_job_options`) are overridden by **per-instance options** (`workflow.step_job_options = {...}`), which are in turn overridden by **per-step options** (`step ..., job_options: {...}`). The merged hash is passed straight to `PerformStepJob.set(...)` for every enqueue of that step, including reattempts and resume re-enqueueing.
 
-If a step specifies `wait:`, GenevaDrive passes the delay to ActiveJob's `set(wait_until:)`. This means your queue adapter handles the scheduling — GenevaDrive doesn't implement its own timer.
+Per-instance options are stored in the workflow's `metadata` column, so they survive across step boundaries and are excluded from the dedupe uniqueness check — two workflows for the same hero cannot coexist just because their job options differ.
 
-### Recommended Queue Adapters
+#### When per-step job options matter: protecting in-flight work from a fresh backlog
 
-We recommend using a queue adapter that co-commits with your database:
+Consider a workflow that downloads, processes, and cleans up a large artifact per hero:
 
-- **Solid Queue** — Built for Rails, uses your existing database
-- **GoodJob** — PostgreSQL-based, with excellent admin UI
-- **Gouda** — Another PostgreSQL option with simple semantics
+```ruby
+class RubygemsWorkflow < GenevaDrive::Workflow
+  step :extract do
+    # Download a large tarball to local disk
+  end
 
-Co-committing matters because GenevaDrive relies on transactional guarantees. When a step completes and schedules the next step, both the state change and the job enqueue should be atomic. With co-committing adapters, if the transaction rolls back, the job is never enqueued.
+  step :process do
+    # Do work on the extracted data
+  end
 
-With non-transactional adapters (Sidekiq, Resque), there's a small window where the job is enqueued but the transaction hasn't committed. GenevaDrive handles this gracefully — the job will see the step execution in the wrong state and skip it — but you may see occasional log warnings.
+  step :cleanup do
+    # Delete the on-disk artifact
+  end
+end
+```
 
-### Custom Job Options
+If you enqueue 50,000 of these at once, all 50,000 `:extract` jobs land on the queue at the default priority — ahead of the `:process` and `:cleanup` steps of workflows that have already downloaded something. On queue adapters where lower numbers run first, the workers happily drain `:extract` jobs first, filling the disk with unprocessed artifacts until the volume runs out and everything starts failing.
 
-Override the queue or priority for all steps in a workflow:
+Bumping the later steps to a higher priority (lower number) fixes this:
 
 ```ruby
-class HighPriorityWorkflow < GenevaDrive::Workflow
-  set_step_job_options queue: :critical, priority: 0
+class RubygemsWorkflow < GenevaDrive::Workflow
+  step :extract, job_options: {priority: 10} do
+    # Download a large tarball to local disk
+  end
 
-  step :urgent_action do
-    UrgentService.process!(hero)
+  step :process do  # runs at default priority — ahead of :extract
+    # Do work on the extracted data
+  end
+
+  step :cleanup do  # also runs ahead of :extract
+    # Delete the on-disk artifact
   end
 end
 ```
 
-The options are passed directly to ActiveJob's `set` method.
+Workflows that have already extracted their artifact can now drain through `:process` and `:cleanup` — releasing disk — while new `:extract` jobs wait their turn. The fleet reaches steady state instead of collapsing under its own backlog.
 
----
+The same pattern is useful whenever a later step releases a scarce resource (disk, external quota, a database lock) that earlier steps consume: give the release-work a higher priority than the acquire-work.
 
 ## Housekeeping
 
@@ -957,7 +1445,7 @@ Configure housekeeping thresholds in an initializer:
 # config/initializers/geneva_drive.rb
 GenevaDrive.delete_completed_workflows_after = 30.days
 GenevaDrive.stuck_in_progress_threshold = 1.hour
-GenevaDrive.stuck_scheduled_threshold = 1.hour
+GenevaDrive.stuck_scheduled_threshold = 15.minutes
 GenevaDrive.stuck_recovery_action = :reattempt  # or :cancel
 ```
 
@@ -981,8 +1469,6 @@ GoodJob::Cron.schedule(
 GenevaDrive::HousekeepingJob.perform_later
 ```
 
----
-
 ## Testing
 
 ### Test Helpers
@@ -1046,7 +1532,29 @@ test "skips email if user unsubscribed" do
 end
 ```
 
----
+### Transactional Tests and SQLite
+
+GenevaDrive defers job enqueueing to `after_all_transactions_commit` so that step execution records are visible to the job worker before it runs. This can cause problems with transactional tests on SQLite — the `after_all_transactions_commit` callback writes to the database after the inner transaction commits, but with SQLite's single-writer limitation this can conflict with the test transaction wrapper or other connections. Symptoms include `SQLite3` errors in workflow tests while the rest of the test suite works fine.
+
+By default, GenevaDrive detects `Rails.env.test?` and skips the deferral, enqueueing jobs immediately. This means transactional tests work out of the box with no extra setup.
+
+If you need strict after-commit semantics in a specific test (for example, to verify the exact commit-then-enqueue ordering), you can re-enable deferral:
+
+```ruby
+test "job is enqueued only after commit" do
+  GenevaDrive.enqueue_after_commit = true
+
+  # ... test that relies on real after_commit timing ...
+ensure
+  GenevaDrive.enqueue_after_commit = false
+end
+```
+
+If you are not using transactional tests at all (for example, you use DatabaseCleaner with truncation), you can set this globally in your initializer:
+
+```ruby
+GenevaDrive.enqueue_after_commit = true
+```
 
 ## Observability
 
@@ -1087,13 +1595,199 @@ ActiveSupport::Notifications.subscribe("step.geneva_drive") do |event|
 end
 ```
 
+### Metric gauges
+
+`GenevaDrive::HousekeepingJob` reports gauges via [Measurometer](https://rubygems.org/gems/measurometer) on every run:
+
+| Gauge | Tags | Value |
+|-------|------|-------|
+| `geneva_drive.<state>` | _(none)_ | Absolute count of workflows in `<state>` (e.g. `ready`, `paused`, `finished`), summed across all classes |
+| `geneva_drive.<state>` | `workflow: <ClassName>` | Absolute count of workflows in `<state>` for a single workflow class |
+| `geneva_drive.paused_ratio` | `workflow: <ClassName>` | Float `0.0..1.0` — that class's `paused` count divided by its total population (all states) |
+
+`paused_ratio` is normalized on purpose: absolute paused counts are hard to alert on (50 paused of 50 is a fire; 50 of 500,000 is noise), whereas the ratio is bounded and comparable across classes. The denominator is the whole population (paused ÷ total), so it stays within `0..1` even when nothing is ongoing.
+
 ---
 
-## Appendix
+# Part VI — Appendix
+
+## Appendix: Why "Durable Functions" Are a Mirage
+
+There is a rather popular approach to building durable execution systems based on the concept of "durable functions". Systems like [Temporal](https://temporal.io) and [absurd](https://lucumr.pocoo.org/2025/11/3/absurd-workflows/) as well as [Vercel Workflows](https://vercel.com/docs/workflow) take that concept quite far. It seems neat on the surface, yet deeply flawed in nature.
+
+The assumption made with those "durable functions" is that it is possible to _pretend that you have a marshalable stack._ For example, this section in a workflow function:
+
+```js
+let step = 0;
+while (step++ < 20) {
+  const { newMessages, finishReason } = await ctx.step("iteration", async () => {
+    return await singleStep(messages);
+  });
+  messages.push(...newMessages);
+  if (finishReason !== "tool-calls") {
+    break;
+  }
+}
+```
+
+can only work if `step` gets marshaled and reinstated if the function gets resumed. Async generators (and Fibers in Ruby, and - in general - any systems based on continuations or coroutines) allow suspension and resumption, but none allow proper _serialization and revival._ If you try to encode a durable function, consisting of multiple steps, as a suspendable and resumable workflow, you essentially have 3 ways to do it:
+
+* Make your function restartable from the very beginning (idempotent)
+* Use a serializable system stack frame, which - usually - comes down to serializing a VM image upon suspension
+* Make the user write functions that only - and ever - use special facilities for accessing transients (current time, database connections, heavy resources)
+
+Most "workflow engines" do their utmost to maintain the guise of resumable functions _while not providing them._ The fact that you have to wait on a Fiber to receive an HTTP result is not very useful if the only program that can receive that result is the very process which has started that HTTP request.
+
+### Why no modern runtime provides stack serialization
+
+The fundamental issue is that no mainstream runtime — V8, SpiderMonkey, YARV, the JVM, the CLR — provides the ability to serialize an executing call stack to bytes and revive it later. This is not an oversight. It is a deliberate engineering decision driven by hard constraints.
+
+A call stack contains pointers: return addresses, references to heap objects, handles to file descriptors and sockets, pointers into native libraries. Serializing a pointer is meaningless — the memory address 0x7fff5fbff8c0 on one machine means nothing on another, or even on the same machine after a restart. To serialize a stack, you must either:
+
+1. **Replace all pointers with symbolic references** that can be resolved at revival time. This requires a complete indirection layer over every memory access — a performance catastrophe for general-purpose code.
+2. **Serialize the entire heap along with the stack**, effectively snapshotting the whole process. This is what Smalltalk images did.
+3. **Restrict the language** so that stacks never contain non-serializable values. This means no closures over native resources, no FFI, no direct system calls.
+
+Modern runtimes chose speed over serializability. JavaScript engines like V8 perform aggressive JIT compilation that inlines functions, eliminates stack frames, and stores values in machine registers. The "stack" you think exists in your `async` function is a fiction maintained for debugging — the actual execution state is scattered across registers, hidden classes, inline caches, and optimized machine code that has no stable representation.
+
+### Systems that actually solved this
+
+True stack serialization is not impossible. It has been done — just not in environments optimized for raw speed.
+
+**Smalltalk images** are the canonical example. A Smalltalk system serializes its entire object memory, including all activation records (stack frames), to a single file. You can save an image mid-computation, quit, restart days later, and continue exactly where you left off. This works because Smalltalk controls everything: the object format, the bytecode interpreter, the garbage collector. There are no opaque pointers to external resources — or if there are, the image-saving mechanism explicitly handles them.
+
+**Erlang/OTP** takes a different approach: processes are so lightweight and isolated that you simply design for crash recovery. A process dies, its supervisor restarts it, and it reconstructs its state from durable storage. There's no pretense that you can freeze and thaw a running computation — you design for restart from the beginning.
+
+**Scheme continuations** (particularly in implementations like Chez Scheme or Gambit) can capture delimited continuations and, in some implementations, serialize them. But these implementations pay the cost: they maintain a CPS-transformed representation that is inherently slower than direct-style execution.
+
+**[Seaside](https://seaside.st/)** deserves special mention. This Smalltalk web framework, developed in the early 2000s, used continuations to model web application control flow. You could write a multi-page wizard as a single method with `call:` and `answer:` — the framework would suspend execution while waiting for user input and resume it when the response arrived. [Wee](https://github.com/mneumann/wee), a Ruby port inspired by Seaside's ideas, attempted the same trick using Ruby's `callcc`. Both frameworks demonstrated genuine continuation-based web development. But they also demonstrated its limits: Seaside required either keeping all session continuations in memory (scaling poorly) or relying on Smalltalk's image persistence (requiring the same VM instance to handle subsequent requests). Wee suffered from Ruby 1.8's notorious continuation memory leaks and remained a curiosity rather than a production tool.
+
+The fundamental problem with continuation-based web frameworks is process affinity. A suspended continuation exists in the memory of a specific process on a specific machine. When the user submits the next form, that exact process must handle the request — no load balancer can route it elsewhere, no autoscaler can spin up a fresh instance to handle the load, no deployment can replace the running code. This is incompatible with modern elastic infrastructure. Kubernetes doesn't care that your user's shopping cart continuation lives in pod `web-7f8d9c-xk2p4` — when traffic spikes, it will route requests wherever capacity exists. When you deploy, it will terminate old pods and start new ones. Your continuations die with them.
+
+### The problem of transient resources
+
+Even if you could serialize a continuation, you would face the problem of transient resources. A continuation captures the call stack, but the call stack contains references to objects that cannot meaningfully survive process boundaries.
+
+Consider a database transaction. Your step opens a connection, begins a transaction, inserts a row, and then — mid-transaction — suspends to wait for user confirmation:
+
+```ruby
+step :reserve_inventory do
+  ActiveRecord::Base.transaction do
+    hero.line_items.each { |item| Inventory.decrement!(item.sku, item.quantity) }
+    # Suspend here, wait for payment confirmation...
+    yield  # In a hypothetical continuation-based system
+    hero.update!(reserved_at: Time.current)
+  end
+end
+```
+
+What happens when you try to revive this continuation on a different machine, or even the same machine after a restart? The `ActiveRecord::Base.connection` object holds a socket to a PostgreSQL server. That socket is gone. You could theoretically reconnect — some systems use lazy connection resolution for exactly this reason — but reconnecting gives you a *new* connection. The transaction you started? It was rolled back the moment the original connection died. The `BEGIN` you issued exists only in the logs. The row locks you held have been released. Some other process may have already modified the rows you thought you had locked.
+
+There is no way to "re-enter" a transaction. Transactions are not addressable resources you can resume — they are ephemeral states of a connection that exist only as long as that connection lives. The same applies to file handles, HTTP connections mid-request, mutex locks, and any other resource that represents a relationship with an external system. A serialized continuation that references such resources is not a suspended computation — it is a lie about the state of the world.
+
+The lesson from these systems is clear: serializable execution state requires either total control over the runtime environment or acceptance of significant performance overhead. You cannot bolt it onto V8 or Ruby's YARV after the fact.
+
+### Why modern developers won't build this
+
+Building a marshalable stack VM is a multi-year, multi-million-dollar undertaking. It requires:
+
+- Deep expertise in compiler construction, garbage collection, and runtime systems
+- Willingness to sacrifice raw performance for serializability
+- Long-term maintenance commitment as the underlying platform evolves
+
+The JavaScript ecosystem optimizes for different goals: startup time, peak throughput, memory efficiency on mobile devices. Google, Mozilla, and Apple compete on V8, SpiderMonkey, and JavaScriptCore benchmarks. No one is competing on "ability to serialize a running function to disk."
+
+The developers building "durable function" frameworks are, by and large, application developers — skilled in their domain, but not runtime engineers. They are building atop V8, not replacing it. They cannot make V8 serialize its internal state because V8 was never designed to expose that state. The best they can do is replay: run the function again from the start, skip the steps that already completed, and hope the interleaving of side effects is deterministic. This is not serialization. It is simulation.
+
+### Pretending is denial
+
+When a framework claims to offer "durable functions" without true stack serialization, it is engaging in denial — not about the laws of physics, but about the semantics of their own system.
+
+Consider what happens when a "durable function" resumes. The framework:
+
+1. Loads the function definition
+2. Starts executing from the beginning
+3. Intercepts calls to "step" functions and returns cached results instead of re-executing
+
+This only works if the control flow between steps is perfectly deterministic. But JavaScript (and Ruby, and Python) are not deterministic languages. The order of object keys, the behavior of `Math.random()`, the resolution of race conditions in `Promise.all()` — all of these can vary between runs. If your loop counter depends on a hash iteration order that changed between Node versions, your "resumed" function takes a different path than the original.
+
+The frameworks paper over this with restrictions: don't use randomness, don't depend on time, don't read from external systems except through blessed APIs. But these restrictions are invisible until you violate them. You write what looks like normal code, you test it, it works — and then six months later, after a Node upgrade, a resumed workflow takes a wrong turn and corrupts your data.
+
+Honesty requires admitting what the system actually provides. If execution state is not truly serialized, don't pretend it is. Make the boundaries explicit. Make the steps explicit. Make the user acknowledge, at every step boundary, that they are persisting state to a database. GenevaDrive takes this position.
+
+## Appendix: Pause as an Operational Safety Valve
+
+When a step raises an unhandled exception, the default behavior is to **pause** the workflow. This is not a coincidence — it is the most operationally useful thing we can do. A paused workflow is not broken. It is stopped, intact, waiting for a human to decide what happens next.
+
+### Why pause instead of letting the exception propagate, retry, or cancel?
+
+Consider the alternatives:
+
+- **Let the exception propagate.** The step execution job raises, and the workflow stays in `performing` state. This is bad — a `performing` workflow cannot have a new step execution started, so there is no way to advance it once the bug is fixed or the upstream problem is resolved. The workflow appears to hang indefinitely.
+- **Infinite retry** can hammer a broken external service, burn API quota, or loop on a bug that no amount of retrying will fix.
+- **Cancel** throws away all the work the workflow has already done. If five of seven steps completed successfully, canceling means starting over — or worse, leaving the system in a half-finished state with no record of what happened.
+
+Pausing avoids all of these. The workflow stops advancing, but every piece of state is preserved: which step failed, what exception was raised, the full backtrace, and which step would run next. An operator can inspect the situation, fix the underlying problem (deploy a bug fix, correct bad data, restore an external service), and then decide how to proceed.
+
+### The slot stays occupied
+
+A paused workflow is still **ongoing**. It keeps its slot in the unique index on `(type, hero_type, hero_id)`. This means no competing workflow can be created for the same hero while the paused one exists. If a cron job or a controller action tries to create a duplicate, the unique constraint rejects it.
+
+This is a feature, not a limitation. Imagine a payment processing workflow pauses because the gateway returned an unexpected error. You do not want a second payment workflow starting for the same order while the first one is stopped mid-flight — that risks double-charging. The paused workflow holds the slot, acting as a lock that says "a human needs to look at this before anything else happens for this hero."
+
+### Unpausing a workflow
+
+You have three options when a workflow is paused:
+
+**`resume!`** sets the workflow back to `ready` and re-enqueues the step that was about to run. If the step was originally scheduled for some time in the future and that time has now passed, it runs immediately — the system recognizes it is overdue. If the scheduled time is still in the future, it waits the remaining duration. This is the most common recovery path: fix the root cause, then resume.
+
+```ruby
+workflow = PaymentProcessingWorkflow.find(id)
+workflow.resume!  # Re-enqueues the failed step
+```
+
+**`skip!`** marks the current step as skipped and advances to the next one. This is useful when the step is no longer relevant — perhaps you resolved the issue out-of-band, or the step was attempting something that has since been handled manually.
+
+```ruby
+workflow = PaymentProcessingWorkflow.find(id)
+workflow.skip!  # Advances past the failed step
+```
 
-### Complete Example Workflows
+**`cancel!`** terminates the workflow entirely. The slot in the unique index is released, and a new workflow for the same hero can be created.
 
-#### User Onboarding Workflow
+```ruby
+workflow = PaymentProcessingWorkflow.find(id)
+workflow.cancel!  # Ends the workflow, frees the hero slot
+```
+
+### Deliberate pause from step code
+
+Steps can also call `pause!` explicitly to request human intervention before the workflow continues. This is the "emergency stop button" — the step has detected a condition that requires a conscious decision rather than automatic progression.
+
+The payment processing example in this manual demonstrates this pattern. When the gateway flags a transaction as potentially fraudulent, the step pauses the workflow rather than proceeding:
+
+```ruby
+step :capture_payment, wait: 1.hour do
+  result = PaymentGateway.capture(
+    authorization_id: hero.authorization_id,
+    idempotency_key: "capture-#{hero.id}"
+  )
+  hero.update!(captured_at: Time.current, transaction_id: result.transaction_id)
+rescue PaymentGateway::FraudSuspected
+  hero.flag_for_fraud_review!
+  pause!  # A human must review before we continue
+end
+```
+
+The workflow will sit in `paused` state — holding the slot, preventing duplicates — until a fraud analyst reviews the case and calls `resume!` or `cancel!`.
+
+### Pause on missing step definitions
+
+There is one more scenario where pause happens automatically. If a workflow references a step name that no longer exists in the class definition — typically after a deploy that removed or renamed a step — the executor pauses the workflow rather than silently skipping or crashing. This gives operators a chance to notice the mismatch and decide whether to skip, cancel, or deploy a fix.
+
+## Complete Example Workflows
+
+### User Onboarding Workflow
 
 This workflow demonstrates named steps with wait times, skip conditions, and blanket cancellation. It guides a new user through account setup with timed reminders.
 
@@ -1140,7 +1834,7 @@ class UserOnboardingWorkflow < GenevaDrive::Workflow
 end
 ```
 
-#### Payment Processing Workflow
+### Payment Processing Workflow
 
 This workflow demonstrates manual exception handling, dynamic retry waits, and early termination. It handles the complexity of interacting with an external payment gateway.
 
@@ -1211,25 +1905,19 @@ class PaymentProcessingWorkflow < GenevaDrive::Workflow
 end
 ```
 
-#### Data Retention Workflow
+### User Erasure Workflow
 
-This workflow demonstrates handling hero deletion mid-workflow. It processes GDPR-style data erasure requests while maintaining compliance records.
-
-```ruby
-class DataRetentionWorkflow < GenevaDrive::Workflow
-  may_proceed_without_hero!
+This workflow processes a GDPR-style data erasure request. Every step requires the hero to exist — if an admin or another process deletes the user externally before the workflow finishes, the next step will raise on `hero` access, pausing the workflow for an operator to investigate. This is the correct behavior: silent continuation with a missing user would be worse than stopping.
 
-  step :create_compliance_record do
-    ComplianceRecord.create!(
-      user_id: hero.id,
-      user_email: hero.email,
-      request_type: "erasure",
-      requested_at: Time.current,
-      workflow_id: id
-    )
-  end
+The final step destroys the hero. Because it is the last step, the workflow transitions to `finished` and there are no subsequent steps that need the hero.
 
+```ruby
+class UserErasureWorkflow < GenevaDrive::Workflow
   step :export_to_archive do
+    # Every step accesses hero directly — no nil guards.
+    # If hero was deleted externally, this raises and the
+    # workflow pauses. An operator can then investigate why
+    # the user vanished before erasure completed.
     archive_data = UserDataExporter.export(hero)
     ComplianceArchive.store(
       user_id: hero.id,
@@ -1239,56 +1927,45 @@ class DataRetentionWorkflow < GenevaDrive::Workflow
   end
 
   step :notify_third_parties do
-    # Request deletion from integrated services
     hero.oauth_connections.each do |connection|
       ThirdPartyDeletionService.request(connection)
     end
   end
 
   step :delete_user_data, wait: 24.hours do
-    # Give third parties time to process
-    # hero may be nil if already deleted
-    return unless hero
-
+    # Give third parties time to process deletion requests
     hero.posts.destroy_all
     hero.comments.destroy_all
     hero.messages.destroy_all
     hero.files.each { |f| f.purge_later }
   end
 
-  step :delete_user_record do
-    return unless hero
-
-    hero_id = hero.id
-    hero.destroy!
-
-    # Update compliance record
-    ComplianceRecord.find_by(user_id: hero_id, workflow_id: id)
-      &.update!(completed_at: Time.current)
-  end
-
   step :send_confirmation do
-    record = ComplianceRecord.find_by(workflow_id: id)
-    return unless record
+    ErasureMailer.complete(hero.email).deliver_later
+  end
 
-    ComplianceMailer.erasure_complete(record.user_email).deliver_later
+  step :delete_user_record do
+    # Last step — hero is destroyed, workflow finishes.
+    # No subsequent steps need the hero.
+    hero.destroy!
   end
 end
 ```
 
-### Quick Reference
+## Quick Reference
 
-#### Flow Control Methods
+### Flow Control Methods
 
 | Method | Effect |
 |--------|--------|
 | `cancel!` | Stop workflow, mark canceled |
 | `pause!` | Stop workflow, await manual resume |
-| `reattempt!(wait:)` | Retry current step, optionally after delay |
+| `reattempt!(wait:, rewind:)` | Retry current step; `rewind: true` clears cursor |
 | `skip!` | Skip current step, proceed to next |
 | `finished!` | Complete workflow early |
+| `suspend!(wait:)` | Interrupt resumable step, continue via successor after delay |
 
-#### Workflow States
+### Workflow States
 
 | State | Meaning |
 |-------|---------|
@@ -1298,7 +1975,7 @@ end
 | `canceled` | Workflow was canceled |
 | `paused` | Awaiting manual intervention |
 
-#### Step Execution States
+### Step Execution States
 
 | State | Meaning |
 |-------|---------|
@@ -1309,13 +1986,18 @@ end
 | `canceled` | Canceled before execution |
 | `skipped` | Skipped via `skip_if` or `skip!` |
 
-#### Step Options
+A resumable step interrupted mid-iteration completes its execution with outcome `continued` and schedules a successor execution — there is no separate state for it.
+
+### Step Options
 
 | Option | Type | Description |
 |--------|------|-------------|
 | `wait:` | Duration | Delay before step executes |
+| `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!`) |
 | `max_reattempts:` | Integer, nil | Max consecutive reattempts before pausing (default: 100, `nil` = unlimited) |
 | `before_step:` | Symbol | Insert before this step |
 | `after_step:` | Symbol | Insert after this step |
+| `max_iterations:` | Integer | (resumable_step) Interrupt after N iterations, continue via successor |
+| `max_runtime:` | Duration | (resumable_step) Interrupt after duration elapsed, continue via successor |