ruby_reactor 0.8.6 → 0.8.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c59b0af2a9d34b620e3400cff78e0df3b2e580d1138b37ed5aee1b9e5a78f548
-  data.tar.gz: 4e3c2b92b6ae58797beae470b60c69015e15b2b8d6855ce710e71a999d0ae62f
+  metadata.gz: 1d262a9eed4af540e9573901be72e882f2c5e013550d51881dccef9205c6e873
+  data.tar.gz: 7a499dd2203c8059bccf9638b621974784593cabe54fddbb88e16036b7c634c5
 SHA512:
-  metadata.gz: a3ac367241909b09a5f0451b9278489776e7bedc56b506043c786892b86247a646b297a7c6192be6e5935b5e9a861f36e66e2f370a7c3e0741820cbcaa1ee409
-  data.tar.gz: 1fd3ff1f692008747021d11d5356613163a8c7777e33ead22260da4b3959bc5f6ec7fff3cb5928444815298011ff4b0e1e2e10e34c55a9781b98d9ab80893e40
+  metadata.gz: 578c3ceef421e1718c8ec48e746feae08e226e085c235b6594ac881ce0aedcf0fea8e684508c966584a6bc803bfa11a4fbf24a0666b065285f1161b8b12505dd
+  data.tar.gz: 6ee564153b8a3ce213fddf09e91df37be6b967b5a284c5cd0cdbbc4bca8b68ae4a5b3b064c314492f6f53b1bfde4ae29173cef2439886064d10c742c677cc128

data/.release-please-manifest.json

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

data/.specify/feature.json

@@ -1,3 +1,3 @@
 {
-  "feature_directory": "specs/009-distributed-map-undo"
+  "feature_directory": "specs/010-rollback-follow-ups"
 }

data/CHANGELOG.md

@@ -239,8 +239,57 @@ Every breaking or shape-changing item of the rollback work, with what to change.
 9. **`rollback_failures` entries may carry `map_step:` / `element_index:`** and the reasons
    `:context_unavailable` / `:element_in_flight` (additive).
 
+### Migration notes: rollback and resume follow-ups
+
+1. **A resume that meets the reactor's held `with_lock` or `with_semaphore` no longer raises.**
+   `continue` used to raise `Lock::AcquisitionError` / `Semaphore::AcquisitionError` and leave
+   the run paused. It now validates the payload, accepts the resume, and returns a
+   `RubyReactor::DispatchResult`; a worker waits for the lock and finishes the run. A `rescue` of
+   those errors around `continue` simply stops firing. An invalid payload is still answered at
+   once, as before.
+2. **A second resume of the same interrupt raises `ValidationError`** ("Cannot resume: interrupt
+   :x was already resumed"), in every execution mode, including `Sidekiq::Testing.inline!`.
+3. **A resume for another ready interrupt of a `running` run is accepted** (it used to raise "the
+   reactor is running") and returns a `DispatchResult`.
+4. **Interrupt attempt counts restart** for runs paused across the upgrade: they move out of the
+   run's context into their own record, so such a run may take up to `max_attempts - 1` extra
+   invalid payloads.
+5. **A synchronous `Reactor.run` holds the run's liveness lock** while it executes. A
+   `Reactor.undo(id)` of a run still executing in its caller's process now waits for it, then
+   raises `Lock::AcquisitionError`, as it does for a run executing in a worker.
+
 ### Features
 
+* **An `interrupt` inside a composed child pauses the top-level run.** Before, the compose step
+  failed with `NoMethodError` and the run rolled back. Now the top-level run is stored `paused`, at
+  any compose depth and after a `fan_out` map in the child, and the paused result carries its id.
+  Resume it on the top-level class by the interrupt's step path, an Array of the compose step names
+  then the interrupt (`continue(id:, payload:, step_name: [:approval, :wait_for_manager])`), by id
+  or by the child interrupt's correlation id. Payload validation, `max_attempts`,
+  `resume: :background` and the resume guards apply as for a top-level interrupt. A resume
+  contended on the child's own `with_lock`/`with_semaphore` fails and rolls back the run. Contention
+  on the top-level reactor's lock hands the resume to a worker. `Reactor.undo`
+  of the paused run rolls back the child's completed steps, then the parent's. A composed child
+  refuses a `continue` of its own. New `Reactor#ready_interrupt_steps` lists the pending
+  interrupts (Symbols, and paths for nested ones). `be_paused_at`, `have_ready_interrupts` and
+  `TestSubject#resume(step:)` accept paths. A `continue` must now name a pending interrupt: naming
+  another ready step, which used to store the payload as that step's result, raises
+  `ValidationError`. An `interrupt` inside a `map` element now fails that element with "not
+  supported inside a map element" instead of `NoMethodError`.
+  See [Interrupts inside composed reactors](documentation/interrupts.md#interrupts-inside-composed-reactors).
+* **`undo_all` on a map: one call rolls back every completed element.** A map declaring
+  `undo_all { |completed_results| ... }` is rolled back (an atomic map's failure, a later step's
+  failure, or `Reactor.undo`) by calling the block once with a lazy, index-ordered Enumerable of
+  the completed elements' results, instead of replaying each element's own undos. A fan-out map
+  reads its stored results and dispatches no element rollback jobs; nothing is held in memory all
+  at once. Failed elements still roll themselves back; a block that raises or returns a
+  `Failure` is reported as one rollback failure (`kind: :undo_all`) and the steps before the map
+  are still undone. New matcher: `have_run_undo_all(:map).with_elements(n)`.
+* **A resume contended on the reactor's lock or semaphore is accepted, not lost** (see migration
+  note 1). New test helpers: `resume(..., process_jobs: false)` and the `be_resume_deferred`
+  matcher.
+* **Several interrupts can be resumed at once** (see migration note 3): each accepted resume is
+  applied once.
 * **`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
@@ -342,6 +391,24 @@ Every breaking or shape-changing item of the rollback work, with what to change.
 
 ### Bug Fixes
 
+* **The recovery sweep no longer re-runs a run still executing in its caller's process.** A
+  synchronous `Reactor.run` (or an inline `continue`) now holds the run's liveness lock, renewed
+  while it executes, so a sweep during a long step leaves it alone; a killed process is still
+  recovered once the lock lapses (`context_lock_ttl`).
+* **A caller's final save no longer overwrites a worker's progress.** A synchronous run that hands
+  off at a fan-out map (or a `background` step) keeps its lock until its final save, and a Worker
+  now takes the run's lock (waiting up to 2s) before it reads the run, so it always resumes from
+  the caller's final state.
+* **Two resumes of one interrupt at the same instant: exactly one is accepted**, even in inline
+  job-testing mode, where both used to run.
+* **A resumed run waiting on a reactor lock or semaphore is no longer marked `failed` without
+  rolling back.** The snooze limit (`lock_snooze_max_attempts`) now applies only before a run is
+  admitted; an admitted run (a deferred or `resume: :background` resume) keeps waiting and logs
+  `ruby_reactor.resume.waiting` once.
+* **Manual undo finishes a `compensate` an interruption cut off.** A run aborted while its failing
+  step's `compensate` ran now records that step; `Reactor.undo(id)` runs the `compensate` again,
+  with the same arguments and reason, before undoing the completed steps (also inside composed
+  children and inline map elements). The dashboard flags such a run.
 * **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.
@@ -444,6 +511,20 @@ 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.8](https://github.com/arturictus/ruby_reactor/compare/v0.8.7...v0.8.8) (2026-10-10)
+
+
+### Bug Fixes
+
+* Rollback and Resume Follow-ups ([#72](https://github.com/arturictus/ruby_reactor/issues/72)) ([251fe9f](https://github.com/arturictus/ruby_reactor/commit/251fe9f6a9499738b6abcd6befd3a99e7cebec9f))
+
+## [0.8.7](https://github.com/arturictus/ruby_reactor/compare/v0.8.6...v0.8.7) (2026-10-08)
+
+
+### Features
+
+* add support for interrupts inside composed children ([#71](https://github.com/arturictus/ruby_reactor/issues/71)) ([7be968e](https://github.com/arturictus/ruby_reactor/commit/7be968eb5dbfc6458e9419d8c6fddbf9d89cc80e))
+
 ## [0.8.6](https://github.com/arturictus/ruby_reactor/compare/v0.8.5...v0.8.6) (2026-10-08)
 
 

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

data/README.md

@@ -595,7 +595,12 @@ any background job is enqueued the root context is persisted, and after every
 completed step a checkpoint advances the stored blob — so a crash re-runs at most
 one step, never the whole reactor. Each running reactor also holds a short
 **liveness lock** that a live worker auto-extends; its absence is how a dead
-worker is detected.
+worker is detected. A run executing in the caller's process (a synchronous
+`Reactor.run`, an inline `continue`) holds the same lock while it executes, so a
+sweep never runs it a second time, however long a step takes; if that process is
+killed, the lock lapses within `context_lock_ttl` and the run is recovered like a
+worker's. A worker takes the run's lock before it reads the run, so it always
+resumes from the last save of whoever held it.
 
 **Recovery is not automatic until you start the sweeper.** A crashed worker's
 reactor only resumes when the recovery sweeper notices the lapsed liveness lock
@@ -704,6 +709,16 @@ ApprovalReactor.continue_by_correlation_id(
 )
 ```
 
+An interrupt inside a `compose`d child pauses the top-level run; resume it there by the step path,
+e.g. `step_name: [:approval, :wait_for_manager]`. See
+[Interrupts inside composed reactors](documentation/interrupts.md#interrupts-inside-composed-reactors).
+`continue` validates the payload in the calling process first: an invalid one is answered with its
+validation failure and nothing is stored. A valid one claims its interrupt, so of two resumes of the
+same interrupt exactly one is accepted (the other raises "already resumed"). When the run is busy,
+another interrupt's resume is still running, or the reactor's `with_lock`/`with_semaphore` is held,
+the accepted resume is handed to a worker and `continue` returns a `DispatchResult` instead of
+raising, so a webhook's resume is never lost. See [Resuming Execution](documentation/interrupts.md#resuming-execution).
+
 ### Locks, Semaphores & Ordered Locks
 
 Coordinate across processes with Redis-backed primitives:
@@ -714,6 +729,8 @@ Coordinate across processes with Redis-backed primitives:
 - **`with_period`** — run at most once per calendar bucket (dedup / once-per-day, once-per-month, etc).
 - **`with_ordered_lock`** — strict transaction ordering via a monotonically increasing nonce assigned at enqueue. Workers can only proceed when their nonce equals `last_completed + 1`.
 
+An interrupt's resume that meets the reactor's held lock or semaphore is accepted and deferred to a worker, which waits for it (`continue` returns a `DispatchResult`); a run already admitted is never failed by the snooze limit for waiting.
+
 ```ruby
 class RefundOrderReactor < RubyReactor::Reactor
   input :order_id
@@ -899,8 +916,8 @@ 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
+**Rollback.** A map rolls back like a composed reactor: the `undo`s already declared on the element
+reactor's steps are each element's rollback, unless the map declares `undo_all` (below). 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
@@ -911,6 +928,28 @@ failing atomic fan-out map lets elements already in flight finish before it repo
 element `undo`s idempotent: one cut off by a killed worker runs again. See
 [Rollback](documentation/data_pipelines.md#rollback).
 
+**One bulk undo.** When an API can roll back many elements in one call (a bulk refund), declare
+`undo_all` on the map. Every rollback of the map then calls it **once** with the completed elements'
+results, instead of replaying each element's undos:
+
+```ruby
+map :charges, ChargeReactor do
+  source input(:payments)
+  argument :payment, element(:charges)
+  fan_out batch_size: 100
+
+  # A lazy Enumerable of the completed elements' results, in index order.
+  undo_all do |charges|
+    Payments.bulk_refund(charges.map { |charge| charge[:id] }.to_a)
+  end
+end
+```
+
+A fan-out map dispatches no element rollback jobs for it, and nothing holds every result at once.
+Failed elements still roll themselves back; a block that raises or returns a `Failure` is reported as
+one rollback failure (`kind: :undo_all`), and the steps before the map are still undone. See
+[`undo_all`](documentation/data_pipelines.md#undo_all-one-bulk-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`).

data/lib/ruby_reactor/dsl/map_builder.rb

@@ -84,6 +84,19 @@ module RubyReactor
         @collect_block = block
       end
 
+      # One call that rolls back every completed element (010 US7), instead of
+      # replaying each element's own undos: a bulk refund, a batch delete. The
+      # block gets a lazy Enumerable of the completed elements' results, in
+      # index order, on every rollback of the map.
+      def undo_all(&block)
+        raise RubyReactor::Error::ValidationError.new("map :#{@name} undo_all needs a block", step: @name) unless block
+        if @undo_all_block
+          raise RubyReactor::Error::ValidationError.new("map :#{@name} declares undo_all twice", step: @name)
+        end
+
+        @undo_all_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
@@ -144,7 +157,8 @@ module RubyReactor
             batch_size: { source: RubyReactor::Template::Value.new(@batch_size) },
             collect_block: { source: RubyReactor::Template::Value.new(@collect_block) },
             atomic: { source: RubyReactor::Template::Value.new(@atomic) },
-            fan_out: { source: RubyReactor::Template::Value.new(@fan_out) }
+            fan_out: { source: RubyReactor::Template::Value.new(@fan_out) },
+            **undo_all_argument
           },
           run_block: nil,
           compensate_block: nil,
@@ -155,6 +169,11 @@ module RubyReactor
         }
       end
 
+      # Read at rollback from this declaration (`MapStep#undo_all_block`).
+      def undo_all_argument
+        @undo_all_block ? { undo_all_block: { source: RubyReactor::Template::Value.new(@undo_all_block) } } : {}
+      end
+
       def extract_dependencies_from_mappings
         dependencies = []
         @argument_mappings.each_value do |source|

data/lib/ruby_reactor/error/recorded_failure.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module RubyReactor
+  module Error
+    # The reason a cut-off `compensate` receives when a manual undo runs it
+    # again (010 R-10): the run was aborted while it ran, and the original
+    # exception cannot be rebuilt from storage. It carries that exception's
+    # message, and its class name as `original_class`.
+    class RecordedFailure < Base
+      attr_reader :original_class
+
+      def initialize(message, original_class:)
+        super(message)
+        @original_class = original_class
+      end
+    end
+  end
+end

data/lib/ruby_reactor/executor/compensation_manager.rb

@@ -41,12 +41,32 @@ module RubyReactor
         @rollback_failures.replace(Array(ContextSerializer.deserialize_value(list)))
       end
 
+      # A step that paused (a compose whose child hit an interrupt) is already
+      # on top as a partial run; its re-run replaces that entry, so the step is
+      # undone once (010 R-04).
+      # ponytail: assumes the paused step's entry is on top when it re-runs,
+      # which holds because a run stops at a pause and resumes at that step.
       def add_to_undo_stack(step_info)
+        undo_stack.pop if undo_stack.last && undo_stack.last[:step].name == step_info[:step].name
         @context.undo_stack << step_info
       end
 
+      # A failing step whose `compensate` was cut off by an interruption, as
+      # an aborted run keeps it for manual undo (010 R-10, DM §4); nil once that
+      # `compensate` returned. The `arguments` key marks the record: 009's
+      # hand-off states carry none.
+      def pending_record
+        return unless @pending && !@pending[:compensated]
+
+        { "trigger" => "failure", "step" => @pending[:step].to_s, "compensated" => false,
+          "arguments" => ContextSerializer.serialize_value(@pending[:arguments] || {}),
+          "error" => recorded_error(@pending[:error]),
+          "failures" => ContextSerializer.serialize_value(@rollback_failures) }
+      end
+
       def handle_step_failure(step_config, error, arguments)
-        @pending = { step: step_config.name, error: error, compensated: false }
+        @pending = { step: step_config.name, error: error, compensated: false,
+                     arguments: step_config.rollback_arguments(arguments) }
         # A step whose OWN coordination acquisition failed (contention, or a
         # bad key proc) never ran its body — "no step compensates, the
         # contended step's work has not been attempted" (US3-1/T018), which
@@ -115,6 +135,12 @@ module RubyReactor
 
       private
 
+      def recorded_error(error)
+        return error if error.is_a?(String)
+
+        { "class" => error.class.name, "message" => error.respond_to?(:message) ? error.message : error.to_s }
+      end
+
       def middlewares
         @context.middlewares || RubyReactor::MiddlewareRunner.new([])
       end

data/lib/ruby_reactor/executor/result_handler.rb

@@ -27,6 +27,8 @@ module RubyReactor
           handle_retries_exhausted(step_config, result, resolved_arguments)
         when RubyReactor::Failure
           handle_failure(step_config, result, resolved_arguments)
+        when RubyReactor::InterruptResult
+          handle_interrupted(step_config, resolved_arguments)
         else
           handle_unknown_result(step_config, result, resolved_arguments)
         end
@@ -148,6 +150,20 @@ module RubyReactor
         result
       end
 
+      # A composed child paused at an interrupt (010): the step stays
+      # incomplete, and this run pauses on it. `with_step` cleared
+      # `current_step` on the way out; it is the run's resume cursor. The
+      # child's completed steps are only undone through this step, so it joins
+      # the undo stack as a partial run, as an interrupted compose does (R-04).
+      def handle_interrupted(step_config, resolved_arguments)
+        @context.current_step = step_config.name
+        return unless step_config.undoes_partial_run?
+
+        @compensation_manager.add_to_undo_stack({ step: step_config,
+                                                  arguments: step_config.rollback_arguments(resolved_arguments),
+                                                  result: RubyReactor.Success(nil) })
+      end
+
       # A step returned `RubyReactor.Skipped(...)`: the run continues exactly as
       # for a Success (value, hand-off, period mark), but the step is NOT pushed
       # for undo — it had nothing to do, so there is nothing to revert (008 R-19).

data/lib/ruby_reactor/executor/retry_manager.rb

@@ -108,8 +108,8 @@ module RubyReactor
           result
         when RubyReactor::Failure
           handle_failure_result(step_config, reactor_class, result)
-        when RetryQueuedResult, RubyReactor::DispatchResult
-          # Pass through async results
+        when RetryQueuedResult, RubyReactor::DispatchResult, RubyReactor::InterruptResult
+          # Pass through async results, and a composed child's pause
           result
         else
           clear_retry_state

data/lib/ruby_reactor/executor/step_executor.rb

@@ -431,6 +431,15 @@ module RubyReactor
           return RubyReactor.Success(result)
         end
 
+        # A map element cannot pause: nothing would resume it. The step fails
+        # like any other, rolling back what the element completed (010 R-08).
+        if inside_map_element?
+          failure = RubyReactor::Failure("interrupt :#{step_config.name} is not supported inside a map element",
+                                         step_name: step_config.name, reactor_name: @reactor_class.name,
+                                         retryable: false)
+          return @result_handler.handle_step_result(step_config, failure, {})
+        end
+
         # We are pausing
         correlation_id = nil
         correlation_id = step_config.correlation_id_block.call(@context) if step_config.correlation_id_block
@@ -445,6 +454,17 @@ module RubyReactor
         )
       end
 
+      # This run, or one it is composed into, is a map element.
+      def inside_map_element?
+        context = @context
+        while context
+          return true if context.map_metadata
+
+          context = context.parent_context
+        end
+        false
+      end
+
       def configuration
         RubyReactor::Configuration.instance
       end

data/lib/ruby_reactor/executor.rb

@@ -21,6 +21,12 @@ module RubyReactor
     attr_reader :reactor_class, :context, :dependency_graph, :compensation_manager, :retry_manager, :result_handler,
                 :step_executor, :result, :middlewares
 
+    # The owner of a run lock (`async:<id>`) the caller already holds: a Worker
+    # or `continue` that locked the run before loading it (010 R-02, R-03).
+    # `acquire_context_lock` then re-enters it (the lock counts by owner), and
+    # the outer holder releases last.
+    attr_writer :context_lock_owner
+
     def initialize(reactor_class, inputs = {}, context = nil)
       # Resume, map, compose and background workers build an Executor without
       # going through Reactor#run; the inferred wiring must exist there too.
@@ -109,6 +115,12 @@ module RubyReactor
       input_validator = InputValidator.new(@reactor_class, @context)
       input_validator.validate!
 
+      # A run in the caller's process holds its liveness lock too (010 R-01),
+      # so the sweeper never mistakes it for a dead worker's run and a Worker
+      # resumed by its hand-off waits for its final save. In a worker the
+      # executor runs `resume_execution`, which takes it there.
+      acquire_context_lock unless @context.inline_async_execution
+
       reset_held_lock_keys!
       acquire_locks_with_telemetry
 
@@ -168,6 +180,10 @@ module RubyReactor
       release_locks unless @parked
       leave_ordered_lock_scope
       save_context if persist_context? && !skip_context_persist?
+      # Released only after that save (J-3, 009 R-13): a Worker waiting on the
+      # lock then reads this run's final state.
+      @acquired_context_lock&.release
+      @acquired_context_lock = nil
 
       emit_lifecycle_completion(completed)
     end
@@ -221,6 +237,10 @@ module RubyReactor
       # holds it — composed/nested children resume inline under the root worker
       # and must not contend on the root's own key.
       acquire_context_lock
+      # The only place a claimed resume payload enters a context (010 R-04,
+      # J-5): under the run's lock, before the reactor-level lock or
+      # semaphore, so a contended resume still saves the payload it applied.
+      InterruptClaims.apply!(@context) if (@context.root_context || @context).equal?(@context)
 
       reset_held_lock_keys!
 
@@ -249,7 +269,6 @@ module RubyReactor
       @context.admit!
       prepare_for_resume
       save_context
-      @past_gates = true
 
       @result = if @context.current_step
                   execute_current_step_and_continue
@@ -313,6 +332,7 @@ module RubyReactor
     def undo_all(&after_pop)
       saved = @context.rollback && @context.rollback["failures"]
       @compensation_manager.restore_rollback_failures(saved) if saved
+      compensate_pending!
       @compensation_manager.rollback_completed_steps(&after_pop)
       clear_saved_rollback_failures
     rescue Error::RollbackHandedOff
@@ -390,12 +410,6 @@ module RubyReactor
                                                            RubyReactor.reactor_storage_name(@reactor_class))
     end
 
-    # True once `resume_execution` is past its reactor-level gates (context
-    # lock, lock, semaphore, period): from there on it may have run steps.
-    def past_gates?
-      @past_gates == true
-    end
-
     # Reached only by an interruption — a signal, an exit, out of memory, an
     # enclosing timeout (008 R-08, R-16); every other exception was rescued as
     # `Error::Rescuable` and rolled back. Running user rollback code now is
@@ -404,7 +418,13 @@ module RubyReactor
     # `Reactor#undo`; the `ensure` persists it, best effort. A worker run stays
     # `running` and its job is redelivered.
     def mark_aborted
-      @context.status = :aborted unless @context.inline_async_execution
+      return if @context.inline_async_execution
+
+      @context.status = :aborted
+      # The failing step's `compensate`, if the interruption cut it off: a
+      # manual undo runs it again before the undo stack (010 R-10, J-9).
+      record = @compensation_manager.pending_record
+      @context.rollback = record if record
     end
 
     # A rollback run from a `rescue Error::Rescuable` body is outside the
@@ -663,6 +683,8 @@ module RubyReactor
     # defeat the guard. Only the root executor acquires — a composed/nested child
     # resumes inline under the root worker and shares the root's lock, so it must
     # not try to re-acquire the same key with a different owner (self-deadlock).
+    # Held by a worker's resume and by a run in the caller's process alike (010
+    # R-01); an outer holder's owner, when set, is re-entered (R-03).
     def acquire_context_lock
       root = @context.root_context || @context
       return unless root.equal?(@context) # only the root executor holds it
@@ -980,7 +1002,7 @@ module RubyReactor
     # gives (I-7).
     def finish_rollback(state)
       @compensation_manager.restore_rollback_failures(state["failures"])
-      return finish_undo if state["trigger"] == "undo"
+      return finish_undo(state) if state["trigger"] == "undo"
 
       failure = ContextSerializer.deserialize_value(state["failure"])
       step_config = state["step"] && @reactor_class.steps[state["step"].to_sym]
@@ -998,8 +1020,38 @@ module RubyReactor
       @result_handler.handle_execution_error(e)
     end
 
-    def finish_undo
+    # A manual undo ends `cancelled`, or `failed` when it was the failure of
+    # an interrupt whose payload attempts ran out (010 R-08).
+    # An aborted run's failing step whose `compensate` an interruption cut off
+    # (010 R-10, J-9): run it again, with the recorded arguments and reason,
+    # before the undo stack. Only that record carries `arguments`; 009's
+    # hand-off states, which name the same keys, are finished elsewhere.
+    def compensate_pending!
+      state = @context.rollback
+      return unless state.is_a?(Hash) && state.key?("arguments") && state["compensated"] == false
+
+      step_config = state["step"] && @reactor_class.steps[state["step"].to_sym]
+      return unless step_config
+
+      @compensation_manager.compensate(step_config, recorded_reason(state["error"]),
+                                       ContextSerializer.deserialize_value(state["arguments"]))
+      state["compensated"] = true
+    end
+
+    def recorded_reason(error)
+      return error unless error.is_a?(Hash)
+
+      Error::RecordedFailure.new(error["message"], original_class: error["class"])
+    end
+
+    def finish_undo(state)
       @compensation_manager.rollback_completed_steps
+      if state["failure_reason"]
+        @context.status = "failed"
+        @context.failure_reason = state["failure_reason"]
+        return nil
+      end
+
       @context.cancelled = true
       @context.cancellation_reason = "Undo triggered"
       @context.status = "cancelled"

data/lib/ruby_reactor/interrupt_claims.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module RubyReactor
+  # A resume claims its interrupt before anything runs (010 R-04): the first
+  # `SET NX` wins, in every execution mode, and the claim holds the validated
+  # payload. Only the execution that owns the run's lock copies a claim into
+  # the context (J-5), at the start of `Executor#resume_execution`, so a
+  # resume never writes the run from outside it.
+  module InterruptClaims
+    module_function
+
+    # true when this call won the interrupt; false when a resume already did.
+    # `path` is the interrupt's step path (010 R-05); a nested one is keyed `a.b`.
+    def claim!(context, path, payload)
+      storage.claim_interrupt_resume(context.context_id, storage_name(context), key(Array(path)),
+                                     JSON.generate(ContextSerializer.serialize_value(payload)))
+    end
+
+    # true when a resume already claimed the interrupt, applied or not.
+    def claimed?(context, path)
+      storage.retrieve_interrupt_resumes(context.context_id, storage_name(context), [key(Array(path))]).any?
+    end
+
+    # `{ step => payload }` (a nested interrupt: `{ [child, step] => payload }`)
+    # for the claimed interrupts that have no result yet.
+    def unapplied(context)
+      paths = pending_interrupts(context)
+      return {} if paths.empty?
+
+      raw = storage.retrieve_interrupt_resumes(context.context_id, storage_name(context), paths.map { |p| key(p) })
+      paths.filter_map do |path|
+        if raw.key?(key(path))
+          [path.one? ? path.first : path,
+           ContextSerializer.deserialize_value(JSON.parse(raw[key(path)]))]
+        end
+      end.to_h
+    end
+
+    # Copies every unapplied claim into the context that paused at it (010 R-06).
+    # Returns their steps.
+    def apply!(context)
+      claims = unapplied(context)
+      claims.each do |step, payload|
+        path = Array(step)
+        path[0...-1].reduce(context) { |ctx, name| child(ctx, name) }.set_result(path.last, payload)
+      end
+      claims.keys
+    end
+
+    # Step paths of the interrupts without a result, here and in paused composed children.
+    def pending_interrupts(context, prefix = [])
+      steps = context.reactor_class.respond_to?(:steps) ? context.reactor_class.steps : {}
+      interrupts = steps.select do |name, config|
+        config.respond_to?(:interrupt?) && config.interrupt? && !context.has_result?(name)
+      end
+      own = interrupts.keys.map { |name| prefix + [name] }
+      nested = steps.keys.flat_map do |name|
+        (c = child(context, name)) ? pending_interrupts(c, prefix + [name]) : []
+      end
+      own + nested
+    end
+
+    def child(context, name)
+      entry = context.composed_contexts[name] || context.composed_contexts[name.to_s]
+      c = entry.is_a?(Hash) && (entry[:context] || entry["context"])
+      c if c.is_a?(Context) && c.status.to_s == "paused"
+    end
+
+    def key(path)
+      path.join(".")
+    end
+
+    def storage_name(context)
+      RubyReactor.reactor_storage_name(context.reactor_class)
+    end
+
+    def storage
+      RubyReactor.configuration.storage_adapter
+    end
+  end
+end