ruby_reactor 0.5.1 → 0.5.3

data/lib/ruby_reactor/ordered_lock.rb

@@ -0,0 +1,158 @@
+# frozen_string_literal: true
+
+module RubyReactor
+  # Strict-ordering primitive. A monotonically increasing nonce is assigned at
+  # enqueue time; the worker can proceed only when its nonce equals
+  # `last_completed + 1`. Otherwise the worker raises {WaitError}, which the
+  # Sidekiq worker rescues and re-snoozes via `perform_in`.
+  #
+  # See `with_ordered_lock` for usage from a reactor.
+  class OrderedLock
+    # Raised by the gate check when the worker's nonce is ahead of
+    # `last_completed + 1`. Carries `retry_after_seconds`, a hint derived from
+    # the poison-pill timeout on the *blocker* nonce.
+    class WaitError < StandardError
+      attr_reader :retry_after_seconds, :key, :nonce, :last_completed
+
+      def initialize(key:, nonce:, last_completed:, retry_after_seconds:)
+        @key = key
+        @nonce = nonce
+        @last_completed = last_completed
+        @retry_after_seconds = retry_after_seconds
+        super("OrderedLock '#{key}' nonce #{nonce} waiting on #{last_completed + 1}")
+      end
+    end
+
+    # Default poison-pill: if the blocker nonce was assigned more than
+    # `poison_pill_timeout` seconds ago and never advanced, the gate treats it
+    # as dead and advances past it. Prevents permanent head-of-line blocking
+    # from a crashed caller that INCRed but never enqueued.
+    DEFAULT_POISON_PILL_TIMEOUT = 600
+
+    # TTL on the Redis counter keys. Bumped on every assign so an active
+    # sequence never expires; only fully-drained ones GC themselves.
+    DEFAULT_TTL = 86_400
+
+    attr_reader :key, :nonce, :epoch, :poison_pill_timeout, :strict
+
+    def initialize(key, nonce: nil, epoch: nil, poison_pill_timeout: DEFAULT_POISON_PILL_TIMEOUT, # rubocop:disable Metrics/ParameterLists
+                   ttl: DEFAULT_TTL, strict: true)
+      @key = key
+      @nonce = nonce
+      @epoch = epoch
+      @poison_pill_timeout = poison_pill_timeout
+      @ttl = ttl
+      @strict = strict
+    end
+
+    # Atomic INCR on the `next` counter. Caller-side; runs during
+    # `Reactor.run` BEFORE `perform_async`. Returns `[nonce, epoch]` — the nonce
+    # we own plus the generation it belongs to (used to fence stale stragglers).
+    def self.assign(key, ttl: DEFAULT_TTL)
+      adapter = RubyReactor.configuration.storage_adapter
+      adapter.ordered_lock_assign(key, ttl: ttl)
+    end
+
+    # Gate check. Returns `:go`, `:drained_go`, `:skip_chain_failed`,
+    # `:stale_batch`, or raises {WaitError}.
+    # - `:go` — proceed to run steps.
+    # - `:drained_go` — the batch fully drained and GC'd while this caller slept.
+    #   A genuine late straggler should run; a Sidekiq redelivery of an
+    #   already-terminal context should be skipped. The executor disambiguates
+    #   via the stored context status.
+    # - `:skip_chain_failed` — only in strict mode: an earlier nonce in this
+    #   sequence terminated with a Failure, so this run is short-circuited
+    #   with `Skipped(reason: :ordered_lock_chain_failed)` without executing.
+    # - `:stale_batch` — this run's epoch no longer matches the key's current
+    #   generation: its batch fully drained and the numbering was reused by a
+    #   newer batch. The run is short-circuited with
+    #   `Skipped(reason: :ordered_lock_stale_batch)` and must not participate.
+    # - `:poison_advance` is collapsed to `:go` from the caller's perspective.
+    def check!
+      raise ArgumentError, "OrderedLock#check! requires a nonce" unless @nonce
+
+      state, retry_after, last_completed, first_failed = adapter.ordered_lock_can_proceed(
+        @key,
+        nonce: @nonce,
+        poison_pill_timeout: @poison_pill_timeout,
+        epoch: @epoch.to_i
+      )
+
+      case state
+      when "go", "poison_advance"
+        chain_failed?(first_failed) ? :skip_chain_failed : :go
+      when "drained_go"
+        # Batch fully drained and GC'd while this caller slept. A genuine late
+        # straggler may run (poison semantics); a redelivery of an
+        # already-terminal context must not. The executor disambiguates via the
+        # stored context status. (fail_key is GC'd here, so no chain check.)
+        :drained_go
+      when "stale"
+        :stale_batch
+      when "wait"
+        raise WaitError.new(
+          key: @key,
+          nonce: @nonce,
+          last_completed: last_completed,
+          retry_after_seconds: retry_after
+        )
+      else
+        raise "Unexpected OrderedLock state: #{state.inspect}"
+      end
+    end
+
+    # Move `last_completed` forward. Idempotent: only the nonce equal to
+    # `last_completed + 1` advances; others are no-ops (the poison-pill path
+    # may have already skipped us).
+    #
+    # Call on terminal status only (success, permanent failure, escalated skip).
+    # Retryable failures must NOT advance — the same nonce keeps owning until
+    # the job either succeeds or exhausts its retry budget.
+    #
+    # `failed:` records this nonce as the chain-failure marker (only the FIRST
+    # failure sticks). In strict mode the marker causes subsequent nonces to
+    # short-circuit with Skipped.
+    def advance!(failed: false)
+      raise ArgumentError, "OrderedLock#advance! requires a nonce" unless @nonce
+
+      adapter.ordered_lock_advance(@key, nonce: @nonce, failed: failed, epoch: @epoch.to_i, ttl: @ttl)
+    end
+
+    # Restamp this nonce's `assigned_at` to "now" while its steps execute, so a
+    # successor does not poison-advance past a blocker that is merely slow (not
+    # dead). Called on an interval by a background heartbeat thread for the
+    # duration of step execution. No-op if the nonce's timer was already deleted
+    # by a terminal advance, or if the batch has gone stale (epoch fence).
+    def heartbeat!
+      return unless @nonce
+
+      adapter.ordered_lock_heartbeat(@key, nonce: @nonce, epoch: @epoch.to_i)
+    end
+
+    # Read-only inspection. `{ next:, last_completed:, in_flight: [...] }`.
+    def self.peek(key)
+      RubyReactor.configuration.storage_adapter.ordered_lock_peek(key)
+    end
+
+    # Manual ops escape hatch — force-advance past a stuck nonce.
+    def self.skip!(key, nonce:)
+      RubyReactor.configuration.storage_adapter.ordered_lock_skip(key, nonce: nonce)
+    end
+
+    # Nuke all counters for a key. Ops only; concurrent enqueues during reset
+    # produce undefined ordering.
+    def self.reset!(key)
+      RubyReactor.configuration.storage_adapter.ordered_lock_reset(key)
+    end
+
+    private
+
+    def chain_failed?(first_failed)
+      @strict && first_failed.to_i.positive? && @nonce > first_failed.to_i
+    end
+
+    def adapter
+      RubyReactor.configuration.storage_adapter
+    end
+  end
+end

data/lib/ruby_reactor/reactor.rb

@@ -102,14 +102,20 @@ module RubyReactor
         return validation_result
       end
 
+      # Assign-at-enqueue: ordered_lock nonce is INCRed atomically here so
+      # the order matches the caller's order, not whichever worker happens to
+      # pick the job up first.
+      assign_ordered_lock_nonce!
+
       if self.class.async? && !@context.inline_async_execution
         # For async reactors, queue a job for the whole reactor
         @context.status = :running
         Executor.middlewares_for(self.class).on(:before_async_enqueue, @context)
+        # Persist BEFORE enqueue — the job payload is identity-only (F2).
         save_context
 
-        serialized_context = ContextSerializer.serialize(@context)
-        @result = configuration.async_router.perform_async(serialized_context, self.class.name,
+        @result = configuration.async_router.perform_async(@context.context_id,
+                                                           RubyReactor.reactor_storage_name(self.class),
                                                            intermediate_results: @context.intermediate_results)
 
         # Even if it's an AsyncResult, it might have finished inline (e.g. Sidekiq::Testing.inline!)
@@ -307,10 +313,11 @@ module RubyReactor
 
     def perform_async_run
       @context.status = :running
+      # Persist BEFORE enqueue — the job payload is identity-only (F2).
       save_context
 
-      serialized_context = ContextSerializer.serialize(@context)
-      @result = configuration.async_router.perform_async(serialized_context, self.class.name,
+      @result = configuration.async_router.perform_async(@context.context_id,
+                                                         RubyReactor.reactor_storage_name(self.class),
                                                          intermediate_results: @context.intermediate_results)
 
       check_for_inline_completion
@@ -419,10 +426,46 @@ module RubyReactor
 
     def save_context
       storage = configuration.storage_adapter
-      reactor_class_name = self.class.name || "AnonymousReactor-#{self.class.object_id}"
+      reactor_class_name = RubyReactor.reactor_storage_name(self.class)
       serialized_context = ContextSerializer.serialize(@context)
       storage.store_context(@context.context_id, serialized_context, reactor_class_name)
     end
+
+    def assign_ordered_lock_nonce!
+      return unless self.class.respond_to?(:ordered_lock_config) && self.class.ordered_lock_config
+      return if @context.private_data[:ordered_lock] || @context.private_data["ordered_lock"]
+
+      config = self.class.ordered_lock_config
+      key = config[:key_proc].call(@context.inputs)
+
+      # Synchronous nested `Reactor.run` of an ordered-lock reactor on the same
+      # key would deadlock: the outer nonce holds the slot, an inner nonce
+      # would never advance until the outer completes — but the outer is
+      # blocked waiting for the inner to return. Mirror the compose behavior:
+      # silently skip nonce assignment (the inner runs without gate/advance)
+      # and log a warning so this isn't invisible.
+      active = Executor::OrderedLockSupport.active_keys
+      if active.include?(key)
+        RubyReactor.configuration.logger.warn(
+          "RubyReactor: nested `Reactor.run` of #{self.class.name || "<anonymous>"} on " \
+          "ordered-lock key '#{key}' from inside another ordered-lock reactor on the same " \
+          "key — nonce assignment skipped, inner run executes without ordering enforcement. " \
+          "Use a different key or move the inner call to a top-level invocation if you need ordering."
+        )
+        return
+      end
+
+      nonce, epoch = RubyReactor::OrderedLock.assign(key, ttl: config[:ttl])
+
+      @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
   end
   # rubocop:enable Metrics/ClassLength
 end

data/lib/ruby_reactor/rspec/helpers.rb

@@ -2,7 +2,13 @@
 
 module RubyReactor
   module RSpec
+    # Globally-included helpers. Only methods whose names clearly belong to
+    # RubyReactor's test surface live here (`test_reactor`). Sidekiq-coupled
+    # helpers live in `SidekiqHelpers` and are scoped to `type: :reactor`.
     module Helpers
+      # Build a `TestSubject` around a reactor invocation. Captures the run for
+      # later introspection via matchers; runs the reactor lazily on first
+      # query unless `.run` is called explicitly.
       def test_reactor(reactor_class, inputs, context: {}, async: nil, process_jobs: true)
         TestSubject.new(
           reactor_class: reactor_class,

data/lib/ruby_reactor/rspec/matchers.rb

@@ -415,6 +415,72 @@ module RubyReactor
         end
       end
 
+      # Asserts the last-assigned ordered_lock nonce for a key. Subject is
+      # the user-provided ordered_lock key (without the `ordered_lock:` prefix).
+      #
+      #   expect("orders:42").to have_ordered_lock_next(3)
+      ::RSpec::Matchers.define :have_ordered_lock_next do |expected|
+        match { |key| Matchers.coordination_adapter.ordered_lock_peek(key)[:next] == expected }
+
+        failure_message do |key|
+          state = Matchers.coordination_adapter.ordered_lock_peek(key)
+          "expected ordered_lock '#{key}' next to be #{expected}, got #{state[:next]} " \
+            "(last_completed: #{state[:last_completed]}, in_flight: #{state[:in_flight].inspect})"
+        end
+      end
+
+      # Asserts the last-advanced cursor for an ordered_lock key.
+      #
+      #   expect("orders:42").to have_ordered_lock_last_completed(2)
+      ::RSpec::Matchers.define :have_ordered_lock_last_completed do |expected|
+        match do |key|
+          Matchers.coordination_adapter.ordered_lock_peek(key)[:last_completed] == expected
+        end
+
+        failure_message do |key|
+          state = Matchers.coordination_adapter.ordered_lock_peek(key)
+          "expected ordered_lock '#{key}' last_completed to be #{expected}, " \
+            "got #{state[:last_completed]} (next: #{state[:next]}, in_flight: #{state[:in_flight].inspect})"
+        end
+      end
+
+      # Asserts the exact set of in-flight nonces for an ordered_lock key.
+      # Order-insensitive — the matcher sorts both sides.
+      #
+      #   expect("orders:42").to have_ordered_lock_in_flight(2, 3)
+      ::RSpec::Matchers.define :have_ordered_lock_in_flight do |*expected|
+        match do |key|
+          actual = Matchers.coordination_adapter.ordered_lock_peek(key)[:in_flight].sort
+          actual == expected.flatten.map(&:to_i).sort
+        end
+
+        failure_message do |key|
+          state = Matchers.coordination_adapter.ordered_lock_peek(key)
+          "expected ordered_lock '#{key}' in_flight to be #{expected.flatten.sort.inspect}, " \
+            "got #{state[:in_flight].inspect} (next: #{state[:next]}, last_completed: #{state[:last_completed]})"
+        end
+      end
+
+      # Asserts an ordered_lock key has fully drained — counters GC'd, no
+      # in-flight nonces. After a clean drain `peek` returns all zeros.
+      #
+      #   expect("orders:42").to be_ordered_lock_drained
+      ::RSpec::Matchers.define :be_ordered_lock_drained do
+        match do |key|
+          state = Matchers.coordination_adapter.ordered_lock_peek(key)
+          state[:next].zero? && state[:last_completed].zero? && state[:in_flight].empty?
+        end
+
+        failure_message do |key|
+          state = Matchers.coordination_adapter.ordered_lock_peek(key)
+          "expected ordered_lock '#{key}' to be drained, but state is #{state.inspect}"
+        end
+
+        failure_message_when_negated do |key|
+          "expected ordered_lock '#{key}' not to be drained, but counters are all zero"
+        end
+      end
+
       # Add more matchers as per plan
       # rubocop:enable Metrics/BlockLength
     end

data/lib/ruby_reactor/rspec/sidekiq_helpers.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module RubyReactor
+  module RSpec
+    # Async-job manipulation helpers. Names like `drain_async_jobs` are too
+    # generic to live in the global spec namespace, so this module is only
+    # auto-included into examples tagged `type: :reactor`. Specs that need it
+    # outside that tag should `include RubyReactor::RSpec::SidekiqHelpers`
+    # explicitly.
+    module SidekiqHelpers
+      # Drain every queued async job across all RubyReactor worker classes
+      # until the queues are empty. Recursive — handles jobs that re-enqueue
+      # themselves (e.g. ordered_lock snoozes) and worker chains that queue
+      # additional jobs.
+      def drain_async_jobs(max_iterations: 100)
+        SidekiqHelpers.drain_async_jobs(max_iterations: max_iterations)
+      end
+
+      # All currently-pending async jobs, wrapped in `PendingJob` so callers
+      # can perform individual jobs out-of-order (e.g. to assert
+      # ordered_lock's snooze behavior) without touching Sidekiq internals.
+      def pending_async_jobs
+        SidekiqHelpers.pending_async_jobs
+      end
+
+      PendingJob = Struct.new(:worker_class, :raw) do
+        def perform!
+          worker_class.jobs.delete(raw)
+          worker_class.new.perform(*raw["args"])
+        end
+
+        def args
+          raw["args"]
+        end
+      end
+
+      def self.worker_classes
+        @worker_classes ||= [
+          RubyReactor::SidekiqWorkers::Worker,
+          RubyReactor::SidekiqWorkers::MapElementWorker,
+          RubyReactor::SidekiqWorkers::MapCollectorWorker
+        ]
+      end
+
+      def self.drain_async_jobs(max_iterations: 100)
+        return unless defined?(Sidekiq::Testing)
+
+        max_iterations.times do
+          processed_any = false
+          worker_classes.each do |worker_class|
+            while (job = worker_class.jobs.shift)
+              worker_class.new.perform(*job["args"])
+              processed_any = true
+            end
+          end
+
+          break unless processed_any
+        end
+      end
+
+      def self.pending_async_jobs
+        return [] unless defined?(Sidekiq::Testing)
+
+        worker_classes.flat_map do |worker_class|
+          worker_class.jobs.map { |raw| PendingJob.new(worker_class, raw) }
+        end
+      end
+    end
+  end
+end

data/lib/ruby_reactor/rspec/storage_reset.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module RubyReactor
+  module RSpec
+    # Test-only `reset!` impls layered onto storage adapters at framework
+    # load time. Kept out of `lib/ruby_reactor/storage/*` so production code
+    # never gains a "wipe everything" entry point.
+    module StorageReset
+      module RedisAdapterReset
+        def reset!
+          @redis.flushdb
+        end
+      end
+
+      def self.install!
+        return if @installed
+
+        ::RubyReactor::Storage::RedisAdapter.prepend(RedisAdapterReset)
+        @installed = true
+      end
+    end
+  end
+end

data/lib/ruby_reactor/rspec/test_subject.rb

@@ -246,6 +246,8 @@ module RubyReactor
                   end
                 end
           RubyReactor::Success.new(val)
+        when "skipped"
+          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)
@@ -269,6 +271,17 @@ module RubyReactor
         end
       end
 
+      # A clean halt: either a `with_period` gate or a step returning
+      # `RubyReactor.Skipped(...)`. The sync run already produced the exact
+      # Skipped (reason/step intact) — surface it. For async runs the worker
+      # swallows the return value, so rebuild from the trace.
+      def skipped_result(ctx)
+        return @run_result if @run_result.is_a?(RubyReactor::Skipped)
+
+        entry = ctx.execution_trace.reverse.find { |t| t[:type].to_s == "skipped" }
+        RubyReactor::Skipped.new(reason: entry&.dig(:reason), step_name: entry&.dig(:step))
+      end
+
       def success?
         ensure_executed!
         @reactor_instance.context.status.to_s == "completed"
@@ -419,34 +432,7 @@ module RubyReactor
       def process_pending_jobs
         return unless defined?(Sidekiq::Testing)
 
-        # Loop until no more jobs are being queued
-        # This handles batched map execution where jobs queue more jobs
-        max_iterations = 100
-        iterations = 0
-
-        while iterations < max_iterations
-          iterations += 1
-          jobs_processed = false
-
-          # Known worker classes to check
-          worker_classes = [
-            RubyReactor::SidekiqWorkers::Worker,
-            RubyReactor::SidekiqWorkers::MapElementWorker,
-            RubyReactor::SidekiqWorkers::MapCollectorWorker
-          ]
-
-          worker_classes.each do |worker_class|
-            while worker_class.jobs.any?
-              job = worker_class.jobs.shift
-              worker_class.new.perform(*job["args"])
-              jobs_processed = true
-            end
-          end
-
-          break unless jobs_processed
-        end
-
-        # Final reload
+        SidekiqHelpers.drain_async_jobs
         @reactor_instance = @reactor_class.find(@reactor_instance.context.context_id)
       end
 

data/lib/ruby_reactor/rspec.rb

@@ -2,17 +2,54 @@
 
 require_relative "rspec/helpers"
 require_relative "rspec/matchers"
+require_relative "rspec/sidekiq_helpers"
+require_relative "rspec/storage_reset"
 require_relative "rspec/test_subject"
 
 module RubyReactor
   module RSpec
+    # Examples opt into RubyReactor's RSpec setup (Sidekiq fake mode,
+    # storage wipe, snooze knob reset) by declaring `type: :reactor`.
+    REACTOR_METADATA = { type: :reactor }.freeze
+
+    DEFAULT_SNOOZE_BASE_DELAY = 5
+    DEFAULT_SNOOZE_JITTER = 5
+    DEFAULT_SNOOZE_MAX_ATTEMPTS = 20
+
     def self.configure(config)
       require_relative "rspec/step_executor_patch"
 
       config.include RubyReactor::RSpec::Helpers
       config.include RubyReactor::RSpec::Matchers
+      config.include RubyReactor::RSpec::SidekiqHelpers, REACTOR_METADATA
 
       ::RubyReactor::Executor::StepExecutor.prepend(RubyReactor::RSpec::StepExecutorPatch)
+      StorageReset.install!
+
+      config.before(:each, REACTOR_METADATA) do
+        RubyReactor::RSpec.prepare_example!
+      end
+    end
+
+    # Idempotent setup invoked before each `type: :reactor` example. Restores
+    # Sidekiq fake mode, clears the queues, wipes the storage adapter, and
+    # rolls back snooze knobs so cross-example bleed-through can't happen.
+    def self.prepare_example!
+      if defined?(::Sidekiq::Testing)
+        begin
+          ::Sidekiq::Testing.fake! unless ::Sidekiq::Testing.fake?
+        rescue ::Sidekiq::Testing::TestModeAlreadySetError
+          # Nested fake!/inline! block already active in this thread; leave it.
+        end
+        ::Sidekiq::Worker.clear_all
+      end
+
+      adapter = ::RubyReactor.configuration.storage_adapter
+      adapter.reset! if adapter.respond_to?(:reset!)
+
+      ::RubyReactor.configuration.lock_snooze_base_delay = DEFAULT_SNOOZE_BASE_DELAY
+      ::RubyReactor.configuration.lock_snooze_jitter = DEFAULT_SNOOZE_JITTER
+      ::RubyReactor.configuration.lock_snooze_max_attempts = DEFAULT_SNOOZE_MAX_ATTEMPTS
     end
   end
 end

data/lib/ruby_reactor/sidekiq_adapter.rb

@@ -2,18 +2,19 @@
 
 module RubyReactor
   class SidekiqAdapter
-    def self.perform_async(serialized_context, reactor_class_name = nil, intermediate_results: {})
-      job_id = SidekiqWorkers::Worker.perform_async(serialized_context, reactor_class_name)
-      context = ContextSerializer.deserialize(serialized_context)
+    # 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 = SidekiqWorkers::Worker.perform_async(context_id, reactor_class_name)
       RubyReactor::AsyncResult.new(job_id: job_id, intermediate_results: intermediate_results,
-                                   execution_id: context.context_id)
+                                   execution_id: context_id)
     end
 
-    def self.perform_in(delay, serialized_context, reactor_class_name = nil, intermediate_results: {})
-      job_id = SidekiqWorkers::Worker.perform_in(delay, serialized_context, reactor_class_name)
-      context = ContextSerializer.deserialize(serialized_context)
+    def self.perform_in(delay, context_id, reactor_class_name = nil, intermediate_results: {})
+      job_id = SidekiqWorkers::Worker.perform_in(delay, context_id, reactor_class_name)
       RubyReactor::AsyncResult.new(job_id: job_id, intermediate_results: intermediate_results,
-                                   execution_id: context.context_id)
+                                   execution_id: context_id)
     end
 
     # rubocop:disable Metrics/ParameterLists

data/lib/ruby_reactor/sidekiq_workers/sweeper_worker.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+require "sidekiq"
+require "securerandom"
+
+module RubyReactor
+  module SidekiqWorkers
+    # Self-rescheduling recovery tick. 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.
+    class SweeperWorker
+      include ::Sidekiq::Worker
+
+      # 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.sidekiq_queue
+
+      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::SweeperWorker sweep failed: #{e.class}: #{e.message}")
+      end
+
+      # 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 self.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