@ultimat3/realtime 23.0.0 → 24.0.0

package/src/page-outbox.ts

@@ -1,13 +1,10 @@
 /**
- * The page's ONE outbox: writes a page could not send are queued in `OfflineQueue`, persisted in
- * the page's durable store under the current principal, and replayed IN ORDER over HTTP — each to
- * `actionPath(name)` through core's `clientTransport`, each with its own idempotency key, so a
- * replay after a lost response is answered from the action's idempotency store and never applied
- * twice. Replayed on open, on `online`, and on the service worker's `OUTBOX_DRAIN_MESSAGE`.
- * A principal change wipes the previous principal's queue: its writes are never sent as the next.
+ * The page's ONE outbox: writes a page could not send, persisted under the current principal and
+ * replayed IN ORDER over HTTP, each under its own idempotency key. AT LEAST once — an entry leaves
+ * the disk when its ack is written. A principal change abandons the pass and wipes the queue.
  */
 
-import type { ClientScope } from '@ultimat3/core/page';
+import type { ClientScope, UltimateError } from '@ultimat3/core/page';
 import {
   actionPath,
   classifyThrown,
@@ -15,12 +12,14 @@ import {
   OUTBOX_DRAIN_MESSAGE,
   onRescope,
   pageClient,
+  renderThrowable,
 } from '@ultimat3/core/page';
 import type { LocalStore } from './local-store-idb';
 import { pageLocalStore, scopeKey } from './local-store-idb';
 import type { DrainReport, QueuedMutation, QueueState, QueueStore } from './offline-queue';
 import { MemoryQueueStore, OfflineQueue, toQueueError } from './offline-queue';
 import { OUTBOX_KEY, type OutboxEntry, type OutboxHandle, type OutboxHost } from './outbox-slot';
+import { LocalStoreUnavailableError, OfflineQueueAbandonedError } from './page-errors';
 import { peekPageRealtime } from './page-store';
 import { carriedBy } from './record-store';
 
@@ -63,70 +62,142 @@ export interface OutboxOptions {
    * the write queued and the post it liked missing, and showed the old count.
    */
   readonly beforeEnqueue?: (() => Promise<void>) | undefined;
+  /** Where a disk that refused the queue is said, by code. Default `console.warn`. */
+  readonly warn?: ((error: UltimateError) => void) | undefined;
 }
 
 const EMPTY: DrainReport = { sent: 0, collapsed: 0, remaining: 0, stoppedAt: null };
 
+/** One principal's open queue, and the scope the drain lock is named after. */
+interface Held {
+  readonly queue: OfflineQueue;
+  readonly scope: string | undefined;
+}
+
 export function createOutbox(options: OutboxOptions): PageOutbox {
   const principal =
     options.principal ?? ((): ClientScope['principal'] => pageClient().scope.principal);
   const send = options.send ?? sendOverHttp;
   const overlays =
     options.overlays ?? ((): OutboxOverlays | undefined => peekPageRealtime()?.store);
-  let queue: OfflineQueue | undefined;
-  /** The scope the open queue belongs to — what the drain lock is named after. */
-  let scope: string | undefined;
+  /**
+   * The open queue AND the scope it belongs to, as one value: a pass captures both when it starts,
+   * so nothing it does later can be read off a principal that arrived since.
+   */
+  let held: Held | undefined;
+  /**
+   * Bumped by every principal change, SYNCHRONOUSLY. Anything here that resolves a queue after an
+   * await compares it first: the answer to "whose queue" must be the one from before the await.
+   */
+  let epoch = 0;
+  const warn = options.warn ?? ((error: UltimateError): void => console.warn(error));
+  const unavailable = (what: string, error: unknown): void =>
+    warn(new LocalStoreUnavailableError({ reason: `${what}: ${renderThrowable(error)}` }));
 
+  /** Never rejects: a queue the disk would not open is a memory queue, said once by code. */
   const open = async (): Promise<void> => {
-    scope = scopeKey(principal());
-    queue = await OfflineQueue.open(queueStore(await options.local, scope));
-  };
-  let ready = open();
-  let running: Promise<DrainReport> | undefined;
-  /** A trigger landed while a pass ran: one more pass follows it, never one per trigger. */
-  let again = false;
-
-  const deliver = async (mutation: QueuedMutation): Promise<void> => {
-    const current = queue;
-    const carried = new Set<string>();
+    const at = epoch;
+    const scope = scopeKey(principal());
+    let queue: OfflineQueue;
     try {
-      await send({ key: mutation.key, name: mutation.name, input: mutation.input }, carried);
+      queue = await OfflineQueue.open(queueStore(await options.local, scope));
     } catch (error) {
-      const kind = classifyThrown(error);
-      // The network, or a server asking to be asked again: stays queued, and the pass stops so
-      // nothing behind it overtakes it.
-      if (kind === 'retryable' || kind === 'retry-after') throw error;
-      // Anything else is the server's decision about this write — kept for the UI, never resent.
-      await current?.fail(mutation.key, toQueueError(error));
-      overlays()?.drop(mutation.key);
+      unavailable('the outbox could not be opened', error);
+      queue = await OfflineQueue.open(new MemoryQueueStore());
+    }
+    // The principal left while the disk was being read: this queue is the one that left with it,
+    // and the handler that saw the change has already chained the next open.
+    if (at !== epoch) {
+      queue.abandon();
       return;
     }
-    await current?.ack(mutation.key);
-    const store = overlays();
-    try {
-      // Exactly as a live write settles: a row the answer did not carry keeps its overlay until
-      // the server's row for it arrives.
-      store?.settle(mutation.key, carried);
-    } catch {
-      // A custom merge that answered no row: the server's truth stands.
-      store?.drop(mutation.key);
+    held?.queue.abandon();
+    held = { queue, scope };
+  };
+  let ready = open();
+  /** The current principal's queue: `ready` is re-made by a rescope, so it is re-read until still. */
+  const current = async (): Promise<Held | undefined> => {
+    for (;;) {
+      const opening = ready;
+      await opening;
+      if (opening === ready) return held;
     }
   };
+  let running: Promise<DrainReport> | undefined;
+  /** A trigger landed while a pass ran: one more pass follows it, never one per trigger. */
+  let again = false;
+
+  const deliver =
+    (queue: OfflineQueue) =>
+    async (mutation: QueuedMutation): Promise<void> => {
+      const carried = new Set<string>();
+      try {
+        await send({ key: mutation.key, name: mutation.name, input: mutation.input }, carried);
+      } catch (error) {
+        const kind = classifyThrown(error);
+        // The network, or a server asking to be asked again: stays queued, and the pass stops so
+        // nothing behind it overtakes it. So does a queue whose principal left mid-send.
+        if (kind === 'retryable' || kind === 'retry-after' || queue.abandoned) throw error;
+        // Anything else is the server's decision about this write — kept for the UI, never resent.
+        await queue.fail(mutation.key, toQueueError(error));
+        overlays()?.drop(mutation.key);
+        return;
+      }
+      // The principal changed while this was on the wire: its store and its twins are already
+      // gone, and what is on the page now is somebody else's.
+      if (queue.abandoned) return;
+      await queue.ack(mutation.key);
+      const store = overlays();
+      try {
+        // Exactly as a live write settles: a row the answer did not carry keeps its overlay until
+        // the server's row for it arrives.
+        store?.settle(mutation.key, carried);
+      } catch {
+        // A custom merge that answered no row: the server's truth stands.
+        store?.drop(mutation.key);
+      }
+    };
 
   onRescope((_next, prev) => {
     const gone = scopeKey(prev.principal);
+    // SYNCHRONOUSLY, before anything is awaited: a pass parked inside `send` resumes into the next
+    // principal's session, and the wipe below reaches the disk but never the pass. Abandoned, it
+    // sends nothing more and writes nothing back.
+    held?.queue.abandon();
+    held = undefined;
+    epoch += 1;
+    // The single-flight slot is the principal's too: left set, the next principal's trigger JOINED
+    // the abandoned pass — handed its report, another principal's key in it — and its own queue
+    // was not drained until some later trigger. `settled` only clears a slot that is still its own.
+    running = undefined;
+    again = false;
     ready = ready.then(async () => {
-      if (gone !== undefined) await (await options.local).wipe(gone);
+      try {
+        if (gone !== undefined) await (await options.local).wipe(gone);
+      } catch (error) {
+        // Still on disk, under the scope that left: unreachable from this principal, and the next
+        // boot's `wipeOthers` takes it. Said, never thrown — a rejection here used to poison the
+        // chain, so every later enqueue, replay and rescope on this tab failed with it.
+        unavailable("the previous principal's outbox could not be wiped", error);
+      }
       await open();
     });
   });
 
   const self: PageOutbox = {
     enqueue: async (entry) => {
+      // WHOSE queue is decided now, before anything is awaited: resolved after the flush below,
+      // a write issued under one principal and parked there was queued — and sent — as the next.
+      // A queue still opening is waited for, and belongs to this call only if nobody left since.
+      const at = epoch;
+      const mine = held ?? (await current());
+      if (mine === undefined || at !== epoch) {
+        throw new OfflineQueueAbandonedError({ name: entry.name });
+      }
       // A disk that refused the rows must not also cost the write: the intent still goes on disk.
       await options.beforeEnqueue?.().catch(() => undefined);
-      await ready;
-      await queue?.enqueue(entry);
+      // Abandoned meanwhile, it refuses by the same code.
+      await mine.queue.enqueue(entry);
     },
     replay: () => {
       // Single flight: a trigger that lands while a replay is running JOINS it. Open, `online`,
@@ -140,20 +211,19 @@ export function createOutbox(options: OutboxOptions): PageOutbox {
         return running;
       }
       const pass = (async (): Promise<DrainReport> => {
-        await ready;
-        if (queue === undefined) return EMPTY;
+        const now = await current();
+        if (now === undefined) return EMPTY;
         // Checked when the pass STARTS, whoever asked (the socket's reconnect asks too): an
         // attempt the browser already knows cannot leave is a failed request on the wire and
         // nothing more. `online` asks again.
-        if (knownOffline()) return { ...EMPTY, remaining: queue.pending().length };
-        const draining = queue;
+        if (knownOffline()) return { ...EMPTY, remaining: now.queue.pending().length };
         // One tab drains a principal's outbox at a time, and it drains what EVERY tab queued: the
         // queue is re-read under the lock, so a write another tab made since this one opened is
         // sent too, and an `inflight` entry — which only a pass holding this lock could have put
         // on the wire, and it is over — goes back to `pending`.
-        return await exclusive(`ultimate-outbox:${scope ?? 'memory'}`, async () => {
-          await draining.reload();
-          return await draining.drain(deliver);
+        return await exclusive(`ultimate-outbox:${now.scope ?? 'memory'}`, async () => {
+          await now.queue.reload();
+          return await now.queue.drain(deliver(now.queue));
         });
       })();
       const settled = (report?: DrainReport): void => {
@@ -172,9 +242,10 @@ export function createOutbox(options: OutboxOptions): PageOutbox {
       return pass;
     },
     get size(): number {
-      return queue?.pending().length ?? 0;
+      return held?.queue.pending().length ?? 0;
     },
-    pending: () => (queue?.pending() ?? []).map(({ key, name, input }) => ({ key, name, input })),
+    pending: () =>
+      (held?.queue.pending() ?? []).map(({ key, name, input }) => ({ key, name, input })),
     get ready(): Promise<void> {
       return ready;
     },

package/src/pg-advisory-lock.ts

@@ -3,11 +3,11 @@
 // is scoped to this connection's Postgres *session*, so acquiring means keeping the connection
 // open and releasing means closing it: no lease, no renewal, no fencing token, ever.
 
+import type { AdvisoryLock } from './advisory-lock';
 import { ReplicationFailedError } from './errors';
 import { PgConnection, type PgRows } from './pg-connection';
 import { bunPgStream, type PgTarget, parsePgUrl } from './pg-socket';
 import type { PgStream } from './pg-wire';
-import type { AdvisoryLock } from './replicator';
 import type { Rng } from './thundering-herd';
 
 /** A key reaches a simple query unparameterised, so its charset is the injection boundary. */
@@ -45,6 +45,7 @@ export class PgAdvisoryLock implements AdvisoryLock {
    * the process dies. A standby then never takes over a slot whose owner has already stopped.
    */
   #acquiring: Promise<boolean> | null = null;
+  readonly #lostListeners = new Set<(reason: string) => void>();
 
   constructor(options: PgAdvisoryLockOptions) {
     if (!KEY_PATTERN.test(options.key)) {
@@ -91,6 +92,7 @@ export class PgAdvisoryLock implements AdvisoryLock {
       database: target.database,
       applicationName: `ultimate-replicator-lock:${this.key}`,
       rng: this.#options.rng,
+      ssl: target.ssl,
     });
     let rows: PgRows;
     try {
@@ -110,9 +112,51 @@ export class PgAdvisoryLock implements AdvisoryLock {
     // `release()` — which is exactly what lets a crashed replicator free the slot with nothing
     // left to clean up.
     this.#connection = connection;
+    // The session is idle from here on, and an idle session has no reader: without this a server
+    // that ended it was never noticed, and `tryAcquire()` went on answering `true` from memory
+    // for a lock Postgres had already handed to another process.
+    connection.watchIdle((reason) => this.#lost(connection, reason));
     return true;
   }
 
+  /**
+   * Drop the session without the unlock statement. The socket is closed outright — no goodbye is
+   * written, because a write to a black-holed socket is one more thing that never settles — and
+   * Postgres releases the lock when the session ends. An acquisition still in flight is dropped
+   * the moment it lands.
+   */
+  abandon(): void {
+    const acquiring = this.#acquiring;
+    if (acquiring !== null) {
+      // Voided: its own caller has the outcome; this only makes sure nothing stays held after it.
+      void acquiring.then(
+        () => this.abandon(),
+        () => undefined,
+      );
+      return;
+    }
+    const connection = this.#connection;
+    if (connection === null) return;
+    this.#connection = null;
+    connection.destroy();
+  }
+
+  onLost(listener: (reason: string) => void): () => void {
+    this.#lostListeners.add(listener);
+    return () => {
+      this.#lostListeners.delete(listener);
+    };
+  }
+
+  /** The session ended underneath the lock. A release that got there first owns the goodbye. */
+  #lost(connection: PgConnection, reason: string): void {
+    if (this.#connection !== connection) return;
+    this.#connection = null;
+    // The socket is already gone: nothing is said to it, and the listeners hear first.
+    connection.destroy();
+    for (const listener of [...this.#lostListeners]) listener(reason);
+  }
+
   async release(): Promise<void> {
     // A release that arrives mid-acquisition waits it out. `#connection` is still `null` there, so
     // the early return below would answer "nothing to release" and the session would open behind

package/src/pg-auth.ts

@@ -63,8 +63,10 @@ class ScramSha256Session implements ScramSession {
     if (!serverNonce.startsWith(this.#clientNonce)) {
       throw new ReplicationProtocolError({
         stage: 'auth',
-        detail: `server nonce "${serverNonce}" does not extend client nonce "${this.#clientNonce}"`,
-        fix: 'x doctor db — the server did not echo the client nonce; check for a proxy on the replication URL',
+        detail:
+          `server nonce "${serverNonce}" does not extend client nonce "${this.#clientNonce}" — ` +
+          'the server did not echo the client nonce; check for a proxy on the replication URL',
+        fix: 'x doctor --json',
       });
     }
 
@@ -216,8 +218,11 @@ function parseServerFirst(text: string): ServerFirst {
   if (iterations > MAX_SCRAM_ITERATIONS) {
     throw new ReplicationProtocolError({
       stage: 'auth',
-      detail: `server-first-message asked for ${iterationsText} PBKDF2 iterations, above the ${MAX_SCRAM_ITERATIONS} ceiling`,
-      fix: 'x doctor db — point the replication URL at postgres itself; a real server asks for 4096',
+      detail:
+        `server-first-message asked for ${iterationsText} PBKDF2 iterations, above the ` +
+        `${MAX_SCRAM_ITERATIONS} ceiling — a real server asks for 4096, so point the replication ` +
+        'URL at postgres itself',
+      fix: 'x doctor --json',
     });
   }
   const salt = decodeBase64('salt', saltB64);

package/src/pg-bytes.ts

@@ -129,7 +129,10 @@ export class ByteWriter {
   }
 
   uint8(value: number): this {
-    this.#bytes[this.#room(1)] = value & 0xff;
+    // The offset FIRST: `#room` may replace `#bytes`, and `this.#bytes[this.#room(1)]` reads the
+    // old buffer before it does — the byte that caused a growth was written into the discard.
+    const at = this.#room(1);
+    this.#bytes[at] = value & 0xff;
     return this;
   }
 

package/src/pg-connection.ts

@@ -2,7 +2,7 @@
 // queries, and the CopyBoth switch that a replication stream lives inside. It speaks only in
 // messages, never in bytes on a socket, so the whole handshake is driven by hand in the tests.
 
-import { logger } from '@ultimat3/core';
+import { logger, renderThrowable } from '@ultimat3/core';
 import { ReplicationFailedError, ReplicationProtocolError } from './errors';
 import {
   chooseMechanism,
@@ -12,6 +12,7 @@ import {
   scramSession,
 } from './pg-auth';
 import { ByteReader } from './pg-bytes';
+import { answersWeakAuth, type SslMode } from './pg-tls';
 import {
   copyDoneMessage,
   frame,
@@ -42,6 +43,11 @@ export interface PgConnectionOptions {
   readonly applicationName?: string | undefined;
   /** Injected so the SCRAM nonce is deterministic under a seeded test. */
   readonly rng?: Rng | undefined;
+  /**
+   * The `sslmode` the stream was dialled under — what decides whether a cleartext or md5 password
+   * request is answered (`answersWeakAuth`). Unstated is `prefer`, which refuses both.
+   */
+  readonly ssl?: SslMode | undefined;
 }
 
 /** A result set as text, exactly as the wire carries it. `null` is SQL NULL, never `''`. */
@@ -61,12 +67,30 @@ const needPassword = (method: string): ReplicationFailedError =>
     fix: 'put the credentials in the URL: postgres://user:password@host:5432/db',
   });
 
+/**
+ * The server asked for the password in a form the network can use, on a session nothing
+ * guarantees is encrypted. Refused before a byte of it is written.
+ */
+const weakAuthRefused = (method: string, ssl: SslMode | undefined): ReplicationFailedError =>
+  new ReplicationFailedError({
+    stage: 'auth',
+    detail:
+      `the server asked for ${method} and sslmode=${ssl ?? 'prefer'} does not guarantee an ` +
+      'encrypted session — connect with ?sslmode=require (or verify-full), move the role to ' +
+      'scram-sha-256, or state ?sslmode=disable to accept a cleartext session',
+    fix: 'x doctor --json',
+  });
+
 export class PgConnection {
   readonly #stream: PgStream;
   readonly #reader: MessageReader;
   readonly #parameters = new Map<string, string>();
   #copyBoth = false;
   #closed = false;
+  /** The read parked on an idle session, if one is — see `watchIdle`. A query takes it over. */
+  #idle: Promise<PgMessage | undefined> | undefined;
+  #onIdleEnd: ((reason: string) => void) | undefined;
+  #querying = false;
 
   private constructor(stream: PgStream) {
     this.#stream = stream;
@@ -123,26 +147,82 @@ export class PgConnection {
 
   /** One simple query. Returns the rows as text; a `CommandComplete` with no rows returns `[]`. */
   async query(sql: string): Promise<PgRows> {
-    await this.#stream.write(queryMessage(sql));
-    const rows: (readonly (string | null)[])[] = [];
-    for (;;) {
-      const message = await this.#expect('query');
-      switch (message.tag) {
-        case 'D':
-          rows.push(dataRow(message.body));
-          break;
-        case 'E':
-          // Drain to `ReadyForQuery` first: leaving the session mid-result desynchronises reuse.
-          await this.#drainToReady();
-          throw serverError('query', message.body);
-        case 'Z':
-          return rows;
-        default:
-          this.#note(message);
+    this.#querying = true;
+    try {
+      await this.#stream.write(queryMessage(sql));
+      const rows: (readonly (string | null)[])[] = [];
+      for (;;) {
+        const message = await this.#expect('query');
+        switch (message.tag) {
+          case 'D':
+            rows.push(dataRow(message.body));
+            break;
+          case 'E':
+            // Drain to `ReadyForQuery` first: leaving the session mid-result desynchronises reuse.
+            await this.#drainToReady();
+            throw serverError('query', message.body);
+          case 'Z':
+            return rows;
+          default:
+            this.#note(message);
+        }
       }
+    } finally {
+      this.#querying = false;
+      this.#park();
     }
   }
 
+  /**
+   * Watch a session that is doing NOTHING. An idle connection has no reader, so a server that
+   * ended it — a failover, `pg_terminate_backend`, a dropped socket — was noticed by the next
+   * statement, which for a session held only for its advisory lock is never. This parks one read
+   * between queries: EOF, a read error or an ErrorResponse calls `onEnd` once, with why.
+   *
+   * Never for `close()`. A `query()` takes the parked read over rather than racing it — the stream
+   * allows one reader — and the watch resumes when the query is done.
+   */
+  watchIdle(onEnd: (reason: string) => void): void {
+    this.#onIdleEnd = onEnd;
+    this.#park();
+  }
+
+  #park(): void {
+    if (this.#closed || this.#querying || this.#copyBoth) return;
+    if (this.#onIdleEnd === undefined || this.#idle !== undefined) return;
+    const parked = this.#reader.next();
+    this.#idle = parked;
+    const ended = (reason: string): void => {
+      const onEnd = this.#onIdleEnd;
+      this.#onIdleEnd = undefined;
+      if (!this.#closed) onEnd?.(reason);
+    };
+    parked.then(
+      (message) => {
+        // A query took this read over: the message is its answer, not this watch's.
+        if (this.#idle !== parked) return;
+        this.#idle = undefined;
+        if (message === undefined) return ended('the server closed the connection');
+        if (message.tag === 'E') return ended(renderThrowable(serverError('idle', message.body)));
+        this.#note(message);
+        this.#park();
+      },
+      (failure: unknown) => {
+        if (this.#idle !== parked) return;
+        this.#idle = undefined;
+        ended(renderThrowable(failure));
+      },
+    );
+  }
+
+  /** The next message: the read an idle watch already parked, when there is one. */
+  #next(): Promise<PgMessage | undefined> {
+    const parked = this.#idle;
+    if (parked === undefined) return this.#reader.next();
+    this.#idle = undefined;
+    return parked;
+  }
+
   /**
    * `START_REPLICATION` — the connection stops being request/response and becomes a duplex copy
    * stream. There is no way back short of closing it, which is why this is one-way on purpose.
@@ -205,6 +285,18 @@ export class PgConnection {
     this.#stream.close();
   }
 
+  /**
+   * Close the socket and say nothing — no `Terminate`, nothing awaited. For a session that may
+   * already be dead: `close()` writes a goodbye first, and a write to a black-holed socket is a
+   * promise nothing settles. The server ends the session when the socket goes, which releases
+   * whatever the session held. Never reported to an idle watch.
+   */
+  destroy(): void {
+    if (this.#closed) return;
+    this.#closed = true;
+    closeQuietly(this.#stream);
+  }
+
   async #authenticate(options: PgConnectionOptions): Promise<void> {
     let scram: ScramSession | undefined;
     for (;;) {
@@ -222,12 +314,16 @@ export class PgConnection {
         case AUTH_CLEARTEXT: {
           const password = options.password ?? '';
           if (password === '') throw needPassword('a cleartext password');
+          if (!answersWeakAuth(options.ssl)) {
+            throw weakAuthRefused('a cleartext password', options.ssl);
+          }
           await this.#stream.write(passwordMessage(password));
           break;
         }
         case AUTH_MD5: {
           const password = options.password ?? '';
           if (password === '') throw needPassword('an md5 password');
+          if (!answersWeakAuth(options.ssl)) throw weakAuthRefused('an md5 password', options.ssl);
           const salt = reader.take(4);
           await this.#stream.write(
             passwordMessage(md5Password({ user: options.user, password, salt })),
@@ -276,13 +372,13 @@ export class PgConnection {
 
   async #drainToReady(): Promise<void> {
     for (;;) {
-      const message = await this.#reader.next();
+      const message = await this.#next();
       if (message === undefined || message.tag === 'Z') return;
     }
   }
 
   async #expect(stage: string): Promise<PgMessage> {
-    const message = await this.#reader.next();
+    const message = await this.#next();
     if (message !== undefined) return message;
     throw new ReplicationFailedError({
       stage,
@@ -315,8 +411,10 @@ export class PgConnection {
 const outOfOrder = (what: string): ReplicationProtocolError =>
   new ReplicationProtocolError({
     stage: 'auth',
-    detail: `the server sent ${what} before it offered a SASL mechanism`,
-    fix: 'x doctor db — the SASL exchange arrived out of order; check for a pooler or proxy between this client and postgres',
+    detail:
+      `the server sent ${what} before it offered a SASL mechanism — the exchange arrived out of ` +
+      'order; check for a pooler or proxy between this client and postgres',
+    fix: 'x doctor --json',
   });
 
 /** A `close()` that throws must not replace the handshake failure that is worth reporting. */

package/src/pg-entity-row.ts

@@ -58,3 +58,19 @@ export function entityRow(
   for (const field of sealedFields(entity)) delete row[field.property];
   return row;
 }
+
+/**
+ * The entity properties a decoded `after` image does not carry — what an UPDATE's unchanged TOAST
+ * columns become once the tuple is an entity row. Asked only when the tuple said it left columns
+ * out, and answered in the row's own vocabulary: a consumer compares these against the properties
+ * it projects, and it has never seen a physical column name. A sealed column is never listed: no
+ * change names one, so its absence says nothing.
+ */
+export function omittedProperties(relation: PgRelation, row: PhysicalRow): readonly string[] {
+  const entity = entityForTable(relation.name);
+  if (entity === undefined) return [];
+  const sealed = new Set(sealedFields(entity).map((field) => field.property));
+  return Object.keys(entity.$columns)
+    .filter((property) => !Object.hasOwn(row, property) && !sealed.has(property))
+    .sort();
+}

package/src/pg-identity-tables.ts

@@ -0,0 +1,25 @@
+// Single responsibility: which replicated tables need `REPLICA IDENTITY FULL` for a reason the
+// live-query path does not have — a channel with params routes a DELETE by columns of the OLD row.
+
+import type { Channel } from './channel-decl';
+import { registeredChannels } from './channel-registry';
+
+/**
+ * The `records` tables of every channel declared with params, deduped and sorted.
+ *
+ * A live query never needs FULL on a keyed table: its shared window holds the whole row, so a
+ * delete that names only the key is enough. A channel holds no window. Its removal is routed to
+ * the topic the old row's params name (`channel-records.ts`), and under the default identity the
+ * old image is the key alone — it names no topic, no `remove` is sent, and every member keeps the
+ * deleted record. A channel with no params has one topic and needs nothing.
+ */
+export function paramsChannelTables(
+  channels: Iterable<Channel> = registeredChannels(),
+): readonly string[] {
+  const tables = new Set<string>();
+  for (const declared of channels) {
+    if (declared.params.length === 0) continue;
+    for (const projection of declared.records) tables.add(projection.table);
+  }
+  return [...tables].sort();
+}