@spooky-sync/core 0.0.1-canary.245 → 0.0.1-canary.246

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { A as ServerViewMeta, B as TimingPhase, C as QueryTimings, D as RecordVersionDiff, E as RecordVersionArray, F as StorageHealthStatus, G as SealedQuery, H as LocalStore, I as StoreType, K as EventDefinition, L as SyncHealth, M as Sp00kyQueryResult, N as Sp00kyQueryResultPromise, O as RegistrationTimings, P as StorageHealth, R as SyncHealthConfig, S as QueryTimeToLive, T as ReconnectConfig, U as DatabaseEventSystem, V as UpdateOptions, W as DatabaseEventTypes, _ as QueryConfigRecord, a as MATERIALIZATION_SAMPLE_WINDOW, b as QueryStatus, c as MutationEvent, d as PhaseStat, f as PinoTransmit, g as QueryConfig, h as QueryAuthorityCallback, i as Level, j as Sp00kyConfig, k as RunOptions, l as MutationEventType, m as PreloadRefresh, n as DebounceOptions, o as MembershipOutcome, p as PreloadOptions, q as EventSystem, r as EventSubscriptionOptions, s as MutationCallback, t as ConnectionState, u as PersistenceClient, v as QueryHash, w as QueryUpdateCallback, x as QueryStatusCallback, y as QueryState, z as SyncHealthStatus } from "./types.js";
+import { A as RunOptions, B as SyncHealthStatus, C as QueryTimeToLive, D as RecordVersionArray, E as ReconnectConfig, F as StorageHealth, G as DatabaseEventTypes, H as UpdateOptions, I as StorageHealthStatus, J as EventSystem, K as SealedQuery, L as StoreType, M as Sp00kyConfig, N as Sp00kyQueryResult, O as RecordVersionDiff, P as Sp00kyQueryResultPromise, R as SyncHealth, S as QueryStatusCallback, T as QueryUpdateCallback, U as LocalStore, V as TimingPhase, W as DatabaseEventSystem, _ as QueryConfig, a as Level, b as QueryState, c as MutationCallback, d as PersistenceClient, f as PhaseStat, g as QueryAuthorityCallback, h as PreloadRefresh, i as InlineRow, j as ServerViewMeta, k as RegistrationTimings, l as MutationEvent, m as PreloadOptions, n as DebounceOptions, o as MATERIALIZATION_SAMPLE_WINDOW, p as PinoTransmit, q as EventDefinition, r as EventSubscriptionOptions, s as MembershipOutcome, t as ConnectionState, u as MutationEventType, v as QueryConfigRecord, w as QueryTimings, x as QueryStatus, y as QueryHash, z as SyncHealthConfig } from "./types.js";
 import { AccessDefinition, BackendNames, BackendRoutes, BucketNames, ColumnSchema, FinalQuery, GetTable, QueryBuilder, QueryOptions, QueryPlan, RecordId, RoutePayload, SchemaStructure, TableModel, TableNames, TypeNameToTypeMap } from "@spooky-sync/query-builder";
 import * as surrealdb0 from "surrealdb";
 import { Duration, RecordId as RecordId$1, Surreal, SurrealEvents, SurrealTransaction } from "surrealdb";
@@ -1180,6 +1180,7 @@ type RuntimeEvent = {
 } | {
   type: 'LiveChange';
   hashes: QueryHash[];
+  rows?: InlineRow[];
 } | {
   type: 'TabRole';
   role: 'solo' | 'leader' | 'follower';
@@ -1622,8 +1623,12 @@ interface Adapters {
   };
   remote: {
     queryResponses(sql: string, vars?: Record<string, unknown>): Promise<StatementResult[]>;
-    /** Subscribe to `LIVE SELECT * FROM <table>`; the callback receives the changed query hashes. */
-    live(table: string, onChange: (hashes: string[]) => void): Promise<string>;
+    /**
+     * Subscribe to `LIVE SELECT * FROM <table>`; the callback receives the
+     * changed query hashes, plus the changed rows themselves when the
+     * subscription was opened with the body joined on (`liveInlineBodies`).
+     */
+    live(table: string, onChange: (hashes: string[], rows?: InlineRow[]) => void): Promise<string>;
     kill(uuid: string): Promise<void>;
   };
   ssp: {
@@ -2355,4 +2360,4 @@ declare function textToHtml(text: string): string;
  */
 
 //#endregion
-export { AppReleaseHandle, AppReleaseModule, type AppReleaseOptions, type AppReleaseSnapshot, AuthEventSystem, AuthEventTypeMap, AuthEventTypes, AuthService, BLURHASH_IMAGE_EXTENSIONS, type BlobCacheStats, type BlobEntry, type BlobKey, type BlobReadOptions, type BlobUrlLease, type BlurhashEncodeOptions, type BlurhashSetting, BucketHandle, BucketPutOptions, BucketPutResult, CURSOR_COLORS, ConnectionState, CrdtField, CrdtManager, DEFAULT_LOCAL_OP_TIMEOUT_MS, DebounceOptions, EventSubscriptionOptions, type FailedMutationRow as FailedMutation, FeatureFlagHandle, FeatureFlagModule, type FeatureFlagOptions, type FeatureFlagOverride, type FeatureFlagSnapshot, Level, LocalOpTimeoutError, MATERIALIZATION_SAMPLE_WINDOW, MembershipOutcome, MutationCallback, MutationEvent, MutationEventType, PersistenceClient, PhaseStat, PinoTransmit, PreloadOptions, PreloadRefresh, QueryAuthorityCallback, QueryConfig, QueryConfigRecord, QueryHash, QueryState, QueryStatus, QueryStatusCallback, QueryTimeToLive, QueryTimings, QueryUpdateCallback, ReconnectConfig, RecordVersionArray, RecordVersionDiff, RegistrationTimings, RunOptions, ServerViewMeta, Sp00kyClient, Sp00kyClientDeps, Sp00kyConfig, Sp00kyQueryResult, Sp00kyQueryResultPromise, StorageHealth, StorageHealthStatus, StoreType, SyncHealth, SyncHealthConfig, SyncHealthStatus, TimingPhase, UpdateOptions, blurhashSidecarPath, bucketContentToBlob, createAuthEventSystem, cursorColorFromName, decode as decodeBlurhash, encode as encodeBlurhash, encodeImageToBlurhash, fileToUint8Array, isBlurhashValid, isImagePath, semverGt, textToHtml };
+export { AppReleaseHandle, AppReleaseModule, type AppReleaseOptions, type AppReleaseSnapshot, AuthEventSystem, AuthEventTypeMap, AuthEventTypes, AuthService, BLURHASH_IMAGE_EXTENSIONS, type BlobCacheStats, type BlobEntry, type BlobKey, type BlobReadOptions, type BlobUrlLease, type BlurhashEncodeOptions, type BlurhashSetting, BucketHandle, BucketPutOptions, BucketPutResult, CURSOR_COLORS, ConnectionState, CrdtField, CrdtManager, DEFAULT_LOCAL_OP_TIMEOUT_MS, DebounceOptions, EventSubscriptionOptions, type FailedMutationRow as FailedMutation, FeatureFlagHandle, FeatureFlagModule, type FeatureFlagOptions, type FeatureFlagOverride, type FeatureFlagSnapshot, InlineRow, Level, LocalOpTimeoutError, MATERIALIZATION_SAMPLE_WINDOW, MembershipOutcome, MutationCallback, MutationEvent, MutationEventType, PersistenceClient, PhaseStat, PinoTransmit, PreloadOptions, PreloadRefresh, QueryAuthorityCallback, QueryConfig, QueryConfigRecord, QueryHash, QueryState, QueryStatus, QueryStatusCallback, QueryTimeToLive, QueryTimings, QueryUpdateCallback, ReconnectConfig, RecordVersionArray, RecordVersionDiff, RegistrationTimings, RunOptions, ServerViewMeta, Sp00kyClient, Sp00kyClientDeps, Sp00kyConfig, Sp00kyQueryResult, Sp00kyQueryResultPromise, StorageHealth, StorageHealthStatus, StoreType, SyncHealth, SyncHealthConfig, SyncHealthStatus, TimingPhase, UpdateOptions, blurhashSidecarPath, bucketContentToBlob, createAuthEventSystem, cursorColorFromName, decode as decodeBlurhash, encode as encodeBlurhash, encodeImageToBlurhash, fileToUint8Array, isBlurhashValid, isImagePath, semverGt, textToHtml };

package/dist/index.js

@@ -1073,8 +1073,8 @@ function selfAllowlistedVariant(flag, userId) {
 
 //#endregion
 //#region src/modules/devtools/index.ts
-const CORE_VERSION = "0.0.1-canary.245";
-const WASM_VERSION = "0.0.1-canary.245";
+const CORE_VERSION = "0.0.1-canary.246";
+const WASM_VERSION = "0.0.1-canary.246";
 const SURREAL_VERSION = "3.0.3";
 var DevToolsService = class DevToolsService {
 	eventsHistory = [];
@@ -4533,9 +4533,10 @@ function createInterpreter(adapters, host) {
 				const pending = adapters.remote.queryResponses(effect.sql, effect.vars);
 				return effect.timeoutMs ? withTimeout(pending, effect.timeoutMs, () => /* @__PURE__ */ new Error(`Remote request timed out after ${effect.timeoutMs}ms`)) : pending;
 			}
-			case "remote.live": return adapters.remote.live(effect.table, (hashes) => host.dispatch({
+			case "remote.live": return adapters.remote.live(effect.table, (hashes, rows) => host.dispatch({
 				type: "LiveChange",
-				hashes
+				hashes,
+				rows
 			}));
 			case "remote.kill": return adapters.remote.kill(effect.uuid);
 			case "ssp.register": {
@@ -4643,7 +4644,13 @@ function* fetchRows(env) {
 		}
 	}
 }
-/** Write one chunk's bodies to the store and circuit; record their versions. */
+/**
+* Write one chunk's bodies to the store and circuit; record their versions.
+*
+* Shared with the LIVE path: a body that arrives on a notification is landed
+* through here so it is indistinguishable from a fetched one, which is what
+* makes `planFetch` stop asking for it.
+*/
 function* landChunk(env, requested, rows, versions, state, epoch) {
 	const bodies = [];
 	const ingest = [];
@@ -5035,10 +5042,15 @@ function* pollTick(env) {
 //#endregion
 //#region src/sync/live.saga.ts
 /**
-* LIVE on the session's `_00_list_ref` table. Events never carry data into
-* state: every change only marks its query's membership dirty, and the
-* batched re-read decides. Followers get the same dirt relayed by the
-* leader.
+* LIVE on the session's `_00_list_ref` table. An event marks its query's
+* membership dirty and the batched re-read decides; followers get the same
+* dirt relayed by the leader.
+*
+* When the subscription was opened with the body joined on
+* (`liveInlineBodies`) the event ALSO carries the changed row. That is an
+* optimisation on top, never a source of truth: the row is landed exactly as a
+* fetched body would be, so a notification the server drops costs nothing but
+* the round trip it would have saved.
 */
 function* liveStart(env) {
 	const state = yield fx.state.read((s) => s);
@@ -5085,10 +5097,11 @@ function* liveInvalidate() {
 	}));
 }
 /** One or more edges of these queries changed on the server. */
-function* liveChange(hashes) {
+function* liveChange(env, hashes, rows) {
 	const [known, role] = yield fx.state.read((s) => [hashes.filter((h) => s.queries.has(h)), s.tabRole]);
 	if (known.length === 0) return;
 	yield fx.state.update(patchSync({ pollIdleStreak: 0 }));
+	if (rows && rows.length > 0) yield* landInlineRows(env, rows);
 	yield* markMembershipDirty(known);
 	if (role === "leader") yield fx.emit({
 		type: "tabs:broadcast",
@@ -5098,6 +5111,29 @@ function* liveChange(hashes) {
 		}
 	});
 }
+/**
+* Land bodies that rode in on the notification. Rows already held at this
+* version or newer are dropped: one edit bumps the edge in every view holding
+* the row, so the same body arrives once per view.
+*/
+function* landInlineRows(env, rows) {
+	const state = yield fx.state.read((s) => s);
+	const fresh = /* @__PURE__ */ new Map();
+	for (const row of rows) {
+		if ((state.versions.get(row.id) ?? -1) >= row.version) continue;
+		const held = fresh.get(row.id);
+		if (!held || held.version < row.version) fresh.set(row.id, row);
+	}
+	if (fresh.size === 0) return;
+	const picked = [...fresh.values()];
+	const epoch = yield fx.local.epoch();
+	if (!(yield* landChunk(env, picked.map((r) => r.id), picked.map((r) => r.record), new Map(picked.map((r) => [r.id, r.version])), state, epoch))) yield fx.emit({
+		type: "log",
+		level: "debug",
+		message: "inline live body not landed; the fetch path will pull it",
+		data: { ids: picked.map((r) => r.id) }
+	});
+}
 
 //#endregion
 //#region src/sync/connection.saga.ts
@@ -5230,7 +5266,7 @@ function* tabMessage(env, raw) {
 			yield fx.state.update(compose(setVersions(msg.records.filter((r) => r.op !== "DELETE").map((r) => [r.id, typeof r.record?._00_rv === "number" ? r.record._00_rv : 0])), deleteVersions(msg.records.filter((r) => r.op === "DELETE").map((r) => r.id)), ...[...new Set(msg.records.map((r) => r.table))].map((t) => markTableDirty(t))));
 			return;
 		case "membership-dirty":
-			if (Array.isArray(msg.hashes)) yield* liveChange(msg.hashes);
+			if (Array.isArray(msg.hashes)) yield* liveChange(env, msg.hashes);
 			return;
 		case "outbox-changed":
 			if (role !== "leader") return;
@@ -5566,7 +5602,7 @@ function route(env, event) {
 			lane: serial("live")
 		};
 		case "LiveChange": return {
-			saga: liveChange(event.hashes),
+			saga: liveChange(env, event.hashes, event.rows),
 			lane: serial("live-change")
 		};
 		case "TabRole": return {
@@ -12473,7 +12509,7 @@ function createTabsCoordinator(config, s, host) {
 	return new TabsCoordinator({
 		tabId: s.tabId,
 		fingerprint: computeTabsFingerprint({
-			coreVersion: "0.0.1-canary.245",
+			coreVersion: "0.0.1-canary.246",
 			schemaHash: hash53(config.schemaSurql),
 			endpoint: config.database.endpoint ?? "",
 			namespace: config.database.namespace,
@@ -12578,6 +12614,29 @@ function hashOfEdge(value) {
 	const str = inId instanceof RecordId$1 ? String(inId.id) : String(inId).replace(/^_00_query:/, "");
 	return str.length > 0 ? str : null;
 }
+/**
+* The row an edge notification carries, when the subscription joined it on.
+*
+* Without `FETCH out` the edge's `out` is a record id and there is nothing to
+* land, so this returns null and the caller falls back to fetching the body.
+* It also returns null for a row the session may not read (the join yields
+* `out: null`) and for an edge whose target has been deleted.
+*/
+function rowOfEdge(value) {
+	const edge = value;
+	const out = edge?.out;
+	if (!out || typeof out !== "object" || Array.isArray(out) || out instanceof RecordId$1) return null;
+	const rid = out.id;
+	if (!(rid instanceof RecordId$1)) return null;
+	const id = encodeRecordId(rid);
+	const version = typeof edge?.version === "number" ? edge.version : null;
+	if (version === null) return null;
+	return {
+		id,
+		version,
+		record: out
+	};
+}
 /** Build the adapters the interpreter drives from the services. */
 function createAdapters(config, s, host, lateModules) {
 	const timers = /* @__PURE__ */ new Map();
@@ -12670,11 +12729,14 @@ function createAdapters(config, s, host, lateModules) {
 		remote: {
 			queryResponses: (sql, vars) => s.remote.queryResponses(sql, vars),
 			live: async (table, onChange) => {
-				const [uuid] = await s.remote.query(`LIVE SELECT * FROM ${table}`);
+				const join = config.liveInlineBodies ? " FETCH out" : "";
+				const [uuid] = await s.remote.query(`LIVE SELECT * FROM ${table}${join}`);
 				(await s.remote.getClient().liveOf(uuid)).subscribe((message) => {
 					if (message.action === "KILLED") return;
 					const hash = hashOfEdge(message.value);
-					if (hash) onChange([hash]);
+					if (!hash) return;
+					const row = message.action === "DELETE" ? null : rowOfEdge(message.value);
+					onChange([hash], row ? [row] : void 0);
 				});
 				return String(uuid);
 			},

package/dist/otel/index.d.ts

@@ -1,4 +1,4 @@
-import { f as PinoTransmit } from "../types.js";
+import { p as PinoTransmit } from "../types.js";
 import { Level } from "pino";
 
 //#region src/otel/index.d.ts

package/dist/types.d.ts

@@ -598,6 +598,26 @@ interface Sp00kyConfig<S extends SchemaStructure> {
    * freshness path and no duplicate one-shot fetches are made.
    */
   instantHydrate?: boolean;
+  /**
+   * Carry the changed row's body on the LIVE notification instead of going
+   * back for it.
+   *
+   * The client holds exactly one live subscription, on its `_00_list_ref`
+   * table, and today it is a doorbell: the notification is reduced to the
+   * query hash and the row is then pulled with `SELECT * FROM $ids`. The edge
+   * is a real graph edge, so `FETCH out` makes SurrealDB resolve the row into
+   * the notification and the body fetch disappears.
+   *
+   * The push stays advisory: the body is landed exactly the way a fetched body
+   * is (store write, circuit ingest, version recorded), so a notification the
+   * server drops costs nothing but the old round trip. Membership is still
+   * read back; only the body fetch is saved.
+   *
+   * Default `false`. The cost is wire bytes: one edit bumps the edge in every
+   * view holding the row, and under `FETCH` each of those notifications
+   * carries its own full copy of the body.
+   */
+  liveInlineBodies?: boolean;
   /**
    * Enable realtime sync while signed out. When `true`, the client starts its
    * `_00_list_ref` poll (and a LIVE subscription) against the shared
@@ -769,6 +789,17 @@ interface StorageHealth {
   role?: 'leader' | 'follower' | 'solo';
 }
 type QueryHash = string;
+/**
+ * One changed row delivered inline on a LIVE notification, when the
+ * subscription was opened with the body joined on (see
+ * {@link Sp00kyConfig.liveInlineBodies}). `version` is the edge's `version`,
+ * i.e. the same number the membership read would have reported for this row.
+ */
+interface InlineRow {
+  id: string;
+  version: number;
+  record: Record<string, unknown>;
+}
 type RecordVersionArray = Array<[string, number]>;
 /**
  * Represents the difference between two record version sets.
@@ -1057,4 +1088,4 @@ interface DebounceOptions {
   delay?: number;
 }
 //#endregion
-export { ServerViewMeta as A, TimingPhase as B, QueryTimings as C, RecordVersionDiff as D, RecordVersionArray as E, StorageHealthStatus as F, SealedQuery as G, LocalStore as H, StoreType as I, EventDefinition as K, SyncHealth as L, Sp00kyQueryResult as M, Sp00kyQueryResultPromise as N, RegistrationTimings as O, StorageHealth as P, SyncHealthConfig as R, QueryTimeToLive as S, ReconnectConfig as T, DatabaseEventSystem as U, UpdateOptions as V, DatabaseEventTypes as W, QueryConfigRecord as _, MATERIALIZATION_SAMPLE_WINDOW as a, QueryStatus as b, MutationEvent as c, PhaseStat as d, PinoTransmit as f, QueryConfig as g, QueryAuthorityCallback as h, Level$1 as i, Sp00kyConfig as j, RunOptions as k, MutationEventType as l, PreloadRefresh as m, DebounceOptions as n, MembershipOutcome as o, PreloadOptions as p, EventSystem as q, EventSubscriptionOptions as r, MutationCallback as s, ConnectionState as t, PersistenceClient as u, QueryHash as v, QueryUpdateCallback as w, QueryStatusCallback as x, QueryState as y, SyncHealthStatus as z };
+export { RunOptions as A, SyncHealthStatus as B, QueryTimeToLive as C, RecordVersionArray as D, ReconnectConfig as E, StorageHealth as F, DatabaseEventTypes as G, UpdateOptions as H, StorageHealthStatus as I, EventSystem as J, SealedQuery as K, StoreType as L, Sp00kyConfig as M, Sp00kyQueryResult as N, RecordVersionDiff as O, Sp00kyQueryResultPromise as P, SyncHealth as R, QueryStatusCallback as S, QueryUpdateCallback as T, LocalStore as U, TimingPhase as V, DatabaseEventSystem as W, QueryConfig as _, Level$1 as a, QueryState as b, MutationCallback as c, PersistenceClient as d, PhaseStat as f, QueryAuthorityCallback as g, PreloadRefresh as h, InlineRow as i, ServerViewMeta as j, RegistrationTimings as k, MutationEvent as l, PreloadOptions as m, DebounceOptions as n, MATERIALIZATION_SAMPLE_WINDOW as o, PinoTransmit as p, EventDefinition as q, EventSubscriptionOptions as r, MembershipOutcome as s, ConnectionState as t, MutationEventType as u, QueryConfigRecord as v, QueryTimings as w, QueryStatus as x, QueryHash as y, SyncHealthConfig as z };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spooky-sync/core",
-  "version": "0.0.1-canary.245",
+  "version": "0.0.1-canary.246",
   "type": "module",
   "sideEffects": false,
   "main": "./dist/index.js",
@@ -63,8 +63,8 @@
     }
   },
   "dependencies": {
-    "@spooky-sync/query-builder": "0.0.1-canary.245",
-    "@spooky-sync/ssp-wasm": "0.0.1-canary.245",
+    "@spooky-sync/query-builder": "0.0.1-canary.246",
+    "@spooky-sync/ssp-wasm": "0.0.1-canary.246",
     "@sqlite.org/sqlite-wasm": "3.53.0-build1",
     "@surrealdb/wasm": "^3.0.3",
     "blurhash": "^2.0.5",

package/src/client/router.ts

@@ -71,7 +71,7 @@ export function route(env: SagaEnv, event: RuntimeEvent): RouteTarget {
     case 'LiveStart':
       return { saga: liveStart(env), lane: serial('live') };
     case 'LiveChange':
-      return { saga: liveChange(event.hashes), lane: serial('live-change') };
+      return { saga: liveChange(env, event.hashes, event.rows), lane: serial('live-change') };
     case 'TabRole':
       return { saga: setRole(env, event.role), lane: serial('tabs') };
     case 'TabMessage':

package/src/client/services.ts

@@ -1,6 +1,6 @@
 import { RecordId, type Uuid } from 'surrealdb';
 import type { SchemaStructure } from '@spooky-sync/query-builder';
-import type { Sp00kyConfig, PersistenceClient } from '../types';
+import type { InlineRow, Sp00kyConfig, PersistenceClient } from '../types';
 import type { Logger } from '../services/logger/index';
 import { createLogger } from '../services/logger/index';
 import { ConnectionSupervisor, LocalMigrator, RemoteDatabaseService, createLocalEngine } from '../services/database/index';
@@ -216,6 +216,28 @@ export function hashOfEdge(value: unknown): string | null {
   return str.length > 0 ? str : null;
 }
 
+/**
+ * The row an edge notification carries, when the subscription joined it on.
+ *
+ * Without `FETCH out` the edge's `out` is a record id and there is nothing to
+ * land, so this returns null and the caller falls back to fetching the body.
+ * It also returns null for a row the session may not read (the join yields
+ * `out: null`) and for an edge whose target has been deleted.
+ */
+export function rowOfEdge(value: unknown): InlineRow | null {
+  const edge = value as { out?: unknown; version?: unknown } | null;
+  const out = edge?.out;
+  if (!out || typeof out !== 'object' || Array.isArray(out) || out instanceof RecordId) return null;
+  // Must be a real RecordId: the landing path keys off `row.id` being one, and
+  // would otherwise record the version for a body it never wrote.
+  const rid = (out as { id?: unknown }).id;
+  if (!(rid instanceof RecordId)) return null;
+  const id = encodeRecordId(rid);
+  const version = typeof edge?.version === 'number' ? edge.version : null;
+  if (version === null) return null;
+  return { id, version, record: out as Record<string, unknown> };
+}
+
 /** Build the adapters the interpreter drives from the services. */
 export function createAdapters<S extends SchemaStructure>(config: Sp00kyConfig<S>, s: Services<S>, host: ServiceHost, lateModules: () => { init(): void }[]): Adapters {
   const timers = new Map<string, ReturnType<typeof setTimeout>>();
@@ -305,12 +327,23 @@ export function createAdapters<S extends SchemaStructure>(config: Sp00kyConfig<S
     remote: {
       queryResponses: (sql, vars) => s.remote.queryResponses(sql, vars),
       live: async (table, onChange) => {
-        const [uuid] = await s.remote.query<[Uuid]>(`LIVE SELECT * FROM ${table}`);
+        // `FETCH out` resolves the edge's target into the notification, so the
+        // body arrives with the doorbell instead of costing a second round
+        // trip. The clause is only ever added, never relied on: a server that
+        // ignores it, or a row the session cannot read, simply yields no
+        // inline row and the fetch path takes over.
+        const join = config.liveInlineBodies ? ' FETCH out' : '';
+        const [uuid] = await s.remote.query<[Uuid]>(`LIVE SELECT * FROM ${table}${join}`);
         const live = await s.remote.getClient().liveOf(uuid);
         live.subscribe((message) => {
           if (message.action === 'KILLED') return;
           const hash = hashOfEdge(message.value);
-          if (hash) onChange([hash]);
+          if (!hash) return;
+          // Not on DELETE: that edge is a row leaving the view, and for a row
+          // that was actually deleted the join yields nothing anyway. Landing
+          // a body there would only ever write back what is going away.
+          const row = message.action === 'DELETE' ? null : rowOfEdge(message.value);
+          onChange([hash], row ? [row] : undefined);
         });
         return String(uuid);
       },

package/src/kernel/events.ts

@@ -1,4 +1,4 @@
-import type { ConnectionState, QueryHash, QueryStatus, SyncHealth } from '../types';
+import type { ConnectionState, InlineRow, QueryHash, QueryStatus, SyncHealth } from '../types';
 import type { StreamUpdate } from '../services/stream-processor/index';
 
 /**
@@ -33,7 +33,7 @@ export type RuntimeEvent =
   | { type: 'ConnectionChanged'; state: ConnectionState }
   | { type: 'StreamUpdate'; update: StreamUpdate }
   | { type: 'LiveStart' }
-  | { type: 'LiveChange'; hashes: QueryHash[] }
+  | { type: 'LiveChange'; hashes: QueryHash[]; rows?: InlineRow[] }
   | { type: 'TabRole'; role: 'solo' | 'leader' | 'follower' }
   | { type: 'TabMessage'; message: unknown };
 

package/src/kernel/interpreter.ts

@@ -2,6 +2,7 @@ import { Duration } from 'surrealdb';
 import type { LocalStore } from '../services/database/cache-engine';
 import type { IngestRecord, StreamUpdate } from '../services/stream-processor/index';
 import type { ClientState } from '../state/client-state';
+import type { InlineRow } from '../types';
 import { withTimeout } from '../utils/index';
 import type { Effect, RegisterResult, ServiceCalls, Settled, StatementResult } from './effects';
 import type { OutEvent, RuntimeEvent } from './events';
@@ -11,8 +12,12 @@ export interface Adapters {
   local: Pick<LocalStore, 'query' | 'execute' | 'select' | 'getById' | 'upsert' | 'delete'> & { readonly epoch: number };
   remote: {
     queryResponses(sql: string, vars?: Record<string, unknown>): Promise<StatementResult[]>;
-    /** Subscribe to `LIVE SELECT * FROM <table>`; the callback receives the changed query hashes. */
-    live(table: string, onChange: (hashes: string[]) => void): Promise<string>;
+    /**
+     * Subscribe to `LIVE SELECT * FROM <table>`; the callback receives the
+     * changed query hashes, plus the changed rows themselves when the
+     * subscription was opened with the body joined on (`liveInlineBodies`).
+     */
+    live(table: string, onChange: (hashes: string[], rows?: InlineRow[]) => void): Promise<string>;
     kill(uuid: string): Promise<void>;
   };
   ssp: {
@@ -76,7 +81,7 @@ export function createInterpreter(adapters: Adapters, host: InterpreterHost): In
           : pending;
       }
       case 'remote.live':
-        return adapters.remote.live(effect.table, (hashes) => host.dispatch({ type: 'LiveChange', hashes }));
+        return adapters.remote.live(effect.table, (hashes, rows) => host.dispatch({ type: 'LiveChange', hashes, rows }));
       case 'remote.kill':
         return adapters.remote.kill(effect.uuid);
       case 'ssp.register': {

package/src/query/fetch.saga.ts

@@ -60,8 +60,14 @@ export function* fetchRows(env: SagaEnv): Saga<void> {
   }
 }
 
-/** Write one chunk's bodies to the store and circuit; record their versions. */
-function* landChunk(
+/**
+ * Write one chunk's bodies to the store and circuit; record their versions.
+ *
+ * Shared with the LIVE path: a body that arrives on a notification is landed
+ * through here so it is indistinguishable from a fetched one, which is what
+ * makes `planFetch` stop asking for it.
+ */
+export function* landChunk(
   env: SagaEnv,
   requested: string[],
   rows: Array<Record<string, unknown>>,

package/src/sync/live.saga.test.ts

@@ -1,9 +1,11 @@
 import { describe, expect, it } from 'vitest';
+import { RecordId } from 'surrealdb';
 import { runPure } from '../testing/run-pure';
 import { buildEntry, buildState } from '../testing/build';
 import * as R from '../state/reducers';
 import { defaultEnv } from '../query/env';
 import { liveChange, liveInvalidate, liveStart } from './live.saga';
+import { rowOfEdge } from '../client/services';
 
 const env = defaultEnv({ tables: [] } as any);
 
@@ -56,14 +58,80 @@ describe('liveStart', () => {
 describe('liveChange', () => {
   it('marks known hashes dirty, resets the poll streak, relays as leader; ignores unknown hashes', async () => {
     const s = R.patchSync({ pollIdleStreak: 3 })(buildState([buildEntry({ def: { hash: 'a' } })]));
-    const out = await runPure(liveChange(['a', 'zz']), { state: { ...s, tabRole: 'leader' } });
+    const out = await runPure(liveChange(env, ['a', 'zz']), { state: { ...s, tabRole: 'leader' } });
     expect([...out.state.membershipDirty]).toEqual(['a']);
     expect(out.state.sync.pollIdleStreak).toBe(0);
     expect(out.timers.get('membership')).toEqual({ ms: 50, event: { type: 'ReadDirtyMembership' } });
     expect(out.emitted).toEqual([{ type: 'tabs:broadcast', message: { type: 'membership-dirty', hashes: ['a'] } }]);
-    const solo = await runPure(liveChange(['a']), { state: s });
+    const solo = await runPure(liveChange(env, ['a']), { state: s });
     expect(solo.emitted).toEqual([]);
-    const none = await runPure(liveChange(['zz']), { state: s });
+    const none = await runPure(liveChange(env, ['zz']), { state: s });
     expect(none.timers.size).toBe(0);
   });
 });
+
+describe('rowOfEdge', () => {
+  const rid = new RecordId('game', 'g1');
+
+  it('reads the joined body off the notification', () => {
+    expect(rowOfEdge({ in: new RecordId('_00_query', 'a'), out: { id: rid, result: '1-0' }, version: 7 })).toEqual({
+      id: 'game:g1',
+      version: 7,
+      record: { id: rid, result: '1-0' },
+    });
+  });
+
+  it('yields nothing when there is no body to read', () => {
+    // No FETCH clause: `out` is still just the record id.
+    expect(rowOfEdge({ out: rid, version: 7 })).toBeNull();
+    // The session may not read the row, or its target is gone.
+    expect(rowOfEdge({ out: null, version: 7 })).toBeNull();
+    // A body with no version cannot be placed against what we already hold.
+    expect(rowOfEdge({ out: { id: rid }, version: undefined })).toBeNull();
+    // `landChunk` keys off a real RecordId; a string id would record the
+    // version for a body it never wrote.
+    expect(rowOfEdge({ out: { id: 'game:g1' }, version: 7 })).toBeNull();
+    expect(rowOfEdge(null)).toBeNull();
+  });
+});
+
+describe('liveChange with the body joined on', () => {
+  const rid = new RecordId('game', 'g1');
+  const row = (version: number) => ({ id: 'game:g1', version, record: { id: rid, result: '1-0' } });
+  const handlers = { 'local.execute': () => undefined, 'ssp.ingest': () => undefined };
+
+  it('lands the pushed body so the fetch plan has nothing left to pull', async () => {
+    const s = buildState([buildEntry({ def: { hash: 'a' } })]);
+    const out = await runPure(liveChange(env, ['a'], [row(7)]), { state: s, handlers });
+
+    // Recorded at the edge's version: this is what makes `planFetch` skip it.
+    expect(out.state.versions.get('game:g1')).toBe(7);
+    // Written to the store and ingested into the circuit, exactly as a fetch would.
+    expect(out.log.filter((e) => e.kind === 'local.execute')).toHaveLength(1);
+    expect(out.log.filter((e) => e.kind === 'ssp.ingest')).toHaveLength(1);
+    // Still a doorbell: membership is re-read regardless.
+    expect([...out.state.membershipDirty]).toEqual(['a']);
+  });
+
+  it('ignores a body we already hold at that version or newer', async () => {
+    const s = R.setVersions([['game:g1', 7]])(buildState([buildEntry({ def: { hash: 'a' } })]));
+    const out = await runPure(liveChange(env, ['a'], [row(7)]), { state: s, handlers });
+    expect(out.log.filter((e) => e.kind === 'local.execute')).toHaveLength(0);
+    expect([...out.state.membershipDirty]).toEqual(['a']);
+  });
+
+  it('writes one copy when the same row arrives for several views', async () => {
+    const s = buildState([buildEntry({ def: { hash: 'a' } })]);
+    const out = await runPure(liveChange(env, ['a'], [row(7), row(7), row(8)]), { state: s, handlers });
+    expect(out.log.filter((e) => e.kind === 'local.execute')).toHaveLength(1);
+    expect(out.state.versions.get('game:g1')).toBe(8);
+  });
+
+  it('behaves exactly as before when no body rode along', async () => {
+    const s = buildState([buildEntry({ def: { hash: 'a' } })]);
+    const out = await runPure(liveChange(env, ['a']), { state: s, handlers });
+    expect(out.log.filter((e) => e.kind === 'local.execute')).toHaveLength(0);
+    expect(out.state.versions.size).toBe(0);
+    expect([...out.state.membershipDirty]).toEqual(['a']);
+  });
+});

package/src/sync/live.saga.ts

@@ -1,4 +1,4 @@
-import type { QueryHash } from '../types';
+import type { InlineRow, QueryHash } from '../types';
 import type { Saga } from '../kernel/saga';
 import { fx } from '../kernel/effects';
 import type { ClientState } from '../state/client-state';
@@ -6,12 +6,18 @@ import * as R from '../state/reducers';
 import type { SagaEnv } from '../query/env';
 import { listRefTable } from '../query/env';
 import { markMembershipDirty } from '../query/membership.saga';
+import { landChunk } from '../query/fetch.saga';
 
 /**
- * LIVE on the session's `_00_list_ref` table. Events never carry data into
- * state: every change only marks its query's membership dirty, and the
- * batched re-read decides. Followers get the same dirt relayed by the
- * leader.
+ * LIVE on the session's `_00_list_ref` table. An event marks its query's
+ * membership dirty and the batched re-read decides; followers get the same
+ * dirt relayed by the leader.
+ *
+ * When the subscription was opened with the body joined on
+ * (`liveInlineBodies`) the event ALSO carries the changed row. That is an
+ * optimisation on top, never a source of truth: the row is landed exactly as a
+ * fetched body would be, so a notification the server drops costs nothing but
+ * the round trip it would have saved.
  */
 export function* liveStart(env: SagaEnv): Saga<void> {
   const state = (yield fx.state.read((s) => s)) as ClientState;
@@ -40,10 +46,42 @@ export function* liveInvalidate(): Saga<void> {
 }
 
 /** One or more edges of these queries changed on the server. */
-export function* liveChange(hashes: QueryHash[]): Saga<void> {
+export function* liveChange(env: SagaEnv, hashes: QueryHash[], rows?: InlineRow[]): Saga<void> {
   const [known, role] = (yield fx.state.read((s) => [hashes.filter((h) => s.queries.has(h)), s.tabRole])) as [QueryHash[], ClientState['tabRole']];
   if (known.length === 0) return;
   yield fx.state.update(R.patchSync({ pollIdleStreak: 0 }));
+  // Before marking membership dirty: recording the version here is what makes
+  // the re-read's `planFetch` find nothing left to pull for this row.
+  if (rows && rows.length > 0) yield* landInlineRows(env, rows);
   yield* markMembershipDirty(known);
   if (role === 'leader') yield fx.emit({ type: 'tabs:broadcast', message: { type: 'membership-dirty', hashes: known } });
 }
+
+/**
+ * Land bodies that rode in on the notification. Rows already held at this
+ * version or newer are dropped: one edit bumps the edge in every view holding
+ * the row, so the same body arrives once per view.
+ */
+function* landInlineRows(env: SagaEnv, rows: InlineRow[]): Saga<void> {
+  const state = (yield fx.state.read((s) => s)) as ClientState;
+  const fresh = new Map<string, InlineRow>();
+  for (const row of rows) {
+    if ((state.versions.get(row.id) ?? -1) >= row.version) continue;
+    const held = fresh.get(row.id);
+    if (!held || held.version < row.version) fresh.set(row.id, row);
+  }
+  if (fresh.size === 0) return;
+  const picked = [...fresh.values()];
+  const epoch = (yield fx.local.epoch()) as number;
+  const landed = yield* landChunk(
+    env,
+    picked.map((r) => r.id),
+    picked.map((r) => r.record),
+    new Map(picked.map((r) => [r.id, r.version] as const)),
+    state,
+    epoch
+  );
+  if (!landed) {
+    yield fx.emit({ type: 'log', level: 'debug', message: 'inline live body not landed; the fetch path will pull it', data: { ids: picked.map((r) => r.id) } });
+  }
+}

package/src/sync/tabs.saga.ts

@@ -63,7 +63,8 @@ export function* tabMessage(env: SagaEnv, raw: unknown): Saga<void> {
       return;
     }
     case 'membership-dirty':
-      if (Array.isArray(msg.hashes)) yield* liveChange(msg.hashes);
+      // No inline rows here: the leader relays its own bodies as an `ingest`.
+      if (Array.isArray(msg.hashes)) yield* liveChange(env, msg.hashes);
       return;
     case 'outbox-changed':
       if (role !== 'leader') return;

package/src/types.ts

@@ -292,6 +292,26 @@ export interface Sp00kyConfig<S extends SchemaStructure> {
    * freshness path and no duplicate one-shot fetches are made.
    */
   instantHydrate?: boolean;
+  /**
+   * Carry the changed row's body on the LIVE notification instead of going
+   * back for it.
+   *
+   * The client holds exactly one live subscription, on its `_00_list_ref`
+   * table, and today it is a doorbell: the notification is reduced to the
+   * query hash and the row is then pulled with `SELECT * FROM $ids`. The edge
+   * is a real graph edge, so `FETCH out` makes SurrealDB resolve the row into
+   * the notification and the body fetch disappears.
+   *
+   * The push stays advisory: the body is landed exactly the way a fetched body
+   * is (store write, circuit ingest, version recorded), so a notification the
+   * server drops costs nothing but the old round trip. Membership is still
+   * read back; only the body fetch is saved.
+   *
+   * Default `false`. The cost is wire bytes: one edit bumps the edge in every
+   * view holding the row, and under `FETCH` each of those notifications
+   * carries its own full copy of the body.
+   */
+  liveInlineBodies?: boolean;
   /**
    * Enable realtime sync while signed out. When `true`, the client starts its
    * `_00_list_ref` poll (and a LIVE subscription) against the shared
@@ -469,6 +489,18 @@ export interface StorageHealth {
 
 export type QueryHash = string;
 
+/**
+ * One changed row delivered inline on a LIVE notification, when the
+ * subscription was opened with the body joined on (see
+ * {@link Sp00kyConfig.liveInlineBodies}). `version` is the edge's `version`,
+ * i.e. the same number the membership read would have reported for this row.
+ */
+export interface InlineRow {
+  id: string;
+  version: number;
+  record: Record<string, unknown>;
+}
+
 // Flat array format: [[record-id, version], [record-id, version], ...]
 export type RecordVersionArray = Array<[string, number]>;