@ultimat3/realtime 21.0.0 → 22.0.0

package/src/pg-entity-row.ts

@@ -1,198 +1,51 @@
-// Physical Postgres row -> entity-row shaping: snake_case columns become camelCase properties,
-// and the `<p>_minor` / `<p>_currency` / `<p>_scale` columns fold into one `<p>: Money`-shaped
-// property. The inverse of the camelCasing here is `@ultimat3/entity`'s `column.ts#snake`, and
-// the fold is its `pg-row.ts#moneyOf` — neither is imported (this package declares no dependency
-// on tier 2), so both are pinned by a test instead: `pg-entity-row-parity.test.ts` reads one
-// physical row through both surfaces and asserts one object.
-
-import { describeValue } from '@ultimat3/core';
+// Physical Postgres row -> the entity row the app declared, by `@ultimat3/entity`'s own decoder.
+// The relation names the table, `entityForTable` names the entity, and `decodeRow` shapes the row
+// by each column's declared KIND — money included — exactly as a repository read does.
+//
+// It GUESSED, until 22.0.0: snake_case camelCased by string rules and any `<p>_minor`/`<p>_currency`
+// 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.
+
+import { decodeRow, entityForTable } from '@ultimat3/entity';
 import { ReplicationProtocolError } from './errors';
-import type { PhysicalRow, PhysicalValue } from './pg-values';
-
-/** `org_id` -> `orgId`, `published_at` -> `publishedAt`. The inverse of `@ultimat3/entity`'s `snake()`. */
-export function camel(column: string): string {
-  const [head = '', ...tail] = column.split('_');
-  return head + tail.map(capitalize).join('');
-}
-
-/** A leading, trailing, or doubled underscore produces an empty part; it contributes nothing. */
-function capitalize(part: string): string {
-  return part.charAt(0).toUpperCase() + part.slice(1);
-}
-
-interface FoldedMoney {
-  readonly property: string;
-  /** The physical columns the fold consumed, in declaration order — named together on a collision. */
-  readonly columns: readonly string[];
-  readonly value: PhysicalRow;
-}
-
-/**
- * `price_minor` / `price_currency` / `price_scale` -> `price`; any other column name has no money
- * prefix. The scale column is matched here for the same reason the other two are: unmatched, it
- * survived the fold as a physical `priceScale` property beside `price`, so one row read live and
- * the same row read through a repository reported two different shapes — and the sub-cent amount
- * the scale names was delivered to every subscriber unscaled.
- */
-function moneyPrefix(column: string): string | null {
-  if (column.endsWith('_minor')) return column.slice(0, -'_minor'.length);
-  if (column.endsWith('_currency')) return column.slice(0, -'_currency'.length);
-  if (column.endsWith('_scale')) return column.slice(0, -'_scale'.length);
-  return null;
-}
-
-/**
- * `Money` is `{ minor: number; currency: string }` everywhere in the framework, so `minor` is
- * normalised here rather than passed through: `pgoutput` decodes an int8 as text once it leaves
- * `Number.isSafeInteger` range and a numeric as text always, which would otherwise make one column
- * a number on one row and a string on the next. A value no JS number holds exactly is not money
- * this pipeline can carry, and saying so is better than shipping a `minor` the contract forbids.
- */
-function moneyMinor(column: string, value: number | string): number {
-  const minor =
-    typeof value === 'number' ? value : /^-?\d+$/.test(value) ? Number(value) : Number.NaN;
-  if (Number.isSafeInteger(minor)) return minor;
-  throw new ReplicationProtocolError({
-    stage: 'value',
-    detail: `column "${column}" carries ${shownNumber(value)}, which is not a whole number of minor units`,
-    fix: `store ${column} as a bigint inside ±2^53 — Money.minor is a number, never a float or a bigint`,
-  });
-}
-
-/**
- * `MoneyValue.scale` is a whole, non-negative count of decimal places, so that — and only that —
- * is what this decoder refuses: a fractional or negative scale is not a value the shape can carry
- * at all, exactly as an out-of-range `minor` is not.
- *
- * The `0…MAX_MONEY_SCALE` CEILING is `@ultimat3/schema`'s and is deliberately not restated here:
- * it is enforced at both ends of this column already — the CHECK `@ultimat3/entity`'s
- * `describeColumn` emits on `<p>_scale`, and `parseScale` on the repository read — and this
- * package declares no `@ultimat3/schema` dependency, so a copy of the bound here would be a
- * second declaration that can drift from the one that decides.
- *
- * `/^\d+$/` and not `Number(value)`: `Number('')` is 0, and 0 means whole units — the one value
- * an empty column must never decode to. The same guard `parseScale` uses.
- */
-function moneyScale(column: string, value: PhysicalValue): number {
-  const digits = typeof value === 'string' && /^\d+$/.test(value);
-  const scale = typeof value === 'number' ? value : digits ? Number(value) : Number.NaN;
-  if (Number.isSafeInteger(scale) && scale >= 0) return scale;
-  throw new ReplicationProtocolError({
-    stage: 'value',
-    detail: `column "${column}" carries ${shownNumber(value)}, which is not a whole number of decimal places`,
-    fix: `store ${column} as a non-negative integer, or null for the currency's own minor unit`,
-  });
-}
+import type { PhysicalRow } from './pg-values';
+import type { PgRelation } from './pgoutput';
 
 /**
- * **Paired with `parseMinor` in `@ultimat3/entity`'s `columns.ts`, and the pairing is the rule
- * rather than the spelling: an amount may be echoed when it is *provably numeric*, and this file
- * has to prove it at run time because entity proves it from the branch.**
- *
- * Entity reaches its echo only on a value already narrowed to a finite non-integer `number`, a
- * `bigint`, or a `/^-?\d+$/` string. Here the value came off the WAL, and a `<p>_minor` pair is
- * matched by column *name*: any `text` column called `note_minor` beside `note_currency` routes
- * arbitrary user content through this throw. `"${value}"` on that path is the leak
- * `describeValue` exists for — the message is built before any field-level redaction can see it,
- * and it reaches the log store and the operator alike.
- *
- * So the amount survives when its content is a number (a float, an out-of-range integer, or a
- * string that *is* one), and everything else is reported as shape. The scale column is matched by
- * name the same way and carries the same risk, so it renders through here too.
+ * A key-only `before` image — any replica identity but FULL — carries NULL for every column that is
+ * not part of the key. Those NULLs are not the row's values, and handed to the decoder a not-null
+ * column would read as a table that no longer matches its entity. They are dropped, so the image
+ * decodes as what it is: the key, and nothing claimed about the rest.
  */
-function shownNumber(value: PhysicalValue): string {
-  if (typeof value === 'number') return `"${value}"`;
-  if (typeof value !== 'string') return describeValue(value);
-  const numeric = value.trim() !== '' && Number.isFinite(Number(value));
-  return numeric ? `"${value}"` : describeValue(value);
-}
-
-/**
- * `name` is part of a `<p>_minor` / `<p>_currency` (/ `<p>_scale`) group, or null if it is not.
- * The first two must be present *and* typed like money — a null currency (an unset money value) is
- * not "half a pair", it simply is not a pair, so every column falls through as an ordinary value.
- *
- * The scale column is the one member that may be absent or NULL, and both mean the same thing:
- * "the currency's own minor unit". Neither produces a `scale` key, because `undefined` and `0` are
- * different values — `0` claims whole units, a 100x reinterpretation of an ordinary price — which
- * is exactly the rule `moneyOf` follows on the repository side. What it may NOT do is survive as a
- * column of its own: the fold consumes it whenever the group folds.
- */
-function foldMoney(
-  physical: Readonly<Record<string, PhysicalValue>>,
-  name: string,
-): FoldedMoney | null {
-  const prefix = moneyPrefix(name);
-  if (prefix === null) return null;
-
-  const minorKey = `${prefix}_minor`;
-  const currencyKey = `${prefix}_currency`;
-  if (!Object.hasOwn(physical, minorKey) || !Object.hasOwn(physical, currencyKey)) return null;
-
-  const minor = physical[minorKey];
-  const currency = physical[currencyKey];
-  if (!(typeof minor === 'number' || typeof minor === 'string') || typeof currency !== 'string') {
-    return null;
+function replicatedOnly(relation: PgRelation, physical: PhysicalRow): PhysicalRow {
+  if (relation.replicaIdentity === 'f') return physical;
+  const keys = new Set(relation.columns.filter((column) => column.key).map((c) => c.name));
+  const kept: PhysicalRow = {};
+  for (const [name, value] of Object.entries(physical)) {
+    if (value !== null || keys.has(name)) kept[name] = value;
   }
-
-  const scaleKey = `${prefix}_scale`;
-  const scale = Object.hasOwn(physical, scaleKey) ? physical[scaleKey] : undefined;
-  return {
-    property: camel(prefix),
-    columns: scale === undefined ? [minorKey, currencyKey] : [minorKey, currencyKey, scaleKey],
-    value: {
-      minor: moneyMinor(minorKey, minor),
-      currency,
-      ...(scale === undefined || scale === null ? {} : { scale: moneyScale(scaleKey, scale) }),
-    },
-  };
+  return kept;
 }
 
 /**
- * `camel()` is not injective — `a_b` and `a__b` both give `aB`, `x` and `x_` both give `x` — and
- * `entityRow` writes by assignment, so without this the second column would silently overwrite the
- * first and the row would be short one value with nothing to read about it.
+ * The entity row for one replicated tuple. A relation with no registered entity is refused: the
+ * stream only selects tables `replicatedRelations()` named from the entity registry, so one that
+ * arrives unregistered is a process that never loaded the app's entities.
  */
-function claim(taken: Map<string, string>, property: string, column: string): void {
-  const first = taken.get(property);
-  if (first !== undefined) {
+export function entityRow(
+  relation: PgRelation,
+  physical: PhysicalRow,
+  image: 'before' | 'after',
+): PhysicalRow {
+  const entity = entityForTable(relation.name);
+  if (entity === undefined) {
     throw new ReplicationProtocolError({
       stage: 'value',
-      detail: `columns "${first}" and "${column}" both map to the entity property "${property}"`,
-      fix: `rename one of them — two columns cannot share one property once camelCased`,
+      detail: `table "${relation.name}" has no registered entity, so its rows cannot be decoded`,
+      fix: 'load the app before starting the replicator — runRole({ root, env }) does — or drop the table from the entity list',
     });
   }
-  taken.set(property, column);
-}
-
-/**
- * A physical postgres row -> the row shape the rest of the pipeline is written against.
- * Two things are not one-to-one and both live here: the column is snake_case while the entity
- * property is camelCase, and money is one property over the columns `<p>_minor`/`<p>_currency`
- * and the nullable `<p>_scale`.
- */
-export function entityRow(physical: Readonly<Record<string, PhysicalValue>>): PhysicalRow {
-  const row: PhysicalRow = {};
-  // Column order in is key order out; a folded money property lands wherever its earliest member
-  // (whichever of the three the source happened to emit first) would otherwise have sat.
-  const consumed = new Set<string>();
-  // Which column produced each property, so a collision names both sides rather than losing one.
-  const taken = new Map<string, string>();
-
-  for (const name of Object.keys(physical)) {
-    if (consumed.has(name)) continue;
-
-    const money = foldMoney(physical, name);
-    if (money !== null) {
-      claim(taken, money.property, money.columns.join('/'));
-      row[money.property] = money.value;
-      for (const column of money.columns) consumed.add(column);
-      continue;
-    }
-
-    const property = camel(name);
-    claim(taken, property, name);
-    row[property] = physical[name] ?? null;
-  }
-  return row;
+  const source = image === 'before' ? replicatedOnly(relation, physical) : physical;
+  return decodeRow(entity, source) as PhysicalRow;
 }

package/src/pg-preflight.ts

@@ -45,17 +45,20 @@ export async function preflight(
     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",
+      // Not `ALTER SYSTEM`: managed and operator-run Postgres refuse it, and the setting lives in
+      // the provider's configuration. The setting, where it goes, and that it needs a restart.
+      fix: "set wal_level=logical in the server configuration — postgresql.conf, your managed provider's database flags, or `postgres -c wal_level=logical` on a container — then restart postgres",
     });
   }
   const publications = await connection.query(
     `SELECT 1 FROM pg_publication WHERE pubname = '${publication}'`,
   );
   if (publications.length === 0) {
+    const [role] = await connection.query('SELECT current_user');
     throw new ReplicationFailedError({
       stage: 'preflight',
       detail: `no publication named "${publication}" exists`,
-      fix: `CREATE PUBLICATION ${publication} FOR ALL TABLES;`,
+      fix: publicationFix(publication, entities, role?.[0]),
     });
   }
   await warnPartialIdentity(connection, entities);
@@ -77,6 +80,25 @@ export async function preflight(
   }
 }
 
+/**
+ * The publication an app needs is exactly its entities' tables, and `FOR TABLE` is what an app role
+ * that owns them may create — `FOR ALL TABLES`, which this said, needs a superuser a managed
+ * database never hands out. Streaming also needs the `REPLICATION` role attribute, which no fix
+ * line named. Every name here already passed `assertIdentifier`; the role is quoted, because a
+ * role name is whatever the operator chose.
+ */
+function publicationFix(
+  publication: string,
+  entities: ReadonlySet<string>,
+  role: string | null | undefined,
+): string {
+  const tables = [...entities].sort().join(', ');
+  const create = `CREATE PUBLICATION ${publication} FOR TABLE ${tables};`;
+  const who =
+    typeof role === 'string' && role !== '' ? `"${role.replaceAll('"', '""')}"` : 'CURRENT_USER';
+  return `${create} -- and, if the role cannot stream yet: ALTER ROLE ${who} WITH REPLICATION;`;
+}
+
 /**
  * The fourth preflight question, and the one that does NOT refuse. A live query decides whether a
  * row left its result set from `change.before`, and under any replica identity but FULL that tuple

package/src/pg-replication.ts

@@ -337,8 +337,15 @@ export class PgReplicationStream {
       case 'delete':
         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);
+        }
+        return;
       default:
-        // Relation, truncate, origin, type, logical message: nothing the matcher can act on.
+        // Relation, origin, type, logical message: nothing the matcher can act on.
         return;
     }
   }
@@ -375,9 +382,11 @@ export class PgReplicationStream {
     // Read off the Relation message rather than off the tuple: a DEFAULT-identity table whose
     // non-key columns happen to be NULL sends the same bytes a FULL one does, so counting missing
     // keys would undercount exactly the rows a policy is most likely to misjudge.
-    if (op !== 'insert' && relation.replicaIdentity !== 'f') this.#partialBefore += 1;
-    const before = toRow(relation, oldTuple);
-    const after = toRow(relation, newTuple);
+    if ((op === 'update' || op === 'delete') && relation.replicaIdentity !== 'f') {
+      this.#partialBefore += 1;
+    }
+    const before = toRow(relation, oldTuple, 'before');
+    const after = toRow(relation, newTuple, 'after');
     const event: ChangeEvent = {
       entity: relation.name,
       op,
@@ -462,9 +471,13 @@ export class PgReplicationStream {
 }
 
 /** A physical tuple becomes the row the matcher's predicates are written against, or nothing. */
-function toRow(relation: PgRelation, physical: PhysicalRow | null): Row | null {
+function toRow(
+  relation: PgRelation,
+  physical: PhysicalRow | null,
+  image: 'before' | 'after',
+): Row | null {
   if (physical === null) return null;
-  const row = entityRow(physical);
+  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.

package/src/pg-wire.ts

@@ -36,7 +36,17 @@ const MAX_MESSAGE_BYTES = 64 * 1024 * 1024;
  */
 export class MessageReader {
   readonly #stream: PgStream;
+  /** Bytes of messages whose length is not yet known, or complete ones not yet taken. */
   #buffer: Uint8Array = new Uint8Array(0);
+  /**
+   * One message whose length IS known and whose bytes are still arriving: allocated once at its
+   * full size and filled in place. Joining every chunk onto what was held re-copied the whole
+   * message per chunk — quadratic, measured at 5.2 s of blocked event loop for one 32 MB CopyData
+   * on the replication connection every live window depends on.
+   */
+  #pending: { readonly bytes: Uint8Array; filled: number } | null = null;
+  /** Messages completed out of `#pending`, in arrival order, ahead of anything in `#buffer`. */
+  readonly #ready: Uint8Array[] = [];
 
   constructor(stream: PgStream) {
     this.#stream = stream;
@@ -44,7 +54,8 @@ export class MessageReader {
 
   /** Bytes already read but not yet consumed — what a reconnect would have to replay. */
   get buffered(): number {
-    return this.#buffer.length;
+    const ready = this.#ready.reduce((sum, bytes) => sum + bytes.length, 0);
+    return this.#buffer.length + (this.#pending?.filled ?? 0) + ready;
   }
 
   /** The next complete message, or `undefined` at a clean EOF. */
@@ -54,10 +65,11 @@ export class MessageReader {
       if (framed !== undefined) return framed;
       const chunk = await this.#stream.read();
       if (chunk === undefined) {
-        if (this.#buffer.length === 0) return undefined;
+        const held = this.buffered;
+        if (held === 0) return undefined;
         throw new ReplicationProtocolError({
           stage: 'read',
-          detail: `the connection closed with ${this.#buffer.length} bytes of a partial message`,
+          detail: `the connection closed with ${held} bytes of a partial message`,
           fix: 'x doctor db — the backend was terminated mid-message; the server log names the reason',
         });
       }
@@ -66,18 +78,33 @@ export class MessageReader {
   }
 
   #append(chunk: Uint8Array): void {
+    let rest = chunk;
+    const pending = this.#pending;
+    if (pending !== null) {
+      const take = Math.min(pending.bytes.length - pending.filled, rest.length);
+      pending.bytes.set(rest.subarray(0, take), pending.filled);
+      pending.filled += take;
+      rest = rest.subarray(take);
+      if (pending.filled < pending.bytes.length) return;
+      this.#ready.push(pending.bytes);
+      this.#pending = null;
+    }
+    if (rest.length === 0) return;
     if (this.#buffer.length === 0) {
-      this.#buffer = chunk;
+      this.#buffer = rest;
       return;
     }
-    const joined = new Uint8Array(this.#buffer.length + chunk.length);
+    // Only ever a few bytes are held here: a message whose length is known moves to `#pending`.
+    const joined = new Uint8Array(this.#buffer.length + rest.length);
     joined.set(this.#buffer, 0);
-    joined.set(chunk, this.#buffer.length);
+    joined.set(rest, this.#buffer.length);
     this.#buffer = joined;
   }
 
   /** A message is `tag` + Int32 length that counts itself but not the tag. */
   #take(): PgMessage | undefined {
+    const done = this.#ready.shift();
+    if (done !== undefined) return messageOf(done);
     const buffer = this.#buffer;
     if (buffer.length < 5) return undefined;
     const length = new DataView(buffer.buffer, buffer.byteOffset, buffer.byteLength).getInt32(
@@ -92,16 +119,24 @@ export class MessageReader {
       });
     }
     const total = length + 1;
-    if (buffer.length < total) return undefined;
-    const message: PgMessage = {
-      tag: String.fromCharCode(buffer[0] ?? 0),
-      body: buffer.subarray(5, total),
-    };
+    if (buffer.length < total) {
+      // The length is known, so the message gets its one allocation now and fills in place.
+      const bytes = new Uint8Array(total);
+      bytes.set(buffer, 0);
+      this.#pending = { bytes, filled: buffer.length };
+      this.#buffer = new Uint8Array(0);
+      return undefined;
+    }
     this.#buffer = buffer.subarray(total);
-    return message;
+    return messageOf(buffer.subarray(0, total));
   }
 }
 
+const messageOf = (whole: Uint8Array): PgMessage => ({
+  tag: String.fromCharCode(whole[0] ?? 0),
+  body: whole.subarray(5),
+});
+
 /** `tag` + Int32 length + body — the shape of every frontend message except the startup packet. */
 export const frame = (tag: string, body: Uint8Array): Uint8Array =>
   new ByteWriter(body.length + 5)
@@ -189,10 +224,11 @@ export const FIXES: Readonly<Record<string, string>> = {
   // the half of #97 that outlived the three log-injection holes. The publication is the operator's
   // to create; the slot the replicator creates for itself on its next start.
   '42704':
-    'psql "$REPLICATION_URL" -c "CREATE PUBLICATION x_changes FOR ALL TABLES"' +
-    "   # x_changes is the default name; use REPLICATION_PUBLICATION's value where it is set. " +
+    'psql "$REPLICATION_URL" -c "CREATE PUBLICATION x_changes FOR TABLE <every entity table>"' +
+    "   # x_changes is the default name; use REPLICATION_PUBLICATION's value where it is set, and FOR TABLE because FOR ALL TABLES needs a superuser. " +
     "The slot is the replicator's own and it creates one on its next start",
-  '0A000': 'set wal_level = logical in postgresql.conf and restart the server',
+  '0A000':
+    "set wal_level=logical in the server configuration (postgresql.conf, or your managed provider's database flags) and restart the server",
 };
 
 /** What a SQLSTATE this table has no entry for is answered with. */

package/src/policy-fake.ts

@@ -0,0 +1,14 @@
+// A policy that admits every caller, for the tests that declare a channel whose authz is not
+// their subject. Structural, never built with `@ultimat3/policy`: realtime reaches that package
+// only through `@ultimat3/query`'s `guard`, and a direct import would be a second authz path.
+// An app says the same thing with `allow('public')`, which is what this stands in for.
+
+import type { QueryPolicy } from '@ultimat3/query';
+
+export const OPEN_POLICY: QueryPolicy = Object.freeze({
+  kind: 'allow',
+  label: 'public',
+  permissions: [],
+  children: [],
+  run: () => ({ allowed: true as const }),
+});

package/src/query-window.ts

@@ -125,29 +125,43 @@ export function createEntry(
 export async function fillWindow(
   entry: QueryEntry,
 ): Promise<{ rows: readonly Row[]; lsn: string }> {
-  // Read before `startRead` clears it: a second caller arriving during the read joins it and is
-  // not the one that forced it, which is what keeps one forced read from becoming N.
-  const forced = entry.stale;
-  const pending = forced || entry.reading === null ? startRead(entry) : entry.reading;
-  const result = await pending.result;
-  return await entry.lock.run(async () => {
-    // Two rules, and neither can stand in for the other. Against another READ it is identity —
-    // the same check `startRead` makes on `entry.reading` one function down, and the one
-    // `packages/cache/src/single-flight.ts` makes for the same reason — because an lsn cannot
-    // order two reads at all: a definition with no lsn provider answers `''` for both, and
-    // `'' >= ''` let the older one overwrite the gap repair the newer one had just landed, with
-    // `stale` already cleared by its issue and therefore nothing left to re-read. Against a
-    // CHANGE it is still the lsn, because a fanout moved `entry.lsn` forwards while this read was
-    // in flight and rewinding to what the read saw hands that subscriber rows the fanout has
-    // moved past — except for a forced read, which was issued *because* what is under it is
-    // wrong.
-    if (isNewestRead(entry, pending) && (forced || result.lsn >= entry.lsn)) {
-      applyRead(entry, pending, result);
-    }
-    return { rows: entry.rows, lsn: entry.lsn };
-  });
+  for (let attempt = 0; ; attempt += 1) {
+    // Read before `startRead` clears it: a second caller arriving during the read joins it and is
+    // not the one that forced it, which is what keeps one forced read from becoming N.
+    const forced = entry.stale;
+    const pending = forced || entry.reading === null ? startRead(entry) : entry.reading;
+    const result = await pending.result;
+    const again = await entry.lock.run(async () => {
+      // Two rules, and neither can stand in for the other. Against another READ it is identity —
+      // the same check `startRead` makes on `entry.reading` one function down, and the one
+      // `packages/cache/src/single-flight.ts` makes for the same reason — because an lsn cannot
+      // order two reads at all: a definition with no lsn provider answers `''` for both, and
+      // `'' >= ''` let the older one overwrite the gap repair the newer one had just landed, with
+      // `stale` already cleared by its issue and therefore nothing left to re-read. Against a
+      // CHANGE it is still the lsn, because a fanout moved `entry.lsn` forwards while this read was
+      // in flight and rewinding to what the read saw hands that subscriber rows the fanout has
+      // moved past — except for a forced read, which was issued *because* what is under it is
+      // wrong, and for the FIRST read, which has no window under it to rewind: a fanout never
+      // patches a window no read has landed in (`live-fanout.ts`), it marks it stale instead.
+      const first = entry.applied === 0;
+      if (isNewestRead(entry, pending) && (forced || first || result.lsn >= entry.lsn)) {
+        applyRead(entry, pending, result);
+      }
+      // A change reached this window while its first read was in flight and could not be folded,
+      // so what just landed may predate it: read once more before serving anyone a partial window.
+      return first && entry.stale && attempt < COLD_REREADS;
+    });
+    if (!again) return { rows: entry.rows, lsn: entry.lsn };
+  }
 }
 
+/**
+ * How many times a cold window re-reads because writes kept landing during its read. Bounded: a
+ * table written faster than it can be read would otherwise never serve a subscriber, and after the
+ * bound the window stays `stale`, so the next change re-reads it anyway.
+ */
+const COLD_REREADS = 3;
+
 /**
  * The same replacement, for a caller that is already holding the lane. A fanout cannot call
  * `fillWindow` — that takes the entry's own lane, and a lane is not reentrant — so the one path

package/src/replicator.ts

@@ -14,7 +14,7 @@
 import { isWriteDigest, logger, uuid, withSpan } from '@ultimat3/core';
 import type { ChangeEvent, ChangeFeed } from './changefeed';
 import type { Transport } from './fanout';
-import { type BackoffPolicy, backoffDelay, defaultBackoff, type Rng } from './thundering-herd';
+import { type BackoffPolicy, defaultBackoff, policyDelay, type Rng } from './thundering-herd';
 
 export const CHANGE_SUBJECT_PREFIX = 'x.change';
 
@@ -225,13 +225,16 @@ export function createReplicator(options: ReplicatorOptions): Replicator {
     },
 
     retryDelayMs(attempt: number): number {
-      return backoffDelay(attempt, backoff, options.rng ?? Math.random);
+      // This method's contract is 0-based (`retryDelayMs(0)` is the base); core counts from 1.
+      return policyDelay(backoff, attempt + 1, options.rng ?? Math.random);
     },
   };
 }
 
 /** Drops events the pipeline cannot use and hoists the tenant id out of the row. */
 export function normalize(change: ChangeEvent): ChangeEvent | null {
+  // The one change that carries no row by design; nothing to hoist a tenant out of.
+  if (change.op === 'truncate') return change;
   const row = change.after ?? change.before;
   if (!row) return null;
   if (change.op === 'insert' && change.after === null) return null;
@@ -253,7 +256,14 @@ export function parseEnvelope(payload: string): ChangeEnvelope | null {
     if (typeof parsed !== 'object' || parsed === null) return null;
     const shape = parsed as Partial<ChangeEvent> & { seq?: unknown; producer?: unknown };
     if (typeof shape.entity !== 'string' || typeof shape.lsn !== 'string') return null;
-    if (shape.op !== 'insert' && shape.op !== 'update' && shape.op !== 'delete') return null;
+    if (
+      shape.op !== 'insert' &&
+      shape.op !== 'update' &&
+      shape.op !== 'delete' &&
+      shape.op !== 'truncate'
+    ) {
+      return null;
+    }
     return {
       change: {
         entity: shape.entity,

package/src/server.ts

@@ -41,6 +41,7 @@ export {
   DEFAULT_MAX_TOPICS_PER_NODE,
 } from './channel';
 export { type ChannelDescription, describeChannels } from './channel-describe';
+export { RealtimeTopologyError } from './errors';
 export {
   InProcessTransport,
   type InProcessTransportOptions,
@@ -62,6 +63,11 @@ export {
   LiveQueryRegistry,
   type LiveQueryRegistryOptions,
 } from './live-query';
+export {
+  type LiveReplicator,
+  type LiveReplicatorOptions,
+  startLiveReplicator,
+} from './live-replicator';
 export {
   applyToWindow,
   type BridgeResult,
@@ -109,7 +115,7 @@ export { openNatsClient } from './nats-lib-client';
 export { NatsTransport, type NatsTransportOptions } from './nats-transport';
 export { PgAdvisoryLock, type PgAdvisoryLockOptions } from './pg-advisory-lock';
 // ---- the postgres replication path ------------------------------------------------------------
-export { camel, entityRow } from './pg-entity-row';
+export { entityRow } from './pg-entity-row';
 export {
   changeLsn,
   commitPositionOf,
@@ -166,16 +172,15 @@ export {
   actorIdOf,
   CLOSE,
   DEFAULT_FRAME_BURST,
-  DEFAULT_IDLE_TIMEOUT_MS,
   DEFAULT_MAX_BUFFERED_BYTES,
   DEFAULT_MAX_FRAMES_PER_SECOND,
-  idleSweepPeriodMs,
   SocketRegistry,
   type SocketRegistryOptions,
   SyncSocket,
   type SyncSocketOptions,
   type WsLike,
 } from './socket';
+export { DEFAULT_IDLE_TIMEOUT_MS, idleSweepPeriodMs } from './socket-idle';
 export type {
   GateFailed,
   GateStage,