solid-jobs 0.1.2 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1a9ddd8000ed07b176d4e291ba7e6b5c1b6a3d909efe282ea6ace542d676e142
-  data.tar.gz: 242f4734ef254188dee64f1ce73df43cbb83f6d39840d7e8f59c6017a499a5f3
+  metadata.gz: 8c178515fb3c56d80f0380da9f25114cd44679135b4d3d39fb468c45760748a7
+  data.tar.gz: 94080a99ea85f351714722d4f4f073ab99f01b2e5096a8e304670138171cf1ab
 SHA512:
-  metadata.gz: 8d2bb684bb107820e189f12d4ac709ce8ad43e546bdf2da5933fcd781627655a8897030ed53010861a74619d65afb33fd89466a1c12993d8ab51e4de85f9c2f8
-  data.tar.gz: 22fb65c94e80dc84dc94f5e6ad3fa9a5047378f45fe29263c5a98817c6a0aeda71f9d54f597a69b0407332e8052f1a5d5da097b97fbd22be912543c56015f78d
+  metadata.gz: fc05837b46c971dfd517cedac8bd46960867160cce776384eced29d41fac3a787b1f45a1a8f2d21ebeddbdb828766087a01396f245a255e5e77443bfa5366a2f
+  data.tar.gz: af56380ec6a6e82470d4df8c477b0e87eec5dc9aaddb9d04fcad32f6d630f695254c77008b2c4cb4400b496a2a5a566a4b1e58fec2b93d536ad3447868146099

data/CHANGELOG.md

@@ -2,7 +2,40 @@
 
 All notable changes to this project will be documented in this file.
 
-## [Unreleased]
+## [0.2.0] - 2026-10-03
+
+### Breaking
+
+- Replace the previous job API with the independent `SolidJobs::Task` API:
+  `enqueue`, `enqueue_after`, `enqueue_at`, `enqueue_many`, `execute`, and
+  `with_options`.
+- Replace the previous payload with a SolidJobs envelope using `id`, `task`,
+  `arguments`, `channel`, `run_at`, `created_ms`, and `queued_ms`.
+- Move all Redis data into the `solid_jobs:` keyspace. Existing queued data is
+  not read or migrated automatically.
+- Replace middleware chains with `publish_interceptors` and
+  `execute_interceptors`, whose interceptors implement `around(context)`.
+- Replace the administrative API with `Metrics`, `Channel`, `StoredTask`,
+  `PlannedTasks`, `RetryingTasks`, `DiscardedTasks`, `Node`, `Nodes`,
+  `Execution`, and `Claims`.
+- Replace queue configuration with channels and the `:weighted`, `:priority`,
+  and `:shuffle` ordering modes.
+- Remove all Sidekiq compatibility aliases and wire-format compatibility.
+
+### Changed
+
+- Claims use UUID task IDs and claim tokens, with generation-fenced completion
+  and requeue operations.
+- Failure handling uses `max_failures`, `retry_within`, `retry_delay`, and
+  `after_final_failure`.
+- Testing modes are now `:capture` and `:execute`.
+
+## [0.1.3] - 2026-10-01
+
+### Changed
+
+- Require `solid-redis` 1.0.11 and rely on its `solid-resp-ractor` dependency
+  instead of declaring and loading the RESP codec directly.
 
 ## [0.1.2] - 2026-10-01
 
@@ -56,5 +89,8 @@ All notable changes to this project will be documented in this file.
 - Reliable-hot-path and CPU-scaling profilers plus the independent Sidekiq
   comparison benchmark.
 
-[Unreleased]: https://github.com/nicolasva/solid-jobs/compare/v0.1.0...HEAD
+[0.2.0]: https://github.com/nicolasva/solid-jobs/compare/v0.1.3...v0.2.0
+[0.1.3]: https://github.com/nicolasva/solid-jobs/compare/v0.1.2...v0.1.3
+[0.1.2]: https://github.com/nicolasva/solid-jobs/compare/v0.1.1...v0.1.2
+[0.1.1]: https://github.com/nicolasva/solid-jobs/compare/v0.1.0...v0.1.1
 [0.1.0]: https://github.com/nicolasva/solid-jobs/releases/tag/v0.1.0

data/README.md

@@ -1,163 +1,183 @@
 # SolidJobs
 
 [![Build Status](https://github.com/nicolasva/solid-jobs/actions/workflows/ci.yml/badge.svg)](https://github.com/nicolasva/solid-jobs/actions/workflows/ci.yml)
-[![Code Climate](https://codeclimate.com/github/nicolasva/solid-jobs/badges/gpa.svg)](https://codeclimate.com/github/nicolasva/solid-jobs)
 [![Gem Version](https://badge.fury.io/rb/solid-jobs.svg)](https://rubygems.org/gems/solid-jobs)
-[![Documentation Status](https://img.shields.io/badge/docs-rubydoc.info-blue.svg)](https://www.rubydoc.info/gems/solid-jobs)
-[![Downloads](https://img.shields.io/gem/dt/solid-jobs.svg)](https://rubygems.org/gems/solid-jobs)
 
-SolidJobs is a Ractor-oriented Redis background job system for Ruby. It uses
-`solid-redis` for Redis access and keeps mutable clients, pools, middleware,
-and runtime state local to their owning Ractor.
+SolidJobs is a Ractor-oriented Redis task runner for Ruby. It provides its own
+task API, Redis envelope, keyspace, interceptor model, failure policy, and
+inspection API.
 
-SolidJobs is an independent implementation. It does not depend on or load the
-Sidekiq gem. Its Redis job payloads and queue keys are designed to be
-compatible with the Sidekiq 8 open-source data format.
-
-SolidJobs and its required gems use pure Ruby and do not require native
-extensions. Hot paths are designed around bounded buffers, reusable immutable
-configuration, and low-allocation command batches.
+SolidJobs is **not compatible with Sidekiq**. It does not read Sidekiq queues,
+does not write Sidekiq payloads, and does not expose Sidekiq's job API. Existing
+applications and queued work must be migrated explicitly.
 
 ## Installation
 
-Add SolidJobs 0.1 to your bundle:
-
 ```ruby
-gem "solid-jobs", "~> 0.1.0"
+gem "solid-jobs"
 ```
 
-Then run:
-
-```sh
-bundle install
-```
-
-## Delivery semantics
+Then run `bundle install`.
 
-SolidJobs provides **at-least-once** job delivery. A worker atomically moves a
-job from `queue:<name>` to a process reservation list before execution and
-removes it only after a successful ACK. Graceful shutdown requeues unfinished
-jobs; reservations owned by a crashed process are recovered into their
-original queues.
-
-A process can still crash after the application side effect and before the
-ACK. The recovered job will then run again. Jobs must therefore be idempotent
-or implement an application-level deduplication key when duplicate side
-effects are unsafe. SolidJobs does not claim exactly-once execution.
+## Defining and submitting tasks
 
 ```ruby
-class HardJob
-  include SolidJobs::Job
+class RecalculateAccount
+  include SolidJobs::Task
 
-  solid_jobs_options queue: "critical", retry: 10
+  task_options channel: "critical", max_failures: 10
 
   def perform(account_id)
     Account.find(account_id).recalculate!
   end
 end
 
-HardJob.perform_async(42)
-HardJob.perform_in(30, 42)
+RecalculateAccount.enqueue(42)
+RecalculateAccount.enqueue_after(30, 42)
+RecalculateAccount.enqueue_at(Time.now + 300, 42)
+RecalculateAccount.enqueue_many([[42], [43], [44]])
+```
+
+The persisted envelope is specific to SolidJobs:
+
+```json
+{
+  "id": "7ec33ed5-1b77-4bde-8960-bd77231f10ef",
+  "task": "RecalculateAccount",
+  "arguments": [42],
+  "channel": "critical",
+  "max_failures": 10,
+  "created_ms": 1790981000000,
+  "queued_ms": 1790981000001
+}
 ```
 
-Run workers:
+All internal Redis keys use the `solid_jobs:` namespace. Ready work is stored
+under `solid_jobs:channel:<name>`; planned, retrying, discarded, node, claim,
+attempt, and metric data use separate namespaced keys.
+
+Run executors:
 
 ```sh
 bundle exec solid-jobs --require ./config/environment \
-  --concurrency 8 --queue critical,3 --queue default
+  --concurrency 8 --channel critical,3 --channel default
 ```
 
-## Tests
-
-SolidJobs uses Minitest exclusively:
+## Configuration
 
-```sh
-# Unit and bounded Redis integration tests
-bundle exec rake test
+```ruby
+SolidJobs.configure do |config|
+  config.channels = [["critical", 3], "default"]
+  config.channel_order = :weighted
+  config.concurrency = 8
+  config.shutdown_timeout = 25
+  config.default_task_options = {
+    channel: "default",
+    max_failures: 25,
+  }
+end
+```
 
-# Bounded concurrency and multi-process recovery stress
-STRESS_JOBS=10000 bundle exec rake stress
+`channel_order` accepts `:weighted` for bounded weighted round-robin,
+`:priority` for declaration-order priority, and `:shuffle` for random
+selection from the weighted channel list.
 
-# Reproducible random-fault campaign
-SOLID_JOBS_TORTURE=1 STRESS_JOBS=100000 bundle exec rake torture
+## Interceptors
 
-# Re-run an exact failure sequence
-SOLID_JOBS_TORTURE=1 STRESS_JOBS=100000 STRESS_SEED=123456 bundle exec rake torture
+Publication and execution use SolidJobs interceptors. An interceptor implements
+`around(context)` and yields to continue:
 
-# Repeated fresh-process RESP/Ractor startup torture
-STARTUP_TORTURE_CYCLES=1000 \
-STARTUP_TORTURE_READERS=100 \
-bundle exec rake startup_torture
+```ruby
+class TraceExecution
+  def around(context)
+    Telemetry.start(context.envelope.fetch("id"))
+    yield
+  ensure
+    Telemetry.finish
+  end
+end
 
-# Long-running stability; defaults to 24 hours
-SOLID_JOBS_SOAK=1 SOLID_JOBS_SOAK_SECONDS=86400 bundle exec rake soak
+SolidJobs.configure do |config|
+  config.execute_interceptors.use(TraceExecution)
+end
 ```
 
-The torture report reconciles enqueued, uniquely completed, duplicate,
-dead, queued, and reserved jobs. Any non-zero `LOST` value fails the test.
+Publication interceptors receive `SolidJobs::Publisher::Publication`; execution
+interceptors receive `SolidJobs::Executor::Execution`.
 
-Profile the reliable execution path independently from application work:
+## Failure handling
 
-```sh
-REDIS_URL=redis://127.0.0.1:6379/0 \
-HOT_PATH_JOBS=10000 \
-bundle exec rake benchmark:hot_path
+Tasks default to 25 failures. A task can customize the delay or final action:
+
+```ruby
+class ImportCatalog
+  include SolidJobs::Task
+
+  task_options max_failures: 8, retry_within: 3_600
+
+  retry_delay do |failure_count, error, envelope|
+    :drop if error.is_a?(InvalidCatalog)
+  end
+
+  after_final_failure do |envelope, error|
+    Alerts.catalog_import_failed(envelope.fetch("id"), error)
+  end
+end
 ```
 
-The report separates time and allocations for reservation, payload reuse,
-observability registration, dispatch/perform wrapping, observability cleanup,
-and fenced ACK. Fetch decodes the payload once for both reservation metadata
-and dispatch; its job body is intentionally empty.
+`retry_delay` may return a delay in seconds, `:drop`, or `:archive`. Without an
+override, SolidJobs uses capped exponential backoff with equal jitter.
+
+## Delivery semantics
+
+SolidJobs provides **at-least-once** delivery. An executor atomically claims a
+task before execution and completes the claim only after `perform` returns.
+Graceful shutdown requeues unfinished tasks. Claims owned by a crashed node are
+recovered into their original channels.
+
+A process can still crash after an application side effect and before claim
+completion. The recovered task then runs again. Tasks must be idempotent or use
+application-level deduplication when duplicate effects are unsafe.
+
+See [docs/reliability.md](docs/reliability.md) for the state machine, claim
+fencing, recovery rules, and Ruby Ractor caveats.
+
+## Testing
 
-Diagnose CPU scaling independently from Redis:
+```ruby
+SolidJobs.testing!(:capture) do
+  RecalculateAccount.enqueue(42)
+  RecalculateAccount.captured
+end
+
+SolidJobs.testing!(:execute) do
+  RecalculateAccount.enqueue(42)
+end
+```
+
+Run the project suites:
 
 ```sh
-CPU_SCALING_JOBS=1000 \
-CPU_SCALING_ITERATIONS=210000 \
-bundle exec rake benchmark:cpu_scaling
+bundle exec rake test
+STRESS_JOBS=10000 bundle exec rake stress
+SOLID_JOBS_TORTURE=1 STRESS_JOBS=100000 bundle exec rake torture
+SOLID_JOBS_SOAK=1 SOLID_JOBS_SOAK_SECONDS=86400 bundle exec rake soak
 ```
 
-This runs the identical CPU loop through pure Ractors and through the
-SolidJobs in-memory dispatch path. Each 1/2/4/8 case uses fresh processes and
-reports execution latency, scaling efficiency, CPU-seconds per 1,000 jobs,
-RSS, allocations, GC time, heap slots, and malloc growth.
-
-## Sidekiq comparison
-
-The separate `benchmark_sidekiq_solid-jobs` bundle runs Sidekiq and SolidJobs
-against the same isolated Redis server. It covers enqueue, bulk enqueue,
-CPU-bound processing, I/O-bound processing, mixed processing, and long-running
-stability. Every measurement runs in a fresh Ruby process; client order
-alternates and the default report uses the median of six repetitions.
-
-The current homogeneous CPU-processing reference uses Ruby 4.0.1,
-Sidekiq 8.1.7, a 210,000-iteration integer workload, and 1,000 jobs per case:
-
-| Concurrency | Sidekiq jobs/s | SolidJobs jobs/s | SolidJobs scaling | Sidekiq CPU-s/1k | SolidJobs CPU-s/1k | Sidekiq RSS | SolidJobs RSS | Sidekiq alloc/job | SolidJobs alloc/job |
-|---:|---:|---:|---:|---:|---:|---:|---:|---:|---:|
-| 1 | 142 | 138 | 100.0% | 6.95 | 7.11 | 41.5 MiB | 72.0 MiB | 129.8 | 89.9 |
-| 2 | 144 | 272 | 98.7% | 6.94 | 7.16 | 41.8 MiB | 77.6 MiB | 117.5 | 81.3 |
-| 4 | 143 | 539 | 97.8% | 6.99 | 7.18 | 41.9 MiB | 71.4 MiB | 111.9 | 77.2 |
-| 8 | 144 | 957 | 86.7% | 6.94 | 8.01 | 42.2 MiB | 69.5 MiB | 108.7 | 75.4 |
-
-At eight concurrency units, SolidJobs reaches 957 jobs/s versus 144 jobs/s
-for one Sidekiq process. This is Ractor parallelism rather than equal CPU
-efficiency: SolidJobs consumes 766% CPU and 8.01 CPU-seconds per 1,000 jobs,
-while Sidekiq consumes 100% CPU and 6.94 CPU-seconds per 1,000 jobs. SolidJobs
-also uses more RSS, but reaches 13.77 jobs/s/MiB versus 3.41 for Sidekiq.
-
-These are local synthetic measurements, not application-capacity claims.
-Queue p95/p99 values in this run use sparse sampling and are excluded from the
-summary until the final latency campaign increases the sample count. Ruby
-3.4.4 eight-Ractor results are also excluded: Ruby 3.4's Ractor scheduler
-crashed (concurrent TCP/RESP initialization, reproduced on macOS arm64 and
-Linux x86_64) or deadlocked VM-wide on a GC barrier under cross-Ractor
-message traffic (`test/support/ractor_barrier_repro.rb` reproduces it without
-SolidJobs).
-Ruby 4.0.1 passed the equivalent reproducers, and `StartupBarrier` serializes
-component initialization before releasing normal parallel processing.
-**Multi-Ractor servers are recommended on Ruby ≥ 4.0**; see
-`docs/reliability.md`.
-
-The project is under active development. The Web UI and commercial Sidekiq
-features are not part of the initial scope.
+## Migrating from Sidekiq
+
+There is no transparent migration path because compatibility is intentionally
+absent:
+
+1. Replace `include Sidekiq::Job` with `include SolidJobs::Task`.
+2. Replace `sidekiq_options` with `task_options`.
+3. Replace `perform_async`, `perform_in`, and `perform_bulk` with `enqueue`,
+   `enqueue_after`, and `enqueue_many`.
+4. Replace middleware with SolidJobs interceptors.
+5. Drain or export existing Sidekiq queues before switching. SolidJobs will not
+   consume them.
+6. Start SolidJobs with `--channel`; `--queue` is not accepted.
+
+The Active Job adapter remains available as
+`ActiveJob::QueueAdapters::SolidJobsAdapter`, but it writes only SolidJobs
+envelopes and keys.

data/docs/reliability.md

@@ -1,63 +1,61 @@
 # Reliability model
 
-SolidJobs uses a Redis-backed at-least-once state machine:
+SolidJobs uses a namespaced Redis-backed at-least-once state machine:
 
 ```text
 READY
   |
-  | BLMOVE reservation
+  | atomic claim
   v
-IN_PROGRESS ---- ACK/LREM ----> removed
+CLAIMED ---- fenced completion ----> removed
   |
-  +---- application error ----> RETRY or DEAD, then ACK
+  +---- application error ----> RETRYING or DISCARDED, then completion
   +---- graceful timeout -----> READY
-  +---- process crash --------> reservation retained
+  +---- node crash -----------> claim retained
                                   |
                                   +---- recovery ----> READY
 ```
 
-The reservation list is named `<process-identity>:reserved:<processor-id>`.
-Each execution receives a distinct reservation journal entry:
+Ready tasks live in `solid_jobs:channel:<name>`. Each executor owns at most one
+claimed-task list and one claim journal entry:
 
 ```text
-job_id          stable across replay
-reservation_id  unique per execution attempt
-process_id      owning process identity
-worker_id       owning Processor Ractor
-attempt         monotonically increasing execution count
-reserved_at     wall-clock reservation time
+task_id      stable across replay
+claim_token  unique per execution attempt
+node_id      owning server identity
+executor_id  owning Executor Ractor
+channel      destination used by recovery
+attempt      monotonically increasing execution count
+claimed_at   wall-clock claim time
 ```
 
-ACK and requeue are fenced by `reservation_id`. Their Lua scripts first
-verify that the worker still owns the current journal generation. A delayed
-or revived worker cannot remove or requeue a newer reservation, even when a
-supervisor reuses the same processor slot.
+Completion and requeue are fenced by `claim_token`. Their Lua scripts verify
+that the executor still owns the current journal generation before changing
+state. A delayed or revived executor cannot complete or requeue a newer claim.
 
-The payload retains its canonical `queue` field, allowing another process to
-restore it after the owner is no longer alive. Recovery uses process liveness
-and heartbeat, never reservation age alone, so a legitimate long-running job
-is not stolen while its owner remains alive.
+The envelope retains its canonical `channel`, allowing another node to restore
+it after its owner dies. Recovery uses node liveness and heartbeat, never claim
+age alone, so a legitimate long-running task is not stolen.
 
 ## Failure boundaries
 
-- Before reservation: the job remains in `queue:<name>`.
-- After reservation or during `perform`: the job remains reserved.
-- After the application effect but before ACK: recovery replays the job.
-- Redis unavailable during ACK: the job remains reserved and is replayed.
-- Graceful shutdown: the active job may finish within the configured timeout;
+- Before claim: the task remains in `solid_jobs:channel:<name>`.
+- After claim or during `perform`: the task remains claimed.
+- After the application effect but before completion: recovery replays it.
+- Redis unavailable during completion: the task remains claimed and is replayed.
+- Graceful shutdown: the active task may finish within the configured timeout;
   otherwise it is interrupted and requeued.
-- `SIGKILL`: no handler runs; recovery relies exclusively on Redis state.
+- `SIGKILL`: recovery relies exclusively on Redis state.
 
-This design intentionally favors no job loss over duplicate suppression.
-Exactly-once side effects require application-level idempotency.
+This design favors no task loss over duplicate suppression. Exactly-once side
+effects require application-level idempotency.
 
 ## Startup isolation
 
-The server does not reserve work while components are booting. Heartbeat,
-Processor, and Scheduler Ractors initialize their local configuration and
-Redis pool, report `READY` exactly once, and wait behind
-`SolidJobs::StartupBarrier`. Processing starts only after every component is
-ready:
+The server does not claim work while components are booting. Heartbeat,
+Processor, and Timer Ractors initialize their local configuration and Redis
+pool, report `READY` exactly once, and wait behind
+`SolidJobs::StartupBarrier`:
 
 ```text
 BOOTING -> ALL_READY -> RUNNING
@@ -65,85 +63,69 @@ BOOTING -> ALL_READY -> RUNNING
 ```
 
 Boot failure is terminal. Already-ready components receive `:abort`, close
-their local resources, and never enter their fetch loops. Cleanup is
-idempotent. Component startup is serialized, avoiding concurrent TCP/RESP
-initialization paths known to crash Ruby 3.4 (reproduced on 3.4.4 macOS arm64
-and 3.4.11 Linux x86_64; `rake startup_torture` is the reproducer); normal
-processing remains parallel after `RUNNING`.
-
-### Ruby 3.4 Ractor caveat
-
-Ruby 3.4's Ractor scheduler can deadlock the whole VM (main thread included)
-when a GC-triggered `rb_ractor_sched_barrier_start` runs while several
-Ractors exchange `move: true` messages: every thread parks in
-`ractor_sched_barrier_join_wait_locked` and the barrier never completes.
-`test/support/ractor_barrier_repro.rb` reproduces it **without SolidJobs or
-Redis** (one receiver, four senders, 24k moved messages per iteration):
-Ruby 3.4.4 freezes within the first iterations, Ruby 4.0.1 completes 30/30.
-Inside SolidJobs the same traffic pattern is the Processor → Heartbeat
-`:work`/`:done`/`:stats` channel, so any multi-Processor server on Ruby 3.4
-is exposed; once frozen, neither `Timeout` nor process exit
-(`rb_ractor_terminate_all`) can recover.
-
-Recommendation: **run multi-Ractor SolidJobs servers on Ruby ≥ 4.0**. On
-Ruby 3.4 use the client/API side freely, and prefer one process per
-Processor (`concurrency: 1`) for the server. Server-based stress tests are
-skipped on Ruby < 4 for this reason, and `Server#start` logs a warning when
-it detects `concurrency > 1` on Ruby < 4.
-
-### Bounded shutdown
+their local resources, and never enter their claim loops. Cleanup is
+idempotent.
+
+## Ruby 3.4 Ractor caveat
+
+Ruby 3.4's Ractor scheduler can deadlock the VM when a GC-triggered scheduler
+barrier runs while several Ractors exchange moved messages.
+`test/support/ractor_barrier_repro.rb` reproduces this without SolidJobs or
+Redis. Ruby 4.0.1 completes the equivalent reproducer.
+
+Run multi-Ractor SolidJobs servers on Ruby >= 4.0. On Ruby 3.4, prefer one
+process per Processor (`concurrency: 1`). Server stress tests are skipped on
+Ruby versions affected by this runtime issue, and `Server#start` warns when it
+detects a multi-Ractor configuration there.
+
+## Bounded shutdown
 
 `Server#stop` never waits forever for a component. Each Ractor gets
-`shutdown_timeout + Server::STOP_GRACE` to return after `:stop`; the signal
-is re-sent up to `STOP_RESENDS` times, then the component is abandoned with
-an error log so the process can proceed with shutdown.
+`shutdown_timeout + Server::STOP_GRACE` to return after `:stop`; the signal is
+re-sent up to `STOP_RESENDS` times before the component is abandoned with an
+error log.
 
 ## Configuration scope
 
 `SolidJobs.config` and the testing mode are Ractor-local, not thread-local.
-Every thread and fiber inside a Ractor (for example Puma workers or Rails
-request threads) shares the configuration set on that Ractor, while each
-Ractor keeps its own isolated configuration.
+Every thread and fiber inside a Ractor shares its configuration, while each
+Ractor owns isolated mutable state and Redis connections.
 
 ## Integrity auditing
 
-Fault and chaos tests can reconcile a known set of job IDs against every
-Redis-backed state:
+Fault tests can reconcile known task IDs against every Redis-backed state:
 
 ```ruby
 report = SolidJobs::IntegrityCheck.call(
-  expected_job_ids: submitted_job_ids,
+  expected_job_ids: submitted_task_ids,
   acked_key: "test:completed",
 )
 
 raise report.inspect unless report.ok?
 ```
 
-The report separates lost jobs, unexpected/orphaned jobs, inconsistent
-reservation journals, dangling attempt indexes, duplicate active states, and
-malformed payloads. ACK removes the completed job's attempt index atomically;
-requeue retains it so a recovered reservation increments the same attempt
-sequence.
+The report separates lost tasks, unexpected tasks, inconsistent claim
+journals, dangling attempt indexes, duplicate active states, and malformed
+envelopes. Completion removes the task's attempt index atomically; requeue
+retains it so recovery increments the same attempt sequence.
 
-## Backpressure and queues
+## Backpressure and channels
 
-Each Processor owns at most one reservation and reserves only immediately
-before execution. A process with concurrency `N` therefore holds at most `N`
-active reservations, regardless of Redis queue depth.
+Each Processor owns at most one claim and claims only immediately before
+execution. A node with concurrency `N` therefore holds at most `N` active
+claims, regardless of channel depth.
 
-Queue mode defaults to `:weighted`:
+Channel order defaults to `:weighted`:
 
-- `:weighted` uses bounded weighted round-robin and does not starve configured
-  queues;
-- `:strict` always checks queues in declaration order and may intentionally
-  starve lower-priority queues while a higher-priority queue remains busy;
-- `:random` samples the configured weighted queue list on each reservation.
+- `:weighted` uses bounded weighted round-robin;
+- `:priority` checks channels in declaration order;
+- `:shuffle` samples the configured weighted channel list.
 
-Paused queues are excluded before reservation.
+Paused channels are excluded before claiming.
 
 ## Retry storms
 
-Retries use capped exponential backoff with equal jitter. For attempt `n`, the
-ceiling is `min(retry_base_delay * 2**n, retry_max_delay)` and the actual delay
+Retries use capped exponential backoff with equal jitter. For failure `n`, the
+ceiling is `min(retry_base_delay * 2**(n - 1), retry_max_delay)` and the delay
 is distributed between half and all of that ceiling. Defaults are 15 seconds
-and one hour. This spreads recovery traffic after a shared external outage.
+and one hour.

data/lib/active_job/queue_adapters/solid_jobs_adapter.rb

@@ -27,16 +27,15 @@ module ActiveJob
       private
 
       def push(job, at: nil)
-        payload = {
-          "class" => SolidJobs::ActiveJob::Wrapper,
+        envelope = {
+          "task" => SolidJobs::ActiveJob::Wrapper,
           "wrapped" => job.class.name,
-          "queue" => job.queue_name,
-          "args" => [job.serialize],
+          "channel" => job.queue_name,
+          "arguments" => [job.serialize],
         }
-        payload["at"] = at if at
-        SolidJobs::Client.push(payload)
+        envelope["run_at"] = at if at
+        SolidJobs::Publisher.publish(envelope)
       end
     end
   end
 end
-

data/lib/solid_jobs/active_job.rb

@@ -3,14 +3,11 @@
 module SolidJobs
   module ActiveJob
     class Wrapper
-      include SolidJobs::Job
-      solid_jobs_options retry: true
+      include SolidJobs::Task
 
       def perform(job_data)
-        ::ActiveJob::Base.execute(job_data.merge("provider_job_id" => jid))
+        ::ActiveJob::Base.execute(job_data.merge("provider_job_id" => task_id))
       end
     end
-    JobWrapper = Wrapper
   end
 end
-