ruby_reactor 0.8.2 → 0.8.3

data/specs/active_job.md

@@ -1,259 +0,0 @@
-# Pluggable Background Adapters (Sidekiq → ActiveJob)
-
-## Goal
-
-Today RubyReactor is hardwired to Sidekiq for everything async: enqueuing,
-resuming, map-element fan-out/collection, and the recovery sweeper. We want
-to support other background processors — starting with ActiveJob — without
-duplicating the reactor-resume/snooze/escalate logic per adapter.
-
-## What's already abstracted (good news)
-
-The **enqueue side** is already behind a seam:
-
-- `RubyReactor.configuration.async_router` (default `RubyReactor::Adapters::Sidekiq::Router`,
-  [configuration.rb:126-128](../lib/ruby_reactor/configuration.rb#L126-L128)) is the
-  only thing the core engine calls to go async. Call sites:
-  [reactor.rb:117](../lib/ruby_reactor/reactor.rb#L117),
-  [reactor.rb:319](../lib/ruby_reactor/reactor.rb#L319),
-  [step/map_step.rb:274](../lib/ruby_reactor/step/map_step.rb#L274),
-  [step/map_step.rb:285](../lib/ruby_reactor/step/map_step.rb#L285),
-  [map/dispatcher.rb:177](../lib/ruby_reactor/map/dispatcher.rb#L177),
-  [map/element_executor.rb:155](../lib/ruby_reactor/map/element_executor.rb#L155),
-  [map/element_executor.rb:176](../lib/ruby_reactor/map/element_executor.rb#L176),
-  [executor/retry_manager.rb:59,80](../lib/ruby_reactor/executor/retry_manager.rb#L59),
-  [executor/step_executor.rb:219](../lib/ruby_reactor/executor/step_executor.rb#L219),
-  [sweeper.rb:48](../lib/ruby_reactor/sweeper.rb#L48),
-  [map/sweeper.rb:99](../lib/ruby_reactor/map/sweeper.rb#L99).
-- The router contract is 5 class methods on `SidekiqAdapter`
-  ([sidekiq_adapter.rb](../lib/ruby_reactor/sidekiq_adapter.rb)):
-  `perform_async`, `perform_in`, `perform_map_element_async`,
-  `perform_map_element_in`, `perform_map_collection_async`. All return
-  `RubyReactor::DispatchResult`.
-- An adapter for any other queueing backend just needs to implement that
-  same 5-method contract and assign it to `config.async_router`. **This part
-  needs no rework.**
-
-## What's NOT abstracted (the actual gap)
-
-The **worker/job side** — the classes the queue invokes — bakes Sidekiq in
-directly. **Decision: these move into `RubyReactor::Adapters::Sidekiq::*`**
-(renamed from `RubyReactor::SidekiqWorkers::*`), with a sibling
-`RubyReactor::Adapters::ActiveJob::*` for the new adapter — see
-[Namespace](#namespace) below.
-
-| Class (today) | File | Sidekiq coupling |
-|---|---|---|
-| `SidekiqWorkers::Worker` | [worker.rb](../lib/ruby_reactor/sidekiq_workers/worker.rb) | `include ::Sidekiq::Worker`, `sidekiq_options`, `sidekiq_retries_exhausted`, and internally calls `self.class.perform_in(...)` to reschedule snoozes (lines 116, 91-117) |
-| `SidekiqWorkers::MapElementWorker` | [map_element_worker.rb](../lib/ruby_reactor/sidekiq_workers/map_element_worker.rb) | `include ::Sidekiq::Worker`; body is a 1-line delegate to `Map::ElementExecutor.perform` |
-| `SidekiqWorkers::MapCollectorWorker` | [map_collector_worker.rb](../lib/ruby_reactor/sidekiq_workers/map_collector_worker.rb) | same — 1-line delegate to `Map::Collector.perform` |
-| `SidekiqWorkers::SweeperWorker` | [sweeper_worker.rb](../lib/ruby_reactor/sidekiq_workers/sweeper_worker.rb) | `include ::Sidekiq::Worker`, `sidekiq_options retry: false`, self-reschedules via `perform_in` / class-level `perform_in` in `schedule_next` |
-
-Plus test-side coupling:
-
-- [rspec/sidekiq_helpers.rb](../lib/ruby_reactor/rspec/sidekiq_helpers.rb) hardcodes
-  the 3 Sidekiq worker classes and `Sidekiq::Testing` fake-mode draining.
-- [rspec/test_subject.rb:194-203,433](../lib/ruby_reactor/rspec/test_subject.rb#L194-L203)
-  gates job-processing on `defined?(Sidekiq::Testing)` and forces
-  `async_router` back to `SidekiqAdapter`.
-- [ruby_reactor.rb:22-27](../lib/ruby_reactor.rb#L22-L27) optionally requires
-  `sidekiq`; [ruby_reactor.rb:359](../lib/ruby_reactor.rb#L359) calls
-  `SidekiqWorkers::SweeperWorker.schedule_next` directly from
-  `RubyReactor.start_sweeper!`.
-
-The real logic worth extracting lives almost entirely in
-`SidekiqWorkers::Worker#perform` (~65 lines): rehydrate context from
-storage, deserialize, resolve `reactor_class`, mark
-`inline_async_execution`, run `Executor#resume_execution`, and on
-lock/semaphore/rate-limit/ordered-lock contention either snooze (re-enqueue
-with a computed delay) or escalate to `failed`. None of that is
-Sidekiq-specific — it only *touches* Sidekiq via `self.class.perform_in` to
-reschedule.
-
-## Proposal
-
-### 1. Normalize the enqueue API at the job-class boundary, not in the shared logic
-
-`Sidekiq::Worker` gives every job class `.perform_async` / `.perform_in` for
-free. ActiveJob doesn't — it has `.perform_later` and
-`.set(wait: delay).perform_later`. Rather than teach the shared logic two
-different reschedule calls, give every framework-specific job class the
-same two class methods, so the shared mixin can keep calling
-`self.class.perform_in(...)` unchanged:
-
-```ruby
-module RubyReactor
-  module Adapters
-    module ActiveJob
-      module Compat
-        def perform_async(*args) = perform_later(*args)
-        def perform_in(delay, *args) = set(wait: delay).perform_later(*args)
-      end
-    end
-  end
-end
-```
-
-### 2. Extract `RubyReactor::Worker` — the framework-agnostic mixin
-
-Move the body of `Adapters::Sidekiq::Worker#perform` (and its private snooze/
-escalate/deserialization-failure helpers) into a plain module with no
-`Sidekiq` reference:
-
-```ruby
-module RubyReactor
-  module Worker
-    def perform(context_id, reactor_class_name = nil, snooze_count = 0)
-      # ...exact same logic as today's SidekiqWorkers::Worker#perform...
-    end
-
-    private
-    # handle_snooze, compute_snooze_delay, hinted_retry?, escalate_snooze,
-    # log_infrastructure_failure, handle_deserialization_failure,
-    # build_failed_context_payload — unchanged, moved verbatim.
-  end
-end
-```
-
-`Adapters::Sidekiq::Worker` then becomes:
-
-```ruby
-module RubyReactor
-  module Adapters
-    module Sidekiq
-      class Worker
-        include ::Sidekiq::Worker
-        include RubyReactor::Worker
-
-        sidekiq_options retry: RubyReactor.configuration.sidekiq_retry_count,
-                        dead: false, queue: RubyReactor.configuration.sidekiq_queue
-      end
-    end
-  end
-end
-```
-
-And a new `Adapters::ActiveJob::Worker`:
-
-```ruby
-module RubyReactor
-  module Adapters
-    module ActiveJob
-      class Worker < ::ActiveJob::Base
-        extend Compat
-        include RubyReactor::Worker
-
-        queue_as { RubyReactor.configuration.sidekiq_queue } # or a renamed generic config
-      end
-    end
-  end
-end
-```
-
-Same pattern applies to `MapElementWorker` / `MapCollectorWorker` — they're
-already a 1-line delegate, so genericizing is just swapping the include; no
-logic to extract.
-
-### 3. Sweeper
-
-`SweeperWorker`'s window-claim-lock + self-reschedule logic
-([sweeper_worker.rb:30-70](../lib/ruby_reactor/sidekiq_workers/sweeper_worker.rb#L30-L70))
-is also framework-agnostic except for the `perform_in` call in
-`schedule_next`. Extract the same way into `RubyReactor::SweeperJob`,
-included into both `Adapters::Sidekiq::SweeperWorker` (`sidekiq_options retry: false`)
-and an `Adapters::ActiveJob::SweeperWorker`. `RubyReactor.start_sweeper!`
-([ruby_reactor.rb:356-360](../lib/ruby_reactor.rb#L356-L360)) needs to call
-through whichever sweeper job class matches the configured adapter instead
-of hardcoding `Adapters::Sidekiq::SweeperWorker`.
-
-### 4. New `RubyReactor::Adapters::ActiveJob::Router`
-
-Mirrors today's `RubyReactor::Adapters::Sidekiq::Router` (renamed from
-`SidekiqAdapter`) exactly — same 5 methods, just pointing at the
-`Adapters::ActiveJob::*` job classes instead of `Adapters::Sidekiq::*`. No
-changes needed to any core call site; swap is purely
-`config.async_router = RubyReactor::Adapters::ActiveJob::Router`.
-
-### 5. Optional config sugar
-
-`configuration.rb` already does this pattern for storage
-([configuration.rb:114-121](../lib/ruby_reactor/configuration.rb#L114-L121)):
-a single `storage.adapter` symbol resolves to a concrete adapter instance.
-Could mirror it — `config.queue_adapter = :sidekiq | :active_job` resolving
-both `async_router` and the sweeper job class — but this is sugar, not
-required for the feature to work. Confirm whether you want it.
-
-### 6. Test helpers
-
-`rspec/sidekiq_helpers.rb` and the `Sidekiq::Testing` branch in
-`rspec/test_subject.rb` only fire for Sidekiq today. For ActiveJob, Rails
-already ships `ActiveJob::TestHelper` (`perform_enqueued_jobs`,
-`have_enqueued_job`) which covers most of this generically. We'd still want
-something equivalent to `drain_async_jobs` (loops until self-rescheduling
-jobs — e.g. ordered-lock snoozes — stop producing new ones), so
-`test_subject.rb`'s job-processing gate needs to branch on which
-testing framework is active (or be driven by `configuration.async_router`)
-rather than hardcoding `defined?(Sidekiq::Testing)`.
-
-### 7. Loading
-
-`ruby_reactor.rb:22-27` optionally `require "sidekiq"`. Add the same
-optional-require pattern for `active_job`, so neither dependency is forced
-on users who only need one.
-
-## Namespace
-
-**Decided: `RubyReactor::Adapters::Sidekiq::*` / `RubyReactor::Adapters::ActiveJob::*`.**
-
-Renames/moves required (mechanical, but touches every reference):
-
-| Today | Becomes |
-|---|---|
-| `RubyReactor::SidekiqAdapter` | `RubyReactor::Adapters::Sidekiq::Router` |
-| `RubyReactor::SidekiqWorkers::Worker` | `RubyReactor::Adapters::Sidekiq::Worker` |
-| `RubyReactor::SidekiqWorkers::MapElementWorker` | `RubyReactor::Adapters::Sidekiq::MapElementWorker` |
-| `RubyReactor::SidekiqWorkers::MapCollectorWorker` | `RubyReactor::Adapters::Sidekiq::MapCollectorWorker` |
-| `RubyReactor::SidekiqWorkers::SweeperWorker` | `RubyReactor::Adapters::Sidekiq::SweeperWorker` |
-| (new) | `RubyReactor::Adapters::ActiveJob::Router` |
-| (new) | `RubyReactor::Adapters::ActiveJob::{Worker,MapElementWorker,MapCollectorWorker,SweeperWorker}` |
-
-Files move from `lib/ruby_reactor/sidekiq_workers/*.rb` +
-`lib/ruby_reactor/sidekiq_adapter.rb` to
-`lib/ruby_reactor/adapters/sidekiq/*.rb` (Zeitwerk-driven, so the directory
-move IS the rename — no manual `module` boilerplate beyond nesting). New
-ActiveJob side lives in `lib/ruby_reactor/adapters/active_job/*.rb`.
-
-References that need updating for the rename:
-- [configuration.rb:107](../lib/ruby_reactor/configuration.rb#L107) — `@async_router ||= RubyReactor::SidekiqAdapter`
-- [ruby_reactor.rb:359](../lib/ruby_reactor.rb#L359) — `SidekiqWorkers::SweeperWorker.schedule_next`
-- [rspec/sidekiq_helpers.rb](../lib/ruby_reactor/rspec/sidekiq_helpers.rb) — `worker_classes` list
-- [rspec/test_subject.rb:196](../lib/ruby_reactor/rspec/test_subject.rb#L196) — stub target
-- [spec/ruby_reactor/sidekiq_workers/worker_spec.rb](../spec/ruby_reactor/sidekiq_workers/worker_spec.rb),
-  [spec/ruby_reactor/sidekiq_workers/sweeper_worker_spec.rb](../spec/ruby_reactor/sidekiq_workers/sweeper_worker_spec.rb) —
-  `described_class` references, move to `spec/ruby_reactor/adapters/sidekiq/`
-
-## Retry config — decided: generic
-
-`sidekiq_retry_count` / `sidekiq_queue` rename to `config.job_retry_count` /
-`config.queue_name`, used by both adapters:
-
-- `Adapters::Sidekiq::Worker` → `sidekiq_options retry: config.job_retry_count, dead: false, queue: config.queue_name`
-- `Adapters::ActiveJob::Worker` → maps to `retry_on StandardError, attempts: config.job_retry_count` (infra
-  failures only — reactor-specific errors are already caught by the shared
-  snooze/escalate logic in `RubyReactor::Worker` before they'd ever reach
-  the framework's retry layer) and `queue_as { config.queue_name }`.
-- `sidekiq_retries_exhausted` (currently an empty hook) → ActiveJob
-  equivalent is `retry_on ... do |job, error| ... end` / `discard_on`.
-
-`configuration.rb` changes: add `job_retry_count`/`queue_name` as the
-canonical attrs; keep `sidekiq_retry_count`/`sidekiq_queue` as deprecated
-aliases delegating to the new names so existing configs don't break.
-
-None of this requires touching the enqueue-side call sites in
-`reactor.rb`, `executor/*`, `map/*` — that seam already works (it just calls
-through `config.async_router`, whose value changes, not its call sites).
-The work is isolated to: `lib/ruby_reactor/worker.rb` (new),
-`lib/ruby_reactor/sweeper_job.rb` (new), the `sidekiq_workers/` →
-`adapters/sidekiq/` move + rename, `adapters/active_job/*.rb` (new, 5
-classes: `Router` + 4 job classes), and the test-helper /
-`start_sweeper!` branching described above.

data/specs/deferred-003-step-lock-declarations/checklists/requirements.md

@@ -1,51 +0,0 @@
-# Specification Quality Checklist: Step-Scoped Coordination
-
-**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:
-  - **Contention**: park the execution and retry it later rather than failing (FR-015). No
-    queue exists in a synchronous run, so that path waits then fails (FR-016) — the split is
-    documented rather than hidden.
-  - **Scope**: all five primitives at step level (FR-002), with the two whose meaning does not
-    narrow trivially pinned down explicitly — deduplication skips the step rather than halting
-    the reactor (FR-003), strict ordering sequences that step only (FR-004).
-  - **Rollback**: exclusivity and concurrency ceilings are re-taken for compensate/undo
-    (FR-024); rate ceilings and dedup windows are not (FR-025).
-  - **Re-entrancy**: reuses the nested-workflow rules unchanged — execution-owned holds,
-    counted nesting, an execution-wide held-key registry, refusal at hand-off when ownership
-    cannot cross a process boundary, and keep-ownership-across-parks (FR-019 to FR-022,
-    FR-018).
-- "Non-technical stakeholders" is read as *developers who are not this library's
-  maintainers*: the spec names no Ruby constructs, gems, or file paths outside the verbatim
-  user input.
-- Ready for `/speckit-plan`.

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

@@ -1,154 +0,0 @@
-# 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

@@ -1,131 +0,0 @@
-# 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.