cairnq 0.6.0 → 0.8.0

package/README.md

@@ -34,7 +34,9 @@ try {
 } catch (err) {
   if (err instanceof TaskFailed) log(err.code, err.message, err.retryable); // envelope fields
   else if (err instanceof TaskTimeout) {
-    /* err.taskId keeps running */
+    // The task keeps running — resume the wait instead of submitting again.
+    const result = await tasks.wait(err.taskId, { timeoutMs: 60_000 });
+    // …or tasks.waitByKey(key), from a process that never held the id.
   }
 }
 ```
@@ -72,8 +74,13 @@ const worker = Worker.sqlite("tasks.db", {
   onError: (err, info) => log.warn({ err, ...info }), // claims/writes the loop survived
 });
 
-// Nothing else deletes rows. Sweep terminal tasks on a schedule.
-await tasks.purge({ olderThanMs: 7 * 24 * 3600_000 });
+// 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. 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: { succeeded: 300_000, failed: 7 * 24 * 3600_000 } },
+});
 ```
 
 A handler that does real side effects should bail out when it loses its lease —

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,18 +1,29 @@
 import type { BackpressureOptions } from "./backpressure.js";
-import { type Task, type TaskStatus } from "./models.js";
+import { type RetentionOptions } from "./retention.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. */
-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 declare class CairnQ {
     private readonly _store;
+    /** null unless `retention` was configured. */
+    private readonly sweeper;
     constructor(_store: TaskStore, opts?: ClientOptions);
     static sqlite(path: string, opts?: {
         busyTimeoutMs?: number;
@@ -24,6 +35,8 @@ export declare class CairnQ {
     } & ClientOptions): CairnQ;
     get store(): TaskStore;
     connect(): Promise<void>;
+    /** Stop retention (waiting for a sweep in flight, so no purge outlives the
+     * store) and close the store. */
     close(): Promise<void>;
     /** Enqueue a task. With `maxQueueDepth` configured this blocks while the
      * target queue is at its limit, and raises QueueFull if it stays there for
@@ -38,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>;
@@ -55,13 +73,23 @@ export declare class CairnQ {
     /** Task counts per queue, keyed by status and zero-filled across all statuses
      * — `(await stats()).default.queued` is the backlog of a queue. */
     stats(): Promise<Record<string, Record<TaskStatus, number>>>;
-    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>;
+    /** 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>;
     /** 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. */
     call(name: string, payload?: unknown, opts?: CallOptions): Promise<unknown>;
     call<P, R>(task: TaskDef<P, R>, payload?: P, opts?: CallOptions): Promise<R>;
 }

package/dist/client.js

@@ -1,12 +1,15 @@
+import { RetentionSweeper } from "./retention.js";
 import { TaskCanceled, TaskFailed } from "./errors.js";
 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 } 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;
+    /** null unless `retention` was configured. */
+    sweeper;
     constructor(_store, opts = {}) {
         this._store = _store;
         // Installed on the store, not held here: every submit path goes through the
@@ -14,6 +17,13 @@ export class CairnQ {
         if (opts.maxQueueDepth != null) {
             _store.useBackpressure(opts);
         }
+        // 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, opts = {}) {
         const { busyTimeoutMs, ...client } = opts;
@@ -31,8 +41,11 @@ export class CairnQ {
     connect() {
         return this._store.connect();
     }
-    close() {
-        return this._store.close();
+    /** Stop retention (waiting for a sweep in flight, so no purge outlives the
+     * store) and close the store. */
+    async close() {
+        await this.sweeper?.stop();
+        await this._store.close();
     }
     submit(task, payload, opts = {}) {
         return this._store.submit({ name: taskName(task), payload, ...opts });
@@ -50,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);
     }
@@ -77,16 +99,32 @@ export class CairnQ {
     stats() {
         return this._store.stats();
     }
+    /** 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, 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
+     * 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, opts = {}) {
+        return pollWaitByKey(this._store, key, {
+            ...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

@@ -35,16 +35,24 @@ export declare class QueueFull extends CairnQError {
     waitedMs: number;
     constructor(queue: string, maxDepth: number, waitedMs: number);
 }
-/** wait/call did not reach a terminal status in time. The task keeps running.
- * `task` is the last snapshot wait() observed (null if get() found nothing), and
- * the message says what state it was stuck in — a queued-never-claimed task is
- * the classic first-run failure (no worker, no handler, wrong queue or file). */
+/** wait/call did not reach a terminal status in time. The task keeps running, so
+ * `taskId` is the handle for picking the wait back up — `wait(err.taskId)`
+ * re-attaches to the same task from anywhere that can reach the store. `task` is
+ * the last snapshot wait() observed (null if the lookup found nothing), and the
+ * message says what state it was stuck in — a queued-never-claimed task is the
+ * classic first-run failure (no worker, no handler, wrong queue or file).
+ *
+ * `key` is set when the wait watched a key rather than an id; `taskId` is then
+ * the task the key pointed at, or the key itself when it pointed at nothing —
+ * there was no id to report. */
 export declare class TaskTimeout extends CairnQError {
     taskId: string;
     readonly task: Task | null;
+    readonly key: string | null;
     constructor(taskId: string, opts?: {
         timeoutMs?: number;
         task?: Task | null;
+        key?: string | null;
     });
 }
 /** A waited-on task ended in `failed`. The envelope's fields are unpacked onto the
@@ -62,6 +70,29 @@ export declare class TaskCanceled extends CairnQError {
     taskId: string;
     constructor(taskId: string);
 }
+/**
+ * A heartbeat beat came back later than its own interval allowed.
+ *
+ * The heartbeat shares the event loop with the handlers whose leases it renews,
+ * so a handler that blocks the loop stops the renewal with it: the lease expires,
+ * the task is recovered and redelivered, and a second worker starts computing
+ * what the first is still computing — one task, billed twice, with no error
+ * 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 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. 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;
+    readonly intervalMs: number;
+    readonly leaseMs: number;
+    constructor(lateMs: number, intervalMs: number, leaseMs: number);
+}
 /** A worker write affected 0 rows: the lease expired and was reclaimed. */
 export declare class LostLease extends CairnQError {
     taskId: string;

package/dist/errors.js

@@ -67,9 +67,12 @@ export class QueueFull extends CairnQError {
  * observed. No worker running, no handler for the name, wrong queue, and two
  * processes on different database files all look identical from the API side —
  * queued, never claimed — so that case names the likely causes. */
-function timeoutDetail(task) {
-    if (!task)
-        return "task not found — wrong database file, or already purged?";
+function timeoutDetail(task, key) {
+    if (!task) {
+        return key === null
+            ? "task not found — wrong database file, or already purged?"
+            : "no task under this key — never submitted, or already purged?";
+    }
     if (isQueued(task)) {
         const delayMs = task.run_at_ms - nowMs();
         if (task.attempt === 0 && delayMs <= 0) {
@@ -83,20 +86,30 @@ function timeoutDetail(task) {
         return "cancel requested, waiting for the handler to observe it";
     return `still running (attempt ${task.attempt}/${task.max_attempts})`;
 }
-/** wait/call did not reach a terminal status in time. The task keeps running.
- * `task` is the last snapshot wait() observed (null if get() found nothing), and
- * the message says what state it was stuck in — a queued-never-claimed task is
- * the classic first-run failure (no worker, no handler, wrong queue or file). */
+/** wait/call did not reach a terminal status in time. The task keeps running, so
+ * `taskId` is the handle for picking the wait back up — `wait(err.taskId)`
+ * re-attaches to the same task from anywhere that can reach the store. `task` is
+ * the last snapshot wait() observed (null if the lookup found nothing), and the
+ * message says what state it was stuck in — a queued-never-claimed task is the
+ * classic first-run failure (no worker, no handler, wrong queue or file).
+ *
+ * `key` is set when the wait watched a key rather than an id; `taskId` is then
+ * the task the key pointed at, or the key itself when it pointed at nothing —
+ * there was no id to report. */
 export class TaskTimeout extends CairnQError {
     taskId;
     task;
+    key;
     constructor(taskId, opts = {}) {
+        const key = opts.key ?? null;
+        const subject = key === null ? `task ${taskId}` : `key ${key}`;
         super(opts.timeoutMs == null
-            ? `task ${taskId} did not finish in time`
-            : `task ${taskId} did not finish within ${opts.timeoutMs}ms: ${timeoutDetail(opts.task ?? null)}`);
+            ? `${subject} did not finish in time`
+            : `${subject} did not finish within ${opts.timeoutMs}ms: ${timeoutDetail(opts.task ?? null, key)}`);
         this.taskId = taskId;
         this.name = "TaskTimeout";
         this.task = opts.task ?? null;
+        this.key = key;
     }
 }
 /** A waited-on task ended in `failed`. The envelope's fields are unpacked onto the
@@ -127,6 +140,38 @@ export class TaskCanceled extends CairnQError {
         this.name = "TaskCanceled";
     }
 }
+/**
+ * A heartbeat beat came back later than its own interval allowed.
+ *
+ * The heartbeat shares the event loop with the handlers whose leases it renews,
+ * so a handler that blocks the loop stops the renewal with it: the lease expires,
+ * the task is recovered and redelivered, and a second worker starts computing
+ * what the first is still computing — one task, billed twice, with no error
+ * 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 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. 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;
+    intervalMs;
+    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, 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;
+        this.name = "EventLoopBlocked";
+    }
+}
 /** A worker write affected 0 rows: the lease expired and was reclaimed. */
 export class LostLease extends CairnQError {
     taskId;

package/dist/index.d.ts

@@ -1,7 +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 { RetentionCutoffs, RetentionOptions } from "./retention.js";
 export { Worker } from "./worker.js";
 export type { BatchHandler, Handler, TypedHandler, WorkerOptions } from "./worker.js";
 export { TaskContext } from "./context.js";
@@ -12,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 { CairnQError, AlreadyExists, QueueFull, TaskTimeout, TaskFailed, TaskCanceled, TaskError, LostLease, ProtocolVersionMismatch, SerializationError, } from "./errors.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

@@ -1,10 +1,11 @@
 export { CairnQ } from "./client.js";
 export { QueueDepthGate } from "./backpressure.js";
+export { RetentionSweeper } from "./retention.js";
 export { Worker } from "./worker.js";
 export { TaskContext } from "./context.js";
 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 { CairnQError, AlreadyExists, QueueFull, TaskTimeout, TaskFailed, TaskCanceled, TaskError, LostLease, ProtocolVersionMismatch, SerializationError, } from "./errors.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

@@ -0,0 +1,72 @@
+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 | RetentionCutoffs;
+    /** Time between sweeps. Default 3_600_000 (one hour). */
+    intervalMs?: number;
+    /** Rows deleted per statement while draining. Default 1_000. */
+    limit?: number;
+    /**
+     * Called for a sweep that threw. The next sweep runs on schedule regardless —
+     * a purge that failed because the database was busy is not a reason to stop
+     * retaining — so without this a store quietly stops being swept. Must not throw.
+     */
+    onError?: (err: unknown) => void;
+}
+/**
+ * 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 declare class RetentionSweeper {
+    private readonly store;
+    private readonly opts;
+    /** Whether the scheduled loop is running. */
+    private active;
+    /** Set by stop(), so a drain in progress can cut itself short too. */
+    private stopping;
+    /** Resolves the current sleep early, so stop() need not wait out an interval. */
+    private wake;
+    /** The loop itself, awaited by stop() so no purge outlives the store. */
+    private loop;
+    private readonly intervalMs;
+    /** 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. */
+    stop(): Promise<void>;
+    private run;
+    /**
+     * 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.
+     */
+    sweep(): Promise<number>;
+    /** Sleep, interruptible by stop(). Unref'd: retention is housekeeping, and a
+     * pending sweep must never be the reason a process refuses to exit. */
+    private sleep;
+}