@spooky-sync/core 0.0.1-canary.31 → 0.0.1-canary.310

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

package/src/client/bucket-handle.ts

@@ -0,0 +1,227 @@
+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 };
+}
+
+/**
+ * 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 {
+  constructor(
+    private bucketName: string,
+    private remote: RemoteDatabaseService,
+    /** Absent on the raw handle the cache itself reads through. */
+    private blobs?: BlobCache | null,
+    private settings?: BucketHandleSettings
+  ) {}
+
+  /** 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.remote.query(`RETURN f"${this.bucketName}:/${path}".put($content);`, { 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.remote.query(`RETURN f"${this.bucketName}:/${sidecar}".put($content);`, {
+          content: 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> {
+    const [result] = await this.remote.query<[unknown]>(
+      `RETURN f"${this.bucketName}:/${path}".get();`
+    );
+    return result;
+  }
+
+  /**
+   * 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.remote.query(`RETURN f"${this.bucketName}:/${path}".delete();`);
+    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.remote.query(`RETURN f"${this.bucketName}:/${sidecar}".delete();`);
+        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> {
+    const [result] = await this.remote.query<[boolean]>(
+      `RETURN f"${this.bucketName}:/${path}".exists();`
+    );
+    return result;
+  }
+
+  async head(path: string): Promise<Record<string, unknown>> {
+    const [result] = await this.remote.query<[Record<string, unknown>]>(
+      `RETURN f"${this.bucketName}:/${path}".head();`
+    );
+    return result;
+  }
+
+  async copy(sourcePath: string, targetPath: string): Promise<void> {
+    await this.remote.query(`RETURN f"${this.bucketName}:/${sourcePath}".copy($target);`, {
+      target: targetPath,
+    });
+  }
+
+  async rename(sourcePath: string, targetPath: string): Promise<void> {
+    await this.remote.query(`RETURN f"${this.bucketName}:/${sourcePath}".rename($target);`, {
+      target: targetPath,
+    });
+  }
+
+  async list(prefix?: string): Promise<string[]> {
+    const p = prefix ?? '';
+    const [result] = await this.remote.query<[string[]]>(
+      `RETURN f"${this.bucketName}:/${p}".list();`
+    );
+    return result;
+  }
+}
+

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