cairnq 0.8.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";
@@ -98,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/client.d.ts

@@ -1,7 +1,8 @@
 import type { BackpressureOptions } from "./backpressure.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 { 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">;
@@ -28,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>;
@@ -73,6 +77,17 @@ 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. */

package/dist/client.js

@@ -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;
@@ -99,6 +101,19 @@ 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. */

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/index.d.ts

@@ -12,8 +12,12 @@ 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 { 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";

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 { 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/store/base.d.ts

@@ -83,6 +83,32 @@ export declare function statementParams(sql: string): readonly string[];
  * them in one place is what stops SQLite and Postgres from drifting apart in
  * behavior; the shared SQL already stops them from drifting in wording.
  */
+/**
+ * Why `watch` is calling back.
+ *
+ * `queued` / `done` come from the store's push channel and name what moved;
+ * `poll` is the timer saying the watch cannot rule out a change. None of them
+ * carries state — the row is the truth.
+ */
+export interface WatchSignal {
+    reason: "queued" | "done" | "poll";
+    /** The queue a task was queued on. Only on `queued`. */
+    queue?: string;
+    /** The task that reached a terminal status. Only on `done`. */
+    taskId?: string;
+}
+export interface WatchOptions {
+    /** Restrict `queued` signals to these queues. Unset watches every queue. */
+    queues?: string[];
+    /**
+     * How often to signal in the absence of a push channel — and, where there is
+     * one, how long a dropped listener can go unnoticed. The default trades a
+     * dashboard's idle query rate against how stale it may look.
+     */
+    pollMs?: number;
+}
+/** See WatchOptions.pollMs. */
+export declare const DEFAULT_WATCH_POLL_MS = 2000;
 export declare abstract class TaskStore {
     /** Set by useBackpressure; null means submit is ungated. */
     private gate;
@@ -100,6 +126,34 @@ export declare abstract class TaskStore {
      * build ids and payloads before opening the transaction, not within it.
      */
     protected abstract tx<T>(fn: (fetch: Fetch) => Promise<T>): Promise<T>;
+    /**
+     * `tx`, but also handing `fn` the driver's own session so the CALLER can run
+     * their statements in the same transaction as the protocol's.
+     *
+     * This is what lets a task's settlement and the rows that task produced commit
+     * together. Without it the two are separate transactions and there is a window
+     * where the work is durable but the task still reads as unfinished — a crash
+     * there costs a full recomputation on retry, and for non-idempotent work costs
+     * more than that.
+     *
+     * Optional, because the session type is the driver's, not the protocol's: a
+     * store that has no session worth handing out simply does not implement it and
+     * `completeIn` reports that. Postgres implements it; SQLite does not.
+     */
+    protected txWithSession?<T>(fn: (fetch: Fetch, session: unknown) => Promise<T>): Promise<T>;
+    /**
+     * Register for this store's push channel, if it has one; returns an
+     * unsubscribe. A store without a push channel does not implement this, and
+     * `watch` degrades to its timer alone.
+     */
+    protected subscribePush?(onSignal: (signal: WatchSignal) => void): () => void;
+    /**
+     * Nudge the push channel back up if it has dropped. Called from `watch`'s
+     * timer, which is the only thing keeping a client-side subscriber alive: a
+     * process that never claims never calls claimWake, so without this a listener
+     * that died once would never come back there.
+     */
+    protected warmPush?(): void;
     /**
      * Whether it is worth opening the claim transaction at all. SQLite gates its
      * single write lock behind a read-only probe; Postgres readers don't block
@@ -169,6 +223,28 @@ export declare abstract class TaskStore {
      * them.
      */
     stats(): Promise<Record<string, Record<TaskStatus, number>>>;
+    /**
+     * Call `onSignal` when the tasks on `queues` may have changed — something was
+     * queued, or something finished.
+     *
+     * This is notify-ACCELERATED POLLING, not an event log, and the difference is
+     * the whole contract. Where a push channel is available (Postgres LISTEN) an
+     * idle watch costs nothing and a signal arrives within milliseconds of the
+     * event. Where it is not — a transaction-mode pooler refuses LISTEN, SQLite has
+     * no channel at all — the timer alone still delivers `poll` signals, so a
+     * consumer that re-reads on every signal is correct in both cases and merely
+     * less prompt in one.
+     *
+     * What it will NOT do is promise that a signal means something happened, or
+     * that every event produces its own signal. Treat a signal as "re-read now"
+     * and take the truth from `stats()` / `list()` / `get()`, which is where it
+     * lives. `reason` is a hint for reading less: a `done` signal names the task,
+     * so a dashboard can refresh that row instead of the list.
+     *
+     * Returns an unsubscribe. The timer is unref'd — watching does not hold a
+     * process open.
+     */
+    watch(opts: WatchOptions, onSignal: (signal: WatchSignal) => void): () => void;
     /**
      * How many more tasks fit on `queue` under `maxDepth` — 0 once it is full.
      *
@@ -262,6 +338,29 @@ export declare abstract class TaskStore {
         workerId: string;
         result: unknown;
     }): Promise<Task>;
+    /**
+     * `complete`, with the caller's own writes committed in the same transaction.
+     *
+     * `fn` runs first and whatever it returns becomes the task's result; the
+     * settlement is the last statement in the transaction. So a lost lease — the
+     * settlement matching no row — rolls the caller's writes back with it, and
+     * there is no ordering in which the work is recorded but the task is not.
+     *
+     * The settlement runs LAST rather than checking ownership up front on purpose:
+     * the ownership predicate lives in the protocol's complete.sql, and a
+     * fail-fast pre-check here would be a second copy of it, free to drift. The
+     * cost of that choice is that a doomed attempt does its work before finding
+     * out, which is the rare path.
+     *
+     * `fn` must be replayable for the same reason `tx`'s callback must be.
+     */
+    completeIn<S, T>(input: {
+        taskId: string;
+        workerId: string;
+    }, fn: (session: S) => Promise<T>): Promise<{
+        task: Task;
+        value: T;
+    }>;
     fail(input: {
         taskId: string;
         workerId: string;

package/dist/store/base.js

@@ -122,17 +122,8 @@ export function statementParams(sql) {
     }
     return names;
 }
-/**
- * The storage seam.
- *
- * A backend supplies three things: how to run one protocol statement, how to run
- * several inside a transaction, and how its dialect binds parameters. Everything
- * above that — the submit conflict branches, the *_by_key lookups, the
- * recover-then-claim sequence, the ownership-checked writes — lives here once,
- * because those are protocol decisions rather than storage decisions. Keeping
- * them in one place is what stops SQLite and Postgres from drifting apart in
- * behavior; the shared SQL already stops them from drifting in wording.
- */
+/** See WatchOptions.pollMs. */
+export const DEFAULT_WATCH_POLL_MS = 2_000;
 export class TaskStore {
     /** Set by useBackpressure; null means submit is ungated. */
     gate = null;
@@ -354,6 +345,57 @@ export class TaskStore {
         }
         return out;
     }
+    /**
+     * Call `onSignal` when the tasks on `queues` may have changed — something was
+     * queued, or something finished.
+     *
+     * This is notify-ACCELERATED POLLING, not an event log, and the difference is
+     * the whole contract. Where a push channel is available (Postgres LISTEN) an
+     * idle watch costs nothing and a signal arrives within milliseconds of the
+     * event. Where it is not — a transaction-mode pooler refuses LISTEN, SQLite has
+     * no channel at all — the timer alone still delivers `poll` signals, so a
+     * consumer that re-reads on every signal is correct in both cases and merely
+     * less prompt in one.
+     *
+     * What it will NOT do is promise that a signal means something happened, or
+     * that every event produces its own signal. Treat a signal as "re-read now"
+     * and take the truth from `stats()` / `list()` / `get()`, which is where it
+     * lives. `reason` is a hint for reading less: a `done` signal names the task,
+     * so a dashboard can refresh that row instead of the list.
+     *
+     * Returns an unsubscribe. The timer is unref'd — watching does not hold a
+     * process open.
+     */
+    watch(opts, onSignal) {
+        const pollMs = Math.max(1, opts.pollMs ?? DEFAULT_WATCH_POLL_MS);
+        const queues = opts.queues ?? null;
+        let live = true;
+        const emit = (signal) => {
+            // A signal delivered after unsubscribe would have the consumer re-reading
+            // a store it has stopped caring about, possibly a closed one.
+            if (live)
+                onSignal(signal);
+        };
+        const unsubscribe = this.subscribePush?.((signal) => {
+            // A queued signal names its queue, so a watch scoped to some queues can
+            // drop the rest. A done signal names only the task — which queue it was on
+            // is not in the notification, so it is never filtered out.
+            if (signal.reason === "queued" && queues && signal.queue && !queues.includes(signal.queue)) {
+                return;
+            }
+            emit(signal);
+        });
+        const timer = setInterval(() => {
+            this.warmPush?.();
+            emit({ reason: "poll" });
+        }, pollMs);
+        timer.unref?.();
+        return () => {
+            live = false;
+            unsubscribe?.();
+            clearInterval(timer);
+        };
+    }
     /**
      * How many more tasks fit on `queue` under `maxDepth` — 0 once it is full.
      *
@@ -504,6 +546,40 @@ export class TaskStore {
             result: input.result == null ? null : dumpJson(input.result),
         });
     }
+    /**
+     * `complete`, with the caller's own writes committed in the same transaction.
+     *
+     * `fn` runs first and whatever it returns becomes the task's result; the
+     * settlement is the last statement in the transaction. So a lost lease — the
+     * settlement matching no row — rolls the caller's writes back with it, and
+     * there is no ordering in which the work is recorded but the task is not.
+     *
+     * The settlement runs LAST rather than checking ownership up front on purpose:
+     * the ownership predicate lives in the protocol's complete.sql, and a
+     * fail-fast pre-check here would be a second copy of it, free to drift. The
+     * cost of that choice is that a doomed attempt does its work before finding
+     * out, which is the rare path.
+     *
+     * `fn` must be replayable for the same reason `tx`'s callback must be.
+     */
+    async completeIn(input, fn) {
+        if (!this.txWithSession) {
+            throw new Error("this store cannot share a transaction with the caller — " +
+                "completeIn requires a Postgres store (see PgExecutor)");
+        }
+        return this.txWithSession(async (fetch, session) => {
+            const value = await fn(session);
+            const rows = await fetch("complete", {
+                id: input.taskId,
+                worker_id: input.workerId,
+                result: value == null ? null : dumpJson(value),
+            });
+            // Rolls back `fn`'s writes along with the settlement that did not land.
+            if (!rows.length)
+                throw new LostLease(input.taskId);
+            return { task: rowToTask(rows[0]), value };
+        });
+    }
     async fail(input) {
         let error;
         try {

package/dist/store/pg-executor.d.ts

@@ -0,0 +1,77 @@
+/**
+ * The seam between PostgresStore and whatever actually talks to Postgres.
+ *
+ * PostgresStore owns the *dialect* — the protocol's named-parameter SQL rewritten
+ * to `$n`, the migration ledger, the LISTEN policy. It does not own the
+ * *connection*. Applications that already run a Postgres driver (an ORM, a pool
+ * they size themselves) pass their own executor and cairnq joins that session
+ * instead of opening a second one, which is what makes a task's settlement
+ * commit in the same transaction as the rows the task produced.
+ *
+ * Implementing one is small — see `createPoolExecutor` below for the reference
+ * implementation over `pg`, and PROTOCOL.md for the two things an adapter must
+ * get right that are easy to miss: int8 must come back as a JS number (every
+ * cairnq bigint is an epoch-ms or a counter, all inside the safe range), and
+ * jsonb must come back as an object, not a string.
+ */
+/** A row as the driver hands it back: column name -> value. */
+export type Row = Record<string, unknown>;
+/**
+ * Somewhere statements can run. The same shape whether it is a pool (each call
+ * on some connection) or one transaction's dedicated connection — the store's
+ * statements do not care, and this is what lets `tx` hand the same interface to
+ * its callback.
+ */
+export interface PgSession {
+    /**
+     * One parameterised statement, `$1`-style. `values` is positional and may
+     * legitimately contain nulls — a null parameter is "this filter is off" in
+     * several protocol statements, not a missing argument.
+     */
+    query(text: string, values: readonly unknown[]): Promise<Row[]>;
+    /**
+     * Parameterless SQL that may hold several statements, for migration DDL.
+     * Separate from `query` because it must go over the simple query protocol:
+     * the extended protocol a parameterised call uses accepts only one statement,
+     * and every migration is a script.
+     */
+    exec(sql: string): Promise<void>;
+}
+/** A session that can also open transactions, listen, and be shut down. */
+export interface PgExecutor extends PgSession {
+    /**
+     * Run `fn` inside one transaction on one dedicated connection, committing if
+     * it returns and rolling back if it throws. The store relies on both halves:
+     * a claim that cannot see its own `recover_leases` is a double-dispatch, and a
+     * keyed submit that commits half way poisons the key.
+     */
+    tx<T>(fn: (session: PgSession) => Promise<T>): Promise<T>;
+    /**
+     * Subscribe a dedicated connection to `channels`. Optional: an executor that
+     * omits it (or a Postgres that refuses LISTEN) costs latency, never
+     * correctness — the store falls back to plain polling, which is the contract
+     * PROTOCOL.md gives for push wakeups.
+     *
+     * Resolves with a function that stops listening. `onClose` reports a
+     * connection that dropped on its own, so the store can degrade and retry.
+     *
+     * Throw `ListenUnavailable` when this Postgres will never accept LISTEN — a
+     * transaction-mode pooler, say. Any other rejection is read as transient and
+     * retried with backoff, so a permanent condition raised as a plain Error
+     * becomes a reconnect loop that cannot succeed.
+     */
+    listen?(channels: readonly string[], onNotify: (channel: string, payload: string | undefined) => void, onClose: () => void): Promise<() => void>;
+    /**
+     * Release this executor's resources. Called by PostgresStore.close() ONLY for
+     * an executor the store created itself: an injected one belongs to the caller,
+     * whose other work would not survive cairnq closing it.
+     */
+    close(): Promise<void>;
+}
+/**
+ * LISTEN will not work on this connection, and retrying cannot change that.
+ * See `PgExecutor.listen`.
+ */
+export declare class ListenUnavailable extends Error {
+    constructor(message?: string);
+}

package/dist/store/pg-executor.js

@@ -0,0 +1,26 @@
+/**
+ * The seam between PostgresStore and whatever actually talks to Postgres.
+ *
+ * PostgresStore owns the *dialect* — the protocol's named-parameter SQL rewritten
+ * to `$n`, the migration ledger, the LISTEN policy. It does not own the
+ * *connection*. Applications that already run a Postgres driver (an ORM, a pool
+ * they size themselves) pass their own executor and cairnq joins that session
+ * instead of opening a second one, which is what makes a task's settlement
+ * commit in the same transaction as the rows the task produced.
+ *
+ * Implementing one is small — see `createPoolExecutor` below for the reference
+ * implementation over `pg`, and PROTOCOL.md for the two things an adapter must
+ * get right that are easy to miss: int8 must come back as a JS number (every
+ * cairnq bigint is an epoch-ms or a counter, all inside the safe range), and
+ * jsonb must come back as an object, not a string.
+ */
+/**
+ * LISTEN will not work on this connection, and retrying cannot change that.
+ * See `PgExecutor.listen`.
+ */
+export class ListenUnavailable extends Error {
+    constructor(message = "LISTEN is not available on this connection") {
+        super(message);
+        this.name = "ListenUnavailable";
+    }
+}

package/dist/store/pg-pool.d.ts

@@ -0,0 +1,16 @@
+import { type PgExecutor } from "./pg-executor.js";
+/**
+ * The built-in executor: a `pg.Pool` over a libpq DSN. What `CairnQ.postgres(dsn)`
+ * uses, and the reference for what an adapter over another driver must do.
+ *
+ * Creating it does not connect — `pg.Pool` is lazy, and the store's first
+ * statement (the migration ledger) is what proves the database is reachable.
+ *
+ * `schema` puts cairnq's tables in a schema of their own rather than in whatever
+ * the connection's search_path leads with. The protocol's SQL names no schema, so
+ * this is a per-connection `search_path` and not one statement changes.
+ */
+export declare function createPoolExecutor(dsn: string, opts?: {
+    max?: number;
+    schema?: string;
+}): Promise<PgExecutor>;