ruby_reactor 0.7.0 → 0.8.0

data/CHANGELOG.md

@@ -1,5 +1,152 @@
 # 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)
+
+
+### Features
+
+* reactor signal semantics ([#52](https://github.com/arturictus/ruby_reactor/issues/52)) ([9147d06](https://github.com/arturictus/ruby_reactor/commit/9147d066da603c0afc1af6536b6afac7e165a034))
+
 ## [0.7.0](https://github.com/arturictus/ruby_reactor/compare/v0.6.0...v0.7.0) (2026-09-08)
 
 
@@ -120,6 +267,10 @@ was dispatched precisely so the parent would not depend on it. A later step that
 reads the result and returns `Failure` triggers compensation normally, so no
 failure is unrecoverable, just not automatic.
 
+* Reactor signal semantics: `Skipped` is renamed to `Halt` (the existing clean-stop behaviour, unchanged otherwise), and `Skipped` is reused with new meaning — marking a single step skipped while the reactor continues, with its value flowing to dependants exactly like `Success`. One-line outcome helpers `success!`, `fail!`, `skip!`, and `halt!` end a step immediately from any call depth. `Failure` (and `fail!`) accept a `retry:` spelling alongside the existing `retryable:`. `compensate`/`undo` now default to `Skipped` instead of `Success`, so the execution trace distinguishes rollback logic that ran from rollback logic that was never written.
+
+  **Migration**: `Skipped(reason: "...")` (the old halt) is now `Halt(reason: "...")`; `result.skipped?` for a clean halt is now `result.halted?`; the `be_skipped` matcher for a clean halt is now `be_halted`. The old call shape raises `ArgumentError` naming `Halt` — there is no silent compatibility path. Run status `:skipped` is renamed `:halted`; contexts persisted by a pre-upgrade version with status `"skipped"` are still read back correctly as halted.
+
 ## [0.5.4](https://github.com/arturictus/ruby_reactor/compare/v0.5.3...v0.5.4) (2026-06-18)
 
 

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
-at specs/001-background-async-steps/plan.md
+shell commands, and other important information, read the current plan:
+`specs/004-inheritable-step-class/plan.md`
 <!-- SPECKIT END -->

data/README.md

@@ -230,29 +230,33 @@ RubyReactor supports two ways to define step logic:
 | **Class steps** (preferred) | Real business logic, compensation/undo, shared steps, testability |
 | **Inline blocks** | Quick prototypes, trivial one-liners, documentation examples |
 
-Whichever style you use, a step's `run` returns one of three signals — all exposed as bare helpers in both class steps and inline blocks:
+Whichever style you use, a step's `run` returns one of four signals — all exposed as bare helpers in both class steps and inline blocks:
 
 - **`Success(value)`** — step succeeded; `value` flows to dependent steps.
 - **`Failure(error)`** — step failed; the reactor rolls back completed steps (compensate/undo).
-- **`Skipped(reason:)`** — clean halt: stop the reactor, keep partial progress, **no rollback**. See [Skipping a reactor cleanly](documentation/core_concepts.md#skipping-a-reactor-cleanly).
+- **`Halt(reason:)`** — clean halt: stop the reactor, keep partial progress, **no rollback**. See [Halting a reactor cleanly](documentation/core_concepts.md#halting-a-reactor-cleanly).
+- **`Skipped(value)`** — mark this one step skipped; the reactor continues and `value` flows to dependants exactly like `Success`. See [Skipping a single step](documentation/core_concepts.md#skipping-a-single-step).
 
-**Class steps** are plain Ruby classes that include `RubyReactor::Step` and implement `run`, and optionally `compensate` and `undo`:
+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** 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
@@ -319,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
@@ -726,7 +726,7 @@ class MonthlyBillingReactor < RubyReactor::Reactor
   input :org_id
 
   # Run at most once per UTC month per org. Subsequent calls in the same month
-  # return RubyReactor::Skipped without executing any step. Pair with
+  # return RubyReactor::Halt without executing any step. Pair with
   # with_lock for strict at-most-one even under concurrent racers.
   with_period(every: :month) { |inputs| "monthly_billing:#{inputs[:org_id]}" }
 
@@ -801,26 +801,38 @@ On contention:
 - **Inline** (`Reactor.run`) raises `RubyReactor::Lock::AcquisitionError` / `RubyReactor::Semaphore::AcquisitionError` / `RubyReactor::RateLimit::ExceededError` / `RubyReactor::OrderedLock::WaitError`.
 - **Async** (Sidekiq or ActiveJob) snoozes the job via `perform_in(delay, ...)`. For rate limits the delay uses the error's `retry_after_seconds` hint (precise wakeup — the bucket roll time is known exactly); for locks, semaphores, and ordered-lock waits it's `lock_snooze_base_delay + jitter` (a short re-poll, since a held lock or a live blocker nonce typically clears in milliseconds). Snoozes do not count against the backend's retry budget. After `lock_snooze_max_attempts` snoozes the context is marked failed (ordered-lock waits bypass the cap — see the ordered-lock docs).
 
-On dedup hits (period gate already marked), the reactor returns a `RubyReactor::Skipped` result instead — no steps run, no exception:
+On dedup hits (period gate already marked), the reactor returns a `RubyReactor::Halt` result instead — no steps run, no exception:
 
 ```ruby
 result = MonthlyBillingReactor.run(org_id: 42)
-result.success?  # true (Skipped is a Success subclass)
-result.skipped?  # true on dedup hit, false otherwise
+result.success?  # true (Halt is a Success subclass)
+result.halted?   # true on dedup hit, false otherwise
 ```
 
-A step's `run` block can also return `Skipped(reason: "...")` to halt the reactor cleanly — remaining steps don't execute, **and already-completed steps are NOT compensated**. Use it when the rest of the workflow is unnecessary and partial progress should be kept (`Failure` is for "stop and roll back"). `Skipped` is a bare helper just like `Success`/`Failure` (or use the fully-qualified `RubyReactor.Skipped(...)`).
+A step's `run` block can also return `Halt(reason: "...")` to stop the reactor cleanly — remaining steps don't execute, **and already-completed steps are NOT compensated**. Use it when the rest of the workflow is unnecessary and partial progress should be kept (`Failure` is for "stop and roll back"). `Halt` is a bare helper just like `Success`/`Failure` (or use the fully-qualified `RubyReactor.Halt(...)`).
 
 ```ruby
 step :ensure_active do
   argument :user, result(:fetch_user)
   run do |args, _ctx|
-    next Skipped(reason: "user_opted_out") if args[:user].opted_out?
+    next Halt(reason: "user_opted_out") if args[:user].opted_out?
     Success(args[:user])
   end
 end
 ```
 
+To skip a *single* step while the reactor continues — the step did nothing, but the rest of the workflow should still run — return `Skipped(value)` instead. The value flows to dependants exactly like a `Success` value, and the step is not enrolled for rollback:
+
+```ruby
+step :maybe_sync do
+  argument :user, result(:fetch_user)
+  run do |args, _ctx|
+    next Skipped(args[:user]) if args[:user].already_synced?
+    Success(sync!(args[:user]))
+  end
+end
+```
+
 See [Locks, Semaphores, Rate Limits, Periods & Ordered Locks](documentation/locks_and_semaphores.md) for re-entrancy, auto-extend, multi-window quotas, bucket semantics, owner identity, snooze tuning, ordered-lock assignment + poison-pill semantics, and operational notes.
 
 ### Map & Parallel Execution
@@ -1003,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
 
-  # Optional cross-field block (composes with the inline rules above)
-  validate_args do
-    required(:amount).filled(:decimal, lt?: 10_000)
+  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:
+
+- 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:
 
@@ -1337,7 +1446,7 @@ Comprehensive guide to testing reactors with RubyReactor's testing utilities. Le
 
 ### [Locks, Semaphores, Rate Limits, Periods & Ordered Locks](documentation/locks_and_semaphores.md)
 
-Coordinate access to shared resources across processes with Redis-backed primitives: exclusive locks (`with_lock`), concurrency-limiting semaphores (`with_semaphore`), fixed-window rate limits with multi-window quotas (`with_rate_limit`), calendar-bucketed dedup (`with_period`, returning `Skipped` results), and strict sequential ordering via a monotonically increasing nonce assigned at enqueue (`with_ordered_lock`). Covers re-entrancy across composed reactors, TTL auto-extend, inline-vs-async contention behavior, smart `retry_after` snoozes for rate limits, snooze tuning, the token-based semaphore safety model, once-per-day/month/year scheduling patterns, ordered-lock counter reset on drain, poison-pill timeouts, and deadlock-safe composition rules.
+Coordinate access to shared resources across processes with Redis-backed primitives: exclusive locks (`with_lock`), concurrency-limiting semaphores (`with_semaphore`), fixed-window rate limits with multi-window quotas (`with_rate_limit`), calendar-bucketed dedup (`with_period`, returning `Halt` results), and strict sequential ordering via a monotonically increasing nonce assigned at enqueue (`with_ordered_lock`). Covers re-entrancy across composed reactors, TTL auto-extend, inline-vs-async contention behavior, smart `retry_after` snoozes for rate limits, snooze tuning, the token-based semaphore safety model, once-per-day/month/year scheduling patterns, ordered-lock counter reset on drain, poison-pill timeouts, and deadlock-safe composition rules.
 
 ### [Middlewares & OpenTelemetry](documentation/middlewares.md)
 

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
@@ -103,6 +103,13 @@ module RubyReactor
       @current_step = old_step
     end
 
+    # Appends an execution-trace event stamped with whether this process is the
+    # worker (`inline_async_execution`). Traces written before this field
+    # existed stay unlabeled on deserialize.
+    def append_execution_trace(entry)
+      @execution_trace << entry.merge(background: !!@inline_async_execution)
+    end
+
     def to_h
       {
         inputs: @inputs,

data/lib/ruby_reactor/context_serializer.rb

@@ -36,6 +36,11 @@ module RubyReactor
       # rubocop:disable Metrics/CyclomaticComplexity, Metrics/MethodLength
       def serialize_value(value)
         case value
+        when RubyReactor::Halt
+          { "_type" => "Halt", "reason" => value.reason, "period_key" => value.period_key,
+            "step_name" => value.step_name }
+        when RubyReactor::Skipped
+          { "_type" => "Skipped", "value" => serialize_value(value.value), "reason" => value.reason }
         when RubyReactor::Success
           { "_type" => "Success", "value" => serialize_value(value.value) }
         when RubyReactor::Failure
@@ -112,6 +117,14 @@ module RubyReactor
           if value.key?("_type")
             # Special serialized types (Time, BigDecimal, etc.)
             case value["_type"]
+            when "Halt"
+              RubyReactor::Halt.new(
+                reason: value["reason"],
+                period_key: value["period_key"],
+                step_name: value["step_name"]
+              )
+            when "Skipped"
+              RubyReactor::Skipped.new(deserialize_value(value["value"]), reason: value["reason"])
             when "Success"
               RubyReactor::Success(deserialize_value(value["value"]))
             when "Failure"

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/lockable.rb

@@ -53,7 +53,7 @@ module RubyReactor
 
         # Configure a calendar-aligned dedup window for this reactor. The
         # reactor will run at most once per bucket per key; subsequent calls
-        # in the same bucket return `RubyReactor::Skipped` without executing
+        # in the same bucket return `RubyReactor::Halt` without executing
         # any steps.
         #
         # Note: `with_period` is *dedup*, not *concurrency*. Two concurrent
@@ -93,7 +93,7 @@ module RubyReactor
         #   assign. Only fully-drained sequences GC themselves.
         # @param strict [Boolean] When true (default), if any nonce in the
         #   sequence terminates with a `Failure`, all subsequent nonces are
-        #   short-circuited with `Skipped(reason: :ordered_lock_chain_failed)`
+        #   short-circuited with `Halt(reason: :ordered_lock_chain_failed)`
         #   instead of executing. This models "stop the line on the first
         #   problem" pipelines (e.g. ledger transactions). When false, the
         #   sequence keeps executing every nonce in order regardless of prior

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)