ruby_reactor 0.5.4 → 0.6.0

data/lib/ruby_reactor/adapters/active_job/map_collector_worker.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require "active_job"
+
+module RubyReactor
+  module Adapters
+    module ActiveJob
+      class MapCollectorWorker < ::ActiveJob::Base
+        extend Compat
+
+        queue_as { RubyReactor.configuration.queue_name }
+
+        def perform(arguments)
+          RubyReactor::Map::Collector.perform(arguments)
+        end
+      end
+    end
+  end
+end

data/lib/ruby_reactor/adapters/active_job/map_element_worker.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require "active_job"
+
+module RubyReactor
+  module Adapters
+    module ActiveJob
+      class MapElementWorker < ::ActiveJob::Base
+        extend Compat
+
+        queue_as { RubyReactor.configuration.queue_name }
+
+        def perform(arguments)
+          RubyReactor::Map::ElementExecutor.perform(arguments)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module RubyReactor
+  module Adapters
+    module ActiveJob
+      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::ActiveJob::Worker.perform_async(context_id, reactor_class_name)
+          RubyReactor::AsyncResult.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::ActiveJob::Worker.perform_in(delay, context_id, reactor_class_name)
+          RubyReactor::AsyncResult.new(job_id: job_id, intermediate_results: intermediate_results,
+                                       execution_id: context_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::ActiveJob::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::AsyncResult.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::ActiveJob::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 AsyncResult so RetryManager#handle_async_retry recognises the
+          # element was successfully requeued and yields a RetryQueuedResult.
+          RubyReactor::AsyncResult.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::ActiveJob::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::AsyncResult.new(job_id: job_id)
+        end
+        # rubocop:enable Metrics/ParameterLists
+      end
+    end
+  end
+end

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

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require "active_job"
+
+module RubyReactor
+  module Adapters
+    module ActiveJob
+      class SweeperWorker < ::ActiveJob::Base
+        extend Compat
+        include RubyReactor::SweeperJob
+
+        queue_as { RubyReactor.configuration.queue_name }
+      end
+    end
+  end
+end

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

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require "active_job"
+
+module RubyReactor
+  module Adapters
+    module ActiveJob
+      # ActiveJob worker for executing RubyReactor reactors asynchronously.
+      # All resume/snooze/escalate logic lives in `RubyReactor::Worker` — this
+      # class only wires it to ActiveJob.
+      #
+      # Infra-failure retries only: reactor-specific contention/config errors
+      # are already rescued inside `RubyReactor::Worker#perform` (snoozed or
+      # escalated to `failed`) before they'd ever reach this `retry_on`.
+      class Worker < ::ActiveJob::Base
+        extend Compat
+        include RubyReactor::Worker
+
+        queue_as { RubyReactor.configuration.queue_name }
+        retry_on StandardError, attempts: RubyReactor.configuration.job_retry_count
+      end
+    end
+  end
+end

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

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module RubyReactor
+  module Adapters
+    module Sidekiq
+      class MapCollectorWorker
+        include ::Sidekiq::Worker
+
+        def perform(arguments)
+          RubyReactor::Map::Collector.perform(arguments)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module RubyReactor
+  module Adapters
+    module Sidekiq
+      class MapElementWorker
+        include ::Sidekiq::Worker
+
+        def perform(arguments)
+          RubyReactor::Map::ElementExecutor.perform(arguments)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,91 @@
+# 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::AsyncResult.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::AsyncResult.new(job_id: job_id, intermediate_results: intermediate_results,
+                                       execution_id: context_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::AsyncResult.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 AsyncResult so RetryManager#handle_async_retry recognises the
+          # element was successfully requeued and yields a RetryQueuedResult.
+          RubyReactor::AsyncResult.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::AsyncResult.new(job_id: job_id)
+        end
+        # rubocop:enable Metrics/ParameterLists
+      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,25 @@
+# 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 |_, _exception|
+          # Handle infrastructure failures (network, Redis, etc.)
+        end
+      end
+    end
+  end
+end

data/lib/ruby_reactor/configuration.rb

@@ -7,13 +7,23 @@ 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
 
+    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 +89,18 @@ module RubyReactor
       @context_lock_ttl ||= 60
     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 +124,7 @@ module RubyReactor
     end
 
     def async_router
-      @async_router ||= RubyReactor::SidekiqAdapter
+      @async_router ||= RubyReactor::Adapters::Sidekiq::Router
     end
 
     def storage

data/lib/ruby_reactor/map/element_executor.rb

@@ -51,7 +51,7 @@ module RubyReactor
         # The element already runs inside its own background worker, so any async
         # steps (and async retries) must execute inline here rather than handing
         # off to a detached Worker that would escape map result/counter tracking.
-        # This mirrors SidekiqWorkers::Worker, which sets the same flag.
+        # This mirrors RubyReactor::Worker, which sets the same flag.
         context.inline_async_execution = true
 
         storage = RubyReactor.configuration.storage_adapter

data/lib/ruby_reactor/rspec/active_job_helpers.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module RubyReactor
+  module RSpec
+    # ActiveJob counterpart to `SidekiqHelpers`, used internally by
+    # `AsyncTestHelpers` to drain the ActiveJob `:test` queue adapter. Only
+    # the static methods are needed (`AsyncTestHelpers` dispatches to them);
+    # `Rails::ActiveJob::TestHelper` already covers most spec-author-facing
+    # assertions, so this module is not auto-included into examples.
+    module ActiveJobHelpers
+      PendingJob = Struct.new(:job_class, :raw) do
+        def perform!
+          ::ActiveJob::Base.queue_adapter.enqueued_jobs.delete(raw)
+          job_class.new(*raw[:args]).perform_now
+        end
+
+        def args
+          raw[:args]
+        end
+      end
+
+      def self.test_adapter?
+        defined?(::ActiveJob::Base) &&
+          ::ActiveJob::Base.queue_adapter.is_a?(::ActiveJob::QueueAdapters::TestAdapter)
+      end
+
+      # Drain every queued job in the ActiveJob `:test` adapter until the
+      # queue is empty. Recursive — handles jobs that re-enqueue themselves
+      # (e.g. ordered_lock snoozes) and job chains that queue additional jobs.
+      def self.drain_async_jobs(max_iterations: 100)
+        return unless test_adapter?
+
+        queue = ::ActiveJob::Base.queue_adapter.enqueued_jobs
+
+        max_iterations.times do
+          break if queue.empty?
+
+          queue.dup.each do |job|
+            queue.delete(job)
+            job[:job].new(*job[:args]).perform_now
+          end
+        end
+      end
+
+      def self.pending_async_jobs
+        return [] unless test_adapter?
+
+        ::ActiveJob::Base.queue_adapter.enqueued_jobs.map { |raw| PendingJob.new(raw[:job], raw) }
+      end
+    end
+  end
+end

data/lib/ruby_reactor/rspec/async_test_helpers.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module RubyReactor
+  module RSpec
+    # Single entry point `TestSubject` uses to detect and drain whichever
+    # async testing framework — Sidekiq::Testing fake mode or ActiveJob's
+    # `:test` queue adapter — is currently active, so the job-processing gate
+    # isn't hardcoded to one background processor.
+    module AsyncTestHelpers
+      def self.active?
+        sidekiq_testing? || active_job_testing?
+      end
+
+      def self.sidekiq_testing?
+        defined?(::Sidekiq::Testing) && ::Sidekiq::Testing.fake?
+      end
+
+      def self.active_job_testing?
+        ActiveJobHelpers.test_adapter?
+      end
+
+      def self.drain_async_jobs(max_iterations: 100)
+        if sidekiq_testing?
+          SidekiqHelpers.drain_async_jobs(max_iterations: max_iterations)
+        elsif active_job_testing?
+          ActiveJobHelpers.drain_async_jobs(max_iterations: max_iterations)
+        end
+      end
+
+      def self.pending_async_jobs
+        if sidekiq_testing?
+          SidekiqHelpers.pending_async_jobs
+        elsif active_job_testing?
+          ActiveJobHelpers.pending_async_jobs
+        else
+          []
+        end
+      end
+    end
+  end
+end

data/lib/ruby_reactor/rspec/sidekiq_helpers.rb

@@ -36,9 +36,9 @@ module RubyReactor
 
       def self.worker_classes
         @worker_classes ||= [
-          RubyReactor::SidekiqWorkers::Worker,
-          RubyReactor::SidekiqWorkers::MapElementWorker,
-          RubyReactor::SidekiqWorkers::MapCollectorWorker
+          RubyReactor::Adapters::Sidekiq::Worker,
+          RubyReactor::Adapters::Sidekiq::MapElementWorker,
+          RubyReactor::Adapters::Sidekiq::MapCollectorWorker
         ]
       end
 

data/lib/ruby_reactor/rspec/test_subject.rb

@@ -191,9 +191,9 @@ module RubyReactor
         end
 
         @run_result = nil
-        if @process_jobs && defined?(Sidekiq::Testing)
-          # Ensure SidekiqAdapter is used to capture jobs in fake mode
-          allow(RubyReactor.configuration).to receive(:async_router).and_return(RubyReactor::SidekiqAdapter)
+        if @process_jobs && AsyncTestHelpers.sidekiq_testing?
+          # Ensure the Sidekiq router is used to capture jobs in fake mode
+          allow(RubyReactor.configuration).to receive(:async_router).and_return(RubyReactor::Adapters::Sidekiq::Router)
 
           # Avoid nesting error which happens in Sidekiq 7+ if a mode is already set
           begin
@@ -203,6 +203,10 @@ module RubyReactor
           rescue Sidekiq::Testing::TestModeAlreadySetError
             @run_result = execution_class.run(@inputs)
           end
+        elsif @process_jobs && AsyncTestHelpers.active_job_testing?
+          # Ensure the ActiveJob router is used to capture jobs in the :test adapter
+          allow(RubyReactor.configuration).to receive(:async_router).and_return(RubyReactor::Adapters::ActiveJob::Router)
+          @run_result = execution_class.run(@inputs)
         else
           @run_result = execution_class.run(@inputs)
         end
@@ -250,7 +254,7 @@ module RubyReactor
           skipped_result(ctx)
         when "running"
           # Try to determine if it is truly running or if we just missed the completion
-          if @process_jobs && defined?(Sidekiq::Testing)
+          if @process_jobs && AsyncTestHelpers.active?
             # Force one more check
             process_pending_jobs
             # Reload status
@@ -357,7 +361,7 @@ module RubyReactor
         @reactor_instance.continue(payload: payload, step_name: step_name)
 
         # Process any pending async jobs
-        process_pending_jobs if @process_jobs && defined?(Sidekiq::Testing)
+        process_pending_jobs if @process_jobs && AsyncTestHelpers.active?
 
         # Reload the reactor instance to get updated state
         @reactor_instance = @reactor_class.find(@reactor_instance.context.context_id)
@@ -430,9 +434,9 @@ module RubyReactor
       private
 
       def process_pending_jobs
-        return unless defined?(Sidekiq::Testing)
+        return unless AsyncTestHelpers.active?
 
-        SidekiqHelpers.drain_async_jobs
+        AsyncTestHelpers.drain_async_jobs
         @reactor_instance = @reactor_class.find(@reactor_instance.context.context_id)
       end
 

data/lib/ruby_reactor/rspec.rb

@@ -3,6 +3,8 @@
 require_relative "rspec/helpers"
 require_relative "rspec/matchers"
 require_relative "rspec/sidekiq_helpers"
+require_relative "rspec/active_job_helpers"
+require_relative "rspec/async_test_helpers"
 require_relative "rspec/storage_reset"
 require_relative "rspec/test_subject"
 
@@ -44,6 +46,8 @@ module RubyReactor
         ::Sidekiq::Worker.clear_all
       end
 
+      ::ActiveJob::Base.queue_adapter.enqueued_jobs.clear if AsyncTestHelpers.active_job_testing?
+
       adapter = ::RubyReactor.configuration.storage_adapter
       adapter.reset! if adapter.respond_to?(:reset!)
 

data/lib/ruby_reactor/sweeper_job.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module RubyReactor
+  # Self-rescheduling recovery tick, shared by every queueing backend's
+  # sweeper job class. Each run sweeps both the top-level reactor sweeper and
+  # the map sweeper, then schedules the next tick — a perpetual chain the
+  # host kicks once via `RubyReactor.start_sweeper!`.
+  #
+  # super_fetch safety. Sidekiq Enterprise `super_fetch` reliably re-runs a job
+  # whose worker died mid-execution. For a self-rescheduling chain that is a
+  # hazard: a tick can crash AFTER enqueuing its successor but BEFORE acking, so
+  # super_fetch recovers the crashed tick *alongside* the successor it already
+  # scheduled — the chain forks and then doubles every interval. We therefore do
+  # NOT rely on "exactly one job exists". The next tick is claimed by a
+  # per-time-window lock: every duplicate computes the SAME target window and
+  # only one wins the claim, so recovered/duplicated ticks collapse back to a
+  # single chain. The claim lock is never released — it simply expires — so no
+  # delete can race two duplicates into both winning.
+  module SweeperJob
+    def self.included(base)
+      base.extend(ClassMethods)
+    end
+
+    def perform
+      config = RubyReactor.configuration
+      return unless config.sweeper_enabled
+
+      run_sweeps(config)
+    ensure
+      # Always chain forward (unless disabled), even after an error above, so a
+      # single bad sweep can't kill recovery. The window lock keeps this from
+      # forking under super_fetch.
+      self.class.schedule_next if RubyReactor.configuration.sweeper_enabled
+    end
+
+    def run_sweeps(config)
+      RubyReactor::Sweeper.run_once(limit: config.sweeper_limit)
+      RubyReactor::Map::Sweeper.run_once(limit: config.sweeper_limit)
+    rescue StandardError => e
+      config.logger.error("RubyReactor sweeper sweep failed: #{e.class}: #{e.message}")
+    end
+
+    module ClassMethods
+      # Enqueue the next tick for the upcoming time window, claiming that window
+      # so concurrent/duplicate/recovered ticks produce exactly one successor.
+      # Idempotent: also safe to call from `start_sweeper!` on every process boot.
+      def schedule_next
+        interval = RubyReactor.configuration.sweeper_interval
+        window = (Time.now.to_i / interval) + 1
+
+        lock = RubyReactor::Lock.new(
+          "sweeper:window:#{window}",
+          owner: SecureRandom.uuid,
+          ttl: interval * 2, # outlive the window; expires on its own (never released)
+          wait: 0,
+          auto_extend: false
+        )
+        lock.acquire # raises AcquisitionError if this window is already claimed
+
+        delay = (window * interval) - Time.now.to_i
+        perform_in([delay, 1].max)
+      rescue RubyReactor::Lock::AcquisitionError
+        # Another tick already scheduled this window — collapse the duplicate.
+        nil
+      end
+    end
+  end
+end

data/lib/ruby_reactor/version.rb

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