@spooky-sync/core 0.0.1-canary.29 → 0.0.1-canary.290

package/src/client/router.ts

@@ -0,0 +1,100 @@
+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 { adoptPendingWrites, flushPendingWrites, 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 'FlushPendingWrites':
+      return { saga: flushPendingWrites() };
+    case 'AdoptPendingWrites':
+      return { saga: adoptPendingWrites(), 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,195 @@
+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 } })], R.reloadViews(new Map([['v', ['thing:1']]])))
+    );
+    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);
+  });
+});

package/src/client/runtime.ts

@@ -0,0 +1,296 @@
+import type { Logger } from '../services/logger/index';
+import type { QueryAuthorityCallback, QueryHash, QueryStatus, QueryStatusCallback, QueryUpdateCallback } from '../types';
+import type { OutEvent, RuntimeEvent } from '../kernel/events';
+import type { Adapters, Interpreter } from '../kernel/interpreter';
+import { createInterpreter } from '../kernel/interpreter';
+import type { Lane, Saga } from '../kernel/saga';
+import { runSaga } from '../kernel/saga';
+import type { ClientState } from '../state/client-state';
+import { emptyState } from '../state/client-state';
+import { deriveStatus, isAuthoritative } from '../state/lifecycle';
+import * as R from '../state/reducers';
+import { fetchingQueryCount, pendingMutationCount } from '../state/selectors';
+import type { SagaEnv } from '../query/env';
+import { route } from './router';
+
+interface Waiter {
+  until: (s: ClientState) => boolean;
+  resolve: () => void;
+  reject: (e: unknown) => void;
+}
+
+export interface RuntimeOptions {
+  env: SagaEnv;
+  adapters: Adapters;
+  logger: Logger;
+  tabId: string;
+  initialState?: ClientState;
+}
+
+/**
+ * The one effectful object of the engine: holds the state, runs sagas on
+ * lanes, fires timers, fans events out to subscribers and schedules
+ * materialization for dirty queries. No decision logic lives here.
+ */
+export class Runtime {
+  private stateValue: ClientState;
+  private readonly interpret: Interpreter;
+  private readonly env: SagaEnv;
+  private readonly adapters: Adapters;
+  private readonly logger: Logger;
+  private readonly serialLanes = new Map<string, Promise<unknown>>();
+  private readonly dedupeLanes = new Map<string, Promise<unknown>>();
+  private readonly waiters = new Set<Waiter>();
+  private readonly recordSubs = new Map<QueryHash, Set<QueryUpdateCallback>>();
+  private readonly statusSubs = new Map<QueryHash, Set<QueryStatusCallback>>();
+  private readonly authoritySubs = new Map<QueryHash, Set<QueryAuthorityCallback>>();
+  private readonly lastStatus = new Map<QueryHash, QueryStatus>();
+  private readonly listeners = new Map<string, Set<(event: OutEvent) => void>>();
+  private readonly scheduledMaterialize = new Set<QueryHash>();
+  private readonly timerKeys = new Set<string>();
+  private lastActivity = { fetching: 0, pending: 0 };
+  private lastHealth: ClientState['sync']['health'];
+  private disposed = false;
+
+  constructor(opts: RuntimeOptions) {
+    this.env = opts.env;
+    this.logger = opts.logger;
+    this.stateValue = opts.initialState ?? emptyState({ tabId: opts.tabId });
+    this.lastHealth = this.stateValue.sync.health;
+    const timers = opts.adapters.timers;
+    this.adapters = {
+      ...opts.adapters,
+      timers: {
+        set: (key, ms, fire) => {
+          this.timerKeys.add(key);
+          timers.set(key, ms, () => {
+            this.timerKeys.delete(key);
+            if (!this.disposed) fire();
+          });
+        },
+        clear: (key) => {
+          this.timerKeys.delete(key);
+          timers.clear(key);
+        },
+      },
+    };
+    this.interpret = createInterpreter(this.adapters, {
+      getState: () => this.stateValue,
+      setState: (next) => this.setState(next),
+      waitFor: (until, signal) => this.waitFor(until, signal),
+      emit: (event) => this.emit(event),
+      dispatch: (event) => void this.dispatch(event),
+    });
+  }
+
+  get state(): ClientState {
+    return this.stateValue;
+  }
+
+  /** Run a saga, optionally on a lane. Rejections propagate to the caller. */
+  run<R>(saga: Saga<R>, opts: { lane?: Lane; signal?: AbortSignal } = {}): Promise<R> {
+    const exec = () => runSaga(saga, (effect) => this.interpret(effect, { signal: opts.signal }));
+    const lane = opts.lane;
+    if (!lane) return exec();
+    if (lane.kind === 'dedupe') {
+      const running = this.dedupeLanes.get(lane.key);
+      if (running) return running as Promise<R>;
+      const p = exec().finally(() => {
+        if (this.dedupeLanes.get(lane.key) === p) this.dedupeLanes.delete(lane.key);
+      });
+      this.dedupeLanes.set(lane.key, p);
+      return p;
+    }
+    const prev = this.serialLanes.get(lane.key) ?? Promise.resolve();
+    const p = prev.then(exec, exec);
+    const tail = p.catch(() => undefined);
+    this.serialLanes.set(lane.key, tail);
+    void tail.then(() => {
+      if (this.serialLanes.get(lane.key) === tail) this.serialLanes.delete(lane.key);
+    });
+    return p;
+  }
+
+  /** Route an event to its saga. Never rejects: failures are logged. */
+  dispatch(event: RuntimeEvent): Promise<void> {
+    if (this.disposed) return Promise.resolve();
+    const target = route(this.env, event);
+    return this.run(target.saga, { lane: target.lane }).then(
+      () => undefined,
+      (error) => {
+        this.logger.error({ error, event: event.type, Category: 'sp00ky-client::Runtime::dispatch' }, 'saga failed');
+      }
+    );
+  }
+
+  private setState(next: ClientState): void {
+    const prev = this.stateValue;
+    if (next === prev) return;
+    this.stateValue = next;
+    for (const w of [...this.waiters]) {
+      let ok = false;
+      try {
+        ok = w.until(next);
+      } catch (error) {
+        this.waiters.delete(w);
+        w.reject(error);
+        continue;
+      }
+      if (ok) {
+        this.waiters.delete(w);
+        w.resolve();
+      }
+    }
+    for (const hash of next.dirty) {
+      if (this.scheduledMaterialize.has(hash)) continue;
+      this.scheduledMaterialize.add(hash);
+      this.adapters.timers.set(`mat:${hash}`, this.env.materializeDebounceMs, () => {
+        this.scheduledMaterialize.delete(hash);
+        void this.dispatch({ type: 'Materialize', hash });
+      });
+    }
+    for (const [hash, subs] of this.statusSubs) {
+      const entry = next.queries.get(hash);
+      if (!entry) continue;
+      const status = deriveStatus(entry.lifecycle);
+      if (this.lastStatus.get(hash) === status) continue;
+      this.lastStatus.set(hash, status);
+      for (const cb of subs) this.safely(() => cb(status));
+      this.notify({ type: 'query:status', hash, status });
+    }
+    const activity = { fetching: fetchingQueryCount(next), pending: pendingMutationCount(next) };
+    if (activity.fetching !== this.lastActivity.fetching || activity.pending !== this.lastActivity.pending) {
+      this.lastActivity = activity;
+      this.notify({ type: 'activity:changed', ...activity });
+    }
+    // Health is notified from here, not from the saga that folds a sync round:
+    // `connection` moves through `setConnection` on a transport event with no
+    // round attached, and a subscriber that only heard the round would show a
+    // stale socket state forever. `setHealth` keeps the identity stable while
+    // the values are unchanged, so this fires exactly on real transitions.
+    if (next.sync.health !== this.lastHealth) {
+      this.lastHealth = next.sync.health;
+      this.notify({ type: 'health:changed', health: next.sync.health });
+    }
+  }
+
+  waitFor(until: (s: ClientState) => boolean, signal?: AbortSignal): Promise<void> {
+    try {
+      if (until(this.stateValue)) return Promise.resolve();
+    } catch (error) {
+      return Promise.reject(error);
+    }
+    if (signal?.aborted) return Promise.reject(new Error('aborted'));
+    return new Promise<void>((resolve, reject) => {
+      const waiter: Waiter = { until, resolve, reject };
+      this.waiters.add(waiter);
+      signal?.addEventListener(
+        'abort',
+        () => {
+          if (this.waiters.delete(waiter)) reject(new Error('aborted'));
+        },
+        { once: true }
+      );
+    });
+  }
+
+  /** Deliver an outbound event to its subscribers and listeners. */
+  emit(event: OutEvent): void {
+    switch (event.type) {
+      case 'query:records':
+        for (const cb of this.recordSubs.get(event.hash) ?? []) this.safely(() => cb(event.records as Record<string, any>[]));
+        break;
+      case 'query:authority':
+        for (const cb of this.authoritySubs.get(event.hash) ?? []) this.safely(() => cb(event.known));
+        break;
+      case 'log':
+        this.logger[event.level](Object.assign({}, event.data as object | undefined, { Category: 'sp00ky-client::saga' }), event.message);
+        break;
+      default:
+        break;
+    }
+    this.notify(event);
+  }
+
+  private notify(event: OutEvent): void {
+    for (const cb of this.listeners.get(event.type) ?? []) this.safely(() => cb(event));
+    for (const cb of this.listeners.get('*') ?? []) this.safely(() => cb(event));
+  }
+
+  private safely(fn: () => void): void {
+    try {
+      fn();
+    } catch (error) {
+      this.logger.error({ error, Category: 'sp00ky-client::Runtime::subscriber' }, 'subscriber threw');
+    }
+  }
+
+  /** Observe outbound events by type (`'*'` for all). */
+  on(type: OutEvent['type'] | '*', cb: (event: OutEvent) => void): () => void {
+    const set = this.listeners.get(type) ?? new Set();
+    set.add(cb);
+    this.listeners.set(type, set);
+    return () => void set.delete(cb);
+  }
+
+  subscribe(hash: QueryHash, cb: QueryUpdateCallback, options: { immediate?: boolean } = {}): () => void {
+    const set = this.recordSubs.get(hash) ?? new Set();
+    set.add(cb);
+    this.recordSubs.set(hash, set);
+    this.setState(R.subscribe(hash)(this.stateValue));
+    if (options.immediate) {
+      const entry = this.stateValue.queries.get(hash);
+      if (entry) this.safely(() => cb(entry.records as Record<string, any>[]));
+    }
+    return () => {
+      if (!set.delete(cb)) return;
+      if (set.size === 0) this.recordSubs.delete(hash);
+      this.setState(R.unsubscribe(hash, this.adapters.clock.now())(this.stateValue));
+    };
+  }
+
+  subscribeStatus(hash: QueryHash, cb: QueryStatusCallback, options: { immediate?: boolean } = {}): () => void {
+    const set = this.statusSubs.get(hash) ?? new Set();
+    set.add(cb);
+    this.statusSubs.set(hash, set);
+    const entry = this.stateValue.queries.get(hash);
+    if (entry) {
+      const status = deriveStatus(entry.lifecycle);
+      this.lastStatus.set(hash, status);
+      if (options.immediate) this.safely(() => cb(status));
+    }
+    return () => {
+      set.delete(cb);
+      if (set.size === 0) {
+        this.statusSubs.delete(hash);
+        this.lastStatus.delete(hash);
+      }
+    };
+  }
+
+  subscribeAuthority(hash: QueryHash, cb: QueryAuthorityCallback, options: { immediate?: boolean } = {}): () => void {
+    const set = this.authoritySubs.get(hash) ?? new Set();
+    set.add(cb);
+    this.authoritySubs.set(hash, set);
+    if (options.immediate) {
+      const entry = this.stateValue.queries.get(hash);
+      if (entry) this.safely(() => cb(isAuthoritative(entry.lifecycle)));
+    }
+    return () => {
+      set.delete(cb);
+      if (set.size === 0) this.authoritySubs.delete(hash);
+    };
+  }
+
+  /** Apply a reducer outside a saga (facade conveniences such as timing reports). */
+  update(reducer: (s: ClientState) => ClientState): void {
+    this.setState(reducer(this.stateValue));
+  }
+
+  dispose(): void {
+    this.disposed = true;
+    for (const key of [...this.timerKeys]) this.adapters.timers.clear(key);
+    for (const w of this.waiters) w.reject(new Error('runtime disposed'));
+    this.waiters.clear();
+  }
+}