cairnq 0.13.0 → 0.14.0

package/dist/store/base.d.ts

@@ -2,10 +2,11 @@ import { type Task, type TaskRef, type TaskStatus } from "../models.js";
 import { type BackpressureOptions } from "../backpressure.js";
 /** Encode a value for a protocol JSON column, raising SerializationError on
  * anything JSON cannot represent. Refuses what JSON.stringify would silently
- * mangle into `null`: NaN/Infinity anywhere, undefined/function/symbol inside an
- * array, and a top-level undefined that disappears entirely — either way the
- * twin SDK reads back something other than what the caller meant (the Python
- * SDK rejects the same values, via allow_nan=False). */
+ * mangle: NaN/Infinity anywhere, undefined/function/symbol inside an array, a
+ * top-level undefined that disappears entirely, and the objects that would be
+ * written as an empty one (see emptiesItselfOut) — either way the twin SDK
+ * reads back something other than what the caller meant. The Python SDK rejects
+ * the same classes of value; see its dump_json. */
 export declare function dumpJson(value: unknown): string;
 /** Refuse to run against a store whose protocol major this SDK does not speak.
  * The supported major is a protocol fact, not a dialect one — every backend
@@ -28,7 +29,8 @@ export interface SubmitInput {
     parentId?: string | null;
     rootId?: string | null;
     correlationId?: string | null;
-    runAtDelayMs?: number;
+    /** Run no earlier than this many ms from now. */
+    delayMs?: number;
 }
 export interface ListInput {
     status?: TaskStatus | null;
@@ -109,32 +111,6 @@ export declare function statementParams(sql: string): readonly string[];
  * them in one place is what stops SQLite and Postgres from drifting apart in
  * behavior; the shared SQL already stops them from drifting in wording.
  */
-/**
- * Why `watch` is calling back.
- *
- * `queued` / `done` come from the store's push channel and name what moved;
- * `poll` is the timer saying the watch cannot rule out a change. None of them
- * carries state — the row is the truth.
- */
-export interface WatchSignal {
-    reason: "queued" | "done" | "poll";
-    /** The queue a task was queued on. Only on `queued`. */
-    queue?: string;
-    /** The task that reached a terminal status. Only on `done`. */
-    taskId?: string;
-}
-export interface WatchOptions {
-    /** Restrict `queued` signals to these queues. Unset watches every queue. */
-    queues?: string[];
-    /**
-     * How often to signal in the absence of a push channel — and, where there is
-     * one, how long a dropped listener can go unnoticed. The default trades a
-     * dashboard's idle query rate against how stale it may look.
-     */
-    pollMs?: number;
-}
-/** See WatchOptions.pollMs. */
-export declare const DEFAULT_WATCH_POLL_MS = 2000;
 export declare abstract class TaskStore {
     /** Set by useBackpressure; null means submit is ungated. */
     private gate;
@@ -167,25 +143,12 @@ export declare abstract class TaskStore {
      * `completeIn` reports that. Postgres implements it; SQLite does not.
      */
     protected txWithSession?<T>(fn: (fetch: Fetch, session: unknown) => Promise<T>): Promise<T>;
-    /**
-     * Register for this store's push channel, if it has one; returns an
-     * unsubscribe. A store without a push channel does not implement this, and
-     * `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
-     * process that never claims never calls claimWake, so without this a listener
-     * that died once would never come back there.
-     */
-    protected warmPush?(): void;
     /**
      * Whether it is worth opening the claim transaction at all — the read-only
      * `claimable_probe`, which every dialect ships.
@@ -207,13 +170,31 @@ export declare abstract class TaskStore {
     /** Resolves when `taskId` may have gone terminal. Plain ref'd sleep —
      * pollWait awaits it directly, so it is what keeps the process alive. */
     taskDoneWake(_taskId: string, timeoutMs: number): Promise<void>;
+    /**
+     * Whether this store's driver hands JSON columns back as text.
+     *
+     * Declared by the store rather than sniffed per value, because for a JSON
+     * *string* the two wire forms are indistinguishable: the text form of
+     * `"hello"` and the decoded form of `"hello"` are both strings, and treating
+     * the decoded one as text parses it twice — `"s3://…"` threw, `"42"` came back
+     * as the number 42. See rowToTask.
+     *
+     * True is the SQLite answer and the safe default: its JSON columns are TEXT,
+     * always. PostgresStore replaces it with what its driver actually does, which
+     * it measures rather than assumes — an injected executor's driver is the
+     * application's choice, not cairnq's.
+     */
+    protected jsonIsText: boolean;
+    /** rowToTask, told this store's wire form. Every row in this class goes
+     * through here so no call site has to remember to pass it. */
+    private toTask;
     /**
      * An ownership-checked worker write (heartbeat/progress/succeed/complete/fail).
      * Each statement's WHERE pins worker_id + a live lease, so 0 rows back means
      * the lease was lost — every such write reports it the same way.
      */
     private ownedWrite;
-    private static one;
+    private one;
     private static oneRef;
     /**
      * Bound how deep a queue may get before `submit` blocks. Off unless set.
@@ -259,54 +240,12 @@ export declare abstract class TaskStore {
      * retention expressible at all — see PurgeInput.
      */
     purge(input?: PurgeInput): Promise<string[]>;
-    /**
-     * Task counts per queue, keyed by status and zero-filled across all statuses —
-     * `(await stats()).default.queued` is the backlog of a queue. A queue appears
-     * only while it has rows; terminal tasks keep counting until `purge` removes
-     * them.
-     *
-     * `queue` restricts the aggregate to one queue, which is also what stops the
-     * caller paying for every other queue's rows: one installation carrying two
-     * workloads is the coordination this project recommends, and the unfiltered
-     * form reads the whole table. A named queue is always present in the result,
-     * zero-filled if it has no rows at all — asking about a specific queue and
-     * getting `undefined` back would make every caller write the same fallback.
-     *
-     * Filtered or not, this COUNTS, so it costs what it counts: a whole queue,
-     * terminal rows included. Right for a dashboard, wrong on an interval — poll
-     * `queueDepth`, which is bounded, and keep this for when the real numbers are
-     * the point.
-     */
-    stats(queue?: string): Promise<Record<string, Record<TaskStatus, number>>>;
-    /**
-     * Call `onSignal` when the tasks on `queues` may have changed — something was
-     * queued, or something finished.
-     *
-     * This is notify-ACCELERATED POLLING, not an event log, and the difference is
-     * the whole contract. Where a push channel is available (Postgres LISTEN) an
-     * idle watch costs nothing and a signal arrives within milliseconds of the
-     * event. Where it is not — a transaction-mode pooler refuses LISTEN, SQLite has
-     * no channel at all — the timer alone still delivers `poll` signals, so a
-     * consumer that re-reads on every signal is correct in both cases and merely
-     * less prompt in one.
-     *
-     * What it will NOT do is promise that a signal means something happened, or
-     * that every event produces its own signal. Treat a signal as "re-read now"
-     * and take the truth from `stats()` / `list()` / `get()`, which is where it
-     * lives. `reason` is a hint for reading less: a `done` signal names the task,
-     * so a dashboard can refresh that row instead of the list.
-     *
-     * Returns an unsubscribe. The timer is unref'd — watching does not hold a
-     * process open.
-     */
-    watch(opts: WatchOptions, onSignal: (signal: WatchSignal) => void): () => void;
     /**
      * How many more tasks fit on `queue` under `maxDepth` — 0 once it is full.
      *
-     * The cheap half of backpressure: bounded at `maxDepth` index entries, unlike
-     * `stats()`, which aggregates the whole table (terminal rows included) and so
-     * costs more the longer a database has been running. Use it directly to shed
-     * load or shape a producer; `QueueDepthGate` builds the blocking form on top.
+     * The cheap half of backpressure: bounded at `maxDepth` index entries, so it
+     * stays cheap to ask on every enqueue. Use it directly to shed load or shape
+     * a producer; `QueueDepthGate` builds the blocking form on top.
      */
     queueDepth(queue: string, maxDepth: number): Promise<number>;
     /**

package/dist/store/base.js

@@ -2,6 +2,48 @@ import { newId } from "../ids.js";
 import { AlreadyExists, errorEnvelope, LostLease, ProtocolVersionMismatch, SerializationError, UnsupportedBackend, } from "../errors.js";
 import { isTerminalStatus, rowToRef, rowToTask, STATUSES, } from "../models.js";
 import { QueueDepthGate } from "../backpressure.js";
+/**
+ * Whether `JSON.stringify` would write this object without its contents.
+ *
+ * Every such value serializes to `{}` — or, for a typed array, to an object
+ * keyed by index — with everything it actually held silently gone. A handler
+ * that returns a `Map` would otherwise record `{}` as the task's result:
+ * succeeded, no error, and nothing left to recover the value from. That is the
+ * same class of silent mangle as `NaN` becoming `null`, so it is refused the
+ * same way.
+ *
+ * Structural rather than a list of built-in names, because a list is only ever
+ * as current as the day it was written. An enumeration of `Map`/`Set`/`Promise`/
+ * the typed arrays already missed `Float16Array` (ES2025, and `engines` here is
+ * node >=22), `Blob`, `Headers`, `URLSearchParams`, and — unfixably, since its
+ * tag is plain `[object Object]` — a class whose state is all private fields.
+ * The rule below catches those, and whatever the platform adds next, with
+ * nothing to maintain:
+ *
+ * - **A non-plain object with no own enumerable properties.** Its state lives
+ *   somewhere `JSON.stringify` cannot reach (internal slots, private fields, a
+ *   host binding), so `{}` is all that would be written. A *plain* `{}` is
+ *   deliberately exempt: an empty object is a value, not a loss.
+ * - **Any `ArrayBuffer` view.** A typed array writes its indices as string keys
+ *   and reads back as an object, not an array — non-empty, so the first rule
+ *   does not see it.
+ *
+ * A class instance that carries ordinary properties still crosses: those
+ * properties are exactly what gets written, and nothing is lost. `Date` never
+ * reaches here at all — `toJSON` has already replaced it with its ISO string by
+ * the time a replacer is called, which is also why `toJSON` remains the escape
+ * hatch for anything that wants to define its own JSON form.
+ */
+function emptiesItselfOut(v) {
+    if (ArrayBuffer.isView(v))
+        return true;
+    const proto = Object.getPrototypeOf(v);
+    // Plain and null-prototype objects are the two shapes whose own enumerable
+    // properties ARE their contents, so an empty one is honestly empty.
+    if (proto === Object.prototype || proto === null)
+        return false;
+    return Object.keys(v).length === 0;
+}
 const rejectMangled = function (_key, v) {
     if (typeof v === "number" && !Number.isFinite(v)) {
         throw new SerializationError(`non-finite number ${v} is not JSON-serializable`);
@@ -12,14 +54,19 @@ const rejectMangled = function (_key, v) {
     if (Array.isArray(this) && (v === undefined || typeof v === "function" || typeof v === "symbol")) {
         throw new SerializationError(`${typeof v} inside an array is not JSON-serializable`);
     }
+    if (v !== null && typeof v === "object" && !Array.isArray(v) && emptiesItselfOut(v)) {
+        const name = v.constructor?.name ?? "object";
+        throw new SerializationError(`${name} carries nothing JSON.stringify can see and would be written as an empty object`);
+    }
     return v;
 };
 /** Encode a value for a protocol JSON column, raising SerializationError on
  * anything JSON cannot represent. Refuses what JSON.stringify would silently
- * mangle into `null`: NaN/Infinity anywhere, undefined/function/symbol inside an
- * array, and a top-level undefined that disappears entirely — either way the
- * twin SDK reads back something other than what the caller meant (the Python
- * SDK rejects the same values, via allow_nan=False). */
+ * mangle: NaN/Infinity anywhere, undefined/function/symbol inside an array, a
+ * top-level undefined that disappears entirely, and the objects that would be
+ * written as an empty one (see emptiesItselfOut) — either way the twin SDK
+ * reads back something other than what the caller meant. The Python SDK rejects
+ * the same classes of value; see its dump_json. */
 export function dumpJson(value) {
     let text;
     try {
@@ -32,11 +79,36 @@ export function dumpJson(value) {
     if (text === undefined) {
         throw new SerializationError(`value of type ${typeof value} is not JSON-serializable`);
     }
-    // Every mangled value reaches the output as the literal `null`, so a
-    // null-free result needs no strict pass — this keeps the replacer (which
-    // forfeits V8's native stringifier) off the hot path.
-    if (text.includes("null"))
+    // Every mangled value betrays itself in the output, so the strict pass — which
+    // forfeits V8's native stringifier — runs only when one of its traces is
+    // there: `null` for a mangled scalar, `{}` for an opaque container emptied
+    // out, `{"0":` for a typed array rewritten as an index-keyed object. Each is a
+    // superset (a payload carrying an empty object, or a literal "0" key, merely
+    // pays for a second pass that then finds nothing), and together they are
+    // exhaustive over everything rejectMangled rejects. Measured on a null-free
+    // payload the three checks cost ~20% of the encode, against ~130% for running
+    // the replacer unconditionally.
+    //
+    // The second pass builds a whole string and throws it away, so a hit costs
+    // 2.4x the encode (211us against 87us on a 42KB payload) where a validating
+    // WALK would cost 28us. It stays a second stringify anyway, twice over: a walk
+    // would have to reproduce seven of JSON.stringify's traversal semantics by
+    // hand — toJSON applied before the replacer sees a value, boxed primitives,
+    // sparse arrays, own-enumerable ordering, getters called once each, and a
+    // cycle guard the native pass does not need here but a walk would (an impure
+    // getter can introduce a cycle the first pass did not see, where stringify
+    // throws and a walk recurses forever) — and a divergence between the two is
+    // either a false rejection or the silent-data-loss bug coming back. It is also
+    // the wrong thing to optimise: every dumpJson sits next to a durable write, so
+    // 124us is noise beside the transaction it precedes. Revisit only with a
+    // profile showing this in double digits of submit latency, and pair any walk
+    // with a differential test asserting the two agree over generated values.
+    //
+    // The `{}` trace cannot be narrowed, either: an emptied-out Map and a
+    // legitimate empty object are byte-identical in the output.
+    if (text.includes("null") || text.includes("{}") || text.includes('{"0":')) {
         JSON.stringify(value, rejectMangled);
+    }
     return text;
 }
 const SUPPORTED_PROTOCOL_MAJOR = 1;
@@ -140,7 +212,9 @@ export function specialize(sql, params) {
     }
     if (!active)
         return sql;
-    const key = active + sql;
+    // "\u0000" delimits: the names run together with no separator otherwise, and
+    // ("a," + "b,SELECT") and ("a,b," + "SELECT") would be one cache entry.
+    const key = active + "\u0000" + sql;
     let out = specialCache.get(key);
     if (out === undefined) {
         out = sql.replace(OPTIONAL_FILTER, (whole, name, column) => params[name] != null ? `${column} = :${name}` : whole);
@@ -168,8 +242,17 @@ export function statementParams(sql) {
     }
     return names;
 }
-/** See WatchOptions.pollMs. */
-export const DEFAULT_WATCH_POLL_MS = 2_000;
+/**
+ * The storage seam.
+ *
+ * A backend supplies three things: how to run one protocol statement, how to run
+ * several inside a transaction, and how its dialect binds parameters. Everything
+ * above that — the submit conflict branches, the *_by_key lookups, the
+ * recover-then-claim sequence, the ownership-checked writes — lives here once,
+ * because those are protocol decisions rather than storage decisions. Keeping
+ * them in one place is what stops SQLite and Postgres from drifting apart in
+ * behavior; the shared SQL already stops them from drifting in wording.
+ */
 export class TaskStore {
     /** Set by useBackpressure; null means submit is ungated. */
     gate = null;
@@ -207,6 +290,26 @@ export class TaskStore {
         return new Promise((resolve) => setTimeout(resolve, timeoutMs));
     }
     // --------------------------------------------------------------- internals
+    /**
+     * Whether this store's driver hands JSON columns back as text.
+     *
+     * Declared by the store rather than sniffed per value, because for a JSON
+     * *string* the two wire forms are indistinguishable: the text form of
+     * `"hello"` and the decoded form of `"hello"` are both strings, and treating
+     * the decoded one as text parses it twice — `"s3://…"` threw, `"42"` came back
+     * as the number 42. See rowToTask.
+     *
+     * True is the SQLite answer and the safe default: its JSON columns are TEXT,
+     * always. PostgresStore replaces it with what its driver actually does, which
+     * it measures rather than assumes — an injected executor's driver is the
+     * application's choice, not cairnq's.
+     */
+    jsonIsText = true;
+    /** rowToTask, told this store's wire form. Every row in this class goes
+     * through here so no call site has to remember to pass it. */
+    toTask(row) {
+        return rowToTask(row, this.jsonIsText);
+    }
     /**
      * An ownership-checked worker write (heartbeat/progress/succeed/complete/fail).
      * Each statement's WHERE pins worker_id + a live lease, so 0 rows back means
@@ -216,10 +319,12 @@ export class TaskStore {
         const rows = await this.fetch(name, params);
         if (!rows.length)
             throw new LostLease(taskId);
-        return rowToTask(rows[0]);
+        return this.toTask(rows[0]);
     }
-    static one(rows) {
-        return rows.length ? rowToTask(rows[0]) : null;
+    // An instance method, unlike oneRef: mapping a Task reads this store's JSON
+    // wire form, and a TaskRef has no JSON column to read.
+    one(rows) {
+        return rows.length ? this.toTask(rows[0]) : null;
     }
     static oneRef(rows) {
         return rows.length ? rowToRef(rows[0]) : null;
@@ -246,7 +351,7 @@ export class TaskStore {
             metadata: dumpJson(input.metadata ?? {}),
             max_attempts: input.maxAttempts ?? 3,
             priority: input.priority ?? 0,
-            delay_ms: input.runAtDelayMs ?? 0,
+            delay_ms: input.delayMs ?? 0,
             parent_id: input.parentId ?? null,
             root_id: input.rootId ?? id,
             correlation_id: input.correlationId ?? null,
@@ -265,8 +370,8 @@ export class TaskStore {
         if (input.maxAttempts != null && input.maxAttempts < 1) {
             throw new Error(`maxAttempts must be >= 1, got ${input.maxAttempts}`);
         }
-        if (input.runAtDelayMs != null && input.runAtDelayMs < 0) {
-            throw new Error(`runAtDelayMs must be >= 0, got ${input.runAtDelayMs}`);
+        if (input.delayMs != null && input.delayMs < 0) {
+            throw new Error(`delayMs must be >= 0, got ${input.delayMs}`);
         }
         // After validation and before the first write: bad arguments should fail
         // now, not after waiting out a full queue. Reads the resolved queue, so the
@@ -274,7 +379,7 @@ export class TaskStore {
         if (this.gate)
             await this.gate.acquire(ins.queue);
         if (key === null)
-            return rowToTask((await this.fetch("insert_task", ins))[0]);
+            return this.toTask((await this.fetch("insert_task", ins))[0]);
         // A key makes submit a read-then-write, so it has to be one transaction —
         // opened by taking the key's lock, because on Postgres the transaction alone
         // is not enough: concurrent same-key submits must not both see "no existing
@@ -292,7 +397,7 @@ export class TaskStore {
                     if (conflict === "reject")
                         throw new AlreadyExists(key);
                     if (reusable(conflict, current.status))
-                        return rowToTask(current);
+                        return this.toTask(current);
                     // The strategy declined the recorded task, so the key repoints to the
                     // fresh one inserted below. Cancel only what is still live: a terminal
                     // task has nothing to stop, and cancelling it would rewrite a settled
@@ -304,14 +409,14 @@ export class TaskStore {
             }
             const row = (await fetch("insert_task", ins))[0];
             await fetch("upsert_key", { key, task_id: id });
-            return rowToTask(row);
+            return this.toTask(row);
         });
     }
     async get(taskId) {
-        return TaskStore.one(await this.fetch("get", { id: taskId }));
+        return this.one(await this.fetch("get", { id: taskId }));
     }
     async getByKey(key) {
-        return TaskStore.one(await this.fetch("get_by_key", { key }));
+        return this.one(await this.fetch("get_by_key", { key }));
     }
     /** The wait loop's probe: id + status alone, so polling a task with a large
      * payload does not re-read and re-parse that payload on every beat. */
@@ -341,13 +446,13 @@ export class TaskStore {
             limit: input.limit ?? 100,
             offset: input.offset ?? 0,
         });
-        return rows.map(rowToTask);
+        return rows.map((r) => this.toTask(r));
     }
     async cancel(taskId) {
-        return TaskStore.one(await this.fetch("cancel", { id: taskId }));
+        return this.one(await this.fetch("cancel", { id: taskId }));
     }
     async retry(taskId, opts = {}) {
-        return TaskStore.one(await this.fetch("retry", { id: taskId, reset_attempt: opts.resetAttempt ?? false }));
+        return this.one(await this.fetch("retry", { id: taskId, reset_attempt: opts.resetAttempt ?? false }));
     }
     async cancelByKey(key) {
         return this.byKey("cancel", key, {});
@@ -367,7 +472,7 @@ export class TaskStore {
             const existing = (await fetch("get_key", { key }));
             if (!existing.length)
                 return null;
-            return TaskStore.one(await fetch(name, { id: existing[0].task_id, ...params }));
+            return this.one(await fetch(name, { id: existing[0].task_id, ...params }));
         });
     }
     /**
@@ -390,104 +495,12 @@ export class TaskStore {
         });
         return rows.map((r) => r.id);
     }
-    /**
-     * Task counts per queue, keyed by status and zero-filled across all statuses —
-     * `(await stats()).default.queued` is the backlog of a queue. A queue appears
-     * only while it has rows; terminal tasks keep counting until `purge` removes
-     * them.
-     *
-     * `queue` restricts the aggregate to one queue, which is also what stops the
-     * caller paying for every other queue's rows: one installation carrying two
-     * workloads is the coordination this project recommends, and the unfiltered
-     * form reads the whole table. A named queue is always present in the result,
-     * zero-filled if it has no rows at all — asking about a specific queue and
-     * getting `undefined` back would make every caller write the same fallback.
-     *
-     * Filtered or not, this COUNTS, so it costs what it counts: a whole queue,
-     * terminal rows included. Right for a dashboard, wrong on an interval — poll
-     * `queueDepth`, which is bounded, and keep this for when the real numbers are
-     * the point.
-     */
-    async stats(queue) {
-        const zeros = () => Object.fromEntries(STATUSES.map((s) => [s, 0]));
-        const out = {};
-        // Seed before the query, not after: a named queue with no rows returns no
-        // rows to seed from, and that is exactly the case the promise is about.
-        if (queue != null)
-            out[queue] = zeros();
-        for (const row of await this.fetch("stats", { queue: queue ?? null })) {
-            const per = (out[row.queue] ??= zeros());
-            per[row.status] = Number(row.count);
-        }
-        return out;
-    }
-    /**
-     * Call `onSignal` when the tasks on `queues` may have changed — something was
-     * queued, or something finished.
-     *
-     * This is notify-ACCELERATED POLLING, not an event log, and the difference is
-     * the whole contract. Where a push channel is available (Postgres LISTEN) an
-     * idle watch costs nothing and a signal arrives within milliseconds of the
-     * event. Where it is not — a transaction-mode pooler refuses LISTEN, SQLite has
-     * no channel at all — the timer alone still delivers `poll` signals, so a
-     * consumer that re-reads on every signal is correct in both cases and merely
-     * less prompt in one.
-     *
-     * What it will NOT do is promise that a signal means something happened, or
-     * that every event produces its own signal. Treat a signal as "re-read now"
-     * and take the truth from `stats()` / `list()` / `get()`, which is where it
-     * lives. `reason` is a hint for reading less: a `done` signal names the task,
-     * so a dashboard can refresh that row instead of the list.
-     *
-     * Returns an unsubscribe. The timer is unref'd — watching does not hold a
-     * process open.
-     */
-    watch(opts, onSignal) {
-        const pollMs = Math.max(1, opts.pollMs ?? DEFAULT_WATCH_POLL_MS);
-        const queues = opts.queues ?? null;
-        let live = true;
-        const emit = (signal) => {
-            // A signal delivered after unsubscribe would have the consumer re-reading
-            // a store it has stopped caring about, possibly a closed one.
-            if (live)
-                onSignal(signal);
-        };
-        const unsubscribe = this.subscribePush?.((signal) => {
-            // A queued signal names its queue, so a watch scoped to some queues can
-            // drop the rest. A done signal names only the task — which queue it was on
-            // is not in the notification, so it is never filtered out.
-            if (signal.reason === "queued" && queues && signal.queue && !queues.includes(signal.queue)) {
-                return;
-            }
-            emit(signal);
-        });
-        const timer = setInterval(() => {
-            this.warmPush?.();
-            // 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 () => {
-            live = false;
-            unsubscribe?.();
-            clearInterval(timer);
-        };
-    }
     /**
      * How many more tasks fit on `queue` under `maxDepth` — 0 once it is full.
      *
-     * The cheap half of backpressure: bounded at `maxDepth` index entries, unlike
-     * `stats()`, which aggregates the whole table (terminal rows included) and so
-     * costs more the longer a database has been running. Use it directly to shed
-     * load or shape a producer; `QueueDepthGate` builds the blocking form on top.
+     * The cheap half of backpressure: bounded at `maxDepth` index entries, so it
+     * stays cheap to ask on every enqueue. Use it directly to shed load or shape
+     * a producer; `QueueDepthGate` builds the blocking form on top.
      */
     async queueDepth(queue, maxDepth) {
         if (!Number.isInteger(maxDepth) || maxDepth < 0) {
@@ -580,7 +593,7 @@ export class TaskStore {
                     name: oneName ? names[0] : null,
                     limit,
                 });
-                return rows.map(rowToTask);
+                return rows.map((r) => this.toTask(r));
             });
         });
     }
@@ -668,7 +681,7 @@ export class TaskStore {
             // Rolls back `fn`'s writes along with the settlement that did not land.
             if (!rows.length)
                 throw new LostLease(input.taskId);
-            return { task: rowToTask(rows[0]), value };
+            return { task: this.toTask(rows[0]), value };
         });
     }
     async fail(input) {

package/dist/store/pg-executor.d.ts

@@ -44,6 +44,17 @@
  * The reference implementation happens not to be affected — `pg` uses the
  * extended protocol by default — which is why this is stated here rather than
  * left to be discovered.
+ *
+ * A second thing, smaller but just as easy to get wrong: whatever this executor
+ * does with json/jsonb, it must do CONSISTENTLY. The store measures the wire
+ * form once at connect, with a `select '"cairnq"'::jsonb` probe, and maps every
+ * row it later reads according to the answer — so an executor that decodes
+ * jsonb for one statement and hands back text for another (or answers the probe
+ * differently from how it returns task rows) will have its payloads read the
+ * wrong way. Decoding or not are both fine; disagreeing with yourself is not.
+ * The probe exists because the two forms cannot be told apart from a value: a
+ * JSON string arrives as a string either way, so a guess parses the decoded one
+ * twice — `"s3://…"` throws and `"42"` silently becomes the number 42.
  */
 /** A row as the driver hands it back: column name -> value. */
 export type Row = Record<string, unknown>;

package/dist/store/pg-executor.js

@@ -44,6 +44,17 @@
  * The reference implementation happens not to be affected — `pg` uses the
  * extended protocol by default — which is why this is stated here rather than
  * left to be discovered.
+ *
+ * A second thing, smaller but just as easy to get wrong: whatever this executor
+ * does with json/jsonb, it must do CONSISTENTLY. The store measures the wire
+ * form once at connect, with a `select '"cairnq"'::jsonb` probe, and maps every
+ * row it later reads according to the answer — so an executor that decodes
+ * jsonb for one statement and hands back text for another (or answers the probe
+ * differently from how it returns task rows) will have its payloads read the
+ * wrong way. Decoding or not are both fine; disagreeing with yourself is not.
+ * The probe exists because the two forms cannot be told apart from a value: a
+ * JSON string arrives as a string either way, so a guess parses the decoded one
+ * twice — `"s3://…"` throws and `"42"` silently becomes the number 42.
  */
 /**
  * LISTEN will not work on this connection, and retrying cannot change that.

package/dist/store/pg-pool.js

@@ -150,6 +150,20 @@ export async function createPoolExecutor(dsn, opts = {}) {
             // its connection for its whole life, and a pooled one would be a slot the
             // store never gives back. If `opts` ever grows connection-level settings
             // (ssl, application_name), the listener must receive them too.
+            //
+            // `schema` is deliberately NOT forwarded, and it is the exception worth
+            // stating rather than the omission it looks like: a NOTIFY channel name is
+            // scoped to the database, never to a schema, so a search_path would change
+            // nothing about what arrives here. The consequence is real but bounded —
+            // two cairnq installations in different schemas of ONE database hear each
+            // other's notifications, and a queue name they happen to share wakes the
+            // wrong workers. Correctness is unaffected (a wake is only ever a hint;
+            // the claim that follows re-reads the rows and finds none of them), so the
+            // cost is one wasted poll per foreign submit. Fixing it properly means
+            // putting the schema in the channel name, which is a migration and a
+            // mixed-version-fleet hazard: a worker still listening on the old channel
+            // would hear nothing and fall back to polling for the length of the
+            // rollout.
             const client = new pg.Client({ connectionString: dsn });
             await client.connect(); // failure here is transient: caller retries with backoff
             client.on("notification", (msg) => onNotify(msg.channel, msg.payload));