ruby_reactor 0.7.1 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: abde4c2dc313b2e5d4a74873f1fc337743e6847e8f47fcbd121fd1a72be1d557
-  data.tar.gz: defd25588b78022c339ffd105d4e304d80e676498272c887cafecb60f100dc7e
+  metadata.gz: 6e671a274b5dc3854189ab1f3c40ff4d7e307a567ed960dbad0be1405f05ff58
+  data.tar.gz: 0a44e9cf8dbed99b72762381300c4c503500d3025f21288e473eef377a28dbec
 SHA512:
-  metadata.gz: 595c701f476086c166d0e157c062e0bea0e6fb243b1c5466017bf488461b987b44c70b56e081770c586a1d83519311c58da9769ae83e302fb7d17d1cdc8f37fb
-  data.tar.gz: 7dadad987df2ec6d9c1b44e93ed328f07d77660310726dceeb1ee8957cc9e63b73bd3c2338792280bfc780a95650bcac12b384af3d2aad83b3309aa4896f6d0d
+  metadata.gz: a39666bdba5d7c911589da0f30a12e29a9f5187c31a9a1bfb9ddc0c55aba26cac201db3e8083854f79858d6845ed98097589979873a0a4aa7cc8dfdaca635856
+  data.tar.gz: a5069c91a3942f1697a317baee2223b790b4262ca6d90f61a1b3aa0cd8b61ff9b199b7a05f58f791df11bd7b4336611907a6abd3cbce6ebfd007d9bc92949c4e

data/.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "0.7.1"
+  ".": "0.8.0"
 }

data/.specify/feature.json

@@ -1,3 +1,3 @@
 {
-  "feature_directory": "specs/001-reactor-signal-semantics"
+  "feature_directory": "specs/004-inheritable-step-class"
 }

data/.specify/memory/constitution.md

@@ -1,25 +1,27 @@
 <!--
 SYNC IMPACT REPORT
 ==================
-Version change: 1.1.0 → 1.2.0 (MINOR: Principle VI expanded with a 4th requirement —
-  docker-compose.yml currency + docker-run acceptance tests)
+Version change: 1.2.1 → 1.3.0 (MINOR: Development Workflow now REQUIRES every generated
+  plan.md and tasks.md to carry an explicit documentation-update task/gate, with the
+  requirement propagated into both templates — a new enforcement mechanism, not just
+  wording)
 
-Modified principles:
-  - Principle VI: Demo-App Proof of Feature — added requirement 4, "Docker acceptance
-    run" (docker-compose.yml MUST track demo_app's services; demo: rake tasks are the
-    project's acceptance suite, runnable via `docker compose run`)
+Modified principles: none (Development Workflow section, not a Core Principle)
 
-Added sections: none (existing Principle VI section extended)
+Added sections: none
 
 Removed sections: none
 
 Templates checked:
-  - .specify/templates/plan-template.md   ✅ Constitution Check gate is generic ("Gates determined
-                                             based on constitution file") — no edit required
-  - .specify/templates/spec-template.md   ✅ No principle-specific content — no edit required
-  - .specify/templates/tasks-template.md  ✅ Already covers demo-app polish tasks — no edit required
+  - .specify/templates/plan-template.md      ✅ Added Constitution Check checklist item:
+                                                 identify README.md/./documentation impact
+  - .specify/templates/spec-template.md      ✅ No principle-specific content — no edit required
+  - .specify/templates/tasks-template.md     ✅ Polish-phase doc task now explicit and marked
+                                                 REQUIRED, citing README.md + ./documentation
   - .specify/templates/checklist-template.md ✅ Generic — no edit required
-  - .specify/extensions.yml               ✅ No before/after_constitution hooks registered
+  - .specify/extensions.yml                  ✅ No before/after_constitution hooks registered
+  - README.md                                ✅ No principle-specific claims to update
+  - documentation/*.md                       ✅ No principle-specific claims to update
 
 Deferred TODOs: none
 -->
@@ -164,9 +166,17 @@ gaps in the matcher library surface as work instead of as workarounds.
 - Feature branches target `main`. PRs MUST pass CI (RSpec + RuboCop) before merge.
 - Releases are managed by release-please. Version bump lives in
   `lib/ruby_reactor/version.rb`. Do not manually edit the version in gemspec.
-- New features MUST update `README.md` documentation and add entries to
-  `CHANGELOG.md` under the correct semantic heading (`Features`, `Bug Fixes`,
-  `documentation`).
+- Every task MUST update documentation as part of its own change, not as a
+  follow-up: `README.md` and any affected file under `./documentation` MUST be
+  kept current with the behavior the task introduces, changes, or removes. A
+  task that alters observable behavior without a matching documentation update
+  is incomplete. New features additionally MUST add entries to `CHANGELOG.md`
+  under the correct semantic heading (`Features`, `Bug Fixes`, `documentation`).
+- Every `plan.md` produced by `/speckit-plan` and every `tasks.md` produced by
+  `/speckit-tasks` MUST include at least one explicit task or checklist item to
+  update `README.md` and the relevant file(s) under `./documentation` for the
+  feature's behavior. A plan or task list that omits a documentation-update
+  task is incomplete and MUST be rejected in review.
 - Class-based step definitions are the preferred authoring style (not inline
   lambdas). Documentation and examples MUST reflect this.
 - The `demo_app/` directory serves as a living integration example. Changes to
@@ -198,4 +208,4 @@ justified in the `Complexity Tracking` table of the plan.
 Compliance review: at each MINOR or MAJOR gem release, confirm this constitution
 still accurately reflects the codebase and update as needed.
 
-**Version**: 1.2.0 | **Ratified**: 2025-10-02 | **Last Amended**: 2026-09-09
+**Version**: 1.3.0 | **Ratified**: 2025-10-02 | **Last Amended**: 2026-09-11

data/.specify/templates/plan-template.md

@@ -42,6 +42,10 @@
 
 [Gates determined based on constitution file]
 
+- [ ] Documentation impact identified: which `README.md` sections and which
+      file(s) under `./documentation` this feature will require updating
+      (Constitution Development Workflow — carried into tasks.md as a required task)
+
 ## Project Structure
 
 ### Documentation (this feature)

data/.specify/templates/tasks-template.md

@@ -151,7 +151,7 @@ Examples of foundational tasks (adjust based on your project):
 
 **Purpose**: Improvements that affect multiple user stories
 
-- [ ] TXXX [P] Documentation updates in docs/
+- [ ] TXXX [P] Update `README.md` and affected file(s) under `./documentation` for this feature (REQUIRED — Constitution Development Workflow)
 - [ ] TXXX Code cleanup and refactoring
 - [ ] TXXX Performance optimization across all stories
 - [ ] TXXX [P] Additional unit tests (if requested) in tests/unit/

data/CHANGELOG.md

@@ -1,5 +1,145 @@
 # Changelog
 
+## Unreleased
+
+### ⚠ BREAKING CHANGES
+
+* **`RubyReactor::Step` is now a base class, not a mixin.** `include RubyReactor::Step` on a
+  plain class with `def self.run(arguments, context)` is gone — no compatibility shim, no dual
+  authoring style. A step subclasses `RubyReactor::Step` and writes `run` (and optionally
+  `compensate`/`undo`) as **instance** methods reading the validated arguments and the context
+  through `inputs`/`context` accessors instead of parameters. Every instance is built fresh for
+  its one action (`run`, `undo`, or `compensate`) from the stored arguments/result/reason alone —
+  nothing an author sets in `run` is visible in a later `undo`/`compensate`, which is exactly what
+  makes rollback behave identically whether it lands in the same process as `run` or, as with an
+  `async_step`, in a separate later one. `inputs` holds the same values in all three actions: the
+  arguments with the contract's defaults applied. Only `run` enforces the contract; `undo` and
+  `compensate` never do, so rollback cannot fail on the inputs that caused the failure.
+
+  ```ruby
+  # Before
+  class ChargeStep
+    include RubyReactor::Step
+
+    input :amount, :integer, gteq?: 1
+
+    def self.run(arguments, context)
+      Success(charge!(arguments[:amount]))
+    end
+
+    def self.undo(result, arguments, context)
+      refund!(result[:charge_id])
+      Success()
+    end
+  end
+
+  # After
+  class ChargeStep < RubyReactor::Step
+    input :amount, :integer, gteq?: 1
+
+    def run
+      Success(charge!(inputs[:amount]))
+    end
+
+    def undo
+      refund!(result[:charge_id])
+      Success()
+    end
+  end
+  ```
+
+  **Migration:** for every class step, replace `include RubyReactor::Step` with
+  `< RubyReactor::Step`, turn `def self.run(args, ctx)` into `def run` reading `inputs`/`context`,
+  and likewise for `def self.undo(result, args, ctx)` / `def self.compensate(reason, args, ctx)` →
+  `def undo` / `def compensate` reading `result`/`reason`/`inputs`/`context`. The class-level
+  `MyStep.run(arguments, context)` / `.call` / `.undo(result, arguments, context)` /
+  `.compensate(reason, arguments, context)` entry points every caller (executor, worker, a direct
+  unit-test call) already used are unchanged. Inline `step { run { |args, ctx| ... } }` blocks are
+  untouched by this change.
+
+* **A class step's signal helpers (`success!`/`fail!`/`skip!`/`halt!`) now translate correctly on
+  every execution path, including the `async_step`/`background` worker.** Previously the worker had
+  no `catch` of its own, so a signal thrown from a class step running there escaped as an
+  `UncaughtThrowError` instead of the intended `Success`/`Failure`/`Skipped`/`Halt` — the base
+  class's class-level `run`/`undo`/`compensate` now own that translation, so every caller gets it
+  for free with no worker change. Known remaining gap, unchanged by this release: an **inline**
+  `run`/`compensate`/`undo` block's signals are still uncaught on the worker path.
+
+* **A step's own input-validation failure is now guaranteed non-retryable on every path.**
+  `result.retryable?` is `false` whether the violation happened synchronously, inside an
+  `async_step`/`background` worker, or inside a `compose`d child's own step — previously only the
+  async worker path got this right; the synchronous path and a validation failure surfacing
+  through `compose` both defaulted to `retryable? == true`.
+
+* **`Failure(...)` takes the same arguments everywhere.** Inside a class step and inside an inline
+  `run`/`compensate`/`undo` block, `Failure` now forwards every argument to `RubyReactor.Failure`,
+  so options such as `Failure("declined", retryable: false)` work instead of raising
+  `ArgumentError`. A bare `Failure()` with no error is no longer accepted, matching
+  `RubyReactor.Failure`, and a hash error needs braces, `Failure({ code: 1 })`, because a braceless
+  `Failure(code: 1)` is now read as options.
+
+### Features
+
+* **Step input contracts.** A step class declares its own inputs with `input :name, :type, **predicates`
+  (plus `optional:`, `default:`, `redact:`, the `do |i| ... end` macro block and `validate:`) and
+  cross-field rules with `validate_inputs`. The contract is enforced before `run` on every path
+  (inline, retries, `async_step` and `background` workers, resume, `map`, and a direct
+  `Step.run(args, context)` call), and a violation fails with `validation_errors` and the step's
+  name after completed steps are rolled back. Subclasses inherit and extend the contract.
+  Introspection: `input_contract`, `declared_inputs`, `required_input_names`, `declares_inputs?`.
+* **Inline step contracts.** `inputs do ... end` inside a `step` block takes the same `input` /
+  `validate_inputs` lines as a step class and is enforced the same way.
+* **Wiring by name.** A declared input with no `argument` resolves from the reactor input of the
+  same name (never from a step result). A required input that is neither wired nor a reactor input
+  raises `Error::ValidationError` before any step runs. `Reactor.validate_definition!` runs that
+  check on demand, e.g. from an initializer or CI.
+* For a step that owns a contract, a type or predicate on `argument`, `validate_args`, or an
+  `argument` for an undeclared input raises `Error::ValidationError` when the `step` line is
+  evaluated.
+* `have_validation_error` now also matches validation failures raised at a step, not only
+  reactor-input failures.
+* `Failure#to_h` includes `retryable`, so a non-retryable failure stays non-retryable after it
+  crosses a worker boundary.
+* A step that returns another unit's validation failure (e.g. an `async_step` reader propagating
+  the worker's `Failure`) keeps its `validation_errors` on the reactor's final failure.
+
+### Deprecations
+
+* Rules on `argument` (`argument :x, src, :type, **predicates`) and `validate_args` keep working
+  for steps without a contract, and print one deprecation notice per declaration site. Move them
+  to `input` / `validate_inputs` on the step class, or into an `inputs do ... end` block for an
+  inline step, and keep `argument :x, src` for wiring. Removal is no earlier than the next major
+  version. See "Step Input Contracts" in the README for the migration.
+
+### Bug Fixes
+
+* A supplied `false` reactor input or step result no longer resolves to `nil`.
+  `Context#get_input`, `Context#get_result` and `Template::Result#fetch` now check whether the key
+  exists instead of whether the value is truthy. Code that relied on `false` arriving as `nil`
+  will now see `false`.
+* An input-validation `Failure` stays non-retryable across serialization. `Failure`'s
+  hash extractor and the reactor's stored `failure_reason` both dropped a `retryable: false`
+  (`||` swallowed the `false`, and the reactor never stored the flag at all), so a failure
+  rebuilt from JSON or reloaded with `Reactor.find` reported `retryable? == true`.
+* A step-contract violation inside `compose` now reaches the parent with its `validation_errors`
+  and retryability intact, instead of being rebuilt from the child's error message alone.
+* A reactor reopened after its first run is re-checked: `validate_definition!` no longer memoizes,
+  so a step declared later can no longer reach execution with a required input unwired.
+* A class step that calls `halt!` under `async_step` is recorded as a halt rather than an
+  ordinary `nil` success, and `result(:step)` hands the reader the `Halt` — the same way it
+  already hands over a `Failure`.
+
+## [0.8.0](https://github.com/arturictus/ruby_reactor/compare/v0.7.1...v0.8.0) (2026-09-21)
+
+
+### ⚠ BREAKING CHANGES
+
+* Step Instance and input validations per step  ([#51](https://github.com/arturictus/ruby_reactor/issues/51))
+
+### Features
+
+* Step Instance and input validations per step  ([#51](https://github.com/arturictus/ruby_reactor/issues/51)) ([4a20583](https://github.com/arturictus/ruby_reactor/commit/4a2058399d73e9b3bf767659dd5ba080537dc291))
+
 ## [0.7.1](https://github.com/arturictus/ruby_reactor/compare/v0.7.0...v0.7.1) (2026-09-14)
 
 

data/CLAUDE.md

@@ -1,5 +1,5 @@
 <!-- SPECKIT START -->
 For additional context about technologies to be used, project structure,
 shell commands, and other important information, read the current plan:
-`specs/001-reactor-signal-semantics/plan.md`
+`specs/004-inheritable-step-class/plan.md`
 <!-- SPECKIT END -->

data/README.md

@@ -239,23 +239,24 @@ Whichever style you use, a step's `run` returns one of four signals — all expo
 
 One-line helpers end a step immediately from any call depth: `success!(value)`, `fail!(error, retry: true)`, `halt!(reason:)`, `skip!(value)` — equivalent to `return`ing the matching signal, usable in `run`, `compensate`, and `undo` bodies.
 
-**Class steps** are plain Ruby classes that include `RubyReactor::Step` and implement `run`, and optionally `compensate` and `undo`:
+**Class steps** subclass `RubyReactor::Step` and implement `run`, and optionally `compensate` and `undo`, as instance methods reading `inputs` and `context`:
 
 ```ruby
-class ReserveInventoryStep
-  include RubyReactor::Step
+class ReserveInventoryStep < RubyReactor::Step
+  # The step's input contract: enforced before `run` on every execution path.
+  input :order, :hash
 
-  def self.run(arguments, context)
-    reservation_id = InventoryService.reserve(arguments[:order][:items])
+  def run
+    reservation_id = InventoryService.reserve(inputs[:order][:items])
     Success(reservation_id: reservation_id)
   end
 
-  def self.compensate(error, arguments, context)
-    InventoryService.release_partial(arguments[:order][:items])
+  def compensate
+    InventoryService.release_partial(inputs[:order][:items])
     Success()
   end
 
-  def self.undo(result, arguments, context)
+  def undo
     InventoryService.release(result[:reservation_id])
     Success()
   end
@@ -322,29 +323,25 @@ RubyReactor allows you to define complex workflows as "reactors" with steps that
 ```ruby
 require 'ruby_reactor'
 
-class ValidateEmailStep
-  include RubyReactor::Step
-
-  def self.run(arguments, _context)
-    email = arguments[:email]
+class ValidateEmailStep < RubyReactor::Step
+  def run
+    email = inputs[:email]
     email&.include?('@') ? Success(email.strip) : Failure("Email must contain @")
   end
 end
 
-class CreateUserStep
-  include RubyReactor::Step
-
-  def self.run(arguments, _context)
+class CreateUserStep < RubyReactor::Step
+  def run
     Success(
       id: rand(10000),
-      email: arguments[:email],
-      password_hash: arguments[:password_hash],
+      email: inputs[:email],
+      password_hash: inputs[:password_hash],
       created_at: Time.now
     )
   end
 
-  def self.compensate(_error, arguments, _context)
-    Notify.to(arguments[:email])
+  def compensate
+    Notify.to(inputs[:email])
     Success()
   end
 end
@@ -1018,26 +1015,123 @@ result.error                       # => RubyReactor::Error::InputValidationError
 result.error.field_errors[:name]   # => "size cannot be less than 2"
 ```
 
-### Step Argument & Output Validation
+### Step Input Contracts
 
-Arguments can be validated inline using the same forms as `input`. Inline rules
-compose with a `validate_args` block (used for cross-field rules):
+A step declares the inputs it accepts; the reactor only says where each value
+comes from. Rules live with the unit of work, so a step reused by three
+reactors is validated the same way in all three.
 
 ```ruby
-step :charge do
-  argument :amount,   input(:amount),   :decimal, gt?: 0
-  argument :currency, input(:currency), :string,  included_in?: %w[USD EUR GBP]
-  argument :user,     input(:user),     User              # type? instance check
+class ChargeStep < RubyReactor::Step
+  input :amount,   :integer, gteq?: 1
+  input :currency, :string,  included_in?: %w[USD EUR GBP]
+  input :user,     User                                   # type? instance check
+  input :note,     :string,  optional: true, default: "", max_size?: 100
+  input :token,    :string,  redact: true                 # "[REDACTED]" in failures and traces
+
+  # Cross-field rules over the whole argument hash, applied last
+  validate_inputs do
+    required(:amount).filled(:integer, lt?: 10_000)
+  end
+
+  def run
+    Success(charge!(inputs))
+  end
+end
+```
+
+`input` takes the same forms as a reactor `input` (inline type and predicates,
+`do |i| ... end` macro block, `validate: Schema`). The contract is enforced before
+`run` on every path: inline execution, each retry attempt, `async_step` and
+`background` workers, resume, every `map` element, and a direct
+`ChargeStep.run(args, context)` call. A violation raises
+`RubyReactor::Error::InputValidationError`; inside a reactor that becomes a
+`Failure` with `validation_errors` and the step's name, after completed steps are
+rolled back, and `have_validation_error(:amount)` matches it.
+
+**Wiring.** `argument` only maps values:
+
+```ruby
+class ChargeReactor < RubyReactor::Reactor
+  input :amount
+  input :currency
+  input :user
+
+  step :charge, ChargeStep do
+    argument :user, result(:load_user)   # explicit wiring always wins
+  end                                    # :amount and :currency resolve by name
+end
+```
+
+A declared input with no `argument` resolves from the reactor input of the same
+name. Step results are never used for this. A required input that is neither
+wired nor a reactor input raises `RubyReactor::Error::ValidationError` before any
+step runs, naming the reactor, the step, the input, and both fixes.
+`ChargeReactor.validate_definition!` runs the same check without running the
+reactor, e.g. in an initializer or a CI task.
+
+For a step that owns a contract, these raise `RubyReactor::Error::ValidationError`
+when the `step` line is evaluated:
 
-  # Optional cross-field block (composes with the inline rules above)
-  validate_args do
-    required(:amount).filled(:decimal, lt?: 10_000)
+- a type or predicate on `argument` (`argument :amount, input(:amount), :integer`)
+- `validate_args`
+- an `argument` naming an input the step does not declare
+
+There are no per-reactor overrides. If two reactors need different bounds for the
+same value, write two steps (or a parameterized step), or relax the contract.
+
+**Inline steps** declare the same lines inside `inputs do ... end`. Inside the
+block `input` declares; outside it, `input(:x)` is still the template reference:
+
+```ruby
+step :charge do
+  inputs do
+    input :amount,   :integer, gteq?: 1
+    input :currency, :string,  included_in?: %w[USD EUR GBP]
   end
 
+  argument :amount,   input(:amount)
+  argument :currency, input(:currency)
+
   run { |args, _| charge!(args) }
 end
 ```
 
+Moving an inline step into a class is deleting the `inputs do` wrapper.
+
+**Presence.** A value is provided when its key exists, not when it is truthy:
+
+| Supplied | Required input | Optional input with `default:` |
+|---|---|---|
+| `false`, `0`, `""`, `[]` | passes, value kept | value kept |
+| `nil` | fails ("must be filled") | default applied |
+| key absent | fails ("is missing") | default applied |
+
+**Migrating from rules on `argument`.** Rules on `argument` and `validate_args`
+still work for steps with no contract, and print a one-time deprecation notice per
+declaration site. Removal is no earlier than the next major version.
+
+```ruby
+# Before
+step :charge, ChargeStep do
+  argument :amount, input(:amount), :integer, gteq?: 1
+  validate_args { required(:amount).filled(:integer, lt?: 10_000) }
+end
+
+# After: the rules move into the step
+class ChargeStep < RubyReactor::Step
+  input :amount, :integer, gteq?: 1
+  validate_inputs { required(:amount).filled(:integer, lt?: 10_000) }
+end
+
+step :charge, ChargeStep   # or keep `argument :amount, input(:amount)` for wiring
+```
+
+For an inline step, put the same `input` / `validate_inputs` lines inside
+`inputs do ... end`.
+
+### Step Output Validation
+
 Output validation is scalar-aware — pass a type/predicates for a single value,
 or a block for a hash output:
 

data/lib/ruby_reactor/context.rb

@@ -64,7 +64,7 @@ module RubyReactor
     end
 
     def get_input(name, path = nil)
-      value = @inputs[name.to_sym] || @inputs[name.to_s]
+      value = Utils::FetchIndifferent.call(@inputs, name)
       return nil if value.nil?
 
       if path
@@ -76,7 +76,7 @@ module RubyReactor
     alias input get_input
 
     def get_result(step_name, path = nil)
-      value = @intermediate_results[step_name.to_sym] || @intermediate_results[step_name.to_s]
+      value = Utils::FetchIndifferent.call(@intermediate_results, step_name)
       return nil if value.nil?
 
       if path

data/lib/ruby_reactor/dsl/interrupt_builder.rb

@@ -36,6 +36,12 @@ module RubyReactor
           end
       end
 
+      def inputs(*)
+        raise RubyReactor::Error::ValidationError,
+              "interrupt :#{@name} does not take an `inputs` contract; validate the resume payload with " \
+              "`validate_payload`."
+      end
+
       # Deprecated alias for {#validate_payload}.
       def validate(schema = nil, &block)
         unless @warned_validate

data/lib/ruby_reactor/dsl/reactor.rb

@@ -82,25 +82,11 @@ module RubyReactor
           input_validations[name] = validator if validator
         end
 
-        # Dispatch across the layered `input` forms:
-        #   Form 3 — pre-built schema / contract (`validate:`)
-        #   Form 2 — block bound to the value macro (`do |i| ... end`)
-        #   legacy — single-key schema block (`do required(:name)... end`)
-        #   Form 1 / 1b — inline scalar or class type
-        #   Form 0 — declaration only (no validator)
+        # The legacy single-key schema block is deprecated on reactor inputs
+        # only; the form dispatch itself is shared with step input contracts.
         def build_input_validator_for(name, type, optional, validate, predicates, &block)
-          if validate
-            create_input_validator(validate)
-          elsif block
-            if block.arity.nonzero?
-              build_macro_validator(name, optional, &block)
-            else
-              warn_deprecated_input_block
-              create_input_validator(block)
-            end
-          elsif type || predicates.any?
-            build_inline_validator(name, type, optional, predicates)
-          end
+          warn_deprecated_input_block if !validate && block&.arity&.zero?
+          build_declaration_validator(name, type, optional, validate, predicates, &block)
         end
         private :build_input_validator_for
 
@@ -163,6 +149,38 @@ module RubyReactor
           step_config
         end
 
+        # Checks that every required input of every contract-owning step is
+        # satisfied, and wires the unwired ones from same-named reactor inputs
+        # (never from step results). Runs before the first execution because
+        # the reactor's full input list is only known once its body has run;
+        # public so an app can call it at boot or in CI.
+        def validate_definition!
+          steps.each do |step_name, step_config|
+            contract = step_config.input_contract if step_config.respond_to?(:input_contract)
+            next unless contract
+
+            contract.declarations.each_value do |declaration|
+              wire_by_name!(step_name, step_config, declaration)
+            end
+          end
+        end
+
+        def wire_by_name!(step_name, step_config, declaration)
+          input_name = declaration.name
+          return if step_config.arguments.key?(input_name)
+
+          if inputs.key?(input_name)
+            step_config.arguments[input_name] =
+              { source: RubyReactor::Template::Input.new(input_name), transform: nil, origin: :inferred }
+          elsif !declaration.optional
+            raise RubyReactor::Error::ValidationError,
+                  "#{name || inspect} step :#{step_name} requires input :#{input_name}, which is neither wired " \
+                  "nor a reactor input. Wire it (`argument :#{input_name}, input(:x)` / `result(:step)`) or " \
+                  "declare `input :#{input_name}` on the reactor."
+          end
+        end
+        private :wire_by_name!
+
         def returns(step_name = nil)
           if step_name
             reject_async_return_step!(step_name)