@ultimat3/realtime 31.4.2 → 31.5.0

package/CLAUDE.md

@@ -107,6 +107,9 @@ A rule marked `†` has its full text in [`docs/history/realtime-rules.md`](../.
   `live-fanout` tests).
 - **`startLiveReplicator` SUBSCRIBES to `entity.row`/`entity.bulk`**, never a slot: `stop()`
   releases its own; two both hear a write (`live-replicator.test.ts`). Its handlers never throw.
+- **A window is keyed by the PARSED input** (`LiveQueryDefinition.queryId`): a stripped junk key
+  opens no window. An entry is built from what `prepare` returned (`PreparedWindow`), never a
+  re-lookup (`live-definition-input.test.ts`). A cold window is staled only by a table it reads.
 - **A WINDOW is per TENANT** (`windowId(queryHash, tenant)`, `live-tenant.ts`); the read runs as a
   service actor carrying ONLY that org, never the subscriber. †
 - **A `sid` is CLIENT data: a subscription is keyed by `(socket, sid)`** (`subscription-book.ts`);

package/README.md

@@ -366,11 +366,17 @@ Two actors on one live query get two different result sets, and a row that leave
 is delivered to them as a `delete` — never as silence.
 
 **The shared read is a TENANT's, never the node's.** One `(query, input)` is one window per org:
-its id is `windowId(queryHash(name, input), tenant)`, the tenant being the subscriber's
-`actor.orgId`, and its source is read in a context that carries that org and nothing else of any
-subscriber's. So a repo that leaves the tenant to the acting actor — what `x g query --live`
-generates — reads on a sync node exactly as it reads over HTTP, and no org predicate is written
-by hand.
+its id is `windowId(queryHash(name, parsed), tenant)` — `parsed` the input as the query's own
+schema parsed it (`LiveQueryDefinition.queryId`), so a key the schema strips opens no second window
+— the tenant being the subscriber's `actor.orgId`, and its source is read in a context that
+carries that org and nothing else of any subscriber's. So a repo that leaves the tenant to the
+acting actor — what `x g query --live` generates — reads on a sync node exactly as it reads over
+HTTP, and no org predicate is written by hand.
+
+A hand-written `LiveQueryDefinition` (`@ultimat3/realtime/server`) that resolves per input in
+`prepare` returns a `PreparedWindow` — `{ matcher, rowEntity, rowKey }` — and the entry is built
+from that answer, never looked up again: a bounded cache another subscribe evicted in between would
+answer nothing, and the entry would be born reading no table.
 
 | On a sync node | Answer |
 |---|---|
@@ -665,8 +671,9 @@ made it — a key already queued collapses as always, and nothing queued is ever
   `subscribe` is one lane per sid, or per topic name; `hello` and
   the server-authored kinds are unlaned. A lane exists only while work is queued on it, because a
   lane keyed by a client-chosen sid that outlived its work is an unbounded map one socket can grow.
-- **A window's `qid` is `@ultimat3/query`'s `queryHash(name, input)`, qualified by the tenant it
-  is read for** (`windowId`) — `<name>:<first 16 hex of SHA-256(canonicalJson(input))>`, 64 bits
+- **A window's `qid` is `@ultimat3/query`'s `queryHash(name, input)` over the PARSED input,
+  qualified by the tenant it is read for** (`windowId`; a re-seat derives the new tenant's id from
+  the held one, `retenant`, never re-hashing the input as sent) — `<name>:<first 16 hex of SHA-256(canonicalJson(input))>`, 64 bits
   `As of 2026-08` where it was a 32-bit FNV-1a. It is a *sharing* key: a hit is answered with the existing entry and the seated window, both holding the
   first subscriber's input and rows, and input is client-chosen, so a collision is one client served
   out of another's window. This package derives none of its own — `qidOf` was a second spelling of

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/realtime",
-  "version": "31.4.2",
+  "version": "31.5.0",
   "description": "Three-tier realtime: channels, live queries, local-first sync — one protocol, one mutator shape",
   "keywords": [
     "ultimate",
@@ -52,10 +52,10 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/core": "31.4.2",
-    "@ultimat3/entity": "31.4.2",
-    "@ultimat3/policy": "31.4.2",
-    "@ultimat3/query": "31.4.2",
+    "@ultimat3/core": "31.5.0",
+    "@ultimat3/entity": "31.5.0",
+    "@ultimat3/policy": "31.5.0",
+    "@ultimat3/query": "31.5.0",
     "nats": "2.29.3"
   }
 }

package/src/live-contract.ts

@@ -16,6 +16,13 @@ import type { JsonValue, LiveRow } from './json';
 import type { IncrementalMatcher } from './matcher-bridge';
 import type { SyncSocket } from './socket';
 
+/** One input's resolved, subject-less half — what `prepare` hands the entry it is about to build. */
+export interface PreparedWindow {
+  readonly matcher: IncrementalMatcher;
+  readonly rowEntity: string | null;
+  readonly rowKey: ((row: LiveRow) => string) | null;
+}
+
 export interface SnapshotResult<R extends LiveRow = LiveRow> {
   readonly rows: readonly R[];
   readonly lsn: string;
@@ -76,8 +83,18 @@ export interface LiveQueryDefinition<R extends LiveRow = LiveRow> {
    * design — a change event must not await anything — so a definition that has to compile a
    * source or a shape does it here, after `authorize` allowed this subscriber and before the
    * shared window exists.
+   *
+   * What it resolved comes BACK, and the entry is built from that: looked up again by input, a
+   * bounded cache another subscribe evicted in between answered nothing, and the entry was born
+   * reading no table. `undefined` = resolve through `matcher` / `rowEntity` / `rowKey`.
+   */
+  prepare?(input: JsonValue): Promise<PreparedWindow | undefined>;
+  /**
+   * The query id this input names: `queryHash(name, parsed)` over the input the read PARSED, so
+   * a key the schema strips opens no second window. Asked after `authorize`, before `prepare`.
+   * Absent, the registry keys the window by the input as sent.
    */
-  prepare?(input: JsonValue): Promise<void>;
+  queryId?(input: JsonValue): Promise<string>;
 }
 
 /** Who a live subscribe is charged to: the socket's actor, else its address, on the node's clock. */

package/src/live-definition.ts

@@ -18,6 +18,8 @@ import {
 } from '@ultimat3/core';
 import {
   type AnyQuery,
+  parsedQueryInput,
+  QueryInputInvalidError,
   queryHash,
   queryName,
   spendQueryLimit,
@@ -135,9 +137,39 @@ export function liveQueryDefinition(
   const name = queryName(target);
   // Keyed by query id, and holding no subscriber's decision — that is what makes it shareable.
   const windows = new Map<string, SharedWindow>();
+  const maxWindows = finiteOption('live()', 'maxWindows', options.maxWindows ?? 256);
+  // Input as sent → query id of the input as parsed. Bounded like `windows`, for the same reason:
+  // its key is client-chosen. An eviction costs one parse.
+  const ids = new Map<string, string>();
+
+  const queryId = async (input: JsonValue): Promise<string> => {
+    const sent = queryHash(name, input);
+    const known = ids.get(sent);
+    if (known !== undefined) return known;
+    let value: unknown;
+    try {
+      // The query's own capped parse (`MAX_ISSUES`), never the schema called raw: this is client
+      // input, and the read path's bound on what one refusal costs holds here too.
+      value = await parsedQueryInput(target, input);
+    } catch (error) {
+      // A refused input keeps the id of what was sent and is not remembered: `target.live` raises
+      // the query's own `X_INPUT_INVALID` for it, exactly as before.
+      if (error instanceof QueryInputInvalidError) return sent;
+      throw error;
+    }
+    const parsed = queryHash(name, value);
+    ids.set(sent, parsed);
+    evictOldest(ids, maxWindows);
+    return parsed;
+  };
+  /** Synchronous, for a caller that did not take `prepare`'s answer: may miss after an eviction. */
+  const seatedFor = (input: JsonValue): SharedWindow | undefined => {
+    const sent = queryHash(name, input);
+    return windows.get(ids.get(sent) ?? sent);
+  };
 
   const resolve = async (input: JsonValue): Promise<SharedWindow> => {
-    const qid = queryHash(name, input);
+    const qid = await queryId(input);
     const seated = windows.get(qid);
     if (seated !== undefined) return seated;
     const live = await target.live(input, {
@@ -168,7 +200,7 @@ export function liveQueryDefinition(
       },
     };
     windows.set(qid, built);
-    evictOldest(windows, finiteOption('live()', 'maxWindows', options.maxWindows ?? 256));
+    evictOldest(windows, maxWindows);
     return built;
   };
 
@@ -178,8 +210,10 @@ export function liveQueryDefinition(
     // it off the resolved matcher. This is the value for a definition asked before `prepare` ran,
     // and it matches nothing rather than guessing an entity.
     entities: [],
+    queryId,
     prepare: async (input) => {
-      await resolve(input);
+      const { matcher, rowEntity, rowKey } = await resolve(input);
+      return { matcher, rowEntity, rowKey };
     },
     snapshot: async ({ input, tenant, traceparent, phase }): Promise<SnapshotResult> => {
       const window = await resolve(input);
@@ -198,11 +232,11 @@ export function liveQueryDefinition(
       );
       return { rows, lsn };
     },
-    matcher: (input) => windows.get(queryHash(name, input))?.matcher ?? UNRESOLVED,
+    matcher: (input) => seatedFor(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,
+    rowEntity: (input) => seatedFor(input)?.rowEntity ?? null,
+    rowKey: (input) => seatedFor(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.
@@ -216,7 +250,7 @@ export function liveQueryDefinition(
 }
 
 /** Insertion-ordered, so the oldest compiled input is the one that goes. */
-function evictOldest(windows: Map<string, SharedWindow>, max: number): void {
+function evictOldest(windows: Map<string, unknown>, max: number): void {
   while (windows.size > max) {
     const oldest = windows.keys().next();
     if (oldest.done === true) return;

package/src/live-entries.ts

@@ -1,13 +1,98 @@
-// The registry's windows, indexed by the relations each one reads. One owner for both, so an entry
-// added or forgotten can never be in the table and missing from the index (or the reverse): a
-// change then reaches only the windows that read its table, never every window on the node.
+// The registry's windows: born under the node's ceiling, indexed by the relations each one reads,
+// dropped with their retained patches. One owner for all three, so an entry added or forgotten can
+// never be in the table and missing from the index (or the reverse), and a change reaches only the
+// windows that read its table, never every window on the node.
 
-import type { QueryEntry } from './query-window';
+import { finiteOption } from '@ultimat3/core';
+import { SubscriptionLimitError } from './errors';
+import type { JsonValue } from './json';
+import type { LiveQueryDefinition, PreparedWindow } from './live-contract';
+import { DEFAULT_MAX_ENTRIES, type LiveQueryRegistryOptions } from './live-query-options';
+import { type QueryEntry, queryEntry } from './query-window';
+
+/** What the entry table reads off the registry's options. */
+export type LiveEntriesOptions = Pick<
+  LiveQueryRegistryOptions,
+  'source' | 'maxEntries' | 'readDeadlineMs' | 'schedule'
+>;
 
 export class LiveEntries {
   readonly #byQid = new Map<string, QueryEntry>();
   /** `shape.entities` → the entries reading it. A shape is fixed at birth, so this never moves. */
   readonly #byTable = new Map<string, Set<QueryEntry>>();
+  readonly #options: LiveEntriesOptions;
+  readonly #maxEntries: number;
+
+  constructor(options: LiveEntriesOptions) {
+    this.#options = options;
+    this.#maxEntries = finiteOption(
+      'the live-query registry',
+      'maxEntries',
+      options.maxEntries ?? DEFAULT_MAX_ENTRIES,
+    );
+  }
+
+  /**
+   * The entry for `qid`, born now if none holds it — from `prepare`'s answer when there is one,
+   * never a second lookup by input (`QueryEntry`'s `prepared`).
+   */
+  seat(
+    qid: string,
+    definition: LiveQueryDefinition,
+    input: JsonValue,
+    tenant: string | null,
+    prepared: PreparedWindow | undefined,
+  ): QueryEntry {
+    const existing = this.#byQid.get(qid);
+    if (existing) return existing;
+    // The node-wide ceiling, refused where the entry would be born. `qid` derives from
+    // client-chosen input, so one socket varying it mints a matcher, a row window and a
+    // `WindowLock` per value, and every change then fans out over all of them.
+    if (this.#byQid.size >= this.#maxEntries) {
+      throw new SubscriptionLimitError({
+        scope: 'node',
+        id: definition.name,
+        limit: this.#maxEntries,
+        knob: 'maxEntries',
+      });
+    }
+    const matcher = prepared?.matcher ?? definition.matcher(input);
+    const created = queryEntry(qid, definition, input, matcher, {
+      readDeadlineMs: this.#options.readDeadlineMs,
+      schedule: this.#options.schedule,
+      tenant,
+      prepared,
+    });
+    this.add(created);
+    return created;
+  }
+
+  /**
+   * An entry with no subscribers left, gone with its retained patches. `forget` had no caller once:
+   * the entry was dropped and the `ResumeSource` never told, so its ring sat at full capacity until
+   * the LRU happened to evict it — a client-chosen input's memory outliving the last subscriber.
+   */
+  release(qid: string): void {
+    this.delete(qid);
+    this.#options.source.forget?.(qid);
+  }
+
+  /**
+   * An entry nothing is holding, released — for the case where a subscriber never arrived. Five
+   * cold failures against `maxEntries: 5` used to refuse every later subscribe on the node with
+   * `X_SUBSCRIPTION_LIMIT`, forever, after the database recovered.
+   */
+  dropIfUnheld(qid: string, entry: QueryEntry): void {
+    // Identity, never presence: an entry this subscribe did not create may already have been
+    // dropped and re-created under the same qid.
+    if (this.#byQid.get(qid) !== entry) return;
+    if (entry.subscribers.size !== 0) return;
+    // A read published on the entry belongs to a subscriber that has not attached yet — it owns
+    // the entry's fate, and dropping it here would leave that subscriber holding a window no
+    // change is ever fanned out to.
+    if (entry.reading !== null) return;
+    this.release(qid);
+  }
 
   get size(): number {
     return this.#byQid.size;
@@ -53,18 +138,19 @@ export class LiveEntries {
   }
 
   /**
-   * Every window one change is work for: its table's readers, plus every window that owes a
-   * read whatever it reads — a `stale` one is repaired by the next change to reach it, and one no
-   * read has landed in yet marks itself stale so its in-flight read is followed by a fresh one
-   * (`live-fanout.ts`). Those two are a boolean pair per entry, read without a lane; the expensive
-   * part — a lane entered, a closure queued, a fanout awaited — is paid by these entries only.
+   * Every window one change is work for: its table's readers, plus every `stale` one whatever it
+   * reads — the next change to reach it repairs it. A window no read has landed in yet is work
+   * only as a reader (`live-fanout.ts` stales it so its in-flight read is followed by a fresh
+   * one): a change to a table it does not read is no hole in that read. `stale` is a boolean per
+   * entry, read without a lane; the expensive part — a lane entered, a closure queued, a fanout
+   * awaited — is paid by these entries only.
    * Measured: 10k windows on other tables, 34.6 ms → 0.23 ms per change (29 → 4,430/s).
    */
   targets(table: string): QueryEntry[] {
     const readers = this.readersOf(table);
     const out = [...readers];
     for (const entry of this.#byQid.values()) {
-      if ((entry.stale || entry.applied === 0) && !readers.has(entry)) out.push(entry);
+      if (entry.stale && !readers.has(entry)) out.push(entry);
     }
     return out;
   }

package/src/live-fanout.ts

@@ -49,9 +49,11 @@ export async function fanoutChange(
   // 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.
+  // read that lands is applied and followed by one that includes this change. Only a change to a
+  // relation it READS (the guard `truncated` uses): any other is no hole in that read, and staling
+  // on it made every new window on a busy node read twice and re-snapshot every subscriber.
   if (entry.applied === 0) {
-    entry.stale = true;
+    if (entry.shape.entities.includes(change.table)) entry.stale = true;
     return { sent: 0, stale: 0 };
   }
   if (change.op === 'truncate') return await truncated(deps, entry, change);

package/src/live-query.ts

@@ -6,23 +6,24 @@
 // policy is never sent to that actor — it arrives as a `delete` if they hold it, and is dropped
 // otherwise.
 
-import { type Clock, finiteOption, systemClock, uuidV7 } from '@ultimat3/core';
+import { type Clock, systemClock, uuidV7 } from '@ultimat3/core';
 import { queryHash } from '@ultimat3/query';
 import type { ChangeEvent } from './changefeed';
 import { type LiveCursor, makeCursor } from './cursor';
-import { LiveQueryUnknownError, SubscriptionLimitError } from './errors';
+import { LiveQueryUnknownError } from './errors';
 import type { JsonValue } from './json';
 import type { LiveQueryDefinition, LiveSubscription, SnapshotResult } from './live-contract';
 import { DeliveryCounts, deliverChange } from './live-deliver';
 import { LiveEntries } from './live-entries';
-import { type FanoutDeps, repairSubscriber, repairWindow, snapshotFrame } from './live-fanout';
+import { type FanoutDeps, repairWindow, snapshotFrame } from './live-fanout';
 import { floorAfterRead } from './live-floor';
-import { DEFAULT_MAX_ENTRIES, type LiveQueryRegistryOptions } from './live-query-options';
+import type { LiveQueryRegistryOptions } from './live-query-options';
 import { reauthorizeSocket } from './live-reauth';
+import { repairEveryWindow, repairSocket } from './live-repair';
 import { resumeOnto } from './live-resume';
 import { type Charge, type SubscribeArgs, spendOnce } from './live-spend';
 import { liveTenantOf, windowId } from './live-tenant';
-import { fillWindow, noteTraceparent, type QueryEntry, queryEntry } from './query-window';
+import { fillWindow, noteTraceparent, type QueryEntry } from './query-window';
 import type { SyncSocket } from './socket';
 import { type Subscriber, SubscriberGate } from './subscriber-gate';
 import { SubscriptionBook, subscriptionKey } from './subscription-book';
@@ -37,13 +38,12 @@ export {
 export class LiveQueryRegistry {
   readonly #definitions = new Map<string, LiveQueryDefinition>();
   /** Indexed by the relations each window reads (`live-entries.ts`): a change is work for few. */
-  readonly #entries = new LiveEntries();
+  readonly #entries: LiveEntries;
   /** Keyed by `(socket, sid)`, never by `sid` alone — `subscription-book.ts` owns why. */
   readonly #book: SubscriptionBook;
   readonly #options: LiveQueryRegistryOptions;
   readonly #clock: Clock;
   readonly #gate: SubscriberGate;
-  readonly #maxEntries: number;
   /** What one lane needs, and nothing this class holds beyond it. */
   readonly #fanout: FanoutDeps;
   #lastLsn = '';
@@ -58,11 +58,7 @@ export class LiveQueryRegistry {
     this.#options = options;
     this.#clock = options.clock ?? systemClock;
     this.#gate = new SubscriberGate(options);
-    this.#maxEntries = finiteOption(
-      'the live-query registry',
-      'maxEntries',
-      options.maxEntries ?? DEFAULT_MAX_ENTRIES,
-    );
+    this.#entries = new LiveEntries(options);
     // The book owns the caps because it is the only thing that can answer them in O(1).
     this.#book = new SubscriptionBook(options);
     this.#fanout = { gate: this.#gate, source: options.source, clock: this.#clock };
@@ -191,12 +187,14 @@ export class LiveQueryRegistry {
     // The window is the subscriber's TENANT's: two orgs on one `(query, input)` are two entries,
     // two reads and two retained rings, so no shared row ever stands between them and a policy.
     const tenant = liveTenantOf(args.socket.actor);
-    const qid = windowId(queryHash(args.name, args.input), tenant);
+    // The PARSED input's id when the definition can name it: a key the schema strips is no window.
+    const queryId = (await definition.queryId?.(args.input)) ?? queryHash(args.name, args.input);
+    const qid = windowId(queryId, tenant);
     // After this subscriber's own decision, never before it: resolving a shape for a caller who
     // may not subscribe is work an unauthorized client gets to schedule.
-    await definition.prepare?.(args.input);
+    const prepared = await definition.prepare?.(args.input);
 
-    const entry = this.#entryFor(qid, definition, args.input, tenant);
+    const entry = this.#entries.seat(qid, definition, args.input, tenant, prepared);
     noteTraceparent(entry, args.traceparent);
     try {
       // Charged where a read happens, never from the cursor's say-so (`live-spend.ts`).
@@ -206,7 +204,7 @@ export class LiveQueryRegistry {
       // The entry was born above, before anything could fill it. Everything below can throw — the
       // snapshot, the resume, the window's own read deadline — and `unsubscribe` is the only other
       // removal path, reachable only through a subscription that in this case was never attached.
-      this.#dropIfUnheld(qid, entry);
+      this.#entries.dropIfUnheld(qid, entry);
       throw error;
     }
   }
@@ -275,30 +273,7 @@ export class LiveQueryRegistry {
     entry.subscribers.delete(subscriptionKey(socketId, sid));
     // An entry with no subscribers stops costing a matcher and a change window.
     if (entry.subscribers.size !== 0) return;
-    this.#entries.delete(subscription.qid);
-    // And the retained patches go with it. `forget` had no caller: the entry was dropped here and
-    // the `ResumeSource` was never told, so its ring for that qid sat at full capacity until the
-    // LRU happened to evict it — a client-chosen input's memory outliving the last subscriber.
-    this.#options.source.forget?.(subscription.qid);
-  }
-
-  /**
-   * An entry nothing is holding, dropped with the retained patches that were kept for it — the
-   * same three steps `unsubscribe` takes when the last subscriber leaves, for the case where a
-   * subscriber never arrived. Five cold failures against `maxEntries: 5` used to refuse every
-   * later subscribe on the node with `X_SUBSCRIPTION_LIMIT`, forever, after the database recovered.
-   */
-  #dropIfUnheld(qid: string, entry: QueryEntry): void {
-    // Identity, never presence: an entry this subscribe did not create may already have been
-    // dropped and re-created under the same qid.
-    if (this.#entries.get(qid) !== entry) return;
-    if (entry.subscribers.size !== 0) return;
-    // A read published on the entry belongs to a subscriber that has not attached yet — it owns
-    // the entry's fate, and dropping it here would leave that subscriber holding a window no
-    // change is ever fanned out to.
-    if (entry.reading !== null) return;
-    this.#entries.delete(qid);
-    this.#options.source.forget?.(qid);
+    this.#entries.release(subscription.qid);
   }
 
   unsubscribeSocket(socketId: string): void {
@@ -326,6 +301,7 @@ export class LiveQueryRegistry {
         book: this.#book,
         gate: this.#gate,
         unsubscribe: (socketId, sid) => this.unsubscribe(socketId, sid),
+        tenantOf: (qid) => this.#entries.get(qid)?.tenant,
         // A re-seat is the subscription it already was, so it is never charged again.
         resubscribe: (args) => this.#subscribe(args, { due: false }),
       },
@@ -353,37 +329,14 @@ export class LiveQueryRegistry {
     );
   }
 
-  /**
-   * This socket's marked subscriptions, repaired now it can take a frame: Bun's `drain`. Frames that
-   * left. Every lane is entered before any is awaited, as `deliverChange` does, so one slow policy
-   * pass holds up its own query id and nothing else.
-   */
-  async repair(socket: SyncSocket): Promise<number> {
-    const repairs = [...socket.desynced].map(async (sid) => {
-      const subscription = this.#book.get(socket.id, sid);
-      const entry = subscription && this.#entries.get(subscription.qid);
-      if (!subscription || !entry) return false;
-      // Its rows are about to be replaced, so wait: this drain is the only one coming. Bounded by
-      // the read's own deadline, and a read that failed staled the window, which refuses below.
-      await entry.reading?.result.catch(() => undefined);
-      return await entry.lock.run(() => repairSubscriber(this.#fanout, entry, subscription));
-    });
-    return (await Promise.all(repairs)).filter(Boolean).length;
+  /** This socket's marked subscriptions, repaired now it can take a frame: Bun's `drain`. */
+  repair(socket: SyncSocket): Promise<number> {
+    return repairSocket(this.#fanout, this.#book, this.#entries, socket);
   }
 
   /** The node's sweep: every window owing a mark, each in its lane, one read a window at most. */
-  async repairMarked(): Promise<number> {
-    const lanes = [...this.#entries.values()].map((entry) =>
-      entry.lock.run(() => repairWindow(this.#fanout, entry)),
-    );
-    let sent = 0;
-    let failure: { readonly error: unknown } | null = null;
-    for (const lane of await Promise.allSettled(lanes)) {
-      if (lane.status === 'fulfilled') sent += lane.value;
-      else failure ??= { error: lane.reason };
-    }
-    if (failure !== null) throw failure.error;
-    return sent;
+  repairMarked(): Promise<number> {
+    return repairEveryWindow(this.#fanout, this.#entries);
   }
 
   #attachUnlessGone(
@@ -427,34 +380,6 @@ export class LiveQueryRegistry {
     return subscription;
   }
 
-  #entryFor(
-    qid: string,
-    definition: LiveQueryDefinition,
-    input: JsonValue,
-    tenant: string | null,
-  ): QueryEntry {
-    const existing = this.#entries.get(qid);
-    if (existing) return existing;
-    // The node-wide ceiling, refused where the entry would be born. `qid` derives from
-    // client-chosen input, so one socket varying it mints a matcher, a row window and a
-    // `WindowLock` per value, and every change then fans out over all of them.
-    if (this.#entries.size >= this.#maxEntries) {
-      throw new SubscriptionLimitError({
-        scope: 'node',
-        id: definition.name,
-        limit: this.#maxEntries,
-        knob: 'maxEntries',
-      });
-    }
-    const created = queryEntry(qid, definition, input, definition.matcher(input), {
-      readDeadlineMs: this.#options.readDeadlineMs,
-      schedule: this.#options.schedule,
-      tenant,
-    });
-    this.#entries.add(created);
-    return created;
-  }
-
   /**
    * One read, then one policy pass per subscriber. Never one read per subscriber — and never a
    * partial pass: a gate that fails raises out of `subscribe`, because a snapshot missing the rows

package/src/live-reauth.ts

@@ -3,12 +3,11 @@
 // rather than carried past a ceiling. Split from `live-query.ts` at its size ceiling: the registry
 // owns the entry table, this owns what a re-authorization does to one socket's subscriptions.
 
-import { queryHash } from '@ultimat3/query';
 import { isPolicyDenial } from './errors';
 import type { LiveSubscription } from './live-contract';
 import { refuseSubscription } from './live-refusal';
 import type { SubscribeArgs } from './live-spend';
-import { liveTenantOf, windowId } from './live-tenant';
+import { liveTenantOf, retenant } from './live-tenant';
 import type { SyncSocket } from './socket';
 import type { SubscriberGate } from './subscriber-gate';
 import type { SubscriptionBook } from './subscription-book';
@@ -19,6 +18,8 @@ export interface ReauthDeps {
   readonly book: SubscriptionBook;
   readonly gate: SubscriberGate;
   unsubscribe(socketId: string, sid: string): void;
+  /** The tenant a window is read for; `undefined` when no entry holds that id. */
+  tenantOf(qid: string): string | null | undefined;
   /** Subscribe again under the same sid, uncharged — a re-seat is not a new subscription. */
   resubscribe(args: SubscribeArgs): Promise<{ readonly frame: Frame }>;
 }
@@ -94,8 +95,14 @@ async function reseat(
   failed: { readonly error: unknown } | undefined,
 ): Promise<boolean> {
   const { sid, input, definition } = subscription;
-  const wanted = windowId(queryHash(definition.name, input), liveTenantOf(socket.actor));
-  if (wanted === subscription.qid) return false;
+  const tenant = liveTenantOf(socket.actor);
+  const seated = deps.tenantOf(subscription.qid);
+  // Derived from the window held, never re-hashed from the input: a window is keyed by the PARSED
+  // input (`LiveQueryDefinition.queryId`), so a hash of the input as sent names another id whenever
+  // the schema stripped a key, and every re-auth re-seated that subscription for nothing.
+  if (seated === tenant) return false;
+  const wanted =
+    seated === undefined ? subscription.qid : retenant(subscription.qid, seated, tenant);
   deps.unsubscribe(socket.id, sid);
   if (failed !== undefined) {
     refuseSubscription(socket, sid, failed.error);

package/src/live-repair.ts

@@ -0,0 +1,47 @@
+// The registry's two repair paths, each window in its own lane: one socket's marked subscriptions
+// when it can take a frame again (Bun's `drain`), and the node's sweep over every window owing a
+// mark. Split from `live-query.ts` at its size ceiling: the registry owns the tables, this owns
+// what a repair does with them.
+
+import type { LiveEntries } from './live-entries';
+import { type FanoutDeps, repairSubscriber, repairWindow } from './live-fanout';
+import type { SyncSocket } from './socket';
+import type { SubscriptionBook } from './subscription-book';
+
+/**
+ * This socket's marked subscriptions, repaired now. Frames that left. Every lane is entered before
+ * any is awaited, as `deliverChange` does, so one slow policy pass holds up its own query id and
+ * nothing else.
+ */
+export async function repairSocket(
+  fanout: FanoutDeps,
+  book: SubscriptionBook,
+  entries: LiveEntries,
+  socket: SyncSocket,
+): Promise<number> {
+  const repairs = [...socket.desynced].map(async (sid) => {
+    const subscription = book.get(socket.id, sid);
+    const entry = subscription && entries.get(subscription.qid);
+    if (!subscription || !entry) return false;
+    // Its rows are about to be replaced, so wait: this drain is the only one coming. Bounded by
+    // the read's own deadline, and a read that failed staled the window, which refuses below.
+    await entry.reading?.result.catch(() => undefined);
+    return await entry.lock.run(() => repairSubscriber(fanout, entry, subscription));
+  });
+  return (await Promise.all(repairs)).filter(Boolean).length;
+}
+
+/** The node's sweep: every window owing a mark, each in its lane, one read a window at most. */
+export async function repairEveryWindow(fanout: FanoutDeps, entries: LiveEntries): Promise<number> {
+  const lanes = [...entries.values()].map((entry) =>
+    entry.lock.run(() => repairWindow(fanout, entry)),
+  );
+  let sent = 0;
+  let failure: { readonly error: unknown } | null = null;
+  for (const lane of await Promise.allSettled(lanes)) {
+    if (lane.status === 'fulfilled') sent += lane.value;
+    else failure ??= { error: lane.reason };
+  }
+  if (failure !== null) throw failure.error;
+  return sent;
+}

package/src/live-tenant.ts

@@ -23,3 +23,15 @@ export function liveTenantOf(actor: Actor | null): string | null {
 export function windowId(queryId: string, tenant: string | null): string {
   return tenant === null ? queryId : JSON.stringify([queryId, tenant]);
 }
+
+/**
+ * The same query id, read for another tenant: `windowId`'s inverse, then `windowId` again. A
+ * re-seat asks this of the window it holds rather than re-hashing the input, because the id is
+ * taken over the PARSED input (`LiveQueryDefinition.queryId`), which the input as sent is not.
+ */
+export function retenant(qid: string, from: string | null, to: string | null): string {
+  if (from === null) return windowId(qid, to);
+  const pair: unknown = JSON.parse(qid);
+  const queryId = Array.isArray(pair) && typeof pair[0] === 'string' ? pair[0] : qid;
+  return windowId(queryId, to);
+}

package/src/query-window.ts

@@ -5,7 +5,12 @@
 import type { LiveReadPhase } from '@ultimat3/query';
 import { WindowReadTimeoutError } from './errors';
 import type { JsonValue, LiveRow } from './json';
-import type { LiveQueryDefinition, LiveSubscription, SnapshotResult } from './live-contract';
+import type {
+  LiveQueryDefinition,
+  LiveSubscription,
+  PreparedWindow,
+  SnapshotResult,
+} from './live-contract';
 import type { IncrementalMatcher, SubscriptionShape } from './matcher-bridge';
 import type { Scheduler } from './thundering-herd';
 import { timeoutScheduler } from './thundering-herd';
@@ -92,7 +97,14 @@ export function queryEntry(
   definition: LiveQueryDefinition,
   input: JsonValue,
   matcher: IncrementalMatcher,
-  options?: EntryOptions & { readonly tenant?: string | null },
+  options?: EntryOptions & {
+    readonly tenant?: string | null;
+    /**
+     * What `prepare` resolved for this input. Its row scope is taken as given, never looked up
+     * again by input: a bounded cache another subscribe evicted in between answers nothing.
+     */
+    readonly prepared?: PreparedWindow | undefined;
+  },
 ): QueryEntry {
   const tenant = options?.tenant ?? null;
   return {
@@ -102,8 +114,7 @@ export function queryEntry(
     tenant,
     // Resolved with the matcher, from the same build: `prepare` has already run, so a definition
     // that compiles its shape per input can answer.
-    rowEntity: definition.rowEntity?.(input) ?? null,
-    rowKey: definition.rowKey?.(input) ?? null,
+    ...rowScope(definition, input, options?.prepared),
     shape: {
       qid,
       // The matcher knows the dependency set this *input* produced; `definition.entities` is the
@@ -130,6 +141,25 @@ export function queryEntry(
   };
 }
 
+/**
+ * The identity scope an entry's rows travel under: what `prepare` resolved when it answered, else
+ * asked of the definition by input. Only a scope the definition states — one with no `rowEntity`
+ * sends none, whatever it resolved.
+ */
+function rowScope(
+  definition: LiveQueryDefinition,
+  input: JsonValue,
+  prepared: PreparedWindow | undefined,
+): Pick<QueryEntry, 'rowEntity' | 'rowKey'> {
+  const entity = definition.rowEntity;
+  const key = definition.rowKey;
+  return {
+    rowEntity:
+      entity === undefined ? null : prepared ? prepared.rowEntity : (entity(input) ?? null),
+    rowKey: key === undefined ? null : prepared ? prepared.rowKey : (key(input) ?? null),
+  };
+}
+
 /**
  * Remember the subscriber's `traceparent` for the window's next read. Bounded and never parsed
  * here: a value is either a string a W3C header could be or it is dropped, and `traceLiveRead`

package/src/server.ts

@@ -108,6 +108,7 @@ export {
 export type {
   LiveQueryDefinition,
   LiveSubscription,
+  PreparedWindow,
   SnapshotResult,
 } from './live-contract';
 export { type LiveDefinitionOptions, liveQueryDefinition } from './live-definition';