@ultimat3/realtime 1.2.0 → 2.0.0

package/src/cursor.ts

@@ -7,7 +7,7 @@ import { type Clock, systemClock } from '@ultimat3/core';
 import { CursorStaleError } from './errors';
 import { canonicalJson, fnv1a, type Row, type RowPatch } from './json';
 
-/** Ids are bounded so a cursor stays small enough to ship in a `hello` frame. */
+/** Ids are bounded so a cursor stays small enough to ship on every `subscribe` frame. */
 export const CURSOR_ID_LIMIT = 512;
 
 /** A digest of `''` means "not verified at this lsn" — set on every delta resume. */
@@ -69,6 +69,12 @@ export interface ResumeSource {
   /** Patches strictly after `lsn`, or `null` when the gap is not covered by the retained window. */
   since(qid: string, lsn: string): RowPatch[] | null;
   headLsn(qid: string): string | null;
+  /**
+   * The last subscriber of this query went away, so nothing will ever resume from its retained
+   * patches. Optional because a source may retain nothing; the registry calls it when it drops
+   * the entry, which is the only moment anything knows the window is unreachable.
+   */
+  forget?(qid: string): void;
 }
 
 export type ResumeResult<R extends Row = Row> =

package/src/errors.ts

@@ -7,6 +7,8 @@ import { registerErrorCodes, UltimateError } from '@ultimat3/core';
 export const REALTIME_OWNED_ERROR_CODES = [
   'X_TOPIC_FORBIDDEN',
   'X_SUBSCRIPTION_LIMIT',
+  'X_SUBSCRIPTION_ID_TAKEN',
+  'X_FRAME_RATE_LIMIT',
   'X_PROTOCOL_VERSION',
   'X_CURSOR_STALE',
   'X_REBASE_CONFLICT',
@@ -17,6 +19,10 @@ export const REALTIME_OWNED_ERROR_CODES = [
   'X_REPLICATOR_SLOT_HELD',
   'X_LIVE_CLIENT_MISSING',
   'X_LIVE_ROW_UNIDENTIFIED',
+  'X_LIVE_QUERY_UNKNOWN',
+  'X_QUERY_NOT_SUBSCRIBABLE',
+  'X_SOCKET_UNAUTHENTICATED',
+  'X_SOCKET_AUTH_UNAVAILABLE',
 ] as const;
 
 /**
@@ -26,6 +32,62 @@ export const REALTIME_OWNED_ERROR_CODES = [
  */
 export const REALTIME_BORROWED_ERROR_CODES = ['X_NOT_IMPLEMENTED'] as const;
 
+/**
+ * The two codes an authz **decision** carries. Everything else a gate throws — a rule that reached
+ * for a row and timed out, a predicate with a typo in it — is a failure to reach a decision at all,
+ * and reading one as "denied" publishes an outage as a permission change: rows leave the screen,
+ * `live.rows_denied` ticks up, and nothing ever pages anyone.
+ */
+export const POLICY_DENIAL_CODES: ReadonlySet<string> = new Set([
+  'X_FORBIDDEN',
+  'X_UNAUTHENTICATED',
+]);
+
+/**
+ * The sync protocol's answer to "which of these is a 4xx". A denied topic, a subscription cap, a
+ * skewed protocol version and a cursor that fell out of the buffer are all conditions the CLIENT
+ * caused and the ack frame already explains — so an error monitor that held them would be a log
+ * nobody reads. Everything else, including an accidental `TypeError`, is this node's fault.
+ * Kept beside the code list so the two cannot drift, and it spreads the denial codes rather than
+ * respelling them: a denial is always the client's own condition.
+ */
+export const REALTIME_CLIENT_FAULT_CODES: ReadonlySet<string> = new Set([
+  ...POLICY_DENIAL_CODES,
+  'X_TOPIC_FORBIDDEN',
+  'X_SUBSCRIPTION_LIMIT',
+  'X_SUBSCRIPTION_ID_TAKEN',
+  // The client is the one sending too fast, and it is the one that can stop.
+  'X_FRAME_RATE_LIMIT',
+  'X_PROTOCOL_VERSION',
+  'X_LIVE_QUERY_UNKNOWN',
+  'X_CURSOR_STALE',
+  'X_REBASE_CONFLICT',
+  // The credential is the client's to send; the node deciding it has none is not this node failing.
+  // Its twin, `X_SOCKET_AUTH_UNAVAILABLE`, is deliberately absent — that one IS this node failing.
+  'X_SOCKET_UNAUTHENTICATED',
+]);
+
+/** True when the client is the one who can fix it, so the node must not page anyone about it. */
+export function isClientFault(error: unknown): boolean {
+  return REALTIME_CLIENT_FAULT_CODES.has(codeOf(error) ?? '');
+}
+
+/**
+ * True when a gate **decided** against the actor, false when it never got that far. The gates take
+ * arbitrary functions — `LiveQueryDefinition.authorize` and `.visible` are supplied by the caller —
+ * so the question is asked of the error's code rather than of a class this package could import.
+ */
+export function isPolicyDenial(error: unknown): boolean {
+  return POLICY_DENIAL_CODES.has(codeOf(error) ?? '');
+}
+
+/** The `X_*` code an unknown throw carries, or `null` — the one place that reads it off `unknown`. */
+function codeOf(error: unknown): string | null {
+  if (typeof error !== 'object' || error === null || !('code' in error)) return null;
+  const code = (error as { code: unknown }).code;
+  return typeof code === 'string' ? code : null;
+}
+
 /** Every code realtime can throw through `RealtimeError`: the ones it owns plus the borrowed one. */
 export const REALTIME_ERROR_CODES = [
   ...REALTIME_OWNED_ERROR_CODES,
@@ -37,7 +99,9 @@ export type RealtimeErrorCode = (typeof REALTIME_ERROR_CODES)[number];
 
 export const REALTIME_ERROR_TITLES: Readonly<Record<RealtimeOwnedErrorCode, string>> = {
   X_TOPIC_FORBIDDEN: 'the actor may not subscribe to this topic',
-  X_SUBSCRIPTION_LIMIT: 'socket or tenant hit its subscription cap',
+  X_SUBSCRIPTION_LIMIT: 'socket, tenant or node hit its subscription cap',
+  X_SUBSCRIPTION_ID_TAKEN: 'a subscribe frame reused a sid this socket already holds',
+  X_FRAME_RATE_LIMIT: 'one socket sent frames faster than this node will route them',
   X_PROTOCOL_VERSION: 'client and sync node disagree on the wire protocol',
   X_CURSOR_STALE: 'the resume LSN is outside the change buffer',
   X_REBASE_CONFLICT: 'a local mutation could not be rebased',
@@ -48,6 +112,10 @@ export const REALTIME_ERROR_TITLES: Readonly<Record<RealtimeOwnedErrorCode, stri
   X_REPLICATOR_SLOT_HELD: 'another replicator already owns this database',
   X_LIVE_CLIENT_MISSING: 'a realtime hook ran with no LiveClient registered',
   X_LIVE_ROW_UNIDENTIFIED: 'a live query returned a row with no id',
+  X_LIVE_QUERY_UNKNOWN: 'no live query is registered under the name a subscribe frame asked for',
+  X_QUERY_NOT_SUBSCRIBABLE: 'a hook was bound to a query that is not declared live',
+  X_SOCKET_UNAUTHENTICATED: 'the sync upgrade carried no credential this app accepts',
+  X_SOCKET_AUTH_UNAVAILABLE: 'the sync node could not decide who a connecting socket is',
 };
 
 // One unconditional call, so a second package claiming one of realtime's codes throws
@@ -83,13 +151,60 @@ export class TopicForbiddenError extends RealtimeError {
   }
 }
 
-/** Load shedding, not a crash: a socket or tenant asked for more subscriptions than the cap. */
+/**
+ * Load shedding, not a crash: a socket, a tenant or this node asked for more than its cap.
+ *
+ * `knob` is the option that raises it, and it is passed rather than derived because the `node`
+ * scope has more than one — a live-query entry ceiling and a channel-topic ceiling are two
+ * different numbers on two different objects. The fix names the constructor option, never an
+ * `app.config.ts` field: there is none (`docs/architecture/07-realtime-internals.md:244`), and a
+ * fix line naming a field that does not exist is an instruction that cannot be followed.
+ */
 export class SubscriptionLimitError extends RealtimeError {
-  constructor(args: { scope: 'socket' | 'tenant'; id: string; limit: number }) {
+  constructor(args: {
+    scope: 'socket' | 'tenant' | 'node';
+    id: string;
+    limit: number;
+    knob?: string;
+  }) {
+    const knob = args.knob ?? (args.scope === 'socket' ? 'maxPerSocket' : 'maxPerTenant');
     super({
       code: 'X_SUBSCRIPTION_LIMIT',
       cause: `${args.scope} ${args.id} reached the subscription cap of ${args.limit}`,
-      fix: `raise realtime.limits.${args.scope === 'socket' ? 'perSocket' : 'perTenant'} in app.config.ts, or unsubscribe unused live queries`,
+      fix: `raise ${knob} where this sync node is constructed, or unsubscribe unused live queries`,
+    });
+  }
+}
+
+/**
+ * One socket sent frames faster than the node will route them. The accept budget spends a token
+ * per UPGRADE, so before this existed an authenticated socket — the cheapest possible foothold —
+ * could drive an unbounded number of subscribe frames into a DB read, a presence write and a
+ * fleet-wide publish each, with nothing between the frame and the work.
+ *
+ * A client fault, so it never pages anyone: the ack frame carries this and the client backs off.
+ */
+export class FrameRateLimitError extends RealtimeError {
+  constructor(args: { socketId: string; perSecond: number }) {
+    super({
+      code: 'X_FRAME_RATE_LIMIT',
+      cause: `socket ${args.socketId} exceeded ${args.perSecond} frames per second`,
+      fix: 'batch subscribes into one frame per subscription and retry after the delay, or raise maxFramesPerSecond where createSyncNode() is called',
+    });
+  }
+}
+
+/**
+ * The client chose a subscription id it is already using on this socket. Refused rather than
+ * replaced: attaching over it would strand the earlier subscription inside its query entry, where
+ * nothing can unsubscribe it and the entry's matcher and shared window are never freed.
+ */
+export class SubscriptionIdTakenError extends RealtimeError {
+  constructor(args: { sid: string; socketId: string }) {
+    super({
+      code: 'X_SUBSCRIPTION_ID_TAKEN',
+      cause: `socket ${args.socketId} already holds a live subscription with sid "${args.sid}"`,
+      fix: 'send a fresh sid with each subscribe frame — crypto.randomUUID() is what the bundled client uses',
     });
   }
 }
@@ -241,6 +356,80 @@ export class LiveRowUnidentifiedError extends RealtimeError {
   }
 }
 
+/**
+ * A `subscribe` frame named a live query this node does not have. Distinct from a version skew
+ * because the two have opposite instructions: this one was reported as `X_PROTOCOL_VERSION`, whose
+ * fix is "x build && redeploy the client" — and redeploying a client that spells the name the same
+ * way changes nothing, while the registry that would have shown the mismatch never gets opened.
+ * A misspelling and an unregistered query produce the same frame, so the fix names both.
+ *
+ * The name it prints is the one the client sent; the registry is never enumerated back over the
+ * wire, because an unauthenticated socket asking for "a" through "zz" is not entitled to a list of
+ * every read this app declares.
+ *
+ * `fix` is the command and nothing else. What to do with what it prints belongs in `cause`: a fix
+ * line is pasted into a shell, so prose appended to it is a command that does not run.
+ */
+export class LiveQueryUnknownError extends RealtimeError {
+  constructor(args: { name: string }) {
+    super({
+      code: 'X_LIVE_QUERY_UNKNOWN',
+      cause: `no live query is registered as "${args.name}" on this node — subscribe under a name the registry prints, or pass the query to defineApi({ queries }) if it is missing`,
+      fix: 'x queries list --json',
+    });
+  }
+}
+
+/**
+ * `liveHookFor` was handed a read that never patches. Refused where the binding is written rather
+ * than at the first render, because a hook over a non-live query has nothing to subscribe to — it
+ * would return an empty set forever and look like a policy denial or an empty table.
+ */
+export class QueryNotSubscribableError extends RealtimeError {
+  constructor(args: { name: string }) {
+    super({
+      code: 'X_QUERY_NOT_SUBSCRIBABLE',
+      // Empty at module load, when the binding runs and `registerQueries()` has not stamped a
+      // name yet — say so rather than printing `query ""`.
+      cause: `query ${args.name === '' ? '<unregistered>' : `"${args.name}"`} is not declared live: true, so it has no subscription for a hook to read`,
+      fix: 'add live: true to the query declaration, or read it once through query.client({ baseUrl }) — wiki/Queries-And-Live-Queries.md',
+    });
+  }
+}
+
+/**
+ * The app's `authenticate` decided this upgrade belongs to nobody. A **decision**, so it is the
+ * client's own condition and never pages anyone: the refusal is the whole point of the hook.
+ *
+ * Distinct from `X_TOPIC_FORBIDDEN`, which is a subscriber that got a socket and then asked for
+ * something it may not have. This one never gets a socket at all — a websocket refused after the
+ * upgrade is a connection the client must tear down to learn about.
+ */
+export class SocketUnauthenticatedError extends RealtimeError {
+  constructor(args: { reason: string }) {
+    super({
+      code: 'X_SOCKET_UNAUTHENTICATED',
+      cause: `the websocket upgrade was refused: ${args.reason}`,
+      fix: 'send the credential createSyncNode({ authenticate }) reads on the upgrade request, or return an anonymous Actor from it to admit this socket',
+    });
+  }
+}
+
+/**
+ * `authenticate` raised instead of deciding. The same rule the row gate follows: a failure is not a
+ * denial, so the client is told to come back rather than told it may not connect — a token service
+ * that timed out must not read to a user as "you are signed out", and it must page someone.
+ */
+export class SocketAuthUnavailableError extends RealtimeError {
+  constructor(args: { detail: string }) {
+    super({
+      code: 'X_SOCKET_AUTH_UNAVAILABLE',
+      cause: `authenticate() raised instead of deciding who a connecting socket is: ${args.detail}`,
+      fix: 'x doctor --json',
+    });
+  }
+}
+
 /** Deep infrastructure that is interface-complete but not wired. Carries the exact next step. */
 export class NotImplementedError extends RealtimeError {
   constructor(args: { what: string; fix: string }) {

package/src/frame-lanes.ts

@@ -0,0 +1,58 @@
+// The order this node applies one socket's inbound frames in. `sync-node.message` dispatches every
+// frame as `void (async () => routeFrame(…))()`, so nothing upstream orders them and a router that
+// awaits a policy, a snapshot read or `onMutate` finishes in whatever order those settle.
+//
+// **Not one lane per socket.** A global per-socket lane puts every frame behind the slowest one,
+// and the slowest one is a snapshot read — a database round trip that every reconnecting client
+// pays once per live query, which is precisely the 50,000-client restart storm this framework is
+// measured on. What has to be ordered is narrower and exact:
+//
+// | Frames | Lane | Why that is the unit |
+// |---|---|---|
+// | `mutate` | `mutate` (one per socket) | they write the database, and the client numbered them |
+// | `subscribe` on a query | `sub:<sid>` | `add` then `drop` for one sid, or the drop finds nothing and the add strands the subscription it was meant to end |
+// | `subscribe` on a topic | `topic:<name>` | the same add/drop pair, one membership |
+// | `hello`, server-authored kinds | none | they read state and write none of it |
+//
+// The caps are NOT this file's job — a lane makes concurrent frames sequential, and N sequential
+// subscribes still pass a check-then-act cap N times. `SubscriptionBook.reserve` and
+// `ChannelHub`'s bridge reservation are what bound them, synchronously, before the first await.
+
+import type { Frame } from './sync-protocol';
+import { WindowLock } from './window-lock';
+
+/**
+ * FIFO per key, concurrent across keys. A lane exists only while something is queued on it, so the
+ * map is empty between frames — keyed by a client-chosen sid, a lane that outlived its work would
+ * be an unbounded map one socket could grow at will.
+ */
+export class FrameLanes {
+  readonly #lanes = new Map<string, { lock: WindowLock; queued: number }>();
+
+  run<T>(key: string, work: () => Promise<T>): Promise<T> {
+    const lane = this.#lanes.get(key) ?? { lock: new WindowLock(), queued: 0 };
+    lane.queued += 1;
+    this.#lanes.set(key, lane);
+    const result = lane.lock.run(work);
+    const done = (): void => {
+      lane.queued -= 1;
+      // Only when nothing is waiting: dropping a lane with work still queued on it would let the
+      // next frame open a second lane beside the first and overtake it.
+      if (lane.queued === 0 && this.#lanes.get(key) === lane) this.#lanes.delete(key);
+    };
+    result.then(done, done);
+    return result;
+  }
+
+  /** Test-only probe: lanes still held. A count that does not return to zero is the leak. */
+  get size(): number {
+    return this.#lanes.size;
+  }
+}
+
+/** The lane a frame belongs in, or `null` for the kinds nothing has to order. */
+export function laneKeyOf(frame: Frame): string | null {
+  if (frame.type === 'mutate') return 'mutate';
+  if (frame.type !== 'subscribe') return null;
+  return frame.target.kind === 'topic' ? `topic:${frame.target.topic}` : `sub:${frame.sid}`;
+}

package/src/hooks.ts

@@ -15,26 +15,34 @@ interface Registered {
   /** Read to subscribe, bumped to invalidate: `OfflineQueue` stores plain arrays, not signals. */
   readonly version: () => number;
   readonly bump: () => void;
+  /** Drops this registration's queue listener. The client outlives the registration. */
+  readonly release: () => void;
 }
 
 let registered: Registered | null = null;
 
 /** Register once, in the app entry, before the first render. One app, one socket, one client. */
 export function setLiveClient(client: LiveClient): void {
+  // The previous registration's listener goes with it. The client outlives `setLiveClient` — a hot
+  // reload, a test's next case, an app that re-registers after signing in — so a discarded
+  // unsubscribe is a listener nothing can reach, bumping a signal nothing renders, once per
+  // registration this process ever made.
+  registered?.release();
   const [version, setVersion] = client.signal<number>(0);
   const bump = (): void => {
     setVersion(version() + 1);
   };
-  registered = { client, version, bump };
   // Closes the gap a direct call can't: a reconnect drains automatically inside `connect()`, and
   // an ack/fail frame arrives asynchronously inside `#onFrame` — neither is awaited by any hook, so
   // this is the only path that reaches them. The direct `bump()` calls below stay too: they fire at
   // the earliest possible moment for the call that made them, and a redundant bump is harmless.
-  client.onQueueChange(bump);
+  const release = client.onQueueChange(bump);
+  registered = { client, version, bump, release };
 }
 
 /** For tests: drop the registration so cases stay independent. */
 export function clearLiveClient(): void {
+  registered?.release();
   registered = null;
 }
 
@@ -54,9 +62,14 @@ export type LiveInput = JsonValue | (() => JsonValue);
 
 /**
  * A callable result set: `feed()` are the rows, `feed.state()` / `feed.cursor()` /
- * `feed.unsubscribe()` are the rest of the `LiveHandle` hanging off it.
+ * `feed.unsubscribe()` are the rest of the `LiveHandle` hanging off it. It is also `Disposable`
+ * (inherited from `LiveHandle`), so `using feed = useLive(...)` unsubscribes on scope exit.
+ *
+ * `R` is only constrained to `object`: on the wire every row is a `Row`, but a hook bound to a
+ * declared query (`query-hook.ts`) answers in that query's own row type, which is whatever its
+ * `sql` returns. The three members hanging off the accessor are the same for every `R`.
  */
-export type LiveRows<R extends Row = Row> = (() => readonly R[]) & Omit<LiveHandle<R>, 'rows'>;
+export type LiveRows<R extends object = Row> = (() => readonly R[]) & Omit<LiveHandle, 'rows'>;
 
 /**
  * Subscribe to a live query. `query` is anything carrying a `name`, which a `@ultimat3/query`
@@ -66,7 +79,7 @@ export type LiveRows<R extends Row = Row> = (() => readonly R[]) & Omit<LiveHand
  * A thunk `input` is read **once**, at subscribe time: tier 3 has no reactive runtime of its own,
  * so nothing re-runs it when its dependencies change. Changing input means a new subscription.
  * The caller owns `unsubscribe` — nothing here disposes on unmount, because nothing here knows
- * what a mount is.
+ * what a mount is. `using` works too, when the caller does have a scope to hang it on.
  */
 export function useLive<R extends Row = Row>(query: LiveQueryRef, input: LiveInput): LiveRows<R> {
   const handle = live('useLive').client.useLive<R>(
@@ -77,6 +90,7 @@ export function useLive<R extends Row = Row>(query: LiveQueryRef, input: LiveInp
     state: handle.state,
     cursor: handle.cursor,
     unsubscribe: handle.unsubscribe,
+    [Symbol.dispose]: handle[Symbol.dispose],
   });
 }
 

package/src/identity-map.ts

@@ -0,0 +1,141 @@
+// One row VALUE per `(scope, id)` for the whole client — the identity map the thesis takes from
+// Ember Data. Two components holding two copies of one row is the bug it makes unrepresentable:
+// a live query's window and the tier-3 local store are both projections over this one map, so a
+// write through either is the same row for both. Membership and order live in the projections.
+
+import type { JsonObject, JsonValue, Row } from './json';
+
+/**
+ * The entity's table — the same name `ChangeEvent.entity`, `tx.<table>` and a mutator's `entity`
+ * already use, which is what makes the live path and the local store address one row identically.
+ * A subscription whose entity the server did not name gets a private `?query:<name>` scope: no
+ * sharing is worse than sharing two different entities that happen to spell one id the same way.
+ */
+export type RowScope = string;
+
+/** `scope`+NUL+`id`. NUL cannot occur in an entity name, so the join is unambiguous. */
+export type RowKey = string;
+
+export function rowKey(scope: RowScope, id: string): RowKey {
+  return `${scope}\u0000${id}`;
+}
+
+/** The scope a subscription uses until the server names its entity. `?` starts no entity name. */
+export function privateScope(queryName: string): RowScope {
+  return `?query:${queryName}`;
+}
+
+export type IdentityListener = (changed: ReadonlySet<RowKey>) => void;
+
+/**
+ * The map. Values are immutable: every write produces a NEW row object, because a projection over
+ * this map hands its rows to a signal and a mutated-in-place row is a render that never happens.
+ * "One row per id" therefore means one *current value* per id, referenced by every holder at once.
+ */
+export class IdentityMap {
+  readonly #values = new Map<RowKey, Row>();
+  /** How many projections hold each key. A row nobody holds is dropped — a window is not a leak. */
+  readonly #holds = new Map<RowKey, number>();
+  readonly #listeners = new Set<IdentityListener>();
+  /** Non-null while a batch is open; every write inside one notifies exactly once, at the end. */
+  #changed: Set<RowKey> | null = null;
+
+  peek(scope: RowScope, id: string): Row | undefined {
+    return this.#values.get(rowKey(scope, id));
+  }
+
+  /** Whole-row write: the value becomes exactly this row. `insert` and a rollback's undo use it. */
+  set(scope: RowScope, row: Row): Row {
+    const key = rowKey(scope, row.id);
+    const current = this.#values.get(key);
+    if (current === row) return row;
+    this.#values.set(key, row);
+    this.#touch(key);
+    return row;
+  }
+
+  /**
+   * Merge changed columns onto the current value. This is the write every server patch, every
+   * snapshot row and every `upsert` takes: a projection that selected fewer columns must not blank
+   * the columns another projection is rendering, so a write never removes a key. `undefined` in a
+   * patch means "leave it alone", exactly as the local store's contract already says.
+   */
+  merge(
+    scope: RowScope,
+    id: string,
+    columns: Readonly<Record<string, JsonValue | undefined>>,
+  ): Row {
+    const key = rowKey(scope, id);
+    const current = this.#values.get(key);
+    const next: JsonObject = { ...current };
+    let changed = current === undefined;
+    for (const [column, value] of Object.entries(columns)) {
+      if (value === undefined || column === 'id') continue;
+      if (current === undefined || current[column] !== value) changed = true;
+      next[column] = value;
+    }
+    const row: Row = { ...next, id };
+    // A patch that changed nothing must not re-emit: a no-op write re-rendering every holder is
+    // how a live query becomes the most expensive thing on the page.
+    if (!changed && current !== undefined) return current;
+    this.#values.set(key, row);
+    this.#touch(key);
+    return row;
+  }
+
+  retain(scope: RowScope, id: string): void {
+    const key = rowKey(scope, id);
+    this.#holds.set(key, (this.#holds.get(key) ?? 0) + 1);
+  }
+
+  /** The last holder leaving drops the value: an infinite scroll must not retain every row it saw. */
+  release(scope: RowScope, id: string): void {
+    const key = rowKey(scope, id);
+    const holds = this.#holds.get(key);
+    if (holds === undefined) return;
+    if (holds > 1) {
+      this.#holds.set(key, holds - 1);
+      return;
+    }
+    this.#holds.delete(key);
+    if (this.#values.delete(key)) this.#touch(key);
+  }
+
+  /** Every write inside `fn` collapses into one notification — one patch frame, one render. */
+  batch<T>(fn: () => T): T {
+    if (this.#changed !== null) return fn();
+    const collected = new Set<RowKey>();
+    this.#changed = collected;
+    try {
+      return fn();
+    } finally {
+      this.#changed = null;
+      if (collected.size > 0) this.#notify(collected);
+    }
+  }
+
+  subscribe(listener: IdentityListener): () => void {
+    this.#listeners.add(listener);
+    return () => {
+      this.#listeners.delete(listener);
+    };
+  }
+
+  /** Held keys. Tests assert on it; nothing in the client branches on a count. */
+  get size(): number {
+    return this.#values.size;
+  }
+
+  #touch(key: RowKey): void {
+    const batch = this.#changed;
+    if (batch !== null) {
+      batch.add(key);
+      return;
+    }
+    this.#notify(new Set([key]));
+  }
+
+  #notify(changed: ReadonlySet<RowKey>): void {
+    for (const listener of this.#listeners) listener(changed);
+  }
+}