ruby_reactor 0.5.2 → 0.5.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 66c0a0c5591cd862dc61063d752f4d92111370808256bfdae749825fec68429b
-  data.tar.gz: 212ac4ce7ef87e5d28606cab0aff8358afde437389fbb5b2d717b1b5874daa77
+  metadata.gz: b41cd34a4e2437fdeead7ad0b9ddeebc493f711e0cc7db8a31ab7c61f3e2be8d
+  data.tar.gz: 4179974d1156150a84ca60ef75e04b619dc9a7a2b26fefa5ef7e40beba5c8e14
 SHA512:
-  metadata.gz: 75e3bd7ead2281ef7bd1a74fe42a1aaaa1ff5ac92db2b72172e779b0fa9591878268b9829c939def027a6d368ad0ad7b00eddaa05bbb5497f0678229b68b17c0
-  data.tar.gz: 46c44e73bef1e7f2a11d7a5de51de83a2a9a2505aa8c5b06cf64215bc97c4c272f67f23a220187431a188a6dcca216ee13741566fc61e1ead6a8d7dc7b392d74
+  metadata.gz: bc39fd70ce8a3318dbd41cd49deb4e7ebd66c084e7fb007ff5651d26cf1853c97cf32577ffda863c754328a49518b629aa41f1341398c49e43cd4e5df5070439
+  data.tar.gz: 83eddedaebfe39c7b3dad5b88eeaab15c08e11d78a8c894473ab82044047d8c392a4387674199fbb80d4542cf1698f64ce95b7448b8a8cf421ef7ca703b1cbb6

data/.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "0.5.2"
+  ".": "0.5.4"
 }

data/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## [0.5.4](https://github.com/arturictus/ruby_reactor/compare/v0.5.3...v0.5.4) (2026-06-18)
+
+
+### documentation
+
+* emphasize class-based steps as preferred way  ([#38](https://github.com/arturictus/ruby_reactor/issues/38)) ([0ee6234](https://github.com/arturictus/ruby_reactor/commit/0ee62346fd0c49d97c57cef780a6a7135d4253cd))
+
+## [0.5.3](https://github.com/arturictus/ruby_reactor/compare/v0.5.2...v0.5.3) (2026-06-17)
+
+
+### Features
+
+* Durability & Recovery ([#39](https://github.com/arturictus/ruby_reactor/issues/39)) ([103e583](https://github.com/arturictus/ruby_reactor/commit/103e5835b413eec2302fa63f3e998d487cfd9eaf))
+
 ## [0.5.2](https://github.com/arturictus/ruby_reactor/compare/v0.5.1...v0.5.2) (2026-06-14)
 
 

data/README.md

@@ -36,6 +36,7 @@ The key value is **Reliability**: if any part of your workflow fails, Ruby React
 | Locks / sem / rate / per | Yes          | No              | No          | Manual              |
 | Built-in web dashboard   | Yes          | No              | No          | No                  |
 | Async with Sidekiq       | Yes          | No              | Limited     | Yes                 |
+| Durable crash recovery   | Yes          | No              | No          | Manual              |
 
 ## Real-World Use Cases
 
@@ -44,12 +45,14 @@ The key value is **Reliability**: if any part of your workflow fails, Ruby React
 - **Subscription Billing**: Coordinate Stripe charges, invoice email generation, and internal entitlement updates. Use interrupts to pause the workflow when 3rd-party APIs are required to continue the workflow or when specific customer approval is needed.
 
 ## Table of Contents
+
 - [Features](#features)
 - [Comparison](#comparison)
 - [Real-World Use Cases](#real-world-use-cases)
 - [Installation](#installation)
 - [Configuration](#configuration)
 - [Quick Start](#quick-start)
+- [Defining Steps](#defining-steps)
 - [Web Dashboard](#web-dashboard)
   - [Rails Installation](#rails-installation)
 - [Usage](#usage)
@@ -57,6 +60,7 @@ The key value is **Reliability**: if any part of your workflow fails, Ruby React
   - [Async Execution](#async-execution)
     - [Full Reactor Async](#full-reactor-async)
     - [Step-Level Async](#step-level-async)
+  - [Durability & Recovery](#durability--recovery)
   - [Interrupts (Pause & Resume)](#interrupts-pause--resume)
   - [Locks, Semaphores & Ordered Locks](#locks-semaphores--ordered-locks)
   - [Map & Parallel Execution](#map--parallel-execution)
@@ -90,53 +94,96 @@ Or install it yourself as:
 
 ## Configuration
 
-Configure RubyReactor with your Sidekiq and Redis settings:
+Every setting is **optional** — RubyReactor ships with the defaults shown. Drop
+this into an initializer (e.g. `config/initializers/ruby_reactor.rb`); pasted as-is
+it changes nothing, so it doubles as a reference of every knob.
 
-Every setting below is **optional** — RubyReactor ships with the defaults shown. Override only what you need.
+> **Reading the block:** lines starting with `##` are documentation. Lines starting
+> with a single `#` (a `config.…` call) are real settings commented at their
+> default — uncomment one to enable it.
 
 ```ruby
 RubyReactor.configure do |config|
-  # Storage adapter. Default: :redis (the only adapter shipped today).
-  config.storage.adapter = :redis
-  # Redis URL. Default: "redis://localhost:6379/0".
+  ## === Storage (Redis) ===
+
+  ## Storage adapter. Default: :redis (the only adapter shipped today).
+  # config.storage.adapter = :redis
+
+  ## Redis URL. Default: "redis://localhost:6379/0".
   config.storage.redis_url = ENV.fetch("REDIS_URL", "redis://localhost:6379/0")
-  # Extra options passed to Redis.new. Default: {}.
-  config.storage.redis_options = { timeout: 1 }
-
-  # Sidekiq queue used by RubyReactor's async worker. Default: :default.
-  config.sidekiq_queue = :default
-  # Sidekiq retry count for infrastructure failures only (deserialization,
-  # Redis, network). Step retries are managed separately. Default: 3.
-  config.sidekiq_retry_count = 3
-
-  # Lock/semaphore/rate-limit/ordered-lock contention snooze behavior for
-  # async reactors. When a Sidekiq worker cannot acquire a primitive it
-  # re-enqueues itself with `lock_snooze_base_delay + rand(0..lock_snooze_jitter)`
-  # seconds (rate-limit uses a precise `retry_after_seconds` hint from the error;
-  # ordered-lock waits re-poll at the base delay so a successor catches its
-  # blocker finishing fast), up to `lock_snooze_max_attempts` times before
-  # marking the context :failed. Defaults: 5 / 5 / 20. Set max_attempts to
-  # :infinity to never give up.
-  config.lock_snooze_base_delay = 5
-  config.lock_snooze_jitter = 5
-  config.lock_snooze_max_attempts = 20
-
-  # Named rate limits shared across reactors. Reference them with
-  # `with_rate_limit(:stripe)`. See Locks, Semaphores, Rate Limits & Periods.
-  config.rate_limits.register(:stripe, limits: { second: 3, minute: 100 })
 
-  # Logger. Default: Logger.new($stderr).
-  config.logger = Logger.new($stdout)
+  ## Extra options passed to Redis.new. Default: {}.
+  # config.storage.redis_options = { timeout: 1 }
+
+  ## === Sidekiq ===
+
+  ## Sidekiq queue used by RubyReactor's async worker. Default: :default.
+  # config.sidekiq_queue = :default
+
+  ## Sidekiq retry count for infrastructure failures only (deserialization,
+  ## Redis, network). Step retries are managed separately. Default: 3.
+  # config.sidekiq_retry_count = 3
+
+  ## === Contention snooze (locks / semaphores / rate limits / ordered locks) ===
+
+  ## When a Sidekiq worker cannot acquire a primitive it re-enqueues itself with
+  ## `lock_snooze_base_delay + rand(0..lock_snooze_jitter)` seconds (rate-limit
+  ## uses a precise `retry_after_seconds` hint from the error; ordered-lock waits
+  ## re-poll at the base delay so a successor catches its blocker finishing fast),
+  ## up to `lock_snooze_max_attempts` times before marking the context :failed.
+  ## Set max_attempts to :infinity to never give up.
+  # config.lock_snooze_base_delay = 5
+  # config.lock_snooze_jitter = 5
+  # config.lock_snooze_max_attempts = 20
+
+  ## === Durability & crash recovery (see "Durability & Recovery" below) ===
+
+  ## Retention TTL (seconds) for stored reactor/map state. Must exceed your
+  ## worst-case snooze/retry window; re-stamped on every write. Default: 86_400.
+  # config.context_ttl = 86_400
+
+  ## TTL (seconds) for the per-context liveness lock. A live worker auto-extends
+  ## it; its absence is the sweeper's "worker died" signal. Must exceed the
+  ## longest a single step can run without yielding the GIL. Default: 60.
+  # config.context_lock_ttl = 60
+
+  ## Minimum seconds between per-step checkpoints within one run. 0 = checkpoint
+  ## after every step (strongest guarantee). Raise to coalesce mid-run writes for
+  ## long reactors — only safe when steps are idempotent. Default: 0.
+  # config.checkpoint_min_interval = 0
 
-  # Async router. Default: RubyReactor::SidekiqAdapter. Swap for a custom
-  # adapter if you don't use Sidekiq — the adapter only needs to respond to
-  # `perform_async(serialized_context, reactor_class_name, **)`.
+  ## Recovery sweeper (the chain is kicked once by `RubyReactor.start_sweeper!`).
+  # config.sweeper_enabled = true    # run recovery by default
+  # config.sweeper_interval = 30     # seconds between sweeps = recovery-latency bound
+  # config.sweeper_limit = 1000      # max contexts/maps inspected per sweep
+
+  ## === Misc ===
+
+  ## Logger. Default: Logger.new($stdout).
+  # config.logger = Logger.new($stdout)
+
+  ## Async router. Default: RubyReactor::SidekiqAdapter. Swap for a custom adapter
+  ## if you don't use Sidekiq — it only needs to respond to
+  ## `perform_async(context_id, reactor_class_name, **)`.
   # config.async_router = MyCustomAdapter
+
+  ## === Examples (no default — set these to use the feature) ===
+
+  ## Named rate limits shared across reactors. Reference with `with_rate_limit(:stripe)`.
+  # config.rate_limits.register(:stripe, limits: { second: 3, minute: 100 })
+
+  ## OpenTelemetry / custom middlewares. Default: [].
+  # config.middlewares = [RubyReactor::OpenTelemetry]
 end
 ```
 
 You can also leave out the `configure` block entirely — defaults work for local development against a Redis on `localhost:6379`.
 
+> **Crash recovery needs a kick.** The `sweeper_*` settings above only configure
+> the recovery sweeper — they do not start it. Call `RubyReactor.start_sweeper!`
+> once at boot (ideally from a Sidekiq `on(:startup)` hook) or no crashed reactor
+> will ever resume. See [Durability & Recovery](#durability--recovery).
+
 
 ## Quick Start
 
@@ -152,6 +199,60 @@ result = HelloReactor.run
 puts result.value  # => "Hello from Ruby Reactor!"
 ```
 
+> **Note:** Examples in this README use inline `step` blocks where a step is trivial. For production workflows, prefer [class-based steps](#defining-steps).
+
+## Defining Steps
+
+RubyReactor supports two ways to define step logic:
+
+| Style | Best for |
+|-------|----------|
+| **Class steps** (preferred) | Real business logic, compensation/undo, shared steps, testability |
+| **Inline blocks** | Quick prototypes, trivial one-liners, documentation examples |
+
+Whichever style you use, a step's `run` returns one of three signals — all exposed as bare helpers in both class steps and inline blocks:
+
+- **`Success(value)`** — step succeeded; `value` flows to dependent steps.
+- **`Failure(error)`** — step failed; the reactor rolls back completed steps (compensate/undo).
+- **`Skipped(reason:)`** — clean halt: stop the reactor, keep partial progress, **no rollback**. See [Skipping a reactor cleanly](documentation/core_concepts.md#skipping-a-reactor-cleanly).
+
+**Class steps** are plain Ruby classes that include `RubyReactor::Step` and implement `run`, and optionally `compensate` and `undo`:
+
+```ruby
+class ReserveInventoryStep
+  include RubyReactor::Step
+
+  def self.run(arguments, context)
+    reservation_id = InventoryService.reserve(arguments[:order][:items])
+    Success(reservation_id: reservation_id)
+  end
+
+  def self.compensate(error, arguments, context)
+    InventoryService.release_partial(arguments[:order][:items])
+    Success()
+  end
+
+  def self.undo(result, arguments, context)
+    InventoryService.release(result[:reservation_id])
+    Success()
+  end
+end
+
+class OrderProcessingReactor < RubyReactor::Reactor
+  step :reserve_inventory, ReserveInventoryStep do
+    argument :order, result(:validate_order)
+  end
+end
+```
+
+**Why prefer class steps?**
+
+- **Testability** — unit-test `run`, `compensate`, and `undo` in isolation without booting the whole reactor
+- **Composability** — share the same step class across multiple reactors and compose larger workflows from small, focused units
+- **Readability** — reactor files stay orchestration-only; business logic lives in named classes instead of growing inline blocks
+
+See [Core Concepts — Step Classes](documentation/core_concepts.md#step-classes-preferred) for the full reference. Usage examples below mix class and inline steps — inline where the logic is trivial.
+
 ## Web Dashboard
 
 RubyReactor ships with a built-in web dashboard to inspect reactor executions, view logs, and retry failed steps. The dashboard is a Rack app (a [Roda](https://roda.jeremyevans.net/) application) bundled inside the gem with its pre-compiled JS/CSS assets — no extra install or asset build step is required.
@@ -191,60 +292,59 @@ You can secure the dashboard using standard Rails authentication methods (e.g.,
 
 ## Usage
 
-RubyReactor allows you to define complex workflows as "reactors" with steps that can depend on each other, handle failures with compensations, and validate inputs.
+RubyReactor allows you to define complex workflows as "reactors" with steps that can depend on each other, handle failures with compensations, and validate inputs. Examples in this section mix class steps with inline blocks; see [Defining Steps](#defining-steps) for guidance.
 
 ### Basic Example: User Registration
 
 ```ruby
 require 'ruby_reactor'
 
+class ValidateEmailStep
+  include RubyReactor::Step
+
+  def self.run(arguments, _context)
+    email = arguments[:email]
+    email&.include?('@') ? Success(email.strip) : Failure("Email must contain @")
+  end
+end
+
+class CreateUserStep
+  include RubyReactor::Step
+
+  def self.run(arguments, _context)
+    Success(
+      id: rand(10000),
+      email: arguments[:email],
+      password_hash: arguments[:password_hash],
+      created_at: Time.now
+    )
+  end
+
+  def self.compensate(_error, arguments, _context)
+    Notify.to(arguments[:email])
+    Success()
+  end
+end
+
 class UserRegistrationReactor < RubyReactor::Reactor
-  # Define inputs with optional validation
   input :email
   input :password
 
-  # Define steps with their dependencies
-  step :validate_email do
+  step :validate_email, ValidateEmailStep do
     argument :email, input(:email)
-
-    run do |args, context|
-      if args[:email] && args[:email].include?('@')
-        Success(args[:email].strip)
-      else
-        Failure("Email must contain @")
-      end
-    end
   end
 
   step :hash_password do
     argument :password, input(:password)
-
-    run do |args, context|
+    run do |args, _context|
       require 'digest'
-      hashed = Digest::SHA256.hexdigest(args[:password])
-      Success(hashed)
+      Success(Digest::SHA256.hexdigest(args[:password]))
     end
   end
 
-  step :create_user do
-    # Arguments can reference results from other steps
+  step :create_user, CreateUserStep do
     argument :email, result(:validate_email)
     argument :password_hash, result(:hash_password)
-
-    run do |args, context|
-      user = {
-        id: rand(10000),
-        email: args[:email],
-        password_hash: args[:password_hash],
-        created_at: Time.now
-      }
-      Success(user)
-    end
-
-    compensate do |error, args, context|
-      Notify.to(args[:email])
-      Success()
-    end
   end
 
   step :notify_user do
@@ -256,12 +356,12 @@ class UserRegistrationReactor < RubyReactor::Reactor
       Success()
     end
 
-    compensate do |error, args, context|
+    compensate do |_error, args, _context|
       Email.send("support@acme.com", "Email verification for #{args[:email]} couldn't be sent")
       Success()
     end
   end
-  # Specify which step's result to return
+
   returns :create_user
 end
 
@@ -341,6 +441,73 @@ def create(params)
 end
 ```
 
+### Durability & Recovery
+
+Async reactors are durable: state lives in Redis, not in the job payload. Before
+any background job is enqueued the root context is persisted, and after every
+completed step a checkpoint advances the stored blob — so a crash re-runs at most
+one step, never the whole reactor. Each running reactor also holds a short
+**liveness lock** that a live worker auto-extends; its absence is how a dead
+worker is detected.
+
+**Recovery is not automatic until you start the sweeper.** A crashed worker's
+reactor only resumes when the recovery sweeper notices the lapsed liveness lock
+and re-enqueues it. The sweeper is a self-rescheduling chain — **kick it once per
+process boot:**
+
+The recommended spot is a Sidekiq server startup hook, so only the worker
+process runs recovery (not your web/console/client processes):
+
+```ruby
+# config/initializers/sidekiq.rb
+Sidekiq.configure_server do |config|
+  config.on(:startup) { RubyReactor.start_sweeper! }
+end
+```
+
+Anywhere that runs once at boot works too — e.g. a Rails initializer:
+
+```ruby
+# config/initializers/ruby_reactor.rb
+RubyReactor.start_sweeper!
+```
+
+That's all that's required: `start_sweeper!` is idempotent (safe to call on every
+boot — duplicate kicks collapse to one chain), runs both the top-level reactor
+sweeper and the map sweeper every `config.sweeper_interval` seconds, and stops if
+you set `config.sweeper_enabled = false`. The interval is your recovery-latency
+bound.
+
+> **Sidekiq Enterprise `super_fetch` compatibility:** the chain is safe under
+> reliable fetch. `super_fetch` re-runs a job whose worker died mid-execution, so
+> a tick that crashes *after* enqueuing its successor but *before* acking would,
+> with naive single-flight, be recovered alongside that successor and fork the
+> chain (doubling every interval). RubyReactor avoids this: it never relies on
+> "one job in the chain" — each next tick is claimed by a per-time-window lock, so
+> a `super_fetch`-recovered tick computes the same window, loses the claim, and
+> collapses back to a single successor. The startup hook above is likewise
+> idempotent across multiple `super_fetch` server processes.
+
+**Prefer your own scheduler?** Set `config.sweeper_enabled = false` (which makes
+`start_sweeper!` a no-op) and drive recovery from cron, a Kubernetes `CronJob`,
+`sidekiq-cron`, `sidekiq-scheduler`, or Rails recurring tasks. Each tick is one
+call:
+
+```ruby
+RubyReactor.sweep_once # => { reactors: <n re-enqueued>, maps: <n recovered> }
+```
+
+For example, a rake task a system cron / CronJob can invoke:
+
+```ruby
+# lib/tasks/ruby_reactor.rake
+namespace :ruby_reactor do
+  task sweep: :environment do
+    RubyReactor.sweep_once
+  end
+end
+```
+
 ### Interrupts (Pause & Resume)
 
 Pause execution to wait for external events like webhooks or user approvals.
@@ -500,14 +667,14 @@ result.success?  # true (Skipped is a Success subclass)
 result.skipped?  # true on dedup hit, false otherwise
 ```
 
-A step's `run` block can also return `RubyReactor.Skipped(reason: "...")` to halt the reactor cleanly — remaining steps don't execute, **and already-completed steps are NOT compensated**. Use it when the rest of the workflow is unnecessary and partial progress should be kept (`Failure` is for "stop and roll back").
+A step's `run` block can also return `Skipped(reason: "...")` to halt the reactor cleanly — remaining steps don't execute, **and already-completed steps are NOT compensated**. Use it when the rest of the workflow is unnecessary and partial progress should be kept (`Failure` is for "stop and roll back"). `Skipped` is a bare helper just like `Success`/`Failure` (or use the fully-qualified `RubyReactor.Skipped(...)`).
 
 ```ruby
 step :ensure_active do
   argument :user, result(:fetch_user)
-  run do |args|
-    next RubyReactor.Skipped(reason: "user_opted_out") if args[:user].opted_out?
-    RubyReactor.Success(args[:user])
+  run do |args, _ctx|
+    next Skipped(reason: "user_opted_out") if args[:user].opted_out?
+    Success(args[:user])
   end
 end
 ```
@@ -976,7 +1143,7 @@ end
 
 ### Testing
 
-RubyReactor provides testing utilities for RSpec. See the [Testing with RSpec](documentation/testing.md) guide for comprehensive documentation.
+RubyReactor provides testing utilities for RSpec. See the [Testing with RSpec](documentation/testing.md) guide for comprehensive documentation — including [unit-testing class-based steps](documentation/testing.md#testing-step-classes) directly.
 
 ```ruby
 RSpec.describe PaymentReactor do
@@ -1003,7 +1170,7 @@ end
 For detailed documentation, see the following guides:
 
 ### [Core Concepts](documentation/core_concepts.md)
-Learn about the fundamental building blocks of RubyReactor: Reactors, Steps, Context, and Results. Understand how steps are defined, how data flows between them, and how the context maintains state throughout execution.
+Learn about the fundamental building blocks of RubyReactor: Reactors, Steps, Context, and Results. Covers class-based steps (the preferred approach) and inline blocks, how data flows between steps, and how the context maintains state throughout execution.
 
 ### [DAG (Directed Acyclic Graph)](documentation/DAG.md)
 Deep dive into how RubyReactor manages dependencies. This guide explains how the Directed Acyclic Graph is constructed to ensure steps execute in the correct topological order, enabling automatic parallelization of independent steps.

data/lib/ruby_reactor/configuration.rb

@@ -9,12 +9,76 @@ module RubyReactor
 
     attr_writer :sidekiq_queue, :sidekiq_retry_count, :logger, :async_router,
                 :lock_snooze_base_delay, :lock_snooze_jitter, :lock_snooze_max_attempts,
-                :middlewares
+                :middlewares, :context_ttl, :context_lock_ttl, :checkpoint_min_interval,
+                :sweeper_enabled, :sweeper_interval, :sweeper_limit
 
     def sidekiq_queue
       @sidekiq_queue ||= :default
     end
 
+    # Retention TTL (seconds) for a stored reactor context. Storage is
+    # load-bearing for resume, so this must comfortably exceed the worst-case
+    # snooze/retry window. Refreshed on every checkpoint write.
+    def context_ttl
+      @context_ttl ||= 86_400
+    end
+
+    # Minimum wall-clock seconds between two PER-STEP durable checkpoints within a
+    # single worker run. The save-per-step checkpoint (`on_step_complete`) bounds
+    # crash re-execution to one step, but re-serializes and re-writes the WHOLE
+    # root blob after every Success — O(steps × context_size) writes for a long,
+    # large reactor. This throttle coalesces the mid-run intermediate checkpoints:
+    # a checkpoint is written only if at least this many seconds have elapsed since
+    # the last one. The final terminal/handoff state is ALWAYS persisted (by the
+    # run's ensure-save and the pre-enqueue checkpoint), so throttling only affects
+    # mid-run granularity. Tradeoff: with interval > 0, a crash may re-run every
+    # step completed inside the last interval — safe only when those steps are
+    # idempotent or side-effect-free.
+    #
+    # Default 0 -> checkpoint after EVERY step (strongest guarantee, no coalescing).
+    def checkpoint_min_interval
+      @checkpoint_min_interval ||= 0
+    end
+
+    # Whether the recovery sweepers run. The host kicks the self-rescheduling
+    # chain once (`RubyReactor.start_sweeper!`, e.g. from an initializer); each
+    # tick re-checks this flag, so flipping it to false stops the chain at the
+    # next tick. Default on: durability is inert without a running sweeper, so
+    # recovery must work out of the box.
+    def sweeper_enabled
+      @sweeper_enabled = true if @sweeper_enabled.nil?
+      @sweeper_enabled
+    end
+
+    # Seconds between sweeps. This is the upper bound on recovery latency for a
+    # dead worker — lower it for faster recovery, raise it to cut scan load.
+    def sweeper_interval
+      @sweeper_interval ||= 30
+    end
+
+    # Max contexts/maps inspected per sweep (passed to each sweeper's run_once).
+    def sweeper_limit
+      @sweeper_limit ||= 1000
+    end
+
+    # TTL (seconds) for the per-context liveness lock (`async:<id>`). Short by
+    # design — it is a liveness signal, not retention. A live worker auto-extends
+    # it (every ttl/3 s, from a background thread); its absence is the sweeper's
+    # "worker died" signal.
+    #
+    # SAFETY CONSTRAINT: this MUST exceed the longest a single step can run
+    # WITHOUT letting the auto-extend thread make progress. Under MRI the
+    # extender shares the GIL, so a step that holds the GIL continuously for
+    # longer than this TTL (a long CPU-bound pure-Ruby loop, a C extension that
+    # never releases the GIL, or a stop-the-world GC pause) lets the lock lapse.
+    # A lapsed lock looks "dead" to the sweeper, which may re-enqueue a duplicate
+    # that runs CONCURRENTLY with the still-live original — a double-run. I/O-bound
+    # steps release the GIL and keep the lock fresh, so the default 60s suits
+    # typical workloads; raise it if you run long synchronous CPU-bound steps.
+    def context_lock_ttl
+      @context_lock_ttl ||= 60
+    end
+
     def sidekiq_retry_count
       @sidekiq_retry_count ||= 3
     end
@@ -36,7 +100,7 @@ module RubyReactor
     end
 
     def logger
-      @logger ||= Logger.new($stderr)
+      @logger ||= Logger.new($stdout)
     end
 
     def async_router

data/lib/ruby_reactor/context_serializer.rb

@@ -19,13 +19,18 @@ module RubyReactor
 
       def deserialize(serialized_data)
         decompressed = decompress_if_needed(serialized_data)
-        data = JSON.parse(decompressed, symbolize_names: false)
+        deserialize_hash(JSON.parse(decompressed, symbolize_names: false))
+      rescue JSON::ParserError => e
+        raise RubyReactor::Error::DeserializationError, "Failed to parse serialized context: #{e.message}"
+      end
 
+      # Deserialize from an already-parsed Hash (e.g. what the storage adapter's
+      # `retrieve_context` returns). Lets the rehydrate-by-id worker path avoid a
+      # second JSON parse while still schema-validating. Schema validation lives
+      # here so both the string and Hash entry points enforce it.
+      def deserialize_hash(data)
         validate_schema_version(data)
-
         Context.deserialize_from_retry(data)
-      rescue JSON::ParserError => e
-        raise RubyReactor::Error::DeserializationError, "Failed to parse serialized context: #{e.message}"
       end
 
       # rubocop:disable Metrics/CyclomaticComplexity, Metrics/MethodLength

data/lib/ruby_reactor/dsl/template_helpers.rb

@@ -19,7 +19,7 @@ module RubyReactor
         RubyReactor::Template::Element.new(map_name, path)
       end
 
-      # Make Success and Failure available in DSL contexts
+      # Make Success, Failure, and Skipped available in DSL contexts
       # rubocop:disable Naming/MethodName
       def Success(value = nil)
         # rubocop:enable Naming/MethodName
@@ -31,6 +31,12 @@ module RubyReactor
         # rubocop:enable Naming/MethodName
         RubyReactor.Failure(error)
       end
+
+      # rubocop:disable Naming/MethodName
+      def Skipped(reason: nil, **kwargs)
+        # rubocop:enable Naming/MethodName
+        RubyReactor.Skipped(reason: reason, **kwargs)
+      end
     end
   end
 end

data/lib/ruby_reactor/executor/ordered_lock_support.rb

@@ -180,7 +180,7 @@ module RubyReactor
       end
 
       def stored_context_status
-        reactor_class_name = @reactor_class.name || "AnonymousReactor-#{@reactor_class.object_id}"
+        reactor_class_name = RubyReactor.reactor_storage_name(@reactor_class)
         data = RubyReactor.configuration.storage_adapter.retrieve_context(@context.context_id, reactor_class_name)
         return nil unless data
 

data/lib/ruby_reactor/executor/retry_manager.rb

@@ -48,7 +48,7 @@ module RubyReactor
                                  @context.root_context || @context
                                end
 
-        reactor_class_name = context_to_serialize.reactor_class.name
+        reactor_class_name = RubyReactor.reactor_storage_name(context_to_serialize.reactor_class)
 
         @middlewares.on(:before_async_enqueue, context_to_serialize)
 
@@ -72,7 +72,12 @@ module RubyReactor
             fail_fast: map_args[:fail_fast]
           )
         else
-          configuration.async_router.perform_in(delay, serialized_context, reactor_class_name)
+          # Persist BEFORE enqueue — the job payload is identity-only (F2). The
+          # rescheduled job rehydrates the root by id from storage.
+          configuration.storage_adapter.store_context(
+            context_to_serialize.context_id, serialized_context, reactor_class_name
+          )
+          configuration.async_router.perform_in(delay, context_to_serialize.context_id, reactor_class_name)
         end
       end