ruby_reactor 0.7.0 → 0.8.0

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)
@@ -110,9 +113,9 @@ module RubyReactor
       # 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)
+      if (halted = check_period_gate)
         completed = true
-        return finalize_skipped(skipped)
+        return finalize_halt(halted)
       end
 
       @context.status = :running
@@ -218,9 +221,9 @@ module RubyReactor
 
       # 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)
+      if first_run && (halted = check_period_gate)
         completed = true
-        return finalize_skipped(skipped)
+        return finalize_halt(halted)
       end
 
       prepare_for_resume
@@ -393,16 +396,16 @@ module RubyReactor
       @context.current_step.nil? && @context.intermediate_results.empty?
     end
 
-    # Record and persist a Skipped result, then return it. Shared by the
+    # Record and persist a Halt 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
+    def finalize_halt(halted)
+      @result = halted
       update_context_status(@result)
       save_context
       @result
     end
 
-    # Returns a Skipped result if the period bucket is already marked, else nil.
+    # Returns a Halt result if the period bucket is already marked, else nil.
     # 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).
@@ -413,13 +416,13 @@ module RubyReactor
       key = period_key(config)
       return nil unless RubyReactor.configuration.storage_adapter.period_seen?(key)
 
-      RubyReactor::Skipped.new(reason: :period, period_key: key)
+      RubyReactor::Halt.new(reason: :period, period_key: key)
     end
 
     def mark_period_on_success(result)
       return unless @reactor_class.respond_to?(:period_config) && @reactor_class.period_config
       return unless result.is_a?(RubyReactor::Success)
-      return if result.is_a?(RubyReactor::Skipped)
+      return if result.is_a?(RubyReactor::Halt)
 
       config = @reactor_class.period_config
       ttl = RubyReactor::Period.ttl_seconds(config[:every])
@@ -662,8 +665,8 @@ module RubyReactor
       case result
       when RubyReactor::DispatchResult
         @context.status = :running
-      when RubyReactor::Skipped
-        @context.status = :skipped
+      when RubyReactor::Halt
+        @context.status = :halted
       when RubyReactor::Success
         @context.status = :completed
       when RubyReactor::Failure
@@ -696,14 +699,16 @@ module RubyReactor
         @result = @step_executor.execute_all_steps
       else
         case result
-        # Skipped must be listed before Success (Skipped < Success) so the
+        # Halt must be listed before Success (Halt < Success) so the
         # halt path wins over the "continue with remaining steps" path.
-        when RubyReactor::Skipped,
+        # Skipped is NOT listed here — it is a Success subclass and must
+        # continue with the remaining steps, same as a plain Success.
+        when RubyReactor::Halt,
              RetryQueuedResult,
              RubyReactor::Failure,
              RubyReactor::DispatchResult,
              RubyReactor::InterruptResult
-          # Terminal: step was skipped, requeued, failed, paused, or handed
+          # Terminal: step halted, requeued, failed, paused, or handed
           # off to async. Return the result as-is.
           @result = result
         when RubyReactor::Success

data/lib/ruby_reactor/map/element_executor.rb

@@ -141,7 +141,13 @@ module RubyReactor
         index = arguments[:index]
         parent_class = arguments[:parent_reactor_class_name] # Using short name for variable
 
-        if result.success?
+        if result.halted?
+          # A Halt must not be collected as a (nil) value indistinguishable
+          # from an ordinary success — mark it so the enumerator reconstructs
+          # a real Halt for the consumer.
+          storage.store_map_result(map_id, index, { _halt: true, reason: result.reason },
+                                   parent_class, strict_ordering: arguments[:strict_ordering])
+        elsif result.success?
           storage.store_map_result(map_id, index, ContextSerializer.serialize_value(result.value),
                                    parent_class, strict_ordering: arguments[:strict_ordering])
         else

data/lib/ruby_reactor/map/helpers.rb

@@ -96,13 +96,15 @@ module RubyReactor
           # Manually update execution trace to reflect completion
           # This is necessary because resume_execution continues from the NEXT step
           # and the async step (which returned DispatchResult) needs to be marked as done with actual value
-          parent_context.execution_trace << {
-            type: :result,
-            step: step_name_sym,
-            timestamp: Time.now,
-            value: final_result.value,
-            status: :success
-          }
+          parent_context.append_execution_trace(
+            {
+              type: :result,
+              step: step_name_sym,
+              timestamp: Time.now,
+              value: final_result.value,
+              status: :success
+            }
+          )
 
           parent_context.current_step = nil
           executor.resume_execution

data/lib/ruby_reactor/map/result_enumerator.rb

@@ -101,6 +101,8 @@ module RubyReactor
           # whoever happened to materialize the enumerator (the JSON encoder, in
           # the dashboard's case) instead of the stack of the step that failed.
           RubyReactor::Failure.new(result["_error"], backtrace: [])
+        elsif result.is_a?(Hash) && result.key?("_halt")
+          RubyReactor::Halt.new(reason: result["reason"])
         else
           RubyReactor::Success.new(ContextSerializer.deserialize_value(result))
         end

data/lib/ruby_reactor/map/sweeper.rb

@@ -92,7 +92,7 @@ module RubyReactor
 
         results = data["intermediate_results"] || {}
         status = data["status"].to_s
-        results.key?(meta["step_name"].to_s) || %w[completed failed skipped].include?(status)
+        results.key?(meta["step_name"].to_s) || %w[completed failed halted skipped].include?(status)
       end
 
       def retrigger_collector(meta)

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/open_telemetry.rb

@@ -502,9 +502,9 @@ module RubyReactor
 
       case result
       when RubyReactor::Success
-        if result.skipped?
-          span.set_attribute("reactor.status", "skipped")
-          span.set_attribute("reactor.skipped_reason", result.reason.to_s)
+        if result.halted?
+          span.set_attribute("reactor.status", "halted")
+          span.set_attribute("reactor.halt_reason", result.reason.to_s)
           span.status = ::OpenTelemetry::Trace::Status.ok
         else
           span.set_attribute("reactor.status", "completed")
@@ -578,7 +578,10 @@ module RubyReactor
 
       case result
       when RubyReactor::Success
-        if result.skipped?
+        if result.halted?
+          span.set_attribute("step.status", "halted")
+          span.set_attribute("step.halt_reason", result.reason.to_s)
+        elsif result.skipped?
           span.set_attribute("step.status", "skipped")
           span.set_attribute("step.skipped_reason", result.reason.to_s)
         else

data/lib/ruby_reactor/ordered_lock.rb

@@ -62,11 +62,11 @@ module RubyReactor
     #   via the stored context status.
     # - `:skip_chain_failed` — only in strict mode: an earlier nonce in this
     #   sequence terminated with a Failure, so this run is short-circuited
-    #   with `Skipped(reason: :ordered_lock_chain_failed)` without executing.
+    #   with `Halt(reason: :ordered_lock_chain_failed)` without executing.
     # - `:stale_batch` — this run's epoch no longer matches the key's current
     #   generation: its batch fully drained and the numbering was reused by a
     #   newer batch. The run is short-circuited with
-    #   `Skipped(reason: :ordered_lock_stale_batch)` and must not participate.
+    #   `Halt(reason: :ordered_lock_stale_batch)` and must not participate.
     # - `:poison_advance` is collapsed to `:go` from the caller's perspective.
     def check!
       raise ArgumentError, "OrderedLock#check! requires a nonce" unless @nonce
@@ -111,7 +111,7 @@ module RubyReactor
     #
     # `failed:` records this nonce as the chain-failure marker (only the FIRST
     # failure sticks). In strict mode the marker causes subsequent nonces to
-    # short-circuit with Skipped.
+    # short-circuit with Halt.
     def advance!(failed: false)
       raise ArgumentError, "OrderedLock#advance! requires a nonce" unless @nonce
 

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)
@@ -264,18 +261,18 @@ module RubyReactor
         RubyReactor.configuration.storage_adapter
       end
 
-      # Distinguishes `RubyReactor::Skipped` from a plain `Success`. Works on
-      # any object with a `skipped?` predicate.
+      # Distinguishes `RubyReactor::Halt` (a clean halt) from a plain
+      # `Success`. Works on any object with a `halted?` predicate.
       #
       # Examples:
-      #   expect(result).to be_skipped
-      #   expect(result).to be_skipped.because(:period)
-      #   expect(result).to be_skipped.at_step(:second)
-      ::RSpec::Matchers.define :be_skipped do
+      #   expect(result).to be_halted
+      #   expect(result).to be_halted.because(:period)
+      #   expect(result).to be_halted.at_step(:second)
+      ::RSpec::Matchers.define :be_halted do
         match do |subject|
           subject.ensure_executed! if subject.respond_to?(:ensure_executed!)
           actual = subject.respond_to?(:result) ? subject.result : subject
-          next false unless actual.respond_to?(:skipped?) && actual.skipped?
+          next false unless actual.respond_to?(:halted?) && actual.halted?
           next false if @expected_reason && actual.reason != @expected_reason
           next false if @expected_step && actual.step_name != @expected_step
 
@@ -292,12 +289,62 @@ module RubyReactor
 
         failure_message do |subject|
           actual = subject.respond_to?(:result) ? subject.result : subject
-          if !actual.respond_to?(:skipped?) || !actual.skipped?
-            "expected result to be Skipped, got #{actual.class}"
+          if !actual.respond_to?(:halted?) || !actual.halted?
+            "expected result to be Halt, got #{actual.class}"
           elsif @expected_reason && actual.reason != @expected_reason
-            "expected Skipped reason #{@expected_reason.inspect}, got #{actual.reason.inspect}"
+            "expected Halt reason #{@expected_reason.inspect}, got #{actual.reason.inspect}"
+          else
+            "expected Halt at_step #{@expected_step.inspect}, got #{actual.step_name.inspect}"
+          end
+        end
+
+        failure_message_when_negated do
+          "expected result not to be Halt"
+        end
+      end
+
+      # Asserts that a STEP was skipped — either the subject itself is a
+      # `RubyReactor::Skipped` result, or the execution trace records a
+      # `:skipped` entry (optionally for a specific step via `.at_step`). A
+      # halted run never satisfies this — halting and skipping are distinct.
+      #
+      # Examples:
+      #   expect(result).to be_skipped
+      #   expect(subject).to be_skipped.at_step(:maybe_sync)
+      ::RSpec::Matchers.define :be_skipped do
+        match do |subject|
+          subject.ensure_executed! if subject.respond_to?(:ensure_executed!)
+          actual = subject.respond_to?(:result) ? subject.result : subject
+          next false if actual.respond_to?(:halted?) && actual.halted?
+
+          entries = skipped_trace_entries(subject)
+          next entries.any? { |e| e[:step].to_s == @expected_step.to_s } if @expected_step
+          next true if entries.any?
+
+          actual.respond_to?(:skipped?) && actual.skipped?
+        end
+
+        chain :at_step do |step|
+          @expected_step = step
+        end
+
+        def skipped_trace_entries(subject)
+          trace = if subject.respond_to?(:reactor_instance)
+                    subject.reactor_instance.context.execution_trace
+                  elsif subject.respond_to?(:execution_trace)
+                    subject.execution_trace
+                  else
+                    []
+                  end
+          trace.select { |e| e[:type].to_s == "skipped" }
+        end
+
+        failure_message do |subject|
+          actual = subject.respond_to?(:result) ? subject.result : subject
+          if @expected_step
+            "expected a skipped step named #{@expected_step.inspect}, found none in the execution trace"
           else
-            "expected Skipped at_step #{@expected_step.inspect}, got #{actual.step_name.inspect}"
+            "expected result to be Skipped, got #{actual.class}"
           end
         end
 

data/lib/ruby_reactor/rspec/test_subject.rb

@@ -300,8 +300,8 @@ module RubyReactor
                   end
                 end
           RubyReactor::Success.new(val)
-        when "skipped"
-          skipped_result(ctx)
+        when "halted", "skipped" # "skipped" is the legacy name for a halt
+          halted_result(ctx)
         when "running"
           # Try to determine if it is truly running or if we just missed the completion
           if @process_jobs && AsyncTestHelpers.active?
@@ -326,14 +326,14 @@ module RubyReactor
       end
 
       # A clean halt: either a `with_period` gate or a step returning
-      # `RubyReactor.Skipped(...)`. The sync run already produced the exact
-      # Skipped (reason/step intact) — surface it. For async runs the worker
+      # `RubyReactor.Halt(...)`. The sync run already produced the exact
+      # Halt (reason/step intact) — surface it. For async runs the worker
       # swallows the return value, so rebuild from the trace.
-      def skipped_result(ctx)
-        return @run_result if @run_result.is_a?(RubyReactor::Skipped)
+      def halted_result(ctx)
+        return @run_result if @run_result.is_a?(RubyReactor::Halt)
 
-        entry = ctx.execution_trace.reverse.find { |t| t[:type].to_s == "skipped" }
-        RubyReactor::Skipped.new(reason: entry&.dig(:reason), step_name: entry&.dig(:step))
+        entry = ctx.execution_trace.reverse.find { |t| t[:type].to_s == "halt" }
+        RubyReactor::Halt.new(reason: entry&.dig(:reason), step_name: entry&.dig(:step))
       end
 
       def success?