ruby_reactor 0.8.1 → 0.8.3

data/lib/ruby_reactor/retry_context.rb

@@ -3,13 +3,14 @@
 module RubyReactor
   # Tracks retry attempts and state for steps in async execution
   class RetryContext
-    attr_accessor :step_attempts, :current_step, :failure_reason, :next_retry_at
+    attr_accessor :step_attempts, :current_step, :failure_reason, :next_retry_at, :contention_attempts
 
     def initialize
       @step_attempts = {}
       @current_step = nil
       @failure_reason = nil
       @next_retry_at = nil
+      @contention_attempts = {}
     end
 
     def increment_attempt_for_step(step_name)
@@ -18,6 +19,16 @@ module RubyReactor
       @step_attempts[step_name] += 1
     end
 
+    # Undoes one `increment_attempt_for_step` — called at the start of a
+    # contention park (Finding 2) so a busy key never eats the retry budget
+    # meant for genuine failures. Floored at 0.
+    def decrement_attempt_for_step(step_name)
+      step_name = step_name.to_s
+      return unless @step_attempts[step_name]
+
+      @step_attempts[step_name] = [@step_attempts[step_name] - 1, 0].max
+    end
+
     def attempts_for_step(step_name)
       step_name = step_name.to_s
       @step_attempts[step_name] || 0
@@ -28,11 +39,27 @@ module RubyReactor
       attempts < max_attempts
     end
 
+    def increment_contention_for_step(step_name)
+      step_name = step_name.to_s
+      @contention_attempts[step_name] ||= 0
+      @contention_attempts[step_name] += 1
+    end
+
+    def contention_attempts_for_step(step_name)
+      step_name = step_name.to_s
+      @contention_attempts[step_name] || 0
+    end
+
+    def clear_contention_for_step(step_name)
+      @contention_attempts.delete(step_name.to_s)
+    end
+
     def reset
       @step_attempts = {}
       @current_step = nil
       @failure_reason = nil
       @next_retry_at = nil
+      @contention_attempts = {}
     end
 
     def serialize_for_retry
@@ -40,7 +67,8 @@ module RubyReactor
         step_attempts: @step_attempts,
         current_step: @current_step,
         failure_reason: serialize_error(@failure_reason),
-        next_retry_at: @next_retry_at&.iso8601
+        next_retry_at: @next_retry_at&.iso8601,
+        contention_attempts: @contention_attempts
       }
     end
 
@@ -50,6 +78,7 @@ module RubyReactor
       context.current_step = data["current_step"]
       context.failure_reason = deserialize_error(data["failure_reason"])
       context.next_retry_at = data["next_retry_at"] ? Time.iso8601(data["next_retry_at"]) : nil
+      context.contention_attempts = data["contention_attempts"] || {}
       context
     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
@@ -18,6 +19,21 @@ module RubyReactor
           process_jobs: process_jobs
         )
       end
+
+      # Holds `key` as an EXTERNAL owner for the duration of the block, so a
+      # spec can assert against genuine lock contention (a step or reactor
+      # failing/parking because something else already holds its key)
+      # without reaching into `RubyReactor::Lock` or raw Redis calls itself.
+      # Released even if the block raises.
+      #
+      #   hold_lock("acct:1") { expect(ChargeStep.run({ account_id: 1 }, nil)).to be_a(RubyReactor::Failure) }
+      def hold_lock(key, owner: "spec", ttl: 30)
+        lock = RubyReactor::Lock.new(key, owner: owner, ttl: ttl, wait: 0, auto_extend: true)
+        lock.acquire
+        yield
+      ensure
+        lock&.release
+      end
     end
   end
 end

data/lib/ruby_reactor/rspec/matchers.rb

@@ -528,6 +528,98 @@ module RubyReactor
         end
       end
 
+      # Asserts a `:contention_park` trace entry exists for a step (US7-4,
+      # T054). Subject can be a `test_reactor` wrapper, a dispatch/find result
+      # (`.context`), or a raw `Context` (`.execution_trace`) — matching
+      # `have_run_step`'s subject flexibility. Use `.on(key)` to pin the key.
+      #
+      #   expect(result).to have_contended_at(:charge)
+      #   expect(result).to have_contended_at(:charge).on("acct:1")
+      ::RSpec::Matchers.define :have_contended_at do |step_name|
+        match do |subject|
+          trace = execution_trace_for(subject)
+          @entry = trace.find do |t|
+            t[:type].to_s == "contention_park" && t[:step].to_s == step_name.to_s &&
+              (@expected_key.nil? || t[:key].to_s == @expected_key.to_s)
+          end
+          !@entry.nil?
+        end
+
+        chain :on do |key|
+          @expected_key = key
+        end
+
+        def execution_trace_for(subject)
+          subject.ensure_executed! if subject.respond_to?(:ensure_executed!)
+          if subject.respond_to?(:reactor_instance)
+            subject.reactor_instance.context.execution_trace
+          elsif subject.respond_to?(:context)
+            subject.context.execution_trace
+          else
+            subject.execution_trace
+          end
+        end
+
+        failure_message do |_subject|
+          msg = "expected execution trace to contain a contention_park entry for step :#{step_name}"
+          msg += " on key #{@expected_key.inspect}" if @expected_key
+          msg
+        end
+
+        failure_message_when_negated do |_subject|
+          msg = "expected execution trace not to contain a contention_park entry for step :#{step_name}"
+          msg += " on key #{@expected_key.inspect}" if @expected_key
+          msg
+        end
+      end
+
+      # Asserts that a failed run reports a rollback (undo or compensation)
+      # of `step_name` that did not complete, on `Failure#rollback_failures`.
+      # Subject is a `Failure` or a `test_reactor` wrapper (its `result`).
+      #
+      #   expect(result).to have_rollback_failure(:charge)
+      #   expect(subject).to have_rollback_failure(:charge).for_key("acct:1").because(:coordination_unavailable)
+      #   expect(subject).not_to have_rollback_failure(:charge)
+      ::RSpec::Matchers.define :have_rollback_failure do |step_name|
+        match do |subject|
+          @entries = rollback_failures_for(subject)
+          @entries.any? do |e|
+            e[:step].to_s == step_name.to_s &&
+              (@expected_key.nil? || e[:key].to_s == @expected_key.to_s) &&
+              (@expected_reason.nil? || e[:reason].to_s == @expected_reason.to_s)
+          end
+        end
+
+        chain :for_key do |key|
+          @expected_key = key
+        end
+
+        chain :because do |reason|
+          @expected_reason = reason
+        end
+
+        def rollback_failures_for(subject)
+          subject.ensure_executed! if subject.respond_to?(:ensure_executed!)
+          actual = subject.respond_to?(:result) ? subject.result : subject
+          actual.respond_to?(:rollback_failures) ? actual.rollback_failures : []
+        end
+
+        def expectation_text(step_name)
+          text = "a rollback failure for :#{step_name}"
+          text += " on key #{@expected_key.inspect}" if @expected_key
+          text += " because #{@expected_reason.inspect}" if @expected_reason
+          text
+        end
+
+        failure_message do |_subject|
+          "expected #{expectation_text(step_name)}, got rollback_failures #{@entries.inspect}"
+        end
+
+        failure_message_when_negated do |_subject|
+          "expected no #{expectation_text(step_name)}, got rollback_failures #{@entries.inspect}"
+        end
+      end
+
       # Add more matchers as per plan
       # rubocop:enable Metrics/BlockLength
     end

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,46 @@ 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?
+          impl = step_config_orig.impl
+
+          if impl.respond_to?(:run_without_coordination)
+            ->(args, ctx) { impl.run_without_coordination(args, ctx) }
+          else
+            ->(args, ctx) { impl.run(args, ctx) }
+          end
+        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 +807,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/async_reactor_step.rb

@@ -15,6 +15,44 @@ module RubyReactor
     # ordered-lock nonce at ENQUEUE time (so ordering matches caller order), and
     # persist before enqueueing (F2).
     class AsyncReactorStep < RubyReactor::Step
+      class << self
+        # Exclusive keys this EXECUTION currently holds, read from the root
+        # context's registry. Shared by the `async_reactor` dispatch check
+        # below (via `detect_lock_deadlock`) and the `async_step` dispatch-time
+        # guard (`Executor::AsyncStepDispatch`, T034) — both hand off work to
+        # a process that will never share this execution's owner, so a key
+        # the execution currently holds would deadlock the dispatched unit.
+        def held_lock_keys(context)
+          root = context.root_context || context
+          Array(root.private_data[:held_lock_keys] || root.private_data["held_lock_keys"])
+        end
+
+        # `kind:` names what is being dispatched ("async_reactor" / "async_step")
+        # so the two guards share one message shape instead of drifting apart.
+        def deadlock_message(key, dispatched_name, context, kind: "async_reactor")
+          parent = context.reactor_class&.name || "the dispatching reactor"
+          <<~MSG.strip
+            #{kind} dispatch of #{dispatched_name || "<anonymous>"} would deadlock: it declares the lock key \
+            '#{key}', which #{parent} currently holds and will not release until it finishes.
+            The child would snooze forever, and if #{parent} later reads this child's result it would wait \
+            for work that can never start. Lock ownership is never shared across the async boundary — the \
+            two run concurrently, so sharing it would break mutual exclusion outright.
+            Fix, in order of preference:
+              1. Use `compose` instead of `async_reactor` if the child belongs inside #{parent}'s critical \
+            section and its result is needed — waiting for it means the work is sequential anyway.
+              2. Narrow the lock keys, if parent and child actually protect different resources.
+              3. Restructure so the locked reactor never reads the child's result — fire-and-forget, and \
+            verify in the child itself or in a successor reactor outside the lock window.#{async_step_remedy(kind)}
+          MSG
+        end
+
+        def async_step_remedy(kind)
+          return "" unless kind == "async_step"
+
+          "\n  4. Run the step inline (drop `async_step`) if it belongs inside the critical section."
+        end
+      end
+
       def run
         child_class = inputs[:async_reactor_class]
         child_inputs = build_child_inputs(inputs[:argument_mappings] || {})
@@ -60,13 +98,13 @@ module RubyReactor
       # loudly, at dispatch. Ordinary cross-execution contention on the same
       # key is unaffected and still snoozes normally.
       def detect_lock_deadlock(child_class, child_inputs)
-        held = held_lock_keys
+        held = self.class.held_lock_keys(context)
         return nil if held.empty?
 
         collision = child_lock_keys(child_class, child_inputs).find { |key| held.include?(key) }
         return nil unless collision
 
-        RubyReactor.Failure(deadlock_message(collision, child_class))
+        RubyReactor.Failure(self.class.deadlock_message(collision, child_class.name, context))
       end
 
       def child_lock_keys(child_class, child_inputs)
@@ -83,28 +121,6 @@ module RubyReactor
         keys.compact
       end
 
-      def held_lock_keys
-        root = context.root_context || context
-        Array(root.private_data[:held_lock_keys] || root.private_data["held_lock_keys"])
-      end
-
-      def deadlock_message(key, child_class)
-        parent = context.reactor_class&.name || "the dispatching reactor"
-        <<~MSG.strip
-          async_reactor dispatch of #{child_class.name || "<anonymous>"} would deadlock: it declares the \
-          lock key '#{key}', which #{parent} currently holds and will not release until it finishes.
-          The child would snooze forever, and if #{parent} later reads this child's result it would wait \
-          for work that can never start. Lock ownership is never shared across the async boundary — the \
-          two run concurrently, so sharing it would break mutual exclusion outright.
-          Fix, in order of preference:
-            1. Use `compose` instead of `async_reactor` if the child belongs inside #{parent}'s critical \
-          section and its result is needed — waiting for it means the work is sequential anyway.
-            2. Narrow the lock keys, if parent and child actually protect different resources.
-            3. Restructure so the locked reactor never reads the child's result — fire-and-forget, and \
-          verify in the child itself or in a successor reactor outside the lock window.
-        MSG
-      end
-
       # `RSpec::TestSubject`'s `async: false` clears the dispatch marker to run
       # the whole reactor in one process.
       def run_inline?