ruby_reactor 0.8.2 → 0.8.4

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

@@ -5,7 +5,7 @@
     <link rel="icon" type="image/svg+xml" href="./vite.svg" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <title>ui</title>
-    <script type="module" crossorigin src="./assets/index-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

@@ -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

@@ -7,6 +7,7 @@ require "time"
 require_relative "ruby_reactor/registry"
 require_relative "ruby_reactor/utils/code_extractor"
 require_relative "ruby_reactor/dsl/lockable" # Add this
+require_relative "ruby_reactor/dsl/retryable"
 require_relative "ruby_reactor/lock"
 require_relative "ruby_reactor/ordered_lock"
 require_relative "ruby_reactor/semaphore"
@@ -133,14 +134,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 +160,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 +181,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 +241,7 @@ module RubyReactor
         line_number: @line_number,
         code_snippet: @code_snippet,
         validation_errors: @validation_errors,
+        rollback_failures: @rollback_failures,
         backtrace: @backtrace
       }
     end
@@ -334,9 +340,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
@@ -365,8 +388,9 @@ module RubyReactor
   end
 
   # Global helper methods
+  # A step returning its own inputs (`Success(inputs)`) stores the Hash.
   def self.Success(value = nil)
-    Success.new(value)
+    Success.new(value.is_a?(Step::Inputs) ? value.to_h : value)
   end
 
   def self.Failure(error, **kwargs)

data/specs/{004-inheritable-step-class → 006-step-retry-declarations}/checklists/requirements.md

@@ -1,7 +1,7 @@
-# Specification Quality Checklist: Inheritable Step Class
+# Specification Quality Checklist: Step-Scoped Retry Declarations
 
 **Purpose**: Validate specification completeness and quality before proceeding to planning
-**Created**: 2026-09-11
+**Created**: 2026-09-25
 **Feature**: [spec.md](../spec.md)
 
 ## Content Quality
@@ -31,10 +31,11 @@
 
 ## Notes
 
-- Feature is a public-API refactor of a Ruby library, so the spec necessarily names the
-  public authoring surface (`RubyReactor::Step`, `run`, `fail!`, `call`). These are the
-  product, not implementation details; internal mechanics (prepend, singleton wrapping)
-  appear only in the Input quote and in FR-011 as things that must NOT exist.
-- Key scope decision (single authoring style, mixin removed) resolved via the decision rule
-  the description supplied; recorded under Assumptions rather than left as a clarification.
-- Items marked incomplete require spec updates before `/speckit-clarify` or `/speckit-plan`
+- The product is a library, so its user-facing DSL words (`retries`, `compose`,
+  `async_reactor`, `map`) are the user vocabulary, not implementation detail. Internal classes,
+  files, and storage are not named.
+- Resolved 2026-09-25: a direct call to a step class runs once. Only the reactor coordinates
+  retries (FR-013, Clarifications).
+- Removing reactor-wide defaults was added from the user's follow-up messages. It is US1 and is
+  delivered first as a standalone change (FR-005 to FR-007, FR-017 delivery order, FR-020
+  migration note); step class work (US2 onward) starts after it.

data/specs/006-step-retry-declarations/contracts/dsl-surface.md

@@ -0,0 +1,89 @@
+# Contract: Retry DSL Surface
+
+The public API after this feature. Anything not listed here keeps its current behavior.
+
+## 1. Removed: `retry_defaults` (Phase A)
+
+```ruby
+class PaymentReactor < RubyReactor::Reactor
+  retry_defaults max_attempts: 3   # => raises at class definition
+end
+```
+
+- Raises `RubyReactor::Error::DeprecatedDslError` (a `ValidationError`) when the class body
+  runs, whatever the arguments.
+- Message (shape): ``"`retry_defaults` has been removed from PaymentReactor: reactor-wide
+  defaults silently applied only to steps declared after them. Declare `retries` on each step
+  class (or step block) that should retry; a step with no `retries` runs once."``
+- There is no reader. `PaymentReactor.retry_defaults` with no arguments raises the same error.
+
+## 2. `retries` on a step class (Phase B)
+
+```ruby
+class ChargeCard < RubyReactor::Step
+  with_lock { |i| "card:#{i[:card_token]}" }
+  input :card_token, :string
+  retries max_attempts: 3, backoff: :exponential, base_delay: 5   # all keywords optional
+
+  def run = Success(PaymentService.charge(inputs[:card_token]))
+end
+```
+
+| Call                                   | Result                                                     |
+|----------------------------------------|------------------------------------------------------------|
+| `retries`                              | `{max_attempts: 3, backoff: :exponential, base_delay: 1}`  |
+| `retries max_attempts: 5`              | `{max_attempts: 5, backoff: :exponential, base_delay: 1}`  |
+| `retries max_attempts: 1`              | explicit "never retry"                                     |
+| `retries max_attempts: 0` / `2.5` / `"3"` | `ArgumentError` naming `ChargeCard`, `max_attempts`, value |
+| `retries backoff: :jitter`             | `ArgumentError` naming `ChargeCard`, `backoff`, value      |
+| `retries base_delay: -1`               | `ArgumentError` naming `ChargeCard`, `base_delay`, value   |
+| `ChargeCard.retry_config`              | the hash above, or `nil` if never declared                 |
+
+Inheritance: `class ChargeCardEU < ChargeCard; end` returns ChargeCard's policy from
+`retry_config`. Redeclaring in `ChargeCardEU` changes only `ChargeCardEU`.
+
+## 3. `retries` in a reactor step block (unchanged vocabulary)
+
+The same module provides it, so the table above also applies inside `step`, `async_step`,
+`compose` and `async_reactor` blocks (the error names the step, e.g. `charge_card`).
+
+```ruby
+step :charge_card do                 # inline: valid, as today
+  retries max_attempts: 3, backoff: :exponential, base_delay: 5
+  run { |args, _ctx| PaymentService.charge(args[:card_token]) }
+end
+
+step :charge_card, LegacyCharge do   # class without its own policy: valid, as today
+  retries max_attempts: 3
+end
+
+step :charge_card, ChargeCard do     # ChargeCard declares retries: REFUSED
+  retries max_attempts: 5
+end
+# => Error::ValidationError at reactor definition:
+#    "PaymentReactor step :charge_card declares `retries` inline, but ChargeCard declares it
+#     too. Keep ONE: drop the inline declaration to use ChargeCard's, or remove it from
+#     ChargeCard. To vary the policy per workflow, subclass ChargeCard."
+```
+
+## 4. Effective policy introspection
+
+```ruby
+PaymentReactor.steps[:charge_card].retry_config  # => {max_attempts: 3, backoff: …, base_delay: …}
+PaymentReactor.steps[:charge_card].retry_source  # => :step_class | :step_block | :none
+PaymentReactor.steps[:charge_card].retryable?    # => max_attempts > 1
+```
+
+## 5. Direct invocation
+
+`ChargeCard.run(args)` / `.call(args)` runs **once**, whatever `retries` says, and returns
+its `Failure` to the caller. Only a reactor coordinates retries. (Locks, by contrast, are
+taken on a direct call.)
+
+## 6. Runtime (unchanged)
+
+Under a class policy, retry behavior is the same as under a step-block policy with the same
+values: which failures are retried (`Failure#retryable?`, `fail!(retry: false)`, input
+contract failures), attempt counting across requeues, in-process sleep versus background
+`perform_in`, `MaxRetriesExhaustedFailure`, the `retry_attempt` middleware event, and
+compensation after the last attempt.

data/specs/006-step-retry-declarations/data-model.md

@@ -0,0 +1,58 @@
+# Data Model: Step-Scoped Retry Declarations
+
+No persisted data changes. The per-execution attempt record (`RetryContext#step_attempts`)
+and its serialization stay the same. Everything below is class-level configuration held in
+memory.
+
+## Retry Policy
+
+A frozen-shape hash. It is the same shape every consumer reads today.
+
+| Key            | Type                              | Default        | Validation (declaration time, `ArgumentError`) |
+|----------------|-----------------------------------|----------------|------------------------------------------------|
+| `max_attempts` | Integer                           | `3` (declared) | `Integer`, `>= 1`                              |
+| `backoff`      | Symbol                            | `:exponential` | one of `:exponential`, `:linear`, `:fixed`     |
+| `base_delay`   | Numeric (incl. AS::Duration)      | `1`            | `Numeric`, `>= 0`                              |
+
+`NO_RETRIES = { max_attempts: 1, backoff: :exponential, base_delay: 1 }` is the effective
+policy when nothing is declared. `retryable?` is false for it.
+
+## Declaration holders
+
+| Holder                              | How it declares                      | Reader                   | Inheritance                            |
+|-------------------------------------|--------------------------------------|--------------------------|----------------------------------------|
+| Step class (`< RubyReactor::Step`)  | `retries …` in class body            | `.retry_config` (or nil) | copied to subclass on `inherited`      |
+| `StepBuilder` (step / async_step)   | `retries …` in the reactor step block | `#retry_config` (or nil) | n/a                                    |
+| `ComposeBuilder`, `AsyncReactorBuilder` | `retries …` in the block         | `#retry_config` (or nil) | n/a                                    |
+| Reactor class                       | **none**: `retry_defaults` raises `DeprecatedDslError` | n/a | n/a                            |
+
+All four `retries` entry points come from one module (`Dsl::Retryable`), so vocabulary,
+defaults and validation are identical.
+
+## Effective policy (`StepConfig`)
+
+```text
+StepConfig#retry_config
+  = own (from builder)                         -> source :step_block
+  | impl.retry_config  (impl responds, non-nil) -> source :step_class
+  | NO_RETRIES                                  -> source :none
+
+StepConfig#retry_source  ∈ { :step_block, :step_class, :none }
+```
+
+Resolved lazily on each read, like `lock_config`. The reactor class is never consulted.
+
+## Definition-time rules
+
+| Rule                                                               | Where                         | Error                        |
+|--------------------------------------------------------------------|-------------------------------|------------------------------|
+| Invalid policy value                                               | `Retryable#retries`           | `ArgumentError`              |
+| `retries` in step block **and** on `impl` (own or inherited)       | `StepBuilder#build`           | `Error::ValidationError`     |
+| `retry_defaults` called on a reactor                               | `Dsl::Reactor.retry_defaults` | `Error::DeprecatedDslError`  |
+
+## Runtime (unchanged)
+
+The attempt record is `RetryContext#step_attempts[step_name]`, kept through serialization and
+requeue. `RetryManager` (in-process and background requeue) and `StepWorker` (`async_step`)
+compare it with `step_config.retry_config[:max_attempts]`. A direct `Step.run` never
+consults a policy (`StepCoordination#retry_pending?` is false for direct calls).

data/specs/006-step-retry-declarations/plan.md

@@ -0,0 +1,187 @@
+# Implementation Plan: Step-Scoped Retry Declarations
+
+**Branch**: `retry_confs_in_steps` | **Date**: 2026-09-25 | **Spec**: [spec.md](spec.md)
+
+**Input**: Feature specification from `specs/006-step-retry-declarations/spec.md`
+
+## Summary
+
+Two phases, delivered in this order (spec FR-017):
+
+- **Phase A: remove `retry_defaults`.** `retry_defaults` becomes a stub that raises
+  `DeprecatedDslError`. Every read of it is deleted: the three builder fallbacks, the
+  `RetryManager` fallback, the `TestSubject` copies, and the `included` ivar. After this,
+  `StepConfig`'s policy can come only from its own block. Ships as a standalone `feat!`
+  commit with the suite green.
+- **Phase B: `retries` on step classes.** A new `Dsl::Retryable` module, modeled on
+  `Dsl::Lockable::ClassMethods`, provides `retries` with validation, a `retry_config` reader,
+  and `inherited` propagation. `RubyReactor::Step` extends it; the step, compose and
+  async-reactor builders include it, which replaces their duplicated `retries` methods.
+  `StepConfig#retry_config` resolves lazily in the order own declaration, then
+  `impl.retry_config`, then `NO_RETRIES`, the same way `lock_config` does. Declaring the policy
+  both on the class and in the step block is refused, like locks.
+
+Runtime retry code (`RetryManager`, `StepWorker`, `RetryContext`) is unchanged apart from
+deleting the fallback. Direct `Step.run` already never retries (research R7).
+
+## Technical Context
+
+**Language/Version**: Ruby >= 3.0
+
+**Primary Dependencies**: existing only: dry-validation, Sidekiq/ActiveJob adapters. No new
+gems.
+
+**Storage**: Redis (unchanged; no new keys, no serialization change)
+
+**Testing**: RSpec against real Redis (`bundle exec rspec`); `demo_app` RSpec with the shipped
+`RubyReactor::RSpec` surface; RuboCop
+
+**Target Platform**: Ruby gem (MRI), sync and background (Sidekiq/ActiveJob) execution
+
+**Project Type**: library (gem) + `demo_app` Rails integration example
+
+**Performance Goals**: no runtime cost beyond one extra `||` per `retry_config` read
+
+**Constraints**: public API change. The removal is breaking (`feat!`, migration note). Phase B
+is additive. Behavior for reactors that never used `retry_defaults` must not change.
+
+**Scale/Scope**: about 8 lib files touched, 1 new module; ~4 spec files migrated; 1 new spec
+file; 1 demo reactor + rake task + spec; ~10 docs files
+
+## Constitution Check
+
+*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*
+
+| Principle | Status | Notes |
+| --- | --- | --- |
+| I. Gem-first | ✅ | All code in `lib/`, reachable via `require "ruby_reactor"`; no host coupling. |
+| II. Saga integrity | ✅ | Compensation after the last attempt is unchanged; the new specs cover exhaust-then-compensate on class steps. |
+| III. Test-first, real infra | ✅ | Each phase starts with failing specs; background paths drained against real Redis; no Redis mocking. |
+| IV. Observability | ✅ | `retry_attempt` events and `MaxRetriesExhaustedFailure` unchanged; `StepConfig#retry_source` adds introspection. |
+| V. Simplicity & SemVer | ✅ | One module replaces 3 duplicated methods (net deletion); no policy object (R3). Removal ships as `feat!` with a migration note (R9). |
+| VI. Demo-app proof | ✅ | `StepRetryDemoReactor` + `demo:step_retry` + spec using only the shipped matchers (`have_retried_step`, `be_failure`, `be_success`). |
+| Workflow: class-based steps in docs/examples | ✅ | Docs lead with the step class form. |
+
+- [x] Documentation impact identified: which `README.md` sections and which file(s) under
+      `./documentation` this feature will require updating (Constitution Development Workflow;
+      carried into tasks.md as a required task):
+  - **Phase A**: `documentation/retry_configuration.md` (delete "Reactor-Level Defaults", add
+    a "Migrating from `retry_defaults`" section), `documentation/core_concepts.md` (≈360,
+    remove "Uses reactor defaults"), `documentation/background_and_async.md` (≈482-530),
+    `documentation/examples/{inventory_management,order_processing,payment_processing}.md`,
+    the `demo_app/documentation/` copies of the same, README line 1486 ("reactor or step
+    level"), and `llms*.txt` if they mention it.
+  - **Phase B**: `documentation/retry_configuration.md` (step class form first; precedence;
+    conflict rule; subclassing to vary per workflow; direct call runs once, unlike locks),
+    `documentation/core_concepts.md` retry section, the README Features bullet (line 24),
+    and the README Retry Configuration blurb.
+
+**Post-design re-check**: ✅ no violations. Complexity Tracking is empty.
+
+## Project Structure
+
+### Documentation (this feature)
+
+```text
+specs/006-step-retry-declarations/
+├── spec.md
+├── plan.md              # this file
+├── research.md          # Phase 0
+├── data-model.md        # Phase 1
+├── quickstart.md        # Phase 1
+├── contracts/
+│   └── dsl-surface.md   # Phase 1
+├── checklists/
+│   └── requirements.md
+└── tasks.md             # /speckit-tasks
+```
+
+### Source Code (repository root)
+
+```text
+lib/ruby_reactor/
+├── dsl/
+│   ├── retryable.rb              # NEW (B): retries + validation, retry_config, inherited
+│   ├── reactor.rb                # A: retry_defaults -> DeprecatedDslError stub; drop included ivar
+│   ├── step_builder.rb           # A: drop reactor fallback; B: include Retryable, drop own
+│   │                             #    retries, check_retry_conflict!, StepConfig lazy
+│   │                             #    retry_config + retry_source + NO_RETRIES
+│   ├── compose_builder.rb        # A: drop fallback; B: include Retryable, drop own retries
+│   └── async_reactor_builder.rb  # A: drop fallback; B: include Retryable, drop own retries
+├── step.rb                       # B: extend Dsl::Retryable
+├── executor/retry_manager.rb     # A: drop reactor_class.retry_defaults fallbacks
+└── rspec/test_subject.rb         # A: drop 3 @retry_defaults copies
+
+spec/
+├── async_retry_dsl_spec.rb               # A: retry_defaults example -> asserts removal error
+├── ruby_reactor_spec.rb                  # A: move retry_defaults into step-level retries
+├── support/order_processing_reactor.rb   # A: same
+└── ruby_reactor/step_retries/*_spec.rb  # NEW: removal (A); declaration, class_policy,
+                                          #   step_block_parity, conflict, execution_paths,
+                                          #   inheritance, introspection, test_surface (B)
+
+demo_app/
+├── spec/support/order_processing_reactor.rb      # A: drop retry_defaults
+├── app/reactors/step_retry_demo_reactor.rb       # NEW (B)
+├── lib/tasks/demo_reactors.rake                  # B: demo:step_retry
+└── spec/reactors/step_retry_demo_reactor_spec.rb # NEW (B)
+```
+
+**Structure Decision**: single gem layout (`lib/`, `spec/`) plus `demo_app/`, as in every
+earlier feature. The new module lives next to `dsl/lockable.rb`, which it mirrors.
+
+## Phase A: remove `retry_defaults` (ships first, standalone)
+
+1. **Red**: change `spec/async_retry_dsl_spec.rb:23-33` to expect `DeprecatedDslError`,
+   message included. Add: a subclass of `RubyReactor::Reactor` with no retry declarations runs
+   a failing step exactly once.
+2. **Green**: stub in `dsl/reactor.rb`; delete the `included` ivar; builders pass their own
+   `@retry_config` (initialized `nil`, not `{}`); `StepConfig` defaults to `NO_RETRIES` when
+   nil; `RetryManager#calculate_backoff_delay` reads only `step_config.retry_config` (drop the
+   now-unused `reactor_class` argument or rename it `_reactor_class`); delete the
+   `TestSubject` copies.
+3. Migrate `spec/ruby_reactor_spec.rb`, `spec/support/order_processing_reactor.rb` and
+   `demo_app/spec/support/order_processing_reactor.rb` to step-level `retries` on the steps
+   that relied on the default. Keep their assertions unchanged, so behavior is proven
+   identical.
+4. Docs (see the Constitution Check list) and the `BREAKING CHANGE:` footer with the
+   migration text.
+5. Gate: `grep retry_defaults` is clean except the stub and its spec; `rspec` and `rubocop`
+   are green. Commit `feat!: remove reactor-wide retry_defaults`.
+
+## Phase B: `retries` on step classes
+
+1. **Red**: `spec/ruby_reactor/step_retries/*_spec.rb` (one file per story) covering the quickstart table.
+2. **Green**:
+   - `Dsl::Retryable` (R3, R4): `BACKOFF_STRATEGIES`, `retries`, `retry_config`,
+     `inherited`.
+   - `Step` extends it. `StepBuilder`, `ComposeBuilder` and `AsyncReactorBuilder` include it
+     and delete their own `retries`; remove `retry_config` from `StepBuilder`'s
+     `attr_accessor`.
+   - `StepConfig` (R5): store `@retry_config` raw; lazy `retry_config`; `retry_source`.
+   - `StepBuilder#check_retry_conflict!` (R6), called from `build` next to
+     `check_coordination_conflicts!`.
+3. **Demo** (Constitution VI): `StepRetryDemoReactor` with class steps, showing
+   succeed-after-retry, exhaust-then-compensate, and a single-attempt undeclared step, using
+   `base_delay` near zero so the task runs fast; the `demo:step_retry` task depends on
+   `[:environment, :flush_redis]`; the spec uses only `test_reactor`, `failing_at`/`mock_step`,
+   `be_success`, `be_failure` and `have_retried_step`.
+4. Docs (Phase B list above).
+5. Gate: `rspec`, `rubocop`, and the docker demo run. Commit `feat: declare retries on step
+   classes`.
+
+## Risks
+
+- **Hidden `{}`-vs-`nil` assumptions.** Code that checks `retry_config.empty?` breaks once
+  the builders pass `nil`. Mitigation: `grep -rn "retry_config" lib` during Phase A; every
+  consumer goes through `StepConfig#retry_config`, which never returns nil.
+- **`name` collision in validation messages.** Builders' `name` is the step symbol and
+  `Step.name` is the class name. Both are what the message should show. An anonymous step
+  class has `name == nil`, so fall back to `inspect`.
+- **Rubocop.** `inherited` in an included module triggers no cop today (Lockable does the
+  same). The unused `reactor_class` argument in `RetryManager` needs removing or renaming to
+  `_reactor_class`.
+
+## Complexity Tracking
+
+No violations. The table is empty.