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

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,56 @@
+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: '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' }]);
+  });
+});

package/src/client/router.ts

@@ -0,0 +1,96 @@
+import type { RuntimeEvent } from '../kernel/events';
+import type { Lane, Saga } from '../kernel/saga';
+import type { SagaEnv } from '../query/env';
+import { ensureRegistered, registerRemote } from '../query/register.saga';
+import { readDirtyMembership, readMembership, recoverLostView } from '../query/membership.saga';
+import { fetchRows } from '../query/fetch.saga';
+import { materialize, streamUpdate } from '../query/materialize.saga';
+import { ackPrune, gcTick, lifecycleTick } from '../query/lifecycle.saga';
+import { drain } from '../mutation/push.saga';
+import { flushWrite } from '../mutation/write.saga';
+import { pollTick } from '../sync/poll.saga';
+import { liveChange, liveStart } from '../sync/live.saga';
+import { connectionChanged, selfHealTick, syncOutcome } from '../sync/connection.saga';
+import { setRole, tabMessage } from '../sync/tabs.saga';
+import { pageHide, primeCircuit, startRemote, versionsPrimed, warmBlobs } from '../boot/boot.saga';
+import { authFlip } from '../boot/auth-flip.saga';
+import { bucketSwitch } from '../boot/bucket-switch.saga';
+import { fx } from '../kernel/effects';
+
+export interface RouteTarget {
+  saga: Saga<unknown>;
+  lane?: Lane;
+}
+
+const serial = (key: string): Lane => ({ kind: 'serial', key });
+const dedupe = (key: string): Lane => ({ kind: 'dedupe', key });
+
+function* materializeDirty(): Saga<void> {
+  const dirty = (yield fx.state.read((s) => [...s.dirty])) as string[];
+  for (const hash of dirty) yield fx.dispatch({ type: 'Materialize', hash });
+}
+
+/** One table: which saga handles an event, and on which lane. */
+export function route(env: SagaEnv, event: RuntimeEvent): RouteTarget {
+  switch (event.type) {
+    case 'EnsureRegistered':
+      return { saga: ensureRegistered(env, { requireAuth: event.requireAuth, attempt: event.attempt }), lane: serial('ensure') };
+    case 'RegisterRemote':
+      return { saga: registerRemote(env, event.hash, event.retry), lane: dedupe(`register:${event.hash}`) };
+    case 'RecoverLostView':
+      return { saga: recoverLostView(event.hash), lane: dedupe(`view-lost:${event.hash}`) };
+    case 'ReadDirtyMembership':
+      return { saga: readDirtyMembership(env), lane: serial('membership') };
+    case 'ReadMembership':
+      return { saga: readMembership(env, event.hashes, { force: true }), lane: serial('membership') };
+    case 'FetchRows':
+      return { saga: fetchRows(env), lane: serial('fetch') };
+    case 'Materialize':
+      return { saga: materialize(event.hash), lane: serial(`mat:${event.hash}`) };
+    case 'MaterializeDirty':
+      return { saga: materializeDirty() };
+    case 'StreamUpdate':
+      return { saga: streamUpdate(event.update), lane: serial(`stream:${event.update.queryHash}`) };
+    case 'LifecycleTick':
+    case 'HeartbeatNow':
+      return { saga: lifecycleTick(env), lane: dedupe('lifecycle') };
+    case 'AckPrune':
+      return { saga: ackPrune(), lane: dedupe('ack-prune') };
+    case 'GcTick':
+      return { saga: gcTick(), lane: dedupe('gc') };
+    case 'Drain':
+      return { saga: drain(env), lane: serial('outbox') };
+    case 'FlushWrite':
+      return { saga: flushWrite(env, event.key), lane: serial('outbox-write') };
+    case 'PollTick':
+      return { saga: pollTick(env), lane: dedupe('poll') };
+    case 'SelfHealTick':
+      return { saga: selfHealTick(env), lane: dedupe('heal') };
+    case 'SyncOutcome':
+      return { saga: syncOutcome(env, event.ok, event.error), lane: serial('health') };
+    case 'ConnectionChanged':
+      return { saga: connectionChanged(env, event.state), lane: serial('connection') };
+    case 'LiveStart':
+      return { saga: liveStart(env), lane: serial('live') };
+    case 'LiveChange':
+      return { saga: liveChange(env, event.hashes, event.rows), lane: serial('live-change') };
+    case 'TabRole':
+      return { saga: setRole(env, event.role), lane: serial('tabs') };
+    case 'TabMessage':
+      return { saga: tabMessage(env, event.message), lane: serial('tabs') };
+    case 'StartRemote':
+      return { saga: startRemote(), lane: dedupe('start-remote') };
+    case 'PrimeCircuit':
+      return { saga: primeCircuit(), lane: dedupe('prime') };
+    case 'VersionsPrimed':
+      return { saga: versionsPrimed(event.entries) };
+    case 'WarmBlobs':
+      return { saga: warmBlobs(), lane: dedupe('blobs') };
+    case 'AuthFlip':
+      return { saga: authFlip(env, event.userId), lane: serial('bucket') };
+    case 'BucketSwitch':
+      return { saga: bucketSwitch(env, event.target), lane: serial('bucket') };
+    case 'PageHide':
+      return { saga: pageHide() };
+  }
+}

package/src/client/runtime.test.ts

@@ -0,0 +1,192 @@
+import { describe, expect, it } from 'vitest';
+import { fakeAdapters } from '../testing/adapters';
+import { buildEntry, buildState } from '../testing/build';
+import { defaultEnv } from '../query/env';
+import { fx } from '../kernel/effects';
+import type { Saga } from '../kernel/saga';
+import * as R from '../state/reducers';
+import { Runtime } from './runtime';
+
+const env = defaultEnv({ tables: [] } as any, { materializeDebounceMs: 5 });
+const noop = () => {};
+const logs: unknown[] = [];
+const logger: any = { debug: noop, info: noop, warn: noop, trace: noop, error: (o: unknown) => logs.push(o), child: () => logger };
+const make = (over: Parameters<typeof fakeAdapters>[0] = {}, initialState = buildState()) => {
+  const a = fakeAdapters(over);
+  const rt = new Runtime({ env, adapters: a.adapters, logger, tabId: 'tab-a', initialState });
+  return { a, rt };
+};
+const tick = () => new Promise((r) => setTimeout(r, 0));
+
+describe('Runtime lanes', () => {
+  it('serial lanes run one at a time in order; dedupe lanes join the running saga', async () => {
+    const { rt } = make();
+    const order: string[] = [];
+    function* step(name: string, wait: Promise<void>): Saga<string> {
+      order.push(`${name}:start`);
+      yield fx.state.wait(() => true);
+      await0(wait);
+      order.push(`${name}:end`);
+      return name;
+    }
+    let release!: () => void;
+    const gate = new Promise<void>((r) => (release = r));
+    const await0 = (_p: Promise<void>) => undefined;
+    const a = rt.run(step('a', gate), { lane: { kind: 'serial', key: 'x' } });
+    const b = rt.run(step('b', gate), { lane: { kind: 'serial', key: 'x' } });
+    release();
+    expect(await a).toBe('a');
+    expect(await b).toBe('b');
+    expect(order).toEqual(['a:start', 'a:end', 'b:start', 'b:end']);
+    let n = 0;
+    function* counted(): Saga<number> {
+      n++;
+      yield fx.state.wait(() => true);
+      return n;
+    }
+    const d1 = rt.run(counted(), { lane: { kind: 'dedupe', key: 'd' } });
+    const d2 = rt.run(counted(), { lane: { kind: 'dedupe', key: 'd' } });
+    expect(await d1).toBe(1);
+    expect(await d2).toBe(1);
+    expect(n).toBe(1);
+    const d3 = await rt.run(counted(), { lane: { kind: 'dedupe', key: 'd' } });
+    expect(d3).toBe(2);
+  });
+  it('a failing saga on a serial lane does not block the next one; dispatch logs and never rejects', async () => {
+    const { rt } = make();
+    function* boom(): Saga<void> {
+      yield fx.state.wait(() => true);
+      throw new Error('nope');
+    }
+    function* fine(): Saga<string> {
+      yield fx.state.wait(() => true);
+      return 'ok';
+    }
+    await expect(rt.run(boom(), { lane: { kind: 'serial', key: 'k' } })).rejects.toThrow('nope');
+    expect(await rt.run(fine(), { lane: { kind: 'serial', key: 'k' } })).toBe('ok');
+    logs.length = 0;
+    await rt.dispatch({ type: 'Materialize', hash: 'missing' });
+    await rt.dispatch({ type: 'ReadMembership', hashes: [] });
+    expect(logs).toEqual([]);
+  });
+});
+
+describe('Runtime state hooks', () => {
+  it('dirty queries are materialized after the debounce, once per burst', async () => {
+    const { a, rt } = make({ local: { select: async () => [{ id: 'thing:1' }] } }, buildState([buildEntry({ def: { hash: 'q', plan: { table: 'thing' } as any } })]));
+    const seen: unknown[] = [];
+    rt.subscribe('q', (rows) => seen.push(rows));
+    rt.update(R.markDirty(['q']));
+    rt.update(R.markDirty(['q']));
+    expect(a.timers.pending.has('mat:q')).toBe(true);
+    a.timers.fire('mat:q');
+    await tick();
+    await tick();
+    expect(seen).toEqual([[{ id: 'thing:1' }]]);
+    expect(rt.state.dirty.has('q')).toBe(false);
+  });
+  it('status and authority subscriptions fire on transitions, immediate delivers the current value', async () => {
+    const { rt } = make({}, buildState([buildEntry({ def: { hash: 'q' } })]));
+    const statuses: string[] = [];
+    const auths: boolean[] = [];
+    const offS = rt.subscribeStatus('q', (s) => statuses.push(s), { immediate: true });
+    const offA = rt.subscribeAuthority('q', (k) => auths.push(k), { immediate: true });
+    const offA2 = rt.subscribeAuthority('q', () => auths.push(false));
+    rt.update(R.applyLifecycle('q', { type: 'fetch-begin' }));
+    rt.update(R.applyLifecycle('q', { type: 'fetch-begin' }));
+    rt.update(R.applyLifecycle('q', { type: 'fetch-end' }));
+    rt.update(R.applyLifecycle('q', { type: 'fetch-end' }));
+    rt.emit({ type: 'query:authority', hash: 'q', known: true });
+    expect(statuses).toEqual(['idle', 'fetching', 'idle']);
+    expect(auths).toEqual([false, true, false]);
+    offA2();
+    offA();
+    rt.emit({ type: 'query:authority', hash: 'q', known: false });
+    expect(auths).toHaveLength(3);
+    offS();
+    rt.update(R.applyLifecycle('q', { type: 'fetch-begin' }));
+    expect(statuses).toHaveLength(3);
+    const missing: string[] = [];
+    rt.subscribeStatus('zz', (s) => missing.push(s), { immediate: true });
+    rt.subscribeAuthority('zz', () => missing.push('x'), { immediate: true });
+    expect(missing).toEqual([]);
+  });
+  it('notifies health on a transport change, and only on a real move', () => {
+    const { rt } = make();
+    const seen: string[] = [];
+    rt.on('health:changed', (e) => seen.push(e.type === 'health:changed' ? e.health.connection : '?'));
+    rt.update(R.setConnection('connected'));
+    rt.update(R.setConnection('connected'));
+    rt.update(R.setConnection('reconnecting'));
+    expect(seen).toEqual(['connected', 'reconnecting']);
+    // A health snapshot rebuilt with the same values must not re-notify.
+    rt.update(R.setHealth({ ...rt.state.sync.health }));
+    expect(seen).toHaveLength(2);
+    rt.update(R.setHealth({ ...rt.state.sync.health, status: 'degraded' }));
+    expect(seen).toHaveLength(3);
+  });
+  it('activity, listeners, records subscription bookkeeping, waitFor and dispose', async () => {
+    const { a, rt } = make({}, buildState([buildEntry({ def: { hash: 'q' } })]));
+    const events: string[] = [];
+    const off = rt.on('activity:changed', (e) => events.push(JSON.stringify(e)));
+    rt.on('*', (e) => events.push(`*${e.type}`));
+    rt.update(R.applyLifecycle('q', { type: 'fetch-begin' }));
+    expect(events).toEqual(['{"type":"activity:changed","fetching":1,"pending":0}', '*activity:changed']);
+    off();
+    const rows: unknown[] = [];
+    const unsub = rt.subscribe('q', (r) => rows.push(r), { immediate: true });
+    expect(rows).toEqual([[]]);
+    expect(rt.state.queries.get('q')!.subscribers).toBe(1);
+    rt.emit({ type: 'query:records', hash: 'q', records: [{ id: 1 }] });
+    expect(rows).toHaveLength(2);
+    unsub();
+    unsub();
+    expect(rt.state.queries.get('q')!.subscribers).toBe(0);
+    expect(rt.state.queries.get('q')!.lastSubscriberLeftAt).toBe(1_700_000_000_000);
+    rt.emit({ type: 'log', level: 'warn', message: 'x' });
+    rt.subscribe('q', () => {
+      throw new Error('subscriber bug');
+    });
+    rt.emit({ type: 'query:records', hash: 'q', records: [] });
+    expect(logs.at(-1)).toMatchObject({ error: new Error('subscriber bug') });
+    await expect(rt.waitFor(() => true)).resolves.toBeUndefined();
+    const ctrl = new AbortController();
+    ctrl.abort();
+    await expect(rt.waitFor(() => false, ctrl.signal)).rejects.toThrow('aborted');
+    const ctrl2 = new AbortController();
+    const p = rt.waitFor(() => false, ctrl2.signal);
+    ctrl2.abort();
+    await expect(p).rejects.toThrow('aborted');
+    await expect(
+      rt.waitFor(() => {
+        throw new Error('bad selector');
+      })
+    ).rejects.toThrow('bad selector');
+    let calls = 0;
+    const throwingLater = rt.waitFor(() => {
+      calls++;
+      if (calls > 1) throw new Error('bad selector later');
+      return false;
+    });
+    rt.update(R.setFailedCount(1));
+    await expect(throwingLater).rejects.toThrow('bad selector later');
+    const pending = rt.waitFor(() => false);
+    a.timers.pending.clear();
+    rt.update(R.markDirty(['q']));
+    expect(a.timers.pending.has('mat:q')).toBe(true);
+    rt.dispose();
+    await expect(pending).rejects.toThrow('disposed');
+    expect(a.timers.pending.size).toBe(0);
+    await rt.dispatch({ type: 'PollTick' });
+    expect(rt.update(R.setFailedCount(1))).toBeUndefined();
+  });
+  it('a disposed runtime ignores late timer fires', async () => {
+    const { a, rt } = make({}, buildState([buildEntry({ def: { hash: 'q' } })]));
+    rt.update(R.markDirty(['q']));
+    const fire = a.timers.pending.get('mat:q')!.fire;
+    rt.dispose();
+    fire();
+    await tick();
+    expect(rt.state.dirty.has('q')).toBe(true);
+  });
+});