cairnq 0.7.0 → 0.9.0

package/dist/retention.js

@@ -1,3 +1,4 @@
+import { validatePurgeInput } from "./store/base.js";
 /** Sweep every hour unless asked otherwise — often enough that a queue with a
  * day of retention never carries more than an hour of extra rows, rare enough
  * that the sweep is invisible next to the task traffic. */
@@ -31,18 +32,35 @@ export class RetentionSweeper {
     /** The loop itself, awaited by stop() so no purge outlives the store. */
     loop = null;
     intervalMs;
-    purgeInput;
+    /** Rows per purge statement while draining — see DEFAULT_LIMIT. */
+    limit;
+    /** One purge per cutoff: a lone entry for a number, one per status for a map. */
+    purgeInputs;
     constructor(store, opts) {
         this.store = store;
         this.opts = opts;
-        if (!Number.isFinite(opts.olderThanMs) || opts.olderThanMs < 0) {
-            throw new Error(`retention.olderThanMs must be >= 0, got ${opts.olderThanMs}`);
-        }
         this.intervalMs = opts.intervalMs ?? DEFAULT_INTERVAL_MS;
         if (!Number.isFinite(this.intervalMs) || this.intervalMs < 1) {
             throw new Error(`retention.intervalMs must be >= 1, got ${this.intervalMs}`);
         }
-        this.purgeInput = { olderThanMs: opts.olderThanMs, limit: opts.limit ?? DEFAULT_LIMIT };
+        this.limit = opts.limit ?? DEFAULT_LIMIT;
+        const cutoffs = typeof opts.olderThanMs === "number"
+            ? [[undefined, opts.olderThanMs]]
+            : Object.entries(opts.olderThanMs);
+        // An empty map retains nothing and sweeps nothing — almost certainly a bug
+        // upstream of this call, so refuse it rather than silently never purging.
+        if (!cutoffs.length) {
+            throw new Error("retention.olderThanMs must name at least one status");
+        }
+        this.purgeInputs = cutoffs.map(([status, ms]) => ({
+            olderThanMs: ms,
+            status,
+            limit: this.limit,
+        }));
+        // Fail fast on the store's own purge rules (terminal status, cutoff >= 0):
+        // the sweep runs an hour from now, and its errors only surface via onError.
+        for (const input of this.purgeInputs)
+            validatePurgeInput(input);
     }
     start() {
         if (this.active)
@@ -86,17 +104,21 @@ export class RetentionSweeper {
      * demand — after a backfill, or from a maintenance command.
      */
     async sweep() {
-        const limit = this.purgeInput.limit;
         let deleted = 0;
-        for (;;) {
-            const ids = await this.store.purge(this.purgeInput);
-            deleted += ids.length;
-            if (ids.length < limit || this.stopping)
-                return deleted;
-            // Hand the loop back between batches: a large drain must not starve the
-            // submits and claims sharing this process.
-            await this.sleep(0);
+        for (const input of this.purgeInputs) {
+            for (;;) {
+                const ids = await this.store.purge(input);
+                deleted += ids.length;
+                if (this.stopping)
+                    return deleted;
+                if (ids.length < this.limit)
+                    break;
+                // Hand the loop back between batches: a large drain must not starve the
+                // submits and claims sharing this process.
+                await this.sleep(0);
+            }
         }
+        return deleted;
     }
     /** Sleep, interruptible by stop(). Unref'd: retention is housekeeping, and a
      * pending sweep must never be the reason a process refuses to exit. */

package/dist/store/base.d.ts

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

@@ -1,6 +1,6 @@
 import { newId } from "../ids.js";
 import { AlreadyExists, errorEnvelope, LostLease, ProtocolVersionMismatch, SerializationError, } from "../errors.js";
-import { rowToTask, STATUSES, TERMINAL } from "../models.js";
+import { isTerminalStatus, rowToRef, rowToTask, STATUSES, } from "../models.js";
 import { QueueDepthGate } from "../backpressure.js";
 const rejectMangled = function (_key, v) {
     if (typeof v === "number" && !Number.isFinite(v)) {
@@ -65,13 +65,29 @@ const CONFLICTS = ["reuse", "reuse-succeeded", "reject", "replace"];
 function reusable(conflict, status) {
     if (conflict === "replace")
         return false;
-    if (!TERMINAL.includes(status))
+    if (!isTerminalStatus(status))
         return true;
     return conflict === "reuse-succeeded" && status === "succeeded";
 }
 /** The queue a submit lands on when it names none. Owned here, where the
  * default is applied, so nothing above has to re-derive it. */
 export const DEFAULT_QUEUE = "default";
+/** Validate a purge's inputs. Shared with RetentionSweeper, which fail-fasts at
+ * construction on the same rules an hourly sweep would otherwise only surface
+ * through its onError hook — one statement of the rules, two callers. */
+export function validatePurgeInput(input) {
+    if (input.olderThanMs != null && (!Number.isFinite(input.olderThanMs) || input.olderThanMs < 0)) {
+        throw new Error(`olderThanMs must be >= 0, got ${input.olderThanMs}`);
+    }
+    if (input.limit != null && input.limit < 1) {
+        throw new Error(`limit must be >= 1, got ${input.limit}`);
+    }
+    // Terminal only: purge never deletes live work, so accepting `queued` here
+    // would be accepting a filter that silently matches nothing.
+    if (input.status != null && !isTerminalStatus(input.status)) {
+        throw new Error(`status must be terminal, got ${input.status}`);
+    }
+}
 export const LEASE_EXPIRED_ERROR_JSON = dumpJson(errorEnvelope({
     type: "LeaseExpired",
     code: "lease_expired",
@@ -106,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;
@@ -159,6 +166,9 @@ export class TaskStore {
     static one(rows) {
         return rows.length ? rowToTask(rows[0]) : null;
     }
+    static oneRef(rows) {
+        return rows.length ? rowToRef(rows[0]) : null;
+    }
     // ------------------------------------------------------------- client side
     /**
      * Bound how deep a queue may get before `submit` blocks. Off unless set.
@@ -232,7 +242,7 @@ export class TaskStore {
                     // fresh one inserted below. Cancel only what is still live: a terminal
                     // task has nothing to stop, and cancelling it would rewrite a settled
                     // row (and hand a `canceled` back to whoever is waiting on it).
-                    if (!TERMINAL.includes(current.status)) {
+                    if (!isTerminalStatus(current.status)) {
                         await fetch("cancel", { id: existing[0].task_id });
                     }
                 }
@@ -248,6 +258,16 @@ export class TaskStore {
     async getByKey(key) {
         return TaskStore.one(await this.fetch("get_by_key", { key }));
     }
+    /** The wait loop's probe: id + status alone, so polling a task with a large
+     * payload does not re-read and re-parse that payload on every beat. */
+    async getStatus(taskId) {
+        return TaskStore.oneRef(await this.fetch("get_status", { id: taskId }));
+    }
+    /** getStatus, following a key instead of an id — re-resolved per call, so a
+     * `replace` moves the probe onto the new task. */
+    async getStatusByKey(key) {
+        return TaskStore.oneRef(await this.fetch("get_status_by_key", { key }));
+    }
     async list(input = {}) {
         // Validate up front, like submit's conflict guard: a typo'd status otherwise
         // matches nothing and returns [] indistinguishably from "no such tasks".
@@ -302,14 +322,11 @@ export class TaskStore {
      * call it in a loop until it returns fewer than `limit`.
      */
     async purge(input = {}) {
-        if (input.olderThanMs != null && input.olderThanMs < 0) {
-            throw new Error(`olderThanMs must be >= 0, got ${input.olderThanMs}`);
-        }
-        if (input.limit != null && input.limit < 1) {
-            throw new Error(`limit must be >= 1, got ${input.limit}`);
-        }
+        validatePurgeInput(input);
         const rows = await this.fetch("purge", {
             older_than_ms: input.olderThanMs ?? 0,
+            status: input.status ?? null,
+            name: input.name ?? null,
             limit: input.limit ?? 1_000,
         });
         return rows.map((r) => r.id);
@@ -328,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.
      *
@@ -478,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>;