@ultimat3/realtime 1.2.0 → 2.0.0

package/src/index.ts

@@ -1,7 +1,14 @@
 // Public API. Explicit, tier by tier: channels, live queries, local-first sync, plus the wire and
 // the server/client halves that carry all three.
 
-export { type ChangeBufferOptions, RingChangeBuffer } from './change-buffer';
+// ---- the client's one stateless piece, reusable against an app's own store ----------------------
+export { applyPatches, orderAfterPatches } from './apply-patches';
+export {
+  type ChangeBufferOptions,
+  DEFAULT_MAX_BUFFER_BYTES,
+  DEFAULT_MAX_BUFFER_BYTES_PER_QUERY,
+  RingChangeBuffer,
+} from './change-buffer';
 // ---- tier 2: live queries ----------------------------------------------------------------------
 export {
   type ChangeEvent,
@@ -25,12 +32,12 @@ export {
   type SelectChangeFeedOptions,
   selectChangeFeed,
 } from './changefeed-env';
-
 // ---- tier 1: channels + presence ---------------------------------------------------------------
 export {
   ChannelHub,
   type ChannelHubOptions,
   channelFrame,
+  DEFAULT_MAX_TOPICS_PER_NODE,
   type Topic,
   type TopicGuard,
   type TopicGuardArgs,
@@ -39,7 +46,6 @@ export {
 } from './channel';
 // ---- server + client halves -------------------------------------------------------------------
 export {
-  applyPatches,
   type ClientSocket,
   LiveClient,
   type LiveClientOptions,
@@ -48,6 +54,7 @@ export {
   type LiveState,
   type MutatorRef,
   type SignalFactory,
+  type Unsubscribe,
 } from './client';
 // ---- reconnect ----------------------------------------------------------------------------------
 export {
@@ -71,10 +78,13 @@ export {
 // ---- errors ----------------------------------------------------------------------------------
 export {
   CursorStaleError,
+  FrameRateLimitError,
   LiveClientMissingError,
+  LiveQueryUnknownError,
   LiveRowUnidentifiedError,
   NotImplementedError,
   ProtocolVersionError,
+  QueryNotSubscribableError,
   REALTIME_ERROR_CODES,
   REALTIME_ERROR_TITLES,
   RealtimeError,
@@ -115,6 +125,15 @@ export {
   useMutation,
   useMutationQueue,
 } from './hooks';
+// ---- the client's single source of truth: one row per (entity, id) ------------------------------
+export {
+  type IdentityListener,
+  IdentityMap,
+  privateScope,
+  type RowKey,
+  type RowScope,
+  rowKey,
+} from './identity-map';
 // ---- shared value domain ---------------------------------------------------------------------
 export {
   canonicalJson,
@@ -128,16 +147,19 @@ export {
   type RowOp,
   type RowPatch,
 } from './json';
-export { type LiveDefinitionOptions, liveQueryDefinition } from './live-definition';
 export {
   type LiveQueryDefinition,
-  LiveQueryRegistry,
-  type LiveQueryRegistryOptions,
   type LiveSubscription,
   qidOf,
-  type RowDenied,
   type SnapshotResult,
+} from './live-contract';
+export { type LiveDefinitionOptions, liveQueryDefinition } from './live-definition';
+export {
+  DEFAULT_MAX_ENTRIES,
+  LiveQueryRegistry,
+  type LiveQueryRegistryOptions,
 } from './live-query';
+export { type Registration, RowWindows } from './live-rows';
 // ---- tier 3: local-first ------------------------------------------------------------------------
 export {
   createOpfsLocalStore,
@@ -161,15 +183,23 @@ export {
   type SubscriptionShape,
   toBridgeResult,
 } from './matcher-bridge';
-export type { NatsConnectOptions } from './nats-commands';
 // ---- the production bus -------------------------------------------------------------------------
 export {
-  NatsConnection,
-  type NatsConnectionOptions,
+  DEFAULT_NATS_PORT,
+  DEFAULT_REQUEST_TIMEOUT_MS,
+  type NatsClient,
+  type NatsClientOptions,
+  type NatsConnect,
+  type NatsHeaders,
+  type NatsMessage,
   type NatsMessageHandler,
+  type NatsRequestManyOptions,
+  type NatsRequestOptions,
   type NatsSubscription,
-} from './nats-connection';
-export { type FakeNatsOptions, FakeNatsServer, fakeNatsStream } from './nats-fake';
+  type NatsTarget,
+  parseNatsUrl,
+} from './nats-client';
+export { FakeNatsBroker, type FakeNatsOptions, fakeNatsConnect } from './nats-fake';
 export {
   assertBucket,
   assertServerVersion,
@@ -178,24 +208,12 @@ export {
   type KvRecord,
   kvGet,
   kvLast,
+  kvStream,
   kvSubject,
   kvWrite,
 } from './nats-jetstream';
 export { decodeToken, encodeToken, NatsKvSet, type NatsKvSetOptions } from './nats-kv';
-export {
-  type NatsHeaders,
-  type NatsMessage,
-  type NatsOperation,
-  NatsProtocolParser,
-  type NatsServerInfo,
-} from './nats-protocol';
-export {
-  bunNatsStream,
-  type NatsStream,
-  type NatsTarget,
-  natsStreamOver,
-  parseNatsUrl,
-} from './nats-socket';
+export { openNatsClient } from './nats-lib-client';
 export { NatsTransport, type NatsTransportOptions } from './nats-transport';
 export {
   type DrainReport,
@@ -226,12 +244,28 @@ export {
 } from './pgoutput';
 export { authorizeWithPolicy, type GateOptions, visibleWithPolicy } from './policy-gate';
 export {
+  DEFAULT_MAX_PRESENCE_MEMBERS,
   PRESENCE_KEY_PREFIX,
+  PRESENCE_SWEEP_PREFIX,
   type PresenceInput,
   type PresenceOptions,
   PresenceRegistry,
+  type PresenceRoster,
   presenceFrame,
 } from './presence';
+/** The typed projection: one query bound to one named hook, `useLiveFeed({ orgId })`. */
+export {
+  type LiveQueryHook,
+  type LiveQuerySource,
+  liveHookFor,
+} from './query-hook';
+export {
+  createEntry,
+  fillWindow,
+  orgIdOf,
+  type QueryEntry,
+  refillWindowInLane,
+} from './query-window';
 export {
   type ConflictStrategy,
   type CustomMerge,
@@ -249,30 +283,61 @@ export {
 export {
   type AdvisoryLock,
   CHANGE_SUBJECT_PREFIX,
+  type ChangeEnvelope,
   changeSubject,
   createReplicator,
   InMemoryAdvisoryLock,
   normalize,
   parseChange,
+  parseEnvelope,
   type Replicator,
   type ReplicatorOptions,
   type ReplicatorStats,
+  SeqGapDetector,
 } from './replicator';
 export {
   actorIdOf,
   CLOSE,
+  DEFAULT_FRAME_BURST,
+  DEFAULT_MAX_BUFFERED_BYTES,
+  DEFAULT_MAX_FRAMES_PER_SECOND,
   SocketRegistry,
   type SocketRegistryOptions,
   SyncSocket,
   type SyncSocketOptions,
   type WsLike,
 } from './socket';
+export type {
+  GateFailed,
+  GateStage,
+  RowDenied,
+  Subscriber,
+  SubscriberGateOptions,
+} from './subscriber-gate';
+export {
+  GrantBook,
+  type GrantSweepDeps,
+  type GrantSweepResult,
+  type SyncAuthenticator,
+  type SyncGrant,
+  sweepGrants,
+} from './sync-auth';
+export {
+  createFrameRouter,
+  type FrameRouter,
+  type FrameRouterOptions,
+  type MutationHandler,
+} from './sync-frames';
 export {
-  createSyncNode,
   type ListenOptions,
   listenSyncNode,
-  type MutationHandler,
   type SyncListener,
+} from './sync-listen';
+export {
+  createSyncNode,
+  DEFAULT_MAX_CONNECTIONS,
+  DEFAULT_MAX_FRAME_BYTES,
+  DEFAULT_REAUTH_INTERVAL_MS,
   type SyncNode,
   type SyncNodeOptions,
   type SyncWs,
@@ -286,6 +351,7 @@ export {
   decode,
   encode,
   FRAME_KINDS,
+  FRAME_LIMITS,
   type Frame,
   type FrameKind,
   type HelloFrame,
@@ -316,6 +382,8 @@ export {
   type ReconnectReason,
   type Rng,
   reconnectFrame,
+  type Scheduler,
+  timeoutScheduler,
 } from './thundering-herd';
 export {
   DEFAULT_PRESENCE_BUCKET,

package/src/json.ts

@@ -49,8 +49,28 @@ export function changedColumns(before: JsonObject | null, after: JsonObject): Js
   return out;
 }
 
-/** Key-sorted JSON so a query id derived from input is stable across property order. */
+/**
+ * Key-sorted JSON so a query id derived from input is stable across property order — and
+ * INJECTIVE, because that id decides who shares a window.
+ *
+ * `qidOf` is `stableDigest(canonicalJson(input))` and a qid HIT hands the joiner the existing
+ * entry: the first subscriber's compiled source, its matcher and its seated rows. Two inputs that
+ * canonicalise to one string are therefore two clients served out of one window. `JSON.stringify`
+ * is not injective over numbers — `NaN` and `±Infinity` are both `"null"`, which also collides
+ * with JSON `null` itself, and `-0` is `"0"` — so the number branch is spelled out here.
+ *
+ * `-0` is the one of those a client can put on the wire (`JSON.parse('{"a":-0}')` answers `-0`);
+ * the non-finite three have no JSON spelling and arrive only from a caller building `input` in JS,
+ * such as `useLive(feed, () => ({ limit: Number.parseInt(raw) }))` on an unparseable `raw`.
+ * The tokens are bare, never quoted: this output is only ever hashed, and the `string` branch
+ * always quotes, so an unquoted word cannot collide with the text that spells it.
+ *
+ * The twin of `@ultimat3/query`'s and `@ultimat3/action`'s rules in their own `stable.ts`. All
+ * three are tier 3, so no two of them can import each other; the shared home is `@ultimat3/core`
+ * if one is ever made.
+ */
 export function canonicalJson(value: JsonValue): string {
+  if (typeof value === 'number') return canonicalNumber(value);
   if (value === null || typeof value !== 'object') return JSON.stringify(value) ?? 'null';
   if (Array.isArray(value)) return `[${value.map(canonicalJson).join(',')}]`;
   const keys = Object.keys(value).sort();
@@ -58,6 +78,23 @@ export function canonicalJson(value: JsonValue): string {
   return `{${parts.join(',')}}`;
 }
 
+/** Ordinary numbers are `String(n)`, byte-identical to what this emitted before. */
+function canonicalNumber(value: number): string {
+  if (Number.isNaN(value)) return 'NaN';
+  if (!Number.isFinite(value)) return value > 0 ? 'Infinity' : '-Infinity';
+  return Object.is(value, -0) ? '-0' : String(value);
+}
+
+/**
+ * SHA-256, first 16 hex characters. For the hashes that are also SHARING keys — a `qid` decides
+ * which subscribers are served from one window, and it is derived from input a client chooses, so
+ * the 32 bits `fnv1a` answers are a collision anyone can find offline in seconds. Same primitive
+ * and same width `@ultimat3/entity`'s `planScope` already chose for a cursor's scope.
+ */
+export function stableDigest(text: string): string {
+  return new Bun.CryptoHasher('sha256').update(text).digest('hex').slice(0, 16);
+}
+
 /** FNV-1a, 32-bit, hex. Not cryptographic — it identifies and detects drift, it does not protect. */
 export function fnv1a(text: string): string {
   let hash = 0x811c9dc5;

package/src/live-contract.ts

@@ -0,0 +1,67 @@
+// What a live query IS: the id one is keyed by, the contract a definition satisfies, and the
+// subscription one socket holds. Split from `live-query.ts` because four modules need the shape
+// and none of them needs the registry that runs it — and because one file runs one job.
+
+import type { Actor } from '@ultimat3/core';
+import type { LiveCursor } from './cursor';
+import { canonicalJson, type JsonValue, type Row, stableDigest } from './json';
+import type { IncrementalMatcher } from './matcher-bridge';
+import type { SyncSocket } from './socket';
+
+/**
+ * `qid` = hash(query name, input). Fanout subjects and change windows are keyed by it.
+ *
+ * The hash is a **sharing** key, which is why it is `stableDigest` and not `fnv1a`: `#entryFor`
+ * answers a hit with the EXISTING entry and `liveQueryDefinition` answers with the seated
+ * `SharedWindow`, both carrying the first subscriber's input, compiled source and rows. Input is
+ * client-chosen, so a second input colliding with the first passes `authorize` against its own
+ * arguments and is then served out of somebody else's window — and 32 bits is a collision found
+ * offline in seconds.
+ */
+export function qidOf(name: string, input: JsonValue): string {
+  return `${name}:${stableDigest(canonicalJson(input))}`;
+}
+
+export interface SnapshotResult<R extends Row = Row> {
+  readonly rows: readonly R[];
+  readonly lsn: string;
+}
+
+export interface LiveQueryDefinition<R extends Row = Row> {
+  readonly name: string;
+  /** Dependency set for the pre-filter. `x verify` rejects a `live: true` query without one. */
+  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>>;
+  /** 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. */
+  visible(args: { actor: Actor | null; row: R; input: JsonValue }): boolean | Promise<boolean>;
+  /** Built once per `qid`, since a qid pins both the query and its input. */
+  matcher(input: JsonValue): IncrementalMatcher;
+  /**
+   * The entity every row of this result set belongs to, resolved per input exactly as `matcher`
+   * is. It is the client's identity scope, and it can only come from here: a browser cannot
+   * compile the shape a `sql` produces. `null` means "not stated", and the client then keeps the
+   * rows private to that one subscription rather than guessing.
+   */
+  rowEntity?(input: JsonValue): 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
+   * source or a shape does it here, after `authorize` allowed this subscriber and before the
+   * shared window exists.
+   */
+  prepare?(input: JsonValue): Promise<void>;
+}
+
+export interface LiveSubscription {
+  readonly sid: string;
+  readonly qid: string;
+  readonly socket: SyncSocket;
+  readonly input: JsonValue;
+  readonly definition: LiveQueryDefinition;
+  cursor: LiveCursor;
+}

package/src/live-definition.ts

@@ -9,10 +9,10 @@
 // every time. Collapsing the second onto the first is privilege escalation with a cache hit rate.
 
 import type { Ctx } from '@ultimat3/core';
-import { type AnyQuery, queryName, sourceFor } from '@ultimat3/query';
+import { type AnyQuery, queryName } from '@ultimat3/query';
 import { LiveRowUnidentifiedError } from './errors';
 import { isRow, type JsonValue, type Row } from './json';
-import { type LiveQueryDefinition, qidOf, type SnapshotResult } from './live-query';
+import { type LiveQueryDefinition, qidOf, type SnapshotResult } from './live-contract';
 import { type IncrementalMatcher, matcherFor } from './matcher-bridge';
 import { authorizeWithPolicy, visibleWithPolicy } from './policy-gate';
 
@@ -44,6 +44,8 @@ export interface LiveDefinitionOptions {
  */
 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;
   read(): Promise<readonly Row[]>;
 }
 
@@ -81,17 +83,17 @@ export function liveQueryDefinition(
       enforce: false,
       ...(options.epoch === undefined ? {} : { epoch: options.epoch }),
     });
-    // A second, subject-less build of the same source: `LiveQuery` describes the read (shape,
-    // reads, SQL text) but deliberately cannot run it, and the window needs rows. Both calls are
-    // pure source construction, both are subject-less, and they happen once per query id.
-    const source = await sourceFor(target, input, {
-      ctx: options.ctx,
-      enforce: false,
-      surface: 'live',
-    });
+    // One build, and the window reads through it. `live.execute()` runs the source the shape and
+    // the dependency set above were taken from, so the rows a subscriber is served and the matcher
+    // that patches them describe the same `(query, input)` by construction. Asking `sourceFor` for
+    // 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 built: SharedWindow = {
       matcher: matcherFor(live),
-      read: async () => rowsOf(name, await source.execute()),
+      // `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,
+      read: async () => rowsOf(name, await live.execute()),
     };
     windows.set(qid, built);
     evictOldest(windows, options.maxWindows ?? 256);
@@ -112,6 +114,9 @@ export function liveQueryDefinition(
       return { rows: await window.read(), lsn: options.lsn?.() ?? '' };
     },
     matcher: (input) => windows.get(qidOf(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(qidOf(name, input))?.rowEntity ?? 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

@@ -0,0 +1,150 @@
+// One change, one query id, inside that query's lane: match it, fold it into the shared window,
+// then one policy pass per subscriber over what came out. Split from `live-query.ts` because the
+// registry owns the lanes and the entry table while this owns what happens inside one of them —
+// and because one file runs one job. The lane itself is never taken here: the caller is holding it.
+
+import type { Clock } from '@ultimat3/core';
+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 { type QueryEntry, refillWindowInLane } from './query-window';
+import type { Subscriber, SubscriberGate } from './subscriber-gate';
+import { type Frame, PROTOCOL_VERSION } from './sync-protocol';
+
+export interface FanoutDeps {
+  readonly gate: SubscriberGate;
+  readonly source: ResumeSource;
+  readonly clock: Clock;
+}
+
+export interface FanoutResult {
+  /** Frames that left this node for this query id. */
+  readonly sent: number;
+  /** `1` when the change was at or below the window's own lsn — `live.changes_stale`. */
+  readonly stale: number;
+}
+
+/**
+ * The fanout for one entry, run inside that entry's lane — so the window this mutates at the top is
+ * still the window every subscriber's gate reads at the bottom, and the patches reach the retained
+ * buffer in the order the client will be asked to fold them.
+ */
+export async function fanoutChange(
+  deps: FanoutDeps,
+  entry: QueryEntry,
+  change: ChangeEvent,
+): 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.
+  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 };
+  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);
+
+  let sent = 0;
+  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
+      // 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
+      // repaired against rows nothing trusts, and the next change, having refilled the window,
+      // sends it a patch instead of the snapshot it is still owed. A lost tail degrades every
+      // subscriber the same way, whatever each was holding.
+      subscription.socket.markDesynced(subscription.sid);
+      continue;
+    }
+    // `desynced` had four writers and no reader: a subscriber whose patch was dropped by
+    // backpressure, whose gate failed, or whose window lost its tail was recorded as diverged and
+    // then served the next patch as if nothing had happened — permanently and silently stale on a
+    // healthy socket. A marked subscriber is re-snapshotted out of the shared window instead, at
+    // the cost of one frame and no DB read, and only then is the mark cleared.
+    if (subscription.socket.desynced.has(subscription.sid)) {
+      if (await resnapshot(deps, entry, subscription)) sent += 1;
+      continue;
+    }
+    const who: Subscriber = { sid: subscription.sid, actor: subscription.socket.actor };
+    let allowed: readonly RowPatch[];
+    try {
+      allowed = await deps.gate.filterPatches(
+        entry,
+        who,
+        result.patches,
+        new Set(subscription.cursor.ids),
+      );
+    } catch {
+      // Already counted and reported as a gate failure. Degrade this one subscriber the way a
+      // lost window tail degrades them — desynced, re-snapshotted on the next flush — because
+      // rejecting here would abandon the fanout to every other subscriber over one actor's
+      // broken rule, and delivering the patches anyway would be the leak.
+      subscription.socket.markDesynced(subscription.sid);
+      continue;
+    }
+    if (allowed.length === 0) continue;
+    const frame: Frame = {
+      type: 'patch',
+      v: PROTOCOL_VERSION,
+      sid: subscription.sid,
+      patches: allowed,
+      lsn: change.lsn,
+    };
+    if (subscription.socket.send(frame)) {
+      subscription.cursor = advance(subscription.cursor, allowed, change.lsn, change.at);
+      sent += 1;
+    } else {
+      subscription.socket.markDesynced(subscription.sid);
+    }
+  }
+  return { sent, stale: 0 };
+}
+
+/**
+ * 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
+ * `subscribe` does, because a cursor over the pre-policy window would claim ids the client was
+ * never sent. The mark is cleared only on a frame that left: a send refused by backpressure keeps
+ * the subscriber diverged, which is the state it is actually in.
+ */
+async function resnapshot(
+  deps: FanoutDeps,
+  entry: QueryEntry,
+  subscription: LiveSubscription,
+): Promise<boolean> {
+  const who: Subscriber = { sid: subscription.sid, actor: subscription.socket.actor };
+  let rows: readonly Row[];
+  try {
+    rows = await deps.gate.filterRows(entry, who, entry.rows);
+  } catch {
+    // Counted and reported as a gate failure already. It stays desynced: a subscriber whose rule
+    // cannot decide is not one to serve rows to, and the next change tries again.
+    return false;
+  }
+  const cursor = makeCursor(entry.qid, entry.lsn, rows, deps.clock.now().getTime());
+  if (!subscription.socket.send(snapshotFrame(entry, subscription.sid, rows, cursor))) return false;
+  subscription.cursor = cursor;
+  subscription.socket.clearDesynced(subscription.sid);
+  return true;
+}
+
+/** The one place a snapshot frame is built, so the identity scope cannot be told to one caller only. */
+export function snapshotFrame(
+  entry: QueryEntry,
+  sid: string,
+  rows: readonly Row[],
+  cursor: LiveCursor,
+): Frame {
+  const base = { type: 'snapshot', v: PROTOCOL_VERSION, sid, rows, cursor } as const;
+  return entry.rowEntity === null ? base : { ...base, entity: entry.rowEntity };
+}