ruby_reactor 0.7.1 → 0.8.0

data/specs/002-step-input-contracts/plan.md

@@ -0,0 +1,165 @@
+# Implementation Plan: Step Input Contracts
+
+**Branch**: `step_validations` | **Date**: 2026-09-10 | **Spec**: [spec.md](./spec.md)
+
+**Input**: Feature specification from `specs/002-step-input-contracts/spec.md`
+
+## Summary
+
+Move validation out of the reactor and into the unit of work. A step class declares its own
+inputs with `input :name, :type, **predicates`; an inline step declares the same lines inside
+an `inputs do ... end` block. The reactor's `argument` keeps dependency wiring and value
+mapping and loses rule declaration for any step that owns a contract — attempting both fails
+at the `step` macro rather than producing two overlapping rule sets at run time.
+
+Enforcement for class steps lives in a `run` wrapper prepended onto the step's singleton
+class, which covers the executor, the async worker, and direct invocation with one mechanism
+and reuses the library's existing `Error::InputValidationError` protocol (raise → rollback →
+`build_validation_failure` → `have_validation_error`). Inline contracts compile to the
+existing `args_validator` and close the async worker's missing validation call.
+
+Two supporting corrections ship with it: an unwired declared input resolves from a same-named
+reactor input (checked before execution, never from another step's result), and falsey values
+stop being lost in transit — `Context#get_input`/`#get_result` and `Template::Result#fetch`
+currently turn a supplied `false` into `nil`, which contracts would escalate into a spurious
+"must be filled" failure.
+
+Design decisions and the evidence behind them: [research.md](./research.md).
+
+## Technical Context
+
+**Language/Version**: Ruby >= 3.0.0
+
+**Primary Dependencies**: dry-validation ~> 1.10 (schema construction; already a hard gem
+dependency), sidekiq ~> 7.0 (async step path), redis ~> 5.0, zeitwerk ~> 2.6
+
+**Storage**: Redis (unchanged by this feature — contracts are compile-time declarations;
+resolved arguments already round-trip through `ContextSerializer`)
+
+**Testing**: RSpec with real Redis (constitution III). Feature specs under
+`spec/ruby_reactor/dsl/` and `spec/ruby_reactor/`; acceptance via `demo_app/` rake tasks run
+through `docker compose run`.
+
+**Target Platform**: Ruby library (gem), sync and Sidekiq-backed async execution
+
+**Project Type**: Library / DSL
+
+**Performance Goals**: Validation cost is per-step-execution and already paid today for
+reactor-declared rules; no measurable regression. Contract compilation happens once at class
+definition. `validate_definition!` is memoized per reactor class.
+
+**Constraints**: Public API is SemVer-governed — additive DSL (MINOR); no existing reactor may
+change behavior except the falsey-value fix (PATCH-class bug fix, changelog note required).
+dry-validation stays the only validation engine.
+
+**Scale/Scope**: ~8 library files touched, 1 new file, plus demo-app artifacts and README.
+No new gem dependency.
+
+## Constitution Check
+
+*GATE: passed before Phase 0. Re-checked after Phase 1 design — see bottom of this section.*
+
+| Principle | Assessment |
+|---|---|
+| **I. Gem-First Design** | ✅ Entirely inside `lib/`. No host coupling, no monkey-patching. The Sidekiq-facing change (`StepWorker`) is inside the existing adapter boundary. |
+| **II. Saga Pattern Integrity** | ✅ Validation failures raise `Error::InputValidationError`, which `handle_execution_error` already routes through `rollback_completed_steps` before building the failure. Compensation semantics are inherited, not re-implemented. Validation runs *before* the step body, so a rejected step produces no side effect to compensate. |
+| **III. Test-First with Real Infrastructure** | ✅ Red-Green-Refactor per task. The async-worker validation gap (research Finding 2) is exercised against real Redis + Sidekiq, not `Sidekiq::Testing.inline!`. |
+| **IV. Observability by Default** | ✅ Failures carry reactor name, step name, redacted inputs, and field errors — `build_validation_failure` already assembles this; D3 adds the missing step attribution for class steps. FR-015 keeps `redact:` declarable on a step's own contract. |
+| **V. Simplicity and SemVer** | ✅ MINOR: `input` on step classes and `inputs do` in step blocks are additive; reactor-declared rules keep working (D9 deprecation, not removal). The conflict error (D5) can only fire on code written after this release, since declaring a contract on a step class is not possible today. Falsey fix is a bug fix with a changelog note. Two enforcement mechanisms are justified in Complexity Tracking. |
+| **VI. Demo-App Proof of Feature** | ✅ Planned as blocking work, not follow-up: example reactor + `demo:` rake task + spec using only the shipped matchers + `docker compose run` acceptance. `have_validation_error` already exists, so no matcher extension is expected — if a task finds an assertion it cannot express, the matcher is added to `lib/ruby_reactor/rspec/` in the same change. |
+
+**Post-design re-check**: no new violations. The design adds no new dependency, no new
+storage primitive, and no new failure shape — it routes a new declaration site into the
+error protocol the library already has. The one item carried to Complexity Tracking is the
+dual enforcement mechanism.
+
+## Project Structure
+
+### Documentation (this feature)
+
+```text
+specs/002-step-input-contracts/
+├── plan.md              # This file
+├── spec.md              # Feature specification
+├── research.md          # Phase 0 — current-state findings and design decisions
+├── data-model.md        # Phase 1 — contract/declaration entities and lifecycle
+├── quickstart.md        # Phase 1 — how to run and verify the feature
+├── contracts/
+│   └── dsl-surface.md   # Phase 1 — public DSL, errors, introspection API
+├── checklists/
+│   └── requirements.md  # Spec quality checklist (complete)
+└── tasks.md             # Phase 2 — /speckit-tasks output, NOT created here
+```
+
+### Source Code (repository root)
+
+```text
+lib/ruby_reactor/
+├── step.rb                          # + `input` DSL, contract storage/inheritance,
+│                                    #   introspection, singleton `run` wrapper (D1, D3)
+├── step/
+│   └── input_contract.rb            # NEW — declaration list, schema compilation,
+│                                    #   defaults, redaction, inheritance merge
+├── dsl/
+│   ├── step_builder.rb              # + `inputs do` block (D2); conflict + unknown-argument
+│   │                                #   errors at build time (D5)
+│   ├── reactor.rb                   # + `validate_definition!` (D6), name-based
+│   │                                #   fallback wiring (D7)
+│   └── validation_helpers.rb        # reused unchanged by the step-side builder
+├── executor/
+│   └── step_executor.rb             # stamp `step_name` on re-raised validation errors (D3)
+├── step_worker.rb                   # validate inline-step args; InputValidationError branch (D4)
+├── context.rb                       # presence-aware get_input / get_result (D8)
+├── template/result.rb               # presence-aware nested fetch (D8)
+├── utils/
+│   └── fetch_indifferent.rb         # NEW — the one shared presence-aware lookup (D8)
+├── reactor.rb                       # call validate_definition! before execution (D6)
+└── rspec/
+    └── test_subject.rb              # call validate_definition! from test_reactor (D6)
+
+spec/ruby_reactor/
+├── dsl/step_input_contract_spec.rb        # NEW — declaration, inheritance, introspection
+├── dsl/step_contract_conflict_spec.rb     # NEW — D5 errors, D6 satisfiability
+├── step_contract_enforcement_spec.rb      # NEW — all execution paths incl. async worker
+└── falsey_input_resolution_spec.rb        # NEW — FR-023 across inputs, results, paths
+
+demo_app/
+├── app/reactors/validated_signup_reactor.rb   # NEW — contract-owning step, pass + fail path
+├── lib/tasks/demo_reactors.rake               # + demo:validated_signup
+└── spec/reactors/validated_signup_reactor_spec.rb  # NEW — shipped matchers only
+
+README.md                            # class-step form primary, inline equivalent, migration
+CHANGELOG.md                         # Features + Bug Fixes entries
+```
+
+**Structure Decision**: The gem's existing layout is kept as-is. Two new library files only —
+`step/input_contract.rb` (the declaration object the spec's Key Entities describe) and
+`utils/fetch_indifferent.rb` (one helper, three call sites). Everything else is an edit to the
+file that already owns the concern.
+
+## Phase 2 outline (for `/speckit-tasks`)
+
+Dependency-ordered, each block independently testable:
+
+1. **Falsey resolution (FR-023)** — `fetch_indifferent` + three call sites + spec. Independent
+   of everything else; land first so contract work builds on correct presence semantics.
+2. **Contract declaration (US1, FR-001/002/013/014/015)** — `InputContract`, `Step#input`,
+   inheritance, introspection. No enforcement yet.
+3. **Enforcement (US1, FR-003/004/022)** — prepended `run` wrapper, step-name stamping,
+   worker path. Covers class steps on every execution path.
+4. **Reactor-side split (US2, FR-005/006/018)** — conflict and unknown-argument errors at the
+   `step` macro.
+5. **Inline contracts (US3, FR-007)** — `inputs do` block → `args_validator`, worker
+   validation call, equivalence spec against the class form.
+6. **Wiring resolution (US4, FR-008/020/021)** — `validate_definition!`, name-based fallback,
+   invocation from `run`/`call`/`test_reactor`.
+7. **Back-compat + deprecation (US5, FR-010/011)** — existing-suite green, one-time notices.
+8. **Docs + demo (FR-016/017)** — README, CHANGELOG, demo reactor + rake + spec, docker
+   acceptance run.
+
+## Complexity Tracking
+
+| Violation | Why Needed | Simpler Alternative Rejected Because |
+|-----------|------------|--------------------------------------|
+| Two enforcement mechanisms — prepended `run` for class steps (D3), `args_validator` for inline steps (D4) | An inline step has no class to prepend to, and a class step must validate on paths the reactor does not control (`StepWorker#execute_step_body`, direct invocation). | Putting every contract into `args_validator` leaves the async worker path and direct invocation unvalidated (research Finding 2), and re-centralizes in the reactor exactly what this feature moves into the step. Both mechanisms raise the same error class through the same handler, so the observable behavior is one protocol, and an equivalence spec pins them together. |
+| `validate_definition!` runs at first execution rather than at class load (D6) | The satisfiability check needs the reactor's complete input list, which is not available while the class body is still executing, and there is no registry of user reactor classes to sweep at boot (research Finding 7). | `TracePoint(:end)` to detect the end of a class body is unreadable and breaks on reopened classes; requiring `input` before `step` silently breaks valid existing reactors. The user-visible property is preserved — the reactor fails before step one runs, not on the run that first reaches the step. |

data/specs/002-step-input-contracts/quickstart.md

@@ -0,0 +1,170 @@
+# Quickstart: Step Input Contracts
+
+**Feature**: `specs/002-step-input-contracts/` | **Date**: 2026-09-10
+
+How to run and verify this feature end to end. DSL details live in
+[contracts/dsl-surface.md](./contracts/dsl-surface.md); design rationale in
+[research.md](./research.md).
+
+## Prerequisites
+
+- Ruby >= 3.0, `bundle install`
+- Docker (for the gem's test Redis on port 6780 and the demo app's Redis on 6380)
+
+```bash
+docker compose up -d redis-test        # required: spec_helper aborts without it
+```
+
+## Scenario 1 — a step class owns its contract (US1)
+
+```ruby
+class ValidatedUserStep
+  include RubyReactor::Step
+
+  input :name,  :string,  min_size?: 2
+  input :email, :string
+  input :age,   :integer, gteq?: 18
+  input :bio,   :string,  optional: true, default: "No bio provided", max_size?: 100
+
+  def self.run(args, _context)
+    Success(args.merge(created_at: Time.now))
+  end
+end
+
+class SignupReactor < RubyReactor::Reactor
+  input :name
+  input :email
+  input :age
+
+  step :profile, ValidatedUserStep      # no argument block — resolved by name
+  returns :profile
+end
+```
+
+**Expected**
+
+```ruby
+SignupReactor.run(name: "Ada", email: "ada@example.com", age: 36)
+# => Success, bio defaulted to "No bio provided"
+
+SignupReactor.run(name: "A", email: "ada@example.com", age: 17)
+# => Failure; validation_errors has :name and :age; ValidatedUserStep.run never called
+```
+
+**Verify**
+
+```bash
+bundle exec rspec spec/ruby_reactor/dsl/step_input_contract_spec.rb
+bundle exec rspec spec/ruby_reactor/step_contract_enforcement_spec.rb
+```
+
+## Scenario 2 — the reactor may not redeclare rules (US2)
+
+```ruby
+class BadReactor < RubyReactor::Reactor
+  input :age
+  step :profile, ValidatedUserStep do
+    argument :age, input(:age), :integer, gteq?: 21   # ← rules on a contract-owning step
+  end
+end
+# raises RubyReactor::Error::ValidationError when the class body runs,
+# naming BadReactor, :profile, :age, and ValidatedUserStep
+```
+
+Same for `validate_args do ... end`, and for an `argument` naming an input the step never
+declares.
+
+**Verify**: `bundle exec rspec spec/ruby_reactor/dsl/step_contract_conflict_spec.rb`
+
+## Scenario 3 — inline steps, same vocabulary (US3)
+
+```ruby
+step :charge do
+  inputs do
+    input :amount, :decimal, gt?: 0
+  end
+  argument :amount, input(:amount)
+  run { |args, _| Success(charge!(args[:amount])) }
+end
+```
+
+**Expected**: identical outcomes to the same declarations in a step class, for both
+conforming and violating values (SC-005). The equivalence spec asserts this pair directly.
+
+## Scenario 4 — missing wiring is caught before execution (US4)
+
+```ruby
+class IncompleteReactor < RubyReactor::Reactor
+  input :name                       # :email and :age never declared or wired
+  step :profile, ValidatedUserStep
+end
+
+IncompleteReactor.run(name: "Ada")
+# => RubyReactor::Error::ValidationError naming :profile, :email, and how to satisfy it.
+# ValidatedUserStep.run is never called; no step in the reactor runs.
+```
+
+Callable directly for a boot-time or CI check:
+
+```ruby
+IncompleteReactor.validate_definition!
+```
+
+## Scenario 5 — falsey values survive (FR-023)
+
+```ruby
+class NotifyStep
+  include RubyReactor::Step
+  input :notify, :bool
+  def self.run(args, _ctx) = Success(args[:notify])
+end
+
+SomeReactor.run(notify: false)
+# => Success(false) — not a "must be filled" failure, and not nil
+```
+
+Covers reactor inputs, prior step results, and nested paths through either.
+
+**Verify**: `bundle exec rspec spec/ruby_reactor/falsey_input_resolution_spec.rb`
+
+## Scenario 6 — every execution path (FR-003)
+
+The async worker is the path that has no argument validation today
+([research.md](./research.md) Finding 2), so it is the one worth running against real
+infrastructure rather than `Sidekiq::Testing.inline!`:
+
+```bash
+docker compose up -d demo-redis sidekiq
+docker compose run --rm demo-app bin/rails demo:validated_signup
+```
+
+**Expected output**: the passing run prints the created profile; the failing run prints a
+validation failure naming the step and the offending fields; the `async_step` variant shows
+the same failure produced inside the worker.
+
+## Full suite
+
+```bash
+docker compose up -d redis-test
+bundle exec rspec                     # gem suite
+bundle exec rubocop                   # required by the constitution, no --disable-pending-cops
+
+docker compose run --rm demo-app bundle exec rspec spec/reactors/validated_signup_reactor_spec.rb
+docker compose run --rm demo-app bin/rails demo:validated_signup
+```
+
+## Acceptance checklist
+
+| # | Claim | How it is verified |
+|---|---|---|
+| SC-001 | Contract readable from the step class alone | No demo reactor declares a rule for a contract-owning step |
+| SC-002 | Same step, same rules in every reactor | Two reactors reuse `ValidatedUserStep`, zero per-reactor rules |
+| SC-003 | Conflicts reported at definition | Scenario 2 raises when the class body runs |
+| SC-004 | Unwired required inputs reported before execution | Scenario 4 |
+| SC-005 | Inline ↔ class equivalence | Scenario 3 equivalence spec |
+| SC-006 | Existing behavior preserved | Full gem suite green |
+| SC-007 | Failure names reactor, step, fields | `have_validation_error` + failure payload assertions |
+| SC-008 | Demo runs in docker, both paths | Scenario 6 |
+| SC-009 | Name-matched reactors need no arguments | Scenario 1 has no argument block |
+| SC-010 | Direct call ≡ reactor call | `ValidatedUserStep.run({age: 17}, ctx)` raises the same error |
+| SC-011 | `false` arrives as `false` | Scenario 5 |

data/specs/002-step-input-contracts/research.md

@@ -0,0 +1,233 @@
+# Phase 0 Research: Step Input Contracts
+
+**Feature**: `specs/002-step-input-contracts/` | **Date**: 2026-09-10
+
+All findings below come from reading the current implementation, not from assumption. File
+references are to the state of `step_validations` at the time of writing.
+
+## Current state (what exists today)
+
+| Concern | Where it lives now |
+|---|---|
+| Step argument wiring + rules | `Dsl::StepBuilder#argument` (`lib/ruby_reactor/dsl/step_builder.rb:41`) — one call does source mapping, transform, type, and predicates |
+| Cross-field rules | `Dsl::StepBuilder#validate_args` (`step_builder.rb:76`) |
+| Schema construction | `Validation::SchemaBuilder` (`build_inline`, `build_args`, `apply_inline_rules`) |
+| Enforcement (inline path) | `Executor::StepExecutor#validate_step_arguments` (`step_executor.rb:312`) — **raises** `Error::InputValidationError` |
+| Failure shaping | `Executor::ResultHandler#handle_execution_error` (`result_handler.rb:39`) — rollback + `build_validation_failure` |
+| Step classes | `RubyReactor::Step` (`lib/ruby_reactor/step.rb`) — 43 lines: result helpers plus `run`/`compensate`/`undo` stubs. **No declaration DSL at all.** |
+
+### Finding 1 — class steps have no contract surface and no implicit inputs
+
+`resolve_arguments` builds only from `step_config.arguments`. `run_step_implementation`
+(`step_executor.rb:346-353`) falls back to `@context.inputs` **only when the step has a run
+block**. A class step with no `argument` declarations receives `{}`. FR-020's name-based
+fallback is therefore new behavior for class steps, not a preserved one.
+
+### Finding 2 — there are two step execution paths, and only one validates
+
+- Inline/retry/resume: `execute_step` → `execute_step_with_retry` → `safe_execute_step_sync`
+  → `execute_step_sync_without_result_handling` → `validate_step_arguments`. ✅
+- `async_step` worker: `StepWorker#execute_step_body` (`step_worker.rb:112-118`) calls
+  `step_config.run_block.call` / `step_config.impl.run` directly. **No validation.** ❌
+
+FR-003 ("enforced on every execution path") is not satisfiable by adding rules to
+`step_config` alone.
+
+### Finding 3 — raising is the established validation protocol
+
+`safe_execute_step_sync` (`step_executor.rb:186`) explicitly re-raises
+`Error::InputValidationError` so it is never retried and never wrapped as a generic step
+failure. `handle_execution_error` then rolls back completed steps and calls
+`build_validation_failure`, producing the `validation_errors` payload that
+`have_validation_error` (`rspec/matchers.rb:154`) reads. Any new enforcement point that
+raises this error inherits the correct failure shape, saga rollback, retry suppression, and
+matcher support for free.
+
+### Finding 4 — `input` is already overloaded, and collides inside step blocks
+
+- On a reactor body, `Dsl::Reactor::ClassMethods#input` (`dsl/reactor.rb:70`) **declares**.
+- Inside `step ... do ... end`, `StepBuilder` includes `Dsl::TemplateHelpers`, whose
+  `input(name, path = nil)` (`template_helpers.rb:8`) **returns a `Template::Input`** used as
+  an argument source.
+
+So `input` means "declare" in one scope and "reference" in an adjacent one. Any inline-step
+contract syntax must not make that worse. This is the single biggest design constraint on
+FR-007/FR-012.
+
+### Finding 5 — falsey values are lost before a step sees them
+
+`Context#get_input` (`context.rb:67`) and `#get_result` (`context.rb:79`) both use
+`@inputs[name.to_sym] || @inputs[name.to_s]`; `Template::Result#fetch`
+(`template/result.rb:178`) repeats the pattern for nested lookups. A supplied `false`
+resolves to `nil`. Under contracts this escalates from a silent wrong value into a spurious
+"must be filled" failure (FR-023).
+
+### Finding 6 — internal steps include `RubyReactor::Step`
+
+`MapStep`, `ComposeStep`, and `AsyncReactorStep` all `include RubyReactor::Step`. Anything
+added to that module must be inert for a step that declares no contract.
+
+### Finding 7 — no registry of user reactor classes
+
+`Registry` (`lib/ruby_reactor/registry.rb`) holds only dynamically-generated reactors from
+inline `map`/`compose`. There is no list of all user-defined reactor classes, so there is no
+place to hang a global "validate every reactor at boot" pass without adding one.
+
+---
+
+## Decisions
+
+### D1 — A contract is declared with `input` on the step class
+
+```ruby
+class ChargeStep
+  include RubyReactor::Step
+
+  input :amount,   :decimal, gt?: 0
+  input :currency, :string,  included_in?: %w[USD EUR GBP]
+  input :user,     User
+  input :note,     :string,  optional: true, max_size?: 100
+
+  def self.run(args, context) = Success(charge!(args))
+end
+```
+
+**Rationale**: matches the user's sketch and the reactor's own `input`. No collision exists in
+a step class body — `Step` does not include `TemplateHelpers`.
+
+**Signature** is deliberately identical to `Dsl::Reactor::ClassMethods#input`:
+`input(name, type = nil, optional: false, default: nil, redact: false, **predicates, &block)`,
+including the Form-2 macro block (`input :x do |i| ... end`) and `validate:` for a pre-built
+schema. Reuses `Dsl::ValidationHelpers` verbatim.
+
+**Alternatives rejected**: `accepts` / `param` — a third word for a concept the library
+already names twice.
+
+### D2 — Inline steps declare a contract inside an `inputs do ... end` block
+
+```ruby
+step :charge do
+  inputs do
+    input :amount,   :decimal, gt?: 0
+    input :currency, :string,  included_in?: %w[USD EUR GBP]
+  end
+
+  argument :amount,   input(:amount)      # still the template reference
+  argument :currency, input(:currency)
+
+  run { |args, _| charge!(args) }
+end
+```
+
+**Rationale**: Finding 4. Inside the `inputs` block, `self` is a contract builder where
+`input` unambiguously declares; outside it, `input(:x)` keeps meaning the template reference
+it has always meant. Zero back-compat risk, no arity magic, and the declaration lines are
+byte-identical to the ones in a step class — moving an inline step into a class is deleting
+the wrapper (FR-007, SC-005).
+
+**Alternatives rejected**:
+
+- *Arity overload* — `input(:x)` returns a template, `input(:x, :string)` declares. Tempting
+  (no extra nesting) but `input :x` as a bare statement becomes silently meaningless, and the
+  same token in the same block would mean two different things depending on argument count.
+  This is exactly the "strange bugs and hard-to-debug validation errors" the spec exists to
+  remove.
+- *Renaming the template helper* to `reactor_input(:x)` — breaks every existing reactor.
+
+### D3 — Enforcement lives in the step, via a prepended `run`
+
+`Step.included(base)` prepends a wrapper onto `base.singleton_class`. The wrapper validates
+the arguments against the contract and then calls `super`. A step with no contract skips
+straight to `super` (Finding 6).
+
+**Rationale**: one enforcement point covers all three call sites — the executor
+(`step_executor.rb:353`), the async worker (`step_worker.rb:118`, Finding 2), and direct
+invocation (FR-022) — instead of three. `TestSubject`'s mock wrapper
+(`rspec/test_subject.rb:647`) calls `impl.run`, so mocked steps validate too.
+
+On violation the wrapper **raises** `Error::InputValidationError` (Finding 3), not a `Failure`
+— that is the protocol the executor, the rollback path, and `have_validation_error` already
+speak.
+
+**Step attribution**: the step class knows its own name but not the reactor's step name.
+`safe_execute_step_sync`'s existing `rescue Error::InputValidationError` (`step_executor.rb:186`)
+gains `e.step_name ||= step_config.name` before the re-raise — attribution stamped where the
+name is known.
+
+**Alternatives rejected**: building the step's validator into `StepConfig#args_validator` at
+DSL time. Simpler-looking, but leaves the worker path unvalidated and direct invocation
+unvalidated, and re-centralizes in the reactor what this feature is trying to move into the
+step.
+
+### D4 — Inline contracts reuse `args_validator`; the worker path gets the missing call
+
+An inline step has no class to prepend to, so its `inputs` block compiles to an
+`args_validator` on `StepConfig`, enforced by the existing `validate_step_arguments`. To
+close Finding 2, `StepWorker#execute_step_body` gains the same validation call, and its
+`rescue StandardError` grows an `Error::InputValidationError` branch so the worker produces
+the same failure shape rather than a generic `Failure(e)`.
+
+Two mechanisms, one protocol: both raise `Error::InputValidationError`, both land in
+`build_validation_failure`.
+
+### D5 — Reactor-side conflicts fail at the `step` macro
+
+`StepBuilder#build` already has both `@impl` and `@arg_validations`. When `@impl` declares a
+contract and the reactor supplied a type, predicates, `validate_args`, or an `inputs` block,
+raise immediately — the error points at the offending line in the reactor class body
+(FR-006). Same for an `argument` naming an input the contract does not declare (FR-018).
+
+Message names the reactor, the step, the argument, and the owning step class.
+
+### D6 — Satisfiability is checked by `validate_definition!`, memoized, at first execution
+
+FR-021 needs the reactor's full input list, which is not known while the class body is still
+executing — `input` declarations may follow `step` declarations. Finding 7 rules out a
+global boot-time sweep.
+
+`Reactor.validate_definition!` walks every step with a contract and asserts each required
+input is satisfied by an explicit `argument` or a same-named reactor input. It is memoized
+and invoked from `Reactor.run`/`.call` before execution begins, and from `test_reactor`, and
+is public so an application can call it in an initializer or CI check.
+
+**Deviation from spec wording**: FR-008/FR-021 and US4 say "when the reactor class is
+loaded". Conflict and unknown-argument checks (D5) genuinely are load-time. The
+satisfiability check fires at first execution instead. The user-visible property the spec
+cares about — the error names the reactor, step, and input, and does not depend on reaching
+that step at run time — holds either way: a reactor whose wiring is incomplete fails before
+step one runs, not on the unlucky run that first reaches the step.
+
+**Alternatives rejected**: `TracePoint(:end)` to detect the end of a class body (clever,
+unreadable, breaks on reopened classes); requiring `input` before `step` (silently breaks
+valid existing reactors).
+
+### D7 — Name-based fallback resolves at `validate_definition!` time, reactor inputs only
+
+An unwired declared input becomes `Template::Input.new(name)` appended to the step's
+`arguments` — the same object an explicit `argument :x, input(:x)` produces, so nothing
+downstream changes. Explicit wiring wins (never overwritten). Step results are never
+consulted (FR-020), so resolution can't shift when an unrelated step is renamed.
+
+### D8 — Presence means "supplied", via one shared helper
+
+Add `RubyReactor::Utils.fetch_indifferent(hash, key)` —
+`hash.key?(key.to_sym) ? hash[key.to_sym] : hash[key.to_s]` — and use it at `context.rb:67`,
+`context.rb:79`, and `template/result.rb:178`. Defaults (FR-013) apply when the key is absent
+or the resolved value is `nil`; `false` is neither, so it survives.
+
+**SemVer**: a fix, not a break — no documented behavior said `false` becomes `nil`.
+
+### D9 — Deprecation, not removal, for reactor-declared rules
+
+`argument :x, src, :string, gt?: 0` on a step with no contract keeps working unchanged
+(FR-010). It emits a one-time-per-site deprecation naming the `input` replacement once the
+step's own contract is the documented path (FR-011). Removal is a later MAJOR.
+
+## Open risks
+
+| Risk | Mitigation |
+|---|---|
+| Prepending to `singleton_class` surprises anyone who aliases or redefines `self.run` after `include` | Prepend happens at `include` time, so a later `def self.run` is still `super`'d correctly. Covered by a spec. |
+| `inputs do` block inside `step` is a third nesting level | Only for inline steps; the constitution already names class steps the preferred style. |
+| Two enforcement mechanisms (D3 prepend, D4 validator) could drift | Both raise the same error class through the same handler; a shared spec asserts identical outcomes for the class and inline forms (SC-005). |
+| Falsey fix changes behavior for anyone relying on `false → nil` | Pre-existing defect; changelog note under Bug Fixes. |