ruby_reactor 0.8.4 → 0.8.5

data/specs/008-rollback-reliability/contracts/api-surface.md

@@ -0,0 +1,126 @@
+# Contract: Public API Surface Changes
+
+These are the changes visible to gem users. No DSL keyword is added. The 2026-09-27 revision
+removes three: `retries` on `compose`/`async_reactor`, `where` and `guard` (§1).
+
+## 1. DSL
+
+### `async_step`: rollback declarations
+
+```ruby
+async_step :notify, NotifyStep do
+  argument :user_id, input(:user_id)
+  compensate { |error, inputs, ctx| Audit.log_failed_notification(inputs.user_id) } # runs in the unit's job
+  undo { |value, inputs, ctx| ... }   # => RubyReactor::Error::ValidationError at class definition
+end
+```
+
+**Inline `undo` in `async_step`** raises `Error::ValidationError` when the class is defined. The
+message names the step and explains:
+
+- An `async_step` is independent. Its parent never undoes it.
+- Cleanup for a surfaced failure belongs in the reading step's `compensate`.
+- Cleanup that must run when the parent rolls back needs a construct the parent tracks: a `step`,
+  a `compose` or a `map`.
+
+**A step class that defines `undo`**, used with `async_step`: a warning goes out through the
+existing definition-time warning channel (`StepBuilder#warn_deprecation`), once per reactor and
+step. It says the class's `undo` will not run for this async use. There is no error.
+
+**`compensate` in `async_step`** (inline or class) runs **once**, in the unit's own job, after the
+body's final attempt fails. It does not run on attempts that are retried, on `Halt`, or on
+never-started failures.
+
+### `map`: no DSL change
+
+Rollback replays the `undo` blocks already declared on the element reactor's steps.
+
+### Removed: `retries` on `compose` / `async_reactor` (R-14)
+
+```ruby
+compose :reserve, ReservationReactor do
+  retries max_attempts: 3   # => RubyReactor::Error::DeprecatedDslError at class definition
+end
+```
+
+The message names the step and says to declare `retries` on the child reactor's own steps. The same
+applies inside an inline `compose` block and in an `async_reactor` block. Without `retries`, both
+constructs run their child exactly once per parent step.
+
+### Removed: `where` / `guard` (R-15)
+
+```ruby
+step :sync_user, SyncUserStep do
+  where { |ctx| ctx.get_input(:enabled) }   # => RubyReactor::Error::DeprecatedDslError
+end
+```
+
+The message names the step and says to return `Skipped(value)` (or call `skip!`) from the step
+body. It applies to `step`, `async_step` and `interrupt` blocks.
+
+### `Skipped`: meaning defined (R-17)
+
+`Skipped` is an instrumentation mark and never changes execution: a `background after:` hand-off
+fires and a `with_period` bucket is marked, as for a `Success` (before: neither). A skipped step is
+never undone (unchanged).
+
+## 2. Errors (`RubyReactor::Error`)
+
+| Class | Parent | Raised by | Carried on the Failure as |
+| --- | --- | --- | --- |
+| `ArgumentResolutionError` (new) | `Error::Base` | a step's `argument` source, `transform` or result path raising | `step_name`, `exception_class` = the cause's class, `retryable: false` |
+| `Rescuable` (new, a matcher module, not an exception class) | — | used in `rescue Error::Rescuable` | matches every `Exception` except `SignalException`, `SystemExit`, `NoMemoryError`, `Timeout::ExitException` |
+
+`ArgumentResolutionError` does not propagate out of `Reactor.run`. The run returns a `Failure` as
+for any step failure. (`ConditionError` from the first implementation is removed, R-15.)
+
+## 3. `RubyReactor::Failure`
+
+| Path | Before | After |
+| --- | --- | --- |
+| argument resolution raises | `"Execution failed: <msg>"`, no `step_name`, nothing rolled back | step failure message, `step_name`, `reactor_name`, `step_arguments: {}`, completed steps undone |
+| unknown exception outside a step body (standard or not, except interruptions) | `"Execution failed: <msg>"`, no rollback | completed steps undone. `step_name` = the executing step when known |
+| non-`StandardError` raised by a step body (e.g. `NotImplementedError`, custom `Exception`) | propagated out of `Reactor.run`, no rollback | returned as the step's `Failure`: step compensated, completed steps undone, `exception_class` = the original class |
+| compensation of the failing step fails (`CompensationError`) | `"Execution error: <msg>"`, no `step_name` | same message, `step_name` set |
+
+### `rollback_failures` entries
+
+The existing keys are `step`, `kind`, `key`, `reason` and `message`. New optional keys:
+
+- `map_step`: Symbol
+- `element_index`: Integer
+
+New `reason` values:
+
+- `:context_unavailable`: an element context expired before rollback
+- `:element_in_flight`: the element was still running at rollback time
+
+## 4. Execution status
+
+- **New status `aborted`**:
+  - Readable on the stored context: `status`, dashboard, web API.
+  - Set only for executions in the caller's process that are cut short by an interruption
+    (`SignalException`, `SystemExit`, `NoMemoryError`, `Timeout::ExitException`). The exception is
+    re-raised unchanged. Its stored undo stack holds only the entries not yet undone.
+  - The reactor `Sweeper` does not resume aborted executions.
+  - `Reactor#undo` (manual undo) rolls them back.
+- **Dashboard and web API**:
+  - `aborted` is accepted in status filters and shown like the other terminal-looking states.
+  - It is not grouped with `failed`, because no rollback ran.
+
+## 5. Stored records
+
+- **Async step result record**: gains `compensation: { status, rollback_failures, completed_at }`
+  when the unit's compensate ran (data-model §8).
+- **Map results hash**: an index can hold `{ "_skipped" => true }`. `ResultEnumerator` never yields
+  skipped slots. They exist only on a failed fail-fast map, which is never collected as a success.
+
+## 6. Middleware events
+
+No new event names. Changes in when existing events fire:
+
+- `start_compensation` / `complete_compensation` / `failed_compensation` now fire in the async step
+  unit's job, with the unit's context and step name.
+- `start_undo` / `complete_undo` / `failed_undo` fire for each element step undone by a map
+  rollback, with the **element's** context.
+- `failed_step` for argument-resolution failures now carries the step name, like any step failure.

data/specs/008-rollback-reliability/contracts/rollback-semantics.md

@@ -0,0 +1,76 @@
+# Contract: Rollback Semantics
+
+This is the behavior contract reactor authors can rely on after this feature. The tests (R-11) and
+the updated 007 harness (SC-002) check it event by event.
+
+Notation: `run:x`, `compensate:x`, `undo:x`. `e.s[i]` is step `s` of map element `i`.
+`child.s` / `k.s` is a step of a composed child. `=> failure(x)` means the failure is attributed to
+step `x`.
+
+## 1. The one rule
+
+1. A construct that **completed** is tracked for undo, unless it is an async unit
+   (`rollback_tracked? == false`, which is the documented independence).
+2. On failure, the failing construct is **compensated** if its work started. It is **not**
+   compensated if it never started: contention, key error, refused dispatch, argument resolution
+   error, argument/type validation.
+3. Then every tracked construct is **undone**, newest first.
+4. A compensate or undo that fails does not stop the rest. It is listed in `rollback_failures`.
+5. `Halt` stops without rollback. `Skipped` never changes execution and is never undone; it
+   marks the trace.
+6. Every exception counts as a failure under rules 2–4, standard or not, except an interruption
+   (`SignalException`, `SystemExit`, `NoMemoryError`, an enclosing timeout). An interruption runs no
+   rollback. An execution in the caller's process is marked `aborted`, keeping only the entries not
+   yet undone, and `Reactor#undo` rolls it back later. A worker execution is redelivered.
+7. A nested reactor (`compose`, `async_reactor`) is never retried as a whole. Only steps retry.
+
+## 2. What compensate and undo mean per construct
+
+| Construct | compensate (its own failure) | undo (a later failure, or manual undo) |
+| --- | --- | --- |
+| step | its `compensate` (inline block, else class, else skipped) | its `undo` (same order) |
+| `compose` | replay the child's undo stack. The child already rolled itself back, so this is a no-op | replay the child's undo stack, newest first |
+| `map` (inline and fan-out) | replay the undo stack of every **completed** element, in descending element index. Failed elements rolled themselves back already | the same, for every completed element |
+| `map` fan-out, fail-fast | as above, after **every** index has settled. Elements that were in flight when the failure happened are included | as above |
+| `async_step` | not tracked by the parent. The **unit** compensates itself once, in its own job, after its final attempt fails | none. An inline `undo` block is rejected at definition time; a class `undo` is warned about and not run |
+| `async_reactor` | not tracked by the parent. The child rolls itself back (unchanged) | none (unchanged) |
+
+## 3. Canonical sequences (old → new)
+
+These are the 007 scenarios whose sequence changes. All other 007 scenarios are unchanged. The last
+four rows were found when the harness was re-run (T069): each is a direct consequence of an in-scope
+fix (F-13, F-01, F-04, R-06), not a separate change.
+
+| Scenario | Baseline (0.8.3) | After this feature |
+| --- | --- | --- |
+| S-map-01 inline, fail-fast, elem 2 fails | `… compensate:e.e2[2] undo:e.e1[2] undo:a` | `… compensate:e.e2[2] undo:e.e1[2] undo:e.e2[1] undo:e.e1[1] undo:e.e2[0] undo:e.e1[0] undo:a => failure(m)` |
+| S-map-03 inline, all ok, b fails | `… run:b compensate:b undo:a` | `… run:b compensate:b undo:e.e2[3] undo:e.e1[3] undo:e.e2[2] undo:e.e1[2] undo:e.e2[1] undo:e.e1[1] undo:e.e2[0] undo:e.e1[0] undo:a => failure(b)` |
+| S-map-04 fan-out, fail-fast, jobs 0..3 | `… compensate:e.e2[2] undo:e.e1[2] undo:a` | `… compensate:e.e2[2] undo:e.e1[2] undo:e.e2[1] undo:e.e1[1] undo:e.e2[0] undo:e.e1[0] undo:a => failure(m)` (elem 3 skipped) |
+| S-map-04b fan-out, fail-fast, jobs 3,2,1,0 | `… run:e.e1[3] run:e.e2[3] … compensate:e.e2[2] undo:e.e1[2] undo:a` | `… compensate:e.e2[2] undo:e.e1[2] undo:e.e2[3] undo:e.e1[3] undo:a => failure(m)` (elems 1, 0 skipped) |
+| S-map-06 fan-out, all ok, b fails | `… run:b compensate:b undo:a` | same as S-map-03 |
+| S-map-07 compose(c0 → map(elem 2 fails)) | `… undo:e.e1[2] undo:child.c0 undo:a` | `… undo:e.e1[2] undo:e.e2[1] undo:e.e1[1] undo:e.e2[0] undo:e.e1[0] undo:child.c0 undo:a => failure(child)` |
+| S-map-08 element = e1 → compose(k1) → e2 | `… compensate:e.e2[2] undo:k.k1 undo:e.e1[2]` | `… compensate:e.e2[2] undo:k.k1 undo:e.e1[2] undo:e.e2[1] undo:k.k1 undo:e.e1[1] undo:e.e2[0] undo:k.k1 undo:e.e1[0] => failure(m)` |
+| S-compose-05 compose declares `retries` | `… retry:child#1 run:child.c2 => success` | `=> raised(DeprecatedDslError)` at class definition (R-14) |
+| S-compose-05b child's c2 declares `retries`, fails once, then b fails | `… run:child.c2 run:b compensate:b undo:child.c2` (compose retries) | `run:child.c1 run:child.c2 retry:c2#1 run:child.c2 run:b compensate:b undo:child.c2 undo:child.c1 => failure(b)`: c1 runs once, c2 retries inside the child (R-14) |
+| S-plain-07 b's transform raises | `run:a => failure(?)` | `run:a undo:a => failure(b)` |
+| S-edge-03 b raises a custom `Exception` subclass | `run:a run:b => raised` (status `running`) | `run:a run:b compensate:b undo:a => failure(b)` (R-16) |
+| S-edge-03b (new) b raises `Interrupt` | — | `run:a run:b => raised(Interrupt)` (same object), status **`aborted`**. `Reactor#undo` then gives `undo:a` |
+| S-edge-04 b declares `where` | `run:a compensate:b undo:a => failure(b)` | `=> raised(DeprecatedDslError)` at class definition (R-15) |
+| S-async-02 unit u fails, reader r fails | `run:a run:u run:r compensate:r undo:a` | `run:a run:u compensate:u run:r compensate:r undo:a => failure(r)` |
+| S-async-07 unit u retries 3× then fails, no reader | `run:a run:b run:u run:u run:u => success` | `run:a run:b run:u run:u run:u compensate:u => success` (`compensate:u` recorded on the unit's record) |
+| S-plain-03 b fails, its compensate fails | `run:a run:b compensate:b undo:a => failure(?)` | same sequence `=> failure(b)` (a `CompensationError` carries the step name, FR-017) |
+| S-map-12 fan-out map, element has an async_step, elem 1 fails | `… compensate:e.e2[1] undo:e.e1[1] undo:a run:e.u[0] run:e.u[1]` | `… compensate:e.e2[1] undo:e.e1[1] undo:e.e2[0] undo:e.e1[0] undo:a run:e.u[0] run:e.u[1] => failure(m)` (element 0 is rolled back; its async unit is not, INV-25) |
+| S-async-01 unit u fails, no reader | `run:a run:b run:u => success` | `run:a run:b run:u compensate:u => success` |
+| S-async-08 reader's wait on u times out | `run:a undo:a run:u => failure(?)` | `run:a undo:a run:u compensate:u => failure(r)` (the timeout is wrapped as the reader's `ArgumentResolutionError`) |
+
+## 4. Guarantees tied to invariants
+
+| Invariant | After this feature |
+| --- | --- |
+| INV-06 every failure after completed work rolls back | HOLDS for every exception except interruptions, which give `aborted` plus manual undo |
+| INV-07 never-started is never compensated | HOLDS, including argument resolution errors (`where`/`guard` no longer exist) |
+| INV-13 a retried unit does not treat rolled-back work as done | HOLDS: only steps retry; a nested reactor cannot be retried as a whole |
+| INV-19 / INV-20 succeeded map elements are rolled back | HOLDS in both modes |
+| INV-22 left-in-place set after fail-fast is deterministic | HOLDS (it is always empty). Which elements run stays scheduling-dependent |
+| INV-24 a unit's own compensate runs | HOLDS (unit-local, once, after the final attempt) |
+| INV-25 parent rollback never touches async units | HOLDS (unchanged; expressed via `rollback_tracked?`) |

data/specs/008-rollback-reliability/data-model.md

@@ -0,0 +1,139 @@
+# Data Model: Reliable Rollback Across Constructs
+
+These are the records and state this feature adds or changes. The existing shapes are in
+`lib/ruby_reactor/context.rb` (context blob) and `lib/ruby_reactor/storage/redis_adapter.rb`
+(map and step records). Decisions are referenced as `R-nn` ([research.md](research.md)).
+
+## 1. Construct (step config): lifecycle operations (R-01)
+
+`StepConfig` is the step as declared in a reactor. Behavior only, nothing is stored.
+
+| Operation | Returns / raises | Notes |
+| --- | --- | --- |
+| `resolve_arguments(context)` | `Hash` of resolved arguments. Raises `Error::ArgumentResolutionError` on any `Error::Rescuable` exception (R-16), except `Error::ExecutionParked` and its subclasses, which propagate | Replaces `StepExecutor#resolve_arguments` and `StepWorker#resolve_arguments` |
+| `call_body(arguments, context)` | step result (exists) | unchanged |
+| `call_compensate(error, arguments, context)` | step result | Dispatch order: inline block, then impl `.compensate`, then `Skipped`. Moved out of `CompensationManager` |
+| `call_undo(result_value, arguments, context)` | step result | Dispatch order: inline block, then impl `.undo`, then `Skipped` |
+| `rollback_tracked?` | `true` unless `async_dispatch?` | `ResultHandler` pushes a success only when this is true |
+
+Coordination re-take, trace entries, middleware events and `rollback_failures` stay in
+`CompensationManager`, which wraps these calls.
+
+## 2. Never-started errors (R-06)
+
+| Class | Parent | Attributes | Retryable |
+| --- | --- | --- | --- |
+| `Error::ArgumentResolutionError` | `Error::Base` | `step`, `original_error`, `exception_class` (the cause's class name), `message` | no |
+`CompensationManager::NEVER_STARTED_ERROR_CLASSES` becomes `Contended`, `KeyError`,
+`DispatchRefused`, `ArgumentResolutionError`. (`ConditionError` was removed with `where`/`guard`,
+R-15.)
+
+**Rule**: a failure whose error is in this set is not compensated, and the completed steps are
+undone.
+
+## 3. Context status (R-08)
+
+| Status | Meaning | Set by | Terminal for `Worker`? | Swept? |
+| --- | --- | --- | --- | --- |
+| `pending`, `running`, `paused`, `completed`, `failed`, `halted`, `cancelled` | unchanged | unchanged | unchanged | only `running` |
+| **`aborted`** (new) | An execution in the caller's process was cut short by an interruption (R-16: signal, exit, out of memory, enclosing timeout). Its completed work is still outstanding, and `undo_stack` keeps exactly the entries not yet undone | `Executor#execute`/`#resume_execution` `rescue Exception` (reached only by interruptions), when `!inline_async_execution` | not resumed forward (only a manual undo applies) | no |
+
+State transitions:
+
+```text
+running --(interruption, caller process)--> aborted --(Reactor#undo)--> cancelled
+running --(interruption, worker)----------> running (job redelivered, unchanged)
+running --(any other exception)-----------> failed (rolled back, like any step failure)
+```
+
+## 4. Undo record (context `undo_stack` entry)
+
+The shape is unchanged: `{ step_name, arguments, result }` serialized.
+
+| Construct | Pushed when | `arguments` / `result` stored |
+| --- | --- | --- |
+| step | success and `rollback_tracked?` | resolved arguments / result (unchanged) |
+| compose | success | unchanged |
+| map, inline | success (unchanged) | unchanged (resolved args + collected result) |
+| **map, fan-out** (new, R-03) | collector success branch, before resuming the parent | `{}` / `Success(nil)`. `MapStep#undo` reads neither field |
+| `async_step`, `async_reactor` | never (`rollback_tracked? == false`) | — |
+
+## 5. Map element outcome (R-02, R-04)
+
+Element outcome is derived. It is not stored as a new field.
+
+| Outcome | Source of truth | Rolled back by the map? |
+| --- | --- | --- |
+| succeeded | element context `status == completed` | **yes**: replay its undo stack, then save the element |
+| failed | element context `status == failed` (it already rolled itself back) | no |
+| halted | element context `status == halted` | no (`Halt` semantics unchanged) |
+| skipped (fail-fast) | results hash slot `{ "_skipped" => true }`. No executed context | no |
+| never dispatched (fail-fast) | results hash slot `{ "_skipped" => true }`, written by the dispatcher claim | no |
+| context expired | id in the element index, context row missing | reported: `reason: :context_unavailable` |
+| live duplicate | the `map_element:<map_id>:<index>` lock is held when rollback runs | reported: `reason: :element_in_flight` |
+
+**Element index**: the existing list `store_map_element_context_id(map_id, context_id, parent_class)`.
+Rollback dedupes the ids. The element index number comes from the element context's
+`map_metadata[:index]`.
+
+**Settled**: every `0...count` index has a slot in the results hash. The slot is a value, an
+`_error`, a `_halt` or a `_skipped`. A fail-fast failure is applied to the parent only once the map
+is settled.
+
+**Order**: descending element index.
+
+## 6. Rollback failure entry
+
+These are the existing keys: `step`, `kind` (`:compensate`/`:undo`), `key`, `reason`, `message`.
+
+| Addition | When |
+| --- | --- |
+| `map_step:` (Symbol) | the entry came from a map element's rollback |
+| `element_index:` (Integer, or `nil` for `:context_unavailable`) | same. It is `nil` when the element's row expired, because the index lives only in the row |
+| `reason: :context_unavailable` | an element context expired before rollback |
+| `reason: :element_in_flight` | the element's liveness lock was held at rollback time |
+
+Entries from an element's own steps keep `step:`, the element step's name.
+
+## 7. Trace entry: discarded compose attempt (removed, R-14)
+
+The `compose_attempt_discarded` entry R-05 added is removed. A compose is never retried, so there
+are no discarded attempts.
+
+## 8. Async step record: compensation (R-09)
+
+This adds one field to the existing step result record (`store_step_result`). The unit writes it
+in its own job and never writes the parent context.
+
+```text
+"compensation" => {
+  "status" => "completed" | "failed" | "skipped",   # skipped: compensate returned Skipped / not declared
+  "rollback_failures" => [<entries>],
+  "completed_at" => iso8601
+}
+```
+
+The field is present only when the body ran and finally failed. It is absent for successes, halts,
+never-started failures and retried attempts that later succeeded.
+
+## 9. Failure attribution (FR-017)
+
+Every failure returned on these paths carries `reactor_name`, `step_name` (when a step was
+executing), redacted `inputs` and a reason. `exception_class` is the original cause's class:
+
+- argument resolution
+- any other `Error::Rescuable` exception, standard or not (R-16)
+- a failed compensation (`CompensationError`)
+
+## 10. Exception classes (R-16)
+
+| Class | Rolls back? | Outcome |
+| --- | --- | --- |
+| `Error::Rescuable` (any `Exception` except the four below) | yes | failure returned, step compensated if its body started, completed steps undone |
+| `SignalException` (incl. `Interrupt`, `Sidekiq::Shutdown`), `SystemExit`, `NoMemoryError`, `Timeout::ExitException` | no | re-raised unchanged. A caller-process run is stored `aborted`; a worker job is redelivered |
+
+## 11. Undo stack during rollback (R-16)
+
+`rollback_completed_steps` pops each entry after its undo returns (a failed undo is still popped and
+recorded in `rollback_failures`, as before). The stored stack of an aborted run is therefore the set
+of entries still to undo, newest last.

data/specs/008-rollback-reliability/plan.md

@@ -0,0 +1,233 @@
+# Implementation Plan: Reliable Rollback Across Constructs
+
+**Branch**: `execution_flow_analysis` | **Date**: 2026-09-26, revised 2026-09-27 (PR #65 review) | **Spec**: [spec.md](spec.md)
+
+**Input**: Feature specification from `specs/008-rollback-reliability/spec.md`
+
+## Summary
+
+This plan closes the four High findings from the 007 analysis, and the smaller findings the same
+fixes cover, so that every construct rolls back by one rule:
+
+- **F-01**: map elements that succeeded are never rolled back.
+- **F-02**: a retried `compose` resumes a child that was already undone.
+- **F-03**: some failures skip rollback entirely.
+- **F-04**: an `async_step`'s own `compensate`/`undo` never run.
+- **Also fixed**: F-05 (fan-out leftovers depend on scheduling), F-06 (a raising condition
+  compensates a step that never ran) and F-13 (failures without a step name).
+
+**Revision 2026-09-27 (PR #65 review)**. The first implementation is on the branch. The review
+reverses three of its decisions, and this plan now covers the rework (research R-14–R-18):
+
+- **R-14**: nested reactors are never retried as a whole. `retries` on `compose`/`async_reactor`
+  raises at class definition. The fresh-child code (R-05) is deleted. This closes F-02.
+- **R-15**: `where`/`guard` are removed. `ConditionError` goes with them. This closes F-06.
+- **R-16**: every exception rolls back except interruptions (`SignalException`, `SystemExit`,
+  `NoMemoryError`, `Timeout::ExitException`). One matcher module, `Error::Rescuable`, replaces
+  `rescue StandardError` at the user-code boundaries. `aborted` is kept for interruptions only, and
+  the rollback loop pops each undo entry as it completes.
+- **R-17**: `Skipped` is documented as "this run caused no effect". No code change.
+
+Approach of the first implementation ([research.md](research.md)), still valid except where marked:
+
+- **Bounded "step owns its lifecycle" refactor (R-01)**:
+  - `StepConfig` becomes the single owner of each step's lifecycle operations: resolve arguments,
+    conditions, body, compensate, undo, and whether a success is tracked for undo.
+  - Construct classes own what rollback means for them: `MapStep` replays its elements, and
+    `ComposeStep` starts a fresh child on retry.
+  - The executor keeps only orchestration.
+- **Map (R-02–R-04)**:
+  - `MapStep#compensate`/`#undo` replay each completed element's own undo stack, found through the
+    element index both modes already write.
+  - A fan-out map joins the parent's undo stack.
+  - A fail-fast fan-out waits until every index has settled before it rolls back.
+- **Compose (R-05, superseded by R-14)**: ~~a retry after a failed attempt starts a fresh child~~.
+  A compose cannot be retried.
+- **Failures (R-06–R-08, revised by R-15/R-16)**:
+  - Argument errors become attributed never-started failures (condition errors no longer exist).
+  - Every exception except interruptions rolls back.
+  - Interruptions mark an inline run `aborted`.
+- **async_step (R-09, R-10)**:
+  - The unit compensates itself once in its own job after its final failure.
+  - An inline `undo` is rejected at definition time; an `undo` inherited from a step class is
+    warned.
+  - Async units declare themselves as not tracked for undo.
+
+## Technical Context
+
+**Language/Version**: Ruby >= 3.0
+
+**Primary Dependencies**: Sidekiq (async router), Redis (state, locks), dry-validation (contracts),
+optional OpenTelemetry middleware. No new dependencies.
+
+**Storage**: Redis via `RubyReactor::Storage::RedisAdapter`. The map element-context index,
+map results hash, context rows and step result records already exist. New stored data:
+`_skipped` result slots (R-04), `compensation` on the async step record (R-09), status value
+`aborted` (R-08, R-16). The `compose_attempt_discarded` trace entry (R-05) is removed by R-14.
+
+**Testing**: RSpec against real Redis (`redis://localhost:6780`). Sidekiq fake mode plus
+`drain_async_jobs` for fan-out and async paths. The 007 evidence harness is used as the
+regression check (SC-002). The demo app specs use the shipped matchers only.
+
+**Target Platform**: Ruby gem (MRI), Sidekiq workers, Rails demo app in Docker
+
+**Project Type**: Library (gem)
+
+**Performance Goals**:
+
+- Rollback of N succeeded map elements is linear in N and runs serially in the process that
+  detected the failure.
+- A 10,000-element map fails and rolls back without a storage size error (SC-006).
+- Fail-fast fan-out reports failure only after the slowest element in flight settles. This is
+  accepted and documented.
+
+**Constraints**:
+
+- Single-writer context rule: an async unit never writes its parent's context. Map rollback writes
+  element contexts only after they settle, under each element's liveness lock (R-02 §5).
+- No new per-element data in the parent blob (FR-008).
+- Park signals (`Error::ExecutionParked`) never turn into failures.
+
+**Scale/Scope**:
+
+- About 14 library files touched (below).
+- 6 new spec files, 1 tightened spec, and 1 updated evidence harness.
+- 4 demo artifacts per behavior group (reactor, rake task, spec).
+- 9 documentation files.
+
+## Constitution Check
+
+*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*
+
+| Principle | Status | Note |
+| --- | --- | --- |
+| I. Gem-First Design | PASS | All changes are inside `lib/`, behind the existing public API. No host coupling. The Sidekiq-specific parts stay in the existing workers and adapters. |
+| II. Saga Pattern Integrity | PASS (this feature exists for it) | It closes four violations of "partial execution without a recovery path is forbidden". Every exception raised by reactor code now rolls back (R-16). Interruptions get an explicit recovery path (`aborted` plus manual undo, with only the not-yet-undone entries kept) instead of a silent forward resume. |
+| III. Test-First with Real Infrastructure | PASS | Every behavior task writes its failing spec first against real Redis. Async paths use fake mode plus drain, never `inline!` (R-11). |
+| IV. Observability by Default | PASS | New failures carry reactor name, step name, redacted inputs and reason (FR-017). `aborted` is added to the dashboard state model. Unit compensation is recorded on the unit's record, and compensation middleware events fire. Map rollback failures carry `map_step`/`element_index`. |
+| V. Simplicity & SemVer | PASS with notes | The refactor is bounded to removing real duplicates (R-01). Full step self-execution was rejected. The revision deletes code: compose retries, `where`/`guard`, `ConditionError`. Six changes are breaking: element `undo`s run, `async_step` `compensate` runs, an inline `undo` on `async_step` raises, `retries` on `compose`/`async_reactor` raises, `where`/`guard` raise, and non-`StandardError` exceptions roll back instead of propagating. They are marked `!` and carry CHANGELOG migration notes (R-12). |
+| VI. Demo-App Proof of Feature | PASS (planned) | Demo reactor, rake task and matcher-based spec for map rollback, a compose whose child step retries itself, failure rollback (argument error and non-`StandardError`), `async_step` compensate and `aborted`. See Project Structure. The tasks are added to `demo:all`. The removed DSL needs no demo: a reactor that uses it cannot load. |
+
+- [x] Documentation impact identified (research R-13):
+  - **README.md**: lines 16, 25, 35, 545-550, 1309 and 1398, plus the Compensation section.
+  - **documentation/**: `data_pipelines.md`, `composition.md`, `background_and_async.md`,
+    `core_concepts.md`, `DAG.md`, `locks_and_semaphores.md`, `interrupts.md`.
+  - **007 analysis**: `execution-order.md` and `invariants.md`, refreshed.
+  - **CHANGELOG.md**: entries with migration notes.
+  - This is carried into tasks.md as a required task per user story.
+
+**Post-design re-check (after Phase 1, revised 2026-09-27)**: PASS. No new abstraction beyond the
+`StepConfig` methods that replace existing duplicates, and one matcher module (`Error::Rescuable`)
+that replaces a repeated `rescue StandardError` with the review's rule. The only new public error
+class is `ArgumentResolutionError`. There are no new DSL keywords, and three are removed.
+
+## Project Structure
+
+### Documentation (this feature)
+
+```text
+specs/008-rollback-reliability/
+├── plan.md              # This file
+├── research.md          # Phase 0: decisions R-01..R-13
+├── data-model.md        # Phase 1: records, statuses, entry shapes
+├── quickstart.md        # Phase 1: validation guide
+├── contracts/
+│   ├── rollback-semantics.md   # Per-construct rollback contract + sequences
+│   └── api-surface.md          # DSL, errors, Failure/rollback_failures, statuses, events
+├── checklists/requirements.md
+└── tasks.md             # Phase 2 (/speckit-tasks)
+```
+
+### Source Code (repository root)
+
+```text
+lib/ruby_reactor/
+├── dsl/step_builder.rb              # StepConfig: resolve_arguments, call_compensate, call_undo,
+│                                    #   rollback_tracked? (R-01/R-06/R-10); where/guard stubs (R-15)
+├── dsl/{compose,async_reactor}_builder.rb  # retries stub, no Retryable (R-14)
+├── dsl/{interrupt,map}_builder.rb   # drop conditions/guards (R-15)
+├── error/rescuable.rb               # new: rescue matcher, everything but interruptions (R-16)
+├── dsl/async_macros.rb              # async_step: reject inline undo, warn on class undo (R-09)
+├── error/argument_resolution_error.rb  # new (R-06)
+├── executor.rb                      # rescue Rescuable → failure; rescue Exception → :aborted (R-08/R-16)
+├── executor/step_executor.rb        # route resolution failures through result handling; use StepConfig ops
+├── executor/compensation_manager.rb # NEVER_STARTED += ArgumentResolutionError; compensate under with_step;
+│                                    #   public #compensate; dispatch via StepConfig; Rescuable; pop per entry
+│                                    #   (R-01/R-02/R-06/R-16)
+├── executor/result_handler.rb       # rollback on unknown errors + attribution; rollback_tracked? (R-07/R-10)
+├── step/map_step.rb                 # real compensate/undo = element replay (R-02)
+├── step/compose_step.rb             # fresh-child code removed (R-14)
+├── map/helpers.rb                   # collector success pushes map step on parent undo stack (R-03)
+├── map/collector.rb                 # fail-fast resolves only when no index is missing (R-04)
+├── map/element_executor.rb          # skipped element stores _skipped slot (R-04)
+├── map/dispatcher.rb                # on fail-fast, claim + settle undispatched indices (R-04)
+├── map/result_enumerator.rb         # tolerate _skipped slots (R-04)
+├── step_worker.rb                   # StepConfig ops; unit-local compensate + record (R-09)
+├── storage/redis_reactor_scan.rb    # 'aborted' known status (R-08)
+└── web/ (api.rb + UI filters)       # 'aborted' shown (R-08)
+
+spec/ruby_reactor/rollback/
+├── map_rollback_spec.rb
+├── map_fan_out_settle_spec.rb
+├── compose_retry_spec.rb        # rewritten for R-14
+├── failure_rollback_spec.rb     # condition examples out, non-StandardError examples in (R-15/R-16)
+├── aborted_execution_spec.rb    # Interrupt, mid-rollback interruption, enclosing Timeout (R-16)
+├── removed_dsl_spec.rb          # new: where/guard rejected (R-15)
+└── async_step_compensate_spec.rb
+spec/ruby_reactor/dsl/async_step_spec.rb   # tightened (line ~111)
+
+specs/007-execution-flow-analysis/evidence/probes/*.rb  # expected sequences updated for in-scope scenarios
+
+demo_app/
+├── app/reactors/{map_refund,compose_retry,argument_failure,async_step_compensate}_demo_reactor.rb
+├── lib/tasks/demo_reactors.rake            # demo:map_rollback, :compose_retry, :failure_rollback,
+│                                           #   :async_step_compensate, aggregate :rollback_reliability (in demo:all)
+└── spec/reactors/<same names>_demo_reactor_spec.rb
+
+README.md, documentation/*.md, CHANGELOG.md  # per R-13 / R-12
+```
+
+**Structure Decision**: single gem project. Changes stay within the existing `lib/ruby_reactor`
+module layout. There are no new directories under `lib/`. The new specs are grouped under
+`spec/ruby_reactor/rollback/` so the feature's coverage reads as one unit.
+
+## Delivery Order
+
+The user stories are independent. This order minimizes rework:
+
+1. **Foundation (R-01)**:
+   - `StepConfig` lifecycle methods: `resolve_arguments`, wrapping `should_run?` (removed by R-15), `call_compensate`,
+     `call_undo`, `rollback_tracked?`.
+   - `CompensationManager` dispatches through them and runs compensate under `with_step`.
+   - This is a refactor with no behavior change. The existing suite stays green.
+2. **US3 (P1) Failures**: R-06, R-07, R-08. These are the smallest changes, and they give every
+   later failure its attribution.
+3. **US2 (P1) Compose retry**: R-05.
+4. **US1 (P1) Map**: R-02, then R-03 (fan-out undo stack), then R-04 (settle). This is the largest
+   change.
+5. **US4 (P2) async_step**: R-09.
+6. **US5 (P3) One rule**: R-10, the refreshed F-10 table, the 007 docs refresh and the harness
+   re-run (SC-002).
+7. **Per story**: README and documentation edits, the demo artifacts and CHANGELOG. Each story ships
+   its own docs and demo, not in a final batch (Constitution Development Workflow).
+8. **Revision 2026-09-27** (steps 1-7 are done on the branch): R-14 (US2 rework), R-15 (US6), R-16
+   (US3 rework), R-17 (docs), each with its specs, demo, docs and CHANGELOG, then the harness re-run
+   and the full suite. R-18 lists the files.
+
+## Risks
+
+| Risk | Mitigation |
+| --- | --- |
+| Existing specs pin the old failure shapes ("Execution failed: …", "Execution error: …", no `step_name`) | Update them in the story that changes the shape, and note it in the CHANGELOG |
+| Sweeper re-enqueues **in-progress** inline runs (running, no `async:` lock). This is pre-existing, and unchanged except that aborted runs are now excluded | Out of scope. Record it in `specs/future_improvements.md` |
+| Element contexts that expire before a late rollback | Reported as `context_unavailable` in `rollback_failures`, never silent. `context_ttl` is documented as the rollback horizon |
+| Flaky specs when suites share the test Redis | Run the new specs alone before debugging. Don't run the demo and gem suites concurrently |
+| R-16 turns test assertion/mock errors raised inside step bodies into step failures, so an existing spec that relied on them propagating now sees a `Failure` | Run the full suite after the swap. A spec asserting on the result still fails loudly. Fix any spec that asserted inside a body by asserting on the result instead, and note the change in CHANGELOG |
+| Removing compose `retries` and `where`/`guard` makes 007 probe files fail at load | Move those reactor definitions inside their scenario blocks so the rejection is the observed outcome |
+| Demo Docker stack collides with other worktrees | Use an isolated compose project (`-p rr_<worktree>`) and an override file (quickstart) |
+
+## Complexity Tracking
+
+No Constitution violations to justify. The `StepConfig` lifecycle methods replace two duplicate
+implementations (`resolve_arguments` in the executor and the worker, and compensate dispatch in
+`CompensationManager` plus the new `StepWorker` need). They are not a new layer.