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

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/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;

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