ruby_reactor 0.8.3 → 0.8.4

data/lib/ruby_reactor/dsl/retryable.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module RubyReactor
+  module Dsl
+    # The one `retries` vocabulary. A step class EXTENDS it (class-level DSL);
+    # the step, compose and async_reactor builders INCLUDE it, so every form
+    # shares the same defaults and validation. Modeled on
+    # `Lockable::ClassMethods`: `inherited` copies the declaration down, so a
+    # subclass redeclaring leaves its parent and siblings untouched.
+    module Retryable
+      BACKOFF_STRATEGIES = %i[exponential linear fixed].freeze
+
+      # The declared policy, or nil when nothing was declared.
+      attr_reader :retry_config
+
+      def retries(max_attempts: 3, backoff: :exponential, base_delay: 1)
+        unless max_attempts.is_a?(Integer) && max_attempts >= 1
+          invalid_retries!(:max_attempts, "an Integer >= 1", max_attempts)
+        end
+        invalid_retries!(:backoff, "one of #{BACKOFF_STRATEGIES.inspect}", backoff) unless
+          BACKOFF_STRATEGIES.include?(backoff)
+        invalid_retries!(:base_delay, "a Numeric >= 0", base_delay) unless
+          base_delay.is_a?(Numeric) && base_delay >= 0
+
+        @retry_config = { max_attempts: max_attempts, backoff: backoff, base_delay: base_delay }
+      end
+
+      def inherited(subclass)
+        super
+        subclass.instance_variable_set(:@retry_config, @retry_config) if @retry_config
+      end
+
+      private
+
+      def invalid_retries!(option, expected, value)
+        raise ArgumentError, "#{retry_owner_label}: retries #{option} must be #{expected} (got #{value.inspect})"
+      end
+
+      # A step class's name, or a builder's step name.
+      def retry_owner_label
+        name&.to_s || inspect
+      end
+    end
+  end
+end

data/lib/ruby_reactor/dsl/step_builder.rb

@@ -6,6 +6,7 @@ module RubyReactor
       include RubyReactor::Dsl::TemplateHelpers
       include RubyReactor::Dsl::ValidationHelpers
       include RubyReactor::Dsl::Lockable::ClassMethods
+      include RubyReactor::Dsl::Retryable
 
       COORDINATION_MACROS = {
         lock_config: "with_lock", semaphore_config: "with_semaphore", rate_limit_config: "with_rate_limit",
@@ -13,7 +14,7 @@ module RubyReactor
       }.freeze
 
       attr_accessor :name, :impl, :arguments, :run_block, :compensate_block, :undo_block, :conditions, :guards,
-                    :dependencies, :args_validator, :output_validator, :retry_config
+                    :dependencies, :args_validator, :output_validator
 
       def initialize(name, impl = nil, reactor = nil)
         @name = name
@@ -30,7 +31,7 @@ module RubyReactor
         @validate_args_input = nil
         @args_validator = nil
         @output_validator = nil
-        @retry_config = {}
+        @retry_config = nil
         @inline_contract = nil
         @rule_sites = []
       end
@@ -130,20 +131,13 @@ module RubyReactor
         )
       end
 
-      def retries(max_attempts: 3, backoff: :exponential, base_delay: 1)
-        @retry_config = {
-          max_attempts: max_attempts,
-          backoff: backoff,
-          base_delay: base_delay
-        }
-      end
-
       # `async_dispatch` marks a step whose work is dispatched as an independent
       # 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!
         check_coordination_conflicts!
+        check_retry_conflict!
         warn_deprecated_rules
 
         step_config = {
@@ -160,7 +154,7 @@ module RubyReactor
           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,
+          retry_config: @retry_config,
           lock_config: @lock_config,
           semaphore_config: @semaphore_config,
           rate_limit_config: @rate_limit_config,
@@ -190,6 +184,16 @@ module RubyReactor
         end
       end
 
+      # Same rule as the coordination macros: one retry policy per step.
+      def check_retry_conflict!
+        return unless @retry_config && @impl.respond_to?(:retry_config) && @impl.retry_config
+
+        raise Error::ValidationError,
+              "#{reactor_label} step :#{@name} declares `retries` inline, but #{@impl} declares it too. " \
+              "Keep ONE: drop the inline declaration to use #{@impl}'s, or remove it from #{@impl}. " \
+              "To vary the policy per workflow, subclass #{@impl} and declare `retries` there."
+      end
+
       # 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!
@@ -250,8 +254,10 @@ module RubyReactor
     end
 
     class StepConfig
+      NO_RETRIES = { max_attempts: 1, backoff: :exponential, base_delay: 1 }.freeze
+
       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, :async_dispatch,
                   :inline_contract
 
       def initialize(config)
@@ -268,7 +274,7 @@ module RubyReactor
         @args_validator = config[:args_validator]
         @output_validator = config[:output_validator]
         @inline_contract = config[:inline_contract]
-        @retry_config = { max_attempts: 1 }.merge(config[:retry_config] || {})
+        @retry_config = config[:retry_config]
         @lock_config = config[:lock_config]
         @semaphore_config = config[:semaphore_config]
         @rate_limit_config = config[:rate_limit_config]
@@ -287,6 +293,21 @@ module RubyReactor
         @lock_config || (impl.lock_config if impl.respond_to?(:lock_config))
       end
 
+      # A step's EFFECTIVE retry policy, resolved like the coordination
+      # readers: its own (step block) declaration, else the class step's,
+      # else a single attempt. Never nil. The reactor is never consulted.
+      def retry_config
+        @retry_config || (impl.retry_config if impl.respond_to?(:retry_config)) || NO_RETRIES
+      end
+
+      # Where `retry_config` came from: :step_block, :step_class or :none.
+      def retry_source
+        return :step_block if @retry_config
+        return :step_class if impl.respond_to?(:retry_config) && impl.retry_config
+
+        :none
+      end
+
       def semaphore_config
         @semaphore_config || (impl.semaphore_config if impl.respond_to?(:semaphore_config))
       end
@@ -343,7 +364,7 @@ module RubyReactor
       def call_body(arguments, context)
         catch(StepSignals::TAG) do
           if has_run_block?
-            run_block.call(arguments, context)
+            run_block.call(wrap_inputs(arguments), context)
           elsif impl.respond_to?(:run_without_coordination)
             impl.run_without_coordination(arguments, context)
           else
@@ -373,6 +394,11 @@ module RubyReactor
         !@run_block.nil?
       end
 
+      # What an inline `run`/`undo`/`compensate` block receives as its inputs.
+      def wrap_inputs(arguments)
+        RubyReactor::Step::Inputs.new(arguments, contract: input_contract, owner: "step :#{name}")
+      end
+
       def retryable?
         (retry_config[:max_attempts] || 0) > 1
       end

data/lib/ruby_reactor/error/undeclared_input_error.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module RubyReactor
+  module Error
+    # A step read an input it can't read (a typo, or a name it never
+    # declared). It fails the same way on every attempt, so it never retries.
+    class UndeclaredInputError < NoMethodError
+      def retryable?
+        false
+      end
+    end
+  end
+end

data/lib/ruby_reactor/executor/compensation_manager.rb

@@ -123,7 +123,7 @@ module RubyReactor
           compensate_result = coordinated_rollback(step_config, arguments) do
             catch(StepSignals::TAG) do
               if step_config.compensate_block
-                step_config.compensate_block.call(error, arguments, @context)
+                step_config.compensate_block.call(error, step_config.wrap_inputs(arguments), @context)
               elsif step_config.has_impl?
                 step_config.impl.compensate(error, arguments, @context)
               else
@@ -168,7 +168,7 @@ module RubyReactor
           undo_result = coordinated_rollback(step_config, arguments) do
             catch(StepSignals::TAG) do
               if step_config.undo_block
-                step_config.undo_block.call(result.value, arguments, @context)
+                step_config.undo_block.call(result.value, step_config.wrap_inputs(arguments), @context)
               elsif step_config.has_impl?
                 step_config.impl.undo(result.value, arguments, @context)
               else

data/lib/ruby_reactor/executor/result_handler.rb

@@ -188,13 +188,14 @@ module RubyReactor
         raise error
       end
 
+      # Wrapped first, so a returned `Step::Inputs` is validated and stored as its Hash.
       def handle_unknown_result(step_config, result, resolved_arguments)
-        validate_step_output(step_config, result, resolved_arguments)
         success_result = RubyReactor.Success(result)
+        validate_step_output(step_config, success_result.value, resolved_arguments)
         @step_results[step_config.name] = success_result
         @compensation_manager.add_to_undo_stack({ step: step_config, arguments: resolved_arguments,
                                                   result: success_result })
-        @context.set_result(step_config.name, result)
+        @context.set_result(step_config.name, success_result.value)
         @dependency_graph.complete_step(step_config.name)
       end
 

data/lib/ruby_reactor/executor/retry_manager.rb

@@ -24,19 +24,18 @@ module RubyReactor
                                                                          step_config.retry_config[:max_attempts])
       end
 
-      def calculate_backoff_delay(step_config, _error, reactor_class)
+      def calculate_backoff_delay(step_config)
         attempt_number = @context.retry_context.attempts_for_step(step_config.name)
-        backoff_strategy = step_config.retry_config[:backoff] || reactor_class.retry_defaults[:backoff]
-        base_delay = step_config.retry_config[:base_delay] || reactor_class.retry_defaults[:base_delay]
+        retry_config = step_config.retry_config
 
-        delay = RetryContext.calculate_backoff_delay(attempt_number, backoff_strategy, base_delay)
+        delay = RetryContext.calculate_backoff_delay(attempt_number, retry_config[:backoff], retry_config[:base_delay])
         @context.retry_context.next_retry_at = Time.now + delay
         delay
       end
 
-      def requeue_job_for_step_retry(step_config, error, reactor_class)
+      def requeue_job_for_step_retry(step_config)
         @context.current_step = step_config.name
-        delay = calculate_backoff_delay(step_config, error, reactor_class)
+        delay = calculate_backoff_delay(step_config)
 
         requeue_job(step_config, delay)
       end
@@ -147,14 +146,14 @@ module RubyReactor
 
         # Always try async retry if configured
         if is_async
-          handle_async_retry(step_config, reactor_class, result)
+          handle_async_retry(step_config)
         else
-          handle_sync_retry(step_config, reactor_class, result)
+          handle_sync_retry(step_config)
         end
       end
 
-      def handle_async_retry(step_config, reactor_class, result)
-        requeue_result = requeue_job_for_step_retry(step_config, result.error, reactor_class)
+      def handle_async_retry(step_config)
+        requeue_result = requeue_job_for_step_retry(step_config)
 
         # If it returned an DispatchResult, we are truly async.
         # Otherwise, it ran inline and we should return the result of that execution.
@@ -169,8 +168,8 @@ module RubyReactor
         end
       end
 
-      def handle_sync_retry(step_config, reactor_class, result)
-        delay = calculate_backoff_delay(step_config, result.error, reactor_class)
+      def handle_sync_retry(step_config)
+        delay = calculate_backoff_delay(step_config)
         sleep(delay)
         nil # continue loop
       end

data/lib/ruby_reactor/rspec/test_subject.rb

@@ -556,7 +556,6 @@ module RubyReactor
           @middlewares = superclass.middlewares.dup
           @return_step = superclass.return_step
           @background_handoff = superclass.background_handoff
-          @retry_defaults = superclass.instance_variable_get(:@retry_defaults)
 
           # 2. Add Name Handling with Unique Registry Entry
           # We must register a unique name so that if this reactor is reloaded (e.g. after async child completion),
@@ -648,7 +647,6 @@ module RubyReactor
           @middlewares = superclass.middlewares.dup
           @return_step = superclass.return_step
           @background_handoff = superclass.background_handoff
-          @retry_defaults = superclass.instance_variable_get(:@retry_defaults)
         end
 
         strip_background_and_async!(child_class)
@@ -736,7 +734,6 @@ module RubyReactor
           @middlewares = superclass.middlewares.dup
           @return_step = superclass.return_step
           @background_handoff = superclass.background_handoff
-          @retry_defaults = superclass.instance_variable_get(:@retry_defaults)
         end
 
         # Recursively apply interceptors to the child reactor
@@ -765,14 +762,15 @@ module RubyReactor
       # callable a mock block can invoke.
       def original_impl_for(step_config_orig, target_step)
         if step_config_orig.has_run_block?
-          step_config_orig.run_block
+          # A mock may hand `original` a plain Hash (`args.to_h.merge(...)`).
+          ->(args, ctx) { step_config_orig.run_block.call(step_config_orig.wrap_inputs(args), ctx) }
         elsif step_config_orig.has_impl?
           impl = step_config_orig.impl
 
           if impl.respond_to?(:run_without_coordination)
             ->(args, ctx) { impl.run_without_coordination(args, ctx) }
           else
-            ->(args, ctx) { impl.run(args, ctx) }
+            ->(args, ctx) { impl.run(args.to_h, ctx) }
           end
         else
           ->(_, _) { raise "No implementation found for #{target_step}" }

data/lib/ruby_reactor/step/async_reactor_step.rb

@@ -15,6 +15,10 @@ module RubyReactor
     # ordered-lock nonce at ENQUEUE time (so ordering matches caller order), and
     # persist before enqueueing (F2).
     class AsyncReactorStep < RubyReactor::Step
+      # Untyped, so no validation: declared only so `inputs.x` can read them.
+      input :async_reactor_class
+      input :argument_mappings, optional: true
+
       class << self
         # Exclusive keys this EXECUTION currently holds, read from the root
         # context's registry. Shared by the `async_reactor` dispatch check
@@ -54,8 +58,8 @@ module RubyReactor
       end
 
       def run
-        child_class = inputs[:async_reactor_class]
-        child_inputs = build_child_inputs(inputs[:argument_mappings] || {})
+        child_class = inputs.async_reactor_class
+        child_inputs = build_child_inputs(inputs.argument_mappings || {})
 
         # A dispatch-time failure fails the DISPATCHING step, i.e. normal saga
         # handling in the parent. That is deliberately outside the

data/lib/ruby_reactor/step/compose_step.rb

@@ -3,6 +3,10 @@
 module RubyReactor
   class Step
     class ComposeStep < RubyReactor::Step
+      # Untyped, so no validation: declared only so `inputs.x` can read them.
+      input :composed_reactor_class
+      input :argument_mappings, optional: true
+
       def run
         step_name = context.current_step
         composed_data = context.composed_contexts[step_name]
@@ -12,7 +16,7 @@ module RubyReactor
         store_child_context(step_name, child_context)
 
         # Execute the composed reactor
-        result = execute_child_reactor(inputs[:composed_reactor_class], child_context, composed_data)
+        result = execute_child_reactor(inputs.composed_reactor_class, child_context, composed_data)
 
         # Update the stored context
         store_child_context(step_name, child_context)
@@ -30,7 +34,7 @@ module RubyReactor
         return RubyReactor.Success() unless composed_data && composed_data[:context]
 
         child_context = composed_data[:context]
-        executor = RubyReactor::Executor.new(inputs[:composed_reactor_class], {}, child_context)
+        executor = RubyReactor::Executor.new(inputs.composed_reactor_class, {}, child_context)
         executor.undo_all
         executor.save_context
 
@@ -59,8 +63,8 @@ module RubyReactor
         child_context = composed_data ? composed_data[:context] : nil
 
         unless child_context
-          composed_inputs = build_composed_inputs(inputs[:argument_mappings] || {})
-          child_context = RubyReactor::Context.new(composed_inputs, inputs[:composed_reactor_class])
+          composed_inputs = build_composed_inputs(inputs.argument_mappings || {})
+          child_context = RubyReactor::Context.new(composed_inputs, inputs.composed_reactor_class)
         end
 
         link_contexts(child_context, context)

data/lib/ruby_reactor/step/input_contract.rb

@@ -25,6 +25,11 @@ module RubyReactor
       def input(name, type = nil, optional: false, default: nil, redact: false, validate: nil, **predicates, &block)
         # rubocop:enable Metrics/ParameterLists
         check_dry_validation_available!
+        if Step::Inputs.public_method_defined?(name)
+          raise Error::ValidationError,
+                "input :#{name} is reserved: step code reads inputs as `inputs.#{name}`, and `#{name}` is already " \
+                "a method there. Rename the input."
+        end
         unless default.nil? || optional
           raise Error::ValidationError,
                 "input :#{name} declares `default:` but is required; a default only applies to an " \

data/lib/ruby_reactor/step/inputs.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module RubyReactor
+  class Step
+    # What step code (`run`, `undo`, `compensate`) receives as its inputs: a
+    # frozen, read-only view of the argument Hash with one reader per name the
+    # step may read. Any other name raises `Error::UndeclaredInputError` on the
+    # line that reads it, instead of returning nil and failing somewhere else.
+    #
+    #   inputs.order_guid      # the value, or nil for an absent optional input
+    #   inputs.order_id        # raises UndeclaredInputError
+    #   inputs.to_h            # supplied values, readable names only
+    #   Service.call(**inputs) # via `to_hash`
+    #
+    # Readable names are the contract's declarations, or the keys present when
+    # the step has none. Built only where inputs reach step code; everything
+    # else in the gem keeps the Hash.
+    class Inputs
+      def initialize(values, contract: nil, owner: nil)
+        @values = values.to_h
+        @owner = owner
+        declared = contract&.declarations&.keys || []
+        @names = declared.empty? ? @values.keys.map(&:to_sym).uniq : declared
+        @redacted = contract&.redacted_names || []
+        freeze
+      end
+
+      def to_h
+        @names.each_with_object({}) do |name, hash|
+          hash[name] = Utils::FetchIndifferent.call(@values, name) if supplied?(name)
+        end
+      end
+      alias to_hash to_h
+
+      def inspect
+        to_h.to_h { |name, value| [name, @redacted.include?(name) ? InputContract::REDACTED : value] }.inspect
+      end
+
+      private
+
+      def method_missing(name, *args)
+        return Utils::FetchIndifferent.call(@values, name) if args.empty? && @names.include?(name)
+
+        declared = @names.empty? ? "none" : @names.map(&:inspect).join(", ")
+        raise Error::UndeclaredInputError.new("#{@owner} has no input :#{name}. Declared inputs: #{declared}.", name)
+      end
+
+      def respond_to_missing?(name, include_private = false)
+        @names.include?(name) || super
+      end
+
+      def supplied?(name)
+        @values.key?(name) || @values.key?(name.to_s)
+      end
+    end
+  end
+end

data/lib/ruby_reactor/step/map_step.rb

@@ -3,8 +3,18 @@
 module RubyReactor
   class Step
     class MapStep < RubyReactor::Step
+      # Untyped, so no validation: declared only so `inputs.x` can read them.
+      input :source
+      input :mapped_reactor_class
+      input :argument_mappings, optional: true
+      input :strict_ordering, optional: true
+      input :batch_size, optional: true
+      input :collect_block, optional: true
+      input :fail_fast, optional: true
+      input :fan_out, optional: true
+
       def run
-        return RubyReactor::Failure("Map source cannot be nil") if inputs[:source].nil?
+        return RubyReactor::Failure("Map source cannot be nil") if inputs.source.nil?
 
         # Initialize map state in context if not present
         context.map_operations ||= {}
@@ -77,21 +87,21 @@ module RubyReactor
       def fan_out?
         return false if context.map_metadata || context.root_context&.map_metadata
 
-        inputs[:fan_out]
+        inputs.fan_out
       end
 
       def run_inline
         results = execute_inline_map
         return results if results.is_a?(RubyReactor::Failure) || results.is_a?(RubyReactor::Halt)
 
-        process_results(results, inputs[:collect_block], inputs[:fail_fast])
+        process_results(results, inputs.collect_block, inputs.fail_fast)
       end
 
       def execute_inline_map
         results = []
-        fail_fast = inputs[:fail_fast].nil? || inputs[:fail_fast]
+        fail_fast = inputs.fail_fast.nil? || inputs.fail_fast
 
-        inputs[:source].each_with_index do |element, index|
+        inputs.source.each_with_index do |element, index|
           result = execute_single_element(element, index)
 
           # An element-level Halt propagates as a run halt: stop immediately
@@ -110,8 +120,8 @@ module RubyReactor
       end
 
       def execute_single_element(element, index)
-        mapped_inputs = self.class.build_mapped_inputs(inputs[:argument_mappings] || {}, context, element)
-        child_context = RubyReactor::Context.new(mapped_inputs, inputs[:mapped_reactor_class])
+        mapped_inputs = self.class.build_mapped_inputs(inputs.argument_mappings || {}, context, element)
+        child_context = RubyReactor::Context.new(mapped_inputs, inputs.mapped_reactor_class)
 
         link_contexts(child_context, context)
 
@@ -131,10 +141,10 @@ module RubyReactor
           name: context.current_step,
           type: :map_ref,
           map_id: map_id,
-          element_reactor_class: inputs[:mapped_reactor_class].name
+          element_reactor_class: inputs.mapped_reactor_class.name
         }
 
-        executor = RubyReactor::Executor.new(inputs[:mapped_reactor_class], {}, child_context)
+        executor = RubyReactor::Executor.new(inputs.mapped_reactor_class, {}, child_context)
         executor.execute
         executor.result
       end
@@ -162,9 +172,9 @@ module RubyReactor
       def run_async(step_name)
         map_id = "#{context.context_id}:#{step_name}"
         context.map_operations[step_name.to_s] = map_id
-        prepare_async_execution(map_id, inputs[:source].size)
+        prepare_async_execution(map_id, inputs.source.size)
 
-        reactor_class_info = build_reactor_class_info(inputs[:mapped_reactor_class], step_name)
+        reactor_class_info = build_reactor_class_info(inputs.mapped_reactor_class, step_name)
 
         initialize_map_metadata(map_id, reactor_class_info)
 
@@ -175,7 +185,7 @@ module RubyReactor
           name: step_name.to_s,
           type: :map_ref,
           map_id: map_id,
-          element_reactor_class: inputs[:mapped_reactor_class].name
+          element_reactor_class: inputs.mapped_reactor_class.name
         }
 
         RubyReactor::DispatchResult.new(
@@ -188,9 +198,9 @@ module RubyReactor
       def initialize_map_metadata(map_id, reactor_class_info)
         storage = RubyReactor.configuration.storage_adapter
         storage.initialize_map_operation(
-          map_id, inputs[:source].size, context.reactor_class.name,
-          strict_ordering: inputs[:strict_ordering], reactor_class_info: reactor_class_info,
-          **map_recovery_metadata(inputs[:step_name] || context.current_step)
+          map_id, inputs.source.size, context.reactor_class.name,
+          strict_ordering: inputs.strict_ordering, reactor_class_info: reactor_class_info,
+          **map_recovery_metadata(context.current_step)
         )
       end
 
@@ -215,21 +225,21 @@ module RubyReactor
         # own worker, with the map counter/collector tracking completion. This
         # lets elements with async steps or async retries hand off correctly
         # instead of being forced to run synchronously in a single worker.
-        batch_size = inputs[:batch_size] || inputs[:source].size
+        batch_size = inputs.batch_size || inputs.source.size
 
         RubyReactor::Map::Dispatcher.perform(
           map_id: map_id,
           parent_context_id: context.context_id,
           parent_reactor_class_name: context.reactor_class.name,
-          source: inputs[:source],
+          source: inputs.source,
           batch_size: batch_size,
           step_name: step_name,
-          argument_mappings: inputs[:argument_mappings],
-          strict_ordering: inputs[:strict_ordering],
-          mapped_reactor_class: inputs[:mapped_reactor_class],
-          fail_fast: inputs[:fail_fast].nil? || inputs[:fail_fast]
+          argument_mappings: inputs.argument_mappings,
+          strict_ordering: inputs.strict_ordering,
+          mapped_reactor_class: inputs.mapped_reactor_class,
+          fail_fast: inputs.fail_fast.nil? || inputs.fail_fast
         )
-        queue_collector(map_id, step_name, inputs[:strict_ordering])
+        queue_collector(map_id, step_name, inputs.strict_ordering)
         "map:#{map_id}"
       end
 

data/lib/ruby_reactor/step.rb

@@ -5,13 +5,14 @@ module RubyReactor
   #
   #   class MyStep < RubyReactor::Step
   #     input :amount, :integer
-  #     def run = Success(charged: inputs[:amount])
+  #     def run = Success(charged: inputs.amount)
   #   end
   #
   # Lifecycle of every class-level call (`.run`/`.call`, `.undo`, `.compensate`):
   #
   # 1. Resolve `inputs`: the given arguments with the contract's defaults
-  #    applied. `run`, `undo`, and `compensate` all see the same values.
+  #    applied. `run`, `undo`, and `compensate` all see the same values,
+  #    through a read-only `Step::Inputs` (`inputs.amount`).
   # 2. `.run` ONLY: enforce the declared input contract, raising
   #    `Error::InputValidationError` before any instance exists.
   # 2b. `.run` ONLY: step-scoped coordination (`with_lock` etc, if declared)
@@ -30,17 +31,20 @@ module RubyReactor
   #    throw (`success!`/`skip!`/`fail!`/`halt!`) into its result wrapper.
   #
   # No `prepend`/`define_method`/`method_missing` — every step in the class
-  # reads top to bottom as ordinary method calls. The one `extend` is
-  # `Dsl::Lockable::ClassMethods` (the five coordination macros), a
-  # self-contained module with no hooks of its own (Finding 9).
+  # reads top to bottom as ordinary method calls. The two `extend`s are
+  # `Dsl::Lockable::ClassMethods` (the five coordination macros) and
+  # `Dsl::Retryable` (`retries`), self-contained modules whose only hook is
+  # an `inherited` that copies their declarations down (Finding 9).
   class Step
     include RubyReactor::StepSignals
     extend RubyReactor::Dsl::Lockable::ClassMethods
+    extend RubyReactor::Dsl::Retryable
 
     attr_reader :inputs, :context, :result, :reason
 
     def initialize(inputs, context, result: nil, reason: nil)
-      @inputs = inputs
+      contract = self.class.input_contract if self.class.declares_inputs?
+      @inputs = Inputs.new(inputs, contract: contract, owner: self.class.name || self.class.inspect)
       @context = context
       @result = result
       @reason = reason
@@ -163,11 +167,13 @@ module RubyReactor
         @own_input_contract ||= Step::InputContract.new(owner: self)
       end
 
+      # `to_h`: a step body may hand its own `Inputs` on (`OtherStep.run(inputs, context)`).
       def with_defaults(arguments)
-        input_contract.apply_defaults(arguments)
+        input_contract.apply_defaults(arguments.to_h)
       end
 
       def enforce_contract!(arguments)
+        arguments = arguments.to_h
         return arguments unless declares_inputs?
 
         input_contract.enforce!(arguments)

data/lib/ruby_reactor/version.rb

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