ruby_reactor 0.8.4 → 0.8.5

data/specs/007-execution-flow-analysis/evidence/probes/07_interrupts_manual.rb

@@ -0,0 +1,185 @@
+# frozen_string_literal: true
+
+# Interrupts, manual cancel/undo, failure kinds and crash re-drive:
+# research H2 (worker), H5 contrast, H24 (pause), H26–H28.
+
+module P
+  class Intr01 < Base
+    with_lock { |_inputs| "rk" }
+    pstep :a
+    interrupt(:approval) { wait_for :a }
+    pstep :c, after: :approval, fail: true
+  end
+
+  class Intr02 < Base
+    pstep :a
+    interrupt :approval do
+      wait_for :a
+      max_attempts 1
+      validate_payload { required(:ok).filled(:bool) }
+    end
+    pstep :c, after: :approval
+  end
+
+  class Intr03 < Base
+    pstep :a
+    interrupt(:approval) { wait_for :a }
+    pstep :c, after: :approval
+  end
+
+  class Intr04 < Base
+    with_lock { |_inputs| "rk" }
+    pstep :a
+    pstep :b, after: :a
+  end
+
+  # A worker-side step whose lock stays contended past lock_snooze_max_attempts.
+  class Edge01 < Base
+    background all: true
+    pstep :a
+    pstep(:b, after: :a) { with_lock { |_args| "sk" } }
+  end
+
+  class Crash < Exception; end # rubocop:disable Lint/InheritException
+
+  class Edge02 < Base
+    background all: true
+    pstep :a
+    pstep :b, after: :a do
+      run do |_inputs, _ctx|
+        Probe.rec("run:b")
+        # A killed worker is an interruption (Sidekiq::Shutdown < Interrupt);
+        # any other exception would be b's own failure and roll back (008 R-16).
+        raise Interrupt, "worker killed" if (Probe.counters[:crash] += 1) == 1
+
+        RubyReactor.Success("b")
+      end
+    end
+    pstep :c, after: :b
+  end
+
+  class Edge03 < Base
+    pstep :a
+    pstep :b, after: :a, fail: :raise do
+      run do |_inputs, _ctx|
+        Probe.rec("run:b")
+        raise Crash, "non-StandardError"
+      end
+    end
+  end
+
+  class Edge03b < Base
+    pstep :a
+    pstep :b, after: :a do
+      run do |_inputs, _ctx|
+        Probe.rec("run:b")
+        raise Interrupt, "signal"
+      end
+    end
+  end
+
+  class Edge05 < Base
+    pstep :a
+    pstep :b, after: :a do
+      inputs { input :x, :string }
+      argument :x, value(5)
+    end
+  end
+
+  class Edge06 < Base
+    input :n, :integer
+    pstep :a
+  end
+end
+
+def status_of(klass, id) = "status=#{klass.find(id).context.status}"
+
+Probe.scenario "S-intr-01", "reactor with_lock(rk): a → interrupt → [continue] → c(fails)",
+               mode: :inline,
+               expected: %w[lock_acquired:rk run:a lock_released:lock:rk lock_acquired:rk run:c compensate:c undo:a
+                            lock_released:lock:rk => failure(c)] do
+  paused = P::Intr01.run({})
+  Probe.note("first run => #{Probe.outcome(paused)}")
+  P::Intr01.continue(id: paused.execution_id, step_name: :approval, payload: { ok: true })
+end
+
+Probe.scenario "S-intr-02", "a → interrupt(validate, max_attempts 1) ← invalid payload",
+               mode: :inline, expected: %w[run:a undo:a => failure(approval)] do
+  paused = P::Intr02.run({})
+  P::Intr02.continue(id: paused.execution_id, step_name: :approval, payload: { ok: "nope" })
+end
+
+Probe.scenario "S-intr-03", "a → interrupt → Reactor.cancel",
+               mode: :inline, expected: %w[run:a => status=cancelled] do
+  paused = P::Intr03.run({})
+  P::Intr03.cancel(id: paused.execution_id, reason: "user gave up")
+  status_of(P::Intr03, paused.execution_id)
+end
+
+Probe.scenario "S-intr-04", "completed a → b; reactor lock rk held by another owner; Reactor.undo(id)",
+               mode: :inline, expected: %w[lock_acquired:rk run:a run:b lock_released:lock:rk undo:b undo:a
+                                           => status=cancelled] do
+  done = P::Intr04.run({})
+  P.hold_lock("rk", "someone-else")
+  P::Intr04.undo(done.execution_id)
+  status_of(P::Intr04, done.execution_id)
+end
+
+Probe.scenario "S-edge-01", "background all: a → b(step lock held elsewhere; lock_snooze_max_attempts 2)",
+               mode: :worker, expected: %w[run:a undo:a => failure(b)] do
+  RubyReactor.configuration.lock_snooze_max_attempts = 2
+  P.hold_lock("sk", "someone-else")
+  Probe.run_async(P::Edge01)
+ensure
+  RubyReactor.configuration.lock_snooze_max_attempts = 20
+end
+
+Probe.scenario "S-edge-02", "background all: a → b(worker crashes once) → c; job redelivered",
+               mode: :worker, expected: %w[run:a run:b crash run:b run:c => success] do
+  P::Edge02.run({})
+  job = RubyReactor::Adapters::Sidekiq::Worker.jobs.first.dup
+  begin
+    Probe.drain
+  rescue Interrupt
+    Probe.rec("crash")
+  end
+  RubyReactor::Adapters::Sidekiq::Worker.new.perform(*job["args"])
+  Probe.drain
+  P::Edge02.find(job["args"].first)
+end
+
+Probe.scenario "S-edge-03", "a → b(raises a non-StandardError Exception)",
+               mode: :inline, expected: %w[run:a run:b compensate:b undo:a => failure(b)] do
+  P::Edge03.run({}) # 008 R-16: the step's own failure, rolled back
+end
+
+Probe.scenario "S-edge-03b", "a → b(interrupted: raises Interrupt)",
+               mode: :inline, expected: %w[run:a run:b => raised(Interrupt)] do
+  reactor = P::Edge03b.new
+  reactor.run({})
+rescue Interrupt
+  stored = RubyReactor.configuration.storage_adapter.retrieve_context(reactor.context.context_id, "P::Edge03b")
+  Probe.note("stored status=#{stored["status"]}") # 008 R-08/R-16: aborted, awaiting a manual undo
+  "raised(Interrupt)"
+end
+
+Probe.scenario "S-edge-04", "a → b(declares a where-condition)",
+               mode: :inline, expected: %w[=> raised(RubyReactor::Error::DeprecatedDslError)] do
+  # 008 R-15: `where`/`guard` are removed, so the class cannot be defined.
+  Class.new(P::Base) do
+    pstep :a
+    pstep(:b, after: :a) { where { |_ctx| true } }
+  end
+rescue RubyReactor::Error::DeprecatedDslError
+  "raised(RubyReactor::Error::DeprecatedDslError)"
+end
+
+Probe.scenario "S-edge-05", "a → b(argument type check fails)",
+               mode: :inline, expected: %w[run:a undo:a => failure(b)] do
+  P::Edge05.run({})
+end
+
+Probe.scenario "S-edge-06", "reactor input validation fails",
+               mode: :inline, expected: %w[=> failure(?)] do
+  P::Edge06.run({ n: "not a number" })
+end

data/specs/007-execution-flow-analysis/evidence/run.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+# bundle exec ruby specs/007-execution-flow-analysis/evidence/run.rb [| tee …/output.txt]
+# PROBE=<substring> limits the run to matching scenario ids.
+
+require_relative "harness"
+
+puts "# Execution-flow probes — #{Time.now.utc.iso8601} — ruby_reactor #{RubyReactor::VERSION} " \
+     "(#{`git rev-parse --short HEAD`.strip})"
+puts
+
+Dir[File.join(__dir__, "probes", "*.rb")].each { |f| require f }
+
+total = Probe.tally.values.sum
+puts "#{total} scenarios, #{Probe.tally[:match]} match, #{Probe.tally[:mismatch]} mismatch"

data/specs/007-execution-flow-analysis/plan.md

@@ -0,0 +1,127 @@
+# Implementation Plan: Execution Flow & Compensation Analysis
+
+**Branch**: `execution_flow_analysis` | **Date**: 2026-09-26 | **Spec**: [spec.md](spec.md)
+
+**Input**: Feature specification from `specs/007-execution-flow-analysis/spec.md`
+
+## Summary
+
+A documentation-only research project. It maps how RubyReactor orders forward execution and
+rollback (compensate + undo) across plain steps, `compose`, `map` (inline and fan-out), `async_step`,
+`async_reactor`, `background` reactors and interrupts, under locks, retries and every failure kind.
+It answers the user's three open questions (map element rollback, rollback of earlier composed
+reactors, map-level `compensate_all`/`compensate_each`).
+
+Approach: read the executor source and cite it by `file:line`. Confirm each headline claim with a
+small **probe**, a throwaway reactor run against the real test Redis through the real worker code
+paths (Sidekiq fake mode + drain). Each probe prints its observed event sequence next to the
+sequence the report claims. Deliverables are Markdown under this feature directory. Library code,
+the test suite and the demo app are not touched.
+
+## Technical Context
+
+**Language/Version**: Markdown + Mermaid (report); Ruby >= 3.0 (probe scripts only, run against
+`lib/` of this checkout)
+
+**Primary Dependencies**: `ruby_reactor` (this checkout), `sidekiq/testing` fake mode, the
+`RubyReactor::RSpec::SidekiqHelpers.drain_async_jobs` helper (plain-Ruby callable), `redis` gem
+
+**Storage**: Test Redis at `redis://localhost:6780` (`RUBY_REACTOR_TEST_REDIS_URL` overrides), the
+same instance `spec/spec_helper.rb` uses
+
+**Testing**: Probes check themselves. Each scenario declares the expected event sequence and prints
+`MATCH` / `MISMATCH` with both sequences. No RSpec files are added (FR-011).
+
+**Target Platform**: Developer machine / CI shell with Redis reachable
+
+**Project Type**: Library research (no runtime change)
+
+**Performance Goals**: N/A. Full probe run should finish in under 1 minute, so it can be re-run
+as behavior changes.
+
+**Constraints**: Zero diff under `lib/`, `spec/`, `demo_app/`, `README.md`, `documentation/`
+(SC-005). Probes must not sleep on real backoff (use `base_delay: 0`/tiny delays).
+
+**Scale/Scope**: 6 constructs (step, compose, map, async_step, async_reactor, background reactor)
++ interrupts × failure positions (before / inside / after, nested) × modes (inline / worker) ×
+cross-cutting conditions (reactor lock, step lock/semaphore, ordered lock, retries, failure
+kinds). Roughly 40–60 matrix cells, 25–40 invariants.
+
+## Constitution Check
+
+*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*
+
+| Principle | Status | Note |
+|---|---|---|
+| I. Gem-First Design | PASS (N/A) | No `lib/` change. |
+| II. Saga Pattern Integrity | PASS | The research exists to check this principle; findings feed later remedies. |
+| III. Test-First with Real Infrastructure | PASS | No product code, so no Red-Green cycle. Probes use real Redis and real worker bodies, no mocks, matching the principle's intent. |
+| IV. Observability by Default | PASS (N/A) | No runtime change. Probes observe through the shipped middleware hooks. |
+| V. Simplicity & SemVer | PASS | No version bump, no API change. |
+| VI. Demo-App Proof of Feature | N/A (justified) | Not a user-facing feature or public API change. No demo reactor/rake/spec. Any remedy chosen later carries its own demo. |
+| Dev Workflow: docs task | PASS with deviation (see Complexity Tracking) | The documentation task here is an **audit**. Every README/documentation claim contradicted or left unstated by the findings is listed with `file:line` in the findings report. Editing those files is deferred to the remedy features, because behavior does not change here. |
+
+- [x] Documentation impact identified: README.md sections "Error Handling and Compensation",
+      "async_step" / "Compensation is opt-in", "async_reactor"; `documentation/composition.md`
+      (`async_reactor` vs `compose` table); `documentation/background_and_async.md` ("Compensation
+      is opt-in", "Error Handling and Compensation"); `documentation/data_pipelines.md` (fail_fast);
+      `documentation/core_concepts.md` ("Compensation Order"); `documentation/DAG.md`. All are
+      **audited**, not edited (tasks.md carries the audit task).
+
+**Post-design re-check (after Phase 1)**: unchanged. All gates PASS. The one deviation is tracked below.
+
+## Project Structure
+
+### Documentation (this feature)
+
+```text
+specs/007-execution-flow-analysis/
+├── spec.md
+├── plan.md                    # this file
+├── research.md                # Phase 0: method decisions + preliminary hypotheses
+├── data-model.md              # Phase 1: scenario / event / invariant / finding / option shapes
+├── quickstart.md              # Phase 1: how to run probes and validate the report
+├── contracts/
+│   └── report-structure.md    # Phase 1: required sections + ID/label conventions
+├── checklists/
+│   └── requirements.md
+├── tasks.md                   # Phase 2 (/speckit-tasks)
+├── analysis/                  # Deliverable (/speckit-implement)
+│   ├── README.md              # index, reading guide, answers to the 3 questions (US2)
+│   ├── execution-order.md     # construct lifecycles (FR-001) + order matrix (FR-002/003/012)
+│   ├── invariants.md          # invariants w/ status, evidence, test coverage (FR-006/008)
+│   └── findings-and-options.md# findings + doc audit (FR-009) and options (FR-010)
+└── evidence/                  # Reproducible observations (FR-007, SC-003)
+    ├── harness.rb             # recorder middleware, scenario DSL, Redis/Sidekiq setup
+    ├── probes/*.rb            # one file per area: plain, compose, map, async, coordination, edge
+    ├── run.rb                 # loads harness + probes, prints results
+    └── output.txt             # captured run transcript cited by the report
+```
+
+### Source Code (repository root)
+
+No source changes. Read-only inputs:
+
+```text
+lib/ruby_reactor/executor.rb                  # execute / resume_execution / lock lifetime
+lib/ruby_reactor/executor/*.rb                # step loop, retries, result handling, rollback, coordination
+lib/ruby_reactor/step/{compose,map,async_reactor}_step.rb
+lib/ruby_reactor/map/*.rb                     # dispatcher, element executor, collector, helpers
+lib/ruby_reactor/step_worker.rb, worker.rb    # async_step unit, reactor worker
+lib/ruby_reactor/reactor.rb                   # run / continue / undo / cancel
+lib/ruby_reactor/template/result.rb           # async result read semantics
+spec/**                                       # mapped for invariant coverage (FR-008)
+README.md, documentation/*.md                 # audited for claims (FR-009)
+```
+
+**Structure Decision**: Everything lives under `specs/007-execution-flow-analysis/`. The report
+is split into four files by question type (what order? what always holds? what is wrong and what
+could we do?), plus an index. Probes are grouped by area into a handful of files so each report
+claim can cite `probe-id` and the transcript line.
+
+## Complexity Tracking
+
+| Violation | Why Needed | Simpler Alternative Rejected Because |
+|-----------|------------|-------------------------------------|
+| Docs task is an audit, not README/documentation edits | This feature changes no behavior. The research shows some current behavior may be unintended (e.g. map rollback is a `TODO`). | Writing current behavior into README/documentation now would present possibly buggy semantics as contract before the follow-up decision. Each remedy feature updates the docs itself. |
+| Probe scripts (Ruby) inside a documentation-only feature | SC-003 requires reproducible observations, not only source reading. | Reading alone can't settle ordering in multi-process paths (collector, step worker). Adding RSpec files would change the test suite (FR-011). |

data/specs/007-execution-flow-analysis/quickstart.md

@@ -0,0 +1,51 @@
+# Quickstart: Reproducing & Validating the Analysis
+
+## Prerequisites
+
+- Ruby per `.tool-versions`, `bundle install` done at repo root.
+- Test Redis reachable. Default `redis://localhost:6780`, the same one the spec suite uses:
+
+  ```sh
+  docker run -d --name rr-test-redis -p 6780:6379 redis:7-alpine   # if not already running
+  # or: export RUBY_REACTOR_TEST_REDIS_URL=redis://localhost:6379
+  ```
+
+  Probes call `FLUSHDB` on that Redis between scenarios, like the spec suite's storage reset.
+  **Do not point them at a Redis holding data you care about.**
+
+## Run the probes
+
+```sh
+bundle exec ruby specs/007-execution-flow-analysis/evidence/run.rb \
+  | tee specs/007-execution-flow-analysis/evidence/output.txt
+```
+
+Optional filter: `PROBE=map bundle exec ruby …/run.rb` runs only scenario ids containing `map`.
+
+**Expected outcome**: every block ends in `MATCH`. The tail line prints
+`N scenarios, N match, 0 mismatch`. If a block says `MISMATCH`, behavior has drifted from the
+report: fix the report (observation wins, see contracts/report-structure.md).
+
+## Validate the report
+
+```sh
+cd specs/007-execution-flow-analysis
+# 1. No unfilled matrix cells / placeholders (the report quotes the source's
+#    own `# TODO` comment in MapStep, so TODO is not a placeholder marker here)
+grep -nE 'TBD|\?\?\?|\[fill' analysis/*.md            # expect: no output
+# 2. Every scenario id cited in the report resolves to a probe block
+ID='S-(plain|compose|map|async|bg|lock|retry|intr|edge)-[0-9]+[a-z]?'
+grep -ohE "$ID" analysis/*.md | sort -u > /tmp/cited
+grep -oE "^== $ID" evidence/output.txt | sed 's/== //' | sort -u > /tmp/run
+comm -23 /tmp/cited /tmp/run                          # expect: no output
+# 3. Zero product diff
+git diff --stat main -- lib spec demo_app README.md documentation   # expect: empty
+```
+
+## Scenarios that prove the headline answers
+
+| Question | Scenario ids (see analysis/README.md) |
+|---|---|
+| Q1 map elements rollback | `S-map-*` |
+| Q2 earlier composed reactors rollback | `S-compose-*` |
+| Q3 map compensate_all / each gap | `S-map-*` + findings-and-options.md |

data/specs/007-execution-flow-analysis/research.md

@@ -0,0 +1,202 @@
+# Research: Execution Flow & Compensation Analysis
+
+**Phase 0 output for** [plan.md](plan.md). No `NEEDS CLARIFICATION` remained in the Technical
+Context. This file records the **method** decisions and the **preliminary hypotheses** that Phase 0
+code reading produced. The hypotheses are the targets the implementation must confirm or refute
+with evidence. They are not conclusions.
+
+Baseline: commit `faf90e8d` (after #61 step-scoped retries and #63 inputs protection).
+
+## Method decisions
+
+### D1 — Evidence = source citations + executable probes against real Redis
+
+- **Decision**: Each behavioral claim cites `file:line` [R]. Headline claims are also reproduced by
+  a probe [O] in `evidence/probes/`, run with Sidekiq in **fake** mode and drained through
+  `RubyReactor::RSpec::SidekiqHelpers.drain_async_jobs`. That runs the real `Worker`,
+  `MapElementWorker`, `MapCollectorWorker` and `StepWorker` bodies against the real test Redis.
+- **Rationale**: Multi-process paths (collector resuming a parent, step worker writing records,
+  async reactor child) are hard to order by reading alone. Fake+drain is the same mechanism the
+  gem's own async specs use, so the observations match what the suite trusts.
+- **Alternatives considered**: New RSpec files under `spec/` (rejected: FR-011, changes the test
+  suite). Mocked storage (rejected: Constitution III). Docker demo app (rejected: same code paths,
+  far slower to iterate). `Sidekiq::Testing.inline!` (rejected as the default: it re-enters jobs
+  synchronously inside the caller's frame and skips liveness locks, so it hides real ordering. Used
+  only where a probe needs it explicitly, and labelled).
+
+### D2 — Trace capture: recorder middleware + step-body log
+
+- **Decision**: One recorder collects, in order, (a) body events that probe steps write themselves
+  (`run:X`, `compensate:X`, `undo:X`), and (b) middleware events from a registered recording
+  middleware (`lock_acquired`, `lock_released`, `semaphore_*`, `retry_attempt`,
+  `start_compensation`, `start_undo`, `start_reactor`, `failed_reactor`, …). Probes also dump
+  `Failure#rollback_failures` and the context `execution_trace` where useful.
+- **Rationale**: Body events show *what ran*. Middleware events show *where locks sit relative to
+  rollback*, which US3 AS2 asks for. Both come from shipped surfaces, with no patching.
+- **Alternatives considered**: Monkey-patching `CompensationManager` (rejected: evidence must come
+  from the public surface). Reading only `execution_trace` (rejected: it omits lock events and
+  lives per context, so nested children would have to be stitched together).
+
+### D3 — Execution modes covered
+
+- **Decision**: inline (plain `Reactor.run`). Worker: `background all:` / `after:` / `before:`,
+  fan-out map, `async_step`, `async_reactor`, collector resume. Interrupt pause/continue.
+  The ActiveJob backend is **not** probed separately. Its adapters delegate to the same shared
+  bodies (`Worker`, `Map::ElementExecutor`, `Map::Collector`, `StepWorker`), and the report cites
+  that delegation [R].
+- **Rationale**: Ordering is decided in the shared bodies. The adapters only enqueue and perform.
+- **Alternatives considered**: Probing both backends (rejected: doubles runtime and adds no ordering
+  information).
+
+### D4 — Vocabulary
+
+- **Decision**: *compensate* = the failing step's own cleanup (receives the error).
+  *undo* = rollback of a previously completed step, walked in reverse completion order (receives
+  its result). *rollback* = both. *Left in place* = completed work that no rollback touches.
+  *Unit* = an `async_step` or `async_reactor` dispatch.
+- **Rationale**: Matches `CompensationManager` and README usage, so readers can map the report
+  onto the code.
+
+### D5 — Evidence labels
+
+- **Decision**: `[R: path:line]` read in source. `[O: probe-id]` observed in
+  `evidence/output.txt`. `[T: spec/path:line]` covered by an existing spec. A claim with only [R]
+  is marked *by reading*.
+
+### D6 — Invariant status
+
+- **Decision**: `HOLDS` (evidence agrees, no counter-example found), `VIOLATED` (a reproducible
+  counter-example exists), `CONDITIONAL` (holds only under stated conditions, which are listed),
+  `UNDETERMINED` (evidence insufficient; says what would settle it).
+
+### D7 — Finding severity
+
+- **Decision**: **High**: completed side effects silently left in place on failure, a side effect
+  that can run twice, or rollback of work that never ran. **Medium**: the behavior is
+  defensible but differs by mode (inline vs worker) or contradicts documentation. **Low**:
+  clarity/naming. The behavior is predictable, but the DSL gives no hint of it.
+
+### D8 — Deliverable layout
+
+- **Decision**: See plan.md "Project Structure": four report files under `analysis/` plus
+  `evidence/`.
+- **Rationale**: Readers come with one of three questions (what order? what always holds? what's
+  wrong?). One file per question keeps each scannable. The index carries the three direct
+  answers so SC-002 (under 5 minutes) holds.
+
+### D9 — Documentation is audited, not edited
+
+- **Decision**: Contradicted or missing claims are listed in `findings-and-options.md` with
+  `file:line` and the quoted text.
+- **Rationale**: See plan.md Complexity Tracking.
+
+### D10 — Coordination scope
+
+- **Decision**: Reactor-level `with_lock` / `with_semaphore` / `with_ordered_lock` / rate
+  limit / period, and step-level `with_lock` / `with_semaphore` / `with_ordered_lock` /
+  `with_rate_limit` / `with_period`. Lock and semaphore are probed. Ordered lock, rate limit and
+  period are analysed by reading, with probes only where they create a distinct rollback path.
+
+## Preliminary hypotheses (to confirm or refute in implementation)
+
+Each hypothesis becomes a probe and/or an invariant. Source pointers are where reading found it.
+
+### Plain steps
+
+- **H1** Failure of step N: `compensate(N)`, then `undo(N-1 … 1)` in reverse completion order,
+  then no further steps run. `executor/compensation_manager.rb` `handle_step_failure`,
+  `rollback_completed_steps`.
+- **H2** A step whose own lock/semaphore/rate-limit acquisition failed (never started) is **not**
+  compensated. Earlier steps are still undone. `compensation_manager.rb`
+  `NEVER_STARTED_ERROR_CLASSES`.
+- **H3** A compensate that fails still lets prior undos run. The reactor then fails with a
+  `CompensationError`-derived message. An undo that fails does **not** stop the remaining undos.
+  Both are reported on `rollback_failures`.
+- **H4** `Halt` stops without any rollback. `Skipped` steps never enter the undo stack.
+- **H5** An exception that is **not** a `RubyReactor::Error::Base` and escapes outside a step body
+  (e.g. an argument `transform` or a `where`/guard raising) reaches
+  `ResultHandler#build_execution_failure`'s "unknown error" branch, which does **not** roll back.
+  Completed steps are left in place.
+- **H6** Output-validation failure compensates the step (its side effect exists) and undoes prior
+  steps.
+
+### Retries
+
+- **H7** Retries run before any compensation. Compensation runs exactly once, after the last
+  attempt (`MaxRetriesExhaustedFailure`). No per-attempt compensation.
+- **H8** Inline reactor: retry backoff `sleep`s in-process. In a worker (`background`, map
+  element): the retry is a re-enqueue (`RetryQueuedResult`), and compensation happens in whichever
+  delivery exhausts the attempts.
+- **H9** `async_step` retries are in-worker loops (`StepWorker#run_step`). They never re-enqueue,
+  and exhaustion writes a failed record **without** calling the step's `compensate`.
+
+### Compose
+
+- **H10** Child failure: the child rolls itself back first (child compensate + child undos). Then
+  the parent treats the compose step as failed. `ComposeStep#compensate` runs, but is a no-op
+  because the child undo stack is already cleared, or because `current_step` is not the compose
+  name when the compensate runs outside `with_step`. Then the parent undoes its own earlier steps,
+  **including earlier compose steps**, whose `undo` replays the child's undo stack in reverse.
+- **H11** A parent step failing **after** a completed compose undoes the compose, which undoes all
+  child steps in reverse. So yes, earlier composed reactors are rolled back.
+- **H12** `compose` with `retries`: after a child failure the child's `intermediate_results` survive
+  the rollback. A retry *resumes* the child, and the child treats its already **undone** steps as
+  completed. Those steps are not re-run, and the retried step sees stale results.
+  Suspected High finding. Must be probed.
+- **H13** A composed child's own reactor-level lock is re-entrant with the parent's (same root
+  owner).
+
+### Map
+
+- **H14** `MapStep#compensate` is a `TODO` returning `Success()`, and `MapStep` has no `undo`. So
+  (a) when element K fails fail-fast, elements 0..K-1 that already succeeded are **left in place**.
+  Only element K's own reactor rolls back its own steps. (b) When a step **after** the map fails,
+  the map's elements are **not** undone.
+- **H15** `fail_fast false`: failed elements roll back individually (inside their own executor, or
+  via `executor.undo_all` in `ElementExecutor#handle_result`). Succeeded elements stay. The map
+  step itself succeeds and hands a `ResultEnumerator` to the collect block / dependants.
+- **H16** Fan-out map, fail-fast: elements already dispatched keep running after the first failure
+  (only *not-yet-started* elements check `check_fail_fast?`). The collector fails the parent
+  using the first recorded failure, and later-finishing elements are neither compensated nor
+  reflected.
+- **H17** Inline map: completed element contexts are not retained anywhere the parent could
+  reach to undo them. Even a working `MapStep#undo` would need new storage. Fan-out elements'
+  contexts are stored by id (`store_map_element_context_id`), so they *are* reachable.
+- **H18** Map has no `retries` DSL. Retries are per inner step, inside each element.
+
+### async_step / async_reactor
+
+- **H19** A unit never enters the parent's undo stack. Parent rollback never touches it.
+- **H20** A unit's failure does not fail the parent. A reader receives the `Failure` object as an
+  argument and must `fail!` explicitly. That fails the **reader** step: the reader's compensate
+  runs, then the parent's undos. The async_step's own `compensate`/`undo` blocks **never** run.
+  This contradicts `documentation/background_and_async.md` ("they run only if the failure is
+  surfaced into the parent's compensation path").
+- **H21** An `async_reactor` child is an ordinary reactor. It rolls back its own steps on its own
+  failure, in its worker. The parent is not affected unless a reader opts in.
+- **H22** Reader wait timeout (`AsyncWaitTimeoutError`) is an `Error::Base` raised during argument
+  resolution, so the parent rolls back its completed steps.
+
+### background / worker
+
+- **H23** `background after:/before:` serializes the undo stack. A worker-side failure undoes steps
+  that ran in the **calling** process too.
+- **H24** Reactor-level lock/semaphore is held from admission to the executor's `ensure`, i.e.
+  **through** rollback. It is released on interrupt pause (not a park), and kept across parks.
+- **H25** Step-level lock is released after the body and **re-acquired** for that step's
+  compensate/undo (`around_rollback`), with `rollback_wait`. There is a window between forward
+  release and rollback re-acquire.
+
+### Interrupts / manual
+
+- **H26** After a pause, the undo stack is persisted. A failure after `continue` undoes steps that
+  completed before the pause. An interrupt validation exhausting `max_attempts` calls `undo` and
+  marks the reactor failed.
+- **H27** `Reactor.cancel` does not roll back. `Reactor.undo(id)` rolls back and cancels, and does
+  **not** take the reactor-level lock (step-level rollback locks still apply).
+
+### Crash / re-drive
+
+- **H28** Checkpoint after each successful step bounds a crash re-run to at most the one step in
+  flight, which can run twice (at-least-once). Its undo is recorded only if its result was
+  checkpointed.