ruby_reactor 0.8.0 → 0.8.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6e671a274b5dc3854189ab1f3c40ff4d7e307a567ed960dbad0be1405f05ff58
-  data.tar.gz: 0a44e9cf8dbed99b72762381300c4c503500d3025f21288e473eef377a28dbec
+  metadata.gz: 31b3ac286396e1d29f1bad40e87f4f55b8ecc3e6c715e6cfd2ca0496d9c8dd0c
+  data.tar.gz: d518e5aceb0e5fa6dd43007e1f324612c84a53528e73a76463db7ecb652f0a95
 SHA512:
-  metadata.gz: a39666bdba5d7c911589da0f30a12e29a9f5187c31a9a1bfb9ddc0c55aba26cac201db3e8083854f79858d6845ed98097589979873a0a4aa7cc8dfdaca635856
-  data.tar.gz: a5069c91a3942f1697a317baee2223b790b4262ca6d90f61a1b3aa0cd8b61ff9b199b7a05f58f791df11bd7b4336611907a6abd3cbce6ebfd007d9bc92949c4e
+  metadata.gz: 2e91db7e2c548b834f285fe514747bc407b29fbb4cdb10e4aef44b05ff556d518ccf77ad4d02fc3e097907d7298843bc32b7e5a57d4f4a8ae687795dc702fa71
+  data.tar.gz: 6a2252e7fdf4740f1d297f2855bb60f07c4b66e0a551c8d90e4394fd1acafd829098323d40afb4f9bc650c76a53818d76566c70f65c89c4b60ed11f9018a3d48

data/.release-please-manifest.json

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

data/CHANGELOG.md

@@ -129,6 +129,20 @@
   ordinary `nil` success, and `result(:step)` hands the reader the `Halt` — the same way it
   already hands over a `Failure`.
 
+## [0.8.2](https://github.com/arturictus/ruby_reactor/compare/v0.8.1...v0.8.2) (2026-09-22)
+
+
+### Features
+
+* Enhance mocking capabilities for nested reactors with scoped APIs and examples ([#58](https://github.com/arturictus/ruby_reactor/issues/58)) ([a462265](https://github.com/arturictus/ruby_reactor/commit/a462265b233f94f07fc39628b59a2bb038744fc9))
+
+## [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 +212,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)
@@ -1397,7 +1411,7 @@ end
 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
+RSpec.describe PaymentReactor, type: :reactor do
   it "processes payment successfully" do
     subject = test_reactor(PaymentReactor, order_id: 123, amount: 99.99)
     
@@ -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/rspec/helpers.rb

@@ -2,9 +2,10 @@
 
 module RubyReactor
   module RSpec
-    # Globally-included helpers. Only methods whose names clearly belong to
-    # RubyReactor's test surface live here (`test_reactor`). Sidekiq-coupled
-    # helpers live in `SidekiqHelpers` and are scoped to `type: :reactor`.
+    # Entry-point helpers (`test_reactor`), auto-included into examples tagged
+    # `type: :reactor`. Specs that want them outside that tag should
+    # `include RubyReactor::RSpec::Helpers` explicitly. Sidekiq-coupled helpers
+    # live in `SidekiqHelpers`, scoped the same way.
     module Helpers
       # Build a `TestSubject` around a reactor invocation. Captures the run for
       # later introspection via matchers; runs the reactor lazily on first

data/lib/ruby_reactor/rspec/test_subject.rb

@@ -48,44 +48,93 @@ module RubyReactor
         self
       end
 
-      # Fluent API for mocking nested map steps
-      # @example
-      #   reactor.map(:my_map).mock_step(:inner_step) { ... }
+      # Fluent/scoped API for mocking nested map steps.
+      #
+      # Without a block, returns a proxy scoped to this map step — chain
+      # `mock_step`/`failing_at`/`map`/`composed` on it to configure several
+      # things inside the same nested reactor:
+      #   reactor.map(:my_map).mock_step(:a) { ... }.mock_step(:b) { ... }
+      #
+      # With a block, the proxy is yielded and the *outer* subject is
+      # returned, so sibling nested reactors can be configured in the same
+      # chain without leaking scope between them:
+      #   test_reactor(Parent, params)
+      #     .map(:my_map) { |m| m.mock_step(:a) { ... } }
+      #     .composed(:other_child) { |c| c.mock_step(:b) { ... } }
       def map(step_name)
-        StepProxy.new(self, step_name)
+        proxy = StepProxy.new(self, [step_name])
+        return proxy unless block_given?
+
+        yield proxy
+        self
       end
 
-      # Fluent API for mocking nested compose steps
+      # Fluent/scoped API for mocking nested compose steps. See `#map` for
+      # the block vs. no-block behavior.
       # @example
-      #   reactor.compose(:my_sub_reactor).mock_step(:inner_step) { ... }
+      #   reactor.composed(:my_sub_reactor).mock_step(:inner_step) { ... }
       def composed(step_name)
         # If already executed, return the traversed subject
         return traverse_composed(step_name) if @executed
 
-        # Otherwise return a configuration proxy
-        StepProxy.new(self, step_name)
+        proxy = StepProxy.new(self, [step_name])
+        return proxy unless block_given?
+
+        yield proxy
+        self
       end
       alias compose composed
 
-      # Proxy class for fluent mocking configuration
+      # Proxy scoped to a nested step path (e.g. [:parent_compose, :child_map]).
+      # All mutating calls stay scoped to this path: `mock_step`/`failing_at`
+      # return the proxy itself (not the outer subject) so several inner
+      # steps of the *same* nested reactor can be chained without resetting
+      # scope back to the parent.
       class StepProxy
-        def initialize(subject, step_name)
+        def initialize(subject, step_path)
           @subject = subject
-          @step_name = step_name
+          @step_path = step_path
+        end
+
+        def mock_step(inner_step_name, *nested_steps, element_index: nil, &block)
+          @subject.mock_step(*@step_path, inner_step_name, *nested_steps, element_index: element_index, &block)
+          self
         end
 
-        def mock_step(inner_step_name, *nested_steps, &block)
-          @subject.mock_step(@step_name, inner_step_name, *nested_steps, &block)
-          @subject # Return subject to allow chaining or calling run
+        def failing_at(inner_step_name, *nested_steps, element_index: nil, &block)
+          @subject.failing_at(*@step_path, inner_step_name, *nested_steps, element_index: element_index, &block)
+          self
         end
 
-        # Support deep nesting?
         def map(inner_step_name)
-          StepProxy.new(@subject, [@step_name, inner_step_name].flatten)
+          proxy = self.class.new(@subject, @step_path + [inner_step_name])
+          return proxy unless block_given?
+
+          yield proxy
+          self
         end
 
         def composed(inner_step_name)
-          StepProxy.new(@subject, [@step_name, inner_step_name].flatten)
+          proxy = self.class.new(@subject, @step_path + [inner_step_name])
+          return proxy unless block_given?
+
+          yield proxy
+          self
+        end
+        alias compose composed
+
+        # Delegate everything else (run, success?, result, step_result, ...)
+        # to the outer subject, so a proxy can stand in for it wherever a
+        # `TestSubject` is expected (e.g. `expect(subject).to be_success`
+        # right after a non-block `.composed(:x).mock_step(:y)` chain).
+        def method_missing(name, ...)
+          return @subject.public_send(name, ...) if @subject.respond_to?(name)
+
+          super
+        end
+
+        def respond_to_missing?(name, include_private = false)
+          @subject.respond_to?(name, include_private) || super
         end
       end
 
@@ -491,12 +540,13 @@ module RubyReactor
       end
 
       def prepare_execution_class
+        @force_sync = @async == false
+
         # Even if no interceptors, we might need to subclass to force the whole
         # reactor to run in-process.
-        return @reactor_class if @interceptors.empty? && @async != false
+        return @reactor_class if @interceptors.empty? && !@force_sync
 
         interceptors = @interceptors
-        force_sync = @async == false
 
         execution_class = Class.new(@reactor_class) do
           # 1. Copy configuration from parent
@@ -514,19 +564,17 @@ module RubyReactor
           unique_name = "#{superclass.name}Mock#{object_id}"
           define_singleton_method(:name) { unique_name }
           RubyReactor::Registry.register(unique_name, self)
+        end
 
-          # 3. `async: false` / `run_async(false)` means "run this reactor's full
-          # logic here, in one process". Under the new DSL that is three things:
-          # suppress the `background` hand-off, and run `async_step` /
-          # `async_reactor` units inline instead of dispatching them.
-          if force_sync
-            @background_handoff = nil
-            @steps.each do |name, config|
-              next unless config.respond_to?(:async_dispatch?) && config.async_dispatch?
-
-              @steps[name] = config.clone.tap { |c| c.instance_variable_set(:@async_dispatch, nil) }
-            end
-          end
+        # 3. `async: false` / `run_async(false)` means "run this reactor's full
+        # logic here, in one process" — all the way down. Suppress this
+        # class's own `background` hand-off and `async_step`/`async_reactor`
+        # dispatch, then recursively do the same for every `compose`d/`map`ped
+        # child reactor (`apply_nested_interceptors` below clones from
+        # whatever class ends up wired in here, so it inherits this).
+        if @force_sync
+          strip_background_and_async!(execution_class)
+          force_sync_nested_reactors!(execution_class)
         end
 
         # 4. Apply Interceptors
@@ -535,6 +583,79 @@ module RubyReactor
         execution_class
       end
 
+      # Clears the background hand-off and any `async_dispatch` flags on a
+      # class's OWN steps. Nested composed/map children are separate classes,
+      # handled by `force_sync_nested_reactors!`.
+      def strip_background_and_async!(klass)
+        klass.instance_variable_set(:@background_handoff, nil)
+        klass.steps.each do |name, config|
+          next unless config.respond_to?(:async_dispatch?) && config.async_dispatch?
+
+          klass.steps[name] = config.clone.tap { |c| c.instance_variable_set(:@async_dispatch, nil) }
+        end
+      end
+
+      # Rewrites every `compose`/`map` step to target a subclass that has
+      # itself been force-synced (background/async stripped, and recursively,
+      # its own nested composed/map children), so `run_async(false)` reaches
+      # every level of a reactor tree instead of only the top one.
+      def force_sync_nested_reactors!(klass)
+        klass.steps.each do |step_name, step_config|
+          arg_key, source = nested_reactor_source(step_config)
+          next unless source
+
+          forced_child = build_forced_sync_class(source.value)
+
+          new_args = step_config.arguments.dup
+          new_args[arg_key] = new_args[arg_key].merge(source: RubyReactor::Template::Value.new(forced_child))
+          # A fan-out map is NOT an `async_dispatch` step — its hand-off lives in
+          # the `fan_out` argument, so `strip_background_and_async!` never sees
+          # it. Turn it off here (on the clone, leaving the original config
+          # untouched for normal runs) or `run_async(false)` would still
+          # dispatch element jobs and leave the reactor parked at the map.
+          if arg_key == :mapped_reactor_class && new_args[:fan_out]
+            new_args[:fan_out] = new_args[:fan_out].merge(source: RubyReactor::Template::Value.new(false))
+          end
+
+          new_step_config = step_config.clone
+          new_step_config.instance_variable_set(:@arguments, new_args)
+          klass.steps[step_name] = new_step_config
+        end
+      end
+
+      def nested_reactor_source(step_config)
+        return [nil, nil] unless step_config.respond_to?(:arguments)
+
+        args = step_config.arguments
+        # `async_reactor` is included: clearing its dispatch marker makes the
+        # child run inline, but inline means `child_class.run(...)` on the
+        # ORIGINAL class — whose own background/async steps would dispatch
+        # again. The child has to be force-synced too.
+        %i[mapped_reactor_class composed_reactor_class async_reactor_class].each do |arg_key|
+          source = args[arg_key]&.[](:source)
+          return [arg_key, source] if source.is_a?(RubyReactor::Template::Value)
+        end
+
+        [nil, nil]
+      end
+
+      def build_forced_sync_class(original_child_reactor)
+        child_class = Class.new(original_child_reactor) do
+          define_singleton_method(:name) { original_child_reactor.name }
+          @steps = superclass.steps.dup
+          @inputs = superclass.inputs.dup
+          @input_validations = superclass.input_validations.dup
+          @middlewares = superclass.middlewares.dup
+          @return_step = superclass.return_step
+          @background_handoff = superclass.background_handoff
+          @retry_defaults = superclass.instance_variable_get(:@retry_defaults)
+        end
+
+        strip_background_and_async!(child_class)
+        force_sync_nested_reactors!(child_class)
+        child_class
+      end
+
       def apply_interceptors(klass, interceptors)
         # Group interceptors by the current level step
         grouped = interceptors.group_by { |i| i[:step_path].first }
@@ -564,7 +685,7 @@ module RubyReactor
           direct_interceptors.each do |interceptor|
             case interceptor[:type]
             when :failure
-              apply_failure_interceptor(step_config, target_step)
+              apply_failure_interceptor(step_config, target_step, step_config_orig, interceptor)
             when :mock
               apply_mock_interceptor(step_config, target_step, step_config_orig, interceptor)
             end
@@ -595,9 +716,19 @@ module RubyReactor
 
         original_child_reactor = target_reactor_class_source.value
 
-        # Dynamically subclass the child reactor
+        # Dynamically subclass the child reactor.
+        #
+        # It needs a resolvable identity of its OWN: a fan-out map serializes
+        # only `mapped_reactor_class.name` into each element job, and the worker
+        # resolves that name back through `const_get` first. Keeping the
+        # original name would therefore resolve to the original, unmocked class
+        # in every element. Registering a unique name makes the fan-out payload
+        # (and the `element_reactor_class` that `#map_elements` traverses) point
+        # at THIS class.
         mocked_child_reactor = Class.new(original_child_reactor) do
-          define_singleton_method(:name) { original_child_reactor.name }
+          unique_name = "#{original_child_reactor.name || "AnonymousReactor"}Mock#{object_id}"
+          define_singleton_method(:name) { unique_name }
+          RubyReactor::Registry.register(unique_name, self)
           # Copy configuration
           @steps = superclass.steps.dup
           @inputs = superclass.inputs.dup
@@ -629,9 +760,40 @@ module RubyReactor
         step_config.arguments[arg_key][:source] = RubyReactor::Template::Value.new(mocked_child_reactor)
       end
 
-      def apply_failure_interceptor(step_config, target_step)
-        failure_impl = lambda do |_input, _context|
-          RubyReactor::Failure("Simulated failure at #{target_step}")
+      # The original run behavior for a step, used both as the fallback when
+      # `element_index` excludes the current map element and as the `original`
+      # callable a mock block can invoke.
+      def original_impl_for(step_config_orig, target_step)
+        if step_config_orig.has_run_block?
+          step_config_orig.run_block
+        elsif step_config_orig.has_impl?
+          ->(args, ctx) { step_config_orig.impl.run(args, ctx) }
+        else
+          ->(_, _) { raise "No implementation found for #{target_step}" }
+        end
+      end
+
+      # A map element's own context carries `map_metadata[:index]`. When an
+      # interceptor is scoped to one element via `element_index:`, only that
+      # element's context matches — everything else falls through to the
+      # original implementation.
+      def matches_element_index?(context, element_index)
+        return true if element_index.nil?
+
+        meta = context.map_metadata
+        meta && (meta[:index] == element_index || meta["index"] == element_index)
+      end
+
+      def apply_failure_interceptor(step_config, target_step, step_config_orig, interceptor)
+        element_index = interceptor[:conditions][:element_index]
+        original_impl = original_impl_for(step_config_orig, target_step)
+
+        failure_impl = lambda do |input, context|
+          if matches_element_index?(context, element_index)
+            RubyReactor::Failure("Simulated failure at #{target_step}")
+          else
+            original_impl.call(input, context)
+          end
         end
 
         step_config.instance_variable_set(:@run_block, failure_impl)
@@ -639,18 +801,13 @@ module RubyReactor
 
       def apply_mock_interceptor(step_config, target_step, step_config_orig, interceptor)
         mock_block = interceptor[:conditions][:block]
-
-        # Prepare original implementation call
-        original_impl = if step_config_orig.has_run_block?
-                          step_config_orig.run_block
-                        elsif step_config_orig.has_impl?
-                          ->(args, ctx) { step_config_orig.impl.run(args, ctx) }
-                        else
-                          ->(_, _) { raise "No implementation found for #{target_step}" }
-                        end
+        element_index = interceptor[:conditions][:element_index]
+        original_impl = original_impl_for(step_config_orig, target_step)
 
         # Create the new implementation that wraps the user block
         wrapper_impl = lambda do |args, context|
+          next original_impl.call(args, context) unless matches_element_index?(context, element_index)
+
           if mock_block.arity == 3
             mock_block.call(args, context, original_impl)
           else

data/lib/ruby_reactor/rspec.rb

@@ -21,7 +21,14 @@ module RubyReactor
     def self.configure(config)
       require_relative "rspec/step_executor_patch"
 
-      config.include RubyReactor::RSpec::Helpers
+      # `test_reactor` and the async-job helpers are only auto-included into
+      # examples tagged `type: :reactor`, so a host app's other specs keep a
+      # clean namespace. Specs that want them without the tag can
+      # `include RubyReactor::RSpec::Helpers` explicitly.
+      #
+      # Matchers stay unconditional: `::RSpec::Matchers.define` registers them
+      # globally at load time, so gating this include would not scope anything.
+      config.include RubyReactor::RSpec::Helpers, REACTOR_METADATA
       config.include RubyReactor::RSpec::Matchers
       config.include RubyReactor::RSpec::SidekiqHelpers, REACTOR_METADATA
 

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
@@ -86,8 +91,8 @@ module RubyReactor
         results = []
         fail_fast = inputs[:fail_fast].nil? || inputs[:fail_fast]
 
-        inputs[:source].each do |element|
-          result = execute_single_element(element)
+        inputs[:source].each_with_index do |element, index|
+          result = execute_single_element(element, index)
 
           # An element-level Halt propagates as a run halt: stop immediately
           # rather than being collected as a (nil) value.
@@ -104,7 +109,7 @@ module RubyReactor
         results
       end
 
-      def execute_single_element(element)
+      def execute_single_element(element, index)
         mapped_inputs = self.class.build_mapped_inputs(inputs[:argument_mappings] || {}, context, element)
         child_context = RubyReactor::Context.new(mapped_inputs, inputs[:mapped_reactor_class])
 
@@ -118,7 +123,7 @@ module RubyReactor
         child_context.map_metadata = {
           map_id: map_id,
           parent_reactor_class_name: context.reactor_class.name,
-          index: nil # Inline map execution doesn't track index in metadata currently, but could
+          index: index
         }
 
         # Store reference in composed_contexts so the UI knows where to find elements

data/lib/ruby_reactor/version.rb

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

data/specs/scoped_rspec_matchers.md

@@ -0,0 +1,158 @@
+# Scoping the RSpec matchers to `type: :reactor`
+
+## Goal
+
+`RubyReactor::RSpec.configure(config)` should add **nothing** to a host app's
+example groups unless they opt in with `type: :reactor`. Helpers already work
+that way. The 19 matchers do not — they are global the moment
+`ruby_reactor/rspec` is required, and moving them behind the tag needs a
+one-line-per-matcher change plus a migration.
+
+## Current state
+
+[lib/ruby_reactor/rspec.rb:20-42](../lib/ruby_reactor/rspec.rb#L20-L42):
+
+| Piece | Scoped to `type: :reactor`? |
+| --- | --- |
+| `Helpers` (`test_reactor`) | yes — `config.include …, REACTOR_METADATA` |
+| `SidekiqHelpers` (`drain_async_jobs`, `pending_async_jobs`) | yes |
+| `before(:each)` setup (fake mode, storage wipe, snooze reset) | yes |
+| `Matchers` (19 matchers) | **no** |
+| `StorageReset.install!`, `StepExecutor.prepend` | no — load-time monkeypatches, out of scope for this doc |
+
+## Why the `config.include` line does nothing today
+
+[matchers.rb](../lib/ruby_reactor/rspec/matchers.rb) declares every matcher as:
+
+```ruby
+module Matchers
+  ::RSpec::Matchers.define :be_success do
+    ...
+  end
+end
+```
+
+`define` is [`RSpec::Matchers::DSL#define`](https://github.com/rspec/rspec-expectations/blob/main/lib/rspec/matchers/dsl.rb),
+and its entire body is a `define_method` **on the receiver**:
+
+```ruby
+def define(name, &declarations)
+  warn_about_block_args(name, declarations)
+  define_method name do |*expected, &block_arg|
+    RSpec::Matchers::DSL::Matcher.new(name, declarations, self, *expected, &block_arg)
+  end
+end
+alias_method :matcher, :define
+```
+
+The receiver is `::RSpec::Matchers`, which RSpec includes into *every* example
+group. So the matcher methods land in the global spec namespace at require
+time, and `RubyReactor::RSpec::Matchers` ends up an empty module — the
+`config.include RubyReactor::RSpec::Matchers` line in
+[rspec.rb:32](../lib/ruby_reactor/rspec.rb#L32) includes nothing. Adding
+`REACTOR_METADATA` to that line scopes nothing either.
+
+## The change
+
+Extend the DSL into **our** module, so `define_method` targets
+`RubyReactor::RSpec::Matchers`:
+
+```ruby
+module RubyReactor
+  module RSpec
+    module Matchers
+      extend ::RSpec::Matchers::DSL   # <- add
+
+      matcher :be_success do          # <- was ::RSpec::Matchers.define
+        ...
+      end
+    end
+  end
+end
+```
+
+Then gate the include:
+
+```ruby
+config.include RubyReactor::RSpec::Matchers, REACTOR_METADATA
+```
+
+Mechanically: one `extend` line, 19 `::RSpec::Matchers.define` →
+`matcher` rewrites (`sed` handles it), one changed line in `rspec.rb`, and the
+comment at [rspec.rb:29-30](../lib/ruby_reactor/rspec.rb#L29-L30) — which
+currently explains why matchers *can't* be scoped — deleted.
+
+Nothing inside the matcher bodies changes. `Matchers.coordination_adapter`
+([matchers.rb:260](../lib/ruby_reactor/rspec/matchers.rb#L260)) is called with
+an explicit receiver and resolves lexically at match time, so it is unaffected.
+
+### Verified
+
+A probe against this repo's `spec_helper`, with one matcher declared each way:
+
+```
+UNTAGGED scoped: expected :nope to respond to `probe_scoped?`   # not included -> falls through
+UNTAGGED global: GLOBAL-MATCHER-RAN: expected :ok, got :nope    # still global
+TAGGED   scoped: SCOPED-MATCHER-RAN: expected :ok, got :nope    # real matcher, chains and all
+```
+
+Note the first line: scoping a matcher out does **not** produce a
+`NoMethodError`. See below.
+
+## The trap: `be_*` / `have_*` fall through to a predicate matcher
+
+All 19 matcher names start with `be_` or `have_`, which is exactly the prefix
+RSpec's dynamic predicate matchers claim. Once a matcher is no longer in scope,
+`expect(x).to be_success` stops meaning "RubyReactor's `be_success`" and starts
+meaning "call `x.success?`". Two consequences:
+
+1. **`respond_to?(:be_success)` is not a scoping test.** It returns `true` in
+   any example group for any `be_*`/`have_*` name, because
+   `RSpec::Matchers#respond_to_missing?` claims the whole prefix. Test scoping
+   by running an expectation and reading the failure message (as the probe
+   above does), not by probing `respond_to?`.
+2. **Some call sites degrade silently rather than breaking.** `TestSubject` and
+   the result objects define `success?`, `failure?`, `paused?`, `halted?` and
+   `skipped?` ([test_subject.rb:388-405](../lib/ruby_reactor/rspec/test_subject.rb#L388-L405),
+   [ruby_reactor.rb:50-62](../lib/ruby_reactor.rb#L50-L62)), so an untagged
+   `expect(result).to be_success` keeps passing via the predicate — with a
+   generic failure message instead of the rich one in
+   [matchers.rb:14-23](../lib/ruby_reactor/rspec/matchers.rb#L14-L23), and
+   without the `ensure_executed!` nudge the real matcher does. Anything with a
+   chain (`have_run_step(:x).returning(y)`, `be_halted.because(:period)`,
+   `be_locked.by(owner)`) or a non-predicate name fails loudly instead.
+
+So the migration cost is not "find the red specs" — a suite can go green while
+quietly asserting something weaker. Grep for the matcher names rather than
+trusting a passing run.
+
+## Migration
+
+In this repo, 34 spec files use these matchers; 24 of them are not tagged
+`type: :reactor`. Most only need the tag added to the `RSpec.describe` line, the
+same edit made for `test_reactor` in `0a3ebdab`. Order of work:
+
+1. Rewrite `matchers.rb` to the DSL-extend form, leave the include ungated —
+   suite must stay green (proves the rewrite alone changes nothing).
+2. Gate the include, run the suite, tag the files that fail.
+3. Grep the 24 untagged files for matcher names and tag the rest by hand —
+   step 2 will not catch the silent-degradation cases above.
+4. Update [documentation/testing.md](../documentation/testing.md#L17-L35),
+   whose Setup section currently says matchers are available everywhere, and
+   the comment at [rspec.rb:29-30](../lib/ruby_reactor/rspec.rb#L29-L30).
+
+## Breaking change
+
+Downstream suites calling these matchers in untagged groups are affected, with
+the same silent-degradation caveat: a user's suite may stay green while
+asserting less. This warrants a `BREAKING CHANGE:` footer and a release note
+that names the fallback behavior explicitly, not just "matchers are now
+scoped".
+
+## Alternative considered
+
+Keep matchers global, on the grounds that `be_success` / `have_run_step` are
+already ambiguous with RSpec's predicate matchers and that a host app gains
+little from gating them. This costs nothing and breaks nobody — worth taking if
+the namespace complaint is theoretical rather than something a host app has
+actually hit.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ruby_reactor
 version: !ruby/object:Gem::Version
-  version: 0.8.0
+  version: 0.8.2
 platform: ruby
 authors:
 - Artur
@@ -289,6 +289,7 @@ files:
 - specs/deferred-003-step-lock-declarations/spec.md
 - specs/deferred-003-step-lock-declarations/tasks.md
 - specs/possible_feature.md
+- specs/scoped_rspec_matchers.md
 - teley/Dockerfile
 homepage: https://github.com/arturictus/ruby_reactor
 licenses: []