ruby_reactor 0.7.0 → 0.8.0

data/specs/deferred-003-step-lock-declarations/contracts/dsl-surface.md

@@ -0,0 +1,154 @@
+# Public DSL Contract: Step-Scoped Coordination
+
+**Feature**: `specs/003-step-lock-declarations/` | **Date**: 2026-09-10
+
+The gem's external interface is its DSL. This document is what the specs assert against and
+what `documentation/locks_and_semaphores.md` must match.
+
+## 1. The five macros, now available on steps
+
+Identical signatures to the reactor-level forms (`Dsl::Lockable`). The only difference is what
+the key proc receives: **the step's resolved arguments**, where the reactor form receives the
+reactor's inputs.
+
+```ruby
+class ChargeStep < RubyReactor::Step
+  input :account_id
+  input :amount
+
+  with_lock(ttl: 60, wait: 0, auto_extend: true) { |args| "acct:#{args[:account_id]}" }
+
+  def run
+    Success(charge!(inputs))
+  end
+end
+```
+
+| Macro | Step-scoped meaning |
+|---|---|
+| `with_lock { \|args\| key }` | At most one execution inside this step's work per key |
+| `with_semaphore(limit: N) { \|args\| key }` | At most N executions inside this step's work per key |
+| `with_rate_limit(limit:, period:) { \|args\| key }` | At most X executions of this step per window per key. `with_rate_limit(:name)` still references a registered global limit |
+| `with_period(every:) { \|args\| key }` | This step runs at most once per bucket per key. **The step is skipped**; the workflow continues |
+| `with_ordered_lock { \|args\| key }` | Executions pass through this step in sequence per key |
+
+### `with_period` differs from the reactor form
+
+Reactor-level `with_period` halts the whole reactor when the bucket is marked. At step level
+that would kill a workflow over one deduplicated step, so the **step** is skipped and the
+following steps run. A step returning `Skipped` behaves as it does anywhere else.
+
+### `with_ordered_lock` provides a weaker guarantee than its reactor namesake
+
+The reactor form assigns its position at enqueue time, so it orders executions by enqueue. A
+step's key is computed from arguments that do not exist until the step is reached, so the step
+form orders executions **by arrival at that step**. For a step that sits first in its reactor
+the two coincide; the deeper the step, the weaker the promise. This is documented on the macro
+itself, not only here.
+
+## 2. Inline steps
+
+```ruby
+step :charge do
+  with_lock { |args| "acct:#{args[:account_id]}" }
+
+  argument :account_id, input(:account_id)
+  run { |args, _| charge!(args) }
+end
+```
+
+Same macros, same behavior as the class form.
+
+## 3. Where it is enforced
+
+Acquisition happens after guards and after argument validation, so a step that will be skipped
+or will fail validation never takes a hold.
+
+| Order | Taken | Released |
+|---|---|---|
+| 1 | Ordered-lock gate (nothing else held while waiting for a turn) | last |
+| 2 | Dedup window, fast check | — |
+| 3 | Rate limit | — |
+| 4 | Exclusive lock | 3rd |
+| 5 | Semaphore | 2nd |
+| 6 | Dedup window, re-check under the lock | marked on success |
+
+Released in reverse in an `ensure`, on success, failure, or unexpected error.
+
+| Entry point | Coordinated |
+|---|---|
+| Reactor step execution | ✅ |
+| Retried attempt | ✅ each attempt takes and releases |
+| `async_step` worker | ✅ taken in the worker, never in the dispatcher |
+| `background` hand-off worker | ✅ |
+| Resume after interrupt | ✅ |
+| Each `map` iteration | ✅ |
+| `ChargeStep.run(args, ctx)` directly | ✅ wait-then-fail; no execution to park |
+| `compensate` / `undo` | ✅ exclusion primitives only — see §6 |
+| Step suppressed by `where`/guard | ❌ by design |
+| Interrupt step | ❌ declaring coordination on one raises |
+
+## 4. Contention
+
+| Execution path | Behavior |
+|---|---|
+| Running in a worker | The execution is **parked** and retried later. No step compensates; the contended step's work has not been attempted. |
+| Running synchronously | Waits up to the configured `wait:`, then fails with a contention error naming reactor, step, and key. Rollback proceeds as for any step failure. |
+
+Contention attempts are counted separately from failure retries and bounded by a configurable
+ceiling; exceeding it turns the park into a contention failure. A busy key can therefore never
+exhaust the retry budget meant for genuine failures, nor snooze forever.
+
+## 5. Re-entrancy
+
+Identical to nested reactors — same primitives, no second rule set:
+
+- Holds are owned by the **execution** (its root context), so a step keyed the same as its own
+  reactor, or nested work inside a locked step, proceeds without waiting.
+- Nested holds on one key are counted; the key frees for other executions only when the
+  outermost hold is released.
+- The keys an execution holds are tracked for the execution as a whole.
+- **Ownership never crosses a process hand-off.** Dispatching work that declares a key the
+  execution currently holds is refused before dispatch, with a message naming the key, the
+  holder, and how to restructure. This now covers `async_step` dispatch as well as
+  `async_reactor`.
+- An execution that parks while holding coordination re-adopts it on resume without recording a
+  second acquisition, falling back to competing normally if the hold lapsed.
+
+## 6. Rollback
+
+| Primitive | Re-taken for compensate/undo |
+|---|---|
+| `with_lock`, `with_semaphore` | ✅ same key, computed from the same arguments |
+| `with_rate_limit`, `with_period`, `with_ordered_lock` | ❌ a forward-work quota must never suppress cleanup |
+
+Compensation that cannot acquire within its wait is reported, never silently skipped. It does
+not park — the execution is already mid-failure.
+
+## 7. Errors
+
+| Situation | Outcome |
+|---|---|
+| Key proc raises, or returns nil/empty | Step fails before its work runs, naming step and cause |
+| Contention, synchronous | `Lock::AcquisitionError` / `Semaphore::AcquisitionError` / `RateLimit::ExceededError`, naming reactor, step, key |
+| Contention ceiling exceeded | Contention failure with the attempt count |
+| Coordination declared on an interrupt step | Raises at declaration, pointing at reactor-level coordination |
+| Hand-off would deadlock | Failure at dispatch naming key, holder, and remedies |
+| Backing store unreachable | Step fails with the cause; work never runs unprotected |
+
+## 8. Observability
+
+- Acquisition, release, and acquisition failure are distinct events carrying the key and the
+  owning step.
+- A contention-parked execution is reported distinctly from a failure — a snooze round must not
+  read as a phantom failure.
+- The dashboard's coordination view shows step-level holds alongside reactor-level ones,
+  identified by step.
+
+## 9. Compatibility
+
+- Additive. A step declaring nothing behaves exactly as today.
+- Reactor-level declarations are unchanged in syntax and behavior.
+- Guidance: reactor level for "this whole workflow is exclusive", step level for "this one
+  operation is exclusive". Step level keeps the critical section small, so prefer it when only
+  part of the workflow needs protection.

data/specs/deferred-003-step-lock-declarations/data-model.md

@@ -0,0 +1,131 @@
+# Phase 1 Data Model: Step-Scoped Coordination
+
+**Feature**: `specs/003-step-lock-declarations/` | **Date**: 2026-09-10
+
+Definition-time state lives on Ruby classes. Runtime state lives in Redis (the holds
+themselves, unchanged key spaces) and in `context.private_data` (per-execution bookkeeping,
+which already round-trips through `ContextSerializer`).
+
+## StepCoordinationDeclaration
+
+What a unit of work declares about when it may run. One per primitive per step; a step may
+declare several.
+
+| Field | Type | Notes |
+|---|---|---|
+| `primitive` | `:lock` \| `:semaphore` \| `:rate_limit` \| `:period` \| `:ordered_lock` | |
+| `key_proc` | Proc | Receives the step's **resolved arguments**, returns the key. Where the reactor form receives reactor inputs. |
+| `ttl` | Integer | `:lock`, `:ordered_lock`. Default as today. |
+| `wait` | Integer | `:lock`, `:semaphore`. Tolerance before contention handling. |
+| `auto_extend` | Boolean | `:lock`. Keeps the hold alive while the step's work runs. |
+| `limit` | Integer | `:semaphore` — concurrent holders per key. |
+| `limits` | Hash | `:rate_limit` — window → ceiling, or a registered name. |
+| `every` | Symbol \| Integer | `:period` — bucket size. |
+| `poison_pill_timeout`, `strict` | Integer, Boolean | `:ordered_lock`. |
+
+**Validation rules**:
+
+- Declaring any primitive on an interrupt step raises at declaration time (research D6).
+- The existing per-macro argument validation is unchanged — e.g. `with_rate_limit(:name)`
+  still refuses to also take `limit:`/`period:`/a block; `with_period` still validates `every:`
+  eagerly at class load.
+- A key proc returning nil or empty fails the step before its work runs (FR-007).
+
+**Ownership**: a step class, or an inline step's `StepConfig`. Propagates to subclasses via
+the existing `inherited` hook; a subclass redeclaring a primitive replaces the parent's.
+
+**Introspection** (FR-006): `declares_coordination?`, `coordination_declarations`, and the
+existing per-primitive readers (`lock_config`, `semaphore_config`, …) available on the step.
+
+## Hold
+
+The runtime fact that one execution holds one key. Redis-side representation is unchanged —
+this is the model of what already exists, now also created by steps.
+
+| Field | Source | Notes |
+|---|---|---|
+| `key` | key proc output, namespaced per primitive | |
+| `owner` | root context id | The basis of re-entrancy: every reactor and step in one execution tree shares it. A direct step invocation uses a per-call UUID instead. |
+| `owning_step` | step name | New. Nil for a reactor-level hold. |
+| `nesting_count` | adapter-maintained | Increments on re-acquire by the same owner; the key frees at zero. |
+| `acquired_at`, `ttl` | as today | Refreshed by the auto-extend thread while the step's work runs. |
+
+**Lifecycle**: `acquired` → (`extended`…) → `released`, or `expired` if the holder dies.
+Release is in `ensure` around the step body, in reverse acquisition order.
+
+## HeldKeyRegistry
+
+`root.private_data[:held_lock_keys]` — the set of keys this execution currently holds.
+Unchanged structure; step holds push and pop the same way reactor holds do.
+
+Read by the dispatch-time deadlock guard: handing off work that declares a key present in the
+registry is refused before dispatch (FR-022). Extended in this feature to consult a dispatched
+**step class's** declarations, not only a child reactor's.
+
+## ContentionState
+
+Per-execution bookkeeping for the park-and-retry path, in `context.private_data`.
+
+| Field | Type | Notes |
+|---|---|---|
+| `attempts_by_step` | Hash{step → Integer} | Counted separately from failure retries, so a busy key cannot exhaust the budget meant for genuine failures. |
+| `ceiling` | Integer | Configurable. Exceeding it converts the park into a contention failure (FR-017). |
+| `next_attempt_at` | Time | Set from the primitive's own hint (`retry_after_seconds` for rate limits) or the configured contention backoff. |
+
+**Transitions**:
+
+```text
+reached step ──cannot acquire──> in a worker?
+                                  │
+                      yes ────────┴──────── no
+                       │                     │
+              attempts < ceiling?      waited `wait` already
+                 │         │                 │
+               yes        no                 │
+                 │         │                 │
+        park + requeue   contention      contention
+        (RetryQueued)     failure         failure
+                 │
+          redelivered ──> retry acquisition
+```
+
+A parked execution has run no part of the contended step and compensated nothing (FR-015).
+
+## StepOrderedLockState
+
+Per-step sequencing state, in `context.private_data`, keyed by step name. Mirrors the
+reactor-level `private_data[:ordered_lock]` stash.
+
+| Field | Notes |
+|---|---|
+| `key`, `nonce`, `epoch` | Assigned when the execution first reaches the step; reused across contention redeliveries. |
+| `poison_pill_timeout`, `ttl`, `strict` | From the declaration. |
+
+**Caveat carried from research D8**: the nonce is assigned on arrival at the step, not at
+enqueue, so the guarantee is arrival-ordered rather than enqueue-ordered.
+
+## CoordinationOutcome
+
+What the executor produces at a coordinated step boundary.
+
+| Outcome | When | Result |
+|---|---|---|
+| Proceed | All declared primitives taken | Step body runs, holds released after |
+| Skip | Dedup window already marked for this bucket and key | `Skipped` for the step; workflow continues (FR-003) |
+| Skip (chain) | Strict ordering and an earlier position failed | `Skipped` for the step (FR-004) |
+| Park | Contention, in a worker, under the ceiling | `RetryQueuedResult`; execution resumes at this step later |
+| Fail | Contention synchronously, or over the ceiling, or key computation failed | Step failure; rollback proceeds as for any step failure |
+| Refuse | Hand-off would deadlock on a held key | Failure at dispatch, naming key, holder, and remedies (FR-022) |
+
+## Rollback interaction
+
+| Primitive | Re-taken for compensate/undo? |
+|---|---|
+| `:lock` | ✅ same key, same values (FR-024) |
+| `:semaphore` | ✅ |
+| `:rate_limit` | ❌ a forward-work quota must not suppress cleanup (FR-025) |
+| `:period` | ❌ same reason |
+| `:ordered_lock` | ❌ sequencing governs forward work |
+
+Compensation that cannot acquire within its wait is reported, never silently skipped
+(FR-026), and never parks — the execution is already mid-failure.

data/specs/deferred-003-step-lock-declarations/plan.md

@@ -0,0 +1,166 @@
+# Implementation Plan: Step-Scoped Coordination
+
+**Branch**: `step_validations` | **Date**: 2026-09-10 | **Spec**: [spec.md](./spec.md)
+
+**Input**: Feature specification from `specs/003-step-lock-declarations/spec.md`
+
+## Summary
+
+Let a step declare its own coordination — exclusivity, concurrency ceiling, rate ceiling,
+dedup window, strict ordering — keyed on the step's own resolved arguments, so one step of a
+workflow can be serialized without serializing the workflow.
+
+The declaration surface already exists: `Dsl::Lockable`'s five macros are a self-contained
+module whose only contract is "a key proc that receives a hash". Steps host it unchanged and
+pass their arguments where the reactor passes its inputs. Enforcement is a `StepCoordination`
+object the executor wraps around the step body, in the same fixed order the reactor uses.
+
+Contention parks the execution rather than failing it, reusing `requeue_job_for_step_retry` —
+which already persists the context with `current_step` set and re-enqueues — with contention
+attempts counted separately from failure retries. Synchronously there is no queue to park
+into, so that path waits then fails.
+
+Re-entrancy reuses every existing nested-workflow primitive unchanged: holds owned by the root
+context id, the adapter's nesting count, the `held_lock_keys` registry, and the dispatch-time
+deadlock guard — which already covers step holds, since it reads that registry.
+
+Design decisions and evidence: [research.md](./research.md).
+
+## Technical Context
+
+**Language/Version**: Ruby >= 3.0.0
+
+**Primary Dependencies**: redis ~> 5.0 (every primitive is Redis-backed), sidekiq ~> 7.0
+(the park-and-retry path), zeitwerk ~> 2.6. No new dependency.
+
+**Storage**: Redis. Step holds use the same key spaces, TTLs, and Lua primitives as reactor
+holds (`storage/redis_locking.rb`, `storage/redis_ordered_locking.rb`). New per-step state is
+confined to `context.private_data` (contention counter, per-step ordered-lock nonce), which
+already round-trips through `ContextSerializer`.
+
+**Testing**: RSpec against real Redis (constitution III). Concurrency claims need genuine
+parallelism — overlap detection across processes/threads, not mocked timing. The park-and-
+retry path must be exercised with a real Sidekiq worker, not `Sidekiq::Testing.inline!`.
+
+**Target Platform**: Ruby library, sync and Sidekiq-backed async execution
+
+**Project Type**: Library / DSL
+
+**Performance Goals**: A step declaring nothing pays one nil check per step. A step declaring
+coordination pays the same Redis round-trips the reactor-level equivalent pays today, moved
+from once-per-run to once-per-step-execution. The point of the feature is that the critical
+section shrinks, so end-to-end throughput under contention should improve, not regress.
+
+**Constraints**: Additive and SemVer-MINOR — no existing reactor changes behavior. Coordination
+must never be held across a process hand-off. The critical section must stay minimal:
+acquisition happens after guards and after argument validation.
+
+**Scale/Scope**: ~10 library files touched, 2-3 new, plus demo-app artifacts and docs. The
+ordered-lock phase is roughly the weight of the other four primitives combined.
+
+## Constitution Check
+
+*GATE: passed before Phase 0. Re-checked after Phase 1 design — see below.*
+
+| Principle | Assessment |
+|---|---|
+| **I. Gem-First Design** | ✅ Entirely inside `lib/`. Redis and Sidekiq usage stays behind the existing adapter and router boundaries; callers still provide their own connections. |
+| **II. Saga Pattern Integrity** | ✅ The strongest alignment in this feature. Coordination is re-taken for compensate/undo (FR-024), so rollback of a protected operation is protected too — closing a race the reactor-level lock leaves open whenever rollback outlives the reactor's own hold. Contention parks rather than fails, so routine contention never triggers spurious compensation. Nothing changes which steps run or in what order (FR-014). |
+| **III. Test-First with Real Infrastructure** | ✅ Non-negotiable here: every claim is a concurrency claim. Real Redis, real Sidekiq for the park path. `Sidekiq::Testing.inline!` is explicitly wrong for this feature — it re-enters the worker synchronously inside the holding frame (the reason `acquire_context_lock` skips itself under it, `executor.rb:470`). |
+| **IV. Observability by Default** | ✅ FR-028/FR-029. Events carry the step name; the dashboard's coordination view learns step-level state; a contention-parked execution is distinguishable from a failed one, reusing the `:snooze_reactor` precedent that already keeps snooze rounds from reading as phantom failures. |
+| **V. Simplicity and SemVer** | ⚠️ Justified. MINOR and fully additive — a step declaring nothing is unaffected. But the scope is five primitives where the request was one, and YAGNI applies to four of them; the step-level ordered lock in particular invents a guarantee (order-of-arrival) weaker than the one its name implies. Recorded in Complexity Tracking, sequenced last, and flagged as the first thing to cut. |
+| **VI. Demo-App Proof of Feature** | ✅ Blocking work: example reactor + `demo:` rake task + spec using only shipped matchers + `docker compose run`. `be_locked`, `have_available_tokens`, `have_held_tokens`, `have_rate_limit_count`, `be_period_marked`, and the ordered-lock matchers already exist; step-scoped assertions are expected to need at least one addition (a step-attributed hold), which goes into `lib/ruby_reactor/rspec/` in the same change rather than being worked around. |
+
+**Post-design re-check**: no new violations. No new dependency, no new storage primitive, no
+new failure shape — the design routes a second declaration site into mechanisms that already
+exist. The two carried items are scope (five primitives) and the ordered-lock guarantee gap.
+
+## Project Structure
+
+### Documentation (this feature)
+
+```text
+specs/003-step-lock-declarations/
+├── plan.md              # This file
+├── spec.md              # Feature specification
+├── research.md          # Phase 0 — current-state findings and design decisions
+├── data-model.md        # Phase 1 — declaration/hold entities and lifecycle
+├── quickstart.md        # Phase 1 — how to run and verify
+├── contracts/
+│   └── dsl-surface.md   # Phase 1 — public DSL, semantics per primitive, errors
+├── checklists/
+│   └── requirements.md  # Spec quality checklist (complete)
+└── tasks.md             # Phase 2 — /speckit-tasks output, NOT created here
+```
+
+### Source Code (repository root)
+
+```text
+lib/ruby_reactor/
+├── dsl/
+│   ├── lockable.rb                   # unchanged module, now also hosted by steps
+│   └── step_builder.rb               # + the five macros for inline steps; refuse on
+│                                     #   interrupt steps (D6); config onto StepConfig
+├── step.rb                           # + host Lockable macros; introspection (D1)
+├── executor/
+│   ├── step_coordination.rb          # NEW — acquire/release in fixed order, contention
+│   │                                 #   handling, park decision (D2, D3, D4)
+│   ├── step_executor.rb              # wrap the step body in StepCoordination
+│   ├── retry_manager.rb              # contention requeue + separate contention counter (D4)
+│   └── compensation_manager.rb       # re-take exclusion primitives for compensate/undo (FR-024)
+├── step/
+│   └── async_reactor_step.rb         # deadlock guard also covers async_step dispatch (D5)
+├── step_worker.rb                    # coordination around the worker-side step body
+├── retry_context.rb                  # + contention attempt counter
+├── web/coordination_serializer.rb    # + step-level coordination state (D9)
+└── rspec/matchers.rb                 # + step-attributed hold assertions as needed
+
+spec/ruby_reactor/
+├── step_coordination/lock_spec.rb           # NEW — US1, US2 (real concurrency)
+├── step_coordination/contention_spec.rb     # NEW — US3 both paths, bounded retries
+├── step_coordination/reentrancy_spec.rb     # NEW — US4 incl. dispatch refusal
+├── step_coordination/primitives_spec.rb     # NEW — US5, one per primitive
+├── step_coordination/rollback_spec.rb       # NEW — US6
+└── step_coordination/inline_spec.rb         # NEW — US8 equivalence
+
+demo_app/
+├── app/reactors/step_lock_demo_reactor.rb        # NEW — serialized, contended, compensated
+├── lib/tasks/demo_reactors.rake                  # + demo:step_lock
+└── spec/reactors/step_lock_demo_reactor_spec.rb  # NEW — shipped matchers only
+
+documentation/locks_and_semaphores.md   # step-scoped forms, when to prefer which
+README.md, CHANGELOG.md
+```
+
+**Structure Decision**: Existing layout kept. One new library file carries the feature
+(`executor/step_coordination.rb`); everything else is an edit to the file that already owns
+the concern. Specs get a `step_coordination/` directory because they are concurrency tests
+with shared harness needs, not unit tests scattered across existing files.
+
+## Phase 2 outline (for `/speckit-tasks`)
+
+Dependency-ordered. Phases 1-6 deliver US1-US4 and US6-US8 in full.
+
+1. **Declaration surface** — host `Lockable` on `Step` and `StepBuilder`, introspection,
+   refuse on interrupt steps. No enforcement yet.
+2. **Exclusive lock enforcement (US1, US2)** — `StepCoordination` around the step body,
+   acquire/release, keep-alive, guard skip, key-computation failure. Real-concurrency specs.
+3. **Re-entrancy (US4)** — root-context owner, registry push/pop, `async_step` dispatch guard.
+4. **Contention (US3)** — requeue park, contention counter and ceiling, sync wait-then-fail.
+5. **Rollback (US6)** — re-take exclusion primitives for compensate/undo; verify rate/dedup are
+   not applied.
+6. **Remaining narrowing primitives (US5 partial)** — semaphore, rate limit, period-skips-step.
+7. **Observability + inline steps (US7, US8)** — events, dashboard, matcher additions, inline
+   equivalence.
+8. **Step-level ordered lock (US5 remainder)** — per-step nonce, heartbeat, advance-on-terminal,
+   strict chain skip. Last, and separable: see Complexity Tracking.
+9. **Docs + demo** — `documentation/locks_and_semaphores.md`, README, CHANGELOG, demo reactor +
+   rake + spec, docker acceptance run.
+
+## Complexity Tracking
+
+| Violation | Why Needed | Simpler Alternative Rejected Because |
+|-----------|------------|--------------------------------------|
+| Five primitives at step level where the request named one (Principle V / YAGNI) | Explicit user decision after being shown the narrower option. Parity means an author never has to ask which primitives "work" on a step. | Shipping `with_lock` alone covers the stated use case and every acceptance scenario in US1-US4. It was offered and declined. The four extra primitives are sequenced after the core so the schedule can still absorb them being cut. |
+| Step-level ordered lock provides a weaker guarantee than its reactor-level namesake | Included in the user's "all five" decision. Sequencing at step arrival is still useful for a step that sits first in its reactor, where arrival order equals enqueue order. | The reactor-level guarantee cannot be reproduced: the nonce would have to be assigned at enqueue, but the key expression reads arguments that do not exist until the step is reached (research Finding 5). Mitigation is documentation on the macro plus a demo that shows arrival ordering explicitly — not a silent redefinition of the word "ordered". |
+| Contention behaves differently in a worker (park) than synchronously (wait, then fail) | Direct consequence of the chosen park-and-retry behavior; a synchronous run has no queue to park into. | Failing on both paths is simpler and was the recommended option; it was declined. `contention_wait` already encodes this exact split for reactor-level holds, so the divergence is inherited rather than invented, and it is one branch in one method. |

data/specs/deferred-003-step-lock-declarations/quickstart.md

@@ -0,0 +1,169 @@
+# Quickstart: Step-Scoped Coordination
+
+**Feature**: `specs/003-step-lock-declarations/` | **Date**: 2026-09-10
+
+How to run and verify this feature. DSL details: [contracts/dsl-surface.md](./contracts/dsl-surface.md).
+Design rationale: [research.md](./research.md).
+
+## Prerequisites
+
+Every claim here is a concurrency claim, so real infrastructure is mandatory — mocked Redis or
+`Sidekiq::Testing.inline!` cannot prove any of it. Inline testing mode is actively wrong for
+this feature: it re-enters the worker synchronously inside the frame that already holds the
+lock.
+
+```bash
+docker compose up -d redis-test              # gem suite (port 6780)
+docker compose up -d demo-redis sidekiq      # demo app + a real worker
+```
+
+## Scenario 1 — one step serializes, the workflow does not (US1, US2)
+
+```ruby
+class ChargeStep < RubyReactor::Step
+  input :account_id
+  input :amount
+
+  with_lock { |args| "acct:#{args[:account_id]}" }
+
+  def run
+    Success(charge!(inputs))
+  end
+end
+
+class PaymentReactor < RubyReactor::Reactor
+  input :account_id
+  input :amount
+
+  step :audit,  AuditStep       # unlocked
+  step :charge, ChargeStep      # locked on the account
+  step :notify, NotifyStep      # unlocked
+end
+```
+
+**Expected**: two concurrent runs with the same `account_id` never overlap inside `:charge`;
+`:audit` and `:notify` of both runs overlap freely. Two runs with different `account_id`
+overlap everywhere.
+
+```bash
+bundle exec rspec spec/ruby_reactor/step_coordination/lock_spec.rb
+```
+
+## Scenario 2 — contention parks instead of failing (US3)
+
+```ruby
+# Two worker-backed executions, same key:
+PaymentReactor.run(account_id: 1, amount: 10)   # via background dispatch
+PaymentReactor.run(account_id: 1, amount: 20)
+
+# => both complete successfully; the second after the first released.
+#    No compensation ran. The second was requeued, not failed.
+```
+
+Synchronously there is no queue to park into:
+
+```ruby
+PaymentReactor.run(account_id: 1, amount: 20)   # in-process, key held elsewhere
+# => Failure(Lock::AcquisitionError, reactor:, step: :charge, key: "acct:1")
+#    prior steps compensated, as with any step failure
+```
+
+```bash
+bundle exec rspec spec/ruby_reactor/step_coordination/contention_spec.rb
+```
+
+Also asserted there: contention attempts are bounded, counted separately from failure retries,
+and an execution over the ceiling reports contention rather than snoozing forever.
+
+## Scenario 3 — re-entrancy matches nested reactors (US4)
+
+```ruby
+class OuterReactor < RubyReactor::Reactor
+  input :id
+  with_lock { |i| "k:#{i[:id]}" }        # reactor holds it
+  step :work, LockingStep                 # step declares the same key
+end
+```
+
+**Expected**: completes without waiting on itself; the key becomes available to other
+executions only after the outermost release.
+
+Where ownership cannot cross a process boundary, the hand-off is refused up front:
+
+```ruby
+# execution holds "k:1", then dispatches work that declares "k:1"
+# => Failure at dispatch naming the key, the holder, and how to restructure.
+#    Never a silent wait.
+```
+
+```bash
+bundle exec rspec spec/ruby_reactor/step_coordination/reentrancy_spec.rb
+```
+
+## Scenario 4 — rollback runs under the same exclusivity (US6)
+
+```ruby
+# :charge succeeds holding "acct:1", a later step fails, rollback reaches :charge
+# => the compensation runs holding "acct:1"
+# => a concurrent execution cannot enter :charge's forward work while it runs
+```
+
+Rate ceilings and dedup windows are deliberately *not* applied to compensation — cleanup is
+never suppressed by a forward-work quota.
+
+```bash
+bundle exec rspec spec/ruby_reactor/step_coordination/rollback_spec.rb
+```
+
+## Scenario 5 — the other primitives (US5)
+
+```bash
+bundle exec rspec spec/ruby_reactor/step_coordination/primitives_spec.rb
+```
+
+Asserts, one per primitive:
+
+- semaphore: at most N inside the step's work per key
+- rate limit: further executions of the step contend rather than exceed the rate
+- dedup window: the **step** is skipped and the workflow continues — the reactor is not halted
+- ordered lock: executions pass through the step in sequence; stop-the-line short-circuits that
+  step for later positions
+
+## Scenario 6 — end to end against real infrastructure
+
+```bash
+docker compose run --rm demo-app bin/rails demo:step_lock
+```
+
+**Expected output**: the serialized path (two executions, non-overlapping step bodies), the
+contended path (one parked and retried, both completing), and the compensated path (rollback
+holding the same key).
+
+## Full suite
+
+```bash
+docker compose up -d redis-test
+bundle exec rspec
+bundle exec rubocop
+
+docker compose run --rm demo-app bundle exec rspec spec/reactors/step_lock_demo_reactor_spec.rb
+docker compose run --rm demo-app bin/rails demo:step_lock
+```
+
+## Acceptance checklist
+
+| # | Claim | Verified by |
+|---|---|---|
+| SC-001 | Same-key step bodies never overlap | Scenario 1, sustained concurrent run |
+| SC-002 | Unrelated steps still overlap | Scenario 1 |
+| SC-003 | Released within one step boundary, all outcomes | Scenario 1 + failure/raise cases |
+| SC-004 | Contention costs zero compensations | Scenario 2 |
+| SC-005 | Worker path protected identically to in-process | Scenarios 1 and 6 |
+| SC-006 | Nested holds on one key complete without self-waiting | Scenario 3 |
+| SC-007 | Deadlocking hand-offs refused at dispatch | Scenario 3 |
+| SC-008 | Killed holder frees the key without operator action | kill-process test in lock_spec |
+| SC-009 | Compensation runs under the same exclusivity | Scenario 4 |
+| SC-010 | Operator can see step, key, holder; park ≠ failure | dashboard + log assertions |
+| SC-011 | Uncomputable key never runs the work | lock_spec |
+| SC-012 | Existing reactor-level coordination tests unchanged | full suite |
+| SC-013 | Demo shows serialized, contended, compensated | Scenario 6 |