ruby_reactor 0.7.1 → 0.8.1

data/README.md

@@ -5,7 +5,7 @@
 
 # RubyReactor
 
-A dynamic, dependency-resolving saga orchestrator for Ruby. Ruby Reactor implements the Saga pattern with compensation-based error handling and DAG-based execution planning. It leverages **Sidekiq or ActiveJob** for asynchronous execution and **Redis** for state persistence.
+A dynamic, dependency-resolving saga orchestrator for Ruby. Ruby Reactor implements the Saga pattern with compensation-based error handling and DAG-based execution planning. It leverages **Sidekiq or ActiveJob** for background execution and **Redis** for state persistence.
 
 ![Payment workflow reactor](documentation/images/payment_workflow.png)
 
@@ -18,13 +18,14 @@ The key value is **Reliability**: if any part of your workflow fails, Ruby React
 ## Features
 
 - **DAG-based Execution**: Steps are executed based on their dependencies, allowing for parallel execution of independent steps.
-- **Async Execution**: Steps can be executed asynchronously in the background using Sidekiq or ActiveJob (so any ActiveJob-compatible queue — Resque, Solid Queue, GoodJob, etc. — works too).
+- **Background Execution**: Hand a whole reactor, or everything after a declared step, to a background job via Sidekiq or ActiveJob (so any ActiveJob-compatible queue — Resque, Solid Queue, GoodJob, etc. — works too).
+- **Async Steps & Reactors**: `async_step` and `async_reactor` dispatch independent units of work while the reactor keeps running; steps that read their result wait for it.
 - **Map & Parallel Execution**: Iterate over collections in parallel with the `map` step, distributing work across multiple workers.
 - **Retries**: Configurable retry logic for failed steps, with exponential backoff.
 - **Compensation**: Automatic rollback of completed steps when a failure occurs.
 - **Interrupts**: Pause and resume workflows to wait for external events (webhooks, user approvals).
 - **Input Validation**: Integrated with `dry-validation` for robust input checking.
-- **Distributed Locks, Semaphores, Rate Limits, Periods & Ordered Locks**: Coordinate across processes with Redis-backed primitives — exclusive locks for at-most-one-runner, semaphores for capacity caps, fixed-window rate limits for external APIs (single or multi-window like "3/sec AND 100/min"), `with_period` to dedup reactors to once per calendar bucket, and `with_ordered_lock` for strict transaction ordering via a monotonically increasing nonce assigned at enqueue. Async jobs snooze on contention with smart `retry_after` instead of consuming retry budget.
+- **Distributed Locks, Semaphores, Rate Limits, Periods & Ordered Locks**: Coordinate across processes with Redis-backed primitives — exclusive locks for at-most-one-runner, semaphores for capacity caps, fixed-window rate limits for external APIs (single or multi-window like "3/sec AND 100/min"), `with_period` to dedup reactors to once per calendar bucket, and `with_ordered_lock` for strict transaction ordering via a monotonically increasing nonce assigned at enqueue. Background jobs snooze on contention with smart `retry_after` instead of consuming retry budget.
 
 ## Comparison
 
@@ -35,7 +36,7 @@ The key value is **Reliability**: if any part of your workflow fails, Ruby React
 | Interrupts (pause/resume)| Yes          | No              | No          | Manual              |
 | Locks / sem / rate / per | Yes          | No              | No          | Manual              |
 | Built-in web dashboard   | Yes          | No              | No          | No                  |
-| Async (Sidekiq/AJ)       | Yes          | No              | Limited     | Yes                 |
+| Background (Sidekiq/AJ)  | Yes          | No              | Limited     | Yes                 |
 | Durable crash recovery   | Yes          | No              | No          | Manual              |
 
 ## Real-World Use Cases
@@ -57,9 +58,10 @@ The key value is **Reliability**: if any part of your workflow fails, Ruby React
   - [Rails Installation](#rails-installation)
 - [Usage](#usage)
   - [Basic Example: User Registration](#basic-example-user-registration)
-  - [Async Execution](#async-execution)
-    - [Full Reactor Async](#full-reactor-async)
+  - [Background Execution](#background-execution)
+    - [Full Background](#full-background)
     - [Background Hand-off](#background-hand-off)
+  - [Async Steps & Reactors](#async-steps--reactors)
     - [`async_step`](#async_step-one-step-dispatched-on-its-own)
     - [`async_reactor`](#async_reactor-a-whole-nested-reactor-running-independently)
   - [Durability & Recovery](#durability--recovery)
@@ -119,7 +121,7 @@ RubyReactor.configure do |config|
 
   ## === Background job backend (Sidekiq by default, or ActiveJob) ===
 
-  ## Queue used by RubyReactor's async worker. Default: :default.
+  ## Queue used by RubyReactor's background worker. Default: :default.
   # config.queue_name = :default
 
   ## Retry count for infrastructure failures only (deserialization, Redis,
@@ -180,8 +182,8 @@ RubyReactor.configure do |config|
   ## Logger. Default: Logger.new($stdout).
   # config.logger = Logger.new($stdout)
 
-  ## Async router. Default: RubyReactor::Adapters::Sidekiq::Router. Swap in the
-  ## built-in ActiveJob adapter (see "Async Execution" below), or point at any
+  ## Background job router. Default: RubyReactor::Adapters::Sidekiq::Router. Swap in the
+  ## built-in ActiveJob adapter (see "Background Execution" below), or point at any
   ## custom adapter — it only needs to respond to
   ## `perform_async(context_id, reactor_class_name, **)`.
   # config.async_router = RubyReactor::Adapters::ActiveJob::Router
@@ -239,23 +241,24 @@ Whichever style you use, a step's `run` returns one of four signals — all expo
 
 One-line helpers end a step immediately from any call depth: `success!(value)`, `fail!(error, retry: true)`, `halt!(reason:)`, `skip!(value)` — equivalent to `return`ing the matching signal, usable in `run`, `compensate`, and `undo` bodies.
 
-**Class steps** are plain Ruby classes that include `RubyReactor::Step` and implement `run`, and optionally `compensate` and `undo`:
+**Class steps** subclass `RubyReactor::Step` and implement `run`, and optionally `compensate` and `undo`, as instance methods reading `inputs` and `context`:
 
 ```ruby
-class ReserveInventoryStep
-  include RubyReactor::Step
+class ReserveInventoryStep < RubyReactor::Step
+  # The step's input contract: enforced before `run` on every execution path.
+  input :order, :hash
 
-  def self.run(arguments, context)
-    reservation_id = InventoryService.reserve(arguments[:order][:items])
+  def run
+    reservation_id = InventoryService.reserve(inputs[:order][:items])
     Success(reservation_id: reservation_id)
   end
 
-  def self.compensate(error, arguments, context)
-    InventoryService.release_partial(arguments[:order][:items])
+  def compensate
+    InventoryService.release_partial(inputs[:order][:items])
     Success()
   end
 
-  def self.undo(result, arguments, context)
+  def undo
     InventoryService.release(result[:reservation_id])
     Success()
   end
@@ -322,29 +325,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
@@ -401,7 +400,7 @@ else
 end
 ```
 
-### Async Execution
+### Background Execution
 
 Execute reactors in the background using Sidekiq or ActiveJob. The backend is
 chosen via `config.async_router` (defaults to the Sidekiq adapter); to run on
@@ -413,13 +412,14 @@ RubyReactor.configure do |config|
 end
 ```
 
-That's the only switch — everything below (full-reactor async, step-level
-async, durability, retries, snoozing) works identically on either backend.
+That's the only switch — everything below (background execution, `async_step`
+/ `async_reactor`, durability, retries, snoozing) works identically on either
+backend.
 
-#### Full Reactor Async
+#### Full Background
 
 ```ruby
-class AsyncReactor < RubyReactor::Reactor
+class BackgroundReactor < RubyReactor::Reactor
   background all: true # Entire reactor runs in background
 
   step :long_running_task do
@@ -428,7 +428,7 @@ class AsyncReactor < RubyReactor::Reactor
 end
 
 # Returns immediately with DispatchResult
-result = AsyncReactor.run(params)
+result = BackgroundReactor.run(params)
 ```
 
 #### Background Hand-off
@@ -496,6 +496,13 @@ changes where code runs, not the saga contract.
 > to `async_step`/`async_reactor`, whose names mean something else. It now raises
 > at class-definition time. The exact replacement is `background all: true`.
 
+### Async Steps & Reactors
+
+`async_step` and `async_reactor` dispatch an **independent** unit of work to its
+own job while the reactor keeps running. Unlike `background`, they do not move
+the reactor itself — they are separate units with their own outcome and
+compensation.
+
 #### `async_step`: one step, dispatched on its own
 
 Where `background` relocates the *rest* of a reactor, `async_step` dispatches one
@@ -572,12 +579,12 @@ parent back.
 
 Lock ownership is never shared across the async boundary: a child declaring a key
 the parent holds fails at dispatch with an explanatory error rather than
-deadlocking. See [Async Reactors](documentation/async_reactors.md) for the full
+deadlocking. See [Background & Async Execution](documentation/background_and_async.md) for the full
 rules.
 
 ### Durability & Recovery
 
-Async reactors are durable: state lives in Redis, not in the job payload. Before
+Background reactors are durable: state lives in Redis, not in the job payload. Before
 any background job is enqueued the root context is persisted, and after every
 completed step a checkpoint advances the stored blob — so a crash re-runs at most
 one step, never the whole reactor. Each running reactor also holds a short
@@ -743,7 +750,7 @@ class ChargeReactor < RubyReactor::Reactor
   input :account_id
 
   # Respect upstream Stripe rate limits: 3/sec and 100/min.
-  # Async workers snooze for exactly retry_after seconds instead of
+  # Background workers snooze for exactly retry_after seconds instead of
   # consuming the backend's retry budget.
   with_rate_limit(
     limits: { second: 3, minute: 100 }
@@ -756,7 +763,7 @@ class ChargeReactor < RubyReactor::Reactor
 end
 
 class OrderedTransactionReactor < RubyReactor::Reactor
-  async
+  background all: true
   input :account_id
   input :transaction
 
@@ -797,12 +804,12 @@ class ChargeReactor < RubyReactor::Reactor
 end
 ```
 
-Referencing an unregistered name raises `RubyReactor::RateLimitRegistry::UnknownLimitError`. Named limits hit the same enforcement path as inline ones, so async snooze behavior is identical.
+Referencing an unregistered name raises `RubyReactor::RateLimitRegistry::UnknownLimitError`. Named limits hit the same enforcement path as inline ones, so background snooze behavior is identical.
 
 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).
+- **Background** (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::Halt` result instead — no steps run, no exception:
 
@@ -850,8 +857,8 @@ class DataProcessingReactor < RubyReactor::Reactor
     source input(:items)
     argument :item, element(:process_items)
     
-    # Enable async execution with batching
-    async true, batch_size: 50
+    # Run elements as background jobs, in batches
+    fan_out batch_size: 50
 
     step :transform do
       argument :item, input(:item)
@@ -863,9 +870,13 @@ class DataProcessingReactor < RubyReactor::Reactor
 end
 ```
 
-By using `async true` with `batch_size`, the system applies **Back Pressure** to efficiently manage resources. [Read more about Back Pressure & Resource Management](documentation/data_pipelines.md#back-pressure--resource-management).
+A `fan_out` map is a **hand-off point**: the reactor stops at the map (the caller gets a `DispatchResult`), every element runs as its own background job, and once all outcomes are collected the reactor resumes in a worker with the steps after the map. It fans out the same way when the reactor is already running in a worker (e.g. `background all: true`).
+
+By using `fan_out` with `batch_size`, the system applies **Back Pressure** to efficiently manage resources. [Read more about Back Pressure & Resource Management](documentation/data_pipelines.md#back-pressure--resource-management).
+
+`batch_size` is optional: with `fan_out` alone, RubyReactor fans out one worker per element (defaulting the batch size to the full source size) and aggregates the outcomes into a `ResultEnumerator` — convenient for small collections, but with no back pressure. See [`fan_out` Without `batch_size`](documentation/data_pipelines.md#fan_out-without-batch_size).
 
-`batch_size` is optional: with `async true` alone, RubyReactor fans out one worker per element (defaulting the batch size to the full source size) and aggregates the outcomes into a `ResultEnumerator` — convenient for small collections, but with no back pressure. See [Async Without `batch_size`](documentation/data_pipelines.md#async-without-batch_size).
+> **Breaking change:** `async true` inside a `map` block has been **removed** — it read like `async_step`/`async_reactor`, which dispatch independent units the reactor does not stop for. It now raises at class-definition time. The exact replacement is `fan_out` (`fan_out batch_size: N`).
 
 #### Map with Dynamic Source (ActiveRecord)
 
@@ -881,7 +892,7 @@ map :archive_old_users do
   end
   
   argument :user, element(:archive_old_users)
-  async true, batch_size: 100
+  fan_out batch_size: 100
 
   step :archive do
     argument :user, input(:user)
@@ -1018,26 +1029,123 @@ result.error                       # => RubyReactor::Error::InputValidationError
 result.error.field_errors[:name]   # => "size cannot be less than 2"
 ```
 
-### Step Argument & Output Validation
+### Step Input Contracts
 
-Arguments can be validated inline using the same forms as `input`. Inline rules
-compose with a `validate_args` block (used for cross-field rules):
+A step declares the inputs it accepts; the reactor only says where each value
+comes from. Rules live with the unit of work, so a step reused by three
+reactors is validated the same way in all three.
 
 ```ruby
-step :charge do
-  argument :amount,   input(:amount),   :decimal, gt?: 0
-  argument :currency, input(:currency), :string,  included_in?: %w[USD EUR GBP]
-  argument :user,     input(:user),     User              # type? instance check
+class ChargeStep < RubyReactor::Step
+  input :amount,   :integer, gteq?: 1
+  input :currency, :string,  included_in?: %w[USD EUR GBP]
+  input :user,     User                                   # type? instance check
+  input :note,     :string,  optional: true, default: "", max_size?: 100
+  input :token,    :string,  redact: true                 # "[REDACTED]" in failures and traces
+
+  # Cross-field rules over the whole argument hash, applied last
+  validate_inputs do
+    required(:amount).filled(:integer, lt?: 10_000)
+  end
+
+  def run
+    Success(charge!(inputs))
+  end
+end
+```
+
+`input` takes the same forms as a reactor `input` (inline type and predicates,
+`do |i| ... end` macro block, `validate: Schema`). The contract is enforced before
+`run` on every path: inline execution, each retry attempt, `async_step` and
+`background` workers, resume, every `map` element, and a direct
+`ChargeStep.run(args, context)` call. A violation raises
+`RubyReactor::Error::InputValidationError`; inside a reactor that becomes a
+`Failure` with `validation_errors` and the step's name, after completed steps are
+rolled back, and `have_validation_error(:amount)` matches it.
+
+**Wiring.** `argument` only maps values:
+
+```ruby
+class ChargeReactor < RubyReactor::Reactor
+  input :amount
+  input :currency
+  input :user
+
+  step :charge, ChargeStep do
+    argument :user, result(:load_user)   # explicit wiring always wins
+  end                                    # :amount and :currency resolve by name
+end
+```
 
-  # Optional cross-field block (composes with the inline rules above)
-  validate_args do
-    required(:amount).filled(:decimal, lt?: 10_000)
+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:
 
@@ -1332,8 +1440,8 @@ Learn about the fundamental building blocks of RubyReactor: Reactors, Steps, Con
 ### [DAG (Directed Acyclic Graph)](documentation/DAG.md)
 Deep dive into how RubyReactor manages dependencies. This guide explains how the Directed Acyclic Graph is constructed to ensure steps execute in the correct topological order, enabling automatic parallelization of independent steps.
 
-### [Async Reactors](documentation/async_reactors.md)
-Explore the ways to move work off the calling process: Full Reactor Async, the `background` hand-off, `async_step`, and `async_reactor`. Learn how RubyReactor leverages Sidekiq or ActiveJob for background processing, non-blocking execution, and scalable worker management.
+### [Background & Async Execution](documentation/background_and_async.md)
+Explore the ways to move work off the calling process: background execution (`background all: true` and the `background after:`/`before:` hand-off) and async units (`async_step`, `async_reactor`). Learn how RubyReactor leverages Sidekiq or ActiveJob for background processing, non-blocking execution, and scalable worker management.
 
 ### [Composition](documentation/composition.md)
 Discover how to build complex, modular workflows by composing reactors within other reactors. This guide covers inline composition, class-based composition, and how to manage dependencies between composed workflows.
@@ -1342,7 +1450,7 @@ Discover how to build complex, modular workflows by composing reactors within ot
 Master the `map` feature for processing collections. Learn about parallel execution, batch processing for large datasets, and error handling strategies like fail-fast vs. partial result collection.
 
 ### [Retry Configuration](documentation/retry_configuration.md)
-Configure robust retry policies for your steps. This guide details the available backoff strategies (exponential, linear, fixed), how to configure retries at the reactor or step level, and how async retries work without blocking workers.
+Configure robust retry policies for your steps. This guide details the available backoff strategies (exponential, linear, fixed), how to configure retries at the reactor or step level, and how background retries work without blocking workers.
 
 ### [Interrupts](documentation/interrupts.md)
 Learn how to pause and resume reactors to handle long-running processes, manual approvals, and asynchronous callbacks. Patterns for correlation IDs, timeouts, and payload validation.
@@ -1352,11 +1460,11 @@ 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 `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.
+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-background 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)
 
-Hook into the execution lifecycle with observer middlewares. Covers the full set of lifecycle events (reactor, step, retry, compensation/undo, async hand-off, locks/semaphores), writing and registering custom middlewares (global and per-reactor), and the built-in `RubyReactor::OpenTelemetry` tracing middleware — span structure, input/argument redaction, distributed trace propagation across async/retry boundaries, and custom exporters.
+Hook into the execution lifecycle with observer middlewares. Covers the full set of lifecycle events (reactor, step, retry, compensation/undo, background hand-off, locks/semaphores), writing and registering custom middlewares (global and per-reactor), and the built-in `RubyReactor::OpenTelemetry` tracing middleware — span structure, input/argument redaction, distributed trace propagation across background/retry boundaries, and custom exporters.
 
 ### Examples
 - [Order Processing](documentation/examples/order_processing.md) - Complete order processing workflow example
@@ -1376,7 +1484,7 @@ Hook into the execution lifecycle with observer middlewares. Covers the full set
 - [ ] Multiple storage adapters
   - [X] Redis
   - [ ] ActiveRecord
-- [X] Multiple Async adapters
+- [X] Multiple background job adapters
   - [X] Sidekiq
   - [X] ActiveJob
 - [X] OpenTelemetry support

data/lib/ruby_reactor/adapters/active_job/router.rb

@@ -10,13 +10,13 @@ module RubyReactor
         def self.perform_async(context_id, reactor_class_name = nil, intermediate_results: {})
           job_id = RubyReactor::Adapters::ActiveJob::Worker.perform_async(context_id, reactor_class_name)
           RubyReactor::DispatchResult.new(job_id: job_id, intermediate_results: intermediate_results,
-                                       execution_id: context_id)
+                                          execution_id: context_id)
         end
 
         def self.perform_in(delay, context_id, reactor_class_name = nil, intermediate_results: {})
           job_id = RubyReactor::Adapters::ActiveJob::Worker.perform_in(delay, context_id, reactor_class_name)
           RubyReactor::DispatchResult.new(job_id: job_id, intermediate_results: intermediate_results,
-                                       execution_id: context_id)
+                                          execution_id: context_id)
         end
 
         # One `async_step`'s work, dispatched as its own independent unit. The

data/lib/ruby_reactor/adapters/sidekiq/router.rb

@@ -10,13 +10,13 @@ module RubyReactor
         def self.perform_async(context_id, reactor_class_name = nil, intermediate_results: {})
           job_id = RubyReactor::Adapters::Sidekiq::Worker.perform_async(context_id, reactor_class_name)
           RubyReactor::DispatchResult.new(job_id: job_id, intermediate_results: intermediate_results,
-                                       execution_id: context_id)
+                                          execution_id: context_id)
         end
 
         def self.perform_in(delay, context_id, reactor_class_name = nil, intermediate_results: {})
           job_id = RubyReactor::Adapters::Sidekiq::Worker.perform_in(delay, context_id, reactor_class_name)
           RubyReactor::DispatchResult.new(job_id: job_id, intermediate_results: intermediate_results,
-                                       execution_id: context_id)
+                                          execution_id: context_id)
         end
 
         # One `async_step`'s work, dispatched as its own independent unit. The

data/lib/ruby_reactor/context.rb

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

data/lib/ruby_reactor/dsl/interrupt_builder.rb

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

data/lib/ruby_reactor/dsl/map_builder.rb

@@ -20,7 +20,7 @@ module RubyReactor
         end
         @reactor = reactor
         @argument_mappings = {}
-        @async = false
+        @fan_out = false
         @strict_ordering = true
         @batch_size = nil
         @source_enumerable = nil
@@ -40,9 +40,28 @@ module RubyReactor
                              end
       end
 
-      def async(async = true, batch_size: nil)
-        @async = async
-        @batch_size = batch_size if batch_size
+      # Run every element as its own background job. `batch_size` caps how many
+      # element jobs are enqueued at a time (back pressure); without it the whole
+      # source fans out at once. A fan-out map is a hand-off point: the reactor
+      # stops at the map and resumes in a worker once the collector has every
+      # element's outcome.
+      def fan_out(enabled = true, batch_size: nil)
+        @fan_out = enabled
+        self.batch_size(batch_size) unless batch_size.nil?
+      end
+
+      # `async` on a map named element fan-out with the word that now means
+      # `async_step` / `async_reactor` — independent units the reactor does not
+      # stop for. A fan-out map does stop the reactor, so it gets its own word.
+      def async(*)
+        raise RubyReactor::Error::DeprecatedDslError.new(
+          "`async` inside a `map` block has been removed: it read as `async_step`/`async_reactor`, which " \
+          "dispatch independent units, whereas a fan-out map hands the reactor off until every element " \
+          "finishes. Use `fan_out` instead (`fan_out batch_size: N` for back pressure) — note this also " \
+          "changes worker dispatch: each element now runs in its own background worker rather than being " \
+          "suppressed inline by `inline_async_execution` as the old `async true` was.",
+          step: @name
+        )
       end
 
       def strict_ordering(enabled = true)
@@ -50,6 +69,13 @@ module RubyReactor
       end
 
       def batch_size(size)
+        unless size.is_a?(Integer) && size.positive?
+          raise RubyReactor::Error::ValidationError.new(
+            "`batch_size` must be a positive Integer, got #{size.inspect}",
+            step: @name
+          )
+        end
+
         @batch_size = size
       end
 
@@ -98,7 +124,7 @@ module RubyReactor
             batch_size: { source: RubyReactor::Template::Value.new(@batch_size) },
             collect_block: { source: RubyReactor::Template::Value.new(@collect_block) },
             fail_fast: { source: RubyReactor::Template::Value.new(@fail_fast) },
-            async: { source: RubyReactor::Template::Value.new(@async) }
+            fan_out: { source: RubyReactor::Template::Value.new(@fan_out) }
           },
           run_block: nil,
           compensate_block: nil,

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)