cairnq 0.6.0 → 0.8.0

package/dist/retention.js

@@ -0,0 +1,137 @@
+import { validatePurgeInput } 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
+ * that the sweep is invisible next to the task traffic. */
+const DEFAULT_INTERVAL_MS = 3_600_000;
+/** Rows per purge statement. The same bound `purge` defaults to: big enough that
+ * a backlog drains in few statements, small enough that each is a short write. */
+const DEFAULT_LIMIT = 1_000;
+/**
+ * Deletes terminal tasks on a schedule, for as long as the handle is open.
+ *
+ * `purge` exists because nothing else in CairnQ removes rows, and a queue whose
+ * payloads carry real data — an image, a document, a batch of embeddings — turns
+ * that into a disk leak measured in gigabytes per backfill. Every deployment
+ * that runs longer than a demo needs the sweep; leaving it to an external
+ * scheduler means the leak is the default and remembering is the opt-in.
+ *
+ * It sweeps in bounded batches with a yield between them, so draining a backlog
+ * that accumulated while nothing was sweeping stays a sequence of short writes
+ * rather than one long one — on SQLite that matters, since a long write holds
+ * the single write lock against every producer and worker on the file.
+ */
+export class RetentionSweeper {
+    store;
+    opts;
+    /** Whether the scheduled loop is running. */
+    active = false;
+    /** Set by stop(), so a drain in progress can cut itself short too. */
+    stopping = false;
+    /** Resolves the current sleep early, so stop() need not wait out an interval. */
+    wake = null;
+    /** The loop itself, awaited by stop() so no purge outlives the store. */
+    loop = null;
+    intervalMs;
+    /** Rows per purge statement while draining — see DEFAULT_LIMIT. */
+    limit;
+    /** One purge per cutoff: a lone entry for a number, one per status for a map. */
+    purgeInputs;
+    constructor(store, opts) {
+        this.store = store;
+        this.opts = opts;
+        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.limit = opts.limit ?? DEFAULT_LIMIT;
+        const cutoffs = typeof opts.olderThanMs === "number"
+            ? [[undefined, opts.olderThanMs]]
+            : Object.entries(opts.olderThanMs);
+        // 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() {
+        if (this.active)
+            return;
+        this.active = true;
+        this.stopping = false;
+        this.loop = this.run();
+    }
+    /** Stop sweeping and wait for the sweep in flight, if any. */
+    async stop() {
+        this.stopping = true;
+        this.active = false;
+        this.wake?.();
+        await this.loop;
+        this.loop = null;
+    }
+    async run() {
+        // Sleep first: a process that restarts often would otherwise purge on every
+        // boot, which is a write burst exactly when the store is busiest.
+        while (!this.stopping) {
+            await this.sleep(this.intervalMs);
+            if (this.stopping)
+                return;
+            try {
+                await this.sweep();
+            }
+            catch (err) {
+                try {
+                    this.opts.onError?.(err);
+                }
+                catch {
+                    // A reporting hook must never take the sweep down with it — the same
+                    // rule the worker's onError follows.
+                }
+            }
+        }
+    }
+    /**
+     * Delete everything past the cutoff now, in bounded batches, and return how
+     * many rows went. The scheduled loop calls this; call it directly to drain on
+     * demand — after a backfill, or from a maintenance command.
+     */
+    async sweep() {
+        let deleted = 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
+     * pending sweep must never be the reason a process refuses to exit. */
+    sleep(ms) {
+        return new Promise((resolve) => {
+            const timer = setTimeout(resolve, ms);
+            timer.unref?.();
+            this.wake = () => {
+                clearTimeout(timer);
+                resolve();
+            };
+        }).finally(() => {
+            this.wake = null;
+        });
+    }
+}

package/dist/store/base.d.ts

@@ -1,4 +1,4 @@
-import { type Task, type TaskStatus } from "../models.js";
+import { type Task, type TaskRef, type TaskStatus } from "../models.js";
 import { type BackpressureOptions } from "../backpressure.js";
 /** Encode a value for a protocol JSON column, raising SerializationError on
  * anything JSON cannot represent. Refuses what JSON.stringify would silently
@@ -11,7 +11,7 @@ export declare function dumpJson(value: unknown): string;
  * The supported major is a protocol fact, not a dialect one — every backend
  * checks it here so the constant can't fork per store. */
 export declare function checkProtocolVersion(version: number): void;
-declare const CONFLICTS: readonly ["reuse", "reject", "replace"];
+declare const CONFLICTS: readonly ["reuse", "reuse-succeeded", "reject", "replace"];
 export type Conflict = (typeof CONFLICTS)[number];
 /** The queue a submit lands on when it names none. Owned here, where the
  * default is applied, so nothing above has to re-derive it. */
@@ -39,8 +39,19 @@ export interface ListInput {
     limit?: number;
     offset?: number;
 }
+/** Validate a purge's inputs. Shared with RetentionSweeper, which fail-fasts at
+ * construction on the same rules an hourly sweep would otherwise only surface
+ * through its onError hook — one statement of the rules, two callers. */
+export declare function validatePurgeInput(input: PurgeInput): void;
 export interface PurgeInput {
     olderThanMs?: number;
+    /** Restrict the sweep to one terminal status. Retention needs are tiered —
+     * succeeded rows are spent once their result is consumed, failed ones are
+     * worth keeping for diagnosis — and without this the shortest-lived tier
+     * sets the retention for every row. Absent means all terminal statuses. */
+    status?: TaskStatus;
+    /** Restrict the sweep to one task name. Absent means all names. */
+    name?: string;
     limit?: number;
 }
 export type Params = Record<string, unknown>;
@@ -109,6 +120,7 @@ export declare abstract class TaskStore {
      */
     private ownedWrite;
     private static one;
+    private static oneRef;
     /**
      * Bound how deep a queue may get before `submit` blocks. Off unless set.
      *
@@ -121,6 +133,12 @@ export declare abstract class TaskStore {
     submit(input: SubmitInput): Promise<Task>;
     get(taskId: string): Promise<Task | null>;
     getByKey(key: string): Promise<Task | null>;
+    /** The wait loop's probe: id + status alone, so polling a task with a large
+     * payload does not re-read and re-parse that payload on every beat. */
+    getStatus(taskId: string): Promise<TaskRef | null>;
+    /** getStatus, following a key instead of an id — re-resolved per call, so a
+     * `replace` moves the probe onto the new task. */
+    getStatusByKey(key: string): Promise<TaskRef | null>;
     list(input?: ListInput): Promise<Task[]>;
     cancel(taskId: string): Promise<Task | null>;
     retry(taskId: string, opts?: {

package/dist/store/base.js

@@ -1,6 +1,6 @@
 import { newId } from "../ids.js";
 import { AlreadyExists, errorEnvelope, LostLease, ProtocolVersionMismatch, SerializationError, } from "../errors.js";
-import { rowToTask, STATUSES } from "../models.js";
+import { isTerminalStatus, rowToRef, rowToTask, STATUSES, } from "../models.js";
 import { QueueDepthGate } from "../backpressure.js";
 const rejectMangled = function (_key, v) {
     if (typeof v === "number" && !Number.isFinite(v)) {
@@ -51,10 +51,43 @@ export function checkProtocolVersion(version) {
 // CONFLICTS is the canonical declaration; the type derives from it so the
 // runtime guard in submit() and the type can't drift apart (same pattern as
 // STATUSES/TaskStatus in models.ts).
-const CONFLICTS = ["reuse", "reject", "replace"];
+const CONFLICTS = ["reuse", "reuse-succeeded", "reject", "replace"];
+/**
+ * Whether a keyed submit's strategy accepts the task the key already points at.
+ *
+ * Both reuse strategies deduplicate work that is still in play — that is what a
+ * key is for, and the answer cannot depend on the outcome of a task that has no
+ * outcome yet. They differ only on what a *finished* task means: `reuse` treats
+ * the key as free again, while `reuse-succeeded` reads a succeeded task as a
+ * cached result. Neither ever hands back a failed or canceled one, which would
+ * poison the key for every later submit (see PROTOCOL.md "Key conflict").
+ */
+function reusable(conflict, status) {
+    if (conflict === "replace")
+        return false;
+    if (!isTerminalStatus(status))
+        return true;
+    return conflict === "reuse-succeeded" && status === "succeeded";
+}
 /** The queue a submit lands on when it names none. Owned here, where the
  * default is applied, so nothing above has to re-derive it. */
 export const DEFAULT_QUEUE = "default";
+/** Validate a purge's inputs. Shared with RetentionSweeper, which fail-fasts at
+ * construction on the same rules an hourly sweep would otherwise only surface
+ * through its onError hook — one statement of the rules, two callers. */
+export function validatePurgeInput(input) {
+    if (input.olderThanMs != null && (!Number.isFinite(input.olderThanMs) || input.olderThanMs < 0)) {
+        throw new Error(`olderThanMs must be >= 0, got ${input.olderThanMs}`);
+    }
+    if (input.limit != null && input.limit < 1) {
+        throw new Error(`limit must be >= 1, got ${input.limit}`);
+    }
+    // Terminal only: purge never deletes live work, so accepting `queued` here
+    // would be accepting a filter that silently matches nothing.
+    if (input.status != null && !isTerminalStatus(input.status)) {
+        throw new Error(`status must be terminal, got ${input.status}`);
+    }
+}
 export const LEASE_EXPIRED_ERROR_JSON = dumpJson(errorEnvelope({
     type: "LeaseExpired",
     code: "lease_expired",
@@ -142,6 +175,9 @@ export class TaskStore {
     static one(rows) {
         return rows.length ? rowToTask(rows[0]) : null;
     }
+    static oneRef(rows) {
+        return rows.length ? rowToRef(rows[0]) : null;
+    }
     // ------------------------------------------------------------- client side
     /**
      * Bound how deep a queue may get before `submit` blocks. Off unless set.
@@ -207,12 +243,17 @@ export class TaskStore {
                 // free after all, whatever the strategy.
                 const current = (await fetch("get", { id: existing[0].task_id }))[0];
                 if (current) {
-                    if (conflict === "reuse")
-                        return rowToTask(current);
                     if (conflict === "reject")
                         throw new AlreadyExists(key);
-                    // "replace": cancel the recorded task, then repoint the key below.
-                    await fetch("cancel", { id: existing[0].task_id });
+                    if (reusable(conflict, current.status))
+                        return rowToTask(current);
+                    // The strategy declined the recorded task, so the key repoints to the
+                    // fresh one inserted below. Cancel only what is still live: a terminal
+                    // task has nothing to stop, and cancelling it would rewrite a settled
+                    // row (and hand a `canceled` back to whoever is waiting on it).
+                    if (!isTerminalStatus(current.status)) {
+                        await fetch("cancel", { id: existing[0].task_id });
+                    }
                 }
             }
             const row = (await fetch("insert_task", ins))[0];
@@ -226,6 +267,16 @@ export class TaskStore {
     async getByKey(key) {
         return TaskStore.one(await this.fetch("get_by_key", { key }));
     }
+    /** The wait loop's probe: id + status alone, so polling a task with a large
+     * payload does not re-read and re-parse that payload on every beat. */
+    async getStatus(taskId) {
+        return TaskStore.oneRef(await this.fetch("get_status", { id: taskId }));
+    }
+    /** getStatus, following a key instead of an id — re-resolved per call, so a
+     * `replace` moves the probe onto the new task. */
+    async getStatusByKey(key) {
+        return TaskStore.oneRef(await this.fetch("get_status_by_key", { key }));
+    }
     async list(input = {}) {
         // Validate up front, like submit's conflict guard: a typo'd status otherwise
         // matches nothing and returns [] indistinguishably from "no such tasks".
@@ -280,14 +331,11 @@ export class TaskStore {
      * call it in a loop until it returns fewer than `limit`.
      */
     async purge(input = {}) {
-        if (input.olderThanMs != null && input.olderThanMs < 0) {
-            throw new Error(`olderThanMs must be >= 0, got ${input.olderThanMs}`);
-        }
-        if (input.limit != null && input.limit < 1) {
-            throw new Error(`limit must be >= 1, got ${input.limit}`);
-        }
+        validatePurgeInput(input);
         const rows = await this.fetch("purge", {
             older_than_ms: input.olderThanMs ?? 0,
+            status: input.status ?? null,
+            name: input.name ?? null,
             limit: input.limit ?? 1_000,
         });
         return rows.map((r) => r.id);

package/dist/wait.d.ts

@@ -1,7 +1,17 @@
 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;
+}
 /**
  * Grow the polling interval towards the ceiling.
  *
@@ -11,11 +21,21 @@ export declare const MAX_POLL_MS = 500;
  * 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`. */
-export declare function pollWait(store: TaskStore, taskId: string, { timeoutMs, pollMs, maxPollMs, }: {
-    timeoutMs: number;
-    pollMs?: number;
-    maxPollMs?: number;
-}): Promise<Task>;
+/** 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 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
+ * polls until something appears, the same way waiting on an id that does not
+ * exist yet does.
+ *
+ * There is nothing to subscribe to before the key resolves, so those naps are
+ * plain sleeps; once it resolves, the store's push channel applies as usual.
+ */
+export declare function pollWaitByKey(store: TaskStore, key: string, opts: PollOptions): Promise<Task>;

package/dist/wait.js

@@ -1,9 +1,11 @@
 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;
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 /**
  * Grow the polling interval towards the ceiling.
  *
@@ -15,22 +17,59 @@ const GROWTH = 1.5;
 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. `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, }) {
+/**
+ * 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-probe is the
+ * source of truth either way, so a plain sleep is always a correct answer.
+ */
+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 store.get(taskId);
+        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(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));
+            throw new TaskTimeout(ref?.id ?? subject, { timeoutMs, task, key });
+        await wake(ref, Math.min(interval, remaining));
         interval = nextPollMs(interval, 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.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 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
+ * polls until something appears, the same way waiting on an id that does not
+ * exist yet does.
+ *
+ * There is nothing to subscribe to before the key resolves, so those naps are
+ * plain sleeps; once it resolves, the store's push channel applies as usual.
+ */
+export function pollWaitByKey(store, 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.js

@@ -1,6 +1,6 @@
 import { DEFAULT_RETRY_BACKOFF_MAX_MS, DEFAULT_RETRY_BACKOFF_MS, failDelayMs } from "./backoff.js";
 import { TaskContext } from "./context.js";
-import { asEnvelope, errorEnvelope, exceptionEnvelope, LostLease, SerializationError, } from "./errors.js";
+import { asEnvelope, errorEnvelope, EventLoopBlocked, exceptionEnvelope, LostLease, SerializationError, } from "./errors.js";
 import { newId } from "./ids.js";
 import { SQLiteStore } from "./store/sqlite.js";
 import { PostgresStore } from "./store/postgres.js";
@@ -703,6 +703,26 @@ export class Worker {
         let wake = null;
         // 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));
+        // When this heartbeat last ran. A loop cannot report its own absence — a
+        // handler that blocks for its whole attempt never lets the timer fire at all
+        // — so the check lives outside the loop and cancel() runs it too.
+        let lastBeatAt = Date.now();
+        /** Report a heartbeat that has not run for more than two intervals: a whole
+         * beat missed, which at lease/3 means the next such block loses the lease
+         * outright. Fires while the lease still holds — after it expires the only
+         * evidence is a task that ran twice, in two workers' logs, with no error in
+         * either. */
+        const checkBeat = () => {
+            const now = Date.now();
+            const lateMs = now - lastBeatAt - interval;
+            if (lateMs > interval) {
+                this.report(new EventLoopBlocked(lateMs, interval, leaseMs), {
+                    phase: "execute",
+                    taskId: ctxs[0].taskId,
+                });
+            }
+            lastBeatAt = now;
+        };
         const done = (async () => {
             while (active) {
                 // Cancellable sleep: cancel() resolves this immediately and clears the
@@ -717,6 +737,7 @@ export class Worker {
                 wake = null;
                 if (!active)
                     break;
+                checkBeat();
                 const live = ctxs.filter((c) => !c.settled && !c.lostLease);
                 if (!live.length)
                     break;
@@ -746,6 +767,10 @@ export class Worker {
                 active = false;
                 if (wake)
                     wake();
+                // The attempt is over, so this is the last chance to notice that the
+                // heartbeat never got one — the whole-attempt block, which is also the
+                // one where the lease is already gone.
+                checkBeat();
             },
             done,
         };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cairnq",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "description": "SQLite-first, cross-language, storage-centered durable task runtime",
   "license": "MIT",
   "author": "Jannchie <jannchie@gmail.com>",

package/src/client.ts

@@ -1,24 +1,35 @@
 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 TaskDef, taskName } from "./task.js";
-import { pollWait } 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
  * store's own constructor arguments. */
-export type ClientOptions = Partial<BackpressureOptions>;
+export type ClientOptions = Partial<BackpressureOptions> & {
+  /** Delete terminal tasks older than a cutoff, on a schedule, for as long as
+   * this handle is open. Off unless set — and off means rows accumulate forever,
+   * because nothing else in CairnQ removes them. */
+  retention?: RetentionOptions;
+};
 
 /** API-side handle. Thin wrapper over a TaskStore + SDK-orchestrated wait/call. */
 export class CairnQ {
+  /** null unless `retention` was configured. */
+  private readonly sweeper: RetentionSweeper | null;
+
   constructor(
     private readonly _store: TaskStore,
     opts: ClientOptions = {},
@@ -28,6 +39,13 @@ export class CairnQ {
     if (opts.maxQueueDepth != null) {
       _store.useBackpressure(opts as BackpressureOptions);
     }
+    // Retention is the opposite case: it belongs to the handle, because a worker
+    // sharing the store must not also be deleting rows behind the API's back.
+    // Started here rather than in connect(), which is optional — every other
+    // path connects lazily, and retention that silently depends on an optional
+    // call is retention that silently does not happen.
+    this.sweeper = opts.retention ? new RetentionSweeper(_store, opts.retention) : null;
+    this.sweeper?.start();
   }
 
   static sqlite(path: string, opts: { busyTimeoutMs?: number } & ClientOptions = {}): CairnQ {
@@ -50,8 +68,11 @@ export class CairnQ {
     return this._store.connect();
   }
 
-  close(): Promise<void> {
-    return this._store.close();
+  /** Stop retention (waiting for a sweep in flight, so no purge outlives the
+   * store) and close the store. */
+  async close(): Promise<void> {
+    await this.sweeper?.stop();
+    await this._store.close();
   }
 
   /** Enqueue a task. With `maxQueueDepth` configured this blocks while the
@@ -80,6 +101,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);
   }
@@ -114,25 +146,43 @@ export class CairnQ {
     return this._store.stats();
   }
 
-  wait(
-    taskId: string,
-    opts: { timeoutMs?: number; pollMs?: number } = {},
-  ): Promise<Task> {
+  /** 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: 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,
+    });
+  }
+
+  /** Wait for whatever task the `key` currently points at — the cross-process
+   * form of picking a wait back up, when the id was never in hand or the process
+   * 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: WaitOptions = {}): Promise<Task> {
+    return pollWaitByKey(this._store, key, {
+      ...opts,
+      timeoutMs: opts.timeoutMs ?? DEFAULT_WAIT_TIMEOUT_MS,
     });
   }
 
   /** submit + wait. Resolves with the result on success; rejects with
    * TaskFailed / TaskCanceled / TaskTimeout otherwise. Pass a TaskDef and the
-   * resolved value is typed as its Result. */
+   * resolved value is typed as its Result.
+   *
+   * `waitTimeoutMs` bounds the wait, not the task: on timeout the task runs on,
+   * and `wait(err.taskId)` — or `waitByKey`, from a process that only has the
+   * key — resumes the wait rather than starting the work over. */
   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);