@spooky-sync/core 0.0.1-canary.240 → 0.0.1-canary.242

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

package/src/boot/bucket-switch.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 { bucketSwitch, 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.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', '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('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,115 @@
+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 } 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 { 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();
+  }
+  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* 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' });
+}
+
+/** 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);
+  });
+});

package/src/boot/preload.saga.ts

@@ -0,0 +1,31 @@
+import type { QueryHash } from '../types';
+import type { Saga } from '../kernel/saga';
+import { fx } from '../kernel/effects';
+import { settleFailed, settled } from '../state/selectors';
+import type { SagaEnv } from '../query/env';
+import type { RegisterInput } from '../query/register.saga';
+import { registerLocal } from '../query/register.saga';
+
+export class PreloadFailedError extends Error {
+  constructor(public readonly hash: QueryHash) {
+    super(`Preload could not settle: the registration of ${hash} failed`);
+    this.name = 'PreloadFailedError';
+  }
+}
+
+/**
+ * Preload = a registered query nobody subscribes to. Resolved before on this
+ * device: returns as soon as the entry exists (its rows paint from cache).
+ * Never resolved: blocks until the server's membership and every body are
+ * local and the first materialization ran. The entry is evicted like any
+ * other query a ttl after it was last watched (or registered).
+ */
+export function* preload(env: SagaEnv, input: RegisterInput): Saga<{ hash: QueryHash; waited: boolean }> {
+  const hash = yield* registerLocal(env, input);
+  const phase = (yield fx.state.read((s) => s.queries.get(hash)?.lifecycle.phase)) as string | undefined;
+  if (phase !== 'cold') return { hash, waited: false };
+  yield fx.state.wait((s) => settled(s, hash) || settleFailed(s, hash));
+  const failed = (yield fx.state.read((s) => settleFailed(s, hash))) as boolean;
+  if (failed) throw new PreloadFailedError(hash);
+  return { hash, waited: true };
+}

package/src/client/bucket-handle.test.ts

@@ -0,0 +1,117 @@
+import { describe, expect, it, vi } from 'vitest';
+import { BucketHandle, bucketContentToBlob } from './bucket-handle';
+
+vi.mock('../utils/blurhash', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('../utils/blurhash')>();
+  return { ...actual, encodeImageToBlurhash: vi.fn(async () => 'LEHV6nWB2yk8pyo0adR*.7kCMdnj') };
+});
+
+function fakeRemote(answers: Record<string, unknown> = {}) {
+  const calls: Array<[string, unknown]> = [];
+  const remote = {
+    query: async (sql: string, vars?: unknown) => {
+      calls.push([sql, vars]);
+      for (const [needle, answer] of Object.entries(answers)) if (sql.includes(needle)) return [answer];
+      return [undefined];
+    },
+  } as any;
+  return { remote, calls };
+}
+
+function fakeBlobs() {
+  const log: string[] = [];
+  return {
+    log,
+    blobs: {
+      invalidate: async (k: { path: string }) => void log.push(`invalidate:${k.path}`),
+      read: async (k: { path: string }) => (k.path.endsWith('.bh') ? new Blob(['LEHV6nWB2yk8pyo0adR*.7kCMdnj']) : new Blob(['x'])),
+      acquireUrl: async (k: { path: string }) => ({ url: `blob:${k.path}`, release: () => undefined }),
+      setPinned: (k: { path: string }, pinned: boolean) => void log.push(`pin:${k.path}:${pinned}`),
+      prefetch: async (keys: Array<{ path: string }>) => void log.push(`prefetch:${keys.map((k) => k.path).join('+')}`),
+    } as any,
+  };
+}
+
+describe('bucketContentToBlob', () => {
+  it('coerces strings, buffers and views; passes blobs through; rejects the rest', async () => {
+    expect(bucketContentToBlob(null)).toBeNull();
+    expect(bucketContentToBlob(42)).toBeNull();
+    const b = new Blob(['a']);
+    expect(bucketContentToBlob(b)).toBe(b);
+    expect(await bucketContentToBlob('hi')!.text()).toBe('hi');
+    expect((await bucketContentToBlob(new ArrayBuffer(3))!.arrayBuffer()).byteLength).toBe(3);
+    expect((await bucketContentToBlob(new Uint8Array([1, 2]))!.arrayBuffer()).byteLength).toBe(2);
+  });
+});
+
+describe('BucketHandle', () => {
+  it('put: uploads, invalidates, writes the blurhash sidecar for images (best-effort), honours the setting', async () => {
+    const { remote, calls } = fakeRemote();
+    const { blobs, log } = fakeBlobs();
+    const warn = vi.fn();
+    const h = new BucketHandle('files', remote, blobs, { logger: { warn } });
+    const res = await h.put('a/pic.png', new Uint8Array([1]));
+    expect(res.blurhash).toBe('LEHV6nWB2yk8pyo0adR*.7kCMdnj');
+    expect(calls.map(([s]) => s)).toEqual(['RETURN f"files:/a/pic.png".put($content);', 'RETURN f"files:/a/pic.png.bh".put($content);']);
+    expect(log).toEqual(['invalidate:a/pic.png', 'invalidate:a/pic.png.bh']);
+    const off = new BucketHandle('files', remote, blobs, { blurhash: false });
+    expect((await off.put('b.png', 'x')).blurhash).toBeNull();
+    const perCall = new BucketHandle('files', remote, blobs, { blurhash: { componentX: 2 } });
+    expect((await perCall.put('c.txt', 'x', { blurhash: true })).blurhash).toBeNull();
+    expect((await perCall.put('c.png', 'x', { blurhash: { componentY: 3 } })).blurhash).toBeTruthy();
+    const failing = { query: async (sql: string) => { if (sql.includes('.bh')) throw new Error('sidecar'); return [undefined]; } } as any;
+    const sidecarFail = new BucketHandle('files', failing, blobs, { logger: { warn } });
+    expect((await sidecarFail.put('d.png', 'x')).blurhash).toBeNull();
+    expect(warn).toHaveBeenCalled();
+    const noBlobs = new BucketHandle('files', remote, null);
+    expect((await noBlobs.put('e.png', 'x')).blurhash).toBeTruthy();
+  });
+
+  it('blurhash: reads the sidecar through the cache, negative-caches misses, warns on invalid or failing reads', async () => {
+    const { remote } = fakeRemote();
+    const warn = vi.fn();
+    const { blobs } = fakeBlobs();
+    const h = new BucketHandle('bucketA', remote, blobs, { logger: { warn } });
+    expect(await h.blurhash('img.png')).toBe('LEHV6nWB2yk8pyo0adR*.7kCMdnj');
+    const missing = new BucketHandle('bucketB', remote, { ...blobs, read: async () => null } as any, { logger: { warn } });
+    expect(await missing.blurhash('none.png')).toBeNull();
+    expect(await missing.blurhash('none.png')).toBeNull();
+    const invalid = new BucketHandle('bucketC', remote, { ...blobs, read: async () => new Blob(['not-a-hash']) } as any, { logger: { warn } });
+    expect(await invalid.blurhash('bad.png')).toBeNull();
+    const throwing = new BucketHandle('bucketD', remote, { ...blobs, read: async () => { throw new Error('io'); } } as any, { logger: { warn } });
+    expect(await throwing.blurhash('err.png')).toBeNull();
+    expect(warn).toHaveBeenCalledTimes(2);
+    await new BucketHandle('bucketB', remote, blobs).put('none.png', 'x');
+    expect(await new BucketHandle('bucketB', remote, blobs).blurhash('none.png')).toBeTruthy();
+  });
+
+  it('get / read / url / pin / evict / prefetch / delete / exists / head / copy / rename / list', async () => {
+    const { remote, calls } = fakeRemote({ '.get()': 'content', '.exists()': true, '.head()': { size: 1 }, '.list()': ['a'] });
+    const { blobs, log } = fakeBlobs();
+    const h = new BucketHandle('files', remote, blobs);
+    expect(await h.get('p')).toBe('content');
+    expect(await (await h.read('p'))!.text()).toBe('x');
+    expect(await new BucketHandle('files', remote, null).read('p')).toBeInstanceOf(Blob);
+    expect(await h.url('p')).toEqual({ url: 'blob:p', release: expect.any(Function) });
+    expect(await new BucketHandle('files', remote, null).url('p')).toBeNull();
+    h.pin('p');
+    h.unpin('p');
+    await h.evict('p');
+    await h.prefetch(['a', 'b']);
+    await h.delete('doc.txt');
+    await h.delete('img.png');
+    const flaky = { query: async (sql: string) => { if (sql.includes('.bh".delete')) throw new Error('nope'); return [undefined]; } } as any;
+    await new BucketHandle('files', flaky, blobs).delete('img2.png');
+    expect(await h.exists('p')).toBe(true);
+    expect(await h.head('p')).toEqual({ size: 1 });
+    await h.copy('a', 'b');
+    await h.rename('a', 'b');
+    expect(await h.list()).toEqual(['a']);
+    expect(await h.list('pre/')).toEqual(['a']);
+    expect(log).toContain('pin:p:true');
+    expect(log).toContain('pin:p:false');
+    expect(log).toContain('prefetch:a+b');
+    expect(calls.some(([s]) => s === 'RETURN f"files:/img.png.bh".delete();')).toBe(true);
+    expect(calls.some(([s]) => s === 'RETURN f"files:/pre/".list();')).toBe(true);
+  });
+});