ruby_reactor 0.8.4 → 0.8.6

data/lib/ruby_reactor/adapters/sidekiq/map_element_rollback_worker.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module RubyReactor
+  module Adapters
+    module Sidekiq
+      # Rolls back one element of a fan-out map (009 R-07).
+      class MapElementRollbackWorker
+        include ::Sidekiq::Worker
+
+        def perform(arguments)
+          RubyReactor::Map::ElementRollback.perform(arguments)
+        end
+      end
+    end
+  end
+end

data/lib/ruby_reactor/adapters/sidekiq/router.rb

@@ -58,7 +58,7 @@ module RubyReactor
         # rubocop:disable Metrics/ParameterLists
         def self.perform_map_element_async(map_id:, element_id:, index:, serialized_inputs:, reactor_class_info:,
                                            strict_ordering:, parent_context_id:, parent_reactor_class_name:,
-                                           step_name:, batch_size: nil, serialized_context: nil, fail_fast: nil)
+                                           step_name:, batch_size: nil, serialized_context: nil, atomic: nil)
           job_id = RubyReactor::Adapters::Sidekiq::MapElementWorker.perform_async(
             {
               "map_id" => map_id,
@@ -72,7 +72,7 @@ module RubyReactor
               "step_name" => step_name,
               "batch_size" => batch_size,
               "serialized_context" => serialized_context,
-              "fail_fast" => fail_fast
+              "atomic" => atomic
             }
           )
           RubyReactor::DispatchResult.new(job_id: job_id)
@@ -81,7 +81,7 @@ module RubyReactor
         def self.perform_map_element_in(delay, map_id:, element_id:, index:, serialized_inputs:,
                                         reactor_class_info:, strict_ordering:, parent_context_id:,
                                         parent_reactor_class_name:, step_name:, batch_size: nil,
-                                        serialized_context: nil, fail_fast: nil)
+                                        serialized_context: nil, atomic: nil)
           job_id = RubyReactor::Adapters::Sidekiq::MapElementWorker.perform_in(
             delay,
             {
@@ -96,7 +96,7 @@ module RubyReactor
               "step_name" => step_name,
               "batch_size" => batch_size,
               "serialized_context" => serialized_context,
-              "fail_fast" => fail_fast
+              "atomic" => atomic
             }
           )
           # Return an DispatchResult so RetryManager#handle_async_retry recognises the
@@ -105,6 +105,34 @@ module RubyReactor
         end
         # rubocop:enable Metrics/ParameterLists
 
+        # One element's rollback in a fan-out map's distributed rollback (009
+        # R-07); the `_in` form is its requeue on a contended element lock.
+        def self.perform_map_element_rollback_async(**args)
+          job_id = RubyReactor::Adapters::Sidekiq::MapElementRollbackWorker.perform_async(map_element_rollback_payload(**args))
+          RubyReactor::DispatchResult.new(job_id: job_id)
+        end
+
+        def self.perform_map_element_rollback_in(delay, **args)
+          job_id = RubyReactor::Adapters::Sidekiq::MapElementRollbackWorker.perform_in(
+            delay, map_element_rollback_payload(**args)
+          )
+          RubyReactor::DispatchResult.new(job_id: job_id)
+        end
+
+        # rubocop:disable Metrics/ParameterLists
+        def self.map_element_rollback_payload(map_id:, position:, element_context_id:, reactor_class_info:,
+                                              parent_reactor_class_name:, step_name:, batch_size:, owner_context_id:,
+                                              owner_reactor_class_name:, attempt: 0)
+          {
+            "map_id" => map_id, "position" => position, "element_context_id" => element_context_id,
+            "reactor_class_info" => reactor_class_info, "parent_reactor_class_name" => parent_reactor_class_name,
+            "step_name" => step_name, "batch_size" => batch_size, "owner_context_id" => owner_context_id,
+            "owner_reactor_class_name" => owner_reactor_class_name, "attempt" => attempt
+          }
+        end
+        # rubocop:enable Metrics/ParameterLists
+        private_class_method :map_element_rollback_payload
+
         # rubocop:disable Metrics/ParameterLists
         def self.perform_map_collection_async(parent_context_id:, map_id:, parent_reactor_class_name:, step_name:,
                                               strict_ordering:, timeout:)

data/lib/ruby_reactor/context.rb

@@ -29,6 +29,12 @@ module RubyReactor
                   :cancelled, :cancellation_reason, :parent_context_id, :retried_from_id, :status, :failure_reason,
                   :middlewares
 
+    # Where this execution level's rollback stands while it is `rolling_back`
+    # (009 DM §1): `trigger`, `step`, `compensated`, `failure`, `failures`.
+    # Kept JSON-safe (string keys; `failure` / `failures` already serialized),
+    # so it round-trips unchanged. Nil otherwise.
+    attr_accessor :rollback
+
     # Transient, NOT serialized (absent from `to_h`, `serialize_for_retry`,
     # and `deserialize_from_retry` below — confirmed by
     # reentrancy_spec.rb US4-16). Overrides `StepCoordination#owner` for
@@ -76,6 +82,10 @@ module RubyReactor
       @status.to_s == "failed"
     end
 
+    def rolling_back?
+      @status.to_s == "rolling_back"
+    end
+
     def get_input(name, path = nil)
       value = Utils::FetchIndifferent.call(@inputs, name)
       return nil if value.nil?
@@ -149,7 +159,8 @@ module RubyReactor
         reactor_class: @reactor_class,
         execution_trace: @execution_trace,
         status: @status,
-        failure_reason: @failure_reason
+        failure_reason: @failure_reason,
+        rollback: @rollback
       }
     end
 
@@ -175,6 +186,7 @@ module RubyReactor
         cancellation_reason: @cancellation_reason,
         status: @status,
         failure_reason: ContextSerializer.serialize_value(@failure_reason),
+        rollback: @rollback,
         parent_context_id: @parent_context&.context_id || @parent_context_id,
         retried_from_id: @retried_from_id
       }
@@ -200,6 +212,7 @@ module RubyReactor
       context.cancellation_reason = data["cancellation_reason"]
       context.status = data["status"] || "pending"
       context.failure_reason = ContextSerializer.deserialize_value(data["failure_reason"])
+      context.rollback = data["rollback"]
       context.parent_context_id = data["parent_context_id"]
       context.retried_from_id = data["retried_from_id"]
 

data/lib/ruby_reactor/dsl/async_macros.rb

@@ -137,9 +137,38 @@ module RubyReactor
         builder = RubyReactor::Dsl::StepBuilder.new(name, impl, self)
         builder.instance_eval(&block) if block_given?
 
-        steps[name] = builder.build(async_dispatch: :step)
+        config = builder.build(async_dispatch: :step)
+        check_async_step_undo!(builder, config, caller_locations(1, 1).first)
+        steps[name] = config
       end
 
+      # An async_step is never undone: its parent does not track it for undo
+      # (008 R-09/R-10), so an `undo` on it would be dead code. An inline one
+      # is rejected; a step class's is only warned about, because the same
+      # class is legitimately reused by ordinary steps, where it does run.
+      def check_async_step_undo!(builder, config, site)
+        if config.undo_block
+          raise RubyReactor::Error::ValidationError,
+                "`undo` on async_step :#{config.name} would never run: the parent never undoes an " \
+                "independent async unit. Put failure cleanup in the unit's `compensate` (it runs in the " \
+                "unit's job when its last attempt fails) or in the reading step's `compensate`; for cleanup " \
+                "that must run when the parent rolls back, use a `step`/`compose`/`map` (tracked for undo) " \
+                "or an `async_reactor` child whose steps declare `undo`."
+        end
+
+        return unless defines_undo?(config.impl)
+
+        builder.send(:warn_definition, site, nil,
+                     "async_step :#{config.name} uses #{config.impl}; its `undo` will not run for this async " \
+                     "use (async units are never undone).")
+      end
+      private :check_async_step_undo!
+
+      def defines_undo?(impl)
+        impl.is_a?(Class) && impl < RubyReactor::Step && impl.instance_method(:undo).owner != RubyReactor::Step
+      end
+      private :defines_undo?
+
       # Dispatch a whole nested reactor to run INDEPENDENTLY — linked
       # to this one by execution id for traceability, but excluded from its
       # compensation graph. Fire-and-forget unless a later step reads

data/lib/ruby_reactor/dsl/async_reactor_builder.rb

@@ -10,7 +10,6 @@ module RubyReactor
     # ordering nonce.
     class AsyncReactorBuilder
       include RubyReactor::Dsl::TemplateHelpers
-      include RubyReactor::Dsl::Retryable
 
       attr_accessor :name, :child_reactor_class, :argument_mappings
 
@@ -19,13 +18,23 @@ module RubyReactor
         @child_reactor_class = child_reactor_class
         @reactor = reactor
         @argument_mappings = {}
-        @retry_config = nil
       end
 
       def argument(child_input_name, source)
         @argument_mappings[child_input_name] = source
       end
 
+      # A parent never retries a nested reactor as a whole (008 R-14): the
+      # child owns its steps' retries. Kept as a stub to name the replacement.
+      def retries(*)
+        raise RubyReactor::Error::DeprecatedDslError.new(
+          "`retries` on an `async_reactor` has been removed: a parent never retries a nested " \
+          "reactor as a whole. Declare `retries` on :#{@name}'s child reactor's own steps " \
+          "(`retries max_attempts: 3` in the step block or the step class); the child retries them itself.",
+          step: @name
+        )
+      end
+
       def build
         RubyReactor::Dsl::StepConfig.new(
           async_dispatch: :reactor,
@@ -41,12 +50,9 @@ module RubyReactor
           # that reads `result(:name)` and decides to fail.
           compensate_block: nil,
           undo_block: nil,
-          conditions: [],
-          guards: [],
           dependencies: dependencies_from_mappings,
           args_validator: nil,
-          output_validator: nil,
-          retry_config: @retry_config
+          output_validator: nil
         )
       end
 

data/lib/ruby_reactor/dsl/compose_builder.rb

@@ -4,7 +4,6 @@ module RubyReactor
   module Dsl
     class ComposeBuilder
       include RubyReactor::Dsl::TemplateHelpers
-      include RubyReactor::Dsl::Retryable
 
       attr_accessor :name, :composed_reactor_class, :argument_mappings
 
@@ -21,7 +20,6 @@ module RubyReactor
         end
         @reactor = reactor
         @argument_mappings = {}
-        @retry_config = nil
       end
 
       def argument(composed_input_name, source)
@@ -45,6 +43,17 @@ module RubyReactor
         )
       end
 
+      # A parent never retries a nested reactor as a whole (008 R-14): the
+      # child owns its steps' retries. Kept as a stub to name the replacement.
+      def retries(*)
+        raise RubyReactor::Error::DeprecatedDslError.new(
+          "`retries` on a `compose` has been removed: a parent never retries a nested " \
+          "reactor as a whole. Declare `retries` on :#{@name}'s child reactor's own steps " \
+          "(`retries max_attempts: 3` in the step block or the step class); the child retries them itself.",
+          step: @name
+        )
+      end
+
       def build
         warn_if_child_has_ordered_lock!
         dependencies = extract_dependencies_from_mappings
@@ -59,12 +68,9 @@ module RubyReactor
           run_block: nil,
           compensate_block: nil,
           undo_block: nil,
-          conditions: [],
-          guards: [],
           dependencies: dependencies,
           args_validator: nil,
-          output_validator: nil,
-          retry_config: @retry_config
+          output_validator: nil
         }
 
         RubyReactor::Dsl::StepConfig.new(step_config)

data/lib/ruby_reactor/dsl/definition_warnings.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module RubyReactor
+  module Dsl
+    # Definition-time warnings for the DSL builders, printed once per
+    # declaration site for the process. The including builder sets `@reactor`.
+    module DefinitionWarnings
+      def self.deprecation_sites
+        @deprecation_sites ||= Set.new
+      end
+
+      private
+
+      def warn_deprecation(site, message)
+        warn_definition(site, "DEPRECATION:", "#{message} Removal no earlier than the next MAJOR.")
+      end
+
+      def warn_definition(site, prefix, message)
+        location = "#{site.path}:#{site.lineno}"
+        return unless DefinitionWarnings.deprecation_sites.add?(location)
+
+        warn ["[RubyReactor]", prefix, location, reactor_label, message].compact.join(" ")
+      end
+
+      def reactor_label
+        @reactor&.name || @reactor.inspect
+      end
+    end
+  end
+end

data/lib/ruby_reactor/dsl/interrupt_builder.rb

@@ -73,9 +73,7 @@ module RubyReactor
           validation_schema: @validation_schema,
           max_attempts: @max_attempts,
           resume_mode: @resume_mode,
-          dependencies: @dependencies,
-          conditions: @conditions,
-          guards: @guards
+          dependencies: @dependencies
         }
 
         RubyReactor::Dsl::InterruptStepConfig.new(step_config)

data/lib/ruby_reactor/dsl/map_builder.rb

@@ -4,6 +4,7 @@ module RubyReactor
   module Dsl
     class MapBuilder
       include RubyReactor::Dsl::TemplateHelpers
+      include RubyReactor::Dsl::DefinitionWarnings
 
       attr_accessor :name, :mapped_reactor_class, :argument_mappings, :source_enumerable
 
@@ -25,7 +26,7 @@ module RubyReactor
         @batch_size = nil
         @source_enumerable = nil
         @collect_block = nil
-        @fail_fast = true # Default: stop on first error
+        @atomic = true # Default: every element succeeds, or none is kept
       end
 
       def argument(mapped_input_name, source)
@@ -41,10 +42,10 @@ module RubyReactor
       end
 
       # Run every element as its own background job. `batch_size` caps how many
-      # element jobs are enqueued at a time (back pressure); without it the whole
-      # source fans out at once. A fan-out map is a hand-off point: the reactor
-      # stops at the map and resumes in a worker once the collector has every
-      # element's outcome.
+      # element jobs one throw enqueues (back pressure), forward and rollback;
+      # without it, `Map::DEFAULT_BATCH_SIZE` (50) does. A fan-out map is a
+      # hand-off point: the reactor stops at the map and resumes in a worker
+      # once the collector has every element's outcome.
       def fan_out(enabled = true, batch_size: nil)
         @fan_out = enabled
         self.batch_size(batch_size) unless batch_size.nil?
@@ -83,11 +84,30 @@ module RubyReactor
         @collect_block = block
       end
 
+      # On (the default), the map succeeds only if every element does: the
+      # first element failure fails it, no new element starts, and every
+      # completed element is rolled back. Off, it completes with every
+      # element's outcome; a failed element rolls itself back, the others are
+      # kept.
+      def atomic(enabled = true)
+        @atomic_declared = true
+        @atomic = enabled
+      end
+
+      # The old name for `atomic` (009 R-11), which read as "stop early".
       def fail_fast(enabled = true)
-        @fail_fast = enabled
+        @fail_fast_site = caller_locations(1, 1).first
+        @atomic = enabled
+        warn_deprecation(@fail_fast_site, "map :#{@name} declares fail_fast. Use atomic (same meaning).")
       end
 
       def build
+        if @atomic_declared && @fail_fast_site
+          raise RubyReactor::Error::ValidationError.new(
+            "map :#{@name} declares both fail_fast and atomic; declare only atomic", step: @name
+          )
+        end
+
         dependencies = extract_dependencies_from_mappings
         dependencies << @source_enumerable.step_name if @source_enumerable.is_a?(RubyReactor::Template::Result)
 
@@ -123,14 +143,12 @@ module RubyReactor
             strict_ordering: { source: RubyReactor::Template::Value.new(@strict_ordering) },
             batch_size: { source: RubyReactor::Template::Value.new(@batch_size) },
             collect_block: { source: RubyReactor::Template::Value.new(@collect_block) },
-            fail_fast: { source: RubyReactor::Template::Value.new(@fail_fast) },
+            atomic: { source: RubyReactor::Template::Value.new(@atomic) },
             fan_out: { source: RubyReactor::Template::Value.new(@fan_out) }
           },
           run_block: nil,
           compensate_block: nil,
           undo_block: nil,
-          conditions: [],
-          guards: [],
           dependencies: dependencies.uniq,
           args_validator: nil,
           output_validator: nil

data/lib/ruby_reactor/dsl/step_builder.rb

@@ -7,13 +7,14 @@ module RubyReactor
       include RubyReactor::Dsl::ValidationHelpers
       include RubyReactor::Dsl::Lockable::ClassMethods
       include RubyReactor::Dsl::Retryable
+      include RubyReactor::Dsl::DefinitionWarnings
 
       COORDINATION_MACROS = {
         lock_config: "with_lock", semaphore_config: "with_semaphore", rate_limit_config: "with_rate_limit",
         period_config: "with_period", ordered_lock_config: "with_ordered_lock"
       }.freeze
 
-      attr_accessor :name, :impl, :arguments, :run_block, :compensate_block, :undo_block, :conditions, :guards,
+      attr_accessor :name, :impl, :arguments, :run_block, :compensate_block, :undo_block,
                     :dependencies, :args_validator, :output_validator
 
       def initialize(name, impl = nil, reactor = nil)
@@ -24,8 +25,6 @@ module RubyReactor
         @run_block = nil
         @compensate_block = nil
         @undo_block = nil
-        @conditions = []
-        @guards = []
         @dependencies = []
         @arg_validations = []
         @validate_args_input = nil
@@ -36,11 +35,6 @@ module RubyReactor
         @rule_sites = []
       end
 
-      # Deprecation notices print once per declaration site for the process.
-      def self.deprecation_sites
-        @deprecation_sites ||= Set.new
-      end
-
       def argument(name, source, type = nil, transform: nil, **predicates)
         @arguments[name] = {
           source: source,
@@ -78,12 +72,15 @@ module RubyReactor
         @undo_block = block
       end
 
-      def where(&predicate)
-        @conditions << predicate
+      # `where`/`guard` were a second, pre-body skip mechanism with failure
+      # rules of their own (008 R-15). A step decides to skip itself from its
+      # body instead, so both stay only to name the replacement.
+      def where(*)
+        raise_removed_condition!(:where)
       end
 
-      def guard(&guard_fn)
-        @guards << guard_fn
+      def guard(*)
+        raise_removed_condition!(:guard)
       end
 
       def wait_for(*step_names)
@@ -148,8 +145,6 @@ module RubyReactor
           run_block: @run_block,
           compensate_block: @compensate_block,
           undo_block: @undo_block,
-          conditions: @conditions,
-          guards: @guards,
           dependencies: @dependencies,
           args_validator: @args_validator || build_args_validator(@arg_validations, @validate_args_input),
           output_validator: @output_validator,
@@ -167,6 +162,15 @@ module RubyReactor
 
       private
 
+      def raise_removed_condition!(keyword)
+        raise RubyReactor::Error::DeprecatedDslError.new(
+          "`#{keyword}` inside a step block has been removed (`where`/`guard` are gone). To skip " \
+          ":#{@name}, return `Skipped(value)` (or call `skip!(value)`) from its `run` body; the " \
+          "reactor continues with that value, exactly as for a Success.",
+          step: @name
+        )
+      end
+
       # The same primitive declared BOTH inline and on the step class is
       # ambiguous — two keys for one slot of the fixed acquisition order, and
       # `StepConfig`'s readers would silently let the inline one win. Refuse it
@@ -236,27 +240,15 @@ module RubyReactor
                                               "the step instead (`validate_inputs` in #{target}).")
       end
 
-      def warn_deprecation(site, message)
-        location = "#{site.path}:#{site.lineno}"
-        return unless StepBuilder.deprecation_sites.add?(location)
-
-        warn "[RubyReactor] DEPRECATION: #{location} #{reactor_label} #{message} " \
-             "Removal no earlier than the next MAJOR."
-      end
-
       def owned_contract
         @inline_contract || (@impl.input_contract if @impl.respond_to?(:declares_inputs?) && @impl.declares_inputs?)
       end
-
-      def reactor_label
-        @reactor&.name || @reactor.inspect
-      end
     end
 
     class StepConfig
       NO_RETRIES = { max_attempts: 1, backoff: :exponential, base_delay: 1 }.freeze
 
-      attr_reader :name, :impl, :arguments, :run_block, :compensate_block, :undo_block, :conditions, :guards,
+      attr_reader :name, :impl, :arguments, :run_block, :compensate_block, :undo_block,
                   :dependencies, :args_validator, :output_validator, :async_dispatch,
                   :inline_contract
 
@@ -268,8 +260,6 @@ module RubyReactor
         @run_block = config[:run_block]
         @compensate_block = config[:compensate_block]
         @undo_block = config[:undo_block]
-        @conditions = config[:conditions] || []
-        @guards = config[:guards] || []
         @dependencies = config[:dependencies] || []
         @args_validator = config[:args_validator]
         @output_validator = config[:output_validator]
@@ -358,6 +348,51 @@ module RubyReactor
         input_contract ? input_contract.enforce!(args) : args
       end
 
+      # The step's `argument` wiring resolved against `context`: each source,
+      # then its `transform`. The one copy every process uses (StepExecutor,
+      # StepWorker). Any raise becomes an `ArgumentResolutionError`, a
+      # never-started failure attributed to this step (008 R-06) — except a
+      # park signal (a worker waiting on an async result), which is not a failure.
+      def resolve_arguments(context)
+        arguments.to_h do |arg_name, arg_config|
+          value = arg_config[:source].resolve(context)
+          value = arg_config[:transform].call(value) if arg_config[:transform]
+          [arg_name, value]
+        end
+      rescue Error::ExecutionParked
+        raise
+      rescue Error::Rescuable => e
+        raise never_started(Error::ArgumentResolutionError, "could not resolve its arguments", e)
+      end
+
+      # Rollback dispatch, the same wherever the step rolls back
+      # (CompensationManager, StepWorker): the inline block, else the class
+      # step, else Skipped — nothing defined, rollback continues. Coordination,
+      # trace and middleware stay with the caller.
+      def call_compensate(error, arguments, context)
+        catch(StepSignals::TAG) do
+          if compensate_block
+            compensate_block.call(error, wrap_inputs(arguments), context)
+          elsif has_impl?
+            impl.compensate(error, arguments, context)
+          else
+            RubyReactor.Skipped()
+          end
+        end
+      end
+
+      def call_undo(result_value, arguments, context)
+        catch(StepSignals::TAG) do
+          if undo_block
+            undo_block.call(result_value, wrap_inputs(arguments), context)
+          elsif has_impl?
+            impl.undo(result_value, arguments, context)
+          else
+            RubyReactor.Skipped()
+          end
+        end
+      end
+
       # The step's work as a reactor runs it. Coordination is NOT taken here:
       # the caller (StepExecutor / StepWorker) takes this config's effective
       # declarations — inline and class alike — in one fixed order around it.
@@ -381,6 +416,27 @@ module RubyReactor
         !@async_dispatch.nil?
       end
 
+      # Whether a success of this step is recorded for undo. `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 (008 R-10).
+      def rollback_tracked?
+        !async_dispatch?
+      end
+
+      # Whether a run of this step cut short by an interruption is still
+      # tracked for undo: the construct's own definition decides (008 R-16).
+      def undoes_partial_run?
+        rollback_tracked? && has_impl? && impl.respond_to?(:undoes_partial_run?) && impl.undoes_partial_run?
+      end
+
+      # What the undo record keeps of the step's resolved arguments: all of
+      # them, unless the step reads its rollback state elsewhere (a map reads
+      # its declaration and the map records, 009 R-14).
+      def rollback_arguments(resolved)
+        has_impl? && impl.respond_to?(:rollback_arguments) ? impl.rollback_arguments(resolved) : resolved
+      end
+
       def has_impl?
         !@impl.nil?
       end
@@ -403,14 +459,17 @@ module RubyReactor
         (retry_config[:max_attempts] || 0) > 1
       end
 
-      def should_run?(context)
-        @conditions.all? { |condition| condition.call(context) } &&
-          @guards.all? { |guard| guard.call(context) }
-      end
-
       def interrupt?
         false
       end
+
+      private
+
+      def never_started(error_class, what, cause)
+        error = error_class.new("Step '#{name}' #{what}: #{cause.message}", step: name, original_error: cause)
+        error.set_backtrace(cause.backtrace)
+        error
+      end
     end
   end
 end

data/lib/ruby_reactor/error/argument_resolution_error.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module RubyReactor
+  module Error
+    # A step's `argument` source, `transform` or result path raised. The step's
+    # body never started, so it is never compensated; completed steps are
+    # undone (008 R-06). The same inputs fail the same way, so never retried.
+    class ArgumentResolutionError < Base
+      attr_reader :exception_class
+
+      def initialize(message, step:, original_error:, context: nil)
+        super(message, step: step, context: context, original_error: original_error)
+        @exception_class = original_error.class.name
+      end
+
+      def retryable? = false
+    end
+  end
+end

data/lib/ruby_reactor/error/rescuable.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module RubyReactor
+  module Error
+    # `rescue Error::Rescuable` catches every exception reactor code can raise —
+    # standard or not (`NotImplementedError`, `SystemStackError`, a custom
+    # `Exception` subclass) — so it fails its step and rolls back (008 R-16).
+    #
+    # It lets through only interruptions: exceptions raised INTO running code
+    # from outside it. A signal (incl. `Interrupt`, `Sidekiq::Shutdown`), an
+    # exit, running out of memory, and the one an enclosing `Timeout.timeout`
+    # 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?(RollbackHandedOff)
+      end
+
+      def self.interruption?(exception)
+        INTERRUPTIONS.any? { |klass| exception.is_a?(klass) } ||
+          (defined?(::Timeout::ExitException) && exception.is_a?(::Timeout::ExitException))
+      end
+    end
+  end
+end