@ultimat3/realtime 23.0.0 → 25.0.0

package/src/pg-replication.ts

@@ -4,14 +4,14 @@
 // the lsn is the only authority the pipeline has.
 
 import { type Clock, finiteOption, logger, renderThrowable, systemClock } from '@ultimat3/core';
-import type { ChangeEvent, ChangeOp, PgLogicalReplicationOptions } from './changefeed';
+import type { ChangeEvent, ChangeOp, PostgresChangeFeedOptions } from './changefeed';
 import { ReplicationProtocolError } from './errors';
-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 } from './pg-identifier';
+import { paramsChannelTables } from './pg-identity-tables';
 import { preflight } from './pg-preflight';
+import { replicatedImages, tenantOf } from './pg-replication-row';
 import { bunPgStream, parsePgUrl } from './pg-socket';
 import type { PhysicalRow } from './pg-values';
 import { keyedWrite, PgOutputDecoder, type PgOutputMessage, type PgRelation } from './pgoutput';
@@ -52,10 +52,7 @@ export interface ReplicationStreamStats {
    * 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.
-   */
+  /** Why the pump stopped, or `null` while live. Recorded here and ANNOUNCED through `onEnd`. */
   readonly failure: string | null;
 }
 
@@ -88,14 +85,16 @@ export const commitPositionOf = (lsn: string): bigint => BigInt(`0x${lsn.slice(0
 export interface ReplicationStreamHandlers {
   readonly from?: string | undefined;
   onChange(event: ChangeEvent): void | Promise<void>;
+  /** Called once when the pump dies on its own; never for a `stop()`. */
+  readonly onEnd?: ((reason: string) => void) | undefined;
 }
 
 /**
- * One slot, one connection, one process. Started by `PgLogicalReplicationFeed`, which is itself
+ * One slot, one connection, one process. Started by `PostgresChangeFeed`, which is itself
  * held by the single `replicator` role — the advisory lock upstream is what keeps that "one" true.
  */
 export class PgReplicationStream {
-  readonly #options: PgLogicalReplicationOptions;
+  readonly #options: PostgresChangeFeedOptions;
   readonly #clock: Clock;
   readonly #entities: ReadonlySet<string>;
   readonly #slot: string;
@@ -115,8 +114,9 @@ export class PgReplicationStream {
   #partialBefore = 0;
   #confirmFailures = 0;
   #failure: string | null = null;
+  #onEnd: ((reason: string) => void) | undefined;
 
-  constructor(options: PgLogicalReplicationOptions) {
+  constructor(options: PostgresChangeFeedOptions) {
     this.#options = options;
     this.#clock = options.clock ?? systemClock;
     this.#entities = new Set(options.entities.map((name) => assertIdentifier('entity', name)));
@@ -166,10 +166,12 @@ export class PgReplicationStream {
       replication: 'database',
       applicationName: `ultimate-replicator:${slot}`,
       rng: this.#options.rng,
+      ssl: target.ssl,
     });
     this.#connection = connection;
     try {
-      await preflight(connection, slot, publication, this.#entities);
+      const full = this.#options.fullIdentityTables ?? paramsChannelTables();
+      await preflight(connection, slot, publication, this.#entities, new Set(full));
       const from = handlers.from;
       this.#confirmed = from === undefined ? 0n : commitPositionOf(from);
       await connection.startCopyBoth(
@@ -183,10 +185,10 @@ export class PgReplicationStream {
       throw failure;
     }
     this.#running = true;
-    // 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.
+    // A restart that kept the last death in `stats()` would report a live stream as failed.
     this.#failure = null;
     this.#confirmFailures = 0;
+    this.#onEnd = handlers.onEnd;
     this.#timer = setInterval(
       () => {
         void this.#confirmOnTimer();
@@ -241,6 +243,20 @@ export class PgReplicationStream {
     if (failures.length > 0) throw failures[0];
   }
 
+  /**
+   * `stop()` without the goodbye: no confirm, no `CopyDone`, no `Terminate`, nothing awaited — on a
+   * black-holed walsender each of those is a write nothing settles. The unconfirmed tail is
+   * re-sent to the next stream and dropped by its `from`.
+   */
+  abandon(): void {
+    this.#running = false;
+    this.#onEnd = undefined;
+    this.#clearTimer();
+    const connection = this.#connection;
+    this.#connection = null;
+    connection?.destroy();
+  }
+
   /**
    * The pump's only way out, however it ended — a decode error, or a walsender that said goodbye.
    * The four things it owns go together or not at all, because each one left behind is a dead
@@ -256,8 +272,7 @@ export class PgReplicationStream {
     this.#clearTimer();
     const connection = this.#connection;
     this.#connection = null;
-    // The supervisor reads /readyz, so the loop records, reports and ends rather than throwing
-    // into a promise nothing awaits.
+    // The loop records, reports and ends rather than throwing into a promise nothing awaits.
     logger.error('replication stream ended', { slot: this.#options.slot, error: reason });
     try {
       await connection?.close();
@@ -265,6 +280,14 @@ export class PgReplicationStream {
       // The socket is already unusable and `failure` above is the report that matters — a
       // goodbye that throws must not become the rejection `#drain` promised never to produce.
     }
+    // Last, so whoever restarts finds the socket already let go. Called, never awaited.
+    const onEnd = this.#onEnd;
+    this.#onEnd = undefined;
+    try {
+      onEnd?.(reason);
+    } catch (failure) {
+      logger.error('replication onEnd listener threw', { error: renderThrowable(failure) });
+    }
   }
 
   #clearTimer(): void {
@@ -330,19 +353,21 @@ export class PgReplicationStream {
         if (message.endLsn > this.#confirmed) this.#confirmed = message.endLsn;
         return;
       case 'insert':
-        await this.#deliver('insert', message.relation, null, message.after, handlers);
+        await this.#deliver('insert', message.relation, null, message.after, [], handlers);
         return;
-      case 'update':
-        await this.#deliver('update', message.relation, message.before, message.after, handlers);
+      case 'update': {
+        const { relation, before, after, unchanged } = message;
+        await this.#deliver('update', relation, before, after, unchanged, handlers);
         return;
+      }
       case 'delete':
-        await this.#deliver('delete', message.relation, message.before, null, handlers);
+        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);
+          await this.#deliver('truncate', relation, null, null, [], handlers);
         }
         return;
       default:
@@ -356,6 +381,7 @@ export class PgReplicationStream {
     relation: PgRelation,
     oldTuple: PhysicalRow | null,
     newTuple: PhysicalRow | null,
+    unchanged: readonly string[],
     handlers: ReplicationStreamHandlers,
   ): Promise<void> {
     const transaction = this.#transaction;
@@ -386,10 +412,9 @@ export class PgReplicationStream {
     if ((op === 'update' || op === 'delete') && relation.replicaIdentity !== 'f') {
       this.#partialBefore += 1;
     }
-    const before = toRow(relation, oldTuple, 'before');
-    const after = toRow(relation, newTuple, 'after');
+    const { before, after, omitted } = replicatedImages(relation, oldTuple, newTuple, unchanged);
     const event: ChangeEvent = {
-      entity: relation.name,
+      table: relation.name,
       op,
       before,
       after,
@@ -397,7 +422,8 @@ export class PgReplicationStream {
       txid: transaction.xid.toString(10),
       orgId: tenantOf(after ?? before),
       at: transaction.commitAt,
-      ...(transaction.write === undefined ? {} : { write: transaction.write }),
+      write: transaction.write ?? null,
+      ...(omitted.length === 0 ? {} : { omitted }),
     };
     await handlers.onChange(event);
     this.#lastLsn = lsn;
@@ -470,30 +496,3 @@ export class PgReplicationStream {
     await attempt;
   }
 }
-
-/** A physical tuple becomes the row the matcher's predicates are written against, or nothing. */
-function toRow(
-  relation: PgRelation,
-  physical: PhysicalRow | null,
-  image: 'before' | 'after',
-): Row | null {
-  if (physical === null) return null;
-  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.
-  const id = row['id'];
-  if (typeof id === 'number' && Number.isSafeInteger(id)) row['id'] = String(id);
-  if (isRow(row)) return row;
-  throw new ReplicationProtocolError({
-    stage: 'stream',
-    detail: `table "${relation.name}" replicated a row with no text id column`,
-    fix: `give ${relation.name} an id column, or drop it from the publication and the entity list`,
-  });
-}
-
-/** The tenant, hoisted out of the row so fanout filters without parsing it. */
-const tenantOf = (row: Row | null): string | null => {
-  const orgId = row?.['orgId'];
-  return typeof orgId === 'string' ? orgId : null;
-};

package/src/pg-socket.ts

@@ -52,6 +52,23 @@ export interface PgTarget {
   readonly rootCert?: string | undefined;
 }
 
+/**
+ * One URL part, percent-decoded. `decodeURIComponent` throws a bare `URIError` on a stray `%`
+ * (`50%off`), so a password pasted unencoded failed the replicator with no code and no fix.
+ * Refused under the part's NAME, never its value: that is the database credential.
+ */
+function decodeUrlPart(raw: string, part: 'user' | 'password' | 'database'): string {
+  try {
+    return decodeURIComponent(raw);
+  } catch {
+    throw new ReplicationFailedError({
+      stage: 'connect',
+      detail: `DATABASE_URL has a malformed percent-escape in its ${part}`,
+      fix: `bun -e 'console.log(encodeURIComponent(process.argv[1]))' '<the raw value>'   # then put the result in the ${part} of DATABASE_URL`,
+    });
+  }
+}
+
 /** `postgres://user:pass@host:5432/db?sslmode=require`. The one place a connection URL is read. */
 export function parsePgUrl(url: string): PgTarget {
   let parsed: URL;
@@ -75,13 +92,13 @@ export function parsePgUrl(url: string): PgTarget {
     });
   }
   const { ssl, rootCert } = parseSsl(parsed.searchParams);
-  const database = decodeURIComponent(parsed.pathname.replace(/^\//, ''));
+  const database = decodeUrlPart(parsed.pathname.replace(/^\//, ''), 'database');
   return {
     host: parsed.hostname,
     port: parsed.port === '' ? 5432 : Number.parseInt(parsed.port, 10),
     database: database === '' ? 'postgres' : database,
-    user: decodeURIComponent(parsed.username) || 'postgres',
-    password: parsed.password === '' ? undefined : decodeURIComponent(parsed.password),
+    user: decodeUrlPart(parsed.username, 'user') || 'postgres',
+    password: parsed.password === '' ? undefined : decodeUrlPart(parsed.password, 'password'),
     ssl,
     rootCert,
   };
@@ -189,8 +206,8 @@ export async function pgStreamOver(runtime: BunConnect, target: PgTarget): Promi
   const connectFailure = (error: Error): ReplicationFailedError =>
     new ReplicationFailedError({
       stage: 'connect',
-      detail: error.message,
-      fix: `open the route to ${target.host}:${target.port}, then: x doctor db`,
+      detail: `${error.message} — no route to ${target.host}:${target.port} from this process`,
+      fix: 'x doctor --json',
     });
 
   const handlers: SocketHandlers = {
@@ -229,8 +246,10 @@ export async function pgStreamOver(runtime: BunConnect, target: PgTarget): Promi
       if (written < 0) {
         throw new ReplicationFailedError({
           stage: 'write',
-          detail: `the socket refused a ${rest.length}-byte write`,
-          fix: 'the replicator reconnects on its own; confirm the host is up with: x doctor db',
+          detail:
+            `the socket refused a ${rest.length}-byte write — the replicator reconnects on its ` +
+            'own once the host is back',
+          fix: 'x doctor --json',
         });
       }
       if (written > 0) rest = rest.subarray(written);

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-values.ts

@@ -33,13 +33,20 @@ 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.
+ * Postgres writes a space between the date and the clock, an offset that may be `+00`, `+0530`,
+ * `+05:30` or — for an instant before its zone adopted standard time, a zone's LMT — `-04:56:02`,
+ * 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.
+ *
+ * Seconds only ever follow a colon-separated minute (`EncodeTimezone` in postgres' `datetime.c`),
+ * so `-0456:02` is not a spelling this matches.
  */
 const TIMESTAMP =
-  /^(\d{4,6})-(\d{2})-(\d{2})[ T](\d{2}):(\d{2}):(\d{2})(\.\d+)?(Z|[+-]\d{2}(?::?\d{2})?)?$/;
+  /^(\d{4,6})-(\d{2})-(\d{2})[ T](\d{2}):(\d{2}):(\d{2})(\.\d+)?(Z|[+-]\d{2}(?:\d{2}|:\d{2}(?::\d{2})?)?)?$/;
+
+/** `±HH`, `±HHMM`, `±HH:MM`, `±HH:MM:SS` — the zone group of `TIMESTAMP`, taken apart. */
+const OFFSET = /^([+-])(\d{2}):?(\d{2})?:?(\d{2})?$/;
 
 /**
  * `undefined` for a text this decoder does not describe — `infinity`, a BC date, a non-ISO
@@ -61,18 +68,26 @@ function toInstant(text: string): Date | undefined {
   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)}`,
-  );
+  const offset = offsetMillis(zone);
+  if (offset === undefined) return undefined;
+  // Read the wall clock as UTC, then move it by the offset: `Date` has no spelling for a seconds
+  // offset, so handing it the zone would leave an LMT instant as text while the driver, which
+  // reads the binary form, hands the repository its `Date`.
+  const wall = Date.parse(`${year}-${month}-${day}T${hour}:${minute}:${second}.${millis}Z`);
+  if (Number.isNaN(wall)) return undefined;
+  const parsed = new Date(wall - offset);
   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;
+/** East of UTC is positive. `undefined` for a minute or second past 59 — not an offset at all. */
+function offsetMillis(zone: string | undefined): number | undefined {
+  if (zone === undefined || zone === 'Z') return 0;
+  const parts = OFFSET.exec(zone);
+  if (parts === null) return undefined;
+  const [, sign, hours, minutes = '00', seconds = '00'] = parts;
+  if (Number(minutes) > 59 || Number(seconds) > 59) return undefined;
+  const magnitude = (Number(hours) * 3600 + Number(minutes) * 60 + Number(seconds)) * 1000;
+  return sign === '-' ? -magnitude : magnitude;
 }
 
 const HEX = /^[0-9a-fA-F]*$/;

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/policy-gate.ts

@@ -1,6 +1,6 @@
-// The single seam between realtime and authz. It goes through `@ultimat3/query`'s `guard`, which
-// is itself the only point of contact with `@ultimat3/policy` — one authz system, never two, and
-// realtime does not get its own opinion about what a decision means.
+// The single seam between realtime and authz. It goes through `@ultimat3/query`'s `guardQuery`,
+// which is itself the only point of contact with `@ultimat3/policy` — one authz system, never two,
+// and realtime does not get its own opinion about what a decision means.
 //
 // The row gate turns a denial into "not visible" instead of an error: a row that fails an actor's
 // policy is dropped, never sent. That is the rule from the live-query pipeline, implemented once.
@@ -8,7 +8,7 @@
 // database is down" are different facts and one of them has to page someone.
 
 import type { Actor, Ctx } from '@ultimat3/core';
-import { guard, QueryDeniedError, type QueryPolicy, type QuerySubject } from '@ultimat3/query';
+import { guardQuery, QueryDeniedError, type QueryPolicy, type QuerySubject } from '@ultimat3/query';
 import type { JsonValue, Row } from './json';
 
 export interface GateOptions {
@@ -25,7 +25,7 @@ export function authorizeWithPolicy(
   return async (args) => {
     // No row exists yet at subscribe time; `null` says so rather than leaving the predicate
     // to infer it from an absent field.
-    guard(policy, subjectOf(options, args.actor, args.input, null), 'live');
+    guardQuery(policy, subjectOf(options, args.actor, args.input, null), 'live');
   };
 }
 
@@ -40,10 +40,10 @@ export function visibleWithPolicy<R extends Row = Row>(
 ): (args: { actor: Actor | null; row: R; input: JsonValue }) => Promise<boolean> {
   return async (args) => {
     try {
-      guard(policy, subjectOf(options, args.actor, args.input, args.row), 'live');
+      guardQuery(policy, subjectOf(options, args.actor, args.input, args.row), 'live');
       return true;
     } catch (error) {
-      // `guard` throws `QueryDeniedError` for a decision and for nothing else, so that class is
+      // `guardQuery` throws `QueryDeniedError` for a decision and for nothing else, so that class is
       // the whole of "not visible". A rule that reached for a row and timed out throws something
       // else, and answering `false` to it would report an outage as a permission change: the rows
       // leave the subscriber's screen, `live.rows_denied` counts the drop, and no error reaches

package/src/presence.ts

@@ -6,7 +6,7 @@
 // On the wire it is not a frame kind: a roster change is an `events` frame on the channel the member
 // joined (`channel-presence.ts` is the payload), so only a channel declared `events: true` has one.
 
-import { type Clock, finiteOption, systemClock, uuid } from '@ultimat3/core';
+import { type Clock, finiteOption, systemClock, uuidV7 } from '@ultimat3/core';
 import type { ChannelHub, Topic } from './channel';
 import { presenceEvent } from './channel-presence';
 import type { ChannelEventsFrame } from './channel-wire';
@@ -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;
@@ -75,7 +86,7 @@ export class PresenceRegistry {
       1,
       finiteOption('presence', 'maxMembers', options.maxMembers ?? DEFAULT_MAX_PRESENCE_MEMBERS),
     );
-    this.#nodeId = options.nodeId ?? uuid();
+    this.#nodeId = options.nodeId ?? uuidV7();
   }
 
   get ttlMs(): number {
@@ -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);