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

package/src/modules/cache/index.ts

@@ -33,8 +33,11 @@ export class CacheModule implements StreamUpdateReceiver {
   private versionLookups: Record<string, number> = {};
   /** 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: ((tuples: CacheIngestTuple[]) => void) | null = null;
+  /** See {@link setIngestRelay}. */
+  private relayLocalWritesOnly = false;
 
   constructor(
     private local: LocalStore,
@@ -64,8 +67,21 @@ export class CacheModule implements StreamUpdateReceiver {
     this.streamUpdateCallback(update);
   }
 
-  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 {
     this.ingestRelay = cb;
+    this.relayLocalWritesOnly = opts.localWritesOnly === true;
   }
 
   /**
@@ -197,7 +213,11 @@ export class CacheModule implements StreamUpdateReceiver {
       // 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[]);
+      // `skipDbInsert` is exactly the mutation path (the tx already wrote the
+      // row); sync-fetched batches pass false.
+      if (ingested.length > 0 && (!this.relayLocalWritesOnly || skipDbInsert)) {
+        this.ingestRelay?.(ingested as CacheIngestTuple[]);
+      }
 
       this.logger.debug(
         { count: records.length, Category: 'sp00ky-client::CacheModule::saveBatch' },
@@ -239,7 +259,9 @@ export class CacheModule implements StreamUpdateReceiver {
       // 2. Ingest deletion into DBSP (pass record data so predicates can be matched)
       delete this.versionLookups[id];
       this.streamProcessor.ingestMany([{ table, op: 'DELETE', id, record: recordData }]);
-      this.ingestRelay?.([{ table, op: 'DELETE', id, record: recordData }]);
+      if (!this.relayLocalWritesOnly || skipDbDelete) {
+        this.ingestRelay?.([{ table, op: 'DELETE', id, record: recordData }]);
+      }
 
       this.logger.debug(
         { table, id, Category: 'sp00ky-client::CacheModule::delete' },

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.notify-table.test.ts

@@ -0,0 +1,41 @@
+import { describe, it, expect, vi } from 'vitest';
+import { RecordId } from 'surrealdb';
+import { DataModule } from './index';
+
+// A DELETE that landed in the local store (this tab's own, or one relayed
+// from another tab) needs a forced re-materialize of the table's queries: the
+// SSP may not emit a view update for it.
+
+function makeLogger(): any {
+  const logger: any = { debug: () => {}, info: () => {}, warn: () => {}, error: () => {}, trace: () => {} };
+  logger.child = () => logger;
+  return logger;
+}
+
+const schema = { tables: [{ name: 'comment', columns: {} }, { name: 'thread', columns: {} }] } as any;
+
+function state(hash: string, tableName: string): any {
+  return {
+    config: { id: new RecordId('_00_query', hash), tableName, localArray: [], remoteArray: [] },
+    records: [],
+  };
+}
+
+describe('DataModule.notifyTableQueries', () => {
+  it('re-materializes only the queries on that table, isolating failures', async () => {
+    const local: any = { epoch: 1, query: vi.fn(async () => [[]]) };
+    const dm = new DataModule({ saveBatch: async () => {} } as any, local, schema, makeLogger(), 100);
+    (dm as any).activeQueries.set('c1', state('c1', 'comment'));
+    (dm as any).activeQueries.set('c2', state('c2', 'comment'));
+    (dm as any).activeQueries.set('t1', state('t1', 'thread'));
+    const notified: string[] = [];
+    dm.notifyQuerySynced = vi.fn(async (hash: string) => {
+      notified.push(hash);
+      if (hash === 'c1') throw new Error('boom');
+    }) as any;
+
+    await dm.notifyTableQueries('comment');
+
+    expect(notified.sort()).toEqual(['c1', 'c2']);
+  });
+});

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;
         }
       }
@@ -1893,20 +1929,8 @@ export class DataModule<S extends SchemaStructure> {
     }
 
     // DBSP may not emit view updates for DELETE ops — manually notify all queries
-    // that reference this table. Each is isolated so one failing re-materialize
-    // can't stop the others (or the sync emit below) from running.
-    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'
-          );
-        }
-      }
-    }
+    // that reference this table.
+    await this.notifyTableQueries(tableName);
 
     // Emit mutation event
     const mutationEvent: DeleteEvent = {
@@ -1998,6 +2022,29 @@ export class DataModule<S extends SchemaStructure> {
     }
   }
 
+  /**
+   * 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: string): Promise<void> {
+    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
    */
@@ -2193,12 +2240,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).

package/src/modules/sync/sync.live-removal.test.ts

@@ -110,6 +110,46 @@ describe('LIVE list_ref removal → membership', () => {
     ]);
   });
 
+  // Every tab that ingested a write optimistically (its own, or one relayed
+  // from another tab) already holds the row at the server's version, so the
+  // fetch diff is empty. Membership still has to be recorded, or the row lives
+  // on the settled-write grace alone until the poll catches it.
+  it('adds membership for a row the circuit already holds at the server version', async () => {
+    const { queryState, updateQueryRemoteArray, sync, live } = makeSync();
+    queryState.config.localArray = [
+      ['thread:a', 1],
+      ['thread:b', 1],
+      ['thread:c', 1],
+    ];
+
+    await live('CREATE', 'c', 1);
+
+    expect(updateQueryRemoteArray).toHaveBeenCalledWith('h1', [
+      ['thread:a', 1],
+      ['thread:b', 1],
+      ['thread:c', 1],
+    ]);
+    // …without a refetch: the diff handed to the sync is empty.
+    expect((sync as any).runSyncForQuery).toHaveBeenCalledWith('h1', {
+      added: [],
+      updated: [],
+      removed: [],
+    });
+  });
+
+  it('records a bumped version on UPDATE without rewriting an unchanged list', async () => {
+    const { updateQueryRemoteArray, live } = makeSync();
+
+    await live('UPDATE', 'b', 1);
+    expect(updateQueryRemoteArray).not.toHaveBeenCalled();
+
+    await live('UPDATE', 'b', 2);
+    expect(updateQueryRemoteArray).toHaveBeenCalledWith('h1', [
+      ['thread:a', 1],
+      ['thread:b', 2],
+    ]);
+  });
+
   it('leaves membership alone while it is still unknown', async () => {
     // Nothing authoritative has arrived yet, so there is no list to amend —
     // registration will supply the whole thing shortly.