ruby_reactor 0.8.6 → 0.8.7

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

@@ -0,0 +1,267 @@
+# Feature Specification: Interrupt Inside a Composed Child
+
+**Feature Branch**: `interrupt_inside_composed_child`
+
+**Created**: 2026-10-08
+
+**Status**: Draft
+
+**Input**: User description: "Interrupt inside a composed child. Status: unsupported on main, found
+while implementing 009 (US2-AS2). An `interrupt` in a `compose`d child does not pause the root:
+`ComposeStep#handle_execution_result` calls `success?` on the child's `InterruptResult`, and the
+compose step fails with `NoMethodError`. It fails the same way with or without a fan-out map in the
+child. Direction: propagate the child's `InterruptResult` as the compose step's result, so the root
+pauses; let `Reactor.continue` and the `be_paused_at` matcher name the nested interrupt (a step path
+such as `:fulfil, :approve`); and resume through `ComposeStep#run`, which already re-enters an
+admitted child. Spec: `spec/map/map_compose_fan_out_spec.rb` keeps a `pending` example for it."
+
+## Context
+
+What happens today, and what this feature changes:
+
+| Area | Today | After this feature |
+| --- | --- | --- |
+| Child reaches an `interrupt` | The compose step crashes (`NoMethodError` on the child's pause result); the root fails and rolls back. | The root pauses, stored as `paused`, with the child's completed steps kept. |
+| The paused result | (never reached) | Identifies the **root** run (its `execution_id`) and carries the child interrupt's `correlation_id`. |
+| Naming the pause | Only the root's own steps can be named. | A nested interrupt is named by its step path from the root, e.g. `[:fulfil, :approve]`. |
+| Resuming | (never reached) | `continue` on the root, by id or correlation id, re-enters the child at its interrupt; the child finishes, then the root. |
+| Undo / cancel while paused in a child | (never reached) | Work as for a root-level pause; undo also rolls back the steps the child completed. |
+| Docs | `composition.md` says an `interrupt` inside a composed child is not supported yet. | Documented as supported, with the path form. |
+
+## User Scenarios & Testing *(mandatory)*
+
+### User Story 1 - Pause the root at an interrupt inside a composed child (Priority: P1)
+
+A developer composes a `Fulfilment` reactor into an `Order` reactor (`compose :fulfil,
+Fulfilment`). `Fulfilment` contains `interrupt :approve` waiting for a manager's approval. Running
+`Order` must stop at the approval: the root run is stored as `paused`, the steps completed so far in
+both the root and the child are kept, and the caller gets a paused result that identifies the
+**root** run, so it can be resumed later.
+
+**Why this priority**: Without this the feature is unusable: any reactor that reuses a child with a
+human approval or webhook wait fails outright. Every other story depends on the root pausing
+correctly.
+
+**Independent Test**: Run a root whose composed child has an interrupt. Verify the root is stored as
+`paused`, the result's `execution_id` is the root's id, the child's steps before the interrupt ran
+exactly once, no step after the interrupt (in the child or the root) ran, and nothing was rolled
+back.
+
+**Acceptance Scenarios**:
+
+1. **Given** a root composing a child with steps `c1`, `interrupt :approve`, `c2`, **When** the root
+   runs, **Then** it is stored as `paused`, `c1` ran once, `c2` and every root step after the compose
+   did not run, and the returned result reports `paused?` with the root's `execution_id`.
+2. **Given** the child interrupt declares a `correlation_id`, **When** the root pauses, **Then** the
+   paused result carries that correlation id and it resolves to the root run.
+3. **Given** a child that runs a `fan_out` map before its interrupt, **When** the map completes and
+   the root's worker resumes the run, **Then** the root is stored as `paused` at the child's
+   interrupt (the `pending` example in `spec/map/map_compose_fan_out_spec.rb`).
+4. **Given** the interrupt sits two composes deep (root → middle → child), **When** the root runs,
+   **Then** the top-level root is stored as `paused`; no intermediate reactor is stored or resumable
+   as a run of its own.
+
+---
+
+### User Story 2 - Resume the root by naming the nested interrupt (Priority: P1)
+
+The approval arrives. The developer calls `Order.continue(id:, payload:, step_name: [:fulfil,
+:approve])`, or `Order.continue_by_correlation_id(...)` with the same path. The payload becomes the
+interrupt's result inside the child, the child runs its remaining steps, and the root carries on
+from the compose step to completion, exactly as a root-level interrupt resumes.
+
+**Why this priority**: Pausing without resuming is a dead end. Together with US1 this is the
+minimum viable feature.
+
+**Independent Test**: Pause a root at a child interrupt, then continue it with the step path and a
+payload. Verify the child step after the interrupt receives the payload, the root completes, and
+every step ran exactly once across pause and resume.
+
+**Acceptance Scenarios**:
+
+1. **Given** a root paused at `[:fulfil, :approve]`, **When** `continue` is called with that path
+   and a valid payload, **Then** the child's steps after the interrupt run, the root's steps after
+   the compose run, the root ends `completed`, and its result equals that of an uninterrupted run
+   given the same payload.
+2. **Given** a root paused at a child interrupt with a `correlation_id`, **When**
+   `continue_by_correlation_id` is called on the root class with the path, **Then** the run resumes
+   as in scenario 1.
+3. **Given** the child interrupt declares `resume: :background`, **When** `continue` is called,
+   **Then** the payload is validated in the calling process and the remainder runs in the root's
+   worker, never in a worker for the child.
+4. **Given** a root paused at a child interrupt, **When** `continue` names a step that is not the
+   pending interrupt (a bare `:approve`, a wrong path, or a root step), **Then** it raises
+   `ValidationError` naming the pending path(s) and the run stays `paused`, unchanged.
+5. **Given** the child interrupt validates its payload with `max_attempts: 1`, **When** `continue`
+   is called with an invalid payload, **Then** the whole run is rolled back from the root (the
+   child's completed steps, then the root's) and marked `failed`, as for a root-level interrupt.
+6. **Given** a child that pauses at two interrupts in turn, **When** each is continued in order,
+   **Then** the root pauses again at the second and completes after the second resume.
+
+---
+
+### User Story 3 - Undo or cancel a run paused inside a child (Priority: P2)
+
+The approval is refused, so an operator undoes or cancels the paused order. `Order.undo(id)` must
+roll back every step completed so far, including the child's, and mark the run `cancelled`;
+`Order.cancel(id:, reason:)` must stop it so no later `continue` resumes it.
+
+**Why this priority**: Required for saga correctness once pauses exist, but a paused run is
+already safe to leave alone, so it ranks after pausing and resuming.
+
+**Independent Test**: Pause a root at a child interrupt, call `undo`. Verify the child's completed
+steps were undone once, before the root's, in reverse order, and the run is `cancelled`.
+
+**Acceptance Scenarios**:
+
+1. **Given** a root paused at a child interrupt after `r1` (root) and `c1` (child) completed,
+   **When** the root is undone, **Then** `c1` is undone before `r1`, each once, and the root is
+   `cancelled`.
+2. **Given** a root paused at a child interrupt after a `fan_out` map in the child, **When** the
+   root is undone, **Then** the map's elements, the child's earlier steps, then the root's are
+   rolled back, as 009 specifies for a completed run.
+3. **Given** a root paused at a child interrupt, **When** it is cancelled, **Then** a later
+   `continue` with the nested path raises `ValidationError` and runs nothing.
+
+---
+
+### User Story 4 - Test a nested pause with the RSpec helpers (Priority: P3)
+
+A developer testing `Order` writes `expect(subject).to be_paused_at([:fulfil, :approve])` and
+resumes it from the test subject with the same path.
+
+**Why this priority**: Developer convenience; the runtime behavior is verifiable without it.
+
+**Independent Test**: In a spec using the library's test subject, run a root that pauses in a
+child, assert the matcher passes for the path and fails with a message listing the actual pending
+path for any other name, then resume through the test subject.
+
+**Acceptance Scenarios**:
+
+1. **Given** a test subject paused at a child interrupt, **When** asserting `be_paused_at([:fulfil,
+   :approve])`, **Then** it passes; `be_paused_at(:approve)` fails with a message listing
+   `[:fulfil, :approve]` as the pending step.
+2. **Given** the same subject, **When** its ready interrupt steps are listed, **Then** the nested
+   interrupt appears as its path.
+3. **Given** the same subject, **When** it is resumed with the path and a payload, **Then** it
+   completes as in US2.
+
+---
+
+### Edge Cases
+
+- **Root has its own interrupt ready alongside the compose.** The run pauses at whichever it reaches
+  first; resuming that one runs on and pauses at the other, as for two root-level interrupts.
+- **A second `continue` while the first resume is executing.** Rejected with the existing "not
+  paused" `ValidationError` (008 FR-032), whatever path it names.
+- **The child's reactor class used directly.** `Fulfilment.continue` or
+  `Fulfilment.continue_by_correlation_id` never resumes the child as a run of its own; the root is
+  the only run that owns the pause.
+- **A `continue` that cannot take the root's `with_lock` or `with_semaphore`.** Raises the
+  `AcquisitionError` and leaves the run paused, as for a root-level resume.
+- **A process interruption (signal, exit) during the nested resume.** Handled as today for an
+  interruption inside a composed child: the run is stored `aborted` with outstanding undo work.
+- **An interrupt inside a composed child inside a `map` element.** Out of scope: an interrupt in a
+  map element is not supported either; it must fail with a clear error, not a `NoMethodError`.
+- **Path names a compose step whose child is not paused, or a non-compose step.** Treated as a
+  wrong step name (US2-AS4).
+
+## Requirements *(mandatory)*
+
+### Functional Requirements
+
+**Pausing**
+
+- **FR-001**: When a composed child reaches an `interrupt`, the root run MUST pause: it is stored as
+  `paused`, no step after the interrupt in the child or after the compose in the root runs, and
+  nothing is rolled back.
+- **FR-002**: The pause MUST work at any compose depth, and whether the run reached the interrupt
+  in the caller's process or in a worker (including after a `fan_out` map in the child).
+- **FR-003**: The paused result returned to the caller MUST identify the root run by its
+  `execution_id` and carry the child interrupt's `correlation_id` when it declares one. A result
+  rebuilt by `find(id).result` MUST identify the root run, exactly as for a root-level pause (which
+  does not rebuild the correlation id either).
+- **FR-004**: A child interrupt's `correlation_id` MUST resolve to the root run through the root
+  class's correlation lookup.
+- **FR-005**: Only the root run owns the pause: an intermediate or child reactor MUST NOT be stored,
+  looked up or resumed as a run of its own (single-writer rule).
+
+**Naming and resuming**
+
+- **FR-006**: A nested interrupt MUST be named by its step path from the root: the compose step
+  names from the root down, then the interrupt name, as an ordered list (e.g. `[:fulfil,
+  :approve]`, or `[:order, :fulfil, :approve]` two levels deep). Symbols and strings MUST both be
+  accepted, so a path sent as JSON works.
+- **FR-007**: A bare name MUST keep meaning a step of the root itself; it MUST NOT match a nested
+  interrupt.
+- **FR-008**: `continue` and `continue_by_correlation_id` on the root MUST accept the path, store
+  the payload as the nested interrupt's result, re-enter the child at that interrupt, and run the
+  child's and then the root's remaining steps.
+- **FR-009**: A resumed run MUST produce the same result, and run each step exactly once, as the
+  same tree run without the pause given the same payload.
+- **FR-010**: Every resume rule that applies to a root-level interrupt MUST apply to a nested one,
+  driven by the nested interrupt's own declaration: payload validation and `max_attempts` (rollback
+  of the whole run from the root on exhaustion), `resume: :background` (remainder runs in the root's
+  worker), the paused-only guard, cancellation, and lock/semaphore contention leaving the run
+  paused.
+- **FR-011**: A `continue` naming anything other than a currently pending interrupt MUST raise
+  `ValidationError` listing the pending step(s) in path form, and change nothing.
+
+**Undo and cancel**
+
+- **FR-012**: `undo` on a root paused inside a child MUST roll back the steps the child completed
+  (including any `fan_out` map elements, per 009) before the root's own, each once, and mark the run
+  `cancelled`.
+- **FR-013**: `cancel` on a root paused inside a child MUST make every later `continue` fail.
+
+**Testing helpers and docs**
+
+- **FR-014**: The `be_paused_at` matcher, the ready-interrupt listing and the test subject's resume
+  MUST accept and report nested interrupts in path form; a failure message MUST list the pending
+  path(s).
+- **FR-015**: The `pending` example in `spec/map/map_compose_fan_out_spec.rb` MUST become a real,
+  passing example that pauses at an interrupt after the child's map, then resumes the root to
+  completion.
+- **FR-016**: `composition.md` and `interrupts.md` MUST describe the nested pause, the path form and
+  how undo reaches the child; the "not supported yet" sentence MUST go.
+- **FR-017**: An interrupt reached inside a `map` element (directly or through a compose there) MUST
+  fail the step with an error that says it is unsupported, not a `NoMethodError`.
+
+### Key Entities
+
+- **Root run**: The top-level execution a caller started. Sole owner of the stored state, the
+  `paused` status, the correlation mapping and every resume.
+- **Nested pause point**: The interrupt a composed child stopped at, identified by its step path
+  from the root.
+- **Step path**: Ordered list of compose step names from the root to the child, ending with the
+  interrupt name.
+
+## Success Criteria *(mandatory)*
+
+### Measurable Outcomes
+
+- **SC-001**: 100% of runs whose composed child (at depth 1 or 2) reaches an interrupt end
+  `paused`, with zero failures or rollbacks caused by the pause itself.
+- **SC-002**: A paused-then-resumed run ends with the same final result as the equivalent
+  uninterrupted run in 100% of tested cases, with every step run exactly once.
+- **SC-003**: Undoing a run paused inside a child undoes each completed step exactly once, child
+  steps before root steps, in 100% of tested cases.
+- **SC-004**: Every wrongly named resume is rejected with a message listing the pending path, and
+  leaves the run unchanged.
+- **SC-005**: The previously `pending` example passes on every async backend the suite covers,
+  with no other example in the suite regressing.
+
+## Assumptions
+
+- The path is an ordered list (array). Passing names as separate arguments is already taken: the
+  `be_paused_at` matcher reads `be_paused_at(:a, :b)` as two concurrent root-level interrupts.
+- A bare leaf name is not accepted for a nested interrupt even when unique: explicit paths avoid a
+  silent change of meaning when a root later adds a step of the same name.
+- The web dashboard's display of a nested pause is out of scope; its continue endpoint passes
+  `step_name` through, so a JSON array path works there without extra work.
+- Interrupt `timeout` behavior is unchanged: whatever a root-level interrupt does with it applies
+  equally.
+- Interrupts inside `map` elements stay unsupported; this feature only replaces their crash with a
+  clear error.
+- Builds on 008 (paused-only resume guard, `aborted` runs) and 009 (fan-out map inside a composed
+  child, rollback through the root), both on main.

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

@@ -0,0 +1,315 @@
+---
+description: "Task list for 010 Interrupt Inside a Composed Child"
+---
+
+# Tasks: Interrupt Inside a Composed Child
+
+**Input**: Design documents from `specs/010-interrupt-in-composed-child/`
+
+**Prerequisites**: plan.md, spec.md, research.md, data-model.md, contracts/api-surface.md,
+quickstart.md
+
+**Tests**: Required. Constitution III makes tests test-first on real Redis. Each story's tests are
+written and seen failing before its implementation tasks.
+
+**Organization**: Grouped by user story (spec.md). R-xx refers to research.md, FR-xxx to spec.md.
+
+## Format: `[ID] [P?] [Story] Description`
+
+- **[P]**: can run in parallel (different files, no dependency on an incomplete task)
+- **[Story]**: US1–US4 from spec.md
+
+---
+
+## Phase 1: Setup (Shared Fixtures)
+
+**Purpose**: The reactors every story's specs use.
+
+- [X] T001 Create `spec/ruby_reactor/interrupt_in_compose_spec.rb`, with its fixtures in `spec/support/interrupt_in_compose_fixtures.rb` (`module InterruptInComposeFixtures`, shared with the helpers spec in T033). The fixtures are built on `RollbackRecorder::Reactor` (`spec/support/rollback_recorder.rb`).
+  - `Child` (tag `"child"`): `input :seed, optional: true`; `recording_step :c1`; `interrupt :approve` (`wait_for :c1`, `correlation_id { |ctx| "approve-#{ctx.inputs[:seed]}" }`); `recording_step :c2, after: :approve`. `c2` records the approve payload: `argument :decision, result(:approve)` through the `&extra` block.
+  - `Root`: `recording_step :r1`; `compose :fulfil, Child` (`argument :seed, result(:r1)`); `recording_step :r2, after: :fulfil`.
+  - `Middle`: like `Root`, composing `Child` at `:fulfil`. `Top`: composes `Middle` at `:order`, then `recording_step :t2`.
+  - `TwoInterruptsChild`: `c1`, `interrupt :approve`, `interrupt :sign` (`wait_for :approve`), `c2`; and `TwoInterruptsRoot` composing it.
+  - `RootWithOwnInterrupt`: `r1`, `interrupt :audit` (`wait_for :r1`) and `compose :fulfil, Child` both ready after `r1`, then `r2` after both.
+  - `BackgroundChild`: `Child` with `interrupt :approve, resume: :background`; `BackgroundRoot` composing it.
+  - `ValidatedChild`: `interrupt :approve` with `validate_payload { required(:ok).filled(:bool) }` and `max_attempts: 1`; `ValidatedRetryChild` the same with `max_attempts: 3`; a root composing each.
+  - `before { RollbackRecorder.reset! }`, and a `drain` helper as in `spec/map/map_compose_fan_out_spec.rb`.
+- [X] T002 [P] Add to `MapComposeFanOutSpec` in `spec/map/map_compose_fan_out_spec.rb`: a child fixture `InterruptChild` (same as `Child`, plus `interrupt :approve` after `:m`, with `c2` waiting for `:approve`) and `root :InterruptRoot, InterruptChild`.
+
+---
+
+## Phase 2: Foundational
+
+None. US1's pass-through is the base the other stories build on, and it is small enough to live in
+US1.
+
+---
+
+## Phase 3: User Story 1 - Pause the root at an interrupt inside a composed child (Priority: P1) 🎯 MVP
+
+**Goal**: A root whose composed child reaches an `interrupt` is stored `paused` and returns an
+`InterruptResult` naming the root (FR-001–FR-004).
+
+**Independent Test**: `InterruptInComposeSpec::Root.run({})`:
+
+- the result is `paused?`, with `execution_id` equal to the root's id;
+- `Root.find(id).context.status == "paused"`;
+- the log is exactly `["run:r1", "run:child.c1"]`, with no undo events.
+
+### Tests for User Story 1 (write first, confirm failing)
+
+- [X] T003 [US1] In `spec/ruby_reactor/interrupt_in_compose_spec.rb`, describe "pausing" (US1-AS1). Running `Root`:
+  - returns an `InterruptResult`, with `paused?` true and `execution_id == Root.find(result.execution_id).context.context_id`;
+  - leaves the stored status `"paused"`, with `current_step` `:fulfil`;
+  - leaves the log at `%w[run:r1 run:child.c1]`.
+- [X] T004 [US1] In the same file, assert that the paused result's `correlation_id` is `"approve-r1-value"` (the seed is `r1`'s value), and that `Root.find_by_correlation_id("approve-r1-value").context.context_id` is the root's id (US1-AS2, FR-004).
+- [X] T005 [US1] In the same file, assert that running `Top` stores `Top` as `"paused"`, returns `Top`'s id, and that the log stops after `run:child.c1` (US1-AS4, FR-002).
+- [X] T006 [P] [US1] In `spec/map/map_compose_fan_out_spec.rb`, replace the `pending` example "resumes the root once the child's interrupt after the map is continued" with a real one. Under `for_each_async_backend`:
+  - `run(MapComposeFanOutSpec::InterruptRoot)` leaves the root `"paused"`;
+  - the root's `composed_contexts[:c][:context].current_step` is `:approve`;
+  - no `run:child.c2` was logged.
+
+  The resume half is added in T024 (US1-AS3, FR-015).
+
+### Implementation for User Story 1
+
+- [X] T007 [P] [US1] In `lib/ruby_reactor/step/compose_step.rb`, `handle_execution_result` returns `RubyReactor::InterruptResult.new(execution_id: context.context_id, correlation_id: result.correlation_id, intermediate_results: context.intermediate_results)` when `result.is_a?(RubyReactor::InterruptResult)`. Put it before the `success?` line, with a comment: each compose level re-stamps its own id, so the top-level result names the root (R-02).
+- [X] T008 [P] [US1] In `lib/ruby_reactor/executor/retry_manager.rb`, `handle_retry_result` passes `RubyReactor::InterruptResult` through unchanged. Add it to the `when RetryQueuedResult, RubyReactor::DispatchResult` arm (R-01).
+- [X] T009 [P] [US1] In `lib/ruby_reactor/executor/result_handler.rb`, give `handle_step_result` a `when RubyReactor::InterruptResult` arm, before `else`, calling a new private `handle_interrupted(step_config)`. That method sets `@context.current_step = step_config.name`. Comment: `with_step` cleared it, and it is the root's resume cursor (R-03). Nothing is recorded as a result and the graph node stays incomplete.
+- [X] T010 [US1] Run `bundle exec rspec spec/ruby_reactor/interrupt_in_compose_spec.rb spec/map/map_compose_fan_out_spec.rb spec/compose_spec.rb spec/ruby_reactor/interrupt_spec.rb`. T003–T006 must pass and nothing else may regress.
+
+**Checkpoint**: Roots pause at any depth, sync and after a fan-out map.
+
+---
+
+## Phase 4: User Story 2 - Resume the root by naming the nested interrupt (Priority: P1)
+
+**Goal**: `continue` and `continue_by_correlation_id` on the root accept an Array path and finish
+the run. Wrong names and direct child resumes are refused (FR-005–FR-011).
+
+**Independent Test**: Pause `Root`, then `Root.continue(id:, payload: { ok: true }, step_name:
+[:fulfil, :approve])`. Expect:
+
+- status `"completed"`;
+- log `%w[run:r1 run:child.c1 run:child.c2 run:r2]`;
+- `c2` received the payload.
+
+### Tests for User Story 2 (write first, confirm failing)
+
+- [X] T011 [US2] In `spec/ruby_reactor/interrupt_in_compose_spec.rb`, describe "resuming" (US2-AS1, FR-008/FR-009):
+  - continuing with `[:fulfil, :approve]` completes the root;
+  - each step logs `run:` exactly once across pause and resume;
+  - `c2`'s stored result reflects the payload;
+  - string paths (`["fulfil", "approve"]`) work the same.
+- [X] T012 [US2] In the same file, assert that `Root.continue_by_correlation_id(correlation_id: "approve-r1-value", payload:, step_name: [:fulfil, :approve])` completes the root (US2-AS2).
+- [X] T013 [US2] In the same file, assert each of these raises `RubyReactor::Error::ValidationError` whose message includes `[:fulfil, :approve]`, leaving the status `"paused"` and the log unchanged (US2-AS4, FR-007, FR-011):
+  - `step_name: :approve`;
+  - `step_name: [:fulfil, :nope]`;
+  - `step_name: [:r2, :approve]`;
+  - `step_name: :r2`.
+- [X] T014 [US2] In the same file, assert that a direct child resume raises `ValidationError` matching `/composed child/` and runs nothing (FR-005). Cover both:
+  - `Child.continue(id: <root>.context.composed_contexts[:fulfil][:context].context_id, …)`;
+  - `Child.continue_by_correlation_id(correlation_id: "approve-r1-value", …)`.
+- [X] T015 [US2] In the same file, under `for_each_async_backend`, assert that continuing `BackgroundRoot` (US2-AS3, FR-010):
+  - returns a `DispatchResult`;
+  - completes after `drain`;
+  - calls the async router's `perform_async` with the root's id, and never with the child's id (pattern as in `spec/map/map_compose_fan_out_spec.rb` "signals the root's Worker").
+- [X] T016 [US2] In the same file, assert that continuing the `ValidatedRetryChild` root with `{ ok: "x" }` (FR-010):
+  - raises `InputValidationError` from the class method;
+  - keeps the run `"paused"`;
+  - stores `private_data[:interrupt_attempts]["fulfil.approve"] == 1`;
+  - lets a valid payload then complete it.
+- [X] T017 [US2] In the same file, cover multi-interrupt flows:
+  - `TwoInterruptsRoot`: continue `[:fulfil, :approve]`, which re-pauses with `ready_interrupt_steps == [[:fulfil, :sign]]`; continue `[:fulfil, :sign]`, which completes (US2-AS6).
+  - `RootWithOwnInterrupt`: `ready_interrupt_steps` contains both `:audit` and `[:fulfil, :approve]`; continuing each in turn completes the run (edge case).
+- [X] T018 [US2] In the same file, assert that `Top`'s `ready_interrupt_steps == [[:order, :fulfil, :approve]]`, and that continuing with that path completes `Top` with `run:t2` logged once (FR-006).
+- [X] T019 [US2] In the same file, assert that a `continue` while the resume is executing is refused with the existing "not paused" message (edge case, 008 FR-032). Stub `c2`'s run, via an `&extra` hook, to call `Root.continue` again with the same path, and expect `ValidationError` matching `/running, not paused/`.
+
+### Implementation for User Story 2
+
+- [X] T020 [P] [US2] In `lib/ruby_reactor/step/compose_step.rb`, `prepare_child_context` sets `child_context.private_data[:composed] = true` when it builds a new child context (R-07).
+- [X] T021 [US2] In `lib/ruby_reactor/reactor.rb`, add public `ready_interrupt_steps` (R-05):
+  - Return `[]` unless `@context.status.to_s == "paused"`.
+  - Otherwise return `pending_interrupts(self.class, @context, [])`, a private recursive helper. It builds a `GraphManager` (as `validate_continue_step!` does), takes the ready steps and collects:
+    - for each `interrupt?` step, `prefix.empty? ? name : prefix + [name]`;
+    - for each ready step whose `composed_contexts[name]` is `type: :composed` with a `paused` `:context`, the recursion into `(child.reactor_class, child, prefix + [name])`.
+  - Read hash keys indifferently (symbol or string), since stored `composed_contexts` round-trip through the serializer.
+- [X] T022 [US2] In `lib/ruby_reactor/reactor.rb`, `#continue` (R-06, R-07):
+  - **Child guard**: right after the `current_step` guard, raise `Error::ValidationError, "Cannot resume: #{self.class.name} is a composed child; continue its root run"` when `@context.private_data[:composed] || @context.private_data["composed"]`.
+  - **Path normalization**: `path = Array(step_name).map(&:to_sym)`. A one-element path is a bare name.
+  - **Bare names** keep today's `validate_continue_step!`.
+  - **Paths**:
+    - raise `Error::ValidationError, "Cannot resume: #{path.inspect} is not a pending interrupt; pending: #{ready_interrupt_steps.inspect}"` unless `ready_interrupt_steps.include?(path)`;
+    - then walk `composed_contexts[...][:context]` down `path[0..-2]` to get `target_context`, and take `step_config = target_context.reactor_class.steps[path.last]`.
+  - **Callers to update**:
+    - `validate_continue_payload` takes `step_config` and an attempts key: `path.join(".")` for a path, the Symbol for a bare name;
+    - `set_result` goes to `target_context` with `path.last`;
+    - `background_resume?` reads `step_config`.
+  - Root status, save and `resume_execution` stay as they are.
+- [X] T023 [US2] Run `bundle exec rspec spec/ruby_reactor/interrupt_in_compose_spec.rb spec/ruby_reactor/interrupt_spec.rb spec/ruby_reactor/multiple_interrupts_spec.rb spec/ruby_reactor/interrupt_background_resume_spec.rb spec/integration/interrupt_validation_spec.rb spec/integration/interrupt_max_attempts_spec.rb`. T011–T019 must pass with no regression.
+- [X] T024 [US2] In `spec/map/map_compose_fan_out_spec.rb`, extend the T006 example: `InterruptRoot.continue(id:, payload: {}, step_name: [:c, :approve])`, `drain`, then expect `"completed"` and `r2` == `"r2-value"` (FR-015).
+
+**Checkpoint**: The MVP (US1 + US2) is usable: pause and resume through a compose.
+
+---
+
+## Phase 5: User Story 3 - Undo or cancel a run paused inside a child (Priority: P2)
+
+**Goal**: Undo reaches the child's completed steps, cancel blocks resumes, and `max_attempts`
+exhaustion rolls back from the root (FR-012, FR-013, US2-AS5).
+
+**Independent Test**: Pause `Root`, then `Root.undo(id)`. The log tail is `%w[undo:child.c1
+undo:r1]`, each once, and the status is `"cancelled"`.
+
+### Tests for User Story 3 (write first, confirm failing)
+
+- [X] T025 [US3] In `spec/ruby_reactor/interrupt_in_compose_spec.rb`, describe "undo and cancel":
+  - Undoing a paused `Root` logs `undo:child.c1` before `undo:r1`, each exactly once, and ends `"cancelled"` (US3-AS1).
+  - Undoing a paused `Top` reaches `undo:child.c1` too.
+- [X] T026 [US3] In the same file, assert that a `Root` paused, resumed to completion, then undone logs each of `undo:child.c2`, `undo:child.c1`, `undo:r2` and `undo:r1` exactly once. This proves the partial-run entry was replaced, not duplicated (R-04).
+- [X] T027 [US3] In the same file, assert that `Root.cancel(id:, reason: "no")` on a paused root makes a later `continue` with `[:fulfil, :approve]` raise `ValidationError` matching `/cancelled/`, with no `run:` logged (US3-AS3, FR-013).
+- [X] T028 [US3] In the same file, assert that continuing the `ValidatedChild` root (`max_attempts: 1`) with `{ ok: "x" }` (US2-AS5, FR-010):
+  - returns a `Failure`;
+  - logs `undo:child.c1` before `undo:r1`;
+  - leaves the stored status `"failed"`.
+- [X] T029 [P] [US3] In `spec/map/map_compose_fan_out_spec.rb`, under "rollback through the root", add an example (US3-AS2). Pause `InterruptRoot`, `RollbackRecorder.reset!`, `InterruptRoot.undo(id)`, `drain`, then expect:
+  - `"cancelled"`;
+  - `element_undos.size == 8`, each once;
+  - `undo:child.c1` then `undo:r1` last.
+
+### Implementation for User Story 3
+
+- [X] T030 [US3] In `lib/ruby_reactor/executor/result_handler.rb`, `handle_interrupted` also pushes `{ step: step_config, arguments: step_config.rollback_arguments(resolved_arguments), result: RubyReactor.Success(nil) }` with `@compensation_manager.add_to_undo_stack` when `step_config.undoes_partial_run?`. This is the same entry as `StepExecutor#track_interrupted_construct`. Pass `resolved_arguments` through from `handle_step_result` (R-04).
+- [X] T031 [US3] In `lib/ruby_reactor/executor/compensation_manager.rb`, `add_to_undo_stack` pops the top entry first when it belongs to the same step (`undo_stack.last && undo_stack.last[:step].name == step_info[:step].name`). Add a `ponytail:` comment naming the assumption: a step's entry is on top when it re-runs, because a run stops at a pause (R-04).
+- [X] T032 [US3] Run `bundle exec rspec spec/ruby_reactor/interrupt_in_compose_spec.rb spec/map/map_compose_fan_out_spec.rb spec/ruby_reactor/interrupt_undo_spec.rb spec/ruby_reactor/rollback`. T025–T029 must pass with no regression.
+
+**Checkpoint**: Saga integrity holds for nested pauses.
+
+---
+
+## Phase 6: User Story 4 - Test a nested pause with the RSpec helpers (Priority: P3)
+
+**Goal**: `be_paused_at`, `have_ready_interrupts`, `ready_interrupt_steps` and `resume(step:)`
+accept paths (FR-014).
+
+**Independent Test**: `test_reactor(InterruptInComposeSpec::Root)`. Expect:
+
+- `be_paused_at([:fulfil, :approve])` passes;
+- `be_paused_at(:approve)` fails, with a message containing `[:fulfil, :approve]`;
+- `resume(payload: { ok: true })` reaches `be_success`.
+
+### Tests for User Story 4 (write first, confirm failing)
+
+- [X] T033 [US4] In `spec/ruby_reactor/rspec/helpers_spec.rb`, add a "nested interrupts" context using `InterruptInComposeSpec::Root` (US4-AS1–AS3):
+  - `subject.ready_interrupt_steps == [[:fulfil, :approve]]`;
+  - `be_paused_at([:fulfil, :approve])` passes, and `have_ready_interrupts([:fulfil, :approve])` passes;
+  - `expect { expect(subject).to be_paused_at(:approve) }.to fail_with(/\[:fulfil, :approve\]/)`;
+  - `resume(payload: { ok: true })` with no step, and `resume(step: [:fulfil, :approve], …)`, both end `be_success`.
+
+  Require the fixture file, or move the `InterruptInComposeSpec` module to `spec/support/interrupt_in_compose_fixtures.rb` if it is needed from two files.
+
+### Implementation for User Story 4
+
+- [X] T034 [P] [US4] In `lib/ruby_reactor/rspec/test_subject.rb`:
+  - `ready_interrupt_steps` delegates to `@reactor_instance.ready_interrupt_steps`, and the duplicated graph code goes;
+  - `determine_resume_step` normalizes `step` (`step.is_a?(Array) ? step.map(&:to_sym) : step.to_sym`) before the `include?` check, and prints `step.inspect` in its error.
+- [X] T035 [P] [US4] In `lib/ruby_reactor/rspec/matchers.rb`:
+  - `be_paused_at` and `have_ready_interrupts` normalize each expected name the same way;
+  - sorting in `have_ready_interrupts` uses `sort_by(&:inspect)`, because Symbols and Arrays do not compare;
+  - failure messages print names with `inspect` instead of `":#{s}"`.
+- [X] T036 [US4] Run `bundle exec rspec spec/ruby_reactor/rspec` and the demo interrupt specs (`demo_app/spec/reactors/form_interrupt_reactor_spec.rb`, `webhook_interrupt_reactor_spec.rb`) per quickstart.md §2. T033 must pass with no regression.
+
+**Checkpoint**: All four stories work independently.
+
+---
+
+## Phase 7: Polish & Cross-Cutting Concerns
+
+### Map element guard (FR-017, R-08)
+
+- [X] T037 Add specs that an interrupt inside a map element fails that element with a message matching `/not supported inside a map element/`, never `NoMethodError`:
+  - in `spec/map/map_compose_fan_out_spec.rb`, an element reactor that composes a child with an `interrupt`, run fan-out under `for_each_async_backend`, with the root ending `"failed"`;
+  - in `spec/ruby_reactor/interrupt_in_compose_spec.rb`, the same element run as an inline map.
+- [X] T038 In `lib/ruby_reactor/executor/step_executor.rb`, `handle_interrupt_step` returns `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)` when `@context` or any `parent_context` up the chain has `map_metadata`. Use a small private `inside_map_element?` loop. T037 must pass.
+
+### Demo app (Constitution VI)
+
+- [X] T039 [P] Create `demo_app/app/reactors/manager_approval_reactor.rb`: `ManagerApprovalReactor`, with class-based steps.
+  - `input :order_id`;
+  - `step :reserve_stock`, with an `undo` that prints/records the release;
+  - `interrupt :wait_for_manager` (`wait_for :reserve_stock`, `correlation_id { |ctx| "approval-#{ctx.inputs[:order_id]}" }`, `validate_payload { required(:approved).filled(:bool) }`);
+  - `step :confirm_reservation`, which fails when `approved` is false.
+- [X] T040 [P] Create `demo_app/app/reactors/composed_approval_reactor.rb`: `ComposedApprovalReactor`, with class-based steps.
+  - `input :order_id`;
+  - `step :charge_card`, with an `undo` refund;
+  - `compose :approval, ManagerApprovalReactor` (`argument :order_id, input(:order_id)`);
+  - `step :ship`, after `:approval`.
+- [X] T041 Add `demo:composed_interrupt` to `demo_app/lib/tasks/demo_reactors.rake`, with `desc` and `[:environment, :flush_redis]`. It prints:
+  - the run's status, root id and `ready_interrupt_steps`;
+  - an approved `continue` by correlation id with `step_name: [:approval, :wait_for_manager]`, and its final status;
+  - a second run undone while paused, its status, and that `reserve_stock` and `charge_card` were undone.
+- [X] T042 Create `demo_app/spec/reactors/composed_approval_reactor_spec.rb` (`type: :reactor`), using only the shipped surface:
+  - `test_reactor`, `be_paused_at([:approval, :wait_for_manager])`, `have_ready_interrupts`;
+  - `resume(step: [:approval, :wait_for_manager], payload: { approved: true })` then `be_success` and `have_run_step(:ship).after(:approval)`;
+  - a rejected resume ending `be_failure`.
+
+  Run it locally per quickstart.md §2.
+- [X] T043 Run the Docker acceptance `docker compose … run --rm --no-deps demo-app bash -c "bin/rails db:prepare && bin/rails demo:composed_interrupt"` with an isolated compose project (quickstart.md §2). Record the output in the PR description.
+
+### Documentation (Constitution Development Workflow)
+
+- [X] T044 [P] Update `documentation/composition.md` rule 6: replace "An `interrupt` inside a composed child is not supported yet, with or without a map." with the nested pause behavior, linking to interrupts.md: the root pauses, is resumed by path, and undo reaches the child.
+- [X] T045 [P] Add "Interrupts inside composed reactors" to `documentation/interrupts.md`, after "Resuming Execution". Use class-based examples. Cover:
+  - the path form, why it is an Array, and `ready_interrupt_steps`;
+  - correlation id on the root class;
+  - background resume running in the root's worker;
+  - undo and cancel;
+  - the composed-child guard;
+  - interrupts inside map elements being unsupported.
+- [X] T046 [P] Add one line in `README.md` § *Interrupts (Pause & Resume)* noting that interrupts work inside `compose`d children, resumed by path, with a link to the new interrupts.md section.
+- [X] T047 [P] Add a *Features* entry under *Unreleased* in `CHANGELOG.md`: interrupts inside composed children; Array `step_name` paths; `Reactor#ready_interrupt_steps`; matcher path support; and the map-element interrupt now failing clearly.
+- [X] T048 [P] Remove the "Interrupt inside a composed child" section from `specs/future_improvements.md`.
+
+### Gate
+
+- [X] T049 Run `bundle exec rspec` and `bundle exec rubocop` at the repo root, and the full `demo_app` spec suite per quickstart.md §2. All must be green. If an async example flakes, rerun it alone first (shared test Redis).
+
+---
+
+## Dependencies & Execution Order
+
+- **Setup (T001–T002)** comes first.
+- **US1 (T003–T010)** depends on Setup, and blocks US2, US3 and US4: nothing can be resumed, undone or matched until the root pauses.
+- **US2 (T011–T024)** depends on US1.
+- **US3 (T025–T032)** depends on US1. T028 (`max_attempts` exhaustion) also needs US2's T022 to resolve the nested step config, so implement it after T022.
+- **US4 (T033–T036)** depends on US2's T021 (`Reactor#ready_interrupt_steps`).
+- **Polish**:
+  - the map guard (T037–T038) depends on US1 only;
+  - the demo (T039–T043) depends on US1–US4;
+  - the docs (T044–T048) can be drafted after US2 and finalized last;
+  - T049 runs last.
+
+Within each story, the tests are written and seen failing before the implementation tasks.
+
+## Parallel Opportunities
+
+- T002 can run alongside T001.
+- In US1, T007, T008 and T009 touch three different files.
+- In US2, T020 can run alongside T021/T022 (different file). T021 and T022 share `reactor.rb`, so they run one after the other.
+- In US3, T029 is in a different spec file from T025–T028.
+- In US4, T034 and T035 touch different files.
+- In Polish, T039 and T040 run in parallel, as do T044–T048.
+
+```text
+# US1 implementation, after T003–T006 fail:
+T007 compose_step.rb  |  T008 retry_manager.rb  |  T009 result_handler.rb
+```
+
+## Implementation Strategy
+
+1. **MVP = US1 + US2** (both P1). Pausing alone is a dead end: ship them together. Stop after T024
+   and validate with quickstart.md §1, rows 1–6.
+2. **US3** next. Undo while paused is a saga guarantee (Constitution II), so it must land before
+   release, not as a follow-up.
+3. **US4** after that: test-surface convenience.
+4. **Polish**: map guard, demo with the Docker run, docs, then the full gate.

data/specs/future_improvements.md

@@ -222,18 +222,6 @@ All against real Redis, per the constitution.
 - Docs: `locks_and_semaphores.md`, `background_and_async.md`, and the README's "Durability &
   Recovery" section.
 
-## Interrupt inside a composed child
-
-**Status:** unsupported on main, found while implementing 009 (US2-AS2). An `interrupt` in a
-`compose`d child does not pause the root: `ComposeStep#handle_execution_result` calls `success?` on
-the child's `InterruptResult`, and the compose step fails with `NoMethodError`. It fails the same
-way with or without a fan-out map in the child.
-
-Direction: propagate the child's `InterruptResult` as the compose step's result, so the root
-pauses; let `Reactor.continue` and the `be_paused_at` matcher name the nested interrupt (a step
-path such as `:fulfil, :approve`); and resume through `ComposeStep#run`, which already re-enters
-an admitted child. Spec: `spec/map/map_compose_fan_out_spec.rb` keeps a `pending` example for it.
-
 ## Rollback follow-ups (008)
 
 Raised while implementing specs/008-rollback-reliability. None blocks it.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ruby_reactor
 version: !ruby/object:Gem::Version
-  version: 0.8.6
+  version: 0.8.7
 platform: ruby
 authors:
 - Artur
@@ -330,6 +330,14 @@ files:
 - specs/009-distributed-map-undo/research.md
 - specs/009-distributed-map-undo/spec.md
 - specs/009-distributed-map-undo/tasks.md
+- specs/010-interrupt-in-composed-child/checklists/requirements.md
+- specs/010-interrupt-in-composed-child/contracts/api-surface.md
+- specs/010-interrupt-in-composed-child/data-model.md
+- specs/010-interrupt-in-composed-child/plan.md
+- specs/010-interrupt-in-composed-child/quickstart.md
+- specs/010-interrupt-in-composed-child/research.md
+- specs/010-interrupt-in-composed-child/spec.md
+- specs/010-interrupt-in-composed-child/tasks.md
 - specs/future_improvements.md
 - specs/scoped_rspec_matchers.md
 - specs/specs-inputs-by-method-md-piped-wigderson.md