@spooky-sync/core 0.0.1-canary.327 → 0.0.1-canary.328

package/AGENTS.md

@@ -37,7 +37,7 @@ re-materialized from state, never patched in place.
 - `FailedMutation` — a row of the `_00_failed_mutations` tray (`mutationType`, `recordId`, `data`, `beforeRecord`, `error`, `revert`).
 - `BucketHandle` — file storage handle (`put`, `get`, `delete`, `exists`), plus the cache-aware `read`, `url`, `pin`/`unpin`, `evict`, `prefetch`. `get` is always remote; `read`/`url` go through the blob cache.
 - `services/blobs/` — durable cache for bucket bytes: OPFS holds the files, `_00_blob` holds a manifest that reconcile rebuilds from disk (so a wiped local store costs metadata, not the offline cache). Nothing expires on a timer; eviction is LRU under a byte budget only, skipping pinned and on-screen entries. Config: `blobCache` in `types.ts`.
-- `AuthService` — token management, sign-in/sign-out events.
+- `AuthService` — token management, sign-in/sign-out events. `subscribe(cb, { immediate? })` calls `cb` at once with the current user unless `immediate: false`, then on every change.
 - `CrdtManager`, `CrdtField`, `cursorColorFromName`, `CURSOR_COLORS`: collaborative `@crdt` fields on Loro. Client methods: `openCrdtField(table, recordId, field, draft?)` -> `Promise<CrdtField>` (every open of one field in a tab shares one `LoroDoc`; pair each with a close), `closeCrdtField(table, recordId, field)` -> `Promise<void>` (resolves once unsent edits are in the outbox; offline, once they are saved on the device, never waiting on the network), `createCrdtDraft(table, field)` -> a detached `CrdtField` for a record not created yet (`db.create` first, then pass it to `openCrdtField` as `draft`). `CrdtField`: `getDoc()`, `hasContent()`, `pushCursorState(bytes)`, `onCursorUpdate = cb` (a setter). Config: `crdt: true` preloads Loro, `crdtDebounceMs` (default 300, max wait 2 s). Design: `docs/crdt-v2.md` at the repo root.
 - Types: `Sp00kyConfig` (client-solid wraps it as `SyncedDbConfig`), `QueryTimeToLive`, `PersistenceClient`, `StoreType`, `UpdateOptions`, `RunOptions`, `PreloadOptions`.
 - Subpath: `@spooky-sync/core/otel` — `createOtelTransmit(endpoint)` for piping pino logs to OpenTelemetry.
@@ -57,6 +57,8 @@ re-materialized from state, never patched in place.
 - **`@parent` columns are auto-populated.** Defined in the `.surql` schema as `record<user>` with the `-- @parent` annotation; never write them yourself — they're set from the auth context server-side.
 - **`db.preload` is a registered query.** Resolved before on this device (a `_00_view` row exists) it returns at once; never resolved it waits until the server's membership and every body are local. A signed-out session without `enableAnonymousLiveQueries` is never sent membership, so its preload returns at once instead of blocking. It holds no subscriber, so it is evicted a ttl after registration unless a view mounts the same query. `refresh`/`staleTime` are ignored; pass `signal` to abort a cold wait.
 - **A never-resolved query paints only vouched rows.** Before the server answers (`cold`), the local predicate scan shows a cached body only if some `_00_view` row names it (as a member or subquery child) or a write for it is in flight. A body no view names is an orphan (deleted upstream while nothing watched it): it stays hidden, and the GC deletes it 30 s after boot and then hourly. A `_00_view` row no query has resolved for 14 days is retired by the same sweep, so that query paints cold again.
+- **`database.store` defaults to `'memory'`.** `'indexeddb'` keeps one IndexedDB database per user bucket (`sp00ky-<bucket>`) and needs `@surrealdb/wasm` >= 3.1.0: the 3.0.x engine opened the store but failed every write (`An IndexedDB error occured: idb error`), so each session fell back to memory. 3.1.0 ships the engine as `@surrealdb/wasm-native`; a Vite app lists it in `optimizeDeps.exclude` next to `@surrealdb/wasm`. A store that still cannot open after a drop runs the session in memory (error log `falling back to in-memory`). Under `localEngine: 'sqlite'`, `'indexeddb'` means OPFS.
+- **Boot owns the first identity.** The facade subscribes to auth with `immediate: false`: boot opens the bucket the hint names and `auth.restoreSession` announces the user. `LocalDatabaseService.switchStore` also waits for an in-flight `connect`, and lets statements already past the gate finish before it closes a client: the 3.1 engine streams results from its worker, and a statement whose client closed under it stayed pending until its 30 s deadline with every later local statement queued behind it.
 - **A rejected write is not lost.** Application errors roll the local row back (create/update/delete) and move the mutation to `_00_failed_mutations`; the tray API above lists, retries (as a fresh write) or discards it. Network errors keep the row queued.
 
 ## Module map (under `src/`)

package/dist/index.js

@@ -2188,9 +2188,9 @@ function trimHistory(history, cap) {
 
 //#endregion
 //#region src/modules/devtools/index.ts
-const CORE_VERSION = "0.0.1-canary.327";
-const WASM_VERSION = "0.0.1-canary.327";
-const SURREAL_VERSION = "3.0.3";
+const CORE_VERSION = "0.0.1-canary.328";
+const WASM_VERSION = "0.0.1-canary.328";
+const SURREAL_VERSION = "3.1.0";
 var DevToolsService = class DevToolsService {
 	version = CORE_VERSION;
 	backendInfo = emptyBackendInfo();
@@ -7848,6 +7848,15 @@ var AbstractDatabaseService = class {
 		if (next) next();
 	}
 	/**
+	* Resolve once every statement issued before this call has settled: take
+	* every slot (FIFO, so earlier statements go first), then hand them back.
+	* Bounded by {@link queryTimeoutMs}, like the statements it waits on.
+	*/
+	async drainStatements() {
+		for (let i = 0; i < this.maxConcurrentQueries; i++) await this.acquireQuerySlot();
+		for (let i = 0; i < this.maxConcurrentQueries; i++) this.releaseQuerySlot();
+	}
+	/**
 	* Hook run right before a statement is sent, inside its slot. The remote
 	* service uses it to hold statements while a connect is in flight, so a
 	* query never runs on a socket that is open but has not had its namespace
@@ -8060,6 +8069,8 @@ var LocalDatabaseService = class extends AbstractDatabaseService {
 	gate = Promise.resolve();
 	/** The incoming client while a switch is in flight (for unload cleanup). */
 	pendingSwitchClient = null;
+	/** The open `connect()` started, until it settles. */
+	opening = null;
 	constructor(config, logger) {
 		const events = createDatabaseEventSystem();
 		super(createBareSurrealClient(), logger, events);
@@ -8107,6 +8118,15 @@ var LocalDatabaseService = class extends AbstractDatabaseService {
 		return super.query(query, vars);
 	}
 	async connect(bucketId = ANON_USER_ID) {
+		const opening = this.openBucket(bucketId);
+		this.opening = opening;
+		try {
+			await opening;
+		} finally {
+			if (this.opening === opening) this.opening = null;
+		}
+	}
+	async openBucket(bucketId) {
 		const { namespace, database } = this.getConfig();
 		const store = this.getConfig().store ?? "memory";
 		this.bucketId = bucketId;
@@ -8129,14 +8149,20 @@ var LocalDatabaseService = class extends AbstractDatabaseService {
 	* async chains can detect they're stale.
 	*
 	* Callers own the drain/rebind choreography (close the gate, quiesce sync +
-	* timers BEFORE calling this; re-provision + rebind AFTER).
+	* timers BEFORE calling this; re-provision + rebind AFTER). Statements that
+	* passed the gate before it closed are let finish before the old client
+	* closes: the engine streams results from its worker, and a client closed
+	* under a statement leaves that statement pending until its deadline, with
+	* every later local statement queued behind it.
 	*/
 	async switchStore(bucketId) {
+		if (this.opening) await this.opening.catch(() => {});
 		if (bucketId === this.bucketId) return;
 		const { namespace, database } = this.getConfig();
 		const store = this.getConfig().store ?? "memory";
 		this.storeEpoch++;
 		if (store === "memory") {
+			await this.drainStatements();
 			try {
 				await this.client.close();
 			} catch {}
@@ -8155,6 +8181,7 @@ var LocalDatabaseService = class extends AbstractDatabaseService {
 		} finally {
 			this.pendingSwitchClient = null;
 		}
+		await this.drainStatements();
 		const old = this.client;
 		this.client = next;
 		this.bucketId = bucketId;
@@ -11855,9 +11882,10 @@ var AuthService = class {
 	/**
 	* Subscribe to auth state changes.
 	* callback is called immediately with current value and whenever validation status changes.
+	* `immediate: false` skips that first call: only changes are reported.
 	*/
-	subscribe(cb) {
-		cb(this.announcedUserId());
+	subscribe(cb, opts = {}) {
+		if (opts.immediate !== false) cb(this.announcedUserId());
 		const id = this.events.subscribe(AuthEventTypes.AuthStateChanged, (event) => {
 			cb(event.payload);
 		});
@@ -15364,7 +15392,7 @@ function createTabsCoordinator(config, s, host) {
 	return new TabsCoordinator({
 		tabId: s.tabId,
 		fingerprint: computeTabsFingerprint({
-			coreVersion: "0.0.1-canary.327",
+			coreVersion: "0.0.1-canary.328",
 			schemaHash: hash53(config.schemaSurql),
 			endpoint: config.database.endpoint ?? "",
 			namespace: config.database.namespace,
@@ -16134,7 +16162,7 @@ var Sp00kyClient = class {
 		s.auth.subscribe((userId) => void this.runtime.dispatch({
 			type: "AuthFlip",
 			userId
-		}));
+		}), { immediate: false });
 		this.impersonationBanner = new ImpersonationBanner(() => s.auth.stopImpersonating(), this.config.impersonationBanner);
 		const banner = this.impersonationBanner;
 		this.disposers.push(s.auth.subscribeImpersonation((info) => banner.update(info)), () => banner.unmount());

package/dist/types.d.ts

@@ -601,6 +601,12 @@ declare abstract class AbstractDatabaseService {
   /** FIFO slot acquisition, so `maxConcurrentQueries = 1` keeps strict order. */
   private acquireQuerySlot;
   private releaseQuerySlot;
+  /**
+   * Resolve once every statement issued before this call has settled: take
+   * every slot (FIFO, so earlier statements go first), then hand them back.
+   * Bounded by {@link queryTimeoutMs}, like the statements it waits on.
+   */
+  protected drainStatements(): Promise<void>;
   /**
    * Hook run right before a statement is sent, inside its slot. The remote
    * service uses it to hold statements while a connect is in flight, so a
@@ -851,8 +857,11 @@ declare class AuthService<S extends SchemaStructure> {
   /**
    * Subscribe to auth state changes.
    * callback is called immediately with current value and whenever validation status changes.
+   * `immediate: false` skips that first call: only changes are reported.
    */
-  subscribe(cb: (userId: string | null) => void): () => void;
+  subscribe(cb: (userId: string | null) => void, opts?: {
+    immediate?: boolean;
+  }): () => void;
   /**
    * Run `hook` at the start of every sign-out, while the token and the socket
    * still belong to the leaving user (Web Push removes this device's

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spooky-sync/core",
-  "version": "0.0.1-canary.327",
+  "version": "0.0.1-canary.328",
   "type": "module",
   "sideEffects": false,
   "main": "./dist/index.js",
@@ -75,10 +75,11 @@
     }
   },
   "dependencies": {
-    "@spooky-sync/query-builder": "0.0.1-canary.327",
-    "@spooky-sync/ssp-wasm": "0.0.1-canary.327",
+    "@spooky-sync/query-builder": "0.0.1-canary.328",
+    "@spooky-sync/ssp-wasm": "0.0.1-canary.328",
     "@sqlite.org/sqlite-wasm": "3.53.0-build1",
-    "@surrealdb/wasm": "^3.0.3",
+    "@surrealdb/wasm": "^3.1.0",
+    "@surrealdb/wasm-native": "^3.3.4",
     "blurhash": "^2.0.5",
     "fast-json-patch": "^3.1.1",
     "loro-crdt": "1.11.0",

package/scripts/check-worker-entries.mjs

@@ -23,6 +23,7 @@ const ENTRIES = ['pure.js', 'live.js', 'sw.js'];
 const FORBIDDEN_IMPORTS = [
   '@spooky-sync/ssp-wasm',
   '@surrealdb/wasm',
+  '@surrealdb/wasm-native',
   '@sqlite.org/sqlite-wasm',
   'loro-crdt',
   'pino',

package/skills/sp00ky-core/SKILL.md

@@ -47,7 +47,7 @@ See [references/config.md](references/config.md) for all configuration options.
 Key fields:
 - `database.endpoint` — SurrealDB WebSocket URL
 - `database.namespace` / `database.database` — SurrealDB namespace and database
-- `database.store` — `'indexeddb'` (persistent) or `'memory'` (transient)
+- `database.store` — `'memory'` (transient, the default) or `'indexeddb'` (persistent; needs `@surrealdb/wasm` >= 3.1.0, and Vite apps exclude `@surrealdb/wasm-native` from `optimizeDeps`)
 - `schema` — The `SchemaStructure` object (use `as const satisfies SchemaStructure`)
 - `schemaSurql` — The compiled SURQL schema string for local DB provisioning
 - `logLevel` — `'debug' | 'info' | 'warn' | 'error'`

package/skills/sp00ky-core/references/config.md

@@ -9,7 +9,7 @@ interface Sp00kyConfig<S extends SchemaStructure> {
     namespace: string;
     /** SurrealDB database name */
     database: string;
-    /** Local store type: 'memory' (transient) or 'indexeddb' (persistent) */
+    /** Local store type: 'memory' (transient, default) or 'indexeddb' (persistent) */
     store?: 'memory' | 'indexeddb';
     /** Authentication token */
     token?: string;

package/src/client/sp00ky-client.test.ts

@@ -78,6 +78,41 @@ describe('Sp00kyClient facade', () => {
     expect(client.liveRetryCount).toBe(0);
   });
 
+  it('a warm boot opens the hinted bucket alone; no anon switch races it', async () => {
+    // A reload of a signed-in tab: the hint names the user's bucket and the
+    // store takes a while to open (IndexedDB). The auth service's signed-out
+    // answer at construction used to dispatch a flip to anon, which switched
+    // stores and provisioned while boot was still connecting.
+    let bucket = 'anon';
+    let opened!: () => void;
+    const { client, a, services } = makeClient({
+      services: {
+        'local.connect': (id: string) => {
+          bucket = id;
+          return new Promise<void>((r) => (opened = r));
+        },
+        'local.currentBucketId': () => bucket,
+        'local.beginSwitch': () => () => {},
+        'local.switchStore': async (id: string) => void (bucket = id),
+      },
+    });
+    const init = client.init();
+    await flush();
+    opened();
+    await init;
+    await flush();
+    expect(a.calls.filter(([n]) => n === 'service.local.connect').map(([, args]) => args)).toEqual([['u1']]);
+    expect(a.names()).not.toContain('service.local.beginSwitch');
+    expect(a.names()).not.toContain('service.local.switchStore');
+    expect(a.names()).not.toContain('service.hint.write');
+    expect(client.state.bucketId).toBe('u1');
+
+    // A real auth change still flips.
+    services.authListeners.forEach((cb) => cb(null));
+    await flush();
+    expect(a.calls.filter(([n]) => n === 'service.local.switchStore').map(([, args]) => args)).toEqual([['anon']]);
+  });
+
   it('queryRaw registers locally and returns the hash before any remote work; subscribers paint from the local store', async () => {
     // Boot loads the view index: `thing:1` is vouched for, `thing:2` is an orphan and stays hidden.
     const stored = (sql: string) =>

package/src/client/sp00ky-client.ts

@@ -223,7 +223,13 @@ export class Sp00kyClient<S extends SchemaStructure> {
     const receiver: StreamUpdateReceiver = { onStreamUpdate: (update) => void this.runtime.dispatch({ type: 'StreamUpdate', update }) };
     s.streamProcessor.addReceiver(receiver);
     s.connectionSupervisor.subscribe((state) => void this.runtime.dispatch({ type: 'ConnectionChanged', state }));
-    s.auth.subscribe((userId) => void this.runtime.dispatch({ type: 'AuthFlip', userId }));
+    // Changes only. The immediate answer here is always "signed out" (nothing
+    // is restored before `init()`), and boot owns the first identity: it opens
+    // the bucket the hint names and announces the restored session itself. As
+    // a flip, that answer switched to the anon bucket while boot was still
+    // opening the user's, so two clients provisioned at once, boot failed, and
+    // a persistent store never got past the provider's fallback on reload.
+    s.auth.subscribe((userId) => void this.runtime.dispatch({ type: 'AuthFlip', userId }), { immediate: false });
     // Whoever is looking at the page should be able to tell, and leave. The
     // app can restyle this, replace it (`mode: 'custom'`, with a fallback if
     // its own never renders) or take the job over entirely (`mode: 'none'`).

package/src/modules/auth/auth.local-first.test.ts

@@ -56,6 +56,20 @@ describe('restoreSessionFromToken', () => {
     expect(seen).toContain('user:abc');
   });
 
+  it('reports only changes to a subscriber that opts out of the immediate call', async () => {
+    const { auth } = makeAuth({ token: jwt({ AC: 'account', ID: 'user:abc' }) });
+    const all: (string | null)[] = [];
+    const changes: (string | null)[] = [];
+    auth.subscribe((uid) => all.push(uid));
+    auth.subscribe((uid) => changes.push(uid), { immediate: false });
+    expect(all).toEqual([null]);
+    expect(changes).toEqual([]);
+
+    await auth.restoreSessionFromToken();
+
+    expect(changes).toEqual(['user:abc']);
+  });
+
   it('returns null when there is no token, and when the token carries no id', async () => {
     expect(await makeAuth().auth.restoreSessionFromToken()).toBeNull();
     const noId = makeAuth({ token: jwt({ AC: 'account' }) });

package/src/modules/auth/index.ts

@@ -150,10 +150,10 @@ export class AuthService<S extends SchemaStructure> {
   /**
    * Subscribe to auth state changes.
    * callback is called immediately with current value and whenever validation status changes.
+   * `immediate: false` skips that first call: only changes are reported.
    */
-  subscribe(cb: (userId: string | null) => void): () => void {
-    // Immediate callback
-    cb(this.announcedUserId());
+  subscribe(cb: (userId: string | null) => void, opts: { immediate?: boolean } = {}): () => void {
+    if (opts.immediate !== false) cb(this.announcedUserId());
 
     const id = this.events.subscribe(AuthEventTypes.AuthStateChanged, (event) => {
       cb(event.payload);

package/src/query/membership.saga.test.ts

@@ -178,6 +178,29 @@ describe('rows the server takes out of a query', () => {
     expect((await runPure(applySubqueryChildren('a', []), { state: pending, handlers })).log.some((e) => e.kind === 'local.delete')).toBe(false);
     const follower = { ...base, tabRole: 'follower' as const };
     expect((await runPure(applySubqueryChildren('a', []), { state: follower, handlers })).log.some((e) => e.kind === 'local.delete')).toBe(false);
+    const writing = {
+      ...base,
+      pendingWrites: new Map([['k', { key: 'k', table: 'c', recordId: 'c:1', data: {}, before: null, firstAt: 0, mirrorId: null }]]),
+    };
+    expect((await runPure(applySubqueryChildren('a', []), { state: writing, handlers })).log.some((e) => e.kind === 'local.delete')).toBe(false);
+  });
+  it('a leader relays the removal to its followers; a failed local delete keeps the row known', async () => {
+    const base = buildState(
+      [buildEntry({ def: { hash: 'a' }, lifecycle: { phase: 'live' }, remoteArray: [['t:1', 1]], subqueryRemoteArray: [['c:1', 1]] })],
+      R.setVersions([['t:1', 1], ['c:1', 1]])
+    );
+    const ok = { 'local.upsert': () => undefined, 'local.delete': () => undefined, 'ssp.ingest': () => undefined };
+    const leader = await runPure(applySubqueryChildren('a', []), { state: { ...base, tabRole: 'leader' as const }, handlers: ok });
+    expect(leader.emitted).toContainEqual({ type: 'tabs:broadcast', message: { type: 'ingest', records: [{ table: 'c', op: 'DELETE', id: 'c:1', record: {} }] } });
+    const failing = {
+      ...ok,
+      'local.delete': () => {
+        throw new Error('locked');
+      },
+    };
+    const out = await runPure(applySubqueryChildren('a', []), { state: base, handlers: failing });
+    expect(out.state.versions.has('c:1')).toBe(true);
+    expect(out.log.some((e) => e.kind === 'ssp.ingest')).toBe(false);
   });
 });
 

package/src/services/database/database.ts

@@ -86,6 +86,16 @@ export abstract class AbstractDatabaseService {
     if (next) next();
   }
 
+  /**
+   * Resolve once every statement issued before this call has settled: take
+   * every slot (FIFO, so earlier statements go first), then hand them back.
+   * Bounded by {@link queryTimeoutMs}, like the statements it waits on.
+   */
+  protected async drainStatements(): Promise<void> {
+    for (let i = 0; i < this.maxConcurrentQueries; i++) await this.acquireQuerySlot();
+    for (let i = 0; i < this.maxConcurrentQueries; i++) this.releaseQuerySlot();
+  }
+
   /**
    * Hook run right before a statement is sent, inside its slot. The remote
    * service uses it to hold statements while a connect is in flight, so a

package/src/services/database/local.test.ts

@@ -62,3 +62,89 @@ describe('matchesBucketStore', () => {
     expect(matchesBucketStore('sp00ky', 'sp00ky-anon')).toBe(false);
   });
 });
+
+// A bucket switch that lands while the boot open is still in flight (a reload
+// of a signed-in tab, with IndexedDB slow to open) must wait for it. Run
+// concurrently, the switch closed the client `connect` was opening and both
+// provisioned a store at once, so boot never finished.
+import { vi } from 'vitest';
+import { Surreal } from 'surrealdb';
+import { LocalDatabaseService } from './local';
+
+vi.mock('@surrealdb/wasm', () => ({ createWasmWorkerEngines: () => ({}) }));
+
+describe('LocalDatabaseService open and switch', () => {
+  it('a switch waits for the in-flight connect instead of closing the client it opens', async () => {
+    const opens: Array<{ url: string; done: () => void }> = [];
+    const closed: string[] = [];
+    const urlOf = new WeakMap<object, string>();
+    vi.spyOn(Surreal.prototype, 'connect').mockImplementation(function (this: Surreal, url: string | URL) {
+      urlOf.set(this, String(url));
+      return new Promise<true>((resolve) => opens.push({ url: String(url), done: () => resolve(true) }));
+    });
+    vi.spyOn(Surreal.prototype, 'use').mockResolvedValue({});
+    vi.spyOn(Surreal.prototype, 'close').mockImplementation(async function (this: Surreal) {
+      closed.push(urlOf.get(this) ?? 'placeholder');
+      return true as const;
+    });
+    const logger: any = { trace: vi.fn(), debug: vi.fn(), info: vi.fn(), warn: vi.fn(), error: vi.fn() };
+    logger.child = () => logger;
+    const local = new LocalDatabaseService({ namespace: 'n', database: 'd', store: 'indexeddb' } as any, logger);
+
+    const booting = local.connect('u1');
+    await vi.waitFor(() => expect(opens).toHaveLength(1));
+    const switching = local.switchStore('anon');
+    await new Promise((r) => setTimeout(r, 10));
+    expect(opens.map((o) => o.url)).toEqual(['indxdb://sp00ky-u1']);
+    expect(closed).toEqual([]);
+
+    opens[0].done();
+    await booting;
+    await vi.waitFor(() => expect(opens).toHaveLength(2));
+    expect(opens[1].url).toBe('indxdb://sp00ky-anon');
+    opens[1].done();
+    await switching;
+    expect(closed).toEqual(['indxdb://sp00ky-u1']);
+    expect(local.currentBucketId).toBe('anon');
+    vi.restoreAllMocks();
+  });
+
+  // The engine streams a statement's result from its worker; closing the
+  // client under it left the statement pending until its 30 s deadline, and
+  // every later local statement queued behind it (sign-in hung on "Loading").
+  it.each(['memory', 'indexeddb'] as const)('%s: a switch lets a statement in flight finish before it closes the client', async (store) => {
+    let answer!: (rows: unknown[]) => void;
+    const events: string[] = [];
+    vi.spyOn(Surreal.prototype, 'connect').mockResolvedValue(true);
+    vi.spyOn(Surreal.prototype, 'use').mockResolvedValue({});
+    vi.spyOn(Surreal.prototype, 'query').mockImplementation((() =>
+      new Promise((r) => {
+        answer = (rows) => {
+          events.push('answered');
+          r(rows);
+        };
+      })) as any);
+    vi.spyOn(Surreal.prototype, 'close').mockImplementation(async () => {
+      events.push('close');
+      return true as const;
+    });
+    const logger: any = { trace: vi.fn(), debug: vi.fn(), info: vi.fn(), warn: vi.fn(), error: vi.fn() };
+    logger.child = () => logger;
+    const local = new LocalDatabaseService({ namespace: 'n', database: 'd', store } as any, logger);
+    await local.connect('anon');
+
+    const reading = local.query('SELECT * FROM thing');
+    await vi.waitFor(() => expect(answer).toBeDefined());
+    const release = local.beginSwitch();
+    const switching = local.switchStore('u1');
+    await new Promise((r) => setTimeout(r, 10));
+    expect(events).toEqual([]);
+
+    answer([[]]);
+    await reading;
+    await switching;
+    release();
+    expect(events).toEqual(['answered', 'close']);
+    vi.restoreAllMocks();
+  });
+});

package/src/services/database/local.ts

@@ -104,6 +104,8 @@ export class LocalDatabaseService extends AbstractDatabaseService {
   private gate: Promise<void> = Promise.resolve();
   /** The incoming client while a switch is in flight (for unload cleanup). */
   private pendingSwitchClient: Surreal | null = null;
+  /** The open `connect()` started, until it settles. */
+  private opening: Promise<void> | null = null;
 
   constructor(config: Sp00kyConfig<any>['database'], logger: Logger) {
     const events = createDatabaseEventSystem();
@@ -176,6 +178,16 @@ export class LocalDatabaseService extends AbstractDatabaseService {
   }
 
   async connect(bucketId: string = ANON_USER_ID): Promise<void> {
+    const opening = this.openBucket(bucketId);
+    this.opening = opening;
+    try {
+      await opening;
+    } finally {
+      if (this.opening === opening) this.opening = null;
+    }
+  }
+
+  private async openBucket(bucketId: string): Promise<void> {
     const { namespace, database } = this.getConfig();
     const store = this.getConfig().store ?? 'memory';
     this.bucketId = bucketId;
@@ -201,9 +213,16 @@ export class LocalDatabaseService extends AbstractDatabaseService {
    * async chains can detect they're stale.
    *
    * Callers own the drain/rebind choreography (close the gate, quiesce sync +
-   * timers BEFORE calling this; re-provision + rebind AFTER).
+   * timers BEFORE calling this; re-provision + rebind AFTER). Statements that
+   * passed the gate before it closed are let finish before the old client
+   * closes: the engine streams results from its worker, and a client closed
+   * under a statement leaves that statement pending until its deadline, with
+   * every later local statement queued behind it.
    */
   async switchStore(bucketId: string): Promise<void> {
+    // Never overlap the boot open: the switch would close the client `connect`
+    // is still opening, and both would provision a store at once.
+    if (this.opening) await this.opening.catch(() => {});
     if (bucketId === this.bucketId) return;
     const { namespace, database } = this.getConfig();
     const store = this.getConfig().store ?? 'memory';
@@ -212,6 +231,7 @@ export class LocalDatabaseService extends AbstractDatabaseService {
     if (store === 'memory') {
       // mem:// has no per-user persistence; close + reopen the same client
       // yields a fresh empty store, which is exactly the reset we want.
+      await this.drainStatements();
       try {
         await this.client.close();
       } catch {
@@ -241,6 +261,7 @@ export class LocalDatabaseService extends AbstractDatabaseService {
       this.pendingSwitchClient = null;
     }
 
+    await this.drainStatements();
     const old = this.client;
     this.client = next;
     this.bucketId = bucketId;

package/src/testing/fake-services.ts

@@ -38,7 +38,22 @@ export function fakeServiceBundle<S extends SchemaStructure>(over: Partial<Servi
     streamProcessor: { addReceiver: (r: unknown) => void receivers.push(r), checkpoint: async () => undefined, dispose: noop } as any,
     migrator: {} as any,
     crdt: { attach: noop, setSessionId: noop, closeAll: noop, dispose: noop, open: async () => 'field', close: async () => {} } as any,
-    auth: { subscribe: (cb: (u: string | null) => void) => (authListeners.push(cb), noop), subscribeImpersonation: () => noop, onBeforeSignOut: () => noop, currentUser: null, isAuthenticated: false, token: null, impersonation: null, eventSystem: { subscribe: noop } } as any,
+    // Mirrors `AuthService.subscribe`: the current (signed-out) identity at
+    // once unless the subscriber opts out, then every change.
+    auth: {
+      subscribe: (cb: (u: string | null) => void, opts: { immediate?: boolean } = {}) => {
+        if (opts.immediate !== false) cb(null);
+        authListeners.push(cb);
+        return noop;
+      },
+      subscribeImpersonation: () => noop,
+      onBeforeSignOut: () => noop,
+      currentUser: null,
+      isAuthenticated: false,
+      token: null,
+      impersonation: null,
+      eventSystem: { subscribe: noop },
+    } as any,
     tabs: null,
     tabsUnsupportedReason: 'test',
     tabId: 'tab-test',