ruby_reactor 0.8.2 → 0.8.3

data/specs/002-step-input-contracts/contracts/dsl-surface.md

@@ -1,193 +0,0 @@
-# Public DSL Contract: Step Input Contracts
-
-**Feature**: `specs/002-step-input-contracts/` | **Date**: 2026-09-10
-
-The gem's external interface is its DSL. This document is the contract that
-`spec/ruby_reactor/dsl/` specs assert against and that README must match.
-
-## 1. `input` — declare a contract (step class)
-
-```ruby
-input(name, type = nil, optional: false, default: nil, redact: false,
-      validate: nil, **predicates, &block)
-```
-
-Available on any class that `include RubyReactor::Step`. Signature is intentionally identical
-to the reactor's `input`, minus `transform:` (a step does not transform its own inputs — the
-reactor's `argument` does that).
-
-```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
-  input :token, :string,  redact: true
-
-  input :window do |i|                      # Form 2 — macro block
-    i.filled(:integer, gteq?: 1, lteq?: 24)
-  end
-
-  input :payload, validate: PayloadSchema    # Form 3 — pre-built schema
-
-  def self.run(args, context)
-    Success(profile_from(args))
-  end
-end
-```
-
-**Forms** (dispatch matches `Dsl::Reactor::ClassMethods#build_input_validator_for`):
-
-| Form | Written as | Compiles to |
-|---|---|---|
-| 0 | `input :x` | declaration only, no rule |
-| 1 | `input :x, :string, min_size?: 2` | `required(:x).filled(:string, min_size?: 2)` |
-| 1b | `input :x, User` | `required(:x).filled(type?: User)` |
-| 1-opt | `input :x, :string, optional: true` | `optional(:x).maybe(:string)` |
-| 2 | `input :x do \|i\| ... end` | block bound to the value macro |
-| 3 | `input :x, validate: Schema` | the supplied schema |
-
-## 2. `validate_inputs` — cross-field rules (step class)
-
-```ruby
-class ChargeStep
-  include RubyReactor::Step
-
-  input :amount,   :decimal, gt?: 0
-  input :currency, :string
-
-  validate_inputs do
-    required(:amount).filled(:decimal, lt?: 10_000)
-  end
-end
-```
-
-Composes with the per-input rules; applied last, wins on conflict — same precedence as the
-reactor's existing `validate_args`.
-
-## 3. `inputs do ... end` — declare a contract (inline step)
-
-```ruby
-step :charge do
-  inputs do
-    input :amount,   :decimal, gt?: 0
-    input :currency, :string,  included_in?: %w[USD EUR GBP]
-
-    validate_inputs do
-      required(:amount).filled(:decimal, lt?: 10_000)
-    end
-  end
-
-  argument :amount,   input(:amount)     # `input(:x)` here is still the template reference
-  argument :currency, input(:currency)
-
-  run { |args, _| charge!(args) }
-end
-```
-
-The wrapper block exists because inside a `step` block, bare `input(:x)` already means
-"reference the reactor input" (`Dsl::TemplateHelpers#input`). Inside `inputs do`, `input`
-unambiguously declares. The declaration lines are byte-identical to a step class's, so moving
-an inline step into a class is deleting the wrapper.
-
-## 4. `argument` — wiring only
-
-```ruby
-argument(name, source, transform: nil)
-```
-
-Unchanged for dependency resolution and value mapping.
-
-| Step owns a contract? | `argument :x, src` | `argument :x, src, :string, gt?: 0` | `validate_args do ... end` |
-|---|---|---|---|
-| Yes | ✅ | ❌ raises at the `step` macro | ❌ raises at the `step` macro |
-| No | ✅ | ✅ + deprecation notice | ✅ + deprecation notice |
-
-An `argument` naming an input a contract-owning step does not declare raises at the `step`
-macro.
-
-## 5. Name-based resolution
-
-A declared input with no `argument` is satisfied by the reactor input of the same name.
-
-```ruby
-class MyReactor < RubyReactor::Reactor
-  input :amount
-  input :currency
-
-  step :charge, ChargeStep          # both inputs resolved by name
-end
-```
-
-Rules:
-
-- Reactor inputs only — never another step's result.
-- An explicit `argument` always wins and is never overwritten.
-- A required input satisfied by neither raises before execution begins, naming the step, the
-  input, and both ways to satisfy it.
-
-## 6. Introspection
-
-```ruby
-ChargeStep.input_contract          # => RubyReactor::Step::InputContract
-ChargeStep.declared_inputs         # => { amount: InputDeclaration, ... }
-ChargeStep.required_input_names    # => [:amount, :currency]
-ChargeStep.declares_inputs?        # => true
-```
-
-Read-only. Used by `validate_definition!`, by tooling, and by the dashboard.
-
-## 7. Enforcement points
-
-| Entry point | Enforced | Mechanism |
-|---|---|---|
-| Reactor step execution | ✅ | prepended `run` (class) / `args_validator` (inline) |
-| Retry attempt | ✅ | same, re-validated per attempt |
-| `async_step` worker | ✅ | prepended `run` (class); explicit call in `StepWorker#execute_step_body` (inline) |
-| `background` hand-off worker | ✅ | ordinary step execution inside the worker |
-| Resume after interrupt | ✅ | ordinary step execution |
-| Each `map` iteration | ✅ | child reactor's own step execution |
-| `ChargeStep.run(args, ctx)` directly | ✅ | prepended `run` |
-| `compensate` / `undo` | ❌ by design | rollback receives already-validated arguments |
-| Step that a `where`/guard skips | ❌ by design | a step that never runs never validates |
-
-## 8. Errors
-
-| Situation | Error | Carries |
-|---|---|---|
-| Contract violated | `RubyReactor::Error::InputValidationError` (raised) | `field_errors`, `step_name`, `step_arguments` |
-| Rules declared in reactor and step class | `RubyReactor::Error::ValidationError` at the `step` macro | reactor, step, argument, owning class |
-| `argument` for an undeclared input | `RubyReactor::Error::ValidationError` at the `step` macro | reactor, step, unknown argument |
-| Required input unwired and unmatched | `RubyReactor::Error::ValidationError` before execution | reactor, step, input, both remedies |
-| `default:` on a required input | `RubyReactor::Error::ValidationError` at the `input` call | input name |
-| Contract declared, dry-validation missing | `LoadError` at declaration | install instruction (existing message) |
-
-A raised `InputValidationError` reaches the caller as a `Failure` carrying `validation_errors`,
-after completed steps are rolled back — the existing path in
-`Executor::ResultHandler#handle_execution_error`. `have_validation_error(:field)` matches it
-unchanged.
-
-## 9. Presence semantics
-
-A value is "provided" when its key exists, never when it is truthy.
-
-| Supplied | Required input | Optional input with `default:` |
-|---|---|---|
-| `false` | ✅ passes, step receives `false` | keeps `false`, default not applied |
-| `0`, `""`, `[]` | ✅ passes | value kept |
-| `nil` | ❌ "must be filled" | default applied |
-| key absent | ❌ "is missing" | default applied |
-
-Holds for values sourced from reactor inputs, prior step results, and nested paths within
-either.
-
-## 10. Compatibility
-
-- Additive: every existing reactor and step class compiles and behaves identically.
-- `argument` with types/predicates and `validate_args` keep working for steps that declare no
-  contract; deprecated in favor of a step-owned contract, removal no earlier than the next
-  MAJOR.
-- Falsey-value resolution changes for anyone who relied on `false` arriving as `nil` — a bug
-  fix, recorded under Bug Fixes in the changelog.

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

@@ -1,115 +0,0 @@
-# Phase 1 Data Model: Step Input Contracts
-
-**Feature**: `specs/002-step-input-contracts/` | **Date**: 2026-09-10
-
-Everything here is definition-time state held on Ruby classes. Nothing new is persisted to
-Redis; resolved argument values continue to round-trip through `ContextSerializer` exactly as
-today.
-
-## InputDeclaration
-
-One declared value of one unit of work. Produced by `input` in a step class or inside an
-inline step's `inputs do` block.
-
-| Field | Type | Default | Notes |
-|---|---|---|---|
-| `name` | Symbol | — | Required. Unique within a contract; a redeclaration replaces the earlier one. |
-| `type` | Symbol \| Module \| nil | `nil` | `:string`/`:integer`/`:decimal`… → dry-schema positional type. A Module → `type?: Klass` instance check. `nil` → no type constraint. |
-| `optional` | Boolean | `false` | `false` → `required(name).filled(...)`. `true` → `optional(name).maybe(...)`. |
-| `default` | Object \| nil | `nil` | Applied when the key is absent or resolves to `nil`. Never applied for `false` (FR-023). Mutually meaningful only with `optional: true`. |
-| `redact` | Boolean | `false` | Value is masked in failures and logs (FR-015). |
-| `predicates` | Hash | `{}` | dry-schema predicates: `gt?`, `gteq?`, `min_size?`, `max_size?`, `included_in?`, … |
-| `macro_block` | Proc \| nil | `nil` | Form-2 block: `input :x do |i| i.filled(:string) end`. Bound to the value macro. |
-| `schema` | Object \| nil | `nil` | Form-3 pre-built schema/contract via `validate:`. |
-
-**Validation rules**: `name` must be a Symbol; exactly one of `predicates`+`type`,
-`macro_block`, or `schema` shapes the rule (matching the reactor's existing `input` dispatch in
-`Dsl::Reactor::ClassMethods#build_input_validator_for`); `default` without `optional: true`
-raises at declaration time.
-
-## InputContract
-
-The full set of declarations owned by one unit of work, plus the compiled validator.
-
-| Field | Type | Notes |
-|---|---|---|
-| `owner` | Class \| step name | The step class, or the inline step's name. |
-| `declarations` | Ordered Hash{Symbol → InputDeclaration} | Declaration order preserved for message stability. |
-| `cross_field_block` | Proc \| nil | Cross-field rules over the whole argument hash (FR-002). Composed last, wins on conflict — same precedence as today's `validate_args`. |
-| `validator` | `Validation::InputValidator` | Compiled once, lazily, via `SchemaBuilder.build_args(inline_rules, cross_field_block)`. |
-
-**Derived queries** (the introspection surface, FR-014):
-
-- `required_names` → declarations where `optional == false`
-- `optional_names`, `defaults`, `redacted_names`
-- `declares?(name)`
-
-**Inheritance**: a subclass's contract is `parent.declarations.merge(own.declarations)` — same
-name in the subclass replaces the parent's entry (spec Edge Cases). Resolved by walking the
-superclass chain at first access, memoized per class.
-
-**State**: `declared` (during class body) → `compiled` (first validation or first
-introspection) → immutable. A declaration added after compilation resets to `declared`;
-supported so reopened classes behave predictably, not an encouraged pattern.
-
-## ArgumentWiring
-
-The reactor-side binding. Already exists as the entries of `StepConfig#arguments`; this
-feature narrows its meaning to source + transform only.
-
-| Field | Type | Notes |
-|---|---|---|
-| `name` | Symbol | Must match an `InputDeclaration#name` when the step owns a contract (FR-018). |
-| `source` | `Template::Input` \| `Template::Result` \| `Template::Value` \| `Template::Element` | Unchanged. Also carries dependency information for the DAG. |
-| `transform` | Proc \| nil | Unchanged. Applied after resolution, before validation. |
-| `origin` | `:explicit` \| `:inferred` | New. `:inferred` marks a wiring synthesized by the name-based fallback (FR-020), so error messages and the dashboard can say where it came from. |
-
-**Rules**: an `:explicit` wiring is never replaced by an `:inferred` one. Rules and types on an
-`argument` are rejected when the step owns a contract (FR-006); still accepted, with a
-deprecation notice, when it does not (FR-010).
-
-## ContractCheckResult
-
-Definition-time diagnostics. Not persisted — raised as errors.
-
-| Check | When | Raises | FR |
-|---|---|---|---|
-| Rules declared in both places | `step` macro (`StepBuilder#build`) | `Error::ValidationError` naming reactor, step, argument, owning class | FR-006 |
-| `argument` for an undeclared input | `step` macro | `Error::ValidationError` naming the unknown argument | FR-018 |
-| Required input neither wired nor name-matched | `Reactor.validate_definition!` | `Error::ValidationError` naming step, input, and both ways to satisfy it | FR-008, FR-021 |
-| `default` on a required input | `input` call | `Error::ValidationError` | — |
-
-## Validation failure payload
-
-Unchanged shape — this feature adds sources, not structures. `build_validation_failure`
-(`executor/result_handler.rb`) already emits:
-
-| Field | Source |
-|---|---|
-| `validation_errors` | `InputValidator#format_errors` — flattened `{field => message}` |
-| `step_name` | Stamped by `StepExecutor` for class steps (new, D3); set at the raise site for inline steps (existing) |
-| `reactor_name` | Existing |
-| `step_arguments` | Existing; redacted per `InputDeclaration#redact` |
-
-`have_validation_error(:field)` reads `validation_errors` and therefore works against
-contract failures with no matcher change.
-
-## Lifecycle
-
-```text
-class body        input :amount, :decimal, gt?: 0   → InputDeclaration
-                  ────────────────────────────────    appended to InputContract (declared)
-
-reactor body      step :charge, ChargeStep do
-                    argument :amount, input(:amount) → ArgumentWiring(:explicit)
-                  end
-                  └─ StepBuilder#build ─────────────→ ContractCheckResult (conflict, unknown arg)
-
-first execution   Reactor.validate_definition!      → ContractCheckResult (satisfiability)
-                                                    → ArgumentWiring(:inferred) for unwired
-                                                      declared inputs matching reactor inputs
-
-per step run      resolve_arguments                 → Hash{name => value} (presence-preserving)
-                  contract.validator.call(args)     → Success | raise InputValidationError
-                  step body                         → Result
-```

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

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

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