@ultimat3/realtime 23.0.0 → 25.0.0

package/src/advisory-lock.ts

@@ -0,0 +1,62 @@
+// 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 MemoryAdvisoryLock implements AdvisoryLock {
+  static readonly #held = new Set<string>();
+  readonly key: string;
+  #mine = false;
+
+  constructor(key: string) {
+    this.key = key;
+  }
+
+  async tryAcquire(): Promise<boolean> {
+    if (MemoryAdvisoryLock.#held.has(this.key)) return false;
+    MemoryAdvisoryLock.#held.add(this.key);
+    this.#mine = true;
+    return true;
+  }
+
+  async release(): Promise<void> {
+    if (!this.#mine) return;
+    MemoryAdvisoryLock.#held.delete(this.key);
+    this.#mine = false;
+  }
+
+  abandon(): void {
+    if (!this.#mine) return;
+    MemoryAdvisoryLock.#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;
+  }
+}
+
+/** The one way to build the in-process lock — the twin of `postgresAdvisoryLock()`; the class is a type in the barrel only (`X_FACTORY_NAME_SPELLING`). */
+export function memoryAdvisoryLock(key: string): MemoryAdvisoryLock {
+  return new MemoryAdvisoryLock(key);
+}

package/src/boot.ts

@@ -1,13 +1,14 @@
-// `@ultimat3/realtime/boot` — the page's boot, ONE classic script per document (plan 101), built
-// and served by the CLI the way the sync worker is. It restores the principal's persisted records
-// and opens the outbox, so a reload replays what the previous load queued even on a page whose
-// islands only read. Here and not in `page-store.ts`, so no island bundle carries it.
+// `@ultimat3/realtime/boot` — the page's boot, ONE classic script per document (plan 101), served
+// by the CLI like the sync worker. It installs the page runtime (store, socket, host, channel book;
+// islands await and read it, never carry it — #505), restores the principal's persisted records
+// and opens the outbox, so a reload replays what the last load queued even if islands only read.
 
 import type { ClientScope } from '@ultimat3/core/page';
 import { pageClient } from '@ultimat3/core/page';
 import { pageLocalStore, scopeKey } from './local-store-idb';
 import { pageOutbox } from './page-outbox';
-import { BOOT_KEY, BOOT_RELEASE_KEY, type BootHost, pageRealtime } from './page-store';
+import { installPageRuntime } from './page-runtime';
+import { BOOT_KEY, BOOT_RELEASE_KEY, type BootHost } from './page-store';
 import { persistedTypes, type RecordPersister, recordPersister } from './record-persister';
 import type { RecordStore } from './record-store';
 
@@ -15,9 +16,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 +26,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();
@@ -46,20 +51,25 @@ async function restoreFromDisk(store: RecordStore, principal: Principal): Promis
 type Principal = ClientScope['principal'];
 
 /**
- * Once per page, whoever calls first; the promise is what `pageRealtime().booted` answers. The
- * 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").
+ * Once per page, whoever calls first; the promise is what `pageRealtime().booted` answers — the
+ * one moment an island may treat the page's records as restored (#506 holds first paint on it).
+ * The runtime is installed synchronously, before the first await, so an island waiting on this
+ * script (`awaitPageRuntime`) is released by the script's `load` with the store already there.
+ * The 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);
+  const page = installPageRuntime();
+  // 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(page.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

@@ -1,18 +1,18 @@
 // Single responsibility: environment → change feed. The one place that decides which `ChangeFeed`
 // a boot installs, so `x dev`, a replicator container and any custom host resolve it identically.
-// `PgLogicalReplicationFeed` is useless until something constructs it from a connection string;
+// `PostgresChangeFeed` is useless until something constructs it from a connection string;
 // this is that something, keyed on env rather than a config field so one image deploys everywhere.
 
 import type { Clock } from '@ultimat3/core';
 import { ConfigInvalidError } from '@ultimat3/core';
+import type { AdvisoryLock } from './advisory-lock';
+import { memoryAdvisoryLock } from './advisory-lock';
 import type { ChangeFeed } from './changefeed';
-import { InMemoryChangeFeed, PgLogicalReplicationFeed } from './changefeed';
-import { PgAdvisoryLock } from './pg-advisory-lock';
+import { memoryChangeFeed, postgresChangeFeed } from './changefeed';
+import { postgresAdvisoryLock } 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. */
@@ -105,12 +105,12 @@ export function selectChangeFeed(
 
   if (url === undefined) {
     return {
-      feed: new InMemoryChangeFeed(options.retain === undefined ? {} : { retain: options.retain }),
+      feed: memoryChangeFeed(options.retain === undefined ? {} : { retain: options.retain }),
       mode: 'embedded',
       detail: 'in-process change feed — set DATABASE_URL to decode a real WAL',
       slot: null,
       // Single-process mutual exclusion, which is all one process needs and all it can enforce.
-      lock: new InMemoryAdvisoryLock(replicatorLockKey(DEFAULT_REPLICATION_SLOT)),
+      lock: memoryAdvisoryLock(replicatorLockKey(DEFAULT_REPLICATION_SLOT)),
     };
   }
 
@@ -122,7 +122,7 @@ export function selectChangeFeed(
   return {
     // Slot and publication are validated inside the feed, against the same identifier rule the
     // replication command needs — a second copy of that regex here is a second thing to keep true.
-    feed: new PgLogicalReplicationFeed({
+    feed: postgresChangeFeed({
       url,
       slot,
       publication: nonEmpty(env['REPLICATION_PUBLICATION']) ?? DEFAULT_REPLICATION_PUBLICATION,
@@ -136,7 +136,7 @@ export function selectChangeFeed(
     slot,
     // Taken on the same database the feed reads, so the lock and the slot cannot end up in
     // different places — which is the only way "exactly one replicator" could quietly become two.
-    lock: new PgAdvisoryLock({
+    lock: postgresAdvisoryLock({
       url,
       key: replicatorLockKey(slot),
       stream: options.stream,

package/src/changefeed.ts

@@ -20,8 +20,13 @@ import type { Rng } from './thundering-herd';
 export type ChangeOp = 'insert' | 'update' | 'delete' | 'truncate';
 
 export interface ChangeEvent<R extends Row = Row> {
-  /** Entity name, not table name — the matcher's dependency sets are declared in entity terms. */
-  readonly entity: string;
+  /**
+   * The RELATION (table) name, on every producer: the WAL decoder reads it off the Relation
+   * message, the in-process bridge maps the row observer's entity name onto it, and a
+   * `recordPublisher` sends `projection.table`. A channel matches `projection.table`, a live shape
+   * is `from('<table>', …)`; the record TYPE (entity name) is derived from it (`recordTypeForTable`).
+   */
+  readonly table: string;
   readonly op: ChangeOp;
   readonly before: R | null;
   readonly after: R | null;
@@ -34,23 +39,45 @@ export interface ChangeEvent<R extends Row = Row> {
   readonly at: number;
   /**
    * The write that made this change: `writeDigest` of the idempotency key its request carried
-   * (`@ultimat3/core`). Absent for a change no keyed request made. Read off the WAL message the
-   * Postgres driver writes first in the transaction, or off the request scope in-process; a
-   * channel stamps it on the `records` frame so the writing page recognises its own echo.
+   * (`@ultimat3/core`). `null` for a change no keyed request made — a job, a script, raw SQL. Read
+   * off the WAL message the Postgres driver writes first in the transaction, or off the request
+   * scope in-process; a channel stamps it on its `records` frame and a live query on its `patch`
+   * frame, so the writing page settles its own echo in the same batch. REQUIRED, never optional:
+   * a producer that forgets it is a type error, not a page that paints truth plus overlay.
    */
-  readonly write?: string;
+  readonly write: string | null;
+  /**
+   * 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;
 }
@@ -66,7 +93,7 @@ export function parseLsn(pgLsn: string): string {
   return formatLsn((BigInt(`0x${high}`) << 32n) | BigInt(`0x${low}`));
 }
 
-export interface InMemoryChangeFeedOptions {
+export interface MemoryChangeFeedOptions {
   /** Retained events, so a `start({ from })` inside the window replays instead of skipping. */
   readonly retain?: number;
 }
@@ -76,7 +103,7 @@ export interface InMemoryChangeFeedOptions {
  * ordering is the guarantee the whole pipeline is built on, so it is enforced here rather than
  * assumed downstream.
  */
-export class InMemoryChangeFeed implements ChangeFeed {
+export class MemoryChangeFeed implements ChangeFeed {
   readonly source = 'in-memory';
   readonly #retained: ChangeEvent[] = [];
   readonly #retain: number;
@@ -85,7 +112,7 @@ export class InMemoryChangeFeed implements ChangeFeed {
   #position = 0n;
   #lastLsn: string | null = null;
 
-  constructor(options: InMemoryChangeFeedOptions = {}) {
+  constructor(options: MemoryChangeFeedOptions = {}) {
     this.#retain = finiteOption('the change feed', 'retain', options.retain ?? 1024);
   }
 
@@ -103,6 +130,10 @@ export class InMemoryChangeFeed implements ChangeFeed {
     await this.#tail;
   }
 
+  abandon(): void {
+    this.#handler = null;
+  }
+
   lastLsn(): string | null {
     return this.#lastLsn;
   }
@@ -118,13 +149,19 @@ export class InMemoryChangeFeed implements ChangeFeed {
 
   /** Ergonomic emit: assigns the next lsn and txid so tests read as domain events. */
   async push(
-    entity: string,
+    table: string,
     op: ChangeOp,
-    rows: { before?: Row | null; after?: Row | null; orgId?: string | null; at?: number },
+    rows: {
+      before?: Row | null;
+      after?: Row | null;
+      orgId?: string | null;
+      at?: number;
+      write?: string | null;
+    },
   ): Promise<ChangeEvent> {
     this.#position += 1n;
     const event: ChangeEvent = {
-      entity,
+      table,
       op,
       before: rows.before ?? null,
       after: rows.after ?? null,
@@ -132,6 +169,7 @@ export class InMemoryChangeFeed implements ChangeFeed {
       txid: this.#position.toString(10),
       orgId: rows.orgId ?? null,
       at: rows.at ?? 0,
+      write: rows.write ?? null,
     };
     await this.emit(event);
     return event;
@@ -147,7 +185,7 @@ export class InMemoryChangeFeed implements ChangeFeed {
     // The lane chains on a SETTLED shadow, never on `result` — `window-lock.ts` solves the same
     // problem the same way. Chained on the live tail, one rejected link poisoned every link behind
     // it: later changes rejected with the FIRST error, the handler was never called again and
-    // `lastLsn()` froze. Reachable on any single-node deployment, because `createReplicator`'s
+    // `lastLsn()` froze. Reachable on any single-node deployment, because `changeFeedReplicator`'s
     // `onChange` awaits `transport.publish(...)` and a closed `InProcessTransport` refuses — one
     // transient publish failure ended change delivery for the life of the process. The rejection
     // still reaches the caller that pushed THAT event, and only it; `stop()` awaits the shadow, so
@@ -157,10 +195,15 @@ export class InMemoryChangeFeed implements ChangeFeed {
   }
 }
 
+/** The one way to build the in-process feed — the twin of `postgresChangeFeed()`; the class is a type in the barrel only (`X_FACTORY_NAME_SPELLING`). */
+export function memoryChangeFeed(options: MemoryChangeFeedOptions = {}): MemoryChangeFeed {
+  return new MemoryChangeFeed(options);
+}
+
 /** Settles the shadow lane whichever way the delivery went. Nothing observes the value. */
 const ignore = (): void => undefined;
 
-export interface PgLogicalReplicationOptions {
+export interface PostgresChangeFeedOptions {
   /** Connection string for a role with REPLICATION: `postgres://user:pass@host:5432/db`. */
   readonly url: string;
   /** Replication slot name. Exactly one `replicator` process may hold it. */
@@ -175,37 +218,51 @@ 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;
 }
 
 /**
  * The production feed: `pgoutput` decoding off a logical replication slot. Everything about *how*
  * lives in `pg-replication.ts`; what this class adds is the `ChangeFeed` contract the matcher, the
- * replicator and the fanout are written against — so swapping it for `InMemoryChangeFeed` in `x dev`
+ * replicator and the fanout are written against — so swapping it for `MemoryChangeFeed` in `x dev`
  * changes nothing downstream.
  */
-export class PgLogicalReplicationFeed implements ChangeFeed {
+export class PostgresChangeFeed implements ChangeFeed {
   readonly source = 'pg-logical-replication';
   readonly #stream: PgReplicationStream;
 
-  constructor(options: PgLogicalReplicationOptions) {
+  constructor(options: PostgresChangeFeedOptions) {
     if (options.entities.length === 0) {
       throw new ReplicationFailedError({
         stage: 'preflight',
         detail: 'the feed was given an empty entity list, so no change could ever match',
-        fix: 'pass the entities the publication covers: new PgLogicalReplicationFeed({ entities: [...] })',
+        fix: 'pass the entities the publication covers: postgresChangeFeed({ entities: [...] })',
       });
     }
     this.#stream = new PgReplicationStream(options);
   }
 
   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();
   }
@@ -215,3 +272,8 @@ export class PgLogicalReplicationFeed implements ChangeFeed {
     return this.#stream.stats();
   }
 }
+
+/** The one way to build the WAL-backed feed — the twin of `memoryChangeFeed()`; the class is a type in the barrel only (`X_FACTORY_NAME_SPELLING`). */
+export function postgresChangeFeed(options: PostgresChangeFeedOptions): PostgresChangeFeed {
+  return new PostgresChangeFeed(options);
+}