ruby_reactor 0.8.7 → 0.8.8

data/lib/ruby_reactor/web/public/index.html

@@ -5,7 +5,7 @@
     <link rel="icon" type="image/svg+xml" href="./vite.svg" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <title>ui</title>
-    <script type="module" crossorigin src="./assets/index-C6ejszCQ.js"></script>
+    <script type="module" crossorigin src="./assets/index-DxjQlW7Q.js"></script>
     <link rel="stylesheet" crossorigin href="./assets/index-DM5darhy.css">
   </head>
   <body>

data/lib/ruby_reactor/worker.rb

@@ -8,7 +8,13 @@ module RubyReactor
   # `Adapters::ActiveJob::Compat` on ActiveJob::Base) — nothing here references
   # a specific backend.
   module Worker
-    TERMINAL_STATUSES = %w[completed failed cancelled skipped aborted].freeze
+    TERMINAL_STATUSES = %w[completed failed cancelled skipped halted aborted].freeze
+
+    # Seconds a Worker waits for the run's lock before it reads the run (010
+    # R-02). The usual holder is the caller that enqueued this job, a few
+    # milliseconds from its final save and release; a snooze would cost a whole
+    # scheduled-set poll instead. Same bound as `Map::Collector::COLLECT_LOCK_WAIT`.
+    CONTEXT_LOCK_WAIT = 2
 
     # Use the error's `retry_after_seconds` hint when available
     # (RateLimit::ExceededError carries the time until the bucket rolls);
@@ -81,16 +87,58 @@ module RubyReactor
     # Identity-only payload: storage is the source of truth. Rehydrate the live
     # context from storage by id, then resume. A nil read means the context was
     # swept, expired, or already terminal-and-collected — nothing to resume.
+    #
+    # Lock, then load (010 R-02, J-2): the run's `async:` lock is taken BEFORE
+    # the read, so this job sees the last save of whoever held it — a caller
+    # that just handed off, a manual undo, another worker — and its own later
+    # save can never replace newer progress. The executor re-enters the lock.
     def perform(context_id, reactor_class_name = nil, snooze_count = 0)
       # Normalize so a nil/omitted name resolves to the same storage key the
       # enqueue path wrote (always via reactor_storage_name). Without this a
       # nil here builds "reactor::context:<id>" and misses the stored
       # "reactor:AnonymousReactor:context:<id>", silently no-op'ing.
       reactor_class_name ||= RubyReactor.reactor_storage_name(nil)
+      lock = lock_run(context_id, reactor_class_name, snooze_count)
+      return if lock == :snoozed
+
+      begin
+        perform_locked(context_id, reactor_class_name, snooze_count, lock&.owner)
+      ensure
+        lock&.release
+      end
+    end
+
+    private
+
+    # nil in inline job-testing mode, where a nested re-entry would contend
+    # with itself (as `Executor#acquire_context_lock`). Another live holder
+    # after the wait: snooze, uncapped, having read and written nothing.
+    def lock_run(context_id, reactor_class_name, snooze_count)
+      return nil if inline_testing_mode?
+
+      lock = RubyReactor::Lock.new("async:#{context_id}", owner: SecureRandom.uuid,
+                                                          ttl: RubyReactor.configuration.context_lock_ttl,
+                                                          wait: CONTEXT_LOCK_WAIT, auto_extend: true)
+      lock.acquire
+      lock
+    rescue RubyReactor::Lock::AcquisitionError => e
+      contention = RubyReactor::Lock::ContextLockContention.new(e.message, context_lock_key: "async:#{context_id}")
+      handle_snooze(context_id, reactor_class_name, nil, snooze_count, contention)
+      :snoozed
+    end
+
+    def inline_testing_mode?
+      defined?(::Sidekiq::Testing) && ::Sidekiq::Testing.respond_to?(:inline?) && ::Sidekiq::Testing.inline?
+    end
+
+    def perform_locked(context_id, reactor_class_name, snooze_count, lock_owner)
       data = RubyReactor.configuration.storage_adapter.retrieve_context(context_id, reactor_class_name)
       return if data.nil?
-      # An aborted run is never resumed forward: only a manual undo applies (008 R-08).
-      return if (data["status"] || data[:status]).to_s == "aborted"
+
+      status = (data["status"] || data[:status]).to_s
+      # Finished, cancelled or aborted: nothing to resume (an aborted run takes
+      # only a manual undo, 008 R-08). A stray or duplicate job does nothing.
+      return if TERMINAL_STATUSES.include?(status)
 
       begin
         context = ContextSerializer.deserialize_hash(data)
@@ -115,6 +163,10 @@ module RubyReactor
         return
       end
 
+      # A paused run advances only with a claimed payload (010 R-06): a stray
+      # job must never run the steps that follow the interrupt without one.
+      return if status == "paused" && InterruptClaims.unapplied(context).empty?
+
       # Mark that we're executing inline to prevent nested async calls
       context.inline_async_execution = true
 
@@ -122,7 +174,8 @@ module RubyReactor
         # Resume execution from the failed step — or, for a run whose rollback
         # handed off at a fan-out map, finish that rollback (009 R-04).
         executor = Executor.new(context.reactor_class, {}, context)
-        rolling_back = (data["status"] || data[:status]).to_s == "rolling_back"
+        executor.context_lock_owner = lock_owner
+        rolling_back = status == "rolling_back"
         rolling_back ? executor.resume_rollback : executor.resume_execution
         # No explicit save here: resume_execution's ensure block already persists
         # the final root state (`save_context unless skip_context_persist?`), and
@@ -155,8 +208,6 @@ module RubyReactor
       end
     end
 
-    private
-
     # If reactor_class_name is provided, use it to get the reactor class.
     # This handles cases where the class can't be found via const_get.
     def resolve_reactor_class!(context, reactor_class_name)
@@ -203,6 +254,16 @@ module RubyReactor
                  error.is_a?(RubyReactor::Lock::ContextLockContention) ||
                  error.is_a?(RubyReactor::Error::ExecutionParked))
 
+      # Escalation marks the run `failed` WITHOUT rolling back: harmless before
+      # admission, when nothing ran, but a run already admitted (a resume,
+      # deferred or `resume: :background`, or a re-entry after a hand-off) has
+      # completed steps whose effects would be stranded. It keeps waiting
+      # instead, and says so once (010 R-07, J-8).
+      if capped && context&.admitted?
+        warn_still_waiting(context, snooze_count, error) if max != :infinity && snooze_count == max
+        capped = false
+      end
+
       if capped && max != :infinity && snooze_count >= max
         escalate_snooze(context, snooze_count, error)
         return
@@ -214,6 +275,12 @@ module RubyReactor
       self.class.perform_in(delay, context_id, reactor_class_name, snooze_count + 1)
     end
 
+    def warn_still_waiting(context, snooze_count, error)
+      fields = { event: "ruby_reactor.resume.waiting", reactor: RubyReactor.reactor_storage_name(context.reactor_class),
+                 context_id: context.context_id, error: error.message, snooze_count: snooze_count }
+      RubyReactor.configuration.logger.warn(fields.map { |k, v| "#{k}=#{v.inspect}" }.join(" "))
+    end
+
     # Instance methods delegate to the module functions above — worker
     # behavior is unchanged, just relocated so other callers (StepWorker,
     # T036) can reuse the same logic without a Worker instance.

data/specs/010-rollback-follow-ups/checklists/requirements.md

@@ -0,0 +1,47 @@
+# Specification Quality Checklist: Rollback and Resume Follow-ups
+
+**Purpose**: Validate specification completeness and quality before proceeding to planning
+**Created**: 2026-10-08
+**Feature**: [spec.md](../spec.md)
+
+## Content Quality
+
+- [x] No implementation details (languages, frameworks, APIs)
+- [x] Focused on user value and business needs
+- [x] Written for non-technical stakeholders
+- [x] All mandatory sections completed
+
+## Requirement Completeness
+
+- [x] No [NEEDS CLARIFICATION] markers remain
+- [x] Requirements are testable and unambiguous
+- [x] Success criteria are measurable
+- [x] Success criteria are technology-agnostic (no implementation details)
+- [x] All acceptance scenarios are defined
+- [x] Edge cases are identified
+- [x] Scope is clearly bounded
+- [x] Dependencies and assumptions identified
+
+## Feature Readiness
+
+- [x] All functional requirements have clear acceptance criteria
+- [x] User scenarios cover primary flows
+- [x] Feature meets measurable outcomes defined in Success Criteria
+- [x] No implementation details leak into specification
+
+## Notes
+
+- The gem's public API (`continue`, `Reactor.run`, `Reactor.undo`, `map`, `undo_all`,
+  `DispatchResult`) is the user-facing surface of a library, so naming it is not an implementation
+  detail (same convention as specs 008 and 009). Internal classes, storage keys and lock mechanics
+  are kept out; the one mechanism mentioned (a liveness lock for caller-process runs) is an example
+  in Assumptions, explicitly left to the plan.
+- No clarification markers: each item's direction came from `specs/future_improvements.md`. Defaults
+  chosen where it offered two options:
+  - US5 accepts a resume for another pending interrupt, rather than returning a retryable error,
+    matching US3's hand-off.
+  - US1/US2 get targeted fixes; the full fenced-writes proposal is out of scope.
+  - `undo_all` leaves partially-run (aborted) elements to per-element replay.
+
+  `/speckit-clarify` can revisit any of these.
+- Validation pass 1: all items pass.

data/specs/010-rollback-follow-ups/contracts/api-surface.md

@@ -0,0 +1,123 @@
+# Contract: Public API Surface
+
+Changes to what gem users call, receive, or observe. Internals appear only where a spec pins them.
+
+## 1. `Reactor.continue` / `Reactor#continue` / `Reactor.continue_by_correlation_id`
+
+Signatures are unchanged: `continue(id:, payload:, step_name:, idempotency_key: nil)` on the class,
+`continue(payload:, step_name:, idempotency_key: nil)` on an instance.
+
+### Outcomes
+
+| Situation | Today | After 010 |
+| --- | --- | --- |
+| Valid payload, run `paused`, gates free | resumes inline and returns its result (`Success`, `Failure`, `InterruptResult` or `DispatchResult`) | unchanged |
+| Valid payload, the reactor's `with_lock` / `with_semaphore` is held by another run | raises `Lock::AcquisitionError` / `Semaphore::AcquisitionError`; the run stays `paused` | **returns `DispatchResult`**; the run is `running`; a Worker resumes it once the lock frees (FR-009, FR-010) |
+| Valid payload, `resume: :background` interrupt | returns `DispatchResult` | unchanged |
+| Valid payload for a ready interrupt, run `running` (another resume, or the run is executing) | raises `ValidationError` "the reactor is running, not paused" | **returns `DispatchResult`**; the payload is applied once the run is free (FR-017–FR-019) |
+| Second resume of the same interrupt (concurrent or later) | may run twice (inline mode) or race | **raises `ValidationError`** "Cannot resume: interrupt :x was already resumed" (FR-015, FR-020) |
+| Invalid payload | the class method raises `InputValidationError`; the instance method returns `Failure(invalid_payload: true)`; one attempt counted | unchanged; the attempt is now counted in its own record (data-model §3) |
+| Invalid payload at `max_attempts` | undoes, then saves `failed` (two unlocked writes) | same outcome, under the run's lock (R-08, R-09); may raise `Lock::AcquisitionError` if another execution holds the run for more than 5s |
+| Interrupt not ready | raises `ValidationError` | unchanged |
+| Run finished, `aborted`, `rolling_back`, or cancelled | raises `ValidationError` | unchanged (008 FR-032) |
+
+A `DispatchResult` from a hand-off carries `execution_id: <run id>`. In inline job-testing mode, a
+hand-off that already finished returns the reloaded result, as `resume: :background` does today
+(`check_for_inline_completion`).
+
+**Migration** (CHANGELOG): a `rescue Lock::AcquisitionError` / `Semaphore::AcquisitionError` around
+`continue` no longer fires; the resume was accepted. Callers that treat any non-`Failure` result as
+"resumed" need no change.
+
+### Web dashboard API
+
+`POST /api/reactors/:id/continue`:
+
+- a `DispatchResult` answers `{ success: true, message: "Resume accepted" }`;
+- an "already resumed" rejection answers 422 with the error.
+
+## 2. `Reactor.undo(id)` on an `aborted` run
+
+The signature is unchanged.
+
+- If the run was interrupted during its failing step's `compensate`, that `compensate` runs again
+  first, with the recorded arguments and failure, before the completed steps are undone (FR-022 to
+  FR-025).
+- The `reason` passed to the re-run `compensate`:
+  - the original `String`, if the failure was a string;
+  - an `RubyReactor::Error::RecordedFailure` (`StandardError`) otherwise, whose `message` is the
+    original message and whose `original_class` is the original class name.
+- A failing re-run is reported as any compensation failure is: a `:compensate` trace entry, a
+  `:failed_compensation` middleware event, and a rollback failure. The undo stack is still replayed.
+  The run still ends `cancelled` ("Undo triggered"), as manual undo does today.
+
+Dashboard API (`GET /api/reactors/:id`): an `aborted` run whose `compensate` did not finish adds
+`"pending_compensation": { "step": "<name>" }`. The GUI shows it on the run's detail view.
+
+## 3. `map ... undo_all`
+
+```ruby
+map :refunds do
+  source input(:payments)
+  argument :payment, element(:refunds)
+  step :charge, ChargeStep
+  returns :charge
+  fan_out batch_size: 100
+
+  # Called once per rollback of this map, with the completed elements' results
+  # (a lazy Enumerable, in index order), INSTEAD of each element's own undos.
+  undo_all do |completed_results|
+    Payments.bulk_refund(completed_results.map { |charge| charge[:id] })
+  end
+end
+```
+
+| Rule | Behavior |
+| --- | --- |
+| Declaration | optional; at most once per map; needs a block. Otherwise `Error::ValidationError` at class definition |
+| When it is called | every rollback of the map: an atomic map's failure, a later step's failure, a manual undo |
+| Argument | a lazy `Enumerable` of the results of the elements that completed, in index order; never every element's state at once |
+| Not included | failed elements (they roll themselves back), halted, skipped |
+| Not called | no element completed |
+| Inline map with an `aborted` element (an interrupted run) | that element replays its own undos first; it is not passed |
+| Return | `RubyReactor::Failure` or a raise is a failure; anything else is success |
+| Failure | one rollback failure `{ step: <map>, kind: :undo_all, reason:, message: }`; the steps before the map are still undone |
+| Fan-out | no element rollback jobs, no rollback records |
+| Repetition | once per map rollback; at least once if the executing process dies mid-call |
+
+## 4. Synchronous `Reactor.run`
+
+The signature and results are unchanged. The run holds its liveness lock (`async:<id>`) while it
+executes in the caller's process (R-01). Observable effects:
+
+- `RubyReactor::Sweeper` / `RubyReactor.sweep_once` no longer re-enqueue it while it executes.
+- `Reactor.undo(id)` of that run waits up to 5s, then raises `Lock::AcquisitionError`, as for a run
+  executing in a worker today.
+
+## 5. Worker behavior (background jobs)
+
+| Change | Observable effect |
+| --- | --- |
+| It takes the run's liveness lock before it reads the run (waits up to 2s) | a Worker enqueued by a caller still finishing its hand-off starts within about 2s instead of racing it |
+| It returns on terminal statuses, and on a `paused` run without claimed payloads | stray or duplicate Workers do nothing |
+| Admitted runs are not limited by `lock_snooze_max_attempts` | a resumed run waiting on a reactor lock or semaphore is never marked `failed` without rollback; it logs `ruby_reactor.resume.waiting` once at the limit |
+
+## 6. Structured logs (key=value)
+
+| Event | Level | Fields |
+| --- | --- | --- |
+| `ruby_reactor.resume.deferred` | info | `reactor`, `context_id`, `step`, `reason` (`lock`, `semaphore`, `run_busy`, `background`), `key` |
+| `ruby_reactor.resume.waiting` | warn | `reactor`, `context_id`, `error` (names the contended key), `snooze_count` |
+| `ruby_reactor.map.rollback.undo_all.started` | info | `reactor`, `context_id`, `map_step`, `count` |
+| `ruby_reactor.map.rollback.undo_all.completed` | info | `reactor`, `context_id`, `map_step`, `count`, `failed` |
+
+## 7. RSpec surface (`lib/ruby_reactor/rspec/`)
+
+| Addition | Contract |
+| --- | --- |
+| `TestSubject#resume(payload:, step:, process_jobs: nil)` | Accepts a `paused` **or `running`** run with a ready interrupt, mirroring `continue`. `process_jobs: false` leaves a hand-off pending; `nil` keeps the subject's setting. |
+| `be_resume_deferred` | Passes when the subject's last `resume` returned a `DispatchResult` and the run is `running`. |
+| `have_run_undo_all(:map_step)` / `.with_elements(n)` | Passes when the run's execution trace has an `:undo_all` entry for that map, with a count of `n`. |
+
+The existing `hold_lock`, `be_paused_at`, `have_ready_interrupts`, `have_rollback_failure` and
+`be_success` / `be_failure` are unchanged.

data/specs/010-rollback-follow-ups/contracts/resume-protocol.md

@@ -0,0 +1,132 @@
+# Contract: Run Ownership and Resume Protocol
+
+The sequences the implementation must follow and the invariants the specs pin. The records are
+defined in [data-model.md](../data-model.md). This extends the invariants I-1 to I-8 of
+`specs/009-distributed-map-undo/contracts/rollback-protocol.md`.
+
+## Invariants
+
+- **J-1: a live run holds its lock.** While a run executes anywhere (a worker, the caller's process
+  through `execute`, `continue`, or `undo`), its `async:<id>` lock is held and auto-extended.
+  Exception: inline job-testing mode, which takes no context lock (R-14). The sweeper re-enqueues
+  only `running` and `rolling_back` runs with no lock holder.
+- **J-2: lock, then load.** A Worker, `continue` and `Reactor#undo` read the run only after taking
+  its lock. A synchronous `execute` creates the run, so it has nothing older to read.
+- **J-3: save before release** (009 I-6, extended to `execute`). Every holder persists its final
+  state before its lock count reaches zero.
+- **J-4: one claim per interrupt.** At most one payload is accepted per interrupt per run (the
+  `SET NX` claim). Rejected resumes write nothing.
+- **J-5: claims are applied only by the lock owner.** A claimed payload enters the run's context
+  only in the execution holding `async:<id>`, at the start of `resume_execution`. `continue` never
+  writes the context without the lock.
+- **J-6: an accepted resume is not stranded.** After a successful claim, either the claiming
+  `continue` owns the run and resumes it, or a Worker for the run is enqueued. A Worker that finds
+  the run `paused` with an unapplied claim resumes it.
+- **J-7: validated once.** A claimed payload is never validated again (FR-011).
+- **J-8: no escalation after admission.** An admitted run is never marked `failed` by snooze
+  escalation (R-07).
+- **J-9: no `compensate` is lost.** An `aborted` run whose failing step's `compensate` had not
+  returned keeps a record of it. Manual undo runs it before the undo stack, at each level where it
+  was recorded.
+
+## P-1: Synchronous run with a fan-out hand-off (US1, US2)
+
+```text
+caller process                                   element jobs / collector       Worker(run)
+──────────────                                   ────────────────────────       ───────────
+Reactor.run → Executor#execute
+  take async:<id> (wait 0, auto-extend)          ◀── sweeper sees it held: skip
+  steps…; MapStep#run dispatches, returns DispatchResult
+                                                  elements run; all settled →
+                                                  enqueue Worker(run) ─────────▶ take async:<id> (wait ≤ 2s)
+  ensure: save final state (J-3)                                                    …blocked…
+          release async:<id> ──────────────────────────────────────────────────▶ acquired
+  return DispatchResult                                                          load (sees caller's final save, J-2)
+                                                                                 resume_execution (re-entrant) → adopt map → …
+                                                                                 save; release
+```
+
+If the caller takes more than 2s to release, the Worker snoozes as a `ContextLockContention`
+(uncapped) and retries. It has loaded and written nothing.
+
+## P-2: Resume while the reactor's lock is held (US3)
+
+```text
+webhook → Reactor.continue(id, payload, :approve)
+  find (snapshot) → status paused ✓, :approve ready ✓
+  validate payload ✓ (in this process)
+  SET NX resume:approve ✓
+  take async:<id> ✓ → reload → Executor(owner).resume_execution
+      apply claims → status running → with_lock contended → ensure: save → raise Lock::AcquisitionError
+  rescue: release async:<id> → enqueue Worker(run) → log resume.deferred(reason=lock)
+  return DispatchResult
+Worker(run): lock, then load → running → resume_execution → apply claims (none left) → with_lock
+  contended → snooze (uncapped: admitted) … lock freed → acquire → steps run → final save
+```
+
+## P-3: Two resumes of the same interrupt (US4)
+
+```text
+caller A                       caller B
+find: paused                   find: paused
+validate ✓                     validate ✓
+SET NX resume:approve ✓        SET NX resume:approve ✗ → raise "already resumed" (nothing written)
+take lock, reload, resume …
+```
+
+The same holds in inline job-testing mode: the claim does not depend on the context lock.
+
+## P-4: Resuming a second interrupt while the first executes (US5)
+
+```text
+caller A (approve_a)                              caller B (approve_b)                  Worker(run)
+SET NX resume:approve_a ✓; take async:<id> ✓
+reload; resume_execution: apply claim a
+  running; steps after a…                         find: running; approve_b ready ✓
+                                                  validate ✓; SET NX resume:approve_b ✓
+                                                  take async:<id> ✗ (held by A)
+                                                  enqueue Worker(run); log deferred(run_busy)
+                                                  return DispatchResult
+  reaches approve_b (no result) → pauses
+  save paused; release ───────────────────────────────────────────────────────────▶ take lock; load: paused
+                                                                                    claim b unapplied → resume_execution
+                                                                                    apply claim b → steps → completed
+```
+
+- If A's run reaches its end before B's claim, it pauses at `approve_b`, and the Worker resumes it.
+- If A's run fails and rolls back first, the Worker loads a `failed` run and returns. Claim b is
+  never applied (FR-021).
+
+## P-5: Manual undo of an aborted run (US6)
+
+```text
+caller process: Step X fails → handle_step_failure records @pending{step X, args, error}
+  compensate(X) … SIGTERM → rescue Exception → mark_aborted:
+     status aborted; rollback = {trigger: failure, step: X, compensated: false, arguments, error}
+  ensure: save; release async:<id>
+operator: Reactor.undo(id)
+  take async:<id> (wait 5s) → reload (J-2)
+  rollback merged {trigger: undo, step: X, compensated: false, arguments, error}
+  Executor#undo_all → compensate_pending!: compensate(X, recorded error, recorded args)
+                     → compensated: true
+                     → rollback_completed_steps (newest first)
+  status cancelled ("Undo triggered"); save; release
+```
+
+A composed child or inline map element that was cut off records the same, on its own context. Its
+level's `undo_all` (called through `ComposeStep#undo` or `Map::ElementRollback`) runs it before
+that level's undo stack.
+
+## P-6: Map rollback through `undo_all` (US7)
+
+```text
+executor rollback reaches the map's undo entry (or compensates a failed atomic map)
+  MapStep#compensate → undo_all_block declared → bulk_rollback
+    fan-out: report indexes with no result slot; enum = result slots (Success values, index order)
+    inline:  pass 1 → aborted elements → Map::ElementRollback (per-element replay)
+             enum = completed element contexts, one at a time, index order
+    count == 0 → skip the call
+    log undo_all.started → block.call(enum) → trace :undo_all → log undo_all.completed
+    failure → rollback failure {step: map, kind: :undo_all}
+  return Success / Failure(rollback_failures) → the executor pops the entry → steps before the map
+```

data/specs/010-rollback-follow-ups/data-model.md

@@ -0,0 +1,139 @@
+# Data Model: Rollback and Resume Follow-ups
+
+**Feature**: [spec.md](spec.md) | **Research**: [research.md](research.md)
+
+All records live in Redis through `Storage::RedisAdapter`. `<Class>` is the reactor's storage name
+(`RubyReactor.reactor_storage_name`), and `<id>` is the run's context id.
+
+## 1. Run liveness lock (changed holders)
+
+`lock:async:<id>` is the existing re-entrant lock: Lua owner/count hash, TTL `context_lock_ttl`,
+auto-extended by its holder.
+
+| Holder | Since | Wait | Taken | Released |
+| --- | --- | --- | --- | --- |
+| `Executor#resume_execution`, `#resume_rollback` | 004/009 | 0 | after the reactor-level gates' rate-limit check | after the final save (009 R-13) |
+| `Reactor#undo` | 009 R-12 | 5s | before undoing; **now also before reloading** (R-09) | after the save |
+| **`Executor#execute`** (root, caller process) | **010 R-01** | 0 | after input validation, before the reactor-level lock and semaphore | **after the final save** |
+| **`Worker#perform`** | **010 R-02** | 2s, polling | **before the context is read** | in `ensure`, after the executor released its re-entry |
+| **`Reactor#continue`** | **010 R-05** | 0 | after the claim, **before the reload** | after the resume returns, or before the hand-off enqueue |
+
+- **Re-entry**: the Worker and `continue` pass their owner to the executor
+  (`Executor#context_lock_owner=`). The executor's acquire then raises the count instead of
+  contending.
+- **Inline job-testing mode**: no holder takes it (unchanged).
+- **Reader**: `Sweeper#run_once`, which is unchanged. It now sees caller-process runs as live.
+
+## 2. Interrupt resume claim (new)
+
+| Field | Value |
+| --- | --- |
+| Key | `reactor:<Class>:context:<id>:resume:<step>` |
+| Value | `ContextSerializer.serialize_value(payload)`, as JSON |
+| Created | `SET NX EX context_ttl`, by `Reactor#continue` after the payload has validated |
+| Read | `MGET` over the reactor's interrupt steps that have no result yet: `Executor#resume_execution` right after the context lock, and `Worker#perform` for a `paused` run |
+| Deleted | never; it expires with TTL |
+
+**Lifecycle** of one interrupt:
+
+```text
+absent ──continue (valid payload, SET NX wins)──▶ claimed ──lock owner applies──▶ applied
+  │                                                  │                              │
+  │                     second continue: SET NX loses ─▶ "already resumed"          │
+  └──────────────── continue after apply: the result exists ─▶ "already resumed" ◀──┘
+```
+
+- **Applied** means `context.set_result(step, payload)` by the execution that owns the lock,
+  persisted by that execution's next save.
+- An applied claim stays as the dedupe marker until it expires. After that, the step's result in
+  `intermediate_results` rejects duplicates.
+
+**Validation rules**:
+
+- A claim is written only for an interrupt step that is ready, has no result and has passed payload
+  validation (FR-008, FR-017, FR-020).
+- The run must be `paused` or `running`, and not `cancelled`.
+
+## 3. Interrupt attempt counter (moved)
+
+| Field | Value |
+| --- | --- |
+| Key | `reactor:<Class>:context:<id>:resume_attempts:<step>` |
+| Value | an integer, raised by `INCR` once per invalid payload, with `EXPIRE context_ttl` |
+| Replaces | `context.private_data[:interrupt_attempts][step]`, no longer written |
+
+At `step_config.max_attempts`, the run fails through `Reactor#undo(failure:)` (R-08, R-09). The
+`failure_reason` is unchanged: `message`, `step_name`, `errors`, `payload`, `step_arguments`,
+`attempts`, `validation_errors`.
+
+## 4. `context.rollback` on an aborted run (extended)
+
+There is no new context attribute. 009 added `rollback`, and 010 adds keys for the aborted case
+(R-10).
+
+| Key | Type | Meaning |
+| --- | --- | --- |
+| `trigger` | `"failure"` | a step failure was rolling back when the process was interrupted |
+| `step` | String | the failing step's name, at this context's level |
+| `compensated` | Boolean | whether that step's `compensate` returned. `false` makes manual undo re-run it |
+| `arguments` | serialized Hash | the step's `rollback_arguments`. **Its presence marks the aborted record**; 009 hand-off records do not carry it |
+| `error` | `{ "class", "message" }`, or a String | the failure that `compensate` receives again |
+| `failures` | serialized Array | rollback failures collected before the interruption (009) |
+
+**State transitions** (top level; a composed child or inline element behaves the same at its own
+level):
+
+```text
+running ──step fails──▶ (compensate running) ──interrupted──▶ aborted + rollback{compensated:false}
+                                                                 │
+                       Reactor.undo: lock, reload, merge record, undo_all
+                                                                 ▼
+           compensate re-run (once) ─▶ compensated:true ─▶ undo stack replayed ─▶ cancelled
+running ──step fails──▶ compensate returns ──interrupted during undo stack──▶ aborted (no record;
+                                                         manual undo replays the remaining stack only)
+```
+
+`Web::API` derives `pending_compensation: { step: }` from this record when the status is `aborted`
+and `compensated` is false (R-11).
+
+## 5. Map step declaration: `undo_all` (new)
+
+| Field | Where | Value |
+| --- | --- | --- |
+| `undo_all_block` | map `StepConfig#arguments`, source `Template::Value` | the block given to `undo_all`; absent when not declared |
+
+**Validation rules** (`MapBuilder`, at class definition): a block is required, and the method may be
+declared once per map. Either violation raises `Error::ValidationError` naming the map (FR-027).
+
+### Bulk undo inputs and outcome
+
+| Item | Fan-out map | Inline map |
+| --- | --- | --- |
+| Completed results | forward result slots, in index order, `Success` values only (`Map::ResultEnumerator`) | element contexts with status `completed`, in index order, one deserialized at a time |
+| Replayed per element instead | none (no element is `aborted`) | elements with status `aborted` (pass 1, `Map::ElementRollback`) |
+| Reported unavailable | indexes with no result slot | element contexts that expired, as in 009 |
+| Rollback records or jobs | none | none |
+
+Outcome entries:
+
+- **Execution trace**: `{ type: :undo_all, step: <map step>, count: <completed>, result: <value or error>, timestamp: }`.
+- **Rollback failure**, on a raise or a returned `Failure`:
+  `{ step: <map step>, kind: :undo_all, reason: :raised | :returned_failure, message: }`. It is
+  aggregated into the run's final failure like any rollback failure.
+
+## 6. Worker decision by status (R-06)
+
+| Stored status | Action |
+| --- | --- |
+| `completed`, `failed`, `cancelled`, `skipped`, `aborted`, `halted` | return (release the lock) |
+| `paused` | resume if any interrupt without a result has a claim; otherwise return |
+| `rolling_back` | `resume_rollback` |
+| `running` | `resume_execution` (applies claims first) |
+
+## 7. Snooze limit (R-07)
+
+| Condition | Limited by `lock_snooze_max_attempts`? |
+| --- | --- |
+| Reactor-level lock, semaphore or rate limit before admission (`!context.admitted?`) | yes (unchanged): escalate to `failed` |
+| Reactor-level lock or semaphore once admitted | **no**: one `ruby_reactor.resume.waiting` warning at the limit, then keep snoozing |
+| `ContextLockContention`, `OrderedLock::WaitError`, `ExecutionParked` | no (unchanged) |