cairnq 0.7.0 → 0.9.0

package/dist/store/sqlite.js

@@ -1,9 +1,27 @@
 import { mkdirSync } from "node:fs";
 import { dirname, resolve } from "node:path";
-import Database from "better-sqlite3";
+import { createRequire } from "node:module";
 import { nowMs } from "../ids.js";
 import { loadMigrations, loadStatements } from "../sql.js";
 import { checkProtocolVersion, COMMENT, statementParams, TaskStore, } from "./base.js";
+// `better-sqlite3` is an optional dependency, matching `pg` on the Postgres side:
+// a Postgres-only deployment should not have to build a native module it never
+// loads, and importing this file must not pull one in. Required (not imported)
+// because ensure() is synchronous — the open path applies migrations and cannot
+// await — and createRequire gives a synchronous load from ESM.
+const require = createRequire(import.meta.url);
+let sqliteModule = null;
+function loadSqlite() {
+    if (sqliteModule)
+        return sqliteModule;
+    try {
+        sqliteModule = require("better-sqlite3");
+    }
+    catch {
+        throw new Error("SQLiteStore requires the 'better-sqlite3' package — install it (e.g. `npm i better-sqlite3`)");
+    }
+    return sqliteModule;
+}
 const WAL_RETRY_DELAY_MS = 50;
 const WAL_RETRY_BUDGET_MS = 5_000;
 const BUSY_RETRY_BASE_MS = 1;
@@ -221,7 +239,7 @@ export class SQLiteStore extends TaskStore {
         const memory = isMemory(this.path);
         if (!memory)
             mkdirSync(dirname(this.path), { recursive: true });
-        const db = new Database(this.path);
+        const db = new (loadSqlite())(this.path);
         // Only the synchronous part of the open path gets a real busy_timeout: the WAL
         // switch and the migrations cannot await a retry. See the class comment.
         db.pragma(`busy_timeout = ${this.busyBudgetMs}`);

package/dist/wait.d.ts

@@ -1,10 +1,15 @@
 import { type Task } from "./models.js";
 import type { TaskStore } from "./store/base.js";
+export declare const DEFAULT_WAIT_TIMEOUT_MS = 30000;
 export declare const DEFAULT_POLL_MS = 100;
 export declare const MAX_POLL_MS = 500;
 export interface PollOptions {
     timeoutMs: number;
+    /** The first poll interval (default 100). */
     pollMs?: number;
+    /** Ceiling the poll interval backs off to (default 500). Worth raising for a
+     * task known to take minutes — fewer reads — or lowering when shaving the
+     * average half-interval of completion-detection latency matters. */
     maxPollMs?: number;
 }
 /**
@@ -16,14 +21,14 @@ export interface PollOptions {
  * 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. `pollMs` is the *first* interval;
- * it backs off towards `maxPollMs`. */
+/** Poll the task's status until terminal or timeout. Returns the terminal Task
+ * (any status). Throws TaskTimeout, leaving the task running. `pollMs` is the
+ * *first* interval; it backs off towards `maxPollMs`. */
 export declare function pollWait(store: TaskStore, taskId: string, opts: PollOptions): Promise<Task>;
 /**
  * The same wait, following a key instead of an id.
  *
- * The key is re-resolved on every read, because that is what a key means: a
+ * The key is re-resolved on every probe, because that is what a key means: a
  * pointer to the task that is *current* under it. A `replace` landing mid-wait
  * moves the wait onto the new task rather than reporting the cancellation of the
  * old one, and a key that points at nothing yet is simply not finished — it

package/dist/wait.js

@@ -1,6 +1,7 @@
 import { TaskTimeout } from "./errors.js";
 import { nowMs } from "./ids.js";
 import { isTerminal } from "./models.js";
+export const DEFAULT_WAIT_TIMEOUT_MS = 30_000;
 export const DEFAULT_POLL_MS = 100;
 export const MAX_POLL_MS = 500;
 const GROWTH = 1.5;
@@ -17,36 +18,49 @@ export function nextPollMs(current, maxMs) {
     return Math.min(maxMs, Math.max(current + 1, Math.floor(current * GROWTH)));
 }
 /**
- * Poll `read` until it yields a terminal task, or the timeout elapses.
+ * Poll `probe` until it reports a terminal status, then return the full task
+ * via `read`; or throw once the timeout elapses.
+ *
+ * The loop's repeated read is the status-only `probe` (see get_status.sql): a
+ * waiting caller asks nothing but "is it finished yet", and re-reading the whole
+ * row would drag the payload back — and re-parse it — on every beat for the life
+ * of the wait. The full row is read once, when the probe turns terminal or, on
+ * the timeout beat, for the error's snapshot. Between the probe and that read
+ * the row can vanish (purge) or the key repoint (`replace`); a read that comes
+ * back empty or non-terminal is simply not finished, and the loop keeps polling.
  *
  * `wake` is what the loop sleeps on between reads: a store with a push channel
- * (Postgres) cuts it short when the task goes terminal, but the re-read is the
+ * (Postgres) cuts it short when the task goes terminal, but the re-probe is the
  * source of truth either way, so a plain sleep is always a correct answer.
  */
-async function poll(read, wake, subject, key, { timeoutMs, pollMs = DEFAULT_POLL_MS, maxPollMs = MAX_POLL_MS }) {
+async function poll(probe, read, wake, subject, key, { timeoutMs, pollMs = DEFAULT_POLL_MS, maxPollMs = MAX_POLL_MS }) {
     const deadline = nowMs() + timeoutMs;
     let interval = pollMs;
     for (;;) {
-        const task = await read();
+        const ref = await probe();
+        const remaining = deadline - nowMs();
+        // The one full-read site: when the probe says finished, or on the timeout
+        // beat for the error's stuck-in-what-state snapshot. No ref means no row,
+        // so there is nothing for a read to add to either case.
+        const task = ref && (isTerminal(ref) || remaining <= 0) ? await read() : null;
         if (task && isTerminal(task))
             return task;
-        const remaining = deadline - nowMs();
         if (remaining <= 0)
-            throw new TaskTimeout(task?.id ?? subject, { timeoutMs, task, key });
-        await wake(task, Math.min(interval, remaining));
+            throw new TaskTimeout(ref?.id ?? subject, { timeoutMs, task, key });
+        await wake(ref, Math.min(interval, remaining));
         interval = nextPollMs(interval, maxPollMs);
     }
 }
-/** Poll get() until terminal or timeout. Returns the terminal Task (any status).
- * Throws TaskTimeout, leaving the task running. `pollMs` is the *first* interval;
- * it backs off towards `maxPollMs`. */
+/** Poll the task's status until terminal or timeout. Returns the terminal Task
+ * (any status). Throws TaskTimeout, leaving the task running. `pollMs` is the
+ * *first* interval; it backs off towards `maxPollMs`. */
 export function pollWait(store, taskId, opts) {
-    return poll(() => store.get(taskId), (_task, ms) => store.taskDoneWake(taskId, ms), taskId, null, opts);
+    return poll(() => store.getStatus(taskId), () => store.get(taskId), (_ref, ms) => store.taskDoneWake(taskId, ms), taskId, null, opts);
 }
 /**
  * The same wait, following a key instead of an id.
  *
- * The key is re-resolved on every read, because that is what a key means: a
+ * The key is re-resolved on every probe, because that is what a key means: a
  * pointer to the task that is *current* under it. A `replace` landing mid-wait
  * moves the wait onto the new task rather than reporting the cancellation of the
  * old one, and a key that points at nothing yet is simply not finished — it
@@ -57,5 +71,5 @@ export function pollWait(store, taskId, opts) {
  * plain sleeps; once it resolves, the store's push channel applies as usual.
  */
 export function pollWaitByKey(store, key, opts) {
-    return poll(() => store.getByKey(key), (task, ms) => (task ? store.taskDoneWake(task.id, ms) : sleep(ms)), key, key, opts);
+    return poll(() => store.getStatusByKey(key), () => store.getByKey(key), (ref, ms) => (ref ? store.taskDoneWake(ref.id, ms) : sleep(ms)), key, key, opts);
 }

package/dist/worker.d.ts

@@ -1,5 +1,6 @@
 import type { BackpressureOptions } from "./backpressure.js";
 import { TaskContext } from "./context.js";
+import type { PgExecutor } from "./store/pg-executor.js";
 import type { TaskStore } from "./store/base.js";
 import { type TaskDef } from "./task.js";
 export { retryDelayMs, DEFAULT_RETRY_BACKOFF_MS, DEFAULT_RETRY_BACKOFF_MAX_MS } from "./backoff.js";
@@ -130,11 +131,13 @@ export declare class Worker {
         queues?: string[];
         busyTimeoutMs?: number;
     }): Worker;
-    /** Multi-host backend. `dsn` is a libpq connection string; requires the
-     * optional `pg` package. */
-    static postgres(dsn: string, opts?: WorkerOptions & {
+    /** Multi-host backend. `source` is a libpq connection string — which requires
+     * the optional `pg` package — or a PgExecutor over a driver the application
+     * already runs, which cairnq then shares instead of opening a second pool. */
+    static postgres(source: string | PgExecutor, opts?: WorkerOptions & {
         queues?: string[];
         max?: number;
+        schema?: string;
     }): Worker;
     get id(): string;
     task(handler: Handler): this;

package/dist/worker.js

@@ -133,11 +133,12 @@ export class Worker {
         worker.ownsStore = true;
         return worker;
     }
-    /** Multi-host backend. `dsn` is a libpq connection string; requires the
-     * optional `pg` package. */
-    static postgres(dsn, opts = {}) {
-        const { queues = ["default"], max, ...rest } = opts;
-        const worker = new Worker(new PostgresStore(dsn, { max }), queues, rest);
+    /** Multi-host backend. `source` is a libpq connection string — which requires
+     * the optional `pg` package — or a PgExecutor over a driver the application
+     * already runs, which cairnq then shares instead of opening a second pool. */
+    static postgres(source, opts = {}) {
+        const { queues = ["default"], max, schema, ...rest } = opts;
+        const worker = new Worker(new PostgresStore(source, { max, schema }), queues, rest);
         worker.ownsStore = true;
         return worker;
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cairnq",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "description": "SQLite-first, cross-language, storage-centered durable task runtime",
   "license": "MIT",
   "author": "Jannchie <jannchie@gmail.com>",
@@ -39,19 +39,21 @@
     "test": "vitest run",
     "typecheck": "tsc -p tsconfig.json --noEmit"
   },
-  "dependencies": {
-    "better-sqlite3": "^13.0.2"
-  },
   "peerDependencies": {
+    "better-sqlite3": "^13.0.2",
     "pg": "^8.13.0"
   },
   "peerDependenciesMeta": {
+    "better-sqlite3": {
+      "optional": true
+    },
     "pg": {
       "optional": true
     }
   },
   "devDependencies": {
     "@types/better-sqlite3": "^7.6.11",
+    "better-sqlite3": "^13.0.2",
     "@types/node": "^22.7.0",
     "@types/pg": "^8.11.10",
     "pg": "^8.13.0",

package/src/client.ts

@@ -1,17 +1,27 @@
 import type { BackpressureOptions } from "./backpressure.js";
 import { type RetentionOptions, RetentionSweeper } from "./retention.js";
 import { TaskCanceled, TaskFailed } from "./errors.js";
-import { isFailed, isSucceeded, type Task, type TaskStatus } from "./models.js";
+import { isFailed, isSucceeded, type Task, type TaskRef, type TaskStatus } from "./models.js";
 import { SQLiteStore } from "./store/sqlite.js";
 import { PostgresStore } from "./store/postgres.js";
-import type { ListInput, PurgeInput, SubmitInput, TaskStore } from "./store/base.js";
+import type { PgExecutor } from "./store/pg-executor.js";
+import type {
+  ListInput,
+  PurgeInput,
+  SubmitInput,
+  TaskStore,
+  WatchOptions,
+  WatchSignal,
+} from "./store/base.js";
 import { type TaskDef, taskName } from "./task.js";
-import { pollWait, pollWaitByKey } from "./wait.js";
+import { DEFAULT_WAIT_TIMEOUT_MS, type PollOptions, pollWait, pollWaitByKey } from "./wait.js";
 
 export type SubmitOptions = Omit<SubmitInput, "name" | "payload">;
-export interface CallOptions extends SubmitOptions {
+/** The wait loop's knobs with the timeout optional (default 30s) — the public
+ * face of PollOptions, whose comments document each knob. */
+export type WaitOptions = Partial<PollOptions>;
+export interface CallOptions extends SubmitOptions, Omit<WaitOptions, "timeoutMs"> {
   waitTimeoutMs?: number;
-  pollMs?: number;
 }
 
 /** Options this handle configures on the store it wraps, rather than the
@@ -51,11 +61,16 @@ export class CairnQ {
     return new CairnQ(new SQLiteStore(path, { busyTimeoutMs }), client);
   }
 
-  /** Multi-host backend. `dsn` is a libpq connection string; requires the
-   * optional `pg` package. */
-  static postgres(dsn: string, opts: { max?: number } & ClientOptions = {}): CairnQ {
-    const { max, ...client } = opts;
-    return new CairnQ(new PostgresStore(dsn, { max }), client);
+  /** Multi-host backend. `source` is a libpq connection string — which requires
+   * the optional `pg` package — or a PgExecutor over a driver the application
+   * already runs (an ORM's pool, say), which cairnq then shares instead of
+   * opening a second one. */
+  static postgres(
+    source: string | PgExecutor,
+    opts: { max?: number; schema?: string } & ClientOptions = {},
+  ): CairnQ {
+    const { max, schema, ...client } = opts;
+    return new CairnQ(new PostgresStore(source, { max, schema }), client);
   }
 
   get store(): TaskStore {
@@ -99,6 +114,17 @@ export class CairnQ {
     return this._store.getByKey(key);
   }
 
+  /** The status-only probe wait polls on: id + status, no payload. Public for
+   * the same reason it exists — a dashboard or poller that only asks "is it
+   * finished yet" should not drag the payload back per ask. */
+  getStatus(taskId: string): Promise<TaskRef | null> {
+    return this._store.getStatus(taskId);
+  }
+
+  getStatusByKey(key: string): Promise<TaskRef | null> {
+    return this._store.getStatusByKey(key);
+  }
+
   list(input?: ListInput): Promise<Task[]> {
     return this._store.list(input);
   }
@@ -133,16 +159,29 @@ export class CairnQ {
     return this._store.stats();
   }
 
+  /**
+   * Call `onSignal` when the tasks on `queues` may have changed. Returns an
+   * unsubscribe.
+   *
+   * Notify-accelerated polling, not an event log: a signal means "re-read now",
+   * and `stats()` / `list()` / `get()` are where the truth is. On Postgres an
+   * idle watch costs nothing and signals land in milliseconds; everywhere else
+   * the timer alone still delivers, so the same consumer code is correct either
+   * way. See TaskStore.watch for the full contract.
+   */
+  watch(opts: WatchOptions, onSignal: (signal: WatchSignal) => void): () => void {
+    return this._store.watch(opts, onSignal);
+  }
+
   /** Wait for a task to finish. Resolves with the terminal Task (any status);
    * throws TaskTimeout without stopping the task, so `wait(err.taskId)` picks the
    * same wait back up — from another process, or after a longer deadline. */
-  wait(
-    taskId: string,
-    opts: { timeoutMs?: number; pollMs?: number } = {},
-  ): Promise<Task> {
+  wait(taskId: string, opts: WaitOptions = {}): Promise<Task> {
+    // `??`, not a spread default: a caller forwarding `timeoutMs: undefined`
+    // (call() does) must still get the default, and a spread would override it.
     return pollWait(this._store, taskId, {
-      timeoutMs: opts.timeoutMs ?? 30_000,
-      pollMs: opts.pollMs,
+      ...opts,
+      timeoutMs: opts.timeoutMs ?? DEFAULT_WAIT_TIMEOUT_MS,
     });
   }
 
@@ -151,10 +190,10 @@ export class CairnQ {
    * that held it is gone. Re-resolves the key on each poll, so a `replace`
    * landing mid-wait moves the wait onto the new task, and a key with no task
    * yet is waited for rather than rejected. */
-  waitByKey(key: string, opts: { timeoutMs?: number; pollMs?: number } = {}): Promise<Task> {
+  waitByKey(key: string, opts: WaitOptions = {}): Promise<Task> {
     return pollWaitByKey(this._store, key, {
-      timeoutMs: opts.timeoutMs ?? 30_000,
-      pollMs: opts.pollMs,
+      ...opts,
+      timeoutMs: opts.timeoutMs ?? DEFAULT_WAIT_TIMEOUT_MS,
     });
   }
 
@@ -168,9 +207,9 @@ export class CairnQ {
   async call(name: string, payload?: unknown, opts?: CallOptions): Promise<unknown>;
   async call<P, R>(task: TaskDef<P, R>, payload?: P, opts?: CallOptions): Promise<R>;
   async call(task: string | TaskDef, payload?: unknown, opts: CallOptions = {}): Promise<unknown> {
-    const { waitTimeoutMs = 30_000, pollMs, ...submit } = opts;
+    const { waitTimeoutMs, pollMs, maxPollMs, ...submit } = opts;
     const created = await this.submit(taskName(task), payload, submit);
-    const final = await pollWait(this._store, created.id, { timeoutMs: waitTimeoutMs, pollMs });
+    const final = await this.wait(created.id, { timeoutMs: waitTimeoutMs, pollMs, maxPollMs });
     if (isSucceeded(final)) return final.result;
     if (isFailed(final)) throw new TaskFailed(final.error);
     throw new TaskCanceled(final.id);

package/src/context.ts

@@ -3,6 +3,7 @@ import { asEnvelope, type FailReason, LostLease } from "./errors.js";
 import { cancelRequested, type Task } from "./models.js";
 import type { SubmitOptions } from "./client.js";
 import type { TaskStore } from "./store/base.js";
+import type { PgSession } from "./store/pg-executor.js";
 import { type TaskDef, taskName } from "./task.js";
 import { pollWait } from "./wait.js";
 
@@ -201,6 +202,42 @@ export class TaskContext {
     return task;
   }
 
+  /**
+   * Finalize this task as succeeded, committing the caller's own writes in the
+   * SAME transaction as the settlement. Whatever `write` returns becomes the
+   * task's result.
+   *
+   *     await ctx.succeedIn(async (session) => {
+   *       await db.withSession(session).insert(pages).values(rendered)
+   *       return { pages: rendered.length }
+   *     })
+   *
+   * The alternative — write the rows, then settle — has a window between the two
+   * commits where the work is durable but the task still reads as running. A
+   * crash there re-runs the whole task, which for a render or an ingest means
+   * recomputing it, and for non-idempotent work means doing it twice.
+   *
+   * `session` is the driver's, so this needs a Postgres store built on a
+   * PgExecutor the application shares with its own driver; anything else throws.
+   * If the settlement finds the lease gone, `write`'s work is rolled back with
+   * it and LostLease is raised. Returns null if this task was already settled.
+   *
+   * `write` may be replayed if the backend retries the transaction — derive
+   * nothing inside it that cannot be derived twice.
+   */
+  async succeedIn<T>(write: (session: PgSession) => Promise<T>): Promise<Task | null> {
+    if (this.isSettled) return null;
+    const task = await this.owned(async () => {
+      const { task } = await this.store.completeIn<PgSession, T>(
+        { taskId: this.task.id, workerId: this.workerId },
+        write,
+      );
+      return task;
+    });
+    this.markSettled();
+    return task;
+  }
+
   /**
    * Finalize this task as failed, now. `error` may be a string reason, an Error,
    * a TaskError (which carries its own retryability), or a ready envelope.

package/src/errors.ts

@@ -170,10 +170,12 @@ export class TaskCanceled extends CairnQError {
  * anywhere. Nothing inside the blocked handler can observe that, which is why it
  * is reported through `onError` alongside the other things the run loop survived.
  *
- * The cause is always synchronous work in a handler: a tight loop, a large
+ * The usual cause is synchronous work in a handler: a tight loop, a large
  * JSON.parse, a `*Sync` filesystem or crypto call. Node has one loop and no way
  * to preempt it — move the work to a worker thread, a child process, or an async
- * API that yields.
+ * API that yields. The other cause is a worker simply oversubscribed for its
+ * `leaseMs` — nothing is blocking, there is just more work than turns — which the
+ * same report covers, because the lease is at equal risk either way.
  */
 export class EventLoopBlocked extends CairnQError {
   constructor(
@@ -183,8 +185,9 @@ export class EventLoopBlocked extends CairnQError {
   ) {
     super(
       `heartbeat beat was ${lateMs}ms late (interval ${intervalMs}ms, lease ${leaseMs}ms): ` +
-        `the event loop was blocked long enough to miss a beat. Synchronous work in a ` +
-        `handler starves lease renewal — move it off the loop.`,
+        `the event loop was blocked long enough to miss a beat, so this worker's leases ` +
+        `are at risk. Usually synchronous work in a handler (move it off the loop); ` +
+        `otherwise the worker is oversubscribed for its leaseMs.`,
     );
     this.name = "EventLoopBlocked";
   }

package/src/index.ts

@@ -1,9 +1,9 @@
 export { CairnQ } from "./client.js";
-export type { CallOptions, ClientOptions, SubmitOptions } from "./client.js";
+export type { CallOptions, ClientOptions, SubmitOptions, WaitOptions } from "./client.js";
 export { QueueDepthGate } from "./backpressure.js";
 export type { BackpressureOptions, QueueDepthLimit } from "./backpressure.js";
 export { RetentionSweeper } from "./retention.js";
-export type { RetentionOptions } from "./retention.js";
+export type { RetentionCutoffs, RetentionOptions } from "./retention.js";
 export { Worker } from "./worker.js";
 export type { BatchHandler, Handler, TypedHandler, WorkerOptions } from "./worker.js";
 export { TaskContext } from "./context.js";
@@ -12,12 +12,24 @@ export { defineTask } from "./task.js";
 export type { TaskDef } from "./task.js";
 export { SQLiteStore } from "./store/sqlite.js";
 export { PostgresStore } from "./store/postgres.js";
+export { ListenUnavailable } from "./store/pg-executor.js";
+export type { PgExecutor, PgSession, Row } from "./store/pg-executor.js";
+export { createPoolExecutor } from "./store/pg-pool.js";
 export { TaskStore } from "./store/base.js";
-export type { ListInput, PurgeInput, SubmitInput, Conflict } from "./store/base.js";
-export type { Task, TaskStatus } from "./models.js";
+export type {
+  ListInput,
+  PurgeInput,
+  SubmitInput,
+  Conflict,
+  WatchOptions,
+  WatchSignal,
+} from "./store/base.js";
+export { DEFAULT_WATCH_POLL_MS } from "./store/base.js";
+export type { Task, TaskRef, TaskStatus, TerminalStatus } from "./models.js";
 export {
   STATUSES,
   isTerminal,
+  isTerminalStatus,
   cancelRequested,
   isQueued,
   isRunning,

package/src/models.ts

@@ -31,8 +31,28 @@ export interface Task {
   completed_at_ms: number | null;
 }
 
+/** The id + status pair the wait loop polls on (see get_status.sql) — a probe,
+ * not a snapshot: everything else about the task is deliberately not read. */
+export interface TaskRef {
+  id: string;
+  status: TaskStatus;
+}
+
 const JSON_COLUMNS = ["payload", "result", "error", "metadata"] as const;
-export const TERMINAL: TaskStatus[] = ["succeeded", "failed", "canceled"];
+// As a const tuple so TerminalStatus derives from it — the same declare-once
+// pattern as STATUSES/TaskStatus above.
+export const TERMINAL = ["succeeded", "failed", "canceled"] as const;
+export type TerminalStatus = (typeof TERMINAL)[number];
+
+export function isTerminalStatus(status: TaskStatus): status is TerminalStatus {
+  return (TERMINAL as readonly TaskStatus[]).includes(status);
+}
+
+/** Map a probe row (see get_status.sql) to a TaskRef — the ref twin of
+ * rowToTask, so the row shape stays models' knowledge alone. */
+export function rowToRef(row: Record<string, unknown>): TaskRef {
+  return { id: row.id as string, status: row.status as TaskStatus };
+}
 
 export function rowToTask(row: Record<string, unknown>): Task {
   const t: Record<string, unknown> = { ...row };
@@ -46,8 +66,9 @@ export function rowToTask(row: Record<string, unknown>): Task {
   return t as unknown as Task;
 }
 
-export function isTerminal(task: Task): boolean {
-  return TERMINAL.includes(task.status);
+/** Accepts anything carrying a status — a Task or a TaskRef probe. */
+export function isTerminal(task: Pick<Task, "status">): boolean {
+  return isTerminalStatus(task.status);
 }
 
 export function cancelRequested(task: Task): boolean {

package/src/retention.ts

@@ -1,4 +1,5 @@
-import type { PurgeInput, TaskStore } from "./store/base.js";
+import type { TaskStatus, TerminalStatus } from "./models.js";
+import { validatePurgeInput, type PurgeInput, type TaskStore } from "./store/base.js";
 
 /** Sweep every hour unless asked otherwise — often enough that a queue with a
  * day of retention never carries more than an hour of extra rows, rare enough
@@ -8,12 +9,21 @@ const DEFAULT_INTERVAL_MS = 3_600_000;
  * a backlog drains in few statements, small enough that each is a short write. */
 const DEFAULT_LIMIT = 1_000;
 
+/** Per-status cutoffs. A status left out is never swept — granular retention is
+ * an explicit statement of what may go, not a default for what wasn't named. */
+export type RetentionCutoffs = Partial<Record<TerminalStatus, number>>;
+
 export interface RetentionOptions {
   /**
    * How long a terminal task is kept after it finished. Required: there is no
    * safe default for how long someone else's results stay readable.
+   *
+   * A number keeps every terminal status the same time. Retention needs are
+   * often tiered — a succeeded row is spent once its result is consumed, while
+   * a failed one is worth keeping for diagnosis — so a per-status map sets a
+   * cutoff per status instead: `{ succeeded: 300_000, failed: 86_400_000 }`.
    */
-  olderThanMs: number;
+  olderThanMs: number | RetentionCutoffs;
   /** Time between sweeps. Default 3_600_000 (one hour). */
   intervalMs?: number;
   /** Rows deleted per statement while draining. Default 1_000. */
@@ -50,20 +60,37 @@ export class RetentionSweeper {
   /** The loop itself, awaited by stop() so no purge outlives the store. */
   private loop: Promise<void> | null = null;
   private readonly intervalMs: number;
-  private readonly purgeInput: PurgeInput;
+  /** Rows per purge statement while draining — see DEFAULT_LIMIT. */
+  private readonly limit: number;
+  /** One purge per cutoff: a lone entry for a number, one per status for a map. */
+  private readonly purgeInputs: PurgeInput[];
 
   constructor(
     private readonly store: TaskStore,
     private readonly opts: RetentionOptions,
   ) {
-    if (!Number.isFinite(opts.olderThanMs) || opts.olderThanMs < 0) {
-      throw new Error(`retention.olderThanMs must be >= 0, got ${opts.olderThanMs}`);
-    }
     this.intervalMs = opts.intervalMs ?? DEFAULT_INTERVAL_MS;
     if (!Number.isFinite(this.intervalMs) || this.intervalMs < 1) {
       throw new Error(`retention.intervalMs must be >= 1, got ${this.intervalMs}`);
     }
-    this.purgeInput = { olderThanMs: opts.olderThanMs, limit: opts.limit ?? DEFAULT_LIMIT };
+    this.limit = opts.limit ?? DEFAULT_LIMIT;
+    const cutoffs: [TaskStatus | undefined, number][] =
+      typeof opts.olderThanMs === "number"
+        ? [[undefined, opts.olderThanMs]]
+        : (Object.entries(opts.olderThanMs) as [TaskStatus, number][]);
+    // An empty map retains nothing and sweeps nothing — almost certainly a bug
+    // upstream of this call, so refuse it rather than silently never purging.
+    if (!cutoffs.length) {
+      throw new Error("retention.olderThanMs must name at least one status");
+    }
+    this.purgeInputs = cutoffs.map(([status, ms]) => ({
+      olderThanMs: ms,
+      status,
+      limit: this.limit,
+    }));
+    // Fail fast on the store's own purge rules (terminal status, cutoff >= 0):
+    // the sweep runs an hour from now, and its errors only surface via onError.
+    for (const input of this.purgeInputs) validatePurgeInput(input);
   }
 
   start(): void {
@@ -107,16 +134,19 @@ export class RetentionSweeper {
    * demand — after a backfill, or from a maintenance command.
    */
   async sweep(): Promise<number> {
-    const limit = this.purgeInput.limit as number;
     let deleted = 0;
-    for (;;) {
-      const ids = await this.store.purge(this.purgeInput);
-      deleted += ids.length;
-      if (ids.length < limit || this.stopping) return deleted;
-      // Hand the loop back between batches: a large drain must not starve the
-      // submits and claims sharing this process.
-      await this.sleep(0);
+    for (const input of this.purgeInputs) {
+      for (;;) {
+        const ids = await this.store.purge(input);
+        deleted += ids.length;
+        if (this.stopping) return deleted;
+        if (ids.length < this.limit) break;
+        // Hand the loop back between batches: a large drain must not starve the
+        // submits and claims sharing this process.
+        await this.sleep(0);
+      }
     }
+    return deleted;
   }
 
   /** Sleep, interruptible by stop(). Unref'd: retention is housekeeping, and a