ruby_reactor 0.7.1 → 0.8.0

data/lib/ruby_reactor/dsl/step_builder.rb

@@ -25,17 +25,38 @@ module RubyReactor
         @args_validator = nil
         @output_validator = nil
         @retry_config = {}
+        @inline_contract = nil
+        @rule_sites = []
+      end
+
+      # Deprecation notices print once per declaration site for the process.
+      def self.deprecation_sites
+        @deprecation_sites ||= Set.new
       end
 
       def argument(name, source, type = nil, transform: nil, **predicates)
         @arguments[name] = {
           source: source,
-          transform: transform
+          transform: transform,
+          origin: :explicit
         }
 
         return unless type || predicates.any?
 
         @arg_validations << [name, type, false, predicates]
+        @rule_sites << [name, caller_locations(1, 1).first]
+      end
+
+      # An inline step's input contract. Inside the block `input` declares, as
+      # in a step class; outside it `input(:x)` stays the template reference.
+      def inputs(&block)
+        if @impl
+          raise Error::ValidationError,
+                "step :#{@name}: `inputs` is for inline steps; declare `input` inside #{@impl} instead."
+        end
+
+        @inline_contract ||= RubyReactor::Step::InputContract.new(owner: @name)
+        @inline_contract.instance_eval(&block)
       end
 
       def run(&block)
@@ -67,6 +88,7 @@ module RubyReactor
       # pre-built schema) is applied last and wins on conflicts.
       def validate_args(schema_or_validator = nil, &block)
         @validate_args_input = block || schema_or_validator
+        @validate_args_site = caller_locations(1, 1).first
       end
 
       # Scalar-aware output validation.
@@ -114,6 +136,9 @@ module RubyReactor
       # unit rather than run inline — `:step` for `async_step`, `:reactor` for
       # `async_reactor`. Nil for an ordinary step.
       def build(async_dispatch: nil)
+        check_contract_conflicts!
+        warn_deprecated_rules
+
         step_config = {
           async_dispatch: async_dispatch,
           name: @name,
@@ -127,16 +152,78 @@ module RubyReactor
           dependencies: @dependencies,
           args_validator: @args_validator || build_args_validator(@arg_validations, @validate_args_input),
           output_validator: @output_validator,
+          inline_contract: @inline_contract,
           retry_config: @retry_config.empty? ? (@reactor&.retry_defaults || {}) : @retry_config
         }
 
         RubyReactor::Dsl::StepConfig.new(step_config)
       end
+
+      private
+
+      # A step that owns its input contract takes wiring only from the
+      # reactor: rules here would be a second, overlapping rule set.
+      def check_contract_conflicts!
+        contract = owned_contract
+        return unless contract
+
+        owner = @impl || "its `inputs do ... end` block"
+        if (arg = @arg_validations.first&.first)
+          raise Error::ValidationError,
+                "#{reactor_label} step :#{@name} declares rules on argument :#{arg}, but #{owner} owns its input " \
+                "contract. Move the rule into #{owner} (`input :#{arg}, ...`) and keep only the wiring here: " \
+                "`argument :#{arg}, <source>`."
+        end
+        if @validate_args_input
+          raise Error::ValidationError,
+                "#{reactor_label} step :#{@name} declares `validate_args`, but #{owner} owns its input contract. " \
+                "Move the rule into #{owner} (`validate_inputs ...`) and keep only the wiring here."
+        end
+
+        unknown = @arguments.keys.find { |name| !contract.declares?(name) }
+        return unless unknown
+
+        raise Error::ValidationError,
+              "#{reactor_label} step :#{@name} wires argument :#{unknown}, which #{owner} does not declare. " \
+              "Declared inputs: #{contract.declarations.keys.join(", ")}."
+      end
+
+      # Rules on `argument` / `validate_args` still work for a step without a
+      # contract; they now belong on the step itself.
+      def warn_deprecated_rules
+        target = @impl || "an `inputs do ... end` block"
+        @rule_sites.each do |arg, site|
+          warn_deprecation(site, "step :#{@name} declares rules on `argument :#{arg}`. Declare them on the step " \
+                                 "instead (`input :#{arg}, ...` in #{target}) and keep `argument :#{arg}, <source>` " \
+                                 "for wiring.")
+        end
+        return unless @validate_args_site
+
+        warn_deprecation(@validate_args_site, "step :#{@name} declares rules with `validate_args`. Declare them on " \
+                                              "the step instead (`validate_inputs` in #{target}).")
+      end
+
+      def warn_deprecation(site, message)
+        location = "#{site.path}:#{site.lineno}"
+        return unless StepBuilder.deprecation_sites.add?(location)
+
+        warn "[RubyReactor] DEPRECATION: #{location} #{reactor_label} #{message} " \
+             "Removal no earlier than the next MAJOR."
+      end
+
+      def owned_contract
+        @inline_contract || (@impl.input_contract if @impl.respond_to?(:declares_inputs?) && @impl.declares_inputs?)
+      end
+
+      def reactor_label
+        @reactor&.name || @reactor.inspect
+      end
     end
 
     class StepConfig
       attr_reader :name, :impl, :arguments, :run_block, :compensate_block, :undo_block, :conditions, :guards,
-                  :dependencies, :args_validator, :output_validator, :retry_config, :async_dispatch
+                  :dependencies, :args_validator, :output_validator, :retry_config, :async_dispatch,
+                  :inline_contract
 
       def initialize(config)
         @async_dispatch = config[:async_dispatch]
@@ -151,6 +238,7 @@ module RubyReactor
         @dependencies = config[:dependencies] || []
         @args_validator = config[:args_validator]
         @output_validator = config[:output_validator]
+        @inline_contract = config[:inline_contract]
         @retry_config = { max_attempts: 1 }.merge(config[:retry_config] || {})
       end
 
@@ -165,6 +253,11 @@ module RubyReactor
         !@impl.nil?
       end
 
+      # The contract that governs this step's inputs, or nil when it has none.
+      def input_contract
+        @inline_contract || (@impl.input_contract if @impl.respond_to?(:declares_inputs?) && @impl.declares_inputs?)
+      end
+
       def has_run_block?
         !@run_block.nil?
       end

data/lib/ruby_reactor/dsl/template_helpers.rb

@@ -29,9 +29,9 @@ module RubyReactor
       end
 
       # rubocop:disable Naming/MethodName
-      def Failure(error)
+      def Failure(...)
         # rubocop:enable Naming/MethodName
-        RubyReactor.Failure(error)
+        RubyReactor.Failure(...)
       end
 
       # rubocop:disable Naming/MethodName

data/lib/ruby_reactor/dsl/validation_helpers.rb

@@ -36,6 +36,23 @@ module RubyReactor
         RubyReactor::Validation::InputValidator.new(schema)
       end
 
+      # Dispatch across the layered `input` forms, shared by reactor inputs and
+      # step input contracts:
+      #   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_declaration_validator(name, type, optional, validate, predicates, &block)
+        if validate
+          create_input_validator(validate)
+        elsif block
+          block.arity.nonzero? ? build_macro_validator(name, optional, &block) : create_input_validator(block)
+        elsif type || predicates.any?
+          build_inline_validator(name, type, optional, predicates)
+        end
+      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)

data/lib/ruby_reactor/error/input_validation_error.rb

@@ -28,6 +28,10 @@ module RubyReactor
       def to_s
         @message || build_message
       end
+
+      def retryable?
+        false
+      end
     end
   end
 end

data/lib/ruby_reactor/error/step_failure_error.rb

@@ -3,18 +3,25 @@
 module RubyReactor
   module Error
     class StepFailureError < Base
-      attr_reader :step_arguments, :exception_class
+      attr_reader :step_arguments, :exception_class, :validation_errors
 
       # rubocop:disable Metrics/ParameterLists
-      def initialize(message, step: nil, context: nil, original_error: nil, step_arguments: {}, exception_class: nil)
+      def initialize(message, step: nil, context: nil, original_error: nil, step_arguments: {}, exception_class: nil,
+                     validation_errors: nil)
         # rubocop:enable Metrics/ParameterLists
         super(message, step: step, context: context, original_error: original_error)
         @step_arguments = step_arguments
         @exception_class = exception_class
+        @validation_errors = validation_errors
       end
 
+      # Defers to the original error when it has an opinion (e.g. a step's own
+      # `Error::InputValidationError`, always non-retryable) so that opinion
+      # survives being wrapped into a StepFailureError — the same
+      # `respond_to?(:retryable?)` protocol `RubyReactor::Failure` itself uses.
+      # Defaults to `true` for an ordinary step failure, unchanged from before.
       def retryable?
-        true
+        original_error.respond_to?(:retryable?) ? original_error.retryable? : true
       end
     end
   end

data/lib/ruby_reactor/executor/result_handler.rb

@@ -143,7 +143,8 @@ module RubyReactor
         orig_err = result.original_error.is_a?(Exception) ? result.original_error : nil
         error = Error::StepFailureError.new(result.error, step: step_config.name, context: @context,
                                                           original_error: orig_err,
-                                                          step_arguments: resolved_arguments)
+                                                          step_arguments: resolved_arguments,
+                                                          validation_errors: result.validation_errors)
         if result.respond_to?(:backtrace) && result.backtrace
           error.set_backtrace(result.backtrace)
         elsif orig_err
@@ -155,9 +156,12 @@ module RubyReactor
       def handle_failure(step_config, result, resolved_arguments)
         failure_result = @compensation_manager.handle_step_failure(step_config, result.error, resolved_arguments)
         orig_err = result.error.is_a?(Exception) ? result.error : nil
+        # A step that propagates another unit's validation failure (an
+        # async_step reader) keeps its field errors on the reactor's failure.
         error = Error::StepFailureError.new(failure_result.error, step: step_config.name, context: @context,
                                                                   original_error: orig_err,
-                                                                  step_arguments: resolved_arguments)
+                                                                  step_arguments: resolved_arguments,
+                                                                  validation_errors: result.validation_errors)
         if result.respond_to?(:backtrace) && result.backtrace
           error.set_backtrace(result.backtrace)
         elsif orig_err
@@ -222,7 +226,9 @@ module RubyReactor
           exception_class: exception_class,
           file_path: file_path,
           line_number: line_number,
-          code_snippet: code_snippet
+          code_snippet: code_snippet,
+          validation_errors: error.validation_errors,
+          retryable: error.retryable?
         )
       end
 

data/lib/ruby_reactor/executor/retry_manager.rb

@@ -185,7 +185,8 @@ module RubyReactor
                            []
                          end,
           reactor_name: reactor_class.name,
-          step_arguments: result.respond_to?(:step_arguments) ? result.step_arguments : {}
+          step_arguments: result.respond_to?(:step_arguments) ? result.step_arguments : {},
+          validation_errors: result.validation_errors
         )
       end
 

data/lib/ruby_reactor/executor/step_executor.rb

@@ -183,9 +183,13 @@ 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
+      rescue Error::InputValidationError => e
         # Validation failures are not retryable and must surface as a structured
         # InputValidationError (with field_errors), so let them propagate.
+        # A step class stamps its own class name; inside a reactor the step's
+        # name there is the useful attribution, so it overwrites.
+        e.step_name = step_config.name
+        e.step_arguments ||= resolved_arguments
         raise
       rescue StandardError => e
         # Identify redacted inputs
@@ -340,13 +344,16 @@ module RubyReactor
       end
 
       def run_step_implementation(step_config, arguments)
+        contract = step_config.input_contract
         @context.append_execution_trace(
-          { type: :run, step: step_config.name, timestamp: Time.now, arguments: arguments }
+          { type: :run, step: step_config.name, timestamp: Time.now,
+            arguments: contract ? contract.redact(arguments) : arguments }
         )
         if step_config.has_run_block?
           # Execute inline block
           # If no arguments are defined for the step, pass the reactor inputs as arguments
           args_to_pass = arguments.empty? ? @context.inputs : arguments
+          args_to_pass = step_config.inline_contract.enforce!(args_to_pass) if step_config.inline_contract
           catch(StepSignals::TAG) { step_config.run_block.call(args_to_pass, @context) }
         elsif step_config.has_impl?
           # Execute step class

data/lib/ruby_reactor/executor.rb

@@ -19,6 +19,9 @@ module RubyReactor
                 :step_executor, :result, :middlewares
 
     def initialize(reactor_class, inputs = {}, context = nil)
+      # Resume, map, compose and background workers build an Executor without
+      # going through Reactor#run; the inferred wiring must exist there too.
+      reactor_class.validate_definition! if reactor_class.respond_to?(:validate_definition!)
       @reactor_class = reactor_class
       @context = context || Context.new(inputs, reactor_class)
       @middlewares = Executor.middlewares_for(reactor_class)

data/lib/ruby_reactor/max_retries_exhausted_failure.rb

@@ -7,11 +7,12 @@ module RubyReactor
     # rubocop:disable Metrics/ParameterLists
     def initialize(message, step:, attempts:, original_error: nil,
                    inputs: {}, backtrace: nil, redact_inputs: [],
-                   reactor_name: nil, step_arguments: {})
+                   reactor_name: nil, step_arguments: {}, validation_errors: nil)
       # rubocop:enable Metrics/ParameterLists
       super(message,
             step_name: step, inputs: inputs, backtrace: backtrace,
-            redact_inputs: redact_inputs, reactor_name: reactor_name, step_arguments: step_arguments)
+            redact_inputs: redact_inputs, reactor_name: reactor_name, step_arguments: step_arguments,
+            validation_errors: validation_errors)
       @attempts = attempts
       @original_error = original_error
     end

data/lib/ruby_reactor/reactor.rb

@@ -84,21 +84,17 @@ module RubyReactor
       end
     end
 
-    # rubocop:disable Metrics/MethodLength
     def run(inputs = {})
+      # Before the context exists, so an incomplete definition never saves one.
+      self.class.validate_definition!
+
       # For all reactors, initialize context first to capture execution ID
       @context = @context.is_a?(Context) ? @context : Context.new(inputs, self.class)
 
       # Validate inputs
       validation_result = self.class.validate_inputs(inputs)
       if validation_result.failure?
-        @result = validation_result
-        @context.status = "failed"
-        @context.failure_reason = {
-          message: validation_result.error.message,
-          validation_errors: validation_result.error.field_errors
-        }
-        save_context
+        handle_validation_failure(validation_result)
         return validation_result
       end
 
@@ -144,7 +140,6 @@ module RubyReactor
       end
       @result
     end
-    # rubocop:enable Metrics/MethodLength, Metrics/AbcSize
 
     def continue(payload:, step_name:, idempotency_key: nil)
       _ = idempotency_key
@@ -270,8 +265,9 @@ module RubyReactor
       reason = @context.failure_reason || {}
       return reason if reason.is_a?(RubyReactor::Failure)
 
-      # Use string keys preferred, fallback to symbol
-      r = ->(k) { reason[k.to_s] || reason[k.to_sym] }
+      # Presence-aware: a stored `retryable: false` must not be swallowed by an
+      # `||` fallback and silently default back to retryable.
+      r = ->(k) { Utils::FetchIndifferent.call(reason, k) }
 
       Failure.new(
         r[:message],
@@ -314,7 +310,8 @@ module RubyReactor
       @context.status = "failed"
       @context.failure_reason = {
         message: result.error.message,
-        validation_errors: result.error.field_errors
+        validation_errors: result.error.field_errors,
+        retryable: result.retryable?
       }
       save_context
     end

data/lib/ruby_reactor/rspec/matchers.rb

@@ -156,12 +156,9 @@ module RubyReactor
           subject.ensure_executed!
           return false unless subject.failure?
 
-          # Try to get validation errors from failure reason
-          reason = subject.reactor_instance.context.failure_reason || {}
-
-          # If failure is InputValidationError, it might be serialized differently
-          # Or stored in validation_errors key
-          errors = reason["validation_errors"] || reason[:validation_errors]
+          # `result` normalizes both failure shapes — a reactor-input failure
+          # stored as a hash, and a step failure stored as a Failure.
+          errors = subject.result.validation_errors
 
           if errors
             errors.key?(field.to_s) || errors.key?(field.to_sym)