cairnq 0.7.0 → 0.8.0

package/README.md

@@ -75,9 +75,11 @@ const worker = Worker.sqlite("tasks.db", {
 });
 
 // Nothing else deletes rows, so give the client a retention policy — it sweeps
-// terminal tasks in bounded batches for as long as the handle is open.
+// terminal tasks in bounded batches for as long as the handle is open. A
+// per-status map keeps each status on its own clock (statuses left out are
+// never swept): spent results go in minutes, failures stay for diagnosis.
 const tasks = CairnQ.sqlite("tasks.db", {
-  retention: { olderThanMs: 7 * 24 * 3600_000 },
+  retention: { olderThanMs: { succeeded: 300_000, failed: 7 * 24 * 3600_000 } },
 });
 ```
 

package/dist/_protocol/migrations/postgres/0007_purge_status_index.sql

@@ -0,0 +1,11 @@
+-- Serves purge.sql's optional status filter: without it a filtered sweep walks
+-- cairnq_tasks_completed_idx and visits the table row of every terminal task
+-- older than the cutoff just to discard the wrong statuses — worst exactly in
+-- the tiered configuration the filter exists for (a minutes-scale succeeded
+-- cutoff scanning a day's worth of retained failed rows, every sweep). With
+-- (status, completed_at_ms) each filtered sweep is a bounded range seek already
+-- in completion order. Unfiltered purge keeps using cairnq_tasks_completed_idx.
+create index if not exists cairnq_tasks_status_completed_idx
+    on cairnq_tasks (status, completed_at_ms);
+
+update cairnq_meta set value = '7' where key = 'schema_version';

package/dist/_protocol/migrations/sqlite/0007_purge_status_index.sql

@@ -0,0 +1,11 @@
+-- Serves purge.sql's optional status filter: without it a filtered sweep walks
+-- cairnq_tasks_completed_idx and visits the table row of every terminal task
+-- older than the cutoff just to discard the wrong statuses — worst exactly in
+-- the tiered configuration the filter exists for (a minutes-scale succeeded
+-- cutoff scanning a day's worth of retained failed rows, every sweep). With
+-- (status, completed_at_ms) each filtered sweep is a bounded range seek already
+-- in completion order. Unfiltered purge keeps using cairnq_tasks_completed_idx.
+create index if not exists cairnq_tasks_status_completed_idx
+    on cairnq_tasks (status, completed_at_ms);
+
+update cairnq_meta set value = '7' where key = 'schema_version';

package/dist/_protocol/sql/postgres/get_status.sql

@@ -0,0 +1,7 @@
+-- The status-only probe behind wait/call polling (Postgres dialect). A pending
+-- task's whole row is dead weight to a loop that only asks "is it finished yet"
+-- — with a large payload it re-reads and re-parses megabytes per second of
+-- waiting. The full row is fetched once, via get.sql, when this reports a
+-- terminal status.
+-- params: id
+select id, status from cairnq_tasks where id = :id;

package/dist/_protocol/sql/postgres/get_status_by_key.sql

@@ -0,0 +1,7 @@
+-- get_status.sql, following a key instead of an id (Postgres dialect) — the
+-- probe behind wait_by_key. Resolves the key on every read, so a `replace`
+-- landing mid-wait moves the wait onto the new task.
+-- params: key
+select t.id, t.status from cairnq_tasks t
+join cairnq_task_keys k on k.task_id = t.id
+where k.key = :key;

package/dist/_protocol/sql/postgres/purge.sql

@@ -11,11 +11,18 @@
 -- live task. Locking the rows in the subselect freezes them terminal until the
 -- delete commits; a concurrent retry then re-evaluates against the deleted row
 -- and correctly finds nothing.
--- params: older_than_ms, limit
+-- The status/name filters are optional (pass NULL to skip; `::text` pins the
+-- param's type, as in list.sql): retention needs are tiered — a succeeded row
+-- is spent once its result is consumed, while a failed one is worth keeping
+-- for diagnosis — and without them the shortest-lived tier sets the retention
+-- for every row.
+-- params: older_than_ms, status, name, limit
 delete from cairnq_tasks
 where id in (
     select id from cairnq_tasks
     where status in ('succeeded', 'failed', 'canceled')
+      and (:status::text is null or status = :status)
+      and (:name::text is null or name = :name)
       and completed_at_ms is not null
       and completed_at_ms < (extract(epoch from now()) * 1000)::bigint - :older_than_ms
     order by completed_at_ms asc

package/dist/_protocol/sql/sqlite/get_status.sql

@@ -0,0 +1,6 @@
+-- The status-only probe behind wait/call polling. A pending task's whole row is
+-- dead weight to a loop that only asks "is it finished yet" — with a large
+-- payload it re-reads and re-parses megabytes per second of waiting. The full
+-- row is fetched once, via get.sql, when this reports a terminal status.
+-- params: id
+select id, status from cairnq_tasks where id = :id;

package/dist/_protocol/sql/sqlite/get_status_by_key.sql

@@ -0,0 +1,7 @@
+-- get_status.sql, following a key instead of an id — the probe behind
+-- wait_by_key. Resolves the key on every read, so a `replace` landing mid-wait
+-- moves the wait onto the new task.
+-- params: key
+select t.id, t.status from cairnq_tasks t
+join cairnq_task_keys k on k.task_id = t.id
+where k.key = :key;

package/dist/_protocol/sql/sqlite/purge.sql

@@ -5,11 +5,17 @@
 -- task goes with it via cairnq_task_keys' ON DELETE CASCADE.
 -- The LIMIT lives in a subquery: plain `delete ... limit` needs a non-default
 -- SQLite build option.
--- params: before_ms, limit
+-- The status/name filters are optional (pass NULL to skip, as in list.sql):
+-- retention needs are tiered — a succeeded row is spent once its result is
+-- consumed, while a failed one is worth keeping for diagnosis — and without
+-- them the shortest-lived tier sets the retention for every row.
+-- params: before_ms, status, name, limit
 delete from cairnq_tasks
 where id in (
     select id from cairnq_tasks
     where status in ('succeeded', 'failed', 'canceled')
+      and (:status is null or status = :status)
+      and (:name is null or name = :name)
       and completed_at_ms is not null
       and completed_at_ms < :before_ms
     order by completed_at_ms asc

package/dist/client.d.ts

@@ -1,12 +1,15 @@
 import type { BackpressureOptions } from "./backpressure.js";
 import { type RetentionOptions } from "./retention.js";
-import { type Task, type TaskStatus } from "./models.js";
+import { type Task, type TaskRef, type TaskStatus } from "./models.js";
 import type { ListInput, PurgeInput, SubmitInput, TaskStore } from "./store/base.js";
 import { type TaskDef } from "./task.js";
+import { type PollOptions } 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. */
@@ -48,6 +51,11 @@ export declare class CairnQ {
     queueDepth(queue: string, maxDepth: number): Promise<number>;
     get(taskId: string): Promise<Task | null>;
     getByKey(key: string): Promise<Task | null>;
+    /** 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>;
+    getStatusByKey(key: string): Promise<TaskRef | null>;
     list(input?: ListInput): Promise<Task[]>;
     cancel(taskId: string): Promise<Task | null>;
     cancelByKey(key: string): Promise<Task | null>;
@@ -68,19 +76,13 @@ export declare class CairnQ {
     /** 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>;
     /** 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?: {
-        timeoutMs?: number;
-        pollMs?: number;
-    }): Promise<Task>;
+    waitByKey(key: string, opts?: WaitOptions): Promise<Task>;
     /** 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.

package/dist/client.js

@@ -4,7 +4,7 @@ import { isFailed, isSucceeded } from "./models.js";
 import { SQLiteStore } from "./store/sqlite.js";
 import { PostgresStore } from "./store/postgres.js";
 import { taskName } from "./task.js";
-import { pollWait, pollWaitByKey } from "./wait.js";
+import { DEFAULT_WAIT_TIMEOUT_MS, pollWait, pollWaitByKey } from "./wait.js";
 /** API-side handle. Thin wrapper over a TaskStore + SDK-orchestrated wait/call. */
 export class CairnQ {
     _store;
@@ -63,6 +63,15 @@ export class CairnQ {
     getByKey(key) {
         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) {
+        return this._store.getStatus(taskId);
+    }
+    getStatusByKey(key) {
+        return this._store.getStatusByKey(key);
+    }
     list(input) {
         return this._store.list(input);
     }
@@ -94,9 +103,11 @@ export class CairnQ {
      * 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, opts = {}) {
+        // `??`, 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
@@ -106,14 +117,14 @@ export class CairnQ {
      * yet is waited for rather than rejected. */
     waitByKey(key, opts = {}) {
         return pollWaitByKey(this._store, key, {
-            timeoutMs: opts.timeoutMs ?? 30_000,
-            pollMs: opts.pollMs,
+            ...opts,
+            timeoutMs: opts.timeoutMs ?? DEFAULT_WAIT_TIMEOUT_MS,
         });
     }
     async call(task, payload, opts = {}) {
-        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))

package/dist/errors.d.ts

@@ -80,10 +80,12 @@ export declare 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 declare class EventLoopBlocked extends CairnQError {
     readonly lateMs: number;

package/dist/errors.js

@@ -150,10 +150,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 {
     lateMs;
@@ -161,8 +163,9 @@ export class EventLoopBlocked extends CairnQError {
     leaseMs;
     constructor(lateMs, intervalMs, leaseMs) {
         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.lateMs = lateMs;
         this.intervalMs = intervalMs;
         this.leaseMs = leaseMs;

package/dist/index.d.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";
@@ -14,7 +14,7 @@ export { SQLiteStore } from "./store/sqlite.js";
 export { PostgresStore } from "./store/postgres.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 { STATUSES, isTerminal, cancelRequested, isQueued, isRunning, isSucceeded, isFailed, isCanceled, } from "./models.js";
+export type { Task, TaskRef, TaskStatus, TerminalStatus } from "./models.js";
+export { STATUSES, isTerminal, isTerminalStatus, cancelRequested, isQueued, isRunning, isSucceeded, isFailed, isCanceled, } from "./models.js";
 export { CairnQError, AlreadyExists, QueueFull, TaskTimeout, TaskFailed, TaskCanceled, TaskError, LostLease, EventLoopBlocked, ProtocolVersionMismatch, SerializationError, } from "./errors.js";
 export type { FailReason } from "./errors.js";

package/dist/index.js

@@ -7,5 +7,5 @@ export { defineTask } from "./task.js";
 export { SQLiteStore } from "./store/sqlite.js";
 export { PostgresStore } from "./store/postgres.js";
 export { TaskStore } from "./store/base.js";
-export { STATUSES, isTerminal, cancelRequested, isQueued, isRunning, isSucceeded, isFailed, isCanceled, } from "./models.js";
+export { STATUSES, isTerminal, isTerminalStatus, cancelRequested, isQueued, isRunning, isSucceeded, isFailed, isCanceled, } from "./models.js";
 export { CairnQError, AlreadyExists, QueueFull, TaskTimeout, TaskFailed, TaskCanceled, TaskError, LostLease, EventLoopBlocked, ProtocolVersionMismatch, SerializationError, } from "./errors.js";

package/dist/models.d.ts

@@ -25,9 +25,21 @@ export interface Task {
     updated_at_ms: number;
     completed_at_ms: number | null;
 }
-export declare const TERMINAL: TaskStatus[];
+/** 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;
+}
+export declare const TERMINAL: readonly ["succeeded", "failed", "canceled"];
+export type TerminalStatus = (typeof TERMINAL)[number];
+export declare function isTerminalStatus(status: TaskStatus): status is TerminalStatus;
+/** 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 declare function rowToRef(row: Record<string, unknown>): TaskRef;
 export declare function rowToTask(row: Record<string, unknown>): Task;
-export declare function isTerminal(task: Task): boolean;
+/** Accepts anything carrying a status — a Task or a TaskRef probe. */
+export declare function isTerminal(task: Pick<Task, "status">): boolean;
 export declare function cancelRequested(task: Task): boolean;
 export declare const isQueued: (task: Task) => boolean;
 export declare const isRunning: (task: Task) => boolean;

package/dist/models.js

@@ -4,7 +4,17 @@
 // conformance suite pins this set against.
 export const STATUSES = ["queued", "running", "succeeded", "failed", "canceled"];
 const JSON_COLUMNS = ["payload", "result", "error", "metadata"];
+// As a const tuple so TerminalStatus derives from it — the same declare-once
+// pattern as STATUSES/TaskStatus above.
 export const TERMINAL = ["succeeded", "failed", "canceled"];
+export function isTerminalStatus(status) {
+    return TERMINAL.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) {
+    return { id: row.id, status: row.status };
+}
 export function rowToTask(row) {
     const t = { ...row };
     for (const col of JSON_COLUMNS) {
@@ -16,8 +26,9 @@ export function rowToTask(row) {
     }
     return t;
 }
+/** Accepts anything carrying a status — a Task or a TaskRef probe. */
 export function isTerminal(task) {
-    return TERMINAL.includes(task.status);
+    return isTerminalStatus(task.status);
 }
 export function cancelRequested(task) {
     return task.cancel_requested_at_ms != null;

package/dist/retention.d.ts

@@ -1,10 +1,19 @@
-import type { TaskStore } from "./store/base.js";
+import type { TerminalStatus } from "./models.js";
+import { type TaskStore } from "./store/base.js";
+/** 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. */
@@ -42,7 +51,10 @@ export declare class RetentionSweeper {
     /** The loop itself, awaited by stop() so no purge outlives the store. */
     private loop;
     private readonly intervalMs;
-    private readonly purgeInput;
+    /** Rows per purge statement while draining — see DEFAULT_LIMIT. */
+    private readonly limit;
+    /** One purge per cutoff: a lone entry for a number, one per status for a map. */
+    private readonly purgeInputs;
     constructor(store: TaskStore, opts: RetentionOptions);
     start(): void;
     /** Stop sweeping and wait for the sweep in flight, if any. */

package/dist/retention.js

@@ -1,3 +1,4 @@
+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. */
@@ -31,18 +32,35 @@ export class RetentionSweeper {
     /** The loop itself, awaited by stop() so no purge outlives the store. */
     loop = null;
     intervalMs;
-    purgeInput;
+    /** 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;
-        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 = 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)
@@ -86,17 +104,21 @@ export class RetentionSweeper {
      * demand — after a backfill, or from a maintenance command.
      */
     async sweep() {
-        const limit = this.purgeInput.limit;
         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
      * pending sweep must never be the reason a process refuses to exit. */

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
@@ -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, TERMINAL } 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)) {
@@ -65,13 +65,29 @@ const CONFLICTS = ["reuse", "reuse-succeeded", "reject", "replace"];
 function reusable(conflict, status) {
     if (conflict === "replace")
         return false;
-    if (!TERMINAL.includes(status))
+    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",
@@ -159,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.
@@ -232,7 +251,7 @@ export class TaskStore {
                     // 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 (!TERMINAL.includes(current.status)) {
+                    if (!isTerminalStatus(current.status)) {
                         await fetch("cancel", { id: existing[0].task_id });
                     }
                 }
@@ -248,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".
@@ -302,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,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cairnq",
-  "version": "0.7.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,17 +1,19 @@
 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, 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
@@ -99,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);
   }
@@ -136,13 +149,12 @@ export class CairnQ {
   /** 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 +163,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 +180,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/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";
@@ -14,10 +14,11 @@ export { SQLiteStore } from "./store/sqlite.js";
 export { PostgresStore } from "./store/postgres.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 { 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

package/src/store/base.ts

@@ -6,7 +6,15 @@ import {
   ProtocolVersionMismatch,
   SerializationError,
 } from "../errors.js";
-import { rowToTask, STATUSES, TERMINAL, type Task, type TaskStatus } from "../models.js";
+import {
+  isTerminalStatus,
+  rowToRef,
+  rowToTask,
+  STATUSES,
+  type Task,
+  type TaskRef,
+  type TaskStatus,
+} from "../models.js";
 import { type BackpressureOptions, QueueDepthGate } from "../backpressure.js";
 
 const rejectMangled = function (this: unknown, _key: string, v: unknown): unknown {
@@ -77,7 +85,7 @@ export type Conflict = (typeof CONFLICTS)[number];
  */
 function reusable(conflict: Conflict, status: TaskStatus): boolean {
   if (conflict === "replace") return false;
-  if (!TERMINAL.includes(status)) return true;
+  if (!isTerminalStatus(status)) return true;
   return conflict === "reuse-succeeded" && status === "succeeded";
 }
 
@@ -110,8 +118,32 @@ export interface ListInput {
   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 function validatePurgeInput(input: PurgeInput): void {
+  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 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;
 }
 
@@ -234,6 +266,10 @@ export abstract class TaskStore {
     return rows.length ? rowToTask(rows[0]) : null;
   }
 
+  private static oneRef(rows: any[]): TaskRef | null {
+    return rows.length ? rowToRef(rows[0]) : null;
+  }
+
   // ------------------------------------------------------------- client side
   /**
    * Bound how deep a queue may get before `submit` blocks. Off unless set.
@@ -305,7 +341,7 @@ export abstract class TaskStore {
           // 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 (!TERMINAL.includes(current.status as TaskStatus)) {
+          if (!isTerminalStatus(current.status as TaskStatus)) {
             await fetch("cancel", { id: existing[0].task_id });
           }
         }
@@ -324,6 +360,18 @@ export abstract class TaskStore {
     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: string): Promise<TaskRef | null> {
+    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: string): Promise<TaskRef | null> {
+    return TaskStore.oneRef(await this.fetch("get_status_by_key", { key }));
+  }
+
   async list(input: ListInput = {}): Promise<Task[]> {
     // Validate up front, like submit's conflict guard: a typo'd status otherwise
     // matches nothing and returns [] indistinguishably from "no such tasks".
@@ -385,14 +433,11 @@ export abstract class TaskStore {
    * call it in a loop until it returns fewer than `limit`.
    */
   async purge(input: PurgeInput = {}): Promise<string[]> {
-    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 as string);

package/src/wait.ts

@@ -1,8 +1,9 @@
 import { TaskTimeout } from "./errors.js";
 import { nowMs } from "./ids.js";
-import { isTerminal, type Task } from "./models.js";
+import { isTerminal, type Task, type TaskRef } from "./models.js";
 import type { TaskStore } from "./store/base.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;
@@ -11,7 +12,11 @@ const sleep = (ms: number) => new Promise<void>((resolve) => setTimeout(resolve,
 
 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;
 }
 
@@ -28,15 +33,25 @@ export function nextPollMs(current: number, maxMs: number): number {
 }
 
 /**
- * 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(
+  probe: () => Promise<TaskRef | null>,
   read: () => Promise<Task | null>,
-  wake: (task: Task | null, ms: number) => Promise<void>,
+  wake: (ref: TaskRef | null, ms: number) => Promise<void>,
   subject: string,
   key: string | null,
   { timeoutMs, pollMs = DEFAULT_POLL_MS, maxPollMs = MAX_POLL_MS }: PollOptions,
@@ -44,22 +59,27 @@ async function poll(
   const deadline = nowMs() + timeoutMs;
   let interval = pollMs;
   for (;;) {
-    const task = await read();
-    if (task && isTerminal(task)) return task;
+    const ref = await probe();
     const remaining = deadline - nowMs();
-    if (remaining <= 0) throw new TaskTimeout(task?.id ?? subject, { timeoutMs, task, key });
-    await wake(task, Math.min(interval, remaining));
+    // 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;
+    if (remaining <= 0) 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: TaskStore, taskId: string, opts: PollOptions): Promise<Task> {
   return poll(
+    () => store.getStatus(taskId),
     () => store.get(taskId),
-    (_task, ms) => store.taskDoneWake(taskId, ms),
+    (_ref, ms) => store.taskDoneWake(taskId, ms),
     taskId,
     null,
     opts,
@@ -69,7 +89,7 @@ export function pollWait(store: TaskStore, taskId: string, opts: PollOptions): P
 /**
  * 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
@@ -81,8 +101,9 @@ export function pollWait(store: TaskStore, taskId: string, opts: PollOptions): P
  */
 export function pollWaitByKey(store: TaskStore, key: string, opts: PollOptions): Promise<Task> {
   return poll(
+    () => store.getStatusByKey(key),
     () => store.getByKey(key),
-    (task, ms) => (task ? store.taskDoneWake(task.id, ms) : sleep(ms)),
+    (ref, ms) => (ref ? store.taskDoneWake(ref.id, ms) : sleep(ms)),
     key,
     key,
     opts,