@ultimat3/realtime 9.0.0 → 11.0.0

package/src/pg-replication.ts

@@ -3,19 +3,30 @@
 // 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 Clock, logger, renderThrowable, systemClock } from '@ultimat3/core';
 import type { ChangeEvent, ChangeOp, PgLogicalReplicationOptions } from './changefeed';
 import { ReplicationProtocolError } from './errors';
-import { isRow, type JsonObject, type Row } from './json';
+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, preflight } from './pg-preflight';
 import { bunPgStream, parsePgUrl } from './pg-socket';
+import type { PhysicalRow } from './pg-values';
 import { PgOutputDecoder, type PgOutputMessage, type PgRelation } from './pgoutput';
 
 const DEFAULT_STATUS_INTERVAL_MS = 10_000;
 
+/**
+ * Consecutive standby-status writes that may fail before the stream is declared dead.
+ *
+ * Three, at the default 10s interval, is 30s — inside postgres' own 60s `wal_sender_timeout`, so
+ * the replicator gives up at roughly the same moment the server would. It is a constant and not an
+ * option because it is a fraction of `statusIntervalMs`, and a second knob is a second number that
+ * can disagree with the one it is a fraction of.
+ */
+const MAX_CONFIRM_FAILURES = 3;
+
 /** `r` — the standby status update, the only frontend message a walsender listens for. */
 const STANDBY_STATUS = 0x72;
 
@@ -33,6 +44,13 @@ export interface ReplicationStreamStats {
    * be alerted on. Inserts never count: there is no `before` to be partial.
    */
   readonly partialBefore: number;
+  /**
+   * Standby-status writes that have failed in a row without one landing in between. It is the half
+   * of a broken stream the delivery count cannot show: the read side goes on delivering while
+   * `confirmed_flush_lsn` stops advancing, so WAL accumulates on the primary with nothing else
+   * 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.
@@ -92,6 +110,7 @@ export class PgReplicationStream {
   #skipped = 0;
   #replayed = 0;
   #partialBefore = 0;
+  #confirmFailures = 0;
   #failure: string | null = null;
 
   constructor(options: PgLogicalReplicationOptions) {
@@ -115,6 +134,7 @@ export class PgReplicationStream {
       skipped: this.#skipped,
       replayed: this.#replayed,
       partialBefore: this.#partialBefore,
+      confirmFailures: this.#confirmFailures,
       failure: this.#failure,
     };
   }
@@ -163,8 +183,9 @@ export class PgReplicationStream {
     // 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.
     this.#failure = null;
+    this.#confirmFailures = 0;
     this.#timer = setInterval(() => {
-      void this.#confirm();
+      void this.#confirmOnTimer();
     }, 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?.();
@@ -276,7 +297,7 @@ export class PgReplicationStream {
         }
       }
     } catch (failure) {
-      await this.#die(failure instanceof Error ? failure.message : String(failure));
+      await this.#die(renderThrowable(failure));
     }
   }
 
@@ -312,8 +333,8 @@ export class PgReplicationStream {
   async #deliver(
     op: ChangeOp,
     relation: PgRelation,
-    oldTuple: JsonObject | null,
-    newTuple: JsonObject | null,
+    oldTuple: PhysicalRow | null,
+    newTuple: PhysicalRow | null,
     handlers: ReplicationStreamHandlers,
   ): Promise<void> {
     const transaction = this.#transaction;
@@ -359,9 +380,47 @@ export class PgReplicationStream {
     this.#delivered += 1;
   }
 
+  /**
+   * The TIMER's confirm, and the one call that may not reject. `void this.#confirm()` handed the
+   * rejection to nobody: `#confirm` awaits `#writing`, which rejects the moment the socket is gone,
+   * and no package in this repo installs an `unhandledRejection` handler, so Bun ends the process —
+   * an uncoded `TypeError` reaching the operator with no code and no `fix:`, and exit code 1 on an
+   * otherwise clean shutdown.
+   *
+   * Worse than the crash was the silence before it: `stats().failure` stayed `null`, so `/readyz`
+   * reported the replicator live while `confirmed_flush_lsn` stopped advancing and WAL piled up on
+   * the primary. A run of failures is now a death, the same way `#drain`'s catch is — the four
+   * things `#die` owns go together or not at all.
+   */
+  async #confirmOnTimer(): Promise<void> {
+    try {
+      await this.#confirm();
+      // Consecutive, not cumulative: one confirm that lands means the walsender is being told
+      // where we are, and a lifetime count would eventually kill a healthy stream.
+      this.#confirmFailures = 0;
+    } catch (failure) {
+      this.#confirmFailures += 1;
+      logger.warn('replication confirm failed', {
+        slot: this.#options.slot,
+        consecutive: this.#confirmFailures,
+        error: renderThrowable(failure),
+      });
+      const consecutive = this.#confirmFailures;
+      if (consecutive >= MAX_CONFIRM_FAILURES) {
+        await this.#die(
+          `${consecutive} standby status updates failed in a row — ` +
+            `the slot is not being confirmed: ${renderThrowable(failure)}`,
+        );
+      }
+    }
+  }
+
   /**
    * 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.
+   *
+   * It still RAISES: `stop()` and the keepalive reply both await it and both need the answer. Only
+   * the timer, which awaits nothing, goes through `#confirmOnTimer` above.
    */
   async #confirm(connection: PgConnection | null = this.#connection): Promise<void> {
     if (connection === null || !connection.inCopyBoth) return;
@@ -375,16 +434,21 @@ export class PgReplicationStream {
       .int64(at)
       .uint8(0)
       .finish();
-    this.#writing = this.#writing.then(
-      () => connection.sendCopyData(payload),
-      () => undefined,
-    );
-    await this.#writing;
+    // The chain SERIALIZES writes; it does not decide them. Putting the rejection handler on the
+    // chain itself meant the confirm after a failed one resolved without writing anything —
+    // `.then(send, () => undefined)` runs the second handler and hands back its `undefined`, so
+    // every other standby status update after the first failure was a no-op that reported success.
+    // A run of failures could then never be seen, because the run never got past one.
+    const attempt = this.#writing.then(() => connection.sendCopyData(payload));
+    // What the NEXT caller queues behind is this attempt settled either way; what THIS caller
+    // awaits is the attempt itself, because it is the only one entitled to its outcome.
+    this.#writing = attempt.catch(() => undefined);
+    await attempt;
   }
 }
 
 /** A physical tuple becomes the row the matcher's predicates are written against, or nothing. */
-function toRow(relation: PgRelation, physical: JsonObject | null): Row | null {
+function toRow(relation: PgRelation, physical: PhysicalRow | 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,

package/src/pg-values.ts

@@ -0,0 +1,166 @@
+// One physical Postgres value, off the WAL as text, becomes the value a ROW holds — the same one
+// `@ultimat3/entity`'s repository produces for that column. Lifted out of `pgoutput.ts` so that
+// file stays message framing and this one stays the type catalogue.
+//
+// The rule it enforces is `CLAUDE.md`'s: **a live row must equal a repository row.** The WAL is
+// text and a repository row is not, so `timestamp()` is a `Date` on both sides, `arrayOf()` is a
+// JS array on both sides and `bytes()` is a `Uint8Array` on both sides. Left as postgres' own
+// text, `compareValues(new Date(…), '2026-08-09 12:00:00+00')` fell to `String(left) < String(right)`
+// — `"1786…"` against `"2026-…"` — so one edit to one column moved every row of an
+// `orderBy('createdAt','desc')` feed to the top for every subscriber, and `post.tags.map(…)` threw
+// in the component the first patch reached.
+
+import { renderThrowable } from '@ultimat3/core';
+import { ReplicationProtocolError } from './errors';
+import type { JsonValue } from './json';
+import { arrayElementOid, parsePgArray } from './pg-array';
+
+/**
+ * What a row value can be between the WAL and the wire: JSON, plus the two JS shapes a repository
+ * row already carries. `Date` and `Uint8Array` are not `JsonValue` and are not meant to be — they
+ * are what `JSON.stringify` turns into the string a SNAPSHOT frame carries, which is precisely the
+ * format a patch frame has to converge on.
+ */
+export type PhysicalValue =
+  | JsonValue
+  | Date
+  | Uint8Array
+  | PhysicalValue[]
+  | { [key: string]: PhysicalValue };
+
+export type PhysicalRow = { [key: string]: PhysicalValue };
+
+/**
+ * `2026-08-09 12:00:00.123456+00` -> the ISO-8601 form `new Date` is specified to accept.
+ *
+ * Postgres writes a space between the date and the clock, an offset that may be `+00`, `+0530` or
+ * `+05:30`, and as many fractional digits as the column's precision. `Date` holds milliseconds, so
+ * the fraction is TRUNCATED to three — which is what the driver does on the repository side, so
+ * both readers of one column land on the same instant.
+ */
+const TIMESTAMP =
+  /^(\d{4,6})-(\d{2})-(\d{2})[ T](\d{2}):(\d{2}):(\d{2})(\.\d+)?(Z|[+-]\d{2}(?::?\d{2})?)?$/;
+
+/**
+ * `undefined` for a text this decoder does not describe — `infinity`, a BC date, a non-ISO
+ * `DateStyle` — and the caller keeps the text it arrived as. Silence beats a wrong instant: the
+ * value still crosses, it simply does not claim to be a `Date`.
+ *
+ * The `DateStyle` half is closed at the SESSION and not here: `pg-connection.ts` pins
+ * `datestyle=ISO` in the startup packet, so a server configured `SQL`, `German` or `Postgres`
+ * cannot quietly send this branch every timestamp it decodes. Nothing in this file may depend on
+ * that — a text it cannot read still keeps its text — but a reader wondering why the ISO
+ * assumption is safe should look there rather than rediscover it.
+ *
+ * A `timestamp without time zone` (oid 1114) carries no offset and is read as UTC. This framework's
+ * `timestamp()` is always `timestamptz`, so the only way to reach that branch is an adopted table —
+ * and UTC is the one reading with no ambient zone in it.
+ */
+function toInstant(text: string): Date | undefined {
+  const parts = TIMESTAMP.exec(text);
+  if (parts === null) return undefined;
+  const [, year, month, day, hour, minute, second, fraction, zone] = parts;
+  const millis = fraction === undefined ? '000' : `${fraction.slice(1)}000`.slice(0, 3);
+  const parsed = new Date(
+    `${year}-${month}-${day}T${hour}:${minute}:${second}.${millis}${offsetOf(zone)}`,
+  );
+  return Number.isNaN(parsed.getTime()) ? undefined : parsed;
+}
+
+/** `+05` and `+0530` are offsets postgres writes and `Date` does not read; `±HH:MM` is both. */
+function offsetOf(zone: string | undefined): string {
+  if (zone === undefined || zone === 'Z') return 'Z';
+  if (zone.length === 3) return `${zone}:00`;
+  if (zone.length === 5) return `${zone.slice(0, 3)}:${zone.slice(3)}`;
+  return zone;
+}
+
+const HEX = /^[0-9a-fA-F]*$/;
+
+/**
+ * `\x0102` -> `Uint8Array([1, 2])`, the value `bytes()` parses to on the repository side.
+ *
+ * `undefined` for anything else, including the pre-9.0 `escape` output format: that one is
+ * ambiguous without knowing the server's `bytea_output`, and a wrong byte string is worse than the
+ * text. Nothing this framework creates sets it.
+ */
+function toBytes(text: string): Uint8Array | undefined {
+  if (!text.startsWith('\\x')) return undefined;
+  const hex = text.slice(2);
+  if (hex.length % 2 !== 0 || !HEX.test(hex)) return undefined;
+  const out = new Uint8Array(hex.length / 2);
+  for (let i = 0; i < out.length; i += 1) out[i] = Number.parseInt(hex.slice(i * 2, i * 2 + 2), 16);
+  return out;
+}
+
+/**
+ * Postgres sends every value as text (we never negotiate binary). Decoding depends on the
+ * column's type oid — the wire gives us nothing else to go on, so this switch is the one place
+ * that type catalogue is encoded.
+ */
+export function decodeValue(typeOid: number, text: string): PhysicalValue {
+  switch (typeOid) {
+    case 16: // bool
+      return text === 't';
+
+    case 20: {
+      // int8: only safe as a number if it round-trips exactly; otherwise keep the digits —
+      // a rounded bigint is a worse lie than a string that still parses correctly downstream.
+      const asNumber = Number(text);
+      return Number.isSafeInteger(asNumber) ? asNumber : text;
+    }
+
+    case 21: // int2
+    case 23: // int4
+    case 26: // oid
+      return Number(text);
+
+    case 700: // float4
+    case 701: // float8
+      // JSON has no literal for these three, so the text form survives the round trip instead of
+      // silently becoming a number `JSON.stringify` would otherwise turn into `null`.
+      if (text === 'NaN' || text === 'Infinity' || text === '-Infinity') return text;
+      return Number(text);
+
+    case 1700: // numeric — exactness beats convenience; money is never a float here.
+      return text;
+
+    case 114: // json
+    case 3802: {
+      // jsonb
+      let parsed: unknown;
+      try {
+        parsed = JSON.parse(text);
+      } catch (cause) {
+        throw new ReplicationProtocolError({
+          stage: 'value',
+          detail: `type oid ${typeOid} carried invalid json: ${renderThrowable(cause)}`,
+        });
+      }
+      return parsed as JsonValue;
+    }
+
+    case 1114: // timestamp
+    case 1184: // timestamptz
+      // A `Date`, because `timestamp()` reads back as one through the repository and the two have
+      // to be one value: `JSON.stringify` gives the wire the same ISO string either way.
+      return toInstant(text) ?? text;
+
+    case 1082: // date
+      // Already the value: `date()` parses to `@ultimat3/time`'s `PlainDate`, which IS the
+      // `YYYY-MM-DD` string postgres wrote. Converting it to a `Date` would be the 100x-style
+      // reinterpretation the calendar/instant split exists to prevent.
+      return text;
+
+    case 17: // bytea
+      return toBytes(text) ?? text;
+
+    default: {
+      // An array type's element is the only thing left that changes the answer, and only when this
+      // decoder knows which element type it is — see `pg-array.ts` for what an unknown oid costs.
+      const element = arrayElementOid(typeOid);
+      if (element === undefined) return text; // text, varchar, uuid, enum, and everything else.
+      return parsePgArray(text, (raw) => decodeValue(element, raw)) ?? text;
+    }
+  }
+}

package/src/pgoutput.ts

@@ -1,12 +1,13 @@
-import { renderThrowable } from '@ultimat3/core';
 // Decodes pgoutput logical-replication messages (protocol version 1, Postgres >= 12) into typed
-// PgOutputMessage values, and the postgres text-format values inside each tuple into JsonValue.
-// Pure byte decoding: no sockets, no I/O. A decoder instance owns the per-connection relation
-// cache that later Insert/Update/Delete/Truncate messages reference by oid.
+// PgOutputMessage values. Pure byte decoding: no sockets, no I/O. A decoder instance owns the
+// per-connection relation cache that later Insert/Update/Delete/Truncate messages reference by oid.
+//
+// What a tuple's TEXT means is `pg-values.ts`'s: this file frames messages, that one owns the type
+// catalogue that turns postgres' text into the value a repository row holds.
 
 import { ReplicationProtocolError } from './errors';
-import type { JsonObject, JsonValue } from './json';
 import { ByteReader, pgTimestampToEpochMs } from './pg-bytes';
+import { decodeValue, type PhysicalRow } from './pg-values';
 
 export interface PgColumn {
   /** part of the replica identity key — set by the `flags & 1` bit. */
@@ -40,85 +41,25 @@ export type PgOutputMessage =
       readonly commitAt: number;
     }
   | { readonly kind: 'relation'; readonly relation: PgRelation }
-  | { readonly kind: 'insert'; readonly relation: PgRelation; readonly after: JsonObject }
+  | { readonly kind: 'insert'; readonly relation: PgRelation; readonly after: PhysicalRow }
   | {
       readonly kind: 'update';
       readonly relation: PgRelation;
-      readonly before: JsonObject | null;
-      readonly after: JsonObject;
+      readonly before: PhysicalRow | null;
+      readonly after: PhysicalRow;
     }
-  | { readonly kind: 'delete'; readonly relation: PgRelation; readonly before: JsonObject }
+  | { readonly kind: 'delete'; readonly relation: PgRelation; readonly before: PhysicalRow }
   | { readonly kind: 'truncate'; readonly relations: readonly PgRelation[] }
   /** origin / type / logical message — decoded far enough to be skipped safely. */
   | { readonly kind: 'other'; readonly tag: string };
 
-/**
- * Postgres sends every value as text (we never negotiate binary). Decoding depends on the
- * column's type oid — the wire gives us nothing else to go on, so this switch is the one place
- * that type catalogue is encoded.
- */
-function decodeValue(typeOid: number, text: string): JsonValue {
-  switch (typeOid) {
-    case 16: // bool
-      return text === 't';
-
-    case 20: {
-      // int8: only safe as a number if it round-trips exactly; otherwise keep the digits —
-      // a rounded bigint is a worse lie than a string that still parses correctly downstream.
-      const asNumber = Number(text);
-      return Number.isSafeInteger(asNumber) ? asNumber : text;
-    }
-
-    case 21: // int2
-    case 23: // int4
-    case 26: // oid
-      return Number(text);
-
-    case 700: // float4
-    case 701: // float8
-      // JSON has no literal for these three, so the text form survives the round trip instead of
-      // silently becoming a number `JSON.stringify` would otherwise turn into `null`.
-      if (text === 'NaN' || text === 'Infinity' || text === '-Infinity') return text;
-      return Number(text);
-
-    case 1700: // numeric — exactness beats convenience; money is never a float here.
-      return text;
-
-    case 114: // json
-    case 3802: {
-      // jsonb
-      let parsed: unknown;
-      try {
-        parsed = JSON.parse(text);
-      } catch (cause) {
-        throw new ReplicationProtocolError({
-          stage: 'value',
-          detail: `type oid ${typeOid} carried invalid json: ${renderThrowable(cause)}`,
-        });
-      }
-      return parsed as JsonValue;
-    }
-
-    case 1082: // date
-    case 1114: // timestamp
-    case 1184: // timestamptz
-      return text; // an ISO-ish string; never a `Date` — the row must stay JSON.
-
-    case 17: // bytea — the `\x...` text form, as-is.
-      return text;
-
-    default: // text, varchar, uuid, enum, and everything else not called out above.
-      return text;
-  }
-}
-
 /**
  * Int16 ncolumns + that many columns. Every tuple kind (insert's new row, update/delete's old
  * row, a `'K'` key-only row) shares this decoder: postgres always sends one byte per column,
  * `'u'` standing in for the columns a key-only tuple leaves out — so the column count always
  * matches the relation, and only the per-column byte tells us whether a value is actually there.
  */
-function decodeTupleData(reader: ByteReader, relation: PgRelation): JsonObject {
+function decodeTupleData(reader: ByteReader, relation: PgRelation): PhysicalRow {
   const count = reader.int16();
   if (count !== relation.columns.length) {
     throw new ReplicationProtocolError({
@@ -129,7 +70,9 @@ function decodeTupleData(reader: ByteReader, relation: PgRelation): JsonObject {
     });
   }
 
-  const row: JsonObject = {};
+  // Null-prototype: `column.name` is off the WIRE, so a column literally named `__proto__` set
+  // the prototype of every row this decoder built. `Object.create(null)` has no prototype to set.
+  const row: PhysicalRow = Object.create(null) as PhysicalRow;
   for (const column of relation.columns) {
     const kind = reader.tag();
     if (kind === 'n') {
@@ -256,7 +199,7 @@ export class PgOutputDecoder {
   #decodeUpdate(reader: ByteReader): PgOutputMessage {
     const relation = this.#relationOrThrow(reader.int32());
     let marker = reader.tag();
-    let before: JsonObject | null = null;
+    let before: PhysicalRow | null = null;
     if (marker === 'K' || marker === 'O') {
       before = decodeTupleData(reader, relation);
       marker = reader.tag();

package/src/realtime-error.ts

@@ -0,0 +1,28 @@
+// The class every realtime error extends, and nothing else.
+//
+// Apart from `errors.ts` so a concern-specific error module can extend it WITHOUT importing the
+// code table — `errors.ts` re-exports both, so `RealtimeError` and every subclass stay importable
+// from where they always were. Its own file rather than a re-export inside `errors.ts`, because
+// that would be a cycle: `extends` runs at module evaluation, imports hoist above it, and the base
+// would be in its temporal dead zone by the time the subclass module was evaluated.
+
+import { UltimateError } from '@ultimat3/core';
+import type { RealtimeErrorCode } from './errors';
+
+/**
+ * Base for every realtime error. No `docs:` — `UltimateError` fills it from
+ * `describeErrorCode(code).docs`, which is `@ultimat3/core`'s `ERROR_DOCS_URL`: one page for every
+ * code, never one per code, because `wiki/` is the framework's only public documentation surface
+ * and a code lives there in a TABLE ROW, which has no anchor. The
+ * `https://ultimate.dev/errors/<code>` links this class built until 9.x answered 404, host
+ * included, on every error it has ever thrown — including the ones `toWireError` puts on the wire.
+ */
+export class RealtimeError extends UltimateError {
+  constructor(opts: { code: RealtimeErrorCode; cause: string; fix: string }) {
+    super({
+      code: opts.code,
+      cause: opts.cause,
+      fix: opts.fix,
+    });
+  }
+}

package/src/replication-errors.ts

@@ -0,0 +1,87 @@
+// The four refusals the Postgres replication half raises: the wire, the connection, the slot, and
+// the replica identity it warns about.
+//
+// Split out of `errors.ts` on the one seam this package already draws — these are the only codes
+// no browser can reach, thrown by `pg-*.ts` and the replicator and by nothing on the client half.
+// The codes themselves stay in `errors.ts`, whose `registerErrorCodes()` is what
+// `package.json`'s `sideEffects` names; this module runs nothing at import.
+
+import { RealtimeError } from './realtime-error';
+
+/**
+ * The bytes on the replication socket are not the bytes the protocol allows: a truncated message,
+ * an unknown pgoutput tag, an auth method we do not speak. Always a version or configuration
+ * mismatch rather than a transient fault, so retrying the same connection cannot help.
+ */
+export class ReplicationProtocolError extends RealtimeError {
+  constructor(args: { stage: string; detail: string; fix?: string }) {
+    super({
+      code: 'X_REPLICATION_PROTOCOL',
+      cause: `postgres replication ${args.stage}: ${args.detail}`,
+      fix:
+        args.fix ??
+        'x doctor db — the server must be postgres >= 14 with a pgoutput publication and wal_level=logical',
+    });
+  }
+}
+
+/**
+ * The replication connection itself failed — refused credentials, a slot another process holds,
+ * an `ErrorResponse` from the server. The server's own message is passed through verbatim
+ * because it names the object that has to change.
+ */
+export class ReplicationFailedError extends RealtimeError {
+  constructor(args: { stage: string; detail: string; fix: string }) {
+    super({
+      code: 'X_REPLICATION_FAILED',
+      cause: `postgres replication ${args.stage} failed: ${args.detail}`,
+      fix: args.fix,
+    });
+  }
+}
+
+/**
+ * A second replicator found the advisory lock held. Distinct from `X_REPLICATION_FAILED` because
+ * nothing is wrong with this process: the database already has its one replicator, and a second
+ * one that started anyway would publish every change twice. Terminal for a container whose whole
+ * job is that role — the scheduler is the thing that has to change, not the connection.
+ */
+export class ReplicatorSlotHeldError extends RealtimeError {
+  constructor(args: { key: string; holder?: string | undefined }) {
+    super({
+      code: 'X_REPLICATOR_SLOT_HELD',
+      cause:
+        `advisory lock ${args.key} is held${args.holder === undefined ? '' : ` by ${args.holder}`}` +
+        ' — one database has exactly one replicator',
+      fix: 'scale the replicator to 1 per database: kubectl scale deploy/replicator --replicas=1',
+    });
+  }
+}
+
+/**
+ * A table in the entity list replicates with a replica identity other than FULL, so its `delete`
+ * (and any key-changing `update`) carries the KEY COLUMNS ONLY. `toRow` accepts that tuple —
+ * it only requires a text `id` — so the live matcher decides "did this row leave the result set"
+ * from a one-column row, and a row policy written against `!row.private` reads `undefined`.
+ *
+ * **Raised at preflight and LOGGED, never thrown.** Every app running today on the default
+ * identity would stop booting, and the replicator refusing to start is a worse outcome than the
+ * partial rows it is warning about. The runtime half is `ReplicationStreamStats.partialBefore`,
+ * which counts the changes this actually affects. Refusing it at `x verify` time is the follow-up.
+ *
+ * The tables are named because the fix is per table, and they are the entity list's own names —
+ * every one has already passed `assertIdentifier`, so the `fix:` is SQL that can be pasted.
+ */
+export class ReplicaIdentityError extends RealtimeError {
+  constructor(args: { tables: readonly string[] }) {
+    super({
+      code: 'X_LIVE_REPLICA_IDENTITY',
+      cause:
+        `${args.tables.join(', ')} replicate with a replica identity other than FULL, so a ` +
+        'delete carries the key columns only and a live query decides visibility from a partial row',
+      fix:
+        `${args.tables.map((table) => `ALTER TABLE ${table} REPLICA IDENTITY FULL;`).join(' ')}` +
+        ' -- rows already written to the WAL keep the identity they were written with',
+    });
+  }
+}

package/src/server-render-client.ts

@@ -0,0 +1,96 @@
+// What a live client IS on the server: one that serves the first render and opens no socket.
+//
+// The rule it exists for is `@ultimat3/ui`'s, one package over — no runtime and no DOM is a SERVER
+// RENDER, and a server render gets an honest account of itself rather than a throw. A page whose
+// whole body reads a live query could not server-render at all before this: `useConnection()` threw
+// `X_LIVE_CLIENT_MISSING` and the route answered 500 (issue #271).
+//
+// It implements `LiveClientLike` and imports NO connection lifecycle — no `LiveClient`, no
+// heartbeat, no wire protocol. Measured: reaching the class from here costs every island that
+// calls `useLive` 18 kB it can never run.
+
+import type { LiveClientLike, LiveHandle, LiveQueryRef, SignalFactory } from './client-contract';
+import { ServerRenderLiveError } from './errors';
+import type { JsonValue, Row } from './json';
+import type { LiveState } from './live-rows';
+
+/**
+ * A signal that never changes, because nothing on the server can change it: one render, one pass,
+ * no reactive runtime. The setter is kept rather than dropped so a caller that writes through it
+ * reads its own write back — a signal that swallowed writes would be a different lie.
+ */
+const inertSignal: SignalFactory = <T>(initial: T): [() => T, (next: T) => void] => {
+  let held = initial;
+  return [
+    (): T => held,
+    (next: T): void => {
+      held = next;
+    },
+  ];
+};
+
+/** Frozen, so a handle a page holds cannot be turned into a result set by writing to it. */
+const NO_ROWS: readonly Row[] = Object.freeze([]);
+
+/** Nothing was subscribed, so nothing is released — and a teardown never fails a render. */
+const releaseNothing = (): void => undefined;
+
+/**
+ * The handle a server render gets for a live query: `loading`, never `offline` and never `live`.
+ *
+ * That is the one honest state — the rows arrive over a socket this render does not have, so the
+ * page's own loading fallback is what the document carries until hydration replaces it. `offline`
+ * would be read as a SETTLED answer (`state() !== 'loading'` is the gate `examples/dummy`'s feed
+ * uses), so an empty result set would render "you have no posts" for a feed that has some.
+ */
+function serverRenderHandle<R extends Row>(): LiveHandle<R> {
+  return {
+    rows: () => NO_ROWS as readonly R[],
+    state: (): LiveState => 'loading',
+    cursor: () => null,
+    unsubscribe: releaseNothing,
+    [Symbol.dispose]: releaseNothing,
+  };
+}
+
+/**
+ * Every member that can only mean "talk to the socket" refuses; every member a render READS
+ * answers what a server render actually is.
+ *
+ * `connected: true` is not a lie about the socket — `useConnection().offline` is a banner about
+ * THIS visitor's connectivity, and the request being served is the proof it is up. Answering
+ * `false` would server-render "you are offline" into every document, for a reader who is not, and
+ * then remove it on hydrate.
+ *
+ * It registers nothing, which is what makes ONE instance per process safe under concurrent
+ * renders: a client that kept a registration per `useLive` would grow by one entry per request,
+ * forever, and hold a row window with each.
+ */
+function build(): LiveClientLike {
+  return {
+    signal: inertSignal,
+    queue: undefined,
+    connected: true,
+    reconnectAt: () => null,
+    appUpdateAvailable: () => null,
+    useLive: <R extends Row>(_query: LiveQueryRef, _input: JsonValue): LiveHandle<R> =>
+      serverRenderHandle<R>(),
+    mutate: (): Promise<void> => {
+      throw new ServerRenderLiveError({ operation: 'mutate()' });
+    },
+    drain: (): Promise<void> => {
+      throw new ServerRenderLiveError({ operation: 'drain()' });
+    },
+    // A listener is accepted and never called: nothing on the server can change a queue that does
+    // not exist. Refusing here would break `setLiveClient`, which registers one unconditionally.
+    onQueueChange: () => releaseNothing,
+  };
+}
+
+let held: LiveClientLike | null = null;
+
+/** ONE per process, built on first use. It holds nothing per request — see `build` above. */
+export function serverRenderLiveClient(): LiveClientLike {
+  held ??= build();
+  return held;
+}