@spooky-sync/core 0.0.1-canary.171 → 0.0.1-canary.172

package/dist/index.d.ts

@@ -2157,10 +2157,10 @@ declare class Sp00kyClient<S extends SchemaStructure> {
    * Nothing is sent to the server — the `_00_user_feature` assignment is
    * untouched, so clearing restores whatever the server says. Persisted to
    * localStorage, survives reloads, and applies while signed out. Backs the
-   * DevTools Flags tab, and is a convenient hook for tests.
+   * DevTools Access tab, and is a convenient hook for tests.
    *
    * To change a flag for OTHER users you need admin rights (`spky admin add`)
-   * and the DevTools Flags tab, or `spky flag`.
+   * and the DevTools Access tab, or `spky flag`.
    */
   setFeatureOverride(key: string, variant: string | null, payload?: unknown): void;
   /** Drop every local feature flag override set via `setFeatureOverride`. */

package/dist/index.js

@@ -3069,6 +3069,13 @@ function mutationOwnerTabId(mutationId) {
 
 //#endregion
 //#region src/modules/data/index.ts
+/**
+* How many consecutive empty `_00_list_ref` reads it takes to believe a query
+* really is empty, before any non-empty set has been seen this session. One
+* read is the registration race (the SSP flushes a view's initial edges
+* asynchronously); the second comes from the poll a cycle later.
+*/
+const EMPTY_MEMBERSHIP_CONFIRMATIONS = 2;
 /** Push a timing sample (ms) into a rolling window, capped at the sample window. */
 function pushSample(samples, ms) {
 	samples.push(ms);
@@ -3899,9 +3906,25 @@ var DataModule = class {
 			}, "Query to update remote array not found");
 			return;
 		}
+		if (remoteArray.length === 0 && !queryState.config.remoteSeen) {
+			const emptyReads = (queryState.config.emptyReads ?? 0) + 1;
+			queryState.config.emptyReads = emptyReads;
+			if (emptyReads < EMPTY_MEMBERSHIP_CONFIRMATIONS) {
+				this.logger.debug({
+					hash,
+					emptyReads,
+					Category: "sp00ky-client::DataModule::updateQueryRemoteArray"
+				}, "Ignoring unconfirmed empty membership (server may not have flushed list_ref yet)");
+				return;
+			}
+		}
 		const epoch = this.local.epoch;
 		queryState.config.remoteArray = remoteArray;
 		queryState.config.membershipKnown = true;
+		if (remoteArray.length > 0) {
+			queryState.config.remoteSeen = true;
+			queryState.config.emptyReads = 0;
+		}
 		if (queryState.config.membershipKey) await this.writeWindowMembership(queryState.config.membershipKey, remoteArray);
 		try {
 			await this.local.query(surql.seal(surql.updateSet("id", ["remoteArray"])), {
@@ -3951,9 +3974,11 @@ var DataModule = class {
 			config.remoteArray = [];
 			config.subqueryRemoteArray = void 0;
 			config.membershipKnown = false;
+			config.remoteSeen = false;
+			config.emptyReads = 0;
 			if (config.membershipKey) {
 				const durable = await this.getWindowMembership(config.membershipKey);
-				if (durable) {
+				if (durable?.length) {
 					config.remoteArray = durable;
 					config.membershipKnown = true;
 				}
@@ -4381,7 +4406,7 @@ var DataModule = class {
 		};
 		if (membershipKey && !config.remoteArray?.length) {
 			const durable = await this.getWindowMembership(membershipKey);
-			if (durable) {
+			if (durable?.length) {
 				config.remoteArray = durable;
 				config.membershipKnown = true;
 			}
@@ -6577,7 +6602,7 @@ var FlagsAdminService = class {
 		this.deps = deps;
 	}
 	/**
-	* Everything the Flags tab renders, in one round trip per source.
+	* Everything the Access tab renders, in one round trip per source.
 	*
 	* Each section fails independently: a remote read that throws downgrades to
 	* `isAdmin: false` plus an `error`, while local assignments and overrides
@@ -6609,7 +6634,7 @@ var FlagsAdminService = class {
 		try {
 			snapshot.isAdmin = statementRows(await this.deps.remote.query("SELECT VALUE id FROM _00_admin WHERE user = $auth.id LIMIT 1")).length > 0;
 		} catch (err) {
-			snapshot.error = `Could not check admin status: ${message(err)}. If this deployment predates the Flags tab, run \`spky migrate\` (or redeploy) to apply the internal schema.`;
+			snapshot.error = `Could not check admin status: ${message(err)}. If this deployment predates the Access tab, run \`spky migrate\` (or redeploy) to apply the internal schema.`;
 			return snapshot;
 		}
 		if (!snapshot.isAdmin) return snapshot;
@@ -6729,8 +6754,8 @@ function selfAllowlistedVariant(flag, userId) {
 
 //#endregion
 //#region src/modules/devtools/index.ts
-const CORE_VERSION = "0.0.1-canary.171";
-const WASM_VERSION = "0.0.1-canary.171";
+const CORE_VERSION = "0.0.1-canary.172";
+const WASM_VERSION = "0.0.1-canary.172";
 const SURREAL_VERSION = "3.0.3";
 var DevToolsService = class DevToolsService {
 	eventsHistory = [];
@@ -7088,7 +7113,7 @@ var DevToolsService = class DevToolsService {
 		return data;
 	}
 	/**
-	* Hand the FeatureFlagModule to the Flags tab so it can read and write local
+	* Hand the FeatureFlagModule to the Access tab so it can read and write local
 	* overrides. Called from `Sp00kyClient` once both are constructed; until then
 	* the override methods are no-ops that report an empty map.
 	*/
@@ -11160,7 +11185,7 @@ var Sp00kyClient = class {
 		return new TabsCoordinator({
 			tabId,
 			fingerprint: computeTabsFingerprint({
-				coreVersion: "0.0.1-canary.171",
+				coreVersion: "0.0.1-canary.172",
 				schemaHash: hash53(this.config.schemaSurql),
 				endpoint: this.config.database.endpoint ?? "",
 				namespace: this.config.database.namespace,
@@ -11506,10 +11531,10 @@ var Sp00kyClient = class {
 	* Nothing is sent to the server — the `_00_user_feature` assignment is
 	* untouched, so clearing restores whatever the server says. Persisted to
 	* localStorage, survives reloads, and applies while signed out. Backs the
-	* DevTools Flags tab, and is a convenient hook for tests.
+	* DevTools Access tab, and is a convenient hook for tests.
 	*
 	* To change a flag for OTHER users you need admin rights (`spky admin add`)
-	* and the DevTools Flags tab, or `spky flag`.
+	* and the DevTools Access tab, or `spky flag`.
 	*/
 	setFeatureOverride(key, variant, payload) {
 		this.featureFlags.setLocalOverride(key, variant, payload);

package/dist/types.d.ts

@@ -815,6 +815,29 @@ interface QueryConfig {
    * `remoteArray.length === 0` check cannot tell those apart.
    */
   membershipKnown?: boolean;
+  /**
+   * Whether a NON-EMPTY id-set has arrived from the server for this query in
+   * this session. Gates whether an empty read may be believed.
+   *
+   * The server publishes `_00_list_ref` asynchronously — the SSP queues a
+   * view's initial edges to a coalescing flusher and returns from
+   * `fn::query::register` before they land — so an empty read right after
+   * registration says nothing about the query being empty. Believing it (and
+   * mirroring it to the durable `_00_window` row) blanked lists and kept them
+   * blank across reloads. Once a real set has been seen, a later empty one is a
+   * genuine transition and must be honoured, or removed rows resurrect.
+   *
+   * In-memory only: a fresh session must re-earn the right to believe empties.
+   */
+  remoteSeen?: boolean;
+  /**
+   * Consecutive empty id-sets read from the server while `remoteSeen` is still
+   * false. Bounds how long an unconfirmed empty may be ignored, so a window
+   * that genuinely emptied while this device was away is believed on the second
+   * read instead of rendering stale rows forever. Reset by any non-empty set.
+   * In-memory only.
+   */
+  emptyReads?: number;
   /**
    * Key of this query's durable `_00_window` membership row: a hash of
    * `{surql, params}` WITHOUT the `session::id()` salt that `id` carries, so it

package/package.json

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

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

@@ -280,6 +280,73 @@ describe('membership-authoritative rendering', () => {
       expect(ids(fresh.records)).toEqual(['thread:a', 'thread:b', 'thread:c']);
     });
 
+    it('ignores an empty id-set until a real one has been seen', async () => {
+      // The registration race: the SSP queues a view's initial edges to a
+      // coalescing flusher and returns from `fn::query::register` before they
+      // land, so this read says nothing about the query being empty. Believing
+      // it rendered a blank list AND persisted the blankness.
+      const { dm, state, local, hash } = setup({
+        membershipKey: 'stable-key',
+        remoteArray: [['thread:a', 1]],
+        membershipKnown: true,
+      });
+
+      await dm.updateQueryRemoteArray(hash, []);
+
+      expect(state.config.remoteArray).toEqual([['thread:a', 1]]);
+      expect(local.windowRows.has('stable-key')).toBe(false);
+    });
+
+    it('believes an empty id-set once a non-empty one has arrived', async () => {
+      // The genuine transition — the last row left the window. Honouring it is
+      // what stops a removed row resurrecting from the local body cache.
+      const { dm, state, local, hash } = setup({ membershipKey: 'stable-key' });
+
+      await dm.updateQueryRemoteArray(hash, [['thread:a', 1]]);
+      await dm.updateQueryRemoteArray(hash, []);
+
+      expect(state.config.membershipKnown).toBe(true);
+      expect(state.config.remoteArray).toEqual([]);
+      expect(local.windowRows.get('stable-key')).toMatchObject({ ids: [] });
+    });
+
+    it('believes a repeated empty id-set even with nothing seen this session', async () => {
+      // A window that really did empty while this device was away: the durable
+      // seed must not render forever, so the second read is taken at face value.
+      const { dm, state, hash } = setup({
+        membershipKey: 'stable-key',
+        remoteArray: [['thread:a', 1]],
+        membershipKnown: true,
+      });
+
+      await dm.updateQueryRemoteArray(hash, []);
+      expect(state.config.remoteArray).toEqual([['thread:a', 1]]);
+
+      await dm.updateQueryRemoteArray(hash, []);
+      expect(state.config.remoteArray).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
+      // back to the scan rather than paint an empty list.
+      const { dm, local } = setup({ membershipKey: 'stable-key' });
+      local.windowRows.set('stable-key', { ids: [] });
+
+      const fresh = await (dm as any).createNewQuery({
+        recordId: new RecordId('_00_query', 'h-poisoned'),
+        surql: 'SELECT * FROM thread WHERE done = false;',
+        params: {},
+        ttl: '10m',
+        tableName: 'thread',
+        plan,
+        membershipKey: 'stable-key',
+      });
+
+      expect(fresh.config.membershipKnown).toBeFalsy();
+      expect(ids(fresh.records)).toEqual(['thread:a', 'thread:b', 'thread:c']);
+    });
+
     it('derives the membership key without the session salt', async () => {
       const { dm } = setup();
       const key = () => (dm as any).calculateMembershipKey({ surql: 'X', params: {} });

package/src/modules/data/index.ts

@@ -52,6 +52,14 @@ import {
 } from './window-query';
 import { mintMutationId } from './mutation-id';
 
+/**
+ * How many consecutive empty `_00_list_ref` reads it takes to believe a query
+ * really is empty, before any non-empty set has been seen this session. One
+ * read is the registration race (the SSP flushes a view's initial edges
+ * asynchronously); the second comes from the poll a cycle later.
+ */
+const EMPTY_MEMBERSHIP_CONFIRMATIONS = 2;
+
 /** Push a timing sample (ms) into a rolling window, capped at the sample window. */
 function pushSample(samples: number[], ms: number): void {
   samples.push(ms);
@@ -1198,12 +1206,49 @@ export class DataModule<S extends SchemaStructure> {
       );
       return;
     }
+    // An empty id-set is only believable once a real one has arrived in this
+    // session. `_00_list_ref` is published asynchronously — the SSP queues a
+    // view's initial edges to a coalescing flusher and returns from
+    // `fn::query::register` before they land — so an empty read right after
+    // registration is routinely just "not flushed yet", for a query that has
+    // rows. Taking it at face value latched `membershipKnown` on an empty set,
+    // which renders nothing (no scan fallback), and mirrored `[]` into the
+    // durable `_00_window` row, which kept the list blank across reloads.
+    //
+    // Ignoring it entirely (rather than storing `[]` with the latch withheld)
+    // is deliberate: on a cold start `remoteArray` is seeded from the durable
+    // row, and overwriting that with `[]` would blank the very rows the seed
+    // exists to paint. The `_00_list_ref` poll re-reads within ~500ms and
+    // delivers the real set.
+    // Bounded, though: a query seeded from the durable row on a cold start has
+    // `remoteSeen === false`, and if its window really did empty while this
+    // device was away, the server will keep answering `[]`. Believe it on the
+    // second such read — one poll cycle (~500ms) past the flush window — so
+    // stale rows can't render forever.
+    if (remoteArray.length === 0 && !queryState.config.remoteSeen) {
+      const emptyReads = (queryState.config.emptyReads ?? 0) + 1;
+      queryState.config.emptyReads = emptyReads;
+      if (emptyReads < EMPTY_MEMBERSHIP_CONFIRMATIONS) {
+        this.logger.debug(
+          { hash, emptyReads, Category: 'sp00ky-client::DataModule::updateQueryRemoteArray' },
+          'Ignoring unconfirmed empty membership (server may not have flushed list_ref yet)'
+        );
+        return;
+      }
+    }
+
     const epoch = this.local.epoch;
     queryState.config.remoteArray = remoteArray;
     // The single point where authoritative membership arrives (registration and
     // the `_00_list_ref` poll both land here), so it is where "we now know the
     // membership" is latched and where the durable mirror is written.
     queryState.config.membershipKnown = true;
+    if (remoteArray.length > 0) {
+      // Earns the right to believe a later empty set — that transition is a
+      // genuine removal and must be honoured, or removed rows resurrect.
+      queryState.config.remoteSeen = true;
+      queryState.config.emptyReads = 0;
+    }
     if (queryState.config.membershipKey) {
       await this.writeWindowMembership(queryState.config.membershipKey, remoteArray);
     }
@@ -1269,9 +1314,15 @@ export class DataModule<S extends SchemaStructure> {
       // unknown so the first paint falls back to a scan instead of rendering an
       // empty list until the server answers.
       config.membershipKnown = false;
+      // The new bucket's server sets have not been seen yet — an empty read
+      // must be re-confirmed there too.
+      config.remoteSeen = false;
+      config.emptyReads = 0;
       if (config.membershipKey) {
         const durable = await this.getWindowMembership(config.membershipKey);
-        if (durable) {
+        // 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;
           config.membershipKnown = true;
         }
@@ -1957,7 +2008,11 @@ 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);
-      if (durable) {
+      // `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;
         config.membershipKnown = true;
       }

package/src/modules/devtools/flags.ts

@@ -150,7 +150,7 @@ export class FlagsAdminService {
   constructor(private deps: FlagsAdminDeps) {}
 
   /**
-   * Everything the Flags tab renders, in one round trip per source.
+   * Everything the Access tab renders, in one round trip per source.
    *
    * Each section fails independently: a remote read that throws downgrades to
    * `isAdmin: false` plus an `error`, while local assignments and overrides
@@ -196,7 +196,7 @@ export class FlagsAdminService {
     } catch (err) {
       // A missing `_00_admin` table means the deployment hasn't applied the
       // internal schema yet. Say so — otherwise it reads as "not an admin".
-      snapshot.error = `Could not check admin status: ${message(err)}. If this deployment predates the Flags tab, run \`spky migrate\` (or redeploy) to apply the internal schema.`;
+      snapshot.error = `Could not check admin status: ${message(err)}. If this deployment predates the Access tab, run \`spky migrate\` (or redeploy) to apply the internal schema.`;
       return snapshot;
     }
 

package/src/modules/devtools/index.ts

@@ -86,7 +86,7 @@ export class DevToolsService implements StreamUpdateReceiver {
   private localTablesFetching = false;
   private localTablesAt = 0;
 
-  // Feature flag admin, backing the panel's Flags tab. The local-override
+  // Feature flag admin, backing the panel's Access tab. The local-override
   // store is injected later (`setFeatureFlagOverrides`) because the
   // FeatureFlagModule is built after this service.
   private featureOverrides: LocalOverrideStore | null = null;
@@ -545,7 +545,7 @@ export class DevToolsService implements StreamUpdateReceiver {
   }
 
   /**
-   * Hand the FeatureFlagModule to the Flags tab so it can read and write local
+   * Hand the FeatureFlagModule to the Access tab so it can read and write local
    * overrides. Called from `Sp00kyClient` once both are constructed; until then
    * the override methods are no-ops that report an empty map.
    */
@@ -558,7 +558,7 @@ export class DevToolsService implements StreamUpdateReceiver {
       (window as any).__00__ = {
         version: this.version,
         getState: () => this.getState(),
-        // ---- Feature flags (Flags tab) --------------------------------
+        // ---- Feature flags (Access tab) --------------------------------
         // Remote reads/writes are admin-gated by SurrealDB, not here: a
         // non-admin gets an empty flag list, and the `fn::feature::*` calls
         // are denied outright. The override methods are purely local and

package/src/sp00ky.ts

@@ -465,7 +465,7 @@ export class Sp00kyClient<S extends SchemaStructure> {
       this.dataModule
     );
 
-    // Let the DevTools Flags tab read and write local flag overrides. Done
+    // Let the DevTools Access tab read and write local flag overrides. Done
     // here rather than via the constructor because FeatureFlagModule is built
     // above and DevToolsService takes its deps positionally.
     this.devTools.setFeatureFlagOverrides(this.featureFlags);
@@ -1065,10 +1065,10 @@ export class Sp00kyClient<S extends SchemaStructure> {
    * Nothing is sent to the server — the `_00_user_feature` assignment is
    * untouched, so clearing restores whatever the server says. Persisted to
    * localStorage, survives reloads, and applies while signed out. Backs the
-   * DevTools Flags tab, and is a convenient hook for tests.
+   * DevTools Access tab, and is a convenient hook for tests.
    *
    * To change a flag for OTHER users you need admin rights (`spky admin add`)
-   * and the DevTools Flags tab, or `spky flag`.
+   * and the DevTools Access tab, or `spky flag`.
    */
   setFeatureOverride(key: string, variant: string | null, payload?: unknown): void {
     this.featureFlags.setLocalOverride(key, variant, payload);

package/src/types.ts

@@ -488,6 +488,29 @@ export interface QueryConfig {
    * `remoteArray.length === 0` check cannot tell those apart.
    */
   membershipKnown?: boolean;
+  /**
+   * Whether a NON-EMPTY id-set has arrived from the server for this query in
+   * this session. Gates whether an empty read may be believed.
+   *
+   * The server publishes `_00_list_ref` asynchronously — the SSP queues a
+   * view's initial edges to a coalescing flusher and returns from
+   * `fn::query::register` before they land — so an empty read right after
+   * registration says nothing about the query being empty. Believing it (and
+   * mirroring it to the durable `_00_window` row) blanked lists and kept them
+   * blank across reloads. Once a real set has been seen, a later empty one is a
+   * genuine transition and must be honoured, or removed rows resurrect.
+   *
+   * In-memory only: a fresh session must re-earn the right to believe empties.
+   */
+  remoteSeen?: boolean;
+  /**
+   * Consecutive empty id-sets read from the server while `remoteSeen` is still
+   * false. Bounds how long an unconfirmed empty may be ignored, so a window
+   * that genuinely emptied while this device was away is believed on the second
+   * read instead of rendering stale rows forever. Reset by any non-empty set.
+   * In-memory only.
+   */
+  emptyReads?: number;
   /**
    * Key of this query's durable `_00_window` membership row: a hash of
    * `{surql, params}` WITHOUT the `session::id()` salt that `id` carries, so it