ruby_reactor 0.6.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7ab75328ca5dda28377061047d7ac45c1515266e6e1386778470e57a2b21a674
-  data.tar.gz: 8877cc95bc390355f86a02abff2a1a405c9d021b055d842306ac78abd4145efe
+  metadata.gz: b08f95b4b201fa008ca5f98e8e221f7bb8da00becac3307f7f107406b4a3fd95
+  data.tar.gz: d3884e832408aea3d1caee63342b71c16823474abba8b98536a76dbe55ca1fc2
 SHA512:
-  metadata.gz: 778ed5734e8fbc634e00d93d5af7282d4dd44665b0345d07589b94a3eb866f7e85e1e7b12346369c4066d8d62462ff0b84b621f7c7fc268285aeb3680013e56f
-  data.tar.gz: bf90e0ee6d4da42d7ea783fb81039f978d1deb41e5b2936f1bcb51aecc49952fd05eb7ae90b98fe8ad76352931df48fcd7b978506d6cf53751a4168794d6acbf
+  metadata.gz: 2df63b3d9a9603d61baa4c51ea453399c2890b012fd74e11e01b7931081dfc9d3cc1eba358930166c2847c6cef964d9491b968e40c448d6a62fcb8ea0ae90e90
+  data.tar.gz: 809eb63f486448fb5d0c0d8d15eec39c3e358e3de26dee6c1db8318c9a2f0449fbf32a7f91695e75d58b8eee2ac026e46ce0e063181b567f4b777c35b44d2b52

data/.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "0.6.0"
+  ".": "0.7.0"
 }

data/.specify/feature.json

@@ -1,3 +1,3 @@
 {
-  "feature_directory": "specs/001-cross-service-reactor-sagas"
+  "feature_directory": "specs/001-background-async-steps"
 }

data/CHANGELOG.md

@@ -1,11 +1,124 @@
 # Changelog
 
+## [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.
 
 ## [0.5.4](https://github.com/arturictus/ruby_reactor/compare/v0.5.3...v0.5.4) (2026-06-18)
 
@@ -55,7 +168,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
+at specs/001-background-async-steps/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
@@ -402,20 +417,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 +448,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 +466,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
@@ -1203,7 +1318,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.

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