@spooky-sync/core 0.0.1-canary.33 → 0.0.1-canary.331

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 } });
+  }
+}

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

@@ -0,0 +1,203 @@
+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',
+      'salt.take',
+      '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',
+      ownerSecret: 'owner-2',
+      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('a reload keeps the salt its tab left for the same principal, and the owner secret its views answer to', async () => {
+    const svc = fakeServices({
+      'hint.read': () => 'u1',
+      'auth.restoreSession': async () => 'user:u1',
+      'auth.sessionAuthId': () => 'user:u1',
+      'salt.take': () => ({ salt: 'kept-salt', owner: 'kept-owner' }),
+    });
+    const out = await runPure(boot(env, { sharedTabs: false }), { handlers: { service: svc.handler, 'local.query': () => [] } });
+    expect(svc.calls).toContainEqual(['salt.take', ['user:u1']]);
+    expect(svc.calls).toContainEqual(['crdt.setSessionId', ['kept-salt']]);
+    expect(out.state).toMatchObject({ sessionId: 'kept-salt', saltUserId: 'user:u1', ownerSecret: 'kept-owner' });
+    expect(out.log.filter((e) => e.kind === 'id')).toEqual([]);
+  });
+  it('a salt left by a page that kept no owner secret gets a fresh one', async () => {
+    const svc = fakeServices({
+      'hint.read': () => null,
+      'auth.restoreSession': async () => null,
+      'auth.sessionAuthId': () => null,
+      'salt.take': () => ({ salt: 'kept-salt', owner: null }),
+    });
+    const out = await runPure(boot(env, { sharedTabs: false }), { handlers: { service: svc.handler, 'local.query': () => [] } });
+    expect(out.state).toMatchObject({ sessionId: 'kept-salt', ownerSecret: 'owner-1' });
+  });
+  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('pageHide leaves the salt and owner secret for a reload before releasing views', async () => {
+    const svc = fakeServices();
+    const s = {
+      ...buildState([buildEntry({ def: { hash: 'a' }, lifecycle: { remote: 'registered' } })]),
+      sessionId: 'salt-1',
+      saltUserId: 'user:u1',
+      ownerSecret: 'owner-1',
+    };
+    await runPure(pageHide(), { state: s, handlers: { service: svc.handler } });
+    expect(svc.calls).toEqual([
+      ['salt.leave', ['salt-1', 'user:u1', 'owner-1']],
+      ['remote.releaseViews', [[new RecordId('_00_query', 'a')]]],
+    ]);
+  });
+  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,146 @@
+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 authId = (yield fx.service('auth.sessionAuthId')) as string | null;
+  // A reload keeps the salt its tab had, so registrations land on warm views,
+  // and the owner secret those views answer to.
+  const left = (yield fx.service('salt.take', authId)) as { salt: string; owner: string | null } | null;
+  const salt = (left?.salt ?? (yield fx.id('salt'))) as string;
+  const ownerSecret = (left?.owner ?? (yield fx.id('owner'))) as string;
+  yield fx.state.update(R.setIdentity({ sessionId: salt, userId: restoredUserId, saltUserId: authId, ownerSecret }));
+  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));
+}
+
+/**
+ * The page is going away for good: leave the salt for a reload of this tab,
+ * then hand this tab's views back to the server. The release is deferred
+ * server-side (`fn::query::leave`), so a reload that re-registers within the
+ * grace finds its views still warm.
+ */
+export function* pageHide(): Saga<void> {
+  const [salt, saltUserId, ownerSecret, ids] = (yield fx.state.read((s) => [
+    s.sessionId,
+    s.saltUserId,
+    s.ownerSecret,
+    [...s.queries.values()].filter((e) => e.lifecycle.remote === 'registered').map((e) => e.def.id),
+  ])) as [string | null, string | null, string | null, unknown[]];
+  if (salt) yield fx.service('salt.leave', salt, saltUserId, ownerSecret);
+  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 } });
+  }
+}