ruby_reactor 0.8.3 → 0.8.5

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
 
@@ -21,8 +21,8 @@ The key value is **Reliability**: if any part of your workflow fails, Ruby React
 - **Background Execution**: Hand a whole reactor, or everything after a declared step, to a background job via Sidekiq or ActiveJob (so any ActiveJob-compatible queue — Resque, Solid Queue, GoodJob, etc. — works too).
 - **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**: Configurable retry logic for failed steps, with exponential backoff.
-- **Compensation**: Automatic rollback of completed steps when a failure occurs.
+- **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 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.
 
@@ -247,14 +247,16 @@ One-line helpers end a step immediately from any call depth: `success!(value)`,
 class ReserveInventoryStep < RubyReactor::Step
   # The step's input contract: enforced before `run` on every execution path.
   input :order, :hash
+  # The step's retry policy: applies in every reactor that uses this step.
+  retries max_attempts: 3
 
   def run
-    reservation_id = InventoryService.reserve(inputs[:order][:items])
+    reservation_id = InventoryService.reserve(inputs.order[:items])
     Success(reservation_id: reservation_id)
   end
 
   def compensate
-    InventoryService.release_partial(inputs[:order][:items])
+    InventoryService.release_partial(inputs.order[:items])
     Success()
   end
 
@@ -327,7 +329,7 @@ require 'ruby_reactor'
 
 class ValidateEmailStep < RubyReactor::Step
   def run
-    email = inputs[:email]
+    email = inputs.email
     email&.include?('@') ? Success(email.strip) : Failure("Email must contain @")
   end
 end
@@ -336,14 +338,14 @@ class CreateUserStep < RubyReactor::Step
   def run
     Success(
       id: rand(10000),
-      email: inputs[:email],
-      password_hash: inputs[:password_hash],
+      email: inputs.email,
+      password_hash: inputs.password_hash,
       created_at: Time.now
     )
   end
 
   def compensate
-    Notify.to(inputs[:email])
+    Notify.to(inputs.email)
     Success()
   end
 end
@@ -358,9 +360,9 @@ class UserRegistrationReactor < RubyReactor::Reactor
 
   step :hash_password do
     argument :password, input(:password)
-    run do |args, _context|
+    run do |inputs, _context|
       require 'digest'
-      Success(Digest::SHA256.hexdigest(args[:password]))
+      Success(Digest::SHA256.hexdigest(inputs.password))
     end
   end
 
@@ -373,13 +375,13 @@ class UserRegistrationReactor < RubyReactor::Reactor
     argument :email, result(:validate_email)
     wait_for :create_user
 
-    run do |args, _context|
-      Email.send!(args[:email], "verify your email")
+    run do |inputs, _context|
+      Email.send!(inputs.email, "verify your email")
       Success()
     end
 
-    compensate do |_error, args, _context|
-      Email.send("support@acme.com", "Email verification for #{args[:email]} couldn't be sent")
+    compensate do |_error, inputs, _context|
+      Email.send("support@acme.com", "Email verification for #{inputs.email} couldn't be sent")
       Success()
     end
   end
@@ -443,12 +445,12 @@ class CreateUserReactor < RubyReactor::Reactor
   input :params
 
   step :validate_inputs do
-    run { |args| validate(args[:params]) }
+    run { |inputs| validate(inputs.params) }
   end
 
   step :create_user do
     argument :params, result(:validate_inputs)
-    run { |args| User.create(args[:params]) }
+    run { |inputs| User.create(inputs.params) }
   end
 
   # :create_user is the LAST step to run in the calling process.
@@ -457,13 +459,13 @@ class CreateUserReactor < RubyReactor::Reactor
 
   step :open_account do
     argument :user, result(:create_user)
-    run { |args| Bank.open_account(args[:user]) }
+    run { |inputs| Bank.open_account(inputs.user) }
   end
 
   step :report_new_user do
     argument :user, result(:create_user)
     wait_for :open_account
-    run { |args| Analytics.track(args[:user]) }
+    run { |inputs| Analytics.track(inputs.user) }
   end
 end
 
@@ -514,19 +516,19 @@ class SignupReactor < RubyReactor::Reactor
 
   async_step :send_email do
     argument :to, input(:email)
-    run { |args| Mailer.welcome(args[:to]).deliver_now; Success(:sent) }
+    run { |inputs| Mailer.welcome(inputs.to).deliver_now; Success(:sent) }
   end
 
   # Does NOT wait — it has no dependency on :send_email.
   step :record_signup do
     argument :email, input(:email)
-    run { |args| Success(Signup.create!(email: args[:email])) }
+    run { |inputs| Success(Signup.create!(email: inputs.email)) }
   end
 
   # DOES wait, because it reads the result.
   step :confirm_delivery do
     argument :delivery, result(:send_email)
-    run { |args| Success("confirmed") }
+    run { |inputs| Success("confirmed") }
   end
 end
 ```
@@ -542,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
 
@@ -564,8 +570,8 @@ class SignupReactor < RubyReactor::Reactor
 
   step :verify do
     argument :account, result(:provision_account)   # waits for the child
-    run do |args|
-      args[:account].success? ? Success(args[:account].value) : Failure(args[:account].error)
+    run do |inputs|
+      inputs.account.success? ? Success(inputs.account.value) : Failure(inputs.account.error)
     end
   end
 end
@@ -667,7 +673,7 @@ Pause execution to wait for external events like webhooks or user approvals.
 ```ruby
 class ApprovalReactor < RubyReactor::Reactor
   step :submit_request do
-    run { |args| RequestService.submit(args) }
+    run { |inputs| RequestService.submit(inputs.to_h) }
   end
 
   interrupt :wait_for_manager do
@@ -678,8 +684,8 @@ class ApprovalReactor < RubyReactor::Reactor
 
   step :process_decision do
     argument :decision, result(:wait_for_manager)
-    run do |args| 
-      args[:decision] == 'approved' ? Success() : Failure("Rejected")
+    run do |inputs| 
+      inputs.decision == 'approved' ? Success() : Failure("Rejected")
     end
   end
 end
@@ -716,7 +722,7 @@ class RefundOrderReactor < RubyReactor::Reactor
 
   step :refund do
     argument :order_id, input(:order_id)
-    run { |args| PaymentGateway.refund(args[:order_id]) }
+    run { |inputs| PaymentGateway.refund(inputs.order_id) }
   end
 end
 
@@ -745,7 +751,7 @@ class GeocodeReactor < RubyReactor::Reactor
 
   step :geocode do
     argument :address, input(:address)
-    run { |args| Geocoder.lookup(args[:address]) }
+    run { |inputs| Geocoder.lookup(inputs.address) }
   end
 end
 
@@ -759,7 +765,7 @@ class MonthlyBillingReactor < RubyReactor::Reactor
 
   step :build do
     argument :org_id, input(:org_id)
-    run { |args| Billing.generate(args[:org_id]) }
+    run { |inputs| Billing.generate(inputs.org_id) }
   end
 end
 
@@ -775,7 +781,7 @@ class ChargeReactor < RubyReactor::Reactor
 
   step :charge do
     argument :account_id, input(:account_id)
-    run { |args| Stripe.charge(args[:account_id]) }
+    run { |inputs| Stripe.charge(inputs.account_id) }
   end
 end
 
@@ -792,7 +798,7 @@ class OrderedTransactionReactor < RubyReactor::Reactor
 
   step :apply do
     argument :transaction, input(:transaction)
-    run { |args| Ledger.apply(args[:transaction]) }
+    run { |inputs| Ledger.apply(inputs.transaction) }
   end
 end
 
@@ -816,7 +822,7 @@ class ChargeReactor < RubyReactor::Reactor
 
   step :charge do
     argument :account_id, input(:account_id)
-    run { |args| Stripe.charge(args[:account_id]) }
+    run { |inputs| Stripe.charge(inputs.account_id) }
   end
 end
 ```
@@ -841,21 +847,21 @@ A step's `run` block can also return `Halt(reason: "...")` to stop the reactor c
 ```ruby
 step :ensure_active do
   argument :user, result(:fetch_user)
-  run do |args, _ctx|
-    next Halt(reason: "user_opted_out") if args[:user].opted_out?
-    Success(args[:user])
+  run do |inputs, _ctx|
+    next Halt(reason: "user_opted_out") if inputs.user.opted_out?
+    Success(inputs.user)
   end
 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
   argument :user, result(:fetch_user)
-  run do |args, _ctx|
-    next Skipped(args[:user]) if args[:user].already_synced?
-    Success(sync!(args[:user]))
+  run do |inputs, _ctx|
+    next Skipped(inputs.user) if inputs.user.already_synced?
+    Success(sync!(inputs.user))
   end
 end
 ```
@@ -879,7 +885,7 @@ class DataProcessingReactor < RubyReactor::Reactor
 
     step :transform do
       argument :item, input(:item)
-      run { |args| transform_item(args[:item]) }
+      run { |inputs| transform_item(inputs.item) }
     end
 
     returns :transform
@@ -891,6 +897,14 @@ A `fan_out` map is a **hand-off point**: the reactor stops at the map (the calle
 
 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
+[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).
 
 > **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`).
@@ -913,7 +927,7 @@ map :archive_old_users do
 
   step :archive do
     argument :user, input(:user)
-    run { |args| args[:user].archive! }
+    run { |inputs| inputs.user.archive! }
   end
   
   returns :archive
@@ -921,9 +935,9 @@ end
 
 step :summary do
   argument :results, result(:archive_old_users)
-  run do |args|
-    puts "Archived: #{args[:results].successes.count}"
-    puts "Failed: #{args[:results].failures.count}"
+  run do |inputs|
+    puts "Archived: #{inputs.results.successes.count}"
+    puts "Failed: #{inputs.results.failures.count}"
     Success()
   end
 end
@@ -1005,12 +1019,12 @@ class ValidatedUserReactor < RubyReactor::Reactor
     argument :age, input(:age)
     argument :bio, input(:bio)
 
-    run do |args, context|
+    run do |inputs, context|
       profile = {
-        name: args[:name],
-        email: args[:email],
-        age: args[:age],
-        bio: args[:bio] || "No bio provided",
+        name: inputs.name,
+        email: inputs.email,
+        age: inputs.age,
+        bio: inputs.bio || "No bio provided",
         created_at: Time.now
       }
       Success(profile)
@@ -1124,7 +1138,7 @@ step :charge do
   argument :amount,   input(:amount)
   argument :currency, input(:currency)
 
-  run { |args, _| charge!(args) }
+  run { |inputs, _| charge!(inputs) }
 end
 ```
 
@@ -1201,9 +1215,9 @@ class OrderProcessingReactor < RubyReactor::Reactor
   step :validate_user do
     argument :user_id, input(:user_id)
 
-    run do |args, context|
+    run do |inputs, context|
       # Check if user exists and has permission to purchase
-      user = find_user(args[:user_id])
+      user = find_user(inputs.user_id)
       user ? Success(user) : Failure("User not found")
     end
   end
@@ -1211,8 +1225,8 @@ class OrderProcessingReactor < RubyReactor::Reactor
   step :validate_products do
     argument :product_ids, input(:product_ids)
 
-    run do |args, context|
-      products = args[:product_ids].map { |id| find_product(id) }
+    run do |inputs, context|
+      products = inputs.product_ids.map { |id| find_product(id) }
       if products.all?
         Success(products)
       else
@@ -1224,8 +1238,8 @@ class OrderProcessingReactor < RubyReactor::Reactor
   step :calculate_total do
     argument :products, result(:validate_products)
 
-    run do |args, context|
-      total = args[:products].sum { |p| p[:price] }
+    run do |inputs, context|
+      total = inputs.products.sum { |p| p[:price] }
       Success(total)
     end
   end
@@ -1233,8 +1247,8 @@ class OrderProcessingReactor < RubyReactor::Reactor
   step :check_inventory do
     argument :products, result(:validate_products)
 
-    run do |args, context|
-      available = args[:products].all? { |p| p[:stock] > 0 }
+    run do |inputs, context|
+      available = inputs.products.all? { |p| p[:stock] > 0 }
       available ? Success(true) : Failure("Out of stock")
     end
   end
@@ -1243,15 +1257,15 @@ class OrderProcessingReactor < RubyReactor::Reactor
     argument :user, result(:validate_user)
     argument :total, result(:calculate_total)
 
-    run do |args, context|
+    run do |inputs, context|
       # Process payment logic here
-      payment_id = process_payment(args[:user][:id], args[:total])
+      payment_id = process_payment(inputs.user[:id], inputs.total)
       Success(payment_id)
     end
 
-    undo do |error, args, context|
+    undo do |error, inputs, context|
       # Refund payment on failure
-      refund_payment(args[:payment_id])
+      refund_payment(inputs.payment_id)
       Success()
     end
   end
@@ -1261,14 +1275,14 @@ class OrderProcessingReactor < RubyReactor::Reactor
     argument :products, result(:validate_products)
     argument :payment_id, result(:process_payment)
 
-    run do |args, context|
-      order = create_order_record(args[:user], args[:products], args[:payment_id])
+    run do |inputs, context|
+      order = create_order_record(inputs.user, inputs.products, inputs.payment_id)
       Success(order)
     end
 
-    undo do |error, args, context|
+    undo do |error, inputs, context|
       # Cancel order and update inventory
-      cancel_order(args[:order][:id])
+      cancel_order(inputs.order[:id])
       Success()
     end
   end
@@ -1276,14 +1290,14 @@ class OrderProcessingReactor < RubyReactor::Reactor
   step :update_inventory do
     argument :products, result(:validate_products)
 
-    run do |args, context|
-      args[:products].each { |p| decrement_stock(p[:id]) }
+    run do |inputs, context|
+      inputs.products.each { |p| decrement_stock(p[:id]) }
       Success(true)
     end
 
-    undo do |error, args, context|
+    undo do |error, inputs, context|
       # Restock products
-      args[:products].each { |p| increment_stock(p[:id]) }
+      inputs.products.each { |p| increment_stock(p[:id]) }
       Success()
     end
   end
@@ -1292,8 +1306,8 @@ class OrderProcessingReactor < RubyReactor::Reactor
     argument :user, result(:validate_user)
     argument :order, result(:create_order)
 
-    run do |args, context|
-      send_email(args[:user][:email], "Order confirmed", order_details(args[:order]))
+    run do |inputs, context|
+      send_email(inputs.user[:email], "Order confirmed", order_details(inputs.order))
       Success(true)
     end
   end
@@ -1304,7 +1318,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
@@ -1316,9 +1330,9 @@ class TransactionReactor < RubyReactor::Reactor
     argument :from_account, input(:from_account)
     argument :to_account, input(:to_account)
 
-    run do |args, context|
-      from = find_account(args[:from_account])
-      to = find_account(args[:to_account])
+    run do |inputs, context|
+      from = find_account(inputs.from_account)
+      to = find_account(inputs.to_account)
 
       if from && to && from != to
         Success({from: from, to: to})
@@ -1332,9 +1346,9 @@ class TransactionReactor < RubyReactor::Reactor
     argument :accounts, result(:validate_accounts)
     argument :amount, input(:amount)
 
-    run do |args, context|
-      if args[:accounts][:from][:balance] >= args[:amount]
-        Success(args[:accounts])
+    run do |inputs, context|
+      if inputs.accounts[:from][:balance] >= inputs.amount
+        Success(inputs.accounts)
       else
         Failure("Insufficient funds")
       end
@@ -1345,14 +1359,14 @@ class TransactionReactor < RubyReactor::Reactor
     argument :accounts, result(:check_balance)
     argument :amount, input(:amount)
 
-    run do |args, context|
-      debit(args[:accounts][:from][:id], args[:amount])
-      Success(args[:accounts])
+    run do |inputs, context|
+      debit(inputs.accounts[:from][:id], inputs.amount)
+      Success(inputs.accounts)
     end
 
-    undo do |error, args, context|
+    undo do |error, inputs, context|
       # Credit the amount back
-      credit(args[:accounts][:from][:id], args[:amount])
+      credit(inputs.accounts[:from][:id], inputs.amount)
       Success()
     end
   end
@@ -1361,14 +1375,14 @@ class TransactionReactor < RubyReactor::Reactor
     argument :accounts, result(:debit_account)
     argument :amount, input(:amount)
 
-    run do |args, context|
-      credit(args[:accounts][:to][:id], args[:amount])
+    run do |inputs, context|
+      credit(inputs.accounts[:to][:id], inputs.amount)
       Success({transaction_id: generate_transaction_id()})
     end
 
-    undo do |error, args, context|
+    undo do |error, inputs, context|
       # Debit the amount back from recipient
-      debit(args[:accounts][:to][:id], args[:amount])
+      debit(inputs.accounts[:to][:id], inputs.amount)
       Success()
     end
   end
@@ -1377,9 +1391,9 @@ class TransactionReactor < RubyReactor::Reactor
     argument :accounts, result(:validate_accounts)
     wait_for :credit_account, :debit_account
 
-    run do |args, context|
-      Notify.to(args[:accounts][:from])
-      Notify.to(args[:accounts][:to])
+    run do |inputs, context|
+      Notify.to(inputs.accounts[:from])
+      Notify.to(inputs.accounts[:to])
     end
      
   end
@@ -1406,9 +1420,33 @@ 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.
+
 ### Using Pre-defined Schemas
 
 You can use existing dry-validation schemas:
@@ -1430,8 +1468,8 @@ class SchemaValidatedReactor < RubyReactor::Reactor
   step :process_user do
     argument :user, input(:user)
 
-    run do |args, context|
-      Success(args[:user])
+    run do |inputs, context|
+      Success(inputs.user)
     end
   end
 
@@ -1483,7 +1521,7 @@ Discover how to build complex, modular workflows by composing reactors within ot
 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.
 
 ### [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 configure retries at the reactor or step level, and how background retries work without blocking workers.
+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.
 
 ### [Interrupts](documentation/interrupts.md)
 Learn how to pause and resume reactors to handle long-running processes, manual approvals, and asynchronous callbacks. Patterns for correlation IDs, timeouts, and payload validation.

data/lib/ruby_reactor/dsl/async_macros.rb

@@ -137,9 +137,38 @@ module RubyReactor
         builder = RubyReactor::Dsl::StepBuilder.new(name, impl, self)
         builder.instance_eval(&block) if block_given?
 
-        steps[name] = builder.build(async_dispatch: :step)
+        config = builder.build(async_dispatch: :step)
+        check_async_step_undo!(builder, config, caller_locations(1, 1).first)
+        steps[name] = config
       end
 
+      # An async_step is never undone: its parent does not track it for undo
+      # (008 R-09/R-10), so an `undo` on it would be dead code. An inline one
+      # is rejected; a step class's is only warned about, because the same
+      # class is legitimately reused by ordinary steps, where it does run.
+      def check_async_step_undo!(builder, config, site)
+        if config.undo_block
+          raise RubyReactor::Error::ValidationError,
+                "`undo` on async_step :#{config.name} would never run: the parent never undoes an " \
+                "independent async unit. Put failure cleanup in the unit's `compensate` (it runs in the " \
+                "unit's job when its last attempt fails) or in the reading step's `compensate`; for cleanup " \
+                "that must run when the parent rolls back, use a `step`/`compose`/`map` (tracked for undo) " \
+                "or an `async_reactor` child whose steps declare `undo`."
+        end
+
+        return unless defines_undo?(config.impl)
+
+        builder.send(:warn_definition, site, nil,
+                     "async_step :#{config.name} uses #{config.impl}; its `undo` will not run for this async " \
+                     "use (async units are never undone).")
+      end
+      private :check_async_step_undo!
+
+      def defines_undo?(impl)
+        impl.is_a?(Class) && impl < RubyReactor::Step && impl.instance_method(:undo).owner != RubyReactor::Step
+      end
+      private :defines_undo?
+
       # Dispatch a whole nested reactor to run INDEPENDENTLY — linked
       # to this one by execution id for traceability, but excluded from its
       # compensation graph. Fire-and-forget unless a later step reads