@ultimat3/realtime 22.15.0 → 24.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/realtime",
-  "version": "22.15.0",
+  "version": "24.0.0",
   "description": "Three-tier realtime: channels, live queries, local-first sync — one protocol, one mutator shape",
   "license": "MIT",
   "type": "module",
@@ -38,9 +38,9 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/core": "22.15.0",
-    "@ultimat3/entity": "22.15.0",
-    "@ultimat3/query": "22.15.0",
+    "@ultimat3/core": "24.0.0",
+    "@ultimat3/entity": "24.0.0",
+    "@ultimat3/query": "24.0.0",
     "nats": "2.29.3"
   }
 }

package/src/advisory-lock.ts

@@ -0,0 +1,57 @@
+// Single responsibility: the mutual-exclusion contract behind "exactly one replicator per database",
+// and its single-process implementation. The Postgres one is `pg-advisory-lock.ts`.
+
+/** Session-scoped mutual exclusion. Postgres-backed in production, in-memory for `x dev`. */
+export interface AdvisoryLock {
+  readonly key: string;
+  /** `false` means another process holds it — never block, never steal. */
+  tryAcquire(): Promise<boolean>;
+  release(): Promise<void>;
+  /**
+   * Let go WITHOUT asking: drop the session, synchronously, and wait for nothing. Closing the
+   * session releases the lock, so this is the release for a session that may be dead — an unlock
+   * statement on one is a wait nothing ends. Never calls `onLost`. A no-op when nothing is held.
+   */
+  abandon(): void;
+  /**
+   * Told when a lock this object HELD is gone without `release()` — its session died. Never for a
+   * release, never for a `tryAcquire` that answered `false`. Returns the unsubscribe. The holder
+   * must stop doing what the lock allowed: the database will give it to the next process that asks.
+   */
+  onLost(listener: (reason: string) => void): () => void;
+}
+
+/** Single-process default: correct for `x dev` and tests, useless across containers (by design). */
+export class InMemoryAdvisoryLock implements AdvisoryLock {
+  static readonly #held = new Set<string>();
+  readonly key: string;
+  #mine = false;
+
+  constructor(key: string) {
+    this.key = key;
+  }
+
+  async tryAcquire(): Promise<boolean> {
+    if (InMemoryAdvisoryLock.#held.has(this.key)) return false;
+    InMemoryAdvisoryLock.#held.add(this.key);
+    this.#mine = true;
+    return true;
+  }
+
+  async release(): Promise<void> {
+    if (!this.#mine) return;
+    InMemoryAdvisoryLock.#held.delete(this.key);
+    this.#mine = false;
+  }
+
+  abandon(): void {
+    if (!this.#mine) return;
+    InMemoryAdvisoryLock.#held.delete(this.key);
+    this.#mine = false;
+  }
+
+  /** A set in this process's own heap has no session to lose: the listener is never called. */
+  onLost(): () => void {
+    return () => undefined;
+  }
+}

package/src/boot.ts

@@ -15,9 +15,8 @@ import type { RecordStore } from './record-store';
  * The types the document marks persisted, read back off disk, then the page's outbox opened. None
  * marked is no record disk.
  */
-async function restoreFromDisk(store: RecordStore, principal: Principal): Promise<void> {
+async function restoreFromDisk(store: RecordStore, principal: () => Principal): Promise<void> {
   const types = persistedTypes();
-  const keep = scopeKey(principal);
   let persister: RecordPersister | undefined;
   try {
     // A sign-out by full navigation (a form post and a redirect) never calls `rescope()`, so the
@@ -26,7 +25,12 @@ async function restoreFromDisk(store: RecordStore, principal: Principal): Promis
     // restored. An unscoped page (rendered for nobody) wipes nothing — it knows no principal.
     // Trade-off: two principals in two tabs of one browser — the newer boot wipes the other's
     // disk; that tab keeps its records in memory and re-persists them on its next write.
-    if (keep !== undefined) await (await pageLocalStore()).wipeOthers(keep);
+    //
+    // WHOSE disk is kept is decided AT the wipe, after the store has opened: decided before that
+    // await, a `rescope()` during it kept the principal that left and wiped the one that arrived.
+    const disk = await pageLocalStore();
+    const keep = scopeKey(principal());
+    if (keep !== undefined) await disk.wipeOthers(keep);
     if (types.size > 0) {
       persister = recordPersister({ store, local: await pageLocalStore(), types });
       await persister.restore();
@@ -50,16 +54,17 @@ type Principal = ClientScope['principal'];
  * scope is the page's own — a parameter only so a test can boot an unscoped page (an OBJECT, so an
  * explicit `undefined` principal is not mistaken for "use the default").
  */
-export function bootPage(
-  scope: { readonly principal: Principal } = pageClient().scope,
-): Promise<void> {
+export function bootPage(scope?: { readonly principal: Principal }): Promise<void> {
   const host = globalThis as BootHost;
   const started = host[BOOT_KEY];
   const waiting = host[BOOT_RELEASE_KEY];
   // Already booting — unless what sits there is an island's placeholder, which this boot claims.
   if (started !== undefined && waiting === undefined) return started;
   Reflect.deleteProperty(host, BOOT_RELEASE_KEY);
-  const booted = restoreFromDisk(pageRealtime().store, scope.principal);
+  // Asked each time, never captured: the page's principal is whatever `rescope()` last said.
+  const principal = (): Principal =>
+    scope === undefined ? pageClient().scope.principal : scope.principal;
+  const booted = restoreFromDisk(pageRealtime().store, principal);
   if (started !== undefined && waiting !== undefined) {
     void booted.then(waiting);
     return started;

package/src/change-buffer.ts

@@ -36,11 +36,41 @@ export interface ChangeBufferOptions {
 export const DEFAULT_MAX_BUFFER_BYTES = 64 * 1024 * 1024;
 export const DEFAULT_MAX_BUFFER_BYTES_PER_QUERY = 1024 * 1024;
 
+/**
+ * THE FLOOR RULE, stated once. A ring answers a resume only for a cursor it can PROVE it holds
+ * every later change for; anything else is `null`, and the caller takes one bounded snapshot.
+ *
+ * | The floor is set by | to | a cursor AT the floor |
+ * |---|---|---|
+ * | the ring's first patch (no read floored it) | that patch's lsn | resumes — it has that patch |
+ * | an eviction | the evicted patch's lsn | resumes — everything after it is retained |
+ * | a window's FIRST read, on a node that holds a position | the read's lsn | resumes — the cursor may be that read's own |
+ * | a window's FIRST read with NO position behind it (`sole`) | the read's own mark | resumes, and it is the ONLY cursor below the first patch that does |
+ * | a FORCED re-read (the window missed a change), a truncate, a partial row | the read's lsn, EXCLUSIVE | is refused |
+ *
+ * Why `sole`: a node that has received no change holds no position, so its read is marked with
+ * the node's own origin (`LiveQueryRegistry`), which sorts below every real lsn. A plain floor
+ * there admits every foreign cursor — each is "above" it — for a history this node never held. So
+ * the ring answers that one mark, and otherwise only a cursor at or after its FIRST patch.
+ *
+ * Why the last row is exclusive: a re-read's lsn is the node's last SEEN position, which does not
+ * move for the changes it missed — so "the window at L before the gap" and "the window re-read at
+ * L with the missed rows in it" carry the same cursor, and only refusing L tells them apart.
+ *
+ * What never moves the floor: a read served out of a window that is already filled. The retained
+ * patches are still its true history, and flooring it evicts every other subscriber's resume.
+ */
 interface Ring {
   patches: RowPatch[];
   bytes: number;
-  /** Highest lsn already dropped. A cursor at or after this is still resumable. */
-  evictedThrough: string | null;
+  /** The lsn this ring is complete from. Set at birth and only ever raised. */
+  evictedThrough: string;
+  /** Whether a cursor exactly AT the floor is refused — see the rule above. */
+  exclusive: boolean;
+  /** The one cursor a position-less birth vouches for, until an eviction or a re-read ends it. */
+  sole: string | null;
+  /** The first patch appended after a `sole` birth: where foreign cursors become answerable. */
+  anchor: string | null;
 }
 
 const encoder = new TextEncoder();
@@ -52,12 +82,6 @@ function patchBytes(patch: RowPatch): number {
 
 export class RingChangeBuffer implements ResumeSource {
   readonly #rings = new Map<string, Ring>();
-  /**
-   * Query hashes whose ring was dropped, so the ring the NEXT change builds knows it does not
-   * carry the history before it. A `Set` of ids and not a `Map` of lsns: what the next ring is
-   * complete from is its own first patch, which only that patch can name.
-   */
-  readonly #forgotten = new Set<string>();
   readonly #capacity: number;
   readonly #maxQueries: number;
   readonly #maxBytesPerQuery: number;
@@ -86,17 +110,20 @@ export class RingChangeBuffer implements ResumeSource {
 
   append(qid: string, patch: RowPatch): void {
     const existing = this.#rings.get(qid);
-    // A ring RE-CREATED after a `forget` is complete only from this patch onward: everything before
-    // it went with the ring, and — on the `unsubscribe` path — the entry went too, so the changes
-    // in between were never appended at all. `evictedThrough` at its own first lsn is what makes
-    // `since` refuse a cursor from before that, which it could not do while the field came back
-    // `null` and every earlier cursor read as in-window on a ring that had held none of it.
-    const reborn = this.#forgotten.delete(qid);
+    // A ring is complete only from where it was born. Born HERE, from a patch, that is the patch
+    // itself: this node held no entry for whatever came before, so nothing before it was ever
+    // appended. It used to be born with no floor at all, and a cursor minted on another node —
+    // the rolling-deploy shape — read as in-window on a ring that had held none of its history.
+    // `floorAt` is the earlier, cheaper birth: the lsn the window was read at.
     const ring: Ring = existing ?? {
       patches: [],
       bytes: 0,
-      evictedThrough: reborn ? patch.lsn : null,
+      evictedThrough: patch.lsn,
+      exclusive: false,
+      sole: null,
+      anchor: null,
     };
+    if (ring.sole !== null && ring.anchor === null) ring.anchor = patch.lsn;
     ring.patches.push(patch);
     const cost = patchBytes(patch);
     ring.bytes += cost;
@@ -106,8 +133,48 @@ export class RingChangeBuffer implements ResumeSource {
     while (ring.patches.length > this.#capacity || ring.bytes > this.#maxBytesPerQuery) {
       if (!this.#shift(ring)) break;
     }
-    // Re-insert to move this qid to the tail of the LRU order.
-    if (existing) this.#rings.delete(qid);
+    this.#touch(qid, ring);
+  }
+
+  /**
+   * The window behind `qid` was read at `lsn`: the ring is complete from there, and from nowhere
+   * earlier. The caller decides WHEN (a read that landed, never one served from a filled window)
+   * and whether the floor is `exclusive` (a forced re-read) — the rule is on `Ring`.
+   *
+   * Only ever raises the floor, or tightens it at the same lsn. `''` is no position and says nothing.
+   */
+  floorAt(
+    qid: string,
+    lsn: string,
+    options: { readonly exclusive?: boolean; readonly sole?: boolean } = {},
+  ): void {
+    if (lsn === '') return;
+    const exclusive = options.exclusive === true;
+    const existing = this.#rings.get(qid);
+    const ring: Ring = existing ?? {
+      patches: [],
+      bytes: 0,
+      evictedThrough: lsn,
+      exclusive,
+      sole: options.sole === true ? lsn : null,
+      anchor: null,
+    };
+    if (lsn > ring.evictedThrough || (lsn === ring.evictedThrough && exclusive)) {
+      // Superseded, not evicted: what the read replaced is history with a gap in it.
+      for (let first = ring.patches[0]; first !== undefined && first.lsn <= lsn; ) {
+        this.#shift(ring);
+        first = ring.patches[0];
+      }
+      ring.evictedThrough = lsn;
+      ring.exclusive = exclusive;
+      ring.sole = null;
+    }
+    this.#touch(qid, ring);
+  }
+
+  /** Move `qid` to the tail of the LRU order, then hold both node-wide ceilings. */
+  #touch(qid: string, ring: Ring): void {
+    this.#rings.delete(qid);
     this.#rings.set(qid, ring);
     while (this.#rings.size > this.#maxQueries || this.#bytes > this.#maxBytes) {
       const oldest = this.#rings.keys().next();
@@ -126,13 +193,19 @@ export class RingChangeBuffer implements ResumeSource {
     ring.bytes -= cost;
     this.#bytes -= cost;
     ring.evictedThrough = dropped.lsn;
+    ring.exclusive = false;
+    ring.sole = null;
     return true;
   }
 
   since(qid: string, lsn: string): RowPatch[] | null {
     const ring = this.#rings.get(qid);
     if (!ring) return null;
-    if (ring.evictedThrough !== null && lsn < ring.evictedThrough) return null;
+    if (lsn < ring.evictedThrough) return null;
+    if (ring.exclusive && lsn === ring.evictedThrough) return null;
+    if (ring.sole !== null && lsn !== ring.sole && (ring.anchor === null || lsn < ring.anchor)) {
+      return null;
+    }
     return ring.patches.filter((patch) => patch.lsn > lsn);
   }
 
@@ -149,29 +222,11 @@ export class RingChangeBuffer implements ResumeSource {
    */
   forget(qid: string): void {
     const ring = this.#rings.get(qid);
-    if (ring !== undefined) {
-      this.#bytes -= ring.bytes;
-      this.#rings.delete(qid);
-    }
-    // The qid is remembered, the patches are not — and unconditionally, because the ring being
-    // absent is not the history being intact. Both callers lose history here and neither could say
-    // so: `LiveQueryRegistry.unsubscribe` drops the ENTRY, so every change until the next
-    // subscriber is never appended at all, and the LRU fires on a query that still has LIVE
-    // subscribers. Either way the next `append` was building a ring that reported itself complete
-    // from the beginning of time, so a client reconnecting inside `maxLagMs` folded a partial patch
-    // list onto a stale window with `shouldResnapshot` answering `in-window` and nothing marked
-    // desynced — permanently divergent on a healthy socket. What the tombstone costs in exchange is
-    // a resume that could have been a delta taking the snapshot path; that is one bounded read, and
-    // it is the direction this package errs in everywhere else.
-    this.#forgotten.add(qid);
-    // Bounded like everything else here: insertion-ordered, so the oldest tombstone goes first.
-    // Losing one costs a resume that could have been a delta; keeping them unbounded costs memory
-    // a client-chosen input mints at will.
-    while (this.#forgotten.size > this.#maxQueries) {
-      const oldest = this.#forgotten.values().next();
-      if (oldest.done === true) break;
-      this.#forgotten.delete(oldest.value);
-    }
+    if (ring === undefined) return;
+    this.#bytes -= ring.bytes;
+    this.#rings.delete(qid);
+    // Nothing is remembered about it: the next ring for this qid is born with its own floor, so
+    // it cannot claim the history that went with this one.
   }
 
   get queryCount(): number {

package/src/changefeed-env.ts

@@ -5,14 +5,14 @@
 
 import type { Clock } from '@ultimat3/core';
 import { ConfigInvalidError } from '@ultimat3/core';
+import type { AdvisoryLock } from './advisory-lock';
+import { InMemoryAdvisoryLock } from './advisory-lock';
 import type { ChangeFeed } from './changefeed';
 import { InMemoryChangeFeed, PgLogicalReplicationFeed } from './changefeed';
 import { PgAdvisoryLock } from './pg-advisory-lock';
 import type { PgTarget } from './pg-socket';
 import { parsePgUrl } from './pg-socket';
 import type { PgStream } from './pg-wire';
-import type { AdvisoryLock } from './replicator';
-import { InMemoryAdvisoryLock } from './replicator';
 import type { Rng } from './thundering-herd';
 
 /** The keys read here, and nothing else. Named once so docs and tests cannot drift from the code. */

package/src/changefeed.ts

@@ -39,18 +39,38 @@ export interface ChangeEvent<R extends Row = Row> {
    * channel stamps it on the `records` frame so the writing page recognises its own echo.
    */
   readonly write?: string;
+  /**
+   * Row properties `after` does NOT carry because Postgres did not log them: an UPDATE that left
+   * an out-of-line (TOAST) value untouched sends no bytes for it, and under any replica identity
+   * but FULL there is no old image to read it from. Absent when `after` is the whole row. A
+   * consumer must not adopt `after` as the row while this is set — it re-reads instead.
+   */
+  readonly omitted?: readonly string[];
 }
 
 export interface ChangeFeedStartOptions {
   /** Resume position. Omitted means "from now". */
   readonly from?: string;
   readonly onChange: (event: ChangeEvent) => void | Promise<void>;
+  /**
+   * The feed stopped delivering ON ITS OWN — the walsender ended the copy, a decode failed, the
+   * handler rejected — and will not resume until `start()` is called again. Never called for a
+   * `stop()`. This is the only way out a pump has: nothing awaits its read loop, so a death that
+   * was only recorded was a death nobody saw.
+   */
+  readonly onEnd?: (reason: string) => void;
 }
 
 export interface ChangeFeed {
   readonly source: string;
   start(options: ChangeFeedStartOptions): Promise<void>;
   stop(): Promise<void>;
+  /**
+   * Go silent NOW, without asking: synchronous, nothing written, nothing awaited. For a stream
+   * that may already be dead — `stop()` says goodbye first, and a goodbye to a black-holed socket
+   * is never answered. After it returns no further change is delivered and `onEnd` is not called.
+   */
+  abandon(): void;
   /** Highest lsn delivered to the handler; the replicator persists this to survive a restart. */
   lastLsn(): string | null;
 }
@@ -103,6 +123,10 @@ export class InMemoryChangeFeed implements ChangeFeed {
     await this.#tail;
   }
 
+  abandon(): void {
+    this.#handler = null;
+  }
+
   lastLsn(): string | null {
     return this.#lastLsn;
   }
@@ -175,6 +199,12 @@ export interface PgLogicalReplicationOptions {
   readonly rng?: Rng | undefined;
   /** The byte pipe, injected. Defaults to `Bun.connect`; a test drives a scripted server instead. */
   readonly stream?: ((target: PgTarget) => Promise<PgStream>) | undefined;
+  /**
+   * Tables whose DELETE must carry the whole old row — a channel with params routes a removal by
+   * columns only `REPLICA IDENTITY FULL` logs. Preflight warns for each that is not FULL. Defaults
+   * to what the declared channels need (`pg-identity-tables.ts`).
+   */
+  readonly fullIdentityTables?: readonly string[] | undefined;
 }
 
 /**
@@ -199,13 +229,21 @@ export class PgLogicalReplicationFeed implements ChangeFeed {
   }
 
   async start(options: ChangeFeedStartOptions): Promise<void> {
-    await this.#stream.start({ from: options.from, onChange: options.onChange });
+    await this.#stream.start({
+      from: options.from,
+      onChange: options.onChange,
+      onEnd: options.onEnd,
+    });
   }
 
   async stop(): Promise<void> {
     await this.#stream.stop();
   }
 
+  abandon(): void {
+    this.#stream.abandon();
+  }
+
   lastLsn(): string | null {
     return this.#stream.lastLsn();
   }

package/src/channel-authz.ts

@@ -5,11 +5,17 @@
 import { type Actor, type Ctx, createContext, runWithContext } from '@ultimat3/core';
 import { guard, QueryDeniedError } from '@ultimat3/query';
 import type { Channel } from './channel-decl';
-import { TopicForbiddenError } from './errors';
+import { isTenancyDenial, TopicForbiddenError } from './errors';
 
 /**
  * A denial is `X_TOPIC_FORBIDDEN`. A loader or a rule that RAISED is not a denial and leaves as it
- * came, so the caller can tell an outage from a decision — `onActorChange` keeps the topic on one.
+ * came, so the caller can tell an outage from a decision — `onActorChange` suspends the topic on one.
+ *
+ * Two answers are denials before any rule runs, because neither is an outage:
+ * - **nobody, on a channel that decides on a row.** A loader runs AS the subscriber; with no actor
+ *   it would run as the node, and a row is not something nobody is entitled to.
+ * - **a loader the tenant guard refused** (`TENANCY_DENIAL_CODES`): the actor has no org, or names
+ *   another one. That is the verdict about a removed member, not a store that could not answer.
  */
 export async function authorizeChannel(
   channel: Channel,
@@ -18,17 +24,42 @@ export async function authorizeChannel(
   topic: string,
   params: Readonly<Record<string, string>>,
 ): Promise<void> {
-  // The loader and the rule run AS the subscriber, never as the node. Under the node's context — no
-  // actor, no tenant — a repository read inside the loader was scoped by nothing but what the
-  // loader happened to name, and `@ultimat3/entity`'s tenancy seam had no actor to hold it to.
-  // Services are rebuilt for this actor by `createContext`, the rule `withChildContext` follows.
-  const scoped = actor === null ? ctx : subscriberContext(ctx, actor);
-  const row =
-    channel.row === undefined
-      ? null
-      : await runWithContext(scoped, async () => await channel.row?.({ params, ctx: scoped }));
+  const loader = channel.row;
+  if (loader === undefined) return decide(channel, ctx, actor, topic, params, null);
+  if (actor === null) {
+    throw new TopicForbiddenError({
+      topic,
+      actorId: null,
+      reason: `channel "${channel.name}" decides on a row, and an anonymous socket has no actor to load one as`,
+    });
+  }
+  // The loader and the rule run AS the subscriber, never as the node. Services are rebuilt for
+  // this actor by `createContext`, the rule `withChildContext` follows.
+  const scoped = subscriberContext(ctx, actor);
+  let row: unknown;
+  try {
+    row = await runWithContext(scoped, async () => await loader({ params, ctx: scoped }));
+  } catch (error) {
+    if (!isTenancyDenial(error)) throw error;
+    throw new TopicForbiddenError({
+      topic,
+      actorId: actor.id,
+      reason: `channel "${channel.name}" reads a row outside this actor's tenant`,
+    });
+  }
+  decide(channel, scoped, actor, topic, params, row);
+}
+
+function decide(
+  channel: Channel,
+  ctx: Ctx,
+  actor: Actor | null,
+  topic: string,
+  params: Readonly<Record<string, string>>,
+  row: unknown,
+): void {
   try {
-    guard(channel.policy, { actor, input: params, row, ctx: scoped, query: channel.name }, 'live');
+    guard(channel.policy, { actor, input: params, row, ctx, query: channel.name }, 'live');
   } catch (error) {
     if (!(error instanceof QueryDeniedError)) throw error;
     throw new TopicForbiddenError({

package/src/channel-latch.ts

@@ -0,0 +1,52 @@
+// The denials one socket has been answered with, latched until its session changes — so a client
+// re-asking in a loop is answered without re-running the policy, and only THAT topic is refused.
+// Bounded: a topic is spelled from client params, so an unbounded latch was one entry per refusal.
+
+import { SubscriptionLimitError } from './errors';
+import type { SyncSocket } from './socket';
+
+export class DenialLatch {
+  /** Weakly keyed, so a socket's latch dies with it and no close path has to remember it. */
+  readonly #bySocket = new WeakMap<SyncSocket, Set<string>>();
+  readonly #max: number;
+  readonly #knob: string;
+
+  constructor(max: number, knob: string) {
+    this.#max = max;
+    this.#knob = knob;
+  }
+
+  has(socket: SyncSocket, name: string): boolean {
+    return this.#bySocket.get(socket)?.has(name) === true;
+  }
+
+  /**
+   * Refused BEFORE a policy runs once the latch is full: a socket that has been denied this many
+   * distinct topics is asking for more than it may hold, and each further ask would otherwise be
+   * either a retained entry or a policy pass the client schedules at will.
+   */
+  assertRoom(socket: SyncSocket): void {
+    if ((this.#bySocket.get(socket)?.size ?? 0) < this.#max) return;
+    throw new SubscriptionLimitError({
+      scope: 'socket',
+      id: socket.id,
+      limit: this.#max,
+      knob: this.#knob,
+    });
+  }
+
+  add(socket: SyncSocket, name: string): void {
+    const latched = this.#bySocket.get(socket) ?? new Set<string>();
+    if (latched.size < this.#max) this.#bySocket.set(socket, latched.add(name));
+  }
+
+  /** A new session re-decides everything. */
+  clear(socket: SyncSocket): void {
+    this.#bySocket.delete(socket);
+  }
+
+  /** Denials held for one socket — what a test bounds. */
+  count(socket: SyncSocket): number {
+    return this.#bySocket.get(socket)?.size ?? 0;
+  }
+}

package/src/channel-logs.ts

@@ -74,6 +74,11 @@ export class ChannelLogs {
     for (const update of updates) {
       const open = this.#byTopic.get(update.topic);
       if (open === undefined) continue;
+      // The change could not carry the whole row (`channel-records.ts`): members re-read it.
+      if (update.gap === true) {
+        frames += this.#reopen(update.topic, open.target);
+        continue;
+      }
       const entry = open.ring.append(update.adopt, update.remove, change.write);
       const frame = renderRecords(update.topic, open.ring.epoch, entry);
       frames += this.#sockets.deliverRecords(update.topic, open.ring.epoch, frame);
@@ -91,13 +96,33 @@ export class ChannelLogs {
     let announced = 0;
     for (const [topic, open] of [...this.#byTopic]) {
       if (!carriesTable(open.target.channel, table)) continue;
-      this.#byTopic.delete(topic);
-      const ring = this.open(topic, open.target);
-      announced += this.#sockets.announceGap(topic, ring.epoch);
+      announced += this.#reopen(topic, open.target);
     }
     return announced;
   }
 
+  /**
+   * This node may have missed a change (the bus dropped, or skipped a sequence). Seq is minted
+   * HERE from the changes this node sees, so the hole is invisible to the ring: the next change
+   * would be appended as the next seq and a `since` replayed across it as complete history. Every
+   * open topic that carries records therefore starts a new epoch and tells its members.
+   */
+  invalidate(): number {
+    let announced = 0;
+    for (const [topic, open] of [...this.#byTopic]) {
+      if (open.target.channel.records.length === 0) continue;
+      announced += this.#reopen(topic, open.target);
+    }
+    return announced;
+  }
+
+  /** A new epoch for one topic — nothing in the old ring may be replayed — and a gap to each member. */
+  #reopen(topic: string, target: ChannelTopic): number {
+    this.#byTopic.delete(topic);
+    const ring = this.open(topic, target);
+    return this.#sockets.announceGap(topic, ring.epoch);
+  }
+
   /**
    * A (re)subscribe `since` a position: every frame after it from the ring, or — when the ring
    * cannot prove it holds them all, or the epoch moved — one `replay-gap`.
@@ -107,6 +132,10 @@ export class ChannelLogs {
    * reached nobody — and nothing the client holds can name it. The seat is the one point after
    * which every commit is a frame, so the re-read is told to start from here. A repeated `add` on
    * a socket already seated (the presence beat), or a channel with no records, is sent nothing.
+   *
+   * A `since` that is already CURRENT is answered too: the frame AT its cursor, carrying nothing.
+   * Sent nothing, the client had no frame to leave `joining` on — a channel that was up to date
+   * read as never joined. The seq is one it already holds, so its cursor does not move.
    */
   resume(socket: SyncSocket, topic: string, since: ChannelSince | undefined, fresh: boolean): void {
     const open = this.#byTopic.get(topic);
@@ -124,7 +153,8 @@ export class ChannelLogs {
       if (!socket.send(frame)) socket.gaps.set(topic, open.ring.epoch);
       return;
     }
-    for (const entry of entries) {
+    const answer = entries.length > 0 ? entries : [{ seq: open.ring.seq, adopt: [], remove: [] }];
+    for (const entry of answer) {
       if (!socket.send(renderRecords(topic, open.ring.epoch, entry))) {
         socket.gaps.set(topic, open.ring.epoch);
         return;