@ultimat3/realtime 22.15.0 → 24.0.0

package/src/errors.ts

@@ -1,7 +1,7 @@
 // Realtime's X_* codes. Every throw in this package goes through one of these classes so
 // the same string renders in the terminal, the browser overlay, and `--json`.
 
-import { registerErrorCodes } from '@ultimat3/core';
+import { isFixShellSafe, registerErrorCodes, renderFixShellArg } from '@ultimat3/core';
 import { RealtimeError } from './realtime-error';
 
 /** Codes this package declares and owns. */
@@ -36,6 +36,7 @@ export const REALTIME_OWNED_ERROR_CODES = [
   'X_REALTIME_TOPOLOGY',
   'X_REPLICATION_TLS',
   'X_SOCKET_ORIGIN_REFUSED',
+  'X_OFFLINE_QUEUE_ABANDONED',
 ] as const;
 
 /**
@@ -61,6 +62,24 @@ export const POLICY_DENIAL_CODES: ReadonlySet<string> = new Set([
   'X_UNAUTHENTICATED',
 ]);
 
+/**
+ * `@ultimat3/entity`'s tenant guard refusing a read FOR THIS ACTOR: it carries no org, names
+ * another one, or reached across tenants without the capability. Verdicts about who is asking, so
+ * a channel's row loader raising one is a denial. `X_TENANCY_UNSCOPED` is deliberately absent —
+ * that is a query written without a tenant predicate, which is the app's defect and no decision.
+ * Spelled by name, never matched by prefix: a code's meaning is its owner's, not its shape's.
+ */
+export const TENANCY_DENIAL_CODES: ReadonlySet<string> = new Set([
+  'X_TENANCY_ACTOR_ORG_REQUIRED',
+  'X_TENANCY_ACTOR_MISMATCH',
+  'X_TENANCY_CROSS_DENIED',
+]);
+
+/** True when the tenant guard decided against the actor — see `TENANCY_DENIAL_CODES`. */
+export function isTenancyDenial(error: unknown): boolean {
+  return TENANCY_DENIAL_CODES.has(codeOf(error) ?? '');
+}
+
 /**
  * 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
@@ -146,6 +165,7 @@ export const REALTIME_ERROR_TITLES: Readonly<Record<RealtimeOwnedErrorCode, stri
   X_REALTIME_TOPOLOGY: 'a sync node boots on a real database with no reachable change feed',
   X_REPLICATION_TLS: 'the replication connection failed TLS',
   X_SOCKET_ORIGIN_REFUSED: 'the websocket upgrade came from another origin',
+  X_OFFLINE_QUEUE_ABANDONED: 'a write was queued after its page changed principal',
 };
 
 // One unconditional call, so a second package claiming one of realtime's codes throws
@@ -159,6 +179,7 @@ registerErrorCodes(
 export {
   CursorStaleError,
   LocalStoreUnavailableError,
+  OfflineQueueAbandonedError,
   ProtocolVersionError,
   RealtimeUninstalledError,
   RebaseConflictError,
@@ -300,17 +321,33 @@ export class TransportProtocolError extends RealtimeError {
 }
 
 /**
- * A subscribable read projected a row with no `id`. Patches, cursors and the local store all
- * address a row by `id`, so such a row cannot be delivered — and delivering it anyway produces a
- * subscription that looks correct until the first update nobody can apply.
+ * A subscribable read projected a row with no usable `id`. Patches, cursors and the local store all
+ * address a row by a text `id`, so such a row cannot be delivered — and delivering it anyway
+ * produces a subscription that looks correct until the first update nobody can apply.
+ *
+ * `idType` is set when the row HAS an id that is neither text nor a safe integer (the one numeric
+ * shape the change feed and the snapshot both stringify): "select the primary key" is then the
+ * wrong instruction, because the key is selected.
  */
 export class LiveRowUnidentifiedError extends RealtimeError {
-  constructor(args: { query: string; keys: readonly string[] }) {
-    super({
-      code: 'X_LIVE_ROW_UNIDENTIFIED',
-      cause: `live query "${args.query}" returned a row with no id (columns: ${args.keys.join(', ') || 'none'})`,
-      fix: `select the primary key in ${args.query}'s sql(), or drop live: true from it`,
-    });
+  constructor(args: { query: string; keys: readonly string[]; idType?: string }) {
+    const columns = args.keys.join(', ') || 'none';
+    super(
+      args.idType === undefined
+        ? {
+            code: 'X_LIVE_ROW_UNIDENTIFIED',
+            cause: `live query "${args.query}" returned a row with no id (columns: ${columns})`,
+            fix: `select the primary key in ${args.query}'s sql(), or drop live: true from it`,
+          }
+        : {
+            code: 'X_LIVE_ROW_UNIDENTIFIED',
+            cause: `live query "${args.query}" returned a row whose id is a ${args.idType}, not text or a safe integer — a live row is addressed by a text id, so project the key as text (a uuid or text column) or drop live: true from the query`,
+            // A name the shell would not read verbatim does not travel: the list names it instead.
+            fix: isFixShellSafe(args.query)
+              ? `x queries describe ${renderFixShellArg(args.query, 'name')} --json`
+              : 'x queries list --json',
+          },
+    );
   }
 }
 
@@ -363,11 +400,21 @@ export class SocketUnauthenticatedError extends RealtimeError {
  * the accept budget, so a hostile page costs neither.
  */
 export class SocketOriginRefusedError extends RealtimeError {
-  constructor(args: { reason: string }) {
+  constructor(args: { reason: string; asked: string | null; admitted: readonly string[] }) {
+    // The asking origin is a request header: it travels only as the origin a URL parser read out
+    // of it AND only when the shell screen carries it verbatim, so neither the cause nor the
+    // pasted `export` can hold anything the client wrote beyond a scheme, a host and a port.
+    const parsed = URL.parse(args.asked ?? '')?.origin;
+    const asked = isFixShellSafe(parsed) ? parsed : null;
+    const { admitted } = args;
+    const list =
+      admitted.length === 0
+        ? 'only the origin it was reached on (no APP_URL declared)'
+        : `only ${admitted.join(', ')}`;
     super({
       code: 'X_SOCKET_ORIGIN_REFUSED',
-      cause: `the websocket upgrade was refused: ${args.reason}`,
-      fix: 'export APP_URL="https://www.example.com"   # on the sync role: the origin the page is served on (or createSyncNode({ allowedOrigins }))',
+      cause: `the websocket upgrade was refused: ${args.reason} — asked from ${asked ?? 'an origin that cannot be rendered'}; this node admits ${list}`,
+      fix: `export APP_URL=${asked ?? 'https://www.example.com'}   # on the sync role, and only when that is the origin your pages are served on (or createSyncNode({ allowedOrigins }))`,
     });
   }
 }
@@ -405,13 +452,17 @@ export class WindowReadTimeoutError extends RealtimeError {
   }
 }
 
-/** 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 }) {
+/**
+ * A grant's `refresh()` — the app's token service — did not answer inside its deadline. The grant
+ * is NOT renewed and NOT revoked: it stays expired and the next re-auth pass asks again. What the
+ * deadline buys is the rest of the pass, which one call that never settles used to park forever.
+ */
+export class GrantRefreshTimeoutError extends RealtimeError {
+  constructor(args: { socketId: string; afterMs: number }) {
     super({
-      code: 'X_NOT_IMPLEMENTED',
-      cause: `${args.what} is interface-complete but not implemented in this build`,
-      fix: args.fix,
+      code: 'X_TIMEOUT',
+      cause: `refresh() for the grant of socket ${args.socketId} did not answer within ${args.afterMs}ms, so the re-auth pass moved on; the grant stays expired and is asked again on the next pass`,
+      fix: 'x doctor --json',
     });
   }
 }

package/src/fanout.ts

@@ -36,6 +36,14 @@ export interface Transport {
   publish(subject: string, payload: string): Promise<void>;
   subscribe(subject: string, handler: TransportHandler): Promise<TransportSubscription>;
   readonly shared: TransportSet;
+  /**
+   * Told each time the connection behind this transport comes back from a drop. Fanout is
+   * at-most-once, so whatever was published in between never arrived — and with no later message
+   * there is no sequence number to notice it by. A subscriber that keeps derived state (a `sync`
+   * node's windows) invalidates it here. Returns the unsubscribe. A transport with no connection
+   * to lose never calls the listener.
+   */
+  onReconnect(listener: () => void): () => void;
   close(): Promise<void>;
 }
 
@@ -125,6 +133,11 @@ export class InProcessTransport implements Transport {
     }
   }
 
+  /** One process, no connection: there is nothing to come back from, so nothing is ever said. */
+  onReconnect(): () => void {
+    return () => undefined;
+  }
+
   async subscribe(subject: string, handler: TransportHandler): Promise<TransportSubscription> {
     this.#assertOpen();
     const handlers = this.#handlers.get(subject) ?? new Set<TransportHandler>();

package/src/index.ts

@@ -62,7 +62,7 @@ export {
   FrameRateLimitError,
   LiveQueryUnknownError,
   LiveRowUnidentifiedError,
-  NotImplementedError,
+  OfflineQueueAbandonedError,
   ProtocolVersionError,
   REALTIME_ERROR_CODES,
   REALTIME_ERROR_TITLES,

package/src/live-contract.ts

@@ -26,8 +26,12 @@ export interface LiveQueryDefinition<R extends Row = Row> {
   readonly entities: readonly string[];
   /** Read set. Lets the pre-filter skip updates that touch no column this query reads. */
   readonly columns?: readonly string[];
-  /** Bounded read (`orderBy` + `limit`, enforced by `x verify`), unfiltered by policy. */
-  snapshot(args: { input: JsonValue }): Promise<SnapshotResult<R>>;
+  /**
+   * Bounded read (`orderBy` + `limit`, enforced by `x verify`), unfiltered by policy — and read
+   * FOR `tenant`: the org of the subscribers this window serves, `null` for subscribers that carry
+   * none. A window is keyed by it (`live-tenant.ts`), so one read is never two orgs' rows.
+   */
+  snapshot(args: { input: JsonValue; tenant: string | null }): Promise<SnapshotResult<R>>;
   /** Subscribe-time gate. Throws to deny — the same `policy` used by HTTP, jobs, and MCP. */
   authorize?(args: { actor: Actor | null; input: JsonValue }): void | Promise<void>;
   /** Row-level gate, evaluated per subscriber. The only row filter in the pipeline. */

package/src/live-definition.ts

@@ -9,7 +9,7 @@
 // every time. Collapsing the second onto the first is privilege escalation with a cache hit rate.
 
 import type { Ctx } from '@ultimat3/core';
-import { finiteOption } from '@ultimat3/core';
+import { finiteOption, runWithContext, serviceActor, withChildContext } from '@ultimat3/core';
 import { type AnyQuery, queryHash, queryName } from '@ultimat3/query';
 import { LiveRowUnidentifiedError } from './errors';
 import { isRow, type JsonValue, type Row } from './json';
@@ -22,12 +22,15 @@ export interface LiveDefinitionOptions {
   /**
    * The node's own context — never a subscriber's. It supplies services, clock and locale to the
    * shared read; it supplies no authority, because that read is built with the query's policy
-   * switched off and every row leaving it is gated per subscriber.
+   * switched off and every row leaving it is gated per subscriber. The read itself runs in a CHILD
+   * of it that carries the window's tenant and nothing else of any subscriber's (`readFor`).
    */
   readonly ctx: Ctx;
   /**
-   * Where the shared window sits in the change stream, asked at snapshot time. Without a feed
-   * position a reconnect can only re-snapshot, so a node with a replicator should pass its lsn.
+   * Where the shared window sits in the change stream, asked at snapshot time — the node's newest
+   * received change (`registry.lastLsn`). Omitted, or answering `''` before the first change, the
+   * snapshot claims no position and the retained ring is floored by its first patch instead: a
+   * cursor minted before that patch re-snapshots, one that received it resumes as a delta.
    */
   readonly lsn?: () => string;
   /** Pins the reconnect epoch in tests; the server derives it from the build. */
@@ -82,6 +85,25 @@ const UNRESOLVED: IncrementalMatcher = {
   match: () => ({ patches: [], refill: true }),
 };
 
+/** Who a shared read runs as: the node, in one org. Never a subscriber — a window has many. */
+const LIVE_READER_ID = 'live-window';
+
+/**
+ * Run one shared read FOR a tenant: inside the node's context, as a service actor that carries the
+ * window's org and no subscriber's identity, roles or grants. `@ultimat3/entity`'s tenant guard
+ * derives from the ambient context, so this is what makes a repo that leaves the tenant to the
+ * acting actor read on a sync node exactly as it reads over HTTP — and what refuses a read that
+ * names another org (`X_TENANCY_ACTOR_MISMATCH`), which with NO context was simply answered.
+ *
+ * `tenant === null` runs under the node's own actor, which has no org: a tenant-scoped read is
+ * then `X_TENANCY_ACTOR_ORG_REQUIRED`, the verdict the same anonymous read gets over HTTP.
+ */
+function readFor<T>(ctx: Ctx, tenant: string | null, read: () => Promise<T>): Promise<T> {
+  if (tenant === null) return runWithContext(ctx, read);
+  const actor = serviceActor({ id: LIVE_READER_ID, orgId: tenant });
+  return runWithContext(ctx, () => withChildContext({ actor }, read));
+}
+
 /**
  * Registrable definition for one declared query. `register` takes it by name, so what comes back
  * is input-independent: the per-input half is resolved by `prepare`, which the registry awaits
@@ -140,13 +162,16 @@ export function liveQueryDefinition(
     prepare: async (input) => {
       await resolve(input);
     },
-    snapshot: async ({ input }): Promise<SnapshotResult> => {
+    snapshot: async ({ input, tenant }): Promise<SnapshotResult> => {
       const window = await resolve(input);
       // 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.
+      // `''` when the node holds no position — no `lsn` option, or no change received yet. Never
+      // a made-up one: a position the node never held becomes a ring floor every foreign cursor
+      // is "inside", and the client that resumed there kept rows this node never patched.
       const lsn = options.lsn?.() ?? '';
-      return { rows: await window.read(), lsn };
+      return { rows: await readFor(options.ctx, tenant, () => 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
@@ -171,15 +196,25 @@ function evictOldest(windows: Map<string, SharedWindow>, max: number): void {
 }
 
 /**
- * Rows crossing the wire are addressed by `id` — patches, cursors and the local store all key on
- * it. A projection without one is refused here rather than delivered as a row nobody can patch:
- * the alternative is a subscription that appears to work until the first update.
+ * Rows crossing the wire are addressed by a TEXT `id` — patches, cursors and the local store all
+ * key on it. A safe-integer id is stringified, the one normalisation the change feed applies to the
+ * same row (`pg-replication.ts`'s `toRow`), so a snapshot row and its later patch name one identity.
+ * Anything else is refused here rather than delivered as a row nobody can patch.
  */
 function rowsOf(query: string, rows: readonly object[]): readonly Row[] {
   const out: Row[] = [];
   for (const row of rows) {
-    if (!isRow(row)) throw new LiveRowUnidentifiedError({ query, keys: Object.keys(row) });
-    out.push(row);
+    const id: unknown = (row as { id?: unknown }).id;
+    const candidate =
+      typeof id === 'number' && Number.isSafeInteger(id) ? { ...row, id: String(id) } : row;
+    if (!isRow(candidate)) {
+      throw new LiveRowUnidentifiedError({
+        query,
+        keys: Object.keys(row),
+        ...(id === undefined || id === null ? {} : { idType: typeof id }),
+      });
+    }
+    out.push(candidate);
   }
   return out;
 }

package/src/live-fanout.ts

@@ -8,7 +8,7 @@ import type { ChangeEvent } from './changefeed';
 import { advance, type LiveCursor, makeCursor, type ResumeSource } from './cursor';
 import type { Row, RowPatch } from './json';
 import type { LiveSubscription } from './live-contract';
-import { applyToWindow, bridgeChange } from './matcher-bridge';
+import { applyToWindow, bridgeChange, type Projection, projectionOf } from './matcher-bridge';
 import { type QueryEntry, refillWindowInLane } from './query-window';
 import { type Subscriber, type SubscriberGate, windowIndex } from './subscriber-gate';
 import { type Frame, PROTOCOL_VERSION } from './sync-protocol';
@@ -47,29 +47,53 @@ export async function fanoutChange(
     return { sent: 0, stale: 0 };
   }
   if (change.op === 'truncate') return await truncated(deps, entry, change);
-  if (entry.stale) await refillWindowInLane(entry);
+  const reread = entry.stale;
+  if (reread) {
+    await refillWindowInLane(entry);
+    // What was retained before this read has a hole exactly where the staleness came from.
+    deps.source.floorAt?.(entry.qid, entry.lsn, { exclusive: true });
+    // Every subscriber was fed from the rows this read just replaced, so each is owed a snapshot —
+    // not only the ones `invalidate()` marked: a read that failed or timed out stales the window
+    // and marks nobody.
+    for (const subscription of entry.subscribers.values()) {
+      subscription.socket.markDesynced(subscription.sid);
+    }
+    // The read claims to hold this change already (`lsn` is the node's newest when it began), so
+    // there is nothing to patch. Returning before the loop below was the defect: the guard after
+    // this refused the change as stale and every desynced subscriber went without the change AND
+    // without its snapshot — a run console frozen on its first event after one `updateWhere`.
+    if (change.lsn <= entry.lsn) return { sent: await resnapshotAll(deps, entry), stale: 0 };
+  }
   // 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 bridged = bridgeChange(entry.shape, entry.matcher, change, entry.rows);
-  if (!bridged) return { sent: 0, stale: 0 };
+  // Matching nothing ends the fanout, but never before a re-read's marks are answered.
+  if (!bridged) return { sent: reread ? await resnapshotAll(deps, entry) : 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) };
+  // Asked of the window as it stood BEFORE this change: the partial row must not teach it a shape.
+  const partial = lacksOmitted(change, result.patches, projectionOf(entry.rows));
   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
-  // than patching a guess, and every subscriber below is re-snapshotted out of what that returns.
-  if (result.refill) entry.stale = true;
-  // The retained window holds the pre-policy patch; resume re-filters it per subscriber.
-  for (const patch of result.patches) deps.source.append(entry.qid, patch);
+  // The window lost its tail — or adopted a row the change could not carry whole — so what it
+  // holds is a guess: the next delivery re-reads it rather than patching a guess, and every
+  // subscriber below is re-snapshotted out of what that returns.
+  const guessed = result.refill || partial;
+  if (guessed) entry.stale = true;
+  // The retained window holds the pre-policy patch; resume re-filters it per subscriber. A partial
+  // row is never retained: replayed, it is the same missing column on a resuming client.
+  if (!partial) for (const patch of result.patches) deps.source.append(entry.qid, patch);
+  // And the ring says so now, not at the re-read: a resume in between got a delta lacking it.
+  else deps.source.floorAt?.(entry.qid, change.lsn, { exclusive: true });
 
   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) {
+    if (guessed) {
       // The window lost its tail: guessing is how a sync engine silently diverges. Checked BEFORE
       // the mark, because a repair reads `entry.rows` — which this fanout has just declared a
       // guess — and then CLEARS the mark. A subscriber already diverged would be recorded as
@@ -124,6 +148,32 @@ export async function fanoutChange(
   return { sent, stale: 0 };
 }
 
+/**
+ * Whether a row ENTERS the window without a column the change did not carry
+ * (`ChangeEvent.omitted`: an unchanged out-of-line value Postgres logged no bytes for). An update
+ * patch is safe — it merges onto a window row that already holds the column — but an add adopts
+ * the row as the whole row, into the window, every later snapshot and the retained ring. An
+ * unread projection (an empty window) cannot rule a column out, so every omitted one counts.
+ */
+function lacksOmitted(
+  change: ChangeEvent,
+  patches: readonly RowPatch[],
+  projection: Projection,
+): boolean {
+  const omitted = change.omitted;
+  if (omitted === undefined || omitted.length === 0) return false;
+  return patches.some(
+    (patch) =>
+      patch.op === 'insert' &&
+      patch.row !== null &&
+      omitted.some(
+        (column) =>
+          (projection === undefined || projection.has(column)) &&
+          !Object.hasOwn(patch.row ?? {}, column),
+      ),
+  );
+}
+
 /**
  * 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
@@ -138,12 +188,21 @@ async function truncated(
   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;
+  deps.source.floorAt?.(entry.qid, entry.lsn, { exclusive: true });
   for (const subscription of entry.subscribers.values()) {
     subscription.socket.markDesynced(subscription.sid);
+  }
+  return { sent: await resnapshotAll(deps, entry), stale: 0 };
+}
+
+/** Each marked subscriber, re-snapshotted out of the window just read. Frames that left. */
+async function resnapshotAll(deps: FanoutDeps, entry: QueryEntry): Promise<number> {
+  let sent = 0;
+  for (const subscription of entry.subscribers.values()) {
+    if (!subscription.socket.desynced.has(subscription.sid)) continue;
     if (await resnapshot(deps, entry, subscription)) sent += 1;
   }
-  return { sent, stale: 0 };
+  return sent;
 }
 
 /**

package/src/live-floor.ts

@@ -0,0 +1,35 @@
+// What a window read that just returned owes the retained ring, and the position the subscriber it
+// serves is told. The rule itself is `change-buffer.ts`'s (`Ring`); this is its one caller for a
+// read, split from `live-query.ts` at that file's size ceiling.
+
+import type { ResumeSource } from './cursor';
+import type { FilledWindow, QueryEntry } from './query-window';
+
+export interface NodePosition {
+  /** The newest change this node has received; `''` before the first. */
+  readonly lastLsn: string;
+  /** This node's own mark for a read with no position behind it. Sorts below every real lsn. */
+  readonly origin: string;
+}
+
+/**
+ * Synchronous on purpose: the caller awaits a policy pass next, and the position has to be the
+ * one these ROWS were read at — read after that await, a change folded in meanwhile would be
+ * claimed by a snapshot that does not hold it.
+ */
+export function floorAfterRead(
+  source: ResumeSource,
+  entry: QueryEntry,
+  window: FilledWindow,
+  node: NodePosition,
+): string {
+  // Served out of a window that was already filled: its patch history is still true.
+  if (window.landed === null) return window.lsn;
+  // A read with no position behind it is marked with this node's own origin, so the cursor it
+  // mints is one no other node could have issued.
+  const lsn = window.lsn === '' ? node.origin : window.lsn;
+  if (entry.lsn === '') entry.lsn = lsn;
+  if (window.landed === 'forced') source.floorAt?.(entry.qid, lsn, { exclusive: true });
+  else source.floorAt?.(entry.qid, lsn, { sole: node.lastLsn === '' || window.lsn === '' });
+  return lsn;
+}

package/src/live-query-options.ts

@@ -0,0 +1,38 @@
+// What a `LiveQueryRegistry` is built from, and the one ceiling it defaults. Split from
+// `live-query.ts` at that file's size ceiling: the registry owns behaviour, this owns its knobs.
+
+import type { Actor, Clock } from '@ultimat3/core';
+import type { ReconnectBudget, ResumeSource } from './cursor';
+import type { SubscriberGateOptions } from './subscriber-gate';
+import type { Scheduler } from './thundering-herd';
+
+export interface LiveQueryRegistryOptions extends SubscriberGateOptions {
+  readonly source: ResumeSource;
+  readonly budget?: ReconnectBudget;
+  readonly clock?: Clock;
+  readonly maxPerSocket?: number;
+  readonly maxPerTenant?: number;
+  readonly tenantOf?: (actor: Actor | null) => string | null;
+  /**
+   * Distinct `(query, input)` pairs this node will hold at once. A `qid` derives from
+   * client-chosen input, so without a ceiling one socket mints entries — a matcher, a row window,
+   * a `WindowLock` and a fanout target each — until the process dies.
+   */
+  readonly maxEntries?: number;
+  /**
+   * How long one entry's SHARED snapshot read may hold its slot. Defaults to
+   * `DEFAULT_READ_DEADLINE_MS`. Without it a `definition.snapshot` that never settles pinned the
+   * slot for the life of the process and every later cold subscriber joined a promise nothing
+   * would resolve — one wedged read taking every future subscriber of that query id with it.
+   */
+  readonly readDeadlineMs?: number;
+  /** Injected so that deadline is provable without waiting for one. Production uses `setTimeout`. */
+  readonly schedule?: Scheduler;
+}
+
+/**
+ * Live `(query, input)` pairs one node holds. Reached, the next NEW pair is refused with
+ * `X_SUBSCRIPTION_LIMIT`; subscribing to a pair that already exists keeps working, because the
+ * cost this bounds is the entry, not the subscriber.
+ */
+export const DEFAULT_MAX_ENTRIES = 10_000;