ruby_reactor 0.8.6 → 0.8.8

data/lib/ruby_reactor/web/public/index.html

@@ -5,7 +5,7 @@
     <link rel="icon" type="image/svg+xml" href="./vite.svg" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <title>ui</title>
-    <script type="module" crossorigin src="./assets/index-C6ejszCQ.js"></script>
+    <script type="module" crossorigin src="./assets/index-DxjQlW7Q.js"></script>
     <link rel="stylesheet" crossorigin href="./assets/index-DM5darhy.css">
   </head>
   <body>

data/lib/ruby_reactor/worker.rb

@@ -8,7 +8,13 @@ module RubyReactor
   # `Adapters::ActiveJob::Compat` on ActiveJob::Base) — nothing here references
   # a specific backend.
   module Worker
-    TERMINAL_STATUSES = %w[completed failed cancelled skipped aborted].freeze
+    TERMINAL_STATUSES = %w[completed failed cancelled skipped halted aborted].freeze
+
+    # Seconds a Worker waits for the run's lock before it reads the run (010
+    # R-02). The usual holder is the caller that enqueued this job, a few
+    # milliseconds from its final save and release; a snooze would cost a whole
+    # scheduled-set poll instead. Same bound as `Map::Collector::COLLECT_LOCK_WAIT`.
+    CONTEXT_LOCK_WAIT = 2
 
     # Use the error's `retry_after_seconds` hint when available
     # (RateLimit::ExceededError carries the time until the bucket rolls);
@@ -81,16 +87,58 @@ module RubyReactor
     # Identity-only payload: storage is the source of truth. Rehydrate the live
     # context from storage by id, then resume. A nil read means the context was
     # swept, expired, or already terminal-and-collected — nothing to resume.
+    #
+    # Lock, then load (010 R-02, J-2): the run's `async:` lock is taken BEFORE
+    # the read, so this job sees the last save of whoever held it — a caller
+    # that just handed off, a manual undo, another worker — and its own later
+    # save can never replace newer progress. The executor re-enters the lock.
     def perform(context_id, reactor_class_name = nil, snooze_count = 0)
       # Normalize so a nil/omitted name resolves to the same storage key the
       # enqueue path wrote (always via reactor_storage_name). Without this a
       # nil here builds "reactor::context:<id>" and misses the stored
       # "reactor:AnonymousReactor:context:<id>", silently no-op'ing.
       reactor_class_name ||= RubyReactor.reactor_storage_name(nil)
+      lock = lock_run(context_id, reactor_class_name, snooze_count)
+      return if lock == :snoozed
+
+      begin
+        perform_locked(context_id, reactor_class_name, snooze_count, lock&.owner)
+      ensure
+        lock&.release
+      end
+    end
+
+    private
+
+    # nil in inline job-testing mode, where a nested re-entry would contend
+    # with itself (as `Executor#acquire_context_lock`). Another live holder
+    # after the wait: snooze, uncapped, having read and written nothing.
+    def lock_run(context_id, reactor_class_name, snooze_count)
+      return nil if inline_testing_mode?
+
+      lock = RubyReactor::Lock.new("async:#{context_id}", owner: SecureRandom.uuid,
+                                                          ttl: RubyReactor.configuration.context_lock_ttl,
+                                                          wait: CONTEXT_LOCK_WAIT, auto_extend: true)
+      lock.acquire
+      lock
+    rescue RubyReactor::Lock::AcquisitionError => e
+      contention = RubyReactor::Lock::ContextLockContention.new(e.message, context_lock_key: "async:#{context_id}")
+      handle_snooze(context_id, reactor_class_name, nil, snooze_count, contention)
+      :snoozed
+    end
+
+    def inline_testing_mode?
+      defined?(::Sidekiq::Testing) && ::Sidekiq::Testing.respond_to?(:inline?) && ::Sidekiq::Testing.inline?
+    end
+
+    def perform_locked(context_id, reactor_class_name, snooze_count, lock_owner)
       data = RubyReactor.configuration.storage_adapter.retrieve_context(context_id, reactor_class_name)
       return if data.nil?
-      # An aborted run is never resumed forward: only a manual undo applies (008 R-08).
-      return if (data["status"] || data[:status]).to_s == "aborted"
+
+      status = (data["status"] || data[:status]).to_s
+      # Finished, cancelled or aborted: nothing to resume (an aborted run takes
+      # only a manual undo, 008 R-08). A stray or duplicate job does nothing.
+      return if TERMINAL_STATUSES.include?(status)
 
       begin
         context = ContextSerializer.deserialize_hash(data)
@@ -115,6 +163,10 @@ module RubyReactor
         return
       end
 
+      # A paused run advances only with a claimed payload (010 R-06): a stray
+      # job must never run the steps that follow the interrupt without one.
+      return if status == "paused" && InterruptClaims.unapplied(context).empty?
+
       # Mark that we're executing inline to prevent nested async calls
       context.inline_async_execution = true
 
@@ -122,7 +174,8 @@ module RubyReactor
         # Resume execution from the failed step — or, for a run whose rollback
         # handed off at a fan-out map, finish that rollback (009 R-04).
         executor = Executor.new(context.reactor_class, {}, context)
-        rolling_back = (data["status"] || data[:status]).to_s == "rolling_back"
+        executor.context_lock_owner = lock_owner
+        rolling_back = status == "rolling_back"
         rolling_back ? executor.resume_rollback : executor.resume_execution
         # No explicit save here: resume_execution's ensure block already persists
         # the final root state (`save_context unless skip_context_persist?`), and
@@ -155,8 +208,6 @@ module RubyReactor
       end
     end
 
-    private
-
     # If reactor_class_name is provided, use it to get the reactor class.
     # This handles cases where the class can't be found via const_get.
     def resolve_reactor_class!(context, reactor_class_name)
@@ -203,6 +254,16 @@ module RubyReactor
                  error.is_a?(RubyReactor::Lock::ContextLockContention) ||
                  error.is_a?(RubyReactor::Error::ExecutionParked))
 
+      # Escalation marks the run `failed` WITHOUT rolling back: harmless before
+      # admission, when nothing ran, but a run already admitted (a resume,
+      # deferred or `resume: :background`, or a re-entry after a hand-off) has
+      # completed steps whose effects would be stranded. It keeps waiting
+      # instead, and says so once (010 R-07, J-8).
+      if capped && context&.admitted?
+        warn_still_waiting(context, snooze_count, error) if max != :infinity && snooze_count == max
+        capped = false
+      end
+
       if capped && max != :infinity && snooze_count >= max
         escalate_snooze(context, snooze_count, error)
         return
@@ -214,6 +275,12 @@ module RubyReactor
       self.class.perform_in(delay, context_id, reactor_class_name, snooze_count + 1)
     end
 
+    def warn_still_waiting(context, snooze_count, error)
+      fields = { event: "ruby_reactor.resume.waiting", reactor: RubyReactor.reactor_storage_name(context.reactor_class),
+                 context_id: context.context_id, error: error.message, snooze_count: snooze_count }
+      RubyReactor.configuration.logger.warn(fields.map { |k, v| "#{k}=#{v.inspect}" }.join(" "))
+    end
+
     # Instance methods delegate to the module functions above — worker
     # behavior is unchanged, just relocated so other callers (StepWorker,
     # T036) can reuse the same logic without a Worker instance.

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.