ruby_reactor 0.7.0 → 0.8.0

data/specs/004-inheritable-step-class/plan.md

@@ -0,0 +1,174 @@
+# Implementation Plan: Inheritable Step Class
+
+**Branch**: `004-inheritable-step-class` | **Date**: 2026-09-11 | **Spec**: [spec.md](./spec.md)
+
+**Input**: Feature specification from `/specs/004-inheritable-step-class/spec.md`
+
+**Note**: This template is filled in by the `/speckit-plan` command. See `.specify/templates/plan-template.md` for the execution workflow.
+
+## Summary
+
+Replace the mixin-based step authoring surface (`include RubyReactor::Step` on a plain
+class + `def self.run(args, context)`, with input enforcement hacked in via
+`singleton_class.prepend`) with a single inheritable base class, `RubyReactor::Step`. A
+step author subclasses it, declares `input`/`validate_inputs` on the class exactly as
+today, and writes `run`/`undo`/`compensate` as **instance** methods that read validated
+inputs and the context through accessors. The base class's class-level `run` (aliased
+`call`), `undo`, and `compensate` become the library's one entry point per lifecycle
+action: build a fresh instance, enforce the input contract, invoke the instance method,
+and translate any `StepSignals` throw into the matching result wrapper — all as ordinary,
+readable method calls instead of a prepended module. Owning the signal catch in the base
+class also closes a latent bug: `StepWorker` has no catch today, so a `fail!` inside a
+class step run by `async_step`/`background` currently surfaces as an `UncaughtThrowError`
+(research.md D4). No dual authoring style, no backward-compatibility shim: the mixin form
+is deleted, and every internal step (`ComposeStep`, `MapStep`, `AsyncReactorStep`), every
+demo step, and every spec step migrates to the new class in this change.
+
+## Technical Context
+
+**Language/Version**: Ruby >= 3.0.0 (gemspec `required_ruby_version`, unchanged)
+
+**Primary Dependencies**: `dry-validation` ~> 1.10 (existing, unchanged — input contract
+enforcement already built on it via `RubyReactor::Validation`); no new runtime dependency
+
+**Storage**: N/A for this feature — no schema/persistence format changes. Serialization of
+step arguments (`ContextSerializer`) is unaffected because it operates on plain
+hashes/context, not on step instances.
+
+**Testing**: RSpec (existing `spec/` suite + `demo_app/spec/reactors/` per Constitution
+Principle VI); Redis required and reachable per Constitution Principle III — no test
+strategy change, only the step classes under test change shape.
+
+**Target Platform**: Ruby gem, consumed by Rails/plain-Ruby host applications; no
+platform-specific change.
+
+**Project Type**: Single library project (gem) — `lib/ruby_reactor/`, `spec/`, plus the
+`demo_app/` Rails integration example mandated by Principle VI.
+
+**Performance Goals**: No new performance target. One additional object allocation per
+step invocation (the step instance, replacing the singleton-class call) is expected to be
+negligible relative to existing Redis I/O per step; this plan carries no dedicated
+benchmark task because the spec sets no throughput/latency success criterion.
+
+**Constraints**: Every existing execution path (synchronous, async worker, retry,
+compensation/undo, compose, map, RSpec test-subject interception) MUST keep producing
+identical outcomes (spec User Story 2); the base class MUST NOT intercept or wrap
+author-defined methods (spec FR-011); no compatibility shim (spec FR-012, project
+IMPORTANT note — no production usage yet).
+
+**Scale/Scope**: Touches one core file (`lib/ruby_reactor/step.rb`), the three built-in
+step implementations, every step-shaped spec support file and example under `spec/` and
+`demo_app/`, and the step-authoring sections of `README.md` and `./documentation`. No new
+files outside `lib/ruby_reactor/step/` are structurally required; this is a targeted
+internal refactor of an existing subsystem, not new surface area.
+
+## Constitution Check
+
+*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*
+
+- **I. Gem-First Design** — PASS. `RubyReactor::Step` stays a plain Ruby class reachable
+  via `require "ruby_reactor"`, no host-application coupling introduced, no new optional
+  integration added.
+- **II. Saga Pattern Integrity (NON-NEGOTIABLE)** — PASS, with explicit verification
+  required. Compensation/undo must keep working identically per-step (spec User Story 2,
+  scenarios 3–5); Phase 1 design and the resulting tasks MUST prove undo/compensate run on
+  a fresh instance from stored values only (no leftover run-time instance state crossing
+  process boundaries in async execution) — this is the highest-risk gate for this feature
+  and is called out explicitly in Complexity Tracking below.
+- **III. Test-First with Real Infrastructure** — PASS. No test strategy change; the
+  existing RSpec + real-Redis suite is the verification mechanism, run before and after
+  migration to prove identical behavior (spec SC-003).
+- **IV. Observability by Default** — PASS. Failure attribution (step name, redacted
+  inputs, failure reason) is unchanged in shape; `InputValidationError#step_name` and
+  `#step_arguments` continue to be set at the same point in the enforcement path, just
+  from inside the base class's class-level entry point instead of a prepended module.
+- **V. Simplicity and Semantic Versioning (YAGNI)** — PASS, and this feature exists
+  *because of* this principle: it removes a `singleton_class.prepend` workaround. Per
+  spec Assumptions, dual authoring styles are explicitly rejected as unjustified
+  complexity. This is a breaking public-API change (mixin form removed with no
+  deprecation) — `CHANGELOG.md` MUST record it under a breaking-change heading per
+  Development Workflow. The gem is pre-1.0 (0.7.0) and `.release-please-config.json` sets
+  `bump-minor-pre-major: true`, so a `feat!:` commit yields **0.8.0**; release-please
+  owns the number, `version.rb` is never hand-edited.
+- **VI. Demo-App Proof of Feature (NON-NEGOTIABLE)** — PASS, tracked as an explicit task.
+  All existing `demo_app/app/reactors/*.rb` steps using the mixin form MUST convert to the
+  new base class (7 occurrences in 3 files, plus 6 in 2 `demo_app/spec/` files —
+  research.md D8), and a new demo reactor
+  demonstrating the inheriting style end-to-end (success + failure/rollback path, plus a
+  brownfield service adapter per spec User Story 3) MUST be added with a matching rake
+  task and RSpec-matcher-only spec.
+- [x] Documentation impact identified: `README.md` step-authoring sections (Quick Start /
+      core usage examples) and every file under `./documentation` that shows
+      `include RubyReactor::Step` (`getting_started.md`, `core_concepts.md`,
+      `composition.md`, `async_reactors.md`, `README.md` inside `documentation/`, and the
+      two files under `documentation/examples/`) MUST be updated to the inheriting form,
+      carried into `tasks.md` as required documentation tasks (Constitution Development
+      Workflow).
+
+No unjustified violations. Proceeding to Phase 0.
+
+## Project Structure
+
+### Documentation (this feature)
+
+```text
+specs/004-inheritable-step-class/
+├── plan.md              # This file (/speckit-plan command output)
+├── research.md          # Phase 0 output (/speckit-plan command)
+├── data-model.md        # Phase 1 output (/speckit-plan command)
+├── quickstart.md        # Phase 1 output (/speckit-plan command)
+├── contracts/           # Phase 1 output (/speckit-plan command)
+│   └── step-lifecycle.md
+└── tasks.md             # Phase 2 output (/speckit-tasks command - NOT created by /speckit-plan)
+```
+
+### Source Code (repository root)
+
+```text
+lib/ruby_reactor/
+├── step.rb                       # REWRITTEN: `class Step` replaces `module Step` (mixin)
+├── step_signals.rb                # comment only: catch-site list now names RubyReactor::Step (D4)
+├── step_worker.rb                 # unchanged call site; gains correct signal handling via base class (D4)
+├── step/                          # every file here flips `module Step` → `class Step` together (D9)
+│   ├── input_contract.rb          # namespace line only; contract logic unchanged
+│   ├── compose_step.rb            # MIGRATED: `class ComposeStep < RubyReactor::Step`; dead initialize deleted (D6)
+│   ├── map_step.rb                # MIGRATED: `class MapStep < RubyReactor::Step`; build_mapped_inputs/resolve_element stay class-level (D6)
+│   └── async_reactor_step.rb      # MIGRATED: `class AsyncReactorStep < RubyReactor::Step`
+├── executor/
+│   ├── step_executor.rb           # unchanged call sites (`impl.run(args, ctx)`)
+│   └── compensation_manager.rb    # unchanged call sites (`impl.compensate` / `impl.undo`)
+├── map/helpers.rb                 # unchanged; still calls MapStep.build_mapped_inputs (class-level)
+├── rspec/
+│   └── test_subject.rb            # unchanged call sites (`step_config.impl.run(args, ctx)`)
+└── dsl/
+    └── template_helpers.rb        # unchanged (inline block steps keep `include StepSignals`)
+
+spec/
+├── ruby_reactor/step_contract_*.rb, step_signals_spec.rb, step/map_step_spec.rb, …  # step classes rewritten to subclass form
+├── ruby_reactor/dsl/*step*_spec.rb                                                   # step classes rewritten to subclass form
+└── support/reactors/*.rb                                                             # shared example steps rewritten to subclass form
+
+demo_app/
+├── app/reactors/*.rb                     # 19 mixin usages migrated to subclass form
+├── app/reactors/<new>_reactor.rb          # NEW demo reactor for inheriting style + brownfield adapter
+├── lib/tasks/demo_reactors.rake           # NEW `demo:` task entry for the above
+└── spec/reactors/<new>_reactor_spec.rb    # NEW spec, shipped matchers only
+
+README.md, documentation/*.md, CHANGELOG.md   # updated per Constitution Development Workflow
+```
+
+**Structure Decision**: Single-project Ruby gem layout (existing `lib/`/`spec/` +
+`demo_app/` integration example). No new top-level directories. This is a rewrite of one
+subsystem (`lib/ruby_reactor/step.rb` and its three built-in consumers) plus a
+find-and-migrate pass over every place a step class is authored, not a new component.
+
+## Complexity Tracking
+
+> **Fill ONLY if Constitution Check has violations that must be justified**
+
+No constitution violations. This table instead records the one design risk Phase 0 must
+close out before Phase 1 proceeds (Principle II gate above):
+
+| Risk | Why it exists | How Phase 0/1 must resolve it |
+|------|----------------|-------------------------------|
+| Undo/compensate must not depend on run-time instance state | Async execution runs `run` in one worker process and `undo`/`compensate` in a possibly later, separate invocation; today's design (three independent `self.` methods) cannot leak state between them by construction, but instance methods on one class could tempt an author (or the built-in steps) into memoizing something in `run` and reading it in `undo` | `research.md` decides the instantiation contract (a **fresh instance per lifecycle action**, built only from the stored arguments/result/context — never a shared instance across run and undo); `data-model.md` documents accessors as read-only derived from constructor args, with no cross-action mutable state, and this is stated as a load-bearing rule in the base class's own comments (spec FR-009, FR-011) |

data/specs/004-inheritable-step-class/quickstart.md

@@ -0,0 +1,112 @@
+# Quickstart: Validating the Inheritable Step Class
+
+Prerequisites: repo checked out on this feature branch, Redis reachable
+(Constitution Principle III — `bundle exec rspec` fails fast at suite start if not),
+`bundle install` run.
+
+## 1. Unit-level proof (User Story 1)
+
+Write a throwaway subclass and invoke it directly — no reactor needed, matching how the
+input-contracts feature was validated:
+
+```ruby
+class QuickstartStep < RubyReactor::Step
+  input :amount, :integer, gt?: 0
+
+  def run
+    fail!("too much") if inputs[:amount] > 100
+    Success(charged: inputs[:amount])
+  end
+end
+
+ctx = RubyReactor::Context.new({})
+QuickstartStep.run({ amount: 10 }, ctx)   # => Success(charged: 10)
+QuickstartStep.run({ amount: 200 }, ctx)  # => Failure("too much")
+QuickstartStep.run({ amount: -1 }, ctx)   # raises RubyReactor::Error::InputValidationError, step_name "QuickstartStep"
+
+# Through a reactor, that raised error becomes a Failure — confirm it is non-retryable
+# (research.md D10): the same invalid amount would fail identically on a retry.
+reactor = Class.new(RubyReactor::Reactor) { input :amount; step :charge, QuickstartStep }
+result = reactor.run(amount: -1)
+result.retryable?  # => false
+```
+
+Expected: first call succeeds with the body's value; second call returns the `fail!`
+signal translated to a `Failure`, proving User Story 1 scenario 3; third call **raises**
+(a direct call surfaces the validation error itself — the executor and worker are what
+turn it into a rolled-back `Failure`) and never runs the body, proving scenario 2. See
+[contracts/step-lifecycle.md](./contracts/step-lifecycle.md) for the full invocation
+contract.
+
+## 1b. Worker-path signal proof (User Story 2 scenario 2, research.md D4)
+
+The one behavior that *changes* on purpose: a class step calling `fail!` under
+`async_step` / `background` must now produce the intended `Failure`, not a Failure wrapping
+`UncaughtThrowError`. Write this spec first and watch it fail on the current code:
+
+```ruby
+# spec/ruby_reactor/step_signals_worker_spec.rb (sketch)
+class WorkerFailStep < RubyReactor::Step
+  def run = fail!("nope")
+end
+# reactor with `async_step :boom, WorkerFailStep`; run with drain_async_jobs
+expect(result).to be_failure
+expect(result.error).to eq("nope")   # today: an UncaughtThrowError instance
+```
+
+## 2. Full-suite regression proof (User Story 2)
+
+```sh
+bundle exec rspec
+bundle exec rubocop
+```
+
+Expected: 100% pass, identical to the pre-refactor baseline (spec SC-003). This exercises
+every execution path — sync executor, async worker, retry, compensation/undo, compose,
+map, and the RSpec test-subject interception surface — because those specs already cover
+those paths against whatever step classes exist; after migration (research.md D6, D8)
+they exercise the same paths against the new base class.
+
+## 3. Brownfield adapter proof (User Story 3)
+
+```ruby
+# Pre-existing, untouched service:
+class LegacyChargeService
+  def initialize(user_id) = @user_id = user_id
+  def call = @user_id.positive? ? OpenStruct.new(success?: true, id: 42) : OpenStruct.new(success?: false, error: "bad user")
+end
+
+class ChargeStep < RubyReactor::Step
+  input :user_id, :integer
+
+  def run
+    outcome = LegacyChargeService.new(inputs[:user_id]).call
+    outcome.success? ? Success(charge_id: outcome.id) : Failure(outcome.error)
+  end
+end
+```
+
+Expected: `LegacyChargeService` is never modified; `ChargeStep` is ≤10 lines (spec SC-004).
+
+## 4. Demo-app acceptance proof (User Story 5, Constitution Principle VI)
+
+```sh
+docker compose up -d
+docker compose run --rm demo-app bin/rails demo:inheritable_step   # new task added by this feature
+docker compose run --rm demo-app bundle exec rspec spec/reactors   # demo_app has its own Gemfile/.rspec
+```
+
+Expected: printed success and failure/rollback outcomes for the new demo reactor; the
+full `demo_app/spec/reactors/` suite passes using only the shipped `lib/ruby_reactor/rspec.rb`
+test surface (no hand-rolled scaffolding, per Principle VI). Run the demo specs from
+inside `demo_app/` (or via the compose service as above), never from the gem root.
+
+## 5. Old authoring style is gone (User Story 5)
+
+```sh
+grep -rnE "include RubyReactor::Step\b" lib spec demo_app README.md documentation
+```
+
+Expected: zero matches (spec SC-002). The `\b` matters: without it the grep also hits
+`include RubyReactor::StepSignals`, which is legitimate and stays. Any real match is
+unfinished migration work, not an acceptable remainder.

data/specs/004-inheritable-step-class/research.md

@@ -0,0 +1,308 @@
+# Phase 0 Research: Inheritable Step Class
+
+No `NEEDS CLARIFICATION` markers remain in the Technical Context (see plan.md) or the
+spec. This file records the design decisions Phase 1 depends on, found by reading the
+current implementation rather than by external research — this is an internal refactor of
+an existing subsystem, not a new-technology adoption.
+
+## D1: Class-level entry point shape
+
+**Decision**: `RubyReactor::Step` exposes exactly three class methods —
+`self.run(arguments, context)`, `self.undo(result, arguments, context)`,
+`self.compensate(reason, arguments, context)` — matching the call sites that already
+exist in `step_executor.rb` (`step_config.impl.run(arguments, @context)`) and
+`compensation_manager.rb` (`step_config.impl.compensate(error, arguments, @context)` /
+`step_config.impl.undo(result.value, arguments, @context)`). `self.call` is defined as an
+alias of `self.run` (`singleton_class.alias_method :call, :run` in `inherited`, or simply
+`def self.call(...) = run(...)`).
+
+**Rationale**: Zero call-site changes needed in the executor, compensation manager, or
+`rspec/test_subject.rb` — all three already call `impl.run` / `impl.compensate` /
+`impl.undo` with exactly these signatures today (verified by reading
+`lib/ruby_reactor/executor/step_executor.rb:357-361` and
+`lib/ruby_reactor/executor/compensation_manager.rb:76-121`). The refactor changes what
+happens *inside* those three class methods, not who calls them or with what arguments —
+this is what keeps User Story 2 (every execution path unaffected) achievable without
+touching the executor.
+
+**Alternatives considered**:
+- *A single `self.call(action, ...)` dispatcher* — rejected: would require changing three
+  call sites for no behavioral gain, and obscures the three distinct lifecycle actions
+  behind a string/symbol dispatch.
+- *Keep `run`/`undo`/`compensate` as the only spellings, no `call` alias* — rejected: the
+  prompt explicitly asks for `class_alias :call, :run`-equivalent, and the demo/README
+  narrative style favors reading a step invocation as `MyStep.call(args, context)` in some
+  examples; costs nothing to alias.
+
+## D2: Fresh instance per lifecycle action (closes the Complexity Tracking risk)
+
+**Decision**: Every class-level entry point builds its **own** instance —
+`new(arguments, context)` for `run`, and a separate `new(arguments, context)` (plus the
+one value that action alone receives — `result` for undo, `reason` for compensate) for
+`undo`/`compensate`. No instance is cached or shared across actions on the class.
+
+**Rationale**: Async execution already runs `run` and a later `undo`/`compensate` in
+different invocations, potentially different processes (Sidekiq workers) — `step_worker.rb`
+and `compensation_manager.rb` are separate call sites with no shared Ruby object between
+them today (the mixin design made this true "for free" because there was never an
+instance at all). Making the constructor the *only* place state enters an instance, and
+giving each action its own instance, preserves that guarantee: an author cannot
+accidentally memoize something in `run` and read it back in `undo`, because `undo`'s
+instance never ran `run`. This directly satisfies spec FR-009 ("run on a fresh instance so
+that behaviour is identical whether or not the run happened in the same process") and the
+Edge Case "Run and rollback happen in different processes."
+
+**Alternatives considered**:
+- *One instance per class-level call, reused across a script/test that chains actions
+  manually* — rejected: no call site in the codebase does this, and it would create an
+  attractive nuisance (author writes code that "happens to work" only when run and undo
+  land in the same process during tests, then breaks in production async execution).
+- *Memoized instance keyed by context id* — rejected: unnecessary caching layer, and the
+  existing `undo_stack`/compensation path already carries `arguments` and `result`/`reason`
+  forward explicitly (see `compensation_manager.rb`'s `undo_stack` entries), so there is
+  nothing an instance needs to remember between actions.
+
+## D3: Instance constructor signature and accessors
+
+**Decision**: `initialize(inputs, context, result: nil, reason: nil)` stores everything
+the instance can ever read. Reader names, decided here so tasks.md does not have to:
+
+| Reader | Holds | Available in |
+|---|---|---|
+| `inputs` | the validated (or raw, when no contract) argument hash | run, undo, compensate |
+| `context` | the workflow `RubyReactor::Context` | run, undo, compensate |
+| `result` | the step's own stored result value | undo only (nil elsewhere) |
+| `reason` | the failure that triggered rollback | compensate only (nil elsewhere) |
+
+`undo` and `compensate` therefore take no parameters either — matching the description's
+example shape (`def run` / `def undo` / `def compensate` with no explicit parameter list)
+while still giving the instance everything the class-level entry point receives.
+
+**Rationale**: The feature description's example shows zero-arg instance methods, which
+only works if the instance already holds everything it needs from construction. This
+matches the "form object" / "interactor" idiom common in the Rails codebases the gem
+targets (brownfield compatibility, spec User Story 3). `inputs` (plural) is chosen over
+`input`/`arguments` because it mirrors `context.inputs` on the reactor side and the inline
+`inputs do ... end` contract block, and stays visibly distinct from `arguments`, the word
+the executor uses everywhere for the *unvalidated* resolved hash — reviewers can tell at a
+glance which side of validation a value is on.
+
+**Alternatives considered**:
+- *`input` (singular), mirroring the declaration keyword* — rejected: reads oddly for a
+  hash (`input[:amount]`), and the singular already means "one declaration" at class
+  level.
+- *`arguments`, mirroring the executor* — rejected: same word for pre- and post-validation
+  values invites the exact confusion the contract exists to remove.
+
+**Alternatives considered**:
+- *Instance methods keep taking `(arguments, context)` as parameters, mirroring the old
+  class methods 1:1* — rejected: defeats the point of the refactor (spec explicitly wants
+  `def run` reading state via accessors, not parameters) and just relocates the same
+  shape one level down.
+
+## D4: Signal translation stays a `catch` at the class-level entry point
+
+**Decision**: The class-level `run`/`undo`/`compensate` wrap the instance-method call in
+`catch(StepSignals::TAG) { ... }` (for `run`, validation happens *before* entering the
+catch, so an `InputValidationError` still raises rather than being confused with a
+signal). The executor's and compensation manager's existing outer catches around
+`step_config.impl.*` stay in place unchanged; the two levels nest safely because
+`catch`/`throw` resolve at the innermost matching tag, and the outer ones still do the
+real work for inline `run_block`/`compensate_block`/`undo_block` steps.
+
+**This is not merely redundant — it fixes a latent bug.** `StepWorker#execute_step_body`
+(`lib/ruby_reactor/step_worker.rb`) calls `step_config.impl.run(arguments, context)` with
+**no** `catch(StepSignals::TAG)` at all (verified: the file contains no `catch`). Today a
+`fail!`/`success!`/`skip!`/`halt!` inside a class step executed by the `async_step` /
+`background` worker escapes as `UncaughtThrowError`, which is a `StandardError`, so the
+worker's `rescue StandardError` reports a Failure wrapping the wrong error (and marks it
+retryable). Moving the catch into the base class makes class steps behave identically on
+the worker path with no worker change — this is exactly spec User Story 2 scenario 2.
+Consequences carried into tasks.md:
+
+- A red test first: a class step calling `fail!("x")` under `async_step` must yield
+  `Failure("x")`, not a Failure wrapping `UncaughtThrowError`.
+- Inline `run_block` steps on the worker path remain uncaught. That is pre-existing, out
+  of scope (spec FR-013: inline blocks "keep working unchanged"), and gets a one-line note
+  in `CHANGELOG.md`'s known-issues or a follow-up issue — not silently ignored.
+- The comment in `lib/ruby_reactor/step_signals.rb` listing the catch sites
+  (`step_executor.rb`, `compensation_manager.rb`) is stale; update it to name
+  `RubyReactor::Step`'s entry points as the catch site for class steps.
+
+**Rationale**: Spec FR-007 requires signals to be "translated at the class-level entry
+point," a property of `RubyReactor::Step`'s own three methods, not of any caller. Owning
+the catch in the base class is what makes every current and future call site (executor,
+worker, direct call in a unit test) behave the same without each remembering to wrap.
+
+**Alternatives considered**:
+- *Remove the executor-level catch since it becomes dead code for class-based steps* —
+  rejected: it is not dead for inline block steps, and removing working code the feature
+  doesn't require touching is the kind of speculative churn Principle V rules out.
+- *Add a `catch` to the worker instead of the base class* — rejected: fixes one caller,
+  leaves the next one (a direct `MyStep.run` in a unit test, a future dispatcher) to
+  rediscover the bug; FR-007 puts the responsibility on the step class.
+
+## D5: Default `undo`/`compensate` and "must implement" error
+
+**Decision**: The base class's own instance-level `undo`/`compensate` return
+`RubyReactor.Skipped()` (today's default, moved from the `ClassMethods` module verbatim).
+The base class's instance-level `run` raises `NotImplementedError` naming the subclass
+(`"#{self.class} must implement #run"`), preserving today's message shape
+(`"#{self} must implement .run method"`) with `.` replaced by `#` to reflect that it is
+now an instance method.
+
+**Rationale**: Directly satisfies spec FR-009 and FR-010; minimizes behavior change for
+every subclass that already relies on the "compensation/undo default to skip" contract
+(every demo reactor and most spec support reactors do not define both).
+
+**Alternatives considered**: None — this is a direct behavior-preserving port.
+
+## D6: Migration scope for the three built-in steps
+
+**Decision**: `ComposeStep`, `MapStep`, and `AsyncReactorStep` become
+`class ComposeStep < RubyReactor::Step` etc., with their `self.run`/`self.compensate`/
+`self.undo` bodies moved into instance `run`/`compensate`/`undo` methods that read
+`inputs`/`context` (and `reason`/`result`) via the D3 accessors instead of method
+parameters. Their `class << self; private; ...; end` helper methods (argument-building,
+dispatch, deadlock detection, etc.) move to **private instance methods** — with two
+exceptions that stay **public class methods** because they are called from outside the
+step: `MapStep.build_mapped_inputs` and `MapStep.resolve_element`, used by
+`lib/ruby_reactor/map/helpers.rb:32` for element workers. None of the three declare
+`input`/`validate_inputs` today (they receive a pre-built `arguments` hash assembled by
+the DSL layer, e.g. `arguments[:composed_reactor_class]`), so no input contract is added
+for them — only the authoring shape changes.
+
+`ComposeStep` additionally carries a dead `initialize(composed_reactor_class,
+argument_mappings = {})` and two `attr_reader`s — nothing in `lib/`, `spec/`, or
+`demo_app/` ever calls `ComposeStep.new` (verified by grep). It would shadow the base
+class's `initialize(inputs, context, ...)`, so it is deleted, not migrated.
+
+**Rationale**: Spec FR-014 requires this; these three are the only "library-internal
+steps" that used the mixin form (verified: an anchored `grep -rn "include RubyReactor::Step$"`
+across `lib/` hits exactly these three files — an unanchored grep also matches
+`include RubyReactor::StepSignals` in `step.rb` and `dsl/template_helpers.rb`, which are
+not migrations). Converting private class helpers to private instance methods is a
+mechanical, behavior-preserving move — that logic only ever received `arguments`/`context`
+as explicit parameters. `MapStep` is the largest diff (~300 lines) and should be its own
+task with the existing `spec/ruby_reactor/step/map_step_spec.rb` and `spec/map/` suites
+as the red/green gate.
+
+**Alternatives considered**:
+- *Leave the three built-in steps on a separate, lighter-weight internal mixin instead of
+  the public `RubyReactor::Step` base class* — rejected: spec FR-014 is explicit these
+  migrate too, and a second internal-only step-authoring mechanism reintroduces the exact
+  "two ways to build a step" variance the spec's Assumptions section rules out.
+
+## D7: Inline block steps (reactor DSL `step ... do |args, ctx| ... end`)
+
+**Decision**: Untouched. Inline block steps are stored as `run_block`/`compensate_block`/
+`undo_block` procs on `StepConfig` (see `dsl/step_builder.rb`) and invoked directly by the
+executor/compensation manager, never through `RubyReactor::Step`. They already get
+`StepSignals` via `include RubyReactor::StepSignals` in `dsl/template_helpers.rb`. Nothing
+here changes their behavior or signature.
+
+**Rationale**: Spec explicitly scopes inline blocks as "keep working unchanged" (FR-013,
+Edge Cases). They are a different authoring surface (a block, not a class) and were never
+affected by the `singleton_class.prepend` workaround this feature removes.
+
+## D8: Migration inventory (counts by anchored grep, for tasks.md sizing)
+
+Pattern: `grep -rn "include RubyReactor::Step$"` (anchored — the unanchored form also
+matches `StepSignals`). Counted 2026-09-11; `/speckit-tasks` re-runs it.
+
+| Area | Files | Occurrences | Notes |
+|---|---|---|---|
+| `lib/ruby_reactor/step/` | 3 | 3 | the built-ins (D6) |
+| `spec/` | 13 | 34 | `spec/support/reactors/*.rb` shared steps + per-spec inline classes |
+| `demo_app/app/reactors/` | 3 | 7 | `validated_user_step.rb` (1), `user_etl_reactor.rb` (5), `reserve_inventory.rb` (1) |
+| `demo_app/spec/` | 2 | 6 | |
+| `README.md` | 1 | 5 | |
+| `documentation/` | 7 | 28 | `getting_started`, `core_concepts`, `composition`, `async_reactors`, `README`, `examples/order_processing`, `examples/payment_processing` |
+
+- No gem dependency changes, no `Gemfile`/`gemspec` edits required.
+- Version bump: `.release-please-config.json` sets `bump-minor-pre-major: true`, so a
+  `feat!:` / `BREAKING CHANGE:` commit takes 0.7.0 → **0.8.0**, not 1.0.0. The
+  `CHANGELOG.md` entry still goes under a breaking-change heading with a before/after
+  example (spec FR-015); the number is release-please's business.
+
+## D9: `module Step` becomes `class Step` — every reopening must change together
+
+**Decision**: All five files that currently open `module RubyReactor::Step` —
+`step.rb`, `step/input_contract.rb`, `step/compose_step.rb`, `step/map_step.rb`,
+`step/async_reactor_step.rb` — switch to `class Step` in the same commit. The nested
+constants keep their names (`RubyReactor::Step::InputContract`,
+`RubyReactor::Step::ComposeStep`, `RubyReactor::Step::MapStep`,
+`RubyReactor::Step::AsyncReactorStep`), so the five `lib/` references
+(`dsl/compose_builder.rb`, `dsl/map_builder.rb`, `dsl/async_reactor_builder.rb`,
+`dsl/step_builder.rb`, `map/helpers.rb`) and two `spec/` references are untouched.
+
+**Rationale**: Ruby raises `TypeError: Step is not a module` the moment a `module Step`
+reopening loads after `class Step` (or the reverse), so a partial conversion cannot even
+boot — this is a hard ordering constraint, not a style choice. Keeping the built-in steps
+nested inside their own parent class (`class Step; class MapStep < Step`) is legal, a
+little unusual to read, and the smallest diff; the three built-ins are internal plumbing
+addressed by the DSL builders, never by users, so the namespace is not a public-API
+concern.
+
+**Alternatives considered**:
+- *Move the built-ins to a sibling namespace (`RubyReactor::Steps::MapStep`)* — rejected
+  for this change: seven reference edits plus rename churn for zero user-visible benefit.
+  Worth revisiting only if a fourth built-in step appears (Principle V).
+
+## D10: Input-validation failures are non-retryable everywhere, enforced once
+
+**Decision**: Give `Error::InputValidationError` its own `retryable?` method returning
+`false`, mirroring the existing `Error::StepFailureError#retryable?` pattern
+(`lib/ruby_reactor/error/step_failure_error.rb`).
+
+**Rationale — a real, verified gap, not a hypothetical**: `RubyReactor::Failure.new`
+already defaults `retryable` from the wrapped error when no explicit `retryable:`/`retry:`
+kwarg is given (`lib/ruby_reactor.rb:164-168`:
+`@error.respond_to?(:retryable?) ? @error.retryable? : true`). Three places build a
+`Failure` from an `Error::InputValidationError`:
+
+| Call site | Passes `retryable:` explicitly? | Result today |
+|---|---|---|
+| `StepWorker#execute_step_body` rescue (`step_worker.rb:128-133`, the `async_step`/`background` path) | Yes — `retryable: false` | Correct, and covered by a passing spec (`spec/ruby_reactor/step_contract_async_spec.rb:24-33,59`) |
+| `Executor::ResultHandler#build_validation_failure` (`result_handler.rb:70-82`, the **synchronous** path — the default way almost every reactor runs) | No | `InputValidationError` has no `retryable?` today → defaults to `true` — **wrong**, no test catches it |
+| `Step::ComposeStep#handle_execution_result` (`compose_step.rb`, re-wraps a composed child's failure as `RubyReactor.Failure(result.error)`) | No | Same default → `true` — **wrong**, a validation failure inside a `compose`d child currently looks retryable to the parent |
+
+A single `retryable?` method on the error class fixes all three by construction: the two
+call sites that pass nothing now inherit the correct answer from the error itself, and
+the one call site that already passes `retryable: false` keeps doing so redundantly
+(explicit always wins — no behavior change there, no need to touch that file). Any future
+call site that wraps this error class in a `Failure` without thinking about retryability
+gets the right answer for free — this is the same reasoning as D1/D4: put the guarantee
+on the one object that knows it's true, not on every caller.
+
+**Verified safe**: no existing spec asserts `retryable?` true for an
+`InputValidationError`-derived `Failure`; the one comment that looks related
+(`spec/ruby_reactor/interrupt_spec.rb:62`, "`Should raise validation error (retryable)`")
+is about a raised exception on interrupt resume being retriable by resubmitting a
+corrected payload — a different mechanism, not a `Failure#retryable?` flag — and is
+unaffected (confirmed next paragraph).
+
+**Explicitly out of scope**: `Reactor#continue`'s own rescue at `reactor.rb:190-193`
+(interrupt/resume payload validation) builds `RubyReactor::Failure(e.message, ...)` from
+the error's **message string**, not the error object, so this fix does not reach it and
+`String#respond_to?(:retryable?)` stays `false` → still defaults to `true` there. That is
+a distinct, intentional mechanism (a human resubmits a corrected payload; "retryable" is
+the right word for it) unrelated to a step's own input contract, and outside what "step
+validations" in this feature's scope means. Not changed here.
+
+**Alternatives considered**:
+- *Add `retryable: false` explicitly at `build_validation_failure` and
+  `handle_execution_result`* — rejected: fixes the two known sites but not the next one
+  (Principle V: fix the property once, not the symptom twice); also a currently-passing
+  spec fixture (`spec/ruby_reactor/step_contract_enforcement_spec.rb`) constructs
+  `InputValidationError` directly in a few places without going through either helper, and
+  a class-level `retryable?` is the only fix that covers those uses too, e.g. a future
+  direct `RubyReactor::Failure(e)` written by a test helper.
+- *Check `error.is_a?(Error::InputValidationError)` inside `RubyReactor::Failure#initialize`
+  itself* — rejected: `lib/ruby_reactor.rb` already uses the `respond_to?(:retryable?)`
+  protocol precisely so it never needs to know about individual error subclasses; adding a
+  type check there would be a regression of that existing design, not a fix.
+
+## Outcome
+
+All unknowns resolved. No `NEEDS CLARIFICATION` remains. Proceeding to Phase 1.