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

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,80 @@
+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 signedIn = buildState([], R.setIdentity({ userId: 'user:alice' }));
+    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), {
+      state: signedIn,
+      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), {
+      state: signedIn,
+      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), {
+      state: signedIn,
+      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);
+  });
+  it('signed out without anonymous live queries: registers but never waits, since no membership can reach this session', async () => {
+    const out = await runPure(preload(env, input), {
+      handlers: { 'local.getById': () => null, 'ssp.register': sspOk },
+    });
+    expect(out.result.waited).toBe(false);
+    expect(out.log.filter((e) => e.kind === 'state.wait')).toHaveLength(0);
+    expect(out.log.some((e) => e.kind === 'dispatch' && (e as any).event?.type === 'EnsureRegistered')).toBe(true);
+
+    // With anonymous live queries a signed-out session is sent its membership
+    // on `_00_list_ref_anon`, so it waits like a signed-in one.
+    const hash = await sha256Hex(queryHashInput(input, null));
+    const anon = await runPure(preload(defaultEnv(env.schema, { anonLive: true }), input), {
+      handlers: {
+        'local.getById': () => null,
+        'ssp.register': sspOk,
+        'state.wait': (_e, ctx) =>
+          void (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)),
+      },
+    });
+    expect(anon.result).toEqual({ hash, waited: true });
+  });
+});

package/src/boot/preload.saga.ts

@@ -0,0 +1,40 @@
+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 { receivesMembership } 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).
+ *
+ * A session that cannot be sent membership (signed out, without anonymous
+ * live queries) does not wait either: a view with rows would never settle,
+ * and an app that gates its first paint on a preload showed its loading
+ * screen forever, signed-out landing page included.
+ */
+export function* preload(env: SagaEnv, input: RegisterInput): Saga<{ hash: QueryHash; waited: boolean }> {
+  const hash = yield* registerLocal(env, input);
+  const [phase, reachable] = (yield fx.state.read((s) => [s.queries.get(hash)?.lifecycle.phase, receivesMembership(env, s)])) as [
+    string | undefined,
+    boolean,
+  ];
+  if (phase !== 'cold' || !reachable) 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/bucket-blurhash.test.ts

@@ -0,0 +1,148 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { BucketHandle } from './sp00ky';
+import type { RemoteDatabaseService } from './services/database/index';
+import {
+  blurhashSidecarPath,
+  isImagePath,
+  encodeImageToBlurhash,
+  encodeBlurhash,
+} from './utils/blurhash';
+
+// A real 1x1 hash so isBlurhashValid passes in the read-path tests.
+const VALID_HASH = encodeBlurhash(new Uint8ClampedArray([12, 34, 56, 255]), 1, 1, 1, 1);
+
+function makeRemote(queries: string[]) {
+  return {
+    query: vi.fn(async (surql: string) => {
+      queries.push(surql);
+      return [null];
+    }),
+  } as unknown as RemoteDatabaseService;
+}
+
+describe('blurhash path helpers', () => {
+  it('appends .bh for the sidecar', () => {
+    expect(blurhashSidecarPath('a/b_t.webp')).toBe('a/b_t.webp.bh');
+  });
+
+  it('recognizes image extensions case-insensitively', () => {
+    expect(isImagePath('x/y.webp')).toBe(true);
+    expect(isImagePath('x/y.PNG')).toBe(true);
+    expect(isImagePath('x/y.webp.bh')).toBe(false);
+    expect(isImagePath('x/notes.txt')).toBe(false);
+  });
+});
+
+describe('encodeImageToBlurhash outside a browser', () => {
+  it('returns null instead of throwing (no createImageBitmap in node)', async () => {
+    await expect(encodeImageToBlurhash(new Uint8Array([1, 2, 3]))).resolves.toBeNull();
+  });
+});
+
+describe('BucketHandle.put', () => {
+  let queries: string[];
+
+  beforeEach(() => {
+    queries = [];
+  });
+
+  it('image put succeeds with blurhash null when encoding is unavailable', async () => {
+    const handle = new BucketHandle('covers', makeRemote(queries), null);
+    const result = await handle.put('a/b_t.webp', new Uint8Array([1]));
+    expect(result).toEqual({ blurhash: null });
+    // Only the image put went out; no sidecar for a failed/unavailable encode.
+    expect(queries).toHaveLength(1);
+    expect(queries[0]).toContain('covers:/a/b_t.webp".put');
+  });
+
+  it('skips hashing entirely for non-image paths and when disabled', async () => {
+    const handle = new BucketHandle('covers', makeRemote(queries), null, { blurhash: false });
+    await handle.put('a/b_t.webp', new Uint8Array([1]));
+    await handle.put('a/readme.txt', 'hello');
+    expect(queries).toHaveLength(2);
+    expect(queries.some((q) => q.includes('.bh'))).toBe(false);
+  });
+
+  it('writes the sidecar when a hash is produced', async () => {
+    // Simulate a browser: a createImageBitmap whose bitmap a canvas can read.
+    const pixels = { width: 2, height: 2 };
+    vi.stubGlobal(
+      'createImageBitmap',
+      vi.fn(async () => ({ ...pixels, close: vi.fn() }))
+    );
+    vi.stubGlobal(
+      'OffscreenCanvas',
+      class {
+        width: number;
+        height: number;
+        constructor(w: number, h: number) {
+          this.width = w;
+          this.height = h;
+        }
+        getContext() {
+          return {
+            drawImage: () => {},
+            getImageData: (_x: number, _y: number, w: number, h: number) => ({
+              data: new Uint8ClampedArray(w * h * 4).fill(128),
+            }),
+          };
+        }
+      }
+    );
+    try {
+      const handle = new BucketHandle('covers', makeRemote(queries), null);
+      const result = await handle.put('a/b_t.webp', new Uint8Array([1]));
+      expect(result.blurhash).toBeTruthy();
+      expect(queries).toHaveLength(2);
+      expect(queries[1]).toContain('covers:/a/b_t.webp.bh".put');
+    } finally {
+      vi.unstubAllGlobals();
+    }
+  });
+});
+
+describe('BucketHandle.blurhash', () => {
+  it('returns a valid stored hash and negative-caches misses per path', async () => {
+    const reads: string[] = [];
+    let payload: unknown = VALID_HASH;
+    const remote = {
+      query: vi.fn(async (surql: string) => {
+        reads.push(surql);
+        return [payload];
+      }),
+    } as unknown as RemoteDatabaseService;
+    const handle = new BucketHandle('covers', remote, null);
+
+    await expect(handle.blurhash('hit/x.webp')).resolves.toBe(VALID_HASH);
+
+    payload = null;
+    await expect(handle.blurhash('miss/x.webp')).resolves.toBeNull();
+    const readsAfterMiss = reads.length;
+    // The miss is remembered: no second remote read for the same path.
+    await expect(handle.blurhash('miss/x.webp')).resolves.toBeNull();
+    expect(reads).toHaveLength(readsAfterMiss);
+  });
+
+  it('treats invalid sidecar content as missing', async () => {
+    const remote = {
+      query: vi.fn(async () => ['not a blurhash \\ at all']),
+    } as unknown as RemoteDatabaseService;
+    const handle = new BucketHandle('covers', remote, null);
+    await expect(handle.blurhash('bad/x.webp')).resolves.toBeNull();
+  });
+});
+
+describe('BucketHandle.delete', () => {
+  it('also deletes the sidecar for image paths, best-effort', async () => {
+    const queries: string[] = [];
+    const handle = new BucketHandle('covers', makeRemote(queries), null);
+    await handle.delete('a/b_t.webp');
+    expect(queries).toHaveLength(2);
+    expect(queries[0]).toContain('covers:/a/b_t.webp".delete');
+    expect(queries[1]).toContain('covers:/a/b_t.webp.bh".delete');
+
+    queries.length = 0;
+    await handle.delete('a/notes.txt');
+    expect(queries).toHaveLength(1);
+  });
+});

package/src/build-globals.d.ts

@@ -0,0 +1,12 @@
+// Build-time string constants injected by tsdown's `define` (see
+// tsdown.config.ts). They carry the real bundled frontend package versions so
+// the DevTools can surface frontend/backend version drift.
+//
+// Typed as `string | undefined` on purpose: the substitution only happens when
+// `@spooky-sync/core` is built with our tsdown plugin. A downstream app that
+// bundles core from source never runs that plugin, so these identifiers must be
+// guarded with `typeof` (see modules/devtools/index.ts) to avoid a runtime
+// ReferenceError that would break DB initialization.
+declare const __SP00KY_CORE_VERSION__: string | undefined;
+declare const __SP00KY_WASM_VERSION__: string | undefined;
+declare const __SP00KY_SURREAL_VERSION__: string | undefined;