ruby_reactor 0.8.2 → 0.8.4

data/lib/ruby_reactor/dsl/async_reactor_builder.rb

@@ -10,6 +10,7 @@ module RubyReactor
     # ordering nonce.
     class AsyncReactorBuilder
       include RubyReactor::Dsl::TemplateHelpers
+      include RubyReactor::Dsl::Retryable
 
       attr_accessor :name, :child_reactor_class, :argument_mappings
 
@@ -18,17 +19,13 @@ module RubyReactor
         @child_reactor_class = child_reactor_class
         @reactor = reactor
         @argument_mappings = {}
-        @retry_config = {}
+        @retry_config = nil
       end
 
       def argument(child_input_name, source)
         @argument_mappings[child_input_name] = source
       end
 
-      def retries(max_attempts: 3, backoff: :exponential, base_delay: 1)
-        @retry_config = { max_attempts: max_attempts, backoff: backoff, base_delay: base_delay }
-      end
-
       def build
         RubyReactor::Dsl::StepConfig.new(
           async_dispatch: :reactor,
@@ -49,7 +46,7 @@ module RubyReactor
           dependencies: dependencies_from_mappings,
           args_validator: nil,
           output_validator: nil,
-          retry_config: @retry_config.empty? ? (@reactor&.retry_defaults || {}) : @retry_config
+          retry_config: @retry_config
         )
       end
 

data/lib/ruby_reactor/dsl/compose_builder.rb

@@ -4,6 +4,7 @@ module RubyReactor
   module Dsl
     class ComposeBuilder
       include RubyReactor::Dsl::TemplateHelpers
+      include RubyReactor::Dsl::Retryable
 
       attr_accessor :name, :composed_reactor_class, :argument_mappings
 
@@ -20,7 +21,7 @@ module RubyReactor
         end
         @reactor = reactor
         @argument_mappings = {}
-        @retry_config = {}
+        @retry_config = nil
       end
 
       def argument(composed_input_name, source)
@@ -44,14 +45,6 @@ module RubyReactor
         )
       end
 
-      def retries(max_attempts: 3, backoff: :exponential, base_delay: 1)
-        @retry_config = {
-          max_attempts: max_attempts,
-          backoff: backoff,
-          base_delay: base_delay
-        }
-      end
-
       def build
         warn_if_child_has_ordered_lock!
         dependencies = extract_dependencies_from_mappings
@@ -71,7 +64,7 @@ module RubyReactor
           dependencies: dependencies,
           args_validator: nil,
           output_validator: nil,
-          retry_config: @retry_config.empty? ? (@reactor&.retry_defaults || {}) : @retry_config
+          retry_config: @retry_config
         }
 
         RubyReactor::Dsl::StepConfig.new(step_config)

data/lib/ruby_reactor/dsl/interrupt_builder.rb

@@ -42,6 +42,20 @@ module RubyReactor
               "`validate_payload`."
       end
 
+      # Step-level coordination is refused on an interrupt (research D6): its
+      # body is split across a pause, so a hold taken before the pause would
+      # span the gap — held by nothing while the workflow waits, potentially
+      # forever. `StepBuilder` (the superclass) gains the five macros once
+      # `Lockable` is hosted there; these overrides make sure an interrupt
+      # never inherits them silently (Finding 3).
+      %i[with_lock with_semaphore with_rate_limit with_period with_ordered_lock].each do |macro|
+        define_method(macro) do |*, **|
+          raise RubyReactor::Error::ValidationError,
+                "interrupt :#{@name} cannot declare step-level coordination: its body is split across a pause, " \
+                "so a hold would span the gap. Declare it on the reactor (with_lock etc.) instead."
+        end
+      end
+
       # Deprecated alias for {#validate_payload}.
       def validate(schema = nil, &block)
         unless @warned_validate

data/lib/ruby_reactor/dsl/lockable.rb

@@ -10,6 +10,23 @@ module RubyReactor
       module ClassMethods
         attr_reader :lock_config, :semaphore_config, :period_config, :rate_limit_config, :ordered_lock_config
 
+        # The five configs, nils compacted. Reactors get this too (additive);
+        # steps use it to decide whether `StepCoordination` needs building at
+        # all (`StepCoordination.none?`).
+        def coordination_declarations
+          {
+            lock: lock_config,
+            semaphore: semaphore_config,
+            rate_limit: rate_limit_config,
+            period: period_config,
+            ordered_lock: ordered_lock_config
+          }.compact
+        end
+
+        def declares_coordination?
+          !coordination_declarations.empty?
+        end
+
         # Propagate lock/semaphore/period/rate-limit config to subclasses;
         # without this a subclass of a configured reactor would silently lose
         # those settings.
@@ -22,39 +39,65 @@ module RubyReactor
           subclass.instance_variable_set(:@ordered_lock_config, @ordered_lock_config) if @ordered_lock_config
         end
 
-        # Configure locking for this reactor
+        # Configure locking for this reactor or step
         # @param ttl [Integer] Time to live in seconds (default: 60)
         # @param wait [Integer] Time to wait for lock in seconds (default: 0)
         # @param auto_extend [Boolean] When true (default), a background thread
         #   refreshes the lock TTL every ttl/3 seconds while the reactor runs,
         #   protecting steps that may legitimately outlast `ttl`. Pass `false`
         #   to disable and rely solely on `ttl` for expiry.
-        # @yield [inputs] Block that returns the lock key string
-        def with_lock(ttl: 60, wait: 0, auto_extend: true, &block)
+        # @param rollback_wait [Numeric, nil] STEP only (accepted and ignored on
+        #   a reactor, whose holds are not re-taken for rollback): how long the
+        #   step's `undo`/`compensate` waits to re-take this lock. Defaults to
+        #   `ttl` — a forward holder either finishes or expires within it.
+        #   Rollback never parks: in a worker the wait blocks the thread. An
+        #   undo that cannot re-take the key in time is reported on
+        #   `Failure#rollback_failures`.
+        # @yield [inputs] Block that returns the lock key string. On a reactor,
+        #   `inputs` is the reactor's inputs; on a step, it is the step's own
+        #   resolved arguments (contract defaults applied).
+        def with_lock(ttl: 60, wait: 0, auto_extend: true, rollback_wait: nil, &block)
+          validate_rollback_wait!(rollback_wait)
           @lock_config = {
             ttl: ttl,
             wait: wait,
             auto_extend: auto_extend,
+            rollback_wait: rollback_wait,
             key_proc: block
           }
         end
 
-        # Configure semaphore for this reactor
+        # Configure semaphore for this reactor or step
         # @param limit [Integer] Maximum concurrent executions
         # @param wait [Integer] Time to wait for a token in seconds (default: 0)
-        # @yield [inputs] Block that returns the semaphore key string
-        def with_semaphore(limit:, wait: 0, &block)
+        # @param rollback_wait [Numeric, nil] STEP only, as for `with_lock`.
+        #   Defaults to 60 seconds: a semaphore slot has no hold expiry.
+        # @yield [inputs] Block that returns the semaphore key string. On a
+        #   reactor, `inputs` is the reactor's inputs; on a step, it is the
+        #   step's own resolved arguments.
+        def with_semaphore(limit:, wait: 0, rollback_wait: nil, &block)
+          validate_rollback_wait!(rollback_wait)
           @semaphore_config = {
             limit: limit,
             wait: wait,
+            rollback_wait: rollback_wait,
             key_proc: block
           }
         end
 
-        # Configure a calendar-aligned dedup window for this reactor. The
-        # reactor will run at most once per bucket per key; subsequent calls
-        # in the same bucket return `RubyReactor::Halt` without executing
-        # any steps.
+        def validate_rollback_wait!(value)
+          return if value.nil? || (value.is_a?(Numeric) && value >= 0)
+
+          raise ArgumentError, "rollback_wait must be a number of seconds >= 0 (got #{value.inspect})"
+        end
+        private :validate_rollback_wait!
+
+        # Configure a calendar-aligned dedup window for this reactor or step.
+        # On a reactor, a hit returns `RubyReactor::Halt` without executing
+        # any steps. On a STEP, a hit instead skips just that step
+        # (`RubyReactor.Skipped(reason: :period)`) — halting the whole
+        # workflow over one deduplicated step would defeat the point of
+        # declaring it at step level; the rest of the workflow runs normally.
         #
         # Note: `with_period` is *dedup*, not *concurrency*. Two concurrent
         # racers can both see no marker and both run. Pair with `with_lock`
@@ -64,7 +107,9 @@ module RubyReactor
         #   :month / :year, or an integer number of seconds for a sliding
         #   bucket (index = `time.to_i / every`).
         # @yield [inputs] Block that returns the period key base. The final
-        #   Redis marker key is `period:<base>:<bucket_id>`.
+        #   Redis marker key is `period:<base>:<bucket_id>`. On a reactor,
+        #   `inputs` is the reactor's inputs; on a step, it is the step's own
+        #   resolved arguments.
         def with_period(every:, &block)
           # Validate eagerly so misconfiguration surfaces at class load time.
           RubyReactor::Period.period_seconds(every)
@@ -75,11 +120,13 @@ module RubyReactor
           }
         end
 
-        # Configure strict-ordering nonce gating for this reactor. A
-        # monotonically increasing nonce is assigned at enqueue time; the
-        # worker can only proceed when its nonce equals `last_completed + 1`.
-        # Otherwise the worker raises {OrderedLock::WaitError} and the Sidekiq
-        # worker snoozes via `perform_in`.
+        # Configure strict-ordering nonce gating for this reactor or step. On
+        # a reactor, a monotonically increasing nonce is assigned at enqueue
+        # time; the worker can only proceed when its nonce equals
+        # `last_completed + 1`. Otherwise the worker raises
+        # {OrderedLock::WaitError} and the Sidekiq worker snoozes via
+        # `perform_in`. On a step, the nonce is assigned on first arrival
+        # instead — see the `@yield` note below.
         #
         # Counters reset to 0 once the sequence fully drains (last_completed
         # catches up to next). Re-entrancy is NOT supported — a nested reactor
@@ -101,7 +148,13 @@ module RubyReactor
         #   check only applies to a fresh `execute`; an already-started run
         #   that paused (InterruptResult/DispatchResult) completes on resume even
         #   if the chain failed in the meantime.
-        # @yield [inputs] Block that returns the ordered-lock key string.
+        # @yield [inputs] Block that returns the ordered-lock key string. On a
+        #   STEP, the position is assigned when the execution first REACHES
+        #   the step (its key reads step arguments, which do not exist until
+        #   then), so executions are ordered by ARRIVAL at that step, not by
+        #   enqueue — identical to the reactor form only when the step is
+        #   first in its reactor. The deeper the step, the weaker the
+        #   promise (research D8, contract §1).
         def with_ordered_lock(poison_pill_timeout: OrderedLock::DEFAULT_POISON_PILL_TIMEOUT,
                               ttl: OrderedLock::DEFAULT_TTL,
                               strict: true,
@@ -114,9 +167,9 @@ module RubyReactor
           }
         end
 
-        # Configure rate limiting for this reactor (fixed-window counter).
-        # Pass either a single window via `limit:` + `period:`, or a hash of
-        # windows via `limits:` for layered API quotas.
+        # Configure rate limiting for this reactor or step (fixed-window
+        # counter). Pass either a single window via `limit:` + `period:`, or
+        # a hash of windows via `limits:` for layered API quotas.
         #
         # @example Single window
         #   with_rate_limit(limit: 3, period: :second) { |i| "stripe:#{i[:account_id]}" }
@@ -138,7 +191,9 @@ module RubyReactor
         #   :week / :month / :year, or integer seconds (single-window form)
         # @param limits [Hash{Symbol,Integer => Integer}] mapping of period
         #   unit to limit (multi-window form)
-        # @yield [inputs] Block returning the rate-limit key base (inline forms).
+        # @yield [inputs] Block returning the rate-limit key base (inline
+        #   forms). On a reactor, `inputs` is the reactor's inputs; on a
+        #   step, it is the step's own resolved arguments.
         def with_rate_limit(name = nil, limit: nil, period: nil, limits: nil, &block)
           if name
             if limit || period || limits || block

data/lib/ruby_reactor/dsl/reactor.rb

@@ -11,7 +11,6 @@ module RubyReactor
         base.instance_variable_set(:@middlewares, [])
         base.instance_variable_set(:@input_validations, {})
         base.instance_variable_set(:@background_handoff, nil)
-        base.instance_variable_set(:@retry_defaults, { max_attempts: 3, backoff: :exponential, base_delay: 1 })
       end
 
       module ClassMethods
@@ -55,16 +54,14 @@ module RubyReactor
                 "inputs inside the worker."
         end
 
-        def retry_defaults(**kwargs)
-          if kwargs.empty?
-            @retry_defaults ||= { max_attempts: 1, backoff: :exponential, base_delay: 1 }
-          else
-            @retry_defaults = {
-              max_attempts: kwargs[:max_attempts] || 1,
-              backoff: kwargs[:backoff] || :exponential,
-              base_delay: kwargs[:base_delay] || 1
-            }
-          end
+        # Reactor-wide retry defaults are gone: the builders snapshotted them at
+        # `step` time, so they silently applied only to steps declared AFTER
+        # the `retry_defaults` line. A step's retry policy now lives on the step.
+        def retry_defaults(*, **)
+          raise RubyReactor::Error::DeprecatedDslError,
+                "`retry_defaults` has been removed from #{name || "this reactor"}: reactor-wide defaults " \
+                "silently applied only to steps declared after them. Declare `retries` on each step class " \
+                "(or step block) that should retry; a step with no `retries` runs once."
         end
 
         # rubocop:disable Metrics/ParameterLists

data/lib/ruby_reactor/dsl/retryable.rb

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

data/lib/ruby_reactor/dsl/step_builder.rb

@@ -5,9 +5,16 @@ module RubyReactor
     class StepBuilder
       include RubyReactor::Dsl::TemplateHelpers
       include RubyReactor::Dsl::ValidationHelpers
+      include RubyReactor::Dsl::Lockable::ClassMethods
+      include RubyReactor::Dsl::Retryable
+
+      COORDINATION_MACROS = {
+        lock_config: "with_lock", semaphore_config: "with_semaphore", rate_limit_config: "with_rate_limit",
+        period_config: "with_period", ordered_lock_config: "with_ordered_lock"
+      }.freeze
 
       attr_accessor :name, :impl, :arguments, :run_block, :compensate_block, :undo_block, :conditions, :guards,
-                    :dependencies, :args_validator, :output_validator, :retry_config
+                    :dependencies, :args_validator, :output_validator
 
       def initialize(name, impl = nil, reactor = nil)
         @name = name
@@ -24,7 +31,7 @@ module RubyReactor
         @validate_args_input = nil
         @args_validator = nil
         @output_validator = nil
-        @retry_config = {}
+        @retry_config = nil
         @inline_contract = nil
         @rule_sites = []
       end
@@ -124,19 +131,13 @@ module RubyReactor
         )
       end
 
-      def retries(max_attempts: 3, backoff: :exponential, base_delay: 1)
-        @retry_config = {
-          max_attempts: max_attempts,
-          backoff: backoff,
-          base_delay: base_delay
-        }
-      end
-
       # `async_dispatch` marks a step whose work is dispatched as an independent
       # unit rather than run inline — `:step` for `async_step`, `:reactor` for
       # `async_reactor`. Nil for an ordinary step.
       def build(async_dispatch: nil)
         check_contract_conflicts!
+        check_coordination_conflicts!
+        check_retry_conflict!
         warn_deprecated_rules
 
         step_config = {
@@ -153,7 +154,12 @@ module RubyReactor
           args_validator: @args_validator || build_args_validator(@arg_validations, @validate_args_input),
           output_validator: @output_validator,
           inline_contract: @inline_contract,
-          retry_config: @retry_config.empty? ? (@reactor&.retry_defaults || {}) : @retry_config
+          retry_config: @retry_config,
+          lock_config: @lock_config,
+          semaphore_config: @semaphore_config,
+          rate_limit_config: @rate_limit_config,
+          period_config: @period_config,
+          ordered_lock_config: @ordered_lock_config
         }
 
         RubyReactor::Dsl::StepConfig.new(step_config)
@@ -161,6 +167,33 @@ module RubyReactor
 
       private
 
+      # 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
+      # at class-definition time rather than pick a winner silently.
+      def check_coordination_conflicts!
+        return unless @impl
+
+        COORDINATION_MACROS.each do |reader, macro|
+          next unless instance_variable_get(:"@#{reader}")
+          next unless @impl.respond_to?(reader) && @impl.public_send(reader)
+
+          raise Error::ValidationError,
+                "#{reactor_label} step :#{@name} declares `#{macro}` inline, but #{@impl} declares it too. " \
+                "Keep ONE: drop the inline declaration to use #{@impl}'s, or remove it from #{@impl}."
+        end
+      end
+
+      # Same rule as the coordination macros: one retry policy per step.
+      def check_retry_conflict!
+        return unless @retry_config && @impl.respond_to?(:retry_config) && @impl.retry_config
+
+        raise Error::ValidationError,
+              "#{reactor_label} step :#{@name} declares `retries` inline, but #{@impl} declares it too. " \
+              "Keep ONE: drop the inline declaration to use #{@impl}'s, or remove it from #{@impl}. " \
+              "To vary the policy per workflow, subclass #{@impl} and declare `retries` there."
+      end
+
       # A step that owns its input contract takes wiring only from the
       # reactor: rules here would be a second, overlapping rule set.
       def check_contract_conflicts!
@@ -221,8 +254,10 @@ module RubyReactor
     end
 
     class StepConfig
+      NO_RETRIES = { max_attempts: 1, backoff: :exponential, base_delay: 1 }.freeze
+
       attr_reader :name, :impl, :arguments, :run_block, :compensate_block, :undo_block, :conditions, :guards,
-                  :dependencies, :args_validator, :output_validator, :retry_config, :async_dispatch,
+                  :dependencies, :args_validator, :output_validator, :async_dispatch,
                   :inline_contract
 
       def initialize(config)
@@ -239,7 +274,104 @@ module RubyReactor
         @args_validator = config[:args_validator]
         @output_validator = config[:output_validator]
         @inline_contract = config[:inline_contract]
-        @retry_config = { max_attempts: 1 }.merge(config[:retry_config] || {})
+        @retry_config = config[:retry_config]
+        @lock_config = config[:lock_config]
+        @semaphore_config = config[:semaphore_config]
+        @rate_limit_config = config[:rate_limit_config]
+        @period_config = config[:period_config]
+        @ordered_lock_config = config[:ordered_lock_config]
+      end
+
+      # A step's EFFECTIVE coordination: its own (inline) declaration if it has
+      # one, else the class step's (`impl`). Every consumer — forward
+      # execution, rollback, the dispatch guard, the dashboard — reads only
+      # these five readers, so a step mixing inline and class declarations is
+      # acquired by ONE `StepCoordination` in one global order. The two sources
+      # can never both carry the SAME primitive (`check_coordination_conflicts!`
+      # rejects that at class-definition time), so this is a union.
+      def lock_config
+        @lock_config || (impl.lock_config if impl.respond_to?(:lock_config))
+      end
+
+      # A step's EFFECTIVE retry policy, resolved like the coordination
+      # readers: its own (step block) declaration, else the class step's,
+      # else a single attempt. Never nil. The reactor is never consulted.
+      def retry_config
+        @retry_config || (impl.retry_config if impl.respond_to?(:retry_config)) || NO_RETRIES
+      end
+
+      # Where `retry_config` came from: :step_block, :step_class or :none.
+      def retry_source
+        return :step_block if @retry_config
+        return :step_class if impl.respond_to?(:retry_config) && impl.retry_config
+
+        :none
+      end
+
+      def semaphore_config
+        @semaphore_config || (impl.semaphore_config if impl.respond_to?(:semaphore_config))
+      end
+
+      def rate_limit_config
+        @rate_limit_config || (impl.rate_limit_config if impl.respond_to?(:rate_limit_config))
+      end
+
+      def period_config
+        @period_config || (impl.period_config if impl.respond_to?(:period_config))
+      end
+
+      def ordered_lock_config
+        @ordered_lock_config || (impl.ordered_lock_config if impl.respond_to?(:ordered_lock_config))
+      end
+
+      def coordination_declarations
+        {
+          lock: lock_config,
+          semaphore: semaphore_config,
+          rate_limit: rate_limit_config,
+          period: period_config,
+          ordered_lock: ordered_lock_config
+        }.compact
+      end
+
+      def declares_coordination?
+        !coordination_declarations.empty?
+      end
+
+      # The ONE derivation of what a step's body — and therefore every
+      # coordination key — receives: an inline step with no `argument` wiring
+      # gets the reactor's inputs, and the step's contract applies its
+      # defaults. Forward execution (`body_arguments`), rollback, the async
+      # dispatch guard and the dashboard all go through here, so a key can
+      # never be computed from different values in different places.
+      # Never raises — `enforce!` returns exactly `apply_defaults(args)` when
+      # the arguments are valid, and rollback must not fail on invalid ones.
+      def coordination_arguments(resolved, inputs)
+        args = has_run_block? && resolved.empty? ? inputs : resolved
+        input_contract && args.is_a?(Hash) ? input_contract.apply_defaults(args) : args
+      end
+
+      # `coordination_arguments`, validated: raises InputValidationError
+      # BEFORE any coordination is taken (Finding 8).
+      def body_arguments(resolved, inputs)
+        args = has_run_block? && resolved.empty? ? inputs : resolved
+        input_contract ? input_contract.enforce!(args) : args
+      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.
+      def call_body(arguments, context)
+        catch(StepSignals::TAG) do
+          if has_run_block?
+            run_block.call(wrap_inputs(arguments), context)
+          elsif impl.respond_to?(:run_without_coordination)
+            impl.run_without_coordination(arguments, context)
+          else
+            # A duck-typed impl (any `.run(args, ctx)`) never coordinates itself.
+            impl.run(arguments, context)
+          end
+        end
       end
 
       # True for `async_step` / `async_reactor` — the step's work leaves this
@@ -262,6 +394,11 @@ module RubyReactor
         !@run_block.nil?
       end
 
+      # What an inline `run`/`undo`/`compensate` block receives as its inputs.
+      def wrap_inputs(arguments)
+        RubyReactor::Step::Inputs.new(arguments, contract: input_contract, owner: "step :#{name}")
+      end
+
       def retryable?
         (retry_config[:max_attempts] || 0) > 1
       end

data/lib/ruby_reactor/error/async_result_pending.rb

@@ -9,7 +9,7 @@ module RubyReactor
     # re-enqueues itself via the snooze path, and the wait resumes on
     # redelivery. Bounded by `Configuration#async_park_timeout`, enforced at
     # the wait site before this is raised.
-    class AsyncResultPending < Base
+    class AsyncResultPending < ExecutionParked
       attr_reader :channel
 
       def initialize(message, channel: nil)

data/lib/ruby_reactor/error/execution_parked.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module RubyReactor
+  module Error
+    # Base for the internal "this execution parks" signals raised inside a
+    # worker (`inline_async_execution`). Never persisted, never reaches a
+    # synchronous caller.
+    #
+    # Contract: every rescue between the raise site and the final handler
+    # (`Worker#perform`, or `Map::ElementExecutor` for a map element) either
+    # re-raises it untouched, or parks its own holds and then re-raises. The
+    # requeue happens once, at the top, after every executor on the stack has
+    # parked and saved.
+    class ExecutionParked < Base; end
+  end
+end

data/lib/ruby_reactor/error/reactor_contention_park.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module RubyReactor
+  module Error
+    # A composed child's OWN reactor-level lock, semaphore or rate limit was
+    # contended inside a worker, before the child was admitted. Nothing between
+    # the child and the worker snoozes a nested executor's contention error, so
+    # the child raises this park signal instead: every executor above it keeps
+    # its holds, and the worker requeues the job. Carries the contention error,
+    # and delegates `original`/`retry_after_seconds` to it so `Worker.snooze_delay`
+    # and `Worker.hinted_retry?` treat it exactly like the error it wraps (as
+    # `StepContentionPark` does).
+    class ReactorContentionPark < ExecutionParked
+      attr_reader :original
+
+      def initialize(original)
+        super(original.message)
+        @original = original
+      end
+
+      def retry_after_seconds
+        original.retry_after_seconds if original.respond_to?(:retry_after_seconds)
+      end
+    end
+  end
+end

data/lib/ruby_reactor/error/step_contention_park.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module RubyReactor
+  module Error
+    # A step's own coordination was contended inside a worker: park the
+    # execution at that step. Carries the `StepCoordination::Contended`, and
+    # delegates `original`/`retry_after_seconds` to it so `Worker.snooze_delay`
+    # and `Worker.hinted_retry?` treat it exactly like the contention it wraps.
+    class StepContentionPark < ExecutionParked
+      attr_reader :contended
+
+      def initialize(contended)
+        super(contended.message)
+        @contended = contended
+      end
+
+      def original
+        contended.original
+      end
+
+      def retry_after_seconds
+        contended.retry_after_seconds
+      end
+    end
+  end
+end

data/lib/ruby_reactor/error/undeclared_input_error.rb

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