ruby_reactor 0.5.0 → 0.5.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 134fc0713b22bad85e193592696b24417cb3c30afe8e1e7cec41328df4dafeb5
-  data.tar.gz: 469b9dc316a61f0814b964ff1afd9292bf4a98790807e367ffda3c575c62e4f5
+  metadata.gz: 66c0a0c5591cd862dc61063d752f4d92111370808256bfdae749825fec68429b
+  data.tar.gz: 212ac4ce7ef87e5d28606cab0aff8358afde437389fbb5b2d717b1b5874daa77
 SHA512:
-  metadata.gz: 6c28f483542f87de327e23554783dfffc1d92b89c181c85d1317763aaa0a4f824f07cfbc8dbc9589f9b814bae2d4debe11acaf87c84a9b9f6b7a501110a71ff4
-  data.tar.gz: b856bce9fb30b8e2e8e1b27d01b4801ffa87e95b2214cccddd73d1b0447b5801dd3f90a722977e6955786b81e70b60ac2339450552df216df37fb334a05735b5
+  metadata.gz: 75e3bd7ead2281ef7bd1a74fe42a1aaaa1ff5ac92db2b72172e779b0fa9591878268b9829c939def027a6d368ad0ad7b00eddaa05bbb5497f0678229b68b17c0
+  data.tar.gz: 46c44e73bef1e7f2a11d7a5de51de83a2a9a2505aa8c5b06cf64215bc97c4c272f67f23a220187431a188a6dcca216ee13741566fc61e1ead6a8d7dc7b392d74

data/.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "0.5.0"
+  ".": "0.5.2"
 }

data/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## [0.5.2](https://github.com/arturictus/ruby_reactor/compare/v0.5.1...v0.5.2) (2026-06-14)
+
+
+### Features
+
+* Nonce lock ([#26](https://github.com/arturictus/ruby_reactor/issues/26)) ([5925cac](https://github.com/arturictus/ruby_reactor/commit/5925cac7af93f59be6c0a8a98ab020f96080f60b))
+
+## [0.5.1](https://github.com/arturictus/ruby_reactor/compare/v0.5.0...v0.5.1) (2026-06-14)
+
+
+### Features
+
+* streamline input validation DSL and enhance error handling ([#35](https://github.com/arturictus/ruby_reactor/issues/35)) ([e32f3ec](https://github.com/arturictus/ruby_reactor/commit/e32f3ec91d87cf7a5060558ee705089f1dc76ca6))
+
 ## [0.5.0](https://github.com/arturictus/ruby_reactor/compare/v0.4.1...v0.5.0) (2026-06-11)
 
 

data/README.md

@@ -24,7 +24,7 @@ The key value is **Reliability**: if any part of your workflow fails, Ruby React
 - **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**: 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"), and `with_period` to dedup reactors to once per calendar bucket (once per day/month/year/etc). 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. Async jobs snooze on contention with smart `retry_after` instead of consuming retry budget.
 
 ## Comparison
 
@@ -58,7 +58,7 @@ The key value is **Reliability**: if any part of your workflow fails, Ruby React
     - [Full Reactor Async](#full-reactor-async)
     - [Step-Level Async](#step-level-async)
   - [Interrupts (Pause & Resume)](#interrupts-pause--resume)
-  - [Locks & Semaphores](#locks--semaphores)
+  - [Locks, Semaphores & Ordered Locks](#locks-semaphores--ordered-locks)
   - [Map & Parallel Execution](#map--parallel-execution)
     - [Map with Dynamic Source (ActiveRecord)](#map-with-dynamic-source-activerecord)
   - [Input Validation](#input-validation)
@@ -92,29 +92,51 @@ Or install it yourself as:
 
 Configure RubyReactor with your Sidekiq and Redis settings:
 
+Every setting below is **optional** — RubyReactor ships with the defaults shown. Override only what you need.
+
 ```ruby
 RubyReactor.configure do |config|
-  # Redis configuration for state persistence
+  # Storage adapter. Default: :redis (the only adapter shipped today).
   config.storage.adapter = :redis
+  # Redis URL. Default: "redis://localhost:6379/0".
   config.storage.redis_url = ENV.fetch("REDIS_URL", "redis://localhost:6379/0")
+  # Extra options passed to Redis.new. Default: {}.
   config.storage.redis_options = { timeout: 1 }
 
-  # Sidekiq configuration for async execution
+  # Sidekiq queue used by RubyReactor's async worker. Default: :default.
   config.sidekiq_queue = :default
+  # Sidekiq retry count for infrastructure failures only (deserialization,
+  # Redis, network). Step retries are managed separately. Default: 3.
   config.sidekiq_retry_count = 3
 
-  # Lock contention snooze behavior for async reactors. When a Sidekiq worker
-  # cannot acquire a lock or semaphore, it re-enqueues itself with this delay
-  # (plus jitter) up to `lock_snooze_max_attempts` times before giving up.
+  # Lock/semaphore/rate-limit/ordered-lock contention snooze behavior for
+  # async reactors. When a Sidekiq worker cannot acquire a primitive it
+  # re-enqueues itself with `lock_snooze_base_delay + rand(0..lock_snooze_jitter)`
+  # seconds (rate-limit uses a precise `retry_after_seconds` hint from the error;
+  # ordered-lock waits re-poll at the base delay so a successor catches its
+  # blocker finishing fast), up to `lock_snooze_max_attempts` times before
+  # marking the context :failed. Defaults: 5 / 5 / 20. Set max_attempts to
+  # :infinity to never give up.
   config.lock_snooze_base_delay = 5
   config.lock_snooze_jitter = 5
   config.lock_snooze_max_attempts = 20
 
-  # Logger configuration
+  # Named rate limits shared across reactors. Reference them with
+  # `with_rate_limit(:stripe)`. See Locks, Semaphores, Rate Limits & Periods.
+  config.rate_limits.register(:stripe, limits: { second: 3, minute: 100 })
+
+  # Logger. Default: Logger.new($stderr).
   config.logger = Logger.new($stdout)
+
+  # Async router. Default: RubyReactor::SidekiqAdapter. Swap for a custom
+  # adapter if you don't use Sidekiq — the adapter only needs to respond to
+  # `perform_async(serialized_context, reactor_class_name, **)`.
+  # config.async_router = MyCustomAdapter
 end
 ```
 
+You can also leave out the `configure` block entirely — defaults work for local development against a Redis on `localhost:6379`.
+
 
 ## Quick Start
 
@@ -355,14 +377,15 @@ ApprovalReactor.continue_by_correlation_id(
 )
 ```
 
-### Locks & Semaphores
+### Locks, Semaphores & Ordered Locks
 
 Coordinate across processes with Redis-backed primitives:
 
 - **`with_lock`** — at-most-one runner per key at a time (concurrency control).
 - **`with_semaphore`** — cap total concurrent runners per key (capacity control).
-- **`with_rate_limit`** — fixed-window rate limit, single or multi-window ("3/sec AND 100/min").
+- **`with_rate_limit`** — fixed-window rate limit, single or multi-window ("3/sec AND 100/min"). Inline per-reactor, or reference a named limit registered once in `RubyReactor.configure` and shared across reactors.
 - **`with_period`** — run at most once per calendar bucket (dedup / once-per-day, once-per-month, etc).
+- **`with_ordered_lock`** — strict transaction ordering via a monotonically increasing nonce assigned at enqueue. Workers can only proceed when their nonce equals `last_completed + 1`.
 
 ```ruby
 class RefundOrderReactor < RubyReactor::Reactor
@@ -419,12 +442,55 @@ class ChargeReactor < RubyReactor::Reactor
     run { |args| Stripe.charge(args[:account_id]) }
   end
 end
+
+class OrderedTransactionReactor < RubyReactor::Reactor
+  async
+  input :account_id
+  input :transaction
+
+  # Strict order: a monotonically increasing nonce is assigned at enqueue
+  # time (inside `Reactor.run`). Workers only execute when their nonce
+  # equals last_completed + 1; otherwise they snooze. After the sequence
+  # fully drains the counter resets to 0.
+  with_ordered_lock(poison_pill_timeout: 300) { |inputs| "txs:#{inputs[:account_id]}" }
+
+  step :apply do
+    argument :transaction, input(:transaction)
+    run { |args| Ledger.apply(args[:transaction]) }
+  end
+end
+
+# Caller-side order is preserved; the worker pool may pick jobs in any order
+# but the gate enforces sequential execution per key.
+[tx1, tx2, tx3].each { |tx| OrderedTransactionReactor.run(account_id: 42, transaction: tx) }
 ```
 
+**Named global limits.** When several reactors hit the same external service, register the limit once and reference it by name. The name is the shared key base, so every reactor throttles against one bucket:
+
+```ruby
+RubyReactor.configure do |config|
+  config.rate_limits.register(:stripe, limits: { second: 3, minute: 100 })
+  config.rate_limits.register(:twilio, limit: 10, period: :second)
+end
+
+class ChargeReactor < RubyReactor::Reactor
+  input :account_id
+
+  with_rate_limit(:stripe)   # shared :stripe quota across every reactor
+
+  step :charge do
+    argument :account_id, input(:account_id)
+    run { |args| Stripe.charge(args[:account_id]) }
+  end
+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.
+
 On contention:
 
-- **Inline** (`Reactor.run`) raises `RubyReactor::Lock::AcquisitionError` / `RubyReactor::Semaphore::AcquisitionError` / `RubyReactor::RateLimit::ExceededError`.
-- **Async** (Sidekiq) snoozes the job via `perform_in(delay, ...)`. For rate limits the delay is the error's `retry_after_seconds` (precise wakeup); for locks/semaphores it's `lock_snooze_base_delay + jitter`. Snoozes do not count against the Sidekiq retry budget. After `lock_snooze_max_attempts` snoozes the context is marked failed.
+- **Inline** (`Reactor.run`) raises `RubyReactor::Lock::AcquisitionError` / `RubyReactor::Semaphore::AcquisitionError` / `RubyReactor::RateLimit::ExceededError` / `RubyReactor::OrderedLock::WaitError`.
+- **Async** (Sidekiq) 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 Sidekiq 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:
 
@@ -446,7 +512,7 @@ step :ensure_active do
 end
 ```
 
-See [Locks, Semaphores, Rate Limits & Periods](documentation/locks_and_semaphores.md) for re-entrancy, auto-extend, multi-window quotas, bucket semantics, owner identity, snooze tuning, and operational notes.
+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
 
@@ -513,26 +579,73 @@ end
 
 ### Input Validation
 
-RubyReactor integrates with dry-validation for input validation:
+RubyReactor integrates with dry-validation for input validation. A single
+`input` method escalates from a bare declaration to a full nested schema.
+Name and optionality are declared once.
+
+**Form 0 — declaration only** (no validation, value passes through as-is):
 
 ```ruby
-class ValidatedUserReactor < RubyReactor::Reactor
-  input :name do
-    required(:name).filled(:string, min_size?: 2)
-  end
+input :user
+input :payload, redact: true
+```
 
-  input :email do
-    required(:email).filled(:string)
-  end
+**Form 1 — inline scalar** (the common case). The type is an optional
+positional; any keyword ending in `?` is a dry-schema predicate:
 
-  input :age do
-    required(:age).filled(:integer, gteq?: 18)
-  end
+```ruby
+input :name,  :string,  min_size?: 2
+input :email, :string,  format?: /\A[^@\s]+@[^@\s]+\z/
+input :age,   :integer, gteq?: 18
+
+# optional: true flips required(...).filled -> optional(...).maybe
+input :bio,   :string,  optional: true, max_size?: 100
+```
+
+**Form 1b — class / module** maps to a `type?` instance check:
+
+```ruby
+input :user,  User                 # required(:user).filled(type?: User)
+input :items, Array, min_size?: 1  # instance check + predicate
+```
 
-  # Optional inputs
-  input :bio, optional: true do
-    optional(:bio).maybe(:string, max_size?: 100)
+**Form 2 — macro block** for nested / complex schemas. The block receives the
+input's macro (already bound to the name and optionality), and because it is a
+block argument your class constants and helpers stay reachable:
+
+```ruby
+EMAIL = /\A[^@\s]+@[^@\s]+\z/
+
+input :order do |i|
+  i.hash do
+    required(:customer).hash do
+      required(:email).filled(:string, format?: EMAIL)
+    end
+    required(:items).each do
+      schema { required(:product_id).filled(:string) }
+    end
   end
+end
+```
+
+**Form 3 — pre-built schema / contract** (also the home for coercing dry-types):
+
+```ruby
+UserSchema = Dry::Schema.Params do
+  required(:user).hash { required(:email).filled(:string) }
+end
+
+input :user, validate: UserSchema
+```
+
+Putting the inline forms together:
+
+```ruby
+class ValidatedUserReactor < RubyReactor::Reactor
+  input :name,  :string,  min_size?: 2
+  input :email, :string
+  input :age,   :integer, gteq?: 18
+  input :bio,   :string,  optional: true, max_size?: 100
 
   step :create_profile do
     argument :name, input(:name)
@@ -571,6 +684,62 @@ result = ValidatedUserReactor.run(
 )
 ```
 
+All validation failures — inputs, step arguments, step output, and interrupt
+payloads — surface uniformly as a `RubyReactor::Error::InputValidationError`
+with a `field_errors` hash:
+
+```ruby
+result = ValidatedUserReactor.run(name: "A")
+result.error                       # => RubyReactor::Error::InputValidationError
+result.error.field_errors[:name]   # => "size cannot be less than 2"
+```
+
+### Step Argument & Output Validation
+
+Arguments can be validated inline using the same forms as `input`. Inline rules
+compose with a `validate_args` block (used for cross-field rules):
+
+```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
+
+  # Optional cross-field block (composes with the inline rules above)
+  validate_args do
+    required(:amount).filled(:decimal, lt?: 10_000)
+  end
+
+  run { |args, _| charge!(args) }
+end
+```
+
+Output validation is scalar-aware — pass a type/predicates for a single value,
+or a block for a hash output:
+
+```ruby
+validate_output :integer, gteq?: 0   # scalar return value
+validate_output do                   # hash return value
+  required(:id).filled(:string)
+end
+```
+
+### Interrupt Payload Validation
+
+Validate the payload supplied on resume with `validate_payload` (the older
+`validate` is kept as a deprecated alias):
+
+```ruby
+interrupt :await_approval do
+  wait_for :submit_request
+
+  validate_payload do
+    required(:approved).filled(:bool)
+    optional(:note).maybe(:string)
+  end
+end
+```
+
 ### Complex Workflows with Dependencies
 
 Steps can depend on results from multiple other steps:
@@ -578,7 +747,7 @@ Steps can depend on results from multiple other steps:
 ```ruby
 class OrderProcessingReactor < RubyReactor::Reactor
   input :user_id
-  input :product_ids, validate: ->(ids) { ids.is_a?(Array) && ids.any? }
+  input :product_ids, Array, min_size?: 1
 
   step :validate_user do
     argument :user_id, input(:user_id)
@@ -857,9 +1026,9 @@ Learn how to pause and resume reactors to handle long-running processes, manual
 ### [Testing with RSpec](documentation/testing.md)
 Comprehensive guide to testing reactors with RubyReactor's testing utilities. Learn about the `TestSubject` class for reactor execution and introspection, step mocking for isolating dependencies, testing nested and composed reactors, and custom RSpec matchers like `be_success`, `have_run_step`, and `have_retried_step`.
 
-### [Locks, Semaphores, Rate Limits & Periods](documentation/locks_and_semaphores.md)
+### [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`), and calendar-bucketed dedup (`with_period`, returning `Skipped` results). 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, and once-per-day/month/year scheduling patterns.
+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.
 
 ### [Middlewares & OpenTelemetry](documentation/middlewares.md)
 

data/lib/ruby_reactor/configuration.rb

@@ -59,5 +59,12 @@ module RubyReactor
     def middlewares
       @middlewares ||= []
     end
+
+    # Registry of named rate limits shared across reactors. Configure entries
+    # with `config.rate_limits.register(:name, ...)` and reference them from a
+    # reactor via `with_rate_limit(:name)`.
+    def rate_limits
+      @rate_limits ||= RubyReactor::RateLimitRegistry.new
+    end
   end
 end

data/lib/ruby_reactor/dsl/compose_builder.rb

@@ -41,6 +41,7 @@ module RubyReactor
       end
 
       def build
+        warn_if_child_has_ordered_lock!
         dependencies = extract_dependencies_from_mappings
 
         step_config = {
@@ -78,6 +79,25 @@ module RubyReactor
 
       private
 
+      # Composed children bypass `Reactor#run`, so `assign_ordered_lock_nonce!`
+      # never fires for them — their `with_ordered_lock` declaration is silently
+      # ignored. Surface this at class load so users don't expect ordering
+      # enforcement that isn't happening. Nested ordered-lock sequences must be
+      # invoked as top-level `Reactor.run` to participate.
+      def warn_if_child_has_ordered_lock!
+        return unless @composed_reactor_class
+        return unless @composed_reactor_class.respond_to?(:ordered_lock_config)
+        return unless @composed_reactor_class.ordered_lock_config
+
+        parent_name = @reactor&.name || "<anonymous>"
+        child_name = @composed_reactor_class.name || "<anonymous>"
+        RubyReactor.configuration.logger.warn(
+          "RubyReactor: `with_ordered_lock` on #{child_name} is ignored when " \
+          "composed by #{parent_name}##{@name}. Nested ordered-lock sequences " \
+          "are independent and must run via top-level `Reactor.run` to be enforced."
+        )
+      end
+
       def ensure_composed_reactor_class!
         raise ArgumentError, "No block provided for inline compose" unless @composed_reactor_class
       end

data/lib/ruby_reactor/dsl/interrupt_builder.rb

@@ -23,9 +23,25 @@ module RubyReactor
         @timeout_config = { duration: seconds, strategy: strategy }
       end
 
-      def validate(&block)
+      # Validate the resume payload. Accepts a block (schema DSL) or a pre-built
+      # dry-schema. Payloads are multi-field hashes, so the block stays primary.
+      def validate_payload(schema = nil, &block)
         check_dry_validation_available!
-        @validation_schema = build_validation_schema(&block)
+        @validation_schema =
+          if block
+            build_validation_schema(&block)
+          elsif schema
+            RubyReactor::Validation::SchemaBuilder.schema_for(schema)
+          end
+      end
+
+      # Deprecated alias for {#validate_payload}.
+      def validate(schema = nil, &block)
+        unless @warned_validate
+          @warned_validate = true
+          warn "[RubyReactor] DEPRECATION: interrupt `validate` is deprecated; use `validate_payload` instead."
+        end
+        validate_payload(schema, &block)
       end
 
       def build

data/lib/ruby_reactor/dsl/lockable.rb

@@ -8,7 +8,7 @@ module RubyReactor
       end
 
       module ClassMethods
-        attr_reader :lock_config, :semaphore_config, :period_config, :rate_limit_config
+        attr_reader :lock_config, :semaphore_config, :period_config, :rate_limit_config, :ordered_lock_config
 
         # Propagate lock/semaphore/period/rate-limit config to subclasses;
         # without this a subclass of a configured reactor would silently lose
@@ -19,6 +19,7 @@ module RubyReactor
           subclass.instance_variable_set(:@semaphore_config, @semaphore_config) if @semaphore_config
           subclass.instance_variable_set(:@period_config, @period_config) if @period_config
           subclass.instance_variable_set(:@rate_limit_config, @rate_limit_config) if @rate_limit_config
+          subclass.instance_variable_set(:@ordered_lock_config, @ordered_lock_config) if @ordered_lock_config
         end
 
         # Configure locking for this reactor
@@ -74,6 +75,45 @@ module RubyReactor
           }
         end
 
+        # Configure strict-ordering nonce gating for this reactor. A
+        # monotonically increasing nonce is assigned at enqueue time; the
+        # worker can only proceed when its nonce equals `last_completed + 1`.
+        # Otherwise the worker raises {OrderedLock::WaitError} and the Sidekiq
+        # worker snoozes via `perform_in`.
+        #
+        # Counters reset to 0 once the sequence fully drains (last_completed
+        # catches up to next). Re-entrancy is NOT supported — a nested reactor
+        # with its own `with_ordered_lock` is an independent sequence.
+        #
+        # @param poison_pill_timeout [Integer] seconds since the blocker nonce
+        #   was assigned before the gate auto-advances past it. Protects
+        #   against permanent head-of-line blocking from a caller that INCRed
+        #   the counter but crashed before enqueueing.
+        # @param ttl [Integer] TTL on the counter keys, refreshed on every
+        #   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)`
+        #   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
+        #   failures. The poison state is per-key and clears on full drain. The
+        #   check only applies to a fresh `execute`; an already-started run
+        #   that paused (InterruptResult/AsyncResult) completes on resume even
+        #   if the chain failed in the meantime.
+        # @yield [inputs] Block that returns the ordered-lock key string.
+        def with_ordered_lock(poison_pill_timeout: OrderedLock::DEFAULT_POISON_PILL_TIMEOUT,
+                              ttl: OrderedLock::DEFAULT_TTL,
+                              strict: true,
+                              &block)
+          @ordered_lock_config = {
+            poison_pill_timeout: poison_pill_timeout,
+            ttl: ttl,
+            strict: strict,
+            key_proc: block
+          }
+        end
+
         # Configure rate limiting for this reactor (fixed-window counter).
         # Pass either a single window via `limit:` + `period:`, or a hash of
         # windows via `limits:` for layered API quotas.
@@ -86,44 +126,35 @@ module RubyReactor
         #     limits: { second: 3, minute: 100, hour: 5000 }
         #   ) { |i| "stripe:#{i[:account_id]}" }
         #
+        # @example Named global limit (registered in `RubyReactor.configure`)
+        #   with_rate_limit(:stripe)
+        #
+        # @param name [Symbol] reference a rate limit registered via
+        #   `config.rate_limits.register`. When given, the limit is shared
+        #   across every reactor using that name (the name is the key base);
+        #   no `limit:`/`period:`/`limits:` or block is accepted.
         # @param limit [Integer] requests per period (single-window form)
         # @param period [Symbol, Integer] :second / :minute / :hour / :day /
         #   :week / :month / :year, or integer seconds (single-window form)
         # @param limits [Hash{Symbol,Integer => Integer}] mapping of period
         #   unit to limit (multi-window form)
-        # @yield [inputs] Block returning the rate-limit key base.
-        def with_rate_limit(limit: nil, period: nil, limits: nil, &block)
-          normalized = normalize_rate_limit_args(limit, period, limits)
+        # @yield [inputs] Block returning the rate-limit key base (inline forms).
+        def with_rate_limit(name = nil, limit: nil, period: nil, limits: nil, &block)
+          if name
+            if limit || period || limits || block
+              raise ArgumentError, "with_rate_limit(:#{name}) references a registered limit; " \
+                                   "do not also pass :limit/:period/:limits or a block"
+            end
+
+            @rate_limit_config = { name: name.to_sym }
+            return
+          end
 
           @rate_limit_config = {
-            limits: normalized,
+            limits: RubyReactor::RateLimit.normalize_specs(limit: limit, period: period, limits: limits),
             key_proc: block
           }
         end
-
-        private
-
-        def normalize_rate_limit_args(limit, period, limits)
-          if limits
-            raise ArgumentError, "with_rate_limit: use either :limits, or :limit + :period, not both" if limit || period
-
-            limits.map do |period_key, limit_val|
-              {
-                period_seconds: RubyReactor::Period.period_seconds(period_key),
-                limit: Integer(limit_val),
-                name: period_key.to_s
-              }
-            end
-          elsif limit && period
-            [{
-              period_seconds: RubyReactor::Period.period_seconds(period),
-              limit: Integer(limit),
-              name: period.to_s
-            }]
-          else
-            raise ArgumentError, "with_rate_limit requires :limit + :period, or :limits"
-          end
-        end
       end
     end
   end

data/lib/ruby_reactor/dsl/reactor.rb

@@ -62,8 +62,8 @@ module RubyReactor
         end
 
         # rubocop:disable Metrics/ParameterLists
-        def input(name, transform: nil, description: nil, validate: nil, optional: false, redact: false,
-                  &validation_block)
+        def input(name, type = nil, transform: nil, description: nil, validate: nil, optional: false, redact: false,
+                  **predicates, &block)
           # rubocop:enable Metrics/ParameterLists
           inputs[name] = {
             transform: transform,
@@ -72,12 +72,41 @@ module RubyReactor
             redact: redact
           }
 
-          # Handle validation
-          return unless validate || validation_block
+          validator = build_input_validator_for(name, type, optional, validate, predicates, &block)
+          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)
+        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
+        end
+        private :build_input_validator_for
+
+        def warn_deprecated_input_block
+          return if @warned_input_block
 
-          validator = create_input_validator(validation_block || validate)
-          input_validations[name] = validator
+          @warned_input_block = true
+          warn "[RubyReactor] DEPRECATION: the single-key `input :name do required(:name)... end` block is " \
+               "deprecated. Use the inline form (`input :name, :string, min_size?: 2`) or the macro block " \
+               "(`input :name do |i| ... end`) instead."
         end
+        private :warn_deprecated_input_block
 
         def step(name, impl = nil, &block)
           builder = RubyReactor::Dsl::StepBuilder.new(name, impl, self)
@@ -149,7 +178,9 @@ module RubyReactor
             RubyReactor.Success(inputs_hash)
           else
             error = RubyReactor::Error::InputValidationError.new(errors)
-            RubyReactor.Failure(error)
+            # Same shape as executor-built validation failures: expose the
+            # structured field errors on the Failure itself.
+            RubyReactor.Failure(error, validation_errors: errors, reactor_name: name)
           end
         end