ruby_reactor 0.6.0 → 0.7.1

data/lib/ruby_reactor/executor/retry_manager.rb

@@ -94,12 +94,15 @@ module RubyReactor
 
       def handle_retry_result(step_config, reactor_class, result)
         case result
-        when RubyReactor::Success
+        when RubyReactor::Halt, RubyReactor::Skipped, RubyReactor::Success
+          # Halt and Skipped are Success subclasses, so they already take this
+          # path via inheritance; the explicit arms are readability plus a
+          # guard against a future hierarchy change (R5).
           clear_retry_state
           result
         when RubyReactor::Failure
           handle_failure_result(step_config, reactor_class, result)
-        when RetryQueuedResult, RubyReactor::AsyncResult
+        when RetryQueuedResult, RubyReactor::DispatchResult
           # Pass through async results
           result
         else
@@ -126,8 +129,12 @@ module RubyReactor
           @context
         )
 
-        # Check if we should requeue (async retry)
-        is_async = reactor_class.async? || step_config.async? ||
+        # Check if we should requeue (async retry). The per-step `async` flag is
+        # gone: a step relocated by `background` fails inside the worker, where
+        # `inline_async_execution` already answers this — and a step failing
+        # BEFORE the hand-off point genuinely has no worker to requeue into, so
+        # it must retry synchronously.
+        is_async = reactor_class.async? ||
                    @context.root_context&.reactor_class&.async? ||
                    @context.inline_async_execution
 
@@ -142,9 +149,9 @@ module RubyReactor
       def handle_async_retry(step_config, reactor_class, result)
         requeue_result = requeue_job_for_step_retry(step_config, result.error, reactor_class)
 
-        # If it returned an AsyncResult, we are truly async.
+        # If it returned an DispatchResult, we are truly async.
         # Otherwise, it ran inline and we should return the result of that execution.
-        if requeue_result.is_a?(RubyReactor::AsyncResult)
+        if requeue_result.is_a?(RubyReactor::DispatchResult)
           RetryQueuedResult.new(
             step_config.name,
             @context.retry_context.attempts_for_step(step_config.name),

data/lib/ruby_reactor/executor/step_executor.rb

@@ -3,6 +3,8 @@
 module RubyReactor
   class Executor
     class StepExecutor
+      include AsyncStepDispatch
+
       def initialize(context:, dependency_graph:, reactor_class:, managers:)
         @context = context
         @dependency_graph = dependency_graph
@@ -30,15 +32,15 @@ module RubyReactor
             result = execute_step(step_config)
 
             # If step execution was handed off to async, return the async result
-            return result if result.is_a?(RubyReactor::AsyncResult)
+            return result if result.is_a?(RubyReactor::DispatchResult)
 
             # If a step returns RetryQueuedResult, we need to stop and return it
             return result if result.is_a?(RetryQueuedResult)
 
-            # If a step returns Skipped, halt the reactor cleanly (no
+            # If a step returns Halt, stop the reactor cleanly (no
             # compensation). Must be checked BEFORE Failure / Success because
-            # Skipped is a Success subclass.
-            return result if result.is_a?(RubyReactor::Skipped)
+            # Halt is a Success subclass.
+            return result if result.is_a?(RubyReactor::Halt)
 
             # If a step returns Failure, we need to stop execution and return it
             return result if result.is_a?(RubyReactor::Failure)
@@ -46,13 +48,17 @@ module RubyReactor
             # If a step returns InterruptResult, we need to stop execution and return it
             return result if result.is_a?(RubyReactor::InterruptResult)
 
-            # Only a continue-Success reaches here (Async/Retry/Skipped/Failure/
-            # Interrupt all returned above; nil is inline-async test mode). It is
-            # the one outcome where the loop proceeds to more steps with no other
-            # save in between — every terminal/handoff result persists via its own
-            # path. Write a durable checkpoint so a crash re-runs at most this one
-            # step. Ordering: side-effect -> record result (inside execute_step) ->
-            # checkpoint here.
+            # A Skipped step (or a plain Success) continues the loop — Skipped
+            # is a Success subclass, so this also fires the durable checkpoint
+            # for it, same as a plain success.
+            #
+            # Only a continue-Success/Skipped reaches here (Async/Retry/Halt/
+            # Failure/Interrupt all returned above; nil is inline-async test
+            # mode). It is the one outcome where the loop proceeds to more
+            # steps with no other save in between — every terminal/handoff
+            # result persists via its own path. Write a durable checkpoint so
+            # a crash re-runs at most this one step. Ordering: side-effect ->
+            # record result (inside execute_step) -> checkpoint here.
             @on_step_complete&.call if result.is_a?(RubyReactor::Success)
           end
         end
@@ -62,25 +68,36 @@ module RubyReactor
       end
 
       def execute_step(step_config)
-        # If we're already in inline async execution mode (inside Worker),
-        # treat async steps as sync to avoid infinite recursion
-
         if @dependency_graph.completed.include?(step_config.name)
           return RubyReactor.Success(@context.get_result(step_config.name))
         end
 
-        resolved_arguments = resolve_arguments(step_config)
+        # Decided BEFORE argument resolution: resolving can block (or park) on
+        # an async `result(:name)`, and when the step body is about to be
+        # dispatched elsewhere — a `before:` hand-off, or an `async_step`'s
+        # own worker — that wait belongs to the process that will actually run
+        # it, not this one. (`async_reactor` still resolves here: its resolved
+        # values are the child's INPUTS, needed at dispatch.)
+        deferred_body = step_config.async_dispatch == :step || handoff_at?(step_config, :before)
+        resolved_arguments = deferred_body ? {} : resolve_arguments(step_config)
 
         @middlewares.on(:start_step, step_config.name, resolved_arguments, @context)
         completed = false
         begin
           result = if step_config.interrupt?
                      handle_interrupt_step(step_config)
-                   elsif step_config.async? && !@context.inline_async_execution
-                     handle_async_step(step_config)
+                   elsif step_config.async_dispatch == :step
+                     dispatch_async_step(step_config)
+                   elsif handoff_at?(step_config, :before)
+                     # `before: :x` hands off INSTEAD of running :x, leaving its
+                     # graph node incomplete for the worker to pick up.
+                     handle_background_handoff(step_config)
                    else
                      execute_step_with_retry(step_config, resolved_arguments)
                    end
+          # `after: :x` hands off once :x's result is recorded — the step really
+          # did run here, and only what remains moves to the worker.
+          result = handle_background_handoff(step_config) if handoff_after?(step_config, result)
           completed = true
           if result.is_a?(RubyReactor::Failure)
             @middlewares.on(:failed_step, step_config.name, result, @context)
@@ -96,6 +113,37 @@ module RubyReactor
 
       private
 
+      # The reactor's single hand-off point, `{ mode: :after|:before, step: }`.
+      # Nil for a reactor that never declares `background`.
+      def background_handoff
+        return @background_handoff if defined?(@background_handoff)
+
+        @background_handoff =
+          (@reactor_class.background_handoff if @reactor_class.respond_to?(:background_handoff))
+      end
+
+      # Hand-off is keyed to REACHING the named step, not to where the
+      # declaration sits in the class body. A step whose `where`/guard says it
+      # must not run never triggers it — the hand-off only ever relocates work
+      # that is actually going to happen. Inside the worker the whole thing is
+      # suppressed (`inline_async_execution`) so it cannot re-trigger.
+      def handoff_at?(step_config, mode)
+        point = background_handoff
+        return false unless point && point[:mode] == mode && point[:step] == step_config.name
+        return false if @context.inline_async_execution
+
+        step_config.should_run?(@context)
+      end
+
+      # Post-execution trigger for `after:`. Only a plain continue-Success means
+      # the named step actually completed here — a Failure, Skipped, interrupt,
+      # queued retry or an already-async result each own the flow instead.
+      def handoff_after?(step_config, result)
+        return false unless result.is_a?(RubyReactor::Success) && !result.is_a?(RubyReactor::Skipped)
+
+        handoff_at?(step_config, :after)
+      end
+
       def reconstruct_failure(data)
         return data if data.is_a?(RubyReactor::Failure)
         return nil unless data.is_a?(Hash)
@@ -125,7 +173,7 @@ module RubyReactor
           safe_execute_step_sync(step_config, resolved_arguments)
         end
 
-        unless result.is_a?(RetryQueuedResult) || result.is_a?(RubyReactor::AsyncResult)
+        unless result.is_a?(RetryQueuedResult) || result.is_a?(RubyReactor::DispatchResult)
           @result_handler.handle_step_result(step_config, result, resolved_arguments)
         end
 
@@ -197,9 +245,12 @@ module RubyReactor
         end
       end
 
-      def handle_async_step(step_config)
-        # Step-level async: hand off execution to worker
-
+      # Hand every step not yet executed to a worker job, and return the
+      # `DispatchResult` that halts `execute_all_steps` in the calling process.
+      # Shared verbatim by both `background` forms — they differ only in WHERE
+      # the trigger sits, never in what the hand-off does.
+      def handle_background_handoff(step_config)
+        log_async_event("background.handoff", step_config.name)
         @context.current_step = step_config.name
         @context.undo_stack = @compensation_manager.undo_stack
 
@@ -289,15 +340,17 @@ module RubyReactor
       end
 
       def run_step_implementation(step_config, arguments)
-        @context.execution_trace << { type: :run, step: step_config.name, timestamp: Time.now, arguments: arguments }
+        @context.append_execution_trace(
+          { type: :run, step: step_config.name, timestamp: Time.now, arguments: arguments }
+        )
         if step_config.has_run_block?
           # Execute inline block
           # If no arguments are defined for the step, pass the reactor inputs as arguments
           args_to_pass = arguments.empty? ? @context.inputs : arguments
-          step_config.run_block.call(args_to_pass, @context)
+          catch(StepSignals::TAG) { step_config.run_block.call(args_to_pass, @context) }
         elsif step_config.has_impl?
           # Execute step class
-          step_config.impl.run(arguments, @context)
+          catch(StepSignals::TAG) { step_config.impl.run(arguments, @context) }
         else
           raise Error::ValidationError.new(
             "Step '#{step_config.name}' has no implementation",

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,15 +103,16 @@ 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
       # is a fast path; this one closes the race where two callers both passed
       # it and then serialized on the lock — without it the second caller would
       # re-run work the first already marked. (No-op when no lock is configured.)
-      if (skipped = check_period_gate)
+      if (halted = check_period_gate)
         completed = true
-        return finalize_skipped(skipped)
+        return finalize_halt(halted)
       end
 
       @context.status = :running
@@ -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,17 +202,25 @@ 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.
-      if first_run && (skipped = check_period_gate)
+      if first_run && (halted = check_period_gate)
         completed = true
-        return finalize_skipped(skipped)
+        return finalize_halt(halted)
       end
 
       prepare_for_resume
@@ -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
@@ -348,16 +393,16 @@ module RubyReactor
       @context.current_step.nil? && @context.intermediate_results.empty?
     end
 
-    # Record and persist a Skipped result, then return it. Shared by the
+    # Record and persist a Halt result, then return it. Shared by the
     # pre-lock and post-lock period gates in both execute and resume.
-    def finalize_skipped(skipped)
-      @result = skipped
+    def finalize_halt(halted)
+      @result = halted
       update_context_status(@result)
       save_context
       @result
     end
 
-    # Returns a Skipped result if the period bucket is already marked, else nil.
+    # Returns a Halt result if the period bucket is already marked, else nil.
     # Consulted before AND after lock acquisition on a first execution; genuine
     # resumes never re-check (a paused run must not skip itself when its own
     # marker eventually appears).
@@ -368,13 +413,13 @@ module RubyReactor
       key = period_key(config)
       return nil unless RubyReactor.configuration.storage_adapter.period_seen?(key)
 
-      RubyReactor::Skipped.new(reason: :period, period_key: key)
+      RubyReactor::Halt.new(reason: :period, period_key: key)
     end
 
     def mark_period_on_success(result)
       return unless @reactor_class.respond_to?(:period_config) && @reactor_class.period_config
       return unless result.is_a?(RubyReactor::Success)
-      return if result.is_a?(RubyReactor::Skipped)
+      return if result.is_a?(RubyReactor::Halt)
 
       config = @reactor_class.period_config
       ttl = RubyReactor::Period.ttl_seconds(config[:every])
@@ -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,10 +660,10 @@ module RubyReactor
       return unless result
 
       case result
-      when RubyReactor::AsyncResult
+      when RubyReactor::DispatchResult
         @context.status = :running
-      when RubyReactor::Skipped
-        @context.status = :skipped
+      when RubyReactor::Halt
+        @context.status = :halted
       when RubyReactor::Success
         @context.status = :completed
       when RubyReactor::Failure
@@ -542,14 +696,16 @@ module RubyReactor
         @result = @step_executor.execute_all_steps
       else
         case result
-        # Skipped must be listed before Success (Skipped < Success) so the
+        # Halt must be listed before Success (Halt < Success) so the
         # halt path wins over the "continue with remaining steps" path.
-        when RubyReactor::Skipped,
+        # Skipped is NOT listed here — it is a Success subclass and must
+        # continue with the remaining steps, same as a plain Success.
+        when RubyReactor::Halt,
              RetryQueuedResult,
              RubyReactor::Failure,
-             RubyReactor::AsyncResult,
+             RubyReactor::DispatchResult,
              RubyReactor::InterruptResult
-          # Terminal: step was skipped, requeued, failed, paused, or handed
+          # Terminal: step halted, requeued, failed, paused, or handed
           # off to async. Return the result as-is.
           @result = result
         when RubyReactor::Success

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

@@ -141,12 +141,23 @@ module RubyReactor
         index = arguments[:index]
         parent_class = arguments[:parent_reactor_class_name] # Using short name for variable
 
-        if result.success?
+        if result.halted?
+          # A Halt must not be collected as a (nil) value indistinguishable
+          # from an ordinary success — mark it so the enumerator reconstructs
+          # a real Halt for the consumer.
+          storage.store_map_result(map_id, index, { _halt: true, reason: result.reason },
+                                   parent_class, strict_ordering: arguments[:strict_ordering])
+        elsif result.success?
           storage.store_map_result(map_id, index, ContextSerializer.serialize_value(result.value),
                                    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,14 +95,16 @@ 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
-          parent_context.execution_trace << {
-            type: :result,
-            step: step_name_sym,
-            timestamp: Time.now,
-            value: final_result.value,
-            status: :success
-          }
+          # and the async step (which returned DispatchResult) needs to be marked as done with actual value
+          parent_context.append_execution_trace(
+            {
+              type: :result,
+              step: step_name_sym,
+              timestamp: Time.now,
+              value: final_result.value,
+              status: :success
+            }
+          )
 
           parent_context.current_step = nil
           executor.resume_execution