cairnq 0.9.0 → 0.11.0

package/dist/models.js

@@ -3,7 +3,20 @@
 // truth is the status CHECK constraint in cairnq-protocol's migration, which the
 // conformance suite pins this set against.
 export const STATUSES = ["queued", "running", "succeeded", "failed", "canceled"];
-const JSON_COLUMNS = ["payload", "result", "error", "metadata"];
+export const JSON_COLUMNS = ["payload", "result", "error", "metadata"];
+// 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 a const tuple so TerminalStatus derives from it — the same declare-once
 // pattern as STATUSES/TaskStatus above.
 export const TERMINAL = ["succeeded", "failed", "canceled"];
@@ -24,6 +37,20 @@ export function rowToTask(row) {
         // 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;
 }
 /** Accepts anything carrying a status — a Task or a TaskRef probe. */

package/dist/retention.d.ts

@@ -46,7 +46,17 @@ export declare class RetentionSweeper {
     private active;
     /** Set by stop(), so a drain in progress can cut itself short too. */
     private stopping;
-    /** Resolves the current sleep early, so stop() need not wait out an interval. */
+    /**
+     * 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;
     private wake;
     /** The loop itself, awaited by stop() so no purge outlives the store. */
     private loop;
@@ -57,6 +67,8 @@ export declare class RetentionSweeper {
     private readonly purgeInputs;
     constructor(store: TaskStore, opts: RetentionOptions);
     start(): void;
+    /** Mint a fresh stop signal. */
+    private arm;
     /** Stop sweeping and wait for the sweep in flight, if any. */
     stop(): Promise<void>;
     private run;

package/dist/retention.js

@@ -27,8 +27,18 @@ export class RetentionSweeper {
     active = false;
     /** Set by stop(), so a drain in progress can cut itself short too. */
     stopping = false;
-    /** Resolves the current sleep early, so stop() need not wait out an interval. */
-    wake = 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.
+     */
+    stopSignal;
+    wake;
     /** The loop itself, awaited by stop() so no purge outlives the store. */
     loop = null;
     intervalMs;
@@ -52,6 +62,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,
@@ -67,13 +78,19 @@ export class RetentionSweeper {
             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. */
+    arm() {
+        this.stopSignal = new Promise((resolve) => (this.wake = resolve));
+    }
     /** Stop sweeping and wait for the sweep in flight, if any. */
     async stop() {
         this.stopping = true;
         this.active = false;
-        this.wake?.();
+        this.wake();
         await this.loop;
         this.loop = null;
     }
@@ -123,15 +140,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. */
     sleep(ms) {
-        return new Promise((resolve) => {
-            const timer = setTimeout(resolve, ms);
+        let timer;
+        const nap = new Promise((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/dist/store/base.d.ts

@@ -147,6 +147,12 @@ export declare abstract class TaskStore {
      * `watch` degrades to its timer alone.
      */
     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
@@ -289,9 +295,12 @@ export declare 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.
      */
     claimSession<T>(input: {
         queues: string[];

package/dist/store/base.js

@@ -1,5 +1,5 @@
 import { newId } from "../ids.js";
-import { AlreadyExists, errorEnvelope, LostLease, ProtocolVersionMismatch, SerializationError, } from "../errors.js";
+import { AlreadyExists, errorEnvelope, LostLease, ProtocolVersionMismatch, SerializationError, UnsupportedBackend, } from "../errors.js";
 import { isTerminalStatus, rowToRef, rowToTask, STATUSES, } from "../models.js";
 import { QueueDepthGate } from "../backpressure.js";
 const rejectMangled = function (_key, v) {
@@ -387,7 +387,16 @@ export 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 () => {
@@ -445,9 +454,12 @@ export 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(input, plan) {
         // A list-valued filter cannot be read in claim order, so the planner sorts
@@ -466,6 +478,9 @@ export 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) => {
@@ -564,7 +579,7 @@ export class TaskStore {
      */
     async completeIn(input, fn) {
         if (!this.txWithSession) {
-            throw new Error("this store cannot share a transaction with the caller — " +
+            throw new UnsupportedBackend("this store cannot share a transaction with the caller — " +
                 "completeIn requires a Postgres store (see PgExecutor)");
         }
         return this.txWithSession(async (fetch, session) => {

package/dist/store/pg-executor.d.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. */
 export type Row = Record<string, unknown>;

package/dist/store/pg-executor.js

@@ -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.
  */
 /**
  * LISTEN will not work on this connection, and retrying cannot change that.

package/dist/store/pg-pool.js

@@ -14,11 +14,12 @@ async function loadPg() {
         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)));
+    // 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;
 }
@@ -77,14 +78,39 @@ export async function createPoolExecutor(dsn, opts = {}) {
     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.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/dist/store/postgres.d.ts

@@ -50,6 +50,14 @@ export declare class PostgresStore extends TaskStore {
     /** Set once migrations have run and the protocol version checked out. */
     private executor;
     private connecting;
+    /**
+     * 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;
     private readonly statements;
     private listener;
     private listenerConnecting;
@@ -65,6 +73,27 @@ export declare class PostgresStore extends TaskStore {
     /** Queues notified while nobody was waiting; consumed by the next claimWake
      * so a wake that lands between polls is not lost. */
     private readonly pendingQueues;
+    /**
+     * 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;
     /** Wake callbacks by key: "queued" (broadcast) or "done:<task id>". */
     private readonly waiters;
     /** watch() subscribers. Separate from `waiters`: a waiter is one-shot and
@@ -82,10 +111,45 @@ export declare class PostgresStore extends TaskStore {
     connect(): Promise<void>;
     close(): Promise<void>;
     private ensure;
+    /**
+     * 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;
     private doConnect;
+    /**
+     * 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 checkSchema;
     private applyMigrations;
     private readProtocolVersion;
     protocolVersion(): Promise<number>;
+    protected registerWakeable(queues: string[]): void;
     claimWake(queues: string[], timeoutMs: number): Promise<void>;
     protected subscribePush(onSignal: (signal: WatchSignal) => void): () => void;
     protected warmPush(): void;

package/dist/store/postgres.js

@@ -1,3 +1,4 @@
+import { SchemaMismatch } from "../errors.js";
 import { loadMigrations, loadStatements } from "../sql.js";
 import { checkProtocolVersion, COMMENT, NAMED, statementParams, TaskStore, } from "./base.js";
 import { ListenUnavailable } from "./pg-executor.js";
@@ -69,6 +70,14 @@ export class PostgresStore extends TaskStore {
     /** Set once migrations have run and the protocol version checked out. */
     executor = null;
     connecting = 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.
+     */
+    generation = 0;
     statements;
     // ------------------------------------------------------- LISTEN/NOTIFY state
     // The executor subscribes one dedicated connection to both channels (see
@@ -87,9 +96,31 @@ export class PostgresStore extends TaskStore {
      * hammered from the poll loop. */
     listenerRetryAt = 0;
     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. */
     pendingQueues = new Set();
+    /**
+     * 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.
+     */
+    wakeableQueues = new Set();
     /** Wake callbacks by key: "queued" (broadcast) or "done:<task id>". */
     waiters = new Map();
     /** watch() subscribers. Separate from `waiters`: a waiter is one-shot and
@@ -111,6 +142,7 @@ export class PostgresStore extends TaskStore {
         await this.ensure();
     }
     async close() {
+        this.generation++; // disown any connect still in flight
         this.listenerUnavailable = true; // no revival after close
         this.dropListener();
         const executor = this.executor;
@@ -135,10 +167,29 @@ 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.
+     */
+    resetListenerState() {
+        this.listenerUnavailable = false;
+        this.listenerRetryAt = 0;
+        this.listenerBackoffMs = LISTENER_RETRY_MS;
+    }
     async doConnect() {
+        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));
         }
@@ -148,11 +199,73 @@ export class PostgresStore extends TaskStore {
                 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.
+     */
+    async checkSchema(executor) {
+        // 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 ?? null;
+        const installations = rows
+            .map((r) => r.schema)
+            .filter((s) => 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.`);
+    }
     async applyMigrations(executor) {
         await executor.exec("create table if not exists cairnq_migrations " +
             "(name text primary key, applied_at_ms bigint not null)");
@@ -182,7 +295,12 @@ export class PostgresStore extends TaskStore {
         return this.readProtocolVersion(this.executor);
     }
     // ------------------------------------------------------------ wake channel
+    registerWakeable(queues) {
+        for (const q of queues)
+            this.wakeableQueues.add(q);
+    }
     async claimWake(queues, timeoutMs) {
+        this.registerWakeable(queues);
         if (!this.listenerReady())
             return super.claimWake(queues, timeoutMs);
         const deadline = Date.now() + timeoutMs;
@@ -297,7 +415,9 @@ export class PostgresStore extends TaskStore {
     onNotification(channel, payload) {
         let key;
         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 });
         }

package/dist/worker.d.ts

@@ -98,7 +98,7 @@ export declare class Worker {
     private readonly queues;
     private readonly opts;
     private readonly handlers;
-    private readonly workerId;
+    private readonly ownId;
     /** Payload bytes charged to running handlers — see maxInFlightBytes. */
     private inFlightBytes;
     /** Calls in flight, for the names that cap their own concurrency. */
@@ -139,7 +139,9 @@ export declare class Worker {
         max?: number;
         schema?: string;
     }): Worker;
-    get id(): string;
+    /** This worker's id — what `worker_id` on a running task points at, and what
+     * the Python SDK calls `worker_id` too. */
+    get workerId(): string;
     task(handler: Handler): this;
     task(name: string, handler: Handler): this;
     task<P, R>(def: TaskDef<P, R>, handler: TypedHandler<P, R>): this;