RubyGems - ruby_reactor - Versions diffs - 0.8.2 → 0.8.3 - Mend

ruby_reactor 0.8.2 → 0.8.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (77) hide show

checksums.yaml +4 -4
data/.claude/skills/speckit-review/SKILL.md +324 -0
data/.release-please-manifest.json +1 -1
data/.specify/extensions.yml +10 -0
data/.specify/feature.json +1 -1
data/.specify/workflows/speckit/workflow.yml +13 -1
data/.specify/workflows/workflow-registry.json +2 -2
data/CHANGELOG.md +82 -0
data/CLAUDE.md +2 -2
data/README.md +35 -2
data/lib/ruby_reactor/adapters/active_job/router.rb +19 -0
data/lib/ruby_reactor/adapters/sidekiq/router.rb +21 -0
data/lib/ruby_reactor/context.rb +26 -0
data/lib/ruby_reactor/context_serializer.rb +4 -2
data/lib/ruby_reactor/dsl/interrupt_builder.rb +14 -0
data/lib/ruby_reactor/dsl/lockable.rb +76 -21
data/lib/ruby_reactor/dsl/step_builder.rb +112 -1
data/lib/ruby_reactor/error/async_result_pending.rb +1 -1
data/lib/ruby_reactor/error/execution_parked.rb +16 -0
data/lib/ruby_reactor/error/reactor_contention_park.rb +26 -0
data/lib/ruby_reactor/error/step_contention_park.rb +26 -0
data/lib/ruby_reactor/executor/async_step_dispatch.rb +109 -3
data/lib/ruby_reactor/executor/compensation_manager.rb +99 -17
data/lib/ruby_reactor/executor/ordered_lock_support.rb +76 -44
data/lib/ruby_reactor/executor/result_handler.rb +31 -11
data/lib/ruby_reactor/executor/retry_manager.rb +9 -1
data/lib/ruby_reactor/executor/step_coordination.rb +788 -0
data/lib/ruby_reactor/executor/step_executor.rb +115 -11
data/lib/ruby_reactor/executor.rb +90 -20
data/lib/ruby_reactor/map/element_executor.rb +24 -2
data/lib/ruby_reactor/map/helpers.rb +35 -11
data/lib/ruby_reactor/max_retries_exhausted_failure.rb +2 -2
data/lib/ruby_reactor/open_telemetry.rb +61 -24
data/lib/ruby_reactor/retry_context.rb +31 -2
data/lib/ruby_reactor/rspec/helpers.rb +15 -0
data/lib/ruby_reactor/rspec/matchers.rb +92 -0
data/lib/ruby_reactor/rspec/test_subject.rb +7 -1
data/lib/ruby_reactor/step/async_reactor_step.rb +40 -24
data/lib/ruby_reactor/step/compose_step.rb +14 -3
data/lib/ruby_reactor/step.rb +49 -7
data/lib/ruby_reactor/step_sweeper.rb +29 -1
data/lib/ruby_reactor/step_worker.rb +260 -37
data/lib/ruby_reactor/version.rb +1 -1
data/lib/ruby_reactor/web/api.rb +72 -7
data/lib/ruby_reactor/web/coordination_serializer.rb +120 -2
data/lib/ruby_reactor/web/public/assets/{index-Dw4KV4QY.js → index-CeZU-ESu.js} +9 -9
data/lib/ruby_reactor/web/public/index.html +1 -1
data/lib/ruby_reactor/worker.rb +56 -30
data/lib/ruby_reactor.rb +27 -5
data/specs/future_improvements.md +250 -0
metadata +8 -28
data/specs/002-step-input-contracts/checklists/requirements.md +0 -49
data/specs/002-step-input-contracts/contracts/dsl-surface.md +0 -193
data/specs/002-step-input-contracts/data-model.md +0 -115
data/specs/002-step-input-contracts/plan.md +0 -165
data/specs/002-step-input-contracts/quickstart.md +0 -170
data/specs/002-step-input-contracts/research.md +0 -233
data/specs/002-step-input-contracts/spec.md +0 -359
data/specs/002-step-input-contracts/tasks.md +0 -367
data/specs/004-inheritable-step-class/checklists/requirements.md +0 -40
data/specs/004-inheritable-step-class/contracts/step-lifecycle.md +0 -85
data/specs/004-inheritable-step-class/data-model.md +0 -116
data/specs/004-inheritable-step-class/plan.md +0 -174
data/specs/004-inheritable-step-class/quickstart.md +0 -112
data/specs/004-inheritable-step-class/research.md +0 -308
data/specs/004-inheritable-step-class/spec.md +0 -316
data/specs/004-inheritable-step-class/tasks.md +0 -258
data/specs/active_job.md +0 -259
data/specs/deferred-003-step-lock-declarations/checklists/requirements.md +0 -51
data/specs/deferred-003-step-lock-declarations/contracts/dsl-surface.md +0 -154
data/specs/deferred-003-step-lock-declarations/data-model.md +0 -131
data/specs/deferred-003-step-lock-declarations/plan.md +0 -166
data/specs/deferred-003-step-lock-declarations/quickstart.md +0 -169
data/specs/deferred-003-step-lock-declarations/research.md +0 -196
data/specs/deferred-003-step-lock-declarations/spec.md +0 -447
data/specs/deferred-003-step-lock-declarations/tasks.md +0 -572
data/specs/possible_feature.md +0 -22

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

@@ -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-Dw4KV4QY.js"></script>
+    <script type="module" crossorigin src="./assets/index-CeZU-ESu.js"></script>
     <link rel="stylesheet" crossorigin href="./assets/index-BQvIWPdx.css">
   </head>
   <body>

data/lib/ruby_reactor/worker.rb CHANGED Viewed

@@ -10,6 +10,46 @@ module RubyReactor
   module Worker
     TERMINAL_STATUSES = %w[completed failed cancelled skipped].freeze
+    # Use the error's `retry_after_seconds` hint when available
+    # (RateLimit::ExceededError carries the time until the bucket rolls);
+    # otherwise fall back to the configured base + jitter for lock/semaphore
+    # contention which has no precise hint. Module-level (not just an
+    # instance method) so `StepCoordination::Contended` — which wraps a
+    # contention error but is not itself a snooze-worthy reactor-level
+    # error — can reuse the identical hint logic from the async_step worker
+    # (T036) without including this whole module.
+    #
+    # OrderedLock::WaitError is deliberately excluded from the hint path: its
+    # `retry_after_seconds` is the poison-pill window (the upper bound before
+    # a *dead* blocker is force-advanced), NOT how long the *live* blocker
+    # will take — which is usually milliseconds. Snoozing for the full window
+    # would make every out-of-order nonce sleep up to poison_pill_timeout even
+    # though its blocker finishes immediately, collapsing throughput. Re-poll
+    # at the base delay instead; poison auto-advance still clears a genuinely
+    # dead blocker on a later gate.
+    def self.snooze_delay(config, error)
+      jitter = config.lock_snooze_jitter.to_f
+      jitter_amount = jitter.positive? ? rand(0.0..jitter) : 0.0
+      if hinted_retry?(error)
+        [error.retry_after_seconds.to_f, 0.1].max + jitter_amount
+      else
+        config.lock_snooze_base_delay.to_f + jitter_amount
+      end
+    end
+    def self.hinted_retry?(error)
+      # `StepCoordination::Contended` wraps the WaitError as `.original` —
+      # unwrap so the same exclusion applies whether the caller is the
+      # reactor-level ordered lock (raises WaitError directly) or a step's
+      # (raises Contended, whose OWN `retry_after_seconds` just forwards the
+      # wrapped error's hint unchanged).
+      original = error.respond_to?(:original) ? error.original : error
+      return false if original.is_a?(RubyReactor::OrderedLock::WaitError)
+      error.respond_to?(:retry_after_seconds) && error.retry_after_seconds
+    end
     # Last line of observability when a job burns its whole retry budget on an
     # infrastructure failure and the backend then discards it (Sidekiq runs
     # with `dead: false`): without this, the context would stay "running"
@@ -93,8 +133,11 @@ module RubyReactor
              RubyReactor::Semaphore::AcquisitionError,
              RubyReactor::RateLimit::ExceededError,
              RubyReactor::OrderedLock::WaitError,
-             RubyReactor::Error::AsyncResultPending => e
-        # Snooze on expected concurrency, rate, or ordering contention.
+             RubyReactor::Error::ExecutionParked => e
+        # Snooze on expected concurrency, rate, or ordering contention, or on
+        # a park signal (a step's contention, or an awaited background result)
+        # — raised at any nesting depth, after every executor on the stack has
+        # parked its own holds and saved.
         # OrderedLock::WaitError carries a poison-pill-derived retry hint,
         # consumed by compute_snooze_delay below. We avoid the framework's native
         # retry path so this doesn't burn the job's retry budget or appear
@@ -147,12 +190,14 @@ module RubyReactor
       # duplicate of the *same* execution may wait arbitrarily long for the
       # live original to finish (e.g. a sweeper re-enqueue racing a slow but
       # alive worker). Capping it would fail a legitimately-waiting duplicate.
-      # A parked async wait is likewise uncapped HERE: its bound is
-      # `async_park_timeout`, enforced against `dispatched_at` at the wait
-      # site — counting snoozes would double-bound it with the wrong unit.
+      # A park signal is likewise uncapped HERE, bounded where it is raised:
+      # an async wait by `async_park_timeout` against `dispatched_at`, a
+      # step's contention by `lock_snooze_max_attempts` on that step's own
+      # contention counter (`StepExecutor#handle_contention`) — counting
+      # snoozes too would double-bound either with the wrong unit.
       capped = !(error.is_a?(RubyReactor::OrderedLock::WaitError) ||
                  error.is_a?(RubyReactor::Lock::ContextLockContention) ||
-                 error.is_a?(RubyReactor::Error::AsyncResultPending))
+                 error.is_a?(RubyReactor::Error::ExecutionParked))
       if capped && max != :infinity && snooze_count >= max
         escalate_snooze(context, snooze_count, error)
@@ -165,34 +210,15 @@ module RubyReactor
       self.class.perform_in(delay, context_id, reactor_class_name, snooze_count + 1)
     end
-    # Use the error's `retry_after_seconds` hint when available
-    # (RateLimit::ExceededError carries the time until the bucket rolls);
-    # otherwise fall back to the configured base + jitter for lock/semaphore
-    # contention which has no precise hint.
-    #
-    # OrderedLock::WaitError is deliberately excluded from the hint path: its
-    # `retry_after_seconds` is the poison-pill window (the upper bound before
-    # a *dead* blocker is force-advanced), NOT how long the *live* blocker
-    # will take — which is usually milliseconds. Snoozing for the full window
-    # would make every out-of-order nonce sleep up to poison_pill_timeout even
-    # though its blocker finishes immediately, collapsing throughput. Re-poll
-    # at the base delay instead; poison auto-advance still clears a genuinely
-    # dead blocker on a later gate.
+    # 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.
     def compute_snooze_delay(config, error)
-      jitter = config.lock_snooze_jitter.to_f
-      jitter_amount = jitter.positive? ? rand(0.0..jitter) : 0.0
-      if hinted_retry?(error)
-        [error.retry_after_seconds.to_f, 0.1].max + jitter_amount
-      else
-        config.lock_snooze_base_delay.to_f + jitter_amount
-      end
+      Worker.snooze_delay(config, error)
     end
     def hinted_retry?(error)
-      return false if error.is_a?(RubyReactor::OrderedLock::WaitError)
-      error.respond_to?(:retry_after_seconds) && error.retry_after_seconds
+      Worker.hinted_retry?(error)
     end
     def escalate_snooze(context, snooze_count, error)

data/lib/ruby_reactor.rb CHANGED Viewed

@@ -133,14 +133,14 @@ module RubyReactor
   class Failure
     attr_reader :error, :retryable, :step_name, :inputs, :backtrace, :reactor_name, :step_arguments, :exception_class,
-                :file_path, :line_number, :code_snippet, :validation_errors
+                :file_path, :line_number, :code_snippet, :validation_errors, :rollback_failures
-    # rubocop:disable Metrics/ParameterLists, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+    # rubocop:disable Metrics/ParameterLists, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity, Metrics/MethodLength
     def initialize(error, retryable: nil, step_name: nil, inputs: {}, backtrace: nil, redact_inputs: [],
                    reactor_name: nil, step_arguments: {}, exception_class: nil,
                    file_path: nil, line_number: nil, code_snippet: nil, invalid_payload: false, validation_errors: nil,
-                   **opts)
-      # rubocop:enable Metrics/ParameterLists, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+                   rollback_failures: nil, **opts)
+      # rubocop:enable Metrics/ParameterLists, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity, Metrics/MethodLength
       retryable = opts[:retry] if opts.key?(:retry) # `retry:` wins over `retryable:` when both are given
       @error = error
@@ -159,6 +159,7 @@ module RubyReactor
         line_number ||= attributes[:line_number]
         code_snippet ||= attributes[:code_snippet]
         validation_errors ||= attributes[:validation_errors]
+        rollback_failures ||= attributes[:rollback_failures]
       end
       @retryable = if retryable.nil?
@@ -179,6 +180,9 @@ module RubyReactor
       @code_snippet = code_snippet
       @invalid_payload = invalid_payload
       @validation_errors = validation_errors
+      # Every undo/compensation that did not complete during this failure's
+      # rollback (005 FR-004): `{ step:, kind:, key:, reason:, message: }`.
+      @rollback_failures = normalize_rollback_failures(rollback_failures)
     end
     def success?
@@ -236,6 +240,7 @@ module RubyReactor
         line_number: @line_number,
         code_snippet: @code_snippet,
         validation_errors: @validation_errors,
+        rollback_failures: @rollback_failures,
         backtrace: @backtrace
       }
     end
@@ -334,9 +339,26 @@ module RubyReactor
         file_path: err[:file_path],
         line_number: err[:line_number],
         code_snippet: err[:code_snippet],
-        validation_errors: err[:validation_errors]
+        validation_errors: err[:validation_errors],
+        rollback_failures: err[:rollback_failures]
       }
     end
+    ROLLBACK_FAILURE_SYMBOLS = %i[step kind reason].freeze
+    private_constant :ROLLBACK_FAILURE_SYMBOLS
+    # A stored failure comes back with string keys (and, through plain JSON,
+    # string values); `step`, `kind` and `reason` are Symbols on a live one.
+    def normalize_rollback_failures(entries)
+      return [] unless entries.is_a?(Array)
+      entries.map do |entry|
+        entry.to_h do |k, v|
+          key = k.to_sym
+          [key, ROLLBACK_FAILURE_SYMBOLS.include?(key) && v ? v.to_sym : v]
+        end
+      end
+    end
   end
   # Sentinel returned when a step's work is handed off to a worker job and is

data/specs/future_improvements.md ADDED Viewed

@@ -0,0 +1,250 @@
+# Future improvements for review
+## Guard
+I want to add another hook feature to the step: `guard`
+A guard concept is to execute after validations and before run.
+example:
+```ruby
+class SendEmail < RubyReactor::Step
+  input :email, :string, format?: /\A[^@\s]+@[^@\s]+\z/
+  def guard
+    fail!("Prevent spamming") if EmailService.sent_today?(inputs[:email])
+    success! # optional
+  end
+  def run
+    # do the work
+  end
+end
+```
+## Fenced context writes
+**Status:** proposal, not scheduled. Follows from 005 (step coordination remediation), R-18 and
+R-19 in `specs/005-step-coordination-remediation/research.md`.
+### The rule
+A context is written by one process only: the controlled execution that owns it.
+- Async children (`async_step`, `async_reactor`, map elements) never write their parent. The
+  parent holds only the link written at dispatch; each child keeps its own record, and the
+  dashboard rebuilds its view from the links. 005 made this true for `async_step` (R-18).
+- Today the rule is a convention: any code with a storage adapter can `SET` any context. This
+  proposal makes it a guarantee that the storage enforces.
+### Why a convention is not enough
+Holding the lock at some point is not the same as owning the data when the write lands:
+| Failure | What happens today |
+|---|---|
+| **Paused holder**: a worker holding the `async:<root id>` lock stalls (GC, network, a long rollback wait) past `context_lock_ttl`. The lock expires, a redelivery takes it and makes progress, then the first worker wakes. | The first worker's next `store_context` is a plain `SET`. It overwrites the newer state. Its auto-extender fails silently. Nothing stops the write. |
+| **Stale read**: `Worker#perform` loads the context *before* `resume_execution` takes the context lock. | A previous holder can write between that read and the lock. The new holder then runs on the older snapshot and saves over the newer one. |
+| **Writer outside any execution**: a path writes with no lock at all. | It overwrites whatever the live execution saved. 005 fixed two of these (`StepWorker#save_root`, the map collector's post-resume save); others remain (below). |
+The first two are the textbook reasons distributed locks need fencing. A lock that only *excludes*
+is not enough. The storage must also *reject writes from anyone who no longer holds the lock*.
+### Remaining writers outside a controlled execution
+Found while auditing for 005 R-19:
+| Writer | Where | Today |
+|---|---|---|
+| `Worker.record_retries_exhausted` | backend's retries-exhausted hook | Plain read-modify-write, no lock. Marks the context failed even if a redelivery is live. |
+| `Worker#escalate_snooze` | after the executor returned | Runs after the executor released the context lock. |
+| `Worker#handle_deserialization_failure` | before any executor | Writes a failed payload with no lock. |
+| Map collector, failure branch | `Map::Helpers#resume_parent_execution` | Holds `map_collect:<map_id>`, never the parent's `async:` lock. |
+| `Reactor.cancel`, `Reactor.undo` | any process (app code, console) | `find` → mutate → `save_context`: a blind write racing a live worker. |
+| `Reactor#continue` (interrupt resume) | web request / app code | Writes the payload before `resume_execution` takes the lock. |
+| Synchronous `Reactor.run` / `Executor#execute` | caller's process | Never takes the context lock, so its saves are unfenced. |
+Writers that already belong to the owning execution:
+- `Executor#save_context` and `#checkpoint!` on the worker path;
+- `RetryManager#requeue_job`;
+- `StepExecutor#checkpoint_root!`;
+- `MapStep#prepare_async_execution`.
+Two writers only *create* a row that nothing has read yet:
+- `Reactor#save_context` at enqueue;
+- `AsyncReactorStep#save`, the child's first row.
+### Proposal
+Four parts. Parts 1 and 2 are the mechanism; parts 3 and 4 route the remaining writers through it.
+#### 1. Ownership-checked, versioned writes (the fence)
+- Every context row gets a version: a small key next to the blob,
+  `reactor:<Class>:context:<id>:v`, with the same TTL as the blob.
+- Every write goes through one Lua script. The script takes:
+  - the lock key it claims to hold (`lock:async:<root id>`, or the map element's
+    `lock:map_element:<map>:<index>`);
+  - the owner token of that lock: the per-execution UUID `Executor#acquire_context_lock`
+    already generates;
+  - the version the writer loaded.
+- The script writes only if **the lock is held by that token** *and* **the stored version equals
+  the loaded one**. It then bumps the version.
+- It returns `ok`, `lost_lock` or `stale`:
+```lua
+-- KEYS: context_key, version_key, lock_key   ARGV: blob, ttl, owner, expected_version
+if redis.call('hget', KEYS[3], 'owner') ~= ARGV[3] then return 'lost_lock' end
+local current = tonumber(redis.call('get', KEYS[2]) or '0')
+if current ~= tonumber(ARGV[4]) then return 'stale' end
+redis.call('set', KEYS[1], ARGV[1], 'EX', ARGV[2])
+redis.call('set', KEYS[2], current + 1, 'EX', ARGV[2])
+return 'ok'
+```
+Why both checks:
+- The **owner check** stops a paused holder from writing at all, even before anyone else has
+  written.
+- The **version check** catches a stale read by the current holder, and any path this proposal
+  missed.
+The lock and the data live in the same Redis, and the check runs atomically inside it, so the
+owner comparison does the job of a fencing token. There are no clock or ordering assumptions.
+If locks and contexts ever move to different stores, switch to classic monotonic fencing tokens
+(`INCR` on acquire, highest-token-wins at the store).
+**Creating a row** uses the same script with `expected_version = 0` and no lock check: a
+create-only `SET NX` equivalent. It covers `Reactor#save_context` at enqueue and an
+`async_reactor` child's first row.
+#### 2. Lock, then load
+- A worker takes the context lock **before** it reads the context. The restructure:
+  `Worker#perform` acquires `async:<root id>`, then retrieves and deserializes, then hands
+  the token and the loaded version to `Executor`. Today `resume_execution` acquires the lock
+  mid-way.
+- A synchronous `Reactor.run` takes the same lock for its whole run. It is one `SET NX` and a
+  release; today it takes none.
+- Composed children already run inside the root's lock and write through the root. They reuse
+  the root's token.
+#### 3. External actors send requests, not writes
+Operator actions must not write a live context. Make them requests the owning execution
+consumes, the same pattern as async children writing their own records:
+- **`Reactor.cancel` / `.undo`**:
+  - write a `cancel_requested` key, `reactor:<Class>:context:<id>:cancel`;
+  - the owning execution checks it at each step boundary and cancels or undoes itself, under its
+    own lock;
+  - if no execution is live (the context lock is free), `cancel` takes the lock itself and
+    applies the request directly: lock, load, fenced write.
+- **`Reactor#continue`**: take the lock first (bounded wait, because it is a user action), load,
+  store the payload, resume. If the lock is held, return "busy — retry" instead of racing.
+- **Worker bookkeeping** (`record_retries_exhausted`, `escalate_snooze`, deserialization
+  failure):
+  - take the context lock with `wait: 0`;
+  - if another process holds it, that process owns the outcome, so log and skip;
+  - move `escalate_snooze` inside the executor's lock scope instead of after it.
+- **Map collector**: take the parent's `async:` lock for both branches. The success branch passes
+  the token into `resume_execution`, which must accept an already-held lock (re-entrant by owner).
+#### 4. What a rejected write does
+A write that comes back `lost_lock` or `stale` raises `Error::ContextOwnershipLost`:
+- The executor stops at once. It saves nothing else, runs no further steps, and releases only
+  holds it still owns (every release is already owner-checked).
+- It logs one structured line: `event="ruby_reactor.context.ownership_lost"`, with the context
+  id, the lock key and the expected and actual version.
+- The worker does **not** snooze or retry the job. The current owner is responsible for the run.
+- A rejection is a correctness signal, not an error to hide. Expose it in the log and in the
+  `:failed_reactor` middleware event, but never mark the context failed: its owner decides the
+  outcome.
+### Constraints and open questions
+- **Redis Cluster**: the script touches three keys, which must share a hash slot. Tag them with
+  the root id: `lock:async:{<root>}`, `reactor:<Class>:context:{<root>}`, and the version key. The
+  ordered lock already does this. Changing the key format needs a migration or a dual-read window.
+- **Composed children's own rows**: `Executor#save_context` of a composed child also stores the
+  child under its own id. That is a second key in a different slot. Either tag it with the root
+  id too, or drop these rows. They are an observability path: the root blob already embeds the
+  child.
+- **Inline test mode**: `Sidekiq::Testing.inline!` re-enters the worker inside a frame that holds
+  the lock, which is why `acquire_context_lock` is skipped there today. The fence needs the same
+  exemption, or re-entrancy by owner token.
+- **Redis failover**: replication is asynchronous, so a failover can lose an acknowledged lock
+  or write. This proposal gives single-primary guarantees, the same as today's locks. Stronger
+  guarantees mean `WAIT`/`WAITAOF` on the lock write, or a different store. Document; don't solve
+  here.
+- **Other records**: Step Result Records and map element results have the same shape:
+  - the dispatcher creates the record;
+  - the unit's job updates it under its liveness lock;
+  - it could be fenced the same way.
+  Nothing races there today, because the liveness lock drops concurrent duplicates. Decide
+  whether to fence them now or later.
+### Rollout
+- **SemVer**: MINOR, behind `config.fenced_context_writes` (default `false`) for one release.
+  Existing contexts have no version key, which is read as `0`.
+- A rolling deploy mixes old workers (plain `SET`, no version bump) with new ones, so the new
+  workers would see spurious `stale` results. Enable the flag only after every worker runs the new
+  version. Flip the default in the next MAJOR.
+- **Cost**: one `EVAL` in place of one `SET` per save; checkpoints already save once per step.
+  One extra `SET NX` and release per synchronous run.
+### Test plan
+All against real Redis, per the constitution.
+1. **Paused holder**:
+   - take the lock with a short TTL and let it expire;
+   - a second owner takes it and writes;
+   - the first owner's write returns `lost_lock`, and the stored blob is the second owner's.
+2. **Stale read**:
+   - load at version N;
+   - another writer (holding the lock through a handover) bumps the version to N+1;
+   - the write returns `stale`.
+3. **Lock, then load**: a redelivery that races a finishing holder always runs on the holder's
+   final state. This is the same repro shape as 005 P4.
+4. **One spec per writer** in the tables above, showing it goes through the fence, or takes the
+   lock and skips when it is held.
+5. **Cancel of a live run**: the request is consumed at the next step boundary. The running
+   execution's saves are never overwritten by the canceller.
+6. **Cluster slot co-location**, if Redis Cluster is supported: every key a script touches
+   hashes to one slot.
+### Size
+- Storage adapter: one new script and a versioned `retrieve_context`.
+- Executor and `Worker`: lock, then load, and pass the token.
+- Six writer paths rerouted, plus the cancel/undo request key.
+- Docs: `locks_and_semaphores.md`, `background_and_async.md`, and the README's "Durability &
+  Recovery" section.
+## Fan-out map inside a composed child
+**Status:** bug, already present on main (0.8.1). Raised by the PR #56 review.
+A root that composes a child, where the child runs a `fan_out` map, never finishes. The root
+stays `running`.
+- `MapStep#prepare_async_execution` stores the child under its own id.
+- The map collector loads that child blob. Its `root_context` is nil, so the collector resumes
+  the child as a standalone execution. On a park, it requeues the child the same way.
+- The child completes in its own blob. Nothing resumes the root, and the root's embedded copy of
+  the child stays at the map step.
+To reproduce: `Root` composes `Child`, and `Child` runs a `map ... fan_out batch_size: 1`. Drain
+the element, collector and `Worker` jobs. The root is still `running`.
+A literal patch would have the collector write the root's blob. That breaks the single-writer
+rule, because the collector holds only `map_collect:`, never the root's `async:` lock.
+Direction:
+- The collector records the map's completion on the map's own records, which it already does.
+- The collector requeues the ROOT worker and does not resume the child itself.
+- On re-entry, `MapStep` adopts the finished map: collect the results, don't dispatch again.
+Spec: compose → fan-out map, with and without a park after the map. The root completes either
+way.

metadata CHANGED Viewed

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ruby_reactor
 version: !ruby/object:Gem::Version
-  version: 0.8.2
+  version: 0.8.3
 platform: ruby
 authors:
 - Artur
@@ -98,6 +98,7 @@ files:
 - ".claude/skills/speckit-demo-tests/SKILL.md"
 - ".claude/skills/speckit-implement/SKILL.md"
 - ".claude/skills/speckit-plan/SKILL.md"
+- ".claude/skills/speckit-review/SKILL.md"
 - ".claude/skills/speckit-specify/SKILL.md"
 - ".claude/skills/speckit-tasks/SKILL.md"
 - ".claude/skills/speckit-taskstoissues/SKILL.md"
@@ -175,8 +176,11 @@ files:
 - lib/ruby_reactor/error/dependency_error.rb
 - lib/ruby_reactor/error/deprecated_dsl_error.rb
 - lib/ruby_reactor/error/deserialization_error.rb
+- lib/ruby_reactor/error/execution_parked.rb
 - lib/ruby_reactor/error/input_validation_error.rb
+- lib/ruby_reactor/error/reactor_contention_park.rb
 - lib/ruby_reactor/error/schema_version_error.rb
+- lib/ruby_reactor/error/step_contention_park.rb
 - lib/ruby_reactor/error/step_failure_error.rb
 - lib/ruby_reactor/error/undo_error.rb
 - lib/ruby_reactor/error/validation_error.rb
@@ -188,6 +192,7 @@ files:
 - lib/ruby_reactor/executor/ordered_lock_support.rb
 - lib/ruby_reactor/executor/result_handler.rb
 - lib/ruby_reactor/executor/retry_manager.rb
+- lib/ruby_reactor/executor/step_coordination.rb
 - lib/ruby_reactor/executor/step_executor.rb
 - lib/ruby_reactor/interrupt_result.rb
 - lib/ruby_reactor/lock.rb
@@ -256,39 +261,14 @@ files:
 - lib/ruby_reactor/web/config.ru
 - lib/ruby_reactor/web/coordination_serializer.rb
 - lib/ruby_reactor/web/public/assets/index-BQvIWPdx.css
-- lib/ruby_reactor/web/public/assets/index-Dw4KV4QY.js
+- lib/ruby_reactor/web/public/assets/index-CeZU-ESu.js
 - lib/ruby_reactor/web/public/index.html
 - lib/ruby_reactor/web/public/vite.svg
 - lib/ruby_reactor/worker.rb
 - llms-full.txt
 - llms.txt
 - sig/ruby_reactor.rbs
-- specs/002-step-input-contracts/checklists/requirements.md
-- specs/002-step-input-contracts/contracts/dsl-surface.md
-- specs/002-step-input-contracts/data-model.md
-- specs/002-step-input-contracts/plan.md
-- specs/002-step-input-contracts/quickstart.md
-- specs/002-step-input-contracts/research.md
-- specs/002-step-input-contracts/spec.md
-- specs/002-step-input-contracts/tasks.md
-- specs/004-inheritable-step-class/checklists/requirements.md
-- specs/004-inheritable-step-class/contracts/step-lifecycle.md
-- specs/004-inheritable-step-class/data-model.md
-- specs/004-inheritable-step-class/plan.md
-- specs/004-inheritable-step-class/quickstart.md
-- specs/004-inheritable-step-class/research.md
-- specs/004-inheritable-step-class/spec.md
-- specs/004-inheritable-step-class/tasks.md
-- specs/active_job.md
-- specs/deferred-003-step-lock-declarations/checklists/requirements.md
-- specs/deferred-003-step-lock-declarations/contracts/dsl-surface.md
-- specs/deferred-003-step-lock-declarations/data-model.md
-- specs/deferred-003-step-lock-declarations/plan.md
-- specs/deferred-003-step-lock-declarations/quickstart.md
-- specs/deferred-003-step-lock-declarations/research.md
-- specs/deferred-003-step-lock-declarations/spec.md
-- specs/deferred-003-step-lock-declarations/tasks.md
-- specs/possible_feature.md
+- specs/future_improvements.md
 - specs/scoped_rspec_matchers.md
 - teley/Dockerfile
 homepage: https://github.com/arturictus/ruby_reactor

data/specs/002-step-input-contracts/checklists/requirements.md DELETED Viewed

@@ -1,49 +0,0 @@
-# Specification Quality Checklist: Step Input Contracts
-**Purpose**: Validate specification completeness and quality before proceeding to planning
-**Created**: 2026-09-10
-**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
-- All items pass. 0 [NEEDS CLARIFICATION] markers remain.
-- Resolved with the user on 2026-09-10:
-  - **Naming**: a unit of work declares `input`; the reactor keeps `argument` for wiring only
-    (FR-012).
-  - **Undeclared arguments**: reactor-load error for contract-owning steps (FR-018); steps
-    with no contract and no wiring keep today's pass-all-inputs behavior (FR-019).
-  - **Implicit wiring**: an unwired step input resolves from a same-named reactor input only,
-    checked at reactor-load time; never from another step's result (FR-020, FR-021).
-  - **Direct invocation**: the contract is enforced on every entry point, not only via a
-    reactor (FR-022).
-  - **Falsey values**: presence means "a value was supplied", never "the value is truthy";
-    the pre-existing loss of `false` during argument resolution is corrected as part of this
-    feature (FR-023, SC-011).
-- "Non-technical stakeholders" is read as *developers who are not this library's
-  maintainers*: the spec names no Ruby constructs, gems, or file paths.
-- Ready for `/speckit-plan`.