cairnq 0.1.0 → 0.3.0

package/dist/wait.d.ts

@@ -1,8 +1,21 @@
 import { type Task } from "./models.js";
 import type { TaskStore } from "./store/base.js";
+export declare const DEFAULT_POLL_MS = 100;
+export declare const MAX_POLL_MS = 500;
+/**
+ * Grow the polling interval towards the ceiling.
+ *
+ * wait() has no idea whether the task takes 50ms or an hour. Starting tight keeps
+ * short tasks snappy; growing keeps a long wait from costing a read every 100ms
+ * for its whole duration. The +1 keeps truncation from pinning tiny intervals:
+ * Math.floor(1 * 1.5) === 1 would otherwise never grow past 1.
+ */
+export declare function nextPollMs(current: number, maxMs: number): number;
 /** Poll get() until terminal or timeout. Returns the terminal Task (any status).
- * Throws TaskTimeout, leaving the task running. */
-export declare function pollWait(store: TaskStore, taskId: string, { timeoutMs, pollMs }: {
+ * Throws TaskTimeout, leaving the task running. `pollMs` is the *first* interval;
+ * it backs off towards `maxPollMs`. */
+export declare function pollWait(store: TaskStore, taskId: string, { timeoutMs, pollMs, maxPollMs, }: {
     timeoutMs: number;
     pollMs?: number;
+    maxPollMs?: number;
 }): Promise<Task>;

package/dist/wait.js

@@ -1,18 +1,36 @@
 import { TaskTimeout } from "./errors.js";
 import { nowMs } from "./ids.js";
 import { isTerminal } from "./models.js";
-const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+export const DEFAULT_POLL_MS = 100;
+export const MAX_POLL_MS = 500;
+const GROWTH = 1.5;
+/**
+ * Grow the polling interval towards the ceiling.
+ *
+ * wait() has no idea whether the task takes 50ms or an hour. Starting tight keeps
+ * short tasks snappy; growing keeps a long wait from costing a read every 100ms
+ * for its whole duration. The +1 keeps truncation from pinning tiny intervals:
+ * Math.floor(1 * 1.5) === 1 would otherwise never grow past 1.
+ */
+export function nextPollMs(current, maxMs) {
+    return Math.min(maxMs, Math.max(current + 1, Math.floor(current * GROWTH)));
+}
 /** Poll get() until terminal or timeout. Returns the terminal Task (any status).
- * Throws TaskTimeout, leaving the task running. */
-export async function pollWait(store, taskId, { timeoutMs, pollMs = 150 }) {
+ * Throws TaskTimeout, leaving the task running. `pollMs` is the *first* interval;
+ * it backs off towards `maxPollMs`. */
+export async function pollWait(store, taskId, { timeoutMs, pollMs = DEFAULT_POLL_MS, maxPollMs = MAX_POLL_MS, }) {
     const deadline = nowMs() + timeoutMs;
+    let interval = pollMs;
     for (;;) {
         const task = await store.get(taskId);
         if (task && isTerminal(task))
             return task;
         const remaining = deadline - nowMs();
         if (remaining <= 0)
-            throw new TaskTimeout(taskId);
-        await sleep(Math.min(pollMs, remaining));
+            throw new TaskTimeout(taskId, { timeoutMs, task });
+        // A store with a push channel (Postgres) cuts the sleep short when the task
+        // goes terminal; the re-get above stays the source of truth either way.
+        await store.taskDoneWake(taskId, Math.min(interval, remaining));
+        interval = nextPollMs(interval, maxPollMs);
     }
 }

package/dist/worker.d.ts

@@ -4,13 +4,40 @@ import { type TaskDef } from "./task.js";
 export type Handler = (ctx: TaskContext, payload: any) => unknown | Promise<unknown>;
 /** Handler typed against a TaskDef<P, R>: payload is P, the return is R. */
 export type TypedHandler<P, R> = (ctx: TaskContext, payload: P) => R | Promise<R>;
+/** Where an error the worker recovered from came from. */
+export type ErrorPhase = "claim" | "execute";
 export interface WorkerOptions {
     concurrency?: number;
     leaseMs?: number;
     heartbeatIntervalMs?: number;
     pollIntervalMs?: number;
     claimBatch?: number;
+    /** Base delay before re-running a failed attempt; doubles per attempt. 0 disables. */
+    retryBackoffMs?: number;
+    /** Ceiling for the doubling. */
+    retryBackoffMaxMs?: number;
+    /**
+     * Wall-clock ceiling for one attempt. The heartbeat renews the lease for as
+     * long as a handler runs, so a hung handler would otherwise hold its task
+     * `running` (and its concurrency slot) forever — cancel can't help,
+     * cooperative checks need a live handler. On expiry the worker abandons the
+     * attempt (ctx.signal aborts, further ctx writes throw LostLease) and records
+     * a retryable `handler_timeout` failure. Unset disables the ceiling.
+     */
+    maxRunMs?: number;
+    /**
+     * Called for errors the worker survived — a claim that threw, a store write
+     * that failed while finalizing a task. Without it these are silent: the run
+     * loop carries on either way, so this is the only place an operator learns a
+     * worker is limping. Must not throw.
+     */
+    onError?: (err: unknown, info: {
+        phase: ErrorPhase;
+        taskId?: string;
+    }) => void;
 }
+/** Exponential backoff for the next attempt of a task that just failed. */
+export declare function retryDelayMs(attempt: number, baseMs: number, maxMs: number): number;
 export declare class Worker {
     private readonly store;
     private readonly queues;
@@ -18,7 +45,8 @@ export declare class Worker {
     private readonly handlers;
     private readonly workerId;
     private stopped;
-    private stopResolvers;
+    private stopWake;
+    private readonly stopped$;
     private ownsStore;
     constructor(store: TaskStore, queues: string[], opts?: WorkerOptions);
     static sqlite(path: string, opts?: WorkerOptions & {
@@ -39,9 +67,11 @@ export declare class Worker {
     /** Close the underlying store connection. Call after run() returns. */
     close(): Promise<void>;
     private closeIfOwned;
+    private report;
     run(opts?: {
         concurrency?: number;
     }): Promise<void>;
+    private loop;
     /** Blocking-style entry point for a standalone worker process: run until
      * SIGINT/SIGTERM, then close the store. Use this at a script's top level;
      * use run() / background() when you manage the event loop yourself. */
@@ -52,9 +82,31 @@ export declare class Worker {
     background<T>(fn: () => Promise<T>, opts?: {
         concurrency?: number;
     }): Promise<T>;
+    /**
+     * Run one task to completion. Never rejects: a task-level failure is reported
+     * through onError and the loop moves on. (It used to reject into a promise
+     * nobody awaited — an unhandled rejection that took the process down.)
+     */
     private execute;
+    /**
+     * Run one attempt, bounded by maxRunMs when set. On timeout the attempt is
+     * abandoned: the context is flagged lease-lost first (ctx.signal aborts, and
+     * a handler that keeps running can never write again — see
+     * TaskContext.owned), then the still-pending promise is left to settle on
+     * its own, its outcome discarded. The caller records the handler_timeout
+     * failure; lease recovery is NOT involved, so redelivery is immediate.
+     */
+    private attempt;
     private startHeartbeat;
     private safeFail;
+    /**
+     * The empty-poll sleep. A store with a push channel (Postgres LISTEN/NOTIFY)
+     * cuts it short when a task on this worker's queues becomes claimable;
+     * stop() interrupts it either way, and sleepOrStop bounds it at `ms` so the
+     * poll fallback — which also drives lease recovery — never stretches.
+     */
+    private idle;
     private sleepOrStop;
+    /** Take SIGINT/SIGTERM for the duration of serve(). Returns the undo. */
     private installSignals;
 }

package/dist/worker.js

@@ -1,9 +1,20 @@
 import { TaskContext } from "./context.js";
-import { errorEnvelope, LostLease, TaskError } from "./errors.js";
+import { errorEnvelope, LostLease, SerializationError, TaskError } from "./errors.js";
 import { newId } from "./ids.js";
 import { SQLiteStore } from "./store/sqlite.js";
 import { PostgresStore } from "./store/postgres.js";
 import { taskName } from "./task.js";
+const DEFAULT_RETRY_BACKOFF_MS = 1_000;
+const DEFAULT_RETRY_BACKOFF_MAX_MS = 30_000;
+/** Wait after a failed claim, so a broken database is not polled in a tight loop. */
+const CLAIM_ERROR_BACKOFF_MS = 250;
+/** Exponential backoff for the next attempt of a task that just failed. */
+export function retryDelayMs(attempt, baseMs, maxMs) {
+    if (baseMs <= 0)
+        return 0;
+    const exponent = Math.max(0, attempt - 1);
+    return Math.min(maxMs, baseMs * 2 ** exponent);
+}
 function exceptionEnvelope(err) {
     const e = err;
     return errorEnvelope({
@@ -13,6 +24,23 @@ function exceptionEnvelope(err) {
         retryable: true,
     });
 }
+/** Internal: an attempt outran maxRunMs and was abandoned. */
+class AttemptTimeout extends Error {
+    maxRunMs;
+    constructor(maxRunMs) {
+        super(`attempt exceeded ${maxRunMs}ms`);
+        this.maxRunMs = maxRunMs;
+    }
+}
+function timeoutEnvelope(name, maxRunMs) {
+    return errorEnvelope({
+        type: "HandlerTimeout",
+        code: "handler_timeout",
+        message: `handler for ${name} exceeded maxRunMs=${maxRunMs}ms; the attempt was abandoned`,
+        retryable: true,
+    });
+}
+const TIMED_OUT = Symbol("cairnq.timedOut");
 export class Worker {
     store;
     queues;
@@ -20,7 +48,10 @@ export class Worker {
     handlers = new Map();
     workerId = newId("worker");
     stopped = false;
-    stopResolvers = [];
+    stopWake;
+    // Resolved once by stop(); every sleep races against it. A stopped worker
+    // never restarts, so one promise serves the instance's lifetime.
+    stopped$ = new Promise((r) => (this.stopWake = r));
     // True only when this worker created its own store (via Worker.sqlite); an
     // injected store may be shared, so serve()/background() must not close it.
     ownsStore = false;
@@ -28,6 +59,9 @@ export class Worker {
         this.store = store;
         this.queues = queues;
         this.opts = opts;
+        if (opts.maxRunMs != null && opts.maxRunMs <= 0) {
+            throw new Error(`maxRunMs must be > 0, got ${opts.maxRunMs}`);
+        }
     }
     static sqlite(path, opts = {}) {
         const { queues = ["default"], busyTimeoutMs, ...rest } = opts;
@@ -51,8 +85,10 @@ export class Worker {
         let fn;
         if (typeof arg === "function") {
             // Bare form: worker.task(fn) — registered under the function's name.
+            // Strip the "bound " prefix .bind() stamps on it: otherwise a bound
+            // method registers under "bound process", a name no submit ever uses.
             fn = arg;
-            name = fn.name;
+            name = fn.name.replace(/^(bound )+/, "");
             if (!name) {
                 throw new Error("worker.task(fn): the handler is anonymous; pass a name explicitly, " +
                     "e.g. worker.task('summary.create', fn)");
@@ -68,10 +104,7 @@ export class Worker {
     }
     stop() {
         this.stopped = true;
-        const resolvers = this.stopResolvers;
-        this.stopResolvers = [];
-        for (const r of resolvers)
-            r();
+        this.stopWake();
     }
     /** Close the underlying store connection. Call after run() returns. */
     async close() {
@@ -84,28 +117,66 @@ export class Worker {
         if (this.ownsStore)
             await this.close();
     }
+    report(err, info) {
+        try {
+            this.opts.onError?.(err, info);
+        }
+        catch {
+            // A reporting hook must never take the worker down with it.
+        }
+    }
     async run(opts = {}) {
-        const concurrency = opts.concurrency ?? this.opts.concurrency ?? 1;
+        // Clamped: at 0 the loop would await Promise.race([]) — pending forever,
+        // beyond even stop()'s reach.
+        const concurrency = Math.max(1, opts.concurrency ?? this.opts.concurrency ?? 1);
         const leaseMs = this.opts.leaseMs ?? 30_000;
-        const pollMs = this.opts.pollIntervalMs ?? 500;
         const batch = this.opts.claimBatch ?? concurrency;
         await this.store.connect();
-        this.installSignals();
         const running = new Set();
+        try {
+            await this.loop(concurrency, batch, leaseMs, running);
+        }
+        finally {
+            // Whatever ends the loop — stop(), or something unexpected out of the body
+            // — nothing this worker started may outlive run(). serve() closes the store
+            // as soon as run() settles, and a handler still holding the connection
+            // would fault on it.
+            await Promise.all([...running]);
+        }
+    }
+    async loop(concurrency, batch, leaseMs, running) {
+        const pollMs = this.opts.pollIntervalMs ?? 500;
         while (!this.stopped) {
             const free = concurrency - running.size;
             if (free <= 0) {
-                await this.sleepOrStop(5);
+                // Wait for a slot rather than spinning. execute() never rejects, so
+                // racing these is safe.
+                await Promise.race([...running]);
+                continue;
+            }
+            let claimed;
+            try {
+                claimed = await this.store.claim({
+                    queues: this.queues,
+                    // Only what this worker can run. Queues do not partition work by task
+                    // name, so another worker's tasks would otherwise be claimed here and
+                    // failed for want of a handler. Read each poll: handlers may be
+                    // registered after run() started.
+                    names: [...this.handlers.keys()],
+                    workerId: this.workerId,
+                    leaseMs,
+                    limit: Math.min(batch, free),
+                });
+            }
+            catch (err) {
+                // A claim can fail transiently (lock contention, a dropped connection).
+                // Report it and keep polling — one bad poll must not end the worker.
+                this.report(err, { phase: "claim" });
+                await this.sleepOrStop(CLAIM_ERROR_BACKOFF_MS);
                 continue;
             }
-            const claimed = await this.store.claim({
-                queues: this.queues,
-                workerId: this.workerId,
-                leaseMs,
-                limit: Math.min(batch, free),
-            });
             if (claimed.length === 0) {
-                await this.sleepOrStop(pollMs);
+                await this.idle(pollMs);
                 continue;
             }
             for (const task of claimed) {
@@ -113,16 +184,21 @@ export class Worker {
                 running.add(p);
             }
         }
-        await Promise.all([...running]);
     }
     /** Blocking-style entry point for a standalone worker process: run until
      * SIGINT/SIGTERM, then close the store. Use this at a script's top level;
      * use run() / background() when you manage the event loop yourself. */
     async serve(opts = {}) {
+        // Signals are installed here rather than in run(): serve() is the entry point
+        // that owns the process. run()/background() embed the worker in someone
+        // else's process, where a leftover listener suppresses Node's default Ctrl-C
+        // handling for the host long after the worker is done.
+        const removeSignalHandlers = this.installSignals();
         try {
             await this.run(opts);
         }
         finally {
+            removeSignalHandlers();
             await this.closeIfOwned();
         }
     }
@@ -138,13 +214,18 @@ export class Worker {
             await this.closeIfOwned();
         }
     }
+    /**
+     * Run one task to completion. Never rejects: a task-level failure is reported
+     * through onError and the loop moves on. (It used to reject into a promise
+     * nobody awaited — an unhandled rejection that took the process down.)
+     */
     async execute(task, leaseMs) {
         const ctx = new TaskContext(this.store, task, this.workerId, leaseMs);
         const hb = this.startHeartbeat(ctx, leaseMs);
         try {
             const handler = this.handlers.get(task.name);
             if (!handler) {
-                await this.safeFail(task.id, errorEnvelope({
+                await this.safeFail(task, errorEnvelope({
                     type: "NoHandler",
                     code: "no_handler",
                     message: `no handler registered for ${task.name}`,
@@ -154,16 +235,22 @@ export class Worker {
             }
             let result;
             try {
-                result = await handler(ctx, task.payload);
+                result = await this.attempt(handler, ctx, task);
             }
             catch (err) {
                 if (err instanceof LostLease)
                     return;
+                if (err instanceof AttemptTimeout) {
+                    // Recorded as a retryable failure, so backoff / maxAttempts /
+                    // cancel-wins all apply exactly as for a thrown error.
+                    await this.safeFail(task, timeoutEnvelope(task.name, err.maxRunMs), true);
+                    return;
+                }
                 if (err instanceof TaskError) {
-                    await this.safeFail(task.id, err.envelope(), err.retryable);
+                    await this.safeFail(task, err.envelope(), err.retryable);
                 }
                 else {
-                    await this.safeFail(task.id, exceptionEnvelope(err), true);
+                    await this.safeFail(task, exceptionEnvelope(err), true);
                 }
                 return;
             }
@@ -173,20 +260,68 @@ export class Worker {
                 await this.store.complete({ taskId: task.id, workerId: this.workerId, result });
             }
             catch (err) {
-                if (err instanceof LostLease)
+                if (err instanceof LostLease) {
+                    ctx.markLeaseLost();
                     return;
+                }
+                if (err instanceof SerializationError) {
+                    // The handler succeeded but its return value can't cross the JSON
+                    // protocol (BigInt, non-finite number, circular). Deterministic, so
+                    // fail fast and permanently — the alternative is sitting `running`
+                    // until lease expiry redelivers a task that fails the same way every
+                    // attempt.
+                    await this.safeFail(task, errorEnvelope({
+                        type: "SerializationError",
+                        code: "unserializable_result",
+                        message: `handler result is not JSON-serializable: ${err.message}`,
+                        retryable: false,
+                    }), false);
+                    return;
+                }
                 throw err;
             }
         }
+        catch (err) {
+            this.report(err, { phase: "execute", taskId: task.id });
+        }
         finally {
             hb.cancel();
             await hb.done;
         }
     }
+    /**
+     * Run one attempt, bounded by maxRunMs when set. On timeout the attempt is
+     * abandoned: the context is flagged lease-lost first (ctx.signal aborts, and
+     * a handler that keeps running can never write again — see
+     * TaskContext.owned), then the still-pending promise is left to settle on
+     * its own, its outcome discarded. The caller records the handler_timeout
+     * failure; lease recovery is NOT involved, so redelivery is immediate.
+     */
+    async attempt(handler, ctx, task) {
+        const maxRunMs = this.opts.maxRunMs;
+        if (maxRunMs == null)
+            return handler(ctx, task.payload);
+        // As a real promise: the race needs one (a handler may return a plain
+        // value), and the timeout path .catch()es it.
+        const run = (async () => handler(ctx, task.payload))();
+        let timer;
+        const winner = await Promise.race([
+            run,
+            new Promise((r) => (timer = setTimeout(() => r(TIMED_OUT), maxRunMs))),
+        ]).finally(() => clearTimeout(timer));
+        if (winner !== TIMED_OUT)
+            return winner;
+        ctx.markLeaseLost();
+        // The zombie may still reject later; that must not become an unhandled
+        // rejection — its outcome was already decided to be handler_timeout.
+        run.catch(() => { });
+        throw new AttemptTimeout(maxRunMs);
+    }
     startHeartbeat(ctx, leaseMs) {
         let active = true;
         let wake = null;
-        const interval = this.opts.heartbeatIntervalMs ?? Math.max(1_000, Math.floor(leaseMs / 3));
+        // lease/3 gives two beats of slack; the floor only matters for sub-150ms leases.
+        const interval = this.opts.heartbeatIntervalMs ?? Math.max(50, Math.floor(leaseMs / 3));
         const done = (async () => {
             while (active) {
                 // Cancellable sleep: cancel() resolves this immediately and clears the
@@ -205,8 +340,10 @@ export class Worker {
                     await ctx.heartbeat();
                 }
                 catch (err) {
+                    // ctx.heartbeat() already flagged the lease as lost for the handler.
                     if (err instanceof LostLease)
                         break;
+                    this.report(err, { phase: "execute", taskId: ctx.taskId });
                 }
             }
         })();
@@ -219,34 +356,57 @@ export class Worker {
             done,
         };
     }
-    async safeFail(taskId, envelope, retryable) {
+    async safeFail(task, envelope, retryable) {
+        const delayMs = retryable
+            ? retryDelayMs(task.attempt, this.opts.retryBackoffMs ?? DEFAULT_RETRY_BACKOFF_MS, this.opts.retryBackoffMaxMs ?? DEFAULT_RETRY_BACKOFF_MAX_MS)
+            : 0;
         try {
-            await this.store.fail({ taskId, workerId: this.workerId, error: envelope, retryable });
+            await this.store.fail({
+                taskId: task.id,
+                workerId: this.workerId,
+                error: envelope,
+                retryable,
+                delayMs,
+            });
         }
         catch (err) {
             if (!(err instanceof LostLease))
                 throw err;
         }
     }
+    /**
+     * The empty-poll sleep. A store with a push channel (Postgres LISTEN/NOTIFY)
+     * cuts it short when a task on this worker's queues becomes claimable;
+     * stop() interrupts it either way, and sleepOrStop bounds it at `ms` so the
+     * poll fallback — which also drives lease recovery — never stretches.
+     */
+    idle(ms) {
+        return Promise.race([this.sleepOrStop(ms), this.store.claimWake(this.queues, ms)]);
+    }
     sleepOrStop(ms) {
         if (this.stopped)
             return Promise.resolve();
-        return new Promise((resolve) => {
-            let done = false;
-            const finish = () => {
-                if (done)
-                    return;
-                done = true;
-                clearTimeout(timer);
-                resolve();
-            };
-            const timer = setTimeout(finish, ms);
-            this.stopResolvers.push(finish);
-        });
+        let timer;
+        const nap = new Promise((r) => (timer = setTimeout(r, ms)));
+        // Clear the timer whichever side wins, so a stop is never followed by a
+        // leftover poll timer holding the process open.
+        return Promise.race([nap, this.stopped$]).finally(() => clearTimeout(timer));
     }
+    /** Take SIGINT/SIGTERM for the duration of serve(). Returns the undo. */
     installSignals() {
-        const handler = () => this.stop();
-        process.once("SIGINT", handler);
-        process.once("SIGTERM", handler);
+        const remove = () => {
+            process.off("SIGINT", handler);
+            process.off("SIGTERM", handler);
+        };
+        const handler = () => {
+            // Stand down after the first signal, so a second Ctrl-C reaches Node's
+            // default and kills a worker that will not drain. `once` would only drop
+            // whichever signal fired and leave the other suppressing the default.
+            remove();
+            this.stop();
+        };
+        process.on("SIGINT", handler);
+        process.on("SIGTERM", handler);
+        return remove;
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cairnq",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "SQLite-first, cross-language, storage-centered durable task runtime",
   "license": "MIT",
   "author": "Jannchie <jannchie@gmail.com>",
@@ -33,6 +33,7 @@
   "files": ["dist", "src"],
   "engines": { "node": ">=20" },
   "scripts": {
+    "bench": "tsx bench/run.ts",
     "build": "tsc -p tsconfig.json",
     "test": "vitest run",
     "typecheck": "tsc -p tsconfig.json --noEmit"
@@ -40,13 +41,19 @@
   "dependencies": {
     "better-sqlite3": "^11.3.0"
   },
-  "optionalDependencies": {
+  "peerDependencies": {
     "pg": "^8.13.0"
   },
+  "peerDependenciesMeta": {
+    "pg": {
+      "optional": true
+    }
+  },
   "devDependencies": {
     "@types/better-sqlite3": "^7.6.11",
     "@types/node": "^22.7.0",
     "@types/pg": "^8.11.10",
+    "pg": "^8.13.0",
     "tsx": "^4.19.0",
     "typescript": "^5.6.0",
     "vitest": "^2.1.0"

package/src/client.ts

@@ -1,8 +1,8 @@
 import { TaskCanceled, TaskFailed } from "./errors.js";
-import { isFailed, isSucceeded, type Task } from "./models.js";
+import { isFailed, isSucceeded, type Task, type TaskStatus } from "./models.js";
 import { SQLiteStore } from "./store/sqlite.js";
 import { PostgresStore } from "./store/postgres.js";
-import type { ListInput, SubmitInput, TaskStore } from "./store/base.js";
+import type { ListInput, PurgeInput, SubmitInput, TaskStore } from "./store/base.js";
 import { type TaskDef, taskName } from "./task.js";
 import { pollWait } from "./wait.js";
 
@@ -72,6 +72,20 @@ export class CairnQ {
     return this._store.retryByKey(key, opts);
   }
 
+  /** Delete terminal tasks that finished more than `olderThanMs` ago and return
+   * their ids. Nothing else in CairnQ removes rows, so a long-lived database
+   * needs this on a schedule. Each call is bounded by `limit` to keep the write
+   * short; loop until it returns fewer than `limit`. */
+  purge(input?: PurgeInput): Promise<string[]> {
+    return this._store.purge(input);
+  }
+
+  /** Task counts per queue, keyed by status and zero-filled across all statuses
+   * — `(await stats()).default.queued` is the backlog of a queue. */
+  stats(): Promise<Record<string, Record<TaskStatus, number>>> {
+    return this._store.stats();
+  }
+
   wait(
     taskId: string,
     opts: { timeoutMs?: number; pollMs?: number } = {},