@spooky-sync/core 0.0.1-canary.13 → 0.0.1-canary.130

package/src/modules/crdt/index.ts

@@ -0,0 +1,357 @@
+import type { SchemaStructure } from '@spooky-sync/query-builder';
+import type { LocalStore, RemoteDatabaseService } from '../../services/database/index';
+import type { Logger } from '../../services/logger/index';
+import type { Uuid } from 'surrealdb';
+import { CrdtField } from './crdt-field';
+import { parseRecordIdString } from '../../utils/index';
+
+export { CrdtField, cursorColorFromName, CURSOR_COLORS } from './crdt-field';
+
+/**
+ * CrdtManager manages active CrdtField instances and their sync channels.
+ *
+ * Collaborative state lives in two dedicated tables (defined in
+ * `apps/cli/src/meta_tables_remote.surql`):
+ *   - `_00_crdt`   { record_id, field, state } — one row per (record, field)
+ *   - `_00_cursor` { record_id, session_id, field, state } — one row per
+ *                    (record, session, field)
+ *
+ * Splitting them off the parent row is what makes offline edits mergeable:
+ * each (record, field) gets its own row, so concurrent offline writes don't
+ * collide on the parent's last-write-wins semantics.
+ *
+ * Cross-browser delivery still rides the parent table's existing LIVE feed
+ * to avoid SurrealDB v3 LIVE bugs around dereference-based permission rules
+ * (issues 3602, 4026). On every meta UPSERT the writer also bumps the
+ * parent's `_00_rv` (a no-op assignment); that fires the parent's LIVE
+ * feed, and the receiver pulls the matching `_00_crdt` / `_00_cursor` rows
+ * via subquery. Permission inheritance happens server-side via
+ * `record_id.id != NONE` (SELECT) and `fn::can_update_record` (UPDATE).
+ */
+export class CrdtManager {
+  private fields = new Map<string, CrdtField>();
+  // One LIVE subscription per parent table (e.g. "thread" → uuid).
+  private liveByTable = new Map<string, Uuid>();
+  // Coalesces concurrent first-time subscribes for the same table.
+  private pendingLive = new Map<string, Promise<void>>();
+  private logger: Logger;
+  // SurrealDB session id, used as the per-session key inside `_00_cursor`.
+  private sessionId: string = '';
+
+  constructor(
+    private schema: SchemaStructure,
+    private local: LocalStore,
+    private remote: RemoteDatabaseService,
+    logger: Logger,
+    private debounceMs: number = 500,
+  ) {
+    this.logger = logger.child({ service: 'CrdtManager' });
+  }
+
+  /** Set the session id that scopes this client's cursor entries. Must be
+   *  called before `open()` for cursors to be pushed under a stable key.
+   *  Passed in from `sp00ky.ts` at boot (it already fetches `session::id()`
+   *  for the data-module salt). */
+  setSessionId(sessionId: string): void {
+    this.sessionId = sessionId;
+  }
+
+  /**
+   * Open a CRDT field for collaborative editing.
+   *
+   * @param table - Table name
+   * @param recordId - Full record ID (e.g., "thread:abc")
+   * @param field - Field name (e.g., "title", "content")
+   * @param fallbackText - Current plain text from the record, used to seed the
+   *                       LoroDoc if no CRDT state exists yet (migration path)
+   */
+  async open(
+    table: string,
+    recordId: string,
+    field: string,
+    fallbackText?: string,
+  ): Promise<CrdtField> {
+    this.assertCrdtField(table, field);
+    const cursorsEnabled = this.fieldHasCursor(table, field);
+    const key = this.makeKey(table, recordId, field);
+    let crdtField = this.fields.get(key);
+
+    if (crdtField) {
+      return crdtField;
+    }
+
+    // Read the snapshot directly off the parent row. `@crdt`-only fields
+    // hold the base64 snapshot inline; `@crdt @cursor` fields hold a
+    // `{ state, cursors }` object so we drill into `.state`. The query
+    // always selects the local row — sync-down already populated it
+    // (the snapshot is a column on the parent, not a sidecar table) so
+    // there is no separate fetch on the happy path.
+    let initialCrdtState: Uint8Array | undefined;
+    try {
+      const [result] = await this.local.query<[unknown]>(
+        `SELECT VALUE ${field} FROM ONLY $id`,
+        { id: parseRecordIdString(recordId) },
+      );
+      const snapshot = this.extractSnapshot(result, cursorsEnabled);
+      if (snapshot) initialCrdtState = snapshot;
+    } catch (e) {
+      this.logger.info(
+        { error: String(e), recordId, field, Category: 'sp00ky-client::CrdtManager::open' },
+        'No existing CRDT state found in local cache (continuing with empty doc)'
+      );
+    }
+
+    crdtField = new CrdtField(field, cursorsEnabled, initialCrdtState, this.logger);
+    crdtField.startSync(this.local, this.remote, recordId, this.sessionId, this.debounceMs);
+    this.fields.set(key, crdtField);
+
+    this.logger.info(
+      { key, hasInitialState: !!initialCrdtState, hasFallback: !!fallbackText, Category: 'sp00ky-client::CrdtManager::open' },
+      'CrdtField opened'
+    );
+
+    // Fire-and-forget: the LIVE subscription receives *future* updates;
+    // the initial snapshot is already in hand. `ensureTableSubscription`
+    // coalesces concurrent calls via `pendingLive`, so this is safe.
+    void this.ensureTableSubscription(table);
+
+    // Local was empty — a fresh device, a memory-backed local DB after
+    // reload, or a record that hasn't been sync'd locally yet. Pull the
+    // parent row from remote and dispatch its CRDT field; otherwise the
+    // editor sits empty until the parent's LIVE feed happens to fire.
+    if (!initialCrdtState) {
+      void this.fetchAndDispatchRow(table, recordId);
+    }
+
+    return crdtField;
+  }
+
+  close(table: string, recordId: string, field: string): void {
+    const key = this.makeKey(table, recordId, field);
+    const crdtField = this.fields.get(key);
+    if (crdtField) {
+      crdtField.stopSync();
+      this.fields.delete(key);
+    }
+
+    // If no fields on this table remain open, tear down the table-wide LIVE.
+    const tablePrefix = `${table}:`;
+    const stillOpen = Array.from(this.fields.keys()).some((k) => k.startsWith(tablePrefix));
+    if (!stillOpen) {
+      this.killTableSubscription(table);
+    }
+
+    this.logger.debug(
+      { key, Category: 'sp00ky-client::CrdtManager::close' },
+      'CrdtField closed'
+    );
+  }
+
+  /**
+   * 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(options);
+    }
+    this.fields.clear();
+    for (const table of Array.from(this.liveByTable.keys())) {
+      this.killTableSubscription(table);
+    }
+  }
+
+  /** Ensure a single `LIVE SELECT * FROM <table>` is running, shared across
+   *  every open CrdtField on `table`. */
+  private async ensureTableSubscription(table: string): Promise<void> {
+    if (this.liveByTable.has(table)) return;
+
+    const pending = this.pendingLive.get(table);
+    if (pending) return pending;
+
+    const start = (async () => {
+      try {
+        const [uuid] = await this.remote.query<[Uuid]>(
+          `LIVE SELECT * FROM ${table}`,
+        );
+
+        const subscription = await this.remote.getClient().liveOf(uuid);
+        subscription.subscribe((message) => {
+          if (message.action === 'KILLED') return;
+          if (message.action !== 'CREATE' && message.action !== 'UPDATE') return;
+          this.dispatchRow(table, message.value as Record<string, unknown>);
+        });
+
+        this.liveByTable.set(table, uuid);
+        this.logger.info(
+          { table, Category: 'sp00ky-client::CrdtManager::ensureTableSubscription' },
+          'LIVE SELECT started'
+        );
+      } catch (e) {
+        this.logger.warn(
+          { error: e, table, Category: 'sp00ky-client::CrdtManager::ensureTableSubscription' },
+          'Failed to start LIVE SELECT'
+        );
+      }
+    })();
+
+    this.pendingLive.set(table, start);
+    try {
+      await start;
+    } finally {
+      this.pendingLive.delete(table);
+    }
+  }
+
+  /** Apply a parent-row payload from a non-LIVE source (e.g. the
+   *  list_ref-driven sync engine, when the cross-user LIVE on the
+   *  parent table is filtered out by the SurrealDB cross-session
+   *  permission gap). Same semantics as the internal `dispatchRow`. */
+  applyRow(table: string, row: Record<string, unknown>): void {
+    this.dispatchRow(table, row);
+  }
+
+  /** Dispatch a parent-row LIVE event to every open CrdtField on that
+   *  record. Each open field reads its slice of the row directly — the
+   *  CRDT snapshot is a column on the parent now, so there is no
+   *  follow-up subquery. */
+  private dispatchRow(table: string, row: Record<string, unknown>): void {
+    const id = row.id != null ? String(row.id) : '';
+    if (!id) return;
+
+    const rowKeyPrefix = `${table}:${id}:`;
+    for (const [key, crdtField] of this.fields) {
+      if (!key.startsWith(rowKeyPrefix)) continue;
+      const fieldName = key.slice(rowKeyPrefix.length);
+      const cursorsEnabled = this.fieldHasCursor(table, fieldName);
+      const slice = row[fieldName];
+      const snapshot = this.extractSnapshot(slice, cursorsEnabled);
+      if (snapshot) crdtField.importRemote(snapshot);
+
+      if (cursorsEnabled && slice && typeof slice === 'object') {
+        const cursors = (slice as { cursors?: unknown }).cursors;
+        if (cursors && typeof cursors === 'object') {
+          for (const [sid, blob] of Object.entries(cursors as Record<string, unknown>)) {
+            if (sid === this.sessionId) continue;
+            if (typeof blob === 'string' && blob.length > 0) {
+              crdtField.importRemoteCursor(blob);
+            }
+          }
+        }
+      }
+    }
+  }
+
+  /** One-shot remote fetch for a row whose CRDT field hasn't synced
+   *  locally yet (fresh device, memory-backed local DB after reload, …).
+   *  Used by `open()` when the local read came up empty. Subsequent
+   *  cross-browser updates ride `dispatchRow` via the parent LIVE feed. */
+  private async fetchAndDispatchRow(table: string, id: string): Promise<void> {
+    try {
+      const recordId = parseRecordIdString(id);
+      const [row] = await this.remote.query<[Record<string, unknown> | null]>(
+        `SELECT * FROM ONLY $id`,
+        { id: recordId },
+      );
+      if (!row || typeof row !== 'object') return;
+      this.dispatchRow(table, row as Record<string, unknown>);
+    } catch (e) {
+      this.logger.warn(
+        { error: e, table, id, Category: 'sp00ky-client::CrdtManager::fetchAndDispatchRow' },
+        'Failed to fetch parent row for CRDT hydration'
+      );
+    }
+  }
+
+  /** Schema lookup: does `<table>.<field>` carry a `@cursor` annotation?
+   *  Determines the on-disk shape (plain snapshot vs. `{ state, cursors }`). */
+  private fieldHasCursor(table: string, field: string): boolean {
+    const tableSchema = this.schema.tables.find((t) => t.name === table);
+    return !!tableSchema?.columns[field]?.cursor;
+  }
+
+  /** Pull the LoroDoc snapshot bytes out of a row slice. For `@crdt`-only
+   *  the slice IS the snapshot (Uint8Array); for `@crdt @cursor` it's
+   *  `{ state, cursors }` where `state` carries the snapshot bytes. */
+  private extractSnapshot(value: unknown, cursorsEnabled: boolean): Uint8Array | undefined {
+    const asBytes = (v: unknown): Uint8Array | undefined => {
+      if (v instanceof Uint8Array) return v.length > 0 ? v : undefined;
+      // SurrealDB ferries bytes through several shapes depending on
+      // transport and on whether the field is a top-level `bytes` column
+      // or bytes nested inside a FLEXIBLE object. Round-tripping bytes
+      // through `option<object> FLEXIBLE` (the `@crdt @cursor` shape) in
+      // particular comes back as a plain `number[]` from the local WASM
+      // DB and as `Uint8Array` from the remote WS engine. Normalize all
+      // recognized variants here so the receiving CrdtField doesn't care.
+      if (v instanceof ArrayBuffer) return new Uint8Array(v);
+      if (ArrayBuffer.isView(v)) {
+        const view = v as ArrayBufferView;
+        return new Uint8Array(view.buffer, view.byteOffset, view.byteLength);
+      }
+      if (Array.isArray(v) && v.length > 0 && v.every((n) => typeof n === 'number')) {
+        return Uint8Array.from(v as number[]);
+      }
+      return undefined;
+    };
+
+    if (cursorsEnabled) {
+      if (value && typeof value === 'object' && !(value instanceof Uint8Array)) {
+        return asBytes((value as { state?: unknown }).state);
+      }
+      return undefined;
+    }
+    return asBytes(value);
+  }
+
+  private killTableSubscription(table: string): void {
+    const uuid = this.liveByTable.get(table);
+    if (uuid) {
+      // We're tearing down: KILL on an already-dead/closed LIVE throws, and the
+      // subscription may have ended on its own, so the failure is expected and
+      // safe to drop.
+      this.remote.query('KILL $uuid', { uuid }).catch((err) => {
+        this.logger.debug(
+          { err, table, Category: 'sp00ky-client::CrdtManager::killTableSubscription' },
+          'KILL of table LIVE failed (already closed?)'
+        );
+      });
+      this.liveByTable.delete(table);
+    }
+  }
+
+  private makeKey(table: string, recordId: string, field: string): string {
+    return `${table}:${recordId}:${field}`;
+  }
+
+  /**
+   * Throws if `<table>.<field>` is not annotated `@crdt` in the schema. Catches
+   * typos, removed annotations, and stale schema codegen at the call site instead
+   * of silently producing a non-CRDT writer.
+   */
+  private assertCrdtField(table: string, field: string): void {
+    if (!/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(field)) {
+      throw new Error(
+        `openCrdtField: refusing unsafe field identifier '${field}' — must match [a-zA-Z_][a-zA-Z0-9_]*`
+      );
+    }
+    const tableSchema = this.schema.tables.find((t) => t.name === table);
+    if (!tableSchema) {
+      throw new Error(
+        `openCrdtField: unknown table '${table}'. Available: ${this.schema.tables.map((t) => t.name).join(', ')}`
+      );
+    }
+    const column = tableSchema.columns[field];
+    if (!column) {
+      throw new Error(
+        `openCrdtField: '${table}.${field}' is not in the schema. Available fields: ${Object.keys(tableSchema.columns).join(', ')}`
+      );
+    }
+    if (!column.crdt) {
+      throw new Error(
+        `openCrdtField: '${table}.${field}' is not annotated '@crdt' in the schema. ` +
+          `Add '-- @crdt text' above the field's DEFINE FIELD and regenerate the client schema.`
+      );
+    }
+  }
+}

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

@@ -0,0 +1,150 @@
+import { describe, it, expect } from 'vitest';
+import { RecordId } from 'surrealdb';
+import { DataModule } from './index';
+import type { QueryState } from '../../types';
+
+/**
+ * Tests for instant-hydrate's DataModule half: `applyHydration` (run-once,
+ * remoteArray priming, subscriber notify, and the epoch guard added when the
+ * hydrate fetch moved off the paint path into a background chain) and
+ * `isPreloadFresh` (the marker check that lets a freshly-preloaded query skip
+ * the duplicate one-shot fetch entirely).
+ */
+
+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): QueryState {
+  return {
+    config: {
+      id: new RecordId('_00_query', hash),
+      surql: 'SELECT * FROM user',
+      params: {},
+      localArray: [],
+      remoteArray: [],
+      ttl: '10m',
+      lastActiveAt: new Date(),
+      tableName: 'user',
+    },
+    records: [],
+    ttlTimer: null,
+    ttlDurationMs: 0,
+    updateCount: 0,
+    lastUpdatedAt: null,
+    materializationSamples: [],
+    lastIngestLatencyMs: null,
+    errorCount: 0,
+    status: 'fetching',
+    phaseSamples: {},
+    phaseLast: {},
+    registrationTimings: { parseMs: null, planMs: null, snapshotMs: null, wallMs: null },
+  };
+}
+
+const schema = { tables: [{ name: 'user', columns: {} }] } as any;
+
+function makeRow(id: string, rv = 1) {
+  return { id: new RecordId('user', id), name: id, _00_rv: rv };
+}
+
+describe('DataModule.applyHydration', () => {
+  const hash = 'h1';
+
+  function setup({ epochFlipsOnSave = false } = {}) {
+    let epoch = 1;
+    const saved: any[] = [];
+    const cache: any = {
+      saveBatch: async (batch: any[]) => {
+        saved.push(...batch);
+        if (epochFlipsOnSave) epoch = 2;
+      },
+    };
+    const local: any = {
+      get epoch() {
+        return epoch;
+      },
+      query: async () => [[makeRow('a')]],
+    };
+    const dm = new DataModule(cache, local, schema, makeLogger(), 100);
+    const state = makeQueryState(hash);
+    (dm as any).activeQueries.set(hash, state);
+    return { dm, state, saved };
+  }
+
+  it('primes remoteArray, materializes and notifies subscribers', async () => {
+    const { dm, state, saved } = setup();
+    const emissions: any[] = [];
+    dm.subscribe(hash, (records) => emissions.push(records));
+
+    await dm.applyHydration(hash, [makeRow('a', 3)]);
+
+    expect(state.hydrated).toBe(true);
+    expect(state.config.remoteArray).toEqual([['user:a', 3]]);
+    expect(saved.length).toBe(1);
+    expect(emissions.length).toBe(1);
+    expect(dm.isCold(hash)).toBe(false);
+  });
+
+  it('runs once even when the remote returns nothing (hydrated flag)', async () => {
+    const { dm, state, saved } = setup();
+    await dm.applyHydration(hash, []);
+    expect(state.hydrated).toBe(true);
+    expect(saved).toEqual([]);
+    expect(dm.isCold(hash)).toBe(false); // hydrated → no longer cold
+  });
+
+  it('is a no-op for an unknown query', async () => {
+    const { dm, saved } = setup();
+    await dm.applyHydration('nope', [makeRow('a')]);
+    expect(saved).toEqual([]);
+  });
+
+  it('bails before mutating state when the bucket epoch moves mid-persist', async () => {
+    const { dm, state } = setup({ epochFlipsOnSave: true });
+    const emissions: any[] = [];
+    dm.subscribe(hash, (records) => emissions.push(records));
+
+    await dm.applyHydration(hash, [makeRow('a', 3)]);
+
+    // Rows fetched under the previous auth context must not prime the new
+    // bucket's query state — the rebind's re-registration refills it.
+    expect(state.config.remoteArray).toEqual([]);
+    expect(state.records).toEqual([]);
+    expect(emissions).toEqual([]);
+  });
+});
+
+describe('DataModule.isPreloadFresh', () => {
+  const maxAgeMs = 60_000;
+
+  function makeDm(getById: (table: string, id: string) => Promise<any>) {
+    const local: any = { getById };
+    return new DataModule({} as any, local, schema, makeLogger(), 100);
+  }
+
+  it('true for a marker younger than maxAgeMs', async () => {
+    const dm = makeDm(async () => ({ fetchedAt: Date.now() - 1_000, rowCount: 5 }));
+    expect(await dm.isPreloadFresh('123', maxAgeMs)).toBe(true);
+  });
+
+  it('false for a marker older than maxAgeMs', async () => {
+    const dm = makeDm(async () => ({ fetchedAt: Date.now() - maxAgeMs - 1, rowCount: 5 }));
+    expect(await dm.isPreloadFresh('123', maxAgeMs)).toBe(false);
+  });
+
+  it('false when no marker exists', async () => {
+    const dm = makeDm(async () => null);
+    expect(await dm.isPreloadFresh('123', maxAgeMs)).toBe(false);
+  });
+
+  it('false when the marker read throws (treated as cold)', async () => {
+    const dm = makeDm(async () => {
+      throw new Error('boom');
+    });
+    expect(await dm.isPreloadFresh('123', maxAgeMs)).toBe(false);
+  });
+});

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]]);
+  });
+});