@spooky-sync/core 0.0.1-canary.205 → 0.0.1-canary.207

package/dist/index.d.ts

@@ -537,15 +537,29 @@ declare class CacheModule implements StreamUpdateReceiver {
   private versionLookups;
   /** Shared-tabs leader: fan every committed ingest out to follower circuits.
    *  Fired AFTER the local tx (the rows are already in the shared store, so a
-   *  follower only needs the circuit feed). Never set on followers. */
+   *  follower only needs the circuit feed). A follower relays its own
+   *  mutations to the leader the same way, see {@link setIngestRelay}. */
   private ingestRelay;
+  /** See {@link setIngestRelay}. */
+  private relayLocalWritesOnly;
   constructor(local: LocalStore, streamProcessor: StreamProcessorService, streamUpdateCallback: (update: StreamUpdate) => void, logger: Logger$1);
   /**
    * Implements StreamUpdateReceiver interface
    * Called directly by StreamProcessor when views change
    */
   onStreamUpdate(update: StreamUpdate): void;
-  setIngestRelay(cb: ((tuples: CacheIngestTuple[]) => void) | null): void;
+  /**
+   * Fan every committed ingest out to the other tabs. The leader relays
+   * everything (its sync fetches are the only copy the followers get). A
+   * follower relays with `localWritesOnly`: just the mutation path, which is
+   * the only thing it knows that the leader does not. Its sync-fetched
+   * batches are the leader's data coming back and must not be re-broadcast,
+   * or every follower registration would fan its whole working set to
+   * every tab.
+   */
+  setIngestRelay(cb: ((tuples: CacheIngestTuple[]) => void) | null, opts?: {
+    localWritesOnly?: boolean;
+  }): void;
   /**
    * Shared-tabs follower: feed relayed tuples into THIS tab's circuit only.
    * The rows are already in the shared store (the leader wrote them), so no
@@ -606,6 +620,12 @@ declare class CacheModule implements StreamUpdateReceiver {
  * Merges the functionality of QueryManager and MutationManager.
  * Uses CacheModule for all storage operations.
  */
+/** A `_00_window` row as read back: the id-set and whether the server vouched
+ *  for it (which is what allows an empty set to count as known membership). */
+interface DurableMembership {
+  ids: RecordVersionArray;
+  confirmed: boolean;
+}
 declare class DataModule<S extends SchemaStructure> {
   private cache;
   private local;
@@ -901,11 +921,25 @@ declare class DataModule<S extends SchemaStructure> {
    * authoritative membership on this device. Any read error is treated as
    * "unknown" so a broken row degrades to the predicate scan rather than
    * rendering an empty list.
+   *
+   * `confirmed` is true only for rows written after the server itself vouched
+   * for the set (a non-empty id-set, or an empty one it reported a row count of
+   * zero for, or an empty one that followed a non-empty one in the same
+   * session). Rows written before the marker existed, including the `[]` rows a
+   * pre-`ea56f50e` client mirrored from an unflushed read, read as unconfirmed.
    */
-  getWindowMembership(key: string): Promise<RecordVersionArray | null>;
-  /** Persist the durable membership row. Best-effort: callers must not fail a
-   *  sync round because the mirror write failed. */
-  writeWindowMembership(key: string, ids: RecordVersionArray): Promise<void>;
+  getWindowMembership(key: string): Promise<DurableMembership | null>;
+  /**
+   * Persist the durable membership row. Best-effort: callers must not fail a
+   * sync round because the mirror write failed.
+   *
+   * `confirmed` says whether a cold start may trust this row even when it is
+   * empty. A confirmed empty is a real answer ("the server says this query has
+   * no rows") and stays empty across a reload; an unconfirmed empty is the
+   * retry budget's guess and falls back to the predicate scan on the next boot,
+   * exactly as every empty row did before the marker existed.
+   */
+  writeWindowMembership(key: string, ids: RecordVersionArray, confirmed: boolean): Promise<void>;
   /**
    * Record ids with a mutation still in the outbox, split by direction.
    *
@@ -1015,6 +1049,15 @@ declare class DataModule<S extends SchemaStructure> {
    * Rollback a failed optimistic update by restoring the previous record state
    */
   rollbackUpdate(recordId: RecordId, tableName: string, beforeRecord: Record<string, unknown>): Promise<void>;
+  /**
+   * Force a re-materialize + notify of every active query on `tableName`.
+   * Used after a DELETE landed in the local store (this tab's own, or one
+   * relayed from another tab): the SSP may not emit a view update for a
+   * DELETE ingest, and the re-materialize reads the store, which already
+   * excludes the row. Each query is isolated so one failing re-materialize
+   * can't stop the others.
+   */
+  notifyTableQueries(tableName: string): Promise<void>;
   /**
    * Remove a record from all active query states and notify subscribers
    */
@@ -1065,6 +1108,14 @@ type FollowerToLeaderMessage = {
   mutationId: string;
 } | {
   type: 'request-poll';
+}
+/** An optimistic write this follower committed to the SHARED store and
+ *  ingested into its own circuit. The leader ingests it (no DB write, the
+ *  row is already there) and fans it out to every OTHER follower as
+ *  `ingest-relay`, so a follower's write lands in every tab in one hop
+ *  instead of after the server round-trip. */ | {
+  type: 'ingest';
+  tuples: IngestTuple[];
 };
 type LeaderToFollowerMessage = {
   type: 'db-ready';
@@ -1094,6 +1145,15 @@ type LeaderToFollowerMessage = {
   recordId: string;
   eventType: 'create' | 'update' | 'delete';
   error: string;
+}
+/** The leader's drain pushed a mutation and deleted its outbox row from the
+ *  SHARED store. Every follower starts its settled-write grace so a row it
+ *  was rendering as a pending write does not blink out before its
+ *  `_00_list_ref` membership arrives. */ | {
+  type: 'mutation-settled';
+  mutationId: string;
+  recordId: string;
+  eventType: 'create' | 'update' | 'delete';
 };
 //#endregion
 //#region src/services/tabs/coordinator.d.ts
@@ -1130,6 +1190,11 @@ declare class SyncForwarder {
   unbind(): void;
   private post;
   mutationEnqueued(mutationId: string): void;
+  /** An optimistic write this tab just ingested. Deliberately NOT queued while
+   *  detached: a new leader primes its circuit from the shared store, which
+   *  already holds the row, and replaying a stale tuple at it later would put
+   *  an older `_00_rv` in its version memo. */
+  ingest(tuples: IngestTuple[]): void;
   requestPoll(): void;
 }
 //#endregion
@@ -1361,6 +1426,13 @@ declare class Sp00kySync<S extends SchemaStructure> {
   private onMutationDropped;
   /** A forwarded outbox row from a follower: load + drain it. Idempotent. */
   enqueueForwardedMutation(mutationId: string): Promise<void>;
+  /**
+   * Tuples another tab already committed to the shared store: feed them to
+   * THIS tab's circuit (no local write). A DELETE additionally forces a
+   * re-materialize of the table's queries, exactly as the writing tab does
+   * for itself, because the SSP may not emit a view update for it.
+   */
+  private applyRelayedIngest;
   /** A relayed `_00_list_ref` LIVE event: resolve against THIS tab's queries
    *  and run the exact same handling the LIVE subscription would have. */
   private applyRelayedListRefChange;

package/dist/index.js

@@ -3321,12 +3321,6 @@ function phaseStatOf(samples, lastMs) {
 		count: samples.length
 	};
 }
-/**
-* DataModule - Unified query and mutation management
-*
-* Merges the functionality of QueryManager and MutationManager.
-* Uses CacheModule for all storage operations.
-*/
 var DataModule = class DataModule {
 	/** Tab identity baked into mutation ids (shared-tabs rollback routing);
 	*  undefined in solo mode, where mutation-id falls back to a session id. */
@@ -4030,23 +4024,42 @@ var DataModule = class DataModule {
 	* authoritative membership on this device. Any read error is treated as
 	* "unknown" so a broken row degrades to the predicate scan rather than
 	* rendering an empty list.
+	*
+	* `confirmed` is true only for rows written after the server itself vouched
+	* for the set (a non-empty id-set, or an empty one it reported a row count of
+	* zero for, or an empty one that followed a non-empty one in the same
+	* session). Rows written before the marker existed, including the `[]` rows a
+	* pre-`ea56f50e` client mirrored from an unflushed read, read as unconfirmed.
 	*/
 	async getWindowMembership(key) {
 		try {
 			const row = await this.local.getById("_00_window", new RecordId("_00_window", key));
 			if (!row || typeof row !== "object") return null;
 			const ids = row.ids;
-			return Array.isArray(ids) ? ids : null;
+			if (!Array.isArray(ids)) return null;
+			return {
+				ids,
+				confirmed: row.confirmed === true
+			};
 		} catch {
 			return null;
 		}
 	}
-	/** Persist the durable membership row. Best-effort: callers must not fail a
-	*  sync round because the mirror write failed. */
-	async writeWindowMembership(key, ids) {
+	/**
+	* Persist the durable membership row. Best-effort: callers must not fail a
+	* sync round because the mirror write failed.
+	*
+	* `confirmed` says whether a cold start may trust this row even when it is
+	* empty. A confirmed empty is a real answer ("the server says this query has
+	* no rows") and stays empty across a reload; an unconfirmed empty is the
+	* retry budget's guess and falls back to the predicate scan on the next boot,
+	* exactly as every empty row did before the marker existed.
+	*/
+	async writeWindowMembership(key, ids, confirmed) {
 		try {
 			await this.local.upsert("_00_window", new RecordId("_00_window", key), {
 				ids,
+				confirmed,
 				updatedAt: Date.now()
 			}, "replace");
 		} catch (err) {
@@ -4205,9 +4218,12 @@ var DataModule = class DataModule {
 			}, "Query to update remote array not found");
 			return;
 		}
+		let confirmed = remoteArray.length > 0 || queryState.config.remoteSeen === true;
 		if (remoteArray.length === 0 && !queryState.config.remoteSeen) {
 			const serverRowCount = opts?.serverRowCount;
-			if (!(serverRowCount === 0)) {
+			const knownEmpty = serverRowCount === 0;
+			confirmed = knownEmpty;
+			if (!knownEmpty) {
 				const emptyReads = (queryState.config.emptyReads ?? 0) + 1;
 				queryState.config.emptyReads = emptyReads;
 				if (!(serverRowCount === null || serverRowCount === void 0 ? emptyReads >= EMPTY_MEMBERSHIP_CONFIRMATIONS : false)) {
@@ -4228,7 +4244,7 @@ var DataModule = class DataModule {
 			queryState.config.remoteSeen = true;
 			queryState.config.emptyReads = 0;
 		}
-		if (queryState.config.membershipKey) await this.writeWindowMembership(queryState.config.membershipKey, remoteArray);
+		if (queryState.config.membershipKey) await this.writeWindowMembership(queryState.config.membershipKey, remoteArray, confirmed);
 		try {
 			await this.local.query(surql.seal(surql.updateSet("id", ["remoteArray"])), {
 				id: queryState.config.id,
@@ -4281,8 +4297,8 @@ var DataModule = class DataModule {
 			config.emptyReads = 0;
 			if (config.membershipKey) {
 				const durable = await this.getWindowMembership(config.membershipKey);
-				if (durable?.length) {
-					config.remoteArray = durable;
+				if (durable && (durable.ids.length > 0 || durable.confirmed)) {
+					config.remoteArray = durable.ids;
 					config.membershipKnown = true;
 				}
 			}
@@ -4515,15 +4531,7 @@ var DataModule = class DataModule {
 				Category: "sp00ky-client::DataModule::delete"
 			}, "SSP delete-ingest failed; relying on query re-materialize to reflect the delete");
 		}
-		for (const [queryHash, queryState] of this.activeQueries) if (queryState.config.tableName === tableName) try {
-			await this.notifyQuerySynced(queryHash);
-		} catch (err) {
-			this.logger.error({
-				err,
-				queryHash,
-				Category: "sp00ky-client::DataModule::delete"
-			}, "notifyQuerySynced failed after delete");
-		}
+		await this.notifyTableQueries(tableName);
 		const mutationEvent = {
 			type: "delete",
 			mutation_id: mutationId,
@@ -4594,6 +4602,26 @@ var DataModule = class DataModule {
 		}
 	}
 	/**
+	* Force a re-materialize + notify of every active query on `tableName`.
+	* Used after a DELETE landed in the local store (this tab's own, or one
+	* relayed from another tab): the SSP may not emit a view update for a
+	* DELETE ingest, and the re-materialize reads the store, which already
+	* excludes the row. Each query is isolated so one failing re-materialize
+	* can't stop the others.
+	*/
+	async notifyTableQueries(tableName) {
+		for (const [queryHash, queryState] of this.activeQueries) if (queryState.config.tableName === tableName) try {
+			await this.notifyQuerySynced(queryHash);
+		} catch (err) {
+			this.logger.error({
+				err,
+				queryHash,
+				tableName,
+				Category: "sp00ky-client::DataModule::notifyTableQueries"
+			}, "notifyQuerySynced failed after delete");
+		}
+	}
+	/**
 	* Remove a record from all active query states and notify subscribers
 	*/
 	removeRecordFromQueries(recordId) {
@@ -4712,8 +4740,8 @@ var DataModule = class DataModule {
 		};
 		if (membershipKey && !config.remoteArray?.length) {
 			const durable = await this.getWindowMembership(membershipKey);
-			if (durable?.length) {
-				config.remoteArray = durable;
+			if (durable && (durable.ids.length > 0 || durable.confirmed)) {
+				config.remoteArray = durable.ids;
 				config.membershipKnown = true;
 			}
 		} else if (config.remoteArray?.length) config.membershipKnown = true;
@@ -6118,8 +6146,14 @@ var Sp00kySync = class Sp00kySync {
 			switch (msg.type) {
 				case "sync-hello": break;
 				case "mutation-enqueued":
+					this.listRefIdleStreak = 0;
 					this.enqueueForwardedMutation(msg.mutationId);
 					break;
+				case "ingest":
+					this.applyRelayedIngest(msg.tuples);
+					hub.relayIngest(msg.tuples, tabId);
+					this.listRefIdleStreak = 0;
+					break;
 				case "request-poll":
 					this.listRefIdleStreak = 0;
 					break;
@@ -6164,6 +6198,12 @@ var Sp00kySync = class Sp00kySync {
 		this.killRefLiveQuery();
 		forwarder.onLeaderMessage = (msg) => {
 			switch (msg.type) {
+				case "ingest-relay":
+					this.applyRelayedIngest(msg.tuples);
+					break;
+				case "mutation-settled":
+					this.dataModule.noteWriteSettled(msg.recordId, msg.eventType);
+					break;
 				case "list-ref-change":
 					this.applyRelayedListRefChange(msg).catch((err) => {
 						this.logger.error({
@@ -6209,6 +6249,24 @@ var Sp00kySync = class Sp00kySync {
 		if (this.tabRole !== "leader") return;
 		await this.upQueue.enqueueFromDatabase(mutationId);
 	}
+	/**
+	* Tuples another tab already committed to the shared store: feed them to
+	* THIS tab's circuit (no local write). A DELETE additionally forces a
+	* re-materialize of the table's queries, exactly as the writing tab does
+	* for itself, because the SSP may not emit a view update for it.
+	*/
+	applyRelayedIngest(tuples) {
+		this.cache.applyRelayedIngest(tuples);
+		const deletedTables = /* @__PURE__ */ new Set();
+		for (const t of tuples) if (t.op === "DELETE") deletedTables.add(t.table);
+		for (const table of deletedTables) this.dataModule.notifyTableQueries(table).catch((err) => {
+			this.logger.warn({
+				err,
+				table,
+				Category: "sp00ky-client::Sp00kySync::applyRelayedIngest"
+			}, "Re-materialize after relayed delete failed");
+		});
+	}
 	/** A relayed `_00_list_ref` LIVE event: resolve against THIS tab's queries
 	*  and run the exact same handling the LIVE subscription would have. */
 	async applyRelayedListRefChange(msg) {
@@ -6601,8 +6659,20 @@ var Sp00kySync = class Sp00kySync {
 		}, "Live update is being processed");
 		const diff = createDiffFromDbOp(action, recordId, version, localArray);
 		const hash = extractIdPart(existing.config.id);
-		if (existing.config.membershipKnown && (diff.removed.length || diff.added.length)) {
-			const next = applyRecordVersionDiff(existing.config.remoteArray ?? [], diff);
+		if (existing.config.membershipKnown) {
+			const membershipDiff = action === "DELETE" ? {
+				added: [],
+				updated: [],
+				removed: [recordId]
+			} : {
+				added: [{
+					id: recordId,
+					version
+				}],
+				updated: [],
+				removed: []
+			};
+			const next = applyRecordVersionDiff(existing.config.remoteArray ?? [], membershipDiff);
 			if (!recordVersionArraysEqual(next, existing.config.remoteArray ?? [])) await this.dataModule.updateQueryRemoteArray(hash, next);
 		}
 		await this.runSyncForQuery(hash, diff);
@@ -6721,7 +6791,14 @@ var Sp00kySync = class Sp00kySync {
 	* vanish, and return, while every other client showed it throughout.
 	*/
 	handleMutationSettled(event) {
-		this.dataModule.noteWriteSettled(encodeRecordId(event.record_id), event.type);
+		const recordId = encodeRecordId(event.record_id);
+		this.dataModule.noteWriteSettled(recordId, event.type);
+		this.hub?.broadcast({
+			type: "mutation-settled",
+			mutationId: encodeRecordId(event.mutation_id),
+			recordId,
+			eventType: event.type
+		});
 	}
 	async handleRollback(event, error) {
 		const recordId = encodeRecordId(event.record_id);
@@ -7337,8 +7414,8 @@ function selfAllowlistedVariant(flag, userId) {
 
 //#endregion
 //#region src/modules/devtools/index.ts
-const CORE_VERSION = "0.0.1-canary.205";
-const WASM_VERSION = "0.0.1-canary.205";
+const CORE_VERSION = "0.0.1-canary.207";
+const WASM_VERSION = "0.0.1-canary.207";
 const SURREAL_VERSION = "3.0.3";
 var DevToolsService = class DevToolsService {
 	eventsHistory = [];
@@ -7439,6 +7516,9 @@ var DevToolsService = class DevToolsService {
 				data: q.records,
 				localArray: q.config.localArray,
 				remoteArray: q.config.remoteArray,
+				membershipKnown: q.config.membershipKnown === true,
+				remoteSeen: q.config.remoteSeen === true,
+				emptyReads: q.config.emptyReads ?? 0,
 				timings: this.dataManager.phaseTimings(q)
 			});
 		});
@@ -8864,8 +8944,11 @@ var CacheModule = class {
 	versionLookups = {};
 	/** Shared-tabs leader: fan every committed ingest out to follower circuits.
 	*  Fired AFTER the local tx (the rows are already in the shared store, so a
-	*  follower only needs the circuit feed). Never set on followers. */
+	*  follower only needs the circuit feed). A follower relays its own
+	*  mutations to the leader the same way, see {@link setIngestRelay}. */
 	ingestRelay = null;
+	/** See {@link setIngestRelay}. */
+	relayLocalWritesOnly = false;
 	constructor(local, streamProcessor, streamUpdateCallback, logger) {
 		this.local = local;
 		this.streamProcessor = streamProcessor;
@@ -8885,8 +8968,18 @@ var CacheModule = class {
 		}, "Stream update received");
 		this.streamUpdateCallback(update);
 	}
-	setIngestRelay(cb) {
+	/**
+	* Fan every committed ingest out to the other tabs. The leader relays
+	* everything (its sync fetches are the only copy the followers get). A
+	* follower relays with `localWritesOnly`: just the mutation path, which is
+	* the only thing it knows that the leader does not. Its sync-fetched
+	* batches are the leader's data coming back and must not be re-broadcast,
+	* or every follower registration would fan its whole working set to
+	* every tab.
+	*/
+	setIngestRelay(cb, opts = {}) {
 		this.ingestRelay = cb;
+		this.relayLocalWritesOnly = opts.localWritesOnly === true;
 	}
 	/**
 	* Shared-tabs follower: feed relayed tuples into THIS tab's circuit only.
@@ -8977,7 +9070,7 @@ var CacheModule = class {
 			});
 			const ingested = this.streamProcessor.ingestMany(bulk);
 			for (const t of ingested) this.versionLookups[t.id] = versionOf.get(t.id) ?? 0;
-			if (ingested.length > 0) this.ingestRelay?.(ingested);
+			if (ingested.length > 0 && (!this.relayLocalWritesOnly || skipDbInsert)) this.ingestRelay?.(ingested);
 			this.logger.debug({
 				count: records.length,
 				Category: "sp00ky-client::CacheModule::saveBatch"
@@ -9018,7 +9111,7 @@ var CacheModule = class {
 				id,
 				record: recordData
 			}]);
-			this.ingestRelay?.([{
+			if (!this.relayLocalWritesOnly || skipDbDelete) this.ingestRelay?.([{
 				table,
 				op: "DELETE",
 				id,
@@ -10598,6 +10691,19 @@ var SyncForwarder = class {
 			mutationId
 		});
 	}
+	/** An optimistic write this tab just ingested. Deliberately NOT queued while
+	*  detached: a new leader primes its circuit from the shared store, which
+	*  already holds the row, and replaying a stale tuple at it later would put
+	*  an older `_00_rv` in its version memo. */
+	ingest(tuples) {
+		if (!this.port) return;
+		try {
+			this.port.postMessage({
+				type: "ingest",
+				tuples
+			});
+		} catch {}
+	}
 	requestPoll() {
 		this.post({ type: "request-poll" });
 	}
@@ -10846,6 +10952,8 @@ var TabsCoordinator = class {
 		const forwarder = this.forwarder;
 		await new Promise((resolve) => {
 			let adopted = false;
+			let attached = false;
+			const pending = [];
 			const previousHandler = forwarder.onLeaderMessage;
 			forwarder.onLeaderMessage = (msg) => {
 				if (msg.type === "db-ready" && !adopted) {
@@ -10856,11 +10964,18 @@ var TabsCoordinator = class {
 						leadershipId: msg.leadershipId
 					}).then(() => {
 						this.deps.hooks.becomeSyncFollower(forwarder);
+						attached = true;
+						const backlog = pending.splice(0);
+						for (const m of backlog) forwarder.onLeaderMessage?.(m);
 						this.setRole("follower");
 						resolve();
 					});
 					return;
 				}
+				if (!attached) {
+					pending.push(msg);
+					return;
+				}
 				previousHandler?.(msg);
 			};
 			forwarder.rebind(syncPort);
@@ -12284,7 +12399,7 @@ var Sp00kyClient = class {
 		return new TabsCoordinator({
 			tabId,
 			fingerprint: computeTabsFingerprint({
-				coreVersion: "0.0.1-canary.205",
+				coreVersion: "0.0.1-canary.207",
 				schemaHash: hash53(this.config.schemaSurql),
 				endpoint: this.config.database.endpoint ?? "",
 				namespace: this.config.database.namespace,
@@ -12311,18 +12426,10 @@ var Sp00kyClient = class {
 				resumeSyncLeaderDuties: () => this.sync.resumeLeaderDuties(),
 				becomeSyncFollower: (forwarder) => {
 					this.streamProcessor.setPersistenceEnabled(false);
-					this.cache.setIngestRelay(null);
+					this.cache.setIngestRelay((tuples) => forwarder.ingest(tuples), { localWritesOnly: true });
 					this.sync.setTabContext("follower", tabId);
 					this.dataModule.setTabId(tabId);
 					this.sync.demoteToFollower(forwarder);
-					const inner = forwarder.onLeaderMessage;
-					forwarder.onLeaderMessage = (msg) => {
-						if (msg.type === "ingest-relay") {
-							this.cache.applyRelayedIngest(msg.tuples);
-							return;
-						}
-						inner?.(msg);
-					};
 				},
 				becomeSyncSolo: () => {
 					this.streamProcessor.setPersistenceEnabled(true);

package/dist/types.d.ts

@@ -874,6 +874,11 @@ interface QueryConfig {
    * "never established" has to fall back to a predicate scan of the local store
    * so a query first run on this device still paints offline. A
    * `remoteArray.length === 0` check cannot tell those apart.
+   *
+   * On a cold start it is seeded from the durable `_00_window` row when that
+   * row is non-empty, or empty but `confirmed` (the server reported zero rows
+   * for the query). An unconfirmed empty row is ignored, so a device poisoned
+   * by an old client that mirrored unflushed reads still self-heals.
    */
   membershipKnown?: boolean;
   /**
@@ -889,6 +894,9 @@ interface QueryConfig {
    * genuine transition and must be honoured, or removed rows resurrect.
    *
    * In-memory only: a fresh session must re-earn the right to believe empties.
+   * What does persist is the `confirmed` marker on the `_00_window` row, which
+   * an empty set earns when it arrives with a server row count of zero or after
+   * a non-empty set in the same session.
    */
   remoteSeen?: boolean;
   /**

package/package.json

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

package/src/modules/cache/cache.relay.test.ts

@@ -0,0 +1,95 @@
+import { describe, it, expect, vi } from 'vitest';
+import { RecordId } from 'surrealdb';
+import { CacheModule } from './index';
+
+// The ingest relay is how one tab's circuit learns what another tab wrote.
+// The leader relays every ingest (its sync fetches are the only copy the
+// followers get); a follower relays with `localWritesOnly`, just its mutation
+// path, because its sync-fetched batches are the leader's data coming back.
+
+function makeLogger(): any {
+  const logger: any = { debug: () => {}, info: () => {}, warn: () => {}, error: () => {}, trace: () => {} };
+  logger.child = () => logger;
+  return logger;
+}
+
+function setup() {
+  const local: any = { epoch: 1, execute: vi.fn(async () => {}), query: vi.fn(async () => []) };
+  const ssp: any = {
+    addReceiver: vi.fn(),
+    ingestMany: vi.fn((records: unknown[]) => records),
+  };
+  const cache = new CacheModule(local, ssp, () => {}, makeLogger());
+  const relay = vi.fn();
+  return { cache, local, ssp, relay };
+}
+
+const rec = (id: string, version: number) => ({
+  table: 'thread',
+  op: 'CREATE' as const,
+  record: { id: new RecordId('thread', id), title: 't' },
+  version,
+});
+
+describe('CacheModule ingest relay', () => {
+  it('applyRelayedIngest updates the version memo and never re-relays', () => {
+    const { cache, ssp, relay } = setup();
+    cache.setIngestRelay(relay);
+
+    cache.applyRelayedIngest([
+      { table: 'thread', op: 'CREATE', id: 'thread:a', record: { id: 'thread:a', _00_rv: 4 } },
+    ]);
+
+    expect(ssp.ingestMany).toHaveBeenCalledTimes(1);
+    expect(cache.lookup('thread:a')).toBe(4);
+    expect(relay).not.toHaveBeenCalled();
+  });
+
+  it('localWritesOnly relays the mutation path (save + delete)', async () => {
+    const { cache, local, relay } = setup();
+    cache.setIngestRelay(relay, { localWritesOnly: true });
+
+    await cache.save(rec('a', 1), true);
+    expect(local.execute).not.toHaveBeenCalled();
+    expect(relay).toHaveBeenCalledTimes(1);
+    expect(relay.mock.calls[0][0][0]).toMatchObject({ table: 'thread', op: 'CREATE', id: 'thread:a' });
+
+    const before = { id: 'thread:a', title: 't' };
+    await cache.delete('thread', 'thread:a', true, before);
+    expect(relay).toHaveBeenCalledTimes(2);
+    expect(relay.mock.calls[1][0]).toEqual([
+      { table: 'thread', op: 'DELETE', id: 'thread:a', record: before },
+    ]);
+  });
+
+  it('localWritesOnly stays silent for sync-fetched batches', async () => {
+    const { cache, local, relay } = setup();
+    cache.setIngestRelay(relay, { localWritesOnly: true });
+
+    await cache.saveBatch([rec('a', 1), rec('b', 1)], false);
+    expect(local.execute).toHaveBeenCalledTimes(1);
+    expect(relay).not.toHaveBeenCalled();
+
+    await cache.delete('thread', 'thread:a', false, {});
+    expect(relay).not.toHaveBeenCalled();
+  });
+
+  it('an unscoped relay fires for every ingest', async () => {
+    const { cache, relay } = setup();
+    cache.setIngestRelay(relay);
+
+    await cache.saveBatch([rec('a', 1)], false);
+    await cache.save(rec('b', 1), true);
+    await cache.delete('thread', 'thread:a', false, {});
+
+    expect(relay).toHaveBeenCalledTimes(3);
+  });
+
+  it('setIngestRelay(null) stops relaying', async () => {
+    const { cache, relay } = setup();
+    cache.setIngestRelay(relay, { localWritesOnly: true });
+    cache.setIngestRelay(null);
+    await cache.save(rec('a', 1), true);
+    expect(relay).not.toHaveBeenCalled();
+  });
+});