ruby_reactor 0.8.2 → 0.8.3

data/lib/ruby_reactor/context.rb

@@ -29,6 +29,19 @@ module RubyReactor
                   :cancelled, :cancellation_reason, :parent_context_id, :retried_from_id, :status, :failure_reason,
                   :middlewares
 
+    # 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
+    # everything coordinated with this context (research D5): set by the
+    # `async_step` worker to a per-job id so re-entrancy never crosses a
+    # process hand-off (US4-5).
+    attr_accessor :coordination_owner
+
+    # Transient, NOT serialized: the step whose coordination hook is firing
+    # right now (set by `StepCoordination#emit` for the duration of the hook),
+    # so a middleware can tell a step-level hold from a reactor-level one.
+    attr_accessor :coordinating_step
+
     def initialize(inputs = {}, reactor_class = nil)
       @context_id = SecureRandom.uuid
       @inputs = inputs
@@ -95,6 +108,19 @@ module RubyReactor
       @intermediate_results[step_name.to_sym] = value
     end
 
+    # Set once this execution's reactor-level gates (rate limit, period,
+    # post-lock period re-check) have passed, and never unset — it rides
+    # `private_data`, so it survives parks, retries, pauses and redeliveries.
+    # "Is this a fresh run?" reads it instead of inferring from
+    # `current_step`, which is only the resume cursor (005 R-03).
+    def admitted?
+      !!(private_data[:admitted] || private_data["admitted"])
+    end
+
+    def admit!
+      private_data[:admitted] = true
+    end
+
     def with_step(step_name)
       old_step = @current_step
       @current_step = step_name

data/lib/ruby_reactor/context_serializer.rb

@@ -57,7 +57,8 @@ module RubyReactor
             "file_path" => value.file_path,
             "line_number" => value.line_number,
             "code_snippet" => serialize_value(value.code_snippet),
-            "validation_errors" => serialize_value(value.validation_errors)
+            "validation_errors" => serialize_value(value.validation_errors),
+            "rollback_failures" => serialize_value(value.rollback_failures)
           }
         when RubyReactor::Context
           { "_type" => "Context", "value" => value.serialize_for_retry }
@@ -140,7 +141,8 @@ module RubyReactor
                 file_path: value["file_path"],
                 line_number: value["line_number"],
                 code_snippet: deserialize_value(value["code_snippet"]),
-                validation_errors: deserialize_value(value["validation_errors"])
+                validation_errors: deserialize_value(value["validation_errors"]),
+                rollback_failures: deserialize_value(value["rollback_failures"])
               )
             when "Context"
               Context.deserialize_from_retry(value["value"])

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

@@ -5,6 +5,12 @@ module RubyReactor
     class StepBuilder
       include RubyReactor::Dsl::TemplateHelpers
       include RubyReactor::Dsl::ValidationHelpers
+      include RubyReactor::Dsl::Lockable::ClassMethods
+
+      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
@@ -137,6 +143,7 @@ module RubyReactor
       # `async_reactor`. Nil for an ordinary step.
       def build(async_dispatch: nil)
         check_contract_conflicts!
+        check_coordination_conflicts!
         warn_deprecated_rules
 
         step_config = {
@@ -153,7 +160,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.empty? ? (@reactor&.retry_defaults || {}) : @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 +173,23 @@ 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
+
       # 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!
@@ -240,6 +269,88 @@ module RubyReactor
         @output_validator = config[:output_validator]
         @inline_contract = config[:inline_contract]
         @retry_config = { max_attempts: 1 }.merge(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
+
+      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(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

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/executor/async_step_dispatch.rb

@@ -28,6 +28,14 @@ module RubyReactor
           return RubyReactor.Success(nil)
         end
 
+        deadlock = check_async_step_deadlock(step_config)
+        # Through the normal step-failure handler, never returned bare: a bare
+        # Failure goes straight back to `Executor#execute`, which marks the
+        # context failed WITHOUT rolling back — leaving an earlier step's side
+        # effect uncompensated. `handle_step_result` compensates and raises the
+        # `StepFailureError` the executor's own rescue chain expects.
+        return @result_handler.handle_step_result(step_config, deadlock, {}) if deadlock
+
         record_async_step_dispatch(step_config)
         enqueue_async_step(step_config)
 
@@ -43,6 +51,101 @@ module RubyReactor
         !storage.retrieve_step_result(@context.context_id, step_config.name, async_step_class_name).nil?
       end
 
+      # US4/T034: an `async_step` whose step class declares a key this
+      # execution currently holds would deadlock exactly like `async_reactor`
+      # dispatching into one — refuse before the durable record is written or
+      # the job is enqueued, naming the key (Step::AsyncReactorStep's guard
+      # already covers `async_reactor`; this reuses its message and registry).
+      def check_async_step_deadlock(step_config)
+        held = Step::AsyncReactorStep.held_lock_keys(@context)
+        return nil if held.empty?
+
+        # Only lock and a limit-1 semaphore have the circular-wait shape this
+        # guard defends against (same registry `with_lock`/limit-1
+        # `with_semaphore` push to, T032). Rate limit, period, and the
+        # ordered lock never enter `held_lock_keys`, so they cannot deadlock
+        # a hand-off and are deliberately not checked here.
+        lock_config = step_config.lock_config
+        semaphore_config = step_config.semaphore_config
+        return nil unless lock_config || (semaphore_config && semaphore_config[:limit] == 1)
+
+        args = resolve_args_for_deadlock_check(step_config)
+        return args if args.is_a?(RubyReactor::Failure) # KeyError or "skip, can't resolve without blocking"
+        return nil if args.nil? # skipped — non-blocking resolution was not possible
+
+        collision = async_step_lock_keys(lock_config, semaphore_config, args, step_config)
+                    .find { |key| held.include?(key) }
+        return nil unless collision
+
+        # A never-started error, not a bare message: the step was neither
+        # dispatched nor run, so rollback must not compensate it.
+        message = Step::AsyncReactorStep.deadlock_message(collision, "#{@reactor_class&.name}##{step_config.name}",
+                                                          @context, kind: "async_step")
+        never_started_failure(Executor::StepCoordination::DispatchRefused.new(message, step: step_config.name),
+                              step_config)
+      rescue Executor::StepCoordination::KeyError => e
+        # A guard key that cannot be computed is the same non-retryable step
+        # failure the real acquisition would raise (FR-007) — never a generic
+        # execution error, which would skip rollback of the earlier steps.
+        never_started_failure(e, step_config)
+      end
+
+      # Through `StepCoordination.resolve_key`, so a nil/empty or raising key
+      # proc fails here exactly as it would at acquisition time.
+      def async_step_lock_keys(lock_config, semaphore_config, args, step_config)
+        keys = []
+        keys << Executor::StepCoordination.resolve_key(lock_config, args, step_config.name) if lock_config
+        if semaphore_config && semaphore_config[:limit] == 1
+          keys << Executor::StepCoordination.resolve_key(semaphore_config, args, step_config.name)
+        end
+        keys.compact
+      end
+
+      def never_started_failure(error, step_config)
+        RubyReactor::Failure(error, step_name: step_config.name, reactor_name: @reactor_class&.name,
+                                    retryable: false)
+      end
+
+      # Finding 5: `async_step` defers argument resolution to the worker, so
+      # computing the key here means resolving early — safe UNLESS an
+      # argument reads a still-pending async result, which would BLOCK (or
+      # park) this dispatching step just to run a guard check. Detect that
+      # case without calling `.resolve` at all, skip the guard, and log it.
+      def resolve_args_for_deadlock_check(step_config)
+        if step_config.arguments.values.any? { |cfg| pending_async_source?(cfg[:source]) }
+          log_guard_skipped(step_config)
+          return nil
+        end
+
+        resolved = {}
+        step_config.arguments.each do |name, cfg|
+          value = cfg[:source].resolve(@context)
+          value = cfg[:transform].call(value) if cfg[:transform]
+          resolved[name] = value
+        end
+        # The worker keys off `coordination_arguments` of these same values;
+        # anything else here would let a self-deadlocking job through.
+        step_config.coordination_arguments(resolved, @context.inputs)
+      rescue Executor::StepCoordination::KeyError => e
+        never_started_failure(e, step_config)
+      end
+
+      def pending_async_source?(source)
+        return false unless source.is_a?(RubyReactor::Template::Result)
+        return false if @context.intermediate_results.key?(source.step_name.to_sym) ||
+                        @context.intermediate_results.key?(source.step_name.to_s)
+
+        ref = @context.composed_contexts[source.step_name] || @context.composed_contexts[source.step_name.to_s]
+        ref.is_a?(Hash) && %i[async_step_ref async_reactor_ref].include?(ref[:type]&.to_sym)
+      end
+
+      def log_guard_skipped(step_config)
+        configuration.logger.info(
+          "event=\"ruby_reactor.step_coordination.guard_skipped\" reactor=#{@reactor_class&.name.inspect} " \
+          "step=#{step_config.name.inspect} execution_id=#{@context.context_id.inspect}"
+        )
+      end
+
       def record_async_step_dispatch(step_config)
         root = @context.root_context || @context
         @context.composed_contexts[step_config.name] = {
@@ -98,11 +201,14 @@ module RubyReactor
       end
 
       # One machine-parseable line per hand-off / dispatch, carrying the
-      # three identifiers needed to correlate it with everything else.
-      def log_async_event(event, step_name)
+      # three identifiers needed to correlate it with everything else, plus
+      # any extra key=value fields (e.g. a park's key/primitive/attempt),
+      # inserted before execution_id so it always trails the line.
+      def log_async_event(event, step_name, **fields)
+        extra = fields.map { |k, v| " #{k}=#{v.inspect}" }.join
         configuration.logger.info(
           "event=\"ruby_reactor.#{event}\" reactor=#{@reactor_class&.name.inspect} " \
-          "step=#{step_name.inspect} execution_id=#{@context.context_id.inspect}"
+          "step=#{step_name.inspect}#{extra} execution_id=#{@context.context_id.inspect}"
         )
       end
     end