ruby_reactor 0.8.5 → 0.8.6

data/lib/ruby_reactor/error/rescuable.rb

@@ -12,11 +12,16 @@ module RubyReactor
     # raises — rescuing that would stop the caller's timeout from ever firing.
     # Running rollback code during any of them is unsafe; the executor marks
     # the run `aborted` for a manual undo instead.
+    #
+    # Nor does it match `RollbackHandedOff`, a control signal (009 R-04): it
+    # must pass the `rescue Error::Rescuable` sites between `MapStep#undo` and
+    # the executor (`CompensationManager#undo_step`, `StepExecutor`), which
+    # would otherwise record it as an undo failure.
     module Rescuable
       INTERRUPTIONS = [SignalException, SystemExit, NoMemoryError].freeze
 
       def self.===(exception)
-        exception.is_a?(Exception) && !interruption?(exception)
+        exception.is_a?(Exception) && !interruption?(exception) && !exception.is_a?(RollbackHandedOff)
       end
 
       def self.interruption?(exception)

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

@@ -30,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
@@ -44,29 +56,38 @@ 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 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.
@@ -77,7 +98,9 @@ module RubyReactor
       # 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).
-      def rollback_completed_steps
+      # `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
@@ -86,6 +109,7 @@ module RubyReactor
           undo_stack.pop
           @undo_trace << { type: :undo, step: step_info[:step].name, result: result,
                            arguments: step_info[:arguments] }
+          after_pop&.call
         end
       end
 

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,34 +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. A `CompensationError` names the step
-          # whose compensation failed.
-          @compensation_manager.rollback_completed_steps
+          # 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
           # Any other StandardError after completed work (a checkpoint write,
-          # a hook) still leaves a partial saga: roll it back like any failure
-          # (Constitution II, 008 R-07) and name the step that was executing.
-          @compensation_manager.rollback_completed_steps
+          # 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
@@ -139,7 +171,8 @@ module RubyReactor
         validate_step_output(step_config, result.value, resolved_arguments)
         @step_results[step_config.name] = result
         if step_config.rollback_tracked?
-          @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: result })
         end
         @context.set_result(step_config.name, result.value)
@@ -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(
@@ -276,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_executor.rb

@@ -133,9 +133,11 @@ module RubyReactor
       # the stack. A worker run is redelivered instead, and re-runs the step.
       def track_interrupted_construct(step_config, arguments, error)
         return if @context.inline_async_execution || Error::Rescuable === error # rubocop:disable Style/CaseEquality
+        return if error.is_a?(Error::RollbackHandedOff) # a rollback signal, not an interruption
         return unless step_config.undoes_partial_run?
 
-        @compensation_manager.add_to_undo_stack({ step: step_config, arguments: arguments,
+        @compensation_manager.add_to_undo_stack({ step: step_config,
+                                                  arguments: step_config.rollback_arguments(arguments),
                                                   result: RubyReactor.Success(nil) })
       end
 

data/lib/ruby_reactor/executor.rb

@@ -135,6 +135,10 @@ module RubyReactor
       handle_interrupt(@result) if @result.is_a?(RubyReactor::InterruptResult)
       completed = true
       @result
+    rescue Error::RollbackHandedOff => e
+      record_rollback_handoff(e)
+      completed = true
+      @result
     rescue RubyReactor::Lock::AcquisitionError,
            RubyReactor::Semaphore::AcquisitionError,
            RubyReactor::RateLimit::ExceededError,
@@ -153,7 +157,7 @@ module RubyReactor
       @contention_snooze = true
       raise
     rescue Error::Rescuable => e
-      @result = aborting_on_interruption { @result_handler.handle_execution_error(e) }
+      @result = handing_off { aborting_on_interruption { @result_handler.handle_execution_error(e) } }
       update_context_status(@result)
       completed = true
       @result
@@ -184,6 +188,9 @@ module RubyReactor
     end
 
     def resume_execution # rubocop:disable Metrics/MethodLength,Metrics/PerceivedComplexity,Metrics/CyclomaticComplexity
+      # A composed child re-entered while its own rollback is handed off.
+      return resume_rollback if @context.rolling_back?
+
       middlewares.on(:start_reactor, reactor_class.name, context.inputs, @context)
       completed = false
 
@@ -256,6 +263,10 @@ module RubyReactor
       handle_interrupt(@result) if @result.is_a?(RubyReactor::InterruptResult)
       completed = true
       @result
+    rescue Error::RollbackHandedOff => e
+      record_rollback_handoff(e)
+      completed = true
+      @result
     rescue RubyReactor::Lock::AcquisitionError,
            RubyReactor::Semaphore::AcquisitionError,
            RubyReactor::RateLimit::ExceededError,
@@ -274,7 +285,7 @@ module RubyReactor
       @contention_snooze = true
       raise e
     rescue Error::Rescuable => e
-      aborting_on_interruption { handle_resume_error(e) }
+      handing_off { aborting_on_interruption { handle_resume_error(e) } }
       update_context_status(@result)
       completed = true
       @result
@@ -283,16 +294,100 @@ module RubyReactor
       raise
     ensure
       release_locks unless @parked
+      # Saved while the context lock is still held (009 R-13): released first,
+      # a worker resuming this run could load the pre-save blob, and this save
+      # would then overwrite its progress.
+      save_context unless skip_context_persist?
       @acquired_context_lock&.release
       @acquired_context_lock = nil
       leave_ordered_lock_scope
+
+      emit_lifecycle_completion(completed)
+    end
+
+    # Undoes every completed step (manual undo, a composed child's undo, a
+    # map element's rollback). A rollback that hands off here (009 R-04)
+    # leaves this level's rollback failures on its context, and the next
+    # `undo_all` of the same context picks them up, so none is lost though
+    # the executor is rebuilt on resume (G2).
+    def undo_all(&after_pop)
+      saved = @context.rollback && @context.rollback["failures"]
+      @compensation_manager.restore_rollback_failures(saved) if saved
+      @compensation_manager.rollback_completed_steps(&after_pop)
+      clear_saved_rollback_failures
+    rescue Error::RollbackHandedOff
+      (@context.rollback ||= {})["failures"] =
+        ContextSerializer.serialize_value(@compensation_manager.rollback_failures)
+      raise
+    end
+
+    # Finishes a rollback that handed off at a fan-out map (009 R-04), once
+    # the map's element rollbacks have all reported: the Worker of a
+    # `rolling_back` run, or a composed child re-entered by its root. Under
+    # the run's context lock, as `resume_execution`.
+    def resume_rollback
+      state = @context.rollback || {}
+      # The hand-off came out of a running step (a composed child rolling
+      # back inside `ComposeStep#run`): resume forward, and that step
+      # finishes its child's rollback.
+      if state["trigger"] == "step" || state.empty?
+        @context.rollback = nil
+        @context.status = :running
+        return resume_execution
+      end
+
+      middlewares.on(:start_reactor, reactor_class.name, context.inputs, @context)
+      completed = false
+      enter_ordered_lock_scope
+      acquire_context_lock
+      @result = finish_rollback(state)
+      @context.rollback = nil
+      update_context_status(@result)
+      completed = true
+      @result
+    rescue Error::RollbackHandedOff => e
+      record_rollback_handoff(e)
+      completed = true
+      @result
+    rescue RubyReactor::Lock::AcquisitionError => e
+      @contention_snooze = true
+      raise composed_contention_park(e) || e
+    rescue Error::Rescuable => e
+      handing_off { aborting_on_interruption { handle_resume_error(e) } }
+      update_context_status(@result)
+      completed = true
+      @result
+    rescue Exception # rubocop:disable Lint/RescueException
+      mark_aborted
+      raise
+    ensure
       save_context unless skip_context_persist?
+      @acquired_context_lock&.release
+      @acquired_context_lock = nil
+      leave_ordered_lock_scope
 
       emit_lifecycle_completion(completed)
     end
 
-    def undo_all
-      @compensation_manager.rollback_completed_steps
+    # The rollback's other half (009 R-05): marks the hand-off saved, then
+    # enqueues the owner's Worker if the map rollback already settled and this
+    # side claims the signal. Whichever of this and the last element rollback
+    # job sees both second enqueues the owner, once. Called right after the
+    # `rolling_back` save, while the context lock is still held.
+    def hand_off_rollback!(handed_off)
+      storage = RubyReactor.configuration.storage_adapter
+      map_id = handed_off.map_id
+      map_class = handed_off.reactor_class_name
+      storage.mark_map_rollback_handed_off(map_id, map_class)
+      RubyReactor.configuration.logger.info(
+        "event=ruby_reactor.rollback.handed_off context_id=#{@context.context_id.inspect} map_id=#{map_id.inspect}"
+      )
+      meta = storage.retrieve_map_rollback_metadata(map_id, map_class)
+      return unless meta && storage.count_map_rollback_outcomes(map_id, map_class) >= meta["total"].to_i
+      return unless storage.claim_map_rollback_signal(map_id, map_class)
+
+      RubyReactor.configuration.async_router.perform_async(@context.context_id,
+                                                           RubyReactor.reactor_storage_name(@reactor_class))
     end
 
     # True once `resume_execution` is past its reactor-level gates (context
@@ -318,10 +413,18 @@ module RubyReactor
     def aborting_on_interruption
       yield
     rescue Exception => e # rubocop:disable Lint/RescueException
-      mark_aborted unless Error::Rescuable === e # rubocop:disable Style/CaseEquality
+      mark_aborted unless Error::Rescuable === e || e.is_a?(Error::RollbackHandedOff) # rubocop:disable Style/CaseEquality
       raise
     end
 
+    # A rollback run from a `rescue Error::Rescuable` body (the error's own
+    # rollback) is outside the sibling `rescue Error::RollbackHandedOff`.
+    def handing_off
+      yield
+    rescue Error::RollbackHandedOff => e
+      record_rollback_handoff(e)
+    end
+
     def undo_stack
       @compensation_manager.undo_stack
     end
@@ -768,7 +871,8 @@ module RubyReactor
 
       case result
       when RubyReactor::DispatchResult
-        @context.status = :running
+        # A rollback hand-off returns one too, and stays `rolling_back`.
+        @context.status = :running unless @context.rolling_back?
       when RubyReactor::Halt
         @context.status = :halted
       when RubyReactor::Success
@@ -833,6 +937,82 @@ module RubyReactor
       @result
     end
 
+    # Where this level's rollback stands when it hands off (009 DM §1). A
+    # composed child keeps it on its own context, inside the root's blob, and
+    # re-raises; the top-level run saves it as `rolling_back` while it still
+    # holds the context lock (I-6), runs the handshake, and returns a
+    # `DispatchResult`, as a forward hand-off does.
+    def record_rollback_handoff(handed_off)
+      failure = handed_off.failure
+      handed_off.failure = nil # this level's Failure; the level above builds its own
+      @context.rollback = rollback_state(failure)
+      @context.status = :rolling_back
+      raise handed_off if @context.root_context
+
+      save_context
+      hand_off_rollback!(handed_off)
+      @result = RubyReactor::DispatchResult.new(job_id: "map_rollback:#{handed_off.map_id}",
+                                                intermediate_results: @context.intermediate_results,
+                                                execution_id: @context.context_id)
+    end
+
+    # `trigger`: `failure` (a step failure is rolling back), `undo` (set by
+    # `Reactor#undo`), or `step` (a running step's child handed off, and no
+    # rollback started at this level). A later hand-off of the same rollback
+    # keeps what an earlier one recorded.
+    def rollback_state(failure)
+      state = (@context.rollback || {}).dup
+      pending = @compensation_manager.pending
+      state["trigger"] ||= failure || pending ? "failure" : "step"
+      if pending
+        state["step"] = pending[:step].to_s
+        state["compensated"] = pending[:compensated]
+        state["compensation_error"] = pending[:compensation_error]
+      end
+      state["failure"] = ContextSerializer.serialize_value(failure) if failure
+      state["failures"] = ContextSerializer.serialize_value(@compensation_manager.rollback_failures)
+      state
+    end
+
+    # The rest of a handed-off rollback: the failing step's own compensate if
+    # it had not finished (a map or compose adopts its settled state), the
+    # steps still on the undo stack, then the outcome the inline rollback
+    # gives (I-7).
+    def finish_rollback(state)
+      @compensation_manager.restore_rollback_failures(state["failures"])
+      return finish_undo if state["trigger"] == "undo"
+
+      failure = ContextSerializer.deserialize_value(state["failure"])
+      step_config = state["step"] && @reactor_class.steps[state["step"].to_sym]
+      if step_config && !state["compensated"]
+        @compensation_manager.handle_step_failure(step_config, failure.error, {})
+      else
+        @compensation_manager.rollback_completed_steps
+        if state["compensation_error"]
+          raise Error::CompensationError.new(state["compensation_error"], step: step_config&.name, context: @context)
+        end
+      end
+      @context.current_step = failure.step_name&.to_sym
+      @result_handler.handed_off_failure(failure)
+    rescue Error::CompensationError => e
+      @result_handler.handle_execution_error(e)
+    end
+
+    def finish_undo
+      @compensation_manager.rollback_completed_steps
+      @context.cancelled = true
+      @context.cancellation_reason = "Undo triggered"
+      @context.status = "cancelled"
+      nil
+    end
+
+    def clear_saved_rollback_failures
+      return unless @context.rollback
+
+      @context.rollback.delete("failures")
+      @context.rollback = nil if @context.rollback.empty?
+    end
+
     def handle_interrupt(interrupt_result)
       save_context