ruby_reactor 0.8.1 → 0.8.3

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ruby_reactor
 version: !ruby/object:Gem::Version
-  version: 0.8.1
+  version: 0.8.3
 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"
@@ -175,8 +176,11 @@ 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/undo_error.rb
 - lib/ruby_reactor/error/validation_error.rb
@@ -188,6 +192,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
@@ -256,39 +261,15 @@ 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/future_improvements.md
+- specs/scoped_rspec_matchers.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
-```

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. |