ruby_reactor 0.8.4 → 0.8.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 325464f0f2b9ee374b1267a4c7243121c9b564814d425bfa5ecce59891979468
-  data.tar.gz: 996363b210d54be36ac7065532aac6c0349334b18d8d14816896debd4e8993c4
+  metadata.gz: c59b0af2a9d34b620e3400cff78e0df3b2e580d1138b37ed5aee1b9e5a78f548
+  data.tar.gz: 4e3c2b92b6ae58797beae470b60c69015e15b2b8d6855ce710e71a999d0ae62f
 SHA512:
-  metadata.gz: 3fcbdbe30cce51beec8dd715c543c8db15140de630d94ec3ae01a7ba803d28cb88f44e0ce1ee97c232cbed34863d81b8c4d0ed979f44acf52a27cfbc07f31b04
-  data.tar.gz: 946f4082ec39691d47e35983b9466a128246159f0b191aca061d6c984e2340cabd09da8e111e92b4799ec97a8f4e9753826163e97df48424b3a1583abe40afbc
+  metadata.gz: a3ac367241909b09a5f0451b9278489776e7bedc56b506043c786892b86247a646b297a7c6192be6e5935b5e9a861f36e66e2f370a7c3e0741820cbcaa1ee409
+  data.tar.gz: 1fd3ff1f692008747021d11d5356613163a8c7777e33ead22260da4b3959bc5f6ec7fff3cb5928444815298011ff4b0e1e2e10e34c55a9781b98d9ab80893e40

data/.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "0.8.4"
+  ".": "0.8.6"
 }

data/.specify/feature.json

@@ -1,3 +1,3 @@
 {
-  "feature_directory": "specs/006-step-retry-declarations"
+  "feature_directory": "specs/009-distributed-map-undo"
 }

data/.specify/memory/constitution.md

@@ -1,27 +1,28 @@
 <!--
 SYNC IMPACT REPORT
 ==================
-Version change: 1.2.1 → 1.3.0 (MINOR: Development Workflow now REQUIRES every generated
-  plan.md and tasks.md to carry an explicit documentation-update task/gate, with the
-  requirement propagated into both templates — a new enforcement mechanism, not just
-  wording)
+Version change: 1.3.0 → 1.3.1 (PATCH: factual correction in Technical Constraints — the worker
+  path named a directory that no longer exists; no principle or rule changed)
 
-Modified principles: none (Development Workflow section, not a Core Principle)
+Modified principles: none
+
+Modified sections: Technical Constraints — the "Sidekiq" bullet now points at
+  `lib/ruby_reactor/adapters/{sidekiq,active_job}/`, where the queue-backend workers actually
+  live, and names ActiveJob as the alternative adapter
 
 Added sections: none
 
 Removed sections: none
 
 Templates checked:
-  - .specify/templates/plan-template.md      ✅ Added Constitution Check checklist item:
-                                                 identify README.md/./documentation impact
-  - .specify/templates/spec-template.md      ✅ No principle-specific content — no edit required
-  - .specify/templates/tasks-template.md     ✅ Polish-phase doc task now explicit and marked
-                                                 REQUIRED, citing README.md + ./documentation
+  - .specify/templates/plan-template.md      ✅ No reference to the worker path — no edit required
+  - .specify/templates/spec-template.md      ✅ No reference — no edit required
+  - .specify/templates/tasks-template.md     ✅ No reference — no edit required
   - .specify/templates/checklist-template.md ✅ Generic — no edit required
   - .specify/extensions.yml                  ✅ No before/after_constitution hooks registered
-  - README.md                                ✅ No principle-specific claims to update
-  - documentation/*.md                       ✅ No principle-specific claims to update
+  - README.md, documentation/*.md            ✅ No reference to the old path
+
+Found by /speckit-analyze on specs/009-distributed-map-undo (finding C5), 2026-09-30.
 
 Deferred TODOs: none
 -->
@@ -151,7 +152,9 @@ gaps in the matcher library surface as work instead of as workarounds.
 ## Technical Constraints
 
 - **Ruby**: >= 3.0.0 required. No polyfills for older Rubies.
-- **Sidekiq**: Core async dependency. Workers live in `lib/ruby_reactor/sidekiq_workers/`.
+- **Sidekiq**: Core async dependency. ActiveJob is the supported alternative. Queue-backend
+  workers and routers live in `lib/ruby_reactor/adapters/{sidekiq,active_job}/`; the
+  backend-agnostic worker logic lives in `lib/ruby_reactor/worker.rb` and `lib/ruby_reactor/map/`.
 - **Redis**: Required for state persistence, locks, semaphores, rate limits, and
   periods. The gem does NOT manage Redis connections — callers provide them.
 - **dry-validation**: Input validation DSL. Schema definitions stay inside the
@@ -208,4 +211,4 @@ justified in the `Complexity Tracking` table of the plan.
 Compliance review: at each MINOR or MAJOR gem release, confirm this constitution
 still accurately reflects the codebase and update as needed.
 
-**Version**: 1.3.0 | **Ratified**: 2025-10-02 | **Last Amended**: 2026-09-11
+**Version**: 1.3.1 | **Ratified**: 2025-10-02 | **Last Amended**: 2026-09-30

data/CHANGELOG.md

@@ -4,6 +4,54 @@
 
 ### ⚠ BREAKING CHANGES
 
+* **`retries` on a `compose` or an `async_reactor` raises `RubyReactor::Error::DeprecatedDslError`
+  at class definition.** A parent never retries a nested reactor as a whole: the child retries its
+  own steps. Before, a compose-level retry resumed a child whose earlier steps had already been
+  undone. Declare `retries` on the child's steps instead.
+  See *Migration notes: reliable rollback* below.
+* **`where` and `guard` are removed.** Declaring either on a `step`, `async_step` or `interrupt`
+  raises `RubyReactor::Error::DeprecatedDslError` at class definition. A step that should not run
+  returns `Skipped(value)` (or calls `skip!(value)`) from its body.
+  See *Migration notes: reliable rollback* below.
+* **`Skipped` no longer changes execution.** It is an instrumentation mark (the trace records it;
+  `skipped?` is true): a `background after:` step that returns `Skipped` now hands the rest of
+  the run off like any completed step (before, the rest ran in the calling process), and a
+  `with_period` step whose body returns `Skipped` marks its bucket. A skipped step is still never
+  undone.
+* **An exception that is not a `StandardError` fails the step and rolls back.** A
+  `NotImplementedError`, a `LoadError`, a `SystemStackError` or a custom `Exception` subclass
+  raised by reactor code (a step body, an argument transform, a `compensate`/`undo`, a key proc, a
+  `collect` block) is now that step's failure: the step is compensated if its body ran, completed
+  steps are undone, and `Reactor.run` returns the `Failure` instead of raising. Only interruptions
+  (`SignalException` including `Interrupt`, `SystemExit`, `NoMemoryError`, and an enclosing
+  `Timeout.timeout`'s interruption) still skip rollback and propagate.
+  See *Migration notes: reliable rollback* below.
+* **An `async_step`'s `compensate` runs, in the unit's own job, when its final attempt fails.**
+  Before, `compensate`/`undo` blocks on an `async_step` were accepted and never ran. Now the unit
+  compensates itself once, after its last retry, whether or not any step reads its result —
+  never for a retried attempt, a halt, or a body that never started. The outcome is recorded on
+  the unit's Step Result Record as `compensation: { status, rollback_failures, completed_at }`,
+  and the compensation middleware events fire in the unit's job. A reader that surfaces the
+  failure no longer leads to a second compensation of the unit.
+  See *Migration notes: reliable rollback* below.
+
+* **An inline `undo` inside `async_step` raises `RubyReactor::Error::ValidationError` at class
+  definition.** An independent async unit is never undone, so the block could never run. A step
+  class that defines `undo` and is used with `async_step` prints a definition-time warning
+  instead (the same class may be reused by ordinary steps, where its `undo` runs).
+  See *Migration notes: reliable rollback* below.
+* **A map rolls back the elements that completed.** When a map fails (an element fails under
+  `fail_fast`, or `collect` raises), and when a later step fails or the run is undone manually,
+  every completed element is rolled back by replaying its own step `undo`s, highest index first —
+  in inline and fan-out mode, whatever order the element jobs ran in. Before, completed elements
+  were never rolled back. A fail-fast fan-out map now waits for elements already in flight before
+  it reports its failure, and settles the elements it never started as skipped (which also stops
+  the map sweeper re-dispatching them). An element rollback that does not complete is listed in
+  `Failure#rollback_failures` with `map_step:` and `element_index:`; an element whose context
+  (or the map's element index) expired is reported with `reason: :context_unavailable`, and a
+  still-running duplicate with `reason: :element_in_flight`. A fan-out map whose rollback is
+  incomplete fails with the same `CompensationError` shape as an inline map.
+  See *Migration notes: reliable rollback* below.
 * **`RubyReactor::Step` is now a base class, not a mixin.** `include RubyReactor::Step` on a
   plain class with `def self.run(arguments, context)` is gone — no compatibility shim, no dual
   authoring style. A step subclasses `RubyReactor::Step` and writes `run` (and optionally
@@ -78,8 +126,157 @@
   `RubyReactor.Failure`, and a hash error needs braces, `Failure({ code: 1 })`, because a braceless
   `Failure(code: 1)` is now read as options.
 
+
+### Migration notes: reliable rollback
+
+Every breaking or shape-changing item of the rollback work, with what to change.
+
+1. **Map element `undo`s now run** (breaking, behavior). They run when the map fails, when a later
+   step fails, and on a manual `Reactor.undo(id)`. Make them idempotent.
+
+   ```ruby
+   # Before: this undo never ran for a map element; charges stayed on a failure.
+   # After: it refunds each charged element, highest index first. Guard against a double refund.
+   class ChargeStep < RubyReactor::Step
+     def undo
+       Payments.refund(result[:charge_id]) unless Payments.refunded?(result[:charge_id])
+       Success()
+     end
+   end
+   ```
+
+2. **An `async_step`'s `compensate` now runs in the unit's job** (breaking, behavior), once, after
+   its final attempt fails, whether or not a reader exists. Move reader-only cleanup into the
+   reader.
+
+   ```ruby
+   # Before: never ran.
+   async_step :notify, NotifyStep do
+     compensate { |error, inputs, _ctx| Audit.undelivered(inputs.user_id, error) }
+   end
+   # After: runs in the unit's job after the last retry; the outcome is on the unit's record
+   # as `compensation`. Cleanup that should run only when a reader fails the reactor:
+   step :confirm do
+     argument :delivery, result(:notify)
+     run { |inputs, _ctx| inputs.delivery.is_a?(RubyReactor::Failure) ? Failure("undelivered") : Success() }
+     compensate { |_error, _inputs, _ctx| Support.open_ticket }
+   end
+   ```
+
+3. **An inline `undo` inside `async_step` raises at class definition** (breaking, API).
+
+   ```ruby
+   # Before: accepted, never ran.
+   async_step(:notify) { run { ... }; undo { ... } }
+   # After: raises RubyReactor::Error::ValidationError. Use the unit's `compensate`, a reader's
+   # `compensate`, or an `async_reactor` child whose steps declare `undo`.
+   async_reactor :notify, NotifyReactor   # NotifyReactor's steps declare `undo`
+   ```
+
+4. **`retries` on `compose` / `async_reactor` raises at class definition** (breaking, API). Move
+   the retries onto the child step that can fail transiently. The child retries it itself; the
+   other child steps run once.
+
+   ```ruby
+   # Before: retried the whole child from the parent.
+   compose(:booking, BookingReactor) { retries max_attempts: 2 }
+   # After: raises RubyReactor::Error::DeprecatedDslError. Declare it on the child's step:
+   class ConfirmBookingStep < RubyReactor::Step
+     retries max_attempts: 2
+   end
+   compose :booking, BookingReactor
+   ```
+
+5. **`where` / `guard` are removed** (breaking, API). Skip from the step body. Unlike `where`,
+   the body decides after the step started: its arguments are resolved and validated (a step
+   that relied on `where` to avoid invalid arguments now fails on them), and its lock, semaphore
+   and rate-limit slot are taken first. A `background before:` hand-off at that step now always
+   fires; the body decides in the worker.
+
+   ```ruby
+   # Before
+   step :sync_user do
+     where { |ctx| ctx.get_input(:enabled) }
+     run { |inputs, _ctx| Success(sync!(inputs.user)) }
+   end
+   # After
+   step :sync_user do
+     run do |inputs, ctx|
+       next Skipped(nil) unless ctx.get_input(:enabled)
+       Success(sync!(inputs.user))
+     end
+   end
+   ```
+
+6. **Non-`StandardError` exceptions from reactor code roll back** (breaking, behavior). They no
+   longer propagate out of `Reactor.run`; check the returned `Failure` instead. A test assertion
+   error raised inside a step body (an RSpec expectation, a strict double) now surfaces as the
+   step's `Failure`, so assert on the result.
+
+   ```ruby
+   # Before: NotImplementedError propagated; nothing was undone; the run was stored `aborted`.
+   # After:
+   result = MyReactor.run(inputs)
+   result.failure?         # => true, completed steps undone
+   result.exception_class  # => "NotImplementedError"
+   ```
+
+7. **Argument and unknown errors roll back and carry `step_name`** (fix). The Failure's
+   shape changes on these paths.
+
+   ```ruby
+   # Before: "Execution failed: invalid value for Float(): 'abc'", step_name nil, nothing undone.
+   # After: "Step 'charge' failed: Step 'charge' could not resolve its arguments: …",
+   #        step_name :charge, exception_class "ArgumentError", completed steps undone.
+   result.step_name        # => :charge
+   result.exception_class  # => "ArgumentError"
+   ```
+
+8. **New `aborted` status** (additive), only for runs in the caller's process cut short by an
+   interruption. Dashboards and status filters gain a value; an `aborted` run needs
+   `MyReactor.undo(id)` to roll back.
+
+9. **`rollback_failures` entries may carry `map_step:` / `element_index:`** and the reasons
+   `:context_unavailable` / `:element_in_flight` (additive).
+
 ### Features
 
+* **`fan_out` without `batch_size` is back-pressured: at most 50 element jobs per throw**
+  (`RubyReactor::Map::DEFAULT_BATCH_SIZE`), forward and rollback. Before, every element was
+  enqueued at once. A map of more than 50 elements with no declared `batch_size` now runs in
+  throws of 50, which can lower its peak throughput: declare a larger `batch_size` to keep more
+  element jobs in flight.
+* **Distributed rollback of fan-out maps.** A `fan_out` map that must be rolled back (it failed,
+  a later step failed, or `Reactor.undo`) now rolls back the way it ran: one
+  `MapElementRollbackWorker` job per started element, enqueued `batch_size` per throw with the
+  forward run's back pressure, each loading one element's state. Before, one process loaded every
+  element and undid them one after another. The run ends with the same `Failure` as an inline map's
+  rollback. An element's rollback saves after every undone step, so a worker killed mid-rollback
+  resumes after the last one (the undo that was cut off runs again: keep undos idempotent). Both
+  sweepers recover lost rollback jobs and resumes. Inline maps keep rolling back in process, now
+  reading element states 100 at a time.
+* **`rolling_back` execution status.** A run whose rollback handed off at a fan-out map, until the
+  last element reports; then a worker undoes the steps before the map and the run ends `failed`
+  (`cancelled` for an undo). `Reactor.cancel` and `Reactor.undo` raise
+  `RubyReactor::Error::ValidationError` on it. The dashboard shows it (amber) in every status
+  surface, with the map's rollback progress (`total`, `settled`, `outstanding`, `failed`).
+* **Router methods `perform_map_element_rollback_async` / `perform_map_element_rollback_in`** on both
+  shipped routers, with a `MapElementRollbackWorker` per adapter, on the queue `MapElementWorker`
+  uses. A custom router needs both methods for fan-out map rollback.
+* **`be_rolling_back` matcher.** `pending_async_jobs` / `drain_async_jobs` work on the ActiveJob
+  test adapter too, and `worker_class` names a pending job's class on both backends.
+* **`Reactor.undo` holds the run's context lock**, and raises `RubyReactor::Lock::AcquisitionError`
+  while a live run or rollback holds it.
+
+* **`aborted` execution status.** A run in the caller's process that an interruption
+  (`SignalException` including `Interrupt`, `SystemExit`, `NoMemoryError`, or an enclosing
+  `Timeout.timeout`) cuts short runs no rollback code: the exception reaches the caller unchanged,
+  and the run is stored as `aborted` with only the steps not yet undone still outstanding (an
+  interruption during a rollback keeps exactly the rest, whichever failure started that rollback).
+  Workers and the sweeper never resume it; `Reactor.undo(id)` rolls it back, including the steps a
+  composed child or the elements of an inline `map` completed when the interruption hit inside
+  them. The dashboard and web API show and filter it, next to `failed`. A worker run is unchanged
+  (its job is redelivered).
 * **Step-scoped coordination.** Steps can declare `with_lock`, `with_semaphore`, `with_rate_limit`,
   `with_period`, and `with_ordered_lock` — the same macros as the reactor form, keyed on the step's
   own resolved arguments instead of the reactor's inputs — so one step of a workflow can be
@@ -132,6 +329,11 @@
 
 ### Deprecations
 
+* **`fail_fast` on a `map` is now `atomic`** (same meaning: every element succeeds, or none is
+  kept). `fail_fast` keeps working and prints one deprecation line per declaration site naming
+  `atomic`; it will be removed no earlier than the next major version. Declaring both on one map
+  raises `RubyReactor::Error::ValidationError`. Element jobs enqueued before the upgrade, which
+  carry `fail_fast`, keep the policy they were enqueued with.
 * Rules on `argument` (`argument :x, src, :type, **predicates`) and `validate_args` keep working
   for steps without a contract, and print one deprecation notice per declaration site. Move them
   to `input` / `validate_inputs` on the step class, or into an `inputs do ... end` block for an
@@ -140,6 +342,44 @@
 
 ### Bug Fixes
 
+* **A fan-out map inside a composed reactor no longer leaves the root running forever.** The map's
+  completion resumed the child as a run of its own, and nothing resumed the root. Now the root
+  resumes and finishes, and a failure of the map or of any later step rolls back through the root.
+  A map that was already running inside a composed child when you upgraded keeps the old
+  behavior: its metadata names no owner run.
+* A fan-out map's completion now resumes the run through its own Worker, which adopts the map's
+  outcome, instead of the collector job resuming the run itself. This costs one extra job per
+  fan-out map completion, and removes the collector's write to the run's context.
+* A map element re-dispatched by `RubyReactor::Map::Sweeper` kept neither `batch_size` nor
+  `fail_fast`: the map metadata never stored them, so the element stopped triggering later
+  batches and was no longer atomic. Both are stored now.
+* `Executor#resume_execution` saves the context before it releases the run's context lock. Released
+  first, a worker resuming the same run could load the pre-save state and have its progress
+  overwritten by the late save.
+* A map's undo record no longer stores the map's resolved source in the parent context.
+* A step that returns another unit's `Failure` (a map adopting a failed element, a composed child)
+  keeps that Failure's `exception_class` on the run's final Failure, also when the step's retries
+  are exhausted. Before, an inline map whose element raised reported no `exception_class`.
+
+* `Reactor.continue` accepts a resume only while the reactor is paused at an interrupt. A resume
+  that arrives while the reactor is executing or rolling back, or after it finished or was
+  aborted, raises `RubyReactor::Error::ValidationError` and changes nothing. Before, it resumed the
+  run from its stored state, which could run a rolled-back or aborted run forward again. An
+  accepted resume marks the run `running` before executing, so a concurrent second resume fails.
+  A resume that cannot take the reactor's lock or semaphore raises its `AcquisitionError` and
+  leaves the run paused, so the caller can retry it.
+* A `background after:` step that returns `Halt` no longer hands the rest of the run to a worker:
+  the run halts, as `Halt` promises. Before, the remaining steps ran in a worker.
+* A stored `Failure` keeps at most 100 backtrace frames, plus a `"... N more frames"` line. A stack
+  overflow's backtrace no longer inflates the stored context (about 2.4 MB to 23 KB).
+* Every error after a completed step now rolls back, and the failure names its step. An `argument`
+  source, `transform` or result path that raises fails the step with
+  `RubyReactor::Error::ArgumentResolutionError`: completed steps are undone, the step is neither
+  compensated (its body never started) nor retried, and the Failure carries `step_name`,
+  `reactor_name` and the original `exception_class`. Before, an argument error rolled nothing back
+  and carried no step. The same holds in a worker (an `async_step` unit, a `background` hand-off).
+  Any other exception raised outside a step body ("Execution failed: …") now rolls back completed
+  steps too, and a failure whose compensation raised ("Execution error: …") carries `step_name`.
 * A supplied `false` reactor input or step result no longer resolves to `nil`.
   `Context#get_input`, `Context#get_result` and `Template::Result#fetch` now check whether the key
   exists instead of whether the value is truthy. Code that relied on `false` arriving as `nil`
@@ -204,6 +444,20 @@
 * Docs: a park keeps each level's lock without a second `:lock_acquired` only while the gap stays
   within the lock's `ttl`; a lapsed lock is acquired again.
 
+## [0.8.6](https://github.com/arturictus/ruby_reactor/compare/v0.8.5...v0.8.6) (2026-10-08)
+
+
+### Miscellaneous Chores
+
+* release commit ([#68](https://github.com/arturictus/ruby_reactor/issues/68)) ([9fcb14c](https://github.com/arturictus/ruby_reactor/commit/9fcb14cb8aa6a2c9e48d3327cb8eb279022f59c0))
+
+## [0.8.5](https://github.com/arturictus/ruby_reactor/compare/v0.8.4...v0.8.5) (2026-09-30)
+
+
+### Miscellaneous Chores
+
+* Execution flows improvements and consolidation ([#65](https://github.com/arturictus/ruby_reactor/issues/65)) ([21a4c59](https://github.com/arturictus/ruby_reactor/commit/21a4c59fa13c0e7e66c8e08ccb5f20ea43875353))
+
 ## [0.8.4](https://github.com/arturictus/ruby_reactor/compare/v0.8.3...v0.8.4) (2026-09-26)
 
 

data/CLAUDE.md

@@ -1,5 +1,5 @@
 <!-- SPECKIT START -->
 For additional context about technologies to be used, project structure,
 shell commands, and other important information, read the current plan
-at specs/006-step-retry-declarations/plan.md
+at specs/009-distributed-map-undo/plan.md
 <!-- SPECKIT END -->

data/README.md

@@ -13,7 +13,7 @@ A dynamic, dependency-resolving saga orchestrator for Ruby. Ruby Reactor impleme
 
 Building complex business transactions often results in spaghetti code or brittle "god classes." Ruby Reactor solves this by implementing the **Saga Pattern** in a lightweight, developer-friendly package. It lets you define workflows as clear, dependency-driven steps without the boilerplate of heavy enterprise frameworks.
 
-The key value is **Reliability**: if any part of your workflow fails, Ruby Reactor automatically triggers compensation logic to undo previous steps, ensuring your system never ends up in a corrupted half-state. Whether you're coordinating microservices or monolith modules, you get atomic-like consistency with background processing built-in.
+The key value is **Reliability**: if any part of your workflow fails with an error, Ruby Reactor automatically triggers compensation logic to undo previous steps, ensuring your system never ends up in a corrupted half-state. Only an interruption (a signal, an exit, out of memory) runs no rollback code; the run is recorded as `aborted` so a manual `undo` can roll it back. Whether you're coordinating microservices or monolith modules, you get atomic-like consistency with background processing built-in.
 
 ## Features
 
@@ -22,7 +22,7 @@ The key value is **Reliability**: if any part of your workflow fails, Ruby React
 - **Async Steps & Reactors**: `async_step` and `async_reactor` dispatch independent units of work while the reactor keeps running; steps that read their result wait for it.
 - **Map & Parallel Execution**: Iterate over collections in parallel with the `map` step, distributing work across multiple workers.
 - **Retries**: per-step retry policies (declared on the step class or step block) with exponential, linear, or fixed backoff.
-- **Compensation**: Automatic rollback of completed steps when a failure occurs.
+- **Compensation**: Automatic rollback of completed steps when any error occurs after them, including a raising argument transform or an exception that is not a `StandardError`.
 - **Interrupts**: Pause and resume workflows to wait for external events (webhooks, user approvals).
 - **Input Validation**: Integrated with `dry-validation` for robust input checking.
 - **Distributed Locks, Semaphores, Rate Limits, Periods & Ordered Locks**: Coordinate across processes with Redis-backed primitives — exclusive locks for at-most-one-runner, semaphores for capacity caps, fixed-window rate limits for external APIs (single or multi-window like "3/sec AND 100/min"), `with_period` to dedup reactors to once per calendar bucket, and `with_ordered_lock` for strict transaction ordering via a monotonically increasing nonce assigned at enqueue. Background jobs snooze on contention with smart `retry_after` instead of consuming retry budget.
@@ -32,7 +32,7 @@ The key value is **Reliability**: if any part of your workflow fails, Ruby React
 | Feature                  | Ruby Reactor | dry-transaction | Trailblazer | Custom Sidekiq Jobs |
 |--------------------------|--------------|-----------------|-------------|---------------------|
 | DAG/Parallel execution   | Yes          | No              | Limited     | Manual              |
-| Auto compensation/undo   | Yes          | No              | Manual      | Manual              |
+| Auto compensation/undo   | Yes (steps, compose, map; async units roll back on their own) | No | Manual | Manual |
 | Interrupts (pause/resume)| Yes          | No              | No          | Manual              |
 | Locks / sem / rate / per | Yes          | No              | No          | Manual              |
 | Built-in web dashboard   | Yes          | No              | No          | No                  |
@@ -237,7 +237,7 @@ Whichever style you use, a step's `run` returns one of four signals — all expo
 - **`Success(value)`** — step succeeded; `value` flows to dependent steps.
 - **`Failure(error)`** — step failed; the reactor rolls back completed steps (compensate/undo).
 - **`Halt(reason:)`** — clean halt: stop the reactor, keep partial progress, **no rollback**. See [Halting a reactor cleanly](documentation/core_concepts.md#halting-a-reactor-cleanly).
-- **`Skipped(value)`** — mark this one step skipped; the reactor continues and `value` flows to dependants exactly like `Success`. See [Skipping a single step](documentation/core_concepts.md#skipping-a-single-step).
+- **`Skipped(value)`** — mark this one step skipped. The run continues exactly as for `Success` — `value` flows to dependants — and the step is never undone; the execution trace marks it skipped. See [Skipping a single step](documentation/core_concepts.md#skipping-a-single-step).
 
 One-line helpers end a step immediately from any call depth: `success!(value)`, `fail!(error, retry: true)`, `halt!(reason:)`, `skip!(value)` — equivalent to `return`ing the matching signal, usable in `run`, `compensate`, and `undo` bodies.
 
@@ -544,10 +544,14 @@ time. On success the reader gets the raw value; on failure it gets the
 
 **Compensation is opt-in.** If a dispatched step fails and nothing reads its
 result, the reactor is not compensated — it was dispatched precisely so the
-reactor would not depend on it. A reader that returns `Failure` triggers
-compensation normally. The independence cuts both ways: async dispatches never
-enter the parent's undo stack, so a parent rolling back for its own reasons
-never "undoes" a unit that runs (and may still succeed) elsewhere.
+reactor would not depend on it. The unit's own `compensate` does run: once, in
+the unit's job, after its final attempt fails, recorded on the unit's record as
+`compensation`. A reader that returns `Failure` compensates itself and undoes the
+reactor's completed steps; the unit is not compensated again. The independence
+cuts both ways: async dispatches never enter the parent's undo stack, so a
+parent rolling back for its own reasons never "undoes" a unit that runs (and may
+still succeed) elsewhere. An inline `undo` on an `async_step` would never run, so
+it raises at class-definition time (a step class's `undo` is warned about).
 
 #### `async_reactor`: a whole nested reactor, running independently
 
@@ -630,7 +634,9 @@ That's all that's required: `start_sweeper!` is idempotent (safe to call on ever
 boot — duplicate kicks collapse to one chain), runs both the top-level reactor
 sweeper and the map sweeper every `config.sweeper_interval` seconds, and stops if
 you set `config.sweeper_enabled = false`. The interval is your recovery-latency
-bound.
+bound. Both cover a fan-out map's distributed rollback too: the map sweeper
+re-dispatches a lost element rollback job, and the reactor sweeper re-enqueues a
+`rolling_back` run (like a `running` one) whose resume was lost.
 
 > **Sidekiq Enterprise `super_fetch` compatibility:** the chain is safe under
 > reliable fetch. `super_fetch` re-runs a job whose worker died mid-execution, so
@@ -850,7 +856,7 @@ step :ensure_active do
 end
 ```
 
-To skip a *single* step while the reactor continues — the step did nothing, but the rest of the workflow should still run — return `Skipped(value)` instead. The value flows to dependants exactly like a `Success` value, and the step is not enrolled for rollback:
+To mark a *single* step as having had nothing to do — the rest of the workflow runs as usual — return `Skipped(value)` instead. `Skipped` is only an instrumentation mark, so an engineer reviewing the execution can see the step did not need to run. It never changes how the run executes: the value flows to dependants, and a `background` hand-off and a `with_period` bucket treat it as a completed step. A skipped step had nothing to do, so it is never undone. (`where`/`guard` were removed; skipping from the body is the only way.)
 
 ```ruby
 step :maybe_sync do
@@ -889,11 +895,23 @@ class DataProcessingReactor < RubyReactor::Reactor
 end
 ```
 
-A `fan_out` map is a **hand-off point**: the reactor stops at the map (the caller gets a `DispatchResult`), every element runs as its own background job, and once all outcomes are collected the reactor resumes in a worker with the steps after the map. It fans out the same way when the reactor is already running in a worker (e.g. `background all: true`).
+A `fan_out` map is a **hand-off point**: the reactor stops at the map (the caller gets a `DispatchResult`), every element runs as its own background job, and once all outcomes are collected the reactor resumes in a worker with the steps after the map. It fans out the same way when the reactor is already running in a worker (e.g. `background all: true`), and inside a `compose`d child, where the top-level run is the one that resumes.
 
 By using `fan_out` with `batch_size`, the system applies **Back Pressure** to efficiently manage resources. [Read more about Back Pressure & Resource Management](documentation/data_pipelines.md#back-pressure--resource-management).
 
-`batch_size` is optional: with `fan_out` alone, RubyReactor fans out one worker per element (defaulting the batch size to the full source size) and aggregates the outcomes into a `ResultEnumerator` — convenient for small collections, but with no back pressure. See [`fan_out` Without `batch_size`](documentation/data_pipelines.md#fan_out-without-batch_size).
+**Rollback.** A map rolls back like a composed reactor, with no map-level rollback DSL: the `undo`s
+already declared on the element reactor's steps are each element's rollback. When the map fails
+(an element fails in an `atomic` map, the default, or `collect` raises), and when a later step fails or the run is
+undone manually, every element that completed is rolled back, newest-started first, and the run ends
+with the same `Failure` in inline and fan-out mode alike. A map rolls back the way it ran: an inline
+map in process, reading element states 100 at a time; a fan-out map with **one rollback job per
+started element**, `batch_size` per throw, the same back pressure as its forward run. Until the last
+element reports, the run is `rolling_back`, and only then are the steps before the map undone. A
+failing atomic fan-out map lets elements already in flight finish before it reports the failure. Make
+element `undo`s idempotent: one cut off by a killed worker runs again. See
+[Rollback](documentation/data_pipelines.md#rollback).
+
+`batch_size` is optional: with `fan_out` alone, no throw enqueues more than 50 element jobs (`RubyReactor::Map::DEFAULT_BATCH_SIZE`), forward and rollback, and the outcomes are aggregated into a `ResultEnumerator`. Set `batch_size` to change the throw size. See [`fan_out` Without `batch_size`](documentation/data_pipelines.md#fan_out-without-batch_size).
 
 > **Breaking change:** `async true` inside a `map` block has been **removed** — it read like `async_step`/`async_reactor`, which dispatch independent units the reactor does not stop for. It now raises at class-definition time. The exact replacement is `fan_out` (`fan_out batch_size: N`).
 
@@ -1306,7 +1324,7 @@ end
 
 ### Error Handling and Compensation
 
-When a step fails, RubyReactor automatically undoes completed steps in reverse order, compensate only runs in the failing step and backwalks the executed steps undo blocks:
+When a step fails, RubyReactor automatically undoes completed steps in reverse order, compensate only runs in the failing step and backwalks the executed steps undo blocks. Composed reactors and maps are completed steps too: undoing one replays its child's (or each completed element's) own step `undo`s:
 
 ```ruby
 class TransactionReactor < RubyReactor::Reactor
@@ -1408,9 +1426,42 @@ result.rollback_failures
 ```
 
 `reason` is `:coordination_unavailable`, `:returned_failure`, or `:raised`; `kind`
-is `:undo` or `:compensate`. See
+is `:undo` or `:compensate`. An entry from a map element's rollback also carries
+`map_step:` and `element_index:`, and a map reports an element it could not roll
+back with `reason: :context_unavailable` (its stored context, or the map's element index, expired) or
+`:element_in_flight` (a duplicate of it was still running). See
 [Step Rollback](documentation/locks_and_semaphores.md#step-rollback).
 
+Every error after a completed step rolls back, not only a step body's failure.
+An `argument` source, `transform` or result path that raises fails that step
+with `RubyReactor::Error::ArgumentResolutionError`. The step is not compensated
+(its body never started) nor retried; completed steps are undone. The Failure names the
+step, and `exception_class` reports the original error's class:
+
+```ruby
+result.step_name        # => :charge
+result.exception_class  # => "ArgumentError"
+```
+
+That holds for every exception, not only a `StandardError`: a step class that
+never implemented `run` (`NotImplementedError`) or a custom `Exception` subclass
+fails its step and rolls back the same way, and `exception_class` names it.
+
+Only an interruption (a signal such as `Interrupt`, `SystemExit`, `NoMemoryError`,
+or an enclosing `Timeout.timeout`) reaches the caller unchanged and runs no
+rollback code. A run in the caller's process is stored with status `aborted`,
+the steps not yet undone still outstanding; `MyReactor.undo(id)` rolls them
+back. A run in a worker is redelivered instead.
+
+`MyReactor.undo(id)` holds the run's context lock while it undoes, and raises
+`RubyReactor::Lock::AcquisitionError` if a live run or rollback holds it (retry
+later). When the undo reaches a completed fan-out map, it undoes the steps after
+the map, dispatches the map's element rollbacks and returns with the run
+`rolling_back`; a worker finishes the rest and marks the run `cancelled`. While a
+run is `rolling_back`, both `undo` and `cancel` raise
+`RubyReactor::Error::ValidationError`: cancelling would mark it finished and
+strand the steps before the map.
+
 ### Using Pre-defined Schemas
 
 You can use existing dry-validation schemas:
@@ -1482,7 +1533,7 @@ Explore the ways to move work off the calling process: background execution (`ba
 Discover how to build complex, modular workflows by composing reactors within other reactors. This guide covers inline composition, class-based composition, and how to manage dependencies between composed workflows.
 
 ### [Data Pipelines](documentation/data_pipelines.md)
-Master the `map` feature for processing collections. Learn about parallel execution, batch processing for large datasets, and error handling strategies like fail-fast vs. partial result collection.
+Master the `map` feature for processing collections. Learn about parallel execution, batch processing for large datasets, and error handling strategies like atomic maps vs. partial result collection.
 
 ### [Retry Configuration](documentation/retry_configuration.md)
 Configure robust retry policies for your steps. This guide details the available backoff strategies (exponential, linear, fixed), how to declare retries on a step class or inline step, and how background retries work without blocking workers.

data/lib/ruby_reactor/adapters/active_job/map_element_rollback_worker.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require "active_job"
+
+module RubyReactor
+  module Adapters
+    module ActiveJob
+      # Rolls back one element of a fan-out map (009 R-07).
+      class MapElementRollbackWorker < ::ActiveJob::Base
+        extend Compat
+
+        queue_as { RubyReactor.configuration.queue_name }
+
+        def perform(arguments)
+          RubyReactor::Map::ElementRollback.perform(arguments)
+        end
+      end
+    end
+  end
+end

data/lib/ruby_reactor/adapters/active_job/router.rb

@@ -56,7 +56,7 @@ module RubyReactor
         # rubocop:disable Metrics/ParameterLists
         def self.perform_map_element_async(map_id:, element_id:, index:, serialized_inputs:, reactor_class_info:,
                                            strict_ordering:, parent_context_id:, parent_reactor_class_name:,
-                                           step_name:, batch_size: nil, serialized_context: nil, fail_fast: nil)
+                                           step_name:, batch_size: nil, serialized_context: nil, atomic: nil)
           job_id = RubyReactor::Adapters::ActiveJob::MapElementWorker.perform_async(
             {
               "map_id" => map_id,
@@ -70,7 +70,7 @@ module RubyReactor
               "step_name" => step_name,
               "batch_size" => batch_size,
               "serialized_context" => serialized_context,
-              "fail_fast" => fail_fast
+              "atomic" => atomic
             }
           )
           RubyReactor::DispatchResult.new(job_id: job_id)
@@ -79,7 +79,7 @@ module RubyReactor
         def self.perform_map_element_in(delay, map_id:, element_id:, index:, serialized_inputs:,
                                         reactor_class_info:, strict_ordering:, parent_context_id:,
                                         parent_reactor_class_name:, step_name:, batch_size: nil,
-                                        serialized_context: nil, fail_fast: nil)
+                                        serialized_context: nil, atomic: nil)
           job_id = RubyReactor::Adapters::ActiveJob::MapElementWorker.perform_in(
             delay,
             {
@@ -94,7 +94,7 @@ module RubyReactor
               "step_name" => step_name,
               "batch_size" => batch_size,
               "serialized_context" => serialized_context,
-              "fail_fast" => fail_fast
+              "atomic" => atomic
             }
           )
           # Return an DispatchResult so RetryManager#handle_async_retry recognises the
@@ -103,6 +103,34 @@ module RubyReactor
         end
         # rubocop:enable Metrics/ParameterLists
 
+        # One element's rollback in a fan-out map's distributed rollback (009
+        # R-07); the `_in` form is its requeue on a contended element lock.
+        def self.perform_map_element_rollback_async(**args)
+          job_id = RubyReactor::Adapters::ActiveJob::MapElementRollbackWorker.perform_async(map_element_rollback_payload(**args))
+          RubyReactor::DispatchResult.new(job_id: job_id)
+        end
+
+        def self.perform_map_element_rollback_in(delay, **args)
+          job_id = RubyReactor::Adapters::ActiveJob::MapElementRollbackWorker.perform_in(
+            delay, map_element_rollback_payload(**args)
+          )
+          RubyReactor::DispatchResult.new(job_id: job_id)
+        end
+
+        # rubocop:disable Metrics/ParameterLists
+        def self.map_element_rollback_payload(map_id:, position:, element_context_id:, reactor_class_info:,
+                                              parent_reactor_class_name:, step_name:, batch_size:, owner_context_id:,
+                                              owner_reactor_class_name:, attempt: 0)
+          {
+            "map_id" => map_id, "position" => position, "element_context_id" => element_context_id,
+            "reactor_class_info" => reactor_class_info, "parent_reactor_class_name" => parent_reactor_class_name,
+            "step_name" => step_name, "batch_size" => batch_size, "owner_context_id" => owner_context_id,
+            "owner_reactor_class_name" => owner_reactor_class_name, "attempt" => attempt
+          }
+        end
+        # rubocop:enable Metrics/ParameterLists
+        private_class_method :map_element_rollback_payload
+
         # rubocop:disable Metrics/ParameterLists
         def self.perform_map_collection_async(parent_context_id:, map_id:, parent_reactor_class_name:, step_name:,
                                               strict_ordering:, timeout:)