@spooky-sync/core 0.0.1-canary.31 → 0.0.1-canary.310

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

@@ -0,0 +1,158 @@
+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 }]] : e.sql === 'SELECT * FROM _00_view' ? [[{ id: '_00_view:k', ids: [['t:1', 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', 'AdoptPendingWrites', 'LifecycleTick', 'StartRemote']);
+    // The view index is loaded before anything can paint; the first GC waits out the boot.
+    expect(out.state.views).toEqual(new Map([['k', ['t:1']]]));
+    expect(out.timers.get('gc')).toEqual({ ms: 30_000, event: { type: 'GcTick' } });
+    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,131 @@
+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';
+import { loadViews } from '../query/lifecycle.saga';
+import { GC_BOOT_DELAY_MS } from '../kernel/constants';
+
+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* loadViews();
+  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.timer.set('gc', GC_BOOT_DELAY_MS, { 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 } });
+  }
+}

package/src/boot/bucket-switch.saga.test.ts

@@ -0,0 +1,187 @@
+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 { bucketSwitch, dropImpersonatedBucket, rebindQueries } from './bucket-switch.saga';
+
+const env = defaultEnv({ tables: [] } as any);
+const base = (over: Partial<ReturnType<typeof buildState>> = {}) => ({ ...buildState(), pendingBucket: 'u2', bucketId: 'u1', ...over });
+
+describe('bucketSwitch', () => {
+  it('steps aside when superseded or already on target (releasing the gate)', async () => {
+    const released: number[] = [];
+    const svc = fakeServices({ 'local.currentBucketId': () => 'u1' });
+    await runPure(bucketSwitch(env, 'u2', () => void released.push(1)), { state: { ...base(), pendingBucket: 'u3' }, handlers: { service: svc.handler } });
+    await runPure(bucketSwitch(env, 'u1', () => void released.push(2)), { state: base({ pendingBucket: 'u1' }), handlers: { service: svc.handler } });
+    expect(released).toEqual([1, 2]);
+    expect(svc.names()).toEqual(['local.currentBucketId', 'local.currentBucketId']);
+  });
+  it('solo: drain, swap, provision, blobs, SSP reset, prime, token, rebind, outbox, re-register', async () => {
+    const svc = fakeServices({
+      'local.currentBucketId': () => 'u1',
+      'local.beginSwitch': () => () => undefined,
+      'local.usesSurqlSchema': () => true,
+      'auth.sessionAuthId': () => 'user:u2',
+      'auth.access': () => 'account',
+      'auth.token': () => 'jwt',
+    });
+    const s = base();
+    const withQ = R.compose(
+      R.putQuery(buildEntry({ def: { hash: 'a', viewKey: 'vk', surql: 'SELECT * FROM thing' }, lifecycle: { phase: 'live', remote: 'registered' }, remoteArray: [['t:1', 1]] })),
+      R.outboxReplace([buildOutboxItem()]),
+      R.setVersions([['t:1', 1]]),
+      R.markMembershipDirty(['a'])
+    )({ ...s, sessionId: 'sess2' });
+    const out = await runPure(bucketSwitch(env, 'u2'), {
+      state: withQ,
+      handlers: {
+        service: svc.handler,
+        'local.getById': () => ({ ids: [['t:9', 1]], confirmed: true }),
+        'ssp.register': () => ({ localArray: [['t:9', 1]], timings: {} }),
+        'local.query': () => [],
+      },
+    });
+    expect(svc.names()).toEqual([
+      'local.currentBucketId',
+      'local.beginSwitch',
+      'crdt.closeAll',
+      'local.switchStore',
+      'local.usesSurqlSchema',
+      'migrator.provision',
+      'blobs.setNamespace',
+      'ssp.reset',
+      'ssp.setPermissions',
+      'auth.sessionAuthId',
+      'auth.access',
+      'ssp.setSessionAuth',
+      'auth.consumeEndedImpersonation',
+      'auth.token',
+      'persistence.set',
+    ]);
+    expect(out.log.filter((e) => e.kind === 'timer.clear').map((e) => (e as any).key)).toEqual(['poll', 'outbox', 'membership', 'fetch', 'ack-prune']);
+    expect(out.state).toMatchObject({ bucketId: 'u2', primed: false, outbox: [] });
+    expect(out.state.versions.size).toBe(0);
+    expect(out.state.membershipDirty.size).toBe(0);
+    const e = out.state.queries.get('a')!;
+    expect(e.lifecycle).toMatchObject({ phase: 'cached', remote: 'unregistered' });
+    expect(e.remoteArray).toEqual([['t:9', 1]]);
+    expect(e.localArray).toEqual([['t:9', 1]]);
+    expect(String(e.def.id.table)).toBe('_00_query');
+    // PollTick is load-bearing: the switch cleared the poll timer, and only the
+    // tick re-arms it, so a sign-in without it leaves the client on LIVE alone.
+    expect(out.dispatched.map((d) => d.type)).toEqual(['PrimeCircuit', 'AdoptPendingWrites', 'EnsureRegistered', 'LiveStart', 'PollTick', 'Drain']);
+  });
+  it('shared tabs: moves namespaces, falls back to solo on failure; blob clear on sign-out; failures are logged and the gate always reopens', async () => {
+    let gateReleased = false;
+    const moved = fakeServices({
+      'local.currentBucketId': () => 'u1',
+      'tabs.moveToBucket': async () => 'follower',
+      'auth.sessionAuthId': () => null,
+      'auth.access': () => null,
+      'auth.token': () => null,
+    });
+    const out = await runPure(bucketSwitch(env, 'u2', () => void (gateReleased = true)), {
+      state: { ...base(), tabRole: 'leader' },
+      handlers: { service: moved.handler, 'local.query': () => [] },
+    });
+    expect(out.state.tabRole).toBe('follower');
+    expect(gateReleased).toBe(true);
+    expect(moved.names()).not.toContain('local.switchStore');
+    const failing = fakeServices({
+      'local.currentBucketId': () => 'u1',
+      'local.beginSwitch': () => () => undefined,
+      'tabs.moveToBucket': async () => {
+        throw new Error('broker');
+      },
+      'auth.sessionAuthId': () => null,
+      'auth.access': () => null,
+      'auth.token': () => 'jwt',
+      'persistence.set': async () => {
+        throw new Error('kv');
+      },
+      'blobs.setNamespace': async () => {
+        throw new Error('opfs');
+      },
+    });
+    const fb = await runPure(bucketSwitch(env, 'anon', null, { clearBlobsOnSignOut: true }), {
+      state: { ...base({ pendingBucket: 'anon' }), tabRole: 'leader' },
+      handlers: { service: failing.handler, 'local.query': () => [] },
+    });
+    expect(fb.state.tabRole).toBe('solo');
+    expect(failing.names()).toContain('local.beginSwitch');
+    expect(failing.names()).toContain('ssp.setPersistence');
+    expect(failing.names()).toContain('blobs.clear');
+    expect(fb.emitted.filter((e) => e.type === 'log')).toHaveLength(3);
+  });
+  it('a failing swap still reopens the gate and rethrows', async () => {
+    let released = false;
+    const svc = fakeServices({
+      'local.currentBucketId': () => 'u1',
+      'local.switchStore': async () => {
+        throw new Error('disk');
+      },
+    });
+    await expect(runPure(bucketSwitch(env, 'u2', () => void (released = true)), { state: base(), handlers: { service: svc.handler } })).rejects.toThrow('disk');
+    expect(released).toBe(true);
+  });
+});
+
+describe('dropImpersonatedBucket', () => {
+  it('drops the bucket it just left when that was the impersonated user', async () => {
+    const svc = fakeServices({ 'auth.consumeEndedImpersonation': () => 'user:bob' });
+    await runPure(dropImpersonatedBucket('bob'), { state: buildState(), handlers: { service: svc.handler } });
+    expect(svc.calls).toEqual([
+      ['auth.consumeEndedImpersonation', []],
+      ['local.dropBucket', ['bob']],
+    ]);
+  });
+  it('leaves every other bucket alone', async () => {
+    for (const [ended, left] of [[null, 'bob'], ['user:bob', 'alice'], ['user:bob', 'anon']] as const) {
+      const svc = fakeServices({ 'auth.consumeEndedImpersonation': () => ended });
+      await runPure(dropImpersonatedBucket(left), { state: buildState(), handlers: { service: svc.handler } });
+      expect(svc.names()).toEqual(['auth.consumeEndedImpersonation']);
+    }
+  });
+  it('logs a failed delete instead of failing the switch', async () => {
+    const svc = fakeServices({
+      'auth.consumeEndedImpersonation': () => 'user:bob',
+      'local.dropBucket': async () => {
+        throw new Error('handles still open');
+      },
+    });
+    const out = await runPure(dropImpersonatedBucket('bob'), { state: buildState(), handlers: { service: svc.handler } });
+    expect(out.emitted.filter((e) => e.type === 'log')).toHaveLength(1);
+  });
+});
+
+describe('rebindQueries', () => {
+  it('re-seeds from the new store, rebuilds the local view (tolerating failures), emits authority flips', async () => {
+    const s = R.compose(
+      R.putQuery(buildEntry({ def: { hash: 'a' }, lifecycle: { phase: 'live' } })),
+      R.putQuery(buildEntry({ def: { hash: 'b' }, lifecycle: { phase: 'cold' } }))
+    )({ ...buildState(), sessionId: 's' });
+    const out = await runPure(rebindQueries(), {
+      state: s,
+      handlers: {
+        'local.getById': (e: any) => {
+          if (String((e.id as RecordId).id) === 'view-b') return { ids: [['t:1', 1]], confirmed: true };
+          throw new Error('missing');
+        },
+        'ssp.register': (e: any) => {
+          if (e.plan.queryHash === 'a') throw new Error('wasm');
+          return { localArray: [['t:1', 1]], timings: {} };
+        },
+      },
+    });
+    expect(out.state.queries.get('a')!.lifecycle.phase).toBe('cold');
+    expect(out.state.queries.get('b')!.lifecycle.phase).toBe('cached');
+    expect(out.emitted.filter((e) => e.type === 'query:authority')).toEqual([
+      { type: 'query:authority', hash: 'a', known: false },
+      { type: 'query:authority', hash: 'b', known: true },
+    ]);
+    expect(out.emitted.some((e) => e.type === 'log')).toBe(true);
+  });
+});

package/src/boot/bucket-switch.saga.ts

@@ -0,0 +1,133 @@
+import { RecordId } from 'surrealdb';
+import type { Saga } from '../kernel/saga';
+import type { RegisterResult } from '../kernel/effects';
+import { fx } from '../kernel/effects';
+import type { ClientState, QueryEntry } from '../state/client-state';
+import { seedLifecycle, isAuthoritative } from '../state/lifecycle';
+import * as R from '../state/reducers';
+import { ANON_USER_ID, bucketIdForUser } from '../modules/ref-tables';
+import type { SagaEnv } from '../query/env';
+import { queryHashInput } from '../query/hash';
+import { isResolvedBefore, parseViewRow } from '../query/membership';
+import * as sql from '../query/sql';
+import { loadViews } from '../query/lifecycle.saga';
+import { loadOutbox } from '../mutation/push.saga';
+
+export interface BucketSwitchOptions {
+  clearBlobsOnSignOut: boolean;
+}
+
+/**
+ * Move the client to another user's local store: drain, swap, rebind.
+ * Runs on the serial `bucket` lane; a switch that wakes up to a newer
+ * `pendingBucket` steps aside. Every active query keeps its hash and is
+ * re-seeded from the new store's `_00_view` rows, then re-registered.
+ */
+export function* bucketSwitch(env: SagaEnv, target: string, release: (() => void) | null = null, opts: BucketSwitchOptions = { clearBlobsOnSignOut: false }): Saga<void> {
+  const state = (yield fx.state.read((s) => s)) as ClientState;
+  const current = (yield fx.service('local.currentBucketId')) as string;
+  if (state.pendingBucket !== target || current === target) {
+    release?.();
+    return;
+  }
+  const gate = release ?? ((yield fx.service('local.beginSwitch')) as () => void);
+  for (const key of ['poll', 'outbox', 'membership', 'fetch', 'ack-prune']) yield fx.timer.clear(key);
+  yield fx.state.update(R.clearBucketState());
+  yield fx.service('crdt.closeAll', false);
+  try {
+    if (state.tabRole !== 'solo') {
+      try {
+        const role = (yield fx.service('tabs.moveToBucket', target)) as ClientState['tabRole'];
+        yield fx.state.update(R.setTabRole(role));
+      } catch (error) {
+        yield fx.emit({ type: 'log', level: 'warn', message: 'shared-tabs bucket move failed; switching solo', data: { error } });
+        yield fx.state.update(R.setTabRole('solo'));
+        yield fx.service('ssp.setPersistence', true);
+        yield fx.service('local.switchStore', target);
+      }
+    } else {
+      yield fx.service('local.switchStore', target);
+      if ((yield fx.service('local.usesSurqlSchema')) as boolean) yield fx.service('migrator.provision');
+    }
+    try {
+      if (opts.clearBlobsOnSignOut && target === ANON_USER_ID && current !== ANON_USER_ID) yield fx.service('blobs.clear');
+      yield fx.service('blobs.setNamespace', target);
+    } catch (error) {
+      yield fx.emit({ type: 'log', level: 'warn', message: 'blob cache bucket switch failed', data: { error } });
+    }
+    yield fx.service('ssp.reset');
+    yield fx.service('ssp.setPermissions');
+    yield fx.service('ssp.setSessionAuth', (yield fx.service('auth.sessionAuthId')) as string | null, (yield fx.service('auth.access')) as string | null);
+    yield fx.state.update(R.setIdentity({ bucketId: target }));
+    yield fx.dispatch({ type: 'PrimeCircuit' });
+  } finally {
+    gate();
+  }
+  yield* dropImpersonatedBucket(current);
+  const token = (yield fx.service('auth.token')) as string | null;
+  if (token) {
+    try {
+      yield fx.service('persistence.set', 'sp00ky_auth_token', token);
+    } catch (error) {
+      yield fx.emit({ type: 'log', level: 'warn', message: 'failed to re-persist the auth token', data: { error } });
+    }
+  }
+  yield* loadViews();
+  yield* rebindQueries();
+  yield* loadOutbox(env);
+  yield fx.dispatch({ type: 'EnsureRegistered' });
+  yield fx.dispatch({ type: 'LiveStart' });
+  // The switch cleared the poll timer, and only the tick itself re-arms it: a
+  // sign-in (auth flip -> bucket switch) otherwise left the client running on
+  // LIVE alone for the rest of the session, so any membership change LIVE did
+  // not deliver was never noticed.
+  yield fx.dispatch({ type: 'PollTick' });
+  yield fx.dispatch({ type: 'Drain' });
+}
+
+/**
+ * An impersonation just ended and this switch left its bucket: delete that
+ * user's local data from the admin's device. Best-effort; a failure only
+ * leaves rows the server already let this admin read.
+ */
+export function* dropImpersonatedBucket(left: string): Saga<void> {
+  const ended = (yield fx.service('auth.consumeEndedImpersonation')) as string | null;
+  if (!ended || left === ANON_USER_ID || bucketIdForUser(ended) !== left) return;
+  try {
+    yield fx.service('local.dropBucket', left);
+  } catch (error) {
+    yield fx.emit({ type: 'log', level: 'warn', message: 'could not delete the impersonated bucket', data: { bucket: left, error } });
+  }
+}
+
+/** Re-seed every active query from the new store and rebuild its SSP view. */
+export function* rebindQueries(): Saga<void> {
+  const [entries, sessionId] = (yield fx.state.read((s) => [[...s.queries.values()], s.sessionId])) as [QueryEntry[], string | null];
+  for (const entry of entries) {
+    let view: ReturnType<typeof parseViewRow> = null;
+    try {
+      view = parseViewRow(yield fx.local.getById(sql.VIEW_TABLE, sql.viewRecordId(entry.def.viewKey)));
+    } catch {
+      view = null;
+    }
+    const hash = (yield fx.hash(queryHashInput({ surql: entry.def.surql, params: entry.def.params as Record<string, unknown> }, sessionId))) as string;
+    let localArray: QueryEntry['localArray'] = [];
+    try {
+      const reg = (yield fx.ssp.register({
+        queryHash: entry.def.hash,
+        surql: entry.def.surql,
+        params: entry.def.params as Record<string, unknown>,
+        ttl: entry.def.ttl,
+        tableName: entry.def.tableName,
+      })) as RegisterResult;
+      localArray = reg.localArray;
+    } catch (error) {
+      yield fx.emit({ type: 'log', level: 'warn', message: 'local view rebuild failed after bucket switch', data: { hash: entry.def.hash, error } });
+    }
+    const lifecycle = seedLifecycle(isResolvedBefore(view));
+    yield fx.state.update(R.rebindQuery(entry.def.hash, { id: new RecordId('_00_query', hash), lifecycle, remoteArray: view?.ids ?? [], localArray }));
+    if (isAuthoritative(entry.lifecycle) !== isAuthoritative(lifecycle)) {
+      yield fx.emit({ type: 'query:authority', hash: entry.def.hash, known: isAuthoritative(lifecycle) });
+    }
+  }
+}

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

@@ -0,0 +1,51 @@
+import { describe, expect, it } from 'vitest';
+import { runPure, sha256Hex } from '../testing/run-pure';
+import { buildEntry, buildState } from '../testing/build';
+import * as R from '../state/reducers';
+import { defaultEnv } from '../query/env';
+import { queryHashInput } from '../query/hash';
+import { preload, PreloadFailedError } from './preload.saga';
+
+const env = defaultEnv({ tables: [{ name: 'thing', columns: {} }] } as any);
+const input = { tableName: 'thing', surql: 'SELECT * FROM thing', params: {}, ttl: '10m' as const };
+const sspOk = () => ({ localArray: [], timings: { parseMs: 0, planMs: 0, snapshotMs: 0, wallMs: 0 } });
+
+describe('preload', () => {
+  it('resolved before: returns without waiting and with no remote effect', async () => {
+    const out = await runPure(preload(env, input), {
+      handlers: { 'local.getById': () => ({ ids: [['thing:1', 1]], confirmed: true }), 'ssp.register': sspOk },
+    });
+    expect(out.result.waited).toBe(false);
+    expect(out.log.filter((e) => e.kind === 'remote.query')).toHaveLength(0);
+    expect(out.log.filter((e) => e.kind === 'state.wait')).toHaveLength(0);
+  });
+  it('never resolved: waits for settled (membership + bodies + first render), or fails when the registration failed', async () => {
+    const hash = await sha256Hex(queryHashInput(input, null));
+    const settleIt = (ctx: any) => {
+      ctx.state = R.compose(
+        R.commitMembership(hash, [['thing:1', 1]], true),
+        R.setVersions([['thing:1', 1]]),
+        R.setRecords(hash, [{ id: 'thing:1' }], true, 1)
+      )(ctx.state);
+    };
+    const out = await runPure(preload(env, input), {
+      handlers: { 'local.getById': () => null, 'ssp.register': sspOk, 'state.wait': (_e, ctx) => settleIt(ctx) },
+    });
+    expect(out.result).toEqual({ hash, waited: true });
+    const failed = runPure(preload(env, input), {
+      handlers: {
+        'local.getById': () => null,
+        'ssp.register': sspOk,
+        'state.wait': (_e, ctx) => void (ctx.state = R.applyLifecycle(hash, { type: 'remote-failed' })(ctx.state)),
+      },
+    });
+    await expect(failed).rejects.toBeInstanceOf(PreloadFailedError);
+    const gone = runPure(preload(env, input), {
+      handlers: { 'local.getById': () => null, 'ssp.register': sspOk, 'state.wait': (_e, ctx) => void (ctx.state = R.removeQuery(hash)(ctx.state)) },
+    });
+    await expect(gone).rejects.toThrow(/could not settle/);
+    const already = buildState([buildEntry({ def: { hash }, lifecycle: { phase: 'cached' } })]);
+    const cached = await runPure(preload(env, input), { state: already });
+    expect(cached.result.waited).toBe(false);
+  });
+});