ruby_reactor 0.8.2 → 0.8.3

data/lib/ruby_reactor/executor/step_executor.rb

@@ -2,6 +2,7 @@
 
 module RubyReactor
   class Executor
+    # rubocop:disable Metrics/ClassLength
     class StepExecutor
       include AsyncStepDispatch
 
@@ -106,7 +107,13 @@ module RubyReactor
           end
           result
         rescue Exception => e # rubocop:disable Lint/RescueException
-          @middlewares.on(:failed_step, step_config.name, e, @context) unless completed
+          # A park signal (contention, or an awaited background result) is
+          # "try again later", never a failure: `:snooze_step`, mirroring
+          # `:snooze_reactor` (005 R-04).
+          unless completed
+            event = e.is_a?(Error::ExecutionParked) ? :snooze_step : :failed_step
+            @middlewares.on(event, step_config.name, e, @context)
+          end
           raise
         end
       end
@@ -191,6 +198,24 @@ module RubyReactor
         e.step_name = step_config.name
         e.step_arguments ||= resolved_arguments
         raise
+      rescue Executor::StepCoordination::Contended => e
+        handle_contention(step_config, e, resolved_arguments)
+      # `KeyError`: this step's coordination could not be resolved — a key proc
+      # that raised or returned nil/empty, or an unregistered `with_rate_limit`
+      # name. Not contention: a non-retryable failure, never a park (mirrors
+      # how the reactor-level equivalent escalates instead of snoozing in
+      # `Worker#perform`).
+      rescue Executor::StepCoordination::KeyError => e
+        RubyReactor::Failure(e, step_name: step_config.name, reactor_name: @reactor_class.name,
+                                step_arguments: resolved_arguments, inputs: @context.inputs, retryable: false)
+      # A park signal from a composed child (its contention, or its wait on a
+      # background result) is not this step failing: let it reach the
+      # executors above, which park their own holds, and the worker (F10).
+      # Nor is it a retry attempt: give back the one `prepare_retry_attempt`
+      # just counted, as `handle_contention` does for this step's own park.
+      rescue Error::ExecutionParked
+        @context.retry_context.decrement_attempt_for_step(step_config.name)
+        raise
       rescue StandardError => e
         # Identify redacted inputs
         redact_inputs = @reactor_class.inputs.select { |_, config| config[:redact] }.keys
@@ -205,6 +230,89 @@ module RubyReactor
         )
       end
 
+      # Contention (US3). Synchronously there is no queue to park into: the
+      # step fails. In a worker the execution parks at this step — by raising
+      # `Error::StepContentionPark`, which every executor on the stack lets
+      # through after parking its own holds, and which the worker (or
+      # `Map::ElementExecutor`) requeues once, at the top, after all of them
+      # have saved (005 R-01). Bounded by `lock_snooze_max_attempts` on this
+      # step's own contention counter, separate from its retry budget.
+      #
+      # `Context#with_step`'s `ensure` has already restored `current_step` to
+      # its pre-step value by the time this rescue runs, so it is pinned again
+      # here: it is the resume cursor the redelivery continues from.
+      def handle_contention(step_config, contended, resolved_arguments)
+        return contention_failure(step_config, contended, resolved_arguments) unless @context.inline_async_execution
+
+        @context.current_step = step_config.name
+        # Park evidence belongs to the async path ONLY: synchronously there is
+        # no requeue, the step just fails, and writing these would report a
+        # terminal execution as parked and leave the dashboard "waiting".
+        attempt = @context.retry_context.contention_attempts_for_step(step_config.name) + 1
+        @context.append_execution_trace(
+          { type: :contention_park, step: step_config.name, primitive: contended.primitive, key: contended.key,
+            attempt: attempt, timestamp: Time.now }
+        )
+        @context.private_data[:step_contention] = {
+          step: step_config.name, primitive: contended.primitive, key: contended.key, attempts: attempt,
+          next_attempt_at: nil
+        }
+        log_async_event(
+          "step_coordination.parked", step_config.name,
+          key: contended.key, primitive: contended.primitive, attempt: attempt
+        )
+
+        # A park is not a retry attempt (Finding 2): give back the one
+        # `prepare_retry_attempt` just counted, and count contention instead.
+        @context.retry_context.decrement_attempt_for_step(step_config.name)
+        count = @context.retry_context.increment_contention_for_step(step_config.name)
+        return contention_ceiling_failure(step_config, contended, count) if contention_ceiling?(contended, count)
+
+        raise Error::StepContentionPark, contended
+      end
+
+      # `OrderedLock::WaitError` is exempt, as in `Worker#handle_snooze`: its
+      # own poison-pill timeout is the only meaningful upper bound.
+      def contention_ceiling?(contended, count)
+        max = RubyReactor.configuration.lock_snooze_max_attempts
+        return false if contended.original.is_a?(RubyReactor::OrderedLock::WaitError)
+
+        max != :infinity && count > max
+      end
+
+      # Terminal: earlier parks kept this step's `:step_contention` marker
+      # (which would report a failed execution as still waiting on a key) and
+      # its un-advanced ordered-lock position (which would stall every
+      # successor until its poison_pill_timeout) for a redelivery that is no
+      # longer coming. Hand both back. Carried as a `Contended`, not a bare
+      # string, so `CompensationManager#step_never_started?` still recognises
+      # that this step's body never ran.
+      def contention_ceiling_failure(step_config, contended, count)
+        Executor::StepCoordination.discard_parked_state!(@context)
+        RubyReactor::Failure(
+          Executor::StepCoordination::Contended.new(
+            primitive: contended.primitive, key: contended.key, step_name: step_config.name,
+            reactor_name: @reactor_class.name, original: contended.original,
+            message: "Step '#{step_config.name}' gave up on #{contended.primitive} '#{contended.key}' after " \
+                     "#{count} contention attempts"
+          ),
+          step_name: step_config.name, reactor_name: @reactor_class.name, retryable: false,
+          exception_class: contended.original.class.name
+        )
+      end
+
+      # The `Contended` itself, not its `.original`: it is what tells
+      # `CompensationManager#step_never_started?` that THIS step's own
+      # acquisition failed. A bare `Lock::AcquisitionError` could equally have
+      # been raised by the body (a nested `Reactor.run`), whose side effects
+      # must be compensated. `ResultHandler#resolve_exception_class` reports
+      # the cause's class.
+      def contention_failure(step_config, contended, resolved_arguments)
+        RubyReactor::Failure(contended, step_name: step_config.name, reactor_name: @reactor_class.name,
+                                        step_arguments: resolved_arguments, inputs: @context.inputs,
+                                        retryable: false, exception_class: contended.original.class.name)
+      end
+
       def execute_step_sync(step_config, resolved_arguments = nil)
         @context.with_step(step_config.name) do
           # Check conditions and guards
@@ -349,22 +457,17 @@ module RubyReactor
           { type: :run, step: step_config.name, timestamp: Time.now,
             arguments: contract ? contract.redact(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
-          args_to_pass = step_config.inline_contract.enforce!(args_to_pass) if step_config.inline_contract
-          catch(StepSignals::TAG) { step_config.run_block.call(args_to_pass, @context) }
-        elsif step_config.has_impl?
-          # Execute step class
-          catch(StepSignals::TAG) { step_config.impl.run(arguments, @context) }
-        else
+        unless step_config.has_run_block? || step_config.has_impl?
           raise Error::ValidationError.new(
             "Step '#{step_config.name}' has no implementation",
             step: step_config.name,
             context: @context
           )
         end
+
+        Executor::StepCoordination.run_step(step_config, arguments, context: @context,
+                                                                    reactor_class: @reactor_class,
+                                                                    middlewares: @middlewares)
       end
 
       def find_context_by_id(root_context, target_id)
@@ -382,5 +485,6 @@ module RubyReactor
         nil
       end
     end
+    # rubocop:enable Metrics/ClassLength
   end
 end

data/lib/ruby_reactor/executor.rb

@@ -4,6 +4,9 @@ require "English"
 require_relative "executor/input_validator"
 require_relative "executor/graph_manager"
 require_relative "executor/retry_manager"
+# Before compensation_manager: its NEVER_STARTED_ERROR_CLASSES names
+# StepCoordination at load time, while `class Executor` does not exist yet.
+require_relative "executor/step_coordination"
 require_relative "executor/compensation_manager"
 require_relative "executor/result_handler"
 require_relative "executor/async_step_dispatch"
@@ -118,6 +121,7 @@ module RubyReactor
         return finalize_halt(halted)
       end
 
+      @context.admit!
       @context.status = :running
       save_context
 
@@ -137,12 +141,15 @@ module RubyReactor
            RubyReactor::RateLimitRegistry::UnknownLimitError,
            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.
+      raise composed_contention_park(e) || e
+    rescue Error::ExecutionParked
+      # A park signal from a step of this run (its contention, or a wait on a
+      # background result), reaching a composed child's or a map element's
+      # first run. Every executor on the stack keeps its OWN lock/semaphore
+      # through the gap and re-adopts it on redelivery (005 D-A2); the worker
+      # at the top requeues once, after all of them have saved. A synchronous
+      # caller never sees a park signal: nothing raises one outside a worker.
+      park_held_primitives! if @context.inline_async_execution
       @contention_snooze = true
       raise
     rescue StandardError => e
@@ -151,7 +158,7 @@ module RubyReactor
       completed = true
       @result
     ensure
-      release_locks
+      release_locks unless @parked
       leave_ordered_lock_scope
       save_context if persist_context? && !skip_context_persist?
 
@@ -226,6 +233,10 @@ module RubyReactor
         return finalize_halt(halted)
       end
 
+      # Past every reactor-level gate. Idempotent for a genuine resume, which
+      # was admitted on its first run (or, saved before `admitted` existed,
+      # is marked now).
+      @context.admit!
       prepare_for_resume
       save_context
 
@@ -247,12 +258,14 @@ module RubyReactor
            RubyReactor::RateLimitRegistry::UnknownLimitError,
            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.
+      raise composed_contention_park(e) || e
+    rescue Error::ExecutionParked => e
+      # A step of this run parked (contention, or an awaited background result
+      # not terminal yet) — here, or in a composed child that already parked
+      # its own holds on the way through. 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
@@ -370,8 +383,15 @@ module RubyReactor
     # `execute` for sync reactors, the first `resume_execution` pass for async
     # reactors. Genuine resumes never re-check (a paused reactor must not block
     # itself on resume).
+    #
+    # At most once per execution: a lock or semaphore contended right after
+    # the charge snoozes the job BEFORE admission, and its redelivery is still
+    # a first run. The `rate_limit_charged` marker rides `private_data`, so
+    # that redelivery skips the charge but still runs every other first-run
+    # gate (the period re-check above all).
     def check_rate_limit
       return unless @reactor_class.respond_to?(:rate_limit_config) && @reactor_class.rate_limit_config
+      return if @context.private_data[:rate_limit_charged] || @context.private_data["rate_limit_charged"]
 
       config = @reactor_class.rate_limit_config
 
@@ -386,14 +406,53 @@ module RubyReactor
       end
 
       RubyReactor::RateLimit.new(key_base, limits: limits).check_and_increment!
+      @context.private_data[:rate_limit_charged] = true
     end
 
-    # True when nothing has run yet for this context — the very first execution
-    # of the reactor, including an async reactor's first worker pass. A genuine
-    # resume (paused, async-handed-off, or retried step) always records a
-    # `current_step` before serializing, so it is never mistaken for a first run.
+    # True when this execution has not yet passed its reactor-level gates —
+    # the very first execution, including an async reactor's first worker
+    # pass. Read from the explicit `admitted` marker, so a park at any depth
+    # (which unwinds `with_step` and clears `current_step`) can never make a
+    # redelivery look fresh and re-charge its rate limit (005 R-03). The old
+    # inference is AND-ed in so a context saved before the marker existed
+    # still resumes as it did.
     def first_execution?
-      @context.current_step.nil? && @context.intermediate_results.empty?
+      !@context.admitted? && @context.current_step.nil? && @context.intermediate_results.empty?
+    end
+
+    # A composed child's own reactor-level contention inside a worker. A
+    # root's reaches `Worker#perform`, which snoozes the job; a child's would
+    # first reach the step that composed it, which turns any error into an
+    # ordinary step failure (F3). So the child raises a park signal instead,
+    # and every executor above it keeps its holds until the worker requeues.
+    #
+    # Bounded where it is raised, like a step's contention park (005 R-05):
+    # the child counts its own parks, and past `lock_snooze_max_attempts` the
+    # contention error goes through as that step's failure, so the parent
+    # rolls back and releases its holds — which the worker's snooze
+    # escalation would do neither of. Returns nil to raise `error` unchanged.
+    def composed_contention_park(error)
+      return nil unless @context.inline_async_execution && @context.root_context
+      # A configuration mistake, not contention: it stays a permanent failure.
+      return nil if error.is_a?(RubyReactor::RateLimitRegistry::UnknownLimitError)
+      return nil if within_inline_map_element?
+
+      parks = (@context.private_data[:admission_parks] || @context.private_data["admission_parks"]).to_i + 1
+      @context.private_data[:admission_parks] = parks
+      max = RubyReactor.configuration.lock_snooze_max_attempts
+      return nil if max != :infinity && parks > max
+
+      Error::ReactorContentionPark.new(error)
+    end
+
+    # An inline (non-fan-out) map element has no persisted context of its own:
+    # a park re-runs the whole map step with fresh element contexts, repeating
+    # the elements that already finished and restarting the count above (005
+    # R-01, "Known, not changed"). Under one, contention stays a failure.
+    def within_inline_map_element?
+      ctx = @context
+      ctx = ctx.parent_context until ctx.nil? || (ctx.map_metadata && ctx.root_context)
+      !ctx.nil?
     end
 
     # Record and persist a Halt result, then return it. Shared by the
@@ -612,7 +671,7 @@ module RubyReactor
       if @acquired_semaphore
         key = @acquired_semaphore.key
         release_one("semaphore", @acquired_semaphore)
-        held_lock_keys.delete(key)
+        pop_held_lock_key(key)
         middlewares.on(:semaphore_released, key, @context)
       end
       @acquired_semaphore = nil
@@ -621,11 +680,22 @@ module RubyReactor
 
       key = @acquired_lock.key
       release_one("lock", @acquired_lock)
-      held_lock_keys.delete(key)
+      pop_held_lock_key(key)
       @acquired_lock = nil
       middlewares.on(:lock_released, key, @context)
     end
 
+    # Pop a SINGLE occurrence of `key`, not every occurrence (Finding 1).
+    # With a reactor and a step both holding K, the step's release must not
+    # erase the reactor's still-open entry — the async deadlock guard reads
+    # this registry and would stop seeing K held while the reactor's own
+    # hold is still live. `StepCoordination#pop_key` mirrors this exactly.
+    def pop_held_lock_key(key)
+      keys = held_lock_keys
+      idx = keys.index(key)
+      keys.delete_at(idx) if idx
+    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

data/lib/ruby_reactor/map/element_executor.rb

@@ -61,7 +61,15 @@ module RubyReactor
         return if check_fail_fast?(arguments, storage)
 
         executor = Executor.new(context.reactor_class, {}, context)
-        arguments[:serialized_context] ? executor.resume_execution : executor.execute
+        begin
+          arguments[:serialized_context] ? executor.resume_execution : executor.execute
+        rescue Error::ExecutionParked => e
+          # The element parked (a step's contention, or an awaited background
+          # result) and its executor already parked its own holds on the
+          # context: requeue the element with that context, like `Worker`
+          # snoozes a reactor. Not finished — no result, no counter decrement.
+          return requeue_parked_element(arguments, context, e)
+        end
 
         result = executor.result
 
@@ -75,6 +83,20 @@ module RubyReactor
         finalize_execution(arguments, storage)
       end
 
+      def self.requeue_parked_element(arguments, context, error)
+        context.middlewares&.on(:before_async_enqueue, context)
+        config = RubyReactor.configuration
+        config.async_router.perform_map_element_in(
+          Worker.snooze_delay(config, error),
+          map_id: arguments[:map_id], element_id: arguments[:element_id], index: arguments[:index],
+          serialized_inputs: arguments[:serialized_inputs], reactor_class_info: arguments[:reactor_class_info],
+          strict_ordering: arguments[:strict_ordering], parent_context_id: arguments[:parent_context_id],
+          parent_reactor_class_name: arguments[:parent_reactor_class_name], step_name: arguments[:step_name],
+          batch_size: arguments[:batch_size], serialized_context: ContextSerializer.serialize(context),
+          fail_fast: arguments[:fail_fast]
+        )
+      end
+
       def self.load_parent_context(arguments, reactor_class_name, storage)
         parent_context_data = storage.retrieve_context(arguments[:parent_context_id], reactor_class_name)
         parent_reactor_class = Object.const_get(reactor_class_name)
@@ -204,7 +226,7 @@ module RubyReactor
         RubyReactor::Map::Dispatcher.perform(next_batch_args)
       end
 
-      private_class_method :load_parent_context, :trigger_next_batch_if_needed
+      private_class_method :load_parent_context, :trigger_next_batch_if_needed, :requeue_parked_element
     end
   end
 end

data/lib/ruby_reactor/map/helpers.rb

@@ -90,6 +90,9 @@ module RubyReactor
             executor.middlewares.on(:failed_reactor, parent_context.reactor_class.name, failure_response,
                                     parent_context)
           end
+          # This branch runs no executor loop, so nothing else persists the
+          # failed status: store it here.
+          store_parent(parent_context, storage)
         else
           parent_context.set_result(step_name_sym, final_result.value)
 
@@ -116,20 +119,41 @@ module RubyReactor
           # `after:` target here in the collector instead of the original
           # dispatching worker.
           parent_context.inline_async_execution = true
-          executor.resume_execution
+          resume_parked_aware(executor, parent_context)
         end
+      end
+
+      # `resume_execution` persists the parent itself — under the parent's
+      # context lock, and deliberately NOT when it lost that lock to a live
+      # duplicate or replayed an already-terminal run. Storing again here, after
+      # the lock is released, would overwrite whatever the lock's holder wrote
+      # (single writer), so the resume's own save is the only one.
+      #
+      # This collector is a worker running the parent's execution, so it is
+      # also a final handler for park signals (005 R-01), like `Worker` and
+      # `ElementExecutor`: the resume has already parked the parent's holds and
+      # saved; hand the rest back to the parent's own worker.
+      #
+      # The parent is loaded from its own blob, so it has no `root_context`:
+      # a map inside a composed child resumes and requeues that child as its
+      # own execution, never its root. ponytail: the root is never resumed
+      # after such a map (already so on main); see "Fan-out map inside a
+      # composed child" in specs/future_improvements.md.
+      def resume_parked_aware(executor, parent_context)
+        executor.resume_execution
+      rescue RubyReactor::Error::ExecutionParked => e
+        config = RubyReactor.configuration
+        config.async_router.perform_in(
+          RubyReactor::Worker.snooze_delay(config, e), parent_context.context_id,
+          RubyReactor.reactor_storage_name(parent_context.reactor_class)
+        )
+      end
 
-        # Checkpoint the ROOT, not the sub (F9/C2). When the map is embedded in a
-        # composed sub-reactor, parent_context is the *sub*; storing only the sub
-        # would leave the root blob stale and a rehydrate-by-root-id resume would
-        # lose the map's completion. Resolve the root (which embeds the sub's
-        # post-map state via composed_contexts) and store that. For a top-level
-        # map parent_context IS the root, so this is unchanged.
-        root = parent_context.root_context || parent_context
+      def store_parent(parent_context, storage)
         storage.store_context(
-          root.context_id,
-          ContextSerializer.serialize(root),
-          RubyReactor.reactor_storage_name(root.reactor_class)
+          parent_context.context_id,
+          ContextSerializer.serialize(parent_context),
+          RubyReactor.reactor_storage_name(parent_context.reactor_class)
         )
       end
     end

data/lib/ruby_reactor/max_retries_exhausted_failure.rb

@@ -7,12 +7,12 @@ module RubyReactor
     # rubocop:disable Metrics/ParameterLists
     def initialize(message, step:, attempts:, original_error: nil,
                    inputs: {}, backtrace: nil, redact_inputs: [],
-                   reactor_name: nil, step_arguments: {}, validation_errors: nil)
+                   reactor_name: nil, step_arguments: {}, validation_errors: nil, rollback_failures: nil)
       # rubocop:enable Metrics/ParameterLists
       super(message,
             step_name: step, inputs: inputs, backtrace: backtrace,
             redact_inputs: redact_inputs, reactor_name: reactor_name, step_arguments: step_arguments,
-            validation_errors: validation_errors)
+            validation_errors: validation_errors, rollback_failures: rollback_failures)
       @attempts = attempts
       @original_error = original_error
     end

data/lib/ruby_reactor/open_telemetry.rb

@@ -185,6 +185,24 @@ module RubyReactor
       span.finish
     end
 
+    # The step's attempt ended in a park (its contention, or an awaited
+    # background result): not a failure, and the redelivery opens a new span.
+    # Closed here, since neither `complete_step` nor `failed_step` fires for
+    # it and the span is keyed by step name.
+    def on_snooze_step(step_name, error, _context)
+      token = @step_tokens.delete(step_name)
+      ::OpenTelemetry::Context.detach(token) if token
+      @retry_errors.delete(step_name)
+
+      span = @step_spans.delete(step_name)
+      return unless span
+
+      span.set_attribute("step.status", "parked")
+      span.set_attribute("step.park_reason", error.class.name)
+      span.status = ::OpenTelemetry::Trace::Status.ok
+      span.finish
+    end
+
     def on_retry_attempt(step_name, attempt, error, _context)
       return unless defined?(::OpenTelemetry)
 
@@ -371,63 +389,82 @@ module RubyReactor
       RubyReactor.configuration.logger.warn("Telemetry context injection failed: #{e.message}")
     end
 
-    def on_lock_acquired(key, _context)
+    def on_lock_acquired(key, context)
       span = @reactor_span
       return unless span
 
-      span.set_attribute("reactor.lock.key", key.to_s)
-      span.add_event("lock_acquired", attributes: { "lock.key" => key.to_s })
+      # The reactor span's own attributes describe the REACTOR's hold; a step's
+      # is recorded on its event only, so it can never overwrite them.
+      span.set_attribute("reactor.lock.key", key.to_s) unless coordinating_step(context)
+      span.add_event("lock_acquired", attributes: step_attributes(context).merge("lock.key" => key.to_s))
     end
 
-    def on_lock_released(key, _context)
+    def on_lock_released(key, context)
       span = @reactor_span
       return unless span
 
-      span.add_event("lock_released", attributes: { "lock.key" => key.to_s })
+      span.add_event("lock_released", attributes: step_attributes(context).merge("lock.key" => key.to_s))
     end
 
-    def on_lock_failed(key, error, _context)
+    def on_lock_failed(key, error, context)
       span = @reactor_span
       return unless span
 
-      span.add_event("lock_acquisition_failed", attributes: {
-                       "lock.key" => key.to_s,
-                       "error.message" => error.message,
-                       "error.class" => error.class.name
-                     })
+      span.add_event("lock_acquisition_failed", attributes: step_attributes(context).merge(
+        "lock.key" => key.to_s,
+        "error.message" => error.message,
+        "error.class" => error.class.name
+      ))
     end
 
-    def on_semaphore_acquired(key, limit, _context)
+    def on_semaphore_acquired(key, limit, context)
       span = @reactor_span
       return unless span
 
-      span.set_attribute("reactor.semaphore.key", key.to_s)
-      span.set_attribute("reactor.semaphore.limit", limit.to_i)
+      unless coordinating_step(context)
+        span.set_attribute("reactor.semaphore.key", key.to_s)
+        span.set_attribute("reactor.semaphore.limit", limit.to_i)
+      end
       span.add_event("semaphore_acquired",
-                     attributes: { "semaphore.key" => key.to_s, "semaphore.limit" => limit.to_i })
+                     attributes: step_attributes(context).merge("semaphore.key" => key.to_s,
+                                                                "semaphore.limit" => limit.to_i))
     end
 
-    def on_semaphore_released(key, _context)
+    def on_semaphore_released(key, context)
       span = @reactor_span
       return unless span
 
-      span.add_event("semaphore_released", attributes: { "semaphore.key" => key.to_s })
+      span.add_event("semaphore_released", attributes: step_attributes(context).merge("semaphore.key" => key.to_s))
     end
 
-    def on_semaphore_failed(key, limit, error, _context)
+    def on_semaphore_failed(key, limit, error, context)
       span = @reactor_span
       return unless span
 
-      span.add_event("semaphore_acquisition_failed", attributes: {
-                       "semaphore.key" => key.to_s,
-                       "semaphore.limit" => limit.to_i,
-                       "error.message" => error.message,
-                       "error.class" => error.class.name
-                     })
+      span.add_event("semaphore_acquisition_failed", attributes: step_attributes(context).merge(
+        "semaphore.key" => key.to_s,
+        "semaphore.limit" => limit.to_i,
+        "error.message" => error.message,
+        "error.class" => error.class.name
+      ))
     end
 
     private
 
+    # US7/FR-028: attribute a step-level hold to the step that took it, on
+    # each EVENT (several steps can coordinate within one reactor span).
+    # `coordinating_step` is set by `StepCoordination` around its own hooks
+    # only — NOT `current_step`, which is also set while a resumed reactor
+    # re-takes its own reactor-level holds.
+    def coordinating_step(context)
+      context.respond_to?(:coordinating_step) ? context.coordinating_step : nil
+    end
+
+    def step_attributes(context)
+      step = coordinating_step(context)
+      step ? { "ruby_reactor.step" => step.to_s } : {}
+    end
+
     def extract_context(context)
       return nil unless defined?(::OpenTelemetry)