ruby_reactor 0.8.2 → 0.8.3

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

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

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

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

@@ -1,196 +0,0 @@
-# Phase 0 Research: Step-Scoped Coordination
-
-**Feature**: `specs/003-step-lock-declarations/` | **Date**: 2026-09-10
-
-Findings come from reading the current implementation. File references are to the state of
-`step_validations` at the time of writing.
-
-## Current state
-
-| Concern | Where it lives |
-|---|---|
-| Declaration DSL | `Dsl::Lockable::ClassMethods` — `with_lock`, `with_semaphore`, `with_rate_limit`, `with_period`, `with_ordered_lock`. Included into `Reactor` only. |
-| Acquisition | `Executor#acquire_locks` → `check_rate_limit`, `acquire_exclusive_lock`, `acquire_semaphore` (`executor.rb:350-360`) |
-| Key derivation | `config[:key_proc].call(@context.inputs)` — reactor inputs |
-| Owner | root context id (`executor.rb:501`) — the basis of re-entrancy |
-| Held-key registry | `root.private_data[:held_lock_keys]` |
-| Deadlock guard | `Step::AsyncReactorStep.detect_lock_deadlock` (`async_reactor_step.rb:65`) — refuses dispatch when the child declares a key the parent holds |
-| Park / resume | `park_held_primitives!` + `consume_parked_primitives!`; `Lock#detach` / `#reattach` |
-| Contention split | `Executor#contention_wait` (`executor.rb:566`) — `0` inside a worker (snooze instead of blocking), configured wait otherwise |
-| Step retry requeue | `RetryManager#requeue_job_for_step_retry` — sets `current_step`, persists root context, `perform_in(delay, …)`, returns `RetryQueuedResult` |
-| Ordered lock | `Executor::OrderedLockSupport` — nonce assigned at enqueue in `Reactor#run`, stashed in `private_data[:ordered_lock]`, gate at execute/resume, advance on terminal reactor result, heartbeat thread |
-| Compensation | `CompensationManager#compensate_step` / `#undo_step` |
-| Dashboard | `Web::CoordinationSerializer` — reads `reactor_class.lock_config` etc. |
-
-### Finding 1 — the DSL needs no redesign, only a second host
-
-`Dsl::Lockable::ClassMethods` is already a self-contained module of five macros whose only
-contract is "a key proc that receives a hash". Reactor passes `context.inputs`; a step would
-pass its resolved arguments. The declaration surface is reusable as-is, including its
-`inherited` hook for subclass propagation.
-
-### Finding 2 — `contention_wait` already encodes the sync/worker split the spec asks for
-
-FR-015/FR-016's split is not new policy: `contention_wait` returns `0` inside a worker so the
-job snoozes rather than blocking a thread, and the configured wait outside. Step-level
-coordination gets the correct behavior on both paths by reusing it.
-
-### Finding 3 — parking an execution at a step already exists
-
-`requeue_job_for_step_retry` persists the root context with `current_step` set and enqueues a
-delayed job; the redelivery resumes at that step. It is reached today only from retry-on-
-failure, but nothing in it is failure-specific. Step contention can reuse it verbatim with a
-contention delay, which is why FR-015 ("park, don't fail") costs one call rather than a new
-mechanism.
-
-### Finding 4 — the deadlock guard is keyed on the registry, not on reactors
-
-`detect_lock_deadlock` reads `held_lock_keys` from the root context and compares against the
-*child's* declared keys. Because step-held keys will land in the same registry, the existing
-guard covers "a step holds K, its body dispatches an async_reactor that wants K" with no
-change. It needs extending only to know about `async_step` dispatch, where the dispatched
-step class may itself declare K.
-
-### Finding 5 — ordered lock is structurally reactor-shaped
-
-The nonce is assigned in `Reactor#run` at enqueue time, before any step exists, and the
-advance fires on the *reactor's* terminal result. Its guarantee is "executions run in the
-order they were enqueued". A step-level equivalent cannot assign at enqueue, because the key
-expression reads arguments that are not resolved until the step is reached — so its guarantee
-degrades to "in the order executions reached this step", which is a materially weaker promise.
-See D8; this is the one primitive whose step-scoped meaning is not a simple narrowing.
-
-### Finding 6 — a step holding coordination across a park is nearly unreachable
-
-Argument resolution (including any blocking wait on an async result) happens *before*
-acquisition, and a step whose body is dispatched elsewhere never acquires in the dispatching
-process. The one construct that could hold coordination across a park is an interrupt step,
-whose body is split across a pause. See D6.
-
----
-
-## Decisions
-
-### D1 — Steps host the existing `Lockable` macros unchanged
-
-`RubyReactor::Step::ClassMethods` gains the same five macros by reusing
-`Dsl::Lockable::ClassMethods`; `Dsl::StepBuilder` gains them for inline steps. The key proc
-receives the step's resolved arguments instead of reactor inputs.
-
-**Rationale**: Finding 1. One declaration surface, one set of option semantics, one place to
-document. Authors already know the macros.
-
-**Alternatives rejected**: a parallel `step_lock` vocabulary — two names for one concept.
-
-### D2 — Enforcement is driven by the executor, not by a wrapper on the step
-
-A single `StepCoordination` object wraps the step body. The executor drives it, because three
-requirements are outside a step class's reach: parking the execution on contention (needs the
-requeue path), skipping acquisition for a guard-suppressed step, and re-taking coordination
-during rollback.
-
-FR-023 (direct invocation) is served by the same object, entered with `park: false` — with no
-execution to park, contention waits and then fails, exactly as the synchronous path does.
-
-**Rationale**: this deliberately differs from `002`'s decision to enforce input contracts in a
-prepended `run`. Validation is a pure function of the arguments; coordination is a property of
-the execution — it parks it, releases it, and must survive into rollback. The two belong at
-different layers, and saying so explicitly is cheaper than discovering it later.
-
-### D3 — Fixed acquisition order, mirroring the reactor's
-
-1. Ordered-lock gate (nothing else held while waiting for a turn — the existing hold-and-wait
-   guard in `OrderedLockSupport`)
-2. Period gate, fast path
-3. Rate limit
-4. Exclusive lock
-5. Semaphore
-6. Period gate, re-check under the lock (closes the both-passed race, same as
-   `executor.rb:113`)
-
-Released in reverse. Acquisition happens after guards and after argument validation — a step
-that will fail validation must not first take a lock (FR-012, and it keeps the critical
-section minimal).
-
-### D4 — Contention parks via the step-retry requeue path
-
-On `Lock::AcquisitionError`, `Semaphore::AcquisitionError`, `RateLimit::ExceededError`, or
-`OrderedLock::WaitError`:
-
-- **In a worker** (`context.inline_async_execution`): call the requeue path with a contention
-  delay and return `RetryQueuedResult`. The delay uses the primitive's own hint where it has
-  one (`retry_after_seconds` for rate limits) and a configured contention backoff otherwise.
-- **Synchronously**: `contention_wait` has already blocked for the configured wait, so the
-  error propagates as an ordinary step failure and rollback proceeds.
-
-Contention attempts are counted separately from failure retries (`retry_context` gains a
-contention counter), bounded by a configurable ceiling; exceeding it converts the park into a
-contention failure (FR-017). Counting contention against the step's `retries` budget would let
-a busy key exhaust the retries meant for genuine failures.
-
-**Alternatives rejected**: failing on both paths — the user's chosen behavior is park-and-
-retry; the sync fallback exists only because there is no queue to park into.
-
-### D5 — Re-entrancy reuses every existing primitive verbatim
-
-- **Owner** is the root context id, so a step's hold nests inside its reactor's hold on the
-  same key and inside any ancestor's (FR-019).
-- **Nesting count** is the adapter's existing re-entrancy count; the key frees at zero (FR-020).
-- **Registry**: step-held keys are pushed to and popped from `root.private_data[:held_lock_keys]`
-  exactly as reactor-held keys are (FR-021).
-- **Deadlock guard**: covered for `async_reactor` with no change (Finding 4); extended so
-  `async_step` dispatch also checks the dispatched step class's declared keys against the
-  registry (FR-022).
-- **Direct invocation** has no context, so the owner is a per-call UUID and no re-entrancy
-  applies.
-
-### D6 — Coordination on an interrupt step is refused at declaration
-
-An interrupt step's body is split across a pause, so it is the one construct where a
-step-level hold could span a park (Finding 6). Rather than extend `park_held_primitives!` to
-carry step-level holds across gaps — new state, new reattach path, new failure mode — v1
-raises at declaration time with a message pointing at reactor-level coordination for that case.
-
-Everything FR-018 requires of parked executions continues to work: it describes coordination
-the *execution* holds, which is reactor-level and unchanged.
-
-### D7 — Step-level period skips the step
-
-Reactor-level `with_period` halts the whole reactor when the bucket is already marked. At step
-level that would kill workflows over one deduplicated step, so the step returns `Skipped` and
-the workflow continues (FR-003). The bucket is marked when the step's work succeeds.
-
-### D8 — Step-level ordered lock: nonce assigned on first arrival, sequenced last
-
-The nonce is assigned when an execution first reaches the step, stashed per-step in
-`private_data`, and reused across contention redeliveries. The gate advances when the step
-reaches a terminal result. Strict chain failure short-circuits that step with `Skipped` rather
-than halting the reactor (FR-004).
-
-**Honest caveat**: per Finding 5 this delivers "ordered by arrival at the step", not "ordered
-by enqueue". For a reactor whose first step is the ordered one, the two coincide; the further
-into a workflow the step sits, the weaker the guarantee. This must be documented on the macro
-itself, not just in a spec.
-
-**Sequencing**: this primitive is roughly the same implementation weight as the other four
-combined — per-step nonce state, per-step heartbeat, per-step advance-on-terminal, poison-pill
-and strict-chain handling at step granularity. It is the last phase, and it is the piece to
-cut first if the schedule tightens: phases 1-6 deliver the whole of US1-US4 and US6-US8 without
-it. Recorded in Complexity Tracking.
-
-### D9 — Observability extends the existing surfaces
-
-Middleware events gain the step name; `Web::CoordinationSerializer` learns to read step-level
-configs alongside reactor-level ones; a contention-parked execution is reported distinctly
-from a failure, reusing the `:snooze_reactor` precedent (`executor.rb:166`) so a snooze round
-does not appear as a phantom failure.
-
-## Open risks
-
-| Risk | Mitigation |
-|---|---|
-| Contention behaves differently sync vs. worker | Inherent to the chosen behavior; `contention_wait` makes it one branch, and it is called out in the macro's own documentation. |
-| A busy key snoozes an execution indefinitely | Bounded contention counter (D4), separate from the failure-retry budget. |
-| Step-level ordered lock's weaker guarantee is mistaken for the reactor-level one | Documented on the macro; demo shows arrival-order explicitly. |
-| Lock TTL shorter than a slow step's work | Auto-extend applies to step holds exactly as to reactor holds. |
-| Compensation stalls on a contended key | Compensation waits then reports (FR-026); it never parks, because rollback is already mid-failure. |