ruby_reactor 0.8.2 → 0.8.3

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.2"
+  VERSION = "0.8.3"
 end

data/lib/ruby_reactor/web/api.rb

@@ -47,6 +47,9 @@ module RubyReactor
               structure = self.class.build_structure(reactor_class) if reactor_class.respond_to?(:steps)
 
               api_status = self.class.reactor_status(data)
+              class_name = data[:reactor_class]&.to_s
+              runs = self.class.async_step_runs(data[:composed_contexts], class_name)
+              trace = self.class.with_async_step_runs(data[:execution_trace] || [], runs)
 
               response_data = {
                 id: data[:context_id],
@@ -55,7 +58,9 @@ module RubyReactor
                 current_step: data[:current_step].to_s,
                 retry_count: data[:retry_count] || 0,
                 undo_stack: data[:undo_stack] || [],
-                step_attempts: data.dig(:retry_context, :step_attempts) || {},
+                step_attempts: self.class.with_async_step_attempts(
+                  data.dig(:retry_context, :step_attempts) || {}, runs
+                ),
                 created_at: data[:started_at],
                 inputs: data[:inputs],
                 intermediate_results: self.class.with_map_summaries(
@@ -65,15 +70,14 @@ module RubyReactor
                 # Once per reactor, never per step: the old per-step `async`
                 # field is gone because there is now exactly one hand-off point.
                 background_handoff: self.class.background_handoff_for(reactor_class),
-                steps: data[:execution_trace] || [],
-                composed_contexts: self.class.hydrate_composed_contexts(
-                  data[:composed_contexts] || {},
-                  data[:reactor_class]&.to_s
-                ),
+                steps: trace,
+                composed_contexts: self.class.hydrate_composed_contexts(data[:composed_contexts] || {}, class_name),
                 coordination: CoordinationSerializer.build(
                   reactor_class,
                   inputs: data[:inputs],
-                  context_id: data[:context_id]
+                  context_id: data[:context_id],
+                  execution_trace: trace,
+                  private_data: data[:private_data] || {}
                 ),
                 error: data[:failure_reason]
               }
@@ -294,11 +298,72 @@ module RubyReactor
           when "map_ref" then hydrate_map_ref(value, reactor_class_name)
           when "async_step_ref" then hydrate_async_step_ref(value, reactor_class_name)
           when "async_reactor_ref" then hydrate_async_reactor_ref(value)
+          when "composed" then hydrate_composed_child(value)
           else value
           end
         end
       end
 
+      # An inline `compose` child is embedded in the parent's blob, so its own
+      # `async_step` links are rebuilt the same way, one level down.
+      def self.hydrate_composed_child(value)
+        child = value[:context] || value["context"]
+        return value unless child.is_a?(RubyReactor::Context)
+
+        class_name = RubyReactor.reactor_storage_name(child.reactor_class)
+        runs = async_step_runs(child.composed_contexts, class_name)
+        view = child.to_h.merge(
+          execution_trace: with_async_step_runs(child.execution_trace, runs),
+          composed_contexts: hydrate_composed_contexts(child.composed_contexts, class_name)
+        )
+        value.merge(context: view)
+      end
+
+      # Single writer: an `async_step` unit never writes its parent, which
+      # holds only the `:async_step_ref` written at dispatch. The unit's run —
+      # arguments, attempts, when it started — is on its Step Result Record.
+      # `{ step_name => record }` for every linked unit that has started.
+      def self.async_step_runs(composed_contexts, reactor_class_name)
+        return {} unless composed_contexts.is_a?(Hash)
+
+        composed_contexts.each_with_object({}) do |(name, ref), runs|
+          next unless (ref[:type] || ref["type"]).to_s == "async_step_ref"
+
+          record = async_step_record(ref, reactor_class_name)
+          runs[name] = record if record&.key?("started_at")
+        end
+      end
+
+      def self.async_step_record(ref_data, reactor_class_name)
+        context_id = ref_data[:context_id] || ref_data["context_id"]
+        name = ref_data[:name] || ref_data["name"]
+        return nil unless context_id && name
+
+        RubyReactor.configuration.storage_adapter.retrieve_step_result(context_id, name, reactor_class_name)
+      end
+
+      # The parent's own trace, with each started unit's `:run` entry placed by
+      # its start time — the entry a same-process step writes for itself. A
+      # unit that already has one (a context saved before units stopped
+      # writing their parent) is left as it is.
+      def self.with_async_step_runs(trace, runs)
+        runs.each_with_object(trace.dup) do |(name, record), merged|
+          next if merged.any? { |e| (e[:type] || e["type"]).to_s == "run" && (e[:step] || e["step"]).to_s == name.to_s }
+
+          started = Time.iso8601(record["started_at"])
+          entry = { type: :run, step: name, timestamp: started, background: true,
+                    arguments: ContextSerializer.deserialize_value(record["arguments"]) }
+          later = merged.index { |e| e[:timestamp].is_a?(Time) && e[:timestamp] > started }
+          merged.insert(later || merged.size, entry)
+        end
+      end
+
+      def self.with_async_step_attempts(step_attempts, runs)
+        runs.each_with_object(step_attempts.dup) do |(name, record), merged|
+          merged[name] = record["attempts"] if record["attempts"]
+        end
+      end
+
       # The reference lives on the parent's context; the outcome lives in the
       # Step Result Record. Resolve it so the dashboard can show whether the
       # unit is still dispatched or has landed, mirroring hydrate_map_ref.

data/lib/ruby_reactor/web/coordination_serializer.rb

@@ -4,7 +4,7 @@ module RubyReactor
   module Web
     class CoordinationSerializer
       class << self
-        def build(reactor_class, inputs:, context_id:)
+        def build(reactor_class, inputs:, context_id:, execution_trace: [], private_data: {})
           return {} unless reactor_class
 
           adapter = RubyReactor.configuration.storage_adapter
@@ -20,18 +20,122 @@ module RubyReactor
           end
 
           if reactor_class.rate_limit_config
-            result[:rate_limit] = build_rate_limit(reactor_class.rate_limit_config, normalized_inputs, adapter)
+            result[:rate_limit] = build_rate_limit(resolve_rate_limit(reactor_class.rate_limit_config),
+                                                   normalized_inputs, adapter)
           end
 
           if reactor_class.period_config
             result[:period] = build_period(reactor_class.period_config, normalized_inputs, adapter)
           end
 
+          if reactor_class.respond_to?(:steps)
+            steps = build_steps(reactor_class, normalized_inputs, context_id, execution_trace, adapter)
+            result[:steps] = steps unless steps.empty?
+          end
+
+          waiting = private_data[:step_contention] || private_data["step_contention"] ||
+                    async_step_waiting(reactor_class, context_id, adapter)
+          result[:waiting] = normalize_waiting(waiting) if waiting
+
           result
         end
 
         private
 
+        # US7/FR-029: one row per coordinating step PER PRIMITIVE it declares,
+        # keyed to the step's OWN resolved arguments (from its latest `:run`
+        # trace entry), not the reactor's inputs. A step declaring both
+        # `with_lock` and `with_semaphore` is two rows — both gates are active,
+        # so an operator has to be able to see both. A step not yet reached is
+        # reported "pending" rather than omitted, so the list is stable.
+        def build_steps(reactor_class, inputs, context_id, execution_trace, adapter)
+          reactor_class.steps.flat_map do |name, step_config|
+            next [] unless step_config.respond_to?(:declares_coordination?) && step_config.declares_coordination?
+
+            build_step_entries(name, step_config, inputs, context_id, execution_trace, adapter)
+          end
+        end
+
+        def build_step_entries(name, step_config, inputs, context_id, execution_trace, adapter) # rubocop:disable Metrics/ParameterLists
+          entry = latest_run_entry(execution_trace, name)
+          declarations = step_config.coordination_declarations
+          return [{ step: name.to_s, state: "pending" }] if declarations.empty?
+
+          # One PENDING row per declared primitive too, matching the reached
+          # shape below — a step declaring both a lock and a semaphore has two
+          # gates to wait on, and collapsing them to a single primitive-less
+          # row hides which.
+          if entry.nil?
+            return declarations.keys.map do |primitive|
+              { step: name.to_s, primitive: primitive.to_s, state: "pending" }
+            end
+          end
+
+          # The trace records the RESOLVED arguments; the execution keyed off
+          # `coordination_arguments` of them, so the same function is applied
+          # here. A redacted value was never recorded, so a key computed from it
+          # would name a different Redis key than the one held — report it as
+          # unavailable instead of probing the wrong one.
+          traced = entry[:arguments] || entry["arguments"] || {}
+          if traced.is_a?(Hash) && traced.value?(RubyReactor::Step::InputContract::REDACTED)
+            return declarations.keys.map do |primitive|
+              { step: name.to_s, primitive: primitive.to_s, key: nil,
+                key_error: "key unavailable: the step's arguments are redacted" }
+            end
+          end
+          args = step_config.coordination_arguments(traced.transform_keys(&:to_sym), inputs)
+
+          declarations.map do |primitive, config|
+            built = build_step_primitive(primitive, config, args, context_id, adapter)
+            { step: name.to_s, primitive: primitive.to_s }.merge(built)
+          end
+        end
+
+        def build_step_primitive(primitive, config, args, context_id, adapter)
+          case primitive
+          when :lock then build_lock(config, args, context_id, adapter)
+          when :semaphore then build_semaphore(config, args, adapter)
+          when :rate_limit then build_rate_limit(resolve_rate_limit(config), args, adapter)
+          when :period then build_period(config, args, adapter)
+          else { key: resolve_key(config[:key_proc], args) }
+          end
+        rescue StandardError => e
+          { key: nil, key_error: e.message }
+        end
+
+        def latest_run_entry(execution_trace, step_name)
+          Array(execution_trace).reverse_each.find do |e|
+            type = e[:type] || e["type"]
+            step = e[:step] || e["step"]
+            type.to_s == "run" && step.to_s == step_name.to_s
+          end
+        end
+
+        # A parked `async_step` keeps its "waiting on" marker on its own Step
+        # Result Record, never on the parent's context (005 R-09).
+        def async_step_waiting(reactor_class, context_id, adapter)
+          return nil unless context_id && reactor_class.respond_to?(:steps)
+
+          namespace = RubyReactor.reactor_storage_name(reactor_class)
+          reactor_class.steps.each do |name, step_config|
+            next unless step_config.respond_to?(:async_dispatch) && step_config.async_dispatch == :step
+
+            record = adapter.retrieve_step_result(context_id, name, namespace)
+            return record["waiting"] if record.is_a?(Hash) && record["waiting"]
+          end
+          nil
+        end
+
+        def normalize_waiting(waiting)
+          {
+            step: (waiting[:step] || waiting["step"]).to_s,
+            key: waiting[:key] || waiting["key"],
+            primitive: (waiting[:primitive] || waiting["primitive"]).to_s,
+            attempts: waiting[:attempts] || waiting["attempts"],
+            next_attempt_at: waiting[:next_attempt_at] || waiting["next_attempt_at"]
+          }
+        end
+
         def normalize_inputs(inputs)
           return {} unless inputs.is_a?(Hash)
 
@@ -134,6 +238,20 @@ module RubyReactor
           }
         end
 
+        # `with_rate_limit(:name)` stores only the name; the renderer needs the
+        # registered windows and the name-as-key the limiter actually uses
+        # (mirrors `StepCoordination#rate_limit_key_and_limits`).
+        def resolve_rate_limit(config)
+          return config unless config[:name]
+
+          name = config[:name]
+          { limits: RubyReactor.configuration.rate_limits.fetch(name), key_proc: ->(_args) { name.to_s } }
+        rescue StandardError => e
+          # An unregistered name is a config mistake, not a reason for the
+          # dashboard to 500 — surface it as this row's key_error.
+          { limits: [], key_proc: ->(_args) { raise e } }
+        end
+
         def map_limits(limits)
           Array(limits).map do |window|
             {