@spooky-sync/core 0.0.1-canary.26 → 0.0.1-canary.261

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "@spooky-sync/core",
-  "version": "0.0.1-canary.26",
+  "version": "0.0.1-canary.261",
   "type": "module",
+  "sideEffects": false,
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "exports": {
@@ -17,12 +18,15 @@
   "scripts": {
     "dev": "tsdown --watch",
     "dev:example": "pnpm dev",
-    "build": "tsdown",
-    "test": "vitest"
+    "build": "tsdown && node scripts/check-broker-bundle.mjs",
+    "test": "vitest",
+    "test:run": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "type-check": "tsc --noEmit"
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/mono424/spooky.git",
+    "url": "https://github.com/mono424/sp00ky.git",
     "directory": "packages/core"
   },
   "keywords": [
@@ -59,15 +63,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.261",
+    "@spooky-sync/ssp-wasm": "0.0.1-canary.261",
+    "@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.0.3"
   },
   "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/skills/{spooky-core → sp00ky-core}/SKILL.md

@@ -1,27 +1,27 @@
 ---
-name: spooky-core
+name: sp00ky-core
 description: >-
-  Core client for the Spooky reactive local-first SurrealDB framework. Use when
-  initializing SpookyClient, registering queries and subscriptions, performing
+  Core client for the Sp00ky reactive local-first SurrealDB framework. Use when
+  initializing Sp00kyClient, registering queries and subscriptions, performing
   mutations (create/update/delete), handling auth (signUp/signIn/signOut),
   working with file buckets, or using backend runs (HTTP outbox pattern).
 metadata:
-  author: spooky-sync
+  author: sp00ky-sync
   version: "0.0.1"
 ---
 
-# Spooky Core
+# Sp00ky Core
 
-`@spooky-sync/core` provides `SpookyClient`, the main entry point for the Spooky framework. It handles local-first data sync with SurrealDB, reactive queries, optimistic mutations, authentication, file storage, and backend runs.
+`@spooky-sync/core` provides `Sp00kyClient`, the main entry point for the Sp00ky framework. It handles local-first data sync with SurrealDB, reactive queries, optimistic mutations, authentication, file storage, and backend runs.
 
 ## Initialization
 
 ```typescript
-import { SpookyClient } from '@spooky-sync/core';
+import { Sp00kyClient } from '@spooky-sync/core';
 import { schema } from './generated/schema'; // Generated by `spooky generate`
 import schemaSurql from './generated/schema.surql?raw';
 
-const client = new SpookyClient({
+const client = new Sp00kyClient({
   database: {
     endpoint: 'ws://localhost:8000',
     namespace: 'my_ns',
@@ -40,7 +40,7 @@ await client.init();
 await client.close();
 ```
 
-### SpookyConfig Options
+### Sp00kyConfig Options
 
 See [references/config.md](references/config.md) for all configuration options.
 
@@ -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.
@@ -112,6 +121,15 @@ 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)
 
+### 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
 
 See [references/auth.md](references/auth.md) for the full auth API.
@@ -159,13 +177,13 @@ Buckets must be defined in the schema under the `buckets` array.
 
 ## Backend Runs (HTTP Outbox)
 
-Backend runs let you trigger server-side HTTP operations via an **outbox pattern**. When you call `db.run()`, it creates a job record in a local outbox table. That record syncs to remote SurrealDB, where the Spooky Sync Platform (SSP) picks it up and calls your backend HTTP API. The result status is written back to the job record and syncs to the client reactively.
+Backend runs let you trigger server-side HTTP operations via an **outbox pattern**. When you call `db.run()`, it creates a job record in a local outbox table. That record syncs to remote SurrealDB, where the Sp00ky Sync Platform (SSP) picks it up and calls your backend HTTP API. The result status is written back to the job record and syncs to the client reactively.
 
 ### `db.run()` Signature
 
 ```typescript
 db.run<B extends BackendNames<S>, R extends BackendRoutes<S, B>>(
-  backend: B,        // Backend name from spooky.yml (e.g., 'api')
+  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
@@ -192,7 +210,7 @@ The `assignedTo` option is how you link a job to an entity. Passing a record ID:
 
 ### Full Example
 
-**1. Configure the backend in `spooky.yml`:**
+**1. Configure the backend in `sp00ky.yml`:**
 
 ```yaml
 backends:

package/skills/{spooky-core → sp00ky-core}/references/auth.md

@@ -2,7 +2,7 @@
 
 ## AuthService API
 
-The `AuthService` is available on `SpookyClient` as `client.auth`.
+The `AuthService` is available on `Sp00kyClient` as `client.auth`.
 
 ### Properties
 

package/skills/{spooky-core → sp00ky-core}/references/config.md

@@ -1,7 +1,7 @@
-# SpookyConfig Reference
+# Sp00kyConfig Reference
 
 ```typescript
-interface SpookyConfig<S extends SchemaStructure> {
+interface Sp00kyConfig<S extends SchemaStructure> {
   database: {
     /** SurrealDB WebSocket endpoint URL */
     endpoint?: string;

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

@@ -0,0 +1,82 @@
+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';
+
+const env = defaultEnv({ tables: [{ name: 'user', columns: { id: {}, email_verified: {} } }] } as any);
+
+describe('authFlip', () => {
+  it('sets identity and $auth before the bucket work, writes the hint, switches, rotates the salt for a new principal, 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, 5)).toEqual(['auth.sessionAuthId', 'auth.access', 'ssp.setSessionAuth', 'hint.write', 'local.currentBucketId']);
+    expect(svc.calls[3]).toEqual(['hint.write', ['abc']]);
+    expect(names).toContain('local.switchStore');
+    expect(names).toContain('crdt.setSessionId');
+    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('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,62 @@
+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 } 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 bucket,
+ * then the salt if the principal really changed, then the verified user row.
+ */
+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 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);
+  const saltUserId = (yield fx.state.read((s) => s.saltUserId)) as string | null;
+  if (authId !== saltUserId) {
+    const salt = (yield fx.id('salt')) as string;
+    yield fx.state.update(R.setIdentity({ sessionId: salt, saltUserId: authId }));
+    yield fx.service('crdt.setSessionId', salt);
+  }
+  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 = String(rid.table);
+  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 } });
+  }
+}

package/src/boot/boot.saga.test.ts

@@ -0,0 +1,151 @@
+import { describe, expect, it } from 'vitest';
+import { RecordId } from 'surrealdb';
+import { runPure } from '../testing/run-pure';
+import { fakeServices } from '../testing/services';
+import { buildEntry, buildOutboxItem, buildState } from '../testing/build';
+import * as R from '../state/reducers';
+import { defaultEnv } from '../query/env';
+import { boot, migrateWindowToView, pageHide, primeCircuit, startRemote, versionsPrimed, warmBlobs } from './boot.saga';
+
+const env = defaultEnv({ tables: [] } as any);
+
+describe('boot', () => {
+  it('solo: opens the hinted bucket, provisions, starts the SSP, restores the session, mirrors the outbox, flips localReady, hands off to the network', async () => {
+    const svc = fakeServices({
+      'hint.read': () => 'u1',
+      'local.usesSurqlSchema': () => true,
+      'auth.restoreSession': async () => 'user:u1',
+      'auth.sessionAuthId': () => 'user:u1',
+      'auth.access': () => 'account',
+    });
+    const out = await runPure(boot(env, { sharedTabs: false }), {
+      handlers: { service: svc.handler, 'local.query': (e: any) => (e.sql.startsWith('SELECT count()') ? [[{ count: 1 }]] : []) },
+    });
+    expect(svc.names()).toEqual([
+      'hint.read',
+      'local.connect',
+      'local.usesSurqlSchema',
+      'migrator.provision',
+      'ssp.init',
+      'ssp.setPermissions',
+      'auth.restoreSession',
+      'auth.sessionAuthId',
+      'crdt.setSessionId',
+      'auth.access',
+      'ssp.setSessionAuth',
+      'window.attach',
+      'features.init',
+      'releases.init',
+    ]);
+    expect(svc.calls[1]).toEqual(['local.connect', ['u1']]);
+    expect(out.state).toMatchObject({ bucketId: 'u1', userId: 'user:u1', saltUserId: 'user:u1', sessionId: 'salt-1', localReady: true });
+    expect(out.dispatched.map((d) => d.type)).toEqual(['WarmBlobs', 'PrimeCircuit', 'LifecycleTick', 'GcTick', 'StartRemote']);
+    expect(svc.names()).not.toContain('remote.connect');
+  });
+  it('shared tabs: takes the role from the coordinator, or falls back to solo; schemaless engines skip provisioning; anonymous skips session auth', async () => {
+    const leader = fakeServices({ 'hint.read': () => null, 'tabs.start': async () => 'leader', 'local.usesSurqlSchema': () => false, 'auth.restoreSession': async () => null, 'auth.sessionAuthId': () => null });
+    const out = await runPure(boot(env, { sharedTabs: true }), { handlers: { service: leader.handler, 'local.query': () => [] } });
+    expect(out.state.tabRole).toBe('leader');
+    expect(out.state.bucketId).toBe('anon');
+    expect(leader.names()).not.toContain('local.connect');
+    expect(leader.names()).not.toContain('migrator.provision');
+    expect(leader.names()).not.toContain('ssp.setSessionAuth');
+    const fallback = fakeServices({
+      'hint.read': () => 'x',
+      'tabs.start': async () => {
+        throw new Error('no broker');
+      },
+      'local.usesSurqlSchema': () => false,
+      'auth.restoreSession': async () => null,
+      'auth.sessionAuthId': () => null,
+    });
+    const fb = await runPure(boot(env, { sharedTabs: true }), { handlers: { service: fallback.handler, 'local.query': () => [] } });
+    expect(fallback.calls).toContainEqual(['local.connect', ['x']]);
+    expect(fb.emitted).toContainEqual(expect.objectContaining({ level: 'warn' }));
+  });
+});
+
+describe('migrateWindowToView', () => {
+  it('copies legacy rows once, skips when _00_view has rows, tolerates errors and junk', async () => {
+    const upserts: any[] = [];
+    await runPure(migrateWindowToView(), {
+      handlers: {
+        'local.query': (e: any) =>
+          e.sql.startsWith('SELECT count()')
+            ? [[]]
+            : [[{ id: '_00_window:k1', ids: [['t:1', 1]], confirmed: true, updatedAt: 5 }, { id: new RecordId('_00_window', 'k2'), ids: [] }, { id: 'x', ids: 'bad' }, { ids: [] }]],
+        'local.upsert': (e: any) => void upserts.push(e),
+      },
+    });
+    expect(upserts).toEqual([
+      { kind: 'local.upsert', table: '_00_view', id: new RecordId('_00_view', 'k1'), data: { ids: [['t:1', 1]], confirmed: true, updatedAt: 5 }, mode: 'replace' },
+      { kind: 'local.upsert', table: '_00_view', id: new RecordId('_00_view', 'k2'), data: { ids: [], confirmed: false, updatedAt: 0 }, mode: 'replace' },
+    ]);
+    const skipped = await runPure(migrateWindowToView(), { handlers: { 'local.query': () => [[{ count: 3 }]] } });
+    expect(skipped.log.filter((e) => e.kind === 'local.query')).toHaveLength(1);
+    const failing = await runPure(migrateWindowToView(), {
+      handlers: {
+        'local.query': () => {
+          throw new Error('no table');
+        },
+      },
+    });
+    expect(failing.emitted).toEqual([expect.objectContaining({ level: 'debug' })]);
+  });
+});
+
+describe('startRemote / primeCircuit / versionsPrimed / pageHide / warmBlobs', () => {
+  it('startRemote tolerates connect and auth failures and starts the loops', async () => {
+    const svc = fakeServices({
+      'remote.connect': async () => {
+        throw new Error('offline');
+      },
+      'auth.init': async () => {
+        throw new Error('401');
+      },
+    });
+    const out = await runPure(startRemote(), { handlers: { service: svc.handler } });
+    expect(svc.names()).toEqual(['remote.connect', 'supervisor.start', 'auth.init']);
+    expect(out.emitted.filter((e) => e.type === 'log')).toHaveLength(2);
+    expect(out.dispatched.map((d) => d.type)).toEqual(['EnsureRegistered', 'LiveStart', 'PollTick', 'Drain']);
+    const ok = await runPure(startRemote(), { handlers: { service: fakeServices().handler } });
+    expect(ok.emitted).toEqual([]);
+  });
+  it('primeCircuit passes outbox ids and always flips primed', async () => {
+    const svc = fakeServices({ 'ssp.prime': async () => undefined });
+    const s = buildState([], R.outboxReplace([buildOutboxItem({ recordId: 'thing:1' })]));
+    const out = await runPure(primeCircuit(), { state: s, handlers: { service: svc.handler } });
+    expect(svc.calls).toEqual([['ssp.prime', [['thing:1']]]]);
+    expect(out.state.primed).toBe(true);
+    const failing = fakeServices({
+      'ssp.prime': async () => {
+        throw new Error('snapshot');
+      },
+    });
+    const f = await runPure(primeCircuit(), { state: buildState(), handlers: { service: failing.handler } });
+    expect(f.state.primed).toBe(true);
+    expect(f.emitted).toEqual([expect.objectContaining({ level: 'warn' })]);
+  });
+  it('versionsPrimed records versions; pageHide releases registered views; warmBlobs is best-effort', async () => {
+    const v = await runPure(versionsPrimed([['thing:1', 3]]), { state: buildState() });
+    expect(v.state.versions.get('thing:1')).toBe(3);
+    const svc = fakeServices();
+    const s = buildState([buildEntry({ def: { hash: 'a' }, lifecycle: { remote: 'registered' } }), buildEntry({ def: { hash: 'b' } })]);
+    await runPure(pageHide(), { state: s, handlers: { service: svc.handler } });
+    expect(svc.calls).toEqual([['remote.releaseViews', [[new RecordId('_00_query', 'a')]]]]);
+    const none = fakeServices();
+    await runPure(pageHide(), { state: buildState(), handlers: { service: none.handler } });
+    expect(none.calls).toEqual([]);
+    const blobs = fakeServices({
+      'blobs.start': async () => {
+        throw new Error('opfs');
+      },
+    });
+    const w = await runPure(warmBlobs(), { state: { ...buildState(), bucketId: 'u9' }, handlers: { service: blobs.handler } });
+    expect(blobs.calls).toEqual([['blobs.start', ['u9']]]);
+    expect(w.emitted).toEqual([expect.objectContaining({ level: 'warn' })]);
+    const anon = fakeServices({ 'blobs.start': async () => undefined });
+    await runPure(warmBlobs(), { state: buildState(), handlers: { service: anon.handler } });
+    expect(anon.calls).toEqual([['blobs.start', ['anon']]]);
+  });
+});

package/src/boot/boot.saga.ts

@@ -0,0 +1,128 @@
+import type { Saga } from '../kernel/saga';
+import { fx } from '../kernel/effects';
+import type { ClientState } from '../state/client-state';
+import * as R from '../state/reducers';
+import { ANON_USER_ID } from '../modules/ref-tables';
+import type { SagaEnv } from '../query/env';
+import * as sql from '../query/sql';
+import { loadOutbox } from '../mutation/push.saga';
+
+export interface BootOptions {
+  /** A shared-tabs coordinator is available: ask it for a role instead of opening the store alone. */
+  sharedTabs: boolean;
+}
+
+/**
+ * Local boot. Everything awaited here is network-free: the store opens,
+ * the schema provisions, the SSP starts, the session is restored from the
+ * cached token, the outbox is mirrored. `localReady` flips at the end and
+ * the network half runs in the background (`startRemote`).
+ */
+export function* boot(env: SagaEnv, opts: BootOptions): Saga<void> {
+  const bucket = ((yield fx.service('hint.read')) as string | null) ?? ANON_USER_ID;
+  let shared = false;
+  if (opts.sharedTabs) {
+    try {
+      const role = (yield fx.service('tabs.start', bucket)) as ClientState['tabRole'];
+      yield fx.state.update(R.setTabRole(role));
+      shared = true;
+    } catch (error) {
+      yield fx.emit({ type: 'log', level: 'warn', message: 'shared tabs unavailable; booting solo', data: { error } });
+    }
+  }
+  if (!shared) yield fx.service('local.connect', bucket);
+  yield fx.state.update(R.setIdentity({ bucketId: bucket }));
+  if ((yield fx.service('local.usesSurqlSchema')) as boolean) yield fx.service('migrator.provision');
+  yield* migrateWindowToView();
+  yield fx.dispatch({ type: 'WarmBlobs' });
+  yield fx.service('ssp.init');
+  yield fx.service('ssp.setPermissions');
+  yield fx.dispatch({ type: 'PrimeCircuit' });
+
+  const restoredUserId = (yield fx.service('auth.restoreSession')) as string | null;
+  const salt = (yield fx.id('salt')) as string;
+  const authId = (yield fx.service('auth.sessionAuthId')) as string | null;
+  yield fx.state.update(R.setIdentity({ sessionId: salt, userId: restoredUserId, saltUserId: authId }));
+  yield fx.service('crdt.setSessionId', salt);
+  if (restoredUserId) yield fx.service('ssp.setSessionAuth', authId, (yield fx.service('auth.access')) as string | null);
+
+  yield* loadOutbox(env);
+  yield fx.service('window.attach');
+  yield fx.service('features.init');
+  yield fx.service('releases.init');
+  yield fx.dispatch({ type: 'LifecycleTick' });
+  yield fx.dispatch({ type: 'GcTick' });
+  yield fx.state.update(R.setIdentity({ localReady: true }));
+  yield fx.dispatch({ type: 'StartRemote' });
+}
+
+/** One-time copy of the legacy `_00_window` rows into `_00_view`. */
+export function* migrateWindowToView(): Saga<void> {
+  try {
+    const countRes = (yield fx.local.query(sql.countViewRows())) as unknown[];
+    const countRow = Array.isArray(countRes?.[0]) ? (countRes[0] as Array<{ count?: number }>)[0] : undefined;
+    if ((countRow?.count ?? 0) > 0) return;
+    const legacy = (yield fx.local.query(sql.readLegacyViewRows())) as unknown[];
+    const rows = Array.isArray(legacy?.[0]) ? (legacy[0] as Array<Record<string, unknown>>) : [];
+    for (const row of rows) {
+      const key = typeof row.id === 'string' ? row.id.slice(row.id.indexOf(':') + 1) : String((row.id as { id?: unknown })?.id ?? '');
+      if (!key || !Array.isArray(row.ids)) continue;
+      yield fx.local.upsert(sql.VIEW_TABLE, sql.viewRecordId(key), { ids: row.ids, confirmed: row.confirmed === true, updatedAt: row.updatedAt ?? 0 }, 'replace');
+    }
+  } catch (error) {
+    yield fx.emit({ type: 'log', level: 'debug', message: 'window -> view migration skipped', data: { error } });
+  }
+}
+
+/**
+ * The network half of boot: connect, verify the restored session, then let
+ * membership, LIVE, the poll and the outbox start. Every step is best-effort.
+ */
+export function* startRemote(): Saga<void> {
+  try {
+    yield fx.service('remote.connect');
+  } catch (error) {
+    yield fx.emit({ type: 'log', level: 'warn', message: 'remote connect failed; running from the local store', data: { error } });
+  }
+  yield fx.service('supervisor.start');
+  try {
+    yield fx.service('auth.init');
+  } catch (error) {
+    yield fx.emit({ type: 'log', level: 'warn', message: 'auth verification failed; keeping the restored session', data: { error } });
+  }
+  yield fx.dispatch({ type: 'EnsureRegistered' });
+  yield fx.dispatch({ type: 'LiveStart' });
+  yield fx.dispatch({ type: 'PollTick' });
+  yield fx.dispatch({ type: 'Drain' });
+}
+
+/** Fill the circuit from the local store; `primed` flips even on failure so fetches never hang. */
+export function* primeCircuit(): Saga<void> {
+  const pending = (yield fx.state.read((s) => s.outbox.map((i) => i.recordId))) as string[];
+  try {
+    yield fx.service('ssp.prime', pending);
+  } catch (error) {
+    yield fx.emit({ type: 'log', level: 'warn', message: 'circuit prime failed; starting empty', data: { error } });
+  } finally {
+    yield fx.state.update(R.setIdentity({ primed: true }));
+  }
+}
+
+export function* versionsPrimed(entries: Array<readonly [string, number]>): Saga<void> {
+  yield fx.state.update(R.setVersions(entries));
+}
+
+/** Hand this tab's views back to the server when the page goes away for good. */
+export function* pageHide(): Saga<void> {
+  const ids = (yield fx.state.read((s) => [...s.queries.values()].filter((e) => e.lifecycle.remote === 'registered').map((e) => e.def.id))) as unknown[];
+  if (ids.length > 0) yield fx.service('remote.releaseViews', ids);
+}
+
+export function* warmBlobs(): Saga<void> {
+  const bucket = ((yield fx.state.read((s) => s.bucketId)) as string | null) ?? ANON_USER_ID;
+  try {
+    yield fx.service('blobs.start', bucket);
+  } catch (error) {
+    yield fx.emit({ type: 'log', level: 'warn', message: 'blob cache failed to start', data: { error } });
+  }
+}