ruby_reactor 0.8.0 → 0.8.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6e671a274b5dc3854189ab1f3c40ff4d7e307a567ed960dbad0be1405f05ff58
-  data.tar.gz: 0a44e9cf8dbed99b72762381300c4c503500d3025f21288e473eef377a28dbec
+  metadata.gz: 0d5c03b684aeac0b3d682581e9746e59219622f07752a5b5e30b5381582c09c9
+  data.tar.gz: bccbbdf3eec2187481fba0c5d724b1b2b61d96a32c93139dcf5fcd20e42ff491
 SHA512:
-  metadata.gz: a39666bdba5d7c911589da0f30a12e29a9f5187c31a9a1bfb9ddc0c55aba26cac201db3e8083854f79858d6845ed98097589979873a0a4aa7cc8dfdaca635856
-  data.tar.gz: a5069c91a3942f1697a317baee2223b790b4262ca6d90f61a1b3aa0cd8b61ff9b199b7a05f58f791df11bd7b4336611907a6abd3cbce6ebfd007d9bc92949c4e
+  metadata.gz: ab06166bc3462aa2cf8f4569015575feb7c37ae025022ae84b886dcc171040c2a89a88dbc69208c8b1ec84be6dd19c08c418915856a510506402e7ab72f26044
+  data.tar.gz: cfb0973443827d2d50572f834b1d9d2760464eab4290097b38c73465fcb7268f9e381d211b4a2fe1815f6bb410ac56ffa64c4f61ed17f0a765966392c50494a4

data/.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "0.8.0"
+  ".": "0.8.1"
 }

data/CHANGELOG.md

@@ -129,6 +129,13 @@
   ordinary `nil` success, and `result(:step)` hands the reader the `Halt` — the same way it
   already hands over a `Failure`.
 
+## [0.8.1](https://github.com/arturictus/ruby_reactor/compare/v0.8.0...v0.8.1) (2026-09-22)
+
+
+### Miscellaneous Chores
+
+* Update documentation clarifying background and async concepts ([#55](https://github.com/arturictus/ruby_reactor/issues/55)) ([968e32b](https://github.com/arturictus/ruby_reactor/commit/968e32bbc695e45471d04b7630d8cd437ff41624))
+
 ## [0.8.0](https://github.com/arturictus/ruby_reactor/compare/v0.7.1...v0.8.0) (2026-09-21)
 
 
@@ -198,9 +205,9 @@
   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.
+  Also affected: the map-internal element dispatch option was renamed from
+  `async true` to `fan_out`, so `map :items do async true, batch_size: 2 end`
+  now raises and should become `map :items do fan_out batch_size: 2 end`.
 
   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

data/README.md

@@ -5,7 +5,7 @@
 
 # RubyReactor
 
-A dynamic, dependency-resolving saga orchestrator for Ruby. Ruby Reactor implements the Saga pattern with compensation-based error handling and DAG-based execution planning. It leverages **Sidekiq or ActiveJob** for asynchronous execution and **Redis** for state persistence.
+A dynamic, dependency-resolving saga orchestrator for Ruby. Ruby Reactor implements the Saga pattern with compensation-based error handling and DAG-based execution planning. It leverages **Sidekiq or ActiveJob** for background execution and **Redis** for state persistence.
 
 ![Payment workflow reactor](documentation/images/payment_workflow.png)
 
@@ -18,13 +18,14 @@ The key value is **Reliability**: if any part of your workflow fails, Ruby React
 ## Features
 
 - **DAG-based Execution**: Steps are executed based on their dependencies, allowing for parallel execution of independent steps.
-- **Async Execution**: Steps can be executed asynchronously in the background using Sidekiq or ActiveJob (so any ActiveJob-compatible queue — Resque, Solid Queue, GoodJob, etc. — works too).
+- **Background Execution**: Hand a whole reactor, or everything after a declared step, to a background job via Sidekiq or ActiveJob (so any ActiveJob-compatible queue — Resque, Solid Queue, GoodJob, etc. — works too).
+- **Async Steps & Reactors**: `async_step` and `async_reactor` dispatch independent units of work while the reactor keeps running; steps that read their result wait for it.
 - **Map & Parallel Execution**: Iterate over collections in parallel with the `map` step, distributing work across multiple workers.
 - **Retries**: Configurable retry logic for failed steps, with exponential backoff.
 - **Compensation**: Automatic rollback of completed steps when a failure occurs.
 - **Interrupts**: Pause and resume workflows to wait for external events (webhooks, user approvals).
 - **Input Validation**: Integrated with `dry-validation` for robust input checking.
-- **Distributed Locks, Semaphores, Rate Limits, Periods & Ordered Locks**: Coordinate across processes with Redis-backed primitives — exclusive locks for at-most-one-runner, semaphores for capacity caps, fixed-window rate limits for external APIs (single or multi-window like "3/sec AND 100/min"), `with_period` to dedup reactors to once per calendar bucket, and `with_ordered_lock` for strict transaction ordering via a monotonically increasing nonce assigned at enqueue. Async jobs snooze on contention with smart `retry_after` instead of consuming retry budget.
+- **Distributed Locks, Semaphores, Rate Limits, Periods & Ordered Locks**: Coordinate across processes with Redis-backed primitives — exclusive locks for at-most-one-runner, semaphores for capacity caps, fixed-window rate limits for external APIs (single or multi-window like "3/sec AND 100/min"), `with_period` to dedup reactors to once per calendar bucket, and `with_ordered_lock` for strict transaction ordering via a monotonically increasing nonce assigned at enqueue. Background jobs snooze on contention with smart `retry_after` instead of consuming retry budget.
 
 ## Comparison
 
@@ -35,7 +36,7 @@ The key value is **Reliability**: if any part of your workflow fails, Ruby React
 | Interrupts (pause/resume)| Yes          | No              | No          | Manual              |
 | Locks / sem / rate / per | Yes          | No              | No          | Manual              |
 | Built-in web dashboard   | Yes          | No              | No          | No                  |
-| Async (Sidekiq/AJ)       | Yes          | No              | Limited     | Yes                 |
+| Background (Sidekiq/AJ)  | Yes          | No              | Limited     | Yes                 |
 | Durable crash recovery   | Yes          | No              | No          | Manual              |
 
 ## Real-World Use Cases
@@ -57,9 +58,10 @@ The key value is **Reliability**: if any part of your workflow fails, Ruby React
   - [Rails Installation](#rails-installation)
 - [Usage](#usage)
   - [Basic Example: User Registration](#basic-example-user-registration)
-  - [Async Execution](#async-execution)
-    - [Full Reactor Async](#full-reactor-async)
+  - [Background Execution](#background-execution)
+    - [Full Background](#full-background)
     - [Background Hand-off](#background-hand-off)
+  - [Async Steps & Reactors](#async-steps--reactors)
     - [`async_step`](#async_step-one-step-dispatched-on-its-own)
     - [`async_reactor`](#async_reactor-a-whole-nested-reactor-running-independently)
   - [Durability & Recovery](#durability--recovery)
@@ -119,7 +121,7 @@ RubyReactor.configure do |config|
 
   ## === Background job backend (Sidekiq by default, or ActiveJob) ===
 
-  ## Queue used by RubyReactor's async worker. Default: :default.
+  ## Queue used by RubyReactor's background worker. Default: :default.
   # config.queue_name = :default
 
   ## Retry count for infrastructure failures only (deserialization, Redis,
@@ -180,8 +182,8 @@ RubyReactor.configure do |config|
   ## Logger. Default: Logger.new($stdout).
   # config.logger = Logger.new($stdout)
 
-  ## Async router. Default: RubyReactor::Adapters::Sidekiq::Router. Swap in the
-  ## built-in ActiveJob adapter (see "Async Execution" below), or point at any
+  ## Background job router. Default: RubyReactor::Adapters::Sidekiq::Router. Swap in the
+  ## built-in ActiveJob adapter (see "Background Execution" below), or point at any
   ## custom adapter — it only needs to respond to
   ## `perform_async(context_id, reactor_class_name, **)`.
   # config.async_router = RubyReactor::Adapters::ActiveJob::Router
@@ -398,7 +400,7 @@ else
 end
 ```
 
-### Async Execution
+### Background Execution
 
 Execute reactors in the background using Sidekiq or ActiveJob. The backend is
 chosen via `config.async_router` (defaults to the Sidekiq adapter); to run on
@@ -410,13 +412,14 @@ RubyReactor.configure do |config|
 end
 ```
 
-That's the only switch — everything below (full-reactor async, step-level
-async, durability, retries, snoozing) works identically on either backend.
+That's the only switch — everything below (background execution, `async_step`
+/ `async_reactor`, durability, retries, snoozing) works identically on either
+backend.
 
-#### Full Reactor Async
+#### Full Background
 
 ```ruby
-class AsyncReactor < RubyReactor::Reactor
+class BackgroundReactor < RubyReactor::Reactor
   background all: true # Entire reactor runs in background
 
   step :long_running_task do
@@ -425,7 +428,7 @@ class AsyncReactor < RubyReactor::Reactor
 end
 
 # Returns immediately with DispatchResult
-result = AsyncReactor.run(params)
+result = BackgroundReactor.run(params)
 ```
 
 #### Background Hand-off
@@ -493,6 +496,13 @@ changes where code runs, not the saga contract.
 > 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 Steps & Reactors
+
+`async_step` and `async_reactor` dispatch an **independent** unit of work to its
+own job while the reactor keeps running. Unlike `background`, they do not move
+the reactor itself — they are separate units with their own outcome and
+compensation.
+
 #### `async_step`: one step, dispatched on its own
 
 Where `background` relocates the *rest* of a reactor, `async_step` dispatches one
@@ -569,12 +579,12 @@ 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
+deadlocking. See [Background & Async Execution](documentation/background_and_async.md) for the full
 rules.
 
 ### Durability & Recovery
 
-Async reactors are durable: state lives in Redis, not in the job payload. Before
+Background 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
@@ -740,7 +750,7 @@ class ChargeReactor < RubyReactor::Reactor
   input :account_id
 
   # Respect upstream Stripe rate limits: 3/sec and 100/min.
-  # Async workers snooze for exactly retry_after seconds instead of
+  # Background workers snooze for exactly retry_after seconds instead of
   # consuming the backend's retry budget.
   with_rate_limit(
     limits: { second: 3, minute: 100 }
@@ -753,7 +763,7 @@ class ChargeReactor < RubyReactor::Reactor
 end
 
 class OrderedTransactionReactor < RubyReactor::Reactor
-  async
+  background all: true
   input :account_id
   input :transaction
 
@@ -794,12 +804,12 @@ class ChargeReactor < RubyReactor::Reactor
 end
 ```
 
-Referencing an unregistered name raises `RubyReactor::RateLimitRegistry::UnknownLimitError`. Named limits hit the same enforcement path as inline ones, so async snooze behavior is identical.
+Referencing an unregistered name raises `RubyReactor::RateLimitRegistry::UnknownLimitError`. Named limits hit the same enforcement path as inline ones, so background snooze behavior is identical.
 
 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).
+- **Background** (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::Halt` result instead — no steps run, no exception:
 
@@ -847,8 +857,8 @@ class DataProcessingReactor < RubyReactor::Reactor
     source input(:items)
     argument :item, element(:process_items)
     
-    # Enable async execution with batching
-    async true, batch_size: 50
+    # Run elements as background jobs, in batches
+    fan_out batch_size: 50
 
     step :transform do
       argument :item, input(:item)
@@ -860,9 +870,13 @@ class DataProcessingReactor < RubyReactor::Reactor
 end
 ```
 
-By using `async true` with `batch_size`, the system applies **Back Pressure** to efficiently manage resources. [Read more about Back Pressure & Resource Management](documentation/data_pipelines.md#back-pressure--resource-management).
+A `fan_out` map is a **hand-off point**: the reactor stops at the map (the caller gets a `DispatchResult`), every element runs as its own background job, and once all outcomes are collected the reactor resumes in a worker with the steps after the map. It fans out the same way when the reactor is already running in a worker (e.g. `background all: true`).
+
+By using `fan_out` with `batch_size`, the system applies **Back Pressure** to efficiently manage resources. [Read more about Back Pressure & Resource Management](documentation/data_pipelines.md#back-pressure--resource-management).
+
+`batch_size` is optional: with `fan_out` alone, RubyReactor fans out one worker per element (defaulting the batch size to the full source size) and aggregates the outcomes into a `ResultEnumerator` — convenient for small collections, but with no back pressure. See [`fan_out` Without `batch_size`](documentation/data_pipelines.md#fan_out-without-batch_size).
 
-`batch_size` is optional: with `async true` alone, RubyReactor fans out one worker per element (defaulting the batch size to the full source size) and aggregates the outcomes into a `ResultEnumerator` — convenient for small collections, but with no back pressure. See [Async Without `batch_size`](documentation/data_pipelines.md#async-without-batch_size).
+> **Breaking change:** `async true` inside a `map` block has been **removed** — it read like `async_step`/`async_reactor`, which dispatch independent units the reactor does not stop for. It now raises at class-definition time. The exact replacement is `fan_out` (`fan_out batch_size: N`).
 
 #### Map with Dynamic Source (ActiveRecord)
 
@@ -878,7 +892,7 @@ map :archive_old_users do
   end
   
   argument :user, element(:archive_old_users)
-  async true, batch_size: 100
+  fan_out batch_size: 100
 
   step :archive do
     argument :user, input(:user)
@@ -1426,8 +1440,8 @@ Learn about the fundamental building blocks of RubyReactor: Reactors, Steps, Con
 ### [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.
 
-### [Async Reactors](documentation/async_reactors.md)
-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.
+### [Background & Async Execution](documentation/background_and_async.md)
+Explore the ways to move work off the calling process: background execution (`background all: true` and the `background after:`/`before:` hand-off) and async units (`async_step`, `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.
@@ -1436,7 +1450,7 @@ Discover how to build complex, modular workflows by composing reactors within ot
 Master the `map` feature for processing collections. Learn about parallel execution, batch processing for large datasets, and error handling strategies like fail-fast vs. partial result collection.
 
 ### [Retry Configuration](documentation/retry_configuration.md)
-Configure robust retry policies for your steps. This guide details the available backoff strategies (exponential, linear, fixed), how to configure retries at the reactor or step level, and how async retries work without blocking workers.
+Configure robust retry policies for your steps. This guide details the available backoff strategies (exponential, linear, fixed), how to configure retries at the reactor or step level, and how background retries work without blocking workers.
 
 ### [Interrupts](documentation/interrupts.md)
 Learn how to pause and resume reactors to handle long-running processes, manual approvals, and asynchronous callbacks. Patterns for correlation IDs, timeouts, and payload validation.
@@ -1446,11 +1460,11 @@ 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 `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.
+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-background 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)
 
-Hook into the execution lifecycle with observer middlewares. Covers the full set of lifecycle events (reactor, step, retry, compensation/undo, async hand-off, locks/semaphores), writing and registering custom middlewares (global and per-reactor), and the built-in `RubyReactor::OpenTelemetry` tracing middleware — span structure, input/argument redaction, distributed trace propagation across async/retry boundaries, and custom exporters.
+Hook into the execution lifecycle with observer middlewares. Covers the full set of lifecycle events (reactor, step, retry, compensation/undo, background hand-off, locks/semaphores), writing and registering custom middlewares (global and per-reactor), and the built-in `RubyReactor::OpenTelemetry` tracing middleware — span structure, input/argument redaction, distributed trace propagation across background/retry boundaries, and custom exporters.
 
 ### Examples
 - [Order Processing](documentation/examples/order_processing.md) - Complete order processing workflow example
@@ -1470,7 +1484,7 @@ Hook into the execution lifecycle with observer middlewares. Covers the full set
 - [ ] Multiple storage adapters
   - [X] Redis
   - [ ] ActiveRecord
-- [X] Multiple Async adapters
+- [X] Multiple background job adapters
   - [X] Sidekiq
   - [X] ActiveJob
 - [X] OpenTelemetry support

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

@@ -10,13 +10,13 @@ module RubyReactor
         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::DispatchResult.new(job_id: job_id, intermediate_results: intermediate_results,
-                                       execution_id: context_id)
+                                          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::DispatchResult.new(job_id: job_id, intermediate_results: intermediate_results,
-                                       execution_id: context_id)
+                                          execution_id: context_id)
         end
 
         # One `async_step`'s work, dispatched as its own independent unit. The

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

@@ -10,13 +10,13 @@ module RubyReactor
         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::DispatchResult.new(job_id: job_id, intermediate_results: intermediate_results,
-                                       execution_id: context_id)
+                                          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::DispatchResult.new(job_id: job_id, intermediate_results: intermediate_results,
-                                       execution_id: context_id)
+                                          execution_id: context_id)
         end
 
         # One `async_step`'s work, dispatched as its own independent unit. The

data/lib/ruby_reactor/dsl/map_builder.rb

@@ -20,7 +20,7 @@ module RubyReactor
         end
         @reactor = reactor
         @argument_mappings = {}
-        @async = false
+        @fan_out = false
         @strict_ordering = true
         @batch_size = nil
         @source_enumerable = nil
@@ -40,9 +40,28 @@ module RubyReactor
                              end
       end
 
-      def async(async = true, batch_size: nil)
-        @async = async
-        @batch_size = batch_size if batch_size
+      # Run every element as its own background job. `batch_size` caps how many
+      # element jobs are enqueued at a time (back pressure); without it the whole
+      # source fans out at once. A fan-out map is a hand-off point: the reactor
+      # stops at the map and resumes in a worker once the collector has every
+      # element's outcome.
+      def fan_out(enabled = true, batch_size: nil)
+        @fan_out = enabled
+        self.batch_size(batch_size) unless batch_size.nil?
+      end
+
+      # `async` on a map named element fan-out with the word that now means
+      # `async_step` / `async_reactor` — independent units the reactor does not
+      # stop for. A fan-out map does stop the reactor, so it gets its own word.
+      def async(*)
+        raise RubyReactor::Error::DeprecatedDslError.new(
+          "`async` inside a `map` block has been removed: it read as `async_step`/`async_reactor`, which " \
+          "dispatch independent units, whereas a fan-out map hands the reactor off until every element " \
+          "finishes. Use `fan_out` instead (`fan_out batch_size: N` for back pressure) — note this also " \
+          "changes worker dispatch: each element now runs in its own background worker rather than being " \
+          "suppressed inline by `inline_async_execution` as the old `async true` was.",
+          step: @name
+        )
       end
 
       def strict_ordering(enabled = true)
@@ -50,6 +69,13 @@ module RubyReactor
       end
 
       def batch_size(size)
+        unless size.is_a?(Integer) && size.positive?
+          raise RubyReactor::Error::ValidationError.new(
+            "`batch_size` must be a positive Integer, got #{size.inspect}",
+            step: @name
+          )
+        end
+
         @batch_size = size
       end
 
@@ -98,7 +124,7 @@ module RubyReactor
             batch_size: { source: RubyReactor::Template::Value.new(@batch_size) },
             collect_block: { source: RubyReactor::Template::Value.new(@collect_block) },
             fail_fast: { source: RubyReactor::Template::Value.new(@fail_fast) },
-            async: { source: RubyReactor::Template::Value.new(@async) }
+            fan_out: { source: RubyReactor::Template::Value.new(@fan_out) }
           },
           run_block: nil,
           compensate_block: nil,

data/lib/ruby_reactor/map/helpers.rb

@@ -107,6 +107,15 @@ module RubyReactor
           )
 
           parent_context.current_step = nil
+
+          # Mark the context as a worker before resuming: resume_execution runs
+          # the collector's own worker (this call), not the reactor's normal
+          # caller. Without this, StepExecutor#handoff_at? (gated on
+          # `inline_async_execution`) re-evaluates any later `background`
+          # before:/after: cut point and enqueues a second hand-off, or runs an
+          # `after:` target here in the collector instead of the original
+          # dispatching worker.
+          parent_context.inline_async_execution = true
           executor.resume_execution
         end
 

data/lib/ruby_reactor/step/map_step.rb

@@ -9,7 +9,7 @@ module RubyReactor
         # Initialize map state in context if not present
         context.map_operations ||= {}
 
-        if should_run_async?
+        if fan_out?
           run_async(context.current_step)
         else
           run_inline
@@ -69,10 +69,15 @@ module RubyReactor
 
       private
 
-      def should_run_async?
-        return false if context.inline_async_execution
+      # Fans out anywhere except inside a map element: an element's result and
+      # the map's completion counter are tracked by its own ElementExecutor job,
+      # so a nested hand-off there would escape that tracking. A reactor worker
+      # (`background`, collector resume, `async_reactor` child) fans out as the
+      # caller would — the collector resumes the reactor in a worker either way.
+      def fan_out?
+        return false if context.map_metadata || context.root_context&.map_metadata
 
-        inputs[:async]
+        inputs[:fan_out]
       end
 
       def run_inline

data/lib/ruby_reactor/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module RubyReactor
-  VERSION = "0.8.0"
+  VERSION = "0.8.1"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ruby_reactor
 version: !ruby/object:Gem::Version
-  version: 0.8.0
+  version: 0.8.1
 platform: ruby
 authors:
 - Artur