nexus-ai-pro 2.0.0 → 2.2.0

package/dist/graph/index.js

@@ -2,5 +2,7 @@ export { CompiledGraph, StateGraph, createGraph } from './graph.js';
 export { migrateCheckpoint, toCheckpoint, } from './checkpoint-migration.js';
 export { appendList, appendSet, counter, lastValue, mergeObject, reducerChannel, } from './channels.js';
 export { MemoryGraphCheckpointer, OperationStoreCheckpointer, } from './checkpointer.js';
-export { GraphError, GraphInterrupt, GraphNodeError, GraphNodeTimeoutError, GraphNotInterruptedError, GraphStepLimitError, GraphThreadNotFoundError, GraphValidationError, interruptKey, } from './errors.js';
+export { GraphDrainedError, GraphError, GraphInterrupt, GraphNodeError, GraphNodeTimeoutError, GraphNotInterruptedError, GraphStepLimitError, GraphThreadNotFoundError, GraphValidationError, interruptKey, } from './errors.js';
+export { RunControl } from './run-control.js';
+export { GraphEventStream, GraphStreamOverflowError } from './event-stream.js';
 export { Command, END, Send, START } from '../types/graph.js';

package/dist/graph/lint.d.ts

@@ -0,0 +1,57 @@
+import type { GraphDescription } from '../types/graph.js';
+/** How much a lint finding matters: `error` fails `nexus graph lint`, the others only report. */
+export type GraphLintSeverity = 'error' | 'warning' | 'info';
+/** The rules `lintGraph()` checks. */
+export type GraphLintCode = 'UNBOUNDED_CYCLE' | 'RETRY_WITHOUT_IDEMPOTENCY' | 'RETRY_WITHOUT_TIMEOUT' | 'DEFERRED_DURABILITY_WITH_SIDE_EFFECTS' | 'MEMORY_CHECKPOINTER' | 'NO_CHECKPOINTER' | 'UNBOUNDED_CONCURRENCY' | 'DYNAMIC_ROUTE';
+/** One design problem `lintGraph()` found. */
+export interface GraphLintFinding {
+    /** Which rule found it. */
+    code: GraphLintCode;
+    /** How much it matters. */
+    severity: GraphLintSeverity;
+    /** The node it is about, as a path through subgraphs such as `review/approve`. Absent for the graph itself. */
+    node?: string;
+    /** What is wrong. */
+    message: string;
+    /** What to do about it. */
+    fix: string;
+}
+/** Options for `lintGraph()`. */
+export interface GraphLintOptions {
+    /**
+     * The graph runs where a restart, a second replica, or a hand-off is normal: under the agent
+     * server, a job queue, or more than one process. An in-process checkpointer is then an error, not
+     * a note.
+     */
+    deployed?: boolean;
+    /** Rules to skip, by code. */
+    ignore?: GraphLintCode[];
+}
+/**
+ * Finds designs that work in a demo and fail in production, by reading a compiled graph's shape.
+ *
+ * It needs no run and calls no node: it reads `describe()`, so it also works on a description saved
+ * as JSON. The checks:
+ *
+ * | Code | Severity | Finds |
+ * | --- | --- | --- |
+ * | `UNBOUNDED_CYCLE` | error | A cycle of static edges, which only the step limit can stop |
+ * | `RETRY_WITHOUT_IDEMPOTENCY` | warning | A retried node not declared `idempotent`, whose side effects can repeat |
+ * | `RETRY_WITHOUT_TIMEOUT` | warning | A retried node with no timeout, whose hung attempt is never retried |
+ * | `DEFERRED_DURABILITY_WITH_SIDE_EFFECTS` | warning | `async` or `exit` durability with nodes not declared `idempotent` |
+ * | `MEMORY_CHECKPOINTER` | warning, or error when `deployed` | The in-process default, which a restart loses |
+ * | `NO_CHECKPOINTER` | info | No checkpoints, so no interrupt, resume, or recovery |
+ * | `UNBOUNDED_CONCURRENCY` | warning | A fan-out with no limit on tasks at once |
+ * | `DYNAMIC_ROUTE` | info | A router with no mapping or `ends`, so routes cannot be checked |
+ *
+ * @example
+ * ```ts
+ * import { lintGraph } from 'nexus-ai-pro/graph/lint';
+ *
+ * const findings = lintGraph(graph, { deployed: true });
+ * for (const finding of findings) console.log(finding.severity, finding.code, finding.message);
+ * ```
+ */
+export declare function lintGraph(graph: {
+    describe(): GraphDescription;
+} | GraphDescription, options?: GraphLintOptions): GraphLintFinding[];

package/dist/graph/lint.js

@@ -0,0 +1,141 @@
+export function lintGraph(graph, options = {}) {
+    const description = 'describe' in graph && typeof graph.describe === 'function' ? graph.describe() : graph;
+    const findings = [];
+    lintDescription(description, '', options, findings, true);
+    const ignored = new Set(options.ignore ?? []);
+    return findings.filter((finding) => !ignored.has(finding.code));
+}
+function lintDescription(description, prefix, options, findings, top) {
+    const at = (node) => `${prefix}${node}`;
+    for (const cycle of staticCycles(description)) {
+        findings.push({
+            code: 'UNBOUNDED_CYCLE',
+            severity: 'error',
+            node: at(cycle[0]),
+            message: `${cycle.map((node) => `"${at(node)}"`).join(' → ')} loop through static edges only, so the run can only stop at the step limit.`,
+            fix: 'Route out of the loop with a conditional edge, a Command with declared ends, or an edge to END.',
+        });
+    }
+    const sideEffecting = [];
+    for (const node of description.nodes) {
+        if (!node.idempotent)
+            sideEffecting.push(node.id);
+        if (node.retry && !node.idempotent) {
+            findings.push({
+                code: 'RETRY_WITHOUT_IDEMPOTENCY',
+                severity: 'warning',
+                node: at(node.id),
+                message: `"${at(node.id)}" is retried up to ${node.maxAttempts ?? 'several'} times but is not declared idempotent, so a side effect can happen more than once.`,
+                fix: 'Give its side effects an idempotency key and declare `idempotent: true`, or stop retrying it.',
+            });
+        }
+        const timed = node.timeoutMs !== undefined || node.timeout?.runMs !== undefined || node.timeout?.idleMs !== undefined;
+        if (node.retry && !timed) {
+            findings.push({
+                code: 'RETRY_WITHOUT_TIMEOUT',
+                severity: 'warning',
+                node: at(node.id),
+                message: `"${at(node.id)}" is retried but has no timeout, so an attempt that hangs is never retried.`,
+                fix: 'Set `timeout: { runMs }`, or `idleMs` with `context.heartbeat()` for long work.',
+            });
+        }
+        if (node.subgraph)
+            lintDescription(node.subgraph, `${at(node.id)}/`, options, findings, false);
+    }
+    if (!top)
+        return;
+    if ((description.durability === 'async' || description.durability === 'exit') && sideEffecting.length > 0) {
+        findings.push({
+            code: 'DEFERRED_DURABILITY_WITH_SIDE_EFFECTS',
+            severity: 'warning',
+            message: `Durability is "${description.durability}", so a crash can repeat supersteps, and ${sideEffecting.map((node) => `"${node}"`).join(', ')} ${sideEffecting.length === 1 ? 'is' : 'are'} not declared idempotent.`,
+            fix: 'Use `sync` durability for graphs with side effects, or make those nodes idempotent and declare it.',
+        });
+    }
+    if (description.checkpointer === 'memory') {
+        findings.push({
+            code: 'MEMORY_CHECKPOINTER',
+            severity: options.deployed ? 'error' : 'warning',
+            message: 'Checkpoints go to the in-process default, so a restart loses every thread, and another process cannot resume one.',
+            fix: 'Pass a persistent checkpointer, such as an OperationStoreCheckpointer over Postgres, SQLite, or Redis.',
+        });
+    }
+    if (description.checkpointer === 'none') {
+        findings.push({
+            code: 'NO_CHECKPOINTER',
+            severity: 'info',
+            message: 'The graph writes no checkpoints, so it cannot interrupt, resume, drain, or recover after a crash.',
+            fix: 'Pass a checkpointer if any of those is needed.',
+        });
+    }
+    if (description.maxConcurrency !== undefined && !Number.isFinite(description.maxConcurrency)) {
+        findings.push({
+            code: 'UNBOUNDED_CONCURRENCY',
+            severity: 'warning',
+            message: 'Tasks in a superstep run with no limit, so a large Send fan-out starts all of them at once.',
+            fix: 'Set `maxConcurrency` to what the services behind the nodes can take.',
+        });
+    }
+    for (const node of description.dynamic) {
+        findings.push({
+            code: 'DYNAMIC_ROUTE',
+            severity: 'info',
+            node: at(node),
+            message: `The router after "${at(node)}" has no mapping and the node declares no ends, so its routes cannot be checked or drawn.`,
+            fix: "Give the conditional edge a mapping, or declare the node's `ends`.",
+        });
+    }
+}
+function staticCycles(description) {
+    const deciding = new Set(description.dynamic);
+    for (const node of description.nodes)
+        if (node.ends?.length)
+            deciding.add(node.id);
+    for (const edge of description.edges)
+        if (edge.conditional)
+            deciding.add(edge.from);
+    const next = new Map();
+    for (const edge of description.edges) {
+        if (edge.conditional || deciding.has(edge.from))
+            continue;
+        next.set(edge.from, [...(next.get(edge.from) ?? []), edge.to]);
+    }
+    const cycles = [];
+    const index = new Map();
+    const low = new Map();
+    const stack = [];
+    const onStack = new Set();
+    let counter = 0;
+    const visit = (node) => {
+        index.set(node, counter);
+        low.set(node, counter);
+        counter += 1;
+        stack.push(node);
+        onStack.add(node);
+        for (const to of next.get(node) ?? []) {
+            if (!index.has(to)) {
+                visit(to);
+                low.set(node, Math.min(low.get(node), low.get(to)));
+            }
+            else if (onStack.has(to)) {
+                low.set(node, Math.min(low.get(node), index.get(to)));
+            }
+        }
+        if (low.get(node) !== index.get(node))
+            return;
+        const component = [];
+        let member;
+        do {
+            member = stack.pop();
+            onStack.delete(member);
+            component.push(member);
+        } while (member !== node);
+        const selfLoop = component.length === 1 && (next.get(node) ?? []).includes(node);
+        if (component.length > 1 || selfLoop)
+            cycles.push(component.reverse());
+    };
+    for (const node of description.nodes)
+        if (!index.has(node.id))
+            visit(node.id);
+    return cycles;
+}

package/dist/graph/run-control.d.ts

@@ -0,0 +1,28 @@
+import type { RunControlLike } from '../types/graph.js';
+/**
+ * Stops graph runs cleanly: each finishes its current superstep, writes its checkpoint, and ends with
+ * `GraphDrainedError`, so another worker can `continue()` it.
+ *
+ * An abort signal stops a run in the middle of a superstep, cancelling the nodes in flight. A drain
+ * waits for them, which is what a rolling deploy, a spot eviction, or a scale-down wants: nothing
+ * half done, nothing lost. One control can drain any number of runs at once.
+ *
+ * @example
+ * ```ts
+ * const control = new RunControl();
+ * process.on('SIGTERM', () => control.drain('sigterm'));
+ * await graph.invoke(input, { threadId, control });
+ * ```
+ */
+export declare class RunControl implements RunControlLike {
+    private requested;
+    private readonly listeners;
+    /** True once `drain()` was called. */
+    get draining(): boolean;
+    /** Why the drain was requested. */
+    get reason(): string | undefined;
+    /** Asks every run using this control to stop after its current superstep. A second call is ignored. */
+    drain(reason?: string): void;
+    /** Calls `listener` when a drain is requested. Returns a function that removes it. */
+    onDrain(listener: (reason?: string) => void): () => void;
+}

package/dist/graph/run-control.js

@@ -0,0 +1,26 @@
+export class RunControl {
+    requested;
+    listeners = new Set();
+    get draining() {
+        return this.requested !== undefined;
+    }
+    get reason() {
+        return this.requested?.reason;
+    }
+    drain(reason) {
+        if (this.requested)
+            return;
+        this.requested = { reason };
+        for (const listener of this.listeners) {
+            try {
+                listener(reason);
+            }
+            catch {
+            }
+        }
+    }
+    onDrain(listener) {
+        this.listeners.add(listener);
+        return () => this.listeners.delete(listener);
+    }
+}

package/dist/images/evals.js

@@ -1,4 +1,5 @@
 import { createHash } from 'node:crypto';
+import { linkSignals } from '../utils/signals.js';
 import { ImageValidationError } from './errors.js';
 export class MemoryReviewQueue {
     items = [];
@@ -32,7 +33,8 @@ export class MediaEvalRunner {
         const runsOf = new Map(examples.map((example, index) => [example.id, runCounts[index]]));
         const outcomes = new Map();
         const stop = new AbortController();
-        const signal = runOptions.signal ? AbortSignal.any([stop.signal, runOptions.signal]) : stop.signal;
+        const linked = linkSignals([stop.signal, runOptions.signal]);
+        const signal = linked.signal;
         const { evaluate } = await import('../evaluate/run.js');
         const experiment = await evaluate(async (evalCase, { example, run }) => {
             try {
@@ -57,7 +59,7 @@ export class MediaEvalRunner {
             signal,
             ...(runOptions.store ? { store: runOptions.store } : {}),
             ...(runOptions.metadata ? { metadata: runOptions.metadata } : {}),
-        });
+        }).finally(linked.dispose);
         const caseReports = [];
         const allScores = {};
         const safety = { truePositives: 0, falsePositives: 0, trueNegatives: 0, falseNegatives: 0 };

package/dist/operations/adapters.d.ts

@@ -3,7 +3,8 @@ import type { OperationDispatcher, OperationRecord, OperationStore, OperationSto
  * The Redis commands the operation store needs.
  *
  * Structural rather than tied to one client, so `ioredis`, `node-redis`, or a cluster proxy all
- * satisfy it without this package depending on any of them.
+ * satisfy it without this package depending on any of them. The sorted-set commands are needed only
+ * with `index: true`; `ioredis` has them all.
  */
 export interface RedisOperationLikeClient {
     /** Reads a hash field. */
@@ -16,6 +17,14 @@ export interface RedisOperationLikeClient {
     hvals(key: string): Promise<string[]> | string[];
     /** Optional CAS primitive. When absent the store falls back to a read-compare-write. */
     eval?(script: string, numKeys: number, ...args: string[]): Promise<unknown> | unknown;
+    /** Reads several hash fields in one round trip. Used by the index when present. */
+    hmget?(key: string, ...fields: string[]): Promise<Array<string | null>> | Array<string | null>;
+    /** Adds a sorted-set member. Needed with `index: true`. */
+    zadd?(key: string, score: number, member: string): Promise<unknown> | unknown;
+    /** Removes a sorted-set member. Needed with `index: true`. */
+    zrem?(key: string, member: string): Promise<unknown> | unknown;
+    /** Members by score, as `ZRANGEBYSCORE key min max LIMIT offset count`. Needed with `index: true`. */
+    zrangebyscore?(key: string, min: number | string, max: number | string, limit: 'LIMIT', offset: number, count: number): Promise<string[]> | string[];
 }
 /** Options for the Redis operation store. */
 export interface RedisOperationStoreOptions {
@@ -23,6 +32,19 @@ export interface RedisOperationStoreOptions {
     prefix?: string;
     /** Disables the Lua compare-and-set even when the client exposes `eval`. */
     useEval?: boolean;
+    /**
+     * Keeps queued work in a sorted set by age, and leased work in one by lease expiry, so
+     * `listQueued()` and `claimExpired()` read the oldest few records instead of every one: a claim
+     * costs the same with 100,000 operations queued as with 1,000. The records stay the source of
+     * truth; an index entry only says where to look, and one that no longer matches its record is
+     * skipped and removed.
+     *
+     * Off by default, because a 2.1 worker writes records without index entries. Turn it on once every
+     * worker sharing the prefix runs 2.2, then call `reindex()` once to index what is already there.
+     * Needs `zadd`, `zrem`, and `zrangebyscore`; with `eval`, a record and its index entries change in
+     * one step.
+     */
+    index?: boolean;
 }
 /**
  * Redis-backed operation storage, so a submitted operation survives a restart.
@@ -36,8 +58,13 @@ export declare class RedisOperationStore<TResult = unknown> implements Operation
     private readonly client;
     private readonly prefix;
     private readonly useEval;
+    private readonly indexed;
     constructor(client: RedisOperationLikeClient, options?: RedisOperationStoreOptions);
-    /** Stores a new record and indexes its idempotency key. Refuses records carrying raw bytes. */
+    /**
+     * Stores a new record and indexes its idempotency key. Throws `OperationDuplicateError` when another
+     * record holds the key, checked in the same Lua call as the write when the client has `eval`.
+     * Refuses records carrying raw bytes.
+     */
     create(record: OperationRecord<TResult>): Promise<void>;
     /** Reads a record. */
     read(id: string): Promise<OperationRecord<TResult> | undefined>;
@@ -50,19 +77,40 @@ export declare class RedisOperationStore<TResult = unknown> implements Operation
     delete(id: string): Promise<boolean>;
     /**
      * Records whose lease has expired, or running records without one, up to `limit`, for another
-     * worker to take over.
+     * worker to take over. With the index, reads only records whose lease has lapsed.
      */
     claimExpired(now: string, limit: number): Promise<Array<OperationRecord<TResult>>>;
     /** Finds the record that claimed an idempotency key. */
     findByIdempotencyKey(key: string): Promise<OperationRecord<TResult> | undefined>;
     /** Every record. */
     list(): Promise<Array<OperationRecord<TResult>>>;
-    /** Queued records no worker holds, oldest first. Reads every record, as `list()` does. */
+    /**
+     * Queued records no worker holds, oldest first. With the index, reads them oldest first from the
+     * sorted set and stops at `limit`; without it, reads every record, as `list()` does.
+     */
     listQueued(limit: number, filter?: OperationStoreFilter): Promise<Array<OperationRecord<TResult>>>;
     /** Counts unfinished records by status. Reads every record, as `list()` does. */
     stats(now: string, filter?: OperationStoreFilter): Promise<OperationStoreStats>;
+    /**
+     * Indexes every record already stored, for turning `index` on over existing data. Safe to run
+     * while workers are busy, and to run again: it only adds entries, then removes those that no
+     * longer match their record, checking each record as it does. Resolves to how many records it read.
+     */
+    reindex(): Promise<number>;
+    /**
+     * Reads one index in score order up to `max`, a page at a time, keeping records that pass `keep`
+     * until `limit`. Entries whose record is gone or no longer `belongs` are removed afterwards.
+     */
+    private scanIndex;
+    private readMany;
+    /** Removes index entries that no longer describe their record. Only with `eval`, where the check is atomic. */
+    private prune;
+    /** Writes a record's index entries without `eval`, after the record itself. */
+    private place;
     private recordsKey;
     private idempotencyKey;
+    private queuedKey;
+    private leasesKey;
 }
 /** The part of a BullMQ `Queue` the dispatcher needs. */
 export interface BullMQLikeOperationQueue {

package/dist/operations/adapters.js

@@ -1,4 +1,5 @@
-import { isTerminalOperationStatus } from '../types/operations.js';
+import { isTerminalOperationStatus, TERMINAL_OPERATION_STATUSES } from '../types/operations.js';
+import { OperationDuplicateError } from './errors.js';
 import { assertSerializableRecord } from './serialization.js';
 import { countRecords, isUnheldQueued, matchesFilter } from './stats.js';
 const CAS_SCRIPT = `
@@ -9,21 +10,102 @@ if tonumber(decoded.sequence) ~= tonumber(ARGV[2]) then return 0 end
 redis.call('HSET', KEYS[1], ARGV[1], ARGV[3])
 return 1
 `;
+const PLACE_LUA = `
+local function place(key, score, id)
+  if score ~= '' then redis.call('ZADD', key, score, id) else redis.call('ZREM', key, id) end
+end
+`;
+const UNIQUE_KEY_LUA = `
+if ARGV[3] ~= '' then
+  local owner = redis.call('HGET', KEYS[2], ARGV[3])
+  if owner and owner ~= ARGV[1] and redis.call('HEXISTS', KEYS[1], owner) == 1 then return 0 end
+end
+`;
+const CREATE_SCRIPT = `${UNIQUE_KEY_LUA}
+redis.call('HSET', KEYS[1], ARGV[1], ARGV[2])
+if ARGV[3] ~= '' then redis.call('HSET', KEYS[2], ARGV[3], ARGV[1]) end
+return 1
+`;
+const INDEXED_CREATE_SCRIPT = `${PLACE_LUA}${UNIQUE_KEY_LUA}
+redis.call('HSET', KEYS[1], ARGV[1], ARGV[2])
+if ARGV[3] ~= '' then redis.call('HSET', KEYS[2], ARGV[3], ARGV[1]) end
+place(KEYS[3], ARGV[4], ARGV[1])
+place(KEYS[4], ARGV[5], ARGV[1])
+return 1
+`;
+const INDEXED_CAS_SCRIPT = `${PLACE_LUA}
+local current = redis.call('HGET', KEYS[1], ARGV[1])
+if current == false then return 0 end
+local decoded = cjson.decode(current)
+if tonumber(decoded.sequence) ~= tonumber(ARGV[2]) then return 0 end
+redis.call('HSET', KEYS[1], ARGV[1], ARGV[3])
+place(KEYS[2], ARGV[4], ARGV[1])
+place(KEYS[3], ARGV[5], ARGV[1])
+return 1
+`;
+const PRUNE_SCRIPT = `
+local terminal = { ${TERMINAL_OPERATION_STATUSES.map((status) => `${status} = true`).join(', ')} }
+local removed = 0
+for i = 2, #ARGV do
+  local raw = redis.call('HGET', KEYS[1], ARGV[i])
+  local keep = false
+  if raw then
+    local record = cjson.decode(raw)
+    if ARGV[1] == 'queued' then
+      keep = record.status == 'queued'
+    else
+      keep = (not terminal[record.status]) and (record.lease ~= nil or record.status == 'running')
+    end
+  end
+  if not keep then
+    redis.call('ZREM', KEYS[2], ARGV[i])
+    removed = removed + 1
+  end
+end
+return removed
+`;
 export class RedisOperationStore {
     client;
     prefix;
     useEval;
+    indexed;
     constructor(client, options = {}) {
         this.client = client;
         this.prefix = options.prefix ?? 'nexus-ai-pro:operations:';
         this.useEval = options.useEval !== false && typeof client.eval === 'function';
+        this.indexed = options.index === true;
+        if (this.indexed && !(client.zadd && client.zrem && client.zrangebyscore)) {
+            throw new TypeError('A Redis operation store with index: true needs zadd, zrem, and zrangebyscore');
+        }
     }
     async create(record) {
         assertSerializableRecord(record);
-        await this.client.hset(this.recordsKey(), record.id, JSON.stringify(record));
+        const encoded = JSON.stringify(record);
+        const duplicate = () => new OperationDuplicateError(record.idempotencyKey);
+        if (this.useEval && this.client.eval && !this.indexed) {
+            const created = await this.client.eval(CREATE_SCRIPT, 2, this.recordsKey(), this.idempotencyKey(), record.id, encoded, record.idempotencyKey ?? '');
+            if (Number(created) !== 1)
+                throw duplicate();
+            return;
+        }
+        if (this.indexed && this.useEval && this.client.eval) {
+            const { queued, lease } = indexScores(record);
+            const created = await this.client.eval(INDEXED_CREATE_SCRIPT, 4, this.recordsKey(), this.idempotencyKey(), this.queuedKey(), this.leasesKey(), record.id, encoded, record.idempotencyKey ?? '', queued, lease);
+            if (Number(created) !== 1)
+                throw duplicate();
+            return;
+        }
+        if (record.idempotencyKey) {
+            const owner = await this.client.hget(this.idempotencyKey(), record.idempotencyKey);
+            if (owner && owner !== record.id && (await this.client.hget(this.recordsKey(), owner)))
+                throw duplicate();
+        }
+        await this.client.hset(this.recordsKey(), record.id, encoded);
         if (record.idempotencyKey) {
             await this.client.hset(this.idempotencyKey(), record.idempotencyKey, record.id);
         }
+        if (this.indexed)
+            await this.place(record);
     }
     async read(id) {
         const raw = await this.client.hget(this.recordsKey(), id);
@@ -33,6 +115,11 @@ export class RedisOperationStore {
         assertSerializableRecord(record);
         const encoded = JSON.stringify(record);
         if (this.useEval && this.client.eval) {
+            if (this.indexed) {
+                const { queued, lease } = indexScores(record);
+                const result = await this.client.eval(INDEXED_CAS_SCRIPT, 3, this.recordsKey(), this.queuedKey(), this.leasesKey(), record.id, String(expectedSequence), encoded, queued, lease);
+                return Number(result) === 1;
+            }
             const result = await this.client.eval(CAS_SCRIPT, 1, this.recordsKey(), record.id, String(expectedSequence), encoded);
             return Number(result) === 1;
         }
@@ -40,6 +127,8 @@ export class RedisOperationStore {
         if (!current || current.sequence !== expectedSequence)
             return false;
         await this.client.hset(this.recordsKey(), record.id, encoded);
+        if (this.indexed)
+            await this.place(record);
         return true;
     }
     async delete(id) {
@@ -47,19 +136,22 @@ export class RedisOperationStore {
         if (record?.idempotencyKey)
             await this.client.hdel(this.idempotencyKey(), record.idempotencyKey);
         await this.client.hdel(this.recordsKey(), id);
+        if (this.indexed) {
+            await this.client.zrem?.(this.queuedKey(), id);
+            await this.client.zrem?.(this.leasesKey(), id);
+        }
         return record !== undefined;
     }
     async claimExpired(now, limit) {
+        if (this.indexed) {
+            return this.scanIndex('leases', Date.parse(now), limit, (record) => isExpired(record, now), isLeased);
+        }
         const records = await this.list();
         const expired = [];
         for (const record of records) {
             if (expired.length >= limit)
                 break;
-            if (isTerminalOperationStatus(record.status))
-                continue;
-            if (record.lease && record.lease.expiresAt > now)
-                continue;
-            if (record.status === 'running' || record.lease)
+            if (isExpired(record, now))
                 expired.push(record);
         }
         return expired;
@@ -74,6 +166,9 @@ export class RedisOperationStore {
     }
     async listQueued(limit, filter) {
         const now = new Date().toISOString();
+        if (this.indexed) {
+            return this.scanIndex('queued', Number.POSITIVE_INFINITY, limit, (record) => isUnheldQueued(record, now) && matchesFilter(record, filter), (record) => record.status === 'queued');
+        }
         return (await this.list())
             .filter((record) => isUnheldQueued(record, now) && matchesFilter(record, filter))
             .sort((a, b) => (a.createdAt < b.createdAt ? -1 : a.createdAt > b.createdAt ? 1 : 0))
@@ -82,12 +177,104 @@ export class RedisOperationStore {
     async stats(now, filter) {
         return countRecords(await this.list(), now, filter);
     }
+    async reindex() {
+        if (!this.indexed)
+            throw new TypeError('reindex() needs a store created with index: true');
+        const records = await this.list();
+        for (const record of records) {
+            const { queued, lease } = indexScores(record);
+            if (queued !== '')
+                await this.client.zadd?.(this.queuedKey(), Number(queued), record.id);
+            if (lease !== '')
+                await this.client.zadd?.(this.leasesKey(), Number(lease), record.id);
+        }
+        await this.prune('queued', records.filter((record) => record.status !== 'queued').map((record) => record.id));
+        await this.prune('leases', records.filter((record) => !isLeased(record)).map((record) => record.id));
+        return records.length;
+    }
+    async scanIndex(index, max, limit, keep, belongs) {
+        const found = [];
+        if (limit <= 0)
+            return found;
+        const stale = [];
+        const key = index === 'queued' ? this.queuedKey() : this.leasesKey();
+        const upper = max === Number.POSITIVE_INFINITY ? '+inf' : max;
+        const page = Math.max(16, limit * 4);
+        for (let offset = 0; found.length < limit; offset += page) {
+            const ids = (await this.client.zrangebyscore?.(key, '-inf', upper, 'LIMIT', offset, page)) ?? [];
+            const records = await this.readMany(ids);
+            for (const [position, id] of ids.entries()) {
+                const record = records[position];
+                if (!record || !belongs(record)) {
+                    stale.push(id);
+                    continue;
+                }
+                if (keep(record))
+                    found.push(record);
+                if (found.length >= limit)
+                    break;
+            }
+            if (ids.length < page)
+                break;
+        }
+        await this.prune(index, stale);
+        return found;
+    }
+    async readMany(ids) {
+        if (ids.length === 0)
+            return [];
+        const raws = this.client.hmget
+            ? await this.client.hmget(this.recordsKey(), ...ids)
+            : await Promise.all(ids.map((id) => this.client.hget(this.recordsKey(), id)));
+        return raws.map((raw) => (raw ? JSON.parse(raw) : undefined));
+    }
+    async prune(index, ids) {
+        if (ids.length === 0 || !this.useEval || !this.client.eval)
+            return;
+        const key = index === 'queued' ? this.queuedKey() : this.leasesKey();
+        for (let start = 0; start < ids.length; start += 500) {
+            await this.client.eval(PRUNE_SCRIPT, 2, this.recordsKey(), key, index, ...ids.slice(start, start + 500));
+        }
+    }
+    async place(record) {
+        const { queued, lease } = indexScores(record);
+        if (queued !== '')
+            await this.client.zadd?.(this.queuedKey(), Number(queued), record.id);
+        else
+            await this.client.zrem?.(this.queuedKey(), record.id);
+        if (lease !== '')
+            await this.client.zadd?.(this.leasesKey(), Number(lease), record.id);
+        else
+            await this.client.zrem?.(this.leasesKey(), record.id);
+    }
     recordsKey() {
         return `${this.prefix}records`;
     }
     idempotencyKey() {
         return `${this.prefix}idempotency`;
     }
+    queuedKey() {
+        return `${this.prefix}queued`;
+    }
+    leasesKey() {
+        return `${this.prefix}leases`;
+    }
+}
+function isExpired(record, now) {
+    if (isTerminalOperationStatus(record.status))
+        return false;
+    if (record.lease && record.lease.expiresAt > now)
+        return false;
+    return record.status === 'running' || record.lease !== undefined;
+}
+function isLeased(record) {
+    return !isTerminalOperationStatus(record.status) && (record.lease !== undefined || record.status === 'running');
+}
+function indexScores(record) {
+    return {
+        queued: record.status === 'queued' ? String(Date.parse(record.createdAt)) : '',
+        lease: isLeased(record) ? String(record.lease ? Date.parse(record.lease.expiresAt) : 0) : '',
+    };
 }
 export class BullMQOperationDispatcher {
     queue;