ruby_reactor 0.8.5 → 0.8.7

data/lib/ruby_reactor/reactor.rb

@@ -6,6 +6,9 @@ module RubyReactor
     include RubyReactor::Dsl::Reactor
     include RubyReactor::Dsl::Lockable
 
+    # Seconds a manual undo waits for the run's context lock (009 R-12).
+    UNDO_LOCK_WAIT = 5
+
     attr_reader :context, :result, :undo_trace, :execution_trace
 
     def self.find(id)
@@ -35,6 +38,14 @@ module RubyReactor
       find(context_id)
     end
 
+    # How a resume names an interrupt: a Symbol for one of the reactor's own,
+    # or its step path from the root (an Array: the compose step names, then
+    # the interrupt) for one inside a composed child (010).
+    def self.interrupt_key(step_name)
+      path = Array(step_name).map(&:to_sym)
+      path.one? ? path.first : path
+    end
+
     def self.continue(id:, payload:, step_name:, idempotency_key: nil)
       reactor = find(id)
       result = reactor.continue(payload: payload, step_name: step_name, idempotency_key: idempotency_key)
@@ -60,9 +71,12 @@ module RubyReactor
       reactor.cancel(reason)
     end
 
+    # A rollback that hands off at a fan-out map finishes in a worker, which
+    # applies `cancelled` itself (009 R-12).
     def self.undo(id)
       reactor = find(id)
-      reactor.undo
+      return if reactor.undo == :handed_off
+
       cancel(id: id, reason: "Undo triggered")
     end
 
@@ -148,6 +162,11 @@ module RubyReactor
         raise Error::ValidationError, "Cannot resume: context does not have a current step (was it interrupted?)"
       end
 
+      # A composed child pauses only inside its root, which owns the run (010 R-07).
+      if @context.private_data[:composed] || @context.private_data["composed"]
+        raise Error::ValidationError, "Cannot resume: #{self.class.name} is a composed child; continue its root run"
+      end
+
       if @context.cancelled
         raise Error::ValidationError,
               "Cannot resume: reactor has been cancelled (Reason: #{@context.cancellation_reason})"
@@ -161,19 +180,17 @@ module RubyReactor
               "Cannot resume: the reactor is #{@context.status}, not paused at an interrupt"
       end
 
-      validate_continue_step!(step_name)
+      path = Array(self.class.interrupt_key(step_name))
+      target_context, step_config = resolve_interrupt_target!(path)
 
-      if (failure = validate_continue_payload(payload, step_name))
-        return failure
-      end
+      failure = validate_continue_payload(payload, step_config, path)
+      return failure if failure
 
-      target_step = step_name
-      @context.set_result(target_step, payload)
+      target_context.set_result(path.last, payload) # the context that paused (010 R-06)
 
       # `interrupt :x, resume: :background` — payload is validated and stored
       # (above, in this process); the remaining work goes to a worker instead
       # of running inline in the delivering process.
-      step_config = self.class.steps[step_name.to_sym]
       if step_config.respond_to?(:background_resume?) && step_config.background_resume?
         return @result = enqueue_background_resume
       end
@@ -204,19 +221,49 @@ module RubyReactor
       RubyReactor::Failure(e.message, invalid_payload: true)
     end
 
+    # Undoes every completed step, under the run's context lock so no worker
+    # resumes it meanwhile (009 R-12). Returns `:handed_off` when a fan-out
+    # map's rollback continues in its element jobs: the run is then
+    # `rolling_back`, and a worker finishes it as `cancelled`.
     def undo
+      raise Error::ValidationError, "rollback already in progress" if @context.rolling_back?
+
+      lock = acquire_undo_lock
       executor = Executor.new(self.class, {}, @context)
-      executor.undo_all
+      @context.rollback = { "trigger" => "undo", "compensated" => true, "failures" => [] }
+      begin
+        executor.undo_all
+      rescue Error::RollbackHandedOff => e
+        @context.status = :rolling_back
+        executor.save_context
+        executor.hand_off_rollback!(e)
+        return :handed_off
+      end
+      @context.rollback = nil
       executor.save_context
+    ensure
+      lock&.release
     end
 
     def cancel(reason)
+      # `cancelled` is terminal: the steps before the map would never be undone.
+      raise Error::ValidationError, "rollback in progress; cannot cancel" if @context.rolling_back?
+
       @context.cancelled = true
       @context.cancellation_reason = reason
       @context.status = "cancelled"
       save_context
     end
 
+    # The interrupts this paused run can be resumed at (010 R-05): a Symbol
+    # for one of this reactor's own, and the step path from here (the compose
+    # step names, then the interrupt) for one inside a composed child.
+    def ready_interrupt_steps
+      return [] unless @context.status.to_s == "paused"
+
+      pending_interrupts(self.class, @context, [])
+    end
+
     def validate!
       # Validate reactor configuration
       validate_steps!
@@ -235,6 +282,18 @@ module RubyReactor
       save_context
     end
 
+    # Raises `Lock::AcquisitionError` while a live run or rollback holds it.
+    # Skipped in inline job-testing mode, as `Executor#acquire_context_lock`.
+    def acquire_undo_lock
+      return if defined?(Sidekiq::Testing) && Sidekiq::Testing.respond_to?(:inline?) && Sidekiq::Testing.inline?
+
+      lock = RubyReactor::Lock.new("async:#{@context.context_id}", owner: SecureRandom.uuid,
+                                                                   ttl: configuration.context_lock_ttl,
+                                                                   wait: UNDO_LOCK_WAIT)
+      lock.acquire
+      lock
+    end
+
     def validate_steps!
       return unless self.class.steps.empty?
 
@@ -395,39 +454,69 @@ module RubyReactor
       @undo_trace = executor.undo_trace
     end
 
-    def validate_continue_step!(step_name)
-      return if step_name.to_s == @context.current_step.to_s
+    # The context that paused at the interrupt `path` names, and that
+    # interrupt's config. A one-name path is a step of this reactor; a longer
+    # one names compose steps from here down, then the interrupt (010 R-05).
+    def resolve_interrupt_target!(path)
+      pending = ready_interrupt_steps
+      key = path.one? ? path.first : path
+      unless pending.include?(key)
+        raise Error::ValidationError,
+              "Cannot resume: expected step '#{@context.current_step}' " \
+              "or ready steps #{pending.inspect} but got '#{key}'"
+      end
+
+      target = path[0...-1].reduce(@context) { |context, name| paused_child(context, name) }
+      [target, target.reactor_class.steps[path.last]]
+    end
 
-      # Build graph to check if step is ready
-      graph_manager = Executor::GraphManager.new(self.class, DependencyGraph.new, @context)
+    def pending_interrupts(reactor_class, context, prefix)
+      graph_manager = Executor::GraphManager.new(reactor_class, DependencyGraph.new, context)
       graph_manager.build_and_validate!
       graph_manager.mark_completed_steps_from_context
-      ready_steps = graph_manager.dependency_graph.ready_steps.map(&:name).map(&:to_s)
 
-      return if ready_steps.include?(step_name.to_s)
+      # The interrupt a context paused at stays pending even once a resume
+      # stored its payload: that resume was contended and never ran.
+      ready = graph_manager.dependency_graph.ready_steps
+      paused_at = reactor_class.steps[context.current_step&.to_sym]
+      ready += [paused_at] if paused_at&.interrupt? && ready.none? { |step| step.name == paused_at.name }
+
+      ready.flat_map do |step_config|
+        name = step_config.name.to_sym
+        if step_config.respond_to?(:interrupt?) && step_config.interrupt?
+          [prefix.empty? ? name : prefix + [name]]
+        elsif (child = paused_child(context, name))
+          pending_interrupts(child.reactor_class, child, prefix + [name])
+        else
+          []
+        end
+      end
+    end
 
-      raise Error::ValidationError,
-            "Cannot resume: expected step '#{@context.current_step}' " \
-            "or ready steps #{ready_steps} but got '#{step_name}'"
+    def paused_child(context, step_name)
+      entry = context.composed_contexts[step_name] || context.composed_contexts[step_name.to_s]
+      child = entry.is_a?(Hash) && (entry[:context] || entry["context"])
+      child if child.is_a?(Context) && child.status.to_s == "paused"
     end
 
-    def validate_continue_payload(payload, step_name)
-      step_config = self.class.steps[step_name.to_sym]
+    def validate_continue_payload(payload, step_config, path)
       return unless step_config&.validation_schema
 
+      # A nested interrupt counts apart from a root step of the same name.
+      step_name = path.one? ? path.first : path.join(".").to_sym
+
       validation = step_config.validation_schema.call(payload)
 
       return unless validation.failure?
 
       # Track attempts
-      step_key = step_name.to_sym
       @context.private_data[:interrupt_attempts] ||= {}
-      @context.private_data[:interrupt_attempts][step_key] ||= 0
-      @context.private_data[:interrupt_attempts][step_key] += 1
+      @context.private_data[:interrupt_attempts][step_name] ||= 0
+      @context.private_data[:interrupt_attempts][step_name] += 1
 
       save_context # Persist the attempt count
 
-      current_attempts = @context.private_data[:interrupt_attempts][step_key]
+      current_attempts = @context.private_data[:interrupt_attempts][step_name]
       max_attempts = step_config.max_attempts
 
       if max_attempts != :infinity && current_attempts >= max_attempts

data/lib/ruby_reactor/rspec/active_job_helpers.rb

@@ -11,12 +11,16 @@ module RubyReactor
       PendingJob = Struct.new(:job_class, :raw) do
         def perform!
           ::ActiveJob::Base.queue_adapter.enqueued_jobs.delete(raw)
-          job_class.new(*raw[:args]).perform_now
+          job_class.new(*ActiveJobHelpers.arguments(raw)).perform_now
         end
 
         def args
           raw[:args]
         end
+
+        # The Sidekiq `PendingJob`'s name for it, so step-wise drains read the
+        # same on both backends (009 U4).
+        alias_method :worker_class, :job_class
       end
 
       def self.test_adapter?
@@ -37,11 +41,18 @@ module RubyReactor
 
           queue.dup.each do |job|
             queue.delete(job)
-            job[:job].new(*job[:args]).perform_now
+            job[:job].new(*arguments(job)).perform_now
           end
         end
       end
 
+      # The test adapter keeps a job's arguments serialized; a real backend
+      # hands `perform` the deserialized ones (a job requeueing its own
+      # arguments would otherwise re-serialize ActiveJob's markers).
+      def self.arguments(raw)
+        ::ActiveJob::Arguments.deserialize(raw[:args])
+      end
+
       def self.pending_async_jobs
         return [] unless test_adapter?
 

data/lib/ruby_reactor/rspec/matchers.rb

@@ -4,8 +4,10 @@ module RubyReactor
   module RSpec
     # rubocop:disable Metrics/ModuleLength
     module Matchers
+      extend ::RSpec::Matchers::DSL
+
       # rubocop:disable Metrics/BlockLength
-      ::RSpec::Matchers.define :be_success do
+      matcher :be_success do
         match do |subject|
           subject.ensure_executed! if subject.respond_to?(:ensure_executed!)
           subject.success?
@@ -63,7 +65,7 @@ module RubyReactor
         end
       end
 
-      ::RSpec::Matchers.define :be_failure do
+      matcher :be_failure do
         match do |subject|
           subject.ensure_executed! if subject.respond_to?(:ensure_executed!)
           subject.failure?
@@ -74,7 +76,7 @@ module RubyReactor
         end
       end
 
-      ::RSpec::Matchers.define :have_run_step do |step_name|
+      matcher :have_run_step do |step_name|
         match do |subject|
           subject.ensure_executed!
           @trace = subject.reactor_instance.context.execution_trace
@@ -127,7 +129,7 @@ module RubyReactor
         end
       end
 
-      ::RSpec::Matchers.define :have_retried_step do |step_name|
+      matcher :have_retried_step do |step_name|
         match do |subject|
           subject.ensure_executed!
           attempts = subject.reactor_instance.context.retry_context.attempts_for_step(step_name)
@@ -151,7 +153,7 @@ module RubyReactor
         end
       end
 
-      ::RSpec::Matchers.define :have_validation_error do |field|
+      matcher :have_validation_error do |field|
         match do |subject|
           subject.ensure_executed!
           return false unless subject.failure?
@@ -173,7 +175,7 @@ module RubyReactor
       end
 
       # Matcher to check if reactor is paused at an interrupt
-      ::RSpec::Matchers.define :be_paused do
+      matcher :be_paused do
         match do |subject|
           subject.ensure_executed!
           subject.paused?
@@ -188,53 +190,69 @@ module RubyReactor
         end
       end
 
+      # A run whose rollback handed off at a fan-out map and has not finished
+      # (009): its element rollback jobs are still pending.
+      matcher :be_rolling_back do
+        match do |subject|
+          subject.ensure_executed!
+          subject.rolling_back?
+        end
+
+        failure_message do |subject|
+          "expected reactor to be rolling back, but status was #{subject.reactor_instance.context.status}"
+        end
+
+        failure_message_when_negated do |_subject|
+          "expected reactor not to be rolling back, but it is"
+        end
+      end
+
       # Matcher to check if reactor is paused at a specific interrupt step
       # Works with both single and multiple concurrent interrupts
-      ::RSpec::Matchers.define :be_paused_at do |*step_names|
+      matcher :be_paused_at do |*step_names|
+        # A step inside a composed child is named by its path, e.g. `[:fulfil, :approve]`.
+        expected = -> { step_names.map { |name| RubyReactor::Reactor.interrupt_key(name).inspect }.join(", ") }
+
         match do |subject|
           subject.ensure_executed!
           return false unless subject.paused?
 
           ready_steps = subject.ready_interrupt_steps
-          step_names.all? { |name| ready_steps.include?(name.to_sym) }
+          step_names.all? { |name| ready_steps.include?(RubyReactor::Reactor.interrupt_key(name)) }
         end
 
         failure_message do |subject|
           if subject.paused?
-            ready_steps = subject.ready_interrupt_steps
-            if step_names.size == 1
-              "expected reactor to be paused at :#{step_names.first}, " \
-                "but ready interrupt steps are: #{ready_steps.inspect}"
-            else
-              "expected reactor to be paused at #{step_names.map { |s| ":#{s}" }.join(", ")}, " \
-                "but ready interrupt steps are: #{ready_steps.inspect}"
-            end
+            "expected reactor to be paused at #{expected.call}, " \
+              "but ready interrupt steps are: #{subject.ready_interrupt_steps.inspect}"
           else
-            "expected reactor to be paused at #{step_names.map { |s| ":#{s}" }.join(", ")}, " \
+            "expected reactor to be paused at #{expected.call}, " \
               "but status was #{subject.reactor_instance.context.status}"
           end
         end
 
         failure_message_when_negated do |_subject|
-          "expected reactor not to be paused at #{step_names.map { |s| ":#{s}" }.join(", ")}, but it is"
+          "expected reactor not to be paused at #{expected.call}, but it is"
         end
       end
 
       # Matcher to check the exact set of ready interrupt steps
-      ::RSpec::Matchers.define :have_ready_interrupts do |*expected_steps|
+      matcher :have_ready_interrupts do |*expected_steps|
+        # A step inside a composed child is named by its path, e.g. `[:fulfil, :approve]`.
+        expected = -> { expected_steps.map { |name| RubyReactor::Reactor.interrupt_key(name) } }
+
         match do |subject|
           subject.ensure_executed!
           return false unless subject.paused?
 
-          actual_steps = subject.ready_interrupt_steps.sort
-          expected = expected_steps.map(&:to_sym).sort
-          actual_steps == expected
+          # Symbols and paths (Arrays) do not compare: sort by their inspect.
+          subject.ready_interrupt_steps.sort_by(&:inspect) == expected.call.sort_by(&:inspect)
         end
 
         failure_message do |subject|
           if subject.paused?
             actual_steps = subject.ready_interrupt_steps
-            "expected ready interrupt steps to be #{expected_steps.map { |s| ":#{s}" }}, " \
+            "expected ready interrupt steps to be #{expected.call}, " \
               "but got #{actual_steps.inspect}"
           else
             "expected reactor to be paused with ready interrupt steps, " \
@@ -244,7 +262,7 @@ module RubyReactor
 
         failure_message_when_negated do |subject|
           actual_steps = subject.ready_interrupt_steps
-          "expected ready interrupt steps not to be #{expected_steps.map { |s| ":#{s}" }}, " \
+          "expected ready interrupt steps not to be #{expected.call}, " \
             "but it was #{actual_steps.inspect}"
         end
       end
@@ -277,7 +295,7 @@ module RubyReactor
       #   expect(result).to be_halted
       #   expect(result).to be_halted.because(:period)
       #   expect(result).to be_halted.at_step(:second)
-      ::RSpec::Matchers.define :be_halted do
+      matcher :be_halted do
         match do |subject|
           subject.ensure_executed! if subject.respond_to?(:ensure_executed!)
           actual = subject.respond_to?(:result) ? subject.result : subject
@@ -320,7 +338,7 @@ module RubyReactor
       # Examples:
       #   expect(result).to be_skipped
       #   expect(subject).to be_skipped.at_step(:maybe_sync)
-      ::RSpec::Matchers.define :be_skipped do
+      matcher :be_skipped do
         match do |subject|
           subject.ensure_executed! if subject.respond_to?(:ensure_executed!)
           actual = subject.respond_to?(:result) ? subject.result : subject
@@ -367,7 +385,7 @@ module RubyReactor
       #
       #   expect("order:42").to be_locked
       #   expect("order:42").to be_locked.by("ctx-abc")
-      ::RSpec::Matchers.define :be_locked do
+      matcher :be_locked do
         match do |key|
           info = Matchers.coordination_adapter.lock_info("lock:#{key}")
           next false unless info
@@ -400,7 +418,7 @@ module RubyReactor
       # user-provided semaphore name (without the "semaphore:" prefix).
       #
       #   expect("api_limit").to have_available_tokens(3)
-      ::RSpec::Matchers.define :have_available_tokens do |expected|
+      matcher :have_available_tokens do |expected|
         match do |name|
           Matchers.coordination_adapter.semaphore_state(name)[:available] == expected
         end
@@ -415,7 +433,7 @@ module RubyReactor
       # Asserts the number of currently-checked-out semaphore tokens.
       #
       #   expect("api_limit").to have_held_tokens(2)
-      ::RSpec::Matchers.define :have_held_tokens do |expected|
+      matcher :have_held_tokens do |expected|
         match do |name|
           Matchers.coordination_adapter.semaphore_state(name)[:held] == expected
         end
@@ -434,7 +452,7 @@ module RubyReactor
       #
       #   expect("stripe:42").to have_rate_limit_count(3).for(:second)
       #   expect("stripe:42").to have_rate_limit_count(1).for(:minute).since(started_at)
-      ::RSpec::Matchers.define :have_rate_limit_count do |expected|
+      matcher :have_rate_limit_count do |expected|
         match do |key_base|
           raise ArgumentError, "have_rate_limit_count requires .for(period)" unless @period
 
@@ -458,7 +476,7 @@ module RubyReactor
       # Asserts that a `with_period` bucket has been marked. Use `.for(period)`.
       #
       #   expect("daily_report:7").to be_period_marked.for(:day)
-      ::RSpec::Matchers.define :be_period_marked do
+      matcher :be_period_marked do
         match do |key_base|
           raise ArgumentError, "be_period_marked requires .for(period)" unless @period
 
@@ -482,7 +500,7 @@ module RubyReactor
       # the user-provided ordered_lock key (without the `ordered_lock:` prefix).
       #
       #   expect("orders:42").to have_ordered_lock_next(3)
-      ::RSpec::Matchers.define :have_ordered_lock_next do |expected|
+      matcher :have_ordered_lock_next do |expected|
         match { |key| Matchers.coordination_adapter.ordered_lock_peek(key)[:next] == expected }
 
         failure_message do |key|
@@ -495,7 +513,7 @@ module RubyReactor
       # Asserts the last-advanced cursor for an ordered_lock key.
       #
       #   expect("orders:42").to have_ordered_lock_last_completed(2)
-      ::RSpec::Matchers.define :have_ordered_lock_last_completed do |expected|
+      matcher :have_ordered_lock_last_completed do |expected|
         match do |key|
           Matchers.coordination_adapter.ordered_lock_peek(key)[:last_completed] == expected
         end
@@ -511,7 +529,7 @@ module RubyReactor
       # Order-insensitive — the matcher sorts both sides.
       #
       #   expect("orders:42").to have_ordered_lock_in_flight(2, 3)
-      ::RSpec::Matchers.define :have_ordered_lock_in_flight do |*expected|
+      matcher :have_ordered_lock_in_flight do |*expected|
         match do |key|
           actual = Matchers.coordination_adapter.ordered_lock_peek(key)[:in_flight].sort
           actual == expected.flatten.map(&:to_i).sort
@@ -528,7 +546,7 @@ module RubyReactor
       # in-flight nonces. After a clean drain `peek` returns all zeros.
       #
       #   expect("orders:42").to be_ordered_lock_drained
-      ::RSpec::Matchers.define :be_ordered_lock_drained do
+      matcher :be_ordered_lock_drained do
         match do |key|
           state = Matchers.coordination_adapter.ordered_lock_peek(key)
           state[:next].zero? && state[:last_completed].zero? && state[:in_flight].empty?
@@ -551,7 +569,7 @@ module RubyReactor
       #
       #   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|
+      matcher :have_contended_at do |step_name|
         match do |subject|
           trace = execution_trace_for(subject)
           @entry = trace.find do |t|
@@ -596,7 +614,7 @@ module RubyReactor
       #   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|
+      matcher :have_rollback_failure do |step_name|
         match do |subject|
           @entries = rollback_failures_for(subject)
           @entries.any? do |e|

data/lib/ruby_reactor/rspec/sidekiq_helpers.rb

@@ -12,15 +12,18 @@ module RubyReactor
       # until the queues are empty. Recursive — handles jobs that re-enqueue
       # themselves (e.g. ordered_lock snoozes) and worker chains that queue
       # additional jobs.
+      # Whichever test backend is active (Sidekiq fake mode or the ActiveJob
+      # `:test` adapter), via `AsyncTestHelpers`.
       def drain_async_jobs(max_iterations: 100)
-        SidekiqHelpers.drain_async_jobs(max_iterations: max_iterations)
+        AsyncTestHelpers.drain_async_jobs(max_iterations: max_iterations)
       end
 
       # All currently-pending async jobs, wrapped in `PendingJob` so callers
       # can perform individual jobs out-of-order (e.g. to assert
-      # ordered_lock's snooze behavior) without touching Sidekiq internals.
+      # ordered_lock's snooze behavior) without touching backend internals.
+      # `worker_class` names the job's class on either backend.
       def pending_async_jobs
-        SidekiqHelpers.pending_async_jobs
+        AsyncTestHelpers.pending_async_jobs
       end
 
       PendingJob = Struct.new(:worker_class, :raw) do
@@ -39,6 +42,7 @@ module RubyReactor
           RubyReactor::Adapters::Sidekiq::Worker,
           RubyReactor::Adapters::Sidekiq::MapElementWorker,
           RubyReactor::Adapters::Sidekiq::MapCollectorWorker,
+          RubyReactor::Adapters::Sidekiq::MapElementRollbackWorker,
           RubyReactor::Adapters::Sidekiq::StepWorker
         ]
       end

data/lib/ruby_reactor/rspec/test_subject.rb

@@ -351,14 +351,14 @@ module RubyReactor
           RubyReactor::Success.new(val)
         when "halted", "skipped" # "skipped" is the legacy name for a halt
           halted_result(ctx)
-        when "running"
+        when "running", "rolling_back"
           # Try to determine if it is truly running or if we just missed the completion
           if @process_jobs && AsyncTestHelpers.active?
             # Force one more check
             process_pending_jobs
             # Reload status
             @reactor_instance = @reactor_class.find(@reactor_instance.context.context_id)
-            return result unless @reactor_instance.context.status.to_s == "running"
+            return result unless %w[running rolling_back].include?(@reactor_instance.context.status.to_s)
           end
 
           # If still running, return a Pending/Running result instead of nil
@@ -405,6 +405,13 @@ module RubyReactor
         @reactor_instance.context.status.to_s == "paused"
       end
 
+      # Whether the run's rollback handed off at a fan-out map and has not
+      # finished (009). Reloads, so it reflects jobs performed since.
+      def rolling_back?
+        ensure_executed!
+        @reactor_instance.context.status.to_s == "rolling_back"
+      end
+
       # Get the current step where the reactor is paused (interrupt step)
       # Note: When multiple interrupts are ready, this returns just one of them.
       # Use `ready_interrupt_steps` to get all ready interrupt steps.
@@ -419,29 +426,19 @@ module RubyReactor
       # Get all ready interrupt steps (steps that can be resumed)
       # This is useful when multiple interrupts are waiting concurrently.
       #
-      # @return [Array<Symbol>] list of ready interrupt step names
+      # @return [Array<Symbol, Array<Symbol>>] the reactor's own interrupts by
+      #   name, and one inside a composed child by its step path
+      #   (e.g. `[:fulfil, :approve]`)
       def ready_interrupt_steps
         ensure_executed!
-        return [] unless paused?
-
-        # Build the dependency graph and get ready steps
-        graph = RubyReactor::DependencyGraph.new
-        graph_manager = RubyReactor::Executor::GraphManager.new(
-          @reactor_class, graph, @reactor_instance.context
-        )
-        graph_manager.build_and_validate!
-        graph_manager.mark_completed_steps_from_context
-
-        # Filter to only interrupt steps (using interrupt? predicate method)
-        ready = graph_manager.dependency_graph.ready_steps
-        ready.select { |step_config| step_config.respond_to?(:interrupt?) && step_config.interrupt? }
-             .map { |step_config| step_config.name.to_sym }
+        @reactor_instance.ready_interrupt_steps
       end
 
       # Resume a paused reactor with the given payload
       #
       # @param payload [Hash] The data to provide to the interrupt step
-      # @param step [Symbol, String, nil] The specific interrupt step to resume.
+      # @param step [Symbol, String, Array, nil] The specific interrupt step to resume,
+      #   or the step path of one inside a composed child (e.g. `[:fulfil, :approve]`).
       #   Required when multiple interrupts are ready. If not provided and only
       #   one interrupt is ready, that step will be used.
       # @return [TestSubject] self for chaining and introspection
@@ -476,10 +473,10 @@ module RubyReactor
 
         if step
           # User explicitly specified a step
-          step_sym = step.to_sym
+          step_sym = RubyReactor::Reactor.interrupt_key(step)
           unless ready_steps.include?(step_sym)
             raise RubyReactor::Error::ValidationError,
-                  "Cannot resume: step :#{step} is not ready. Ready steps: #{ready_steps.inspect}"
+                  "Cannot resume: step #{step_sym.inspect} is not ready. Ready steps: #{ready_steps.inspect}"
           end
           step_sym
         elsif ready_steps.size == 1
@@ -523,9 +520,12 @@ module RubyReactor
 
       def ensure_executed!
         run unless @executed
+        return unless %w[running rolling_back].include?(@reactor_instance.context.status.to_s)
 
+        # Not finished: jobs the spec performed itself may have moved it on.
+        @reactor_instance = @reactor_class.find(@reactor_instance.context.context_id)
         # Process jobs if status is running and processing is enabled
-        return unless @process_jobs && @reactor_instance.context.status.to_s == "running"
+        return unless @process_jobs && %w[running rolling_back].include?(@reactor_instance.context.status.to_s)
 
         process_pending_jobs
       end

data/lib/ruby_reactor/rspec.rb

@@ -21,15 +21,12 @@ module RubyReactor
     def self.configure(config)
       require_relative "rspec/step_executor_patch"
 
-      # `test_reactor` and the async-job helpers are only auto-included into
+      # Helpers, matchers and 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.
+      # `include RubyReactor::RSpec::Helpers` / `Matchers` explicitly.
       config.include RubyReactor::RSpec::Helpers, REACTOR_METADATA
-      config.include RubyReactor::RSpec::Matchers
+      config.include RubyReactor::RSpec::Matchers, REACTOR_METADATA
       config.include RubyReactor::RSpec::SidekiqHelpers, REACTOR_METADATA
 
       ::RubyReactor::Executor::StepExecutor.prepend(RubyReactor::RSpec::StepExecutorPatch)