ruby_reactor 0.8.5 → 0.8.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a4187fd51277447b11381c872a01b46d8e7663323b5b470316d8600ead76906e
-  data.tar.gz: 540b0c6b94d007a020f3bfbb3ff035eb47469691bf138cd41588e5a6a28ba468
+  metadata.gz: c59b0af2a9d34b620e3400cff78e0df3b2e580d1138b37ed5aee1b9e5a78f548
+  data.tar.gz: 4e3c2b92b6ae58797beae470b60c69015e15b2b8d6855ce710e71a999d0ae62f
 SHA512:
-  metadata.gz: 59c5faa4c755625a2172a5a7613941a82970aa3b52ac170f6c2f12015f41b289700d320d0195b51d4b13e1cf1f9b86e209bc8c59d5dcc84830a2e65c1c49a48d
-  data.tar.gz: 0be05ffe9539a5ae4c012a8f8e3f26394d27853a86219a7c02d82d9685f7f018bd760c26f749cf34c4899f0c9346c6a54a91ee64e0e274b2f2ad2d12048ee818
+  metadata.gz: a3ac367241909b09a5f0451b9278489776e7bedc56b506043c786892b86247a646b297a7c6192be6e5935b5e9a861f36e66e2f370a7c3e0741820cbcaa1ee409
+  data.tar.gz: 1fd3ff1f692008747021d11d5356613163a8c7777e33ead22260da4b3959bc5f6ec7fff3cb5928444815298011ff4b0e1e2e10e34c55a9781b98d9ab80893e40

data/.release-please-manifest.json

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

data/.specify/feature.json

@@ -1,3 +1,3 @@
 {
-  "feature_directory": "specs/008-rollback-reliability"
+  "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

@@ -241,6 +241,33 @@ Every breaking or shape-changing item of the rollback work, with what to change.
 
 ### 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,
@@ -302,6 +329,11 @@ Every breaking or shape-changing item of the rollback work, with what to change.
 
 ### 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
@@ -310,6 +342,25 @@ Every breaking or shape-changing item of the rollback work, with what to change.
 
 ### 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
@@ -393,6 +444,13 @@ Every breaking or shape-changing item of the rollback work, with what to change.
 * 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)
 
 

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/008-rollback-reliability/plan.md
+at specs/009-distributed-map-undo/plan.md
 <!-- SPECKIT END -->

data/README.md

@@ -634,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
@@ -893,19 +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).
 
 **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 under `fail_fast`, or `collect` raises), and when a later step fails or the run is
-undone manually, every element that completed is rolled back, highest index first, in inline and
-fan-out mode alike. A fail-fast fan-out map lets elements already in flight finish before it reports
-the failure. Make element `undo`s idempotent. See
+(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, 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).
+`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`).
 
@@ -1447,6 +1453,15 @@ 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:
@@ -1518,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:)

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

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module RubyReactor
+  module Adapters
+    module Sidekiq
+      # Rolls back one element of a fan-out map (009 R-07).
+      class MapElementRollbackWorker
+        include ::Sidekiq::Worker
+
+        def perform(arguments)
+          RubyReactor::Map::ElementRollback.perform(arguments)
+        end
+      end
+    end
+  end
+end

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

@@ -58,7 +58,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::Sidekiq::MapElementWorker.perform_async(
             {
               "map_id" => map_id,
@@ -72,7 +72,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)
@@ -81,7 +81,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::Sidekiq::MapElementWorker.perform_in(
             delay,
             {
@@ -96,7 +96,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
@@ -105,6 +105,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::Sidekiq::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::Sidekiq::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:)

data/lib/ruby_reactor/context.rb

@@ -29,6 +29,12 @@ module RubyReactor
                   :cancelled, :cancellation_reason, :parent_context_id, :retried_from_id, :status, :failure_reason,
                   :middlewares
 
+    # Where this execution level's rollback stands while it is `rolling_back`
+    # (009 DM §1): `trigger`, `step`, `compensated`, `failure`, `failures`.
+    # Kept JSON-safe (string keys; `failure` / `failures` already serialized),
+    # so it round-trips unchanged. Nil otherwise.
+    attr_accessor :rollback
+
     # Transient, NOT serialized (absent from `to_h`, `serialize_for_retry`,
     # and `deserialize_from_retry` below — confirmed by
     # reentrancy_spec.rb US4-16). Overrides `StepCoordination#owner` for
@@ -76,6 +82,10 @@ module RubyReactor
       @status.to_s == "failed"
     end
 
+    def rolling_back?
+      @status.to_s == "rolling_back"
+    end
+
     def get_input(name, path = nil)
       value = Utils::FetchIndifferent.call(@inputs, name)
       return nil if value.nil?
@@ -149,7 +159,8 @@ module RubyReactor
         reactor_class: @reactor_class,
         execution_trace: @execution_trace,
         status: @status,
-        failure_reason: @failure_reason
+        failure_reason: @failure_reason,
+        rollback: @rollback
       }
     end
 
@@ -175,6 +186,7 @@ module RubyReactor
         cancellation_reason: @cancellation_reason,
         status: @status,
         failure_reason: ContextSerializer.serialize_value(@failure_reason),
+        rollback: @rollback,
         parent_context_id: @parent_context&.context_id || @parent_context_id,
         retried_from_id: @retried_from_id
       }
@@ -200,6 +212,7 @@ module RubyReactor
       context.cancellation_reason = data["cancellation_reason"]
       context.status = data["status"] || "pending"
       context.failure_reason = ContextSerializer.deserialize_value(data["failure_reason"])
+      context.rollback = data["rollback"]
       context.parent_context_id = data["parent_context_id"]
       context.retried_from_id = data["retried_from_id"]
 

data/lib/ruby_reactor/dsl/definition_warnings.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module RubyReactor
+  module Dsl
+    # Definition-time warnings for the DSL builders, printed once per
+    # declaration site for the process. The including builder sets `@reactor`.
+    module DefinitionWarnings
+      def self.deprecation_sites
+        @deprecation_sites ||= Set.new
+      end
+
+      private
+
+      def warn_deprecation(site, message)
+        warn_definition(site, "DEPRECATION:", "#{message} Removal no earlier than the next MAJOR.")
+      end
+
+      def warn_definition(site, prefix, message)
+        location = "#{site.path}:#{site.lineno}"
+        return unless DefinitionWarnings.deprecation_sites.add?(location)
+
+        warn ["[RubyReactor]", prefix, location, reactor_label, message].compact.join(" ")
+      end
+
+      def reactor_label
+        @reactor&.name || @reactor.inspect
+      end
+    end
+  end
+end

data/lib/ruby_reactor/dsl/map_builder.rb

@@ -4,6 +4,7 @@ module RubyReactor
   module Dsl
     class MapBuilder
       include RubyReactor::Dsl::TemplateHelpers
+      include RubyReactor::Dsl::DefinitionWarnings
 
       attr_accessor :name, :mapped_reactor_class, :argument_mappings, :source_enumerable
 
@@ -25,7 +26,7 @@ module RubyReactor
         @batch_size = nil
         @source_enumerable = nil
         @collect_block = nil
-        @fail_fast = true # Default: stop on first error
+        @atomic = true # Default: every element succeeds, or none is kept
       end
 
       def argument(mapped_input_name, source)
@@ -41,10 +42,10 @@ module RubyReactor
       end
 
       # Run every element as its own background job. `batch_size` caps how many
-      # element jobs are enqueued at a time (back pressure); without it the whole
-      # source fans out at once. A fan-out map is a hand-off point: the reactor
-      # stops at the map and resumes in a worker once the collector has every
-      # element's outcome.
+      # element jobs one throw enqueues (back pressure), forward and rollback;
+      # without it, `Map::DEFAULT_BATCH_SIZE` (50) does. A fan-out map is a
+      # hand-off point: the reactor stops at the map and resumes in a worker
+      # once the collector has every element's outcome.
       def fan_out(enabled = true, batch_size: nil)
         @fan_out = enabled
         self.batch_size(batch_size) unless batch_size.nil?
@@ -83,11 +84,30 @@ module RubyReactor
         @collect_block = block
       end
 
+      # On (the default), the map succeeds only if every element does: the
+      # first element failure fails it, no new element starts, and every
+      # completed element is rolled back. Off, it completes with every
+      # element's outcome; a failed element rolls itself back, the others are
+      # kept.
+      def atomic(enabled = true)
+        @atomic_declared = true
+        @atomic = enabled
+      end
+
+      # The old name for `atomic` (009 R-11), which read as "stop early".
       def fail_fast(enabled = true)
-        @fail_fast = enabled
+        @fail_fast_site = caller_locations(1, 1).first
+        @atomic = enabled
+        warn_deprecation(@fail_fast_site, "map :#{@name} declares fail_fast. Use atomic (same meaning).")
       end
 
       def build
+        if @atomic_declared && @fail_fast_site
+          raise RubyReactor::Error::ValidationError.new(
+            "map :#{@name} declares both fail_fast and atomic; declare only atomic", step: @name
+          )
+        end
+
         dependencies = extract_dependencies_from_mappings
         dependencies << @source_enumerable.step_name if @source_enumerable.is_a?(RubyReactor::Template::Result)
 
@@ -123,7 +143,7 @@ module RubyReactor
             strict_ordering: { source: RubyReactor::Template::Value.new(@strict_ordering) },
             batch_size: { source: RubyReactor::Template::Value.new(@batch_size) },
             collect_block: { source: RubyReactor::Template::Value.new(@collect_block) },
-            fail_fast: { source: RubyReactor::Template::Value.new(@fail_fast) },
+            atomic: { source: RubyReactor::Template::Value.new(@atomic) },
             fan_out: { source: RubyReactor::Template::Value.new(@fan_out) }
           },
           run_block: nil,

data/lib/ruby_reactor/dsl/step_builder.rb

@@ -7,6 +7,7 @@ module RubyReactor
       include RubyReactor::Dsl::ValidationHelpers
       include RubyReactor::Dsl::Lockable::ClassMethods
       include RubyReactor::Dsl::Retryable
+      include RubyReactor::Dsl::DefinitionWarnings
 
       COORDINATION_MACROS = {
         lock_config: "with_lock", semaphore_config: "with_semaphore", rate_limit_config: "with_rate_limit",
@@ -34,11 +35,6 @@ module RubyReactor
         @rule_sites = []
       end
 
-      # Deprecation notices print once per declaration site for the process.
-      def self.deprecation_sites
-        @deprecation_sites ||= Set.new
-      end
-
       def argument(name, source, type = nil, transform: nil, **predicates)
         @arguments[name] = {
           source: source,
@@ -244,25 +240,9 @@ module RubyReactor
                                               "the step instead (`validate_inputs` in #{target}).")
       end
 
-      def warn_deprecation(site, message)
-        warn_definition(site, "DEPRECATION:", "#{message} Removal no earlier than the next MAJOR.")
-      end
-
-      # A definition-time warning, printed once per declaration site.
-      def warn_definition(site, prefix, message)
-        location = "#{site.path}:#{site.lineno}"
-        return unless StepBuilder.deprecation_sites.add?(location)
-
-        warn ["[RubyReactor]", prefix, location, reactor_label, message].compact.join(" ")
-      end
-
       def owned_contract
         @inline_contract || (@impl.input_contract if @impl.respond_to?(:declares_inputs?) && @impl.declares_inputs?)
       end
-
-      def reactor_label
-        @reactor&.name || @reactor.inspect
-      end
     end
 
     class StepConfig
@@ -450,6 +430,13 @@ module RubyReactor
         rollback_tracked? && has_impl? && impl.respond_to?(:undoes_partial_run?) && impl.undoes_partial_run?
       end
 
+      # What the undo record keeps of the step's resolved arguments: all of
+      # them, unless the step reads its rollback state elsewhere (a map reads
+      # its declaration and the map records, 009 R-14).
+      def rollback_arguments(resolved)
+        has_impl? && impl.respond_to?(:rollback_arguments) ? impl.rollback_arguments(resolved) : resolved
+      end
+
       def has_impl?
         !@impl.nil?
       end