@ultimat3/realtime 20.2.1 → 22.0.0

package/src/json.ts

@@ -34,6 +34,11 @@ export interface RowPatch {
   readonly row: JsonObject | null;
   readonly lsn: string;
   readonly index?: number;
+  /**
+   * The row's RECORD key when it is not its `id` — the entity's primary key, rendered by its
+   * projection on the server. Absent means the key is the `id`.
+   */
+  readonly key?: string;
 }
 
 export function isJsonObject(value: unknown): value is JsonObject {

package/src/live-contract.ts

@@ -41,6 +41,11 @@ export interface LiveQueryDefinition<R extends Row = Row> {
    * rows private to that one subscription rather than guessing.
    */
   rowEntity?(input: JsonValue): string | null;
+  /**
+   * The record key each row travels under, resolved with `rowEntity`: the entity's own projection.
+   * `null` (or absent) is a plain table, whose rows are keyed by `id`.
+   */
+  rowKey?(input: JsonValue): ((row: Row) => string) | null;
   /**
    * Resolve whatever this input needs before an entry is built. `matcher` is synchronous by
    * design — a change event must not await anything — so a definition that has to compile a

package/src/live-definition.ts

@@ -14,6 +14,7 @@ import { type AnyQuery, queryHash, queryName } from '@ultimat3/query';
 import { LiveRowUnidentifiedError } from './errors';
 import { isRow, type JsonValue, type Row } from './json';
 import type { LiveQueryDefinition, SnapshotResult } from './live-contract';
+import { liveRecords } from './live-record-type';
 import { type IncrementalMatcher, matcherFor, type Projection } from './matcher-bridge';
 import { authorizeWithPolicy, visibleWithPolicy } from './policy-gate';
 
@@ -47,6 +48,8 @@ interface SharedWindow {
   readonly matcher: IncrementalMatcher;
   /** The compiled shape's root entity — the client's identity scope for every row of this read. */
   readonly rowEntity: string;
+  /** Its projection's record key; `null` for a plain table keyed by `id`. */
+  readonly rowKey: ((row: Row) => string) | null;
   read(): Promise<readonly Row[]>;
 }
 
@@ -109,11 +112,14 @@ export function liveQueryDefinition(
     // a second subject-less copy — which is what this did — paid for the parse and the `sql()`
     // twice per query id and left two descriptions of one read that agreed only by luck.
     const projection = learnProjection();
+    const records = liveRecords(live.shape.entity);
     const built: SharedWindow = {
       matcher: matcherFor(live, projection.read),
-      // `assertMatchable` already refused a shape without one, so this is the entity the matcher
-      // patches rows of — the same name `ChangeEvent.entity` and `tx.<table>` use.
-      rowEntity: live.shape.entity,
+      // `assertMatchable` already refused a shape without one. The shape names the TABLE (what a
+      // `ChangeEvent` carries); the client store keys records by ENTITY name, so the snapshot tells
+      // it the record type, and every frame carries the key the entity's projection renders.
+      rowEntity: records.type,
+      rowKey: records.key,
       read: async () => {
         const rows = rowsOf(name, await live.execute());
         projection.teach(rows);
@@ -136,12 +142,17 @@ export function liveQueryDefinition(
     },
     snapshot: async ({ input }): Promise<SnapshotResult> => {
       const window = await resolve(input);
-      return { rows: await window.read(), lsn: options.lsn?.() ?? '' };
+      // The position is taken BEFORE the rows: the rows are then at least that new, so the claim
+      // is true. Taken after, a commit landing mid-read was claimed and missing — and every change
+      // up to it is dropped downstream as already folded.
+      const lsn = options.lsn?.() ?? '';
+      return { rows: await window.read(), lsn };
     },
     matcher: (input) => windows.get(queryHash(name, input))?.matcher ?? UNRESOLVED,
     // Read off the same resolved window as the matcher, so the scope the client keys rows under and
     // the entity the matcher patches them from can never be two different names.
     rowEntity: (input) => windows.get(queryHash(name, input))?.rowEntity ?? null,
+    rowKey: (input) => windows.get(queryHash(name, input))?.rowKey ?? null,
     // The two per-subscriber gates, both through the package's one authz seam. Neither result is
     // memoised anywhere: `authorize` runs on every subscribe, `visible` on every row of every
     // delivery, and there is no key here an actor could share with another actor.

package/src/live-fanout.ts

@@ -10,7 +10,7 @@ import type { Row, RowPatch } from './json';
 import type { LiveSubscription } from './live-contract';
 import { applyToWindow, bridgeChange } from './matcher-bridge';
 import { type QueryEntry, refillWindowInLane } from './query-window';
-import type { Subscriber, SubscriberGate } from './subscriber-gate';
+import { type Subscriber, type SubscriberGate, windowIndex } from './subscriber-gate';
 import { type Frame, PROTOCOL_VERSION } from './sync-protocol';
 
 export interface FanoutDeps {
@@ -38,14 +38,25 @@ export async function fanoutChange(
 ): Promise<FanoutResult> {
   // A window that missed a change must be replaced before it is patched again, and it can only be
   // replaced here — a fanout holds this entry's lane, and `fillWindow` takes the same one.
+  // No read has landed in this window yet: there is nothing to patch, and a patch folded into the
+  // empty rows would move `entry.lsn` past the read in flight and get that read discarded as older
+  // than the window — every row but the patched one lost, permanently. Marked stale instead, so the
+  // read that lands is applied and followed by one that includes this change.
+  if (entry.applied === 0) {
+    entry.stale = true;
+    return { sent: 0, stale: 0 };
+  }
+  if (change.op === 'truncate') return await truncated(deps, entry, change);
   if (entry.stale) await refillWindowInLane(entry);
   // The consume-side twin of the replicator's own duplicate guard, which had none. `entry.lsn =
   // change.lsn` was unconditional, so a change the window already holds — a redelivery, or one
   // that arrived behind the snapshot that already included it — rewound every subscriber's cursor
   // to it and asked them to fold state they had already folded over newer rows.
   if (entry.lsn !== '' && change.lsn <= entry.lsn) return { sent: 0, stale: 1 };
-  const result = bridgeChange(entry.shape, entry.matcher, change, entry.rows);
-  if (!result) return { sent: 0, stale: 0 };
+  const bridged = bridgeChange(entry.shape, entry.matcher, change, entry.rows);
+  if (!bridged) return { sent: 0, stale: 0 };
+  // Keyed ONCE, here, before the retained window stores them: a resume replays the same key.
+  const result = { ...bridged, patches: keyPatches(entry, change, bridged.patches) };
   entry.lsn = change.lsn;
   entry.rows = applyToWindow(entry.rows, result.patches);
   // The window lost its tail, so what it holds is a guess — the next delivery re-reads it rather
@@ -55,6 +66,8 @@ export async function fanoutChange(
   for (const patch of result.patches) deps.source.append(entry.qid, patch);
 
   let sent = 0;
+  // Indexed once for every subscriber below, never searched per subscriber per patch.
+  const index = windowIndex(entry.rows);
   for (const subscription of entry.subscribers.values()) {
     if (result.refill) {
       // The window lost its tail: guessing is how a sync engine silently diverges. Checked BEFORE
@@ -82,7 +95,8 @@ export async function fanoutChange(
         entry,
         who,
         result.patches,
-        new Set(subscription.cursor.ids),
+        heldBy(subscription.cursor),
+        index,
       );
     } catch {
       // Already counted and reported as a gate failure. Degrade this one subscriber the way a
@@ -110,6 +124,43 @@ export async function fanoutChange(
   return { sent, stale: 0 };
 }
 
+/**
+ * Every row of a relation this window reads is gone. There is nothing to patch from — a truncate
+ * names no row — so the window is re-read now, in the lane, and every subscriber is re-snapshotted
+ * out of what came back: a window that kept the truncated rows until its next change would serve
+ * them to every new subscriber in the meantime.
+ */
+async function truncated(
+  deps: FanoutDeps,
+  entry: QueryEntry,
+  change: ChangeEvent,
+): Promise<FanoutResult> {
+  if (!entry.shape.entities.includes(change.entity)) return { sent: 0, stale: 0 };
+  await refillWindowInLane(entry);
+  if (change.lsn > entry.lsn) entry.lsn = change.lsn;
+  let sent = 0;
+  for (const subscription of entry.subscribers.values()) {
+    subscription.socket.markDesynced(subscription.sid);
+    if (await resnapshot(deps, entry, subscription)) sent += 1;
+  }
+  return { sent, stale: 0 };
+}
+
+/**
+ * A cursor's ids as a set, built once per ids ARRAY rather than once per subscriber per change.
+ * `advance` hands an update's cursor the same array it had (an update moves no id), so the cache
+ * holds across the common change and dies with the array; an insert or delete makes a new one.
+ */
+const heldSets = new WeakMap<readonly string[], ReadonlySet<string>>();
+
+function heldBy(cursor: LiveCursor): ReadonlySet<string> {
+  const cached = heldSets.get(cursor.ids);
+  if (cached !== undefined) return cached;
+  const held = new Set(cursor.ids);
+  heldSets.set(cursor.ids, held);
+  return held;
+}
+
 /**
  * The repair for one diverged subscriber, out of the window the lane is already holding — no DB
  * read, one frame. Its cursor is rebuilt from what this subscriber may actually see, exactly as
@@ -138,7 +189,11 @@ async function resnapshot(
   return true;
 }
 
-/** The one place a snapshot frame is built, so the identity scope cannot be told to one caller only. */
+/**
+ * The one place a snapshot frame is built, so the identity scope and the record keys cannot be
+ * told to one caller only. `keys` rides only when some key differs from its row's `id` — an entity
+ * keyed by `id` sends the frame it always sent.
+ */
 export function snapshotFrame(
   entry: QueryEntry,
   sid: string,
@@ -146,5 +201,25 @@ export function snapshotFrame(
   cursor: LiveCursor,
 ): Frame {
   const base = { type: 'snapshot', v: PROTOCOL_VERSION, sid, rows, cursor } as const;
-  return entry.rowEntity === null ? base : { ...base, entity: entry.rowEntity };
+  const scoped = entry.rowEntity === null ? base : { ...base, entity: entry.rowEntity };
+  const keyOf = entry.rowKey;
+  if (keyOf === null) return scoped;
+  const keys = rows.map((row) => keyOf(row));
+  return keys.every((key, index) => key === rows[index]?.id) ? scoped : { ...scoped, keys };
+}
+
+/**
+ * A patch's record key, from the change's WHOLE row — an update patch carries only the changed
+ * columns, and a key needs every primary-key column. Only stamped where it differs from `id`.
+ */
+function keyPatches(
+  entry: QueryEntry,
+  change: ChangeEvent,
+  patches: readonly RowPatch[],
+): readonly RowPatch[] {
+  const keyOf = entry.rowKey;
+  const whole = change.after ?? change.before;
+  if (keyOf === null || whole === null) return patches;
+  const key = keyOf(whole);
+  return patches.map((patch) => (key === patch.id ? patch : { ...patch, key }));
 }

package/src/live-query.ts

@@ -70,6 +70,7 @@ export class LiveQueryRegistry {
   readonly #maxEntries: number;
   /** What one lane needs, and nothing this class holds beyond it. */
   readonly #fanout: FanoutDeps;
+  #lastLsn = '';
   #staleChanges = 0;
 
   constructor(options: LiveQueryRegistryOptions) {
@@ -363,7 +364,17 @@ export class LiveQueryRegistry {
    * never per node — awaiting one entry before entering the next made one slow policy pass the
    * whole node's pace, and let a lane that threw skip every entry behind it with nobody desynced.
    */
+  /**
+   * The newest change position this registry has been handed. What a node's snapshot may claim
+   * (`liveQueryDefinition`'s `lsn`): a read begun after it holds at least that change, and every
+   * later change is above it. `''` before the first.
+   */
+  get lastLsn(): string {
+    return this.#lastLsn;
+  }
+
   async deliver(change: ChangeEvent): Promise<number> {
+    if (change.lsn > this.#lastLsn) this.#lastLsn = change.lsn;
     const lanes = [...this.#entries.values()].map(async (entry) => {
       try {
         const result = await entry.lock.run(() => fanoutChange(this.#fanout, entry, change));

package/src/live-record-type.ts

@@ -0,0 +1,19 @@
+// Which record type a live query's rows are, and the key each row travels under. A changefeed and
+// a snapshot speak TABLES; the page store keys records by the entity's NAME and PRIMARY KEY. Both
+// come from the entity's own projection here, on the server — the browser never derives a key.
+
+import type { Row } from '@ultimat3/core/page';
+import { recordProjectionForTable } from '@ultimat3/entity/record';
+
+export interface LiveRecords {
+  /** The entity name — or the table itself when no registered entity owns it. */
+  readonly type: string;
+  /** The row's record key, or `null` for a plain table, whose rows are keyed by `id`. */
+  readonly key: ((row: Row) => string) | null;
+}
+
+export function liveRecords(table: string): LiveRecords {
+  const projection = recordProjectionForTable(table);
+  if (projection === undefined) return { type: table, key: null };
+  return { type: projection.type, key: (row) => projection.key(row) };
+}

package/src/live-replicator.ts

@@ -0,0 +1,160 @@
+// The in-process replicator: committed row changes in, `ChangeEvent`s out, fanned into the node.
+//
+// Production decodes the write-ahead log. PGlite has no walsender and the memory driver has no log,
+// so a test process had no change source at all — which is what left the `subscribe` fixture with
+// no driver, and its five tests in `examples/dummy` asserting against a snapshot that never moved.
+//
+// WHAT IS REAL HERE, and it is everything downstream of the decoder: the matcher, the shared window,
+// the per-subscriber `visible` gate, the cursor, the frames. This substitutes for the WAL DECODER
+// and for nothing else — `@ultimat3/entity`'s `setRowObserver` reports what a repository wrote, in
+// this process, and the events are shaped exactly as `PgLogicalReplicationFeed` shapes them.
+//
+// WHAT IS NOT: a write another process made is invisible, because nothing here reads a log. That is
+// the honest bound, and it is why `selectChangeFeed` never picks it — the boot that installs it
+// decides, and only under an embedded database.
+//
+// Lives in `@ultimat3/realtime/server` since 2026-09-23: it imports only `entity` and `realtime`,
+// so it is a second change source beside the WAL decoder, and `x dev` booting it out of
+// `@ultimat3/testing` put the test harness in every dev process's graph. `@ultimat3/testing`
+// re-exports it until 22.0.0.
+//
+// `x dev` is the one boot that installs it outside a test, `As of 2026-09-05` (`@ultimat3/cli`'s
+// `dev-live-feed.ts`), and only under the EMBEDDED database: PGlite has no walsender, every role
+// runs in that one process, so the bound above holds by construction — and a real `DATABASE_URL`
+// gets the decoder instead, never both.
+
+import type { RowBulkChange, RowChange, RowObserver } from '@ultimat3/entity';
+import type { ChangeEvent, ChangeOp } from './changefeed';
+import type { Row } from './json';
+import type { LiveQueryRegistry } from './live-query';
+
+/** What a caller does with a change nobody could deliver. */
+export interface LiveReplicatorOptions {
+  readonly registry: LiveQueryRegistry;
+  /**
+   * The node's declared channels, fed the same `ChangeEvent` — what a real node's change
+   * subscription does beside `registry.deliver` (`sync-node.ts`). Without it a channel's `records`
+   * frames never carried a write made under `x dev`, and every other tab stayed on the old row.
+   */
+  readonly channels?: { deliverChange(change: ChangeEvent): unknown };
+  /** Tenant column, hoisted out of the row so fanout filters without parsing it. */
+  readonly tenantColumn?: string;
+  readonly onError?: (error: unknown) => void;
+}
+
+export interface LiveReplicator {
+  /** Resolves when every change observed so far has been fanned out. Never a sleep. */
+  settled(): Promise<void>;
+  /** Changes this replicator has delivered — the number a test asserts a patch count against. */
+  readonly delivered: number;
+  stop(): void;
+}
+
+/**
+ * A `ChangeEvent` row is `Row` — a JSON object carrying an `id`. Every row a repository stores has
+ * one; the cast is what says so to a compiler that only sees `Record<string, unknown>`, and a row
+ * that genuinely has none fails downstream in `idOf`, with the entity named, exactly as a row off
+ * the wire would.
+ */
+const asRow = (value: Readonly<Record<string, unknown>> | null): Row | null =>
+  value === null ? null : (value as unknown as Row);
+
+/**
+ * Lexicographically comparable, which is the whole contract of an lsn — `formatLsn` in
+ * `@ultimat3/realtime` produces the same shape from a real WAL position. A counter is enough here
+ * because one process observes its own writes in the order it made them.
+ */
+const lsnOf = (position: number): string => position.toString(16).padStart(16, '0');
+
+/**
+ * Install the replicator for the length of one test. It takes over the process row observer and
+ * hands back whatever was installed before, because `bun test` shares one process across files and
+ * an unconditional clear would take an outer harness's observer with it.
+ */
+export async function startLiveReplicator(options: LiveReplicatorOptions): Promise<LiveReplicator> {
+  // Awaited BEFORE the observer exists, so installation is the last thing this function does and
+  // no write between the call and the install can slip past unobserved.
+  const entity = await import('@ultimat3/entity');
+  const { registry } = options;
+  const tenant = options.tenantColumn ?? 'orgId';
+  let position = 0;
+  let delivered = 0;
+  // One promise chain, because ORDERING is the guarantee the whole pipeline is built on — the same
+  // reason `InMemoryChangeFeed` serializes its deliveries rather than firing them concurrently.
+  let tail: Promise<void> = Promise.resolve();
+  let stopped = false;
+
+  const enqueue = (work: () => Promise<void>): void => {
+    tail = tail.then(work).catch((error: unknown) => {
+      // Never rethrown into the chain: one failed fanout must not silence every change behind it,
+      // and a rejection with nobody to hand it to ends the Bun process.
+      options.onError?.(error);
+    });
+  };
+
+  const observer: RowObserver = {
+    onChange(change: RowChange): void {
+      if (stopped) return;
+      position += 1;
+      const at = position;
+      const row = change.after ?? change.before;
+      const orgId = typeof row?.[tenant] === 'string' ? (row[tenant] as string) : null;
+      const event: ChangeEvent = {
+        entity: change.entity,
+        // A repository's three row ops are three of the feed's four; a truncate never comes this way.
+        op: change.op satisfies ChangeOp,
+        before: asRow(change.before),
+        after: asRow(change.after),
+        lsn: lsnOf(at),
+        txid: String(at),
+        orgId,
+        // Deliberately not a clock read: the preload freezes `Date.now()`, and a change's commit
+        // time is not something any assertion in this repo reads. `at` keeps it monotonic anyway.
+        at,
+        // The keyed write it belongs to, read off the request scope — what the WAL decoder reads
+        // off the transaction's opening message — so a channel frame names it here as it would there.
+        ...(change.write === undefined ? {} : { write: change.write }),
+      };
+      enqueue(async () => {
+        // Channels first, as the node does: a live query's fanout that throws must not also cost
+        // every declared channel the change.
+        options.channels?.deliverChange(event);
+        delivered += await registry.deliver(event);
+      });
+    },
+
+    /**
+     * A filtered write names rows this seam never saw, so there is no event to shape. Every window
+     * on the node is marked stale instead and re-read on the next change — `invalidate()` is the
+     * node's own answer to "the change stream skipped something", used here for the one write that
+     * genuinely does. Silence would be the alternative, and a subscriber told nothing happened
+     * diverges with nobody ever asking again.
+     */
+    onBulk(_change: RowBulkChange): void {
+      if (stopped) return;
+      registry.invalidate();
+    },
+  };
+
+  const previous = entity.setRowObserver(observer);
+
+  return {
+    get delivered() {
+      return delivered;
+    },
+    settled: async () => {
+      // Twice: a fanout can enqueue nothing, but the writes that produced these changes may still
+      // be resolving their own promises when a test asks. Awaiting the chain, letting the
+      // microtask queue drain, then awaiting it again covers a change observed in between.
+      await tail;
+      for (let turn = 0; turn < 8; turn += 1) await Promise.resolve();
+      await tail;
+    },
+    stop: () => {
+      stopped = true;
+      // Restored, never cleared: one process runs every test file, and an outer harness's observer
+      // must survive an inner fixture finishing.
+      entity.setRowObserver(previous);
+    },
+  };
+}

package/src/live-rows.ts

@@ -1,90 +1,101 @@
-// One live subscription's window, projected out of the identity map. The registration owns the
-// ORDER (its ids) and the map owns the VALUES — which is what makes post #7 one object however
-// many queries returned it, and what makes a write through any of them reach all of them.
+// One live subscription's window over the page's record store. The registration owns the ORDER
+// (its ids) and the store owns the VALUES — which is what makes post #7 one object however many
+// queries returned it, and what makes a write through any of them reach all of them.
 
+import type { Row } from '@ultimat3/core/page';
 import { orderAfterPatches } from './apply-patches';
 import type { LiveCursor } from './cursor';
-import { type IdentityMap, type RowKey, type RowScope, rowKey } from './identity-map';
-import type { JsonValue, Row, RowPatch } from './json';
+import type { JsonValue, RowPatch } from './json';
+import { type RecordKey, type RecordStore, recordKey } from './record-store';
 
-export type LiveState = 'loading' | 'live' | 'stale' | 'offline';
+export type LiveState = 'loading' | 'live' | 'stale' | 'offline' | 'failed';
 
 /** One live query this client holds. Mutable: the ids and cursor a frame advances live here. */
 export interface Registration {
   readonly sid: string;
   readonly name: string;
   readonly input: JsonValue;
-  readonly setRows: (rows: readonly Row[]) => void;
-  readonly setState: (state: LiveState) => void;
-  readonly setCursor: (cursor: LiveCursor | null) => void;
-  /** Where this window's rows live in the map: the entity the server named, or a private scope. */
-  scope: RowScope;
-  /** Membership and order. The values are the map's — never a second copy of them. */
+  /** The record type the server named for this window; `unnamedType(name)` until it does. */
+  type: string;
+  /** Membership and order. The values are the store's — never a second copy of them. */
   ids: readonly string[];
   cursor: LiveCursor | null;
+  state: LiveState;
+  /** What the node answered when it refused this subscription. Set with `state: 'failed'`. */
+  error: unknown;
+  /** Called after anything a reader of this window renders has moved. */
+  readonly notify: () => void;
 }
 
 /**
- * Every open window over one identity map. It is the only writer of `Registration.ids`, so the
- * retain/release pairs that keep the map from growing without end cannot be forgotten by a caller.
+ * Where a window's rows live when the server named no record type: `?` starts no entity name, so
+ * two unnamed windows sharing an id never merge two entities' rows. Not a record type — only a
+ * snapshot from a node that cannot name the entity lands here.
+ */
+export function unnamedType(queryName: string): string {
+  return `?query:${queryName}`;
+}
+
+/**
+ * Every open window over the one store. It is the only writer of `Registration.ids`, so the
+ * retain/release pairs that keep the store from growing without end cannot be forgotten.
  */
 export class RowWindows {
-  readonly #identity: IdentityMap;
-  /** The window a write is running for, so its own listener does not emit the same rows twice. */
+  readonly #store: RecordStore;
+  /** The window a write is running for, so its own listener does not notify it twice. */
   #writing: Registration | null = null;
 
-  constructor(identity: IdentityMap) {
-    this.#identity = identity;
+  constructor(store: RecordStore) {
+    this.#store = store;
   }
 
-  /**
-   * Start rendering this registration out of the map. The returned close releases its rows and
-   * drops its listener — an unsubscribed component must stop holding rows and stop hearing about
-   * them in the same call, or one of the two outlives the other.
-   */
+  /** Render this registration out of the store; the returned close releases every row it held. */
   open(registration: Registration): () => void {
-    const unsubscribe = this.#identity.subscribe((changed) => {
+    const unsubscribe = this.#store.subscribe((changed) => {
       if (this.#writing === registration) return;
-      if (!holds(registration, changed)) return;
-      this.#emit(registration);
+      if (holds(registration, changed)) registration.notify();
     });
     return () => {
       unsubscribe();
-      this.#identity.batch(() => {
-        for (const id of registration.ids) this.#identity.release(registration.scope, id);
+      this.#store.batch(() => {
+        for (const id of registration.ids) this.#store.release(registration.type, id);
         registration.ids = [];
       });
     };
   }
 
-  /**
-   * A snapshot: server truth for the whole window. `entity` is the scope the server named for this
-   * subscription — the first one that arrives upgrades a private scope to the shared one, which is
-   * what lets two different queries over one entity meet on the same row.
-   */
-  snapshot(registration: Registration, entity: string | null, rows: readonly Row[]): void {
-    const scope = entity ?? registration.scope;
+  /** A snapshot: server truth for the whole window, under the record type the server named. */
+  snapshot(
+    registration: Registration,
+    type: string | null,
+    rows: readonly Row[],
+    keys?: readonly string[],
+  ): void {
+    const next = type ?? registration.type;
+    // The server's record key where it sent one; a row's `id` IS its key everywhere else.
+    const keyed = rows.map((row, index) => [keys?.[index] ?? String(row['id']), row] as const);
     this.#reseat(
       registration,
-      scope,
-      rows.map((row) => row.id),
-      (held) => {
-        for (const row of rows) {
-          if (held.has(row.id)) this.#identity.merge(scope, row.id, row);
-        }
+      next,
+      keyed.map(([id]) => id),
+      () => {
+        for (const [id, row] of keyed) this.#store.merge(next, id, row);
       },
     );
   }
 
-  /** A patch list: values merged into the map, membership and order folded over the ids. */
-  patch(registration: Registration, patches: readonly RowPatch[]): void {
-    const scope = registration.scope;
-    // A `delete` is this window losing the row, never the map losing it: another window holding
-    // the same row keeps it until its own delete arrives.
-    this.#reseat(registration, scope, orderAfterPatches(registration.ids, patches), (held) => {
+  /** A patch list: values merged into the store, membership and order folded over the ids. */
+  patch(registration: Registration, sent: readonly RowPatch[]): void {
+    const type = registration.type;
+    // A window holds RECORD keys: a patch the server keyed is folded under its key, not its id.
+    const patches = sent.map((patch) =>
+      patch.key === undefined ? patch : { ...patch, id: patch.key },
+    );
+    // A `delete` is this window losing the row, never the store losing it: another holder keeps it.
+    this.#reseat(registration, type, orderAfterPatches(registration.ids, patches), (held) => {
       for (const patch of patches) {
         if (patch.op === 'delete' || patch.row === null) continue;
-        if (held.has(patch.id)) this.#identity.merge(scope, patch.id, patch.row);
+        if (held.has(patch.id)) this.#store.merge(type, patch.id, patch.row);
       }
     });
   }
@@ -93,51 +104,43 @@ export class RowWindows {
   rows(registration: Registration): readonly Row[] {
     const out: Row[] = [];
     for (const id of registration.ids) {
-      const row = this.#identity.peek(registration.scope, id);
+      const row = this.#store.peek(registration.type, id);
       if (row !== undefined) out.push(row);
     }
     return out;
   }
 
   /**
-   * Move the window to `nextIds` under `scope`, writing values in between. One batch per frame,
-   * and one emit for the window that caused it.
-   *
+   * Move the window to `nextIds` under `type`, writing values in between — one batch, one notify.
    * The retain comes before the write and the release after it, so a row this window keeps across
-   * the move never reaches zero holds and gets dropped out from under the value it is about to be
-   * given. `write` only touches ids the window ends up holding — a value nobody holds is a value
-   * no release will ever reclaim.
+   * the move never reaches zero holds and is evicted out from under the value it is being given.
    */
   #reseat(
     registration: Registration,
-    scope: RowScope,
+    type: string,
     nextIds: readonly string[],
     write: (held: ReadonlySet<string>) => void,
   ): void {
     const previous = this.#writing;
     this.#writing = registration;
     try {
-      this.#identity.batch(() => {
-        for (const id of nextIds) this.#identity.retain(scope, id);
+      this.#store.batch(() => {
+        for (const id of nextIds) this.#store.retain(type, id);
         write(new Set(nextIds));
-        for (const id of registration.ids) this.#identity.release(registration.scope, id);
-        registration.scope = scope;
+        for (const id of registration.ids) this.#store.release(registration.type, id);
+        registration.type = type;
         registration.ids = nextIds;
       });
     } finally {
       this.#writing = previous;
     }
-    this.#emit(registration);
-  }
-
-  #emit(registration: Registration): void {
-    registration.setRows(this.rows(registration));
+    registration.notify();
   }
 }
 
-function holds(registration: Registration, changed: ReadonlySet<RowKey>): boolean {
+function holds(registration: Registration, changed: ReadonlySet<RecordKey>): boolean {
   for (const id of registration.ids) {
-    if (changed.has(rowKey(registration.scope, id))) return true;
+    if (changed.has(recordKey(registration.type, id))) return true;
   }
   return false;
 }