@ultimat3/realtime 1.0.0

package/src/pg-replication-fixture.ts

@@ -0,0 +1,261 @@
+// Single responsibility: the one scripted walsender this package's replication tests run against —
+// pgoutput message builders, a fake `PgStream` that answers the exact preflight sequence, and the
+// `start()` that boots a feed over it. Kept out of the test file so neither outgrows its ceiling.
+// Not part of the public API — `index.ts` deliberately does not re-export it.
+
+import { frozenClock } from '@ultimat3/core';
+import type { ChangeEvent } from './changefeed';
+import { PgLogicalReplicationFeed } from './changefeed';
+import { ByteReader, ByteWriter, pgTimestampToEpochMs } from './pg-bytes';
+import type { PgStream } from './pg-wire';
+import { frame } from './pg-wire';
+
+// ---- pgoutput fixtures ------------------------------------------------------------------------
+
+export const POSTS_OID = 16_384;
+export const OTHER_OID = 16_385;
+export const TEXT = 25;
+export const INT8 = 20;
+
+export interface FixtureColumn {
+  readonly name: string;
+  readonly key?: boolean;
+  /** Type oid, `TEXT` unless a case is specifically about how another type decodes. */
+  readonly type?: number;
+}
+
+export const relation = (
+  oid: number,
+  name: string,
+  columns: readonly FixtureColumn[],
+): Uint8Array => {
+  const writer = new ByteWriter()
+    .uint8(0x52)
+    .int32(oid)
+    .cstring('public')
+    .cstring(name)
+    .uint8(0x66)
+    .int16(columns.length);
+  for (const column of columns) {
+    writer
+      .uint8(column.key === true ? 1 : 0)
+      .cstring(column.name)
+      .int32(column.type ?? TEXT)
+      .int32(-1);
+  }
+  return writer.finish();
+};
+
+export const tuple = (writer: ByteWriter, values: readonly (string | null)[]): ByteWriter => {
+  writer.int16(values.length);
+  for (const value of values) {
+    if (value === null) writer.uint8(0x6e);
+    else writer.uint8(0x74).int32(value.length).utf8(value);
+  }
+  return writer;
+};
+
+export const begin = (commitLsn: bigint, at: bigint, xid: number): Uint8Array =>
+  new ByteWriter().uint8(0x42).int64(commitLsn).int64(at).int32(xid).finish();
+
+export const commit = (commitLsn: bigint, endLsn: bigint, at: bigint): Uint8Array =>
+  new ByteWriter().uint8(0x43).uint8(0).int64(commitLsn).int64(endLsn).int64(at).finish();
+
+export const insert = (oid: number, values: readonly (string | null)[]): Uint8Array =>
+  tuple(new ByteWriter().uint8(0x49).int32(oid).uint8(0x4e), values).finish();
+
+export const update = (
+  oid: number,
+  before: readonly (string | null)[] | null,
+  after: readonly (string | null)[],
+): Uint8Array => {
+  const writer = new ByteWriter().uint8(0x55).int32(oid);
+  if (before !== null) tuple(writer.uint8(0x4f), before);
+  return tuple(writer.uint8(0x4e), after).finish();
+};
+
+export const remove = (oid: number, before: readonly (string | null)[]): Uint8Array =>
+  tuple(new ByteWriter().uint8(0x44).int32(oid).uint8(0x4f), before).finish();
+
+/** `w` XLogData, wrapped as the `d` CopyData message the walsender sends it in. */
+export const xlog = (payload: Uint8Array, walEnd = 0n): Uint8Array =>
+  frame(
+    'd',
+    new ByteWriter().uint8(0x77).int64(walEnd).int64(walEnd).int64(0n).raw(payload).finish(),
+  );
+
+export const keepalive = (walEnd: bigint, replyRequested: number): Uint8Array =>
+  frame('d', new ByteWriter().uint8(0x6b).int64(walEnd).int64(0n).uint8(replyRequested).finish());
+
+// ---- a scripted walsender ---------------------------------------------------------------------
+
+export const dataRow = (values: readonly (string | null)[]): Uint8Array => {
+  const writer = new ByteWriter().int16(values.length);
+  for (const value of values) {
+    if (value === null) writer.int32(-1);
+    else writer.int32(value.length).utf8(value);
+  }
+  return frame('D', writer.finish());
+};
+
+export const ready = (): Uint8Array => frame('Z', new Uint8Array([0x49]));
+export const complete = (): Uint8Array => frame('C', new ByteWriter().cstring('SELECT 1').finish());
+
+export const joined = (...parts: readonly Uint8Array[]): Uint8Array => {
+  const total = parts.reduce((sum, part) => sum + part.length, 0);
+  const out = new Uint8Array(total);
+  let at = 0;
+  for (const part of parts) {
+    out.set(part, at);
+    at += part.length;
+  }
+  return out;
+};
+
+export interface ServerScript {
+  readonly walLevel?: string;
+  readonly publicationExists?: boolean;
+  /** `null` = no slot yet, so the feed has to create one. */
+  readonly slotPlugin?: string | null;
+}
+
+/**
+ * Answers the exact command sequence the feed issues, and records what it sent back — enough to
+ * drive the whole preflight and then inject WAL by hand.
+ */
+export class FakeWalsender implements PgStream {
+  readonly queries: string[] = [];
+  readonly standby: { position: bigint; at: number }[] = [];
+  closed = false;
+  // `undefined` is EOF: `PgStream.read()` already returns `Uint8Array | undefined`, so the queue
+  // holds it honestly rather than letting `close()` cast one type into the other.
+  readonly #chunks: (Uint8Array | undefined)[] = [];
+  readonly #script: ServerScript;
+  #waiting: ((chunk: Uint8Array | undefined) => void) | null = null;
+
+  constructor(script: ServerScript = {}) {
+    this.#script = script;
+  }
+
+  push(chunk: Uint8Array | undefined): void {
+    const waiter = this.#waiting;
+    this.#waiting = null;
+    if (waiter === null) this.#chunks.push(chunk);
+    else waiter(chunk);
+  }
+
+  read(): Promise<Uint8Array | undefined> {
+    if (this.#chunks.length > 0) return Promise.resolve(this.#chunks.shift());
+    return new Promise((resolve) => {
+      this.#waiting = resolve;
+    });
+  }
+
+  write(bytes: Uint8Array): Promise<void> {
+    // The startup packet is untagged, so a leading protocol version is how it is recognised.
+    const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    if (bytes.length >= 8 && view.getInt32(4, false) === 196_608) {
+      this.push(joined(frame('R', new ByteWriter().int32(0).finish()), ready()));
+      return Promise.resolve();
+    }
+    const reader = new ByteReader(bytes, 'client');
+    const tag = reader.tag();
+    reader.int32();
+    if (tag === 'Q') this.#answer(reader.cstring());
+    if (tag === 'd') this.#recordStandby(reader.rest());
+    return Promise.resolve();
+  }
+
+  close(): void {
+    this.closed = true;
+    this.push(undefined);
+  }
+
+  #recordStandby(payload: Uint8Array): void {
+    const reader = new ByteReader(payload, 'standby');
+    if (reader.tag() !== 'r') return;
+    const position = reader.int64();
+    reader.int64();
+    reader.int64();
+    this.standby.push({ position, at: pgTimestampToEpochMs(reader.int64()) });
+  }
+
+  #answer(sql: string): void {
+    this.queries.push(sql);
+    if (sql.startsWith('START_REPLICATION')) {
+      this.push(frame('W', new ByteWriter().uint8(0).int16(0).finish()));
+      return;
+    }
+    if (sql === 'SHOW wal_level') {
+      this.push(joined(dataRow([this.#script.walLevel ?? 'logical']), complete(), ready()));
+      return;
+    }
+    if (sql.includes('pg_publication')) {
+      const rows = this.#script.publicationExists === false ? [] : [dataRow(['1'])];
+      this.push(joined(...rows, complete(), ready()));
+      return;
+    }
+    if (sql.includes('pg_replication_slots')) {
+      const plugin = this.#script.slotPlugin === undefined ? 'pgoutput' : this.#script.slotPlugin;
+      const rows = plugin === null ? [] : [dataRow([plugin])];
+      this.push(joined(...rows, complete(), ready()));
+      return;
+    }
+    this.push(joined(dataRow(['ok']), complete(), ready()));
+  }
+}
+
+export const POST_COLUMNS: readonly FixtureColumn[] = [
+  { name: 'id', key: true },
+  { name: 'title' },
+  { name: 'org_id' },
+  { name: 'price_minor' },
+  { name: 'price_currency' },
+];
+
+export interface Started {
+  readonly feed: PgLogicalReplicationFeed;
+  readonly server: FakeWalsender;
+  readonly events: ChangeEvent[];
+  /** Resolves once `count` events have been delivered. */
+  settled(count: number): Promise<void>;
+}
+
+export const start = async (
+  options: {
+    script?: ServerScript;
+    from?: string;
+    entities?: readonly string[];
+    statusIntervalMs?: number;
+  } = {},
+): Promise<Started> => {
+  const server = new FakeWalsender(options.script);
+  const events: ChangeEvent[] = [];
+  const feed = new PgLogicalReplicationFeed({
+    url: 'postgres://replicator:secret@db.test:5432/app',
+    slot: 'ultimate_slot',
+    publication: 'ultimate_pub',
+    entities: options.entities ?? ['posts'],
+    clock: frozenClock('2026-08-09T12:00:00.000Z'),
+    stream: () => Promise.resolve(server),
+    ...(options.statusIntervalMs === undefined
+      ? {}
+      : { statusIntervalMs: options.statusIntervalMs }),
+  });
+  await feed.start(
+    options.from === undefined
+      ? { onChange: (event) => void events.push(event) }
+      : { from: options.from, onChange: (event) => void events.push(event) },
+  );
+  return {
+    feed,
+    server,
+    events,
+    // Nothing here is real I/O, so draining the microtask queue is a deterministic "let the pump
+    // finish" — including the commit that follows the last row.
+    settled: async (count) => {
+      for (let tick = 0; tick < 200 && events.length < count; tick += 1) await Promise.resolve();
+      for (let tick = 0; tick < 50; tick += 1) await Promise.resolve();
+    },
+  };
+};

package/src/pg-replication.ts

@@ -0,0 +1,396 @@
+// Single responsibility: turn a Postgres logical-replication slot into ordered `ChangeEvent`s —
+// preflight the three things that are always misconfigured, START_REPLICATION, decode pgoutput,
+// and keep the slot confirmed. The connection, the framing and the pgoutput decode live next door;
+// what is decided here is *ordering*, because the lsn is the only authority the pipeline has.
+
+import { type Clock, logger, systemClock } from '@ultimat3/core';
+import type { ChangeEvent, ChangeOp, PgLogicalReplicationOptions } from './changefeed';
+import { ReplicationFailedError, ReplicationProtocolError } from './errors';
+import { isRow, type JsonObject, type Row } from './json';
+import { ByteReader, ByteWriter, epochMsToPgTimestamp, printLsn } from './pg-bytes';
+import { PgConnection } from './pg-connection';
+import { entityRow } from './pg-entity-row';
+import { bunPgStream, parsePgUrl } from './pg-socket';
+import { PgOutputDecoder, type PgOutputMessage, type PgRelation } from './pgoutput';
+
+/** Identifiers reach a simple query unparameterised, so the charset is the injection boundary. */
+const IDENTIFIER = /^[a-z_][a-z0-9_]*$/;
+
+const DEFAULT_STATUS_INTERVAL_MS = 10_000;
+
+/** `r` — the standby status update, the only frontend message a walsender listens for. */
+const STANDBY_STATUS = 0x72;
+
+export interface ReplicationStreamStats {
+  readonly delivered: number;
+  /** Rows for a table outside the entity list — the publication is wider than the app is. */
+  readonly skipped: number;
+  /** Rows replayed from before the resume position, dropped so `onChange` sees each one once. */
+  readonly replayed: 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.
+   */
+  readonly failure: string | null;
+}
+
+interface Transaction {
+  readonly commitLsn: bigint;
+  readonly commitAt: number;
+  readonly xid: number;
+  /** Position of the next row inside this transaction. Reproducible, which is what makes it usable. */
+  sequence: number;
+}
+
+/**
+ * `<commit lsn><position in transaction>`, both zero-padded hex, so string order is stream order.
+ *
+ * The commit lsn alone is not enough: every row of one transaction shares it, and the replicator
+ * drops anything that does not strictly increase — a five-row insert would deliver one row. The
+ * per-record WAL position is not enough either: logical decoding emits *transactions* in commit
+ * order, so a later-committing transaction can carry lower record positions than an earlier one.
+ * The pair is monotonic in the order changes are delivered and identical on replay, which is what
+ * makes an at-least-once redelivery deduplicate instead of duplicating.
+ */
+export const changeLsn = (commitLsn: bigint, sequence: number): string =>
+  commitLsn.toString(16).padStart(16, '0') + sequence.toString(16).padStart(8, '0');
+
+/** The commit position inside a change lsn — where a resume asks the server to restart. */
+export const commitPositionOf = (lsn: string): bigint => BigInt(`0x${lsn.slice(0, 16) || '0'}`);
+
+const assertIdentifier = (kind: string, value: string): string => {
+  if (IDENTIFIER.test(value)) return value;
+  throw new ReplicationFailedError({
+    stage: 'preflight',
+    detail: `${kind} "${value}" is not a lower-case postgres identifier`,
+    fix: `rename the ${kind} to match [a-z_][a-z0-9_]* — it is interpolated into a replication command`,
+  });
+};
+
+export interface ReplicationStreamHandlers {
+  readonly from?: string | undefined;
+  onChange(event: ChangeEvent): void | Promise<void>;
+}
+
+/**
+ * One slot, one connection, one process. Started by `PgLogicalReplicationFeed`, which is itself
+ * held by the single `replicator` role — the advisory lock upstream is what keeps that "one" true.
+ */
+export class PgReplicationStream {
+  readonly #options: PgLogicalReplicationOptions;
+  readonly #clock: Clock;
+  readonly #entities: ReadonlySet<string>;
+  readonly #slot: string;
+  readonly #publication: string;
+  readonly #decoder = new PgOutputDecoder();
+  #connection: PgConnection | null = null;
+  #timer: ReturnType<typeof setInterval> | null = null;
+  #writing: Promise<void> = Promise.resolve();
+  #transaction: Transaction | null = null;
+  #confirmed = 0n;
+  #lastLsn: string | null = null;
+  #running = false;
+  #pump: Promise<void> | null = null;
+  #delivered = 0;
+  #skipped = 0;
+  #replayed = 0;
+  #failure: string | null = null;
+
+  constructor(options: PgLogicalReplicationOptions) {
+    this.#options = options;
+    this.#clock = options.clock ?? systemClock;
+    this.#entities = new Set(options.entities.map((name) => assertIdentifier('entity', name)));
+    // All three names are checked here rather than in `start()`: a mistyped REPLICATION_SLOT is a
+    // boot-time fact, and refusing it at the first WAL read means a replicator that reported
+    // itself started and then never delivered a change.
+    this.#slot = assertIdentifier('slot', options.slot);
+    this.#publication = assertIdentifier('publication', options.publication);
+  }
+
+  lastLsn(): string | null {
+    return this.#lastLsn;
+  }
+
+  stats(): ReplicationStreamStats {
+    return {
+      delivered: this.#delivered,
+      skipped: this.#skipped,
+      replayed: this.#replayed,
+      failure: this.#failure,
+    };
+  }
+
+  /** Resolves once the stream is live. Delivery continues on the pump until `stop()`. */
+  async start(handlers: ReplicationStreamHandlers): Promise<void> {
+    if (this.#running) return;
+    const slot = this.#slot;
+    const publication = this.#publication;
+    const target = parsePgUrl(this.#options.url);
+    const stream = await (this.#options.stream ?? bunPgStream)(target);
+    const connection = await PgConnection.open({
+      stream,
+      user: target.user,
+      password: target.password,
+      database: target.database,
+      replication: 'database',
+      applicationName: `ultimate-replicator:${slot}`,
+      rng: this.#options.rng,
+    });
+    this.#connection = connection;
+    try {
+      await preflight(connection, slot, publication);
+      const from = handlers.from;
+      this.#confirmed = from === undefined ? 0n : commitPositionOf(from);
+      await connection.startCopyBoth(
+        `START_REPLICATION SLOT ${slot} LOGICAL ${printLsn(this.#confirmed)} ` +
+          `(proto_version '1', publication_names '${publication}')`,
+      );
+    } catch (failure) {
+      await this.stop();
+      throw failure;
+    }
+    this.#running = true;
+    this.#timer = setInterval(() => {
+      void this.#confirm();
+    }, this.#options.statusIntervalMs ?? DEFAULT_STATUS_INTERVAL_MS);
+    // A pending timer must not be what keeps `x dev` alive after the app is done with it.
+    this.#timer.unref?.();
+    this.#pump = this.#drain(connection, handlers);
+  }
+
+  async stop(): Promise<void> {
+    this.#running = false;
+    if (this.#timer !== null) {
+      clearInterval(this.#timer);
+      this.#timer = null;
+    }
+    const connection = this.#connection;
+    this.#connection = null;
+    if (connection === null) return;
+    // Confirming before the goodbye is what stops a restart from replaying the whole window.
+    if (connection.inCopyBoth) {
+      await this.#confirm(connection);
+      await connection.endCopy();
+    }
+    await connection.close();
+    const pump = this.#pump;
+    this.#pump = null;
+    if (pump !== null) await pump;
+  }
+
+  /** The read loop. It owns no timers and no state beyond the current transaction. */
+  async #drain(connection: PgConnection, handlers: ReplicationStreamHandlers): Promise<void> {
+    try {
+      for (;;) {
+        const payload = await connection.nextCopyData();
+        if (payload === undefined) return;
+        const reader = new ByteReader(payload, 'copy-data');
+        const tag = reader.tag();
+        if (tag === 'w') {
+          reader.int64();
+          reader.int64();
+          reader.int64();
+          await this.#apply(this.#decoder.decode(reader.rest()), handlers);
+        } else if (tag === 'k') {
+          const walEnd = reader.int64();
+          reader.int64();
+          const replyRequested = reader.uint8();
+          // Only safe between transactions: inside one, the undelivered tail is still pending.
+          if (this.#transaction === null && walEnd > this.#confirmed) this.#confirmed = walEnd;
+          if (replyRequested === 1) await this.#confirm(connection);
+        } else {
+          throw new ReplicationProtocolError({
+            stage: 'stream',
+            detail: `the walsender sent CopyData "${tag}", which is neither XLogData nor a keepalive`,
+            fix: 'upgrade this package — the server speaks a replication message it does not know',
+          });
+        }
+      }
+    } catch (failure) {
+      if (!this.#running) return;
+      this.#running = false;
+      // The supervisor reads /readyz, so the loop records, reports and ends rather than throwing
+      // into a timer callback nothing awaits — and the confirm timer stops with the loop it
+      // confirms for, or it keeps telling the walsender a dead stream is still keeping up.
+      this.#failure = failure instanceof Error ? failure.message : String(failure);
+      if (this.#timer !== null) {
+        clearInterval(this.#timer);
+        this.#timer = null;
+      }
+      logger.error('replication stream ended', {
+        slot: this.#options.slot,
+        error: this.#failure,
+      });
+    }
+  }
+
+  async #apply(message: PgOutputMessage, handlers: ReplicationStreamHandlers): Promise<void> {
+    switch (message.kind) {
+      case 'begin':
+        this.#transaction = {
+          commitLsn: message.commitLsn,
+          commitAt: message.commitAt,
+          xid: message.xid,
+          sequence: 0,
+        };
+        return;
+      case 'commit':
+        this.#transaction = null;
+        if (message.endLsn > this.#confirmed) this.#confirmed = message.endLsn;
+        return;
+      case 'insert':
+        await this.#deliver('insert', message.relation, null, message.after, handlers);
+        return;
+      case 'update':
+        await this.#deliver('update', message.relation, message.before, message.after, handlers);
+        return;
+      case 'delete':
+        await this.#deliver('delete', message.relation, message.before, null, handlers);
+        return;
+      default:
+        // Relation, truncate, origin, type, logical message: nothing the matcher can act on.
+        return;
+    }
+  }
+
+  async #deliver(
+    op: ChangeOp,
+    relation: PgRelation,
+    oldTuple: JsonObject | null,
+    newTuple: JsonObject | null,
+    handlers: ReplicationStreamHandlers,
+  ): Promise<void> {
+    const transaction = this.#transaction;
+    if (transaction === null) {
+      throw new ReplicationProtocolError({
+        stage: 'stream',
+        detail: `a ${op} arrived outside a transaction`,
+        fix: 'upgrade this package — the pgoutput stream is framed differently than expected',
+      });
+    }
+    // Counted for every row, selected or not, so the lsn depends on the WAL alone: narrowing the
+    // entity list must not renumber a stream a resume cursor already points into.
+    transaction.sequence += 1;
+    if (!this.#entities.has(relation.name)) {
+      this.#skipped += 1;
+      return;
+    }
+    const lsn = changeLsn(transaction.commitLsn, transaction.sequence);
+    // The server restarts at a transaction boundary, so the first transaction after a resume
+    // arrives whole; the rows already delivered are dropped here rather than sent twice.
+    if (handlers.from !== undefined && lsn <= handlers.from) {
+      this.#replayed += 1;
+      return;
+    }
+    const before = toRow(relation, oldTuple);
+    const after = toRow(relation, newTuple);
+    const event: ChangeEvent = {
+      entity: relation.name,
+      op,
+      before,
+      after,
+      lsn,
+      txid: transaction.xid.toString(10),
+      orgId: tenantOf(after ?? before),
+      at: transaction.commitAt,
+    };
+    await handlers.onChange(event);
+    this.#lastLsn = lsn;
+    this.#delivered += 1;
+  }
+
+  /**
+   * Tell the walsender how far we got. Serialized behind one chain because the timer and the read
+   * loop both reach it, and two interleaved writes would frame one another's bytes.
+   */
+  async #confirm(connection: PgConnection | null = this.#connection): Promise<void> {
+    if (connection === null || !connection.inCopyBoth) return;
+    const position = this.#confirmed;
+    const at = epochMsToPgTimestamp(this.#clock.now().getTime());
+    const payload = new ByteWriter(34)
+      .uint8(STANDBY_STATUS)
+      .int64(position)
+      .int64(position)
+      .int64(position)
+      .int64(at)
+      .uint8(0)
+      .finish();
+    this.#writing = this.#writing.then(
+      () => connection.sendCopyData(payload),
+      () => undefined,
+    );
+    await this.#writing;
+  }
+}
+
+/**
+ * The three misconfigurations that produce an unreadable server message if left to the server.
+ * `slot` and `publication` are interpolated into simple queries, so the `IDENTIFIER` charset is the
+ * injection boundary; re-asserted here rather than trusted, so the guarantee travels with the
+ * function instead of living only in `start()`.
+ */
+async function preflight(
+  connection: PgConnection,
+  slot: string,
+  publication: string,
+): Promise<void> {
+  assertIdentifier('slot', slot);
+  assertIdentifier('publication', publication);
+  const [walLevel] = await connection.query('SHOW wal_level');
+  if (walLevel?.[0] !== 'logical') {
+    throw new ReplicationFailedError({
+      stage: 'preflight',
+      detail: `wal_level is "${walLevel?.[0] ?? 'unknown'}", so the server writes no logical WAL`,
+      fix: "ALTER SYSTEM SET wal_level = 'logical'; -- then restart postgres",
+    });
+  }
+  const publications = await connection.query(
+    `SELECT 1 FROM pg_publication WHERE pubname = '${publication}'`,
+  );
+  if (publications.length === 0) {
+    throw new ReplicationFailedError({
+      stage: 'preflight',
+      detail: `no publication named "${publication}" exists`,
+      fix: `CREATE PUBLICATION ${publication} FOR ALL TABLES;`,
+    });
+  }
+  const [existing] = await connection.query(
+    `SELECT plugin FROM pg_replication_slots WHERE slot_name = '${slot}'`,
+  );
+  if (existing === undefined) {
+    // Plain SQL rather than CREATE_REPLICATION_SLOT: the replication command exports a snapshot
+    // that pins xmin for the session, and its option syntax changed in postgres 15.
+    await connection.query(`SELECT pg_create_logical_replication_slot('${slot}', 'pgoutput')`);
+    return;
+  }
+  if (existing[0] !== 'pgoutput') {
+    throw new ReplicationFailedError({
+      stage: 'preflight',
+      detail: `slot "${slot}" decodes with "${existing[0] ?? 'unknown'}", not pgoutput`,
+      fix: `SELECT pg_drop_replication_slot('${slot}'); -- then start the replicator again`,
+    });
+  }
+}
+
+/** A physical tuple becomes the row the matcher's predicates are written against, or nothing. */
+function toRow(relation: PgRelation, physical: JsonObject | null): Row | null {
+  if (physical === null) return null;
+  const row = entityRow(physical);
+  // 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;
+};