@ultimat3/realtime 23.0.0 → 24.0.0

package/src/pg-preflight.ts

@@ -1,7 +1,7 @@
-// Single responsibility: the four questions asked of a database BEFORE `START_REPLICATION`. Two
-// refuse the boot with the exact statement that fixes them, one — the publication — is answered by
-// ensuring it (`pg-publication.ts`), and the fourth warns, because refusing it would stop every app
-// on the default replica identity from starting.
+// Single responsibility: the questions asked of a database BEFORE `START_REPLICATION`. Two refuse
+// the boot with the exact statement that fixes them, one — the publication — is answered by
+// ensuring it (`pg-publication.ts`), and the replica-identity ones warn, because refusing would
+// stop every app on the default replica identity from starting.
 
 import { logger } from '@ultimat3/core';
 import { ReplicaIdentityError, ReplicationFailedError } from './errors';
@@ -22,6 +22,7 @@ export async function preflight(
   slot: string,
   publication: string,
   entities: ReadonlySet<string>,
+  fullIdentity: ReadonlySet<string> = new Set(),
 ): Promise<void> {
   assertIdentifier('slot', slot);
   assertIdentifier('publication', publication);
@@ -37,6 +38,7 @@ export async function preflight(
   }
   await ensurePublication(connection, publication, entities);
   await warnPartialIdentity(connection, entities);
+  await warnChannelIdentity(connection, entities, fullIdentity);
   const [existing] = await connection.query(
     `SELECT plugin FROM pg_replication_slots WHERE slot_name = '${slot}'`,
   );
@@ -102,3 +104,47 @@ async function warnPartialIdentity(
   // `@ultimat3/http`'s error-map stage follows, so a log index can be alerted on by code.
   logger.warn(warning.code, { cause: warning.cause, fix: warning.fix, tables });
 }
+
+/** The log event a params channel's table without FULL identity is reported under. */
+export const CHANNEL_IDENTITY_EVENT = 'replication.channel_identity_partial';
+
+const CHANNEL_IDENTITY_FIX = 'x db gen "replica identity full"';
+
+/**
+ * The tables a channel with params carries that are not `REPLICA IDENTITY FULL`. Their DELETE logs
+ * the key alone, the channel reads its topic off columns the key does not include, and the removal
+ * is sent to nobody: members keep a record that no longer exists, and nothing else says so.
+ *
+ * WARNED, like its neighbour, and for the same reason. Only names that are also in the entity list
+ * are asked about — that list has been through `assertIdentifier`, which is what makes the
+ * interpolation safe; a declared table the feed does not decode is not this stream's to judge.
+ */
+async function warnChannelIdentity(
+  connection: PgConnection,
+  entities: ReadonlySet<string>,
+  fullIdentity: ReadonlySet<string>,
+): Promise<void> {
+  const asked = [...fullIdentity].filter((name) => entities.has(name)).sort();
+  if (asked.length === 0) return;
+  const names = asked.map((name) => `'${name}'`).join(', ');
+  const rows = await connection.query(
+    `SELECT c.relname FROM pg_class c WHERE c.relkind = 'r' AND c.relname IN (${names}) ` +
+      `AND c.relreplident <> 'f'`,
+  );
+  const tables = [
+    ...new Set(
+      rows
+        .map((row) => row[0])
+        .filter((name): name is string => typeof name === 'string' && asked.includes(name)),
+    ),
+  ].sort();
+  if (tables.length === 0) return;
+  logger.warn(CHANNEL_IDENTITY_EVENT, {
+    cause:
+      `${tables.join(', ')} carry a channel declared with params but are not REPLICA IDENTITY ` +
+      'FULL, so a DELETE names no topic and its members keep the deleted record',
+    // `x db gen` reads the same declarations this warning does and writes the ALTER per table.
+    fix: CHANNEL_IDENTITY_FIX,
+    tables,
+  });
+}

package/src/pg-replication-row.ts

@@ -0,0 +1,82 @@
+// Single responsibility: the two row images of one replicated change — a physical tuple pair
+// becomes the `before`/`after` the matcher's predicates are written against, plus the properties
+// `after` could not carry. Split out of `pg-replication.ts`, which decides ordering and nothing else.
+
+import { ReplicationProtocolError } from './errors';
+import { isRow, type Row } from './json';
+import { entityRow, omittedProperties } from './pg-entity-row';
+import type { PhysicalRow } from './pg-values';
+import type { PgRelation } from './pgoutput';
+
+export interface ReplicatedImages {
+  readonly before: Row | null;
+  readonly after: Row | null;
+  /** Properties missing from `after` because Postgres logged no value for them. Usually empty. */
+  readonly omitted: readonly string[];
+}
+
+/**
+ * An UPDATE that leaves an out-of-line (TOAST) value untouched logs no bytes for it, so the new
+ * tuple arrives without that column. Published as it stood, the change read as the whole row: the
+ * window adopted it, and every later snapshot served the row with the column gone.
+ *
+ * Under REPLICA IDENTITY FULL the old tuple carries the value and the column did not change, so it
+ * is copied across and nothing is missing. Under any other identity the old tuple is the key alone
+ * — its other columns are NULL placeholders, not values — so the column is NAMED instead, and the
+ * consumer re-reads the row rather than adopting a partial one.
+ */
+export function replicatedImages(
+  relation: PgRelation,
+  oldTuple: PhysicalRow | null,
+  newTuple: PhysicalRow | null,
+  unchanged: readonly string[],
+): ReplicatedImages {
+  const before = toRow(relation, oldTuple, 'before');
+  if (newTuple === null || unchanged.length === 0) {
+    return { before, after: toRow(relation, newTuple, 'after'), omitted: [] };
+  }
+  // Null-prototype, as the decoder built it: a column name is off the wire.
+  const filled: PhysicalRow = Object.assign(Object.create(null) as PhysicalRow, newTuple);
+  let missing = 0;
+  for (const name of unchanged) {
+    if (relation.replicaIdentity === 'f' && oldTuple !== null && Object.hasOwn(oldTuple, name)) {
+      const kept = oldTuple[name];
+      if (kept !== undefined) filled[name] = kept;
+    } else {
+      missing += 1;
+    }
+  }
+  const after = toRow(relation, filled, 'after');
+  return {
+    before,
+    after,
+    omitted: missing === 0 || after === null ? [] : omittedProperties(relation, after),
+  };
+}
+
+/** 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. */
+export const tenantOf = (row: Row | null): string | null => {
+  const orgId = row?.['orgId'];
+  return typeof orgId === 'string' ? orgId : null;
+};

package/src/pg-replication.ts

@@ -6,12 +6,12 @@
 import { type Clock, finiteOption, logger, renderThrowable, systemClock } from '@ultimat3/core';
 import type { ChangeEvent, ChangeOp, PgLogicalReplicationOptions } 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,6 +85,8 @@ 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;
 }
 
 /**
@@ -115,6 +114,7 @@ export class PgReplicationStream {
   #partialBefore = 0;
   #confirmFailures = 0;
   #failure: string | null = null;
+  #onEnd: ((reason: string) => void) | undefined;
 
   constructor(options: PgLogicalReplicationOptions) {
     this.#options = options;
@@ -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,8 +412,7 @@ 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,
       op,
@@ -398,6 +423,7 @@ export class PgReplicationStream {
       orgId: tenantOf(after ?? before),
       at: transaction.commitAt,
       ...(transaction.write === undefined ? {} : { write: transaction.write }),
+      ...(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

@@ -189,8 +189,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 +229,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-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);