cairnq 0.7.0 → 0.9.0

package/README.md

@@ -1,8 +1,12 @@
 # cairnq (TypeScript / Node)
 
 SQLite-first, cross-language, storage-centered durable task runtime. The
-TypeScript SDK (Node ≥ 20, `better-sqlite3`). API and worker processes coordinate
-only through a shared SQLite file.
+TypeScript SDK (Node ≥ 20). API and worker processes coordinate only through a
+shared SQLite file.
+
+Both drivers are optional peers — install the one you use:
+`npm i better-sqlite3` for the SQLite backend, `npm i pg` for Postgres. Importing
+`cairnq` loads neither, so a Postgres-only deployment builds no native module.
 
 ```ts
 import { CairnQ, Worker } from "cairnq";
@@ -75,9 +79,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 } },
 });
 ```
 
@@ -96,5 +102,64 @@ worker.task("long.job", async (ctx) => {
 Same code, Postgres instead of the file — `CairnQ.postgres(dsn)` /
 `Worker.postgres(dsn)`. Requires the optional `pg` peer dependency (`npm i pg`).
 
+### Sharing the application's connection
+
+Given a `PgExecutor` instead of a DSN, cairnq runs inside a session the
+application already has — no second driver, no second pool:
+
+```ts
+import { CairnQ, type PgExecutor } from "cairnq";
+
+const executor: PgExecutor = { /* ~30 lines over your driver */ };
+const tasks = CairnQ.postgres(executor);
+```
+
+`schema` (DSN form only) puts cairnq's tables in a schema of their own:
+`CairnQ.postgres(dsn, { schema: "cairnq" })` creates it if absent and sets
+`search_path` per connection. The protocol's SQL names no schema, so nothing else
+changes. With your own executor, the search_path is yours to set.
+
+Two things an adapter must get right: `int8` has to come back as a JS number
+(every cairnq `*_ms` is an epoch or a counter, all inside the safe range), and
+`jsonb` as an object rather than a string. An executor cairnq was handed is
+never closed by cairnq.
+
+That shared session is also what lets a task's settlement commit together with
+the rows the task produced:
+
+```ts
+worker.task("render.document", async (ctx, payload) => {
+  const rendered = await render(payload);
+  return ctx.succeedIn(async (session) => {
+    await db.withSession(session).insert(pages).values(rendered);
+    return { pages: rendered.length }; // becomes the task's result
+  });
+});
+```
+
+Without it the two are separate transactions, and a crash between them leaves
+work durable while the task still reads as running — on retry, recomputed. If
+the lease turns out to be gone, the settlement matches no row and the caller's
+writes roll back with it.
+
+## Watching
+
+`watch` calls back when the tasks on a queue may have changed — for a dashboard
+that would otherwise poll:
+
+```ts
+const stop = tasks.watch({ queues: ["render"] }, async (signal) => {
+  if (signal.reason === "done") return refreshOne(signal.taskId!);
+  setCounts(await tasks.stats());
+});
+```
+
+It is notify-accelerated polling, not an event log. On Postgres an idle watch
+costs nothing and a signal lands within milliseconds; where LISTEN is
+unavailable — a transaction-mode pooler, or SQLite, which has no channel — the
+timer alone still delivers `poll` signals. So the same consumer is correct either
+way, and only its promptness differs. Treat a signal as "re-read now"; the truth
+is in `stats()` / `list()` / `get()`.
+
 The protocol (schema + canonical SQL) lives in `../cairnq-protocol` and is shared
 verbatim with the Python SDK. See `../cairnq-protocol/PROTOCOL.md`.

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,16 @@
 import type { BackpressureOptions } from "./backpressure.js";
 import { type RetentionOptions } from "./retention.js";
-import { type Task, type TaskStatus } from "./models.js";
-import type { ListInput, PurgeInput, SubmitInput, TaskStore } from "./store/base.js";
+import { type Task, type TaskRef, type TaskStatus } from "./models.js";
+import type { PgExecutor } from "./store/pg-executor.js";
+import type { ListInput, PurgeInput, SubmitInput, TaskStore, WatchOptions, WatchSignal } 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. */
@@ -25,10 +29,13 @@ export declare class CairnQ {
     static sqlite(path: string, opts?: {
         busyTimeoutMs?: number;
     } & ClientOptions): CairnQ;
-    /** Multi-host backend. `dsn` is a libpq connection string; requires the
-     * optional `pg` package. */
-    static postgres(dsn: string, opts?: {
+    /** Multi-host backend. `source` is a libpq connection string — which requires
+     * the optional `pg` package — or a PgExecutor over a driver the application
+     * already runs (an ORM's pool, say), which cairnq then shares instead of
+     * opening a second one. */
+    static postgres(source: string | PgExecutor, opts?: {
         max?: number;
+        schema?: string;
     } & ClientOptions): CairnQ;
     get store(): TaskStore;
     connect(): Promise<void>;
@@ -48,6 +55,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>;
@@ -65,22 +77,27 @@ 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>>>;
+    /**
+     * Call `onSignal` when the tasks on `queues` may have changed. Returns an
+     * unsubscribe.
+     *
+     * Notify-accelerated polling, not an event log: a signal means "re-read now",
+     * and `stats()` / `list()` / `get()` are where the truth is. On Postgres an
+     * idle watch costs nothing and signals land in milliseconds; everywhere else
+     * the timer alone still delivers, so the same consumer code is correct either
+     * way. See TaskStore.watch for the full contract.
+     */
+    watch(opts: WatchOptions, onSignal: (signal: WatchSignal) => void): () => void;
     /** 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;
@@ -29,11 +29,13 @@ export class CairnQ {
         const { busyTimeoutMs, ...client } = opts;
         return new CairnQ(new SQLiteStore(path, { busyTimeoutMs }), client);
     }
-    /** Multi-host backend. `dsn` is a libpq connection string; requires the
-     * optional `pg` package. */
-    static postgres(dsn, opts = {}) {
-        const { max, ...client } = opts;
-        return new CairnQ(new PostgresStore(dsn, { max }), client);
+    /** Multi-host backend. `source` is a libpq connection string — which requires
+     * the optional `pg` package — or a PgExecutor over a driver the application
+     * already runs (an ORM's pool, say), which cairnq then shares instead of
+     * opening a second one. */
+    static postgres(source, opts = {}) {
+        const { max, schema, ...client } = opts;
+        return new CairnQ(new PostgresStore(source, { max, schema }), client);
     }
     get store() {
         return this._store;
@@ -63,6 +65,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);
     }
@@ -90,13 +101,28 @@ export class CairnQ {
     stats() {
         return this._store.stats();
     }
+    /**
+     * Call `onSignal` when the tasks on `queues` may have changed. Returns an
+     * unsubscribe.
+     *
+     * Notify-accelerated polling, not an event log: a signal means "re-read now",
+     * and `stats()` / `list()` / `get()` are where the truth is. On Postgres an
+     * idle watch costs nothing and signals land in milliseconds; everywhere else
+     * the timer alone still delivers, so the same consumer code is correct either
+     * way. See TaskStore.watch for the full contract.
+     */
+    watch(opts, onSignal) {
+        return this._store.watch(opts, onSignal);
+    }
     /** Wait for a task to finish. Resolves with the terminal Task (any status);
      * throws TaskTimeout without stopping the task, so `wait(err.taskId)` picks the
      * same wait back up — from another process, or after a longer deadline. */
     wait(taskId, 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 +132,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/context.d.ts

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

package/dist/context.js

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

package/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";
@@ -12,9 +12,13 @@ export { defineTask } from "./task.js";
 export type { TaskDef } from "./task.js";
 export { SQLiteStore } from "./store/sqlite.js";
 export { PostgresStore } from "./store/postgres.js";
+export { ListenUnavailable } from "./store/pg-executor.js";
+export type { PgExecutor, PgSession, Row } from "./store/pg-executor.js";
+export { createPoolExecutor } from "./store/pg-pool.js";
 export { TaskStore } from "./store/base.js";
-export type { ListInput, PurgeInput, SubmitInput, Conflict } from "./store/base.js";
-export type { Task, TaskStatus } from "./models.js";
-export { STATUSES, isTerminal, cancelRequested, isQueued, isRunning, isSucceeded, isFailed, isCanceled, } from "./models.js";
+export type { ListInput, PurgeInput, SubmitInput, Conflict, WatchOptions, WatchSignal, } from "./store/base.js";
+export { DEFAULT_WATCH_POLL_MS } from "./store/base.js";
+export type { Task, TaskRef, TaskStatus, TerminalStatus } from "./models.js";
+export { STATUSES, isTerminal, isTerminalStatus, cancelRequested, isQueued, isRunning, 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

@@ -6,6 +6,9 @@ export { TaskContext } from "./context.js";
 export { defineTask } from "./task.js";
 export { SQLiteStore } from "./store/sqlite.js";
 export { PostgresStore } from "./store/postgres.js";
+export { ListenUnavailable } from "./store/pg-executor.js";
+export { createPoolExecutor } from "./store/pg-pool.js";
 export { TaskStore } from "./store/base.js";
-export { STATUSES, isTerminal, cancelRequested, isQueued, isRunning, isSucceeded, isFailed, isCanceled, } from "./models.js";
+export { DEFAULT_WATCH_POLL_MS } from "./store/base.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. */