@ultimat3/realtime 23.0.0 → 25.0.0

package/src/pg-advisory-lock.ts

@@ -3,17 +3,17 @@
 // 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. */
 const KEY_PATTERN = /^[A-Za-z0-9:_.-]+$/;
 
-export interface PgAdvisoryLockOptions {
+export interface PostgresAdvisoryLockOptions {
   /** Connection string for the database whose replicator this is. */
   readonly url: string;
   /** Lock identity, e.g. `x:replicator:<slot>`. Hashed by Postgres, not by us. */
@@ -30,9 +30,9 @@ export interface PgAdvisoryLockOptions {
  * already holds the key would need a matching second `pg_advisory_unlock`, and `release()` only
  * ever issues one, so taking a second grant here would be a leak, not a no-op.
  */
-export class PgAdvisoryLock implements AdvisoryLock {
+export class PostgresAdvisoryLock implements AdvisoryLock {
   readonly key: string;
-  readonly #options: PgAdvisoryLockOptions;
+  readonly #options: PostgresAdvisoryLockOptions;
   #connection: PgConnection | null = null;
   /**
    * The acquisition in flight, if any. `#connection` cannot answer "am I already taking this" —
@@ -45,8 +45,9 @@ 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) {
+  constructor(options: PostgresAdvisoryLockOptions) {
     if (!KEY_PATTERN.test(options.key)) {
       throw new ReplicationFailedError({
         stage: 'preflight',
@@ -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
@@ -132,3 +176,8 @@ export class PgAdvisoryLock implements AdvisoryLock {
     }
   }
 }
+
+/** The one way to build the session lock — the twin of `memoryAdvisoryLock()`; the class is a type in the barrel only (`X_FACTORY_NAME_SPELLING`). */
+export function postgresAdvisoryLock(options: PostgresAdvisoryLockOptions): PostgresAdvisoryLock {
+  return new PostgresAdvisoryLock(options);
+}

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;
@@ -94,7 +118,13 @@ export class PgConnection {
       // trips exactly on servers whose default is not already 3. A server that refuses one
       // answers `ErrorResponse` during startup, so the replicator fails to boot with the server's
       // own words — never a warning that a feed then goes on mis-sorting behind.
-      options: '-c datestyle=ISO -c intervalstyle=postgres -c extra_float_digits=3',
+      //
+      // `TimeZone=UTC` is the one pin libpqwalreceiver does not send, and it closes the same hole
+      // from the other side: a `timestamptz` is written in the SESSION's zone, so a server, database
+      // or role default like `America/New_York` writes a pre-1883 instant at its LMT offset,
+      // `-04:56:02`. The decoder reads that too, but UTC text is the one form with no ambient zone
+      // in it — and a client option outranks every server-side default, `ALTER ROLE … SET` included.
+      options: '-c datestyle=ISO -c intervalstyle=postgres -c extra_float_digits=3 -c TimeZone=UTC',
     };
     if (options.replication !== undefined) parameters['replication'] = options.replication;
     // A handshake fails on ordinary conditions — no password, an ErrorResponse, an EOF — and on
@@ -123,26 +153,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 +291,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 +320,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 +378,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 +417,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();
+}

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;
+};