ruby_reactor 0.8.1 → 0.8.3

data/lib/ruby_reactor/step/compose_step.rb

@@ -21,7 +21,9 @@ module RubyReactor
       end
 
       # Compensating a failed compose and undoing a completed one are the same
-      # work: roll back whatever the child reactor completed.
+      # work: roll back whatever the child reactor completed. Any child undo
+      # that did not complete comes back on the Failure, which the parent's
+      # `CompensationManager` flattens into its own `rollback_failures`.
       def compensate
         step_name = context.current_step
         composed_data = context.composed_contexts[step_name]
@@ -32,7 +34,10 @@ module RubyReactor
         executor.undo_all
         executor.save_context
 
-        RubyReactor.Success()
+        failures = executor.compensation_manager.rollback_failures
+        return RubyReactor.Success() if failures.empty?
+
+        RubyReactor.Failure("composed :#{step_name} rollback incomplete", rollback_failures: failures)
       end
 
       alias undo compensate
@@ -79,7 +84,13 @@ module RubyReactor
       def execute_child_reactor(composed_reactor, child_context, composed_data)
         executor = RubyReactor::Executor.new(composed_reactor, {}, child_context)
 
-        if composed_data && child_context.current_step
+        # Resume once the child has been admitted, not by its `current_step`:
+        # a park two levels down unwinds the child's `with_step` and clears
+        # it, and `execute` would then re-charge the child's rate limit and
+        # fresh-acquire its lock instead of re-adopting the parked hold
+        # (005 R-02). `current_step` stays as the fallback for a child saved
+        # before `admitted` existed.
+        if composed_data && (child_context.admitted? || child_context.current_step)
           executor.resume_execution
         else
           executor.execute

data/lib/ruby_reactor/step/map_step.rb

@@ -91,8 +91,8 @@ module RubyReactor
         results = []
         fail_fast = inputs[:fail_fast].nil? || inputs[:fail_fast]
 
-        inputs[:source].each do |element|
-          result = execute_single_element(element)
+        inputs[:source].each_with_index do |element, index|
+          result = execute_single_element(element, index)
 
           # An element-level Halt propagates as a run halt: stop immediately
           # rather than being collected as a (nil) value.
@@ -109,7 +109,7 @@ module RubyReactor
         results
       end
 
-      def execute_single_element(element)
+      def execute_single_element(element, index)
         mapped_inputs = self.class.build_mapped_inputs(inputs[:argument_mappings] || {}, context, element)
         child_context = RubyReactor::Context.new(mapped_inputs, inputs[:mapped_reactor_class])
 
@@ -123,7 +123,7 @@ module RubyReactor
         child_context.map_metadata = {
           map_id: map_id,
           parent_reactor_class_name: context.reactor_class.name,
-          index: nil # Inline map execution doesn't track index in metadata currently, but could
+          index: index
         }
 
         # Store reference in composed_contexts so the UI knows where to find elements

data/lib/ruby_reactor/step.rb

@@ -13,9 +13,15 @@ module RubyReactor
   # 1. Resolve `inputs`: the given arguments with the contract's defaults
   #    applied. `run`, `undo`, and `compensate` all see the same values.
   # 2. `.run` ONLY: enforce the declared input contract, raising
-  #    `Error::InputValidationError` before any instance exists. `.undo` and
-  #    `.compensate` NEVER enforce it: rollback must not fail on the very
-  #    inputs that may have caused the failure.
+  #    `Error::InputValidationError` before any instance exists.
+  # 2b. `.run` ONLY: step-scoped coordination (`with_lock` etc, if declared)
+  #    is acquired around the rest of `.run`, keyed on the just-validated
+  #    inputs — after contract enforcement, so a step that will fail
+  #    validation never takes a hold (research Finding 7 / Finding 8). A
+  #    reactor never goes through here: it calls `.run_without_coordination`
+  #    and coordinates the step itself (research D2).
+  #    `.undo` and `.compensate` NEVER enforce the input contract: rollback
+  #    must not fail on the very inputs that may have caused the failure.
   # 3. Build a FRESH instance, never reused across actions. An ivar set in
   #    `run` is gone by the time `undo` runs on its own instance, so async
   #    execution running `run` and `undo` in different processes behaves
@@ -23,10 +29,13 @@ module RubyReactor
   # 4. Invoke the matching instance method, translating any `StepSignals`
   #    throw (`success!`/`skip!`/`fail!`/`halt!`) into its result wrapper.
   #
-  # No `prepend`/`extend`/`define_method`/`method_missing` — every step in the
-  # class reads top to bottom as ordinary method calls.
+  # No `prepend`/`define_method`/`method_missing` — every step in the class
+  # reads top to bottom as ordinary method calls. The one `extend` is
+  # `Dsl::Lockable::ClassMethods` (the five coordination macros), a
+  # self-contained module with no hooks of its own (Finding 9).
   class Step
     include RubyReactor::StepSignals
+    extend RubyReactor::Dsl::Lockable::ClassMethods
 
     attr_reader :inputs, :context, :result, :reason
 
@@ -68,12 +77,28 @@ module RubyReactor
     # rubocop:enable Naming/MethodName
 
     class << self
-      def run(arguments, context)
+      # A DIRECT invocation — application code, or another step's body. It is
+      # its own unit of work: it takes this class's coordination itself and,
+      # having no queue to park into, waits then fails (FR-016/FR-023).
+      # `context` is optional: a stand-alone `ChargeStep.run(args)` is its own
+      # execution, with no reactor context to inherit ownership from.
+      def run(arguments, context = nil)
         validated = enforce_contract!(arguments)
-        catch(StepSignals::TAG) { new(validated, context).run }
+        coordinate(validated, context) { run_without_coordination(validated, context) }
       end
       alias call run
 
+      # The reactor's entry (`StepConfig#call_body`): the executor or
+      # `StepWorker` has already taken this step's EFFECTIVE coordination —
+      # the class's declarations and any inline ones, in one fixed order — so
+      # taking the class's here again would split acquisition across two
+      # layers. Still enforces the contract (idempotent: it only applies
+      # defaults to already-valid arguments).
+      def run_without_coordination(arguments, context)
+        validated = enforce_contract!(arguments)
+        catch(StepSignals::TAG) { new(validated, context).run }
+      end
+
       # Same `inputs` as `.run` (defaults applied), but NEVER enforces the contract.
       def undo(result, arguments, context)
         catch(StepSignals::TAG) { new(with_defaults(arguments), context, result: result).undo }
@@ -117,6 +142,23 @@ module RubyReactor
 
       private
 
+      # Step-scoped coordination for a DIRECT call (`direct: true`): never
+      # parks, keeps no state on `context`, and so can never be mistaken for
+      # the coordination of the reactor step whose body made the call.
+      # After `enforce_contract!`, so a step that will fail validation never
+      # takes a hold (Finding 8). A bare step pays one check. `context` may be
+      # nil (a stand-alone `MyStep.run(args)`) — `StepCoordination#owner`
+      # handles that case.
+      def coordinate(validated, context, &block)
+        return block.call if Executor::StepCoordination.none?(self)
+
+        ctx = context if context.is_a?(RubyReactor::Context)
+        Executor::StepCoordination.new(
+          step_config: self, arguments: validated, context: ctx, reactor_class: ctx&.reactor_class,
+          middlewares: ctx&.middlewares || Executor.middlewares_for(ctx&.reactor_class), direct: true
+        ).around_run(&block)
+      end
+
       def own_input_contract
         @own_input_contract ||= Step::InputContract.new(owner: self)
       end

data/lib/ruby_reactor/step_sweeper.rb

@@ -42,9 +42,10 @@ module RubyReactor
 
         arguments = dispatch_arguments(record)
         next unless arguments
+        next if parked?(record)
         next if live?(arguments)
 
-        @async_router.perform_step_async(**arguments)
+        redispatch(record, arguments)
         redispatched += 1
       rescue StandardError => e
         # One bad record must not abort the whole sweep.
@@ -56,6 +57,17 @@ module RubyReactor
 
     private
 
+    # A swept park must not restart its contention counter: rebuilt from the
+    # record alone, a zeroed payload would let `lock_snooze_max_attempts`
+    # never bite. `perform_step_in(0, ...)` is the only re-dispatch that
+    # carries the count.
+    def redispatch(record, arguments)
+      attempts = record["contention_attempts"].to_i
+      return @async_router.perform_step_async(**arguments) unless attempts.positive?
+
+      @async_router.perform_step_in(0, **arguments, contention_attempts: attempts)
+    end
+
     def dispatch_arguments(record)
       values = record.values_at(*DISPATCH_KEYS)
       return nil if values.any?(&:nil?)
@@ -63,6 +75,22 @@ module RubyReactor
       DISPATCH_KEYS.map(&:to_sym).zip(values).to_h
     end
 
+    # A unit parked on step-level contention (StepWorker#handle_contention)
+    # released its liveness lock on purpose and has a redelivery already
+    # scheduled. It looks exactly like a lost unit, so without this the sweep
+    # would dispatch a duplicate that runs the body a second time once the
+    # redelivery fires. Past the stamped window it is fair game again — a
+    # redelivery that eventually lands on a finished unit is dropped by
+    # `StepWorker#already_completed?`.
+    def parked?(record)
+      parked_until = record["parked_until"]
+      return false unless parked_until
+
+      Time.iso8601(parked_until) > Time.now
+    rescue ArgumentError, TypeError
+      false
+    end
+
     def live?(arguments)
       @storage.lock_held?(
         RubyReactor.async_step_lock_key(arguments[:step_context_id], arguments[:step_name])

data/lib/ruby_reactor/step_worker.rb

@@ -11,7 +11,23 @@ module RubyReactor
   # load-bearing — the record is written BEFORE the signal, so a reader that
   # misses the (at-most-once) signal still finds the answer on its next
   # fallback re-check.
+  #
+  # Single writer: a context is written only by the execution that owns it,
+  # and this unit is not the parent's execution. It reads the parent's context
+  # and NEVER writes it back — the parent may be saving newer progress at this
+  # very moment, and an older snapshot written over it would revert that. The
+  # parent holds only the link written at dispatch (`:async_step_ref`); every
+  # fact about this unit — its run (arguments, attempts), its park state and
+  # its outcome — lives on its own Step Result Record, where the dashboard
+  # rebuilds it from the link. A body's changes to `context` are therefore
+  # local to this job and never persisted.
+  # rubocop:disable Metrics/ClassLength
   class StepWorker
+    # Grace added to a park's stamped window, so ordinary queue latency on the
+    # redelivery does not make `StepSweeper` mistake a parked unit for a lost
+    # one (see `#mark_record_parked`).
+    PARK_SWEEP_GRACE = 30
+
     class << self
       def perform(arguments)
         arguments = arguments.transform_keys(&:to_sym)
@@ -25,16 +41,18 @@ module RubyReactor
           root_context_id: arguments[:root_context_id],
           reactor_class_name: arguments[:reactor_class_name],
           step_context_id: arguments[:step_context_id],
-          step_name: arguments[:step_name].to_sym
+          step_name: arguments[:step_name].to_sym,
+          contention_attempts: arguments[:contention_attempts] || 0
         }
       end
     end
 
-    def initialize(root_context_id:, reactor_class_name:, step_context_id:, step_name:)
+    def initialize(root_context_id:, reactor_class_name:, step_context_id:, step_name:, contention_attempts: 0)
       @root_context_id = root_context_id
       @reactor_class_name = reactor_class_name
       @step_context_id = step_context_id || root_context_id
       @step_name = step_name
+      @contention_attempts = contention_attempts.to_i
     end
 
     # The lock is what makes a lost unit recoverable: the record alone cannot say
@@ -61,8 +79,15 @@ module RubyReactor
       context.reactor_class&.validate_definition!
       step_config = context.reactor_class&.steps&.[](@step_name)
       return record_missing_step unless step_config
+      return if already_completed?(context)
 
       complete(run_step(context, step_config), context)
+    rescue Executor::StepCoordination::Contended => e
+      handle_contention(e, context)
+    rescue Executor::StepCoordination::KeyError => e
+      log(:error, "failed", error: "#{e.class}: #{e.message}")
+      complete(RubyReactor.Failure(e, step_name: @step_name, reactor_name: @reactor_class_name, retryable: false),
+               context)
     rescue StandardError => e
       # The unit's failure belongs in its record, where a reader can see it.
       # Raising instead would hand the job to the backend's retry machinery to
@@ -71,6 +96,126 @@ module RubyReactor
       complete(RubyReactor.Failure(e, step_name: @step_name, reactor_name: @reactor_class_name), nil)
     end
 
+    # Finding 6: `async_step` has no delayed re-enqueue of its own, so a
+    # contended step parks the same way a step-level contention park does
+    # elsewhere — reschedule via `perform_step_in`, bounded by
+    # `lock_snooze_max_attempts` (the `OrderedLock::WaitError` exemption
+    # mirrors `Worker#handle_snooze`). WITHOUT calling `complete`: the Step
+    # Result Record stays "dispatched" so a reader keeps waiting instead of
+    # seeing a phantom terminal state.
+    def handle_contention(contended, context = nil)
+      # `run_step`'s loop counted this round as an attempt before the body
+      # raised; a contention park is not a retry attempt, so give it back —
+      # mirrors `StepExecutor#handle_contention`. Left inflated, the count
+      # persists across redeliveries and `StepCoordination#retry_pending?`
+      # eventually reads the step as out of retries, advancing its
+      # ordered-lock position out from under an attempt still to come.
+      context&.retry_context&.decrement_attempt_for_step(@step_name)
+
+      config = RubyReactor.configuration
+      attempt = @contention_attempts + 1
+      uncapped = contended.original.is_a?(RubyReactor::OrderedLock::WaitError)
+
+      if !uncapped && config.lock_snooze_max_attempts != :infinity && attempt > config.lock_snooze_max_attempts
+        log(:warn, "contention_exhausted", key: contended.key, attempt: attempt)
+        # Terminal: an earlier park kept this step's ordered-lock position for
+        # a redelivery that is no longer coming — advance it, or every later
+        # position stalls until its poison pill. `complete` then writes a
+        # fresh terminal record, which drops the position and waiting marker.
+        Executor::StepCoordination.discard_parked_state!(context) if context
+        complete(
+          RubyReactor::Failure(
+            "async_step :#{@step_name} gave up on #{contended.primitive} '#{contended.key}' after " \
+            "#{attempt} contention attempts",
+            step_name: @step_name, reactor_name: @reactor_class_name, retryable: false,
+            exception_class: contended.original.class.name
+          ), context
+        )
+        return
+      end
+
+      delay = RubyReactor::Worker.snooze_delay(config, contended)
+      log(:info, "parked", key: contended.key, primitive: contended.primitive, attempt: attempt, delay: delay)
+      mark_record_parked(context, delay, attempt, contended)
+      RubyReactor.configuration.async_router.perform_step_in(
+        delay, root_context_id: @root_context_id, reactor_class_name: @reactor_class_name,
+               step_context_id: @step_context_id, step_name: @step_name, contention_attempts: attempt
+      )
+    end
+
+    # The liveness lock only drops a CONCURRENT duplicate. A parked unit whose
+    # stamped window lapsed can be swept while its scheduled redelivery is
+    # merely late, so the two deliveries can run one after the other and repeat
+    # the side effect. The record is the durable answer: once it is terminal,
+    # the body must not run again.
+    #
+    # ponytail: the record check, not a durable delivery lease — it closes the
+    # repeat-after-completion case. Two deliveries that both arrive while the
+    # unit is still only parked still both run the body (serialized by the
+    # step's own coordination). Add a lease if that shows up in practice.
+    def already_completed?(context)
+      record = storage.retrieve_step_result(@step_context_id, @step_name, step_result_namespace(context))
+      return false unless record && record["status"] == "completed"
+
+      log(:info, "duplicate_dropped")
+      true
+    end
+
+    # A park releases the liveness lock (`perform`'s ensure) and leaves the
+    # Step Result Record at "dispatched" — which is EXACTLY the shape
+    # `StepSweeper` reads as "this unit's job was lost". Left unmarked it
+    # re-dispatches immediately, and when the parked redelivery then fires the
+    # body runs a second time: two jobs, sequential, so the liveness lock
+    # (which only drops CONCURRENT duplicates) never sees them collide.
+    # Stamping the window the redelivery is due in lets the sweeper tell
+    # parked from lost.
+    #
+    # ponytail: a fixed grace covers ordinary queue latency; a park whose
+    # redelivery is lost is recovered one grace period late rather than never.
+    # Make it configurable only if real queue lag exceeds it.
+    #
+    # The record is also where the unit's OWN park state lives (005 R-09):
+    # its ordered-lock position (`load_step_context` restores it on the
+    # redelivery) and what it waits on (the dashboard's "waiting"). Never the
+    # parent's root blob: the parent may be checkpointing newer progress right
+    # now, and this worker is not its writer (F5).
+    def mark_record_parked(context, delay, attempt, contended)
+      namespace = step_result_namespace(context)
+      record = storage.retrieve_step_result(@step_context_id, @step_name, namespace)
+      return unless record
+
+      record["parked_until"] = (Time.now + delay + PARK_SWEEP_GRACE).iso8601
+      # The counter lives in the job payload, which a sweeper re-dispatch
+      # rebuilds from the record alone — without it a swept park restarts at
+      # zero and `lock_snooze_max_attempts` never bites.
+      record["contention_attempts"] = attempt
+      position = ordered_lock_position(context)
+      record["ordered_lock"] = position if position
+      record["waiting"] = { "step" => @step_name, "primitive" => contended.primitive, "key" => contended.key,
+                            "attempts" => attempt }
+      record.merge!(run_fields)
+      storage.store_step_result(@step_context_id, @step_name, record, namespace)
+    rescue StandardError => e
+      RubyReactor.configuration.logger.warn(
+        "RubyReactor: async_step :#{@step_name} could not mark its record parked: #{e.message}"
+      )
+    end
+
+    def ordered_lock_position(context)
+      stash = context&.private_data&.[](:step_ordered_locks) || context&.private_data&.[]("step_ordered_locks")
+      return nil unless stash
+
+      stash[@step_name.to_s] || stash[@step_name.to_sym]
+    end
+
+    # Records are namespaced by the reactor that OWNS the step (what
+    # `AsyncStepDispatch#async_step_class_name` wrote them under), which for a
+    # composed child is not the root this job was handed.
+    def step_result_namespace(context)
+      owner = context&.reactor_class
+      owner ? RubyReactor.reactor_storage_name(owner) : @reactor_class_name
+    end
+
     def acquire_liveness_lock
       # Inline testing re-enters this frame synchronously, so the lock would
       # self-contend; it only guards cross-process delivery, impossible inline.
@@ -93,37 +238,89 @@ module RubyReactor
     end
 
     def run_step(context, step_config)
+      # A suppressed step never coordinates (FR-012) — decided before the
+      # arguments are validated or any hold is taken, exactly as
+      # `StepExecutor#execute_step_sync` orders it. `complete` persists the
+      # nil result, so the reader sees the same skipped unit a same-process
+      # step would produce.
+      unless step_config.should_run?(context)
+        log(:info, "skipped")
+        return RubyReactor.Success(nil)
+      end
+
       arguments = resolve_arguments(step_config, context)
+      # Reactor-side `argument`/`validate_args` rules gate the step BEFORE its
+      # coordination is acquired, exactly as `StepExecutor#execute_step_sync`
+      # orders them — an async_step must not take a lock (or spend a rate-limit
+      # slot) for arguments it is about to reject.
+      invalid = validate_arguments(step_config, arguments)
+      return invalid if invalid
+
       log(:info, "running")
+      # What `StepExecutor#run_step_implementation` records as a `:run` trace
+      # entry for a same-process step, kept on this unit's record instead (see
+      # the class comment): the dashboard resolves the step's coordination key
+      # and its inspector's arguments from it.
+      contract = step_config.input_contract
+      @run = { "started_at" => Time.now.iso8601(6),
+               "arguments" => ContextSerializer.serialize_value(contract ? contract.redact(arguments) : arguments) }
 
       attempt = 0
       result = nil
 
-      loop do
-        attempt += 1
-        result = execute_step_body(step_config, arguments, context)
-        break unless retry?(step_config, result, attempt)
-
-        delay = backoff_delay(step_config, attempt)
-        log(:warn, "retrying", attempt: attempt, delay: delay)
-        sleep(delay)
+      # Under `with_step`, exactly as `StepExecutor#execute_step_sync` runs a
+      # same-process step: the coordination hooks this worker fires must be
+      # attributable to the step, which reads `context.current_step`.
+      context.with_step(@step_name) do
+        loop do
+          attempt += 1
+          @run["attempts"] = attempt
+          # Mirror the count onto the context: `StepCoordination` reads
+          # `retry_context` to decide whether an ordered-lock position should be
+          # held for a pending retry, and this worker is the one path that never
+          # goes through `RetryManager#prepare_retry_attempt`.
+          context.retry_context.increment_attempt_for_step(@step_name)
+          result = execute_step_body(step_config, arguments, context)
+          break unless retry?(step_config, result, attempt)
+
+          delay = backoff_delay(step_config, attempt)
+          log(:warn, "retrying", attempt: attempt, delay: delay)
+          sleep(delay)
+        end
       end
 
       result
     end
 
+    # Same check and same structured, non-retryable shape `StepExecutor`
+    # produces — the same arguments fail the same rules on every attempt.
+    def validate_arguments(step_config, arguments)
+      return nil unless step_config.args_validator
+
+      validation_result = step_config.args_validator.call(arguments)
+      return nil if validation_result.success?
+
+      error = validation_result.error
+      error.step_name = @step_name
+      error.step_arguments = arguments
+      log(:warn, "invalid_arguments", error: "#{error.class}: #{error.message}")
+      RubyReactor.Failure(error, validation_errors: error.field_errors, step_name: @step_name,
+                                 step_arguments: arguments, reactor_name: @reactor_class_name,
+                                 retryable: false)
+    end
+
+    # The same single enforcement site `StepExecutor` uses
+    # (`StepCoordination.run_step`), so the worker path cannot drift from the
+    # in-process one. `Contended`/`KeyError` — this step's own — propagate
+    # unrescued: `perform_unit` handles them (park, or a non-retryable Failure).
     def execute_step_body(step_config, arguments, context)
-      result =
-        if step_config.has_run_block?
-          args = arguments.empty? ? context.inputs : arguments
-          args = step_config.inline_contract.enforce!(args) if step_config.inline_contract
-          step_config.run_block.call(args, context)
-        elsif step_config.has_impl?
-          step_config.impl.run(arguments, context)
-        else
-          RubyReactor.Failure("Step '#{@step_name}' has no implementation")
-        end
+      unless step_config.has_run_block? || step_config.has_impl?
+        return RubyReactor.Failure("Step '#{@step_name}' has no implementation")
+      end
 
+      result = Executor::StepCoordination.run_step(step_config, arguments, context: context,
+                                                                           reactor_class: context.reactor_class,
+                                                                           middlewares: context.middlewares)
       normalize(result)
     rescue Error::InputValidationError => e
       # Same shape the executor builds, and never retried: the same arguments
@@ -131,6 +328,8 @@ module RubyReactor
       RubyReactor.Failure(e, validation_errors: e.field_errors, step_name: @step_name,
                              step_arguments: e.step_arguments || {}, reactor_name: @reactor_class_name,
                              retryable: false)
+    rescue Executor::StepCoordination::Contended, Executor::StepCoordination::KeyError
+      raise
     rescue StandardError => e
       RubyReactor.Failure(e, step_name: @step_name, reactor_name: @reactor_class_name)
     end
@@ -182,14 +381,21 @@ module RubyReactor
         record["signal"] = "halt"
         record["reason"] = result.reason
       end
-      storage.store_step_result(@step_context_id, @step_name, record, @reactor_class_name)
+      record.merge!(run_fields)
+      # Namespaced by the reactor that OWNS the step — what
+      # `AsyncStepDispatch` wrote the `dispatched` record under and what the
+      # reader's `Template::Result` looks under. For an async_step inside a
+      # composed child that is the child, not the root name this job carries.
+      storage.store_step_result(@step_context_id, @step_name, record, step_result_namespace(context || @step_context))
       log(result.success? ? :info : :warn, result.success? ? "completed" : "completed_with_failure")
       storage.publish(RubyReactor.async_step_channel(@step_context_id, @step_name), "done")
       result
-    ensure
-      # A step body may have mutated the sub-context; nothing else will persist
-      # it, and the dashboard reads the parent's blob.
-      save_root(context) if context
+    end
+
+    # This delivery's run, once the body was reached: `started_at`,
+    # `arguments` (redacted, serialized) and `attempts`. Empty before that.
+    def run_fields
+      @run || {}
     end
 
     def record_missing_parent
@@ -219,16 +425,43 @@ module RubyReactor
       return nil unless data
 
       root = ContextSerializer.deserialize_hash(data)
-      @root_context = root
       found = find_context(root, @step_context_id)
+      # Kept so the paths that deliberately pass no context to `complete`
+      # still write the record under the owning reactor's namespace.
+      @step_context = found
+      restore_parked_position(found) if found
       # The step runs in its own job; nothing it reaches should hand off again.
       found&.inline_async_execution = true
+      # Per-job owner, NEVER the root context id (US4-5, research D5):
+      # ownership never crosses a process hand-off, so this job's coordination
+      # never re-enters the dispatching execution's holds and never blocks a
+      # SECOND async_step dispatch on the same key from proceeding once this
+      # one releases. Derived, not random: `StepCoordination` can detach a
+      # lock across a contention park, and `perform_step_in` redelivers this
+      # same unit — a fresh uuid per redelivery would make `lock.reattach`
+      # fail against its own detached hold until the TTL expired.
+      found&.coordination_owner = "async_step:#{@step_context_id}:#{@step_name}"
+      # `ContextSerializer` does not carry `middlewares`, and nothing else in
+      # this worker builds them — without this the step's coordination hooks
+      # fire into an empty runner, contradicting "identical hooks in a worker".
+      found&.middlewares ||= Executor.middlewares_for(found.reactor_class)
       found
     rescue RubyReactor::Error::DeserializationError, RubyReactor::Error::SchemaVersionError => e
       log(:error, "parent_context_unreadable", error: "#{e.class}: #{e.message}")
       nil
     end
 
+    # A parked unit's ordered-lock position lives on its own record, not in
+    # the parent's blob (see `mark_record_parked`). Put it back where
+    # `StepCoordination` looks, so the redelivery re-reads the SAME nonce.
+    def restore_parked_position(context)
+      record = storage.retrieve_step_result(@step_context_id, @step_name, step_result_namespace(context))
+      position = record && record["ordered_lock"]
+      return unless position
+
+      (context.private_data[:step_ordered_locks] ||= {})[@step_name.to_s] = position.transform_keys(&:to_sym)
+    end
+
     def find_context(context, target_id)
       return context if context.context_id == target_id
 
@@ -241,17 +474,6 @@ module RubyReactor
       nil
     end
 
-    def save_root(_context)
-      return unless @root_context
-
-      storage.store_context(@root_context.context_id, ContextSerializer.serialize(@root_context),
-                            @reactor_class_name)
-    rescue StandardError => e
-      RubyReactor.configuration.logger.warn(
-        "RubyReactor: async_step :#{@step_name} could not persist its parent context: #{e.message}"
-      )
-    end
-
     def storage
       RubyReactor.configuration.storage_adapter
     end
@@ -272,4 +494,5 @@ module RubyReactor
       )
     end
   end
+  # rubocop:enable Metrics/ClassLength
 end

data/lib/ruby_reactor/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module RubyReactor
-  VERSION = "0.8.1"
+  VERSION = "0.8.3"
 end