@spooky-sync/core 0.0.1-canary.153 → 0.0.1-canary.155

package/src/modules/sync/sync.ts

@@ -22,6 +22,9 @@ import type { CacheModule } from '../cache/index';
 import type { DataModule } from '../data/index';
 import { classifySyncError, encodeRecordId, extractIdPart, extractTablePart, surql } from '../../utils/index';
 import { ANON_USER_ID, DEFAULT_REF_MODE, listRefTableFor, RefMode } from '../ref-tables';
+import { mutationOwnerTabId } from '../data/mutation-id';
+import type { LeaderSyncHub, SyncForwarder } from '../../services/tabs/coordinator';
+import { parseRecordIdString } from '../../utils/index';
 
 /**
  * Tunables for `Sp00kySync` construction.
@@ -75,6 +78,15 @@ export class Sp00kySync<S extends SchemaStructure> {
   // subscription in `Sp00kyClient`; null when unauthenticated.
   private currentUserId: string | null = null;
 
+  // ---- shared-tabs role state ----
+  // Followers keep their own remote WS (registration, per-query sync, poll)
+  // but must never drain the shared outbox or hold a second list_ref LIVE.
+  // The leader relays its LIVE events and routes rollbacks by mutation owner.
+  private tabRole: 'solo' | 'leader' | 'follower' = 'solo';
+  private tabId: string | null = null;
+  private hub: LeaderSyncHub | null = null;
+  private forwarder: SyncForwarder | null = null;
+
   private refMode: RefMode = DEFAULT_REF_MODE;
 
   // When true, an unauthenticated client still runs the `_00_list_ref` poll
@@ -366,7 +378,7 @@ export class Sp00kySync<S extends SchemaStructure> {
   public async init() {
     if (this.isInit) throw new Error('Sp00kySync is already initialized');
     this.isInit = true;
-    await this.scheduler.init();
+    await this.scheduler.init({ loadOutbox: this.tabRole !== 'follower' });
     this.subscribeToReconnect();
     void this.scheduler.syncUp();
     void this.scheduler.syncDown();
@@ -393,6 +405,116 @@ export class Sp00kySync<S extends SchemaStructure> {
     }
   }
 
+  // ---- shared-tabs roles ------------------------------------------------------
+
+  /** Set BEFORE init(): shapes what init boots (a follower loads no outbox and
+   *  never starts LIVE; its own registration/poll paths stay untouched). */
+  public setTabContext(role: 'solo' | 'leader' | 'follower', tabId: string | null): void {
+    this.tabRole = role;
+    this.tabId = tabId;
+  }
+
+  /** Leader duties: drain the shared outbox, own the single list_ref LIVE,
+   *  relay LIVE events and rollbacks to followers via `hub`. Idempotent for a
+   *  boot-time leader; a runtime promotion (failover) reloads the outbox,
+   *  which now holds EVERY tab's rows, and restarts LIVE under this session. */
+  public async promoteToLeader(hub: LeaderSyncHub): Promise<void> {
+    this.tabRole = 'leader';
+    this.hub = hub;
+    this.forwarder = null;
+    hub.onFollowerMessage = (tabId, msg) => {
+      void tabId;
+      switch (msg.type) {
+        case 'sync-hello':
+          break;
+        case 'mutation-enqueued':
+          void this.enqueueForwardedMutation(msg.mutationId);
+          break;
+        case 'request-poll':
+          this.listRefIdleStreak = 0;
+          break;
+      }
+    };
+    if (this.isInit) {
+      await this.upQueue.loadFromDatabase();
+      void this.scheduler.syncUp();
+      if (this.currentUserId || this.anonLiveEnabled) {
+        this.startListRefPoll();
+        await this.restartRefLiveQuery().catch((err) => {
+          this.logger.warn(
+            { err, Category: 'sp00ky-client::Sp00kySync::promoteToLeader' },
+            'LIVE restart failed on promotion; poll fallback covers it'
+          );
+        });
+      }
+    }
+  }
+
+  /** Follower duties: no outbox drain, no LIVE. Mutations forward to the
+   *  leader; everything else (registration, per-query sync, poll) runs
+   *  against this tab's own remote session as usual. */
+  public demoteToFollower(forwarder: SyncForwarder): void {
+    this.tabRole = 'follower';
+    this.hub = null;
+    this.forwarder = forwarder;
+    void this.killRefLiveQuery();
+    forwarder.onLeaderMessage = (msg) => {
+      switch (msg.type) {
+        case 'list-ref-change':
+          void this.applyRelayedListRefChange(msg).catch((err) => {
+            this.logger.error(
+              { err, Category: 'sp00ky-client::Sp00kySync::relay' },
+              'Relayed list_ref change failed'
+            );
+          });
+          break;
+        case 'mutation-rolled-back':
+          this.events.emit(SyncEventTypes.MutationRolledBack, {
+            eventType: msg.eventType,
+            recordId: msg.recordId,
+            error: msg.error,
+          });
+          break;
+        default:
+          // db-ready and ingest-relay are handled by the engine/cache wiring
+          // in Sp00kyClient before messages reach this handler.
+          break;
+      }
+    };
+  }
+
+  /** A forwarded outbox row from a follower: load + drain it. Idempotent. */
+  public async enqueueForwardedMutation(mutationId: string): Promise<void> {
+    if (this.tabRole !== 'leader') return;
+    await this.upQueue.enqueueFromDatabase(mutationId);
+  }
+
+  /** A relayed `_00_list_ref` LIVE event: resolve against THIS tab's queries
+   *  and run the exact same handling the LIVE subscription would have. */
+  private async applyRelayedListRefChange(msg: {
+    action: 'CREATE' | 'UPDATE' | 'DELETE';
+    queryId: string;
+    recordId: string;
+    version: number;
+    parent: boolean;
+  }): Promise<void> {
+    const queryId = parseRecordIdString(msg.queryId);
+    // Foreign query (another tab's session-salted hash): not ours, ignore.
+    if (!this.dataModule.getQueryById(queryId)) return;
+    const recordId = parseRecordIdString(msg.recordId);
+    if (msg.parent) {
+      await this.handleRemoteSubqueryChange(msg.action, queryId, recordId, msg.version);
+    } else {
+      await this.handleRemoteListRefChange(msg.action, queryId, recordId, msg.version);
+    }
+  }
+
+  /** One immediate poll cycle (failover convergence). */
+  public async forcePollRound(): Promise<void> {
+    this.listRefIdleStreak = 0;
+    await this.pollListRefForActiveQueries().catch(() => false);
+  }
+
   /**
    * Quiesce all sync activity ahead of a local-bucket switch. After this
    * resolves, nothing in the sync module writes to the local store: the poll
@@ -772,6 +894,9 @@ export class Sp00kySync<S extends SchemaStructure> {
   }
 
   private async startRefLiveQueries() {
+    // Shared-tabs follower: exactly one LIVE per user exists, on the leader;
+    // its events reach this tab through the relay.
+    if (this.tabRole === 'follower') return;
     const tableName = this.listRefTable();
     this.logger.debug(
       { tableName, Category: 'sp00ky-client::Sp00kySync::startRefLiveQueries' },
@@ -837,6 +962,20 @@ export class Sp00kySync<S extends SchemaStructure> {
     this.lastLiveEventAt = Date.now();
     this.listRefIdleStreak = 0;
 
+    // Shared-tabs leader: the list_ref table is USER-scoped, so this LIVE also
+    // carries events for FOLLOWER tabs' queries (their own session-salted
+    // hashes). Relay every primary event; each follower resolves the queryId
+    // against its own DataModule and ignores foreign ones. Then continue with
+    // this tab's own handling below.
+    this.hub?.broadcast({
+      type: 'list-ref-change',
+      action,
+      queryId: encodeRecordId(queryId),
+      recordId: encodeRecordId(recordId),
+      version,
+      parent: false,
+    });
+
     // NOTE: DELETE is handled like CREATE/UPDATE below. When another window (or
     // this one) deletes a record, the server's SSP removes it from `_00_list_ref`
     // and the LIVE subscription delivers a DELETE here — `createDiffFromDbOp`
@@ -846,13 +985,17 @@ export class Sp00kySync<S extends SchemaStructure> {
     const existing = this.dataModule.getQueryById(queryId);
 
     if (!existing) {
-      this.logger.warn(
-        {
-          queryId: queryId.toString(),
-          Category: 'sp00ky-client::Sp00kySync::handleRemoteListRefChange',
-        },
-        'Received remote update for unknown local query'
-      );
+      // With a hub attached, an unknown query is the NORMAL case (it belongs
+      // to a follower tab); without one it still warrants the warning.
+      if (!this.hub) {
+        this.logger.warn(
+          {
+            queryId: queryId.toString(),
+            Category: 'sp00ky-client::Sp00kySync::handleRemoteListRefChange',
+          },
+          'Received remote update for unknown local query'
+        );
+      }
       return;
     }
 
@@ -899,6 +1042,16 @@ export class Sp00kySync<S extends SchemaStructure> {
 
     if (action === 'DELETE') return;
 
+    // Relay child-edge events too (see handleRemoteListRefChange).
+    this.hub?.broadcast({
+      type: 'list-ref-change',
+      action,
+      queryId: encodeRecordId(queryId),
+      recordId: encodeRecordId(childId),
+      version,
+      parent: true,
+    });
+
     const existing = this.dataModule.getQueryById(queryId);
     if (!existing) return;
 
@@ -1013,6 +1166,21 @@ export class Sp00kySync<S extends SchemaStructure> {
       recordId,
       error: error.message,
     });
+
+    // Shared-tabs: the store rollback above already propagated to every tab
+    // via the ingest relay; additionally deliver the EVENT to the tab that
+    // owns the mutation so its UI (toasts, subscribeToRollbacks) fires there.
+    const mutationId = encodeRecordId(event.mutation_id);
+    const owner = mutationOwnerTabId(mutationId);
+    if (this.hub && owner && this.tabId && owner !== this.tabId) {
+      this.hub.sendTo(owner, {
+        type: 'mutation-rolled-back',
+        mutationId,
+        recordId,
+        eventType: event.type,
+        error: error.message,
+      });
+    }
   }
 
   private async processDownEvent(event: DownEvent) {
@@ -1171,6 +1339,16 @@ export class Sp00kySync<S extends SchemaStructure> {
    * @param mutations Array of UpEvents (create/update/delete) to enqueue.
    */
   public async enqueueMutation(mutations: UpEvent[]) {
+    // Follower: the outbox rows are already committed in the SHARED store (the
+    // mutation tx went through the leader's worker); only the leader drains,
+    // so hand over the ids instead of queueing locally. A notify lost in a
+    // failover window is covered by the new leader's loadFromDatabase.
+    if (this.tabRole === 'follower') {
+      for (const m of mutations) {
+        this.forwarder?.mutationEnqueued(encodeRecordId(m.mutation_id));
+      }
+      return;
+    }
     this.scheduler.enqueueMutation(mutations);
   }
 

package/src/services/database/cache-engine.ts

@@ -2,6 +2,7 @@ import type { QueryPlan, RelationPlan, WhereNode } from '@spooky-sync/query-buil
 import type { SealedQuery } from '../../utils/surql';
 import type { DatabaseEventSystem } from './events/index';
 import type { Sp00kyConfig, StorageHealth } from '../../types';
+import type { EngineStorageDiagnostics } from '../../modules/devtools/storage-info';
 
 /**
  * A materialized row. Keys are field names; values are already decoded to the
@@ -121,6 +122,13 @@ export interface LocalStore extends LocalCacheEngine {
   getClient(): unknown;
   getConfig(): Sp00kyConfig<any>['database'];
   readonly currentBucketId: string;
+  /** Which built-in backend this is. OPTIONAL: absent (custom engines) is
+   *  reported as `'custom'` by DevTools. More robust than `instanceof` for
+   *  engines constructed outside this package. */
+  readonly engineKind?: 'surrealdb' | 'sqlite';
+  /** Engine-specific storage numbers for DevTools (DB file size, per-table
+   *  row counts). OPTIONAL: only engines with something to report implement it. */
+  getStorageDiagnostics?(opts?: { tableCounts?: boolean }): Promise<EngineStorageDiagnostics>;
   /**
    * Durability of this engine's local store. OPTIONAL: engines that don't
    * report it (SurrealDB, custom engines) are treated as `'unknown'` by the

package/src/services/database/engine-factory.ts

@@ -16,7 +16,8 @@ import { SqliteCacheEngine } from './sqlite-cache-engine';
 export function createLocalEngine(
   choice: LocalEngineChoice | undefined,
   config: Sp00kyConfig<any>['database'],
-  logger: Logger
+  logger: Logger,
+  opts: { shared?: boolean } = {}
 ): LocalStore {
   if (choice === undefined || choice === 'surrealdb') {
     return new SurrealCacheEngine(config, logger);
@@ -25,7 +26,7 @@ export function createLocalEngine(
     // Mirror the SurrealDB engine's `store` semantics: 'memory' → in-memory
     // SQLite (transient), 'indexeddb' → OPFS-backed (durable).
     const useOpfs = (config.store ?? 'memory') !== 'memory';
-    return new SqliteCacheEngine(config, logger, { useOpfs });
+    return new SqliteCacheEngine(config, logger, { useOpfs, shared: opts.shared });
   }
   // Custom engine instance — trust it to satisfy LocalStore.
   return choice as unknown as LocalStore;

package/src/services/database/sqlite-cache-engine.test.ts

@@ -1,6 +1,7 @@
 import { describe, it, expect } from 'vitest';
 import { RecordId } from 'surrealdb';
 import { pureWriteOpResult, SqliteCacheEngine } from './sqlite-cache-engine';
+import { stubTransport } from './sqlite-transport.fixture';
 import { translateSurql } from './surql-translate';
 import type { SqlOp } from './surql-translate';
 import { surql } from '../../utils/surql';
@@ -13,42 +14,31 @@ function makeLogger(): any {
 }
 
 /**
- * A fake Worker that models the real SQLite worker's open/closed lifecycle:
- * `open` opens the DB, `close` closes it, and `exec`/`run` REJECT with
- * "sqlite: DB not open" when the DB isn't currently open — exactly the failure
- * the fix targets. Records every message `type` (across worker generations) so
- * tests can also inspect dispatch order.
+ * A fake transport handler that models the real SQLite worker's open/closed
+ * lifecycle: `open` opens the DB, `close` closes it, and `exec`/`run` REJECT
+ * with "sqlite: DB not open" when the DB isn't currently open — exactly the
+ * failure the fix targets. Records every message `type` (across transport
+ * generations) so tests can also inspect dispatch order.
  */
-class FakeWorker {
-  onmessage: ((ev: any) => void) | null = null;
-  onerror: any = null;
-  onmessageerror: any = null;
-  private dbOpen = false;
-  constructor(private log: string[]) {}
-  postMessage(msg: any) {
-    this.log.push(msg.type);
-    Promise.resolve().then(() => {
-      let ok = true;
-      let error: string | undefined;
-      let rest: Record<string, unknown> = {};
-      if (msg.type === 'open') {
-        this.dbOpen = true;
-        rest = { persisted: true };
-      } else if (msg.type === 'close') {
-        this.dbOpen = false;
-      } else if (msg.type === 'exec') {
-        if (!this.dbOpen) { ok = false; error = 'sqlite: DB not open'; }
-        else rest = { rows: [] };
-      } else if (msg.type === 'select') {
-        if (!this.dbOpen) { ok = false; error = 'sqlite: DB not open'; }
-        else rest = { rows: [], relationFetches: 0 };
-      } else if (msg.type === 'run' || msg.type === 'batch') {
-        if (!this.dbOpen) { ok = false; error = 'sqlite: DB not open'; }
-      }
-      this.onmessage?.({ data: { id: msg.id, ok, error, ...rest } });
-    });
-  }
-  terminate() {}
+function lifecycleHandler(log: string[]) {
+  let dbOpen = false;
+  return (type: string) => {
+    log.push(type);
+    if (type === 'open') {
+      dbOpen = true;
+      return { persisted: true };
+    }
+    if (type === 'close') {
+      dbOpen = false;
+      return {};
+    }
+    if (type === 'exec' || type === 'select' || type === 'run' || type === 'batch') {
+      if (!dbOpen) throw new Error('sqlite: DB not open');
+      if (type === 'exec') return { rows: [] };
+      if (type === 'select') return { rows: [], relationFetches: 0 };
+    }
+    return {};
+  };
 }
 
 // Regression: switchBucket must run close → reopen as a single serialized
@@ -60,19 +50,7 @@ describe('SqliteCacheEngine.switchBucket serialization', () => {
   it('never dispatches an op to a closed DB during a bucket switch', async () => {
     const log: string[] = [];
     const engine = new SqliteCacheEngine({ namespace: 'n', database: 'd' } as any, makeLogger());
-    // Replicate the real spawnWorker's onmessage wiring (resolve/reject pending).
-    (engine as any).spawnWorker = () => {
-      const w = new FakeWorker(log);
-      w.onmessage = (ev: any) => {
-        const { id, ok, error, ...rest } = ev.data ?? {};
-        const p = (engine as any).pending.get(id);
-        if (!p) return;
-        (engine as any).pending.delete(id);
-        if (ok) p.resolve(rest);
-        else p.reject(new Error(error));
-      };
-      return w as unknown as Worker;
-    };
+    stubTransport(engine, lifecycleHandler(log));
 
     await engine.connect('anon');
     expect(log).toContain('open');
@@ -105,28 +83,10 @@ describe('SqliteCacheEngine system-table seeding', () => {
   it('passes the _00_* system tables to the worker open (fresh-bucket safe)', async () => {
     const msgs: any[] = [];
     const engine = new SqliteCacheEngine({ namespace: 'n', database: 'd' } as any, makeLogger());
-    (engine as any).spawnWorker = () => {
-      const w: any = { onmessage: null, onerror: null, onmessageerror: null, terminate() {} };
-      w.postMessage = (msg: any) => {
-        msgs.push(msg);
-        Promise.resolve().then(() => {
-          const rest = msg.type === 'open' ? { persisted: true } : {};
-          w.onmessage?.({ data: { id: msg.id, ok: true, ...rest } });
-        });
-      };
-      // Wire pending resolution like the real spawnWorker.
-      const inner = w.onmessage;
-      w.onmessage = (ev: any) => {
-        const { id, ok, error, ...rest } = ev.data ?? {};
-        const p = (engine as any).pending.get(id);
-        if (!p) return;
-        (engine as any).pending.delete(id);
-        if (ok) p.resolve(rest);
-        else p.reject(new Error(error));
-        void inner;
-      };
-      return w as unknown as Worker;
-    };
+    stubTransport(engine, (type, payload) => {
+      msgs.push({ type, payload });
+      return type === 'open' ? { persisted: true } : {};
+    });
 
     await engine.connect('user:fresh');
     const open = msgs.find((m) => m.type === 'open');
@@ -154,21 +114,7 @@ describe('SqliteCacheEngine storage health', () => {
       logger,
       opts ?? {}
     );
-    (engine as any).spawnWorker = () => {
-      const w: any = { onmessage: null, onerror: null, onmessageerror: null, terminate() {} };
-      w.postMessage = (msg: any) => {
-        Promise.resolve().then(() => {
-          const rest = msg.type === 'open' ? openReply : {};
-          const { id, ok, error, ...payload } = { id: msg.id, ok: true, error: undefined, ...rest };
-          const p = (engine as any).pending.get(id);
-          if (!p) return;
-          (engine as any).pending.delete(id);
-          if (ok) p.resolve(payload);
-          else p.reject(new Error(error));
-        });
-      };
-      return w as unknown as Worker;
-    };
+    stubTransport(engine, (type) => (type === 'open' ? openReply : {}));
     return { engine, logs };
   }
 
@@ -222,6 +168,189 @@ describe('SqliteCacheEngine storage health', () => {
   });
 });
 
+// Storage numbers for the DevTools Storage tab: DB size via the pragmas, row
+// counts on demand, and the configured-vs-effective workerSelect split. Errors
+// must land in `error` (the worker may be mid bucket-switch), never throw.
+describe('SqliteCacheEngine.getStorageDiagnostics', () => {
+  function makeEngine(execRows: (sql: string) => unknown[]) {
+    const noop = () => {};
+    const logger: any = { debug: noop, info: noop, warn: noop, error: noop, trace: noop };
+    logger.child = () => logger;
+    const engine = new SqliteCacheEngine({ namespace: 'n', database: 'd' } as any, logger);
+    stubTransport(engine, (type, payload) =>
+      type === 'open'
+        ? { persisted: true }
+        : type === 'exec'
+          ? { rows: execRows(payload.sql) }
+          : {}
+    );
+    return engine;
+  }
+
+  it('reports size, freelist, and per-table counts', async () => {
+    const engine = makeEngine((sql) => {
+      if (sql.includes('pragma_page_count')) return [{ bytes: 40960, freelist: 4096 }];
+      if (sql.includes('sqlite_master')) return [{ name: '_00_query' }, { name: 'game' }];
+      if (sql.includes('COUNT(*)'))
+        return [
+          { t: '_00_query', n: 3 },
+          { t: 'game', n: 12 },
+        ];
+      return [];
+    });
+    await engine.connect('user:abc');
+
+    const diag = await engine.getStorageDiagnostics({ tableCounts: true });
+    expect(diag.engine).toBe('sqlite');
+    expect(diag.bucketId).toBe('user:abc');
+    expect(diag.dbSizeBytes).toBe(40960);
+    expect(diag.freelistBytes).toBe(4096);
+    expect(diag.tableCounts).toEqual([
+      { table: '_00_query', rows: 3 },
+      { table: 'game', rows: 12 },
+    ]);
+    // Default config: workerSelect on, never downgraded.
+    expect(diag.workerSelectConfigured).toBe(true);
+    expect(diag.workerSelectEffective).toBe(true);
+  });
+
+  it('skips table counts unless asked and never throws on a dead worker', async () => {
+    const engine = makeEngine(() => [{ bytes: 8192, freelist: 0 }]);
+    await engine.connect('anon');
+
+    const diag = await engine.getStorageDiagnostics();
+    expect(diag.tableCounts).toBeUndefined();
+
+    // No worker at all → the failure lands in `error`, not as a throw.
+    const cold = makeEngine(() => []);
+    const coldDiag = await cold.getStorageDiagnostics();
+    expect(coldDiag.error).toContain('not connected');
+    expect(coldDiag.bucketId).toBe('anon');
+  });
+});
+
+// Shared-tabs engine role modes: the engine object survives every role change
+// (one monotonic epoch per tab), followers speak the same protocol over a
+// MessagePort, and the leaderless window parks ops instead of failing the UI.
+describe('SqliteCacheEngine role modes', () => {
+  function makeSharedEngine() {
+    const log: string[] = [];
+    const engine = new SqliteCacheEngine(
+      { namespace: 'n', database: 'd' } as any,
+      makeLogger(),
+      { shared: true, useOpfs: true }
+    );
+    stubTransport(engine, lifecycleHandler(log));
+    return { engine, log };
+  }
+
+  /** A fake follower dbPort: replies like the worker over postMessage. */
+  function fakeLeaderPort() {
+    const port: any = {
+      onmessage: null as null | ((ev: { data: any }) => void),
+      onmessageerror: null,
+      started: false,
+      closed: false,
+      start() {
+        this.started = true;
+      },
+      close() {
+        this.closed = true;
+      },
+      postMessage(msg: any) {
+        queueMicrotask(() => {
+          const rest =
+            msg.type === 'exec'
+              ? { rows: [] }
+              : msg.type === 'select'
+                ? { rows: [], relationFetches: 0 }
+                : {};
+          port.onmessage?.({ data: { id: msg.id, ok: true, wt: 0, ...rest } });
+        });
+      },
+    };
+    return port;
+  }
+
+  it('adoptOwner opens under the worker lock and wipes stale _00_query rows', async () => {
+    const { engine, log } = makeSharedEngine();
+    const health = await engine.adoptOwner('anon', {
+      workerLockName: 'sp00ky-tabs:fp:anon:worker:1',
+      allowMemoryFallback: false,
+      resumeHeld: false,
+    });
+    expect(health.status).toBe('persistent');
+    expect(engine.storageHealth.role).toBe('leader');
+    expect(log[0]).toBe('open');
+    expect(log).toContain('run'); // the DELETE _00_query wipe
+    expect(engine.currentBucketId).toBe('anon');
+  });
+
+  it('adoptAttached serves reads over the leader port and reports follower role', async () => {
+    const engine = new SqliteCacheEngine(
+      { namespace: 'n', database: 'd' } as any,
+      makeLogger(),
+      { shared: true }
+    );
+    const port = fakeLeaderPort();
+    await engine.adoptAttached(
+      port,
+      { bucketId: 'anon', storageHealth: { status: 'persistent', fallback: false } },
+      () => {}
+    );
+    expect(port.started).toBe(true);
+    expect(engine.storageHealth).toMatchObject({ status: 'persistent', role: 'follower' });
+    await expect(engine.getById('game', 'game:1')).resolves.toBeNull();
+    expect((globalThis as any).__sqliteStats.proxiedOps).toBeGreaterThan(0);
+  });
+
+  it('parks ops through a leader loss and releases them on promotion', async () => {
+    const { engine } = makeSharedEngine();
+    const port = fakeLeaderPort();
+    await engine.adoptAttached(
+      port,
+      { bucketId: 'anon', storageHealth: { status: 'persistent', fallback: false } },
+      () => {}
+    );
+    const epochBefore = engine.epoch;
+    engine.onLeaderLost('leader tab closed');
+    expect(engine.epoch).toBe(epochBefore + 1);
+
+    // Issued during the leaderless window: must not reject immediately.
+    const read = engine.getById('_00_query', 'h1');
+    let settled = false;
+    void read.finally(() => {
+      settled = true;
+    });
+    await new Promise((r) => setTimeout(r, 10));
+    expect(settled).toBe(false);
+
+    await engine.adoptOwner('anon', {
+      workerLockName: 'sp00ky-tabs:fp:anon:worker:2',
+      allowMemoryFallback: false,
+      resumeHeld: false,
+    });
+    await expect(read).resolves.toBeNull();
+    expect(engine.storageHealth.role).toBe('leader');
+  });
+
+  it('bumps the epoch on promotion after having had a store (fences in-flight chains)', async () => {
+    const { engine } = makeSharedEngine();
+    await engine.adoptOwner('anon', {
+      workerLockName: 'sp00ky-tabs:fp:anon:worker:1',
+      allowMemoryFallback: false,
+      resumeHeld: false,
+    });
+    const before = engine.epoch;
+    await engine.adoptOwner('anon', {
+      workerLockName: 'sp00ky-tabs:fp:anon:worker:3',
+      allowMemoryFallback: false,
+      resumeHeld: false,
+    });
+    expect(engine.epoch).toBeGreaterThan(before);
+  });
+});
+
 // `pureWriteOpResult` is the single source of truth for what a pure-write op
 // contributes to a query's per-statement results. The batched fast path in
 // `query()` and the per-op `execOp` path BOTH route through it, so a caller that