@ultimat3/realtime 22.15.0 → 24.0.0

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

@@ -6,8 +6,12 @@
 // pair folded into money by name. So a nullable money column diverged from the repository shape,
 // two plain columns that happened to be called `x_minor`/`x_currency` were folded into a `Money`,
 // and a `.column()` rename arrived under its physical name. One decoder, the entity's, now.
+//
+// A SEALED column is the one place a live row is not the repository's: the log carries the stored
+// string, and nothing here opens it. It is dropped, so a change — on the bus, in the ring, in a
+// patch frame — names no sealed column at all.
 
-import { decodeRow, entityForTable } from '@ultimat3/entity';
+import { decodeRow, entityForTable, sealedFields } from '@ultimat3/entity';
 import { ReplicationProtocolError } from './errors';
 import type { PhysicalRow } from './pg-values';
 import type { PgRelation } from './pgoutput';
@@ -47,5 +51,26 @@ export function entityRow(
     });
   }
   const source = image === 'before' ? replicatedOnly(relation, physical) : physical;
-  return decodeRow(entity, source) as PhysicalRow;
+  const row = decodeRow(entity, source) as PhysicalRow;
+  // Not opened and not forwarded. A client never receives a sealed column on any other path, so
+  // a patch carrying one would be the only frame that does — and a `lookup` column's stored string
+  // is the same for equal plaintexts, which tells every subscriber which rows share a value.
+  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();
+}

package/src/pg-preflight.ts

@@ -1,7 +1,7 @@
-// Single responsibility: the four questions asked of a database BEFORE `START_REPLICATION`. Two
-// refuse the boot with the exact statement that fixes them, one — the publication — is answered by
-// ensuring it (`pg-publication.ts`), and the fourth warns, because refusing it would stop every app
-// on the default replica identity from starting.
+// Single responsibility: the questions asked of a database BEFORE `START_REPLICATION`. Two refuse
+// the boot with the exact statement that fixes them, one — the publication — is answered by
+// ensuring it (`pg-publication.ts`), and the replica-identity ones warn, because refusing would
+// stop every app on the default replica identity from starting.
 
 import { logger } from '@ultimat3/core';
 import { ReplicaIdentityError, ReplicationFailedError } from './errors';
@@ -22,6 +22,7 @@ export async function preflight(
   slot: string,
   publication: string,
   entities: ReadonlySet<string>,
+  fullIdentity: ReadonlySet<string> = new Set(),
 ): Promise<void> {
   assertIdentifier('slot', slot);
   assertIdentifier('publication', publication);
@@ -37,6 +38,7 @@ export async function preflight(
   }
   await ensurePublication(connection, publication, entities);
   await warnPartialIdentity(connection, entities);
+  await warnChannelIdentity(connection, entities, fullIdentity);
   const [existing] = await connection.query(
     `SELECT plugin FROM pg_replication_slots WHERE slot_name = '${slot}'`,
   );
@@ -102,3 +104,47 @@ async function warnPartialIdentity(
   // `@ultimat3/http`'s error-map stage follows, so a log index can be alerted on by code.
   logger.warn(warning.code, { cause: warning.cause, fix: warning.fix, tables });
 }
+
+/** The log event a params channel's table without FULL identity is reported under. */
+export const CHANNEL_IDENTITY_EVENT = 'replication.channel_identity_partial';
+
+const CHANNEL_IDENTITY_FIX = 'x db gen "replica identity full"';
+
+/**
+ * The tables a channel with params carries that are not `REPLICA IDENTITY FULL`. Their DELETE logs
+ * the key alone, the channel reads its topic off columns the key does not include, and the removal
+ * is sent to nobody: members keep a record that no longer exists, and nothing else says so.
+ *
+ * WARNED, like its neighbour, and for the same reason. Only names that are also in the entity list
+ * are asked about — that list has been through `assertIdentifier`, which is what makes the
+ * interpolation safe; a declared table the feed does not decode is not this stream's to judge.
+ */
+async function warnChannelIdentity(
+  connection: PgConnection,
+  entities: ReadonlySet<string>,
+  fullIdentity: ReadonlySet<string>,
+): Promise<void> {
+  const asked = [...fullIdentity].filter((name) => entities.has(name)).sort();
+  if (asked.length === 0) return;
+  const names = asked.map((name) => `'${name}'`).join(', ');
+  const rows = await connection.query(
+    `SELECT c.relname FROM pg_class c WHERE c.relkind = 'r' AND c.relname IN (${names}) ` +
+      `AND c.relreplident <> 'f'`,
+  );
+  const tables = [
+    ...new Set(
+      rows
+        .map((row) => row[0])
+        .filter((name): name is string => typeof name === 'string' && asked.includes(name)),
+    ),
+  ].sort();
+  if (tables.length === 0) return;
+  logger.warn(CHANNEL_IDENTITY_EVENT, {
+    cause:
+      `${tables.join(', ')} carry a channel declared with params but are not REPLICA IDENTITY ` +
+      'FULL, so a DELETE names no topic and its members keep the deleted record',
+    // `x db gen` reads the same declarations this warning does and writes the ALTER per table.
+    fix: CHANNEL_IDENTITY_FIX,
+    tables,
+  });
+}

package/src/pg-replication-row.ts

@@ -0,0 +1,82 @@
+// Single responsibility: the two row images of one replicated change — a physical tuple pair
+// becomes the `before`/`after` the matcher's predicates are written against, plus the properties
+// `after` could not carry. Split out of `pg-replication.ts`, which decides ordering and nothing else.
+
+import { ReplicationProtocolError } from './errors';
+import { isRow, type Row } from './json';
+import { entityRow, omittedProperties } from './pg-entity-row';
+import type { PhysicalRow } from './pg-values';
+import type { PgRelation } from './pgoutput';
+
+export interface ReplicatedImages {
+  readonly before: Row | null;
+  readonly after: Row | null;
+  /** Properties missing from `after` because Postgres logged no value for them. Usually empty. */
+  readonly omitted: readonly string[];
+}
+
+/**
+ * An UPDATE that leaves an out-of-line (TOAST) value untouched logs no bytes for it, so the new
+ * tuple arrives without that column. Published as it stood, the change read as the whole row: the
+ * window adopted it, and every later snapshot served the row with the column gone.
+ *
+ * Under REPLICA IDENTITY FULL the old tuple carries the value and the column did not change, so it
+ * is copied across and nothing is missing. Under any other identity the old tuple is the key alone
+ * — its other columns are NULL placeholders, not values — so the column is NAMED instead, and the
+ * consumer re-reads the row rather than adopting a partial one.
+ */
+export function replicatedImages(
+  relation: PgRelation,
+  oldTuple: PhysicalRow | null,
+  newTuple: PhysicalRow | null,
+  unchanged: readonly string[],
+): ReplicatedImages {
+  const before = toRow(relation, oldTuple, 'before');
+  if (newTuple === null || unchanged.length === 0) {
+    return { before, after: toRow(relation, newTuple, 'after'), omitted: [] };
+  }
+  // Null-prototype, as the decoder built it: a column name is off the wire.
+  const filled: PhysicalRow = Object.assign(Object.create(null) as PhysicalRow, newTuple);
+  let missing = 0;
+  for (const name of unchanged) {
+    if (relation.replicaIdentity === 'f' && oldTuple !== null && Object.hasOwn(oldTuple, name)) {
+      const kept = oldTuple[name];
+      if (kept !== undefined) filled[name] = kept;
+    } else {
+      missing += 1;
+    }
+  }
+  const after = toRow(relation, filled, 'after');
+  return {
+    before,
+    after,
+    omitted: missing === 0 || after === null ? [] : omittedProperties(relation, after),
+  };
+}
+
+/** A physical tuple becomes the row the matcher's predicates are written against, or nothing. */
+function toRow(
+  relation: PgRelation,
+  physical: PhysicalRow | null,
+  image: 'before' | 'after',
+): Row | null {
+  if (physical === null) return null;
+  const row = entityRow(relation, physical, image);
+  // A bigserial id decodes as a number inside `Number.isSafeInteger` range and as text outside it,
+  // so the same table would otherwise identify small rows by number and large ones by string.
+  // `Row.id`, `RowPatch.id` and every cursor are text: the identity is normalised once, here.
+  const id = row['id'];
+  if (typeof id === 'number' && Number.isSafeInteger(id)) row['id'] = String(id);
+  if (isRow(row)) return row;
+  throw new ReplicationProtocolError({
+    stage: 'stream',
+    detail: `table "${relation.name}" replicated a row with no text id column`,
+    fix: `give ${relation.name} an id column, or drop it from the publication and the entity list`,
+  });
+}
+
+/** The tenant, hoisted out of the row so fanout filters without parsing it. */
+export const tenantOf = (row: Row | null): string | null => {
+  const orgId = row?.['orgId'];
+  return typeof orgId === 'string' ? orgId : null;
+};

package/src/pg-replication.ts

@@ -6,12 +6,12 @@
 import { type Clock, finiteOption, logger, renderThrowable, systemClock } from '@ultimat3/core';
 import type { ChangeEvent, ChangeOp, PgLogicalReplicationOptions } from './changefeed';
 import { ReplicationProtocolError } from './errors';
-import { isRow, type Row } from './json';
 import { ByteReader, ByteWriter, epochMsToPgTimestamp, printLsn } from './pg-bytes';
 import { PgConnection } from './pg-connection';
-import { entityRow } from './pg-entity-row';
 import { assertIdentifier } from './pg-identifier';
+import { paramsChannelTables } from './pg-identity-tables';
 import { preflight } from './pg-preflight';
+import { replicatedImages, tenantOf } from './pg-replication-row';
 import { bunPgStream, parsePgUrl } from './pg-socket';
 import type { PhysicalRow } from './pg-values';
 import { keyedWrite, PgOutputDecoder, type PgOutputMessage, type PgRelation } from './pgoutput';
@@ -52,10 +52,7 @@ export interface ReplicationStreamStats {
    * reporting it. Reset by the first confirm that lands.
    */
   readonly confirmFailures: number;
-  /**
-   * Why the pump stopped, or `null` while it is live. The read loop cannot throw into a caller —
-   * nothing awaits it — so this is the one place `/readyz` and a test can see that it died at all.
-   */
+  /** Why the pump stopped, or `null` while live. Recorded here and ANNOUNCED through `onEnd`. */
   readonly failure: string | null;
 }
 
@@ -88,6 +85,8 @@ export const commitPositionOf = (lsn: string): bigint => BigInt(`0x${lsn.slice(0
 export interface ReplicationStreamHandlers {
   readonly from?: string | undefined;
   onChange(event: ChangeEvent): void | Promise<void>;
+  /** Called once when the pump dies on its own; never for a `stop()`. */
+  readonly onEnd?: ((reason: string) => void) | undefined;
 }
 
 /**
@@ -115,6 +114,7 @@ export class PgReplicationStream {
   #partialBefore = 0;
   #confirmFailures = 0;
   #failure: string | null = null;
+  #onEnd: ((reason: string) => void) | undefined;
 
   constructor(options: PgLogicalReplicationOptions) {
     this.#options = options;
@@ -166,10 +166,12 @@ export class PgReplicationStream {
       replication: 'database',
       applicationName: `ultimate-replicator:${slot}`,
       rng: this.#options.rng,
+      ssl: target.ssl,
     });
     this.#connection = connection;
     try {
-      await preflight(connection, slot, publication, this.#entities);
+      const full = this.#options.fullIdentityTables ?? paramsChannelTables();
+      await preflight(connection, slot, publication, this.#entities, new Set(full));
       const from = handlers.from;
       this.#confirmed = from === undefined ? 0n : commitPositionOf(from);
       await connection.startCopyBoth(
@@ -183,10 +185,10 @@ export class PgReplicationStream {
       throw failure;
     }
     this.#running = true;
-    // A restart that kept the last death in `stats()` reports a live stream as failed, and the
-    // supervisor that reads it never sees the replicator come back.
+    // A restart that kept the last death in `stats()` would report a live stream as failed.
     this.#failure = null;
     this.#confirmFailures = 0;
+    this.#onEnd = handlers.onEnd;
     this.#timer = setInterval(
       () => {
         void this.#confirmOnTimer();
@@ -241,6 +243,20 @@ export class PgReplicationStream {
     if (failures.length > 0) throw failures[0];
   }
 
+  /**
+   * `stop()` without the goodbye: no confirm, no `CopyDone`, no `Terminate`, nothing awaited — on a
+   * black-holed walsender each of those is a write nothing settles. The unconfirmed tail is
+   * re-sent to the next stream and dropped by its `from`.
+   */
+  abandon(): void {
+    this.#running = false;
+    this.#onEnd = undefined;
+    this.#clearTimer();
+    const connection = this.#connection;
+    this.#connection = null;
+    connection?.destroy();
+  }
+
   /**
    * The pump's only way out, however it ended — a decode error, or a walsender that said goodbye.
    * The four things it owns go together or not at all, because each one left behind is a dead
@@ -256,8 +272,7 @@ export class PgReplicationStream {
     this.#clearTimer();
     const connection = this.#connection;
     this.#connection = null;
-    // The supervisor reads /readyz, so the loop records, reports and ends rather than throwing
-    // into a promise nothing awaits.
+    // The loop records, reports and ends rather than throwing into a promise nothing awaits.
     logger.error('replication stream ended', { slot: this.#options.slot, error: reason });
     try {
       await connection?.close();
@@ -265,6 +280,14 @@ export class PgReplicationStream {
       // The socket is already unusable and `failure` above is the report that matters — a
       // goodbye that throws must not become the rejection `#drain` promised never to produce.
     }
+    // Last, so whoever restarts finds the socket already let go. Called, never awaited.
+    const onEnd = this.#onEnd;
+    this.#onEnd = undefined;
+    try {
+      onEnd?.(reason);
+    } catch (failure) {
+      logger.error('replication onEnd listener threw', { error: renderThrowable(failure) });
+    }
   }
 
   #clearTimer(): void {
@@ -330,19 +353,21 @@ export class PgReplicationStream {
         if (message.endLsn > this.#confirmed) this.#confirmed = message.endLsn;
         return;
       case 'insert':
-        await this.#deliver('insert', message.relation, null, message.after, handlers);
+        await this.#deliver('insert', message.relation, null, message.after, [], handlers);
         return;
-      case 'update':
-        await this.#deliver('update', message.relation, message.before, message.after, handlers);
+      case 'update': {
+        const { relation, before, after, unchanged } = message;
+        await this.#deliver('update', relation, before, after, unchanged, handlers);
         return;
+      }
       case 'delete':
-        await this.#deliver('delete', message.relation, message.before, null, handlers);
+        await this.#deliver('delete', message.relation, message.before, null, [], handlers);
         return;
       case 'truncate':
         // One change per truncated relation, rowless. It was decoded and DROPPED here, and with the
         // recommended `FOR ALL TABLES` publication every window and every client kept the rows.
         for (const relation of message.relations) {
-          await this.#deliver('truncate', relation, null, null, handlers);
+          await this.#deliver('truncate', relation, null, null, [], handlers);
         }
         return;
       default:
@@ -356,6 +381,7 @@ export class PgReplicationStream {
     relation: PgRelation,
     oldTuple: PhysicalRow | null,
     newTuple: PhysicalRow | null,
+    unchanged: readonly string[],
     handlers: ReplicationStreamHandlers,
   ): Promise<void> {
     const transaction = this.#transaction;
@@ -386,8 +412,7 @@ export class PgReplicationStream {
     if ((op === 'update' || op === 'delete') && relation.replicaIdentity !== 'f') {
       this.#partialBefore += 1;
     }
-    const before = toRow(relation, oldTuple, 'before');
-    const after = toRow(relation, newTuple, 'after');
+    const { before, after, omitted } = replicatedImages(relation, oldTuple, newTuple, unchanged);
     const event: ChangeEvent = {
       entity: relation.name,
       op,
@@ -398,6 +423,7 @@ export class PgReplicationStream {
       orgId: tenantOf(after ?? before),
       at: transaction.commitAt,
       ...(transaction.write === undefined ? {} : { write: transaction.write }),
+      ...(omitted.length === 0 ? {} : { omitted }),
     };
     await handlers.onChange(event);
     this.#lastLsn = lsn;
@@ -470,30 +496,3 @@ export class PgReplicationStream {
     await attempt;
   }
 }
-
-/** A physical tuple becomes the row the matcher's predicates are written against, or nothing. */
-function toRow(
-  relation: PgRelation,
-  physical: PhysicalRow | null,
-  image: 'before' | 'after',
-): Row | null {
-  if (physical === null) return null;
-  const row = entityRow(relation, physical, image);
-  // A bigserial id decodes as a number inside `Number.isSafeInteger` range and as text outside it,
-  // so the same table would otherwise identify small rows by number and large ones by string.
-  // `Row.id`, `RowPatch.id` and every cursor are text: the identity is normalised once, here.
-  const id = row['id'];
-  if (typeof id === 'number' && Number.isSafeInteger(id)) row['id'] = String(id);
-  if (isRow(row)) return row;
-  throw new ReplicationProtocolError({
-    stage: 'stream',
-    detail: `table "${relation.name}" replicated a row with no text id column`,
-    fix: `give ${relation.name} an id column, or drop it from the publication and the entity list`,
-  });
-}
-
-/** The tenant, hoisted out of the row so fanout filters without parsing it. */
-const tenantOf = (row: Row | null): string | null => {
-  const orgId = row?.['orgId'];
-  return typeof orgId === 'string' ? orgId : null;
-};

package/src/pg-socket.ts

@@ -189,8 +189,8 @@ export async function pgStreamOver(runtime: BunConnect, target: PgTarget): Promi
   const connectFailure = (error: Error): ReplicationFailedError =>
     new ReplicationFailedError({
       stage: 'connect',
-      detail: error.message,
-      fix: `open the route to ${target.host}:${target.port}, then: x doctor db`,
+      detail: `${error.message} — no route to ${target.host}:${target.port} from this process`,
+      fix: 'x doctor --json',
     });
 
   const handlers: SocketHandlers = {
@@ -229,8 +229,10 @@ export async function pgStreamOver(runtime: BunConnect, target: PgTarget): Promi
       if (written < 0) {
         throw new ReplicationFailedError({
           stage: 'write',
-          detail: `the socket refused a ${rest.length}-byte write`,
-          fix: 'the replicator reconnects on its own; confirm the host is up with: x doctor db',
+          detail:
+            `the socket refused a ${rest.length}-byte write — the replicator reconnects on its ` +
+            'own once the host is back',
+          fix: 'x doctor --json',
         });
       }
       if (written > 0) rest = rest.subarray(written);