@spooky-sync/core 0.0.1-canary.32 → 0.0.1-canary.320

package/dist/worker-types.js

@@ -0,0 +1,73 @@
+//#region src/push/types.ts
+/**
+* Web Push wire types shared by the page (`db.webPush`), the service worker
+* bridge (`@spooky-sync/core/sw`) and the live feed. Pure: types plus a few
+* dependency-free helpers, safe in any context.
+*
+* `PushPayload` mirrors `packages/push-core/src/config.rs` (`PushPayload`,
+* `PayloadKind`, `Op`, `NotificationTemplate`). Keep the two in step.
+*/
+/** Payload format version this build understands. */
+const PUSH_PAYLOAD_VERSION = 1;
+/** `urlBase64ToUint8Array`: the VAPID key as `applicationServerKey` wants it. */
+function base64UrlToBytes(value) {
+	const padded = value.replace(/-/g, "+").replace(/_/g, "/") + "=".repeat((4 - value.length % 4) % 4);
+	const raw = typeof atob === "function" ? atob(padded) : decodeBase64Fallback(padded);
+	const out = new Uint8Array(raw.length);
+	for (let i = 0; i < raw.length; i++) out[i] = raw.charCodeAt(i);
+	return out;
+}
+function bytesToBase64Url(bytes) {
+	const view = bytes instanceof Uint8Array ? bytes : new Uint8Array(bytes);
+	let raw = "";
+	for (let i = 0; i < view.length; i++) raw += String.fromCharCode(view[i]);
+	return (typeof btoa === "function" ? btoa(raw) : encodeBase64Fallback(raw)).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+function sameBytes(a, b) {
+	if (!a || !b) return false;
+	const x = a instanceof Uint8Array ? a : new Uint8Array(a);
+	const y = b instanceof Uint8Array ? b : new Uint8Array(b);
+	if (x.length !== y.length) return false;
+	for (let i = 0; i < x.length; i++) if (x[i] !== y[i]) return false;
+	return true;
+}
+/** A payload this build can act on (`v` known, `kind` set). */
+function isPushPayload(value) {
+	if (!value || typeof value !== "object") return false;
+	const v = value;
+	return v.v === PUSH_PAYLOAD_VERSION && (v.kind === "rule" || v.kind === "message");
+}
+const B64 = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
+function decodeBase64Fallback(input) {
+	const clean = input.replace(/=+$/, "");
+	let out = "";
+	let buffer = 0;
+	let bits = 0;
+	for (const ch of clean) {
+		const idx = B64.indexOf(ch);
+		if (idx < 0) continue;
+		buffer = buffer << 6 | idx;
+		bits += 6;
+		if (bits >= 8) {
+			bits -= 8;
+			out += String.fromCharCode(buffer >> bits & 255);
+		}
+	}
+	return out;
+}
+function encodeBase64Fallback(raw) {
+	let out = "";
+	for (let i = 0; i < raw.length; i += 3) {
+		const a = raw.charCodeAt(i);
+		const b = i + 1 < raw.length ? raw.charCodeAt(i + 1) : 0;
+		const c = i + 2 < raw.length ? raw.charCodeAt(i + 2) : 0;
+		const n = a << 16 | b << 8 | c;
+		out += B64[n >> 18 & 63] + B64[n >> 12 & 63];
+		out += i + 1 < raw.length ? B64[n >> 6 & 63] : "=";
+		out += i + 2 < raw.length ? B64[n & 63] : "=";
+	}
+	return out;
+}
+
+//#endregion
+export { sameBytes as a, isPushPayload as i, base64UrlToBytes as n, bytesToBase64Url as r, PUSH_PAYLOAD_VERSION as t };

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "@spooky-sync/core",
-  "version": "0.0.1-canary.32",
+  "version": "0.0.1-canary.320",
   "type": "module",
+  "sideEffects": false,
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "exports": {
@@ -12,13 +13,28 @@
     "./otel": {
       "types": "./dist/otel/index.d.ts",
       "import": "./dist/otel/index.js"
+    },
+    "./pure": {
+      "types": "./dist/pure.d.ts",
+      "import": "./dist/pure.js"
+    },
+    "./live": {
+      "types": "./dist/live.d.ts",
+      "import": "./dist/live.js"
+    },
+    "./sw": {
+      "types": "./dist/sw.d.ts",
+      "import": "./dist/sw.js"
     }
   },
   "scripts": {
     "dev": "tsdown --watch",
     "dev:example": "pnpm dev",
-    "build": "tsdown",
-    "test": "vitest"
+    "build": "tsdown && node scripts/check-broker-bundle.mjs && node scripts/check-worker-entries.mjs",
+    "test": "vitest",
+    "test:run": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "type-check": "tsc --noEmit"
   },
   "repository": {
     "type": "git",
@@ -59,15 +75,19 @@
     }
   },
   "dependencies": {
-    "@spooky-sync/query-builder": "workspace:*",
-    "@spooky-sync/ssp-wasm": "workspace:*",
-    "@surrealdb/wasm": "^3.0.0",
+    "@spooky-sync/query-builder": "0.0.1-canary.320",
+    "@spooky-sync/ssp-wasm": "0.0.1-canary.320",
+    "@sqlite.org/sqlite-wasm": "3.53.0-build1",
+    "@surrealdb/wasm": "^3.0.3",
+    "blurhash": "^2.0.5",
     "fast-json-patch": "^3.1.1",
+    "loro-crdt": "^1.5.6",
     "pino": "^10.1.0",
-    "surrealdb": "2.0.0"
+    "surrealdb": "2.1.0"
   },
   "devDependencies": {
     "@types/node": "^22.5.2",
+    "@vitest/coverage-v8": "^3.2.4",
     "tsdown": "^0.12.4",
     "typescript": "^5.6.2",
     "vitest": "^3.2.0"

package/scripts/check-broker-bundle.mjs

@@ -0,0 +1,33 @@
+// Build gate: dist/tabs-broker-worker.js must be self-contained ESM.
+// Bundlers cannot trace `new SharedWorker(url)` module graphs, so any
+// import statement surviving into the emitted broker file would 404 at
+// runtime in consumers (the file is fetched as a bare URL, its relative
+// chunk siblings are not copied along). Run after `tsdown` in the build.
+import { readFileSync } from 'node:fs';
+import { resolve, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const dist = resolve(dirname(fileURLToPath(import.meta.url)), '../dist/tabs-broker-worker.js');
+
+let code;
+try {
+  code = readFileSync(dist, 'utf8');
+} catch {
+  console.error(`check-broker-bundle: ${dist} missing; did tsdown run?`);
+  process.exit(1);
+}
+
+const problems = [];
+// Static or dynamic imports of sibling chunks.
+const importRe = /(?:^|\n)\s*import[\s(]/;
+if (importRe.test(code)) problems.push('contains an import statement');
+if (!code.includes('onconnect')) problems.push('missing onconnect handler');
+
+if (problems.length > 0) {
+  console.error(`check-broker-bundle: dist/tabs-broker-worker.js ${problems.join('; ')}.`);
+  console.error(
+    'The broker worker must stay free of runtime imports (type-only imports are fine in source).'
+  );
+  process.exit(1);
+}
+console.log('check-broker-bundle: ok');

package/scripts/check-worker-entries.mjs

@@ -0,0 +1,172 @@
+// Build gate for the wasm-free subpath entries: dist/pure.js, dist/live.js and
+// dist/sw.js (`@spooky-sync/core/pure`, `/live`, `/sw`). They are imported by
+// service workers, dedicated workers and Node, so across each entry and every
+// chunk it reaches:
+//   - no import of a wasm engine, the circuit, CRDTs or the logger;
+//   - no reference to `window`, `document` or `localStorage` (a service worker
+//     has none of them; an access at module top level would throw on import);
+//   - `/sw` does not even pull in the `surrealdb` SDK.
+// Each entry is then really imported in this Node process (no DOM globals)
+// to catch top-level side effects the static scan cannot see. Prints the
+// gzipped size of each entry (own code, and fully bundled with its npm
+// dependencies when rolldown is reachable). Run after `tsdown` in the build.
+import { readFileSync, existsSync } from 'node:fs';
+import { resolve, dirname, join } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { gzipSync } from 'node:zlib';
+import { createRequire } from 'node:module';
+
+const root = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const dist = join(root, 'dist');
+
+const ENTRIES = ['pure.js', 'live.js', 'sw.js'];
+const FORBIDDEN_IMPORTS = [
+  '@spooky-sync/ssp-wasm',
+  '@surrealdb/wasm',
+  '@sqlite.org/sqlite-wasm',
+  'loro-crdt',
+  'pino',
+  'blurhash',
+];
+const FORBIDDEN_PER_ENTRY = { 'sw.js': ['surrealdb'] };
+const FORBIDDEN_GLOBALS = ['window', 'document', 'localStorage'];
+
+const importRe =
+  /(?:import|export)\s*(?:[^'"`;]*?\sfrom\s*)?["']([^"']+)["']|import\(\s*["']([^"']+)["']\s*\)/g;
+
+/** Blank out comments and string/template literals so identifier scans see code only. */
+function codeOnly(src) {
+  let out = '';
+  let i = 0;
+  while (i < src.length) {
+    const c = src[i];
+    const n = src[i + 1];
+    if (c === '/' && n === '/') {
+      while (i < src.length && src[i] !== '\n') i++;
+      continue;
+    }
+    if (c === '/' && n === '*') {
+      i += 2;
+      while (i < src.length && !(src[i] === '*' && src[i + 1] === '/')) i++;
+      i += 2;
+      continue;
+    }
+    if (c === '"' || c === "'" || c === '`') {
+      const q = c;
+      i++;
+      while (i < src.length && src[i] !== q) i += src[i] === '\\' ? 2 : 1;
+      i++;
+      out += '""';
+      continue;
+    }
+    out += c;
+    i++;
+  }
+  return out;
+}
+
+function walk(entry) {
+  const seen = new Set();
+  const bare = new Set();
+  const stack = [join(dist, entry)];
+  while (stack.length > 0) {
+    const file = stack.pop();
+    if (seen.has(file)) continue;
+    seen.add(file);
+    if (!existsSync(file)) throw new Error(`${entry}: missing ${file}`);
+    const src = readFileSync(file, 'utf8');
+    for (const m of src.matchAll(importRe)) {
+      const spec = m[1] ?? m[2];
+      if (spec.startsWith('.')) stack.push(resolve(dirname(file), spec));
+      else bare.add(spec);
+    }
+  }
+  return { files: [...seen], bare: [...bare] };
+}
+
+const problems = [];
+const sizes = [];
+
+for (const entry of ENTRIES) {
+  let graph;
+  try {
+    graph = walk(entry);
+  } catch (error) {
+    problems.push(String(error.message ?? error));
+    continue;
+  }
+  const forbidden = [...FORBIDDEN_IMPORTS, ...(FORBIDDEN_PER_ENTRY[entry] ?? [])];
+  for (const spec of graph.bare) {
+    if (forbidden.some((f) => spec === f || spec.startsWith(`${f}/`)))
+      problems.push(`${entry} imports ${spec}`);
+  }
+  let own = '';
+  for (const file of graph.files) {
+    const src = readFileSync(file, 'utf8');
+    own += src;
+    if (/\.wasm\b/.test(src))
+      problems.push(`${entry}: ${file.slice(dist.length + 1)} references a .wasm file`);
+    const code = codeOnly(src);
+    for (const name of FORBIDDEN_GLOBALS) {
+      // `x.window` (a property) is fine; a bare identifier is not.
+      const re = new RegExp(`(?<![.\\w$])${name}(?![\\w$])`);
+      if (re.test(code))
+        problems.push(`${entry}: ${file.slice(dist.length + 1)} references \`${name}\``);
+    }
+  }
+  sizes.push({
+    entry,
+    files: graph.files.length,
+    raw: Buffer.byteLength(own),
+    gzip: gzipSync(own).length,
+    deps: graph.bare,
+  });
+}
+
+// Import each entry for real: top-level code must run without DOM globals.
+for (const entry of ENTRIES) {
+  try {
+    await import(pathToFileURL(join(dist, entry)).href);
+  } catch (error) {
+    problems.push(`${entry} fails to import in Node: ${error?.message ?? error}`);
+  }
+}
+
+// Fully bundled size (entry + npm deps, minified), when rolldown is reachable
+// through tsdown. Informational only.
+async function bundledGzip(entry) {
+  try {
+    const req = createRequire(createRequire(join(root, 'package.json')).resolve('tsdown'));
+    const { rolldown } = await import(pathToFileURL(req.resolve('rolldown')).href);
+    const bundle = await rolldown({
+      input: join(dist, entry),
+      platform: 'browser',
+      logLevel: 'silent',
+    });
+    const { output } = await bundle.generate({ format: 'esm', minify: true });
+    await bundle.close();
+    const code = output.map((o) => o.code ?? '').join('');
+    return gzipSync(code).length;
+  } catch {
+    return null;
+  }
+}
+
+for (const s of sizes) s.bundled = await bundledGzip(s.entry);
+
+const kb = (n) => `${(n / 1024).toFixed(2)} kB`;
+for (const s of sizes) {
+  const bundled = s.bundled === null ? '' : `, bundled with deps + minified ${kb(s.bundled)} gzip`;
+  console.log(
+    `check-worker-entries: ${s.entry.padEnd(8)} ${kb(s.raw)} (${kb(s.gzip)} gzip, ${s.files} file${s.files === 1 ? '' : 's'}; deps: ${s.deps.join(', ') || 'none'})${bundled}`
+  );
+}
+
+if (problems.length > 0) {
+  for (const p of problems) console.error(`check-worker-entries: ${p}`);
+  console.error(
+    'The /pure, /live and /sw entries must stay free of wasm, the logger and DOM globals.'
+  );
+  process.exit(1);
+}
+console.log('check-worker-entries: ok');

package/skills/sp00ky-core/SKILL.md

@@ -82,6 +82,15 @@ unsubscribe();
 
 Queries have a time-to-live. Supported values: `'1m'`, `'5m'`, `'10m'` (default), `'15m'`, `'20m'`, `'25m'`, `'30m'`, `'1h'`–`'12h'`, `'1d'`.
 
+### Preloading
+
+`db.preload(query, { signal? })` registers a query without subscribing to it. If
+the server answered this query on this device before (a durable `_00_view` row
+exists) it resolves at once and the rows paint from the local store; otherwise
+it resolves once the server's membership and every record are local. Nothing
+to tear down: the entry is evicted a ttl after registration unless a view mounts
+the same query. `refresh` / `staleTime` are accepted but ignored.
+
 ## Mutations
 
 Mutations are optimistic and automatically synced to the remote SurrealDB instance.
@@ -111,6 +120,19 @@ await client.delete('post', 'post:abc123');
 Use `debounced` option for frequent updates (e.g., live typing):
 - `key: 'recordId'` — Debounce by record ID only (latest write wins, no merge)
 - `key: 'recordId_x_fields'` — Debounce by record ID + changed fields (recommended)
+- `flushOnHide` (default `true`): also keep the merged patch in the local `_00_pending_writes`
+  table and push it as soon as the page is hidden (tab switch, reload, close). A reload or closed
+  tab inside the delay no longer loses the edit: the next boot moves the leftover patch into the
+  outbox. Set `false` for throwaway values (cursor position) to keep the patch in memory only.
+
+### Failed writes
+
+A push the server rejects (permission, validation) is rolled back locally
+(create, update and delete) and moved to the `_00_failed_mutations` tray in the
+same local transaction. Network errors never do this; they retry. Inspect and
+act on the tray with `db.failedMutationCount`, `db.subscribeToFailedMutations(cb)`,
+`db.listFailedMutations()`, `db.retryFailedMutation(id)` (a fresh optimistic
+write) and `db.discardFailedMutation(id)`.
 
 ## Authentication
 
@@ -164,12 +186,15 @@ Backend runs let you trigger server-side HTTP operations via an **outbox pattern
 ### `db.run()` Signature
 
 ```typescript
-db.run<B extends BackendNames<S>, R extends BackendRoutes<S, B>>(
-  backend: B,        // Backend name from sp00ky.yml (e.g., 'api')
-  route: R,          // Route path from OpenAPI spec (e.g., '/spookify')
-  payload: RoutePayload<S, B, R>,  // Typed args for the route
-  options?: RunOptions
-): Promise<void>
+// A method of the client: called as `db.run(backend, route, payload, options)`.
+interface Sp00kyClient<S> {
+  run<B extends BackendNames<S>, R extends BackendRoutes<S, B>>(
+    backend: B, // Backend name from sp00ky.yml (e.g., 'api')
+    route: R, // Route path from OpenAPI spec (e.g., '/spookify')
+    payload: RoutePayload<S, B, R>, // Typed args for the route
+    options?: RunOptions
+  ): Promise<void>;
+}
 ```
 
 All parameters are type-safe — `backend`, `route`, and `payload` are inferred from the generated schema.

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

@@ -71,6 +71,12 @@ interface UpdateOptions {
     key?: 'recordId' | 'recordId_x_fields';
     /** Debounce delay in ms */
     delay?: number;
+    /**
+     * Default true. Keep the merged patch in the local `_00_pending_writes` table and
+     * push it as soon as the page is hidden (tab switch, reload, close), so a reload
+     * inside the delay does not lose it. false: memory only.
+     */
+    flushOnHide?: boolean;
   };
 }
 ```

package/src/boot/auth-flip.saga.test.ts

@@ -0,0 +1,135 @@
+import { describe, expect, it } from 'vitest';
+import { RecordId } from 'surrealdb';
+import { runPure } from '../testing/run-pure';
+import { fakeServices } from '../testing/services';
+import { buildEntry, buildState } from '../testing/build';
+import * as R from '../state/reducers';
+import { defaultEnv } from '../query/env';
+import { authFlip, persistVerifiedUser } from './auth-flip.saga';
+import { queryHashInput } from '../query/hash';
+import { sha256Hex } from '../utils/sha256';
+
+const env = defaultEnv({ tables: [{ name: 'user', columns: { id: {}, email_verified: {} } }] } as any);
+
+describe('authFlip', () => {
+  it('sets identity and $auth, rotates the salt for a new principal before the bucket work, writes the hint, switches, persists the user row', async () => {
+    const released: string[] = [];
+    const svc = fakeServices({
+      'auth.sessionAuthId': () => 'user:abc',
+      'auth.access': () => 'account',
+      'local.currentBucketId': () => 'anon',
+      'local.beginSwitch': () => () => void released.push('gate'),
+      'local.usesSurqlSchema': () => false,
+      'auth.token': () => 'jwt',
+      'auth.currentUser': () => ({ id: new RecordId('user', 'abc'), email_verified: true }),
+    });
+    const state = { ...buildState(), sessionId: 'old', saltUserId: null };
+    const out = await runPure(authFlip(env, 'user:abc'), {
+      state,
+      handlers: { service: svc.handler, 'local.query': () => [], 'local.execute': () => undefined, 'ssp.ingest': () => undefined },
+    });
+    const names = svc.names();
+    expect(names.slice(0, 6)).toEqual(['auth.sessionAuthId', 'auth.access', 'ssp.setSessionAuth', 'crdt.setSessionId', 'hint.write', 'local.currentBucketId']);
+    expect(svc.calls[3]).toEqual(['crdt.setSessionId', ['salt-1']]);
+    expect(svc.calls[4]).toEqual(['hint.write', ['abc']]);
+    expect(names).toContain('local.switchStore');
+    expect(released).toEqual(['gate']);
+    expect(out.state).toMatchObject({ userId: 'user:abc', saltUserId: 'user:abc', sessionId: 'salt-1', bucketId: 'abc' });
+    expect(out.state.versions.get('user:abc')).toBe(1);
+  });
+  it("re-keys active queries under the new principal's salt, so no remote id names the previous principal's view", async () => {
+    const svc = fakeServices({
+      'auth.sessionAuthId': () => 'user:target',
+      'auth.access': () => 'account',
+      'local.currentBucketId': () => 'admin',
+      'local.beginSwitch': () => () => undefined,
+      'local.usesSurqlSchema': () => false,
+      'auth.token': () => 'jwt',
+      'auth.currentUser': () => null,
+    });
+    const def = { surql: 'SELECT * FROM notification', params: {} };
+    const before = await sha256Hex(queryHashInput(def, 'admin-salt'));
+    const state = R.putQuery(
+      buildEntry({ def: { hash: 'q', ...def, id: new RecordId('_00_query', before) }, lifecycle: { phase: 'live', remote: 'registered' } })
+    )({ ...buildState(), sessionId: 'admin-salt', saltUserId: 'user:admin', bucketId: 'admin' });
+    const out = await runPure(authFlip(env, 'user:target'), {
+      state,
+      handlers: {
+        service: svc.handler,
+        'local.getById': () => null,
+        'ssp.register': () => ({ localArray: [], timings: {} }),
+        'local.query': () => [],
+      },
+    });
+    const id = String(out.state.queries.get('q')!.def.id.id);
+    expect(out.state.sessionId).toBe('salt-1');
+    expect(id).toBe(await sha256Hex(queryHashInput(def, 'salt-1')));
+    expect(id).not.toBe(before);
+  });
+  it('a new principal on the same bucket still re-keys its queries', async () => {
+    const svc = fakeServices({
+      'auth.sessionAuthId': () => 'user:b',
+      'auth.access': () => 'account',
+      'local.currentBucketId': () => 'anon',
+      'auth.currentUser': () => null,
+    });
+    const def = { surql: 'SELECT * FROM thing', params: {} };
+    const state = R.putQuery(buildEntry({ def: { hash: 'q', ...def }, lifecycle: { phase: 'live', remote: 'registered' } }))({
+      ...buildState(),
+      sessionId: 'old',
+      saltUserId: 'user:a',
+      bucketId: 'anon',
+    });
+    const out = await runPure(authFlip(env, null), {
+      state,
+      handlers: { service: svc.handler, 'local.getById': () => null, 'ssp.register': () => ({ localArray: [], timings: {} }) },
+    });
+    expect(svc.names()).not.toContain('local.switchStore');
+    expect(String(out.state.queries.get('q')!.def.id.id)).toBe(await sha256Hex(queryHashInput(def, 'salt-1')));
+    expect(out.dispatched.map((d) => d.type)).toContain('EnsureRegistered');
+  });
+  it('same principal on the same bucket: no switch, no salt rotation', async () => {
+    const svc = fakeServices({
+      'auth.sessionAuthId': () => 'user:abc',
+      'auth.access': () => 'account',
+      'local.currentBucketId': () => 'abc',
+      'auth.currentUser': () => null,
+    });
+    const state = { ...buildState(), sessionId: 'keep', saltUserId: 'user:abc', bucketId: 'abc' };
+    const out = await runPure(authFlip(env, 'user:abc'), { state, handlers: { service: svc.handler } });
+    expect(svc.names()).not.toContain('local.switchStore');
+    expect(svc.names()).not.toContain('local.beginSwitch');
+    expect(out.state.sessionId).toBe('keep');
+  });
+});
+
+describe('persistVerifiedUser', () => {
+  it('skips when there is no verified row, an unknown table, or a bare id; writes otherwise and logs failures', async () => {
+    for (const row of [null, { id: 'user:x', a: 1 }, { id: new RecordId('user', 'x') }, { id: new RecordId('nope', 'x'), a: 1 }]) {
+      const svc = fakeServices({ 'auth.currentUser': () => row as any });
+      const out = await runPure(persistVerifiedUser(env), { state: buildState(), handlers: { service: svc.handler } });
+      expect(out.log.filter((e) => e.kind === 'local.execute')).toHaveLength(0);
+    }
+    const svc = fakeServices({ 'auth.currentUser': () => ({ id: new RecordId('user', 'x'), email_verified: true, junk: 1 }) });
+    const s = buildState([buildEntry({ def: { hash: 'q', tableName: 'user' } })], R.setVersions([['user:x', 4]]));
+    const out = await runPure(persistVerifiedUser(env), {
+      state: s,
+      handlers: {
+        service: svc.handler,
+        'local.execute': (e: any) => expect(e.vars.content0).toEqual({ email_verified: true, _00_rv: 4 }),
+        'ssp.ingest': (e: any) => expect(e.records[0].record.junk).toBeUndefined(),
+      },
+    });
+    expect(out.state.dirty.has('q')).toBe(true);
+    const failing = await runPure(persistVerifiedUser(env), {
+      state: s,
+      handlers: {
+        service: svc.handler,
+        'local.execute': () => {
+          throw new Error('locked');
+        },
+      },
+    });
+    expect(failing.emitted).toEqual([expect.objectContaining({ level: 'warn' })]);
+  });
+});

package/src/boot/auth-flip.saga.ts

@@ -0,0 +1,77 @@
+import { RecordId } from 'surrealdb';
+import type { Saga } from '../kernel/saga';
+import { fx } from '../kernel/effects';
+import * as R from '../state/reducers';
+import { bucketIdForUser } from '../modules/ref-tables';
+import type { SagaEnv } from '../query/env';
+import { columnsFor } from '../query/env';
+import * as sql from '../query/sql';
+import { encodeRecordId } from '../utils/index';
+import { cleanRecord } from '../utils/parser';
+import { bucketSwitch, rebindQueries } from './bucket-switch.saga';
+
+/**
+ * The signed-in principal changed (sign-in, sign-out, boot verification).
+ * Identity first (routing and `$auth` for the local SSP), then the salt if
+ * the principal really changed, then the bucket, then the verified user row.
+ *
+ * The salt goes before the bucket because the switch re-keys every active
+ * query (`rebindQueries`) from the salt it finds. A query's remote id hashes
+ * the salt but not the principal, so re-keyed under the old salt it named the
+ * view the previous principal still held, and the SSP refused it as another
+ * identity's (409 `auth_mismatch`) until that view's TTL ran out. On whitepawn
+ * every impersonation start, stop and token lapse refused a tab's queries for
+ * the 10 minutes of that TTL, each refusal a failed sync round, so the rail
+ * read "Can't reach the server" the whole time.
+ */
+export function* authFlip(env: SagaEnv, userId: string | null): Saga<void> {
+  const authId = (yield fx.service('auth.sessionAuthId')) as string | null;
+  const access = (yield fx.service('auth.access')) as string | null;
+  yield fx.state.update(R.setIdentity({ userId }));
+  yield fx.service('ssp.setSessionAuth', authId, access);
+  const saltUserId = (yield fx.state.read((s) => s.saltUserId)) as string | null;
+  const resalted = authId !== saltUserId;
+  if (resalted) {
+    const salt = (yield fx.id('salt')) as string;
+    yield fx.state.update(R.setIdentity({ sessionId: salt, saltUserId: authId }));
+    yield fx.service('crdt.setSessionId', salt);
+  }
+  const target = bucketIdForUser(userId);
+  yield fx.service('hint.write', target);
+  yield fx.state.update(R.setIdentity({ pendingBucket: target }));
+  const current = (yield fx.service('local.currentBucketId')) as string;
+  const release = current === target ? null : ((yield fx.service('local.beginSwitch')) as () => void);
+  yield* bucketSwitch(env, target, release);
+  // No switch means nothing re-keyed the queries under the new salt.
+  if (resalted && current === target) {
+    yield* rebindQueries();
+    yield fx.dispatch({ type: 'EnsureRegistered' });
+  }
+  yield* persistVerifiedUser(env);
+}
+
+/**
+ * Write the user's own row, as the server just returned it, into the local
+ * store so `user` queries see `email_verified` and friends without waiting
+ * for membership. A field refresh, not a version claim.
+ */
+export function* persistVerifiedUser(env: SagaEnv): Saga<void> {
+  const row = (yield fx.service('auth.currentUser')) as Record<string, unknown> | null;
+  if (!row || !(row.id instanceof RecordId) || Object.keys(row).length <= 1) return;
+  const rid = row.id as RecordId<string>;
+  const table = rid.table.name;
+  const columns = columnsFor(env, table);
+  if (!columns) return;
+  const id = encodeRecordId(rid);
+  const version = ((yield fx.state.read((s) => s.versions.get(id))) as number | undefined) || 1;
+  const cleaned = cleanRecord(columns as never, row);
+  const { id: _id, ...content } = cleaned;
+  try {
+    const tx = sql.upsertBodiesTx([{ id: rid, content: { ...content, _00_rv: version } }]);
+    yield fx.local.execute(tx.query, tx.vars);
+    yield fx.ssp.ingest([{ table, op: 'UPDATE', id, record: { ...cleaned, _00_rv: version } }]);
+    yield fx.state.update(R.compose(R.setVersions([[id, version]]), R.markTableDirty(table)));
+  } catch (error) {
+    yield fx.emit({ type: 'log', level: 'warn', message: 'could not persist the verified user row', data: { error } });
+  }
+}