ruby_reactor 0.8.5 → 0.8.7

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.

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

@@ -0,0 +1,149 @@
+# Implementation Plan: Interrupt Inside a Composed Child
+
+**Branch**: `interrupt_inside_composed_child` | **Date**: 2026-10-08 | **Spec**: [spec.md](spec.md)
+
+**Input**: Feature specification from `specs/010-interrupt-in-composed-child/spec.md`
+
+## Summary
+
+A composed child already pauses itself correctly. Its parent then crashes on the
+`InterruptResult`. The fix is mostly letting that result through, plus three gaps it exposes:
+
+1. **Pass the pause up (US1)**: `InterruptResult` arms in `ComposeStep#handle_execution_result`,
+   `RetryManager#handle_retry_result` and `ResultHandler#handle_step_result` (R-01).
+   - The compose re-stamps the result with its own context id, so the top level reports the
+     root's id (R-02).
+   - The result-handler arm sets the root's `current_step` to the compose step, which is the
+     resume cursor that `with_step` would otherwise clear (R-03).
+2. **Name and resume (US2)**: a nested interrupt is an Array path. `Reactor#ready_interrupt_steps`
+   (new, public) derives the pending paths from stored state (R-05).
+   - `Reactor#continue` resolves `(target context, step config, leaf)` once and uses them for
+     validation, attempts, background resume and `set_result` (R-06).
+   - The resume itself is unchanged: the root re-runs the compose step, and `ComposeStep#run`
+     re-enters the admitted child.
+3. **Undo while paused (US3)**: the pausing compose joins the undo stack as a partial-run entry,
+   the same entry an aborted compose gets. `add_to_undo_stack` replaces it when the compose later
+   completes (R-04).
+4. **Test surface (US4)**: `TestSubject#ready_interrupt_steps` delegates to the reactor, and
+   `be_paused_at`/`have_ready_interrupts`/`resume` accept paths.
+5. **Guards**:
+   - a composed child refuses a direct `continue` (`private_data[:composed]`, R-07);
+   - an interrupt inside a map element fails cleanly instead of `NoMethodError` (R-08).
+
+## Technical Context
+
+**Language/Version**: Ruby >= 3.0
+
+**Primary Dependencies**: Sidekiq and ActiveJob adapters, Redis, dry-validation. No new
+dependencies.
+
+**Storage**: Redis through `Storage::RedisAdapter`. No new keys. One new `private_data[:composed]`
+flag on composed child contexts (see [data-model.md](data-model.md)).
+
+**Testing**: RSpec against real Redis (`redis://localhost:6780`), `for_each_async_backend` and
+`drain_async_jobs` for the worker paths. Demo specs use the shipped matchers only.
+
+**Target Platform**: Any Ruby process with Redis; workers via Sidekiq or ActiveJob.
+
+**Project Type**: Library (gem), with `demo_app/` as the integration example.
+
+**Performance Goals**: None new. `ready_interrupt_steps` builds one dependency graph per paused
+level, and only on `continue` or in tests.
+
+**Constraints**: Single-writer context rule: only the root run is stored and resumed as the
+owner, and a pause is written to the embedded child, never to its observability row.
+
+**Scale/Scope**: About 8 lib files touched, each change a few lines, except the `Reactor#continue`
+target resolution. 1 new gem spec file, 1 un-pended example, 2 demo reactors, 1 rake task, 1 demo
+spec, 4 doc files.
+
+## Constitution Check
+
+*Gate re-checked after Phase 1. No violations.*
+
+| Principle | Status | Notes |
+| --- | --- | --- |
+| I. Gem-First | PASS | All in `lib/`; no host coupling. |
+| II. Saga Integrity | PASS | Closes a gap: the "interrupts first-class" clause now holds inside a compose, and undo reaches a paused child's completed steps (R-04). |
+| III. Test-First, Real Infra | PASS | Specs written failing first, on real Redis, across async backends. No `inline!` for orchestration. |
+| IV. Observability | PASS | Paused root status and the embedded child are visible in the dashboard as today. A refused `continue` names the pending path. |
+| V. Simplicity & SemVer | PASS | Pass-through arms; the path is derived, not stored; one public method added. MINOR (R-10), with a CHANGELOG entry. |
+| VI. Demo-App Proof | PASS (planned) | `ManagerApprovalReactor` (child) and `ComposedApprovalReactor` (root) in `demo_app/app/reactors/`; `demo:composed_interrupt`; `demo_app/spec/reactors/composed_approval_reactor_spec.rb` using `be_paused_at([...])`, `resume(step: [...])`, `be_success`, `have_run_step`. Docker acceptance run. |
+
+- [x] Documentation impact identified (carried into tasks.md as a required task):
+  - **`documentation/composition.md`**: replace "An `interrupt` inside a composed child is not
+    supported yet…" (rule 6) with the nested-pause behavior and a pointer to interrupts.md.
+  - **`documentation/interrupts.md`**: new section "Interrupts inside composed reactors" covering
+    the path form, correlation id on the root class, undo/cancel, a child that refuses a direct
+    `continue`, and map elements unsupported.
+  - **`README.md`**: one line in the *Interrupts (Pause & Resume)* section linking to it.
+  - **`CHANGELOG.md`**: *Unreleased → Features*.
+  - **`specs/future_improvements.md`**: drop the "Interrupt inside a composed child" entry.
+
+## Project Structure
+
+### Documentation (this feature)
+
+```text
+specs/010-interrupt-in-composed-child/
+├── plan.md
+├── research.md
+├── data-model.md
+├── quickstart.md
+├── contracts/api-surface.md
+├── checklists/requirements.md
+└── tasks.md             # /speckit-tasks
+```
+
+### Source Code (repository root)
+
+```text
+lib/ruby_reactor/
+├── step/compose_step.rb               # R-01/R-02 pass-through + re-stamp; R-07 mark child composed
+├── executor/retry_manager.rb          # R-01 InterruptResult arm
+├── executor/result_handler.rb         # R-01/R-03/R-04 arm: cursor + partial-run undo entry
+├── executor/compensation_manager.rb   # R-04 replace top entry for the same step
+├── executor/step_executor.rb          # R-08 interrupt inside a map element → Failure
+├── reactor.rb                         # R-05 ready_interrupt_steps; R-06 path in continue; R-07 guard
+└── rspec/
+    ├── test_subject.rb                # delegate ready_interrupt_steps; resume(step: path)
+    └── matchers.rb                    # be_paused_at / have_ready_interrupts accept paths
+
+spec/
+├── ruby_reactor/interrupt_in_compose_spec.rb   # new
+└── map/map_compose_fan_out_spec.rb             # un-pend; add a child fixture with an interrupt after the map
+
+demo_app/
+├── app/reactors/manager_approval_reactor.rb    # child: reserve → interrupt :wait_for_manager → confirm
+├── app/reactors/composed_approval_reactor.rb   # root: charge → compose :approval → ship
+├── lib/tasks/demo_reactors.rake                # demo:composed_interrupt
+└── spec/reactors/composed_approval_reactor_spec.rb
+```
+
+**Structure Decision**: Existing gem layout. No new lib files: each change sits where the
+`InterruptResult` is already handled for root-level pauses.
+
+## Implementation Order
+
+Test-first within each step:
+
+1. **US1**: pass-through arms, re-stamp, cursor. Spec: root pauses at depth 1 and 2, sync and
+   after a fan-out map (un-pend FR-015).
+2. **US2**: `ready_interrupt_steps`, target resolution in `continue`, composed-child guard. Specs:
+   - resume by id and by correlation id;
+   - wrong path;
+   - background resume;
+   - `max_attempts`;
+   - two interrupts in sequence;
+   - a root interrupt ready alongside.
+3. **US3**: partial-run undo entry and its replacement. Specs: undo while paused (plain child, and
+   a child with a fan-out map), cancel then continue, and an undo after completion that undoes the
+   compose once.
+4. **US4**: test subject and matchers.
+5. **Guard R-08**: map element interrupt, inline and fan-out.
+6. **Demo** reactors, rake task, demo spec, Docker acceptance run.
+7. **Docs, CHANGELOG, `future_improvements.md`**, then full `rspec` and `rubocop`.
+
+## Complexity Tracking
+
+No violations to justify.

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

@@ -0,0 +1,64 @@
+# Quickstart: Validating Interrupt Inside a Composed Child
+
+## Prerequisites
+
+- Test Redis on `localhost:6780` (`docker start ruby_reactor_redis_test` if the container exists).
+- `bundle install` at the repo root and in `demo_app/`.
+
+## 1. Gem specs
+
+```bash
+bundle exec rspec spec/ruby_reactor/interrupt_in_compose_spec.rb   # new: US1–US4, edge cases
+bundle exec rspec spec/map/map_compose_fan_out_spec.rb             # FR-015: the former `pending` example
+bundle exec rspec spec/ruby_reactor/interrupt_spec.rb spec/ruby_reactor/multiple_interrupts_spec.rb \
+  spec/ruby_reactor/interrupt_undo_spec.rb spec/ruby_reactor/interrupt_background_resume_spec.rb \
+  spec/integration/interrupt_validation_spec.rb spec/integration/interrupt_max_attempts_spec.rb \
+  spec/compose_spec.rb                                             # no regression
+bundle exec rspec && bundle exec rubocop                           # full gate
+```
+
+Expected:
+
+| Scenario | Outcome |
+| --- | --- |
+| Root composing a child with `c1`, `interrupt :approve`, `c2` | `paused`; `execution_id` is the root's; `c2` and later root steps not run |
+| `Root.continue(id:, payload:, step_name: [:c, :approve])` | `completed`; each step ran once; same result as an uninterrupted run |
+| Two composes deep | `ready_interrupt_steps == [[:c, :c, :approve]]` (path through both composes) |
+| `continue` with `:approve` or a wrong path | `ValidationError` listing `[[:c, :approve]]`; still `paused` |
+| `Child.continue(id: <child id>, …)` | `ValidationError` "is a composed child" |
+| `Root.undo(id)` while paused | `undo:child.c1` before `undo:r1`, each once; `cancelled` |
+| Invalid payload, `max_attempts: 1` | rolled back from the root; `failed` |
+| `resume: :background` on the child interrupt | root's worker runs the remainder; the child is never enqueued |
+| `interrupt` inside a map element (direct or via compose) | element fails with "not supported inside a map element" |
+
+## 2. Demo app (Constitution VI)
+
+Fast local loop (test Redis DB 5, no Docker):
+
+```bash
+cd demo_app
+REDIS_URL=redis://localhost:6780/5 RAILS_ENV=test bundle exec rspec spec/reactors/composed_approval_reactor_spec.rb
+REDIS_URL=redis://localhost:6780/5 bin/rails demo:composed_interrupt
+```
+
+The rake task prints the pause (status, root id, pending path `[:approval, :wait_for_manager]`),
+then the outcome of an approved resume (`completed`) and of a rejected one (`undo` → `cancelled`,
+with the child's step undone).
+
+Acceptance run (isolated compose project; see the per-worktree note in the repo memory):
+
+```bash
+docker compose -p rr_interrupt_compose -f docker-compose.yml -f <override.yml> up -d --build demo-redis demo-sidekiq
+docker compose -p rr_interrupt_compose -f docker-compose.yml -f <override.yml> \
+  run --rm --no-deps demo-app bash -c "bin/rails db:prepare && bin/rails demo:composed_interrupt"
+```
+
+## 3. Docs check
+
+- `documentation/composition.md`: the "not supported yet" sentence is gone, and the nested pause
+  is described.
+- `documentation/interrupts.md`: has a "Interrupts inside composed reactors" section with the path
+  form, undo and correlation behavior.
+- `README.md` Interrupts section: one line pointing to it.
+- `CHANGELOG.md` *Unreleased → Features*: the entry is there.
+- `specs/future_improvements.md`: the "Interrupt inside a composed child" entry is removed.

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

@@ -0,0 +1,207 @@
+# Research: Interrupt Inside a Composed Child
+
+Every decision below was taken by reading the code on `main` (5ca7d1d1). Line references are to
+that commit.
+
+## R-01: Where the pause breaks today
+
+**Finding**: The child's executor handles its own pause correctly: `handle_interrupt_step` sets the
+child's `current_step`, `update_context_status` marks it `paused`, `handle_interrupt` saves it.
+The crash comes later, in the parent, at three places that do not know `InterruptResult`:
+
+1. `ComposeStep#handle_execution_result` calls `result.success?` (`compose_step.rb`, last method).
+2. `RetryManager#handle_retry_result` falls to `else` and turns it into a `Failure("returned
+   unexpected result")`.
+3. `ResultHandler#handle_step_result` falls to `handle_unknown_result`, which would record it as a
+   completed step.
+
+**Decision**: Pass `InterruptResult` through all three. Each gets one explicit arm.
+
+**Alternatives rejected**: A parent-side exception to unwind the stack (like
+`Error::RollbackHandedOff`). An interrupt is a normal result, not an error; `execute_all_steps`
+already stops on it (`step_executor.rb:50`), and both `update_context_status` and
+`execute_current_step_and_continue` already list it as terminal.
+
+## R-02: The paused result names the root run
+
+**Finding**: The child's `InterruptResult` carries the child's `context_id`. A caller would get an
+id that `Root.find` cannot load as the root.
+
+**Decision**: `ComposeStep#handle_execution_result` rebuilds the result with `execution_id:
+context.context_id`, the step's own context, keeping `correlation_id`, and passing
+`context.intermediate_results`. Each compose level re-stamps its own id, so at any depth the
+top-level result carries the root's id.
+
+The root executor's `handle_interrupt` then stores the correlation mapping against the root id
+and the root class (`executor.rb:1016`) with no change.
+
+## R-03: The root's resume cursor
+
+**Finding**: `execute_step_sync_without_result_handling` runs the compose body inside
+`Context#with_step`, whose `ensure` restores the previous `current_step` (nil) when the body
+returns. A root-level interrupt avoids this: `handle_interrupt_step` runs outside `with_step` and
+sets `current_step` itself. After a nested pause, the root would have no cursor, and
+`Reactor#continue` refuses a context without `current_step`.
+
+**Decision**: The `ResultHandler` arm for `InterruptResult` sets `@context.current_step =
+step_config.name`. On resume, `execute_current_step_and_continue` finds the compose step missing
+from `intermediate_results`, re-runs it, and `ComposeStep#run` → `execute_child_reactor` sees an
+admitted child and calls `resume_execution` on it. The child's own `current_step` is the
+interrupt, whose result is now set, so it carries on (`executor.rb:897`).
+
+## R-04: Undo of a run paused inside a child
+
+**Finding**: Rollback replays the undo stack (`CompensationManager#rollback_completed_steps`).
+A step joins it only on success (`ResultHandler#handle_success`). The paused compose step never
+succeeded, so `Root.undo` would undo `r1` and leave the child's `c1` done. A root-level interrupt
+has no such gap, because the interrupt step has no side effects.
+
+The same gap was already closed for an *interrupted* (aborted) compose:
+`StepExecutor#track_interrupted_construct` pushes the step with `result: Success(nil)` because
+`ComposeStep.undoes_partial_run?` is true, and `ComposeStep#compensate` undoes whatever the child
+completed.
+
+**Decision**: The `InterruptResult` arm in `ResultHandler` pushes the same partial-run entry for a
+step whose class `undoes_partial_run?`. When that step later completes,
+`CompensationManager#add_to_undo_stack` replaces a top entry for the same step instead of
+pushing a second one.
+
+- The entry is always the top: the root stops at the pause, so nothing runs after it, and on
+  resume the compose step is the first to run.
+- Replacing it keeps the undo trace to one `undo:<compose>` per run. Pushing twice would undo the
+  compose twice. The second undo would find the child's stack empty, so it would be harmless, but
+  still wrong.
+- `max_attempts` exhaustion calls `undo` (`reactor.rb:478`), so it is covered by the same entry.
+
+**Alternatives rejected**: Special-casing `Reactor#undo` for a paused run, to compensate the
+current compose step first. That is a second rollback path beside the undo stack, and the
+max-attempts path would need the same code again.
+
+## R-05: Naming a nested interrupt
+
+**Decision**: A path is an `Array` of two or more names: the compose step names from the root
+down, then the interrupt. Symbols and strings are both accepted, so a JSON body works through the
+web API's `continue` endpoint. A one-element array is the same as the bare name. A bare name
+keeps its current meaning, a step of the root.
+
+**Pending paths**: Derived from the stored state; no new field is stored. For a context and its
+reactor class:
+
+1. Take the ready steps from the dependency graph. This is the computation
+   `validate_continue_step!` and `TestSubject#ready_interrupt_steps` both do today.
+2. Keep the ready interrupt steps, as names.
+3. For a ready compose step whose stored child context (`composed_contexts[name][:context]`) is
+   `paused`, recurse into the child with its `reactor_class`, prefixing the compose name.
+
+**Decision**: Put this in one public method, `Reactor#ready_interrupt_steps`. It returns Symbols
+for root-level interrupts (unchanged for existing callers) and Arrays for nested ones.
+`TestSubject#ready_interrupt_steps` delegates to it, which removes the duplicated graph code
+there.
+
+**Alternatives rejected**:
+- Splat arguments (`be_paused_at(:fulfil, :approve)`): that already means two concurrent root
+  interrupts.
+- A dotted string `"fulfil.approve"`: step names may contain dots, and Symbol-vs-String parsing
+  would leak into every caller.
+- Matching a unique bare leaf: a root that later adds a step of that name silently changes what an
+  old `continue` call resumes.
+
+**Implementation notes** (added during `/speckit-implement`):
+
+- **Stricter bare names.** `Reactor#continue` now resolves bare names through
+  `ready_interrupt_steps` too. The old fast path accepted any `current_step`, and a compose step
+  is now a valid `current_step`: `continue(step_name: :fulfil)` would have stored the payload as
+  the compose's result and skipped the child. The old wording of the refusal ("expected step 'x'
+  or ready steps [...] but got 'y'") is kept, and it lists the pending interrupts.
+- **The paused-at interrupt stays pending.** A resume contended on the root's lock leaves its
+  payload stored and the run `paused` (`reopen_paused`). That stored payload marks the interrupt
+  complete in the graph. So the interrupt a context's `current_step` names stays pending anyway,
+  and the retry is accepted, at any depth (`resume_guard_spec.rb` and the nested contention
+  example).
+- **`Reactor.interrupt_key(step_name)`** (public class method) is the single normalizer: a
+  one-name path becomes its Symbol, otherwise an Array of Symbols. `continue`, the test subject
+  and the matchers use it.
+
+## R-06: `Reactor#continue` with a path
+
+**Decision**: Resolve the target once, at the top of `continue`: `target_context, step_config,
+leaf = resolve_interrupt_target(step_name)`.
+
+- For a bare name it is `@context`, `self.class.steps[name]`, `name`, which is today's behavior.
+- For a path it first checks membership in `ready_interrupt_steps`, raising `ValidationError` that
+  lists them. It then walks `composed_contexts` down the path and returns the child context, its
+  class's step config and the leaf.
+
+The rest of `continue` uses these three instead of `self.class.steps[step_name]` and
+`@context.set_result`:
+
+- payload validation;
+- the `max_attempts` counter, keyed by the joined path as a Symbol (`:"fulfil.approve"`) for a
+  nested interrupt, so it does not share a counter with a root step of the same name. It has to be
+  a Symbol: the serializer symbolizes `private_data` keys, so a String key would reset after every
+  reload;
+- `background_resume?`;
+- `set_result`.
+
+Status guards, the `running` claim, `save_context` and `resume_execution` stay on the root
+unchanged. So the paused-only guard (008 FR-032), cancel, lock contention (`reopen_paused`) and
+background resume (`enqueue_background_resume` enqueues the root) all apply to a nested resume for
+free.
+
+## R-07: A child never resumes on its own
+
+**Finding**: The child executor's `save_context` also stores the child under its own id and class
+(the observability row), and its `handle_interrupt` maps the correlation id to that row. So
+`Child.find(child_id)` loads a `paused` child, and `Child.continue(...)` or
+`Child.continue_by_correlation_id(...)` would run it as a standalone run. That breaks the
+single-writer rule: the root's embedded copy and the standalone row would diverge.
+
+**Decision**: `ComposeStep#prepare_child_context` marks a new child `private_data[:composed] =
+true`; `private_data` is already serialized. `Reactor#continue` raises `ValidationError` on a
+context carrying that mark (`"Cannot resume: <class> is a composed child; continue its root
+run"`).
+
+- This covers resume by id and by correlation id in one check.
+- The child's correlation row stays: the guard makes it harmless, and dropping it would need a
+  second check in `handle_interrupt`.
+- No stored child predates the mark and can be paused, since a nested pause crashed before this
+  feature.
+
+**Alternative rejected**: Guarding on `parent_context_id`. An `async_reactor` child
+(`async_reactor_step.rb:175`) sets it too, and that child *is* an addressable run that pauses and
+resumes on its own.
+
+## R-08: Interrupt inside a map element
+
+**Finding**: A map element that receives an `InterruptResult` crashes:
+
+- inline: `MapStep#execute_inline_map` calls `result.failure?`;
+- fan-out: `ElementExecutor.handle_result` calls `result.halted?`.
+
+This happens today for an `interrupt` directly in an element. After this feature, the same crash
+also happens for one reached through a compose inside the element.
+
+**Decision**: `StepExecutor#handle_interrupt_step` fails the step ("interrupt :name is not
+supported inside a map element") when the context or any `parent_context` up the chain has
+`map_metadata`. The `Failure` goes through `ResultHandler#handle_step_result`, as an
+argument-resolution failure does, so the element rolls back what it completed before the
+interrupt. The element then fails like any element: an atomic map rolls back, and a
+non-atomic one records the error. One check, at the source, covers both map modes and any compose
+depth inside the element.
+
+## R-09: Out of scope
+
+- `async_reactor` children are addressable runs of their own and already pause on their own. They
+  are unchanged.
+- `reconstruct_paused_result` keeps omitting `correlation_id`, for root-level and nested pauses
+  alike (spec FR-003).
+- The dashboard does not render the nested path. It reads the root's status (`paused`) and
+  drills into `composed_contexts` as today.
+- Compose steps cannot declare `retries` (008 R-14), so a pause never consumes a retry attempt
+  that matters. No decrement is needed.
+
+## R-10: SemVer
+
+The change is MINOR: a previously crashing case now works, plus one additive public method
+(`Reactor#ready_interrupt_steps`) and an additive argument form (Array `step_name`). Nothing that
+worked changes behavior.