ruby_reactor 0.6.0 → 0.7.1

data/lib/ruby_reactor/step/async_reactor_step.rb

@@ -0,0 +1,207 @@
+# frozen_string_literal: true
+
+module RubyReactor
+  module Step
+    # The dispatching half of `async_reactor`: everything that happens in the
+    # PARENT's process. The child then runs as an ordinary independently
+    # dispatched reactor execution — no new enqueue primitive, no new storage
+    # primitive, and no entry in the parent's compensation graph.
+    #
+    # Dispatch reuses the full pre-enqueue sequence of a top-level async run
+    # rather than a raw `perform_async`, because `Reactor#run` does
+    # three load-bearing things a naive `Context.new` + enqueue would silently
+    # skip: validate the child's inputs (the worker's resume path never
+    # validates, so skipping here starts a child on garbage), assign the
+    # ordered-lock nonce at ENQUEUE time (so ordering matches caller order), and
+    # persist before enqueueing (F2).
+    class AsyncReactorStep
+      include RubyReactor::Step
+
+      class << self
+        def run(arguments, context)
+          child_class = arguments[:async_reactor_class]
+          child_inputs = build_child_inputs(arguments[:argument_mappings] || {}, context)
+
+          # A dispatch-time failure fails the DISPATCHING step, i.e. normal saga
+          # handling in the parent. That is deliberately outside the
+          # no-auto-compensation rule, which governs the child's own execution.
+          validation = validate_child_inputs(child_class, child_inputs)
+          return validation if validation
+
+          deadlock = detect_lock_deadlock(child_class, child_inputs, context)
+          return deadlock if deadlock
+
+          return run_inline(child_class, child_inputs, context) if run_inline?(context)
+
+          dispatch(child_class, child_inputs, context)
+        end
+
+        private
+
+        def build_child_inputs(mappings, context)
+          mappings.transform_values { |source| source.resolve(context) }
+        end
+
+        def validate_child_inputs(child_class, child_inputs)
+          return nil unless child_class.respond_to?(:validate_inputs)
+
+          result = child_class.validate_inputs(child_inputs)
+          return nil unless result.failure?
+
+          RubyReactor.Failure(
+            "async_reactor child #{child_class.name} rejected its inputs: #{result.error.message}",
+            validation_errors: (result.error.field_errors if result.error.respond_to?(:field_errors))
+          )
+        end
+
+        # Lock ownership is NOT shared across the async boundary: parent
+        # and child run concurrently, so giving the child the parent's owner
+        # would put both inside the critical section at once — mutual exclusion
+        # silently broken, which is worse than a stall. Instead the one
+        # GUARANTEED deadlock (the parent holds a key its child will wait on,
+        # while the parent may go on to wait for that child) is caught here,
+        # loudly, at dispatch. Ordinary cross-execution contention on the same
+        # key is unaffected and still snoozes normally.
+        def detect_lock_deadlock(child_class, child_inputs, context)
+          held = held_lock_keys(context)
+          return nil if held.empty?
+
+          collision = child_lock_keys(child_class, child_inputs).find { |key| held.include?(key) }
+          return nil unless collision
+
+          RubyReactor.Failure(deadlock_message(collision, child_class, context))
+        end
+
+        def child_lock_keys(child_class, child_inputs)
+          keys = []
+          if child_class.respond_to?(:lock_config) && child_class.lock_config
+            keys << child_class.lock_config[:key_proc].call(child_inputs)
+          end
+
+          # A semaphore with a single slot has the identical circular-wait
+          # shape. Higher limits are contention, not guaranteed deadlock.
+          semaphore = child_class.respond_to?(:semaphore_config) ? child_class.semaphore_config : nil
+          keys << semaphore[:key_proc].call(child_inputs) if semaphore && semaphore[:limit] == 1
+
+          keys.compact
+        end
+
+        def held_lock_keys(context)
+          root = context.root_context || context
+          Array(root.private_data[:held_lock_keys] || root.private_data["held_lock_keys"])
+        end
+
+        def deadlock_message(key, child_class, context)
+          parent = context.reactor_class&.name || "the dispatching reactor"
+          <<~MSG.strip
+            async_reactor dispatch of #{child_class.name || "<anonymous>"} would deadlock: it declares the \
+            lock key '#{key}', which #{parent} currently holds and will not release until it finishes.
+            The child would snooze forever, and if #{parent} later reads this child's result it would wait \
+            for work that can never start. Lock ownership is never shared across the async boundary — the \
+            two run concurrently, so sharing it would break mutual exclusion outright.
+            Fix, in order of preference:
+              1. Use `compose` instead of `async_reactor` if the child belongs inside #{parent}'s critical \
+            section and its result is needed — waiting for it means the work is sequential anyway.
+              2. Narrow the lock keys, if parent and child actually protect different resources.
+              3. Restructure so the locked reactor never reads the child's result — fire-and-forget, and \
+            verify in the child itself or in a successor reactor outside the lock window.
+          MSG
+        end
+
+        # `RSpec::TestSubject`'s `async: false` clears the dispatch marker to run
+        # the whole reactor in one process.
+        def run_inline?(context)
+          config = context.reactor_class&.steps&.[](context.current_step)
+          config.respond_to?(:async_dispatch?) && !config.async_dispatch?
+        end
+
+        def run_inline(child_class, child_inputs, context)
+          result = child_class.run(child_inputs)
+          store_reference(context, execution_id: (result.execution_id if result.respond_to?(:execution_id)),
+                                   child_class: child_class)
+          # Success(nil) for the same reason dispatch returns it: `result(:name)`
+          # must route through the reference (which now points at an already
+          # terminal child) rather than through a recorded value.
+          RubyReactor.Success(nil)
+        end
+
+        def dispatch(child_class, child_inputs, context)
+          child_context = build_child_context(child_class, child_inputs, context)
+          assign_ordered_lock_nonce!(child_class, child_context)
+
+          # Persist BEFORE enqueue (F2) — the payload is identity-only.
+          child_context.status = :running
+          # Marks the child as owned by a job of its own, which is what makes it
+          # sweepable: a compose child carries the same parent_context_id but runs
+          # inline in the parent, so re-enqueueing one would double-run it.
+          child_context.private_data[:async_dispatched] = true
+          save(child_context, child_class)
+
+          # The reference is written synchronously, by the process that is about
+          # to keep running other steps, so there is no cross-process race on it
+          # (unlike the child's eventual result, which the child itself writes).
+          store_reference(context, execution_id: child_context.context_id, child_class: child_class)
+          log_dispatch(context, child_class, child_context)
+
+          RubyReactor.configuration.async_router.perform_async(
+            child_context.context_id, RubyReactor.reactor_storage_name(child_class)
+          )
+
+          RubyReactor.Success(nil)
+        end
+
+        def build_child_context(child_class, child_inputs, context)
+          child_context = RubyReactor::Context.new(child_inputs, child_class)
+          # Linked for traceability only — the child is NOT nested inside the
+          # parent's context tree, because it must survive the parent finishing.
+          child_context.parent_context_id = context.context_id
+          child_context
+        end
+
+        def assign_ordered_lock_nonce!(child_class, child_context)
+          return unless child_class.respond_to?(:ordered_lock_config) && child_class.ordered_lock_config
+
+          config = child_class.ordered_lock_config
+          key = config[:key_proc].call(child_context.inputs)
+          nonce, epoch = RubyReactor::OrderedLock.assign(key, ttl: config[:ttl])
+
+          child_context.private_data[:ordered_lock] = {
+            key: key, nonce: nonce, epoch: epoch,
+            poison_pill_timeout: config[:poison_pill_timeout],
+            ttl: config[:ttl], strict: config.fetch(:strict, true)
+          }
+        end
+
+        def store_reference(context, execution_id:, child_class:)
+          context.composed_contexts[context.current_step] = {
+            name: context.current_step,
+            type: :async_reactor_ref,
+            execution_id: execution_id,
+            reactor_class_name: RubyReactor.reactor_storage_name(child_class),
+            dispatched_at: Time.now
+          }
+        end
+
+        def save(child_context, child_class)
+          RubyReactor.configuration.storage_adapter.store_context(
+            child_context.context_id,
+            RubyReactor::ContextSerializer.serialize(child_context),
+            RubyReactor.reactor_storage_name(child_class)
+          )
+        end
+
+        # The link between parent and child, machine-parseable. Matters
+        # most here — a fire-and-forget child's failure may have no other surface
+        # in the parent at all.
+        def log_dispatch(context, child_class, child_context)
+          RubyReactor.configuration.logger.info(
+            "event=\"ruby_reactor.async_reactor.dispatched\" " \
+            "reactor=#{context.reactor_class&.name.inspect} step=#{context.current_step.inspect} " \
+            "execution_id=#{context.context_id.inspect} child_reactor=#{child_class.name.inspect} " \
+            "child_execution_id=#{child_context.context_id.inspect}"
+          )
+        end
+      end
+    end
+  end
+end

data/lib/ruby_reactor/step/compose_step.rb

@@ -108,7 +108,7 @@ module RubyReactor
         end
 
         def handle_execution_result(result)
-          return result if result.is_a?(RubyReactor::AsyncResult) || result.is_a?(RubyReactor::RetryQueuedResult)
+          return result if result.is_a?(RubyReactor::DispatchResult) || result.is_a?(RubyReactor::RetryQueuedResult)
 
           if result.success?
             RubyReactor.Success(result.value)

data/lib/ruby_reactor/step/map_step.rb

@@ -64,7 +64,7 @@ module RubyReactor
 
         def run_inline(arguments, context)
           results = execute_inline_map(arguments, context)
-          return results if results.is_a?(RubyReactor::Failure)
+          return results if results.is_a?(RubyReactor::Failure) || results.is_a?(RubyReactor::Halt)
 
           process_results(results, arguments[:collect_block], arguments[:fail_fast])
         end
@@ -76,6 +76,10 @@ module RubyReactor
           arguments[:source].each do |element|
             result = execute_single_element(element, arguments, context)
 
+            # An element-level Halt propagates as a run halt: stop immediately
+            # rather than being collected as a (nil) value.
+            return result if result.is_a?(RubyReactor::Halt)
+
             if fail_fast && result.failure?
               return result # Stop immediately on first failure
             end
@@ -168,7 +172,7 @@ module RubyReactor
             element_reactor_class: arguments[:mapped_reactor_class].name
           }
 
-          RubyReactor::AsyncResult.new(
+          RubyReactor::DispatchResult.new(
             job_id: job_id,
             intermediate_results: context.intermediate_results,
             execution_id: context.context_id

data/lib/ruby_reactor/step.rb

@@ -7,6 +7,8 @@ module RubyReactor
     end
 
     module ClassMethods
+      include RubyReactor::StepSignals
+
       # rubocop:disable Naming/MethodName
       def Success(value = nil)
         RubyReactor::Success(value)
@@ -16,8 +18,12 @@ module RubyReactor
         RubyReactor::Failure(error)
       end
 
-      def Skipped(reason: nil, **kwargs)
-        RubyReactor.Skipped(reason: reason, **kwargs)
+      def Halt(reason: nil, **kwargs)
+        RubyReactor.Halt(reason: reason, **kwargs)
+      end
+
+      def Skipped(...)
+        RubyReactor.Skipped(...)
       end
       # rubocop:enable Naming/MethodName
 
@@ -26,11 +32,11 @@ module RubyReactor
       end
 
       def compensate(_reason, _arguments, _context)
-        RubyReactor.Success() # Default: accept failure and continue rollback
+        RubyReactor.Skipped() # Default: nothing defined, rollback continues
       end
 
       def undo(_result, _arguments, _context)
-        RubyReactor.Success() # Default: no-op undo
+        RubyReactor.Skipped() # Default: nothing defined, rollback continues
       end
     end
   end

data/lib/ruby_reactor/step_signals.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module RubyReactor
+  # `success!` / `skip!` / `fail!` / `halt!` — end a step body immediately
+  # with the matching signal, from any call depth. Mixed into both authoring
+  # surfaces (class steps and inline `run` blocks) so the helpers behave
+  # identically in either style (contracts/step-helpers.md).
+  #
+  # Implemented as throw/catch rather than an exception: a `throw` passes
+  # straight through `rescue Exception` while `ensure` blocks still run
+  # (verified in research.md R2), so a step's own broad rescue cannot swallow
+  # the author's intended outcome. The catching `catch(StepSignals::TAG)` lives
+  # at each step-body invocation site (step_executor.rb, compensation_manager.rb).
+  module StepSignals
+    TAG = :ruby_reactor_step_signal
+
+    def success!(value = nil)
+      throw TAG, RubyReactor.Success(value)
+    end
+
+    def skip!(...)
+      throw TAG, RubyReactor.Skipped(...)
+    end
+
+    def fail!(error, **opts)
+      throw TAG, RubyReactor.Failure(error, **opts)
+    end
+
+    def halt!(reason: nil, **kwargs)
+      throw TAG, RubyReactor.Halt(reason: reason, **kwargs)
+    end
+  end
+end

data/lib/ruby_reactor/step_sweeper.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module RubyReactor
+  # Re-dispatches `async_step` units whose job was lost.
+  #
+  # An `async_step` is the one dispatched unit with no context of its own, so
+  # neither Sweeper (top-level contexts) nor Map::Sweeper (map elements) can see
+  # it. All it leaves behind is a Step Result Record stuck at `dispatched`, and
+  # because that record is also the re-attach marker, `already_dispatched?`
+  # actively refuses to dispatch again — so without this sweep a lost unit strands
+  # its parent forever, re-parking on every recovery of the parent itself.
+  #
+  # Liveness is the `async_step:` lock StepWorker holds for the life of the unit,
+  # mirroring how Sweeper reads `async:` and Map::Sweeper reads `map_element:`. A
+  # duplicate that races a live worker loses that lock and drops itself, so a
+  # mis-judged unit re-runs its body at most once.
+  class StepSweeper
+    DEFAULT_LIMIT = 1000
+
+    # The re-dispatch arguments, which the record carries verbatim because its
+    # key names the reactor that owns the step rather than the root the worker
+    # must load. Records written before recovery existed lack them and are skipped.
+    DISPATCH_KEYS = %w[root_context_id reactor_class_name step_context_id step_name].freeze
+
+    def self.run_once(limit: DEFAULT_LIMIT)
+      new.run_once(limit: limit)
+    end
+
+    def initialize(storage: nil, async_router: nil, logger: nil)
+      @storage = storage || RubyReactor.configuration.storage_adapter
+      @async_router = async_router || RubyReactor.configuration.async_router
+      @logger = logger || RubyReactor.configuration.logger
+    end
+
+    # Scans stored Step Result Records and re-dispatches the dispatched-but-dead
+    # ones. Returns the number re-dispatched.
+    def run_once(limit: DEFAULT_LIMIT)
+      redispatched = 0
+
+      @storage.scan_step_results(count: limit).each do |record|
+        next unless record["status"] == "dispatched"
+
+        arguments = dispatch_arguments(record)
+        next unless arguments
+        next if live?(arguments)
+
+        @async_router.perform_step_async(**arguments)
+        redispatched += 1
+      rescue StandardError => e
+        # One bad record must not abort the whole sweep.
+        @logger.warn("RubyReactor::StepSweeper failed to re-dispatch #{record["step_name"]}: #{e.class}: #{e.message}")
+      end
+
+      redispatched
+    end
+
+    private
+
+    def dispatch_arguments(record)
+      values = record.values_at(*DISPATCH_KEYS)
+      return nil if values.any?(&:nil?)
+
+      DISPATCH_KEYS.map(&:to_sym).zip(values).to_h
+    end
+
+    def live?(arguments)
+      @storage.lock_held?(
+        RubyReactor.async_step_lock_key(arguments[:step_context_id], arguments[:step_name])
+      )
+    end
+  end
+end

data/lib/ruby_reactor/step_worker.rb

@@ -0,0 +1,260 @@
+# frozen_string_literal: true
+
+module RubyReactor
+  # The body of one dispatched `async_step`, shared by every queueing backend
+  # (`Adapters::Sidekiq::StepWorker`, `Adapters::ActiveJob::StepWorker`) exactly
+  # as `Map::ElementExecutor` is shared by the map element workers.
+  #
+  # It is deliberately NOT a reactor run: it loads the parent context, resolves
+  # just this one step's arguments against it, runs the step body, writes the
+  # durable Step Result Record, and publishes the completion signal. Ordering is
+  # 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.
+  class StepWorker
+    class << self
+      def perform(arguments)
+        arguments = arguments.transform_keys(&:to_sym)
+        new(**slice_arguments(arguments)).perform
+      end
+
+      private
+
+      def slice_arguments(arguments)
+        {
+          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
+        }
+      end
+    end
+
+    def initialize(root_context_id:, reactor_class_name:, step_context_id:, step_name:)
+      @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
+    end
+
+    # The lock is what makes a lost unit recoverable: the record alone cannot say
+    # whether a `dispatched` unit is mid-flight or gone, so StepSweeper reads this
+    # lock as the liveness signal. It also drops a duplicate delivery rather than
+    # running the body a second time.
+    def perform
+      lock = acquire_liveness_lock
+      return if lock == :contended
+
+      perform_unit
+    ensure
+      lock.release if lock.respond_to?(:release)
+    end
+
+    private
+
+    def perform_unit
+      context = load_step_context
+      return record_missing_parent unless context
+
+      step_config = context.reactor_class&.steps&.[](@step_name)
+      return record_missing_step unless step_config
+
+      complete(run_step(context, step_config), 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
+      # fail identically N more times while every reader waits out its timeout.
+      log(:error, "failed", error: "#{e.class}: #{e.message}")
+      complete(RubyReactor.Failure(e, step_name: @step_name, reactor_name: @reactor_class_name), nil)
+    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.
+      return :inline if inline_testing_mode?
+
+      lock = RubyReactor::Lock.new(
+        RubyReactor.async_step_lock_key(@step_context_id, @step_name),
+        owner: SecureRandom.uuid, ttl: RubyReactor.configuration.context_lock_ttl,
+        wait: 0, auto_extend: true
+      )
+      lock.acquire
+      lock
+    rescue RubyReactor::Lock::AcquisitionError
+      log(:info, "duplicate_dropped")
+      :contended
+    end
+
+    def inline_testing_mode?
+      defined?(Sidekiq::Testing) && Sidekiq::Testing.respond_to?(:inline?) && Sidekiq::Testing.inline?
+    end
+
+    def run_step(context, step_config)
+      arguments = resolve_arguments(step_config, context)
+      log(:info, "running")
+
+      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)
+      end
+
+      result
+    end
+
+    def execute_step_body(step_config, arguments, context)
+      result =
+        if step_config.has_run_block?
+          args = arguments.empty? ? context.inputs : arguments
+          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
+
+      normalize(result)
+    rescue StandardError => e
+      RubyReactor.Failure(e, step_name: @step_name, reactor_name: @reactor_class_name)
+    end
+
+    # Mirrors `Executor::RetryManager#can_retry_step?` for the one path that
+    # never reaches it: an `async_step`'s body runs entirely inside this
+    # worker, so retries here must be attempted synchronously in-process
+    # rather than requeued as a new job.
+    def retry?(step_config, result, attempt)
+      return false unless result.is_a?(RubyReactor::Failure) && result.retryable?
+
+      step_config.retryable? && attempt < step_config.retry_config[:max_attempts]
+    end
+
+    def backoff_delay(step_config, attempt)
+      RetryContext.calculate_backoff_delay(
+        attempt, step_config.retry_config[:backoff], step_config.retry_config[:base_delay]
+      )
+    end
+
+    def normalize(result)
+      return result if result.is_a?(RubyReactor::Success) || result.is_a?(RubyReactor::Failure)
+
+      RubyReactor.Success(result)
+    end
+
+    def resolve_arguments(step_config, context)
+      step_config.arguments.to_h do |arg_name, arg_config|
+        value = arg_config[:source].resolve(context)
+        value = arg_config[:transform].call(value) if arg_config[:transform]
+        [arg_name, value]
+      end
+    end
+
+    # Write first, publish second. The record is the answer; the signal only
+    # saves the reader a fallback interval.
+    def complete(result, context)
+      storage.store_step_result(
+        @step_context_id, @step_name,
+        {
+          "status" => "completed",
+          "success" => result.success?,
+          "result" => ContextSerializer.serialize_value(result.success? ? result.value : result.to_h),
+          "completed_at" => Time.now.iso8601
+        },
+        @reactor_class_name
+      )
+      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
+
+    def record_missing_parent
+      # The parent was swept or outlived its retention window, so this
+      # unit's arguments can never be resolved. A record saying so beats a
+      # reader waiting out the full timeout for an answer that will never come.
+      log(:error, "parent_context_missing")
+      complete(
+        RubyReactor.Failure(
+          "Parent context #{@step_context_id} for async_step :#{@step_name} is no longer in storage " \
+          "(swept, or dispatched longer ago than `context_ttl`). The step's arguments cannot be resolved."
+        ),
+        nil
+      )
+    end
+
+    def record_missing_step
+      log(:error, "step_not_found")
+      complete(
+        RubyReactor.Failure("async_step :#{@step_name} is not defined on #{@reactor_class_name}"),
+        nil
+      )
+    end
+
+    def load_step_context
+      data = storage.retrieve_context(@root_context_id, @reactor_class_name)
+      return nil unless data
+
+      root = ContextSerializer.deserialize_hash(data)
+      @root_context = root
+      found = find_context(root, @step_context_id)
+      # The step runs in its own job; nothing it reaches should hand off again.
+      found&.inline_async_execution = true
+      found
+    rescue RubyReactor::Error::DeserializationError, RubyReactor::Error::SchemaVersionError => e
+      log(:error, "parent_context_unreadable", error: "#{e.class}: #{e.message}")
+      nil
+    end
+
+    def find_context(context, target_id)
+      return context if context.context_id == target_id
+
+      context.composed_contexts.each_value do |entry|
+        next unless entry.is_a?(Hash) && entry[:context].is_a?(RubyReactor::Context)
+
+        found = find_context(entry[:context], target_id)
+        return found if found
+      end
+      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
+
+    # Machine-parseable, and carrying enough identity to correlate a
+    # worker-side outcome with the parent execution — which matters more here
+    # than elsewhere, because a fire-and-forget failure may have no other surface.
+    def log(level, event, **extra)
+      fields = {
+        event: "ruby_reactor.async_step.#{event}",
+        reactor: @reactor_class_name,
+        step: @step_name,
+        execution_id: @step_context_id
+      }.merge(extra)
+
+      RubyReactor.configuration.logger.public_send(
+        level, fields.map { |k, v| "#{k}=#{v.inspect}" }.join(" ")
+      )
+    end
+  end
+end

data/lib/ruby_reactor/storage/adapter.rb

@@ -15,6 +15,27 @@ module RubyReactor
         raise NotImplementedError
       end
 
+      # The durable outcome of one `async_step`, keyed by (parent context, step
+      # name). A separate worker writes it concurrently with the still-running
+      # parent, so it deliberately lives OUTSIDE the parent's context blob —
+      # writing into that blob from two processes would race.
+      #
+      # `record` is a plain hash: at minimum `status` ("dispatched" or
+      # "completed"); a completed record also carries the serialized outcome.
+      # The `dispatched` record is written before the job is enqueued, so it
+      # doubles as the re-attach marker on recovery.
+      def store_step_result(context_id, step_name, record, reactor_class_name)
+        raise NotImplementedError
+      end
+
+      def retrieve_step_result(context_id, step_name, reactor_class_name)
+        raise NotImplementedError
+      end
+
+      def scan_step_results(count: 1000)
+        raise NotImplementedError
+      end
+
       def retrieve_map_results(map_id, reactor_class_name, strict_ordering: true)
         raise NotImplementedError
       end
@@ -63,7 +84,11 @@ module RubyReactor
         raise NotImplementedError
       end
 
-      def scan_reactors(pattern: "*", count: 50)
+      def scan_reactors(pattern: "*", count: 50, include_dispatched_children: false)
+        raise NotImplementedError
+      end
+
+      def scan_reactors_page(pattern: "*", cursor: "0", count: 50, include_dispatched_children: false)
         raise NotImplementedError
       end