@spooky-sync/core 0.0.1-canary.204 → 0.0.1-canary.206

package/dist/tabs-broker-worker.js

@@ -1,6 +1,13 @@
 //#region src/services/tabs/tabs-broker-worker.ts
 const PING_INTERVAL_MS = 5e3;
 const PONG_TIMEOUT_MS = 15e3;
+/** How long a tab has to answer `become-leader` with `leader-ready`. A tab
+*  that hangs mid-promotion sends neither `leader-ready` nor `leader-failed`,
+*  and keeps answering pings, so nothing else here would notice: the
+*  namespace would keep a leader that is not `ready`, mint no follower ports,
+*  and refuse to re-elect (`electIfNeeded` bails while `ns.leader` is set)
+*  until every tab was reloaded. Treat the silence as a failed promotion. */
+const PROMOTION_TIMEOUT_MS = 2e4;
 const FORCE_TAKEOVER_TIMEOUT_MS = 1e3;
 const LEADER_FAILURE_BACKOFF_MS = 1e3;
 const FAILED_CYCLES_BEFORE_MEMORY = 3;
@@ -35,7 +42,8 @@ function getNamespace(fingerprint, bucketId) {
 			failedCycles: 0,
 			electing: false,
 			attachRetry: /* @__PURE__ */ new Map(),
-			tabLockMonitor: null
+			tabLockMonitor: null,
+			promotionTimer: null
 		};
 		namespaces.set(key, ns);
 	}
@@ -63,6 +71,7 @@ function clearLeader(ns, opts) {
 	const leader = ns.leader;
 	if (!leader) return null;
 	ns.leader = null;
+	clearPromotionTimer(ns);
 	ns.tabLockMonitor?.abort();
 	ns.tabLockMonitor = null;
 	const tab = ns.tabs.get(leader.tabId);
@@ -86,6 +95,39 @@ function clearLeader(ns, opts) {
 		workerLock
 	};
 }
+function clearPromotionTimer(ns) {
+	if (ns.promotionTimer) clearTimeout(ns.promotionTimer);
+	ns.promotionTimer = null;
+}
+/**
+* A promotion did not work out: back the tab off, clear the leadership, and
+* re-elect. Shared by the tab's own `leader-failed` report and by the
+* {@link PROMOTION_TIMEOUT_MS} deadline, so a tab that hangs mid-promotion
+* costs the namespace the same 1s backoff as one that fails loudly, instead of
+* owning it forever.
+*
+* Every reason counts toward `failedCycles`. Gating that on 'opfs-unavailable'
+* left any other recurring failure (e.g. a tab lock nobody frees) looping at
+* the backoff interval forever, with allowMemoryFallback never granted, so
+* every tab timed out in start() and booted solo - each one then contending
+* for the OPFS pool on its own, which is exactly what shared-tabs exists to
+* stop.
+*/
+function failPromotion(ns, tabId, leadershipId, opts) {
+	if (ns.leader?.tabId !== tabId || ns.leader.leadershipId !== leadershipId) return;
+	ns.failedCycles += 1;
+	ns.failedUntil.set(tabId, Date.now() + LEADER_FAILURE_BACKOFF_MS);
+	const previous = clearLeader(ns, {
+		demote: false,
+		removeTab: false
+	});
+	const tab = ns.tabs.get(tabId);
+	if (tab) tab.heldLeadership = null;
+	electIfNeeded(ns, opts.timedOut && previous ? {
+		...previous,
+		workerLock: `sp00ky-tabs:${ns.fingerprint}:${ns.bucketId}:worker:${leadershipId}`
+	} : previous);
+}
 /**
 * Fast crash detection: queue a Web Lock request on the leader's tab lock.
 * Locks release the instant their holder's tab dies, so being GRANTED means
@@ -174,6 +216,11 @@ function electIfNeeded(ns, previous = null) {
 				allowMemoryFallback: ns.failedCycles >= FAILED_CYCLES_BEFORE_MEMORY,
 				resumeHeld
 			});
+			clearPromotionTimer(ns);
+			ns.promotionTimer = setTimeout(() => {
+				ns.promotionTimer = null;
+				failPromotion(ns, candidate.tabId, leadershipId, { timedOut: true });
+			}, PROMOTION_TIMEOUT_MS);
 		} finally {
 			ns.electing = false;
 		}
@@ -359,6 +406,7 @@ function handleTabMessage(port, msg, ports) {
 			}
 			ns.leader.ready = true;
 			ns.failedCycles = 0;
+			clearPromotionTimer(ns);
 			startTabLockMonitor(ns, msg.leadershipId);
 			const tab = ns.tabs.get(msg.tabId);
 			if (tab) tab.heldLeadership = {
@@ -374,19 +422,9 @@ function handleTabMessage(port, msg, ports) {
 			assignFollowerPorts(ns);
 			break;
 		}
-		case "leader-failed": {
-			if (ns.leader?.tabId !== msg.tabId || ns.leader.leadershipId !== msg.leadershipId) break;
-			ns.failedCycles += 1;
-			ns.failedUntil.set(msg.tabId, Date.now() + LEADER_FAILURE_BACKOFF_MS);
-			const previous = clearLeader(ns, {
-				demote: false,
-				removeTab: false
-			});
-			const tab = ns.tabs.get(msg.tabId);
-			if (tab) tab.heldLeadership = null;
-			electIfNeeded(ns, previous);
+		case "leader-failed":
+			failPromotion(ns, msg.tabId, msg.leadershipId, { timedOut: false });
 			break;
-		}
 		case "follower-port-attached":
 			if (ns.leader?.tabId === msg.tabId && ns.leader.leadershipId === msg.leadershipId) followerAttached(ns, msg.followerTabId);
 			break;

package/dist/types.d.ts

@@ -334,6 +334,37 @@ interface LocalStore extends LocalCacheEngine {
   /** Fires immediately with the current snapshot, then on every change.
    *  Returns an unsubscribe function. */
   subscribeToStorageHealth?(cb: (health: StorageHealth) => void): () => void;
+  /**
+   * Every cached row's `(id, _00_rv)` per table, ids in stable `table:id`
+   * form. The in-browser circuit primes and reconciles itself from this on
+   * boot instead of re-downloading the working set. OPTIONAL: an engine
+   * without it boots the circuit empty, as before.
+   */
+  scanVersions?(tables: string[]): Promise<Record<string, [string, number][]>>;
+  /**
+   * Circuit snapshot storage, keyed. Lives in the same durable store as the
+   * rows (OPFS SQLite), so it is per-bucket by construction, atomic, and
+   * readable by follower tabs over the port transport. OPTIONAL: an engine
+   * without it primes from `scanVersions` alone.
+   */
+  getSnapshot?(key: string): Promise<StoredSnapshot | null>;
+  putSnapshot?(key: string, bytes: Uint8Array, meta: SnapshotMeta): Promise<void>;
+  deleteSnapshot?(key: string): Promise<void>;
+}
+/** Describes a stored circuit snapshot; what decides whether it is usable. */
+interface SnapshotMeta {
+  /** Bump when the wire shape the circuit reads changes. */
+  formatVersion: number;
+  /** Hash of the schema the rows were projected under. */
+  schemaHash: string;
+  savedAt: number;
+  /** Highest `_00_rv` per table at save time (diagnostics). */
+  maxRv?: Record<string, number>;
+  [key: string]: unknown;
+}
+interface StoredSnapshot {
+  bytes: Uint8Array;
+  meta: SnapshotMeta;
 }
 /** Selected local cache backend. Mirrors the `persistenceClient` config pattern. */
 type LocalEngineChoice = 'surrealdb' | 'sqlite' | LocalStore;
@@ -538,21 +569,19 @@ interface Sp00kyConfig<S extends SchemaStructure> {
    */
   sharedTabs?: boolean;
   /**
-   * Persist the in-browser SSP circuit (store + view caches) as a snapshot so a
-   * reload can restore it instead of re-materializing. Default `false`, and
-   * that default is deliberate.
+   * Persist the in-browser SSP circuit's store as a snapshot in the local
+   * store, so a reload restores it and only steps in what changed since.
+   * Defaults to `true` under `localEngine: 'sqlite'` (the OPFS-backed store
+   * can hold the bytes) and `false` otherwise.
    *
-   * The circuit is DERIVED state: the durable local store (OPFS SQLite) is the
-   * source of truth, and every first paint already reads row bodies from it
-   * (`DataManager.createNewQuery` / `materializeRecords`) using the circuit only
-   * for row identity and ordering. A snapshot buys nothing on reload while
-   * costing a full deep clone of every row of every ingested table plus a JSON
-   * encode of the result, `Circuit::save` in the Rust core, mirroring the
-   * server's rule in `ssp-node`: *never per-ingest*.
+   * Without a snapshot the circuit is primed by reading every cached row back
+   * out of the local store; either way a reload never re-downloads the working
+   * set, which is what an empty circuit used to force: every id in the
+   * server's list_ref classified as missing.
    *
-   * When enabled, snapshots are written on a checkpoint interval
-   * ({@link circuitCheckpointMs}) and on `pagehide`, never per ingest or per
-   * query registration. Enable only for a workload that has measured a win.
+   * Snapshots are store-only (views are re-registered per session) and written
+   * on a checkpoint interval ({@link circuitCheckpointMs}) and when the page
+   * goes hidden, never per ingest or per query registration.
    */
   persistCircuit?: boolean;
   /**
@@ -560,6 +589,16 @@ interface Sp00kyConfig<S extends SchemaStructure> {
    * 30000. Ignored when `persistCircuit` is off.
    */
   circuitCheckpointMs?: number;
+  /**
+   * Keep only the fields registered queries evaluate (filter predicates, join
+   * keys, sort keys, plus `id`/`_00_rv`) per row in the in-browser circuit.
+   * Default `true`. The circuit only ever reads those fields; bodies are
+   * rendered from the local store. Measured on 7700 rows with 20 KB bodies:
+   * the wasm heap peak went from ~500 MB to ~24 MB and the snapshot from
+   * 156 MB to 1.2 MB. A query that evaluates a field earlier rows were kept
+   * without has that field merged in from the local store on registration.
+   */
+  circuitProjection?: boolean;
   /** A pino browser transmit object for forwarding logs (e.g. via @spooky-sync/core/otel). */
   otelTransmit?: PinoTransmit;
   /**
@@ -835,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;
   /**
@@ -850,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.204",
+  "version": "0.0.1-canary.206",
   "type": "module",
   "sideEffects": false,
   "main": "./dist/index.js",
@@ -60,8 +60,8 @@
     }
   },
   "dependencies": {
-    "@spooky-sync/query-builder": "0.0.1-canary.204",
-    "@spooky-sync/ssp-wasm": "0.0.1-canary.204",
+    "@spooky-sync/query-builder": "0.0.1-canary.206",
+    "@spooky-sync/ssp-wasm": "0.0.1-canary.206",
     "@sqlite.org/sqlite-wasm": "3.53.0-build1",
     "@surrealdb/wasm": "^3.0.3",
     "blurhash": "^2.0.5",

package/src/modules/cache/index.ts

@@ -88,6 +88,19 @@ export class CacheModule implements StreamUpdateReceiver {
     return this.versionLookups[recordId] ?? 0;
   }
 
+  /**
+   * Seed the version memo from rows the circuit was primed with out of the
+   * local store, so the first post-reload sync diff does not re-download
+   * bodies the browser already has. Only rows the prime actually put into the
+   * circuit belong here: a memo entry with no circuit row would make the diff
+   * flag the id forever while nothing ever fetches it.
+   */
+  public primeVersions(entries: [string, number][]): void {
+    for (const [id, rv] of entries) {
+      if (rv > (this.versionLookups[id] ?? 0)) this.versionLookups[id] = rv;
+    }
+  }
+
   /** Drop the version cache on a bucket switch — a stale version would make
    *  the sync diff skip fetching a body the new bucket legitimately needs. */
   public clearVersionLookups(): void {
@@ -174,13 +187,17 @@ export class CacheModule implements StreamUpdateReceiver {
       // ingestMany coalesces the per-record stream updates into a single
       // notification per affected query — the UI then updates once, after the
       // whole batch is ingested, instead of row-by-row.
+      const versionOf = new Map<string, number>();
       const bulk = populatedRecords.map((record) => {
         const recordId = encodeRecordId(record.record.id);
-        this.versionLookups[recordId] = record.version;
+        versionOf.set(recordId, record.version);
         return { table: record.table, op: record.op, id: recordId, record: record.record };
       });
-      this.streamProcessor.ingestMany(bulk);
-      this.ingestRelay?.(bulk as CacheIngestTuple[]);
+      // Memo and relay only what the circuit actually took: a chunk that
+      // failed mid-batch is neither "known" here nor fanned out to followers.
+      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 as CacheIngestTuple[]);
 
       this.logger.debug(
         { count: records.length, Category: 'sp00ky-client::CacheModule::saveBatch' },
@@ -221,7 +238,7 @@ export class CacheModule implements StreamUpdateReceiver {
 
       // 2. Ingest deletion into DBSP (pass record data so predicates can be matched)
       delete this.versionLookups[id];
-      this.streamProcessor.ingest(table, 'DELETE', id, recordData);
+      this.streamProcessor.ingestMany([{ table, op: 'DELETE', id, record: recordData }]);
       this.ingestRelay?.([{ table, op: 'DELETE', id, record: recordData }]);
 
       this.logger.debug(

package/src/modules/data/data.membership.test.ts

@@ -77,7 +77,7 @@ function makeLocal(pendingRows: Array<{ recordId: RecordId; mutationType: string
   const bodies = new Map(
     ['a', 'b', 'c'].map((k) => [`thread:${k}`, { id: new RecordId('thread', k), title: k }])
   );
-  const windowRows = new Map<string, { ids: RecordVersionArray }>();
+  const windowRows = new Map<string, { ids: RecordVersionArray; confirmed?: boolean }>();
   const local: any = {
     epoch: 1,
     bodies,
@@ -424,6 +424,67 @@ describe('membership-authoritative rendering', () => {
       expect(state.config.remoteArray).toEqual([]);
     });
 
+    it('marks a non-empty set and a server-confirmed empty set as confirmed', async () => {
+      const { dm, local, hash } = setup({ membershipKey: 'stable-key' });
+
+      await dm.updateQueryRemoteArray(hash, [['thread:a', 1]]);
+      expect(local.windowRows.get('stable-key')).toMatchObject({ confirmed: true });
+
+      // The server reports zero rows: a real answer, durable.
+      await dm.updateQueryRemoteArray(hash, [], { serverRowCount: 0 });
+      expect(local.windowRows.get('stable-key')).toEqual(
+        expect.objectContaining({ ids: [], confirmed: true })
+      );
+    });
+
+    it('marks an empty set that follows a seen set as confirmed', async () => {
+      // Everything the query matched was deleted while this session watched: the
+      // transition is genuine, so the next boot must not resurrect the rows.
+      const { dm, local, hash } = setup({ membershipKey: 'stable-key' });
+      await dm.updateQueryRemoteArray(hash, [['thread:a', 1]]);
+      await dm.updateQueryRemoteArray(hash, [], { serverRowCount: null });
+      expect(local.windowRows.get('stable-key')).toEqual(
+        expect.objectContaining({ ids: [], confirmed: true })
+      );
+    });
+
+    it('leaves the retry-budget empty unconfirmed', async () => {
+      // Two unreadable-row-count empties are believed for this session, but they
+      // are a guess: the durable row must not turn that guess into a permanent
+      // empty list on the next boot.
+      const { dm, local, hash } = setup({
+        membershipKey: 'stable-key',
+        remoteArray: [['thread:a', 1]],
+        membershipKnown: true,
+      });
+      await dm.updateQueryRemoteArray(hash, [], { serverRowCount: null });
+      await dm.updateQueryRemoteArray(hash, [], { serverRowCount: null });
+      expect(local.windowRows.get('stable-key')).toEqual(
+        expect.objectContaining({ ids: [], confirmed: false })
+      );
+    });
+
+    it('seeds a known-empty membership from a confirmed empty durable row', async () => {
+      // The reload after a server-confirmed empty: the list must stay empty
+      // instead of re-admitting every cached body until the next poll blanks it.
+      const { dm, local } = setup({ membershipKey: 'stable-key' });
+      local.windowRows.set('stable-key', { ids: [], confirmed: true });
+
+      const fresh = await (dm as any).createNewQuery({
+        recordId: new RecordId('_00_query', 'h-confirmed-empty'),
+        surql: 'SELECT * FROM thread WHERE done = false;',
+        params: {},
+        ttl: '10m',
+        tableName: 'thread',
+        plan,
+        membershipKey: 'stable-key',
+      });
+
+      expect(fresh.config.membershipKnown).toBe(true);
+      expect(fresh.config.remoteArray).toEqual([]);
+      expect(fresh.records).toEqual([]);
+    });
+
     it('does not seed membership from an empty durable row', async () => {
       // Self-heals devices poisoned before the guard existed: an empty durable
       // row is indistinguishable from "never had membership", so it must fall

package/src/modules/data/data.rebind.test.ts

@@ -122,6 +122,29 @@ describe('DataModule.rebindAfterBucketSwitch', () => {
   });
 });
 
+describe('DataModule.rebindAfterBucketSwitch durable seed', () => {
+  it('seeds a confirmed-empty membership from the new bucket, and ignores an unconfirmed one', async () => {
+    const harness = makeHarness();
+    const { dm, local } = harness as any;
+    const state = makeQueryState('h1', [{ id: 'user:a', name: 'Previous User Row' }]);
+    state.config.membershipKey = 'stable-key';
+    (dm as any).activeQueries.set('h1', state);
+    local.getById = vi.fn(async () => ({ ids: [], confirmed: true }));
+
+    await dm.rebindAfterBucketSwitch();
+    let qs = (dm as any).activeQueries.get('h1') as QueryState;
+    expect(qs.config.membershipKnown).toBe(true);
+    expect(qs.config.remoteArray).toEqual([]);
+    if (qs.ttlTimer) clearTimeout(qs.ttlTimer);
+
+    local.getById = vi.fn(async () => ({ ids: [] }));
+    await dm.rebindAfterBucketSwitch();
+    qs = (dm as any).activeQueries.get('h1') as QueryState;
+    expect(qs.config.membershipKnown).toBe(false);
+    if (qs.ttlTimer) clearTimeout(qs.ttlTimer);
+  });
+});
+
 describe('stale-epoch stream updates', () => {
   it('drops an update whose chain started before a bucket switch', async () => {
     const { dm, local } = makeHarness();

package/src/modules/data/index.ts

@@ -82,6 +82,13 @@ function phaseStatOf(samples: number[], lastMs: number | null): PhaseStat {
  * 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). */
+export interface DurableMembership {
+  ids: RecordVersionArray;
+  confirmed: boolean;
+}
+
 export class DataModule<S extends SchemaStructure> {
   /** Tab identity baked into mutation ids (shared-tabs rollback routing);
    *  undefined in solo mode, where mutation-id falls back to a session id. */
@@ -1161,32 +1168,54 @@ export class DataModule<S extends SchemaStructure> {
   //
   // `_00_window` fixes that: same data, keyed by a session-independent hash, in
   // a table nothing wipes. Mirrors the durable `_00_preload` marker above.
+  //
+  // Row shape: `{ ids, confirmed, updatedAt }`. `confirmed` is the one bit that
+  // lets an EMPTY row be trusted on the next boot (see `getWindowMembership`).
 
   /**
    * Read the durable membership row, or `null` if this query has never had
    * 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: string): Promise<RecordVersionArray | null> {
+  async getWindowMembership(key: string): Promise<DurableMembership | null> {
     try {
       const row = await this.local.getById('_00_window', new RecordId('_00_window', key));
       if (!row || typeof row !== 'object') return null;
       const ids = (row as any).ids;
-      return Array.isArray(ids) ? (ids as RecordVersionArray) : null;
+      if (!Array.isArray(ids)) return null;
+      return { ids: ids as RecordVersionArray, confirmed: (row as any).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: string, ids: RecordVersionArray): Promise<void> {
+  /**
+   * 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: string,
+    ids: RecordVersionArray,
+    confirmed: boolean
+  ): Promise<void> {
     try {
       await this.local.upsert(
         '_00_window',
         new RecordId('_00_window', key),
-        { ids, updatedAt: Date.now() },
+        { ids, confirmed, updatedAt: Date.now() },
         'replace'
       );
     } catch (err) {
@@ -1389,9 +1418,16 @@ export class DataModule<S extends SchemaStructure> {
     // registration, well inside the flush window for a real collection, so
     // "believe it the second time" blanked exactly the lists this guard exists
     // to protect — reported as rows vanishing ~2s after a page load.
+    // Whether this write may be trusted by the NEXT session. Non-empty sets
+    // always; an empty set only when the server stood behind it (a zero row
+    // count, or a real set was seen this session and it is now gone). The
+    // retry-budget path below accepts an empty without that backing and must
+    // stay non-durable, or the poisoned-device self-heal is lost.
+    let confirmed = remoteArray.length > 0 || queryState.config.remoteSeen === true;
     if (remoteArray.length === 0 && !queryState.config.remoteSeen) {
       const serverRowCount = opts?.serverRowCount;
       const knownEmpty = serverRowCount === 0;
+      confirmed = knownEmpty;
       if (!knownEmpty) {
         // Unknown row count still gets a bounded escape hatch, so a server that
         // cannot report one never strands a device on a durable seed forever.
@@ -1429,7 +1465,7 @@ export class DataModule<S extends SchemaStructure> {
       queryState.config.emptyReads = 0;
     }
     if (queryState.config.membershipKey) {
-      await this.writeWindowMembership(queryState.config.membershipKey, remoteArray);
+      await this.writeWindowMembership(queryState.config.membershipKey, remoteArray, confirmed);
     }
     try {
       await this.local.query(
@@ -1499,10 +1535,10 @@ export class DataModule<S extends SchemaStructure> {
       config.emptyReads = 0;
       if (config.membershipKey) {
         const durable = await this.getWindowMembership(config.membershipKey);
-        // Length-checked for the same reason as the cold-start read above: an
-        // empty durable row is indistinguishable from "never had membership".
-        if (durable?.length) {
-          config.remoteArray = durable;
+        // Same rule as the cold-start read: a non-empty row, or an empty one
+        // the server confirmed, is membership; an unmarked empty row is not.
+        if (durable && (durable.ids.length > 0 || durable.confirmed)) {
+          config.remoteArray = durable.ids;
           config.membershipKnown = true;
         }
       }
@@ -2193,12 +2229,16 @@ export class DataModule<S extends SchemaStructure> {
     // removed row reappearing after a reload, and it works with no network.
     if (membershipKey && !config.remoteArray?.length) {
       const durable = await this.getWindowMembership(membershipKey);
-      // `durable.length` on purpose: an empty durable row cannot be told apart
-      // from one written before this device ever saw a real id-set, and treating
-      // it as known means the first paint is empty with no scan fallback. It
-      // also self-heals devices poisoned by the pre-fix `writeWindowMembership`.
-      if (durable?.length) {
-        config.remoteArray = durable;
+      // An empty durable row is trusted only when it carries the `confirmed`
+      // marker, i.e. the server itself reported the query empty. Without it an
+      // empty row cannot be told apart from one written before this device ever
+      // saw a real id-set (or by the pre-`ea56f50e` client that mirrored
+      // unflushed reads), and treating it as known would paint an empty list
+      // with no scan fallback. A confirmed empty is the opposite case: the
+      // server said "no rows", so a reload must stay empty rather than re-admit
+      // every cached body until the next poll blanks it again.
+      if (durable && (durable.ids.length > 0 || durable.confirmed)) {
+        config.remoteArray = durable.ids;
         config.membershipKnown = true;
       }
     } else if (config.remoteArray?.length) {

package/src/modules/devtools/index.ts

@@ -208,6 +208,12 @@ export class DevToolsService implements StreamUpdateReceiver {
         data: q.records,
         localArray: q.config.localArray,
         remoteArray: q.config.remoteArray,
+        // Membership state, so "why is this list empty" is answerable from
+        // the panel: is the server's set known, has a non-empty one been seen
+        // this session, how many empty reads were ignored.
+        membershipKnown: q.config.membershipKnown === true,
+        remoteSeen: q.config.remoteSeen === true,
+        emptyReads: q.config.emptyReads ?? 0,
         // Detailed per-phase processing-time breakdown (SSP sub-phases, local/
         // remote record fetch, frontend reconcile, registration). Flows to both
         // the DevTools panel and the MCP (which returns activeQueries verbatim).
@@ -327,7 +333,9 @@ export class DevToolsService implements StreamUpdateReceiver {
         const info = this.unwrapInfo(res);
         this.localTablesAt = Date.now();
         if (info && info.tables) {
-          const names = Object.keys(info.tables);
+          // The circuit snapshot table holds a BLOB, not JSON rows; the
+          // explorer cannot render it and has nothing to show for it.
+          const names = Object.keys(info.tables).filter((n) => n !== '_00_circuit_snapshot');
           const changed =
             names.length !== this.localTables.length ||
             names.some((n, i) => n !== this.localTables[i]);