@ultimat3/realtime 22.15.0 → 24.0.0

package/src/pg-tls.ts

@@ -62,6 +62,24 @@ export function parseSsl(params: URLSearchParams): SslSettings {
 /** Whether a mode asks the runtime for the verification at all. */
 export const verifies = (ssl: SslMode): boolean => ssl === 'verify-ca' || ssl === 'verify-full';
 
+/**
+ * Whether a cleartext or md5 password request is answered. Cleartext IS the password; md5 is
+ * replayable. What each mode actually protects against:
+ *
+ * - `verify-ca` / `verify-full`: the session is encrypted to a server whose certificate was
+ *   checked. The only modes that stop an ON-PATH attacker.
+ * - `require`: encrypted, to whoever answered. No certificate is verified, so this stops a PASSIVE
+ *   listener and nothing else — an attacker on the path can terminate the TLS session itself and
+ *   ask for the password. Answered anyway: it is libpq's behaviour, and managed databases whose
+ *   CA an app does not hold depend on it. An operator who needs more names a `verify-*` mode.
+ * - `disable`: the operator SAYING the session is cleartext — the opt-in.
+ * - `allow` / `prefer` (the default, and what an unstated mode is): refused. They do not even
+ *   promise encryption — a stripped upgrade falls back to cleartext without a word — so they stop
+ *   neither kind of attacker, and nobody chose that.
+ */
+export const answersWeakAuth = (ssl: SslMode | undefined): boolean =>
+  ssl === 'disable' || ssl === 'require' || (ssl !== undefined && verifies(ssl));
+
 /** OpenSSL's code for a certificate whose chain verified but whose names do not include the host. */
 const HOST_MISMATCH = 'ERR_TLS_CERT_ALTNAME_INVALID';
 

package/src/pg-wire.ts

@@ -69,8 +69,10 @@ export class MessageReader {
         if (held === 0) return undefined;
         throw new ReplicationProtocolError({
           stage: 'read',
-          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',
+          detail:
+            `the connection closed with ${held} bytes of a partial message — the backend was ` +
+            'terminated mid-message, and the server log names the reason',
+          fix: 'x doctor --json',
         });
       }
       this.#append(chunk);
@@ -245,7 +247,7 @@ export const FIXES: Readonly<Record<string, string>> = {
 };
 
 /** What a SQLSTATE this table has no entry for is answered with. */
-const GENERIC_FIX = 'x doctor db — the postgres message above names the object to change';
+const GENERIC_FIX = 'x doctor --json';
 
 /**
  * An `ErrorResponse` becomes the one error class whose `fix` names the command to run.

package/src/pgoutput.ts

@@ -1,9 +1,7 @@
-// Decodes pgoutput logical-replication messages (protocol version 1, Postgres >= 12) into typed
-// 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.
+// Decodes pgoutput logical-replication messages (protocol version 1) into typed PgOutputMessage
+// values; the stream asks `messages 'true'`, which needs Postgres >= 14. Pure byte decoding, no
+// I/O: a decoder owns the per-connection relation cache later tuples reference by oid. What a
+// tuple's TEXT means is `pg-values.ts`'s — this file frames messages, that one owns the types.
 
 import { isWriteDigest, WRITE_ORIGIN_WAL_PREFIX } from '@ultimat3/core';
 import { ReplicationProtocolError } from './errors';
@@ -48,6 +46,12 @@ export type PgOutputMessage =
       readonly relation: PgRelation;
       readonly before: PhysicalRow | null;
       readonly after: PhysicalRow;
+      /**
+       * Physical columns the new tuple sent as `'u'`: an out-of-line (TOAST) value the UPDATE did
+       * not touch, for which Postgres logs no bytes. They are absent from `after`, and this list is
+       * what tells "absent" apart from "the whole row".
+       */
+      readonly unchanged: readonly string[];
     }
   | { readonly kind: 'delete'; readonly relation: PgRelation; readonly before: PhysicalRow }
   | { readonly kind: 'truncate'; readonly relations: readonly PgRelation[] }
@@ -67,7 +71,11 @@ export type PgOutputMessage =
  * `'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): PhysicalRow {
+function decodeTupleData(
+  reader: ByteReader,
+  relation: PgRelation,
+  unchanged?: string[],
+): PhysicalRow {
   const count = reader.int16();
   if (count !== relation.columns.length) {
     throw new ReplicationProtocolError({
@@ -90,6 +98,7 @@ function decodeTupleData(reader: ByteReader, relation: PgRelation): PhysicalRow
     if (kind === 'u') {
       // Omitted, not nulled: "unchanged" and "set to null" are different facts about the row,
       // and a missing key is the only encoding that keeps those two facts distinguishable.
+      unchanged?.push(column.name);
       continue;
     }
     if (kind === 't') {
@@ -245,8 +254,9 @@ export class PgOutputDecoder {
         detail: `expected the new-tuple marker "N" but got "${marker}"`,
       });
     }
-    const after = decodeTupleData(reader, relation);
-    return { kind: 'update', relation, before, after };
+    const unchanged: string[] = [];
+    const after = decodeTupleData(reader, relation, unchanged);
+    return { kind: 'update', relation, before, after, unchanged };
   }
 
   #decodeDelete(reader: ByteReader): PgOutputMessage {

package/src/presence.ts

@@ -25,6 +25,13 @@ export const PRESENCE_SWEEP_PREFIX = 'presence.sweep';
  */
 export const DEFAULT_MAX_PRESENCE_MEMBERS = 256;
 
+/**
+ * Member ids the sweep leader ships on its lease, for the other nodes to record. Bounded because
+ * the lease is one bus message: past it, a member is known to the leader alone, as every member
+ * was before the lease carried a roster.
+ */
+export const PRESENCE_LEASE_ROSTER_LIMIT = 4_096;
+
 export interface PresenceOptions {
   readonly transport: Transport;
   /** Optional: without a hub, presence is queryable but silent (no join/leave frames). */
@@ -65,6 +72,10 @@ export class PresenceRegistry {
   readonly #nodeId: string;
   /** Diffing cache only — the truth is always `transport.shared`. Safe to lose. */
   readonly #seen = new Map<string, Set<string>>();
+  /** Per topic this node LEADS: the roster on its lease, as written. */
+  readonly #shipped = new Map<string, string>();
+  /** Per topic this node FOLLOWS: the ids the leader's lease last named. */
+  readonly #heard = new Map<string, ReadonlySet<string>>();
 
   constructor(options: PresenceOptions) {
     this.#transport = options.transport;
@@ -100,7 +111,10 @@ export class PresenceRegistry {
     return await this.roster(name);
   }
 
-  /** `false` means the member had already expired: the caller must `join` again, not `heartbeat`. */
+  /**
+   * A member's beat: its TTL renewed, nothing announced and nothing read. `false` means the member
+   * had already expired: the caller must `join` again, not `heartbeat`.
+   */
   async heartbeat(name: Topic, id: string): Promise<boolean> {
     const alive = await this.#transport.shared.touch(this.#key(name), id, this.#ttlMs);
     if (!alive) this.#track(name).delete(id);
@@ -190,12 +204,18 @@ export class PresenceRegistry {
       // A room nobody is in is not a room. Without this the cache keeps one entry per topic ever
       // subscribed to, for the life of the process, and the sweep walks all of them forever.
       if ((this.#seen.get(name)?.size ?? 0) === 0) {
-        this.#seen.delete(name);
+        this.#forget(name);
+        continue;
+      }
+      const lease = await this.#claimSweep(name);
+      if (!lease.leads) {
+        this.#record(name, lease.roster);
         continue;
       }
-      if (!(await this.#claimSweep(name))) continue;
+      this.#heard.delete(name);
       gone.push(...(await this.sweep(name)));
-      if ((this.#seen.get(name)?.size ?? 0) === 0) this.#seen.delete(name);
+      await this.#ship(name);
+      if ((this.#seen.get(name)?.size ?? 0) === 0) this.#forget(name);
     }
     return gone;
   }
@@ -211,14 +231,59 @@ export class PresenceRegistry {
    * different views is a duplicate `leave` for a member who has already gone — which is what a
    * `leave` frame means anyway. What it never produces is nobody sweeping: a claim is re-put every
    * pass, and a dead leader's expires within one TTL.
+   *
+   * The leader's claim CARRIES the ids it last saw live, and every follower reads it in the read
+   * the election already makes. That is what a takeover diffs against: a leader that dies takes
+   * its own members with it, and a successor that had skipped every sweep held nothing but its own
+   * — so their leaves were never announced, to anyone, until each client reconnected.
    */
-  async #claimSweep(name: Topic): Promise<boolean> {
+  async #claimSweep(
+    name: Topic,
+  ): Promise<{ readonly leads: boolean; readonly roster: readonly string[] | null }> {
     const key = `${PRESENCE_SWEEP_PREFIX}.${name}`;
-    await this.#transport.shared.put(key, this.#nodeId, '', this.#ttlMs);
+    await this.#transport.shared.put(key, this.#nodeId, this.#shipped.get(name) ?? '', this.#ttlMs);
     const claimants = await this.#transport.shared.entries(key);
     let leader = this.#nodeId;
-    for (const claimant of claimants) if (claimant.member < leader) leader = claimant.member;
-    return leader === this.#nodeId;
+    let roster: readonly string[] | null = null;
+    for (const claimant of claimants) {
+      if (claimant.member > leader) continue;
+      leader = claimant.member;
+      roster = parseRoster(claimant.value);
+    }
+    return { leads: leader === this.#nodeId, roster };
+  }
+
+  /** A follower's pass: what the leader said is live is recorded, what it stopped saying is not. */
+  #record(name: Topic, roster: readonly string[] | null): void {
+    this.#shipped.delete(name);
+    // A leader that has not swept yet has said nothing: nothing is learned and nothing forgotten.
+    if (roster === null) return;
+    const tracked = this.#track(name);
+    const now = new Set(roster);
+    // Dropped by the leader while it is alive means the leader announced it.
+    for (const id of this.#heard.get(name) ?? []) if (!now.has(id)) tracked.delete(id);
+    for (const id of now) tracked.add(id);
+    this.#heard.set(name, now);
+  }
+
+  /** The leader's roster, written onto its lease when it changed. */
+  async #ship(name: Topic): Promise<void> {
+    const ids = [...(this.#seen.get(name) ?? [])].sort().slice(0, PRESENCE_LEASE_ROSTER_LIMIT);
+    const value = JSON.stringify(ids);
+    if (this.#shipped.get(name) === value) return;
+    this.#shipped.set(name, value);
+    await this.#transport.shared.put(
+      `${PRESENCE_SWEEP_PREFIX}.${name}`,
+      this.#nodeId,
+      value,
+      this.#ttlMs,
+    );
+  }
+
+  #forget(name: Topic): void {
+    this.#seen.delete(name);
+    this.#shipped.delete(name);
+    this.#heard.delete(name);
   }
 
   /** Full-set frame for a client that just (re)connected — presence has no delta protocol. */
@@ -283,6 +348,18 @@ export function presenceFrame(
   };
 }
 
+/** A lease value as the leader wrote it: a JSON list of member ids, or nothing yet. */
+function parseRoster(value: string): readonly string[] | null {
+  if (value === '') return null;
+  try {
+    const parsed: unknown = JSON.parse(value);
+    if (!Array.isArray(parsed)) return null;
+    return parsed.filter((id): id is string => typeof id === 'string');
+  } catch {
+    return null;
+  }
+}
+
 function parseMember(id: string, value: string): PresenceMember | null {
   try {
     const parsed: unknown = JSON.parse(value);

package/src/query-window.ts

@@ -30,6 +30,11 @@ export interface QueryEntry {
   readonly qid: string;
   readonly definition: LiveQueryDefinition;
   readonly input: JsonValue;
+  /**
+   * The org this window is read for and patched for — its subscribers' own, `null` for subscribers
+   * that carry none. Part of `qid`, so two orgs on one `(query, input)` are two entries.
+   */
+  readonly tenant: string | null;
   /** Told to the client on every snapshot: the identity scope its rows belong under. */
   readonly rowEntity: string | null;
   /** The record key a row travels under; `null` = its `id` (a plain table). */
@@ -80,12 +85,14 @@ export function createEntry(
   definition: LiveQueryDefinition,
   input: JsonValue,
   matcher: IncrementalMatcher,
-  options?: EntryOptions,
+  options?: EntryOptions & { readonly tenant?: string | null },
 ): QueryEntry {
+  const tenant = options?.tenant ?? null;
   return {
     qid,
     definition,
     input,
+    tenant,
     // Resolved with the matcher, from the same build: `prepare` has already run, so a definition
     // that compiles its shape per input can answer.
     rowEntity: definition.rowEntity?.(input) ?? null,
@@ -96,7 +103,9 @@ export function createEntry(
       // static declaration and can only be a superset of it. Preferring the matcher is what lets a
       // definition built from a real query carry no static list at all.
       entities: matcher.entities.length > 0 ? matcher.entities : definition.entities,
-      orgId: orgIdOf(input),
+      // The window's own tenant first: a change in another org is dropped before any predicate
+      // runs, whether or not the query's `where` happens to name one.
+      orgId: tenant ?? orgIdOf(input),
       ...(definition.columns ? { columns: definition.columns } : {}),
     },
     matcher,
@@ -122,9 +131,8 @@ export function createEntry(
  * had already been fanned out would rewind every later subscriber to rows the window has moved
  * past, so a stale read is discarded and its caller is served from the newer window instead.
  */
-export async function fillWindow(
-  entry: QueryEntry,
-): Promise<{ rows: readonly Row[]; lsn: string }> {
+export async function fillWindow(entry: QueryEntry): Promise<FilledWindow> {
+  let landed: FilledWindow['landed'] = null;
   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.
@@ -146,15 +154,28 @@ export async function fillWindow(
       const first = entry.applied === 0;
       if (isNewestRead(entry, pending) && (forced || first || result.lsn >= entry.lsn)) {
         applyRead(entry, pending, result);
+        // A forced read outranks a first one: what it replaced was known to be wrong.
+        landed = forced || landed === 'forced' ? 'forced' : first ? 'first' : landed;
       }
       // 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 };
+    if (!again) return { rows: entry.rows, lsn: entry.lsn, landed };
   }
 }
 
+/**
+ * The window a caller is served from, and whether THIS call put a read into it. `landed` is what
+ * decides the retained ring's floor (`change-buffer.ts`): `null` is a window that was already
+ * filled — its patch history is still true, and flooring it would evict every other subscriber's.
+ */
+export interface FilledWindow {
+  readonly rows: readonly Row[];
+  readonly lsn: string;
+  readonly landed: 'first' | 'forced' | null;
+}
+
 /**
  * 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
@@ -253,7 +274,7 @@ function startRead(entry: QueryEntry): PendingRead {
  */
 async function readSnapshot(entry: QueryEntry): Promise<SnapshotResult> {
   try {
-    return await entry.definition.snapshot({ input: entry.input });
+    return await entry.definition.snapshot({ input: entry.input, tenant: entry.tenant });
   } catch (error) {
     entry.stale = true;
     throw error;

package/src/record-persister.ts

@@ -88,10 +88,15 @@ export function recordPersister(options: RecordPersisterOptions): RecordPersiste
   });
 
   const restore = async (): Promise<number> => {
-    const scope = scopeKey(principal());
+    const owner = principal();
+    const scope = scopeKey(owner);
     if (scope === undefined) return 0;
+    const stored = await options.local.rows(scope);
+    // The read is async and a principal change can land inside it: its rescope has already cleared
+    // the store, so restoring now would hand the previous principal's rows to the next one.
+    if (principal() !== owner) return 0;
     let restored = 0;
-    for (const [type, rows] of await options.local.rows(scope)) {
+    for (const [type, rows] of stored) {
       if (!options.types.has(type)) continue;
       options.store.restore(type, rows);
       restored += Object.keys(rows).length;

package/src/replication-errors.ts

@@ -17,10 +17,14 @@ 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 requirement rides the cause when the caller names no fix of its own: a `fix:` is one
+      // command, and `x doctor` has no `db` subcommand for the old line to have been one.
+      cause:
+        `postgres replication ${args.stage}: ${args.detail}` +
+        (args.fix === undefined
+          ? ' — the server must be postgres >= 14 with a pgoutput publication and wal_level=logical'
+          : ''),
+      fix: args.fix ?? 'x doctor --json',
     });
   }
 }

package/src/replicator-envelope.ts

@@ -0,0 +1,110 @@
+// The bus envelope, read side: one published change decoded back into a `ChangeEvent` (rows revived
+// through their entity's columns), with the producer and sequence a lost message is visible in —
+// and the detector a `sync` node runs over them. The publisher is `replicator.ts`.
+
+import { isWriteDigest } from '@ultimat3/core';
+import type { ChangeEvent } from './changefeed';
+import { reviveBusRow } from './replicator-row';
+
+/**
+ * What the bus actually carries: one change, plus who published it and where in that publisher's
+ * stream it sits.
+ *
+ * Fanout is core NATS — `publish`, no ack, at most once — so a consumer that reads only the change
+ * cannot tell "nothing happened" from "eleven changes went past while I was reconnecting". An lsn
+ * cannot answer it either: a WAL position is a byte offset, so a legitimate next change is an
+ * arbitrary jump forwards. A per-publisher counter is the one number a gap is visible in.
+ *
+ * Both fields are optional on the wire, so a node reading a publisher that predates them simply
+ * detects nothing — the same rule the `snapshot.entity` field follows, on a subject no client sees.
+ */
+export interface ChangeEnvelope {
+  readonly change: ChangeEvent;
+  /** Monotonic within `producer`, from 1. `null` from a publisher that does not sequence. */
+  readonly seq: number | null;
+  /** Identifies one replicator *run*. A new one restarts `seq` — and follows a stream that died. */
+  readonly producer: string | null;
+}
+
+/** Sync-node side of the bus: decode a published change back into a `ChangeEvent`. */
+export function parseChange(payload: string): ChangeEvent | null {
+  return parseEnvelope(payload)?.change ?? null;
+}
+
+/** The same decode, keeping the two fields a gap is visible in. `parseChange` is this, narrowed. */
+export function parseEnvelope(payload: string): ChangeEnvelope | null {
+  try {
+    const parsed: unknown = JSON.parse(payload);
+    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' &&
+      shape.op !== 'truncate'
+    ) {
+      return null;
+    }
+    return {
+      change: {
+        entity: shape.entity,
+        op: shape.op,
+        before: reviveBusRow(shape.entity, shape.before ?? null),
+        after: reviveBusRow(shape.entity, shape.after ?? null),
+        lsn: shape.lsn,
+        txid: typeof shape.txid === 'string' ? shape.txid : '',
+        orgId: typeof shape.orgId === 'string' ? shape.orgId : null,
+        at: typeof shape.at === 'number' ? shape.at : 0,
+        // Only the minted shape crosses: a frame decoder refuses anything else, so a malformed
+        // label here would cost every member the whole frame rather than one page its echo.
+        ...(isWriteDigest(shape.write) ? { write: shape.write } : {}),
+        ...(isNames(shape.omitted) ? { omitted: shape.omitted } : {}),
+      },
+      seq: typeof shape.seq === 'number' && Number.isFinite(shape.seq) ? shape.seq : null,
+      producer: typeof shape.producer === 'string' ? shape.producer : null,
+    };
+  } catch {
+    return null;
+  }
+}
+
+/** A non-empty list of property names — the only shape `ChangeEvent.omitted` crosses the bus in. */
+const isNames = (value: unknown): value is readonly string[] =>
+  Array.isArray(value) && value.length > 0 && value.every((name) => typeof name === 'string');
+
+/**
+ * The consume-side twin of the publisher's counter, and the only thing on a `sync` node that can
+ * say "this node missed changes". Publish-side duplicate and out-of-order guards already existed;
+ * there was no equivalent here, so a NATS blip during a rolling restart was eleven changes that
+ * simply never happened as far as every subscriber on this node could tell.
+ *
+ * Per producer, because a replicator restart legitimately rewinds the counter. A repeat or a
+ * reordering is *not* reported as a gap — the window's own lsn guard refuses those — and neither is
+ * the first message this node ever reads: a node that joined late has missed everything by
+ * definition, and every subscription it holds started after it did.
+ *
+ * A NEW producer after a known one IS a gap. The run before it died — that is why there is a new
+ * one — and nothing says its last messages reached this node: the tail of a dead stream has no
+ * later sequence number to be missed against. One re-read per replicator restart is the price.
+ */
+export class SeqGapDetector {
+  readonly #next = new Map<string, number>();
+
+  /** `true` when at least one message between the last one and this one was never delivered. */
+  observe(envelope: ChangeEnvelope): boolean {
+    const { producer, seq } = envelope;
+    if (producer === null || seq === null) return false;
+    const expected = this.#next.get(producer);
+    const succeeds = expected === undefined && this.#next.size > 0;
+    // Never backwards: a redelivery must not lower the bar and turn the next legitimate message
+    // into a gap of its own.
+    this.#next.set(producer, Math.max(expected ?? 0, seq + 1));
+    return succeeds || (expected !== undefined && seq > expected);
+  }
+
+  /** Producers this node has read. Bounded by replicator restarts, so it is swept on a drain. */
+  forget(): void {
+    this.#next.clear();
+  }
+}

package/src/replicator-row.ts

@@ -0,0 +1,75 @@
+// Single responsibility: a change's rows across the replicator bus. The bus carries text, a row
+// holds a `Date` and a `Uint8Array`, and `JSON.parse` returns neither — so the publisher writes a
+// form JSON can carry and the sync node reads it back through the ENTITY's own columns.
+
+import { entityForTable } from '@ultimat3/entity';
+import type { Row } from './json';
+
+const CHUNK = 0x8000;
+
+/** Base64 of raw bytes. Chunked: one `String.fromCharCode(...bytes)` overflows the stack at ~100k. */
+function toBase64(bytes: Uint8Array): string {
+  let binary = '';
+  for (let at = 0; at < bytes.length; at += CHUNK) {
+    binary += String.fromCharCode(...bytes.subarray(at, at + CHUNK));
+  }
+  return btoa(binary);
+}
+
+function fromBase64(text: string): Uint8Array {
+  const binary = atob(text);
+  const bytes = new Uint8Array(binary.length);
+  for (let at = 0; at < binary.length; at += 1) bytes[at] = binary.charCodeAt(at);
+  return bytes;
+}
+
+/**
+ * Publish side. A `Date` already serialises to the ISO text its column reads back; a `Uint8Array`
+ * serialises to `{"0":1,"1":2}`, which nothing reads back, so it crosses as base64. Only a
+ * top-level value can be one: `arrayOf()` refuses `bytes()` at declaration.
+ */
+export function busRow(row: Row | null): Row | null {
+  if (row === null) return null;
+  let out: Record<string, unknown> | undefined;
+  for (const [property, value] of Object.entries(row as Record<string, unknown>)) {
+    if (!(value instanceof Uint8Array)) continue;
+    out ??= { ...row };
+    out[property] = toBase64(value);
+  }
+  return out === undefined ? row : (out as unknown as Row);
+}
+
+/**
+ * Consume side: the row as the replicator held it before it was text. Without this every `Date`
+ * reached the matcher as an ISO string, `compareValues(Date, string)` fell to comparing their
+ * printed forms, and one edit to one column moved its row to the top of every window ordered by
+ * a timestamp — on every deployment with a bus, and in no in-process test, which hands the object
+ * over directly.
+ *
+ * Decided by the column that DECLARED the value, never by what the value looks like: a `text()`
+ * holding `2026-08-09T12:00:00.000Z` stays text. `table` is `ChangeEvent.entity`, which on the WAL
+ * path is the relation name. A table with no entity here, a property with no column, and a value
+ * its column refuses are all handed back as they arrived — a change that crosses unrevived is the
+ * old behaviour; a change dropped is a window that silently diverges.
+ */
+export function reviveBusRow(table: string, row: Row | null): Row | null {
+  if (row === null) return null;
+  const entity = entityForTable(table);
+  if (entity === undefined) return row;
+  const out: Record<string, unknown> = {};
+  for (const [property, value] of Object.entries(row as Record<string, unknown>)) {
+    out[property] = value;
+    if (value === null || !Object.hasOwn(entity.$columns, property)) continue;
+    const column = entity.$columns[property];
+    if (column === undefined || column.$meta.sealed !== undefined) continue;
+    try {
+      out[property] =
+        column.$meta.kind === 'bytea' && typeof value === 'string'
+          ? fromBase64(value)
+          : column.$parse(value);
+    } catch {
+      // Kept as it arrived — see the function comment.
+    }
+  }
+  return out as unknown as Row;
+}