ruby_reactor 0.8.3 → 0.8.4

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"
@@ -387,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/006-step-retry-declarations/checklists/requirements.md

@@ -0,0 +1,41 @@
+# Specification Quality Checklist: Step-Scoped Retry Declarations
+
+**Purpose**: Validate specification completeness and quality before proceeding to planning
+**Created**: 2026-09-25
+**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
+
+- 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.

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

@@ -0,0 +1,80 @@
+# Quickstart: Validating Step-Scoped Retry Declarations
+
+The API is in [contracts/dsl-surface.md](contracts/dsl-surface.md) and the resolution rules
+are in [data-model.md](data-model.md).
+
+## Prerequisites
+
+- Ruby >= 3.0, `bundle install`
+- Redis reachable by the suite (Constitution III): `docker compose up -d redis` or a local
+  `redis-server`
+- For the demo: `docker compose up` (see the constitution, Principle VI §4)
+
+## Phase A: `retry_defaults` removed (validate before starting Phase B)
+
+1. The removal error fires at definition time:
+
+   ```bash
+   bundle exec ruby -Ilib -e 'require "ruby_reactor"; Class.new(RubyReactor::Reactor) { retry_defaults max_attempts: 3 }'
+   ```
+
+   Expected: `RubyReactor::Error::DeprecatedDslError`, with a message pointing to step-level
+   `retries`.
+
+2. No references remain outside the removal stub and its spec:
+
+   ```bash
+   grep -rn "retry_defaults" lib spec demo_app README.md documentation llms*.txt
+   ```
+
+   Expected: only `lib/ruby_reactor/dsl/reactor.rb` (the stub) and the spec asserting it
+   raises.
+
+3. The full suite and lint are green:
+
+   ```bash
+   bundle exec rspec && bundle exec rubocop
+   ```
+
+## Phase B: `retries` on step classes
+
+Run the feature specs, then the full suite:
+
+```bash
+bundle exec rspec spec/ruby_reactor/step_retries/
+bundle exec rspec && bundle exec rubocop
+```
+
+What the feature spec must show (each maps to a spec story):
+
+| Scenario | Expected | Spec |
+| --- | --- | --- |
+| Class declares 3 attempts, body fails twice, reactor has no wiring | success on attempt 3 | US2 |
+| Same class, body always fails | `MaxRetriesExhaustedFailure`, 3 attempts, compensation runs | US2 |
+| Inline `retries` vs class `retries`, same values and failures | same attempts, delays, outcome | US3 |
+| Class `retries` + step block `retries` | `ValidationError` at reactor definition | US4 |
+| Class `retries max_attempts: 1` | not retried | US4 |
+| Same class under `background all: true` (drained) | attempts requeued, same count | US5 |
+| Same class as `async_step` | `StepWorker` honors the class policy | US5 |
+| Subclass without / with its own `retries` | inherits / overrides; parent unchanged | US6 |
+| `failing_at` / `mock_step` on a class step | still retried under the class policy | US7 |
+| `steps[:x].retry_source` | `:step_class` / `:step_block` / `:none` | US7 |
+| `ChargeCard.run(args)` directly, failing | one attempt, `Failure` returned | FR-013 |
+| `retries backoff: :bogus` on a class | `ArgumentError` at class definition | FR-004 |
+
+## Demo acceptance run
+
+```bash
+docker compose run --rm demo-app bin/rails demo:step_retry
+docker compose run --rm demo-app bundle exec rspec spec/reactors/step_retry_demo_reactor_spec.rb
+```
+
+The rake task prints three outcomes:
+
+1. a class step that succeeds after retries (`attempts=3 success?=true`);
+2. a class step that exhausts its retries, with an earlier step compensated
+   (`success?=false attempts=3 compensated=true`);
+3. a step with no declaration that is attempted once (`attempts=1`).
+
+When running from a git worktree, pass an isolated compose project name (`-p <name>`) so
+the fixed container names don't collide with another worktree's stack.

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

@@ -0,0 +1,194 @@
+# Research: Step-Scoped Retry Declarations
+
+Every decision below was checked against the code on `retry_confs_in_steps` (base `900d6522`).
+Nothing in Technical Context was left open.
+
+## R1 — How `retry_defaults` works today
+
+**Finding**:
+
+- `Dsl::Reactor.included` sets `@retry_defaults = {max_attempts: 3, …}` on
+  `RubyReactor::Reactor` **only** (`lib/ruby_reactor/dsl/reactor.rb:14`). Nothing copies it to
+  subclasses.
+- The reader `retry_defaults` lazily returns `{max_attempts: 1, …}` for any subclass that never
+  called it (`dsl/reactor.rb:58-68`).
+- `StepBuilder#build`, `ComposeBuilder#build` and `AsyncReactorBuilder#build` **snapshot**
+  `@reactor.retry_defaults` into `retry_config` when their own block declared none
+  (`step_builder.rb:163`, `compose_builder.rb:74`, `async_reactor_builder.rb:52`). So a
+  `retry_defaults` line only affects steps declared *after* it. This is the "unpredictable"
+  behavior the user called out.
+- `RetryManager#calculate_backoff_delay` falls back to `reactor_class.retry_defaults` for
+  `backoff`/`base_delay` (`executor/retry_manager.rb:29-30`).
+- `RSpec::TestSubject` copies `@retry_defaults` into its three generated execution subclasses
+  (`rspec/test_subject.rb:559, 651, 739`).
+
+**Consequence**: a reactor that never called `retry_defaults` already runs undeclared steps
+exactly once. Removing the feature changes behavior only for reactors that call it (spec US1
+scenario 3).
+
+**Callers to migrate**: `spec/async_retry_dsl_spec.rb:23-33`, `spec/ruby_reactor_spec.rb:14, 221`,
+`spec/support/order_processing_reactor.rb:28`, `demo_app/spec/support/order_processing_reactor.rb:28`,
+plus docs (see R10).
+
+## R2 — How to remove `retry_defaults`
+
+**Decision**: replace the method with a stub that raises `Error::DeprecatedDslError` when the
+class is defined, and delete every read of it (the builder fallbacks, the `RetryManager`
+fallback, the `TestSubject` copies, and the `included` ivar).
+
+**Rationale**: this is exactly how the project removed `async true` on reactors
+(`dsl/reactor.rb:48-56`) and `async` in step/compose blocks (`step_builder.rb:119-131`). A call
+fails loudly at load time with a migration message instead of being silently ignored. The
+error names the reactor (`name` or `"anonymous reactor"`) and says: declare `retries` on each
+step class or step block that needs it.
+
+**Alternatives considered**:
+
+- *Deprecation warning, keep working for one release*: rejected. The user asked to remove it
+  altogether, and keeping it alive also keeps the ordering bug from R1.
+- *Delete the method outright (`NoMethodError`)*: rejected. It gives no migration hint and
+  breaks the project's established removal pattern.
+
+**Delivery**: this is Phase A of the plan and ships first, as its own commit, with the full
+suite green (spec FR-017).
+
+## R3 — Where `retries` lives for a step class
+
+**Decision**: a new module `RubyReactor::Dsl::Retryable`, modeled on `Dsl::Lockable::ClassMethods`,
+containing:
+
+- `retries(max_attempts: 3, backoff: :exponential, base_delay: 1)`: validates, then stores
+  `@retry_config`;
+- `retry_config`: the reader, `nil` when nothing was declared;
+- `inherited(subclass)`: copies `@retry_config` to the subclass, exactly like
+  `Lockable#inherited`.
+
+`RubyReactor::Step` **extends** it (class-level DSL). `StepBuilder`, `ComposeBuilder` and
+`AsyncReactorBuilder` **include** it, which replaces their three identical `retries` methods.
+The same is already done with `Lockable::ClassMethods` in `StepBuilder` (`step_builder.rb:8`).
+
+**Rationale**: the user asked us to emulate the locks design. One module gives both forms the
+same vocabulary, the same defaults and the same validation (spec FR-001/FR-002/FR-004), and it
+removes duplication instead of adding it. Inheritance by copying in `inherited` matches locks,
+so a subclass redeclaring its policy leaves its parent and siblings untouched (FR-010).
+
+**Alternatives considered**:
+
+- *Walk `superclass` in the reader (like `input_contract`)*: works too, but it would be a
+  second inheritance mechanism next to Lockable's. Rejected for consistency.
+- *A `RetryPolicy` value object*: rejected. There is only one consumer shape (a 3-key hash
+  read by `RetryManager`/`StepWorker`), so an object would be an abstraction with no second
+  use case (Constitution V).
+
+## R4 — Validation of retry values
+
+**Decision**: `Retryable#retries` raises `ArgumentError` when the declaration is made if:
+
+- `max_attempts` is not an `Integer` `>= 1`;
+- `backoff` is not one of `%i[exponential linear fixed]`;
+- `base_delay` is not a `Numeric` `>= 0`.
+
+The message names the owner (`name`: the step symbol in a builder, the class name on a step
+class), the option and the bad value.
+
+**Rationale**: `ArgumentError` at declaration time is what `with_period`, `with_rate_limit`
+and `validate_rollback_wait!` already do (`dsl/lockable.rb`). An unknown backoff strategy
+fails today only at the first retry (`RetryContext.calculate_backoff_delay` raises
+`ArgumentError`, `retry_context.rb:94`), which can be in production, days later.
+`ActiveSupport::Duration` (`5.seconds`) passes the `Numeric` check, because
+`Duration#is_a?` delegates to its value, so the documented Rails idiom keeps working.
+
+**Behavior change**: `max_attempts: 0`, which today means "no retry", is now refused and must
+be written `max_attempts: 1` (spec Assumptions). It goes in the migration note.
+
+## R5 — Effective policy and precedence on `StepConfig`
+
+**Decision**: `StepConfig` stores the builder's own declaration (`nil` when none) and resolves
+it lazily, the same way `lock_config` does (`step_builder.rb:286-304`):
+
+```text
+retry_config  = own declaration || impl.retry_config (if impl responds) || NO_RETRIES
+retry_source  = :step_block | :step_class | :none
+```
+
+`NO_RETRIES = { max_attempts: 1, backoff: :exponential, base_delay: 1 }.freeze`.
+`retryable?`, `RetryManager`, `StepWorker` and `StepCoordination#retry_pending?` keep reading
+`retry_config` unchanged. Every hash now carries all three keys, so the reactor fallbacks in
+`RetryManager` are unnecessary and removed in Phase A.
+
+**Rationale**: resolving lazily through `impl` is what makes the class policy apply on every
+path that already consults `step_config.retry_config`, with no per-path changes: the
+in-process `RetryManager`, the background requeue, `StepWorker` for `async_step`, and resume
+(FR-011/FR-012). `retry_source` covers the introspection requirement (FR-014) with one method.
+
+**Alternatives considered**: snapshotting `impl.retry_config` at build time. Rejected: it
+diverges from the lock readers and would miss a class policy declared after the reactor
+references the class (for example after a reopen or reload).
+
+## R6 — Conflict between class and step block
+
+**Decision**: `StepBuilder#build` gains `check_retry_conflict!`, next to
+`check_coordination_conflicts!`. It raises `Error::ValidationError` when the block declared
+`retries` **and** `@impl.respond_to?(:retry_config) && @impl.retry_config`. The message has
+the same shape as the lock one: `"<Reactor> step :<name> declares `retries` inline, but
+<Class> declares it too. Keep ONE: …"`, and it also mentions subclassing as the way to vary
+the policy per workflow.
+
+**Rationale**: FR-009 asks for the same rule as locks. An inherited class policy counts as a
+declaration, since `retry_config` returns the copied value.
+
+`ComposeBuilder` and `AsyncReactorBuilder` need no check: their `impl` is an internal
+`ComposeStep`/`AsyncReactorStep` that never declares retries.
+
+## R7 — Direct invocation (clarified: runs once)
+
+**Finding**: `Step.run` never enters `RetryManager`. `StepCoordination#retry_pending?` already
+returns `false` for direct calls (`context_state?` is `!@direct && …`,
+`step_coordination.rb:533-540, 679-681`), and the existing comment says so: "A direct call has
+no retry policy of its own — it is never retried."
+
+**Decision**: no runtime change. Add one spec proving that a step class declaring
+`retries max_attempts: 3` and called directly runs once and returns its failure. Document it
+in `retry_configuration.md` and next to the direct-call docs, contrasting it with locks
+(FR-013).
+
+## R8 — Test surface (`TestSubject`, matchers)
+
+**Finding**: `mock_step` and `failing_at` replace only `@run_block` on the step config
+(`test_subject.rb:797-826`), so `impl`, and with it the class policy, is kept. The
+`have_retried_step` matcher (`rspec/matchers.rb:130`) reads attempt counts from the context,
+not from the declaration.
+
+**Decision**: no new matcher. Delete the three `@retry_defaults` copies (Phase A). Add specs
+proving that `failing_at`/`mock_step` on a class step still retries under the class policy
+(FR-015).
+
+## R9 — Versioning
+
+**Finding**: the version is `0.8.3`, managed by release-please. Earlier breaking removals
+were released as `feat!` with a `⚠ BREAKING CHANGES` section and a **Migration:** line in
+`CHANGELOG.md` (for example `async true`, `CHANGELOG.md:329`).
+
+**Decision**: Phase A lands as a `feat!:` commit whose `BREAKING CHANGE:` footer carries the
+migration text. Release-please generates the CHANGELOG entry from it. The pre-1.0 bump size
+is release-please's call, as with earlier breaking releases. Phase B is a plain `feat:`.
+
+## R10 — Documentation and demo impact
+
+**`retry_defaults` appears in**:
+
+- `documentation/retry_configuration.md` (the "Reactor-Level Defaults" section) and
+  `documentation/core_concepts.md` (≈ line 360, "Uses reactor defaults");
+- `documentation/background_and_async.md` (≈ lines 482-530);
+- `documentation/examples/{inventory_management,order_processing,payment_processing}.md`;
+- the stale copies under `demo_app/documentation/` (`async_reactors.md`, the same `examples/`
+  files, `retry_configuration.md`).
+
+**README**: the Features bullet (line 24) and the Retry Configuration blurb (line 1486,
+"configure retries at the reactor or step level") both need rewording.
+
+**Demo (Constitution VI)**: there is no retry-specific demo today. Retries appear only inline
+in `signal_demo_reactor.rb` and `order_processing_reactor.rb`. Add `StepRetryDemoReactor` using
+class steps, the `demo:step_retry` rake task, and
+`demo_app/spec/reactors/step_retry_demo_reactor_spec.rb`, modeled on
+`step_lock_demo_reactor.rb` and `inheritable_step_demo_reactor_spec.rb`.