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

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

@@ -0,0 +1,195 @@
+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);
+  });
+});
+
+describe('r2 buckets (files with the SSP)', () => {
+  function fakeSsp(files: Record<string, string> = {}) {
+    const requests: Array<{ method: string; url: string; auth: string | null; body: unknown }> = [];
+    const fetchMock = vi.fn(async (url: string, init: RequestInit) => {
+      const headers = (init.headers ?? {}) as Record<string, string>;
+      requests.push({ method: init.method ?? 'GET', url, auth: headers.Authorization ?? null, body: init.body });
+      const key = decodeURIComponent(new URL(url).pathname.replace(/^\/bucket\/[^/]+\//, ''));
+      const json = (status: number, value: unknown) => new Response(JSON.stringify(value), { status });
+      if (headers.Authorization !== 'Bearer tok') return json(401, { error: 'invalid or expired token' });
+      switch (init.method) {
+        case 'PUT':
+          files[key] = typeof init.body === 'string' ? init.body : 'bytes';
+          return json(200, { ok: true });
+        case 'GET':
+          return key in files ? new Response(files[key], { status: 200 }) : json(404, { error: 'no such file' });
+        case 'DELETE':
+          delete files[key];
+          return json(200, { ok: true });
+        default: {
+          const op = JSON.parse(String(init.body));
+          if (op.op === 'exists') return json(200, key in files);
+          if (op.op === 'head') return json(200, key in files ? { key: `/${key}`, size: files[key].length } : null);
+          if (!(key in files)) return json(404, { error: 'no such file' });
+          files[op.target] = files[key];
+          if (op.op === 'rename') delete files[key];
+          return json(200, { ok: true });
+        }
+      }
+    });
+    vi.stubGlobal('fetch', fetchMock);
+    return { requests, files };
+  }
+
+  const remote = (token: string | null = 'tok') => ({ getAuthToken: () => token, query: vi.fn() }) as any;
+  const r2 = (r = remote()) =>
+    new BucketHandle('pics', r, null, { backend: 'r2', files: { endpoint: 'https://app.db.example/' }, blurhash: false });
+
+  it('reads and writes over HTTP with the session token, never the database socket', async () => {
+    const { requests, files } = fakeSsp();
+    const db = remote();
+    const h = r2(db);
+    await h.put('u1/a b.png', 'PNG');
+    expect(files['u1/a b.png']).toBe('PNG');
+    expect(requests[0]).toMatchObject({ method: 'PUT', url: 'https://app.db.example/bucket/pics/u1/a%20b.png', auth: 'Bearer tok' });
+    expect(await ((await h.get('u1/a b.png')) as Blob).text()).toBe('PNG');
+    expect(await h.get('missing.png')).toBeNull();
+    expect(await h.exists('u1/a b.png')).toBe(true);
+    expect(await h.head('u1/a b.png')).toEqual({ key: '/u1/a b.png', size: 3 });
+    await h.copy('u1/a b.png', 'u1/c.png');
+    await h.rename('u1/c.png', 'u1/d.png');
+    expect(Object.keys(files).sort()).toEqual(['u1/a b.png', 'u1/d.png']);
+    await expect(h.copy('nope.png', 'x.png')).rejects.toThrow(/no file/);
+    await h.delete('u1/a b.png');
+    expect(await h.exists('u1/a b.png')).toBe(false);
+    await expect(h.list()).rejects.toThrow(/listing/);
+    expect(db.query).not.toHaveBeenCalled();
+    vi.unstubAllGlobals();
+  });
+
+  it('surfaces refusals and a missing endpoint as errors', async () => {
+    fakeSsp({ 'a.png': 'x' });
+    await expect(r2(remote(null)).get('a.png')).rejects.toThrow(/401.*invalid or expired token/);
+    const noEndpoint = new BucketHandle('pics', remote(), null, { backend: 'r2', files: {} });
+    await expect(noEndpoint.get('a.png')).rejects.toThrow(/files\.endpoint/);
+    vi.unstubAllGlobals();
+  });
+
+  it('a bucket without backend r2 keeps using the database', async () => {
+    const db = { getAuthToken: () => 'tok', query: vi.fn(async () => ['content']) } as any;
+    const fetchMock = vi.fn();
+    vi.stubGlobal('fetch', fetchMock);
+    const h = new BucketHandle('pics', db, null, { files: { endpoint: 'https://app.db.example' } });
+    expect(await h.get('a.png')).toBe('content');
+    expect(fetchMock).not.toHaveBeenCalled();
+    vi.unstubAllGlobals();
+  });
+});

package/src/client/bucket-handle.ts

@@ -0,0 +1,352 @@
+import type { RemoteDatabaseService } from '../services/database/remote';
+import type { BlobCache, BlobReadOptions, BlobUrlLease } from '../services/blobs/index';
+import {
+  blurhashSidecarPath,
+  encodeImageToBlurhash,
+  isImagePath,
+  isBlurhashValid,
+  type BlurhashSetting,
+  type BlurhashEncodeOptions,
+} from '../utils/blurhash';
+
+/** Coerce whatever the `.get()` RPC hands back into a Blob. */
+export function bucketContentToBlob(content: unknown): Blob | null {
+  if (content == null) return null;
+  if (content instanceof Blob) return content;
+  if (typeof content === 'string') return new Blob([content]);
+  if (content instanceof ArrayBuffer) return new Blob([content]);
+  // Uint8Array and friends. The cast sidesteps `ArrayBufferLike` vs
+  // `ArrayBuffer` (SharedArrayBuffer) in lib.dom's BlobPart.
+  if (ArrayBuffer.isView(content)) return new Blob([content as unknown as BlobPart]);
+  return null;
+}
+
+export interface BucketPutOptions {
+  /** Override the client-level {@link Sp00kyConfig.blurhash} setting for this put. */
+  blurhash?: BlurhashSetting;
+}
+
+export interface BucketPutResult {
+  /** The computed blurhash when the content was a hashable image; else null. */
+  blurhash: string | null;
+}
+
+interface BucketHandleSettings {
+  blurhash?: BlurhashSetting;
+  logger?: { warn: (obj: unknown, msg?: string) => void };
+  /** The bucket's backend as generated (`'r2'`: files live with the SSP). */
+  backend?: string;
+  /** {@link Sp00kyConfig.files}: where `r2` bucket files are read and written. */
+  files?: { endpoint?: string };
+}
+
+/** A handle's settings from the client config and the bucket's generated schema. */
+export function bucketSettings(
+  config: { blurhash?: BlurhashSetting; files?: { endpoint?: string }; schema: { buckets?: readonly { name: string; backend?: string }[] } },
+  name: string,
+  logger: { warn: (obj: unknown, msg?: string) => void }
+): BucketHandleSettings {
+  const backend = config.schema.buckets?.find((b) => b.name === name)?.backend;
+  return { blurhash: config.blurhash, logger, backend, files: config.files };
+}
+
+/** Where a bucket's bytes go: SurrealDB itself, or the SSP for `r2` buckets. */
+interface BucketIo {
+  put(path: string, content: string | Uint8Array | Blob): Promise<void>;
+  /** The file, or null when it does not exist. */
+  get(path: string): Promise<unknown>;
+  delete(path: string): Promise<void>;
+  exists(path: string): Promise<boolean>;
+  head(path: string): Promise<Record<string, unknown>>;
+  copy(sourcePath: string, targetPath: string): Promise<void>;
+  rename(sourcePath: string, targetPath: string): Promise<void>;
+  list(prefix: string): Promise<string[]>;
+}
+
+/** `f"bucket:/path"` statements over the database connection. */
+function surrealIo(bucket: string, remote: RemoteDatabaseService): BucketIo {
+  const file = (path: string) => `f"${bucket}:/${path}"`;
+  return {
+    async put(path, content) {
+      await remote.query(`RETURN ${file(path)}.put($content);`, { content });
+    },
+    async get(path) {
+      const [result] = await remote.query<[unknown]>(`RETURN ${file(path)}.get();`);
+      return result;
+    },
+    async delete(path) {
+      await remote.query(`RETURN ${file(path)}.delete();`);
+    },
+    async exists(path) {
+      const [result] = await remote.query<[boolean]>(`RETURN ${file(path)}.exists();`);
+      return result;
+    },
+    async head(path) {
+      const [result] = await remote.query<[Record<string, unknown>]>(`RETURN ${file(path)}.head();`);
+      return result;
+    },
+    async copy(sourcePath, targetPath) {
+      await remote.query(`RETURN ${file(sourcePath)}.copy($target);`, { target: targetPath });
+    },
+    async rename(sourcePath, targetPath) {
+      await remote.query(`RETURN ${file(sourcePath)}.rename($target);`, { target: targetPath });
+    },
+    async list(prefix) {
+      const [result] = await remote.query<[string[]]>(`RETURN ${file(prefix)}.list();`);
+      return result;
+    },
+  };
+}
+
+/**
+ * `BACKEND "r2"` buckets: the SSP keeps the files (R2 on Cloudflare, a
+ * directory under `spky dev`) and serves them at `/bucket/<name>/<key>`,
+ * after asking SurrealDB, as the signed-in user, whether the bucket's
+ * PERMISSIONS clause allows it. The request carries the session's token.
+ */
+function sspIo(bucket: string, remote: RemoteDatabaseService, endpoint: string | undefined): BucketIo {
+  const base = () => {
+    if (!endpoint) {
+      throw new Error(
+        `Bucket '${bucket}' is stored with the SSP (BACKEND "r2"): set \`files.endpoint\` in the client config to the SSP's URL.`
+      );
+    }
+    return endpoint.replace(/\/+$/, '');
+  };
+  const url = (path: string) =>
+    `${base()}/bucket/${encodeURIComponent(bucket)}/${path
+      .split('/')
+      .filter(Boolean)
+      .map(encodeURIComponent)
+      .join('/')}`;
+  const send = async (method: string, path: string, body?: BodyInit, contentType?: string): Promise<Response> => {
+    const headers: Record<string, string> = {};
+    const token = remote.getAuthToken();
+    if (token) headers.Authorization = `Bearer ${token}`;
+    if (contentType) headers['Content-Type'] = contentType;
+    const response = await fetch(url(path), { method, headers, body, credentials: 'omit' });
+    if (!response.ok && response.status !== 404) {
+      let message = response.statusText;
+      try {
+        message = ((await response.json()) as { error?: string }).error ?? message;
+      } catch {
+        // Not JSON: keep the status text.
+      }
+      throw new Error(`Bucket '${bucket}' ${method} ${path} failed (${response.status}): ${message}`);
+    }
+    return response;
+  };
+  const op = async <T>(path: string, body: Record<string, unknown>): Promise<T | null> => {
+    const response = await send('POST', path, JSON.stringify(body), 'application/json');
+    if (response.status === 404) return null;
+    return (await response.json()) as T;
+  };
+  const missing = (path: string) => new Error(`Bucket '${bucket}': no file at ${path}`);
+  return {
+    async put(path, content) {
+      const type = content instanceof Blob ? content.type : undefined;
+      await send('PUT', path, content as BodyInit, type || 'application/octet-stream');
+    },
+    async get(path) {
+      const response = await send('GET', path);
+      return response.status === 404 ? null : await response.blob();
+    },
+    async delete(path) {
+      await send('DELETE', path);
+    },
+    async exists(path) {
+      return (await op<boolean>(path, { op: 'exists' })) ?? false;
+    },
+    async head(path) {
+      return (await op<Record<string, unknown>>(path, { op: 'head' })) as Record<string, unknown>;
+    },
+    async copy(sourcePath, targetPath) {
+      if ((await op(sourcePath, { op: 'copy', target: targetPath })) === null) throw missing(sourcePath);
+    },
+    async rename(sourcePath, targetPath) {
+      if ((await op(sourcePath, { op: 'rename', target: targetPath })) === null) throw missing(sourcePath);
+    },
+    async list() {
+      // SurrealDB refuses `list` to record users; the SSP does too.
+      throw new Error(`Bucket '${bucket}': listing is not available (BACKEND "r2")`);
+    },
+  };
+}
+
+/**
+ * Paths known to have no blurhash sidecar, per tab. The blob cache has no
+ * negative caching, so without this every mount of a hashless image would pay
+ * one serialized remote read. Cleared when a put writes a sidecar or a delete
+ * removes the image. Keyed `${bucket}:${path}` (the image path, not the sidecar).
+ */
+const missingBlurhash = new Set<string>();
+
+export class BucketHandle {
+  private io: BucketIo;
+
+  constructor(
+    private bucketName: string,
+    remote: RemoteDatabaseService,
+    /** Absent on the raw handle the cache itself reads through. */
+    private blobs?: BlobCache | null,
+    private settings?: BucketHandleSettings
+  ) {
+    this.io =
+      settings?.backend === 'r2'
+        ? sspIo(bucketName, remote, settings.files?.endpoint)
+        : surrealIo(bucketName, remote);
+  }
+
+  /** Effective blurhash setting: per-call option > client config > default ON. */
+  private resolveBlurhash(option?: BlurhashSetting): BlurhashEncodeOptions | null {
+    const setting = option ?? this.settings?.blurhash ?? true;
+    if (setting === false) return null;
+    return setting === true ? {} : setting;
+  }
+
+  async put(
+    path: string,
+    content: string | Uint8Array | Blob,
+    options?: BucketPutOptions
+  ): Promise<BucketPutResult> {
+    // Start hashing while the upload is in flight; both browser-side costs
+    // overlap and the sidecar put only queues once the main put resolved.
+    const encodeOptions = this.resolveBlurhash(options?.blurhash);
+    const hashPromise =
+      encodeOptions && isImagePath(path)
+        ? encodeImageToBlurhash(content, encodeOptions)
+        : Promise.resolve(null);
+
+    await this.io.put(path, content);
+    // A path can be overwritten, so anything cached under it is now wrong.
+    await this.blobs?.invalidate({ bucket: this.bucketName, path });
+
+    // The sidecar is best-effort: a hash or sidecar failure must never fail
+    // the image put that triggered it.
+    let hash: string | null = null;
+    try {
+      hash = await hashPromise;
+      if (hash) {
+        const sidecar = blurhashSidecarPath(path);
+        await this.io.put(sidecar, hash);
+        await this.blobs?.invalidate({ bucket: this.bucketName, path: sidecar });
+        missingBlurhash.delete(`${this.bucketName}:${path}`);
+      }
+    } catch (error) {
+      hash = null;
+      this.settings?.logger?.warn({ error, path }, 'blurhash sidecar put failed');
+    }
+    return { blurhash: hash };
+  }
+
+  /**
+   * The blurhash stored alongside an uploaded image (see
+   * {@link blurhashSidecarPath}), or null when there is none. Reads through the
+   * blob cache, so a warm client answers from OPFS without a network hop, and
+   * misses are remembered per tab so a hashless image costs at most one
+   * serialized remote read per session.
+   */
+  async blurhash(path: string): Promise<string | null> {
+    const cacheKey = `${this.bucketName}:${path}`;
+    if (missingBlurhash.has(cacheKey)) return null;
+    try {
+      const blob = await this.read(blurhashSidecarPath(path), { persist: true });
+      if (!blob) {
+        missingBlurhash.add(cacheKey);
+        return null;
+      }
+      const hash = (await blob.text()).trim();
+      if (!isBlurhashValid(hash).result) {
+        this.settings?.logger?.warn({ path }, 'blurhash sidecar holds an invalid hash');
+        missingBlurhash.add(cacheKey);
+        return null;
+      }
+      return hash;
+    } catch (error) {
+      // Transient failure: do NOT negative-cache, the next mount may succeed.
+      this.settings?.logger?.warn({ error, path }, 'blurhash sidecar read failed');
+      return null;
+    }
+  }
+
+  async get(path: string): Promise<unknown> {
+    return this.io.get(path);
+  }
+
+  /**
+   * Read through the local blob cache: OPFS first, the bucket second. Unlike
+   * {@link get} this survives a reload and works offline. Returns null when the
+   * file exists in neither place.
+   */
+  async read(path: string, options?: BlobReadOptions): Promise<Blob | null> {
+    if (!this.blobs) return bucketContentToBlob(await this.get(path));
+    return this.blobs.read({ bucket: this.bucketName, path }, options);
+  }
+
+  /**
+   * A refcounted object URL for `path`, suitable for `<img src>`. The caller
+   * MUST call `release()` when the URL goes off screen. Returns null when the
+   * file does not exist, or when object URLs are unavailable (non-browser).
+   */
+  async url(path: string, options?: BlobReadOptions): Promise<BlobUrlLease | null> {
+    if (!this.blobs) return null;
+    return this.blobs.acquireUrl({ bucket: this.bucketName, path }, options);
+  }
+
+  /** Exempt `path` from pressure eviction. Pinned bytes never expire. */
+  pin(path: string): void {
+    this.blobs?.setPinned({ bucket: this.bucketName, path }, true);
+  }
+
+  unpin(path: string): void {
+    this.blobs?.setPinned({ bucket: this.bucketName, path }, false);
+  }
+
+  /** Drop `path` from the local cache without touching the remote file. */
+  async evict(path: string): Promise<void> {
+    await this.blobs?.invalidate({ bucket: this.bucketName, path });
+  }
+
+  /** Warm the cache for offline use. Already-cached paths are skipped. */
+  async prefetch(paths: string[]): Promise<void> {
+    await this.blobs?.prefetch(paths.map((path) => ({ bucket: this.bucketName, path })));
+  }
+
+  async delete(path: string): Promise<void> {
+    await this.io.delete(path);
+    await this.blobs?.invalidate({ bucket: this.bucketName, path });
+    // Symmetry with put: an image's blurhash sidecar dies with it. Best-effort,
+    // the sidecar may simply not exist.
+    if (isImagePath(path)) {
+      const sidecar = blurhashSidecarPath(path);
+      try {
+        await this.io.delete(sidecar);
+        await this.blobs?.invalidate({ bucket: this.bucketName, path: sidecar });
+      } catch {
+        // Nothing to clean up.
+      }
+      missingBlurhash.delete(`${this.bucketName}:${path}`);
+    }
+  }
+
+  async exists(path: string): Promise<boolean> {
+    return this.io.exists(path);
+  }
+
+  async head(path: string): Promise<Record<string, unknown>> {
+    return this.io.head(path);
+  }
+
+  async copy(sourcePath: string, targetPath: string): Promise<void> {
+    await this.io.copy(sourcePath, targetPath);
+  }
+
+  async rename(sourcePath: string, targetPath: string): Promise<void> {
+    await this.io.rename(sourcePath, targetPath);
+  }
+
+  async list(prefix?: string): Promise<string[]> {
+    return this.io.list(prefix ?? '');
+  }
+}
+

package/src/client/router.test.ts

@@ -0,0 +1,58 @@
+import { describe, expect, it } from 'vitest';
+import type { RuntimeEvent } from '../kernel/events';
+import { defaultEnv } from '../query/env';
+import { route } from './router';
+
+const env = defaultEnv({ tables: [] } as any);
+
+describe('route', () => {
+  it('maps every event to a saga and the documented lane', () => {
+    const cases: Array<[RuntimeEvent, string | undefined]> = [
+      [{ type: 'EnsureRegistered' }, 'serial:ensure'],
+      [{ type: 'RegisterRemote', hash: 'h' }, 'dedupe:register:h'],
+      [{ type: 'ReadDirtyMembership' }, 'serial:membership'],
+      [{ type: 'ReadMembership', hashes: ['h'] }, 'serial:membership'],
+      [{ type: 'FetchRows' }, 'serial:fetch'],
+      [{ type: 'Materialize', hash: 'h' }, 'serial:mat:h'],
+      [{ type: 'MaterializeDirty' }, undefined],
+      [{ type: 'StreamUpdate', update: { queryHash: 'h', localArray: [] } }, 'serial:stream:h'],
+      [{ type: 'LifecycleTick' }, 'dedupe:lifecycle'],
+      [{ type: 'HeartbeatNow' }, 'dedupe:lifecycle'],
+      [{ type: 'AckPrune' }, 'dedupe:ack-prune'],
+      [{ type: 'GcTick' }, 'dedupe:gc'],
+      [{ type: 'Drain' }, 'serial:outbox'],
+      [{ type: 'FlushWrite', key: 'k' }, 'serial:outbox-write'],
+      [{ type: 'FlushPendingWrites' }, undefined],
+      [{ type: 'AdoptPendingWrites' }, 'serial:outbox-write'],
+      [{ type: 'PollTick' }, 'dedupe:poll'],
+      [{ type: 'SelfHealTick' }, 'dedupe:heal'],
+      [{ type: 'SyncOutcome', ok: true }, 'serial:health'],
+      [{ type: 'ConnectionChanged', state: 'connected' }, 'serial:connection'],
+      [{ type: 'LiveStart' }, 'serial:live'],
+      [{ type: 'LiveChange', hashes: [] }, 'serial:live-change'],
+      [{ type: 'TabRole', role: 'leader' }, 'serial:tabs'],
+      [{ type: 'TabMessage', message: {} }, 'serial:tabs'],
+      [{ type: 'StartRemote' }, 'dedupe:start-remote'],
+      [{ type: 'PrimeCircuit' }, 'dedupe:prime'],
+      [{ type: 'VersionsPrimed', entries: [] }, undefined],
+      [{ type: 'WarmBlobs' }, 'dedupe:blobs'],
+      [{ type: 'AuthFlip', userId: null }, 'serial:bucket'],
+      [{ type: 'BucketSwitch', target: 'x' }, 'serial:bucket'],
+      [{ type: 'PageHide' }, undefined],
+    ];
+    for (const [event, lane] of cases) {
+      const target = route(env, event);
+      expect(typeof target.saga.next).toBe('function');
+      expect(target.lane ? `${target.lane.kind}:${target.lane.key}` : undefined).toBe(lane);
+      target.saga.return(undefined);
+    }
+  });
+  it('MaterializeDirty fans out one Materialize per dirty hash', async () => {
+    const { runPure } = await import('../testing/run-pure');
+    const { buildEntry, buildState } = await import('../testing/build');
+    const R = await import('../state/reducers');
+    const s = R.markDirty(['a', 'b'])(buildState([buildEntry({ def: { hash: 'a' } }), buildEntry({ def: { hash: 'b' } })]));
+    const out = await runPure(route(env, { type: 'MaterializeDirty' }).saga, { state: s });
+    expect(out.dispatched).toEqual([{ type: 'Materialize', hash: 'a' }, { type: 'Materialize', hash: 'b' }]);
+  });
+});