@spooky-sync/core 0.0.1-canary.32 → 0.0.1-canary.321

package/src/kernel/constants.test.ts

@@ -0,0 +1,19 @@
+import { describe, expect, it } from 'vitest';
+import { backoffMs, RETRY_BASE_MS, RETRY_MAX_MS } from './constants';
+
+describe('backoffMs', () => {
+  it('doubles from the base and caps at the max', () => {
+    expect(backoffMs(0)).toBe(RETRY_BASE_MS);
+    expect(backoffMs(1)).toBe(RETRY_BASE_MS * 2);
+    expect(backoffMs(3)).toBe(RETRY_BASE_MS * 8);
+    expect(backoffMs(20)).toBe(RETRY_MAX_MS);
+  });
+  it('clamps negative and huge attempts', () => {
+    expect(backoffMs(-5)).toBe(RETRY_BASE_MS);
+    expect(backoffMs(10_000)).toBe(RETRY_MAX_MS);
+  });
+  it('honours custom base and max', () => {
+    expect(backoffMs(2, 100, 250)).toBe(250);
+    expect(backoffMs(1, 100, 250)).toBe(200);
+  });
+});

package/src/kernel/constants.ts

@@ -0,0 +1,80 @@
+/**
+ * Every timing constant of the saga core in one place. Sagas never call
+ * `setTimeout`; they yield `timer.set` effects with one of these delays, so a
+ * test can pin the schedule by asserting the effect log.
+ */
+
+/** Trailing coalesce for materialization after a state change. */
+export const MATERIALIZE_DEBOUNCE_MS = 50;
+/** Coalesce window for LIVE membership dirt before the batched edge re-read. */
+export const MEMBERSHIP_COALESCE_MS = 50;
+/** Re-read ladder while the server reports a view as `materializing`. */
+export const MATERIALIZING_REREAD_LADDER_MS: readonly number[] = [150, 400, 1000];
+/** How long an acked outbox item stays in the overlay when membership never names it. */
+export const ACK_GRACE_MS = 30_000;
+/** Ids per body-fetch statement. */
+export const FETCH_CHUNK = 500;
+/** Outbox statements per push request. */
+export const OUTBOX_BATCH_SIZE = 50;
+/** Push deadline per outbox batch. */
+export const PUSH_TIMEOUT_MS = 30_000;
+/** Exponential backoff for outbox / fetch / registration retries. */
+export const RETRY_BASE_MS = 500;
+export const RETRY_MAX_MS = 15_000;
+/** Registration attempts before a query is reported as failed to settle. */
+export const REGISTER_MAX_RETRIES = 3;
+/**
+ * Pacing of repeated view-lost recovery. The first re-registration after a
+ * `_00_query` row reads as gone is immediate; each further one for the same
+ * query, before the row has been seen again, waits on this backoff.
+ */
+export const VIEW_LOST_RETRY_BASE_MS = 1_000;
+export const VIEW_LOST_RETRY_MAX_MS = 30_000;
+/** `_00_list_ref` poll cadence (fallback when LIVE is quiet). */
+export const LIST_REF_POLL_BASE_MS = 500;
+export const LIST_REF_POLL_MAX_MS = 5_000;
+export const LIST_REF_ROW_BUDGET = 1_500;
+export const LIST_REF_LARGE_VIEW_EDGES = 1_000;
+export const LIST_REF_LARGE_VIEW_POLL_MS = 15_000;
+/** Self-heal cadence while sync health is degraded. */
+export const SELF_HEAL_BASE_MS = 2_000;
+export const SELF_HEAL_MAX_MS = 30_000;
+/** Consecutive failed rounds before health flips to degraded. */
+export const DEGRADE_AFTER_FAILURES = 3;
+/** Burst coalescing of reconnects. */
+export const RECONNECT_REFETCH_COOLDOWN_MS = 10_000;
+/** Waiting for `$auth.id` to be visible after a reconnect. */
+export const AUTH_READY_RETRY_MS = 500;
+export const AUTH_READY_MAX_ATTEMPTS = 10;
+/** Heartbeat at this fraction of the shortest ttl in state. */
+export const TTL_HEARTBEAT_FRACTION = 0.5;
+/**
+ * How long past its due flush another tab's `_00_pending_writes` row may sit
+ * before it counts as abandoned (its tab died before the flush) and is moved
+ * into the outbox here.
+ */
+export const PENDING_WRITE_ORPHAN_MS = 3_000;
+/**
+ * Orphan body garbage collection: the first sweep waits this long after boot
+ * (off the first paint and the first sync round), then repeats on the interval.
+ */
+export const GC_BOOT_DELAY_MS = 30_000;
+export const GC_INTERVAL_MS = 60 * 60 * 1000;
+/** Ids deleted per GC step. */
+export const GC_CHUNK = 200;
+/**
+ * A `_00_view` row no query has resolved for this long stops vouching for its
+ * ids (the sweep deletes it, so its bodies can be collected). Each session
+ * that resolves a query rewrites its row, so this only retires query shapes
+ * the app no longer runs.
+ */
+export const VIEW_RETENTION_MS = 14 * 24 * 60 * 60 * 1000;
+/** Remote adapter slot limit. */
+export const REMOTE_CONCURRENCY = 16;
+/** Rolling telemetry sample window per query. */
+export const TELEMETRY_SAMPLE_WINDOW = 100;
+
+export function backoffMs(attempt: number, base = RETRY_BASE_MS, max = RETRY_MAX_MS): number {
+  const n = Math.max(0, Math.min(attempt, 30));
+  return Math.min(max, base * 2 ** n);
+}

package/src/kernel/effects.test.ts

@@ -0,0 +1,40 @@
+import { describe, expect, it } from 'vitest';
+import { fx } from './effects';
+
+describe('effect constructors', () => {
+  it('build every effect kind as plain data', () => {
+    const sealed = { sql: 'x;', extract: (r: unknown[]) => r[0] };
+    const plan = { table: 't' } as any;
+    const cases: Array<[ReturnType<typeof fx.now>, string]> = [
+      [fx.local.query('SELECT 1', { a: 1 }, 3), 'local.query'],
+      [fx.local.select(plan, { b: 2 }), 'local.select'],
+      [fx.local.execute(sealed, {}, 1), 'local.execute'],
+      [fx.local.getById('t', 'x'), 'local.getById'],
+      [fx.local.upsert('t', 'x', { a: 1 }, 'merge'), 'local.upsert'],
+      [fx.local.delete('t', 'x'), 'local.delete'],
+      [fx.remote.query('RETURN true', undefined, 10), 'remote.query'],
+      [fx.remote.live('_00_list_ref'), 'remote.live'],
+      [fx.remote.kill('u'), 'remote.kill'],
+      [fx.ssp.register({ queryHash: 'h', surql: 's', params: {}, ttl: '10m', tableName: 't' }), 'ssp.register'],
+      [fx.ssp.unregister('h'), 'ssp.unregister'],
+      [fx.ssp.ingest([]), 'ssp.ingest'],
+      [fx.timer.set('k', 5, { type: 'Drain' }), 'timer.set'],
+      [fx.timer.clear('k'), 'timer.clear'],
+      [fx.state.read((s) => s.tabId), 'state.read'],
+      [fx.state.update((s) => s), 'state.update'],
+      [fx.state.wait((s) => s.primed), 'state.wait'],
+      [fx.now(), 'now'],
+      [fx.id('mutation'), 'id'],
+      [fx.hash('abc'), 'hash'],
+      [fx.emit({ type: 'tray:changed', count: 1 }), 'emit'],
+      [fx.dispatch({ type: 'FetchRows' }), 'dispatch'],
+      [fx.all([fx.now()]), 'all'],
+      [fx.service('local.connect', 'anon'), 'service'],
+    ];
+    for (const [effect, kind] of cases) expect(effect.kind).toBe(kind);
+    expect(fx.local.query('SELECT 1', { a: 1 }, 3)).toEqual({ kind: 'local.query', sql: 'SELECT 1', vars: { a: 1 }, epoch: 3 });
+    expect(fx.local.epoch()).toEqual({ kind: 'local.epoch' });
+    expect(fx.timer.set('k', 5, { type: 'Drain' })).toEqual({ kind: 'timer.set', key: 'k', ms: 5, event: { type: 'Drain' } });
+    expect(fx.service('hint.write', 'u1')).toEqual({ kind: 'service', name: 'hint.write', args: ['u1'] });
+  });
+});

package/src/kernel/effects.ts

@@ -0,0 +1,163 @@
+import type { QueryPlan } from '@spooky-sync/query-builder';
+import type { SealedQuery } from '../utils/surql';
+import type { ClientState } from '../state/client-state';
+import type { IngestRecord } from '../services/stream-processor/index';
+import type { RecordVersionArray, RegistrationTimings } from '../types';
+import type { OutEvent, RuntimeEvent } from './events';
+
+export type Vars = Record<string, unknown>;
+
+/** What the in-browser SSP needs to build a local view. */
+export interface RegisterPlan {
+  queryHash: string;
+  surql: string;
+  params: Vars;
+  ttl: string;
+  tableName: string;
+  involvedTables?: string[];
+}
+export interface RegisterResult {
+  localArray: RecordVersionArray;
+  timings: RegistrationTimings;
+}
+
+/** One statement's outcome of a multi-statement remote request. */
+export type StatementResult =
+  | { status: 'OK'; result: unknown }
+  | { status: 'ERR'; error: string };
+
+/** One entry of an `all` fan-out result (allSettled semantics). */
+export type Settled<T = unknown> = { ok: true; value: T } | { ok: false; error: unknown };
+
+/**
+ * Effects are data. A saga yields one and gets its result back on the next
+ * `next()`; the interpreter (client/runtime) is the only place they execute.
+ */
+export type Effect =
+  | { kind: 'local.query'; sql: string; vars?: Vars; epoch?: number }
+  | { kind: 'local.select'; plan: QueryPlan; params?: Vars }
+  | { kind: 'local.execute'; query: SealedQuery<unknown>; vars?: Vars; epoch?: number }
+  | { kind: 'local.getById'; table: string; id: unknown }
+  | { kind: 'local.upsert'; table: string; id: unknown; data: Record<string, unknown>; mode: 'replace' | 'merge' }
+  | { kind: 'local.delete'; table: string; id: unknown }
+  | { kind: 'local.epoch' }
+  | { kind: 'remote.query'; sql: string; vars?: Vars; timeoutMs?: number }
+  | { kind: 'remote.live'; table: string }
+  | { kind: 'remote.kill'; uuid: string }
+  | { kind: 'ssp.register'; plan: RegisterPlan }
+  | { kind: 'ssp.unregister'; hash: string }
+  | { kind: 'ssp.ingest'; records: IngestRecord[] }
+  | { kind: 'timer.set'; key: string; ms: number; event: RuntimeEvent }
+  | { kind: 'timer.clear'; key: string }
+  | { kind: 'state.read'; select: (s: ClientState) => unknown }
+  | { kind: 'state.update'; fn: (s: ClientState) => ClientState }
+  | { kind: 'state.wait'; until: (s: ClientState) => boolean }
+  | { kind: 'now' }
+  | { kind: 'id'; scope: 'mutation' | 'salt' }
+  | { kind: 'hash'; input: string }
+  | { kind: 'emit'; event: OutEvent }
+  | { kind: 'dispatch'; event: RuntimeEvent }
+  | { kind: 'all'; effects: Effect[] }
+  | { kind: 'service'; name: ServiceName; args: unknown[] };
+
+export type EffectKind = Effect['kind'];
+
+/**
+ * Calls into the legacy services that are adapters, not state: auth, tabs,
+ * blobs, migrator, crdt, persistence, the SSP lifecycle, the remote socket.
+ * A saga names the call; the runtime binds it to the real service.
+ */
+export interface ServiceCalls {
+  'hint.read': () => string | null;
+  'hint.write': (bucketId: string) => void;
+  'salt.take': (authId: string | null) => string | null;
+  'salt.leave': (salt: string, authId: string | null) => void;
+  'local.connect': (bucketId: string) => Promise<void>;
+  'local.switchStore': (bucketId: string) => Promise<void>;
+  'local.beginSwitch': () => () => void;
+  'local.currentBucketId': () => string;
+  'local.usesSurqlSchema': () => boolean;
+  'local.dropBucket': (bucketId: string) => Promise<void>;
+  'migrator.provision': () => Promise<void>;
+  'blobs.start': (bucketId: string) => Promise<void>;
+  'blobs.setNamespace': (bucketId: string) => Promise<void>;
+  'blobs.clear': () => Promise<void>;
+  'ssp.init': () => Promise<void>;
+  'ssp.setPermissions': () => void;
+  'ssp.setSessionAuth': (authId: string | null, access: string | null) => void;
+  'ssp.prime': (pendingIds: string[]) => Promise<void>;
+  'ssp.reset': () => Promise<void>;
+  'ssp.setPersistence': (enabled: boolean) => void;
+  'auth.restoreSession': () => Promise<string | null>;
+  'auth.init': () => Promise<void>;
+  'auth.sessionAuthId': () => string | null;
+  'auth.access': () => string | null;
+  'auth.token': () => string | null;
+  'auth.currentUser': () => Record<string, unknown> | null;
+  'auth.consumeEndedImpersonation': () => string | null;
+  'remote.connect': () => Promise<void>;
+  'remote.releaseViews': (ids: unknown[]) => void;
+  'supervisor.start': () => void;
+  'tabs.start': (bucketId: string) => Promise<'solo' | 'leader' | 'follower'>;
+  'tabs.moveToBucket': (bucketId: string) => Promise<'solo' | 'leader' | 'follower'>;
+  'crdt.setSessionId': (sessionId: string) => void;
+  'crdt.closeAll': (flush: boolean) => void;
+  'persistence.set': (key: string, value: unknown) => Promise<void>;
+  'features.init': () => void;
+  'releases.init': () => void;
+  'window.attach': () => void;
+}
+export type ServiceName = keyof ServiceCalls;
+
+/** Typed constructors. Each is one line so the saga reads like the plan. */
+export const fx = {
+  local: {
+    query: (sql: string, vars?: Vars, epoch?: number): Effect => ({ kind: 'local.query', sql, vars, epoch }),
+    select: (plan: QueryPlan, params?: Vars): Effect => ({ kind: 'local.select', plan, params }),
+    execute: (query: SealedQuery<unknown>, vars?: Vars, epoch?: number): Effect => ({
+      kind: 'local.execute',
+      query,
+      vars,
+      epoch,
+    }),
+    getById: (table: string, id: unknown): Effect => ({ kind: 'local.getById', table, id }),
+    upsert: (table: string, id: unknown, data: Record<string, unknown>, mode: 'replace' | 'merge'): Effect => ({
+      kind: 'local.upsert',
+      table,
+      id,
+      data,
+      mode,
+    }),
+    delete: (table: string, id: unknown): Effect => ({ kind: 'local.delete', table, id }),
+    /** The store's current epoch; a write fenced with it is dropped after a bucket switch or transport failover. */
+    epoch: (): Effect => ({ kind: 'local.epoch' }),
+  },
+  remote: {
+    query: (sql: string, vars?: Vars, timeoutMs?: number): Effect => ({ kind: 'remote.query', sql, vars, timeoutMs }),
+    /** Subscribe to `LIVE SELECT * FROM <table>`; resolves to the live uuid. */
+    live: (table: string): Effect => ({ kind: 'remote.live', table }),
+    kill: (uuid: string): Effect => ({ kind: 'remote.kill', uuid }),
+  },
+  ssp: {
+    register: (plan: RegisterPlan): Effect => ({ kind: 'ssp.register', plan }),
+    unregister: (hash: string): Effect => ({ kind: 'ssp.unregister', hash }),
+    ingest: (records: IngestRecord[]): Effect => ({ kind: 'ssp.ingest', records }),
+  },
+  timer: {
+    set: (key: string, ms: number, event: RuntimeEvent): Effect => ({ kind: 'timer.set', key, ms, event }),
+    clear: (key: string): Effect => ({ kind: 'timer.clear', key }),
+  },
+  state: {
+    read: <T>(select: (s: ClientState) => T): Effect => ({ kind: 'state.read', select }),
+    update: (fn: (s: ClientState) => ClientState): Effect => ({ kind: 'state.update', fn }),
+    /** Suspend until `until(state)` holds (checked after every state.update). */
+    wait: (until: (s: ClientState) => boolean): Effect => ({ kind: 'state.wait', until }),
+  },
+  now: (): Effect => ({ kind: 'now' }),
+  id: (scope: 'mutation' | 'salt'): Effect => ({ kind: 'id', scope }),
+  hash: (input: string): Effect => ({ kind: 'hash', input }),
+  emit: (event: OutEvent): Effect => ({ kind: 'emit', event }),
+  dispatch: (event: RuntimeEvent): Effect => ({ kind: 'dispatch', event }),
+  all: (effects: Effect[]): Effect => ({ kind: 'all', effects }),
+  service: <N extends ServiceName>(name: N, ...args: Parameters<ServiceCalls[N]>): Effect => ({ kind: 'service', name, args }),
+} as const;

package/src/kernel/events.ts

@@ -0,0 +1,57 @@
+import type { ConnectionState, InlineRow, QueryHash, QueryStatus, SyncHealth } from '../types';
+import type { StreamUpdate } from '../services/stream-processor/index';
+
+/**
+ * Inbound events. Everything that can start a saga arrives as one of these
+ * through the runtime router: public API calls, adapter callbacks, timers,
+ * and `dispatch` effects from other sagas.
+ */
+export type RuntimeEvent =
+  | { type: 'EnsureRegistered'; requireAuth?: boolean; attempt?: number }
+  | { type: 'RegisterRemote'; hash: QueryHash; retry?: boolean }
+  | { type: 'SyncOutcome'; ok: boolean; error?: unknown }
+  | { type: 'AckPrune' }
+  | { type: 'ReadDirtyMembership' }
+  | { type: 'RecoverLostView'; hash: QueryHash }
+  | { type: 'ReadMembership'; hashes: QueryHash[] }
+  | { type: 'FetchRows' }
+  | { type: 'Materialize'; hash: QueryHash }
+  | { type: 'MaterializeDirty' }
+  | { type: 'LifecycleTick' }
+  | { type: 'GcTick' }
+  | { type: 'Drain' }
+  | { type: 'FlushWrite'; key: string }
+  | { type: 'FlushPendingWrites' }
+  | { type: 'AdoptPendingWrites' }
+  | { type: 'PollTick' }
+  | { type: 'SelfHealTick' }
+  | { type: 'HeartbeatNow' }
+  | { type: 'StartRemote' }
+  | { type: 'PrimeCircuit' }
+  | { type: 'VersionsPrimed'; entries: Array<readonly [string, number]> }
+  | { type: 'WarmBlobs' }
+  | { type: 'AuthFlip'; userId: string | null }
+  | { type: 'BucketSwitch'; target: string }
+  | { type: 'PageHide' }
+  | { type: 'ConnectionChanged'; state: ConnectionState }
+  | { type: 'StreamUpdate'; update: StreamUpdate }
+  | { type: 'LiveStart' }
+  | { type: 'LiveChange'; hashes: QueryHash[]; rows?: InlineRow[] }
+  | { type: 'TabRole'; role: 'solo' | 'leader' | 'follower' }
+  | { type: 'TabMessage'; message: unknown };
+
+export type OutEvent =
+  | { type: 'query:records'; hash: QueryHash; records: ReadonlyArray<Record<string, unknown>> }
+  | { type: 'query:status'; hash: QueryHash; status: QueryStatus }
+  | { type: 'query:authority'; hash: QueryHash; known: boolean }
+  | { type: 'query:view-lost'; hash: QueryHash }
+  | { type: 'query:evicted'; hash: QueryHash }
+  | { type: 'mutation:event'; event: unknown }
+  | { type: 'mutation:settled'; mutationId: string; recordId: string; eventType: string }
+  | { type: 'mutation:rolled-back'; mutationId: string; recordId: string; eventType: string; error: string }
+  | { type: 'tray:changed'; count: number }
+  | { type: 'health:changed'; health: SyncHealth }
+  | { type: 'activity:changed'; fetching: number; pending: number }
+  | { type: 'tabs:broadcast'; message: unknown }
+  | { type: 'tabs:sendTo'; tabId: string; message: unknown }
+  | { type: 'log'; level: 'debug' | 'info' | 'warn' | 'error'; message: string; data?: unknown };

package/src/kernel/interpreter.test.ts

@@ -0,0 +1,116 @@
+import { describe, expect, it } from 'vitest';
+import { RecordId } from 'surrealdb';
+import { fakeAdapters, fakeHost } from '../testing/adapters';
+import { createInterpreter } from './interpreter';
+import { fx } from './effects';
+import { setFailedCount } from '../state/reducers';
+
+describe('interpreter', () => {
+  it('routes store, remote, ssp and service effects to the adapters', async () => {
+    const a = fakeAdapters({
+      remote: { queryResponses: async () => [{ status: 'OK', result: 1 }] },
+      ssp: {
+        registerQueryPlan: (plan) => ({ queryHash: plan.queryHash, localArray: [['t:1', 1]], registration: { parseMs: 1, planMs: 2, snapshotMs: 3 } }),
+      },
+      services: { 'hint.read': () => 'u1' },
+    });
+    const h = fakeHost();
+    const run = createInterpreter(a.adapters, h.host);
+    const sealed = { sql: 'SELECT 1;', extract: (r: unknown[]) => r };
+    await run(fx.local.query('SELECT 1', { a: 1 }, 2));
+    await run(fx.local.query('SELECT 2'));
+    await run(fx.local.execute(sealed, {}, 1));
+    await run(fx.local.select({ table: 't' } as any, {}));
+    await run(fx.local.getById('t', 'x'));
+    await run(fx.local.upsert('t', 'x', { a: 1 }, 'merge'));
+    await run(fx.local.delete('t', 'x'));
+    expect(await run(fx.local.epoch())).toBe(0);
+    expect(await run(fx.remote.query('RETURN 1'))).toEqual([{ status: 'OK', result: 1 }]);
+    expect(await run(fx.remote.live('_00_list_ref'))).toBe('live-uuid');
+    await run(fx.remote.kill('live-uuid'));
+    const reg = await run(fx.ssp.register({ queryHash: 'h', surql: 's', params: {}, ttl: '10m', tableName: 't' }));
+    expect(reg).toEqual({ localArray: [['t:1', 1]], timings: { parseMs: 1, planMs: 2, snapshotMs: 3, wallMs: null } });
+    await run(fx.ssp.unregister('h'));
+    await run(fx.ssp.ingest([]));
+    expect(await run(fx.service('hint.read'))).toBe('u1');
+    expect(a.names()).toEqual([
+      'local.query', 'local.query', 'local.execute', 'local.select', 'local.getById', 'local.upsert', 'local.delete',
+      'remote.live', 'remote.kill', 'ssp.unregister', 'ssp.ingest', 'service.hint.read',
+    ]);
+    expect(a.calls[0]).toEqual(['local.query', ['SELECT 1', { a: 1 }]]);
+  });
+
+  it('ssp.register without a result throws; ssp.register uses default timings when the SSP reports none', async () => {
+    const empty = fakeAdapters({ ssp: { registerQueryPlan: () => undefined } });
+    const h = fakeHost();
+    await expect(createInterpreter(empty.adapters, h.host)(fx.ssp.register({ queryHash: 'h', surql: 's', params: {}, ttl: '1m', tableName: 't' }))).rejects.toThrow(/not initialized/);
+    const bare = fakeAdapters();
+    const reg = await createInterpreter(bare.adapters, h.host)(fx.ssp.register({ queryHash: 'h', surql: 's', params: {}, ttl: '1m', tableName: 't' }));
+    expect(reg).toEqual({ localArray: [], timings: { parseMs: null, planMs: null, snapshotMs: null, wallMs: null } });
+  });
+
+  it('remote.query honours the per-effect timeout', async () => {
+    const slow = fakeAdapters({ remote: { queryResponses: () => new Promise(() => {}) } });
+    const h = fakeHost();
+    await expect(createInterpreter(slow.adapters, h.host)(fx.remote.query('SLOW', undefined, 5))).rejects.toThrow(/timed out/);
+  });
+
+  it('state, wait, clock, ids, hash, timers, emit, dispatch, all', async () => {
+    const a = fakeAdapters({ now: 42 });
+    const h = fakeHost();
+    const run = createInterpreter(a.adapters, h.host);
+    expect(await run(fx.state.read((s) => s.tabId))).toBe('tab-a');
+    await run(fx.state.update(setFailedCount(2)));
+    expect(h.state.failedCount).toBe(2);
+    await run(fx.state.wait((s) => s.failedCount === 2));
+    const waiting = run(fx.state.wait((s) => s.failedCount === 3));
+    h.host.setState(setFailedCount(3)(h.state));
+    await waiting;
+    const ctrl = new AbortController();
+    const aborted = run(fx.state.wait(() => false), { signal: ctrl.signal });
+    ctrl.abort();
+    await expect(aborted).rejects.toThrow('aborted');
+    expect(await run(fx.now())).toBe(42);
+    expect(String(await run(fx.id('mutation')))).toMatch(/^_00_pending_mutations:/);
+    expect(String(await run(fx.id('salt')))).toMatch(/^salt-/);
+    expect(await run(fx.hash('abc'))).toMatch(/^ba7816bf/);
+    await run(fx.timer.set('k', 10, { type: 'Drain' }));
+    expect(a.timers.pending.has('k')).toBe(true);
+    a.timers.fire('k');
+    expect(h.dispatched).toEqual([{ type: 'Drain' }]);
+    await run(fx.timer.set('j', 1, { type: 'FetchRows' }));
+    await run(fx.timer.clear('j'));
+    expect(a.timers.pending.has('j')).toBe(false);
+    await run(fx.emit({ type: 'tray:changed', count: 1 }));
+    expect(h.emitted).toEqual([{ type: 'tray:changed', count: 1 }]);
+    await run(fx.dispatch({ type: 'PollTick' }));
+    expect(h.dispatched.at(-1)).toEqual({ type: 'PollTick' });
+    const settled = await run(fx.all([fx.now(), fx.remote.query('x'), fx.service('hint.read')]));
+    expect(settled).toEqual([{ ok: true, value: 42 }, { ok: true, value: [] }, { ok: true, value: undefined }]);
+    const failing = fakeAdapters({
+      remote: {
+        queryResponses: async () => {
+          throw new Error('boom');
+        },
+      },
+    });
+    const mixed = await createInterpreter(failing.adapters, h.host)(fx.all([fx.remote.query('x'), fx.now()]));
+    expect(mixed).toEqual([{ ok: false, error: new Error('boom') }, { ok: true, value: 1_700_000_000_000 }]);
+  });
+
+  it('live events reach the host as LiveChange dispatches', async () => {
+    let onChange: ((h: string[]) => void) | null = null;
+    const a = fakeAdapters({
+      remote: {
+        live: async (_t, cb) => {
+          onChange = cb;
+          return 'u';
+        },
+      },
+    });
+    const h = fakeHost();
+    await createInterpreter(a.adapters, h.host)(fx.remote.live('_00_list_ref'));
+    onChange!(['a', 'b']);
+    expect(h.dispatched).toEqual([{ type: 'LiveChange', hashes: ['a', 'b'] }]);
+  });
+});

package/src/kernel/interpreter.ts

@@ -0,0 +1,148 @@
+import { Duration } from 'surrealdb';
+import type { LocalStore } from '../services/database/cache-engine';
+import type { IngestRecord, StreamUpdate } from '../services/stream-processor/index';
+import type { ClientState } from '../state/client-state';
+import type { InlineRow } from '../types';
+import { withTimeout } from '../utils/index';
+import type { Effect, RegisterResult, ServiceCalls, Settled, StatementResult } from './effects';
+import type { OutEvent, RuntimeEvent } from './events';
+
+/** The five adapters plus the pure ports, as the interpreter sees them. */
+export interface Adapters {
+  local: Pick<LocalStore, 'query' | 'execute' | 'select' | 'getById' | 'upsert' | 'delete'> & { readonly epoch: number };
+  remote: {
+    queryResponses(sql: string, vars?: Record<string, unknown>): Promise<StatementResult[]>;
+    /**
+     * Subscribe to `LIVE SELECT * FROM <table>`; the callback receives the
+     * changed query hashes, plus the changed rows themselves when the
+     * subscription was opened with the body joined on (`liveInlineBodies`).
+     */
+    live(table: string, onChange: (hashes: string[], rows?: InlineRow[]) => void): Promise<string>;
+    kill(uuid: string): Promise<void>;
+  };
+  ssp: {
+    registerQueryPlan(plan: {
+      queryHash: string;
+      surql: string;
+      params: Record<string, unknown>;
+      ttl: Duration;
+      lastActiveAt: Date;
+      localArray: [];
+      remoteArray: [];
+      meta: { tableName: string; involvedTables?: string[] };
+    }): StreamUpdate | undefined;
+    unregisterQueryPlan(hash: string): void;
+    ingestMany(records: IngestRecord[]): unknown;
+  };
+  timers: { set(key: string, ms: number, fire: () => void): void; clear(key: string): void };
+  clock: { now(): number };
+  ids: { mutation(): string; salt(): string };
+  hash(input: string): Promise<string>;
+  services: ServiceCalls;
+}
+
+/** What the interpreter needs from the runtime: state, waiting, emitting, dispatching. */
+export interface InterpreterHost {
+  getState(): ClientState;
+  setState(next: ClientState): void;
+  waitFor(until: (s: ClientState) => boolean, signal?: AbortSignal): Promise<void>;
+  emit(event: OutEvent): void;
+  dispatch(event: RuntimeEvent): void;
+}
+
+export interface RunContext {
+  signal?: AbortSignal;
+}
+
+export type Interpreter = (effect: Effect, ctx?: RunContext) => Promise<unknown>;
+
+/** Effects become adapter calls here and nowhere else. */
+export function createInterpreter(adapters: Adapters, host: InterpreterHost): Interpreter {
+  const interpret: Interpreter = async (effect, ctx) => {
+    switch (effect.kind) {
+      case 'local.query':
+        return adapters.local.query(effect.sql, effect.vars, effect.epoch === undefined ? undefined : { epoch: effect.epoch });
+      case 'local.select':
+        return adapters.local.select(effect.plan, effect.params);
+      case 'local.execute':
+        return adapters.local.execute(effect.query, effect.vars, effect.epoch === undefined ? undefined : { epoch: effect.epoch });
+      case 'local.getById':
+        return adapters.local.getById(effect.table, effect.id);
+      case 'local.upsert':
+        return adapters.local.upsert(effect.table, effect.id, effect.data, effect.mode);
+      case 'local.delete':
+        return adapters.local.delete(effect.table, effect.id);
+      case 'local.epoch':
+        return adapters.local.epoch;
+      case 'remote.query': {
+        const pending = adapters.remote.queryResponses(effect.sql, effect.vars);
+        return effect.timeoutMs
+          ? withTimeout(pending, effect.timeoutMs, () => new Error(`Remote request timed out after ${effect.timeoutMs}ms`))
+          : pending;
+      }
+      case 'remote.live':
+        return adapters.remote.live(effect.table, (hashes, rows) => host.dispatch({ type: 'LiveChange', hashes, rows }));
+      case 'remote.kill':
+        return adapters.remote.kill(effect.uuid);
+      case 'ssp.register': {
+        const update = adapters.ssp.registerQueryPlan({
+          queryHash: effect.plan.queryHash,
+          surql: effect.plan.surql,
+          params: effect.plan.params,
+          ttl: new Duration(effect.plan.ttl),
+          lastActiveAt: new Date(adapters.clock.now()),
+          localArray: [],
+          remoteArray: [],
+          meta: { tableName: effect.plan.tableName, involvedTables: effect.plan.involvedTables },
+        });
+        if (!update) throw new Error('Stream processor is not initialized');
+        const result: RegisterResult = {
+          localArray: update.localArray,
+          timings: {
+            parseMs: update.registration?.parseMs ?? null,
+            planMs: update.registration?.planMs ?? null,
+            snapshotMs: update.registration?.snapshotMs ?? null,
+            wallMs: null,
+          },
+        };
+        return result;
+      }
+      case 'ssp.unregister':
+        return adapters.ssp.unregisterQueryPlan(effect.hash);
+      case 'ssp.ingest':
+        return adapters.ssp.ingestMany(effect.records);
+      case 'timer.set':
+        return adapters.timers.set(effect.key, effect.ms, () => host.dispatch(effect.event));
+      case 'timer.clear':
+        return adapters.timers.clear(effect.key);
+      case 'state.read':
+        return effect.select(host.getState());
+      case 'state.update': {
+        const next = effect.fn(host.getState());
+        host.setState(next);
+        return next;
+      }
+      case 'state.wait':
+        return host.waitFor(effect.until, ctx?.signal);
+      case 'now':
+        return adapters.clock.now();
+      case 'id':
+        return effect.scope === 'mutation' ? adapters.ids.mutation() : adapters.ids.salt();
+      case 'hash':
+        return adapters.hash(effect.input);
+      case 'emit':
+        return host.emit(effect.event);
+      case 'dispatch':
+        return host.dispatch(effect.event);
+      case 'all': {
+        const settled = await Promise.allSettled(effect.effects.map((e) => interpret(e, ctx)));
+        return settled.map((r): Settled => (r.status === 'fulfilled' ? { ok: true, value: r.value } : { ok: false, error: r.reason }));
+      }
+      case 'service': {
+        const fn = adapters.services[effect.name] as (...args: unknown[]) => unknown;
+        return fn(...effect.args);
+      }
+    }
+  };
+  return interpret;
+}