ruby_reactor 0.7.1 → 0.8.0

data/lib/ruby_reactor/step.rb

@@ -1,42 +1,137 @@
 # frozen_string_literal: true
 
 module RubyReactor
-  module Step
-    def self.included(base)
-      base.extend(ClassMethods)
+  # The single inheritable base every class-based step derives from:
+  #
+  #   class MyStep < RubyReactor::Step
+  #     input :amount, :integer
+  #     def run = Success(charged: inputs[:amount])
+  #   end
+  #
+  # Lifecycle of every class-level call (`.run`/`.call`, `.undo`, `.compensate`):
+  #
+  # 1. Resolve `inputs`: the given arguments with the contract's defaults
+  #    applied. `run`, `undo`, and `compensate` all see the same values.
+  # 2. `.run` ONLY: enforce the declared input contract, raising
+  #    `Error::InputValidationError` before any instance exists. `.undo` and
+  #    `.compensate` NEVER enforce it: rollback must not fail on the very
+  #    inputs that may have caused the failure.
+  # 3. Build a FRESH instance, never reused across actions. An ivar set in
+  #    `run` is gone by the time `undo` runs on its own instance, so async
+  #    execution running `run` and `undo` in different processes behaves
+  #    identically to running both in one.
+  # 4. Invoke the matching instance method, translating any `StepSignals`
+  #    throw (`success!`/`skip!`/`fail!`/`halt!`) into its result wrapper.
+  #
+  # No `prepend`/`extend`/`define_method`/`method_missing` — every step in the
+  # class reads top to bottom as ordinary method calls.
+  class Step
+    include RubyReactor::StepSignals
+
+    attr_reader :inputs, :context, :result, :reason
+
+    def initialize(inputs, context, result: nil, reason: nil)
+      @inputs = inputs
+      @context = context
+      @result = result
+      @reason = reason
+    end
+
+    def run
+      raise NotImplementedError, "#{self.class} must implement #run"
+    end
+
+    def undo
+      RubyReactor.Skipped()
+    end
+
+    def compensate
+      RubyReactor.Skipped()
     end
 
-    module ClassMethods
-      include RubyReactor::StepSignals
+    # rubocop:disable Naming/MethodName
+    def Success(value = nil)
+      RubyReactor.Success(value)
+    end
+
+    def Failure(...)
+      RubyReactor.Failure(...)
+    end
+
+    def Halt(reason: nil, **kwargs)
+      RubyReactor.Halt(reason: reason, **kwargs)
+    end
+
+    def Skipped(...)
+      RubyReactor.Skipped(...)
+    end
+    # rubocop:enable Naming/MethodName
 
-      # rubocop:disable Naming/MethodName
-      def Success(value = nil)
-        RubyReactor::Success(value)
+    class << self
+      def run(arguments, context)
+        validated = enforce_contract!(arguments)
+        catch(StepSignals::TAG) { new(validated, context).run }
       end
+      alias call run
 
-      def Failure(error = nil)
-        RubyReactor::Failure(error)
+      # Same `inputs` as `.run` (defaults applied), but NEVER enforces the contract.
+      def undo(result, arguments, context)
+        catch(StepSignals::TAG) { new(with_defaults(arguments), context, result: result).undo }
       end
 
-      def Halt(reason: nil, **kwargs)
-        RubyReactor.Halt(reason: reason, **kwargs)
+      # Same `inputs` as `.run` (defaults applied), but NEVER enforces the contract.
+      def compensate(reason, arguments, context)
+        catch(StepSignals::TAG) { new(with_defaults(arguments), context, reason: reason).compensate }
       end
 
-      def Skipped(...)
-        RubyReactor.Skipped(...)
+      def input(...)
+        own_input_contract.input(...)
+        @input_contract = nil
       end
-      # rubocop:enable Naming/MethodName
 
-      def run(arguments, context)
-        raise NotImplementedError, "#{self} must implement .run method"
+      def validate_inputs(...)
+        own_input_contract.validate_inputs(...)
+        @input_contract = nil
+      end
+
+      def input_contract
+        @input_contract ||=
+          if superclass.respond_to?(:declares_inputs?) && superclass.declares_inputs?
+            superclass.input_contract.merge(own_input_contract)
+          else
+            own_input_contract
+          end
+      end
+
+      def declared_inputs
+        input_contract.declarations
+      end
+
+      def required_input_names
+        input_contract.required_names
+      end
+
+      def declares_inputs?
+        !input_contract.empty?
       end
 
-      def compensate(_reason, _arguments, _context)
-        RubyReactor.Skipped() # Default: nothing defined, rollback continues
+      private
+
+      def own_input_contract
+        @own_input_contract ||= Step::InputContract.new(owner: self)
       end
 
-      def undo(_result, _arguments, _context)
-        RubyReactor.Skipped() # Default: nothing defined, rollback continues
+      def with_defaults(arguments)
+        input_contract.apply_defaults(arguments)
+      end
+
+      def enforce_contract!(arguments)
+        return arguments unless declares_inputs?
+
+        input_contract.enforce!(arguments)
+      rescue Error::InputValidationError => e
+        e.step_name = name
+        raise
       end
     end
   end

data/lib/ruby_reactor/step_signals.rb

@@ -9,8 +9,12 @@ module RubyReactor
   # Implemented as throw/catch rather than an exception: a `throw` passes
   # straight through `rescue Exception` while `ensure` blocks still run
   # (verified in research.md R2), so a step's own broad rescue cannot swallow
-  # the author's intended outcome. The catching `catch(StepSignals::TAG)` lives
-  # at each step-body invocation site (step_executor.rb, compensation_manager.rb).
+  # the author's intended outcome. For a class-based step, the catching
+  # `catch(StepSignals::TAG)` lives on RubyReactor::Step's own class-level
+  # `run`/`undo`/`compensate` (so every caller — the executor, the async
+  # worker, a direct call — gets identical translation for free); for an
+  # inline `run_block`/`compensate_block`/`undo_block` step, it lives at the
+  # invocation site in step_executor.rb / compensation_manager.rb.
   module StepSignals
     TAG = :ruby_reactor_step_signal
 

data/lib/ruby_reactor/step_worker.rb

@@ -56,6 +56,9 @@ module RubyReactor
       context = load_step_context
       return record_missing_parent unless context
 
+      # A fresh worker process has never run the reactor, so the inferred
+      # wiring for name-resolved inputs does not exist here yet.
+      context.reactor_class&.validate_definition!
       step_config = context.reactor_class&.steps&.[](@step_name)
       return record_missing_step unless step_config
 
@@ -113,6 +116,7 @@ module RubyReactor
       result =
         if step_config.has_run_block?
           args = arguments.empty? ? context.inputs : arguments
+          args = step_config.inline_contract.enforce!(args) if step_config.inline_contract
           step_config.run_block.call(args, context)
         elsif step_config.has_impl?
           step_config.impl.run(arguments, context)
@@ -121,6 +125,12 @@ module RubyReactor
         end
 
       normalize(result)
+    rescue Error::InputValidationError => e
+      # Same shape the executor builds, and never retried: the same arguments
+      # fail the same contract on every attempt.
+      RubyReactor.Failure(e, validation_errors: e.field_errors, step_name: @step_name,
+                             step_arguments: e.step_arguments || {}, reactor_name: @reactor_class_name,
+                             retryable: false)
     rescue StandardError => e
       RubyReactor.Failure(e, step_name: @step_name, reactor_name: @reactor_class_name)
     end
@@ -158,16 +168,21 @@ module RubyReactor
     # Write first, publish second. The record is the answer; the signal only
     # saves the reader a fallback interval.
     def complete(result, context)
-      storage.store_step_result(
-        @step_context_id, @step_name,
-        {
-          "status" => "completed",
-          "success" => result.success?,
-          "result" => ContextSerializer.serialize_value(result.success? ? result.value : result.to_h),
-          "completed_at" => Time.now.iso8601
-        },
-        @reactor_class_name
-      )
+      record = {
+        "status" => "completed",
+        "success" => result.success?,
+        "result" => ContextSerializer.serialize_value(result.success? ? result.value : result.to_h),
+        "completed_at" => Time.now.iso8601
+      }
+      # A `halt!` reports success? == true but carries no value, so without
+      # this the reader cannot tell it from an ordinary success returning nil.
+      # `skip!` needs nothing extra: Skipped keeps its value, and the reader is
+      # meant to see that value exactly as a same-process step would.
+      if result.is_a?(RubyReactor::Halt)
+        record["signal"] = "halt"
+        record["reason"] = result.reason
+      end
+      storage.store_step_result(@step_context_id, @step_name, record, @reactor_class_name)
       log(result.success? ? :info : :warn, result.success? ? "completed" : "completed_with_failure")
       storage.publish(RubyReactor.async_step_channel(@step_context_id, @step_name), "done")
       result

data/lib/ruby_reactor/template/result.rb

@@ -76,7 +76,14 @@ module RubyReactor
         end
 
         value = ContextSerializer.deserialize_value(fetch(record, :result))
-        return value if fetch(record, :success)
+        if fetch(record, :success)
+          # Same rule as Failure below: a halt has no same-process equivalent
+          # for a reader to mirror, so hand over the signal itself.
+          return RubyReactor.Halt(reason: fetch(record, :reason), step_name: @step_name) if
+            fetch(record, :signal).to_s == "halt"
+
+          return value
+        end
 
         RubyReactor::Failure.new(value)
       end
@@ -175,7 +182,7 @@ module RubyReactor
 
       # Records round-trip through JSON, so a key may come back as a string.
       def fetch(hash, key)
-        hash[key] || hash[key.to_s]
+        Utils::FetchIndifferent.call(hash, key)
       end
 
       def extract_path(value, path)

data/lib/ruby_reactor/utils/fetch_indifferent.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module RubyReactor
+  module Utils
+    # Presence-aware symbol/string lookup: a supplied `false` is returned as
+    # `false`, never swallowed by an `a || b` fallback into `nil`.
+    class FetchIndifferent
+      def self.call(hash, key)
+        hash.key?(key.to_sym) ? hash[key.to_sym] : hash[key.to_s]
+      end
+    end
+  end
+end

data/lib/ruby_reactor/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module RubyReactor
-  VERSION = "0.7.1"
+  VERSION = "0.8.0"
 end

data/lib/ruby_reactor.rb

@@ -225,6 +225,7 @@ module RubyReactor
       {
         success: false,
         error: error_message,
+        retryable: @retryable,
         step_name: @step_name,
         inputs: @inputs,
         redact_inputs: @redact_inputs,
@@ -316,8 +317,10 @@ module RubyReactor
     end
 
     def extract_attributes_from_hash(error_hash)
-      # Ensure indifferent access
-      err = ->(k) { error_hash[k.to_s] || error_hash[k.to_sym] }
+      # Presence-aware indifferent access: a serialized `false` (notably
+      # `retryable: false` on a validation failure) must survive the round trip
+      # rather than be swallowed by an `||` fallback into nil.
+      err = ->(k) { Utils::FetchIndifferent.call(error_hash, k) }
 
       {
         error: err[:message] || err[:error] || error_hash,

data/specs/002-step-input-contracts/checklists/requirements.md

@@ -0,0 +1,49 @@
+# Specification Quality Checklist: Step Input Contracts
+
+**Purpose**: Validate specification completeness and quality before proceeding to planning
+**Created**: 2026-09-10
+**Feature**: [spec.md](../spec.md)
+
+## Content Quality
+
+- [x] No implementation details (languages, frameworks, APIs)
+- [x] Focused on user value and business needs
+- [x] Written for non-technical stakeholders
+- [x] All mandatory sections completed
+
+## Requirement Completeness
+
+- [x] No [NEEDS CLARIFICATION] markers remain
+- [x] Requirements are testable and unambiguous
+- [x] Success criteria are measurable
+- [x] Success criteria are technology-agnostic (no implementation details)
+- [x] All acceptance scenarios are defined
+- [x] Edge cases are identified
+- [x] Scope is clearly bounded
+- [x] Dependencies and assumptions identified
+
+## Feature Readiness
+
+- [x] All functional requirements have clear acceptance criteria
+- [x] User scenarios cover primary flows
+- [x] Feature meets measurable outcomes defined in Success Criteria
+- [x] No implementation details leak into specification
+
+## Notes
+
+- All items pass. 0 [NEEDS CLARIFICATION] markers remain.
+- Resolved with the user on 2026-09-10:
+  - **Naming**: a unit of work declares `input`; the reactor keeps `argument` for wiring only
+    (FR-012).
+  - **Undeclared arguments**: reactor-load error for contract-owning steps (FR-018); steps
+    with no contract and no wiring keep today's pass-all-inputs behavior (FR-019).
+  - **Implicit wiring**: an unwired step input resolves from a same-named reactor input only,
+    checked at reactor-load time; never from another step's result (FR-020, FR-021).
+  - **Direct invocation**: the contract is enforced on every entry point, not only via a
+    reactor (FR-022).
+  - **Falsey values**: presence means "a value was supplied", never "the value is truthy";
+    the pre-existing loss of `false` during argument resolution is corrected as part of this
+    feature (FR-023, SC-011).
+- "Non-technical stakeholders" is read as *developers who are not this library's
+  maintainers*: the spec names no Ruby constructs, gems, or file paths.
+- Ready for `/speckit-plan`.

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

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

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