cairnq 0.13.0 → 0.14.0

package/src/store/base.ts

@@ -18,6 +18,47 @@ import {
 } from "../models.js";
 import { type BackpressureOptions, 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: object): boolean {
+  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 (this: unknown, _key: string, v: unknown): unknown {
   if (typeof v === "number" && !Number.isFinite(v)) {
     throw new SerializationError(`non-finite number ${v} is not JSON-serializable`);
@@ -28,15 +69,22 @@ const rejectMangled = function (this: unknown, _key: string, v: unknown): unknow
   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 as { constructor?: { name?: string } }).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: unknown): string {
   let text: string | undefined;
   try {
@@ -48,10 +96,36 @@ export function dumpJson(value: unknown): string {
   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")) JSON.stringify(value, rejectMangled);
+  // 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;
 }
 
@@ -106,7 +180,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 {
@@ -216,7 +291,9 @@ export function specialize(sql: string, params: Params): string {
     if (params[name] != null) active += name + ",";
   }
   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: string, column: string) =>
@@ -258,35 +335,6 @@ export 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 const DEFAULT_WATCH_POLL_MS = 2_000;
-
 export abstract class TaskStore {
   /** Set by useBackpressure; null means submit is ungated. */
   private gate: QueueDepthGate | null = null;
@@ -324,13 +372,6 @@ export abstract class TaskStore {
    */
   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
@@ -338,14 +379,6 @@ export abstract class TaskStore {
    */
   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.
@@ -384,6 +417,28 @@ export abstract class TaskStore {
   }
 
   // --------------------------------------------------------------- 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.
+   */
+  protected 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. */
+  private toTask(row: any): Task {
+    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
@@ -392,11 +447,13 @@ export abstract class TaskStore {
   private async ownedWrite(name: string, taskId: string, params: Params): Promise<Task> {
     const rows = await this.fetch(name, params);
     if (!rows.length) throw new LostLease(taskId);
-    return rowToTask(rows[0]);
+    return this.toTask(rows[0]);
   }
 
-  private static one(rows: any[]): Task | null {
-    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.
+  private one(rows: any[]): Task | null {
+    return rows.length ? this.toTask(rows[0]) : null;
   }
 
   private static oneRef(rows: any[]): TaskRef | null {
@@ -426,7 +483,7 @@ export abstract 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,
@@ -445,14 +502,14 @@ export abstract 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
     // gate cannot throttle one queue while the row lands on another.
     if (this.gate) await this.gate.acquire(ins.queue as string);
-    if (key === null) return rowToTask((await this.fetch("insert_task", ins))[0]);
+    if (key === null) 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
@@ -469,7 +526,7 @@ export abstract class TaskStore {
         const current = (await fetch("get", { id: existing[0].task_id }))[0];
         if (current) {
           if (conflict === "reject") throw new AlreadyExists(key);
-          if (reusable(conflict, current.status as TaskStatus)) return rowToTask(current);
+          if (reusable(conflict, current.status as TaskStatus)) 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
@@ -481,16 +538,16 @@ export abstract 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: string): Promise<Task | null> {
-    return TaskStore.one(await this.fetch("get", { id: taskId }));
+    return this.one(await this.fetch("get", { id: taskId }));
   }
 
   async getByKey(key: string): Promise<Task | null> {
-    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
@@ -523,15 +580,15 @@ export abstract class TaskStore {
       limit: input.limit ?? 100,
       offset: input.offset ?? 0,
     });
-    return rows.map(rowToTask);
+    return rows.map((r) => this.toTask(r));
   }
 
   async cancel(taskId: string): Promise<Task | null> {
-    return TaskStore.one(await this.fetch("cancel", { id: taskId }));
+    return this.one(await this.fetch("cancel", { id: taskId }));
   }
 
   async retry(taskId: string, opts: { resetAttempt?: boolean } = {}): Promise<Task | null> {
-    return TaskStore.one(
+    return this.one(
       await this.fetch("retry", { id: taskId, reset_attempt: opts.resetAttempt ?? false }),
     );
   }
@@ -555,7 +612,7 @@ export abstract class TaskStore {
       await fetch("lock_key", { key });
       const existing = (await fetch("get_key", { key })) as { task_id: string }[];
       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 }));
     });
   }
 
@@ -580,104 +637,12 @@ export abstract class TaskStore {
     return rows.map((r) => r.id as 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.
-   */
-  async stats(queue?: string): Promise<Record<string, Record<TaskStatus, number>>> {
-    const zeros = (): Record<TaskStatus, number> =>
-      Object.fromEntries(STATUSES.map((s) => [s, 0])) as Record<TaskStatus, number>;
-    const out: Record<string, Record<TaskStatus, number>> = {};
-    // 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 as TaskStatus] = 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: WatchOptions, onSignal: (signal: WatchSignal) => void): () => void {
-    const pollMs = Math.max(1, opts.pollMs ?? DEFAULT_WATCH_POLL_MS);
-    const queues = opts.queues ?? null;
-    let live = true;
-    const emit = (signal: WatchSignal): void => {
-      // 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: string, maxDepth: number): Promise<number> {
     if (!Number.isInteger(maxDepth) || maxDepth < 0) {
@@ -782,7 +747,7 @@ export abstract class TaskStore {
           name: oneName ? names![0] : null,
           limit,
         });
-        return rows.map(rowToTask);
+        return rows.map((r) => this.toTask(r));
       });
     });
   }
@@ -888,7 +853,7 @@ export abstract 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 };
     });
   }
 

package/src/store/pg-executor.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. */

package/src/store/pg-pool.ts

@@ -160,6 +160,20 @@ export async function createPoolExecutor(
       // 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));

package/src/store/postgres.ts

@@ -9,7 +9,6 @@ import {
   specialize,
   statementParams,
   TaskStore,
-  type WatchSignal,
 } from "./base.js";
 import { ListenUnavailable, type PgExecutor, type PgSession } from "./pg-executor.js";
 import { createPoolExecutor } from "./pg-pool.js";
@@ -144,9 +143,6 @@ export class PostgresStore extends TaskStore {
   private readonly wakeableQueues = new Set<string>();
   /** Wake callbacks by key: "queued" (broadcast) or "done:<task id>". */
   private readonly waiters = new Map<string, Set<() => void>>();
-  /** watch() subscribers. Separate from `waiters`: a waiter is one-shot and
-   * consumes the notification, a subscriber is standing and only observes. */
-  private readonly subscribers = new Set<(signal: WatchSignal) => void>();
 
   /**
    * `source` is either a libpq connection string — this store then owns a `pg`
@@ -199,8 +195,8 @@ export class PostgresStore extends TaskStore {
    * 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
+   * exists. The fields' initializers give the first state and doConnect calls
+   * this for every later one, so the three cannot be re-armed by halves. Only
    * ever safe under doConnect's generation check.
    */
   private resetListenerState(): void {
@@ -220,6 +216,9 @@ export class PostgresStore extends TaskStore {
       await this.checkSchema(executor);
       await this.applyMigrations(executor);
       checkProtocolVersion(await this.readProtocolVersion(executor));
+      // Before publishing the executor, so no row is ever mapped against an
+      // unmeasured wire form.
+      this.jsonIsText = await this.detectJsonWireForm(executor);
     } catch (e) {
       // Never leak an executor we created; never close one we were handed.
       if (!this.provided) await executor.close().catch(() => {});
@@ -321,6 +320,25 @@ export class PostgresStore extends TaskStore {
     }
   }
 
+  /**
+   * Whether this driver hands json/jsonb back as text, measured rather than
+   * assumed.
+   *
+   * `pg` decodes jsonb by default; asyncpg hands back the text; an application's
+   * own driver — or a `pg` with a type parser the application installed — may do
+   * either, and an injected executor is exactly that case. The two are
+   * indistinguishable from a value once it arrives (see rowToTask), so the
+   * answer has to come from the driver itself.
+   *
+   * A JSON string is the probe because it is the only value whose two forms
+   * differ: as text it arrives with its quotes (`"cairnq"`, 8 characters), as a
+   * decoded value without them (`cairnq`, 6). One statement, once per connect.
+   */
+  private async detectJsonWireForm(s: PgSession): Promise<boolean> {
+    const rows = await s.query(`select '"cairnq"'::jsonb as probe`, []);
+    return rows[0]?.probe === '"cairnq"';
+  }
+
   // Takes an explicit session: during doConnect the executor is not published
   // yet, so this cannot go through fetch(). The statement binds nothing.
   private async readProtocolVersion(s: PgSession): Promise<number> {
@@ -355,16 +373,6 @@ export class PostgresStore extends TaskStore {
     }
   }
 
-  protected subscribePush(onSignal: (signal: WatchSignal) => void): () => void {
-    this.subscribers.add(onSignal);
-    this.listenerReady(); // an API-side watcher is often the only thing asking
-    return () => void this.subscribers.delete(onSignal);
-  }
-
-  protected warmPush(): void {
-    if (this.subscribers.size > 0) this.listenerReady();
-  }
-
   taskDoneWake(taskId: string, timeoutMs: number): Promise<void> {
     if (!this.listenerReady()) return super.taskDoneWake(taskId, timeoutMs);
     return this.wakeOn(`done:${taskId}`, timeoutMs);
@@ -453,10 +461,8 @@ export class PostgresStore extends TaskStore {
       // Buffered only for a queue someone waits on — see wakeableQueues.
       if (this.wakeableQueues.has(payload)) this.pendingQueues.add(payload);
       key = "queued";
-      this.publish({ reason: "queued", queue: payload });
     } else if (channel === DONE_CHANNEL && payload) {
       key = `done:${payload}`;
-      this.publish({ reason: "done", taskId: payload });
     } else {
       return;
     }
@@ -465,19 +471,6 @@ export class PostgresStore extends TaskStore {
     if (set) for (const w of set) w();
   }
 
-  /** Hand a notification to every watch() subscriber. A throwing subscriber is
-   * its own problem: it must not cost the others their signal, nor take down the
-   * listener connection that delivered it. */
-  private publish(signal: WatchSignal): void {
-    for (const s of [...this.subscribers]) {
-      try {
-        s(signal);
-      } catch {
-        // Deliberately swallowed — see above.
-      }
-    }
-  }
-
   private dropListener(): void {
     const stop = this.listener;
     this.listener = null;