ruby_reactor 0.8.1 → 0.8.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0d5c03b684aeac0b3d682581e9746e59219622f07752a5b5e30b5381582c09c9
-  data.tar.gz: bccbbdf3eec2187481fba0c5d724b1b2b61d96a32c93139dcf5fcd20e42ff491
+  metadata.gz: 31b3ac286396e1d29f1bad40e87f4f55b8ecc3e6c715e6cfd2ca0496d9c8dd0c
+  data.tar.gz: d518e5aceb0e5fa6dd43007e1f324612c84a53528e73a76463db7ecb652f0a95
 SHA512:
-  metadata.gz: ab06166bc3462aa2cf8f4569015575feb7c37ae025022ae84b886dcc171040c2a89a88dbc69208c8b1ec84be6dd19c08c418915856a510506402e7ab72f26044
-  data.tar.gz: cfb0973443827d2d50572f834b1d9d2760464eab4290097b38c73465fcb7268f9e381d211b4a2fe1815f6bb410ac56ffa64c4f61ed17f0a765966392c50494a4
+  metadata.gz: 2e91db7e2c548b834f285fe514747bc407b29fbb4cdb10e4aef44b05ff556d518ccf77ad4d02fc3e097907d7298843bc32b7e5a57d4f4a8ae687795dc702fa71
+  data.tar.gz: 6a2252e7fdf4740f1d297f2855bb60f07c4b66e0a551c8d90e4394fd1acafd829098323d40afb4f9bc650c76a53818d76566c70f65c89c4b60ed11f9018a3d48

data/.release-please-manifest.json

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

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.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)
 
 

data/README.md

@@ -1411,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)
     

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

@@ -91,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.
@@ -109,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])
 
@@ -123,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.1"
+  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.1
+  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: []