ruby_reactor 0.8.6 → 0.8.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c59b0af2a9d34b620e3400cff78e0df3b2e580d1138b37ed5aee1b9e5a78f548
-  data.tar.gz: 4e3c2b92b6ae58797beae470b60c69015e15b2b8d6855ce710e71a999d0ae62f
+  metadata.gz: a0d1aa7711547d66d5a7f19acf5e0b13c7e208a9660d3f1714eb8df2e7eff004
+  data.tar.gz: a0b52b6139f80b5133f9585f39ff5fe227e46b34dfb9d1b8767bf4f068e5678f
 SHA512:
-  metadata.gz: a3ac367241909b09a5f0451b9278489776e7bedc56b506043c786892b86247a646b297a7c6192be6e5935b5e9a861f36e66e2f370a7c3e0741820cbcaa1ee409
-  data.tar.gz: 1fd3ff1f692008747021d11d5356613163a8c7777e33ead22260da4b3959bc5f6ec7fff3cb5928444815298011ff4b0e1e2e10e34c55a9781b98d9ab80893e40
+  metadata.gz: 5457e6cf85bb33a4bd12f00161d810a6dc491a590c3cefaaf2c5c967987d78e783e199c77bdff77d2b2745f569098c9492d07f4aebb0a7ad74f023bc5274f525
+  data.tar.gz: 58ad78fe9e8e1c1e6b8b7106c12c384534aae6db6747860202cfb38dd75e3922f35c88b65f91320cfaef9fb121b6b0cae63dce4f42c677a5ae7ee4c6b0ff91b6

data/.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "0.8.6"
+  ".": "0.8.7"
 }

data/.specify/feature.json

@@ -1,3 +1,3 @@
 {
-  "feature_directory": "specs/009-distributed-map-undo"
+  "feature_directory": "specs/010-interrupt-in-composed-child"
 }

data/CHANGELOG.md

@@ -241,6 +241,23 @@ Every breaking or shape-changing item of the rollback work, with what to change.
 
 ### Features
 
+* **An `interrupt` inside a composed child pauses the top-level run.** Before, the compose step
+  failed with `NoMethodError` and the run rolled back. Now the top-level run is stored `paused`, at
+  any compose depth and after a `fan_out` map in the child, and the paused result carries its id.
+  Resume it on the top-level class by the interrupt's step path, an Array of the compose step names
+  then the interrupt (`continue(id:, payload:, step_name: [:approval, :wait_for_manager])`), by id
+  or by the child interrupt's correlation id. Payload validation, `max_attempts`,
+  `resume: :background` and the resume guards apply as for a top-level interrupt. A resume
+  contended on the child's own `with_lock`/`with_semaphore` fails and rolls back the run. Only
+  contention on the top-level reactor's lock leaves it paused. `Reactor.undo`
+  of the paused run rolls back the child's completed steps, then the parent's. A composed child
+  refuses a `continue` of its own. New `Reactor#ready_interrupt_steps` lists the pending
+  interrupts (Symbols, and paths for nested ones). `be_paused_at`, `have_ready_interrupts` and
+  `TestSubject#resume(step:)` accept paths. A `continue` must now name a pending interrupt: naming
+  another ready step, which used to store the payload as that step's result, raises
+  `ValidationError`. An `interrupt` inside a `map` element now fails that element with "not
+  supported inside a map element" instead of `NoMethodError`.
+  See [Interrupts inside composed reactors](documentation/interrupts.md#interrupts-inside-composed-reactors).
 * **`fan_out` without `batch_size` is back-pressured: at most 50 element jobs per throw**
   (`RubyReactor::Map::DEFAULT_BATCH_SIZE`), forward and rollback. Before, every element was
   enqueued at once. A map of more than 50 elements with no declared `batch_size` now runs in
@@ -444,6 +461,13 @@ Every breaking or shape-changing item of the rollback work, with what to change.
 * Docs: a park keeps each level's lock without a second `:lock_acquired` only while the gap stays
   within the lock's `ttl`; a lapsed lock is acquired again.
 
+## [0.8.7](https://github.com/arturictus/ruby_reactor/compare/v0.8.6...v0.8.7) (2026-10-08)
+
+
+### Features
+
+* add support for interrupts inside composed children ([#71](https://github.com/arturictus/ruby_reactor/issues/71)) ([7be968e](https://github.com/arturictus/ruby_reactor/commit/7be968eb5dbfc6458e9419d8c6fddbf9d89cc80e))
+
 ## [0.8.6](https://github.com/arturictus/ruby_reactor/compare/v0.8.5...v0.8.6) (2026-10-08)
 
 

data/CLAUDE.md

@@ -1,5 +1,5 @@
 <!-- SPECKIT START -->
 For additional context about technologies to be used, project structure,
 shell commands, and other important information, read the current plan
-at specs/009-distributed-map-undo/plan.md
+at specs/010-interrupt-in-composed-child/plan.md
 <!-- SPECKIT END -->

data/README.md

@@ -704,6 +704,10 @@ ApprovalReactor.continue_by_correlation_id(
 )
 ```
 
+An interrupt inside a `compose`d child pauses the top-level run; resume it there by the step path,
+e.g. `step_name: [:approval, :wait_for_manager]`. See
+[Interrupts inside composed reactors](documentation/interrupts.md#interrupts-inside-composed-reactors).
+
 ### Locks, Semaphores & Ordered Locks
 
 Coordinate across processes with Redis-backed primitives:

data/lib/ruby_reactor/executor/compensation_manager.rb

@@ -41,7 +41,13 @@ module RubyReactor
         @rollback_failures.replace(Array(ContextSerializer.deserialize_value(list)))
       end
 
+      # A step that paused (a compose whose child hit an interrupt) is already
+      # on top as a partial run; its re-run replaces that entry, so the step is
+      # undone once (010 R-04).
+      # ponytail: assumes the paused step's entry is on top when it re-runs,
+      # which holds because a run stops at a pause and resumes at that step.
       def add_to_undo_stack(step_info)
+        undo_stack.pop if undo_stack.last && undo_stack.last[:step].name == step_info[:step].name
         @context.undo_stack << step_info
       end
 

data/lib/ruby_reactor/executor/result_handler.rb

@@ -27,6 +27,8 @@ module RubyReactor
           handle_retries_exhausted(step_config, result, resolved_arguments)
         when RubyReactor::Failure
           handle_failure(step_config, result, resolved_arguments)
+        when RubyReactor::InterruptResult
+          handle_interrupted(step_config, resolved_arguments)
         else
           handle_unknown_result(step_config, result, resolved_arguments)
         end
@@ -148,6 +150,20 @@ module RubyReactor
         result
       end
 
+      # A composed child paused at an interrupt (010): the step stays
+      # incomplete, and this run pauses on it. `with_step` cleared
+      # `current_step` on the way out; it is the run's resume cursor. The
+      # child's completed steps are only undone through this step, so it joins
+      # the undo stack as a partial run, as an interrupted compose does (R-04).
+      def handle_interrupted(step_config, resolved_arguments)
+        @context.current_step = step_config.name
+        return unless step_config.undoes_partial_run?
+
+        @compensation_manager.add_to_undo_stack({ step: step_config,
+                                                  arguments: step_config.rollback_arguments(resolved_arguments),
+                                                  result: RubyReactor.Success(nil) })
+      end
+
       # A step returned `RubyReactor.Skipped(...)`: the run continues exactly as
       # for a Success (value, hand-off, period mark), but the step is NOT pushed
       # for undo — it had nothing to do, so there is nothing to revert (008 R-19).

data/lib/ruby_reactor/executor/retry_manager.rb

@@ -108,8 +108,8 @@ module RubyReactor
           result
         when RubyReactor::Failure
           handle_failure_result(step_config, reactor_class, result)
-        when RetryQueuedResult, RubyReactor::DispatchResult
-          # Pass through async results
+        when RetryQueuedResult, RubyReactor::DispatchResult, RubyReactor::InterruptResult
+          # Pass through async results, and a composed child's pause
           result
         else
           clear_retry_state

data/lib/ruby_reactor/executor/step_executor.rb

@@ -431,6 +431,15 @@ module RubyReactor
           return RubyReactor.Success(result)
         end
 
+        # A map element cannot pause: nothing would resume it. The step fails
+        # like any other, rolling back what the element completed (010 R-08).
+        if inside_map_element?
+          failure = RubyReactor::Failure("interrupt :#{step_config.name} is not supported inside a map element",
+                                         step_name: step_config.name, reactor_name: @reactor_class.name,
+                                         retryable: false)
+          return @result_handler.handle_step_result(step_config, failure, {})
+        end
+
         # We are pausing
         correlation_id = nil
         correlation_id = step_config.correlation_id_block.call(@context) if step_config.correlation_id_block
@@ -445,6 +454,17 @@ module RubyReactor
         )
       end
 
+      # This run, or one it is composed into, is a map element.
+      def inside_map_element?
+        context = @context
+        while context
+          return true if context.map_metadata
+
+          context = context.parent_context
+        end
+        false
+      end
+
       def configuration
         RubyReactor::Configuration.instance
       end

data/lib/ruby_reactor/reactor.rb

@@ -38,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)
@@ -154,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})"
@@ -167,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
@@ -244,6 +255,15 @@ module RubyReactor
       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!
@@ -434,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/matchers.rb

@@ -210,50 +210,49 @@ module RubyReactor
       # Matcher to check if reactor is paused at a specific interrupt step
       # Works with both single and multiple concurrent interrupts
       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
       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, " \
@@ -263,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

data/lib/ruby_reactor/rspec/test_subject.rb

@@ -426,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
@@ -483,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

data/lib/ruby_reactor/step/compose_step.rb

@@ -74,6 +74,8 @@ module RubyReactor
         unless child_context
           composed_inputs = build_composed_inputs(inputs.argument_mappings || {})
           child_context = RubyReactor::Context.new(composed_inputs, inputs.composed_reactor_class)
+          # Resumed only through this run, never on its own (010 R-07).
+          child_context.private_data[:composed] = true
         end
 
         link_contexts(child_context, context)
@@ -120,6 +122,14 @@ module RubyReactor
         # the metadata the direct and async paths do propagate.
         return result if result.is_a?(RubyReactor::Failure)
 
+        # The child paused at an interrupt: so does this run. Each compose
+        # level re-stamps its own id, so the top-level result names the root.
+        if result.is_a?(RubyReactor::InterruptResult)
+          return RubyReactor::InterruptResult.new(execution_id: context.context_id,
+                                                  correlation_id: result.correlation_id,
+                                                  intermediate_results: context.intermediate_results)
+        end
+
         result.success? ? RubyReactor.Success(result.value) : RubyReactor.Failure(result.error)
       end
     end

data/lib/ruby_reactor/version.rb

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

data/specs/010-interrupt-in-composed-child/checklists/requirements.md

@@ -0,0 +1,43 @@
+# Specification Quality Checklist: Interrupt Inside a Composed Child
+
+**Purpose**: Validate specification completeness and quality before proceeding to planning
+**Created**: 2026-10-08
+**Feature**: [spec.md](../spec.md)
+
+## Content Quality
+
+- [x] No implementation details (languages, frameworks, APIs)
+- [x] Focused on user value and business needs
+- [x] Written for non-technical stakeholders
+- [x] All mandatory sections completed
+
+## Requirement Completeness
+
+- [x] No [NEEDS CLARIFICATION] markers remain
+- [x] Requirements are testable and unambiguous
+- [x] Success criteria are measurable
+- [x] Success criteria are technology-agnostic (no implementation details)
+- [x] All acceptance scenarios are defined
+- [x] Edge cases are identified
+- [x] Scope is clearly bounded
+- [x] Dependencies and assumptions identified
+
+## Feature Readiness
+
+- [x] All functional requirements have clear acceptance criteria
+- [x] User scenarios cover primary flows
+- [x] Feature meets measurable outcomes defined in Success Criteria
+- [x] No implementation details leak into specification
+
+## Notes
+
+- The product is a Ruby library, so its public DSL and API (`compose`, `interrupt`, `continue`,
+  `be_paused_at`, `ValidationError`) are the user-facing surface and are named, as in specs
+  006–009. Internal classes from the input (`ComposeStep#run`, `handle_execution_result`) stay in
+  the Input line and Context table only, as the observed defect; the requirements do not prescribe
+  them.
+- Defaults chosen instead of clarification markers (see Assumptions): path given as an array, bare
+  leaf name not matched to a nested interrupt, web dashboard display and map-element interrupts out
+  of scope.
+- FR-017 is a small adjacent guard: once a compose propagates the pause, a compose inside a map
+  element would hand the map an unhandled pause result, so it must fail clearly.

data/specs/010-interrupt-in-composed-child/contracts/api-surface.md

@@ -0,0 +1,75 @@
+# Public API Contract: Interrupt Inside a Composed Child
+
+Every addition is backward compatible. Calls that do not use a path behave as before.
+
+## `Reactor.run` / `Reactor#run`
+
+When a composed child reaches an interrupt, the run returns an `InterruptResult` with:
+
+- `paused?` → `true`, `status` → `:paused`;
+- `execution_id` → **the root's** id;
+- `correlation_id` → the child interrupt's correlation id, or `nil`.
+
+`Reactor.find(id).result` rebuilds an `InterruptResult` with the root's id, and without
+`correlation_id` (unchanged).
+
+## `Reactor.continue(id:, payload:, step_name:)`, `Reactor#continue(payload:, step_name:)`
+
+`step_name` takes either form:
+
+| `step_name` | Meaning |
+| --- | --- |
+| `:approve` / `"approve"` | A step of the root (unchanged). |
+| `[:fulfil, :approve]` / `["fulfil", "approve"]` | The interrupt `:approve` inside compose `:fulfil`. |
+| `[:order, :fulfil, :approve]` | Two composes deep. |
+| `[:approve]` | Same as `:approve`. |
+
+Errors:
+
+- `RubyReactor::Error::ValidationError` when the name or path is not a pending interrupt
+  (`"Cannot resume: expected step '<current>' or ready steps <ready_interrupt_steps> but got
+  '<name>'"`). Nothing changes and the run stays `paused`. A bare name must now be a pending
+  interrupt: naming any other ready step is refused, where it used to be accepted.
+- `RubyReactor::Error::ValidationError` when the reactor loaded is a composed child: "Cannot
+  resume: <Class> is a composed child; continue its root run".
+- Every existing error keeps its meaning and is driven by the nested interrupt's own declaration:
+  not paused, cancelled, invalid payload (`InputValidationError` from the class method),
+  `max_attempts` exhaustion (`Failure`, run rolled back from the root and `failed`), and
+  lock/semaphore `AcquisitionError` (run stays paused).
+
+`resume: :background` on the nested interrupt enqueues **the root's** worker.
+
+## `Reactor.continue_by_correlation_id(correlation_id:, payload:, step_name:)`
+
+Called on the **root** class with the path. Called on the child class, it raises the
+composed-child `ValidationError` above.
+
+## `Reactor.interrupt_key(step_name)` (new, public)
+
+Normalizes a step name the way `continue` reads it. `:a`, `"a"` and `[:a]` all give `:a`;
+`["f", "a"]` gives `[:f, :a]`.
+
+## `Reactor#ready_interrupt_steps` (new, public)
+
+```ruby
+Order.find(id).ready_interrupt_steps # => [[:fulfil, :approve]]
+```
+
+Returns `[]` unless the run is `paused`. Root-level interrupts come back as Symbols, nested ones as
+Arrays. A root can be paused at a nested interrupt and have one of its own ready at the same
+time, so the list can mix both: `[:audit, [:fulfil, :approve]]`.
+
+## RSpec surface (`require "ruby_reactor/rspec"`)
+
+| API | Change |
+| --- | --- |
+| `subject.ready_interrupt_steps` | Delegates to `Reactor#ready_interrupt_steps`, so it includes paths. |
+| `be_paused_at([:fulfil, :approve])` | Matches a path. `be_paused_at(:a, :b)` still means two root interrupts. Failure messages print entries with `inspect`. |
+| `have_ready_interrupts(:audit, [:fulfil, :approve])` | Exact set, paths included. |
+| `subject.resume(payload:, step: [:fulfil, :approve])` | Resumes a nested interrupt. With one pending interrupt, `step` may be omitted. |
+
+## Map elements
+
+An `interrupt` reached inside a map element, directly or through a compose, fails that element
+with `Failure("interrupt :<name> is not supported inside a map element")`. Before this feature it
+crashed with `NoMethodError`.

data/specs/010-interrupt-in-composed-child/data-model.md

@@ -0,0 +1,40 @@
+# Data Model: Interrupt Inside a Composed Child
+
+No new storage keys or records. One new `private_data` flag; everything else is derived from state
+that is already stored.
+
+## Root context (stored row, unchanged shape)
+
+| Field | While paused inside a child | Notes |
+| --- | --- | --- |
+| `status` | `paused` | Set by `update_context_status` on the root's `InterruptResult`. |
+| `current_step` | the compose step name (e.g. `:fulfil`) | Set by the `ResultHandler` interrupt arm (R-03). |
+| `composed_contexts[:fulfil]` | `{ name:, type: :composed, context: <child> }` | Child embedded as today. |
+| `undo_stack` | ends with the compose step, `result: Success(nil)` | Partial-run entry (R-04). It is replaced, not duplicated, when the compose completes. |
+| `private_data[:interrupt_attempts]` | keyed by `:"fulfil.approve"` (a Symbol) for a nested interrupt | Root-level interrupts keep their own name as the key (R-06). |
+
+## Child context (embedded in the root, and its own observability row)
+
+| Field | While paused | Notes |
+| --- | --- | --- |
+| `status` | `paused` | As today, set by the child's executor. |
+| `current_step` | the interrupt (e.g. `:approve`), or the next compose one level down | |
+| `intermediate_results[:approve]` | the payload, once `continue` accepted it | Written to the embedded child, never the observability row. |
+| `private_data[:composed]` | `true` | **New.** Set when the compose step creates the child; refuses a direct `continue` (R-07). |
+
+## Step path (value object, not stored)
+
+`Array` of two or more step names: the compose steps from the root, then the interrupt. It is
+normalized to Symbols on input. A one-element array is the same as the bare name.
+
+## State transitions (root)
+
+```text
+running ──child reaches interrupt──▶ paused
+paused ──continue(path, valid payload)──▶ running ──▶ completed | failed | paused (next interrupt)
+paused ──continue(path, payload, resume: :background)──▶ running (worker) ──▶ …
+paused ──continue(path, invalid payload, attempts exhausted)──▶ undo ──▶ failed
+paused ──undo──▶ cancelled        paused ──cancel──▶ cancelled
+```
+
+The child mirrors `paused → running → completed` inside the root and is never resumed on its own.