ruby_reactor 0.5.4 → 0.6.0

data/lib/ruby_reactor/worker.rb

@@ -0,0 +1,226 @@
+# frozen_string_literal: true
+
+module RubyReactor
+  # Framework-agnostic resume/snooze/escalate logic shared by every queueing
+  # backend's worker class. Each backend (`Adapters::Sidekiq::Worker`,
+  # `Adapters::ActiveJob::Worker`, ...) includes this and supplies its own
+  # `self.class.perform_in` (native on Sidekiq::Worker, via
+  # `Adapters::ActiveJob::Compat` on ActiveJob::Base) — nothing here references
+  # a specific backend.
+  module Worker
+    # Identity-only payload: storage is the source of truth. Rehydrate the live
+    # context from storage by id, then resume. A nil read means the context was
+    # swept, expired, or already terminal-and-collected — nothing to resume.
+    def perform(context_id, reactor_class_name = nil, snooze_count = 0)
+      # Normalize so a nil/omitted name resolves to the same storage key the
+      # enqueue path wrote (always via reactor_storage_name). Without this a
+      # nil here builds "reactor::context:<id>" and misses the stored
+      # "reactor:AnonymousReactor:context:<id>", silently no-op'ing.
+      reactor_class_name ||= RubyReactor.reactor_storage_name(nil)
+      data = RubyReactor.configuration.storage_adapter.retrieve_context(context_id, reactor_class_name)
+      return if data.nil?
+
+      begin
+        context = ContextSerializer.deserialize_hash(data)
+      rescue RubyReactor::Error::DeserializationError,
+             RubyReactor::Error::SchemaVersionError => e
+        # Permanent failures — re-reading the same stored blob will keep
+        # failing. Mark the context as failed (best-effort) and return so
+        # the job does not burn its retry budget.
+        handle_deserialization_failure(context_id, reactor_class_name, e)
+        return
+      end
+
+      resolve_reactor_class!(context, reactor_class_name)
+      unless context.reactor_class
+        # Still unresolved (class not loaded, or an anonymous reactor with no
+        # storage name to look up) — Executor.new below would blow up on a nil
+        # class and burn the job's retry budget forever. Fail the context now.
+        error = RubyReactor::Error::DeserializationError.new(
+          "reactor class '#{reactor_class_name}' could not be resolved"
+        )
+        handle_deserialization_failure(context_id, reactor_class_name, error)
+        return
+      end
+
+      # Mark that we're executing inline to prevent nested async calls
+      context.inline_async_execution = true
+
+      begin
+        # Resume execution from the failed step
+        executor = Executor.new(context.reactor_class, {}, context)
+        executor.resume_execution
+        # No explicit save here: resume_execution's ensure block already persists
+        # the final root state (`save_context unless skip_context_persist?`), and
+        # in the worker the executor's context IS the root, so an extra checkpoint!
+        # would just re-write the identical blob to the identical key. The
+        # skip_context_persist? guard (stale-batch redelivery of an already-terminal
+        # context) is likewise honored there.
+
+        # Return the executor (which now has the result stored in it)
+        executor
+      rescue RubyReactor::Lock::AcquisitionError,
+             RubyReactor::Semaphore::AcquisitionError,
+             RubyReactor::RateLimit::ExceededError,
+             RubyReactor::OrderedLock::WaitError => e
+        # Snooze on expected concurrency, rate, or ordering contention.
+        # OrderedLock::WaitError carries a poison-pill-derived retry hint,
+        # consumed by compute_snooze_delay below. We avoid the framework's native
+        # retry path so this doesn't burn the job's retry budget or appear
+        # as an error in dashboards. After the configured cap is reached we
+        # escalate by marking the reactor as failed.
+        handle_snooze(context_id, reactor_class_name, context, snooze_count, e)
+      rescue RubyReactor::RateLimitRegistry::UnknownLimitError => e
+        # Permanent configuration error — snoozing or retrying the same job
+        # will keep failing. Mark the context failed immediately.
+        escalate_snooze(context, snooze_count, e)
+      end
+    end
+
+    private
+
+    # If reactor_class_name is provided, use it to get the reactor class.
+    # This handles cases where the class can't be found via const_get.
+    def resolve_reactor_class!(context, reactor_class_name)
+      return unless reactor_class_name && context.reactor_class.nil?
+
+      begin
+        context.reactor_class = Object.const_get(reactor_class_name)
+      rescue NameError
+        # If not found, try to find it in the current namespace
+        # This is a fallback for test environments
+        context.reactor_class = reactor_class_name.constantize if reactor_class_name.respond_to?(:constantize)
+      end
+    end
+
+    def handle_snooze(context_id, reactor_class_name, context, snooze_count, error)
+      config = RubyReactor.configuration
+      max = config.lock_snooze_max_attempts
+
+      # OrderedLock::WaitError bypasses the snooze cap. The gate's
+      # poison_pill_timeout is the only meaningful upper bound on how long a
+      # nonce can legitimately wait; capping snoozes would either fail jobs
+      # prematurely or strand the nonce in `assigned_at` until poison_pill
+      # eventually advances past it. Snooze until the gate passes (or poison
+      # auto-advance moves the cursor past us).
+      # The per-context liveness lock (`async:<id>`) is also uncapped: a
+      # duplicate of the *same* execution may wait arbitrarily long for the
+      # live original to finish (e.g. a sweeper re-enqueue racing a slow but
+      # alive worker). Capping it would fail a legitimately-waiting duplicate.
+      capped = !(error.is_a?(RubyReactor::OrderedLock::WaitError) ||
+                 error.is_a?(RubyReactor::Lock::ContextLockContention))
+
+      if capped && max != :infinity && snooze_count >= max
+        escalate_snooze(context, snooze_count, error)
+        return
+      end
+
+      delay = compute_snooze_delay(config, error)
+      # Re-enqueue by id: the context is already persisted in storage, so the
+      # rescheduled job rehydrates fresh state (no stale blob).
+      self.class.perform_in(delay, context_id, reactor_class_name, snooze_count + 1)
+    end
+
+    # Use the error's `retry_after_seconds` hint when available
+    # (RateLimit::ExceededError carries the time until the bucket rolls);
+    # otherwise fall back to the configured base + jitter for lock/semaphore
+    # contention which has no precise hint.
+    #
+    # OrderedLock::WaitError is deliberately excluded from the hint path: its
+    # `retry_after_seconds` is the poison-pill window (the upper bound before
+    # a *dead* blocker is force-advanced), NOT how long the *live* blocker
+    # will take — which is usually milliseconds. Snoozing for the full window
+    # would make every out-of-order nonce sleep up to poison_pill_timeout even
+    # though its blocker finishes immediately, collapsing throughput. Re-poll
+    # at the base delay instead; poison auto-advance still clears a genuinely
+    # dead blocker on a later gate.
+    def compute_snooze_delay(config, error)
+      jitter = config.lock_snooze_jitter.to_f
+      jitter_amount = jitter.positive? ? rand(0.0..jitter) : 0.0
+
+      if hinted_retry?(error)
+        [error.retry_after_seconds.to_f, 0.1].max + jitter_amount
+      else
+        config.lock_snooze_base_delay.to_f + jitter_amount
+      end
+    end
+
+    def hinted_retry?(error)
+      return false if error.is_a?(RubyReactor::OrderedLock::WaitError)
+
+      error.respond_to?(:retry_after_seconds) && error.retry_after_seconds
+    end
+
+    def escalate_snooze(context, snooze_count, error)
+      RubyReactor.configuration.logger.warn(
+        "RubyReactor snooze limit reached after #{snooze_count} attempts " \
+        "for context #{context.context_id}: #{error.message}"
+      )
+
+      context.status = :failed
+      context.failure_reason = {
+        message: error.message,
+        exception_class: error.class.name,
+        snooze_attempts: snooze_count
+      }
+
+      serialized = ContextSerializer.serialize(context)
+      reactor_class_name = RubyReactor.reactor_storage_name(context.reactor_class)
+      RubyReactor.configuration.storage_adapter.store_context(
+        context.context_id,
+        serialized,
+        reactor_class_name
+      )
+
+      # Escalation is a terminal Failure that never reaches the Executor's
+      # ensure path, so advance the ordered-lock cursor here. Without this
+      # the nonce stays stranded in assigned_at (successors stall for the
+      # full poison_pill_timeout) and, worse, the strict-mode chain marker
+      # is never recorded — successors would RUN instead of being skipped.
+      info = Executor::OrderedLockSupport.info_from(context)
+      Executor::OrderedLockSupport.advance_with_retry(info, failed: true) if info
+    end
+
+    def log_infrastructure_failure(msg, exception)
+      RubyReactor.configuration.logger.error("RubyReactor infrastructure failure: #{exception.message}")
+      RubyReactor.configuration.logger.error("Job details: #{msg.inspect}")
+    end
+
+    # The id-only payload already carries context_id and reactor_class_name, so
+    # there is no blob to parse for metadata — just mark the stored context
+    # failed (best-effort) so the job stops retrying a permanently-broken blob.
+    def handle_deserialization_failure(context_id, reactor_class_name, error)
+      RubyReactor.configuration.logger.error(
+        "RubyReactor deserialization failure for context " \
+        "#{context_id || "unknown"}: #{error.class.name}: #{error.message}"
+      )
+
+      return unless context_id && reactor_class_name
+
+      payload = build_failed_context_payload(context_id, reactor_class_name, error)
+      RubyReactor.configuration.storage_adapter.store_context(
+        context_id,
+        payload,
+        reactor_class_name
+      )
+    rescue StandardError => e
+      # Don't let a persistence failure mask the original deserialization error.
+      RubyReactor.configuration.logger.error(
+        "RubyReactor failed to persist deserialization failure: #{e.class.name}: #{e.message}"
+      )
+    end
+
+    def build_failed_context_payload(context_id, reactor_class_name, error)
+      JSON.generate(
+        "schema_version" => ContextSerializer::SCHEMA_VERSION,
+        "context_id" => context_id,
+        "reactor_class" => reactor_class_name,
+        "status" => "failed",
+        "failure_reason" => {
+          "message" => error.message,
+          "exception_class" => error.class.name
+        }
+      )
+    end
+  end
+end

data/lib/ruby_reactor.rb

@@ -26,6 +26,13 @@ rescue LoadError
   # sidekiq is optional, async features won't be available
 end
 
+# Load active_job if available (for the ActiveJob async adapter)
+begin
+  require "active_job"
+rescue LoadError
+  # active_job is optional, only needed when using the ActiveJob adapter
+end
+
 loader = Zeitwerk::Loader.for_gem
 loader.inflector.inflect("api" => "API", "rspec" => "RSpec")
 loader.setup
@@ -356,7 +363,39 @@ module RubyReactor
   def self.start_sweeper!
     return unless configuration.sweeper_enabled
 
-    SidekiqWorkers::SweeperWorker.schedule_next
+    sweeper_job_class.schedule_next
+  end
+
+  # The sweeper job class living alongside the configured `async_router`
+  # (e.g. `Adapters::Sidekiq::Router` -> `Adapters::Sidekiq::SweeperWorker`),
+  # so the chain is kicked through whichever backend is configured instead of
+  # a hardcoded Sidekiq class. Known built-in routers are mapped explicitly;
+  # a custom `configuration.async_router` falls back to a sibling-namespace
+  # lookup, with a clear error (instead of a bare NameError) when that
+  # convention doesn't hold.
+  def self.sweeper_job_class
+    router = configuration.async_router
+    case router.name
+    when "RubyReactor::Adapters::Sidekiq::Router" then Adapters::Sidekiq::SweeperWorker
+    when "RubyReactor::Adapters::ActiveJob::Router" then Adapters::ActiveJob::SweeperWorker
+    else
+      inferred_sweeper_job_class(router)
+    end
+  end
+
+  def self.inferred_sweeper_job_class(router)
+    namespace_name = router.name.to_s.rpartition("::").first
+    raise sweeper_job_class_error(router) if namespace_name.empty?
+
+    Object.const_get(namespace_name).const_get(:SweeperWorker)
+  rescue NameError
+    raise sweeper_job_class_error(router)
+  end
+
+  def self.sweeper_job_class_error(router)
+    "RubyReactor: cannot infer a sweeper job class for custom async_router " \
+      "#{router.inspect}. Define a `SweeperWorker` class alongside it " \
+      "(same namespace), or override `RubyReactor.sweeper_job_class`."
   end
 
   # Run both recovery sweepers exactly once and return their counts. The

data/specs/active_job.md

@@ -0,0 +1,259 @@
+# Pluggable Background Adapters (Sidekiq → ActiveJob)
+
+## Goal
+
+Today RubyReactor is hardwired to Sidekiq for everything async: enqueuing,
+resuming, map-element fan-out/collection, and the recovery sweeper. We want
+to support other background processors — starting with ActiveJob — without
+duplicating the reactor-resume/snooze/escalate logic per adapter.
+
+## What's already abstracted (good news)
+
+The **enqueue side** is already behind a seam:
+
+- `RubyReactor.configuration.async_router` (default `RubyReactor::Adapters::Sidekiq::Router`,
+  [configuration.rb:126-128](../lib/ruby_reactor/configuration.rb#L126-L128)) is the
+  only thing the core engine calls to go async. Call sites:
+  [reactor.rb:117](../lib/ruby_reactor/reactor.rb#L117),
+  [reactor.rb:319](../lib/ruby_reactor/reactor.rb#L319),
+  [step/map_step.rb:274](../lib/ruby_reactor/step/map_step.rb#L274),
+  [step/map_step.rb:285](../lib/ruby_reactor/step/map_step.rb#L285),
+  [map/dispatcher.rb:177](../lib/ruby_reactor/map/dispatcher.rb#L177),
+  [map/element_executor.rb:155](../lib/ruby_reactor/map/element_executor.rb#L155),
+  [map/element_executor.rb:176](../lib/ruby_reactor/map/element_executor.rb#L176),
+  [executor/retry_manager.rb:59,80](../lib/ruby_reactor/executor/retry_manager.rb#L59),
+  [executor/step_executor.rb:219](../lib/ruby_reactor/executor/step_executor.rb#L219),
+  [sweeper.rb:48](../lib/ruby_reactor/sweeper.rb#L48),
+  [map/sweeper.rb:99](../lib/ruby_reactor/map/sweeper.rb#L99).
+- The router contract is 5 class methods on `SidekiqAdapter`
+  ([sidekiq_adapter.rb](../lib/ruby_reactor/sidekiq_adapter.rb)):
+  `perform_async`, `perform_in`, `perform_map_element_async`,
+  `perform_map_element_in`, `perform_map_collection_async`. All return
+  `RubyReactor::AsyncResult`.
+- An adapter for any other queueing backend just needs to implement that
+  same 5-method contract and assign it to `config.async_router`. **This part
+  needs no rework.**
+
+## What's NOT abstracted (the actual gap)
+
+The **worker/job side** — the classes the queue invokes — bakes Sidekiq in
+directly. **Decision: these move into `RubyReactor::Adapters::Sidekiq::*`**
+(renamed from `RubyReactor::SidekiqWorkers::*`), with a sibling
+`RubyReactor::Adapters::ActiveJob::*` for the new adapter — see
+[Namespace](#namespace) below.
+
+| Class (today) | File | Sidekiq coupling |
+|---|---|---|
+| `SidekiqWorkers::Worker` | [worker.rb](../lib/ruby_reactor/sidekiq_workers/worker.rb) | `include ::Sidekiq::Worker`, `sidekiq_options`, `sidekiq_retries_exhausted`, and internally calls `self.class.perform_in(...)` to reschedule snoozes (lines 116, 91-117) |
+| `SidekiqWorkers::MapElementWorker` | [map_element_worker.rb](../lib/ruby_reactor/sidekiq_workers/map_element_worker.rb) | `include ::Sidekiq::Worker`; body is a 1-line delegate to `Map::ElementExecutor.perform` |
+| `SidekiqWorkers::MapCollectorWorker` | [map_collector_worker.rb](../lib/ruby_reactor/sidekiq_workers/map_collector_worker.rb) | same — 1-line delegate to `Map::Collector.perform` |
+| `SidekiqWorkers::SweeperWorker` | [sweeper_worker.rb](../lib/ruby_reactor/sidekiq_workers/sweeper_worker.rb) | `include ::Sidekiq::Worker`, `sidekiq_options retry: false`, self-reschedules via `perform_in` / class-level `perform_in` in `schedule_next` |
+
+Plus test-side coupling:
+
+- [rspec/sidekiq_helpers.rb](../lib/ruby_reactor/rspec/sidekiq_helpers.rb) hardcodes
+  the 3 Sidekiq worker classes and `Sidekiq::Testing` fake-mode draining.
+- [rspec/test_subject.rb:194-203,433](../lib/ruby_reactor/rspec/test_subject.rb#L194-L203)
+  gates job-processing on `defined?(Sidekiq::Testing)` and forces
+  `async_router` back to `SidekiqAdapter`.
+- [ruby_reactor.rb:22-27](../lib/ruby_reactor.rb#L22-L27) optionally requires
+  `sidekiq`; [ruby_reactor.rb:359](../lib/ruby_reactor.rb#L359) calls
+  `SidekiqWorkers::SweeperWorker.schedule_next` directly from
+  `RubyReactor.start_sweeper!`.
+
+The real logic worth extracting lives almost entirely in
+`SidekiqWorkers::Worker#perform` (~65 lines): rehydrate context from
+storage, deserialize, resolve `reactor_class`, mark
+`inline_async_execution`, run `Executor#resume_execution`, and on
+lock/semaphore/rate-limit/ordered-lock contention either snooze (re-enqueue
+with a computed delay) or escalate to `failed`. None of that is
+Sidekiq-specific — it only *touches* Sidekiq via `self.class.perform_in` to
+reschedule.
+
+## Proposal
+
+### 1. Normalize the enqueue API at the job-class boundary, not in the shared logic
+
+`Sidekiq::Worker` gives every job class `.perform_async` / `.perform_in` for
+free. ActiveJob doesn't — it has `.perform_later` and
+`.set(wait: delay).perform_later`. Rather than teach the shared logic two
+different reschedule calls, give every framework-specific job class the
+same two class methods, so the shared mixin can keep calling
+`self.class.perform_in(...)` unchanged:
+
+```ruby
+module RubyReactor
+  module Adapters
+    module ActiveJob
+      module Compat
+        def perform_async(*args) = perform_later(*args)
+        def perform_in(delay, *args) = set(wait: delay).perform_later(*args)
+      end
+    end
+  end
+end
+```
+
+### 2. Extract `RubyReactor::Worker` — the framework-agnostic mixin
+
+Move the body of `Adapters::Sidekiq::Worker#perform` (and its private snooze/
+escalate/deserialization-failure helpers) into a plain module with no
+`Sidekiq` reference:
+
+```ruby
+module RubyReactor
+  module Worker
+    def perform(context_id, reactor_class_name = nil, snooze_count = 0)
+      # ...exact same logic as today's SidekiqWorkers::Worker#perform...
+    end
+
+    private
+    # handle_snooze, compute_snooze_delay, hinted_retry?, escalate_snooze,
+    # log_infrastructure_failure, handle_deserialization_failure,
+    # build_failed_context_payload — unchanged, moved verbatim.
+  end
+end
+```
+
+`Adapters::Sidekiq::Worker` then becomes:
+
+```ruby
+module RubyReactor
+  module Adapters
+    module Sidekiq
+      class Worker
+        include ::Sidekiq::Worker
+        include RubyReactor::Worker
+
+        sidekiq_options retry: RubyReactor.configuration.sidekiq_retry_count,
+                        dead: false, queue: RubyReactor.configuration.sidekiq_queue
+      end
+    end
+  end
+end
+```
+
+And a new `Adapters::ActiveJob::Worker`:
+
+```ruby
+module RubyReactor
+  module Adapters
+    module ActiveJob
+      class Worker < ::ActiveJob::Base
+        extend Compat
+        include RubyReactor::Worker
+
+        queue_as { RubyReactor.configuration.sidekiq_queue } # or a renamed generic config
+      end
+    end
+  end
+end
+```
+
+Same pattern applies to `MapElementWorker` / `MapCollectorWorker` — they're
+already a 1-line delegate, so genericizing is just swapping the include; no
+logic to extract.
+
+### 3. Sweeper
+
+`SweeperWorker`'s window-claim-lock + self-reschedule logic
+([sweeper_worker.rb:30-70](../lib/ruby_reactor/sidekiq_workers/sweeper_worker.rb#L30-L70))
+is also framework-agnostic except for the `perform_in` call in
+`schedule_next`. Extract the same way into `RubyReactor::SweeperJob`,
+included into both `Adapters::Sidekiq::SweeperWorker` (`sidekiq_options retry: false`)
+and an `Adapters::ActiveJob::SweeperWorker`. `RubyReactor.start_sweeper!`
+([ruby_reactor.rb:356-360](../lib/ruby_reactor.rb#L356-L360)) needs to call
+through whichever sweeper job class matches the configured adapter instead
+of hardcoding `Adapters::Sidekiq::SweeperWorker`.
+
+### 4. New `RubyReactor::Adapters::ActiveJob::Router`
+
+Mirrors today's `RubyReactor::Adapters::Sidekiq::Router` (renamed from
+`SidekiqAdapter`) exactly — same 5 methods, just pointing at the
+`Adapters::ActiveJob::*` job classes instead of `Adapters::Sidekiq::*`. No
+changes needed to any core call site; swap is purely
+`config.async_router = RubyReactor::Adapters::ActiveJob::Router`.
+
+### 5. Optional config sugar
+
+`configuration.rb` already does this pattern for storage
+([configuration.rb:114-121](../lib/ruby_reactor/configuration.rb#L114-L121)):
+a single `storage.adapter` symbol resolves to a concrete adapter instance.
+Could mirror it — `config.queue_adapter = :sidekiq | :active_job` resolving
+both `async_router` and the sweeper job class — but this is sugar, not
+required for the feature to work. Confirm whether you want it.
+
+### 6. Test helpers
+
+`rspec/sidekiq_helpers.rb` and the `Sidekiq::Testing` branch in
+`rspec/test_subject.rb` only fire for Sidekiq today. For ActiveJob, Rails
+already ships `ActiveJob::TestHelper` (`perform_enqueued_jobs`,
+`have_enqueued_job`) which covers most of this generically. We'd still want
+something equivalent to `drain_async_jobs` (loops until self-rescheduling
+jobs — e.g. ordered-lock snoozes — stop producing new ones), so
+`test_subject.rb`'s job-processing gate needs to branch on which
+testing framework is active (or be driven by `configuration.async_router`)
+rather than hardcoding `defined?(Sidekiq::Testing)`.
+
+### 7. Loading
+
+`ruby_reactor.rb:22-27` optionally `require "sidekiq"`. Add the same
+optional-require pattern for `active_job`, so neither dependency is forced
+on users who only need one.
+
+## Namespace
+
+**Decided: `RubyReactor::Adapters::Sidekiq::*` / `RubyReactor::Adapters::ActiveJob::*`.**
+
+Renames/moves required (mechanical, but touches every reference):
+
+| Today | Becomes |
+|---|---|
+| `RubyReactor::SidekiqAdapter` | `RubyReactor::Adapters::Sidekiq::Router` |
+| `RubyReactor::SidekiqWorkers::Worker` | `RubyReactor::Adapters::Sidekiq::Worker` |
+| `RubyReactor::SidekiqWorkers::MapElementWorker` | `RubyReactor::Adapters::Sidekiq::MapElementWorker` |
+| `RubyReactor::SidekiqWorkers::MapCollectorWorker` | `RubyReactor::Adapters::Sidekiq::MapCollectorWorker` |
+| `RubyReactor::SidekiqWorkers::SweeperWorker` | `RubyReactor::Adapters::Sidekiq::SweeperWorker` |
+| (new) | `RubyReactor::Adapters::ActiveJob::Router` |
+| (new) | `RubyReactor::Adapters::ActiveJob::{Worker,MapElementWorker,MapCollectorWorker,SweeperWorker}` |
+
+Files move from `lib/ruby_reactor/sidekiq_workers/*.rb` +
+`lib/ruby_reactor/sidekiq_adapter.rb` to
+`lib/ruby_reactor/adapters/sidekiq/*.rb` (Zeitwerk-driven, so the directory
+move IS the rename — no manual `module` boilerplate beyond nesting). New
+ActiveJob side lives in `lib/ruby_reactor/adapters/active_job/*.rb`.
+
+References that need updating for the rename:
+- [configuration.rb:107](../lib/ruby_reactor/configuration.rb#L107) — `@async_router ||= RubyReactor::SidekiqAdapter`
+- [ruby_reactor.rb:359](../lib/ruby_reactor.rb#L359) — `SidekiqWorkers::SweeperWorker.schedule_next`
+- [rspec/sidekiq_helpers.rb](../lib/ruby_reactor/rspec/sidekiq_helpers.rb) — `worker_classes` list
+- [rspec/test_subject.rb:196](../lib/ruby_reactor/rspec/test_subject.rb#L196) — stub target
+- [spec/ruby_reactor/sidekiq_workers/worker_spec.rb](../spec/ruby_reactor/sidekiq_workers/worker_spec.rb),
+  [spec/ruby_reactor/sidekiq_workers/sweeper_worker_spec.rb](../spec/ruby_reactor/sidekiq_workers/sweeper_worker_spec.rb) —
+  `described_class` references, move to `spec/ruby_reactor/adapters/sidekiq/`
+
+## Retry config — decided: generic
+
+`sidekiq_retry_count` / `sidekiq_queue` rename to `config.job_retry_count` /
+`config.queue_name`, used by both adapters:
+
+- `Adapters::Sidekiq::Worker` → `sidekiq_options retry: config.job_retry_count, dead: false, queue: config.queue_name`
+- `Adapters::ActiveJob::Worker` → maps to `retry_on StandardError, attempts: config.job_retry_count` (infra
+  failures only — reactor-specific errors are already caught by the shared
+  snooze/escalate logic in `RubyReactor::Worker` before they'd ever reach
+  the framework's retry layer) and `queue_as { config.queue_name }`.
+- `sidekiq_retries_exhausted` (currently an empty hook) → ActiveJob
+  equivalent is `retry_on ... do |job, error| ... end` / `discard_on`.
+
+`configuration.rb` changes: add `job_retry_count`/`queue_name` as the
+canonical attrs; keep `sidekiq_retry_count`/`sidekiq_queue` as deprecated
+aliases delegating to the new names so existing configs don't break.
+
+None of this requires touching the enqueue-side call sites in
+`reactor.rb`, `executor/*`, `map/*` — that seam already works (it just calls
+through `config.async_router`, whose value changes, not its call sites).
+The work is isolated to: `lib/ruby_reactor/worker.rb` (new),
+`lib/ruby_reactor/sweeper_job.rb` (new), the `sidekiq_workers/` →
+`adapters/sidekiq/` move + rename, `adapters/active_job/*.rb` (new, 5
+classes: `Router` + 4 job classes), and the test-helper /
+`start_sweeper!` branching described above.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ruby_reactor
 version: !ruby/object:Gem::Version
-  version: 0.5.4
+  version: 0.6.0
 platform: ruby
 authors:
 - Artur
@@ -88,16 +88,64 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".claude/skills/speckit-agent-context-update/SKILL.md"
+- ".claude/skills/speckit-analyze/SKILL.md"
+- ".claude/skills/speckit-checklist/SKILL.md"
+- ".claude/skills/speckit-clarify/SKILL.md"
+- ".claude/skills/speckit-constitution/SKILL.md"
+- ".claude/skills/speckit-converge/SKILL.md"
+- ".claude/skills/speckit-implement/SKILL.md"
+- ".claude/skills/speckit-plan/SKILL.md"
+- ".claude/skills/speckit-specify/SKILL.md"
+- ".claude/skills/speckit-tasks/SKILL.md"
+- ".claude/skills/speckit-taskstoissues/SKILL.md"
 - ".release-please-config.json"
 - ".release-please-manifest.json"
 - ".rspec"
 - ".rubocop.yml"
+- ".specify/extensions.yml"
+- ".specify/extensions/.registry"
+- ".specify/extensions/agent-context/README.md"
+- ".specify/extensions/agent-context/agent-context-config.yml"
+- ".specify/extensions/agent-context/commands/speckit.agent-context.update.md"
+- ".specify/extensions/agent-context/extension.yml"
+- ".specify/extensions/agent-context/scripts/bash/update-agent-context.sh"
+- ".specify/extensions/agent-context/scripts/powershell/update-agent-context.ps1"
+- ".specify/feature.json"
+- ".specify/init-options.json"
+- ".specify/integration.json"
+- ".specify/integrations/claude.manifest.json"
+- ".specify/integrations/speckit.manifest.json"
+- ".specify/memory/constitution.md"
+- ".specify/scripts/bash/check-prerequisites.sh"
+- ".specify/scripts/bash/common.sh"
+- ".specify/scripts/bash/create-new-feature.sh"
+- ".specify/scripts/bash/setup-plan.sh"
+- ".specify/scripts/bash/setup-tasks.sh"
+- ".specify/templates/checklist-template.md"
+- ".specify/templates/constitution-template.md"
+- ".specify/templates/plan-template.md"
+- ".specify/templates/spec-template.md"
+- ".specify/templates/tasks-template.md"
+- ".specify/workflows/speckit/workflow.yml"
+- ".specify/workflows/workflow-registry.json"
 - ".tool-versions"
 - CHANGELOG.md
 - CODE_OF_CONDUCT.md
 - README.md
 - Rakefile
 - lib/ruby_reactor.rb
+- lib/ruby_reactor/adapters/active_job/compat.rb
+- lib/ruby_reactor/adapters/active_job/map_collector_worker.rb
+- lib/ruby_reactor/adapters/active_job/map_element_worker.rb
+- lib/ruby_reactor/adapters/active_job/router.rb
+- lib/ruby_reactor/adapters/active_job/sweeper_worker.rb
+- lib/ruby_reactor/adapters/active_job/worker.rb
+- lib/ruby_reactor/adapters/sidekiq/map_collector_worker.rb
+- lib/ruby_reactor/adapters/sidekiq/map_element_worker.rb
+- lib/ruby_reactor/adapters/sidekiq/router.rb
+- lib/ruby_reactor/adapters/sidekiq/sweeper_worker.rb
+- lib/ruby_reactor/adapters/sidekiq/worker.rb
 - lib/ruby_reactor/configuration.rb
 - lib/ruby_reactor/context.rb
 - lib/ruby_reactor/context_serializer.rb
@@ -150,6 +198,8 @@ files:
 - lib/ruby_reactor/retry_context.rb
 - lib/ruby_reactor/retry_queued_result.rb
 - lib/ruby_reactor/rspec.rb
+- lib/ruby_reactor/rspec/active_job_helpers.rb
+- lib/ruby_reactor/rspec/async_test_helpers.rb
 - lib/ruby_reactor/rspec/helpers.rb
 - lib/ruby_reactor/rspec/matchers.rb
 - lib/ruby_reactor/rspec/sidekiq_helpers.rb
@@ -157,11 +207,6 @@ files:
 - lib/ruby_reactor/rspec/storage_reset.rb
 - lib/ruby_reactor/rspec/test_subject.rb
 - lib/ruby_reactor/semaphore.rb
-- lib/ruby_reactor/sidekiq_adapter.rb
-- lib/ruby_reactor/sidekiq_workers/map_collector_worker.rb
-- lib/ruby_reactor/sidekiq_workers/map_element_worker.rb
-- lib/ruby_reactor/sidekiq_workers/sweeper_worker.rb
-- lib/ruby_reactor/sidekiq_workers/worker.rb
 - lib/ruby_reactor/step.rb
 - lib/ruby_reactor/step/compose_step.rb
 - lib/ruby_reactor/step/map_step.rb
@@ -171,6 +216,7 @@ files:
 - lib/ruby_reactor/storage/redis_locking.rb
 - lib/ruby_reactor/storage/redis_ordered_locking.rb
 - lib/ruby_reactor/sweeper.rb
+- lib/ruby_reactor/sweeper_job.rb
 - lib/ruby_reactor/template/base.rb
 - lib/ruby_reactor/template/dynamic_source.rb
 - lib/ruby_reactor/template/element.rb
@@ -191,9 +237,11 @@ files:
 - lib/ruby_reactor/web/public/assets/index-D7IBZvos.js
 - lib/ruby_reactor/web/public/index.html
 - lib/ruby_reactor/web/public/vite.svg
+- lib/ruby_reactor/worker.rb
 - llms-full.txt
 - llms.txt
 - sig/ruby_reactor.rbs
+- specs/active_job.md
 - teley/Dockerfile
 homepage: https://github.com/arturictus/ruby_reactor
 licenses: []