cairnq 0.9.0 → 0.10.0

package/README.md

@@ -114,10 +114,18 @@ const executor: PgExecutor = { /* ~30 lines over your driver */ };
 const tasks = CairnQ.postgres(executor);
 ```
 
-`schema` (DSN form only) puts cairnq's tables in a schema of their own:
+`schema` puts cairnq's tables in a schema of their own:
 `CairnQ.postgres(dsn, { schema: "cairnq" })` creates it if absent and sets
 `search_path` per connection. The protocol's SQL names no schema, so nothing else
-changes. With your own executor, the search_path is yours to set.
+changes. With your own executor the search_path is yours to set, and `schema`
+becomes an assertion about where it lands.
+
+**Every process in a deployment must agree on it.** A queue whose API and worker
+resolve to different schemas is two empty queues, and — because every migration is
+`create table if not exists` — both sides come up healthy, pass their protocol
+version check, and never see each other's tasks. cairnq refuses to connect where
+it can see that about to happen (`SchemaMismatch`); the Python SDK applies the
+same rule.
 
 Two things an adapter must get right: `int8` has to come back as a JS number
 (every cairnq `*_ms` is an epoch or a counter, all inside the safe range), and

package/dist/_protocol/sql/postgres/installations.sql

@@ -0,0 +1,33 @@
+-- Where cairnq already lives in this database, and where this connection is
+-- pointing. Read-only; runs once per connect, before migrations.
+--
+-- Exists because `search_path` is out-of-band configuration: two processes given
+-- the same DSN can still resolve to different schemas, and because every
+-- migration is `create table if not exists`, the second one to start does not
+-- fail — it quietly builds a parallel, empty installation. Nothing downstream can
+-- tell: protocol_version reads from whichever cairnq_meta the connection sees, so
+-- the version check passes on both sides while the API's tasks are invisible to
+-- the worker forever. The only way to catch that is to look OUTSIDE the
+-- connection's own search_path, which is what this does.
+--
+-- One row per installation, never zero: the LEFT JOIN keeps `current_schema`
+-- readable on a database that holds no cairnq yet, where `schema` is null.
+-- Deliberately NOT an array column — pg_namespace.nspname is `name`, and which
+-- drivers decode a `name[]` (or a text[]) into a list is exactly the kind of
+-- disagreement this protocol keeps out of the SDKs. Scalar columns behave the
+-- same everywhere.
+--
+-- `current_schema()` is null when the search_path names nothing that exists, in
+-- which case the caller cannot conclude anything.
+-- params: (none)
+select
+    current_schema()::text as current_schema,
+    found.schema
+from (select 1) one
+left join (
+    select n.nspname::text as schema
+    from pg_class c
+    join pg_namespace n on n.oid = c.relnamespace
+    where c.relname = 'cairnq_tasks' and c.relkind = 'r'
+) found on true
+order by found.schema;

package/dist/context.d.ts

@@ -19,7 +19,7 @@ export interface TaskContextOptions {
 export declare class TaskContext {
     private readonly store;
     private readonly task;
-    readonly workerId: string;
+    private readonly ownerId;
     private readonly leaseMs;
     private readonly abort;
     private leaseLost;
@@ -27,8 +27,10 @@ export declare class TaskContext {
     private isSettled;
     private readonly backoffMs;
     private readonly backoffMaxMs;
-    constructor(store: TaskStore, task: Task, workerId: string, leaseMs: number, opts?: TaskContextOptions);
+    constructor(store: TaskStore, task: Task, ownerId: string, leaseMs: number, opts?: TaskContextOptions);
     get taskId(): string;
+    /** The worker running this task — what `worker_id` on the row points at. */
+    get workerId(): string;
     get name(): string;
     get queue(): string;
     get attempt(): number;

package/dist/context.js

@@ -14,7 +14,7 @@ import { pollWait } from "./wait.js";
 export class TaskContext {
     store;
     task;
-    workerId;
+    ownerId;
     leaseMs;
     abort = new AbortController();
     leaseLost = false;
@@ -28,10 +28,10 @@ export class TaskContext {
     isSettled = false;
     backoffMs;
     backoffMaxMs;
-    constructor(store, task, workerId, leaseMs, opts = {}) {
+    constructor(store, task, ownerId, leaseMs, opts = {}) {
         this.store = store;
         this.task = task;
-        this.workerId = workerId;
+        this.ownerId = ownerId;
         this.leaseMs = leaseMs;
         this.backoffMs = opts.retryBackoffMs ?? DEFAULT_RETRY_BACKOFF_MS;
         this.backoffMaxMs = opts.retryBackoffMaxMs ?? DEFAULT_RETRY_BACKOFF_MAX_MS;
@@ -39,6 +39,10 @@ export class TaskContext {
     get taskId() {
         return this.task.id;
     }
+    /** The worker running this task — what `worker_id` on the row points at. */
+    get workerId() {
+        return this.ownerId;
+    }
     get name() {
         return this.task.name;
     }
@@ -138,7 +142,7 @@ export class TaskContext {
     async progress(value, message = null) {
         return this.owned(() => this.store.progress({
             taskId: this.task.id,
-            workerId: this.workerId,
+            workerId: this.ownerId,
             progress: value,
             message,
         }));
@@ -146,7 +150,7 @@ export class TaskContext {
     async heartbeat() {
         return this.owned(() => this.store.heartbeat({
             taskId: this.task.id,
-            workerId: this.workerId,
+            workerId: this.ownerId,
             leaseMs: this.leaseMs,
         }));
     }
@@ -180,7 +184,7 @@ export class TaskContext {
     async succeed(result = null) {
         if (this.isSettled)
             return null;
-        const task = await this.owned(() => this.store.complete({ taskId: this.task.id, workerId: this.workerId, result }));
+        const task = await this.owned(() => this.store.complete({ taskId: this.task.id, workerId: this.ownerId, result }));
         this.markSettled();
         return task;
     }
@@ -211,7 +215,7 @@ export class TaskContext {
         if (this.isSettled)
             return null;
         const task = await this.owned(async () => {
-            const { task } = await this.store.completeIn({ taskId: this.task.id, workerId: this.workerId }, write);
+            const { task } = await this.store.completeIn({ taskId: this.task.id, workerId: this.ownerId }, write);
             return task;
         });
         this.markSettled();
@@ -229,7 +233,7 @@ export class TaskContext {
         const [envelope, retryable] = asEnvelope(error, opts.retryable ?? true);
         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/dist/errors.d.ts

@@ -101,6 +101,23 @@ export declare class LostLease extends CairnQError {
 export declare class ProtocolVersionMismatch extends CairnQError {
     constructor(message: string);
 }
+/**
+ * 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 declare class SchemaMismatch extends CairnQError {
+    constructor(message: string);
+}
 /** 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/dist/errors.js

@@ -187,6 +187,26 @@ export class ProtocolVersionMismatch extends CairnQError {
         this.name = "ProtocolVersionMismatch";
     }
 }
+/**
+ * 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) {
+        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/dist/index.d.ts

@@ -20,5 +20,5 @@ export type { ListInput, PurgeInput, SubmitInput, Conflict, WatchOptions, WatchS
 export { DEFAULT_WATCH_POLL_MS } from "./store/base.js";
 export type { Task, TaskRef, TaskStatus, TerminalStatus } from "./models.js";
 export { STATUSES, isTerminal, isTerminalStatus, cancelRequested, isQueued, isRunning, isSucceeded, isFailed, isCanceled, } from "./models.js";
-export { CairnQError, AlreadyExists, QueueFull, TaskTimeout, TaskFailed, TaskCanceled, TaskError, LostLease, EventLoopBlocked, ProtocolVersionMismatch, SerializationError, } from "./errors.js";
+export { CairnQError, AlreadyExists, QueueFull, TaskTimeout, TaskFailed, TaskCanceled, TaskError, LostLease, EventLoopBlocked, ProtocolVersionMismatch, SchemaMismatch, SerializationError, } from "./errors.js";
 export type { FailReason } from "./errors.js";

package/dist/index.js

@@ -11,4 +11,4 @@ export { createPoolExecutor } from "./store/pg-pool.js";
 export { TaskStore } from "./store/base.js";
 export { DEFAULT_WATCH_POLL_MS } from "./store/base.js";
 export { STATUSES, isTerminal, isTerminalStatus, cancelRequested, isQueued, isRunning, isSucceeded, isFailed, isCanceled, } from "./models.js";
-export { CairnQError, AlreadyExists, QueueFull, TaskTimeout, TaskFailed, TaskCanceled, TaskError, LostLease, EventLoopBlocked, ProtocolVersionMismatch, SerializationError, } from "./errors.js";
+export { CairnQError, AlreadyExists, QueueFull, TaskTimeout, TaskFailed, TaskCanceled, TaskError, LostLease, EventLoopBlocked, ProtocolVersionMismatch, SchemaMismatch, SerializationError, } from "./errors.js";

package/dist/models.js

@@ -4,6 +4,19 @@
 // conformance suite pins this set against.
 export const STATUSES = ["queued", "running", "succeeded", "failed", "canceled"];
 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.
+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/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;
 }

package/dist/store/postgres.d.ts

@@ -83,6 +83,29 @@ export declare class PostgresStore extends TaskStore {
     close(): Promise<void>;
     private ensure;
     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>;

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";
@@ -139,6 +140,9 @@ export class PostgresStore extends TaskStore {
         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));
         }
@@ -153,6 +157,58 @@ export class PostgresStore extends TaskStore {
         // 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)");

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;

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.10.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,27 @@ export class ProtocolVersionMismatch extends CairnQError {
   }
 }
 
+/**
+ * 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,7 @@ export {
   LostLease,
   EventLoopBlocked,
   ProtocolVersionMismatch,
+  SchemaMismatch,
   SerializationError,
 } from "./errors.js";
 export type { FailReason } from "./errors.js";

package/src/models.ts

@@ -39,6 +39,19 @@ export interface TaskRef {
 }
 
 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.
+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/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;
 }

package/src/store/postgres.ts

@@ -1,3 +1,4 @@
+import { SchemaMismatch } from "../errors.js";
 import { loadMigrations, loadStatements } from "../sql.js";
 import {
   checkProtocolVersion,
@@ -163,6 +164,9 @@ export class PostgresStore extends TaskStore {
       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) {
@@ -176,6 +180,63 @@ export class PostgresStore extends TaskStore {
     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 " +

package/src/worker.ts

@@ -222,7 +222,7 @@ function release(counts: Map<string, number>, key: string | undefined): void {
 
 export class Worker {
   private readonly handlers = new Map<string, Registration>();
-  private readonly workerId = newId("worker");
+  private readonly ownId = newId("worker");
   /** Payload bytes charged to running handlers — see maxInFlightBytes. */
   private inFlightBytes = 0;
   /** Calls in flight, for the names that cap their own concurrency. */
@@ -305,8 +305,10 @@ export class Worker {
     return worker;
   }
 
-  get id(): string {
-    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(): string {
+    return this.ownId;
   }
 
   task(handler: Handler): this;
@@ -474,7 +476,7 @@ export class Worker {
   }
 
   private context(task: Task, leaseMs: number): TaskContext {
-    return new TaskContext(this.store, task, this.workerId, leaseMs, {
+    return new TaskContext(this.store, task, this.ownId, leaseMs, {
       retryBackoffMs: this.backoffMs,
       retryBackoffMaxMs: this.backoffMaxMs,
     });
@@ -588,7 +590,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 },
+          { queues: this.queues, workerId: this.ownId, leaseMs, names },
           async (claim) => {
             const drawn: { src: ClaimSource; calls: [Registration | undefined, Task[]][] }[] = [];
             let left = free;
@@ -826,7 +828,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) {
       if (err instanceof LostLease) {
@@ -967,7 +969,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) {
@@ -1003,7 +1005,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),