ruby_reactor 0.4.1 → 0.5.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 729d8c7da4954534a2775a360d79fc96326d76b5ca69c7361ca0433e4bd6571e
-  data.tar.gz: e9e545d2ea937135f19c7c04697993125fdfc38d57fc71d6a7b0aede9bf5efa9
+  metadata.gz: 54ecb36ac72eedf48af0025dff29d83986449586683300ce3fe8fd874c1412d5
+  data.tar.gz: 5e3565e3e238bad746d93982ca7b01560893a68755be18fbfce95df6f54ce5b3
 SHA512:
-  metadata.gz: 23aac29ebf4c4e018fc3ab4bffbc46d79fa68ea74d783034fb984094cb7d97e791fc194c767ab59fb4992be267c171f6cbcc1897fb6160df4bedeb88faa3f080
-  data.tar.gz: edffc8600293e035e1d318a4f4b7f7240ec67aa06704e941465e06c6eadda16e1939c36e2a826bd0b92183728360cb3babab4b26b877548559f61a64f2977c4a
+  metadata.gz: 708acdb0c74582cea4c33210ea1bac055080c7dd19c69d166db4b2c22705de2935346d6b09d4fc6c9cbb1bda5ba235cade92a88f04fe791e364bb78bda256138
+  data.tar.gz: e3f03e46d71babe276224571eaad3e794c7d8c695e2865333f5021e680feb21a12cd3b33527035e1349dc600d01faec87b573b691d7e50521c4f0d81610c8b8f

data/.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "0.4.1"
+  ".": "0.5.1"
 }

data/.rubocop.yml

@@ -14,6 +14,7 @@ AllCops:
     - db/**/*
     - config/**/*
     - demo_app/**/*
+    - .ruby-lsp/**/*
 
 Style/StringLiterals:
   EnforcedStyle: double_quotes

data/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## [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)
+
+
+### Features
+
+* Middlewares & OpenTelemetry ([#32](https://github.com/arturictus/ruby_reactor/issues/32)) ([a9e10ce](https://github.com/arturictus/ruby_reactor/commit/a9e10ceb6fa6381ead57a5905931343f8d1182d1))
+
 ## [0.4.1](https://github.com/arturictus/ruby_reactor/compare/v0.4.0...v0.4.1) (2026-05-25)
 
 

data/README.md

@@ -110,6 +110,10 @@ RubyReactor.configure do |config|
   config.lock_snooze_jitter = 5
   config.lock_snooze_max_attempts = 20
 
+  # 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 configuration
   config.logger = Logger.new($stdout)
 end
@@ -361,7 +365,7 @@ 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).
 
 ```ruby
@@ -421,6 +425,28 @@ class ChargeReactor < RubyReactor::Reactor
 end
 ```
 
+**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`.
@@ -475,6 +501,8 @@ 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).
 
+`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).
+
 #### Map with Dynamic Source (ActiveRecord)
 
 You can use a block for `source` to dynamically fetch data, such as from ActiveRecord queries. The result is wrapped in a `ResultEnumerator` for easy access to successes and failures.
@@ -511,26 +539,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
+```
 
-  # Optional inputs
-  input :bio, optional: true do
-    optional(:bio).maybe(:string, 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
+```
+
+**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)
@@ -569,6 +644,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:
@@ -576,7 +707,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)
@@ -859,6 +990,10 @@ Comprehensive guide to testing reactors with RubyReactor's testing utilities. Le
 
 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.
 
+### [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.
+
 ### Examples
 - [Order Processing](documentation/examples/order_processing.md) - Complete order processing workflow example
 - [Payment Processing](documentation/examples/payment_processing.md) - Payment handling with compensation
@@ -871,7 +1006,7 @@ Coordinate access to shared resources across processes with Redis-backed primiti
 - [X] `map` step to iterate over arrays in parallel
 - [X] `compose` special step to execute reactors as step
 - [X] `interrupt` to pause and resume reactors
-- [ ] Middlewares
+- [X] Middlewares
 - [ ] Async ruby to parallelize same level steps
 - [x] Web dashboard to inspect reactor results and errors
 - [ ] Multiple storage adapters
@@ -880,7 +1015,7 @@ Coordinate access to shared resources across processes with Redis-backed primiti
 - [ ] Multiple Async adapters
   - [X] Sidekiq
   - [ ] ActiveJob
-- [ ] OpenTelemetry support
+- [X] OpenTelemetry support
 - [X] locks
 
 ## Development

data/lib/ruby_reactor/configuration.rb

@@ -8,7 +8,8 @@ module RubyReactor
     include Singleton
 
     attr_writer :sidekiq_queue, :sidekiq_retry_count, :logger, :async_router,
-                :lock_snooze_base_delay, :lock_snooze_jitter, :lock_snooze_max_attempts
+                :lock_snooze_base_delay, :lock_snooze_jitter, :lock_snooze_max_attempts,
+                :middlewares
 
     def sidekiq_queue
       @sidekiq_queue ||= :default
@@ -54,5 +55,16 @@ module RubyReactor
                              raise "Unknown storage adapter: #{storage.adapter}"
                            end
     end
+
+    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/context.rb

@@ -5,7 +5,8 @@ module RubyReactor
     attr_accessor :inputs, :intermediate_results, :private_data, :current_step, :retry_count, :concurrency_key,
                   :retry_context, :reactor_class, :execution_trace, :inline_async_execution, :undo_stack,
                   :parent_context, :root_context, :composed_contexts, :context_id, :map_operations, :map_metadata,
-                  :cancelled, :cancellation_reason, :parent_context_id, :retried_from_id, :status, :failure_reason
+                  :cancelled, :cancellation_reason, :parent_context_id, :retried_from_id, :status, :failure_reason,
+                  :middlewares
 
     def initialize(inputs = {}, reactor_class = nil)
       @context_id = SecureRandom.uuid

data/lib/ruby_reactor/context_serializer.rb

@@ -202,9 +202,7 @@ module RubyReactor
 
         hash = flatten_typed_failure(hash) if hash["_type"] == "Failure"
 
-        if hash["code_snippet"].is_a?(Array) && !hash["code_snippet"].empty?
-          return hash
-        end
+        return hash if hash["code_snippet"].is_a?(Array) && !hash["code_snippet"].empty?
 
         file_path, line_number = resolve_failure_location(hash)
         return hash unless file_path && line_number

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

@@ -86,44 +86,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)
@@ -123,8 +152,12 @@ module RubyReactor
           @return_step
         end
 
-        def middleware(middleware_class)
-          middlewares << middleware_class
+        def middleware(middleware_class, **options)
+          middlewares << if options.empty?
+                           middleware_class
+                         else
+                           [middleware_class, options]
+                         end
         end
 
         def validate_inputs(inputs_hash)
@@ -145,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
 

data/lib/ruby_reactor/dsl/step_builder.rb

@@ -20,17 +20,23 @@ module RubyReactor
         @conditions = []
         @guards = []
         @dependencies = []
+        @arg_validations = []
+        @validate_args_input = nil
         @args_validator = nil
         @output_validator = nil
         @async = false
         @retry_config = {}
       end
 
-      def argument(name, source, transform: nil)
+      def argument(name, source, type = nil, transform: nil, **predicates)
         @arguments[name] = {
           source: source,
           transform: transform
         }
+
+        return unless type || predicates.any?
+
+        @arg_validations << [name, type, false, predicates]
       end
 
       def run(&block)
@@ -57,20 +63,26 @@ module RubyReactor
         @dependencies.concat(step_names)
       end
 
+      # Cross-field rules over the whole resolved argument hash. Composes with
+      # per-argument inline validations declared via `argument`; the block (or
+      # pre-built schema) is applied last and wins on conflicts.
       def validate_args(schema_or_validator = nil, &block)
-        if block_given?
-          @args_validator = build_input_validator(block)
-        elsif schema_or_validator
-          @args_validator = build_input_validator(schema_or_validator)
-        end
+        @validate_args_input = block || schema_or_validator
       end
 
-      def validate_output(schema_or_validator = nil, &block)
-        if block_given?
-          @output_validator = build_input_validator(block)
-        elsif schema_or_validator
-          @output_validator = build_input_validator(schema_or_validator)
-        end
+      # Scalar-aware output validation.
+      #   validate_output :integer, gteq?: 0   # single value
+      #   validate_output do ... end            # hash output
+      #   validate_output SomeSchema            # pre-built schema
+      def validate_output(type = nil, **predicates, &block)
+        @output_validator =
+          if block
+            create_input_validator(block)
+          elsif type.is_a?(Symbol) || type.is_a?(Module) || predicates.any?
+            build_scalar_validator(type, predicates)
+          elsif type
+            create_input_validator(type)
+          end
       end
 
       def async(async = true)
@@ -96,7 +108,7 @@ module RubyReactor
           conditions: @conditions,
           guards: @guards,
           dependencies: @dependencies,
-          args_validator: @args_validator,
+          args_validator: @args_validator || build_args_validator(@arg_validations, @validate_args_input),
           output_validator: @output_validator,
           async: @async,
           retry_config: @retry_config.empty? ? (@reactor&.retry_defaults || {}) : @retry_config
@@ -104,32 +116,6 @@ module RubyReactor
 
         RubyReactor::Dsl::StepConfig.new(step_config)
       end
-
-      private
-
-      def build_input_validator(schema_or_block)
-        check_dry_validation_available!
-
-        schema = case schema_or_block
-                 when Proc
-                   build_validation_schema(&schema_or_block)
-                 else
-                   schema_or_block
-                 end
-
-        RubyReactor::Validation::InputValidator.new(schema)
-      end
-
-      def build_validation_schema(&block)
-        RubyReactor::Validation::SchemaBuilder.build_from_block(&block)
-      end
-
-      def check_dry_validation_available!
-        return if defined?(Dry::Schema)
-
-        raise LoadError,
-              "dry-validation gem is required for validation features. Add 'gem \"dry-validation\"' to your Gemfile."
-      end
     end
 
     class StepConfig

data/lib/ruby_reactor/dsl/validation_helpers.rb

@@ -22,6 +22,40 @@ module RubyReactor
         RubyReactor::Validation::InputValidator.new(schema)
       end
 
+      # Form 1 / 1b — inline scalar or class type for a single named value.
+      def build_inline_validator(name, type, optional, predicates)
+        check_dry_validation_available!
+        schema = RubyReactor::Validation::SchemaBuilder.build_inline(name, type, optional, predicates)
+        RubyReactor::Validation::InputValidator.new(schema)
+      end
+
+      # Form 2 — block bound to the value's macro (`required`/`optional`).
+      def build_macro_validator(name, optional, &block)
+        check_dry_validation_available!
+        schema = RubyReactor::Validation::SchemaBuilder.build_macro(name, optional, &block)
+        RubyReactor::Validation::InputValidator.new(schema)
+      end
+
+      # Compose per-argument inline rules with an optional `validate_args`
+      # block / pre-built schema. Returns nil when there is nothing to validate.
+      def build_args_validator(inline_rules, validate_input)
+        return nil if inline_rules.empty? && validate_input.nil?
+
+        check_dry_validation_available!
+        schema = RubyReactor::Validation::SchemaBuilder.build_args(inline_rules, validate_input)
+        return nil unless schema
+
+        RubyReactor::Validation::InputValidator.new(schema)
+      end
+
+      # Scalar-aware single-value validator (used by `validate_output`). The
+      # value is wrapped under `:value` before validation.
+      def build_scalar_validator(type, predicates)
+        check_dry_validation_available!
+        schema = RubyReactor::Validation::SchemaBuilder.build_inline(:value, type, false, predicates)
+        RubyReactor::Validation::InputValidator.new(schema, wrap_key: :value)
+      end
+
       private
 
       def check_dry_validation_available!

data/lib/ruby_reactor/error/input_validation_error.rb

@@ -4,6 +4,10 @@ module RubyReactor
   module Error
     class InputValidationError < Base
       attr_reader :field_errors
+      # Step attribution, set at the raise site when the failure happened at a
+      # step boundary (argument or output validation) rather than at reactor
+      # input validation. Nil for reactor-level input failures.
+      attr_accessor :step_name, :step_arguments
 
       def initialize(field_errors)
         @field_errors = field_errors