@spooky-sync/core 0.0.1-canary.102 → 0.0.1-canary.104

package/dist/types.d.ts

@@ -403,10 +403,13 @@ type QueryConfigRecord = QueryConfig & {
 };
 /**
  * Runtime fetch status of a live query.
- * - `idle`: not currently fetching missing records.
- * - `fetching`: the sync engine is fetching/ingesting missing records for this
- *   query. UI notifications are coalesced so the result lands as a single
- *   update once fetching completes.
+ * - `idle`: registered, initial sync completed, and not currently fetching
+ *   missing records — the materialized rows are authoritative (a windowed
+ *   query's short result really is the end of the list).
+ * - `fetching`: the query is registering (a query is born `fetching` until its
+ *   initial remote sync completes) or the sync engine is fetching/ingesting
+ *   missing records for it. Any pending debounced result is flushed BEFORE the
+ *   flip back to `idle`, so idle status never races ahead of the rows.
  */
 type QueryStatus = 'idle' | 'fetching';
 /**
@@ -420,12 +423,20 @@ interface QueryState {
   /** Set once `applyHydration` has run for this query, so the cold instant-hydrate
    * path fires at most once per query (see DataModule.isCold/applyHydration). */
   hydrated?: boolean;
+  /** Set once `notifyQuerySynced` has emitted for this registration lifetime.
+   * Ephemeral (unlike the persisted `updateCount`), so a re-registered query
+   * always emits at least once even when its records are unchanged — otherwise
+   * an empty re-registered window would never notify and stay "loading". */
+  syncNotified?: boolean;
   /** Timer for TTL expiration. */
   ttlTimer: NodeJS.Timeout | null;
   /** TTL duration in milliseconds. */
   ttlDurationMs: number;
   /** Number of times the query has been updated. */
   updateCount: number;
+  /** Timestamp (ms) of the last user-visible update, or null before the first
+   * one. Surfaced to DevTools as `lastUpdate` — must NOT be stamped on read. */
+  lastUpdatedAt: number | null;
   /**
    * Rolling window of the most recent materialization-step latencies (ms).
    * Capped at MATERIALIZATION_SAMPLE_WINDOW; used to recompute p55/p90/p99

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spooky-sync/core",
-  "version": "0.0.1-canary.102",
+  "version": "0.0.1-canary.104",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -59,8 +59,8 @@
     }
   },
   "dependencies": {
-    "@spooky-sync/query-builder": "0.0.1-canary.102",
-    "@spooky-sync/ssp-wasm": "0.0.1-canary.102",
+    "@spooky-sync/query-builder": "0.0.1-canary.104",
+    "@spooky-sync/ssp-wasm": "0.0.1-canary.104",
     "@surrealdb/wasm": "^3.0.3",
     "fast-json-patch": "^3.1.1",
     "loro-crdt": "^1.5.6",

package/src/modules/cache/index.ts

@@ -1,4 +1,5 @@
 import type { LocalDatabaseService } from '../../services/database/index';
+import { StaleEpochError } from '../../services/database/index';
 import type {
   StreamProcessorService,
   StreamUpdate,
@@ -54,6 +55,12 @@ export class CacheModule implements StreamUpdateReceiver {
     return this.versionLookups[recordId] ?? 0;
   }
 
+  /** 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 {
+    this.versionLookups = {};
+  }
+
   /**
    * Save a single record to local DB and ingest into DBSP
    * Used by mutations (create/update)
@@ -70,6 +77,13 @@ export class CacheModule implements StreamUpdateReceiver {
   async saveBatch(records: CacheRecord[], skipDbInsert: boolean = false): Promise<void> {
     if (records.length === 0) return;
 
+    // Fence against bucket switches: this batch's records were derived from
+    // reads against the CURRENT store/user. If a switch lands while we await
+    // the (gated) local write, the write throws StaleEpochError and the whole
+    // batch — including the SSP ingest — is dropped: the new bucket re-syncs
+    // its own data from the server.
+    const epoch = this.local.epoch;
+
     this.logger.debug(
       {
         count: records.length,
@@ -116,9 +130,12 @@ export class CacheModule implements StreamUpdateReceiver {
           {} as Record<string, any>
         );
 
-        await this.local.execute(query, params);
+        await this.local.execute(query, params, { epoch });
       }
 
+      // Late fence for the skipDbInsert path (no gated write above to trip on).
+      if (this.local.epoch !== epoch) throw new StaleEpochError();
+
       // 2. Bulk ingest into DBSP (use populatedRecords which has _00_rv set).
       // ingestMany coalesces the per-record stream updates into a single
       // notification per affected query — the UI then updates once, after the
@@ -135,6 +152,13 @@ export class CacheModule implements StreamUpdateReceiver {
         'Batch saved successfully'
       );
     } catch (err) {
+      if (err instanceof StaleEpochError) {
+        this.logger.debug(
+          { count: records.length, Category: 'sp00ky-client::CacheModule::saveBatch' },
+          'Dropped batch from before a bucket switch'
+        );
+        return;
+      }
       this.logger.error(
         { err, count: records.length, Category: 'sp00ky-client::CacheModule::saveBatch' },
         'Failed to save batch'
@@ -152,11 +176,13 @@ export class CacheModule implements StreamUpdateReceiver {
       'Deleting record'
     );
 
+    const epoch = this.local.epoch;
     try {
       // 1. Delete from local database
       if (!skipDbDelete) {
-        await this.local.query('DELETE $id', { id: parseRecordIdString(id) });
+        await this.local.query('DELETE $id', { id: parseRecordIdString(id) }, { epoch });
       }
+      if (this.local.epoch !== epoch) throw new StaleEpochError();
 
       // 2. Ingest deletion into DBSP (pass record data so predicates can be matched)
       delete this.versionLookups[id];
@@ -167,6 +193,13 @@ export class CacheModule implements StreamUpdateReceiver {
         'Record deleted successfully'
       );
     } catch (err) {
+      if (err instanceof StaleEpochError) {
+        this.logger.debug(
+          { table, id, Category: 'sp00ky-client::CacheModule::delete' },
+          'Dropped delete from before a bucket switch'
+        );
+        return;
+      }
       this.logger.error(
         { err, table, id, Category: 'sp00ky-client::CacheModule::delete' },
         'Failed to delete record'

package/src/modules/crdt/crdt-field.ts

@@ -124,10 +124,17 @@ export class CrdtField {
     });
   }
 
-  stopSync(): void {
+  /**
+   * Stop syncing this field. Flushes one final remote push by default so the
+   * last keystrokes aren't lost. Pass `{ flush: false }` on a bucket switch —
+   * the remote session already belongs to the NEXT user, and pushing this
+   * (previous user's) snapshot under it would clobber the record remotely.
+   */
+  stopSync(options: { flush?: boolean } = {}): void {
+    const flush = options.flush ?? true;
     if (this.unsubscribe) { this.unsubscribe(); this.unsubscribe = null; }
     if (this.pushTimer) { clearTimeout(this.pushTimer); this.pushTimer = null; }
-    if (this.remote && this.recordId) { void this.pushToRemote(); }
+    if (flush && this.remote && this.recordId) { void this.pushToRemote(); }
   }
 
   importRemote(state: Uint8Array): void {

package/src/modules/crdt/index.ts

@@ -147,9 +147,14 @@ export class CrdtManager {
     );
   }
 
-  closeAll(): void {
+  /**
+   * Close every open field + table LIVE. Fields flush a final remote push by
+   * default; pass `{ flush: false }` on a bucket switch, where that flush
+   * would push the previous user's snapshot under the next user's session.
+   */
+  closeAll(options: { flush?: boolean } = {}): void {
     for (const [_, field] of this.fields) {
-      field.stopSync();
+      field.stopSync(options);
     }
     this.fields.clear();
     for (const table of Array.from(this.liveByTable.keys())) {

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

@@ -0,0 +1,147 @@
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import { RecordId } from 'surrealdb';
+import { DataModule } from './index';
+import type { QueryState } from '../../types';
+
+/**
+ * Tests for the local-bucket-switch surface of DataModule:
+ * - `quiesce()` disarms every debounce + TTL timer;
+ * - `rebindAfterBucketSwitch()` keeps query hashes (subscriptions stay
+ *   attached), resets sync state, notifies subscribers with the emptied
+ *   records so the previous user's rows leave the UI, re-registers the SSP
+ *   view, and returns the hashes for remote re-registration;
+ * - stale-epoch stream updates are dropped instead of applied.
+ */
+
+function makeLogger(): any {
+  const noop = () => {};
+  const logger: any = { debug: noop, info: noop, warn: noop, error: noop, trace: noop };
+  logger.child = () => logger;
+  return logger;
+}
+
+function makeQueryState(hash: string, records: Record<string, any>[]): QueryState {
+  return {
+    config: {
+      id: new RecordId('_00_query', hash),
+      surql: 'SELECT * FROM user',
+      params: {},
+      localArray: [['user:a', 1]],
+      remoteArray: [['user:a', 1]],
+      ttl: '10m',
+      lastActiveAt: new Date(),
+      tableName: 'user',
+    },
+    records,
+    hydrated: true,
+    ttlTimer: null,
+    ttlDurationMs: 600_000,
+    updateCount: 3,
+    lastUpdatedAt: null,
+    materializationSamples: [],
+    lastIngestLatencyMs: null,
+    errorCount: 0,
+    status: 'idle',
+    phaseSamples: {},
+    phaseLast: {},
+    registrationTimings: { parseMs: null, planMs: null, snapshotMs: null, wallMs: null },
+  };
+}
+
+function makeHarness(epoch = 0) {
+  const localQueries: Array<{ query: unknown; vars: unknown; opts: unknown }> = [];
+  const local: any = {
+    epoch,
+    query: vi.fn(async (query: unknown, vars?: unknown, opts?: unknown) => {
+      localQueries.push({ query, vars, opts });
+      return [[]];
+    }),
+  };
+  const cache: any = {
+    registerQuery: vi.fn(() => ({ localArray: [] })),
+  };
+  const dm = new DataModule(cache, local, { tables: [] } as any, makeLogger(), 100);
+  return { dm, local, cache, localQueries };
+}
+
+describe('DataModule.quiesce', () => {
+  it('clears debounce and TTL timers', () => {
+    vi.useFakeTimers();
+    try {
+      const { dm } = makeHarness();
+      const qs = makeQueryState('h1', []);
+      qs.ttlTimer = setTimeout(() => {}, 60_000);
+      (dm as any).activeQueries.set('h1', qs);
+      (dm as any).debounceTimers.set('h1', setTimeout(() => {}, 60_000));
+
+      dm.quiesce();
+
+      expect(qs.ttlTimer).toBeNull();
+      expect((dm as any).debounceTimers.size).toBe(0);
+      expect(vi.getTimerCount()).toBe(0);
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+});
+
+describe('DataModule.rebindAfterBucketSwitch', () => {
+  let harness: ReturnType<typeof makeHarness>;
+
+  beforeEach(() => {
+    harness = makeHarness();
+    (harness.dm as any).activeQueries.set(
+      'h1',
+      makeQueryState('h1', [{ id: 'user:a', name: 'Previous User Row' }])
+    );
+  });
+
+  it('keeps the hash, resets sync state, and notifies subscribers with empty records', async () => {
+    const { dm, cache } = harness;
+    const emissions: unknown[][] = [];
+    dm.subscribe('h1', (records) => emissions.push(records as unknown[]));
+
+    const hashes = await dm.rebindAfterBucketSwitch();
+
+    expect(hashes).toEqual(['h1']);
+    const qs = (dm as any).activeQueries.get('h1') as QueryState;
+    expect(qs.records).toEqual([]);
+    expect(qs.config.localArray).toEqual([]);
+    expect(qs.config.remoteArray).toEqual([]);
+    expect(qs.hydrated).toBe(false);
+    expect(qs.status).toBe('fetching');
+    // Subscribers saw the previous user's rows drop out.
+    expect(emissions).toEqual([[]]);
+    // The SSP view was re-registered (on the fresh, post-reset processor).
+    expect(cache.registerQuery).toHaveBeenCalledWith(
+      expect.objectContaining({ queryHash: 'h1', surql: 'SELECT * FROM user' })
+    );
+    // The TTL heartbeat is re-armed.
+    expect(qs.ttlTimer).not.toBeNull();
+    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();
+    const qs = makeQueryState('h1', [{ id: 'user:a' }]);
+    (dm as any).activeQueries.set('h1', qs);
+
+    // The materialize read happens, then the epoch moves (bucket switched).
+    local.query.mockImplementation(async () => {
+      local.epoch = 1;
+      return [[{ id: 'user:b', name: 'other user row' }]];
+    });
+
+    await (dm as any).processStreamUpdate({
+      queryHash: 'h1',
+      localArray: [['user:b', 1]],
+      op: 'CREATE',
+    });
+
+    // Neither the records nor the persisted arrays moved.
+    expect(qs.records).toEqual([{ id: 'user:a' }]);
+    expect(qs.config.localArray).toEqual([['user:a', 1]]);
+  });
+});

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

@@ -1,4 +1,4 @@
-import { describe, it, expect, beforeEach } from 'vitest';
+import { describe, it, expect, beforeEach, vi, afterEach } from 'vitest';
 import { RecordId } from 'surrealdb';
 import { DataModule } from './index';
 import type { QueryState, QueryStatus } from '../../types';
@@ -6,7 +6,9 @@ import type { QueryState, QueryStatus } from '../../types';
 /**
  * Tests for the per-query fetch status (idle/fetching) added to DataModule:
  * setQueryStatus updates the query object and notifies both the DevTools
- * observer hook and subscribeStatus listeners.
+ * observer hook and subscribeStatus listeners; beginFetching/endFetching
+ * refcount overlapping fetch cycles; flushPendingStreamUpdate lands the
+ * debounced result before a query flips back to idle.
  */
 
 function makeLogger(): any {
@@ -42,10 +44,14 @@ function makeQueryState(hash: string): QueryState {
     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 },
   };
 }
 
@@ -106,3 +112,138 @@ describe('DataModule query fetch status', () => {
     expect(seen).toEqual(['fetching']);
   });
 });
+
+describe('DataModule beginFetching/endFetching refcount', () => {
+  let dm: DataModule<any>;
+  const hash = 'h1';
+  let seen: QueryStatus[];
+
+  beforeEach(() => {
+    dm = makeDataModule();
+    (dm as any).activeQueries.set(hash, makeQueryState(hash));
+    seen = [];
+    dm.subscribeStatus(hash, (s) => seen.push(s));
+  });
+
+  it('emits fetching on 0→1 and idle only on the last exit', () => {
+    dm.beginFetching(hash); // registration
+    dm.beginFetching(hash); // overlapping poll round
+    expect(seen).toEqual(['fetching']);
+
+    dm.endFetching(hash); // inner cycle finishes — must NOT emit idle
+    expect(seen).toEqual(['fetching']);
+    expect((dm as any).activeQueries.get(hash).status).toBe('fetching');
+
+    dm.endFetching(hash);
+    expect(seen).toEqual(['fetching', 'idle']);
+  });
+
+  it('unbalanced endFetching settles to idle without going negative', () => {
+    dm.endFetching(hash); // already idle → no-op notification
+    expect(seen).toEqual([]);
+    dm.beginFetching(hash);
+    dm.endFetching(hash);
+    expect(seen).toEqual(['fetching', 'idle']);
+    expect((dm as any).fetchDepth.has(hash)).toBe(false);
+  });
+});
+
+describe('DataModule pending stream-update flush', () => {
+  let dm: DataModule<any>;
+  const hash = 'h1';
+  let processed: any[];
+
+  const makeUpdate = (op: 'CREATE' | 'UPDATE' | 'DELETE') =>
+    ({ queryHash: hash, op, localArray: [] }) as any;
+
+  beforeEach(() => {
+    vi.useFakeTimers();
+    dm = makeDataModule();
+    (dm as any).activeQueries.set(hash, makeQueryState(hash));
+    processed = [];
+    (dm as any).processStreamUpdate = async (u: any) => {
+      processed.push(u);
+    };
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it('flushPendingStreamUpdate processes the debounced update exactly once', async () => {
+    const update = makeUpdate('CREATE');
+    await dm.onStreamUpdate(update);
+    expect(processed).toEqual([]); // still debounced
+
+    await dm.flushPendingStreamUpdate(hash);
+    expect(processed).toEqual([update]);
+    expect((dm as any).debounceTimers.has(hash)).toBe(false);
+    expect((dm as any).pendingStreamUpdates.has(hash)).toBe(false);
+
+    // The cancelled timer must not process it a second time.
+    await vi.runAllTimersAsync();
+    expect(processed).toEqual([update]);
+
+    // Nothing pending → flush is a no-op.
+    await dm.flushPendingStreamUpdate(hash);
+    expect(processed).toEqual([update]);
+  });
+
+  it('the trailing-edge timer clears the pending entry itself', async () => {
+    const update = makeUpdate('UPDATE');
+    await dm.onStreamUpdate(update);
+    await vi.runAllTimersAsync();
+    expect(processed).toEqual([update]);
+    expect((dm as any).pendingStreamUpdates.has(hash)).toBe(false);
+  });
+
+  it('a DELETE supersedes and drops the pending coalesced update', async () => {
+    const create = makeUpdate('CREATE');
+    const del = makeUpdate('DELETE');
+    await dm.onStreamUpdate(create);
+    await dm.onStreamUpdate(del); // immediate, drops the pending CREATE
+    expect(processed).toEqual([del]);
+    expect((dm as any).pendingStreamUpdates.has(hash)).toBe(false);
+    await vi.runAllTimersAsync();
+    expect(processed).toEqual([del]);
+  });
+
+  it('finalizeDeregister clears pending update and fetch depth', async () => {
+    (dm as any).cache = { unregisterQuery: () => {} };
+    await dm.onStreamUpdate(makeUpdate('CREATE'));
+    dm.beginFetching(hash);
+    dm.finalizeDeregister(hash);
+    expect((dm as any).pendingStreamUpdates.has(hash)).toBe(false);
+    expect((dm as any).debounceTimers.has(hash)).toBe(false);
+    expect((dm as any).fetchDepth.has(hash)).toBe(false);
+    await vi.runAllTimersAsync();
+    expect(processed).toEqual([]);
+  });
+});
+
+describe('DataModule notifyQuerySynced', () => {
+  const hash = 'h1';
+
+  function makeDmWithLocal(rows: any[]): DataModule<any> {
+    const local: any = { query: async () => [rows] };
+    return new DataModule({} as any, local, { tables: [] } as any, makeLogger(), 100);
+  }
+
+  it('notifies once per registration lifetime even when records are unchanged and updateCount > 0', async () => {
+    const dm = makeDmWithLocal([]);
+    const state = makeQueryState(hash);
+    state.updateCount = 7; // persisted from a previous registration
+    (dm as any).activeQueries.set(hash, state);
+
+    let notified = 0;
+    dm.subscribe(hash, () => {
+      notified++;
+    });
+
+    await dm.notifyQuerySynced(hash); // empty result, unchanged — must still emit
+    expect(notified).toBe(1);
+
+    await dm.notifyQuerySynced(hash); // already notified this lifetime → silent
+    expect(notified).toBe(1);
+  });
+});