ruby_reactor 0.8.2 → 0.8.4

data/specs/specs-inputs-by-method-md-piped-wigderson.md

@@ -0,0 +1,77 @@
+# Plan: `inputs.order_id` (implement specs/inputs_by_method.md)
+
+## Context
+
+`Step#inputs` is a plain Hash, so a typo like `inputs[:order_id]` (declared `:order_guid`) returns `nil` and blows up later, far from the bug — worst in `undo`/`compensate`, which skip validation. The design doc (`specs/inputs_by_method.md`) decides: step code reads inputs through a frozen read-only `Step::Inputs` object (`inputs.order_id`); any unreadable name raises `Error::UndeclaredInputError` naming the step and its declared inputs. No `[]`, no shim — every call site migrates in the same change (`feat!`). This plan implements that doc as written; deviations/additions found while reading the code are marked **(new)**.
+
+Branch: `inputs_by_method` off `main`. Test-first (Constitution III): new specs first, then lib, then migration.
+
+**Step 0 (on approval):** copy this plan to `specs/inputs_by_method_plan.md` (next to the design doc) and stop there. Implementation starts only when asked.
+
+## 1. New code (lib)
+
+**`lib/ruby_reactor/step/inputs.rb`** — `RubyReactor::Step::Inputs` (Zeitwerk picks it up).
+- `initialize(values, contract: nil, owner:)`: `@values = values.to_h` (so passing an `Inputs` or nil is safe), readable `@names` = `contract.declarations.keys` when the contract has declarations, else `@values.keys.map(&:to_sym)` **(new: a contract with only `validate_inputs` and no `input` falls back to present keys instead of making everything unreadable)**; `@redacted = contract&.redacted_names || []`; `freeze`.
+- `method_missing(name, *args)`: readable name and no args → `Utils::FetchIndifferent.call(@values, name)`; else raise `UndeclaredInputError`. `respond_to_missing?` → `@names.include?(name) || super`.
+- `to_h` → supplied readable names only, symbol keys, via FetchIndifferent (key present as sym or string). `alias to_hash to_h`.
+- `inspect` → `to_h` with redacted names replaced by `InputContract::REDACTED`.
+
+**`lib/ruby_reactor/error/undeclared_input_error.rb`** — `< NoMethodError`, `def retryable? = false`. Message: `"#{owner} has no input :#{name}. Declared inputs: :a, :b."` (`none` when empty). Retry path already honours it: `Failure#retryable?` (`lib/ruby_reactor.rb:167`) and `StepFailureError#retryable?` ask the error.
+
+**Reserved names** — `InputContract#input` (`lib/ruby_reactor/step/input_contract.rb:25`): raise `Error::ValidationError` when `Step::Inputs.public_method_defined?(name)`. Checked all 141 input names in spec/demo_app/docs: no clashes.
+
+## 2. Injection points (the only places the object is built)
+
+| Where | Change |
+|---|---|
+| `Step#initialize` (`lib/ruby_reactor/step.rb:44`) | `@inputs = Inputs.new(inputs, contract: (self.class.input_contract if self.class.declares_inputs?), owner: self.class.name)`. Covers `.run`/`.undo`/`.compensate`. Update header comment example (`step.rb:8`). |
+| `Step.enforce_contract!` / `with_defaults` (`step.rb:168-179`) | **(new)** `arguments.to_h` first, so a documented nested call `OtherStep.run(inputs, context)` from a step body, and TestSubject's `original` callable, still hand the contract a Hash. |
+| `StepConfig` (`lib/ruby_reactor/dsl/step_builder.rb`) | Add `def wrap_inputs(arguments) = Step::Inputs.new(arguments, contract: input_contract, owner: "step :#{name}")`. |
+| `StepConfig#call_body` (`step_builder.rb:367`) | `run_block.call(wrap_inputs(arguments), context)`. Duck-typed `impl.run` (line 372) unchanged. |
+| `CompensationManager#compensate_step` / `#undo_step` (`lib/ruby_reactor/executor/compensation_manager.rb:126,171`) | Wrap `arguments` with `step_config.wrap_inputs` before the inline block call only. |
+| `TestSubject#original_impl_for` duck-impl lambda (`lib/ruby_reactor/rspec/test_subject.rb:772`) | **(new)** `impl.run(args.to_h, ctx)`. Mock blocks replace `@run_block`, so they receive `Inputs` like the body they stand in for — the `Step` path is covered by the `to_h` above. |
+
+## 3. Returning inputs from a step
+
+- `RubyReactor.Success` (`lib/ruby_reactor.rb:391`): `Success.new(value.is_a?(Step::Inputs) ? value.to_h : value)`.
+- `ResultHandler#handle_unknown_result` (`lib/ruby_reactor/executor/result_handler.rb:192`): build `success_result` first, then `validate_step_output` on `success_result.value`, **and (new) `@context.set_result(..., success_result.value)`** — the doc's swap alone would still store the raw `Inputs` in context.
+
+## 4. Built-in steps
+
+Per the doc, `MapStep`, `ComposeStep`, `AsyncReactorStep` declare their keys (`input :source`, `input :fan_out, optional: true`, …, untyped → no validator, `enforce!` is a no-op) and switch `inputs[:x]` → `inputs.x` (31 sites). `fail_fast: inputs.fail_fast.nil? || inputs.fail_fast` stays.
+- **(new)** drop `inputs[:step_name] ||` in `map_step.rb:193`: `step_name` is never wired, and once declared, `validate_definition!` would wire it by name from a reactor input called `:step_name`.
+
+## 5. Migration (no shim)
+
+Counts: `inputs[` — spec 131, docs 49, README 10, demo_app 44; `args[` — spec 378, docs 157, README 54, demo_app 414 (most in inline blocks).
+- Step bodies only (class `run`/`undo`/`compensate`, inline `run`/`undo`/`compensate` blocks, TestSubject mock blocks): `x[:k]` → `x.k`. Hand edits, not a global replace — lock/semaphore/rate-limit key procs, `validate_inputs`, `where`/`guard`, `transform:` procs stay Hashes.
+- Other Hash use on inputs (`each`, `slice`, `eq(hash)` in specs) → `.to_h`. `**inputs`, `merge(inputs)`, `Success(inputs)` keep working.
+- Docs/README/`demo_app/documentation`: rename inline block param `args` → `inputs`; `documentation/core_concepts.md` step-inputs section documents reader API, `UndeclaredInputError`, reserved names, `to_h`/`**`, `Success(inputs)` conversion (nested not converted).
+- Order: lib → `spec/` → `demo_app/` → docs/README.
+
+**Silent-pass trap:** a spec that expects a step to fail still passes if an unmigrated `[]` now fails it for a different reason. So grep is the driver and the suite is the net, not the other way round.
+
+## 6. Demo (Constitution VI)
+
+Via `/speckit-demo-tests`: `demo_app/app/reactors/undeclared_input_demo_reactor.rb` (step reads a typo'd input), `demo:undeclared_input` in `demo_app/lib/tasks/demo_reactors.rake`, `demo_app/spec/reactors/undeclared_input_demo_reactor_spec.rb` asserting failure with `UndeclaredInputError` and one attempt despite `retries`.
+
+## 7. Tests (written first)
+
+`spec/ruby_reactor/step/inputs_spec.rb`:
+- reader returns value; declared-optional absent → `nil`; `false` stays `false`; string-keyed hash readable.
+- undeclared name raises `UndeclaredInputError` with exact message; `respond_to?`; clash with private Kernel name (`select`) as a declared input reads fine.
+- contract-less step reads present keys only; unwired inline step with `inputs do` reads only declared.
+- `to_h` omits unsupplied optionals; `**inputs`; `inspect` redacts; frozen, no `[]`.
+- `input :method` → `ValidationError` at class definition.
+- class `undo`/`compensate` and inline `run`/`undo`/`compensate` blocks receive `Inputs`; typo in `compensate` surfaces as rollback failure naming the input.
+- step with `retries max_attempts: 3` + typo → one attempt.
+- `Success(inputs)` sync (`result(:step, :x)` works) and async round trip (Hash, not a string); bare `run { |inputs| inputs }` stored/validated as Hash.
+- nested `OtherStep.run(inputs, context)` from a step body works; TestSubject `mock_step` with `original.call(args, ctx)` on a class step works.
+
+## Verification
+
+1. `bundle exec rspec` (real Redis) green; rerun flaky async specs alone before chasing them.
+2. `cd demo_app && bundle exec rspec` green; `bin/rails demo:undeclared_input` shows the error.
+3. `bundle exec rubocop` clean.
+4. Residual audit: `grep -rnE 'inputs\[|\bargs\[' lib spec demo_app documentation README.md` — every remaining hit is a Hash context (key procs, validators, `where`/`guard`, reactor DSL `inputs[name]` in `dsl/reactor.rb`).
+5. Commit as `feat!:` with a migration note (`inputs[:x]` → `inputs.x`, Hash methods → `inputs.to_h`).

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ruby_reactor
 version: !ruby/object:Gem::Version
-  version: 0.8.2
+  version: 0.8.4
 platform: ruby
 authors:
 - Artur
@@ -98,6 +98,7 @@ files:
 - ".claude/skills/speckit-demo-tests/SKILL.md"
 - ".claude/skills/speckit-implement/SKILL.md"
 - ".claude/skills/speckit-plan/SKILL.md"
+- ".claude/skills/speckit-review/SKILL.md"
 - ".claude/skills/speckit-specify/SKILL.md"
 - ".claude/skills/speckit-tasks/SKILL.md"
 - ".claude/skills/speckit-taskstoissues/SKILL.md"
@@ -164,6 +165,7 @@ files:
 - lib/ruby_reactor/dsl/lockable.rb
 - lib/ruby_reactor/dsl/map_builder.rb
 - lib/ruby_reactor/dsl/reactor.rb
+- lib/ruby_reactor/dsl/retryable.rb
 - lib/ruby_reactor/dsl/step_builder.rb
 - lib/ruby_reactor/dsl/template_helpers.rb
 - lib/ruby_reactor/dsl/validation_helpers.rb
@@ -175,9 +177,13 @@ files:
 - lib/ruby_reactor/error/dependency_error.rb
 - lib/ruby_reactor/error/deprecated_dsl_error.rb
 - lib/ruby_reactor/error/deserialization_error.rb
+- lib/ruby_reactor/error/execution_parked.rb
 - lib/ruby_reactor/error/input_validation_error.rb
+- lib/ruby_reactor/error/reactor_contention_park.rb
 - lib/ruby_reactor/error/schema_version_error.rb
+- lib/ruby_reactor/error/step_contention_park.rb
 - lib/ruby_reactor/error/step_failure_error.rb
+- lib/ruby_reactor/error/undeclared_input_error.rb
 - lib/ruby_reactor/error/undo_error.rb
 - lib/ruby_reactor/error/validation_error.rb
 - lib/ruby_reactor/executor.rb
@@ -188,6 +194,7 @@ files:
 - lib/ruby_reactor/executor/ordered_lock_support.rb
 - lib/ruby_reactor/executor/result_handler.rb
 - lib/ruby_reactor/executor/retry_manager.rb
+- lib/ruby_reactor/executor/step_coordination.rb
 - lib/ruby_reactor/executor/step_executor.rb
 - lib/ruby_reactor/interrupt_result.rb
 - lib/ruby_reactor/lock.rb
@@ -224,6 +231,7 @@ files:
 - lib/ruby_reactor/step/async_reactor_step.rb
 - lib/ruby_reactor/step/compose_step.rb
 - lib/ruby_reactor/step/input_contract.rb
+- lib/ruby_reactor/step/inputs.rb
 - lib/ruby_reactor/step/map_step.rb
 - lib/ruby_reactor/step_signals.rb
 - lib/ruby_reactor/step_sweeper.rb
@@ -256,40 +264,24 @@ files:
 - lib/ruby_reactor/web/config.ru
 - lib/ruby_reactor/web/coordination_serializer.rb
 - lib/ruby_reactor/web/public/assets/index-BQvIWPdx.css
-- lib/ruby_reactor/web/public/assets/index-Dw4KV4QY.js
+- lib/ruby_reactor/web/public/assets/index-CeZU-ESu.js
 - lib/ruby_reactor/web/public/index.html
 - lib/ruby_reactor/web/public/vite.svg
 - lib/ruby_reactor/worker.rb
 - llms-full.txt
 - llms.txt
 - sig/ruby_reactor.rbs
-- specs/002-step-input-contracts/checklists/requirements.md
-- specs/002-step-input-contracts/contracts/dsl-surface.md
-- specs/002-step-input-contracts/data-model.md
-- specs/002-step-input-contracts/plan.md
-- specs/002-step-input-contracts/quickstart.md
-- specs/002-step-input-contracts/research.md
-- specs/002-step-input-contracts/spec.md
-- specs/002-step-input-contracts/tasks.md
-- specs/004-inheritable-step-class/checklists/requirements.md
-- specs/004-inheritable-step-class/contracts/step-lifecycle.md
-- specs/004-inheritable-step-class/data-model.md
-- specs/004-inheritable-step-class/plan.md
-- specs/004-inheritable-step-class/quickstart.md
-- specs/004-inheritable-step-class/research.md
-- specs/004-inheritable-step-class/spec.md
-- specs/004-inheritable-step-class/tasks.md
-- specs/active_job.md
-- specs/deferred-003-step-lock-declarations/checklists/requirements.md
-- specs/deferred-003-step-lock-declarations/contracts/dsl-surface.md
-- specs/deferred-003-step-lock-declarations/data-model.md
-- specs/deferred-003-step-lock-declarations/plan.md
-- specs/deferred-003-step-lock-declarations/quickstart.md
-- specs/deferred-003-step-lock-declarations/research.md
-- specs/deferred-003-step-lock-declarations/spec.md
-- specs/deferred-003-step-lock-declarations/tasks.md
-- specs/possible_feature.md
+- specs/006-step-retry-declarations/checklists/requirements.md
+- specs/006-step-retry-declarations/contracts/dsl-surface.md
+- specs/006-step-retry-declarations/data-model.md
+- specs/006-step-retry-declarations/plan.md
+- specs/006-step-retry-declarations/quickstart.md
+- specs/006-step-retry-declarations/research.md
+- specs/006-step-retry-declarations/spec.md
+- specs/006-step-retry-declarations/tasks.md
+- specs/future_improvements.md
 - specs/scoped_rspec_matchers.md
+- specs/specs-inputs-by-method-md-piped-wigderson.md
 - teley/Dockerfile
 homepage: https://github.com/arturictus/ruby_reactor
 licenses: []

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

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

@@ -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
-```