ruby_reactor 0.6.0 → 0.7.1

data/CHANGELOG.md

@@ -1,11 +1,135 @@
 # Changelog
 
+## [0.7.1](https://github.com/arturictus/ruby_reactor/compare/v0.7.0...v0.7.1) (2026-09-14)
+
+
+### Features
+
+* reactor signal semantics ([#52](https://github.com/arturictus/ruby_reactor/issues/52)) ([9147d06](https://github.com/arturictus/ruby_reactor/commit/9147d066da603c0afc1af6536b6afac7e165a034))
+
+## [0.7.0](https://github.com/arturictus/ruby_reactor/compare/v0.6.0...v0.7.0) (2026-09-08)
+
+
+### ⚠ BREAKING CHANGES
+
+* `async` inside a `step` or `compose` block is removed. It was ambiguous — only the first flagged step in a reactor ever took effect and the rest were silently ignored — so it now raises `Error::DeprecatedDslError` at class-definition time, naming its replacements.
+
+### Features
+
+* Async steps and reactors, background DSL instead of `async` ([#46](https://github.com/arturictus/ruby_reactor/issues/46)) ([9326433](https://github.com/arturictus/ruby_reactor/commit/93264331ad69f648f30d9e365048705cd9b0d82d))
+
 ## [0.6.0](https://github.com/arturictus/ruby_reactor/compare/v0.5.4...v0.6.0) (2026-08-16)
 
 
 ### Features
 
 * ActiveJob Support ([#42](https://github.com/arturictus/ruby_reactor/issues/42)) ([0fb6dc4](https://github.com/arturictus/ruby_reactor/commit/0fb6dc4ae4b16c34e0aa33a66f95df3e14ae0807))
+## Unreleased
+
+### ⚠ BREAKING CHANGES
+
+* **The per-step `async` flag is removed.** `async true` inside a `step` **or a
+  `compose`** block now raises `RubyReactor::Error::DeprecatedDslError` (a
+  subclass of `Error::ValidationError`) at reactor **class-definition** time.
+
+  It was ambiguous: only the **first** flagged step in a reactor ever took
+  effect, and every later one was silently ignored. A reactor now declares one
+  hand-off point instead, nameable from either side:
+
+  ```ruby
+  # Before — only the first `async true` did anything
+  step :process_payment do
+    async true
+    # ...
+  end
+
+  # After — the exact equivalent
+  step :process_payment do
+    # ...
+  end
+
+  background before: :process_payment
+  ```
+
+  **Migration:** for a flagged step `:x`, use `background before: :x`. That
+  reproduces the old semantics precisely — `:x` and everything after it move to
+  the worker — without having to identify a predecessor step. The same applies to
+  `async` inside a `compose` block. `after: :x` is the other side of the same cut
+  point (`:x` stays in the calling process); the two coincide in a linear chain
+  but pin different steps in a DAG.
+
+  Not affected: the map-internal `async` element dispatch option
+  (`map :items do async true, batch_size: 2 end`) — a different mechanism that
+  keeps working unchanged.
+
+  One behavior change falls out of "exactly one hand-off point per reactor":
+  resuming a reactor past its hand-off point now finishes in the resuming
+  process, where the old per-step flag would queue a second, undeclared hand-off.
+
+* `RubyReactor::Dsl::StepConfig#async?` and the per-step `async:` field in the
+  dashboard's `Web::API` step structure are gone. The dashboard now exposes the
+  reactor's normalized hand-off point once, as `background_handoff`.
+
+* **Whole-reactor `async true` is removed.** It named the same hand-off idea as
+  `background`, with a different word, and read confusingly next to the new
+  `async_step` / `async_reactor` step macros (both "async" + "reactor", meaning
+  different things). Using it now raises `RubyReactor::Error::DeprecatedDslError`
+  at class-definition time.
+
+  ```ruby
+  # Before
+  class OrderProcessingReactor < RubyReactor::Reactor
+    async true
+    # ...
+  end
+
+  # After — identical behavior, including validating inputs inside the worker
+  class OrderProcessingReactor < RubyReactor::Reactor
+    background all: true
+    # ...
+  end
+  ```
+
+  **Migration:** replace `async true` with `background all: true`. `async?` (the
+  reader) is unchanged and still answers the same question.
+
+* **`RubyReactor::AsyncResult` is renamed to `RubyReactor::DispatchResult`.** The
+  old name no longer fit: the class is the sentinel returned whenever a step's
+  work is handed to a worker and not yet resolved, produced alike by
+  `background`, `async_step`, `async_reactor`, and map's async element dispatch
+  — not specific to "async" as a concept.
+
+  **Migration:** replace any `RubyReactor::AsyncResult` reference (e.g. in a
+  custom `async_router`, or `result.is_a?(RubyReactor::AsyncResult)` checks)
+  with `RubyReactor::DispatchResult`.
+
+### Features
+
+* **`background after:` / `background before:` / `background all:`** — one
+  unambiguous, reactor-level cut point between what runs in the calling process
+  and what runs in a worker (`all:` — the whole reactor, replacing the old
+  whole-reactor `async true`).
+* **`async_step`** — dispatch one step's work to its own job while the reactor
+  keeps running every other ready step. Dependent steps read the outcome through
+  the existing `result(:name)` helper, which gains a bounded notified wait.
+* **`async_reactor`** — dispatch a whole nested reactor to run independently,
+  linked to the parent by execution id for traceability but excluded from its
+  compensation graph. A dispatch-time guard fails loudly instead of deadlocking
+  when a child declares a lock key the parent holds.
+* **`Configuration#async_wait_timeout`** (default `30` seconds) — bounds how long
+  a step blocks reading a dispatched result. Never an unbounded wait.
+* The dashboard renders both new step types and drills into an `async_reactor`
+  child's own execution.
+
+**Compensation for the two new units is opt-in, by design.** A failing
+`async_step` / `async_reactor` does not automatically compensate its parent — it
+was dispatched precisely so the parent would not depend on it. A later step that
+reads the result and returns `Failure` triggers compensation normally, so no
+failure is unrecoverable, just not automatic.
+
+* Reactor signal semantics: `Skipped` is renamed to `Halt` (the existing clean-stop behaviour, unchanged otherwise), and `Skipped` is reused with new meaning — marking a single step skipped while the reactor continues, with its value flowing to dependants exactly like `Success`. One-line outcome helpers `success!`, `fail!`, `skip!`, and `halt!` end a step immediately from any call depth. `Failure` (and `fail!`) accept a `retry:` spelling alongside the existing `retryable:`. `compensate`/`undo` now default to `Skipped` instead of `Success`, so the execution trace distinguishes rollback logic that ran from rollback logic that was never written.
+
+  **Migration**: `Skipped(reason: "...")` (the old halt) is now `Halt(reason: "...")`; `result.skipped?` for a clean halt is now `result.halted?`; the `be_skipped` matcher for a clean halt is now `be_halted`. The old call shape raises `ArgumentError` naming `Halt` — there is no silent compatibility path. Run status `:skipped` is renamed `:halted`; contexts persisted by a pre-upgrade version with status `"skipped"` are still read back correctly as halted.
 
 ## [0.5.4](https://github.com/arturictus/ruby_reactor/compare/v0.5.3...v0.5.4) (2026-06-18)
 
@@ -55,7 +179,7 @@
 
 ### Features
 
-* `AsyncResult` returning intermediate_results ([#10](https://github.com/arturictus/ruby_reactor/issues/10)) ([0cb96d6](https://github.com/arturictus/ruby_reactor/commit/0cb96d66e88097665998601276e38e1c2249c581))
+* `DispatchResult` returning intermediate_results ([#10](https://github.com/arturictus/ruby_reactor/issues/10)) ([0cb96d6](https://github.com/arturictus/ruby_reactor/commit/0cb96d66e88097665998601276e38e1c2249c581))
 * enhance deserialization error handling in Sidekiq worker ([#23](https://github.com/arturictus/ruby_reactor/issues/23)) ([60dde95](https://github.com/arturictus/ruby_reactor/commit/60dde95606d52cc6a9d352ad0117b4092a1ebb9d))
 * Enhance failure messages with step, reactor, redacted inputs, a… ([#11](https://github.com/arturictus/ruby_reactor/issues/11)) ([952feae](https://github.com/arturictus/ruby_reactor/commit/952feaeb6ebbe5fbe2daf470263d8e769ba64138))
 * Introduce reactor interrupt functionality, allowing pausing and… ([#13](https://github.com/arturictus/ruby_reactor/issues/13)) ([53d0861](https://github.com/arturictus/ruby_reactor/commit/53d0861f0238f0e2247e581b0a27cba2f42cfba6))

data/CLAUDE.md

@@ -0,0 +1,5 @@
+<!-- SPECKIT START -->
+For additional context about technologies to be used, project structure,
+shell commands, and other important information, read the current plan:
+`specs/001-reactor-signal-semantics/plan.md`
+<!-- SPECKIT END -->

data/README.md

@@ -59,7 +59,9 @@ The key value is **Reliability**: if any part of your workflow fails, Ruby React
   - [Basic Example: User Registration](#basic-example-user-registration)
   - [Async Execution](#async-execution)
     - [Full Reactor Async](#full-reactor-async)
-    - [Step-Level Async](#step-level-async)
+    - [Background Hand-off](#background-hand-off)
+    - [`async_step`](#async_step-one-step-dispatched-on-its-own)
+    - [`async_reactor`](#async_reactor-a-whole-nested-reactor-running-independently)
   - [Durability & Recovery](#durability--recovery)
   - [Interrupts (Pause & Resume)](#interrupts-pause--resume)
   - [Locks, Semaphores & Ordered Locks](#locks-semaphores--ordered-locks)
@@ -139,6 +141,19 @@ RubyReactor.configure do |config|
   # config.lock_snooze_jitter = 5
   # config.lock_snooze_max_attempts = 20
 
+  ## === Waiting on async results (`result(:name)` on async_step / async_reactor) ===
+
+  ## How long a SYNCHRONOUS caller blocks on a still-pending async result before
+  ## failing with Error::AsyncWaitTimeoutError. Kept tight: a blocking wait pins
+  ## a thread and must stay under typical host timeouts. Default: 30.
+  # config.async_wait_timeout = 30
+
+  ## Total parked time allowed when the reader runs INSIDE a worker: the job
+  ## re-enqueues itself instead of blocking (locks stay held across the gap),
+  ## so this bound can be generous. Measured from the unit's dispatch.
+  ## :infinity removes the bound. Default: 3600.
+  # config.async_park_timeout = 3600
+
   ## === Durability & crash recovery (see "Durability & Recovery" below) ===
 
   ## Retention TTL (seconds) for stored reactor/map state. Must exceed your
@@ -215,11 +230,14 @@ RubyReactor supports two ways to define step logic:
 | **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:
+Whichever style you use, a step's `run` returns one of four 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).
+- **`Halt(reason:)`** — clean halt: stop the reactor, keep partial progress, **no rollback**. See [Halting a reactor cleanly](documentation/core_concepts.md#halting-a-reactor-cleanly).
+- **`Skipped(value)`** — mark this one step skipped; the reactor continues and `value` flows to dependants exactly like `Success`. See [Skipping a single step](documentation/core_concepts.md#skipping-a-single-step).
+
+One-line helpers end a step immediately from any call depth: `success!(value)`, `fail!(error, retry: true)`, `halt!(reason:)`, `skip!(value)` — equivalent to `return`ing the matching signal, usable in `run`, `compensate`, and `undo` bodies.
 
 **Class steps** are plain Ruby classes that include `RubyReactor::Step` and implement `run`, and optionally `compensate` and `undo`:
 
@@ -402,20 +420,23 @@ async, durability, retries, snoozing) works identically on either backend.
 
 ```ruby
 class AsyncReactor < RubyReactor::Reactor
-  async true # Entire reactor runs in background
+  background all: true # Entire reactor runs in background
 
   step :long_running_task do
     run { perform_heavy_work }
   end
 end
 
-# Returns immediately with AsyncResult
+# Returns immediately with DispatchResult
 result = AsyncReactor.run(params)
 ```
 
-#### Step-Level Async
+#### Background Hand-off
 
-You can also mark individual steps as async. Execution will proceed synchronously until the first async step is encountered, at which point the reactor execution is offloaded to a background job.
+A reactor can name **one** point where execution stops running in the caller's
+process and is handed to a worker. Everything before it runs in the caller;
+everything after it runs in a single background job. The cut point is nameable
+from either side.
 
 ```ruby
 class CreateUserReactor < RubyReactor::Reactor
@@ -430,15 +451,16 @@ class CreateUserReactor < RubyReactor::Reactor
     run { |args| User.create(args[:params]) }
   end
 
-  # From here on will run async
+  # :create_user is the LAST step to run in the calling process.
+  # Equivalently here: `background before: :open_account`.
+  background after: :create_user
+
   step :open_account do
-    async true
     argument :user, result(:create_user)
     run { |args| Bank.open_account(args[:user]) }
   end
 
   step :report_new_user do
-    async true
     argument :user, result(:create_user)
     wait_for :open_account
     run { |args| Analytics.track(args[:user]) }
@@ -447,16 +469,112 @@ end
 
 # Usage
 def create(params)
-   # Returns an AsyncResult immediately when 'open_account' is reached
-   result = CreateUserReactor.run(params)
-   
-   # Access synchronous results immediately
-   user = result.intermediate_results[:create_user]
-   
-   # do something with user
+  # Returns an DispatchResult immediately once :create_user completes
+  result = CreateUserReactor.run(params)
+
+  # Access synchronous results immediately
+  user = result.intermediate_results[:create_user]
+
+  # do something with user
+end
+```
+
+`after: :x` guarantees `:x` runs in the calling process and is the last to do so.
+`before: :x` guarantees `:x` runs in the worker and is the first to do so. They
+coincide in a linear chain; **in a DAG they pin different steps**, so pick
+whichever step you actually need pinned. Compensation is unchanged — `background`
+changes where code runs, not the saga contract.
+
+> **Breaking change:** the per-step `async true` flag has been **removed**. It was
+> ambiguous — only the *first* flagged step in a reactor ever took effect and the
+> rest were silently ignored — and it now raises at class-definition time. The
+> exact replacement for a flagged step `:x` is `background before: :x`. The same
+> applies to `async` inside a `compose` block.
+>
+> **Breaking change:** whole-reactor `async true` has also been **removed** — it
+> named the same idea as `background`'s cut point with a different word, right next
+> to `async_step`/`async_reactor`, whose names mean something else. It now raises
+> at class-definition time. The exact replacement is `background all: true`.
+
+#### `async_step`: one step, dispatched on its own
+
+Where `background` relocates the *rest* of a reactor, `async_step` dispatches one
+step's work to its own job while the reactor keeps running every other ready step.
+
+```ruby
+class SignupReactor < RubyReactor::Reactor
+  input :email
+
+  async_step :send_email do
+    argument :to, input(:email)
+    run { |args| Mailer.welcome(args[:to]).deliver_now; Success(:sent) }
+  end
+
+  # Does NOT wait — it has no dependency on :send_email.
+  step :record_signup do
+    argument :email, input(:email)
+    run { |args| Success(Signup.create!(email: args[:email])) }
+  end
+
+  # DOES wait, because it reads the result.
+  step :confirm_delivery do
+    argument :delivery, result(:send_email)
+    run { |args| Success("confirmed") }
+  end
+end
+```
+
+Reading `result(:send_email)` is what makes a step wait — never unbounded, and
+never thread-hungry: a **synchronous caller** blocks, bounded by
+`config.async_wait_timeout` (default 30s); a reader **inside a worker** parks
+instead — after a short grace the job re-enqueues itself, freeing the thread and
+keeping any held lock/semaphore checked out, bounded by
+`config.async_park_timeout` (default 1h) so legitimately slow units get their
+time. On success the reader gets the raw value; on failure it gets the
+`Failure` **object**, so it can inspect it and decide.
+
+**Compensation is opt-in.** If a dispatched step fails and nothing reads its
+result, the reactor is not compensated — it was dispatched precisely so the
+reactor would not depend on it. A reader that returns `Failure` triggers
+compensation normally. The independence cuts both ways: async dispatches never
+enter the parent's undo stack, so a parent rolling back for its own reasons
+never "undoes" a unit that runs (and may still succeed) elsewhere.
+
+#### `async_reactor`: a whole nested reactor, running independently
+
+```ruby
+class SignupReactor < RubyReactor::Reactor
+  input :user_id
+
+  # Fire-and-forget: nothing reads it, so its failure never affects this reactor.
+  async_reactor :backfill_profile, ProfileBackfillReactor do
+    argument :user_id, input(:user_id)
+  end
+
+  async_reactor :provision_account, AccountProvisioningReactor do
+    argument :user_id, input(:user_id)
+  end
+
+  step :verify do
+    argument :account, result(:provision_account)   # waits for the child
+    run do |args|
+      args[:account].success? ? Success(args[:account].value) : Failure(args[:account].error)
+    end
+  end
 end
 ```
 
+The child is an ordinary, independently addressable execution, linked to the
+parent by execution id (drillable in the dashboard) but excluded from its
+compensation graph. Reach for `compose` instead when the child belongs to this
+unit of work — its result is available immediately and its failure rolls the
+parent back.
+
+Lock ownership is never shared across the async boundary: a child declaring a key
+the parent holds fails at dispatch with an explanatory error rather than
+deadlocking. See [Async Reactors](documentation/async_reactors.md) for the full
+rules.
+
 ### Durability & Recovery
 
 Async reactors are durable: state lives in Redis, not in the job payload. Before
@@ -611,7 +729,7 @@ class MonthlyBillingReactor < RubyReactor::Reactor
   input :org_id
 
   # Run at most once per UTC month per org. Subsequent calls in the same month
-  # return RubyReactor::Skipped without executing any step. Pair with
+  # return RubyReactor::Halt without executing any step. Pair with
   # with_lock for strict at-most-one even under concurrent racers.
   with_period(every: :month) { |inputs| "monthly_billing:#{inputs[:org_id]}" }
 
@@ -686,26 +804,38 @@ On contention:
 - **Inline** (`Reactor.run`) raises `RubyReactor::Lock::AcquisitionError` / `RubyReactor::Semaphore::AcquisitionError` / `RubyReactor::RateLimit::ExceededError` / `RubyReactor::OrderedLock::WaitError`.
 - **Async** (Sidekiq or ActiveJob) snoozes the job via `perform_in(delay, ...)`. For rate limits the delay uses the error's `retry_after_seconds` hint (precise wakeup — the bucket roll time is known exactly); for locks, semaphores, and ordered-lock waits it's `lock_snooze_base_delay + jitter` (a short re-poll, since a held lock or a live blocker nonce typically clears in milliseconds). Snoozes do not count against the backend's retry budget. After `lock_snooze_max_attempts` snoozes the context is marked failed (ordered-lock waits bypass the cap — see the ordered-lock docs).
 
-On dedup hits (period gate already marked), the reactor returns a `RubyReactor::Skipped` result instead — no steps run, no exception:
+On dedup hits (period gate already marked), the reactor returns a `RubyReactor::Halt` result instead — no steps run, no exception:
 
 ```ruby
 result = MonthlyBillingReactor.run(org_id: 42)
-result.success?  # true (Skipped is a Success subclass)
-result.skipped?  # true on dedup hit, false otherwise
+result.success?  # true (Halt is a Success subclass)
+result.halted?   # true on dedup hit, false otherwise
 ```
 
-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(...)`).
+A step's `run` block can also return `Halt(reason: "...")` to stop 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"). `Halt` is a bare helper just like `Success`/`Failure` (or use the fully-qualified `RubyReactor.Halt(...)`).
 
 ```ruby
 step :ensure_active do
   argument :user, result(:fetch_user)
   run do |args, _ctx|
-    next Skipped(reason: "user_opted_out") if args[:user].opted_out?
+    next Halt(reason: "user_opted_out") if args[:user].opted_out?
     Success(args[:user])
   end
 end
 ```
 
+To skip a *single* step while the reactor continues — the step did nothing, but the rest of the workflow should still run — return `Skipped(value)` instead. The value flows to dependants exactly like a `Success` value, and the step is not enrolled for rollback:
+
+```ruby
+step :maybe_sync do
+  argument :user, result(:fetch_user)
+  run do |args, _ctx|
+    next Skipped(args[:user]) if args[:user].already_synced?
+    Success(sync!(args[:user]))
+  end
+end
+```
+
 See [Locks, Semaphores, Rate Limits, Periods & Ordered Locks](documentation/locks_and_semaphores.md) for re-entrancy, auto-extend, multi-window quotas, bucket semantics, owner identity, snooze tuning, ordered-lock assignment + poison-pill semantics, and operational notes.
 
 ### Map & Parallel Execution
@@ -1203,7 +1333,7 @@ Learn about the fundamental building blocks of RubyReactor: Reactors, Steps, Con
 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.
 
 ### [Async Reactors](documentation/async_reactors.md)
-Explore the two asynchronous execution models: Full Reactor Async and Step-Level Async. Learn how RubyReactor leverages Sidekiq or ActiveJob for background processing, non-blocking execution, and scalable worker management.
+Explore the ways to move work off the calling process: Full Reactor Async, the `background` hand-off, `async_step`, and `async_reactor`. Learn how RubyReactor leverages Sidekiq or ActiveJob for background processing, non-blocking execution, and scalable worker management.
 
 ### [Composition](documentation/composition.md)
 Discover how to build complex, modular workflows by composing reactors within other reactors. This guide covers inline composition, class-based composition, and how to manage dependencies between composed workflows.
@@ -1222,7 +1352,7 @@ Comprehensive guide to testing reactors with RubyReactor's testing utilities. Le
 
 ### [Locks, Semaphores, Rate Limits, Periods & Ordered Locks](documentation/locks_and_semaphores.md)
 
-Coordinate access to shared resources across processes with Redis-backed primitives: exclusive locks (`with_lock`), concurrency-limiting semaphores (`with_semaphore`), fixed-window rate limits with multi-window quotas (`with_rate_limit`), calendar-bucketed dedup (`with_period`, returning `Skipped` results), and strict sequential ordering via a monotonically increasing nonce assigned at enqueue (`with_ordered_lock`). Covers re-entrancy across composed reactors, TTL auto-extend, inline-vs-async contention behavior, smart `retry_after` snoozes for rate limits, snooze tuning, the token-based semaphore safety model, once-per-day/month/year scheduling patterns, ordered-lock counter reset on drain, poison-pill timeouts, and deadlock-safe composition rules.
+Coordinate access to shared resources across processes with Redis-backed primitives: exclusive locks (`with_lock`), concurrency-limiting semaphores (`with_semaphore`), fixed-window rate limits with multi-window quotas (`with_rate_limit`), calendar-bucketed dedup (`with_period`, returning `Halt` results), and strict sequential ordering via a monotonically increasing nonce assigned at enqueue (`with_ordered_lock`). Covers re-entrancy across composed reactors, TTL auto-extend, inline-vs-async contention behavior, smart `retry_after` snoozes for rate limits, snooze tuning, the token-based semaphore safety model, once-per-day/month/year scheduling patterns, ordered-lock counter reset on drain, poison-pill timeouts, and deadlock-safe composition rules.
 
 ### [Middlewares & OpenTelemetry](documentation/middlewares.md)
 

data/lib/ruby_reactor/adapters/active_job/router.rb

@@ -9,16 +9,31 @@ module RubyReactor
         # there is no blob to deserialize here.
         def self.perform_async(context_id, reactor_class_name = nil, intermediate_results: {})
           job_id = RubyReactor::Adapters::ActiveJob::Worker.perform_async(context_id, reactor_class_name)
-          RubyReactor::AsyncResult.new(job_id: job_id, intermediate_results: intermediate_results,
+          RubyReactor::DispatchResult.new(job_id: job_id, intermediate_results: intermediate_results,
                                        execution_id: context_id)
         end
 
         def self.perform_in(delay, context_id, reactor_class_name = nil, intermediate_results: {})
           job_id = RubyReactor::Adapters::ActiveJob::Worker.perform_in(delay, context_id, reactor_class_name)
-          RubyReactor::AsyncResult.new(job_id: job_id, intermediate_results: intermediate_results,
+          RubyReactor::DispatchResult.new(job_id: job_id, intermediate_results: intermediate_results,
                                        execution_id: context_id)
         end
 
+        # One `async_step`'s work, dispatched as its own independent unit. The
+        # payload is identity-only for the same reason every other dispatch here
+        # is: the worker rehydrates the parent context from storage.
+        def self.perform_step_async(root_context_id:, reactor_class_name:, step_context_id:, step_name:)
+          job_id = RubyReactor::Adapters::ActiveJob::StepWorker.perform_async(
+            {
+              "root_context_id" => root_context_id,
+              "reactor_class_name" => reactor_class_name,
+              "step_context_id" => step_context_id,
+              "step_name" => step_name.to_s
+            }
+          )
+          RubyReactor::DispatchResult.new(job_id: job_id)
+        end
+
         # rubocop:disable Metrics/ParameterLists
         def self.perform_map_element_async(map_id:, element_id:, index:, serialized_inputs:, reactor_class_info:,
                                            strict_ordering:, parent_context_id:, parent_reactor_class_name:,
@@ -39,7 +54,7 @@ module RubyReactor
               "fail_fast" => fail_fast
             }
           )
-          RubyReactor::AsyncResult.new(job_id: job_id)
+          RubyReactor::DispatchResult.new(job_id: job_id)
         end
 
         def self.perform_map_element_in(delay, map_id:, element_id:, index:, serialized_inputs:,
@@ -63,9 +78,9 @@ module RubyReactor
               "fail_fast" => fail_fast
             }
           )
-          # Return an AsyncResult so RetryManager#handle_async_retry recognises the
+          # Return an DispatchResult so RetryManager#handle_async_retry recognises the
           # element was successfully requeued and yields a RetryQueuedResult.
-          RubyReactor::AsyncResult.new(job_id: job_id)
+          RubyReactor::DispatchResult.new(job_id: job_id)
         end
         # rubocop:enable Metrics/ParameterLists
 
@@ -82,7 +97,7 @@ module RubyReactor
               "timeout" => timeout
             }
           )
-          RubyReactor::AsyncResult.new(job_id: job_id)
+          RubyReactor::DispatchResult.new(job_id: job_id)
         end
         # rubocop:enable Metrics/ParameterLists
       end

data/lib/ruby_reactor/adapters/active_job/step_worker.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require "active_job"
+
+module RubyReactor
+  module Adapters
+    module ActiveJob
+      # ActiveJob counterpart to Sidekiq::StepWorker — binding only.
+      class StepWorker < ::ActiveJob::Base
+        extend Compat
+
+        queue_as { RubyReactor.configuration.queue_name }
+
+        def perform(arguments)
+          RubyReactor::StepWorker.perform(arguments)
+        end
+      end
+    end
+  end
+end

data/lib/ruby_reactor/adapters/active_job/worker.rb

@@ -17,7 +17,12 @@ module RubyReactor
         include RubyReactor::Worker
 
         queue_as { RubyReactor.configuration.queue_name }
-        retry_on StandardError, attempts: RubyReactor.configuration.job_retry_count
+        retry_on StandardError, attempts: RubyReactor.configuration.job_retry_count do |job, error|
+          # Attempts exhausted and the job is done for — mark the context
+          # failed and signal any reader waiting on it (mirrors the Sidekiq
+          # adapter's retries-exhausted hook).
+          RubyReactor::Worker.record_retries_exhausted(job.arguments, error)
+        end
       end
     end
   end

data/lib/ruby_reactor/adapters/sidekiq/router.rb

@@ -9,16 +9,31 @@ module RubyReactor
         # there is no blob to deserialize here.
         def self.perform_async(context_id, reactor_class_name = nil, intermediate_results: {})
           job_id = RubyReactor::Adapters::Sidekiq::Worker.perform_async(context_id, reactor_class_name)
-          RubyReactor::AsyncResult.new(job_id: job_id, intermediate_results: intermediate_results,
+          RubyReactor::DispatchResult.new(job_id: job_id, intermediate_results: intermediate_results,
                                        execution_id: context_id)
         end
 
         def self.perform_in(delay, context_id, reactor_class_name = nil, intermediate_results: {})
           job_id = RubyReactor::Adapters::Sidekiq::Worker.perform_in(delay, context_id, reactor_class_name)
-          RubyReactor::AsyncResult.new(job_id: job_id, intermediate_results: intermediate_results,
+          RubyReactor::DispatchResult.new(job_id: job_id, intermediate_results: intermediate_results,
                                        execution_id: context_id)
         end
 
+        # One `async_step`'s work, dispatched as its own independent unit. The
+        # payload is identity-only for the same reason every other dispatch here
+        # is: the worker rehydrates the parent context from storage.
+        def self.perform_step_async(root_context_id:, reactor_class_name:, step_context_id:, step_name:)
+          job_id = RubyReactor::Adapters::Sidekiq::StepWorker.perform_async(
+            {
+              "root_context_id" => root_context_id,
+              "reactor_class_name" => reactor_class_name,
+              "step_context_id" => step_context_id,
+              "step_name" => step_name.to_s
+            }
+          )
+          RubyReactor::DispatchResult.new(job_id: job_id)
+        end
+
         # rubocop:disable Metrics/ParameterLists
         def self.perform_map_element_async(map_id:, element_id:, index:, serialized_inputs:, reactor_class_info:,
                                            strict_ordering:, parent_context_id:, parent_reactor_class_name:,
@@ -39,7 +54,7 @@ module RubyReactor
               "fail_fast" => fail_fast
             }
           )
-          RubyReactor::AsyncResult.new(job_id: job_id)
+          RubyReactor::DispatchResult.new(job_id: job_id)
         end
 
         def self.perform_map_element_in(delay, map_id:, element_id:, index:, serialized_inputs:,
@@ -63,9 +78,9 @@ module RubyReactor
               "fail_fast" => fail_fast
             }
           )
-          # Return an AsyncResult so RetryManager#handle_async_retry recognises the
+          # Return an DispatchResult so RetryManager#handle_async_retry recognises the
           # element was successfully requeued and yields a RetryQueuedResult.
-          RubyReactor::AsyncResult.new(job_id: job_id)
+          RubyReactor::DispatchResult.new(job_id: job_id)
         end
         # rubocop:enable Metrics/ParameterLists
 
@@ -82,7 +97,7 @@ module RubyReactor
               "timeout" => timeout
             }
           )
-          RubyReactor::AsyncResult.new(job_id: job_id)
+          RubyReactor::DispatchResult.new(job_id: job_id)
         end
         # rubocop:enable Metrics/ParameterLists
       end

data/lib/ruby_reactor/adapters/sidekiq/step_worker.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module RubyReactor
+  module Adapters
+    module Sidekiq
+      # One dispatched `async_step`, mirroring MapElementWorker: the backend
+      # binding only, all behavior in the shared `RubyReactor::StepWorker`.
+      class StepWorker
+        include ::Sidekiq::Worker
+
+        def perform(arguments)
+          RubyReactor::StepWorker.perform(arguments)
+        end
+      end
+    end
+  end
+end

data/lib/ruby_reactor/adapters/sidekiq/worker.rb

@@ -16,8 +16,11 @@ module RubyReactor
         sidekiq_options retry: RubyReactor.configuration.job_retry_count, dead: false,
                         queue: RubyReactor.configuration.queue_name
 
-        sidekiq_retries_exhausted do |_, _exception|
-          # Handle infrastructure failures (network, Redis, etc.)
+        sidekiq_retries_exhausted do |msg, exception|
+          # With `dead: false` this job is discarded after its last retry, so
+          # this hook is the only place left to surface the failure: mark the
+          # context failed and signal any reader waiting on it.
+          RubyReactor::Worker.record_retries_exhausted(msg["args"], exception)
         end
       end
     end