cairnq 0.8.0 → 0.10.0

package/src/store/pg-pool.ts

@@ -0,0 +1,157 @@
+import type * as PG from "pg";
+
+import { ListenUnavailable, type PgExecutor, type PgSession, type Row } 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: typeof import("pg") | null = null;
+async function loadPg(): Promise<typeof import("pg")> {
+  if (pgModule) return pgModule;
+  let mod: { default?: typeof import("pg") } & typeof import("pg");
+  try {
+    mod = (await import("pg")) as never;
+  } catch {
+    throw new Error("PostgresStore requires the 'pg' package — install it (e.g. `npm i pg`)");
+  }
+  const pg = (mod.default ?? mod) as typeof import("pg");
+  // Deliberately NOT setting a global int8 type parser here. It would be the
+  // shortest fix for Postgres sending bigint as text, and it is what this file
+  // used to do — but pg's type parsers are process-global, so a library that
+  // installs one silently changes how the APPLICATION's own bigint columns come
+  // back. rowToTask normalizes instead, which costs nothing and leaves the
+  // caller's driver as they configured it.
+  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: PG.PoolClient): Promise<void> {
+  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: Pick<PG.PoolClient, "query">): PgSession {
+  return {
+    async query(text: string, values: readonly unknown[]): Promise<Row[]> {
+      return (await q.query(text, values as unknown[])).rows;
+    },
+    async exec(sql: string): Promise<void> {
+      // 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: string,
+  opts: { max?: number; schema?: string } = {},
+): Promise<PgExecutor> {
+  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<T>(fn: (s: PgSession) => Promise<T>): Promise<T> {
+      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): Promise<() => void> {
+      // 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(): Promise<void> {
+      await pool.end();
+    },
+  };
+}

package/src/store/postgres.ts

@@ -1,5 +1,4 @@
-import type * as PG from "pg";
-
+import { SchemaMismatch } from "../errors.js";
 import { loadMigrations, loadStatements } from "../sql.js";
 import {
   checkProtocolVersion,
@@ -9,48 +8,16 @@ import {
   type Params,
   statementParams,
   TaskStore,
+  type WatchSignal,
 } 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: typeof import("pg") | null = null;
-async function loadPg(): Promise<typeof import("pg")> {
-  if (pgModule) return pgModule;
-  let mod: { default?: typeof import("pg") } & typeof import("pg");
-  try {
-    mod = (await import("pg")) as never;
-  } catch {
-    throw new Error("PostgresStore requires the 'pg' package — install it (e.g. `npm i pg`)");
-  }
-  const pg = (mod.default ?? mod) as typeof import("pg");
-  // 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: string) => (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: PG.PoolClient): Promise<void> {
-  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, type PgExecutor, type PgSession } 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;
@@ -100,26 +67,38 @@ export function toPositional(
  * 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 {
-  private pool: PG.Pool | null = null;
+  private readonly dsn: string | null;
+  /** The caller's executor, if one was injected — never closed by this store. */
+  private readonly provided: PgExecutor | null;
+  /** Set once migrations have run and the protocol version checked out. */
+  private executor: PgExecutor | null = null;
   private connecting: Promise<void> | null = null;
   private readonly statements: Record<string, string>;
 
   // ------------------------------------------------------- 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.
-  private listener: PG.Client | null = null;
+  // 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.
+  private listener: (() => void) | null = null;
   private listenerConnecting: Promise<void> | null = 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. */
   private listenerUnavailable = false;
   /** A failure to even connect is transient (network blip, server restarting):
@@ -132,12 +111,22 @@ export class PostgresStore extends TaskStore {
   private readonly pendingQueues = new Set<string>();
   /** Wake callbacks by key: "queued" (broadcast) or "done:<task id>". */
   private readonly waiters = new Map<string, Set<() => void>>();
+  /** watch() subscribers. Separate from `waiters`: a waiter is one-shot and
+   * consumes the notification, a subscriber is standing and only observes. */
+  private readonly subscribers = new Set<(signal: WatchSignal) => void>();
 
+  /**
+   * `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(
-    private readonly dsn: string,
-    private readonly opts: { max?: number } = {},
+    source: string | PgExecutor,
+    private readonly opts: { max?: number; schema?: string } = {},
   ) {
     super();
+    this.dsn = typeof source === "string" ? source : null;
+    this.provided = typeof source === "string" ? null : source;
     this.statements = loadStatements("postgres");
   }
 
@@ -148,18 +137,19 @@ export class PostgresStore extends TaskStore {
   async close(): Promise<void> {
     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();
   }
 
   private async ensure(): Promise<void> {
-    if (this.pool) 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.
+    if (this.executor) return;
+    // 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;
@@ -170,28 +160,85 @@ export class PostgresStore extends TaskStore {
   }
 
   private async doConnect(): Promise<void> {
-    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();
-      }
+      // Before migrations, which would otherwise create the very installation
+      // this is trying to warn about.
+      await this.checkSchema(executor);
+      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();
   }
 
-  private async applyMigrations(client: PG.PoolClient): Promise<void> {
-    await client.query(
+  /**
+   * Refuse a connection pointed somewhere other than the deployment's cairnq.
+   *
+   * Two shapes, because `schema` means "the schema cairnq's tables live in" and
+   * cairnq can either arrange that (it built the connection) or only check it
+   * (the caller's executor did):
+   *
+   * - `schema` configured -> assert the connection actually resolves there. On
+   *   the DSN path this is a cheap self-check; on an injected executor it is the
+   *   only way to state the expectation at all.
+   * - `schema` not configured -> the dangerous case is being about to create a
+   *   SECOND installation while one already exists elsewhere in this database,
+   *   which is exactly what a mismatched pair of SDKs does. Joining an existing
+   *   installation is fine no matter what else is around, so the check is
+   *   deliberately narrow: it fires only when this schema has no cairnq and some
+   *   other schema does.
+   *
+   * That narrowness is what keeps it from crying wolf. Two applications each
+   * running their own cairnq in their own schema are legitimate; the second one
+   * to be set up trips this once, and saying `schema` explicitly — which such a
+   * deployment should be doing anyway — is both the fix and the confirmation.
+   */
+  private async checkSchema(executor: PgExecutor): Promise<void> {
+    // One row per installation; the statement's LEFT JOIN guarantees at least
+    // one, so current_schema is readable even where cairnq lives nowhere yet.
+    const rows = await executor.query(this.statements.installations, []);
+    const current = (rows[0]?.current_schema as string | null) ?? null;
+    const installations = rows
+      .map((r) => r.schema as string | null)
+      .filter((s): s is string => s != null);
+    const wanted = this.opts.schema;
+
+    if (wanted != null) {
+      if (current !== wanted) {
+        throw new SchemaMismatch(
+          `cairnq is configured for schema ${JSON.stringify(wanted)} but this ` +
+            `connection resolves to ${JSON.stringify(current)} — check the ` +
+            `connection's search_path`,
+        );
+      }
+      return;
+    }
+    // A search_path naming nothing that exists: there is no "here" to compare
+    // against, and the migrations are about to fail with a clearer message.
+    if (current === null) return;
+    if (installations.length === 0 || installations.includes(current)) return;
+
+    throw new SchemaMismatch(
+      `cairnq tables already exist in schema ${installations.map((s) => JSON.stringify(s)).join(", ")} ` +
+        `of this database, but this connection resolves to ${JSON.stringify(current)}, where there are ` +
+        `none. Connecting would create a second, parallel installation that the other one can never see ` +
+        `— an API and a worker split this way agree about everything except where, and no task crosses. ` +
+        `Point this process at the same schema (\`schema\` option, or \`options=-c search_path=...\` in the ` +
+        `DSN), or pass \`schema\` explicitly to confirm a separate installation is what you meant.`,
+    );
+  }
+
+  private async applyMigrations(executor: PgExecutor): Promise<void> {
+    await executor.exec(
       "create table if not exists cairnq_migrations " +
         "(name text primary key, applied_at_ms bigint not null)",
     );
@@ -199,43 +246,31 @@ export class PostgresStore extends TaskStore {
       // 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(
+      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.
-  private async readProtocolVersion(client: PG.PoolClient): Promise<number> {
-    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.
+  private async readProtocolVersion(s: PgSession): Promise<number> {
+    const rows = await s.query(this.statements.protocol_version, []);
+    return rows.length ? Number(rows[0].value) : 0;
   }
 
   async protocolVersion(): Promise<number> {
     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
@@ -255,6 +290,16 @@ export class PostgresStore extends TaskStore {
     }
   }
 
+  protected subscribePush(onSignal: (signal: WatchSignal) => void): () => void {
+    this.subscribers.add(onSignal);
+    this.listenerReady(); // an API-side watcher is often the only thing asking
+    return () => void this.subscribers.delete(onSignal);
+  }
+
+  protected warmPush(): void {
+    if (this.subscribers.size > 0) this.listenerReady();
+  }
+
   taskDoneWake(taskId: string, timeoutMs: number): Promise<void> {
     if (!this.listenerReady()) return super.taskDoneWake(taskId, timeoutMs);
     return this.wakeOn(`done:${taskId}`, timeoutMs);
@@ -280,7 +325,7 @@ export class PostgresStore extends TaskStore {
     });
   }
 
-  /** 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. */
@@ -294,36 +339,39 @@ export class PostgresStore extends TaskStore {
 
   private async startListener(): Promise<void> {
     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: () => void;
       try {
-        await client.connect();
-      } catch {
-        // Could not even connect — transient. Schedule a backed-off retry;
+        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 (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 {
       // Anything unexpected (e.g. `pg` failed to load): off for good rather
@@ -339,8 +387,10 @@ 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;
     }
@@ -349,10 +399,23 @@ export class PostgresStore extends TaskStore {
     if (set) 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. */
+  private publish(signal: WatchSignal): void {
+    for (const s of [...this.subscribers]) {
+      try {
+        s(signal);
+      } catch {
+        // Deliberately swallowed — see above.
+      }
+    }
+  }
+
   private dropListener(): void {
-    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]) w();
   }
@@ -361,25 +424,26 @@ export class PostgresStore extends TaskStore {
   protected async fetch(name: string, params: Params): Promise<any[]> {
     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);
   }
 
   protected async tx<T>(fn: (fetch: Fetch) => Promise<T>): Promise<T> {
     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)));
+  }
+
+  protected async txWithSession<T>(
+    fn: (fetch: Fetch, session: PgSession) => Promise<T>,
+  ): Promise<T> {
+    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. */
+  private boundFetch(s: PgSession): Fetch {
+    return async (name, params) => {
+      const { text, values } = toPositional(this.statements[name], params);
+      return s.query(text, values);
+    };
   }
 }