@ultimat3/realtime 9.0.0 → 11.0.0

package/src/errors.ts

@@ -1,7 +1,8 @@
 // Realtime's X_* codes. Every throw in this package goes through one of these classes so
 // the same string renders in the terminal, the browser overlay, and `--json`.
 
-import { registerErrorCodes, UltimateError } from '@ultimat3/core';
+import { registerErrorCodes } from '@ultimat3/core';
+import { RealtimeError } from './realtime-error';
 
 /** Codes this package declares and owns. */
 export const REALTIME_OWNED_ERROR_CODES = [
@@ -18,6 +19,7 @@ export const REALTIME_OWNED_ERROR_CODES = [
   'X_REPLICATION_FAILED',
   'X_REPLICATOR_SLOT_HELD',
   'X_LIVE_CLIENT_MISSING',
+  'X_LIVE_SERVER_RENDER',
   'X_LIVE_ROW_UNIDENTIFIED',
   'X_LIVE_QUERY_UNKNOWN',
   'X_LIVE_REPLICA_IDENTITY',
@@ -111,7 +113,8 @@ export const REALTIME_ERROR_TITLES: Readonly<Record<RealtimeOwnedErrorCode, stri
   X_REPLICATION_PROTOCOL: 'the WAL stream cannot be decoded',
   X_REPLICATION_FAILED: 'the replication connection was refused',
   X_REPLICATOR_SLOT_HELD: 'another replicator already owns this database',
-  X_LIVE_CLIENT_MISSING: 'a realtime hook ran with no LiveClient registered',
+  X_LIVE_CLIENT_MISSING: 'a realtime hook ran in a browser with no LiveClient registered',
+  X_LIVE_SERVER_RENDER: 'a browser-only live operation ran during a server render',
   X_LIVE_ROW_UNIDENTIFIED: 'a live query returned a row with no id',
   X_LIVE_QUERY_UNKNOWN: 'no live query is registered under the name a subscribe frame asked for',
   X_LIVE_REPLICA_IDENTITY: 'a replicated table sends a key-only row on delete',
@@ -128,19 +131,17 @@ registerErrorCodes(
   ),
 );
 
-const DOCS_BASE = 'https://ultimate.dev/errors/';
-
-/** Base for every realtime error: fills `docs` from the code so no call site can forget it. */
-export class RealtimeError extends UltimateError {
-  constructor(opts: { code: RealtimeErrorCode; cause: string; fix: string }) {
-    super({
-      code: opts.code,
-      cause: opts.cause,
-      fix: opts.fix,
-      docs: `${DOCS_BASE}${opts.code}`,
-    });
-  }
-}
+// Re-exported, never re-declared: `RealtimeError` lives in `realtime-error.ts` and the four
+// replication errors in `replication-errors.ts`, so this file stays the CODE TABLE plus the
+// client-reachable refusals. Every name is still importable from `./errors`, which is what the
+// seventeen `pg-*` modules and the barrel already do.
+export { RealtimeError } from './realtime-error';
+export {
+  ReplicaIdentityError,
+  ReplicationFailedError,
+  ReplicationProtocolError,
+  ReplicatorSlotHeldError,
+} from './replication-errors';
 
 /** Subscribe (or an actor change) denied by the topic's policy. Never leaks the topic's data. */
 export class TopicForbiddenError extends RealtimeError {
@@ -280,93 +281,39 @@ export class TransportProtocolError extends RealtimeError {
 }
 
 /**
- * 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`.
+ * A hook was called IN A BROWSER before the app entry registered its client. Never a transient
+ * fault: the registration is a single call in the entry, so the fix is the call itself rather than
+ * a retry.
  *
- * **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.
+ * A server render is deliberately not this error, and never was a missing registration: there is
+ * no socket to register a client for. It gets `serverRenderLiveClient()` instead — the same rule
+ * `@ultimat3/ui`'s `solid()` follows for a missing Solid runtime, one package over.
  */
-export class ReplicaIdentityError extends RealtimeError {
-  constructor(args: { tables: readonly string[] }) {
+export class LiveClientMissingError extends RealtimeError {
+  constructor(args: { hook: 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',
+      code: 'X_LIVE_CLIENT_MISSING',
+      cause: `${args.hook}() ran in a browser before any LiveClient was registered`,
+      fix: 'setLiveClient(new LiveClient({ signal: createSignal, connect, buildId })) in the app entry, above the first render',
     });
   }
 }
 
 /**
- * A hook was called before the app entry registered its client. Never a transient fault: the
- * registration is a single call in the entry, so the fix is the call itself rather than a retry.
+ * Something that can only mean "talk to the socket" ran on the server client — a mutation, a
+ * publish, a topic subscription, a dial. There is no socket during a server render and there never
+ * will be one: the document is built and sent, and the browser opens the connection.
+ *
+ * A refusal rather than a silent no-op, because both alternatives are worse. Queueing it would
+ * hold one process-wide queue on behalf of whichever request happened to render, and dropping it
+ * would make a write that never happened look like one that did.
  */
-export class LiveClientMissingError extends RealtimeError {
-  constructor(args: { hook: string }) {
+export class ServerRenderLiveError extends RealtimeError {
+  constructor(args: { operation: string }) {
     super({
-      code: 'X_LIVE_CLIENT_MISSING',
-      cause: `${args.hook}() ran before any LiveClient was registered`,
-      fix: 'setLiveClient(new LiveClient({ signal: createSignal, connect, buildId })) in the app entry, above the first render',
+      code: 'X_LIVE_SERVER_RENDER',
+      cause: `${args.operation} ran during a server render, where this app has no live socket`,
+      fix: 'call it from an island mount() instead of from the page — or guard it with hasLiveClient(), which answers false on the server',
     });
   }
 }

package/src/hooks.ts

@@ -3,15 +3,16 @@
 // accessor is a closure over the `SignalFactory` the registered `LiveClient` was built with, and
 // every hook resolves that client through one ambient seam rather than a context per surface.
 
-import type { LiveClient, LiveHandle, LiveQueryRef, MutatorRef } from './client';
+import type { LiveClientLike, LiveHandle, LiveQueryRef, MutatorRef } from './client';
 import { LiveClientMissingError } from './errors';
 import type { JsonValue, Row } from './json';
 import type { LocalTx } from './local-store';
 import type { ConflictStrategy } from './rebase';
+import { serverRenderLiveClient } from './server-render-client';
 
 /** What `setLiveClient` holds. The version signal is the queue's only reactive handle — see below. */
 interface Registered {
-  readonly client: LiveClient;
+  readonly client: LiveClientLike;
   /** Read to subscribe, bumped to invalidate: `OfflineQueue` stores plain arrays, not signals. */
   readonly version: () => number;
   readonly bump: () => void;
@@ -22,7 +23,7 @@ interface Registered {
 let registered: Registered | null = null;
 
 /** Register once, in the app entry, before the first render. One app, one socket, one client. */
-export function setLiveClient(client: LiveClient): void {
+export function setLiveClient(client: LiveClientLike): void {
   // The previous registration's listener goes with it. The client outlives `setLiveClient` — a hot
   // reload, a test's next case, an app that re-registers after signing in — so a discarded
   // unsubscribe is a listener nothing can reach, bumping a signal nothing renders, once per
@@ -50,9 +51,41 @@ export function hasLiveClient(): boolean {
   return registered !== null;
 }
 
+/**
+ * A DOM is the whole of the question — the same probe and the same rule `@ultimat3/ui`'s `solid()`
+ * follows, and deliberately the same words. With a DOM, a hook reaching for a client nobody
+ * registered is a real bug: the app entry forgot `setLiveClient`, and every live query on the page
+ * is dead. Without one there is no socket a client could have been registered FOR — that is a
+ * server render, and `serverRenderLiveClient()` is an honest account of it rather than a
+ * degradation of a working path. Never widen this to "no client, never throw": that is the silent
+ * feed-that-never-loads the split exists to prevent.
+ */
+function hasDom(): boolean {
+  return typeof document !== 'undefined' && typeof window !== 'undefined';
+}
+
+/**
+ * The server render's registration, built once. Deliberately NOT written to `registered`:
+ * `hasLiveClient()` must keep answering `false` on the server, because that is the guard a
+ * component with a static fallback already uses to decide it is being server-rendered
+ * (`examples/dummy`'s `update-banner.tsx`).
+ */
+let serverSide: Registered | null = null;
+
+function serverRegistration(): Registered {
+  if (serverSide !== null) return serverSide;
+  const client = serverRenderLiveClient();
+  // The version signal never moves, and nothing on the server can move it: one pass, no queue,
+  // no ack — so `bump` and `release` are the no-ops that fact makes them.
+  const [version] = client.signal<number>(0);
+  serverSide = { client, version, bump: () => undefined, release: () => undefined };
+  return serverSide;
+}
+
 function live(hook: string): Registered {
-  if (registered === null) throw new LiveClientMissingError({ hook });
-  return registered;
+  if (registered !== null) return registered;
+  if (hasDom()) throw new LiveClientMissingError({ hook });
+  return serverRegistration();
 }
 
 // ---- useLive ------------------------------------------------------------------------------------

package/src/index.ts

@@ -9,6 +9,7 @@ export { applyPatches, orderAfterPatches } from './apply-patches';
 export {
   type ClientSocket,
   LiveClient,
+  type LiveClientLike,
   type LiveClientOptions,
   type LiveHandle,
   type LiveQueryRef,
@@ -34,7 +35,6 @@ export {
   type ResumeSource,
   resumeFrom,
   shouldResnapshot,
-  verifyDigest,
 } from './cursor';
 // ---- errors: one vocabulary for both halves, because every code reaches the wire ---------------
 export {
@@ -55,6 +55,7 @@ export {
   ReplicationFailedError,
   ReplicationProtocolError,
   ReplicatorSlotHeldError,
+  ServerRenderLiveError,
   SubscriptionLimitError,
   TopicForbiddenError,
   TransportProtocolError,
@@ -140,6 +141,8 @@ export {
   type ServerAck,
   strategyName,
 } from './rebase';
+// ---- what a LiveClient IS on the server: it serves the first render and opens no socket --------
+export { serverRenderLiveClient } from './server-render-client';
 // ---- the wire -------------------------------------------------------------------------------------
 export {
   type AckFrame,

package/src/live-query.ts

@@ -10,6 +10,7 @@ import { type Actor, type Clock, systemClock, uuid } from '@ultimat3/core';
 import { queryHash } from '@ultimat3/query';
 import type { ChangeEvent } from './changefeed';
 import {
+  advance,
   type LiveCursor,
   makeCursor,
   type ReconnectBudget,
@@ -199,10 +200,18 @@ export class LiveQueryRegistry {
           resumed.patches,
           new Set(cursor.ids),
         );
-        const subscription = this.#attachUnlessGone(entry, args.socket, sid, resumed.cursor);
+        // Advanced over the FILTERED list, never over `resumed.cursor` — which `resumeFrom` built
+        // by advancing across the retained window, and that window is PRE-POLICY. Seated as it
+        // came back, this subscriber's `cursor.ids` gained the id of every row inserted for every
+        // OTHER actor while it was away; `subscriber-gate` then reads `held.has(patch.id)` off it,
+        // takes the "the subscriber holds this row" branch, and delivers a `delete` frame carrying
+        // another tenant's row id and the instant it went. The leak that branch closes, re-opened
+        // one layer up. `live-fanout.ts` advances over `allowed` for exactly this reason.
+        const seated = advance(cursor, patches, resumed.cursor.lsn, now);
+        const subscription = this.#attachUnlessGone(entry, args.socket, sid, seated);
         return {
           subscription,
-          frame: { type: 'patch', v: PROTOCOL_VERSION, sid, patches, lsn: resumed.cursor.lsn },
+          frame: { type: 'patch', v: PROTOCOL_VERSION, sid, patches, lsn: seated.lsn },
         };
       }
       const subscription = this.#attachUnlessGone(entry, args.socket, sid, resumed.cursor);

package/src/local-store.ts

@@ -222,10 +222,20 @@ export interface OpfsLocalStoreOptions {
  * long write never blocks the main thread. Browser-only, so it must not be reachable from a server
  * bundle — which is why it is a factory that throws rather than a class you can accidentally new
  * on the server.
+ *
+ * The refusal below is the whole of what tier 3's durable half ships today, so its two lines have
+ * to be true of THIS build. Both were false until 2026-08-23: the fix told the caller to import
+ * this factory from a `/browser` subpath, which `package.json`'s `exports` has never declared —
+ * two entries ship, `.` and `./server` — so pasting it ended in a module-resolution failure. Its
+ * alternative was `persist: false` on the query, which `query()` has never accepted either (a
+ * `TS2353` excess property). An instruction that cannot run is axiom 4 failing in the package that
+ * documents it, so the fix now names an export that exists on an entry that exists:
+ * `MemoryLocalStore`, on `.`, declared beside this factory. `fix-specifier.test.ts` is the
+ * mechanical half.
  */
 export function createOpfsLocalStore(options: OpfsLocalStoreOptions): LocalStore {
   throw new NotImplementedError({
-    what: `OPFS SQLite local store (${options.file} v${options.schemaVersion})`,
-    fix: "import { createOpfsLocalStore } from '@ultimat3/realtime/browser' (tier 3, v2); today use MemoryLocalStore or set persist: false on the query",
+    what: `the OPFS SQLite local store for ${options.file} (schema v${options.schemaVersion}), which is realtime tier 3's durable half,`,
+    fix: "replace createOpfsLocalStore(...) with new MemoryLocalStore(), imported from '@ultimat3/realtime' beside it: the same LocalStore contract — journalled writes, ordered rollback, one row value per (entity, id) — held for the tab's lifetime rather than across a reload",
   });
 }

package/src/nats-lib-client.ts

@@ -14,6 +14,7 @@
 // This header said "every failure leaves here as an `UltimateError`" until 2026-08, which a reader
 // took as a guarantee it never was.
 
+import { renderThrowable } from '@ultimat3/core';
 import { connect, Events, headers, Match, type Msg, type MsgHdrs, type NatsConnection } from 'nats';
 import { TransportUnavailableError } from './errors';
 import {
@@ -57,8 +58,13 @@ const unavailable = (target: NatsTarget, reason: string): TransportUnavailableEr
     reason: `${target.host}:${target.port} — ${reason}`,
   });
 
-const describe = (error: unknown): string =>
-  error instanceof Error ? error.message : String(error);
+/**
+ * The caught value as text, for the `reason` that becomes an `X_TRANSPORT_UNAVAILABLE`. Core's
+ * total renderer and never `String(error)`: this text is built inside a `catch` block that has
+ * nothing left to answer with, and `String()` raises on a null-prototype throwable — which a
+ * library that is not this framework's may hand over.
+ */
+const describe = (error: unknown): string => renderThrowable(error);
 
 class LibNatsClient implements NatsClient {
   readonly #connection: NatsConnection;

package/src/nats-transport.ts

@@ -222,7 +222,9 @@ export class NatsTransport implements Transport {
       transport: this.name,
       subject,
       code: isUltimateError(error) ? error.code : undefined,
-      error: error instanceof Error ? error.message : String(error),
+      // `renderThrowable`, never `String(error)`: this is a reporter, and a throwable that fights
+      // being read makes the report the thing that throws.
+      error: renderThrowable(error),
     });
   }
 }

package/src/pg-array.ts

@@ -0,0 +1,141 @@
+// The Postgres array TEXT literal — `{a,b}`, `{"a,b",NULL}`, `{{1,2},{3,4}}` — and the element
+// type behind an array oid. Split from `pg-values.ts` so that file stays the oid switch and this
+// one stays the grammar; the element decoder arrives as a parameter, so neither imports the other.
+//
+// It exists because `@ultimat3/entity`'s repository hands an `arrayOf()` column back as a JS array
+// (the driver parses the literal) while the WAL carries the literal itself. A live row and a
+// repository row have to be the same object, so the literal is parsed here rather than shipped.
+
+/**
+ * `text[]` -> `text`. The wire names only the ARRAY type, so the element type behind it is a
+ * table — and it is a closed one: `arrayOf()` refuses `jsonb`, `bytea`, `money` and a nested array
+ * at declaration, so every array a framework entity can produce has its element listed below.
+ *
+ * The two it refuses are listed anyway (`1001`, `3807`, `199`): an adopted table can hold them,
+ * and decoding an element correctly costs nothing next to leaving the whole literal as text.
+ * An oid with no row — a user-defined enum's array, whose oid is per-database — is left as text
+ * rather than guessed at, which is what `undefined` means to `pg-values.ts`.
+ */
+const ELEMENT_OF = Object.freeze<Record<number, number>>({
+  1000: 16, // bool[]
+  1001: 17, // bytea[]
+  1005: 21, // int2[]
+  1007: 23, // int4[]
+  1009: 25, // text[]
+  1014: 1042, // bpchar[]
+  1015: 1043, // varchar[]
+  1016: 20, // int8[]
+  1021: 700, // float4[]
+  1022: 701, // float8[]
+  1028: 26, // oid[]
+  1115: 1114, // timestamp[]
+  1182: 1082, // date[]
+  1185: 1184, // timestamptz[]
+  1231: 1700, // numeric[]
+  199: 114, // json[]
+  2951: 2950, // uuid[]
+  3807: 3802, // jsonb[]
+});
+
+/** The element type oid behind an array type oid, or `undefined` when this table does not name it. */
+export function arrayElementOid(typeOid: number): number | undefined {
+  return Object.hasOwn(ELEMENT_OF, typeOid) ? ELEMENT_OF[typeOid] : undefined;
+}
+
+/** Where the scan is, so every branch below advances one cursor rather than slicing the text. */
+interface Scan {
+  readonly text: string;
+  at: number;
+}
+
+/**
+ * One array literal -> a nested JS array, or `null` when the text is not one this grammar
+ * describes. `null` is not an error: a dimension prefix (`[0:2]={…}`), a `DateStyle` this decoder
+ * does not read, or a corrupted literal all mean the same thing to the caller — keep the text it
+ * arrived as rather than deliver an array that is missing a member.
+ *
+ * `decode` is the ELEMENT decoder. It never sees a quoted element's quotes or its backslash
+ * escapes: an unquoted `NULL` is the null value and a quoted `"NULL"` is the four-character
+ * string, which is the one distinction the quoting exists to carry.
+ */
+export function parsePgArray<T>(text: string, decode: (raw: string) => T): PgArray<T> | null {
+  const scan: Scan = { text, at: 0 };
+  const parsed = readArray(scan, decode);
+  // Trailing content means the literal was not what this grammar accepted, whatever it parsed.
+  return parsed === null || scan.at !== text.length ? null : parsed;
+}
+
+/** A member is a decoded value, the null member, or — for a multidimensional array — a row of them. */
+export type PgArray<T> = (T | null | PgArray<T>)[];
+
+function readArray<T>(scan: Scan, decode: (raw: string) => T): PgArray<T> | null {
+  if (scan.text[scan.at] !== '{') return null;
+  scan.at += 1;
+  const out: PgArray<T> = [];
+  if (scan.text[scan.at] === '}') {
+    scan.at += 1;
+    return out;
+  }
+  for (;;) {
+    const member = readMember(scan, decode);
+    if (member === FAILED) return null;
+    out.push(member);
+    const next = scan.text[scan.at];
+    scan.at += 1;
+    if (next === '}') return out;
+    if (next !== ',') return null;
+  }
+}
+
+/** A sentinel, because `null` is a legal member and `undefined` would be a second spelling of it. */
+const FAILED = Symbol('pg-array-failed');
+
+function readMember<T>(
+  scan: Scan,
+  decode: (raw: string) => T,
+): T | null | PgArray<T> | typeof FAILED {
+  const head = scan.text[scan.at];
+  if (head === '{') {
+    const nested = readArray(scan, decode);
+    return nested === null ? FAILED : nested;
+  }
+  if (head === '"') {
+    const quoted = readQuoted(scan);
+    return quoted === null ? FAILED : decode(quoted);
+  }
+  const start = scan.at;
+  while (scan.at < scan.text.length) {
+    const char = scan.text[scan.at];
+    if (char === ',' || char === '}') break;
+    // A brace or a quote inside a bare element is a literal this grammar does not describe.
+    if (char === '{' || char === '"') return FAILED;
+    scan.at += 1;
+  }
+  if (scan.at === scan.text.length) return FAILED;
+  const raw = scan.text.slice(start, scan.at);
+  // Unquoted and case-insensitive is the ONLY spelling of the null member; `"NULL"` is a string.
+  return raw.toUpperCase() === 'NULL' ? null : decode(raw);
+}
+
+/** The text between one pair of quotes, with `\\` and `\"` unescaped. `null` if it never closes. */
+function readQuoted(scan: Scan): string | null {
+  scan.at += 1;
+  let out = '';
+  while (scan.at < scan.text.length) {
+    const char = scan.text[scan.at];
+    if (char === '"') {
+      scan.at += 1;
+      return out;
+    }
+    if (char === '\\') {
+      const escaped = scan.text[scan.at + 1];
+      if (escaped === undefined) return null;
+      out += escaped;
+      scan.at += 2;
+      continue;
+    }
+    out += char ?? '';
+    scan.at += 1;
+  }
+  return null;
+}

package/src/pg-connection.ts

@@ -80,8 +80,22 @@ export class PgConnection {
       user: options.user,
       database: options.database,
       application_name: options.applicationName ?? 'ultimate-replicator',
+      // The session's output formats, decided here because the decoder cannot ask. Postgres sends
+      // every WAL value as TEXT and `pg-values.ts` reads a `timestamptz` by matching postgres'
+      // ISO spelling — keeping the raw text when it does not match, on purpose, because a wrong
+      // instant is worse than a string. So `DateStyle = SQL | German | Postgres` on the SERVER
+      // silently re-opens the defect that decode exists to close: the shared window holds `Date`s,
+      // the patch holds text, and one edit to one column jumps its row to the top of every
+      // `orderBy('createdAt','desc')` feed for every subscriber.
+      //
+      // Byte for byte what postgres' OWN logical-replication client sends (`libpqwalreceiver.c`),
+      // which is why a walsender takes it: `intervalstyle` for the values this decoder keeps as
+      // text (a text form still has to be ONE text form), `extra_float_digits` so a float8 round
+      // 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',
     };
-    // A walsender rejects most GUCs, so only the two it accepts are sent.
     if (options.replication !== undefined) parameters['replication'] = options.replication;
     // A handshake fails on ordinary conditions — no password, an ErrorResponse, an EOF — and on
     // every one of them the caller gets an exception instead of an object, so nothing is left

package/src/pg-entity-row.ts

@@ -7,7 +7,7 @@
 
 import { describeValue } from '@ultimat3/core';
 import { ReplicationProtocolError } from './errors';
-import type { JsonObject, JsonValue } from './json';
+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 {
@@ -24,7 +24,7 @@ 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: JsonObject;
+  readonly value: PhysicalRow;
 }
 
 /**
@@ -73,7 +73,7 @@ function moneyMinor(column: string, value: number | string): number {
  * `/^\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: JsonValue): number {
+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;
@@ -100,7 +100,7 @@ function moneyScale(column: string, value: JsonValue): number {
  * 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.
  */
-function shownNumber(value: JsonValue): string {
+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));
@@ -119,7 +119,7 @@ function shownNumber(value: JsonValue): string {
  * column of its own: the fold consumes it whenever the group folds.
  */
 function foldMoney(
-  physical: Readonly<Record<string, JsonValue>>,
+  physical: Readonly<Record<string, PhysicalValue>>,
   name: string,
 ): FoldedMoney | null {
   const prefix = moneyPrefix(name);
@@ -171,8 +171,8 @@ function claim(taken: Map<string, string>, property: string, column: string): vo
  * 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, JsonValue>>): JsonObject {
-  const row: JsonObject = {};
+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>();