perf!(redis): use sorted set index for O(log N) schedule claiming (#14)

* perf(redis): use sorted set index for O(log N) schedule claiming

* fix(redis): auto-backfill due index on first schedule claim

Existing users upgrading will have schedules in the legacy format
(hashes + SET) but not in the new ZSET. Run backfillDueIndex() once
per worker process on the first claimDueSchedule() call so schedules
keep firing without manual intervention.

* perf(redis): update claim schedule script to use sorted set index

* feat(adapter): add migrate() to interface, validate hash in claim script

Replace auto-backfill with an explicit migrate() lifecycle method on the
Adapter interface. Remove #ensureDueIndex() and #dueIndexReady from
RedisAdapter — users call migrate() once after upgrading to populate the
schedules::due ZSET from pre-existing data.

The Lua claim script now validates the hash's next_run_at before claiming,
repairing stale ZSET scores on sight. This keeps the hash canonical and
the ZSET as a derived index.

* fix(redis): harden due schedule index migration

Keep paused and exhausted schedules out of the derived due index, rebuild it idempotently during migration, and restore the Adapter contract after merging current main.

Document the breaking Redis migration and cover schedule lifecycle consistency across adapters.

* chore: remove released changelog entries

* docs: add Redis schedule index changelog

* fix(redis): make schedule index updates atomic

Move schedule upserts, updates, and due-index backfills into Lua so canonical hashes and the derived ZSET cannot diverge under concurrent writes.

Add regression coverage for resume, upsert, and migration interleavings.

* fix(redis): guard cron claim finalization

Finalize cron schedules only when the claimed canonical state is still current, preventing concurrent pause or delete operations from being undone.

Repair malformed due scores during claiming so they cannot block valid schedules.

* fix(redis): reject superseded cron finalization

* style(redis): clarify claim script nesting

* docs: note Redis schedule race safeguards

* fix(redis): preserve schedules across concurrent updates

* fix(redis): guard cron claim ownership

* fix(redis): preserve cron next run during concurrent pause

---------

Co-authored-by: Romain Lanz <romain.lanz@pm.me>

Author: isimisi

.changelog/adapter-aware-workers-and-schedules.md

@@ -0,0 +1,35 @@
+# Indexed Redis Schedule Claims
+
+## Performance Improvement
+
+The Redis adapter now maintains a `schedules::due` sorted-set index scored by each schedule's
+`next_run_at`. Claiming the next due schedule uses this index instead of scanning every stored
+schedule, so polling no longer grows linearly with the total schedule count.
+
+Schedule hashes remain the source of truth. Creating, updating, pausing, resuming, deleting, and
+claiming schedules maintain the derived index, while claiming repairs stale entries when the hash
+and index disagree.
+
+Schedule hash and index writes are atomic, and index consistency is preserved across concurrent
+lifecycle changes. Cron finalization now rejects stale calculations when a schedule is deleted or
+reconfigured while its next run is being calculated. Paused schedules retain their next run but stay
+out of the due index until resumed. Claiming also discards malformed due scores instead of allowing
+one corrupt entry to block later schedules.
+
+## Upgrade Notes
+
+This change requires an explicit migration for existing Redis schedules. The `Adapter` contract now
+includes an idempotent `migrate()` method; built-in adapters without migrations implement it as a
+no-op, and custom adapters must implement it as well.
+
+Run the migration once during deployment, before starting workers or any process that creates or
+updates schedules:
+
+```typescript
+await QueueManager.init(config)
+await QueueManager.use('redis').migrate()
+```
+
+Existing Redis schedules will not fire through the new index until the migration has completed.
+The migration scans all schedules and should remain an explicit deployment step rather than run in
+the worker polling loop.

.changelog/consistent-job-runtime.md

@@ -334,6 +334,26 @@ const connection = new Redis({ host: 'localhost' })
 const adapter = redis(connection)
 ```
 
+#### Migrating Redis schedules after an upgrade
+
+The Redis adapter uses a `schedules::due` sorted-set index to find due schedules. When upgrading
+from a version that predates this index, run the adapter migration once during deployment, before
+starting any workers:
+
+```typescript
+import { QueueManager, Worker } from '@boringnode/queue'
+
+await QueueManager.init(config)
+await QueueManager.use('redis').migrate()
+
+const worker = new Worker(config)
+await worker.start(['default'])
+```
+
+The migration is idempotent and rebuilds the derived index from the canonical schedule hashes.
+Existing Redis schedules will not fire through the new index until it has run. Do not run the
+`O(number of schedules)` migration from the worker polling loop.
+
 ### Knex (PostgreSQL, MySQL, SQLite)
 
 ```typescript

.changelog/hot-reloading-jobs.md

@@ -223,6 +223,16 @@ export interface Adapter {
    */
   destroy(): Promise<void>
 
+  /**
+   * Run adapter-specific migrations needed after a major version upgrade.
+   *
+   * This method is idempotent — it is always safe to call multiple times.
+   * Adapters that have no pending migrations return immediately.
+   *
+   * Call this once during your deployment process before starting workers.
+   */
+  migrate(): Promise<void>
+
   /**
    * Create or update a schedule.
    *

.changelog/redis-schedule-due-index.md

@@ -404,6 +404,10 @@ export class FakeAdapter implements Adapter {
     return Promise.resolve()
   }
 
+  migrate(): Promise<void> {
+    return Promise.resolve()
+  }
+
   async upsertSchedule(config: ScheduleConfig): Promise<string> {
     const id = config.id ?? randomUUID()
     const existing = this.#schedules.get(id)

README.md

@@ -88,6 +88,8 @@ export class KnexAdapter implements Adapter {
     }
   }
 
+  async migrate(): Promise<void> {}
+
   async pop(): Promise<AcquiredJob | null> {
     return this.popFrom('default')
   }

src/contracts/adapter.ts

@@ -122,6 +122,8 @@ export class KyselyAdapter<DB = QueueDatabase> implements Adapter {
     // The Kysely instance is always owned by the application.
   }
 
+  async migrate(): Promise<void> {}
+
   async pop(): Promise<AcquiredJob | null> {
     return this.popFrom('default')
   }