cairnq 0.9.0 → 0.11.0

package/dist/worker.js

@@ -72,7 +72,7 @@ export class Worker {
     queues;
     opts;
     handlers = new Map();
-    workerId = newId("worker");
+    ownId = newId("worker");
     /** Payload bytes charged to running handlers — see maxInFlightBytes. */
     inFlightBytes = 0;
     /** Calls in flight, for the names that cap their own concurrency. */
@@ -142,8 +142,10 @@ export class Worker {
         worker.ownsStore = true;
         return worker;
     }
-    get id() {
-        return this.workerId;
+    /** This worker's id — what `worker_id` on a running task points at, and what
+     * the Python SDK calls `worker_id` too. */
+    get workerId() {
+        return this.ownId;
     }
     task(arg, second, third) {
         // Option form: (name | def, { batch?, concurrency?, resource? }, handler).
@@ -274,7 +276,7 @@ export class Worker {
         return out;
     }
     context(task, leaseMs) {
-        return new TaskContext(this.store, task, this.workerId, leaseMs, {
+        return new TaskContext(this.store, task, this.ownId, leaseMs, {
             retryBackoffMs: this.backoffMs,
             retryBackoffMaxMs: this.backoffMaxMs,
         });
@@ -380,7 +382,7 @@ export class Worker {
                 // Only what this worker can run. Queues do not partition work by task
                 // name, so another worker's tasks would otherwise be claimed here and
                 // failed for want of a handler.
-                { queues: this.queues, workerId: this.workerId, leaseMs, names }, async (claim) => {
+                { queues: this.queues, workerId: this.ownId, leaseMs, names }, async (claim) => {
                     const drawn = [];
                     let left = free;
                     // Resource units this poll has already drawn. resourceCalls only
@@ -612,7 +614,7 @@ export class Worker {
         try {
             // complete (not succeed): finalizes as canceled if a cancel was requested
             // while the handler ran, else succeeded.
-            await this.store.complete({ taskId: ctx.taskId, workerId: this.workerId, result });
+            await this.store.complete({ taskId: ctx.taskId, workerId: this.ownId, result });
             ctx.markSettled();
         }
         catch (err) {
@@ -745,7 +747,7 @@ export class Worker {
                 try {
                     const renewed = await this.store.heartbeatBatch({
                         taskIds: live.map((c) => c.taskId),
-                        workerId: this.workerId,
+                        workerId: this.ownId,
                         leaseMs,
                     });
                     for (const ctx of live) {
@@ -780,7 +782,7 @@ export class Worker {
         try {
             await this.store.fail({
                 taskId: ctx.taskId,
-                workerId: this.workerId,
+                workerId: this.ownId,
                 error: envelope,
                 retryable,
                 delayMs: failDelayMs(ctx.attempt, retryable, this.backoffMs, this.backoffMaxMs),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cairnq",
-  "version": "0.9.0",
+  "version": "0.11.0",
   "description": "SQLite-first, cross-language, storage-centered durable task runtime",
   "license": "MIT",
   "author": "Jannchie <jannchie@gmail.com>",

package/src/context.ts

@@ -37,7 +37,7 @@ export class TaskContext {
   constructor(
     private readonly store: TaskStore,
     private readonly task: Task,
-    public readonly workerId: string,
+    private readonly ownerId: string,
     private readonly leaseMs: number,
     opts: TaskContextOptions = {},
   ) {
@@ -48,6 +48,10 @@ export class TaskContext {
   get taskId(): string {
     return this.task.id;
   }
+  /** The worker running this task — what `worker_id` on the row points at. */
+  get workerId(): string {
+    return this.ownerId;
+  }
   get name(): string {
     return this.task.name;
   }
@@ -150,7 +154,7 @@ export class TaskContext {
     return this.owned(() =>
       this.store.progress({
         taskId: this.task.id,
-        workerId: this.workerId,
+        workerId: this.ownerId,
         progress: value,
         message,
       }),
@@ -161,7 +165,7 @@ export class TaskContext {
     return this.owned(() =>
       this.store.heartbeat({
         taskId: this.task.id,
-        workerId: this.workerId,
+        workerId: this.ownerId,
         leaseMs: this.leaseMs,
       }),
     );
@@ -196,7 +200,7 @@ export class TaskContext {
   async succeed(result: unknown = null): Promise<Task | null> {
     if (this.isSettled) return null;
     const task = await this.owned(() =>
-      this.store.complete({ taskId: this.task.id, workerId: this.workerId, result }),
+      this.store.complete({ taskId: this.task.id, workerId: this.ownerId, result }),
     );
     this.markSettled();
     return task;
@@ -229,7 +233,7 @@ export class TaskContext {
     if (this.isSettled) return null;
     const task = await this.owned(async () => {
       const { task } = await this.store.completeIn<PgSession, T>(
-        { taskId: this.task.id, workerId: this.workerId },
+        { taskId: this.task.id, workerId: this.ownerId },
         write,
       );
       return task;
@@ -253,7 +257,7 @@ export class TaskContext {
     const task = await this.owned(() =>
       this.store.fail({
         taskId: this.task.id,
-        workerId: this.workerId,
+        workerId: this.ownerId,
         error: envelope,
         retryable,
         delayMs: failDelayMs(this.task.attempt, retryable, this.backoffMs, this.backoffMaxMs),

package/src/errors.ts

@@ -208,6 +208,42 @@ export class ProtocolVersionMismatch extends CairnQError {
   }
 }
 
+/**
+ * This store cannot do what was asked, and no argument would change that — the
+ * capability belongs to the backend, not to the call.
+ *
+ * Thrown by `completeIn` on a store with no driver session to share (SQLite has
+ * none). A CairnQError rather than a bare Error so the same catch works across
+ * both SDKs; the Python SDK raises the same named error.
+ */
+export class UnsupportedBackend extends CairnQError {
+  constructor(message: string) {
+    super(message);
+    this.name = "UnsupportedBackend";
+  }
+}
+
+/**
+ * This connection is not pointed at the cairnq installation the rest of the
+ * deployment is using — raised at connect, before any task is written.
+ *
+ * The schema a Postgres connection resolves to is out-of-band configuration
+ * (`search_path`, a `schema` option, an ORM's pool settings), so two processes
+ * given the same DSN can still land in different schemas. Every migration is
+ * `create table if not exists`, so the odd one out does not fail: it builds a
+ * second, empty installation and its protocol version check passes against the
+ * cairnq_meta it just created. Left undetected, an API and a worker then agree
+ * about everything except WHERE, and no task ever crosses.
+ *
+ * The Python SDK raises the same named error.
+ */
+export class SchemaMismatch extends CairnQError {
+  constructor(message: string) {
+    super(message);
+    this.name = "SchemaMismatch";
+  }
+}
+
 /** A value could not be encoded for a protocol JSON column (non-finite number,
  * BigInt, circular structure, …). Raised at the boundary — submit rejects with
  * it, and a worker records a handler result that triggers it as a permanent

package/src/index.ts

@@ -48,6 +48,8 @@ export {
   LostLease,
   EventLoopBlocked,
   ProtocolVersionMismatch,
+  SchemaMismatch,
+  UnsupportedBackend,
   SerializationError,
 } from "./errors.js";
 export type { FailReason } from "./errors.js";

package/src/models.ts

@@ -38,7 +38,20 @@ export interface TaskRef {
   status: TaskStatus;
 }
 
-const JSON_COLUMNS = ["payload", "result", "error", "metadata"] as const;
+export const JSON_COLUMNS = ["payload", "result", "error", "metadata"] as const;
+// The bigint columns. `attempt` / `max_attempts` / `priority` are int4 and
+// `progress` is double precision, so every driver already gives those as numbers;
+// only int8 has a wire form worth normalizing. Nullability differs per column
+// (completed_at_ms may be null, created_at_ms may not), so the coercion has to
+// preserve null rather than turn it into 0.
+export const MS_COLUMNS = [
+  "lease_until_ms",
+  "run_at_ms",
+  "cancel_requested_at_ms",
+  "created_at_ms",
+  "updated_at_ms",
+  "completed_at_ms",
+] as const;
 // As a const tuple so TerminalStatus derives from it — the same declare-once
 // pattern as STATUSES/TaskStatus above.
 export const TERMINAL = ["succeeded", "failed", "canceled"] as const;
@@ -63,6 +76,20 @@ export function rowToTask(row: Record<string, unknown>): Task {
     // already-decoded object. Parse only a string — never assume one backend.
     t[col] = typeof v === "string" ? JSON.parse(v) : (v ?? null);
   }
+  for (const col of MS_COLUMNS) {
+    const v = row[col];
+    // Same argument, for the other column type the drivers disagree about.
+    // Postgres sends int8 down the wire as text to protect precision it cannot
+    // know is unneeded; `pg` surfaces that as a string, postgres.js does too,
+    // asyncpg decodes to int. Normalizing here rather than demanding it of every
+    // driver is what keeps an INJECTED executor honest: the alternative is
+    // asking an application to change its driver's global int8 handling to suit
+    // cairnq, which breaks that application's own bigint columns.
+    //
+    // Lossless: every one of these is an epoch-ms, and a millisecond timestamp
+    // does not reach Number.MAX_SAFE_INTEGER until the year 287396.
+    t[col] = v == null ? null : Number(v);
+  }
   return t as unknown as Task;
 }
 

package/src/retention.ts

@@ -55,8 +55,18 @@ export class RetentionSweeper {
   private active = false;
   /** Set by stop(), so a drain in progress can cut itself short too. */
   private stopping = false;
-  /** Resolves the current sleep early, so stop() need not wait out an interval. */
-  private wake: (() => void) | null = null;
+  /**
+   * Resolved by stop(); every sleep races it. One signal rather than a handle to
+   * the current sleep, because there can be more than one: `sweep()` is public
+   * and meant to be called directly for an on-demand drain, and its
+   * between-batches yield is a sleep of its own. A single handle let that sleep
+   * overwrite the scheduled loop's — and then clear it — leaving stop() nothing
+   * to wake and close() blocked until the whole interval (an hour, by default)
+   * ran out. Same shape as Worker's `stopped$`, and as the Python twin's
+   * asyncio.Event.
+   */
+  private stopSignal!: Promise<void>;
+  private wake!: () => void;
   /** The loop itself, awaited by stop() so no purge outlives the store. */
   private loop: Promise<void> | null = null;
   private readonly intervalMs: number;
@@ -83,6 +93,7 @@ export class RetentionSweeper {
     if (!cutoffs.length) {
       throw new Error("retention.olderThanMs must name at least one status");
     }
+    this.arm();
     this.purgeInputs = cutoffs.map(([status, ms]) => ({
       olderThanMs: ms,
       status,
@@ -97,14 +108,21 @@ export class RetentionSweeper {
     if (this.active) return;
     this.active = true;
     this.stopping = false;
+    // A stopped sweeper can be started again, and the old signal is spent.
+    this.arm();
     this.loop = this.run();
   }
 
+  /** Mint a fresh stop signal. */
+  private arm(): void {
+    this.stopSignal = new Promise<void>((resolve) => (this.wake = resolve));
+  }
+
   /** Stop sweeping and wait for the sweep in flight, if any. */
   async stop(): Promise<void> {
     this.stopping = true;
     this.active = false;
-    this.wake?.();
+    this.wake();
     await this.loop;
     this.loop = null;
   }
@@ -152,15 +170,13 @@ export class RetentionSweeper {
   /** Sleep, interruptible by stop(). Unref'd: retention is housekeeping, and a
    * pending sweep must never be the reason a process refuses to exit. */
   private sleep(ms: number): Promise<void> {
-    return new Promise<void>((resolve) => {
-      const timer = setTimeout(resolve, ms);
+    let timer: NodeJS.Timeout;
+    const nap = new Promise<void>((resolve) => {
+      timer = setTimeout(resolve, ms);
       timer.unref?.();
-      this.wake = () => {
-        clearTimeout(timer);
-        resolve();
-      };
-    }).finally(() => {
-      this.wake = null;
     });
+    // Clear the timer whichever side wins, so a stop is never followed by a
+    // leftover sweep timer.
+    return Promise.race([nap, this.stopSignal]).finally(() => clearTimeout(timer));
   }
 }

package/src/store/base.ts

@@ -5,6 +5,7 @@ import {
   LostLease,
   ProtocolVersionMismatch,
   SerializationError,
+  UnsupportedBackend,
 } from "../errors.js";
 import {
   isTerminalStatus,
@@ -274,6 +275,13 @@ export abstract class TaskStore {
    */
   protected subscribePush?(onSignal: (signal: WatchSignal) => void): () => void;
 
+  /**
+   * Tell a store with a push channel which queues this process will wait on, so
+   * it can buffer their notifications and ignore everyone else's. Optional: a
+   * store without a push channel has nothing to buffer.
+   */
+  protected registerWakeable?(queues: string[]): 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
@@ -561,7 +569,15 @@ export abstract class TaskStore {
     });
     const timer = setInterval(() => {
       this.warmPush?.();
-      emit({ reason: "poll" });
+      // Guarded for the same reason PostgresStore guards its push fan-out: a
+      // consumer that throws must not take the timer down with it. Losing the
+      // timer would silently retire the fallback that makes watch correct
+      // where there is no push channel at all.
+      try {
+        emit({ reason: "poll" });
+      } catch {
+        // The consumer's problem, not the watch's.
+      }
     }, pollMs);
     timer.unref?.();
     return () => {
@@ -631,9 +647,12 @@ export abstract class TaskStore {
    * `plan` runs with the write lock held, so it must await nothing but that
    * callback.
    *
-   * `names` is the union `plan` might ask for — the probe and the recovery are
-   * filtered by it. Returns undefined when the probe finds nothing claimable, in
-   * which case `plan` never runs and no transaction is opened.
+   * `names` is the union `plan` might ask for, and it filters the probe's
+   * queued-work arm. Lease recovery is deliberately NOT filtered by it — nor is
+   * the probe's expired-lease arm — because reclaiming a dead worker's task is
+   * every worker's job, whatever names it happens to handle. Returns undefined
+   * when the probe finds nothing claimable, in which case `plan` never runs and
+   * no transaction is opened.
    */
   async claimSession<T>(
     input: { queues: string[]; workerId: string; leaseMs?: number; names: string[] | null },
@@ -655,6 +674,9 @@ export abstract class TaskStore {
       limit: 1,
       lease_expired_error: LEASE_EXPIRED_ERROR_JSON,
     };
+    // Before the probe: a push-channel store has to know what this caller waits
+    // on from its FIRST claim, not from its first empty poll.
+    this.registerWakeable?.(input.queues);
     if (!(await this.hasClaimableWork(base))) return undefined;
     return this.tx(async (fetch) => {
       await fetch("recover_leases", base);
@@ -768,7 +790,7 @@ export abstract class TaskStore {
     fn: (session: S) => Promise<T>,
   ): Promise<{ task: Task; value: T }> {
     if (!this.txWithSession) {
-      throw new Error(
+      throw new UnsupportedBackend(
         "this store cannot share a transaction with the caller — " +
           "completeIn requires a Postgres store (see PgExecutor)",
       );

package/src/store/pg-executor.ts

@@ -8,11 +8,12 @@
  * 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.
+ * Implementing one is small — see `createPoolExecutor` in pg-pool.ts for the
+ * reference implementation over `pg`. An adapter passes rows through as its
+ * driver produced them: cairnq normalizes both column types the drivers disagree
+ * about (jsonb decoded or not, int8 as text or number) in `rowToTask`, so no
+ * adapter has to reconfigure its driver — and none has to change how the
+ * application's OWN columns come back in order to satisfy cairnq.
  */
 
 /** A row as the driver hands it back: column name -> value. */

package/src/store/pg-pool.ts

@@ -15,11 +15,12 @@ async function loadPg(): Promise<typeof import("pg")> {
     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)));
+  // 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;
 }
@@ -86,14 +87,40 @@ export async function createPoolExecutor(
   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 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.
+    //
+    // Deliberately NOT the `options: '-c search_path=...'` connection parameter,
+    // which reads like the tidier answer: `pg` builds its config as
+    // `Object.assign({}, config, parse(connectionString))`, so a DSN carrying its
+    // own `?options=` (a statement_timeout, say — and cairnq's own SchemaMismatch
+    // message recommends putting `search_path` there) silently REPLACES it, and
+    // the pool then resolves somewhere else entirely. A startup parameter is also
+    // a narrower compatibility surface than a plain statement behind a pooler.
+    //
+    // The Python twin does get to be a startup parameter (asyncpg's
+    // `server_settings`), so there a bad schema fails the connection atomically
+    // and needs no handler below. That asymmetry is the driver's, not a drift.
     pool.on("connect", (client) => {
-      void client.query(`set search_path to "${schema}"`);
+      // The rejection must be handled: `void` on a query that rejects is an
+      // unhandled rejection, which by default takes the process down. And it
+      // must not be swallowed either — a connection whose search_path never
+      // landed would go on serving statements against the wrong schema for its
+      // whole life, which no error anywhere would explain. Ending it is what
+      // makes that loud: this client is about to be handed to a caller, whose
+      // first statement then fails instead of quietly writing to `public`.
+      client.query(`set search_path to "${schema}"`).catch(() => {
+        // `end` is the underlying Client's; the pool hands the connect event a
+        // PoolClient whose `release` does not exist yet at this point. A client
+        // ended here is dropped from the pool when its holder releases it
+        // (pg-pool checks `_queryable`), so this costs a connection, not a slot.
+        void (client as unknown as PG.Client).end().catch(() => {
+          // Already gone. The pool discards it either way.
+        });
+      });
     });
-  }
-  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`

package/src/store/postgres.ts

@@ -1,3 +1,4 @@
+import { SchemaMismatch } from "../errors.js";
 import { loadMigrations, loadStatements } from "../sql.js";
 import {
   checkProtocolVersion,
@@ -86,6 +87,14 @@ export class PostgresStore extends TaskStore {
   /** Set once migrations have run and the protocol version checked out. */
   private executor: PgExecutor | null = null;
   private connecting: Promise<void> | null = null;
+  /**
+   * Bumped by close(). A doConnect that started before the bump must not publish
+   * what it built: close() nulls `connecting` but does not await it, so an
+   * in-flight connect outlives the close and would otherwise install an executor
+   * — and, worse, a LISTEN connection — on a store nobody will close again. That
+   * connection's socket keeps the process alive on its own.
+   */
+  private generation = 0;
   private readonly statements: Record<string, string>;
 
   // ------------------------------------------------------- LISTEN/NOTIFY state
@@ -105,9 +114,31 @@ export class PostgresStore extends TaskStore {
    * hammered from the poll loop. */
   private listenerRetryAt = 0;
   private listenerBackoffMs = LISTENER_RETRY_MS;
+  // NB: these three are re-armed together by resetListenerState().
   /** Queues notified while nobody was waiting; consumed by the next claimWake
    * so a wake that lands between polls is not lost. */
   private readonly pendingQueues = new Set<string>();
+  /**
+   * The queues some caller has actually waited on — the only ones worth
+   * buffering into `pendingQueues`.
+   *
+   * Without it that buffer is a leak: every `cairnq_queued` notification lands in
+   * it, and only claimWake consumes, and only the queues it names. A client-side
+   * handle never calls claimWake at all, and a worker only ever names its own
+   * queues — so a deployment whose queue names carry an identity (`user:1234`)
+   * grows the set forever. This one is bounded by what this process claims from,
+   * which is its own configuration.
+   *
+   * Registered from `claimSession` as well as from `claimWake`, so a worker's
+   * queues are known from its first claim rather than from its first empty poll:
+   * a notification landing between those two would otherwise be dropped, costing
+   * a poll interval exactly when work has just arrived.
+   *
+   * The bound holds because a worker's queue list is its configuration. A caller
+   * driving `claimWake`/`claim` with per-tenant queue names directly still
+   * accumulates one entry per distinct name it passes.
+   */
+  private readonly wakeableQueues = 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
@@ -134,6 +165,7 @@ export class PostgresStore extends TaskStore {
   }
 
   async close(): Promise<void> {
+    this.generation++; // disown any connect still in flight
     this.listenerUnavailable = true; // no revival after close
     this.dropListener();
     const executor = this.executor;
@@ -158,11 +190,31 @@ export class PostgresStore extends TaskStore {
     await this.connecting;
   }
 
+  /**
+   * A fresh connection gets a fresh verdict on LISTEN.
+   *
+   * Every path here connects lazily, so a store used again after close simply
+   * reconnects — and without this it would reconnect permanently degraded to
+   * polling, having decided "no push channel" about a connection that no longer
+   * exists. Called from the constructor for the initial state and from doConnect
+   * for every later one, so the three fields cannot be re-armed by halves. Only
+   * ever safe under doConnect's generation check.
+   */
+  private resetListenerState(): void {
+    this.listenerUnavailable = false;
+    this.listenerRetryAt = 0;
+    this.listenerBackoffMs = LISTENER_RETRY_MS;
+  }
+
   private async doConnect(): Promise<void> {
+    const generation = this.generation;
     const executor =
       this.provided ??
       (await createPoolExecutor(this.dsn!, { max: this.opts.max, schema: this.opts.schema }));
     try {
+      // 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) {
@@ -170,12 +222,78 @@ export class PostgresStore extends TaskStore {
       if (!this.provided) await executor.close().catch(() => {});
       throw e;
     }
+    // Closed while we were connecting: this executor has no owner, so drop it
+    // rather than publishing it. Nothing below may run — clearing
+    // `listenerUnavailable` here is exactly how a closed store would end up with
+    // a listener holding a socket forever.
+    if (generation !== this.generation) {
+      if (!this.provided) await executor.close().catch(() => {});
+      throw new Error("store was closed while connecting");
+    }
     this.executor = executor; // publish only a fully-migrated, version-checked executor
+    this.resetListenerState();
     // Warm the LISTEN subscription in the background so the first idle sleep is
     // already wakeable. Fire-and-forget: failure just means polling.
     this.listenerReady();
   }
 
+  /**
+   * 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 " +
@@ -213,7 +331,12 @@ export class PostgresStore extends TaskStore {
   }
 
   // ------------------------------------------------------------ wake channel
+  protected registerWakeable(queues: string[]): void {
+    for (const q of queues) this.wakeableQueues.add(q);
+  }
+
   async claimWake(queues: string[], timeoutMs: number): Promise<void> {
+    this.registerWakeable(queues);
     if (!this.listenerReady()) return super.claimWake(queues, timeoutMs);
     const deadline = Date.now() + timeoutMs;
     for (;;) {
@@ -324,7 +447,8 @@ export class PostgresStore extends TaskStore {
   private onNotification(channel: string, payload: string | undefined): void {
     let key: string;
     if (channel === QUEUED_CHANNEL && payload) {
-      this.pendingQueues.add(payload);
+      // Buffered only for a queue someone waits on — see wakeableQueues.
+      if (this.wakeableQueues.has(payload)) this.pendingQueues.add(payload);
       key = "queued";
       this.publish({ reason: "queued", queue: payload });
     } else if (channel === DONE_CHANNEL && payload) {