ruby_reactor 0.8.4 → 0.8.6

data/lib/ruby_reactor/error/rollback_handed_off.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module RubyReactor
+  module Error
+    # A control signal, never a failure (009 R-04): a fan-out map started its
+    # distributed rollback and must wait for its element jobs. Raised from
+    # `MapStep#compensate` / `#undo`, it unwinds the rollback without popping
+    # the map's undo entry (the resume cursor), passes every `rescue
+    # Error::Rescuable` (see `Rescuable.===`), and is rescued only by
+    # `Executor` and `Reactor#undo`, which record where the rollback stands,
+    # save, and hand the run off as `rolling_back`.
+    #
+    # `failure` carries the Failure the run will end with, minus its rollback
+    # failures, set by the `ResultHandler` it passes through and consumed by
+    # the executor of that level.
+    class RollbackHandedOff < Base
+      attr_reader :map_id, :reactor_class_name
+      attr_accessor :failure
+
+      def initialize(map_id:, reactor_class_name: nil, message: "rollback handed off at map #{map_id}")
+        super(message)
+        @map_id = map_id
+        @reactor_class_name = reactor_class_name
+      end
+    end
+  end
+end

data/lib/ruby_reactor/executor/compensation_manager.rb

@@ -3,15 +3,17 @@
 module RubyReactor
   class Executor
     class CompensationManager
-      # Raised ONLY by the step's own coordination, before its body: a
-      # coordination error raised from inside a body (a nested direct
+      # Raised ONLY before the step's body: by its own coordination, or while
+      # resolving its arguments (008 R-06).
+      # A coordination error raised from inside a body (a nested direct
       # `Step.run`) arrives as `StepCoordination::NestedCoordinationError`, and
       # a bare `Lock::AcquisitionError` etc. may come from a nested
       # `Reactor.run` — both mean the body ran, so neither is listed here.
       NEVER_STARTED_ERROR_CLASSES = [
         RubyReactor::Executor::StepCoordination::Contended,
         RubyReactor::Executor::StepCoordination::KeyError,
-        RubyReactor::Executor::StepCoordination::DispatchRefused
+        RubyReactor::Executor::StepCoordination::DispatchRefused,
+        RubyReactor::Error::ArgumentResolutionError
       ].freeze
 
       def initialize(context)
@@ -28,11 +30,23 @@ module RubyReactor
       # (005 FR-004). `ResultHandler` attaches it to the final Failure.
       attr_reader :undo_trace, :rollback_failures
 
+      # The step failure being rolled back: `{ step:, error:, compensated:,
+      # compensation_error: }`. A rollback that hands off (009 R-04) records it,
+      # so the resume knows whether that step's own compensate still runs.
+      attr_reader :pending
+
+      # Rollback failures collected before a hand-off, saved serialized on
+      # the context's `rollback` and restored on resume.
+      def restore_rollback_failures(list)
+        @rollback_failures.replace(Array(ContextSerializer.deserialize_value(list)))
+      end
+
       def add_to_undo_stack(step_info)
         @context.undo_stack << step_info
       end
 
       def handle_step_failure(step_config, error, arguments)
+        @pending = { step: step_config.name, error: error, compensated: false }
         # A step whose OWN coordination acquisition failed (contention, or a
         # bad key proc) never ran its body — "no step compensates, the
         # contended step's work has not been attempted" (US3-1/T018), which
@@ -42,38 +56,61 @@ module RubyReactor
         # turning a plain contention failure into a confusing
         # CompensationError. Prior steps still roll back normally.
         if step_never_started?(error)
+          @pending[:compensated] = true
           rollback_completed_steps
-          return RubyReactor.Failure("Step '#{step_config.name}' failed: #{error}")
+          return RubyReactor.Failure(step_failure_message(step_config, error))
         end
 
         # Try compensation
         compensation_result = compensate_step(step_config, error, arguments)
+        @pending[:compensated] = true
+        @pending[:compensation_error] = compensation_error_message(step_config, compensation_result)
         case compensation_result
         when RubyReactor::Success
           # Compensation succeeded, continue with rollback
           rollback_completed_steps
-          RubyReactor.Failure("Step '#{step_config.name}' failed: #{error}")
+          RubyReactor.Failure(step_failure_message(step_config, error))
         when RubyReactor::Failure
           # Compensation failed, this is more serious
           rollback_completed_steps
-          raise Error::CompensationError.new(
-            "Compensation for step '#{step_config.name}' failed: #{compensation_result.error}",
-            step: step_config.name,
-            context: @context,
-            original_error: error
-          )
+          raise Error::CompensationError.new(@pending[:compensation_error], step: step_config.name, context: @context,
+                                                                            original_error: error)
         end
       end
 
-      def rollback_completed_steps
-        undo_stack.reverse_each do |step_info|
+      def step_failure_message(step_config, error)
+        "Step '#{step_config.name}' failed: #{error}"
+      end
+
+      def compensation_error_message(step_config, compensation_result)
+        return unless compensation_result.is_a?(RubyReactor::Failure)
+
+        "Compensation for step '#{step_config.name}' failed: #{compensation_result.error}"
+      end
+
+      # A unit that compensates itself outside the executor loop (StepWorker's
+      # `async_step`): the same coordination re-take, trace, middleware events
+      # and `rollback_failures` as a step compensated here.
+      def compensate(step_config, error, arguments)
+        compensate_step(step_config, error, arguments)
+      end
+
+      # Newest first. Each entry leaves the stack only once its undo returned,
+      # so an interruption mid-rollback leaves exactly the entries still to
+      # undo — the interrupted one included — for a manual undo (008 R-16).
+      # `after_pop` runs after each pop: an element rollback job saves there,
+      # so a redelivery resumes after the last undone entry (009 R-07).
+      def rollback_completed_steps(&after_pop)
+        until undo_stack.empty?
+          step_info = undo_stack.last
           result = @context.with_step(step_info[:step].name) do
             undo_step(step_info[:step], step_info[:result], step_info[:arguments])
           end
+          undo_stack.pop
           @undo_trace << { type: :undo, step: step_info[:step].name, result: result,
                            arguments: step_info[:arguments] }
+          after_pop&.call
         end
-        undo_stack.clear
       end
 
       private
@@ -117,19 +154,18 @@ module RubyReactor
         ).around_rollback(&block)
       end
 
+      # Under `with_step`, as `rollback_completed_steps` runs each undo: a
+      # construct (compose, map) reads `context.current_step` to find its own
+      # state during either rollback moment.
       def compensate_step(step_config, error, arguments)
+        @context.with_step(step_config.name) { compensate_step_body(step_config, error, arguments) }
+      end
+
+      def compensate_step_body(step_config, error, arguments)
         middlewares.on(:start_compensation, step_config.name, error, arguments, @context)
         begin
           compensate_result = coordinated_rollback(step_config, arguments) do
-            catch(StepSignals::TAG) do
-              if step_config.compensate_block
-                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
-                RubyReactor.Skipped() # Default: nothing defined, rollback continues
-              end
-            end
+            step_config.call_compensate(error, arguments, @context)
           end
 
           @context.append_execution_trace(
@@ -152,7 +188,7 @@ module RubyReactor
           end
 
           compensate_result
-        rescue StandardError => e
+        rescue Error::Rescuable => e
           record_rollback_failure(step_config.name, :compensate, e)
           middlewares.on(:failed_compensation, step_config.name, e, @context)
           # A raise is a compensation failure like a returned Failure: the
@@ -162,19 +198,11 @@ module RubyReactor
         end
       end
 
-      def undo_step(step_config, result, arguments) # rubocop:disable Metrics/MethodLength
+      def undo_step(step_config, result, arguments)
         middlewares.on(:start_undo, step_config.name, result, arguments, @context)
         begin
           undo_result = coordinated_rollback(step_config, arguments) do
-            catch(StepSignals::TAG) do
-              if step_config.undo_block
-                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
-                RubyReactor.Skipped() # Default: nothing defined, rollback continues
-              end
-            end
+            step_config.call_undo(result.value, arguments, @context)
           end
 
           @context.append_execution_trace(
@@ -196,7 +224,7 @@ module RubyReactor
           end
 
           undo_result
-        rescue StandardError => e
+        rescue Error::Rescuable => e
           record_rollback_failure(step_config.name, :undo, e)
           middlewares.on(:failed_undo, step_config.name, e, @context)
           # Log undo failure but don't halt the rollback process

data/lib/ruby_reactor/executor/result_handler.rb

@@ -35,9 +35,13 @@ module RubyReactor
       # Every reactor-level Failure that follows a rollback is built here, so
       # this is the one place `rollback_failures` is attached (005 R-08).
       def handle_execution_error(error)
-        failure = build_execution_failure(error)
-        failure.rollback_failures.concat(@compensation_manager.rollback_failures) if failure.is_a?(RubyReactor::Failure)
-        failure
+        with_rollback_failures(build_execution_failure(error))
+      end
+
+      # The end of a rollback that handed off (009 R-04): the Failure recorded
+      # at the hand-off, with every rollback failure collected since.
+      def handed_off_failure(failure)
+        with_rollback_failures(failure)
       end
 
       def final_result(reactor_class)
@@ -51,26 +55,62 @@ module RubyReactor
 
       private
 
+      def with_rollback_failures(failure)
+        failure.rollback_failures.concat(@compensation_manager.rollback_failures) if failure.is_a?(RubyReactor::Failure)
+        failure
+      end
+
+      # Every error rolls back the completed steps first (Constitution II), then
+      # becomes the run's Failure.
       def build_execution_failure(error)
+        if error.is_a?(Error::StepFailureError)
+          current_context = error.context || @context
+          current_context.current_step = error.step
+          store_failed_map_context(current_context) if current_context.map_metadata
+        end
+        handing_off_as(error) { @compensation_manager.rollback_completed_steps }
+        failure_for(error)
+      end
+
+      # A rollback that hands off mid-way (009 R-04) carries the Failure this
+      # run will end with, minus its rollback failures, to the executor that
+      # records the hand-off. `error` is what the run fails with once the
+      # rollback is done (a lambda when it is costly or not built yet).
+      def handing_off_as(error)
+        yield
+      rescue Error::RollbackHandedOff => e
+        e.failure ||= failure_for(error.respond_to?(:call) ? error.call : error)
+        raise
+      end
+
+      def failure_for(error)
         case error
         when Error::StepFailureError
-          handle_step_failure_error(error)
+          create_failure_from_error(error, redacted_input_names(error.context))
         when Error::InputValidationError
           # 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
-          RubyReactor.Failure("Execution error: #{error.message}", exception_class: error.class.name)
+          # A `CompensationError` names the step whose compensation failed.
+          RubyReactor.Failure("Execution error: #{error.message}", exception_class: error.class.name,
+                                                                   step_name: error.step || @context.current_step,
+                                                                   reactor_name: @context.reactor_class&.name)
         else
-          # Unknown errors - don't rollback as they may not be reactor-related
-          RubyReactor.Failure("Execution failed: #{error.message}", exception_class: error.class.name)
+          # Any other StandardError after completed work (a checkpoint write,
+          # a hook) still leaves a partial saga, rolled back like any failure
+          # (Constitution II, 008 R-07); name the step that was executing.
+          RubyReactor.Failure("Execution failed: #{error.message}", exception_class: error.class.name,
+                                                                    step_name: @context.current_step,
+                                                                    reactor_name: @context.reactor_class&.name)
         end
       end
 
+      def redacted_input_names(context)
+        return [] unless context&.reactor_class
+
+        context.reactor_class.inputs.select { |_, config| config[:redact] }.keys
+      end
+
       # 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
@@ -108,9 +148,9 @@ module RubyReactor
         result
       end
 
-      # A step returned `RubyReactor.Skipped(...)`. The reactor continues:
-      # validate and record the value exactly like a Success, but do NOT push
-      # to the undo stack (nothing happened, so there is nothing to undo).
+      # A step returned `RubyReactor.Skipped(...)`: the run continues exactly as
+      # for a Success (value, hand-off, period mark), but the step is NOT pushed
+      # for undo — it had nothing to do, so there is nothing to revert (008 R-19).
       def handle_skipped(step_config, result, resolved_arguments)
         validate_step_output(step_config, result.value, resolved_arguments)
         @step_results[step_config.name] = result
@@ -130,22 +170,15 @@ module RubyReactor
       def handle_success(step_config, result, resolved_arguments)
         validate_step_output(step_config, result.value, resolved_arguments)
         @step_results[step_config.name] = result
-        # `async_step` / `async_reactor` dispatches are independent units of
-        # work with their own compensation flows — the parent rolling back must
-        # not "undo" a dispatch whose unit runs (and may still succeed)
-        # elsewhere. They never enter the parent's undo stack.
-        unless async_unit?(step_config)
-          @compensation_manager.add_to_undo_stack({ step: step_config, arguments: resolved_arguments,
+        if step_config.rollback_tracked?
+          @compensation_manager.add_to_undo_stack({ step: step_config,
+                                                    arguments: step_config.rollback_arguments(resolved_arguments),
                                                     result: result })
         end
         @context.set_result(step_config.name, result.value)
         @dependency_graph.complete_step(step_config.name)
       end
 
-      def async_unit?(step_config)
-        step_config.respond_to?(:async_dispatch?) && step_config.async_dispatch?
-      end
-
       # A composed child's Failure carries the child's own rollback failures;
       # fold them in BEFORE this level rolls back, so they come first.
       def adopt_rollback_failures(result)
@@ -156,36 +189,38 @@ module RubyReactor
 
       def handle_retries_exhausted(step_config, result, resolved_arguments)
         adopt_rollback_failures(result)
-        @compensation_manager.handle_step_failure(step_config, result.original_error, resolved_arguments)
-        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,
-                                                          validation_errors: result.validation_errors)
-        if result.respond_to?(:backtrace) && result.backtrace
-          error.set_backtrace(result.backtrace)
-        elsif orig_err
-          error.set_backtrace(orig_err.backtrace)
+        error = step_failure_error(step_config, result.error, result, resolved_arguments, cause: result.original_error)
+        handing_off_as(error) do
+          @compensation_manager.handle_step_failure(step_config, result.original_error, resolved_arguments)
         end
         raise error
       end
 
       def handle_failure(step_config, result, resolved_arguments)
         adopt_rollback_failures(result)
-        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,
-                                                                  validation_errors: result.validation_errors)
+        message = @compensation_manager.step_failure_message(step_config, result.error)
+        failure_result = handing_off_as(-> { step_failure_error(step_config, message, result, resolved_arguments) }) do
+          @compensation_manager.handle_step_failure(step_config, result.error, resolved_arguments)
+        end
+        raise step_failure_error(step_config, failure_result.error, result, resolved_arguments)
+      end
+
+      # A step that propagates another unit's failure (an async_step reader, a
+      # map adopting a fan-out element's Failure) keeps its field errors and
+      # exception class on the reactor's failure.
+      def step_failure_error(step_config, message, result, resolved_arguments, cause: result.error)
+        orig_err = cause.is_a?(Exception) ? cause : nil
+        error = Error::StepFailureError.new(message, step: step_config.name, context: @context,
+                                                     original_error: orig_err,
+                                                     step_arguments: resolved_arguments,
+                                                     exception_class: (result.exception_class unless orig_err),
+                                                     validation_errors: result.validation_errors)
         if result.respond_to?(:backtrace) && result.backtrace
           error.set_backtrace(result.backtrace)
         elsif orig_err
           error.set_backtrace(orig_err.backtrace)
         end
-        raise error
+        error
       end
 
       # Wrapped first, so a returned `Step::Inputs` is validated and stored as its Hash.
@@ -193,31 +228,16 @@ module RubyReactor
         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,
+        @compensation_manager.add_to_undo_stack({ step: step_config,
+                                                  arguments: step_config.rollback_arguments(resolved_arguments),
                                                   result: success_result })
         @context.set_result(step_config.name, success_result.value)
         @dependency_graph.complete_step(step_config.name)
       end
 
-      def handle_step_failure_error(error)
-        current_context = error.context || @context
-        current_context.current_step = error.step
-
-        store_failed_map_context(current_context) if current_context.map_metadata
-
-        @compensation_manager.rollback_completed_steps
-
-        redact_inputs = []
-        if error.context&.reactor_class
-          redact_inputs = error.context.reactor_class.inputs.select { |_, config| config[:redact] }.keys
-        end
-
-        create_failure_from_error(error, redact_inputs)
-      end
-
       def store_failed_map_context(context)
         return unless context.map_metadata && context.map_metadata[:map_id]
-        return unless context.map_metadata[:fail_fast]
+        return unless Map::Helpers.normalize_arguments(context.map_metadata)[:atomic]
 
         storage = RubyReactor.configuration.storage_adapter
         storage.store_map_failed_context_id(
@@ -254,6 +274,8 @@ module RubyReactor
       def resolve_exception_class(original_error, error)
         # A step's own contention is reported by its cause (Lock::AcquisitionError, ...).
         original_error = original_error.original if original_error.is_a?(StepCoordination::Contended)
+        # Argument failures report their cause's class (008 R-06).
+        return original_error.exception_class if original_error.is_a?(Error::ArgumentResolutionError)
         return original_error.class.name if original_error
 
         error.respond_to?(:exception_class) ? error.exception_class : nil
@@ -274,7 +296,7 @@ module RubyReactor
         # 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)
+        handing_off_as(error) { @compensation_manager.handle_step_failure(step_config, error, resolved_arguments) }
         raise error
       end
 

data/lib/ruby_reactor/executor/retry_manager.rb

@@ -61,7 +61,7 @@ module RubyReactor
         serialized_context = ContextSerializer.serialize(context_to_serialize)
 
         if @context.map_metadata
-          map_args = @context.map_metadata.transform_keys(&:to_sym)
+          map_args = Map::Helpers.normalize_arguments(@context.map_metadata)
           configuration.async_router.perform_map_element_in(
             delay,
             map_id: map_args[:map_id],
@@ -75,7 +75,7 @@ module RubyReactor
             step_name: map_args[:step_name],
             batch_size: map_args[:batch_size],
             serialized_context: serialized_context,
-            fail_fast: map_args[:fail_fast]
+            atomic: map_args[:atomic]
           )
         else
           # Persist BEFORE enqueue — the job payload is identity-only (F2). The
@@ -193,7 +193,8 @@ module RubyReactor
           reactor_name: reactor_class.name,
           step_arguments: result.respond_to?(:step_arguments) ? result.step_arguments : {},
           validation_errors: result.validation_errors,
-          rollback_failures: result.rollback_failures
+          rollback_failures: result.rollback_failures,
+          exception_class: result.exception_class
         )
       end
 

data/lib/ruby_reactor/executor/step_coordination.rb

@@ -99,7 +99,7 @@ module RubyReactor
         key
       rescue KeyError
         raise
-      rescue StandardError => e
+      rescue RubyReactor::Error::Rescuable => e
         raise KeyError.new(
           "#{step_name}: coordination key proc raised #{e.class}: #{e.message}",
           step: step_name, original_error: e
@@ -188,7 +188,7 @@ module RubyReactor
       # counter and marker must survive the park.
       rescue Contended, Error::ExecutionParked
         raise
-      rescue StandardError
+      rescue Error::Rescuable
         clear_contention_state
         raise
       end
@@ -498,7 +498,7 @@ module RubyReactor
         rescue Error::ExecutionParked
           outcome = :parked
           raise
-        rescue StandardError
+        rescue Error::Rescuable
           outcome = :failed
           raise
         ensure
@@ -513,8 +513,8 @@ module RubyReactor
       #   step again and must keep its place: the stash survives, so the next
       #   attempt re-reads the SAME nonce. The heartbeat is stopped across the
       #   gap; `poison_pill_timeout` bounds it.
-      # - :abandoned — an exit that is not a `StandardError` (`Sidekiq::Shutdown`,
-      #   `NoMemoryError`, ...). Not advanced: `Sidekiq::Shutdown` pushes the
+      # - :abandoned — an interruption (`Sidekiq::Shutdown`, `NoMemoryError`,
+      #   ...; `Error::Rescuable`, 008 R-16). Not advanced: `Sidekiq::Shutdown` pushes the
       #   job back to run again, which must keep this place, and `failed: true`
       #   would poison successors for work that may yet complete. With the
       #   heartbeat stopped, the poison pill releases the position within
@@ -644,7 +644,7 @@ module RubyReactor
         return skipped_for_period if storage_adapter.period_seen?(key)
 
         result = yield
-        if plain_success?(result) && !chain_failed?(result)
+        if continuing_success?(result) && !chain_failed?(result)
           storage_adapter.period_mark(key, RubyReactor::Period.ttl_seconds(config[:every]))
         end
         result
@@ -654,8 +654,11 @@ module RubyReactor
         RubyReactor.Skipped(nil, reason: :period, step_name: step_name)
       end
 
-      def plain_success?(result)
-        result.is_a?(RubyReactor::Success) && !result.is_a?(RubyReactor::Halt) && !result.is_a?(RubyReactor::Skipped)
+      # A body's `Skipped` marks the bucket like a Success: it is only an
+      # instrumentation mark. The library's own skips (period, ordered lock)
+      # are returned by the gates around this one, never through it.
+      def continuing_success?(result)
+        result.is_a?(RubyReactor::Success) && !result.is_a?(RubyReactor::Halt)
       end
 
       def period_key(config)