ruby_reactor 0.6.0 → 0.7.0

data/lib/ruby_reactor/executor.rb

@@ -6,6 +6,7 @@ require_relative "executor/graph_manager"
 require_relative "executor/retry_manager"
 require_relative "executor/compensation_manager"
 require_relative "executor/result_handler"
+require_relative "executor/async_step_dispatch"
 require_relative "executor/step_executor"
 require_relative "executor/ordered_lock_support"
 
@@ -53,6 +54,7 @@ module RubyReactor
       @acquired_semaphore = nil
       @acquired_context_lock = nil
       @context_lock_owner = nil
+      @parked = false
       @contention_snooze = false
       @skip_context_persist = false
       @last_checkpoint_at = nil
@@ -101,6 +103,7 @@ module RubyReactor
       input_validator = InputValidator.new(@reactor_class, @context)
       input_validator.validate!
 
+      reset_held_lock_keys!
       acquire_locks_with_telemetry
 
       # Re-check the period gate now that we hold the lock. The pre-lock check
@@ -132,6 +135,13 @@ module RubyReactor
            RubyReactor::OrderedLock::WaitError => e
       @contention_snooze = true
       raise e
+    rescue Error::AsyncResultPending
+      # Only reachable when this executor runs nested inside a worker (a
+      # composed child; sync callers never park). Propagate to the ROOT
+      # resume, which owns the park. This child's own lock/semaphore (if any)
+      # ARE released below and re-competed for on redelivery.
+      @contention_snooze = true
+      raise
     rescue StandardError => e
       @result = @result_handler.handle_execution_error(e)
       update_context_status(@result)
@@ -192,11 +202,19 @@ module RubyReactor
       # and must not contend on the root's own key.
       acquire_context_lock
 
+      reset_held_lock_keys!
+
       # Resumes intentionally skip check_rate_limit (a paused run must not
       # block itself on resume), so acquire lock/semaphore directly rather
-      # than via acquire_locks.
-      acquire_exclusive_lock if @reactor_class.respond_to?(:lock_config) && @reactor_class.lock_config
-      acquire_semaphore if @reactor_class.respond_to?(:semaphore_config) && @reactor_class.semaphore_config
+      # than via acquire_locks. A context parked on an async result kept its
+      # primitives held across the gap — re-adopt them instead of re-competing.
+      parked = consume_parked_primitives!
+      if @reactor_class.respond_to?(:lock_config) && @reactor_class.lock_config
+        acquire_exclusive_lock(reattach: parked[:lock])
+      end
+      if @reactor_class.respond_to?(:semaphore_config) && @reactor_class.semaphore_config
+        acquire_semaphore(reattach_token: parked[:semaphore_token])
+      end
 
       # Post-lock re-check (see execute) — closes the period race for the
       # first run of a locked async reactor.
@@ -227,13 +245,21 @@ module RubyReactor
            RubyReactor::OrderedLock::WaitError => e
       @contention_snooze = true
       raise e
+    rescue Error::AsyncResultPending => e
+      # An awaited async unit is not terminal yet: park. Exclusive lock and
+      # semaphore stay HELD (recorded on the context for the resuming job to
+      # re-adopt); the worker snoozes the job. The context lock is still
+      # released below — the redelivered job must be able to take it.
+      park_held_primitives!
+      @contention_snooze = true
+      raise e
     rescue StandardError => e
       handle_resume_error(e)
       update_context_status(@result)
       completed = true
       @result
     ensure
-      release_locks
+      release_locks unless @parked
       @acquired_context_lock&.release
       @acquired_context_lock = nil
       leave_ordered_lock_scope
@@ -265,6 +291,25 @@ module RubyReactor
       # Serialize context
       serialized_context = ContextSerializer.serialize(@context)
       storage.store_context(@context.context_id, serialized_context, reactor_class_name)
+      publish_completion_signal(storage)
+    end
+
+    # Wake any parent blocked in the notified wait on this execution. Published
+    # AFTER the durable save, never before: the context row is the answer and
+    # the signal only saves the waiter a fallback interval. Unconditional —
+    # publishing to a channel with no subscribers is near-free, so there is no
+    # need for an "am I awaited?" marker.
+    def publish_completion_signal(storage)
+      return unless @context.finished?
+
+      log_completion
+      storage.publish(RubyReactor.async_reactor_channel(@context.context_id), @context.status.to_s)
+    rescue StandardError => e
+      # The signal is an optimisation; losing it costs the waiter one fallback
+      # interval and must never fail the run that just completed.
+      RubyReactor.configuration.logger.warn(
+        "RubyReactor: could not publish completion signal for #{@context.context_id}: #{e.message}"
+      )
     end
 
     # Durable per-step checkpoint. Unlike save_context (which serializes THIS
@@ -386,6 +431,33 @@ module RubyReactor
       RubyReactor::Period.key(base, config[:every])
     end
 
+    # One machine-parseable line whenever an execution reaches a terminal
+    # state, carrying the parent link. A child dispatched fire-and-forget may
+    # have no other surface in its parent at all, so a failure entry also names
+    # the reason.
+    def log_completion
+      return unless @context.parent_context_id
+
+      fields = {
+        event: "ruby_reactor.async_reactor.completed",
+        reactor: @reactor_class&.name,
+        execution_id: @context.context_id,
+        parent_execution_id: @context.parent_context_id,
+        status: @context.status.to_s
+      }
+      fields[:failure] = failure_summary if @context.failed?
+
+      RubyReactor.configuration.logger.public_send(
+        @context.failed? ? :warn : :info,
+        fields.map { |k, v| "#{k}=#{v.inspect}" }.join(" ")
+      )
+    end
+
+    def failure_summary
+      reason = @context.failure_reason
+      reason.respond_to?(:error) ? reason.error.to_s : reason.to_s
+    end
+
     # Per-execution liveness lock on the root context id. Owner is a fresh UUID
     # per execution (NOT the context_id): a duplicate delivery of the *same*
     # context from a different worker must be blocked, so reentrancy by id would
@@ -422,7 +494,7 @@ module RubyReactor
       defined?(Sidekiq::Testing) && Sidekiq::Testing.respond_to?(:inline?) && Sidekiq::Testing.inline?
     end
 
-    def acquire_exclusive_lock
+    def acquire_exclusive_lock(reattach: false)
       config = @reactor_class.lock_config
       key = config[:key_proc].call(@context.inputs)
 
@@ -436,9 +508,21 @@ module RubyReactor
         wait: contention_wait(config[:wait]),
         auto_extend: config.fetch(:auto_extend, true)
       )
+
+      # Re-adopting a lock held across a parked gap: no :lock_acquired event —
+      # the original acquisition already emitted it, and the eventual release
+      # emits exactly one :lock_released. A lapsed TTL falls through to a
+      # fresh acquire.
+      if reattach && lock.reattach
+        @acquired_lock = lock
+        held_lock_keys << key
+        return
+      end
+
       begin
         lock.acquire
         @acquired_lock = lock
+        held_lock_keys << key
         middlewares.on(:lock_acquired, key, @context)
       rescue RubyReactor::Lock::AcquisitionError => e
         middlewares.on(:lock_failed, key, e, @context)
@@ -446,15 +530,29 @@ module RubyReactor
       end
     end
 
-    def acquire_semaphore
+    def acquire_semaphore(reattach_token: nil)
       config = @reactor_class.semaphore_config
       key = config[:key_proc].call(@context.inputs)
       limit = config[:limit]
 
       semaphore = RubyReactor::Semaphore.new(key, limit: limit, wait: contention_wait(config[:wait]))
+
+      # Same shape as the lock reattach above: keep the slot held across the
+      # parked gap, no duplicate :semaphore_acquired event, fall through to a
+      # fresh acquire when the token was lost in between.
+      if reattach_token && semaphore.reattach(reattach_token)
+        @acquired_semaphore = semaphore
+        held_lock_keys << key if limit == 1
+        return
+      end
+
       begin
         semaphore.acquire
         @acquired_semaphore = semaphore
+        # Only a single-slot semaphore has the circular-wait shape the
+        # async_reactor deadlock guard can act on; higher limits are ordinary
+        # contention and must keep snoozing.
+        held_lock_keys << key if limit == 1
         middlewares.on(:semaphore_acquired, key, limit, @context)
       rescue RubyReactor::Semaphore::AcquisitionError => e
         middlewares.on(:semaphore_failed, key, limit, e, @context)
@@ -471,10 +569,47 @@ module RubyReactor
       configured_wait
     end
 
+    # Park on a pending async result: keep exclusive lock / semaphore checked
+    # out through the gap, recording just enough on the (about-to-be-saved)
+    # context for the resuming job to re-adopt them. The lock's auto-extender
+    # dies with this process, so the parked gap is bounded by the lock TTL —
+    # the snooze redelivery (seconds) sits comfortably inside the default 60s.
+    def park_held_primitives!
+      @parked = true
+      parked = {}
+
+      if @acquired_lock
+        @acquired_lock.detach
+        parked[:lock] = true
+        @acquired_lock = nil
+      end
+
+      if @acquired_semaphore
+        parked[:semaphore_token] = @acquired_semaphore.token
+        @acquired_semaphore = nil
+      end
+
+      @context.private_data[:parked_primitives] = parked if parked.any?
+    end
+
+    # One-shot: the marker is deleted on read so a crash after this point
+    # degrades to a fresh acquire (reentrant by owner for the lock) rather
+    # than a stale reattach on some later, unrelated resume.
+    def consume_parked_primitives!
+      raw = @context.private_data.delete(:parked_primitives) ||
+            @context.private_data.delete("parked_primitives") || {}
+
+      {
+        lock: raw[:lock] || raw["lock"],
+        semaphore_token: raw[:semaphore_token] || raw["semaphore_token"]
+      }
+    end
+
     def release_locks
       if @acquired_semaphore
         key = @acquired_semaphore.key
         release_one("semaphore", @acquired_semaphore)
+        held_lock_keys.delete(key)
         middlewares.on(:semaphore_released, key, @context)
       end
       @acquired_semaphore = nil
@@ -483,10 +618,29 @@ module RubyReactor
 
       key = @acquired_lock.key
       release_one("lock", @acquired_lock)
+      held_lock_keys.delete(key)
       @acquired_lock = nil
       middlewares.on(:lock_released, key, @context)
     end
 
+    # Exclusive keys this EXECUTION currently holds, recorded on the root
+    # context so a dispatching step anywhere in the tree can see the whole
+    # chain. Read by the async_reactor deadlock guard; nothing else
+    # depends on it, so a stale entry can only cost a false positive — hence
+    # the reset on the way in.
+    def held_lock_keys
+      root = @context.root_context || @context
+      root.private_data[:held_lock_keys] ||= []
+    end
+
+    # A rehydrated context can carry keys from the process that died holding
+    # them. Only the root executor resets, and only on the way in.
+    def reset_held_lock_keys!
+      return unless (@context.root_context || @context).equal?(@context)
+
+      (@context.root_context || @context).private_data[:held_lock_keys] = []
+    end
+
     def release_one(kind, primitive)
       released = primitive.release
       return if released
@@ -506,7 +660,7 @@ module RubyReactor
       return unless result
 
       case result
-      when RubyReactor::AsyncResult
+      when RubyReactor::DispatchResult
         @context.status = :running
       when RubyReactor::Skipped
         @context.status = :skipped
@@ -547,7 +701,7 @@ module RubyReactor
         when RubyReactor::Skipped,
              RetryQueuedResult,
              RubyReactor::Failure,
-             RubyReactor::AsyncResult,
+             RubyReactor::DispatchResult,
              RubyReactor::InterruptResult
           # Terminal: step was skipped, requeued, failed, paused, or handed
           # off to async. Return the result as-is.

data/lib/ruby_reactor/lock.rb

@@ -54,6 +54,25 @@ module RubyReactor
       adapter.lock_release(@key, @owner)
     end
 
+    # Park support: stop refreshing the TTL but LEAVE the key held — the
+    # parked execution keeps ownership through the gap, bounded by the TTL.
+    def detach
+      stop_extender
+    end
+
+    # Resume ownership after a parked gap: verify we are still the owner and
+    # refresh the TTL — WITHOUT incrementing the reentrancy count. The count
+    # was never decremented at park, so a plain `acquire` here would bump it
+    # to 2 and the final release would leave the key behind until TTL.
+    # Returns false when ownership lapsed (TTL expired mid-park); the caller
+    # falls back to a fresh acquire.
+    def reattach # rubocop:disable Naming/PredicateMethod
+      return false unless adapter.lock_extend(@key, @owner, @ttl)
+
+      start_extender if @auto_extend
+      true
+    end
+
     def synchronize
       acquire
       yield

data/lib/ruby_reactor/map/element_executor.rb

@@ -146,7 +146,12 @@ module RubyReactor
                                    parent_class, strict_ordering: arguments[:strict_ordering])
         else
           executor.undo_all
-          storage.store_map_result(map_id, index, { _error: result.error }, parent_class,
+          # Store the whole serialized Failure, not just its message: step_name,
+          # backtrace, file_path and code_snippet are the only record of why this
+          # element failed once its context row expires, and the dashboard has
+          # nothing else to show for a non-fail_fast map.
+          storage.store_map_result(map_id, index,
+                                   { _error: ContextSerializer.serialize_value(result) }, parent_class,
                                    strict_ordering: arguments[:strict_ordering])
 
           if arguments[:fail_fast]

data/lib/ruby_reactor/map/helpers.rb

@@ -95,7 +95,7 @@ module RubyReactor
 
           # Manually update execution trace to reflect completion
           # This is necessary because resume_execution continues from the NEXT step
-          # and the async step (which returned AsyncResult) needs to be marked as done with actual value
+          # and the async step (which returned DispatchResult) needs to be marked as done with actual value
           parent_context.execution_trace << {
             type: :result,
             step: step_name_sym,

data/lib/ruby_reactor/map/result_enumerator.rb

@@ -96,7 +96,11 @@ module RubyReactor
 
       def wrap_result(result)
         if result.is_a?(Hash) && result.key?("_error")
-          RubyReactor::Failure.new(result["_error"])
+          # `backtrace: []` is load-bearing: without it Failure falls back to
+          # `caller`, so a bare-message element failure would carry the stack of
+          # whoever happened to materialize the enumerator (the JSON encoder, in
+          # the dashboard's case) instead of the stack of the step that failed.
+          RubyReactor::Failure.new(result["_error"], backtrace: [])
         else
           RubyReactor::Success.new(ContextSerializer.deserialize_value(result))
         end

data/lib/ruby_reactor/map/result_summary.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module RubyReactor
+  module Map
+    # A map's result set is unbounded, so the API describes it instead of
+    # inlining it. Inlining meant the JSON encoder materialized the lazy
+    # ResultEnumerator itself — one storage read per element — and rendered every
+    # element failure as an opaque blob with no count of how many there were.
+    class ResultSummary
+      # How many failed elements are described in full. The rest are only
+      # counted — a map failing 50k elements must not produce a 50k-entry
+      # response.
+      SAMPLE_LIMIT = 25
+
+      # Sampled failures are a list, not a detail view, and the same summary is
+      # echoed in intermediate_results, the execution trace and the undo stack —
+      # full traces on each would triple a large payload.
+      BACKTRACE_FRAMES = 10
+
+      # ponytail: one windowed read of the whole map; paginate if maps grow past
+      # what fits in a single response.
+      def self.build(enumerator)
+        total = enumerator.count
+        results = RubyReactor.configuration.storage_adapter.retrieve_map_results_batch(
+          enumerator.map_id, enumerator.reactor_class_name, offset: 0, limit: total
+        )
+        # Slots are index-keyed and the window starts at 0, so a full read means
+        # position == element index. A short read means the map is still filling
+        # in and gaps would shift positions — then indices are omitted.
+        failures = collect_failures(results, indexed: results.size == total)
+
+        {
+          "_type" => "map_results",
+          "total" => total,
+          "succeeded" => total - failures[:count],
+          "failed" => failures[:count],
+          "failures" => failures[:sample],
+          "failures_truncated" => failures[:count] > failures[:sample].size
+        }
+      end
+
+      def self.collect_failures(results, indexed:)
+        count = 0
+        sample = []
+
+        results.each_with_index do |raw, position|
+          next unless raw.is_a?(Hash) && raw.key?("_error")
+
+          count += 1
+          next if sample.size >= SAMPLE_LIMIT
+
+          entry = ContextSerializer.simplify_for_api(Failure.new(raw["_error"], backtrace: []))
+          entry["backtrace"] = Array(entry["backtrace"]).first(BACKTRACE_FRAMES)
+          entry["index"] = position if indexed
+          sample << entry
+        end
+
+        { count: count, sample: sample }
+      end
+      private_class_method :collect_failures
+    end
+  end
+end

data/lib/ruby_reactor/open_telemetry.rb

@@ -147,7 +147,7 @@ module RubyReactor
       span = @step_spans.delete(step_name)
       return unless span
 
-      if result.is_a?(RubyReactor::AsyncResult)
+      if result.is_a?(RubyReactor::DispatchResult)
         # The step was handed off to a background worker; the run block did not
         # execute here. Rename the span so it is not confused with the real
         # execution span emitted later under the resumed reactor span.

data/lib/ruby_reactor/reactor.rb

@@ -118,7 +118,7 @@ module RubyReactor
                                                            RubyReactor.reactor_storage_name(self.class),
                                                            intermediate_results: @context.intermediate_results)
 
-        # Even if it's an AsyncResult, it might have finished inline (e.g. Sidekiq::Testing.inline!)
+        # Even if it's an DispatchResult, it might have finished inline (e.g. Sidekiq::Testing.inline!)
         # Check storage to see if it's already finished or paused (interrupted).
         begin
           reloaded = self.class.find(@context.context_id)
@@ -167,6 +167,14 @@ module RubyReactor
       target_step = step_name
       @context.set_result(target_step, payload)
 
+      # `interrupt :x, resume: :background` — payload is validated and stored
+      # (above, in this process); the remaining work goes to a worker instead
+      # of running inline in the delivering process.
+      step_config = self.class.steps[step_name.to_sym]
+      if step_config.respond_to?(:background_resume?) && step_config.background_resume?
+        return @result = enqueue_background_resume
+      end
+
       # Resume execution
       executor = Executor.new(self.class, {}, @context)
       @result = executor.resume_execution
@@ -311,6 +319,21 @@ module RubyReactor
       save_context
     end
 
+    # Mirror of perform_async_run for the interrupt-resume path: persist the
+    # context (now carrying the validated payload) BEFORE enqueue — the job
+    # payload is identity-only (F2) — then hand the remainder to a worker.
+    def enqueue_background_resume
+      @context.status = :running
+      Executor.middlewares_for(self.class).on(:before_async_enqueue, @context)
+      save_context
+
+      @result = configuration.async_router.perform_async(@context.context_id,
+                                                         RubyReactor.reactor_storage_name(self.class),
+                                                         intermediate_results: @context.intermediate_results)
+
+      check_for_inline_completion || @result
+    end
+
     def perform_async_run
       @context.status = :running
       # Persist BEFORE enqueue — the job payload is identity-only (F2).
@@ -324,7 +347,7 @@ module RubyReactor
     end
 
     def check_for_inline_completion
-      # Even if it's an AsyncResult, it might have finished inline (e.g. Sidekiq::Testing.inline!)
+      # Even if it's an DispatchResult, it might have finished inline (e.g. Sidekiq::Testing.inline!)
       # Check storage to see if it's already finished or paused (interrupted).
       reloaded = self.class.find(@context.context_id)
       if reloaded.finished? || reloaded.context.status.to_s == "paused"

data/lib/ruby_reactor/rspec/sidekiq_helpers.rb

@@ -38,7 +38,8 @@ module RubyReactor
         @worker_classes ||= [
           RubyReactor::Adapters::Sidekiq::Worker,
           RubyReactor::Adapters::Sidekiq::MapElementWorker,
-          RubyReactor::Adapters::Sidekiq::MapCollectorWorker
+          RubyReactor::Adapters::Sidekiq::MapCollectorWorker,
+          RubyReactor::Adapters::Sidekiq::StepWorker
         ]
       end
 

data/lib/ruby_reactor/rspec/step_executor_patch.rb

@@ -14,7 +14,7 @@ module RubyReactor
         result = super
 
         # 2. Add test-specific logic for inline async execution
-        # Only interfere if we got an AsyncResult and we are in a testing environment that supports inline execution
+        # Only interfere if we got an DispatchResult and we are in a testing environment that supports inline execution
         if should_check_inline_completion?(result)
           # Check if it finished or paused inline (e.g. Sidekiq::Testing.inline!)
           refresh_context_from_storage
@@ -75,7 +75,7 @@ module RubyReactor
       end
 
       def should_check_inline_completion?(result)
-        return false unless result.is_a?(RubyReactor::AsyncResult) || result.is_a?(RubyReactor::RetryQueuedResult)
+        return false unless result.is_a?(RubyReactor::DispatchResult) || result.is_a?(RubyReactor::RetryQueuedResult)
         return true if defined?(Sidekiq::Testing) && Sidekiq::Testing.inline?
 
         false

data/lib/ruby_reactor/rspec/test_subject.rb

@@ -130,6 +130,56 @@ module RubyReactor
         elements[index]
       end
 
+      # The durable record for a dispatched `async_step`, or nil if the step was
+      # never dispatched (e.g. under `async: false`, where it ran inline and its
+      # value is an ordinary `step_result`). Mirrors `#composed` / `#map` in
+      # reading the reference off `composed_contexts`.
+      #
+      #   subject.async_step(:send_email)          # => the raw record hash
+      #   subject.async_step(:send_email, :status) # => "dispatched" / "completed"
+      def async_step(step_name, key = nil)
+        ensure_executed!
+
+        entry = composed_entry(step_name)
+        return nil unless entry && entry[:type] == :async_step_ref
+
+        record = RubyReactor.configuration.storage_adapter.retrieve_step_result(
+          entry[:context_id] || @reactor_instance.context.context_id,
+          step_name,
+          RubyReactor.reactor_storage_name(@reactor_instance.class)
+        )
+        key && record ? record[key.to_s] : record
+      end
+
+      # The child execution a dispatched `async_reactor` created, as its own
+      # TestSubject — the same drill-down `#composed` gives for an inline child.
+      def async_reactor(step_name)
+        ensure_executed!
+
+        entry = composed_entry(step_name)
+        return nil unless entry && entry[:type] == :async_reactor_ref
+
+        child_class = RubyReactor::Context.resolve_reactor_class(entry[:reactor_class_name])
+        return nil unless child_class
+
+        child_instance = child_class.find(entry[:execution_id])
+        self.class.new(
+          reactor_class: child_instance.class,
+          inputs: child_instance.context.inputs,
+          context: child_instance.context,
+          async: @async,
+          process_jobs: @process_jobs
+        ).tap do |s|
+          s.instance_variable_set(:@executed, true)
+          s.instance_variable_set(:@reactor_instance, child_instance)
+        end
+      end
+
+      def composed_entry(step_name)
+        contexts = @reactor_instance.context.composed_contexts
+        contexts[step_name] || contexts[step_name.to_s] || contexts[step_name.to_sym]
+      end
+
       private
 
       def traverse_composed(step_name)
@@ -441,7 +491,8 @@ module RubyReactor
       end
 
       def prepare_execution_class
-        # Even if no interceptors, we might need to subclass to override async steps
+        # Even if no interceptors, we might need to subclass to force the whole
+        # reactor to run in-process.
         return @reactor_class if @interceptors.empty? && @async != false
 
         interceptors = @interceptors
@@ -454,7 +505,7 @@ module RubyReactor
           @input_validations = superclass.input_validations.dup
           @middlewares = superclass.middlewares.dup
           @return_step = superclass.return_step
-          @async = superclass.async?
+          @background_handoff = superclass.background_handoff
           @retry_defaults = superclass.instance_variable_get(:@retry_defaults)
 
           # 2. Add Name Handling with Unique Registry Entry
@@ -464,15 +515,16 @@ module RubyReactor
           define_singleton_method(:name) { unique_name }
           RubyReactor::Registry.register(unique_name, self)
 
-          # 3. Apply Force Sync (Disable async on all steps)
+          # 3. `async: false` / `run_async(false)` means "run this reactor's full
+          # logic here, in one process". Under the new DSL that is three things:
+          # suppress the `background` hand-off, and run `async_step` /
+          # `async_reactor` units inline instead of dispatching them.
           if force_sync
+            @background_handoff = nil
             @steps.each do |name, config|
-              next unless config.async?
+              next unless config.respond_to?(:async_dispatch?) && config.async_dispatch?
 
-              # Clone and modify
-              new_config = config.clone
-              new_config.instance_variable_set(:@async, false)
-              @steps[name] = new_config
+              @steps[name] = config.clone.tap { |c| c.instance_variable_set(:@async_dispatch, nil) }
             end
           end
         end
@@ -503,7 +555,8 @@ module RubyReactor
 
           if nested_interceptors.any?
             apply_nested_interceptors(step_config, nested_interceptors)
-            step_config.instance_variable_set(:@async, false)
+            # A mocked inner step only takes effect if the child runs here.
+            step_config.instance_variable_set(:@async_dispatch, nil)
           end
 
           # Apply direct interceptors (mocks/failures on this step)
@@ -551,7 +604,7 @@ module RubyReactor
           @input_validations = superclass.input_validations.dup
           @middlewares = superclass.middlewares.dup
           @return_step = superclass.return_step
-          @async = superclass.async?
+          @background_handoff = superclass.background_handoff
           @retry_defaults = superclass.instance_variable_get(:@retry_defaults)
         end
 
@@ -606,7 +659,9 @@ module RubyReactor
         end
 
         step_config.instance_variable_set(:@run_block, wrapper_impl)
-        step_config.instance_variable_set(:@async, false)
+        # The mock replaces the step's body, so it must run where the spec can
+        # observe it rather than being dispatched to a worker.
+        step_config.instance_variable_set(:@async_dispatch, nil)
       end
     end
     # rubocop:enable Metrics/ClassLength

data/lib/ruby_reactor/semaphore.rb

@@ -40,6 +40,16 @@ module RubyReactor
       release
     end
 
+    # Park support: re-adopt a token that stayed checked out across a parked
+    # gap. Verifies the token is still in the held set — a reset/expiry in
+    # between means the slot was lost and the caller must acquire fresh.
+    def reattach(token) # rubocop:disable Naming/PredicateMethod
+      return false unless token && adapter.semaphore_held?(@key, token)
+
+      @token = token
+      true
+    end
+
     private
 
     def ensure_initialized