ruby_reactor 0.5.4 → 0.7.0

data/lib/ruby_reactor/adapters/sidekiq/router.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+module RubyReactor
+  module Adapters
+    module Sidekiq
+      class Router
+        # Identity-only payload: the worker rehydrates the live context from storage
+        # by (context_id, reactor_class_name). The caller already holds context_id, so
+        # there is no blob to deserialize here.
+        def self.perform_async(context_id, reactor_class_name = nil, intermediate_results: {})
+          job_id = RubyReactor::Adapters::Sidekiq::Worker.perform_async(context_id, reactor_class_name)
+          RubyReactor::DispatchResult.new(job_id: job_id, intermediate_results: intermediate_results,
+                                       execution_id: context_id)
+        end
+
+        def self.perform_in(delay, context_id, reactor_class_name = nil, intermediate_results: {})
+          job_id = RubyReactor::Adapters::Sidekiq::Worker.perform_in(delay, context_id, reactor_class_name)
+          RubyReactor::DispatchResult.new(job_id: job_id, intermediate_results: intermediate_results,
+                                       execution_id: context_id)
+        end
+
+        # One `async_step`'s work, dispatched as its own independent unit. The
+        # payload is identity-only for the same reason every other dispatch here
+        # is: the worker rehydrates the parent context from storage.
+        def self.perform_step_async(root_context_id:, reactor_class_name:, step_context_id:, step_name:)
+          job_id = RubyReactor::Adapters::Sidekiq::StepWorker.perform_async(
+            {
+              "root_context_id" => root_context_id,
+              "reactor_class_name" => reactor_class_name,
+              "step_context_id" => step_context_id,
+              "step_name" => step_name.to_s
+            }
+          )
+          RubyReactor::DispatchResult.new(job_id: job_id)
+        end
+
+        # rubocop:disable Metrics/ParameterLists
+        def self.perform_map_element_async(map_id:, element_id:, index:, serialized_inputs:, reactor_class_info:,
+                                           strict_ordering:, parent_context_id:, parent_reactor_class_name:,
+                                           step_name:, batch_size: nil, serialized_context: nil, fail_fast: nil)
+          job_id = RubyReactor::Adapters::Sidekiq::MapElementWorker.perform_async(
+            {
+              "map_id" => map_id,
+              "element_id" => element_id,
+              "index" => index,
+              "serialized_inputs" => serialized_inputs,
+              "reactor_class_info" => reactor_class_info,
+              "strict_ordering" => strict_ordering,
+              "parent_context_id" => parent_context_id,
+              "parent_reactor_class_name" => parent_reactor_class_name,
+              "step_name" => step_name,
+              "batch_size" => batch_size,
+              "serialized_context" => serialized_context,
+              "fail_fast" => fail_fast
+            }
+          )
+          RubyReactor::DispatchResult.new(job_id: job_id)
+        end
+
+        def self.perform_map_element_in(delay, map_id:, element_id:, index:, serialized_inputs:,
+                                        reactor_class_info:, strict_ordering:, parent_context_id:,
+                                        parent_reactor_class_name:, step_name:, batch_size: nil,
+                                        serialized_context: nil, fail_fast: nil)
+          job_id = RubyReactor::Adapters::Sidekiq::MapElementWorker.perform_in(
+            delay,
+            {
+              "map_id" => map_id,
+              "element_id" => element_id,
+              "index" => index,
+              "serialized_inputs" => serialized_inputs,
+              "reactor_class_info" => reactor_class_info,
+              "strict_ordering" => strict_ordering,
+              "parent_context_id" => parent_context_id,
+              "parent_reactor_class_name" => parent_reactor_class_name,
+              "step_name" => step_name,
+              "batch_size" => batch_size,
+              "serialized_context" => serialized_context,
+              "fail_fast" => fail_fast
+            }
+          )
+          # Return an DispatchResult so RetryManager#handle_async_retry recognises the
+          # element was successfully requeued and yields a RetryQueuedResult.
+          RubyReactor::DispatchResult.new(job_id: job_id)
+        end
+        # rubocop:enable Metrics/ParameterLists
+
+        # rubocop:disable Metrics/ParameterLists
+        def self.perform_map_collection_async(parent_context_id:, map_id:, parent_reactor_class_name:, step_name:,
+                                              strict_ordering:, timeout:)
+          job_id = RubyReactor::Adapters::Sidekiq::MapCollectorWorker.perform_async(
+            {
+              "parent_context_id" => parent_context_id,
+              "map_id" => map_id,
+              "parent_reactor_class_name" => parent_reactor_class_name,
+              "step_name" => step_name,
+              "strict_ordering" => strict_ordering,
+              "timeout" => timeout
+            }
+          )
+          RubyReactor::DispatchResult.new(job_id: job_id)
+        end
+        # rubocop:enable Metrics/ParameterLists
+      end
+    end
+  end
+end

data/lib/ruby_reactor/adapters/sidekiq/step_worker.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module RubyReactor
+  module Adapters
+    module Sidekiq
+      # One dispatched `async_step`, mirroring MapElementWorker: the backend
+      # binding only, all behavior in the shared `RubyReactor::StepWorker`.
+      class StepWorker
+        include ::Sidekiq::Worker
+
+        def perform(arguments)
+          RubyReactor::StepWorker.perform(arguments)
+        end
+      end
+    end
+  end
+end

data/lib/ruby_reactor/adapters/sidekiq/sweeper_worker.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require "sidekiq"
+
+module RubyReactor
+  module Adapters
+    module Sidekiq
+      class SweeperWorker
+        include ::Sidekiq::Worker
+        include RubyReactor::SweeperJob
+
+        # retry: false — the sweep is idempotent and self-rescheduling, so a failed
+        # tick must not pile up Sidekiq retries; the next tick (or a super_fetch
+        # recovery) re-runs it anyway.
+        sidekiq_options retry: false, queue: RubyReactor.configuration.queue_name
+      end
+    end
+  end
+end

data/lib/ruby_reactor/adapters/sidekiq/worker.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require "sidekiq"
+
+module RubyReactor
+  module Adapters
+    module Sidekiq
+      # Sidekiq worker for executing RubyReactor reactors asynchronously
+      # with non-blocking retry capabilities. All resume/snooze/escalate logic
+      # lives in `RubyReactor::Worker` — this class only wires it to Sidekiq.
+      class Worker
+        include ::Sidekiq::Worker
+        include RubyReactor::Worker
+
+        # Enable Sidekiq retries for infrastructure failures only
+        sidekiq_options retry: RubyReactor.configuration.job_retry_count, dead: false,
+                        queue: RubyReactor.configuration.queue_name
+
+        sidekiq_retries_exhausted do |msg, exception|
+          # With `dead: false` this job is discarded after its last retry, so
+          # this hook is the only place left to surface the failure: mark the
+          # context failed and signal any reader waiting on it.
+          RubyReactor::Worker.record_retries_exhausted(msg["args"], exception)
+        end
+      end
+    end
+  end
+end

data/lib/ruby_reactor/async_waiter.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+module RubyReactor
+  # The shared wait core behind `result(:name)` for an `async_step` or an
+  # `async_reactor` that has not finished yet. Both callers hand it a pub/sub
+  # channel and a callable that returns the terminal value (or nil while the work
+  # is still in flight), so there is exactly one implementation of the wait.
+  #
+  # The contract is "durable record answers, signal only hurries":
+  #
+  #   * the completing side writes its durable outcome FIRST, then publishes;
+  #   * this side checks the durable target, then blocks until either the signal
+  #     arrives or a coarse fallback interval elapses, then re-checks.
+  #
+  # Redis pub/sub is at-most-once and unpersisted, so a dropped signal must never
+  # cost correctness — only fallback latency. Every exit path here goes through
+  # the durable check, and the whole thing is bounded: it raises rather than
+  # hanging (SC-005).
+  class AsyncWaiter
+    # Latency backstop for a lost signal, not a tuning surface — derived from the
+    # timeout rather than configured (Principle V). The clamp guarantees ~10
+    # re-checks inside any bound, so a dropped notification costs at most ~10% of
+    # the wait, and never re-checks hotter than once a second.
+    FALLBACK_BOUNDS = (1.0..5.0)
+
+    attr_reader :channel, :timeout
+
+    # @param channel [String] completion-signal channel to listen on
+    # @param timeout [Numeric, nil] seconds; defaults to `async_wait_timeout`
+    # @yieldreturn [Object, nil] the terminal value, or nil while still pending
+    def initialize(channel:, timeout: nil, &terminal_check)
+      @channel = channel
+      @timeout = timeout || RubyReactor.configuration.async_wait_timeout
+      @terminal_check = terminal_check
+      @mutex = Mutex.new
+      @condition = ConditionVariable.new
+      @signalled = false
+    end
+
+    def wait
+      deadline = monotonic + @timeout
+      subscriber = start_subscriber
+
+      loop do
+        value = @terminal_check.call
+        return value unless value.nil?
+
+        remaining = deadline - monotonic
+        raise timeout_error if remaining <= 0
+
+        block_until_signalled_or([fallback_interval, remaining].min)
+      end
+    ensure
+      # ponytail: killing the thread is enough — `subscribe`'s own ensure closes
+      # the dedicated connection on the way out.
+      subscriber&.kill
+    end
+
+    private
+
+    def fallback_interval
+      (@timeout / 10.0).clamp(FALLBACK_BOUNDS)
+    end
+
+    # Subscribing happens before the first durable check so a completion landing
+    # mid-check still wakes us. The subscription is established asynchronously,
+    # so this narrows the race rather than closing it outright — which is fine
+    # precisely because the fallback re-check, not the signal, is what makes the
+    # wait correct.
+    def start_subscriber
+      Thread.new do
+        RubyReactor.configuration.storage_adapter.subscribe(@channel) do |_message|
+          signal!
+          true # stop subscribing — completion is one-shot
+        end
+      rescue StandardError => e
+        # A waiter that loses its notification channel degrades to the fallback
+        # re-check; it must not take the waiting step down with it.
+        RubyReactor.configuration.logger.warn(
+          "RubyReactor: async completion subscription to #{@channel} failed (#{e.class}: #{e.message}); " \
+          "falling back to periodic re-checks"
+        )
+      end
+    end
+
+    def signal!
+      @mutex.synchronize do
+        @signalled = true
+        @condition.broadcast
+      end
+    end
+
+    def block_until_signalled_or(seconds)
+      @mutex.synchronize do
+        @condition.wait(@mutex, seconds) unless @signalled
+        @signalled = false
+      end
+    end
+
+    def timeout_error
+      Error::AsyncWaitTimeoutError.new(
+        "Timed out after #{@timeout}s waiting for async completion on '#{@channel}'. " \
+        "The dispatched work never reached a terminal state within " \
+        "`RubyReactor.configuration.async_wait_timeout` — check that a worker is running and " \
+        "consuming the queue, or raise the timeout if this unit is legitimately slower."
+      )
+    end
+
+    def monotonic
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+  end
+end

data/lib/ruby_reactor/configuration.rb

@@ -7,13 +7,24 @@ module RubyReactor
   class Configuration
     include Singleton
 
-    attr_writer :sidekiq_queue, :sidekiq_retry_count, :logger, :async_router,
+    attr_writer :queue_name, :job_retry_count, :logger, :async_router,
                 :lock_snooze_base_delay, :lock_snooze_jitter, :lock_snooze_max_attempts,
                 :middlewares, :context_ttl, :context_lock_ttl, :checkpoint_min_interval,
-                :sweeper_enabled, :sweeper_interval, :sweeper_limit
+                :sweeper_enabled, :sweeper_interval, :sweeper_limit, :async_wait_timeout,
+                :async_park_timeout
 
+    def queue_name
+      @queue_name ||= :default
+    end
+
+    # Deprecated alias for `queue_name` — kept so existing Sidekiq-only configs
+    # don't break.
     def sidekiq_queue
-      @sidekiq_queue ||= :default
+      queue_name
+    end
+
+    def sidekiq_queue=(value)
+      self.queue_name = value
     end
 
     # Retention TTL (seconds) for a stored reactor context. Storage is
@@ -79,8 +90,46 @@ module RubyReactor
       @context_lock_ttl ||= 60
     end
 
+    # Seconds a step blocks in the notified wait when it reads
+    # `result(:name)` for an `async_step` / `async_reactor` that has not finished
+    # yet. Never unbounded: on expiry the referencing step fails with an
+    # `Error::AsyncWaitTimeoutError`.
+    #
+    # 30s must comfortably exceed dispatch -> worker pickup -> completion for a
+    # small unit under a healthy queue, while staying under the request/job
+    # timeouts of typical hosts (Sidekiq's 25s shutdown grace, Puma's 60s) so a
+    # stuck wait fails loudly on our terms instead of being killed from outside.
+    #
+    # The wait's fallback re-check interval is DERIVED from this, not configured:
+    # `async_wait_timeout / 10` clamped to 1..5s (see AsyncWaiter).
+    def async_wait_timeout
+      @async_wait_timeout ||= 30
+    end
+
+    # Total seconds a WORKER-side `result(:name)` wait may stay parked before
+    # failing with `Error::AsyncWaitTimeoutError`, measured from the unit's
+    # `dispatched_at`. Inside a worker a pending result does not block the
+    # thread for `async_wait_timeout` — after a short in-thread grace the job
+    # parks (re-enqueues itself, locks kept held) and re-checks on redelivery,
+    # so this bound can be generous where the blocking one must stay tight.
+    # `:infinity` removes the bound (the context TTL then remains the only
+    # backstop), mirroring `lock_snooze_max_attempts`.
+    def async_park_timeout
+      @async_park_timeout ||= 3600
+    end
+
+    def job_retry_count
+      @job_retry_count ||= 3
+    end
+
+    # Deprecated alias for `job_retry_count` — kept so existing Sidekiq-only
+    # configs don't break.
     def sidekiq_retry_count
-      @sidekiq_retry_count ||= 3
+      job_retry_count
+    end
+
+    def sidekiq_retry_count=(value)
+      self.job_retry_count = value
     end
 
     # Base seconds the Sidekiq worker waits before re-checking a contended lock.
@@ -104,7 +153,7 @@ module RubyReactor
     end
 
     def async_router
-      @async_router ||= RubyReactor::SidekiqAdapter
+      @async_router ||= RubyReactor::Adapters::Sidekiq::Router
     end
 
     def storage

data/lib/ruby_reactor/context.rb

@@ -2,6 +2,27 @@
 
 module RubyReactor
   class Context
+    # `composed_contexts[step_name]` is the one channel for "children of this
+    # context, referenced for later drill-down" — the dashboard's
+    # `hydrate_composed_contexts` and `RSpec::TestSubject`'s traversal both
+    # switch on the `type:` tag. Four tags, all plain data (no serialization
+    # change between them):
+    #
+    #   :composed          => { name:, type:, context: }  — an inline `compose` child
+    #   :map_ref           => { name:, type:, map_id:, element_reactor_class: }
+    #   :async_step_ref    => { name:, type:, dispatched_at: }
+    #     The reference only. The `async_step`'s actual outcome lives in the Step
+    #     Result Record bucket, keyed by (context_id, step_name), because a
+    #     separate worker writes it concurrently with this still-running context.
+    #   :async_reactor_ref => { name:, type:, execution_id:, reactor_class_name:, dispatched_at: }
+    #     The child is an ordinary addressable reactor, so its outcome is simply
+    #     its own context row — no extra storage primitive.
+    #
+    # Both async refs are written SYNCHRONOUSLY by the dispatching step, before
+    # it returns, so there is no cross-process write race on the reference
+    # itself (unlike the result).
+    COMPOSED_CONTEXT_TYPES = %i[composed map_ref async_step_ref async_reactor_ref].freeze
+
     attr_accessor :inputs, :intermediate_results, :private_data, :current_step, :retry_count, :concurrency_key,
                   :retry_context, :reactor_class, :execution_trace, :inline_async_execution, :undo_stack,
                   :parent_context, :root_context, :composed_contexts, :context_id, :map_operations, :map_metadata,

data/lib/ruby_reactor/context_serializer.rb

@@ -185,6 +185,8 @@ module RubyReactor
       # Simplifies data for public API usage (removes wrappers, flattens types)
       def simplify_for_api(value)
         case value
+        when RubyReactor::Map::ResultEnumerator
+          RubyReactor::Map::ResultSummary.build(value)
         when Hash
           simplified = value.each_with_object({}) do |(k, v), hash|
             hash[k.to_s] = simplify_for_api(v)

data/lib/ruby_reactor/dsl/async_macros.rb

@@ -0,0 +1,176 @@
+# frozen_string_literal: true
+
+module RubyReactor
+  module Dsl
+    # The three ways a reactor sends work out of the calling process, kept
+    # together because they are one design decision seen from three distances:
+    #
+    #   background     — the rest of THIS reactor moves to a worker
+    #                    (`all: true` — EVERYTHING, incl. input validation)
+    #   async_step     — ONE step's work becomes its own job
+    #   async_reactor  — a whole nested reactor runs independently
+    #
+    # Mixed into `Dsl::Reactor::ClassMethods`.
+    module AsyncMacros
+      # The single, unambiguous cut point between what runs in
+      # the calling process and what is handed to a worker. Replaces the
+      # per-step `async` flag, where only the first flagged step ever took
+      # effect and the rest were silently ignored, and the whole-reactor
+      # `async true` flag, which named the same idea with a different word.
+      #
+      #   background after:  :second   # :second is the LAST step to run here
+      #   background before: :third    # :third is the FIRST step in the worker
+      #   background all: true         # the ENTIRE reactor runs in the worker,
+      #                                 # including input validation
+      #
+      # `after:`/`before:` name one cut point from opposite sides — identical
+      # in a linear chain, different in a DAG, where each pins the step it
+      # names. `all:` names no step: there is nothing left to pin, everything
+      # moves. Triggering is keyed to REACHING the named step (or, for `all:`,
+      # to the run starting at all), not to where this declaration sits in
+      # the class body.
+      def background(after: nil, before: nil, all: false)
+        point = validate_background_declaration!(after, before, all)
+
+        @background_handoff = point
+      end
+
+      # The normalized `{ mode:, step: }` pair — one reader, never a one-sided
+      # `background_after`, so no consumer can be accidentally implemented for
+      # `after:` only. `step` is `nil` when `mode` is `:all`.
+      def background_handoff
+        @background_handoff
+      end
+
+      # True only for the whole-reactor hand-off (`background all: true`) —
+      # the entire run, including input validation, happens in a worker.
+      def async?
+        background_handoff&.fetch(:mode, nil) == :all
+      end
+
+      def validate_background_declaration!(after, before, all)
+        given = [after, before, all].count { |v| v }
+        if given > 1
+          raise RubyReactor::Error::ValidationError,
+                "`background` takes exactly one of `after:`, `before:`, or `all:`, got more than one " \
+                "(after: #{after.inspect}, before: #{before.inspect}, all: #{all.inspect}). Each names a " \
+                "different hand-off shape: `after: :x` / `before: :x` pin a cut point around step :x; " \
+                "`all: true` sends the whole reactor, including input validation."
+        end
+
+        if given.zero?
+          raise RubyReactor::Error::ValidationError,
+                "`background` requires one of `after: :step_name` (that step is the last to run in the " \
+                "calling process), `before: :step_name` (that step is the first to run in the worker), or " \
+                "`all: true` (the entire reactor, including input validation, runs in the worker)."
+        end
+
+        point = if all
+                  { mode: :all, step: nil }
+                else
+                  { mode: after ? :after : :before, step: (after || before).to_sym }
+                end
+
+        # Re-declaring the SAME point is a no-op — a class body can be
+        # evaluated twice (Rails reloading, a spec reopening a fixture class)
+        # and that must not be an error. A DIFFERENT second point is the real
+        # footgun `background` exists to remove.
+        if background_handoff && background_handoff != point
+          raise RubyReactor::Error::ValidationError,
+                "#{name || "This reactor"} already declares `background " \
+                "#{describe_handoff_point(background_handoff)}` and cannot also declare `background " \
+                "#{describe_handoff_point(point)}`. A reactor has exactly one hand-off point — a second " \
+                "would reintroduce the ambiguity `background` exists to remove."
+        end
+
+        validate_step_handoff_point!(point) unless point[:mode] == :all
+
+        point
+      end
+      private :validate_background_declaration!
+
+      def validate_step_handoff_point!(point)
+        step_name = point[:step]
+        unless steps.key?(step_name)
+          raise RubyReactor::Error::ValidationError,
+                "`background` names unknown step :#{step_name}. Known steps: " \
+                "#{steps.keys.map { |k| ":#{k}" }.join(", ")}. The step must be defined before the " \
+                "`background` declaration."
+        end
+
+        reject_interrupt_handoff_point!(point)
+      end
+      private :validate_step_handoff_point!
+
+      def describe_handoff_point(point)
+        point[:mode] == :all ? "all: true" : "#{point[:mode]}: :#{point[:step]}"
+      end
+      private :describe_handoff_point
+
+      # An interrupt re-enters the reactor from a foreground process, so an
+      # edge-triggered hand-off keyed to it either never fires (`after:` — the
+      # resume path skips the already-resulted step) or enqueues a worker that
+      # instantly pauses and swallows the InterruptResult (`before:`). Both are
+      # the silent-failure class `background` exists to remove.
+      def reject_interrupt_handoff_point!(point)
+        config = steps[point[:step]]
+        return unless config.respond_to?(:interrupt?) && config.interrupt?
+
+        raise RubyReactor::Error::ValidationError,
+              "`background #{point[:mode]}: :#{point[:step]}` names an interrupt step, which cannot be a " \
+              "hand-off point. To resume :#{point[:step]} in a worker, declare " \
+              "`interrupt :#{point[:step]}, resume: :background` instead; to hand off around it, name an " \
+              "ordinary step on the side you need."
+      end
+      private :reject_interrupt_handoff_point!
+      # A step whose work is dispatched to its own independent worker
+      # job while this reactor keeps executing every other ready step. Same
+      # call shape and same block DSL as `step` — `argument`, `run`,
+      # `compensate`, `undo`, `retries`, validators all behave identically;
+      # only WHERE the body runs changes.
+      #
+      # Any step reading `result(:name)` blocks (bounded) until the unit
+      # finishes. A failure with no reader does NOT compensate this reactor —
+      # compensation is opt-in, via a reader that inspects the result and
+      # returns `Failure` itself.
+      def async_step(name, impl = nil, &block)
+        builder = RubyReactor::Dsl::StepBuilder.new(name, impl, self)
+        builder.instance_eval(&block) if block_given?
+
+        steps[name] = builder.build(async_dispatch: :step)
+      end
+
+      # Dispatch a whole nested reactor to run INDEPENDENTLY — linked
+      # to this one by execution id for traceability, but excluded from its
+      # compensation graph. Fire-and-forget unless a later step reads
+      # `result(:name)`, which blocks until the child is terminal and hands
+      # over the child's real Success/Failure to inspect.
+      #
+      # Contrast with `compose`, which runs the child inline, synchronously,
+      # and fully wired into the parent's rollback path.
+      def async_reactor(name, child_reactor_class, &block)
+        builder = RubyReactor::Dsl::AsyncReactorBuilder.new(name, child_reactor_class, self)
+        builder.instance_eval(&block) if block_given?
+
+        steps[name] = builder.build
+      end
+
+      # A reactor's return value must come from a step that ran in the calling
+      # process. An `async_step` / `async_reactor` may still be in flight when
+      # this reactor finishes — that is the whole point of dispatching it — so
+      # returning it would either mean returning nothing or silently turning
+      # the fire-and-forget contract into a blocking wait.
+      def reject_async_return_step!(step_name)
+        config = steps[step_name]
+        return unless config.respond_to?(:async_dispatch?) && config.async_dispatch?
+
+        kind = config.async_dispatch == :reactor ? "async_reactor" : "async_step"
+        raise RubyReactor::Error::ValidationError,
+              "`returns :#{step_name}` is invalid: :#{step_name} is an `#{kind}`, which may still be " \
+              "running when this reactor finishes. Return a same-process step instead — if you need the " \
+              "dispatched outcome, add a step that reads `result(:#{step_name})` and return that."
+      end
+      private :reject_async_return_step!
+    end
+  end
+end

data/lib/ruby_reactor/dsl/async_reactor_builder.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module RubyReactor
+  module Dsl
+    # Builds the `async_reactor` dispatch step. Same `argument` mapping shape as
+    # `ComposeBuilder`, but deliberately NOT a subclass of it: `compose`'s
+    # builder warns that a child's `with_ordered_lock` is ignored (true for an
+    # inline child, which bypasses `Reactor#run`) whereas an `async_reactor`
+    # child is dispatched through the full pre-enqueue sequence and DOES get its
+    # ordering nonce.
+    class AsyncReactorBuilder
+      include RubyReactor::Dsl::TemplateHelpers
+
+      attr_accessor :name, :child_reactor_class, :argument_mappings
+
+      def initialize(name, child_reactor_class, reactor = nil)
+        @name = name
+        @child_reactor_class = child_reactor_class
+        @reactor = reactor
+        @argument_mappings = {}
+        @retry_config = {}
+      end
+
+      def argument(child_input_name, source)
+        @argument_mappings[child_input_name] = source
+      end
+
+      def retries(max_attempts: 3, backoff: :exponential, base_delay: 1)
+        @retry_config = { max_attempts: max_attempts, backoff: backoff, base_delay: base_delay }
+      end
+
+      def build
+        RubyReactor::Dsl::StepConfig.new(
+          async_dispatch: :reactor,
+          name: @name,
+          impl: RubyReactor::Step::AsyncReactorStep,
+          arguments: {
+            async_reactor_class: { source: RubyReactor::Template::Value.new(@child_reactor_class) },
+            argument_mappings: { source: RubyReactor::Template::Value.new(@argument_mappings) }
+          },
+          run_block: nil,
+          # No compensate/undo: the child is deliberately outside the parent's
+          # compensation graph. Compensation is opt-in, via a later step
+          # that reads `result(:name)` and decides to fail.
+          compensate_block: nil,
+          undo_block: nil,
+          conditions: [],
+          guards: [],
+          dependencies: dependencies_from_mappings,
+          args_validator: nil,
+          output_validator: nil,
+          retry_config: @retry_config.empty? ? (@reactor&.retry_defaults || {}) : @retry_config
+        )
+      end
+
+      private
+
+      def dependencies_from_mappings
+        @argument_mappings.each_value
+                          .select { |source| source.is_a?(RubyReactor::Template::Result) }
+                          .map(&:step_name)
+                          .uniq
+      end
+    end
+  end
+end