@spooky-sync/core 0.0.1-canary.196 → 0.0.1-canary.198

package/dist/index.d.ts

@@ -693,6 +693,28 @@ declare class DataModule<S extends SchemaStructure> {
    * behavior for windows and is preserved.
    */
   private resolveMembership;
+  private readonly settledWrites;
+  private readonly settledDeletes;
+  /**
+   * Grace period for a settled write. Long enough to cover an SSP round trip
+   * that is running slowly (seconds, not milliseconds, when the edge path is
+   * backed up), short enough that a write the server silently dropped cannot
+   * linger misleadingly.
+   *
+   * The rejection case does NOT rely on this expiring: an application error
+   * rolls the mutation back and never reports it settled, so it vanishes at
+   * once. This deadline only bounds the case where the write succeeded and its
+   * membership never arrived at all.
+   */
+  private static readonly SETTLED_WRITE_GRACE_MS;
+  /**
+   * Report that a mutation was accepted by the server and its outbox row
+   * removed. Called only on the SUCCESS path — a rolled-back mutation must
+   * disappear immediately, which is what makes this safe.
+   */
+  noteWriteSettled(recordId: string, mutationType: string): void;
+  /** Drop entries past their deadline. */
+  private pruneSettled;
   /** Apply the pending-write union and pending-delete subtraction, and map to
    *  RecordIds for the engines' id-set path. */
   private buildRenderIds;
@@ -1341,6 +1363,18 @@ declare class Sp00kySync<S extends SchemaStructure> {
    */
   private withPushTimeout;
   private processUpEvent;
+  /**
+   * A mutation the server accepted, reported once its outbox row is gone.
+   *
+   * Keeps the written row in the render set until its membership arrives.
+   * Without this the row is briefly in neither term of
+   * `(membership ∪ pendingWrites) − pendingDeletes` — the outbox delete is
+   * tied to the push, while membership waits on the SSP ingesting the row,
+   * materializing the view, writing the `_00_list_ref` edge and this client
+   * reading it back. The writer therefore watched its own comment appear,
+   * vanish, and return, while every other client showed it throughout.
+   */
+  private handleMutationSettled;
   private handleRollback;
   private processDownEvent;
   /**

package/dist/index.js

@@ -3255,7 +3255,7 @@ function phaseStatOf(samples, lastMs) {
 * Merges the functionality of QueryManager and MutationManager.
 * Uses CacheModule for all storage operations.
 */
-var DataModule = class {
+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. */
 	tabId;
@@ -3583,17 +3583,55 @@ var DataModule = class {
 		if (buildWindowMaterialization(config.surql) !== null) return config.remoteArray?.length && config.remoteArray || sspArray?.length && sspArray || config.localArray || [];
 		return null;
 	}
+	settledWrites = /* @__PURE__ */ new Map();
+	settledDeletes = /* @__PURE__ */ new Map();
+	/**
+	* Grace period for a settled write. Long enough to cover an SSP round trip
+	* that is running slowly (seconds, not milliseconds, when the edge path is
+	* backed up), short enough that a write the server silently dropped cannot
+	* linger misleadingly.
+	*
+	* The rejection case does NOT rely on this expiring: an application error
+	* rolls the mutation back and never reports it settled, so it vanishes at
+	* once. This deadline only bounds the case where the write succeeded and its
+	* membership never arrived at all.
+	*/
+	static SETTLED_WRITE_GRACE_MS = 1e4;
+	/**
+	* Report that a mutation was accepted by the server and its outbox row
+	* removed. Called only on the SUCCESS path — a rolled-back mutation must
+	* disappear immediately, which is what makes this safe.
+	*/
+	noteWriteSettled(recordId, mutationType) {
+		const until = Date.now() + DataModule.SETTLED_WRITE_GRACE_MS;
+		if (mutationType === "delete") this.settledDeletes.set(recordId, until);
+		else this.settledWrites.set(recordId, until);
+	}
+	/** Drop entries past their deadline. */
+	pruneSettled(now) {
+		for (const [id, until] of this.settledWrites) if (until <= now) this.settledWrites.delete(id);
+		for (const [id, until] of this.settledDeletes) if (until <= now) this.settledDeletes.delete(id);
+	}
 	/** Apply the pending-write union and pending-delete subtraction, and map to
 	*  RecordIds for the engines' id-set path. */
 	async buildRenderIds(config, membership, sspArray) {
 		const { writes, deletes } = await this.getPendingRecordIds();
+		const now = Date.now();
+		this.pruneSettled(now);
+		if (this.settledWrites.size > 0) for (const id of this.settledWrites.keys()) writes.add(id);
+		if (this.settledDeletes.size > 0) for (const id of this.settledDeletes.keys()) deletes.add(id);
 		const ordered = [];
 		const seen = /* @__PURE__ */ new Set();
 		for (const [id] of membership) {
+			if (this.settledWrites.size > 0) this.settledWrites.delete(id);
 			if (deletes.has(id) || seen.has(id)) continue;
 			seen.add(id);
 			ordered.push(id);
 		}
+		if (this.settledDeletes.size > 0) {
+			const stillListed = new Set(membership.map(([id]) => id));
+			for (const id of [...this.settledDeletes.keys()]) if (!stillListed.has(id)) this.settledDeletes.delete(id);
+		}
 		if (writes.size > 0) {
 			const localView = sspArray?.length && sspArray || config.localArray || [];
 			for (const [id] of localView) {
@@ -4803,7 +4841,14 @@ var UpQueue = class {
 		for (const { timer } of this.debouncedMutations.values()) clearTimeout(timer);
 		this.debouncedMutations.clear();
 	}
-	async next(fn, onRollback) {
+	/**
+	* @param onSettled Reports a mutation the server ACCEPTED, after its outbox
+	* row is gone. Deliberately not called on the rollback path: a rejected
+	* mutation must stop being rendered immediately, while an accepted one has
+	* to stay visible until its membership arrives (see
+	* `DataModule.noteWriteSettled`).
+	*/
+	async next(fn, onRollback, onSettled) {
 		const event = this.queue.shift();
 		if (event) {
 			try {
@@ -4856,6 +4901,15 @@ var UpQueue = class {
 					Category: "sp00ky-client::UpQueue::next"
 				}, "Failed to remove mutation from database after successful processing");
 			}
+			if (onSettled) try {
+				onSettled(event);
+			} catch (error) {
+				this.logger.error({
+					error,
+					event,
+					Category: "sp00ky-client::UpQueue::next"
+				}, "Settled-write handler failed");
+			}
 			this._events.addEvent({
 				type: SyncQueueEventTypes.MutationDequeued,
 				payload: { queueSize: this.queue.length }
@@ -5407,7 +5461,7 @@ var SyncScheduler = class {
 	downRetryTimer;
 	upRetryAttempt = 0;
 	downRetryAttempt = 0;
-	constructor(upQueue, downQueue, onProcessUp, onProcessDown, logger, onRollback, onSyncOutcome) {
+	constructor(upQueue, downQueue, onProcessUp, onProcessDown, logger, onRollback, onSyncOutcome, onSettled) {
 		this.upQueue = upQueue;
 		this.downQueue = downQueue;
 		this.onProcessUp = onProcessUp;
@@ -5415,6 +5469,7 @@ var SyncScheduler = class {
 		this.logger = logger;
 		this.onRollback = onRollback;
 		this.onSyncOutcome = onSyncOutcome;
+		this.onSettled = onSettled;
 	}
 	async init(opts = {}) {
 		if (opts.loadOutbox !== false) await this.upQueue.loadFromDatabase();
@@ -5508,7 +5563,7 @@ var SyncScheduler = class {
 		let processedAny = false;
 		try {
 			while (this.upQueue.size > 0 && !this.paused) {
-				await this.upQueue.next(this.onProcessUp, this.onRollback);
+				await this.upQueue.next(this.onProcessUp, this.onRollback, this.onSettled);
 				processedAny = true;
 			}
 			if (processedAny) this.onSyncOutcome?.(true);
@@ -5801,7 +5856,7 @@ var Sp00kySync = class Sp00kySync {
 		this.upQueue = new UpQueue(this.local, this.logger, (dropped) => this.onMutationDropped(dropped));
 		this.downQueue = new DownQueue(this.local, this.logger);
 		this.syncEngine = new SyncEngine(this.remote, this.cache, this.schema, this.logger);
-		this.scheduler = new SyncScheduler(this.upQueue, this.downQueue, this.processUpEvent.bind(this), this.processDownEvent.bind(this), this.logger, this.handleRollback.bind(this), this.recordSyncOutcome.bind(this));
+		this.scheduler = new SyncScheduler(this.upQueue, this.downQueue, this.processUpEvent.bind(this), this.processDownEvent.bind(this), this.logger, this.handleRollback.bind(this), this.recordSyncOutcome.bind(this), this.handleMutationSettled.bind(this));
 		this.refSyncIntervalMs = resolveListRefPollInterval(options?.refSyncIntervalMs);
 		this.anonLiveEnabled = options?.anonymousLiveQueries ?? false;
 		this.degradeAfterFailures = Math.max(0, options?.degradeAfterConsecutiveFailures ?? 3);
@@ -6425,6 +6480,20 @@ var Sp00kySync = class Sp00kySync {
 				return;
 		}
 	}
+	/**
+	* A mutation the server accepted, reported once its outbox row is gone.
+	*
+	* Keeps the written row in the render set until its membership arrives.
+	* Without this the row is briefly in neither term of
+	* `(membership ∪ pendingWrites) − pendingDeletes` — the outbox delete is
+	* tied to the push, while membership waits on the SSP ingesting the row,
+	* materializing the view, writing the `_00_list_ref` edge and this client
+	* reading it back. The writer therefore watched its own comment appear,
+	* vanish, and return, while every other client showed it throughout.
+	*/
+	handleMutationSettled(event) {
+		this.dataModule.noteWriteSettled(encodeRecordId(event.record_id), event.type);
+	}
 	async handleRollback(event, error) {
 		const recordId = encodeRecordId(event.record_id);
 		const tableName = event.type === "create" && event.tableName ? event.tableName : extractTablePart(recordId);
@@ -6677,7 +6746,18 @@ var Sp00kySync = class Sp00kySync {
 			}, "Query to register not found");
 			throw new Error("Query to register not found");
 		}
-		await this.remote.query("fn::query::heartbeat($id)", { id: queryState.config.id });
+		const result = await this.remote.query("fn::query::heartbeat($id)", { id: queryState.config.id });
+		const updated = Array.isArray(result) ? result[0] : void 0;
+		if (!(Array.isArray(updated) && updated.length === 0)) return;
+		this.logger.warn({
+			queryHash,
+			id: String(queryState.config.id),
+			Category: "sp00ky-client::Sp00kySync::heartbeatQuery"
+		}, "Query row was reclaimed while still in use; re-registering");
+		this.enqueueDownEvent({
+			type: "register",
+			payload: { hash: queryHash }
+		});
 	}
 	async cleanupQuery(queryHash) {
 		const queryState = this.dataModule.getQueryByHash(queryHash);
@@ -7012,8 +7092,8 @@ function selfAllowlistedVariant(flag, userId) {
 
 //#endregion
 //#region src/modules/devtools/index.ts
-const CORE_VERSION = "0.0.1-canary.196";
-const WASM_VERSION = "0.0.1-canary.196";
+const CORE_VERSION = "0.0.1-canary.198";
+const WASM_VERSION = "0.0.1-canary.198";
 const SURREAL_VERSION = "3.0.3";
 var DevToolsService = class DevToolsService {
 	eventsHistory = [];
@@ -11444,7 +11524,7 @@ var Sp00kyClient = class {
 		return new TabsCoordinator({
 			tabId,
 			fingerprint: computeTabsFingerprint({
-				coreVersion: "0.0.1-canary.196",
+				coreVersion: "0.0.1-canary.198",
 				schemaHash: hash53(this.config.schemaSurql),
 				endpoint: this.config.database.endpoint ?? "",
 				namespace: this.config.database.namespace,

package/package.json

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

package/src/modules/data/data.settled-writes.test.ts

@@ -0,0 +1,206 @@
+import { describe, it, expect, vi, afterEach } from 'vitest';
+import { RecordId } from 'surrealdb';
+import { DataModule } from './index';
+import type { QueryPlan } from '@spooky-sync/query-builder';
+import type { QueryState, RecordVersionArray } from '../../types';
+
+/**
+ * A write is visible before the server confirms it because it sits in the
+ * outbox: the render set is
+ * `(membership ∪ (pendingWrites ∩ localArray)) − pendingDeletes`.
+ *
+ * The outbox row is deleted the instant the push succeeds, but the row does not
+ * enter membership until the SSP has ingested it, materialized the view, written
+ * the `_00_list_ref` edge, and this client has read that back. In between it is
+ * in NEITHER term, so it renders, disappears, and returns.
+ *
+ * Reported from production as "the comment shows up on every other client in
+ * realtime but not on the one that wrote it" — other clients don't blink because
+ * a client that never established membership renders from the predicate scan
+ * instead. The gap is invisible when the round trip is fast and glaring when the
+ * edge path is backed up.
+ */
+
+const noop = () => {};
+
+function makeLogger(): any {
+  const logger: any = { debug: noop, info: noop, warn: noop, error: noop, trace: noop };
+  logger.child = () => logger;
+  return logger;
+}
+
+const schema = { tables: [{ name: 'comment', columns: {} }] } as any;
+const plan: QueryPlan = { table: 'comment', where: [['game', '=', 'game:g1']] } as any;
+
+function makeQueryState(
+  hash: string,
+  opts: { remoteArray?: RecordVersionArray; localArray?: RecordVersionArray } = {}
+): QueryState {
+  return {
+    config: {
+      id: new RecordId('_00_query', hash),
+      surql: 'SELECT * FROM comment WHERE game = $game;',
+      plan,
+      params: { game: 'game:g1' },
+      localArray: opts.localArray ?? [],
+      remoteArray: opts.remoteArray ?? [],
+      membershipKnown: true,
+      ttl: '10m',
+      lastActiveAt: new Date(),
+      tableName: 'comment',
+    },
+    records: [],
+    ttlTimer: null,
+    ttlDurationMs: 0,
+    updateCount: 0,
+    lastUpdatedAt: null,
+    materializationSamples: [],
+    lastIngestLatencyMs: null,
+    errorCount: 0,
+    status: 'idle',
+    phaseSamples: {},
+    phaseLast: {},
+    registrationTimings: { parseMs: null, planMs: null, snapshotMs: null, wallMs: null },
+  } as QueryState;
+}
+
+function setup(
+  stateOpts: Parameters<typeof makeQueryState>[1] = {},
+  pendingRows: Array<{ recordId: RecordId; mutationType: string }> = []
+) {
+  const bodies = new Map(
+    ['old', 'new'].map((k) => [`comment:${k}`, { id: new RecordId('comment', k), body: k }])
+  );
+  const local: any = {
+    epoch: 1,
+    select: vi.fn(async (p: QueryPlan) => {
+      if ((p as any).ids) {
+        return ((p as any).ids as RecordId[])
+          .map((id) => bodies.get(id.toString()))
+          .filter((r): r is NonNullable<typeof r> => r !== undefined);
+      }
+      return Array.from(bodies.values());
+    }),
+    query: vi.fn(async (sql: string) => {
+      if (sql.includes('_00_pending_mutations')) return [pendingRows];
+      if (sql.includes('FROM ONLY')) return [null];
+      return [Array.from(bodies.values())];
+    }),
+    getById: vi.fn(async () => null),
+    upsert: vi.fn(async () => {}),
+  };
+  const dm = new DataModule({ saveBatch: async () => {} } as any, local, schema, makeLogger(), 100);
+  const state = makeQueryState('h1', stateOpts);
+  (dm as any).activeQueries.set('h1', state);
+  return { dm, state };
+}
+
+const ids = (rows: Array<Record<string, any>>) => rows.map((r) => String(r.id));
+const materialize = (dm: DataModule<any>, state: QueryState, ssp?: RecordVersionArray) =>
+  (dm as any).materializeRecords(state, ssp) as Promise<Record<string, any>[]>;
+
+describe('settled-write grace window', () => {
+  afterEach(() => vi.useRealTimers());
+
+  it('keeps an accepted write rendered while membership has not caught up', async () => {
+    // Membership still only knows the old comment; the outbox row for the new
+    // one is already gone because the push succeeded.
+    const { dm, state } = setup({
+      remoteArray: [['comment:old', 1]],
+      localArray: [
+        ['comment:old', 1],
+        ['comment:new', 1],
+      ],
+    });
+
+    dm.noteWriteSettled('comment:new', 'create');
+
+    expect(ids(await materialize(dm, state))).toEqual(['comment:new', 'comment:old']);
+  });
+
+  it('renders nothing extra for a write the server never accepted', async () => {
+    // The rollback path never reports a mutation settled, so a rejected write
+    // has no grace at all. This is what keeps the window from showing rows the
+    // server refused.
+    const { dm, state } = setup({
+      remoteArray: [['comment:old', 1]],
+      localArray: [
+        ['comment:old', 1],
+        ['comment:new', 1],
+      ],
+    });
+
+    expect(ids(await materialize(dm, state))).toEqual(['comment:old']);
+  });
+
+  it('stops granting grace once membership names the row', async () => {
+    const { dm, state } = setup({
+      remoteArray: [['comment:old', 1]],
+      localArray: [
+        ['comment:old', 1],
+        ['comment:new', 1],
+      ],
+    });
+    dm.noteWriteSettled('comment:new', 'create');
+    await materialize(dm, state);
+
+    // Membership catches up; the id must not be double-counted…
+    state.config.remoteArray = [
+      ['comment:old', 1],
+      ['comment:new', 1],
+    ];
+    expect(ids(await materialize(dm, state))).toEqual(['comment:new', 'comment:old']);
+    expect((dm as any).settledWrites.size).toBe(0);
+
+    // …and once the server later drops it from the window, it goes away rather
+    // than being resurrected by a stale grace entry.
+    state.config.remoteArray = [['comment:old', 1]];
+    expect(ids(await materialize(dm, state))).toEqual(['comment:old']);
+  });
+
+  it('expires the grace so a write whose membership never arrives cannot linger', async () => {
+    vi.useFakeTimers();
+    const { dm, state } = setup({
+      remoteArray: [['comment:old', 1]],
+      localArray: [
+        ['comment:old', 1],
+        ['comment:new', 1],
+      ],
+    });
+    dm.noteWriteSettled('comment:new', 'create');
+    expect(ids(await materialize(dm, state))).toContain('comment:new');
+
+    vi.advanceTimersByTime(11_000);
+    expect(ids(await materialize(dm, state))).toEqual(['comment:old']);
+  });
+
+  it('keeps an accepted delete subtracted until membership drops the row', async () => {
+    // The mirror case: membership still lists the row until the SSP publishes
+    // its removal, so without this the deleted row flashes back.
+    const { dm, state } = setup({
+      remoteArray: [
+        ['comment:old', 1],
+        ['comment:new', 1],
+      ],
+      localArray: [['comment:old', 1]],
+    });
+
+    dm.noteWriteSettled('comment:new', 'delete');
+
+    expect(ids(await materialize(dm, state))).toEqual(['comment:old']);
+  });
+
+  it('only grants grace to rows the local view still says match', async () => {
+    // `localArray` is the local SSP's answer to "does this row match the
+    // predicate". A settled write that does NOT match must not be forced into
+    // the render set — same rule the pending-write union already follows.
+    const { dm, state } = setup({
+      remoteArray: [['comment:old', 1]],
+      localArray: [['comment:old', 1]],
+    });
+
+    dm.noteWriteSettled('comment:new', 'create');
+
+    expect(ids(await materialize(dm, state))).toEqual(['comment:old']);
+  });
+});

package/src/modules/data/index.ts

@@ -565,6 +565,62 @@ export class DataModule<S extends SchemaStructure> {
     return null;
   }
 
+  // ---- Settled-write grace window ----------------------------------------
+  //
+  // A local write is visible because it is in the outbox: the render set is
+  // `(membership ∪ (pendingWrites ∩ localArray)) − pendingDeletes`. The outbox
+  // row is deleted the moment the remote push succeeds (see
+  // `UpQueue.next` / `SyncScheduler` — the delete is deliberately tied to the
+  // push, not to anything downstream), but the row does not enter `membership`
+  // until the SSP has ingested it, materialized the view and written the
+  // `_00_list_ref` edge, and this client has read that back.
+  //
+  // Between those two moments the row is in neither term, so it is rendered,
+  // then disappears, then returns — reported as "the comment shows on every
+  // other client but not on the one that wrote it". Other clients don't blink
+  // because a client that never established membership renders from the local
+  // predicate scan instead.
+  //
+  // So a settled write keeps its place in the union for a short grace period,
+  // until membership catches up or the deadline passes. Kept in memory only:
+  // it covers a round trip, and a reload re-derives membership anyway.
+  private readonly settledWrites = new Map<string, number>();
+  private readonly settledDeletes = new Map<string, number>();
+
+  /**
+   * Grace period for a settled write. Long enough to cover an SSP round trip
+   * that is running slowly (seconds, not milliseconds, when the edge path is
+   * backed up), short enough that a write the server silently dropped cannot
+   * linger misleadingly.
+   *
+   * The rejection case does NOT rely on this expiring: an application error
+   * rolls the mutation back and never reports it settled, so it vanishes at
+   * once. This deadline only bounds the case where the write succeeded and its
+   * membership never arrived at all.
+   */
+  private static readonly SETTLED_WRITE_GRACE_MS = 10_000;
+
+  /**
+   * Report that a mutation was accepted by the server and its outbox row
+   * removed. Called only on the SUCCESS path — a rolled-back mutation must
+   * disappear immediately, which is what makes this safe.
+   */
+  noteWriteSettled(recordId: string, mutationType: string): void {
+    const until = Date.now() + DataModule.SETTLED_WRITE_GRACE_MS;
+    if (mutationType === 'delete') this.settledDeletes.set(recordId, until);
+    else this.settledWrites.set(recordId, until);
+  }
+
+  /** Drop entries past their deadline. */
+  private pruneSettled(now: number): void {
+    for (const [id, until] of this.settledWrites) {
+      if (until <= now) this.settledWrites.delete(id);
+    }
+    for (const [id, until] of this.settledDeletes) {
+      if (until <= now) this.settledDeletes.delete(id);
+    }
+  }
+
   /** Apply the pending-write union and pending-delete subtraction, and map to
    *  RecordIds for the engines' id-set path. */
   private async buildRenderIds(
@@ -573,13 +629,39 @@ export class DataModule<S extends SchemaStructure> {
     sspArray?: Array<[string, number]>
   ): Promise<unknown[]> {
     const { writes, deletes } = await this.getPendingRecordIds();
+    const now = Date.now();
+    this.pruneSettled(now);
+    // A settled write counts as pending until membership catches up. Merged
+    // into the same sets so the union/subtraction below is unchanged — the
+    // grace window changes WHEN an id leaves the render set, never how the
+    // set is composed.
+    if (this.settledWrites.size > 0) {
+      for (const id of this.settledWrites.keys()) writes.add(id);
+    }
+    if (this.settledDeletes.size > 0) {
+      for (const id of this.settledDeletes.keys()) deletes.add(id);
+    }
+
     const ordered: string[] = [];
     const seen = new Set<string>();
     for (const [id] of membership) {
+      // Membership has caught up with this write: the grace window has done
+      // its job and ends here rather than at its deadline. Doing it inline
+      // keeps the common case (nothing settled) free of extra passes.
+      if (this.settledWrites.size > 0) this.settledWrites.delete(id);
       if (deletes.has(id) || seen.has(id)) continue;
       seen.add(id);
       ordered.push(id);
     }
+    // A settled DELETE is the mirror case: membership still lists the row
+    // until the SSP publishes its removal, so the id stays subtracted until
+    // membership stops naming it.
+    if (this.settledDeletes.size > 0) {
+      const stillListed = new Set(membership.map(([id]) => id));
+      for (const id of [...this.settledDeletes.keys()]) {
+        if (!stillListed.has(id)) this.settledDeletes.delete(id);
+      }
+    }
     if (writes.size > 0) {
       // Only pending writes the SSP agrees currently match this query — see the
       // formula in `materializeRecords`. `sspArray` is the fresher signal when a

package/src/modules/sync/queue/queue-up.ts

@@ -175,7 +175,18 @@ export class UpQueue {
     this.debouncedMutations.clear();
   }
 
-  async next(fn: (event: UpEvent) => Promise<void>, onRollback?: RollbackCallback): Promise<void> {
+  /**
+   * @param onSettled Reports a mutation the server ACCEPTED, after its outbox
+   * row is gone. Deliberately not called on the rollback path: a rejected
+   * mutation must stop being rendered immediately, while an accepted one has
+   * to stay visible until its membership arrives (see
+   * `DataModule.noteWriteSettled`).
+   */
+  async next(
+    fn: (event: UpEvent) => Promise<void>,
+    onRollback?: RollbackCallback,
+    onSettled?: (event: UpEvent) => void
+  ): Promise<void> {
     const event = this.queue.shift();
     if (event) {
       try {
@@ -229,6 +240,19 @@ export class UpQueue {
           'Failed to remove mutation from database after successful processing'
         );
       }
+      // Report AFTER the outbox row is gone: that delete is exactly what drops
+      // the row out of the render set, so this is the moment the grace window
+      // has to start covering.
+      if (onSettled) {
+        try {
+          onSettled(event);
+        } catch (error) {
+          this.logger.error(
+            { error, event, Category: 'sp00ky-client::UpQueue::next' },
+            'Settled-write handler failed'
+          );
+        }
+      }
       this._events.addEvent({
         type: SyncQueueEventTypes.MutationDequeued,
         payload: { queueSize: this.queue.length },

package/src/modules/sync/scheduler.ts

@@ -37,7 +37,10 @@ export class SyncScheduler {
     // that actually processed ≥1 item): `ok=true` on a clean drain, `ok=false`
     // with the error when the round halted on a failure. Drives the consumer's
     // sync-health tracking; empty/no-op rounds report nothing.
-    private onSyncOutcome?: (ok: boolean, error?: unknown) => void
+    private onSyncOutcome?: (ok: boolean, error?: unknown) => void,
+    // Reports each mutation the server accepted, once its outbox row is gone.
+    // Lets the consumer keep the row rendered until its membership arrives.
+    private onSettled?: (event: UpEvent) => void
   ) {}
 
   async init(opts: { loadOutbox?: boolean } = {}) {
@@ -151,7 +154,7 @@ export class SyncScheduler {
     let processedAny = false;
     try {
       while (this.upQueue.size > 0 && !this.paused) {
-        await this.upQueue.next(this.onProcessUp, this.onRollback);
+        await this.upQueue.next(this.onProcessUp, this.onRollback, this.onSettled);
         processedAny = true;
       }
       if (processedAny) this.onSyncOutcome?.(true);

package/src/modules/sync/sync.heartbeat.test.ts

@@ -0,0 +1,80 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { RecordId } from 'surrealdb';
+import { Sp00kySync } from './sync';
+
+/**
+ * `fn::query::heartbeat` is an `UPDATE $id SET ...`. Against a record that no
+ * longer exists it matches nothing and returns an empty array — it does NOT
+ * recreate the row. Verified against the deployed function:
+ *
+ *     RETURN fn::query::heartbeat(_00_query:definitely_not_a_real_row_xyz);
+ *     -- (0 rows)
+ *
+ * So an unchecked heartbeat cannot tell "refreshed" from "the row I am
+ * refreshing is gone", and a client whose row was reclaimed by the TTL sweep
+ * beats against nothing forever: no membership, no edges, no re-registration.
+ * The page then renders as though the data had been deleted — reported as
+ * "Game not found" on a game that was open and working.
+ *
+ * This is reachable in ordinary use: the sweep expires on `lastActiveAt + ttl`
+ * while the heartbeat runs on a timer browsers throttle hard in background
+ * tabs, so a second window left idle past its TTL is the normal way in.
+ */
+
+function makeSync(heartbeatResult: unknown) {
+  const logger: any = {
+    child: () => logger,
+    debug: () => {}, info: () => {}, warn: () => {}, error: () => {}, trace: () => {},
+  };
+  const remote: any = { query: vi.fn().mockResolvedValue(heartbeatResult) };
+  const queryState: any = { config: { id: new RecordId('_00_query', 'h1') } };
+  const dataModule: any = { getQueryByHash: vi.fn().mockReturnValue(queryState) };
+
+  const sync = new Sp00kySync({} as any, remote, {} as any, dataModule, {} as any, logger);
+  const enqueueDownEvent = vi.fn();
+  (sync as any).enqueueDownEvent = enqueueDownEvent;
+
+  return { sync, remote, dataModule, enqueueDownEvent };
+}
+
+describe('heartbeatQuery — noticing a reclaimed row', () => {
+  beforeEach(() => vi.clearAllMocks());
+
+  it('re-registers when the row it beat against is gone', async () => {
+    // `UPDATE` on a deleted record: one statement, zero updated records.
+    const { sync, enqueueDownEvent } = makeSync([[]]);
+
+    await sync.heartbeatQuery('h1');
+
+    expect(enqueueDownEvent).toHaveBeenCalledWith({
+      type: 'register',
+      payload: { hash: 'h1' },
+    });
+  });
+
+  it('does nothing extra on a healthy heartbeat', async () => {
+    const { sync, enqueueDownEvent } = makeSync([[{ id: 'x', lastActiveAt: 'now' }]]);
+
+    await sync.heartbeatQuery('h1');
+
+    expect(enqueueDownEvent).not.toHaveBeenCalled();
+  });
+
+  it('does not re-register on an unrecognised result shape', async () => {
+    // Only an explicitly EMPTY update result means "the row is gone". Anything
+    // else — a driver returning null, a shape change — must not be read as
+    // deletion, or every heartbeat would re-register the whole working set.
+    for (const shape of [null, undefined, [], [null], ['unexpected']]) {
+      const { sync, enqueueDownEvent } = makeSync(shape);
+      await sync.heartbeatQuery('h1');
+      expect(enqueueDownEvent, `shape ${JSON.stringify(shape)}`).not.toHaveBeenCalled();
+    }
+  });
+
+  it('still throws for a query that is no longer registered locally', async () => {
+    const { sync, dataModule } = makeSync([[]]);
+    dataModule.getQueryByHash.mockReturnValue(undefined);
+
+    await expect(sync.heartbeatQuery('gone')).rejects.toThrow();
+  });
+});

package/src/modules/sync/sync.ts

@@ -454,7 +454,8 @@ export class Sp00kySync<S extends SchemaStructure> {
       this.processDownEvent.bind(this),
       this.logger,
       this.handleRollback.bind(this),
-      this.recordSyncOutcome.bind(this)
+      this.recordSyncOutcome.bind(this),
+      this.handleMutationSettled.bind(this)
     );
     this.refSyncIntervalMs = resolveListRefPollInterval(options?.refSyncIntervalMs);
     this.anonLiveEnabled = options?.anonymousLiveQueries ?? false;
@@ -1362,6 +1363,21 @@ export class Sp00kySync<S extends SchemaStructure> {
     }
   }
 
+  /**
+   * A mutation the server accepted, reported once its outbox row is gone.
+   *
+   * Keeps the written row in the render set until its membership arrives.
+   * Without this the row is briefly in neither term of
+   * `(membership ∪ pendingWrites) − pendingDeletes` — the outbox delete is
+   * tied to the push, while membership waits on the SSP ingesting the row,
+   * materializing the view, writing the `_00_list_ref` edge and this client
+   * reading it back. The writer therefore watched its own comment appear,
+   * vanish, and return, while every other client showed it throughout.
+   */
+  private handleMutationSettled(event: UpEvent): void {
+    this.dataModule.noteWriteSettled(encodeRecordId(event.record_id), event.type);
+  }
+
   private async handleRollback(event: UpEvent, error: Error): Promise<void> {
     const recordId = encodeRecordId(event.record_id);
     const tableName =
@@ -1752,9 +1768,40 @@ export class Sp00kySync<S extends SchemaStructure> {
       );
       throw new Error('Query to register not found');
     }
-    await this.remote.query('fn::query::heartbeat($id)', {
+    // `fn::query::heartbeat` is an `UPDATE $id SET ...`. On a record that no
+    // longer exists that matches nothing and returns an empty array — it does
+    // NOT recreate the row. So an unchecked heartbeat is indistinguishable from
+    // a successful one, and a client whose row was reclaimed keeps beating
+    // against nothing forever: no membership, no edges, no re-registration.
+    // The page renders as if the data were deleted ("Game not found").
+    //
+    // A live query's row is reclaimed more easily than it looks. The sweep
+    // expires on `lastActiveAt + ttl`, and this heartbeat runs on a timer that
+    // browsers throttle hard in background tabs — so a second window left idle
+    // past its TTL is the ordinary way to get here, not an edge case. Until
+    // canary.194 the sweep could not actually remove the in-memory view (it
+    // looked it up under the other of the two query-id spellings), which masked
+    // this: the view survived its own row. Now reclamation is real, so the
+    // client has to notice and rebuild.
+    const result = await this.remote.query('fn::query::heartbeat($id)', {
       id: queryState.config.id,
     });
+    const updated = Array.isArray(result) ? result[0] : undefined;
+    const rowGone = Array.isArray(updated) && updated.length === 0;
+    if (!rowGone) return;
+
+    this.logger.warn(
+      {
+        queryHash,
+        id: String(queryState.config.id),
+        Category: 'sp00ky-client::Sp00kySync::heartbeatQuery',
+      },
+      'Query row was reclaimed while still in use; re-registering'
+    );
+    // Re-register rather than recreate the row here: the row alone is useless
+    // without the SSP view behind it, and only registration rebuilds the view,
+    // republishes `_00_list_ref` and writes `rowCount`.
+    this.enqueueDownEvent({ type: 'register', payload: { hash: queryHash } });
   }
 
   // Eager teardown of a deregistered query's remote `_00_query` view (opt-in,