cairnq 0.7.0 → 0.9.0

package/dist/store/pg-pool.js

@@ -0,0 +1,147 @@
+import { ListenUnavailable } from "./pg-executor.js";
+// `pg` is an optional dependency: the SDK is SQLite-first, so it's loaded lazily
+// the first time a pool-backed executor is built. Absent -> a clear install hint.
+// An application that brings its own executor never reaches this.
+let pgModule = null;
+async function loadPg() {
+    if (pgModule)
+        return pgModule;
+    let mod;
+    try {
+        mod = (await import("pg"));
+    }
+    catch {
+        throw new Error("PostgresStore requires the 'pg' package — install it (e.g. `npm i pg`)");
+    }
+    const pg = (mod.default ?? mod);
+    // Postgres returns bigint (int8, OID 20) as a string to avoid precision loss.
+    // Every cairnq bigint is an epoch-ms or a counter, all within Number's safe
+    // integer range, so parse to number once (globally) to match the Task model
+    // (*_ms typed as number, same as the SQLite SDK). Set before any query runs.
+    pg.types.setTypeParser(pg.types.builtins.INT8, (v) => (v == null ? null : Number(v)));
+    pgModule = pg;
+    return pg;
+}
+/**
+ * Roll back on the way out of a failed transaction, without letting the rollback
+ * become the error the caller sees. A dropped connection fails both the statement
+ * and the rollback, and it is the first one that says what went wrong.
+ */
+async function rollbackQuietly(client) {
+    try {
+        await client.query("rollback");
+    }
+    catch {
+        // Already rolled back, or the connection is gone. Either way the original
+        // error is the one worth propagating.
+    }
+}
+/** The PgSession face of one pg client or pool. */
+function session(q) {
+    return {
+        async query(text, values) {
+            return (await q.query(text, values)).rows;
+        },
+        async exec(sql) {
+            // No values: pg sends this over the simple query protocol, which is what
+            // makes a multi-statement migration script legal here and not in query().
+            await q.query(sql);
+        },
+    };
+}
+/**
+ * A Postgres identifier that is safe to interpolate — cairnq quotes the schema
+ * name, and a name that could close that quote could rewrite the statement.
+ * Deliberately narrower than what Postgres accepts: a schema cairnq is asked to
+ * live in is a deployment decision, not a place to be clever.
+ */
+const PLAIN_IDENT = /^[A-Za-z_][A-Za-z0-9_$]*$/;
+/**
+ * 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 async function createPoolExecutor(dsn, opts = {}) {
+    const pg = await loadPg();
+    const schema = opts.schema;
+    if (schema !== undefined && !PLAIN_IDENT.test(schema)) {
+        throw new Error(`schema must be a plain identifier (letters, digits, _ and $, not starting ` +
+            `with a digit), got ${JSON.stringify(schema)}`);
+    }
+    const pool = new pg.Pool({ connectionString: dsn, max: opts.max });
+    if (schema) {
+        // Queued on the connection before it is handed out, so every statement this
+        // pool ever runs — migrations included — resolves in the right schema. Pooled
+        // connections come and go, which is why this is per-connection rather than a
+        // one-off at startup.
+        pool.on("connect", (client) => {
+            void client.query(`set search_path to "${schema}"`);
+        });
+    }
+    if (schema) {
+        // Created once, here, rather than from the connect handler (which would ask
+        // for CREATE privilege on every new connection) or from the migrations
+        // (which name no schema, by design). Without it the first `create table`
+        // fails with "no schema has been selected to create in", which says nothing
+        // about the cause. This is the one thing that makes building the executor
+        // connect; without `schema` it stays lazy.
+        try {
+            await pool.query(`create schema if not exists "${schema}"`);
+        }
+        catch (e) {
+            await pool.end();
+            throw e;
+        }
+    }
+    const poolSession = session(pool);
+    return {
+        query: poolSession.query,
+        exec: poolSession.exec,
+        async tx(fn) {
+            const client = await pool.connect();
+            try {
+                await client.query("begin");
+                const out = await fn(session(client));
+                await client.query("commit");
+                return out;
+            }
+            catch (e) {
+                await rollbackQuietly(client);
+                throw e;
+            }
+            finally {
+                client.release();
+            }
+        },
+        async listen(channels, onNotify, onClose) {
+            // Built from the raw DSN rather than taken from the pool: a listener holds
+            // its connection for its whole life, and a pooled one would be a slot the
+            // store never gives back. If `opts` ever grows connection-level settings
+            // (ssl, application_name), the listener must receive them too.
+            const client = new pg.Client({ connectionString: dsn });
+            await client.connect(); // failure here is transient: caller retries with backoff
+            client.on("notification", (msg) => onNotify(msg.channel, msg.payload));
+            // A dropped listener degrades to polling; the store reconnects on the next wake.
+            client.on("error", () => onClose());
+            try {
+                await client.query(channels.map((c) => `listen ${c}`).join("; "));
+            }
+            catch (e) {
+                void client.end().catch(() => { });
+                // Connected, but LISTEN was refused (e.g. a transaction-mode pooler) —
+                // deterministic, so tell the store not to retry.
+                throw new ListenUnavailable(e instanceof Error ? e.message : undefined);
+            }
+            return () => void client.end().catch(() => { });
+        },
+        async close() {
+            await pool.end();
+        },
+    };
+}

package/dist/store/postgres.d.ts

@@ -1,4 +1,5 @@
-import { type Fetch, type Params, TaskStore } from "./base.js";
+import { type Fetch, type Params, TaskStore, type WatchSignal } from "./base.js";
+import { type PgExecutor, type PgSession } from "./pg-executor.js";
 /**
  * The rewritten SQL and the order its `$n` slots must be filled in.
  *
@@ -28,23 +29,32 @@ export declare function toPositional(sql: string, params: Params): {
  * PostgresStore — the Postgres dialect of the shared cairnq-protocol SQL.
  *
  * Everything protocol-shaped lives in TaskStore; this file is only what Postgres
- * does differently: a `pg` Pool, `:name` -> `$n` translation, and time taken from
- * the DB clock (`now()`) instead of from the SDK, which is what makes this backend
- * multi-host — unlike SQLite it coordinates API and worker processes across
- * machines, with no shared clock to agree on. claim uses FOR UPDATE SKIP LOCKED
- * and needs no claimable_probe, because PG readers don't block writers. JSON
- * columns are jsonb (bound as JSON text, read back as objects by rowToTask).
+ * does differently: `:name` -> `$n` translation, the migration ledger, LISTEN
+ * policy, and time taken from the DB clock (`now()`) instead of from the SDK,
+ * which is what makes this backend multi-host — unlike SQLite it coordinates API
+ * and worker processes across machines, with no shared clock to agree on. claim
+ * uses FOR UPDATE SKIP LOCKED and needs no claimable_probe, because PG readers
+ * don't block writers. JSON columns are jsonb (bound as JSON text, read back as
+ * objects by rowToTask).
+ *
+ * What it deliberately does NOT own is the connection. Given a DSN it builds a
+ * `pg` pool (see pg-pool.ts); given a PgExecutor it runs inside the caller's
+ * session instead — no second driver, no second pool, and the caller's writes and
+ * cairnq's can share one transaction.
  */
 export declare class PostgresStore extends TaskStore {
-    private readonly dsn;
     private readonly opts;
-    private pool;
+    private readonly dsn;
+    /** The caller's executor, if one was injected — never closed by this store. */
+    private readonly provided;
+    /** Set once migrations have run and the protocol version checked out. */
+    private executor;
     private connecting;
     private readonly statements;
     private listener;
     private listenerConnecting;
-    /** LISTEN is off for good: the store was closed, or the server accepted a
-     * connection but refused LISTEN (e.g. a transaction-mode pooler) —
+    /** LISTEN is off for good: the store was closed, the executor does not support
+     * it, or the server refused it (e.g. a transaction-mode pooler) —
      * deterministic, so retrying would fail the same way every time. */
     private listenerUnavailable;
     /** A failure to even connect is transient (network blip, server restarting):
@@ -57,8 +67,17 @@ export declare class PostgresStore extends TaskStore {
     private readonly pendingQueues;
     /** Wake callbacks by key: "queued" (broadcast) or "done:<task id>". */
     private readonly waiters;
-    constructor(dsn: string, opts?: {
+    /** watch() subscribers. Separate from `waiters`: a waiter is one-shot and
+     * consumes the notification, a subscriber is standing and only observes. */
+    private readonly subscribers;
+    /**
+     * `source` is either a libpq connection string — this store then owns a `pg`
+     * pool and requires the optional `pg` package — or a PgExecutor the caller
+     * already has, which this store uses and never closes.
+     */
+    constructor(source: string | PgExecutor, opts?: {
         max?: number;
+        schema?: string;
     });
     connect(): Promise<void>;
     close(): Promise<void>;
@@ -68,19 +87,28 @@ export declare class PostgresStore extends TaskStore {
     private readProtocolVersion;
     protocolVersion(): Promise<number>;
     claimWake(queues: string[], timeoutMs: number): Promise<void>;
+    protected subscribePush(onSignal: (signal: WatchSignal) => void): () => void;
+    protected warmPush(): void;
     taskDoneWake(taskId: string, timeoutMs: number): Promise<void>;
     /** A promise resolving on notification-or-timeout, deregistering either way.
      * The timer is unref'd: while a listener exists its socket keeps the process
      * alive, and dropListener wakes every waiter the moment it goes away. */
     private wakeOn;
-    /** True once the LISTEN connection is up; starts connecting it otherwise
+    /** True once the LISTEN subscription is up; starts establishing it otherwise
      * (respecting the transient-failure backoff). Callers fall back to plain
      * polling until it is ready (or forever, if it can't be established) —
      * correctness never depends on it. */
     private listenerReady;
     private startListener;
     private onNotification;
+    /** Hand a notification to every watch() subscriber. A throwing subscriber is
+     * its own problem: it must not cost the others their signal, nor take down the
+     * listener connection that delivered it. */
+    private publish;
     private dropListener;
     protected fetch(name: string, params: Params): Promise<any[]>;
     protected tx<T>(fn: (fetch: Fetch) => Promise<T>): Promise<T>;
+    protected txWithSession<T>(fn: (fetch: Fetch, session: PgSession) => Promise<T>): Promise<T>;
+    /** A Fetch that runs the protocol's statements on one particular session. */
+    private boundFetch;
 }

package/dist/store/postgres.js

@@ -1,45 +1,11 @@
 import { loadMigrations, loadStatements } from "../sql.js";
 import { checkProtocolVersion, COMMENT, NAMED, statementParams, TaskStore, } from "./base.js";
-// `pg` is an optional dependency: the SDK is SQLite-first, so it's loaded lazily
-// the first time a PostgresStore connects. Absent -> a clear install hint.
-let pgModule = null;
-async function loadPg() {
-    if (pgModule)
-        return pgModule;
-    let mod;
-    try {
-        mod = (await import("pg"));
-    }
-    catch {
-        throw new Error("PostgresStore requires the 'pg' package — install it (e.g. `npm i pg`)");
-    }
-    const pg = (mod.default ?? mod);
-    // Postgres returns bigint (int8, OID 20) as a string to avoid precision loss.
-    // Every cairnq bigint is an epoch-ms or a counter, all within Number's safe
-    // integer range, so parse to number once (globally) to match the Task model
-    // (*_ms typed as number, same as the SQLite SDK). Set before any query runs.
-    pg.types.setTypeParser(pg.types.builtins.INT8, (v) => (v == null ? null : Number(v)));
-    pgModule = pg;
-    return pg;
-}
-/**
- * Roll back on the way out of a failed transaction, without letting the rollback
- * become the error the caller sees. A dropped connection fails both the statement
- * and the rollback, and it is the first one that says what went wrong.
- */
-async function rollbackQuietly(client) {
-    try {
-        await client.query("rollback");
-    }
-    catch {
-        // Already rolled back, or the connection is gone. Either way the original
-        // error is the one worth propagating.
-    }
-}
+import { ListenUnavailable } from "./pg-executor.js";
+import { createPoolExecutor } from "./pg-pool.js";
 // Notification channels, emitted by the 0003_notify trigger.
 const QUEUED_CHANNEL = "cairnq_queued";
 const DONE_CHANNEL = "cairnq_done";
-// Backoff between attempts to (re)connect the LISTEN connection after a
+// Backoff between attempts to (re)establish the LISTEN subscription after a
 // transient failure. Doubles per failure up to the cap; polling covers the gap.
 const LISTENER_RETRY_MS = 1_000;
 const LISTENER_RETRY_MAX_MS = 30_000;
@@ -82,27 +48,38 @@ export function toPositional(sql, params) {
  * PostgresStore — the Postgres dialect of the shared cairnq-protocol SQL.
  *
  * Everything protocol-shaped lives in TaskStore; this file is only what Postgres
- * does differently: a `pg` Pool, `:name` -> `$n` translation, and time taken from
- * the DB clock (`now()`) instead of from the SDK, which is what makes this backend
- * multi-host — unlike SQLite it coordinates API and worker processes across
- * machines, with no shared clock to agree on. claim uses FOR UPDATE SKIP LOCKED
- * and needs no claimable_probe, because PG readers don't block writers. JSON
- * columns are jsonb (bound as JSON text, read back as objects by rowToTask).
+ * does differently: `:name` -> `$n` translation, the migration ledger, LISTEN
+ * policy, and time taken from the DB clock (`now()`) instead of from the SDK,
+ * which is what makes this backend multi-host — unlike SQLite it coordinates API
+ * and worker processes across machines, with no shared clock to agree on. claim
+ * uses FOR UPDATE SKIP LOCKED and needs no claimable_probe, because PG readers
+ * don't block writers. JSON columns are jsonb (bound as JSON text, read back as
+ * objects by rowToTask).
+ *
+ * What it deliberately does NOT own is the connection. Given a DSN it builds a
+ * `pg` pool (see pg-pool.ts); given a PgExecutor it runs inside the caller's
+ * session instead — no second driver, no second pool, and the caller's writes and
+ * cairnq's can share one transaction.
  */
 export class PostgresStore extends TaskStore {
-    dsn;
     opts;
-    pool = null;
+    dsn;
+    /** The caller's executor, if one was injected — never closed by this store. */
+    provided;
+    /** Set once migrations have run and the protocol version checked out. */
+    executor = null;
     connecting = null;
     statements;
     // ------------------------------------------------------- LISTEN/NOTIFY state
-    // One dedicated connection LISTENs on both channels (see 0003_notify.sql and
-    // the claimWake/taskDoneWake contract on TaskStore). Failure to establish or
-    // keep it silently degrades the store to the base class's plain polling.
+    // The executor subscribes one dedicated connection to both channels (see
+    // 0003_notify.sql and the claimWake/taskDoneWake contract on TaskStore).
+    // Failure to establish or keep it silently degrades the store to the base
+    // class's plain polling. Held as the unsubscribe function, not the connection:
+    // whose connection it is, is the executor's business.
     listener = null;
     listenerConnecting = null;
-    /** LISTEN is off for good: the store was closed, or the server accepted a
-     * connection but refused LISTEN (e.g. a transaction-mode pooler) —
+    /** LISTEN is off for good: the store was closed, the executor does not support
+     * it, or the server refused it (e.g. a transaction-mode pooler) —
      * deterministic, so retrying would fail the same way every time. */
     listenerUnavailable = false;
     /** A failure to even connect is transient (network blip, server restarting):
@@ -115,10 +92,19 @@ export class PostgresStore extends TaskStore {
     pendingQueues = new Set();
     /** Wake callbacks by key: "queued" (broadcast) or "done:<task id>". */
     waiters = new Map();
-    constructor(dsn, opts = {}) {
+    /** watch() subscribers. Separate from `waiters`: a waiter is one-shot and
+     * consumes the notification, a subscriber is standing and only observes. */
+    subscribers = new Set();
+    /**
+     * `source` is either a libpq connection string — this store then owns a `pg`
+     * pool and requires the optional `pg` package — or a PgExecutor the caller
+     * already has, which this store uses and never closes.
+     */
+    constructor(source, opts = {}) {
         super();
-        this.dsn = dsn;
         this.opts = opts;
+        this.dsn = typeof source === "string" ? source : null;
+        this.provided = typeof source === "string" ? null : source;
         this.statements = loadStatements("postgres");
     }
     async connect() {
@@ -127,18 +113,20 @@ export class PostgresStore extends TaskStore {
     async close() {
         this.listenerUnavailable = true; // no revival after close
         this.dropListener();
-        if (this.pool) {
-            const p = this.pool;
-            this.pool = null;
-            this.connecting = null;
-            await p.end();
-        }
+        const executor = this.executor;
+        this.executor = null;
+        this.connecting = null;
+        // An injected executor belongs to the caller, whose other work would not
+        // survive cairnq closing it.
+        if (executor && !this.provided)
+            await executor.close();
     }
     async ensure() {
-        if (this.pool)
+        if (this.executor)
             return;
-        // Cache the in-flight connect so concurrent calls share one pool. On failure,
-        // clear it so a later call retries instead of re-awaiting a rejected promise.
+        // Cache the in-flight connect so concurrent calls share one executor. On
+        // failure, clear it so a later call retries instead of re-awaiting a
+        // rejected promise.
         if (!this.connecting) {
             this.connecting = this.doConnect().catch((e) => {
                 this.connecting = null;
@@ -148,68 +136,50 @@ export class PostgresStore extends TaskStore {
         await this.connecting;
     }
     async doConnect() {
-        const pg = await loadPg();
-        const pool = new pg.Pool({ connectionString: this.dsn, max: this.opts.max });
+        const executor = this.provided ??
+            (await createPoolExecutor(this.dsn, { max: this.opts.max, schema: this.opts.schema }));
         try {
-            const client = await pool.connect();
-            try {
-                await this.applyMigrations(client);
-                checkProtocolVersion(await this.readProtocolVersion(client));
-            }
-            finally {
-                client.release();
-            }
+            await this.applyMigrations(executor);
+            checkProtocolVersion(await this.readProtocolVersion(executor));
         }
         catch (e) {
-            await pool.end(); // never leak a pool when connect fails
+            // Never leak an executor we created; never close one we were handed.
+            if (!this.provided)
+                await executor.close().catch(() => { });
             throw e;
         }
-        this.pool = pool; // publish only a fully-migrated, version-checked pool
-        // Warm the LISTEN connection in the background so the first idle sleep is
+        this.executor = executor; // publish only a fully-migrated, version-checked executor
+        // Warm the LISTEN subscription in the background so the first idle sleep is
         // already wakeable. Fire-and-forget: failure just means polling.
         this.listenerReady();
     }
-    async applyMigrations(client) {
-        await client.query("create table if not exists cairnq_migrations " +
+    async applyMigrations(executor) {
+        await executor.exec("create table if not exists cairnq_migrations " +
             "(name text primary key, applied_at_ms bigint not null)");
         for (const { name, sql } of loadMigrations("postgres")) {
             // Check and apply inside one transaction, with the table lock taken up
             // front: two processes cold-starting together would otherwise both see a
             // migration as unapplied and both run it.
-            try {
-                await client.query("begin");
-                await client.query("lock table cairnq_migrations in exclusive mode");
-                const applied = await client.query("select 1 from cairnq_migrations where name = $1", [
-                    name,
-                ]);
-                if (applied.rowCount === 0) {
-                    await client.query(sql); // multi-statement DDL (simple-query, no params)
-                    await client.query("insert into cairnq_migrations (name, applied_at_ms) values " +
+            await executor.tx(async (s) => {
+                await s.exec("lock table cairnq_migrations in exclusive mode");
+                const applied = await s.query("select 1 from cairnq_migrations where name = $1", [name]);
+                if (applied.length === 0) {
+                    await s.exec(sql); // multi-statement DDL (simple-query, no params)
+                    await s.query("insert into cairnq_migrations (name, applied_at_ms) values " +
                         "($1, (extract(epoch from now()) * 1000)::bigint)", [name]);
                 }
-                await client.query("commit");
-            }
-            catch (e) {
-                await rollbackQuietly(client);
-                throw e;
-            }
+            });
         }
     }
-    // Takes an explicit client: during doConnect the pool is not published yet, so
-    // this cannot go through fetch(). The statement binds nothing, so it runs as-is.
-    async readProtocolVersion(client) {
-        const res = await client.query(this.statements.protocol_version);
-        return res.rows.length ? Number(res.rows[0].value) : 0;
+    // Takes an explicit session: during doConnect the executor is not published
+    // yet, so this cannot go through fetch(). The statement binds nothing.
+    async readProtocolVersion(s) {
+        const rows = await s.query(this.statements.protocol_version, []);
+        return rows.length ? Number(rows[0].value) : 0;
     }
     async protocolVersion() {
         await this.ensure();
-        const client = await this.pool.connect();
-        try {
-            return await this.readProtocolVersion(client);
-        }
-        finally {
-            client.release();
-        }
+        return this.readProtocolVersion(this.executor);
     }
     // ------------------------------------------------------------ wake channel
     async claimWake(queues, timeoutMs) {
@@ -232,6 +202,15 @@ export class PostgresStore extends TaskStore {
             await this.wakeOn("queued", remaining);
         }
     }
+    subscribePush(onSignal) {
+        this.subscribers.add(onSignal);
+        this.listenerReady(); // an API-side watcher is often the only thing asking
+        return () => void this.subscribers.delete(onSignal);
+    }
+    warmPush() {
+        if (this.subscribers.size > 0)
+            this.listenerReady();
+    }
     taskDoneWake(taskId, timeoutMs) {
         if (!this.listenerReady())
             return super.taskDoneWake(taskId, timeoutMs);
@@ -258,7 +237,7 @@ export class PostgresStore extends TaskStore {
             peers.add(waiter);
         });
     }
-    /** True once the LISTEN connection is up; starts connecting it otherwise
+    /** True once the LISTEN subscription is up; starts establishing it otherwise
      * (respecting the transient-failure backoff). Callers fall back to plain
      * polling until it is ready (or forever, if it can't be established) —
      * correctness never depends on it. */
@@ -272,38 +251,38 @@ export class PostgresStore extends TaskStore {
     }
     async startListener() {
         try {
-            const pg = await loadPg();
-            // Built from the raw DSN: if `opts` ever grows connection-level settings
-            // (ssl, application_name), the listener must receive them too.
-            const client = new pg.Client({ connectionString: this.dsn });
+            const executor = this.executor ?? this.provided;
+            // Not connected yet: transient by definition — doConnect calls back in.
+            if (!executor)
+                return;
+            if (!executor.listen) {
+                this.listenerUnavailable = true; // this executor will never push
+                return;
+            }
+            let stop;
             try {
-                await client.connect();
+                stop = await executor.listen([QUEUED_CHANNEL, DONE_CHANNEL], (channel, payload) => this.onNotification(channel, payload), 
+                // A dropped listener degrades to polling; the next wake reconnects.
+                () => this.dropListener());
             }
-            catch {
-                // Could not even connect — transient. Schedule a backed-off retry;
+            catch (e) {
+                if (e instanceof ListenUnavailable) {
+                    // Deterministic (e.g. a transaction-mode pooler): off for good rather
+                    // than a reconnect loop that cannot succeed. Polling covers it.
+                    this.listenerUnavailable = true;
+                    return;
+                }
+                // Could not establish it — transient. Schedule a backed-off retry;
                 // polling covers the gap.
                 this.listenerRetryAt = Date.now() + this.listenerBackoffMs;
                 this.listenerBackoffMs = Math.min(LISTENER_RETRY_MAX_MS, this.listenerBackoffMs * 2);
                 return;
             }
-            client.on("notification", (msg) => this.onNotification(msg.channel, msg.payload));
-            // A dropped listener degrades to polling; the next wake call reconnects.
-            client.on("error", () => this.dropListener());
-            try {
-                await client.query(`listen ${QUEUED_CHANNEL}; listen ${DONE_CHANNEL}`);
-            }
-            catch {
-                // Connected, but LISTEN was refused (e.g. a transaction-mode pooler) —
-                // deterministic, so off for good. Polling covers it.
-                this.listenerUnavailable = true;
-                void client.end().catch(() => { });
-                return;
-            }
             if (this.listenerUnavailable) {
-                void client.end().catch(() => { }); // closed while we were connecting
+                stop(); // closed while we were subscribing
                 return;
             }
-            this.listener = client;
+            this.listener = stop;
             this.listenerBackoffMs = LISTENER_RETRY_MS;
         }
         catch {
@@ -320,9 +299,11 @@ export class PostgresStore extends TaskStore {
         if (channel === QUEUED_CHANNEL && payload) {
             this.pendingQueues.add(payload);
             key = "queued";
+            this.publish({ reason: "queued", queue: payload });
         }
         else if (channel === DONE_CHANNEL && payload) {
             key = `done:${payload}`;
+            this.publish({ reason: "done", taskId: payload });
         }
         else {
             return;
@@ -333,11 +314,23 @@ export class PostgresStore extends TaskStore {
             for (const w of set)
                 w();
     }
+    /** Hand a notification to every watch() subscriber. A throwing subscriber is
+     * its own problem: it must not cost the others their signal, nor take down the
+     * listener connection that delivered it. */
+    publish(signal) {
+        for (const s of [...this.subscribers]) {
+            try {
+                s(signal);
+            }
+            catch {
+                // Deliberately swallowed — see above.
+            }
+        }
+    }
     dropListener() {
-        const client = this.listener;
+        const stop = this.listener;
         this.listener = null;
-        if (client)
-            void client.end().catch(() => { });
+        stop?.();
         // Release everyone promptly; their fallback poll takes over.
         for (const set of [...this.waiters.values()])
             for (const w of [...set])
@@ -347,26 +340,21 @@ export class PostgresStore extends TaskStore {
     async fetch(name, params) {
         await this.ensure();
         const { text, values } = toPositional(this.statements[name], params);
-        return (await this.pool.query(text, values)).rows;
+        return this.executor.query(text, values);
     }
     async tx(fn) {
         await this.ensure();
-        const client = await this.pool.connect();
-        try {
-            await client.query("begin");
-            const out = await fn(async (name, params) => {
-                const { text, values } = toPositional(this.statements[name], params);
-                return (await client.query(text, values)).rows;
-            });
-            await client.query("commit");
-            return out;
-        }
-        catch (e) {
-            await rollbackQuietly(client);
-            throw e;
-        }
-        finally {
-            client.release();
-        }
+        return this.executor.tx((s) => fn(this.boundFetch(s)));
+    }
+    async txWithSession(fn) {
+        await this.ensure();
+        return this.executor.tx((s) => fn(this.boundFetch(s), s));
+    }
+    /** A Fetch that runs the protocol's statements on one particular session. */
+    boundFetch(s) {
+        return async (name, params) => {
+            const { text, values } = toPositional(this.statements[name], params);
+            return s.query(text, values);
+        };
     }
 }