ruby_reactor 0.5.0 → 0.5.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 134fc0713b22bad85e193592696b24417cb3c30afe8e1e7cec41328df4dafeb5
-  data.tar.gz: 469b9dc316a61f0814b964ff1afd9292bf4a98790807e367ffda3c575c62e4f5
+  metadata.gz: 54ecb36ac72eedf48af0025dff29d83986449586683300ce3fe8fd874c1412d5
+  data.tar.gz: 5e3565e3e238bad746d93982ca7b01560893a68755be18fbfce95df6f54ce5b3
 SHA512:
-  metadata.gz: 6c28f483542f87de327e23554783dfffc1d92b89c181c85d1317763aaa0a4f824f07cfbc8dbc9589f9b814bae2d4debe11acaf87c84a9b9f6b7a501110a71ff4
-  data.tar.gz: b856bce9fb30b8e2e8e1b27d01b4801ffa87e95b2214cccddd73d1b0447b5801dd3f90a722977e6955786b81e70b60ac2339450552df216df37fb334a05735b5
+  metadata.gz: 708acdb0c74582cea4c33210ea1bac055080c7dd19c69d166db4b2c22705de2935346d6b09d4fc6c9cbb1bda5ba235cade92a88f04fe791e364bb78bda256138
+  data.tar.gz: e3f03e46d71babe276224571eaad3e794c7d8c695e2865333f5021e680feb21a12cd3b33527035e1349dc600d01faec87b573b691d7e50521c4f0d81610c8b8f

data/.release-please-manifest.json

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

data/CHANGELOG.md

@@ -1,5 +1,12 @@
 # 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)
 
 

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`.
@@ -513,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)
@@ -571,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:
@@ -578,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)

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/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)
@@ -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
 

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

data/lib/ruby_reactor/executor/result_handler.rb

@@ -33,8 +33,11 @@ module RubyReactor
         when Error::StepFailureError
           handle_step_failure_error(error)
         when Error::InputValidationError
-          # Preserve validation errors as-is for proper error handling
-          RubyReactor.Failure(error, validation_errors: error.field_errors)
+          # Unified validation failure shape (inputs, step args, step output).
+          # Roll back any completed steps so saga semantics hold for mid-reactor
+          # validation failures (a no-op for input validation at reactor start).
+          @compensation_manager.rollback_completed_steps
+          build_validation_failure(error)
         when Error::Base
           # Other errors need rollback
           @compensation_manager.rollback_completed_steps
@@ -56,6 +59,25 @@ module RubyReactor
 
       private
 
+      # Failure for a validation error (reactor inputs, step arguments, or
+      # step output), carrying both the structured field errors and the step/
+      # reactor attribution stamped at the raise site (nil step_name for
+      # reactor-level input failures).
+      def build_validation_failure(error)
+        redact_inputs = []
+        redact_inputs = @context.reactor_class.inputs.select { |_, c| c[:redact] }.keys if @context.reactor_class
+
+        RubyReactor.Failure(
+          error,
+          validation_errors: error.field_errors,
+          step_name: error.step_name,
+          step_arguments: error.step_arguments || {},
+          inputs: @context.inputs,
+          redact_inputs: redact_inputs,
+          reactor_name: @context.reactor_class&.name
+        )
+      end
+
       # A step returned `RubyReactor.Skipped(...)`. Halt cleanly: record the
       # event in the trace, do NOT push to the undo stack (so existing
       # completed steps stay as-is — no compensation), and stamp the step
@@ -180,12 +202,17 @@ module RubyReactor
         output_validation_result = step_config.output_validator.call(value)
         return if output_validation_result.success?
 
-        raise Error::StepFailureError.new(
-          "Step '#{step_config.name}' output validation failed: #{output_validation_result.error.message}",
-          step: step_config.name,
-          context: @context,
-          step_arguments: resolved_arguments
-        )
+        error = output_validation_result.error
+        error.step_name = step_config.name
+        error.step_arguments = resolved_arguments
+
+        # The step DID run — its side effect exists even though its output is
+        # invalid. Treat it like a step failure: run the step's own
+        # compensation and roll back prior steps, so the side effect is not
+        # orphaned. Then surface the structured validation error (the later
+        # rollback in handle_execution_error is a no-op — stack already clear).
+        @compensation_manager.handle_step_failure(step_config, error, resolved_arguments)
+        raise error
       end
 
       def extract_location(backtrace)

data/lib/ruby_reactor/executor/step_executor.rb

@@ -128,6 +128,10 @@ module RubyReactor
       def safe_execute_step_sync(step_config, resolved_arguments = nil)
         resolved_arguments ||= resolve_arguments(step_config)
         execute_step_sync_without_result_handling(step_config, resolved_arguments)
+      rescue Error::InputValidationError
+        # Validation failures are not retryable and must surface as a structured
+        # InputValidationError (with field_errors), so let them propagate.
+        raise
       rescue StandardError => e
         # Identify redacted inputs
         redact_inputs = @reactor_class.inputs.select { |_, config| config[:redact] }.keys
@@ -240,11 +244,12 @@ module RubyReactor
         validation_result = step_config.args_validator.call(resolved_arguments)
         return if validation_result.success?
 
-        raise Error::StepFailureError.new(
-          "Step '#{step_config.name}' argument validation failed: #{validation_result.error.message}",
-          step: step_config.name,
-          context: @context
-        )
+        # Stamp step attribution so the resulting Failure can say WHERE the
+        # validation failed, not just what was invalid.
+        error = validation_result.error
+        error.step_name = step_config.name
+        error.step_arguments = resolved_arguments
+        raise error
       end
 
       def resolve_arguments(step_config)

data/lib/ruby_reactor/executor.rb

@@ -71,20 +71,28 @@ module RubyReactor
       middlewares.on(:start_reactor, reactor_class.name, context.inputs, @context)
       completed = false
 
-      skipped = check_period_gate
-      if skipped
-        @result = skipped
-        update_context_status(@result)
-        save_context
+      if (skipped = check_period_gate)
         completed = true
-        return @result
+        return finalize_skipped(skipped)
       end
 
-      acquire_locks_with_telemetry
-
+      # Validate inputs BEFORE consuming a rate-limit slot or grabbing a
+      # lock/semaphore: a run that can never start must not burn quota or
+      # briefly block other callers.
       input_validator = InputValidator.new(@reactor_class, @context)
       input_validator.validate!
 
+      acquire_locks_with_telemetry
+
+      # Re-check the period gate now that we hold the lock. The pre-lock check
+      # is a fast path; this one closes the race where two callers both passed
+      # it and then serialized on the lock — without it the second caller would
+      # re-run work the first already marked. (No-op when no lock is configured.)
+      if (skipped = check_period_gate)
+        completed = true
+        return finalize_skipped(skipped)
+      end
+
       @context.status = :running
       save_context
 
@@ -100,7 +108,8 @@ module RubyReactor
       @result
     rescue RubyReactor::Lock::AcquisitionError,
            RubyReactor::Semaphore::AcquisitionError,
-           RubyReactor::RateLimit::ExceededError => e
+           RubyReactor::RateLimit::ExceededError,
+           RubyReactor::RateLimitRegistry::UnknownLimitError => e
       raise e
     rescue StandardError => e
       @result = @result_handler.handle_execution_error(e)
@@ -118,13 +127,33 @@ module RubyReactor
       end
     end
 
-    def resume_execution
+    def resume_execution # rubocop:disable Metrics/MethodLength
       middlewares.on(:start_reactor, reactor_class.name, context.inputs, @context)
       completed = false
+      # A fresh async reactor run reaches the worker through resume_execution
+      # (it never calls execute), so the period and rate-limit gates that live
+      # in execute must be applied here too. Genuine resumes (a step already ran
+      # or we paused mid-flight, so current_step is set) must NOT re-gate: a
+      # paused reactor must not throttle or skip itself on the way back in.
+      first_run = first_execution?
       begin
         @context.status = :running
-        acquire_exclusive_lock if @reactor_class.respond_to?(:lock_config) && @reactor_class.lock_config
-        acquire_semaphore if @reactor_class.respond_to?(:semaphore_config) && @reactor_class.semaphore_config
+
+        if first_run && (skipped = check_period_gate)
+          completed = true
+          return finalize_skipped(skipped)
+        end
+        check_rate_limit if first_run
+
+        acquire_concurrency_primitives
+
+        # Post-lock re-check (see execute) — closes the period race for the
+        # first run of a locked async reactor.
+        if first_run && (skipped = check_period_gate)
+          completed = true
+          return finalize_skipped(skipped)
+        end
+
         prepare_for_resume
         save_context
 
@@ -142,7 +171,8 @@ module RubyReactor
         @result
       rescue RubyReactor::Lock::AcquisitionError,
              RubyReactor::Semaphore::AcquisitionError,
-             RubyReactor::RateLimit::ExceededError
+             RubyReactor::RateLimit::ExceededError,
+             RubyReactor::RateLimitRegistry::UnknownLimitError
         raise
       rescue StandardError => e
         handle_resume_error(e)
@@ -196,6 +226,10 @@ module RubyReactor
 
     def acquire_locks
       check_rate_limit
+      acquire_concurrency_primitives
+    end
+
+    def acquire_concurrency_primitives
       acquire_exclusive_lock if @reactor_class.respond_to?(:lock_config) && @reactor_class.lock_config
       acquire_semaphore if @reactor_class.respond_to?(:semaphore_config) && @reactor_class.semaphore_config
     end
@@ -206,20 +240,49 @@ module RubyReactor
 
     # Consume one slot from each configured rate-limit window. Raises
     # `RubyReactor::RateLimit::ExceededError` (carrying a `retry_after_seconds`
-    # hint) if any window is full. Only consulted on initial `execute`; resumes
-    # never re-check (a paused reactor must not block itself on resume).
+    # hint) if any window is full. Consulted on the first execution only —
+    # `execute` for sync reactors, the first `resume_execution` pass for async
+    # reactors. Genuine resumes never re-check (a paused reactor must not block
+    # itself on resume).
     def check_rate_limit
       return unless @reactor_class.respond_to?(:rate_limit_config) && @reactor_class.rate_limit_config
 
       config = @reactor_class.rate_limit_config
-      key_base = config[:key_proc].call(@context.inputs)
 
-      RubyReactor::RateLimit.new(key_base, limits: config[:limits]).check_and_increment!
+      if config[:name]
+        # Named global limit: the name is the shared key base and the windows
+        # come from the registry (resolved lazily so config order doesn't matter).
+        key_base = config[:name].to_s
+        limits = RubyReactor.configuration.rate_limits.fetch(config[:name])
+      else
+        key_base = config[:key_proc].call(@context.inputs)
+        limits = config[:limits]
+      end
+
+      RubyReactor::RateLimit.new(key_base, limits: limits).check_and_increment!
+    end
+
+    # True when nothing has run yet for this context — the very first execution
+    # of the reactor, including an async reactor's first worker pass. A genuine
+    # resume (paused, async-handed-off, or retried step) always records a
+    # `current_step` before serializing, so it is never mistaken for a first run.
+    def first_execution?
+      @context.current_step.nil? && @context.intermediate_results.empty?
+    end
+
+    # Record and persist a Skipped result, then return it. Shared by the
+    # pre-lock and post-lock period gates in both execute and resume.
+    def finalize_skipped(skipped)
+      @result = skipped
+      update_context_status(@result)
+      save_context
+      @result
     end
 
     # Returns a Skipped result if the period bucket is already marked, else nil.
-    # Only consulted on initial `execute`; resumes never re-check (a paused run
-    # must not skip itself when its own marker eventually appears).
+    # Consulted before AND after lock acquisition on a first execution; genuine
+    # resumes never re-check (a paused run must not skip itself when its own
+    # marker eventually appears).
     def check_period_gate
       return nil unless @reactor_class.respond_to?(:period_config) && @reactor_class.period_config
 

data/lib/ruby_reactor/rate_limit.rb

@@ -25,6 +25,34 @@ module RubyReactor
       end
     end
 
+    # Normalize the user-facing window args into the internal spec array that
+    # `RateLimit#initialize` expects. Shared by the reactor DSL (`with_rate_limit`)
+    # and the global registry (`config.rate_limits.register`).
+    #
+    # Accepts either a single window (`limit:` + `period:`) or a hash of windows
+    # (`limits:`). Returns Array<Hash{period_seconds:, limit:, name:}>.
+    def self.normalize_specs(limit: nil, period: nil, limits: nil)
+      if limits
+        raise ArgumentError, "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, "rate limit requires :limit + :period, or :limits"
+      end
+    end
+
     attr_reader :key_base, :limits
 
     # @param key_base [String] caller-provided key (e.g. "stripe:account_42")

data/lib/ruby_reactor/rate_limit_registry.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module RubyReactor
+  # Global registry of named rate limits, configured once via
+  # `RubyReactor.configure`. Lets multiple reactors share a single quota for an
+  # external service (e.g. all Stripe-calling reactors throttle against one
+  # `:stripe` bucket).
+  #
+  # @example
+  #   RubyReactor.configure do |config|
+  #     config.rate_limits.register(:stripe, limit: 3, period: :second)
+  #     config.rate_limits.register(:twilio, limits: { second: 10, minute: 100 })
+  #   end
+  #
+  #   class ChargeReactor < RubyReactor::Reactor
+  #     with_rate_limit(:stripe)
+  #   end
+  class RateLimitRegistry
+    # Raised when a reactor references a rate-limit name that was never
+    # registered. This is a configuration error, so it propagates out of
+    # `execute` rather than being swallowed into a step failure result.
+    class UnknownLimitError < StandardError; end
+
+    def initialize
+      @limits = {}
+    end
+
+    # Register a named rate limit. Same window args as the inline DSL form:
+    # a single window (`limit:` + `period:`) or layered windows (`limits:`).
+    def register(name, limit: nil, period: nil, limits: nil)
+      @limits[name.to_sym] = RubyReactor::RateLimit.normalize_specs(
+        limit: limit, period: period, limits: limits
+      )
+      self
+    end
+
+    # Return the normalized spec array for a registered name, or raise if the
+    # name was never registered (resolved lazily at execute time, so the error
+    # surfaces with a clear message instead of a nil dereference).
+    def fetch(name)
+      @limits.fetch(name.to_sym) do
+        raise UnknownLimitError, "Unknown rate limit #{name.inspect}. " \
+                                 "Register it with config.rate_limits.register(#{name.inspect}, ...)."
+      end
+    end
+
+    def registered?(name)
+      @limits.key?(name.to_sym)
+    end
+  end
+end

data/lib/ruby_reactor/sidekiq_workers/worker.rb

@@ -60,6 +60,10 @@ module RubyReactor
           # budget or appear as an error in dashboards. After the configured
           # cap is reached we escalate by marking the reactor as failed.
           handle_snooze(serialized_context, reactor_class_name, context, snooze_count, e)
+        rescue RubyReactor::RateLimitRegistry::UnknownLimitError => e
+          # Permanent configuration error — snoozing or retrying the same job
+          # will keep failing. Mark the context failed immediately.
+          escalate_snooze(context, snooze_count, e)
         end
       end
 

data/lib/ruby_reactor/validation/base.rb

@@ -19,7 +19,10 @@ module RubyReactor
 
       def failure(errors)
         error = RubyReactor::Error::InputValidationError.new(errors)
-        RubyReactor.Failure(error)
+        # Carry the structured field errors on the Failure itself so every
+        # validation failure shape (reactor inputs via `run`, step args, step
+        # output) exposes `validation_errors` uniformly.
+        RubyReactor.Failure(error, validation_errors: errors)
       end
     end
   end

data/lib/ruby_reactor/validation/input_validator.rb

@@ -5,14 +5,16 @@ require "dry-validation"
 module RubyReactor
   module Validation
     class InputValidator < Base
-      attr_reader :schema
+      attr_reader :schema, :wrap_key
 
-      def initialize(schema)
+      def initialize(schema, wrap_key: nil)
         super()
         @schema = schema
+        @wrap_key = wrap_key
       end
 
       def call(data)
+        data = { @wrap_key => data } if @wrap_key
         result = schema.call(data)
 
         if result.success?

data/lib/ruby_reactor/validation/schema_builder.rb

@@ -12,6 +12,88 @@ module RubyReactor
       def self.build_contract_from_block(&block)
         Class.new(Dry::Validation::Contract, &block).new
       end
+
+      # Form 1 / 1b — a single named value with an optional type and predicates.
+      #
+      #   build_inline(:age, :integer, false, { gteq?: 18 })
+      #     => required(:age).filled(:integer, gteq?: 18)
+      #   build_inline(:user, User, false, {})
+      #     => required(:user).filled(type?: User)
+      #   build_inline(:bio, :string, true, { max_size?: 100 })
+      #     => optional(:bio).maybe(:string, max_size?: 100)
+      def self.build_inline(name, type, optional, predicates)
+        rules = [[name, type, optional, predicates]]
+        Dry::Schema.Params do
+          SchemaBuilder.apply_inline_rules(self, rules)
+        end
+      end
+
+      # Form 2 — the block receives the macro already bound to the name and
+      # optionality (`required(name)` / `optional(name)`). Because it is invoked
+      # as a block argument (not via instance_eval) the caller's `self` and
+      # lexical scope (class constants, helper methods) stay reachable.
+      def self.build_macro(name, optional, &block)
+        macro_method = optional ? :optional : :required
+        Dry::Schema.Params do
+          block.call(public_send(macro_method, name))
+        end
+      end
+
+      # Compose per-argument inline rules with an optional `validate_args`
+      # input (block or pre-built schema). Block/inline rules are applied first;
+      # a pre-built schema is merged last so its rules win.
+      def self.build_args(inline_rules, validate_input)
+        block = validate_input.is_a?(Proc) ? validate_input : nil
+        prebuilt = !validate_input.nil? && block.nil? ? schema_for(validate_input) : nil
+
+        composed = build_args_base(inline_rules, block)
+
+        if prebuilt && composed
+          composed.merge(prebuilt)
+        elsif prebuilt
+          prebuilt
+        else
+          composed
+        end
+      end
+
+      def self.build_args_base(inline_rules, block)
+        return Dry::Schema.Params(&block) if inline_rules.empty? && block
+        return nil if inline_rules.empty?
+
+        Dry::Schema.Params do
+          SchemaBuilder.apply_inline_rules(self, inline_rules)
+          instance_exec(&block) if block
+        end
+      end
+
+      # Apply a list of inline rules ([name, type, optional, predicates]) onto a
+      # dry-schema DSL context.
+      def self.apply_inline_rules(dsl, rules)
+        rules.each do |name, type, optional, predicates|
+          macro_method = optional ? :optional : :required
+          rule_method  = optional ? :maybe : :filled
+          positional   = type.is_a?(Symbol) ? [type] : []
+          kwargs       = type.is_a?(Module) ? { type?: type, **predicates } : predicates
+
+          macro = dsl.public_send(macro_method, name)
+          if kwargs.empty?
+            macro.public_send(rule_method, *positional)
+          else
+            macro.public_send(rule_method, *positional, **kwargs)
+          end
+        end
+      end
+
+      # Unwrap an InputValidator into its underlying dry-schema; pass dry-schemas
+      # through unchanged.
+      def self.schema_for(schema_or_validator)
+        if schema_or_validator.is_a?(RubyReactor::Validation::InputValidator)
+          schema_or_validator.schema
+        else
+          schema_or_validator
+        end
+      end
     end
   end
 end

data/lib/ruby_reactor/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module RubyReactor
-  VERSION = "0.5.0"
+  VERSION = "0.5.1"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ruby_reactor
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.5.1
 platform: ruby
 authors:
 - Artur
@@ -141,6 +141,7 @@ files:
 - lib/ruby_reactor/open_telemetry.rb
 - lib/ruby_reactor/period.rb
 - lib/ruby_reactor/rate_limit.rb
+- lib/ruby_reactor/rate_limit_registry.rb
 - lib/ruby_reactor/reactor.rb
 - lib/ruby_reactor/registry.rb
 - lib/ruby_reactor/retry_context.rb