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

package/src/sync/tabs.saga.ts

@@ -0,0 +1,96 @@
+import type { Saga } from '../kernel/saga';
+import { fx } from '../kernel/effects';
+import type { IngestRecord } from '../services/stream-processor/index';
+import type { ClientState, TabRole } from '../state/client-state';
+import * as R from '../state/reducers';
+import type { SagaEnv } from '../query/env';
+import { loadOutbox } from '../mutation/push.saga';
+import { liveChange } from './live.saga';
+
+/**
+ * Shared-tabs role changes. The leader owns the outbox drain, the poll and
+ * LIVE; a follower keeps its own circuit and materialization but gets
+ * membership dirt, acks and rollbacks relayed.
+ */
+export function* setRole(env: SagaEnv, role: TabRole): Saga<void> {
+  const prev = (yield fx.state.read((s) => s.tabRole)) as TabRole;
+  if (prev === role) return;
+  yield fx.state.update(R.setTabRole(role));
+  if (role === 'follower') {
+    yield fx.timer.clear('poll');
+    yield fx.timer.clear('outbox');
+    yield fx.state.update(R.patchSync({ liveUuid: null, liveTable: null }));
+    return;
+  }
+  yield* loadOutbox(env);
+  yield fx.dispatch({ type: 'LiveStart' });
+  yield fx.dispatch({ type: 'PollTick' });
+  yield fx.dispatch({ type: 'EnsureRegistered' });
+}
+
+type TabMessage =
+  | { type: 'ingest'; records: IngestRecord[] }
+  | { type: 'membership-dirty'; hashes: string[] }
+  | { type: 'outbox-changed'; mutationId: string }
+  | { type: 'mutation-settled'; mutationId: string; recordId: string; eventType: string }
+  | { type: 'mutation-rolled-back'; mutationId: string; recordId: string; eventType: string; error: string }
+  | { type: 'failed-mutations-changed'; count: number };
+
+/** A message from another tab of the same origin. */
+export function* tabMessage(env: SagaEnv, raw: unknown): Saga<void> {
+  const msg = raw as TabMessage | null;
+  if (!msg || typeof msg !== 'object' || typeof msg.type !== 'string') return;
+  const role = (yield fx.state.read((s) => s.tabRole)) as ClientState['tabRole'];
+  switch (msg.type) {
+    case 'ingest': {
+      if (!Array.isArray(msg.records) || msg.records.length === 0) return;
+      try {
+        yield fx.ssp.ingest(msg.records);
+      } catch (error) {
+        yield fx.emit({ type: 'log', level: 'warn', message: 'relayed ingest failed', data: { error } });
+      }
+      yield fx.state.update(
+        R.compose(
+          R.setVersions(
+            msg.records
+              .filter((r) => r.op !== 'DELETE')
+              .map((r) => [r.id, typeof r.record?._00_rv === 'number' ? (r.record._00_rv as number) : 0] as const)
+          ),
+          R.deleteVersions(msg.records.filter((r) => r.op === 'DELETE').map((r) => r.id)),
+          ...[...new Set(msg.records.map((r) => r.table))].map((t) => R.markTableDirty(t))
+        )
+      );
+      // A body another tab deleted (its orphan GC) may still be one this tab
+      // names: with the version gone, the fetch plan pulls it back.
+      if (msg.records.some((r) => r.op === 'DELETE')) yield fx.dispatch({ type: 'FetchRows' });
+      return;
+    }
+    case 'membership-dirty':
+      // No inline rows here: the leader relays its own bodies as an `ingest`.
+      if (Array.isArray(msg.hashes)) yield* liveChange(env, msg.hashes);
+      return;
+    case 'outbox-changed':
+      if (role !== 'leader') return;
+      yield* loadOutbox(env);
+      return;
+    case 'mutation-settled': {
+      const now = (yield fx.now()) as number;
+      yield fx.state.update(R.outboxAck(msg.mutationId, now));
+      yield fx.emit({ type: 'mutation:settled', mutationId: msg.mutationId, recordId: msg.recordId, eventType: msg.eventType });
+      return;
+    }
+    case 'mutation-rolled-back': {
+      const table = msg.recordId.slice(0, msg.recordId.indexOf(':'));
+      yield fx.state.update(R.compose(R.outboxRemove(msg.mutationId), R.markTableDirty(table)));
+      yield fx.emit({ type: 'mutation:rolled-back', mutationId: msg.mutationId, recordId: msg.recordId, eventType: msg.eventType, error: msg.error });
+      return;
+    }
+    case 'failed-mutations-changed':
+      if (typeof msg.count !== 'number') return;
+      yield fx.state.update(R.setFailedCount(msg.count));
+      yield fx.emit({ type: 'tray:changed', count: msg.count });
+      return;
+    default:
+      return;
+  }
+}

package/src/testing/adapters.ts

@@ -0,0 +1,133 @@
+import type { Adapters, InterpreterHost } from '../kernel/interpreter';
+import type { ServiceCalls } from '../kernel/effects';
+import type { OutEvent, RuntimeEvent } from '../kernel/events';
+import type { ClientState } from '../state/client-state';
+import { emptyState } from '../state/client-state';
+import { sha256Hex } from './run-pure';
+
+export interface FakeTimers {
+  pending: Map<string, { ms: number; fire: () => void }>;
+  fire(key: string): void;
+  fireAll(): void;
+}
+
+/**
+ * Recording adapters for interpreter / runtime / facade tests. Every call is
+ * logged; behaviour is scripted by overriding the methods you care about.
+ */
+export function fakeAdapters(over: {
+  local?: Partial<Adapters['local']>;
+  remote?: Partial<Adapters['remote']>;
+  ssp?: Partial<Adapters['ssp']>;
+  services?: Partial<ServiceCalls>;
+  now?: number;
+} = {}) {
+  const calls: Array<[string, unknown[]]> = [];
+  const log = (name: string, ...args: unknown[]) => calls.push([name, args]);
+  let now = over.now ?? 1_700_000_000_000;
+  let epoch = 0;
+  const timers: FakeTimers = {
+    pending: new Map(),
+    fire(key) {
+      const t = timers.pending.get(key);
+      if (!t) return;
+      timers.pending.delete(key);
+      t.fire();
+    },
+    fireAll() {
+      for (const key of [...timers.pending.keys()]) timers.fire(key);
+    },
+  };
+  const services = new Proxy({} as ServiceCalls, {
+    get(_t, name: string) {
+      return (...args: unknown[]) => {
+        log(`service.${name}`, ...args);
+        const fn = (over.services as Record<string, (...a: unknown[]) => unknown> | undefined)?.[name];
+        return fn ? fn(...args) : undefined;
+      };
+    },
+  });
+  let ids = 0;
+  const adapters: Adapters = {
+    local: {
+      get epoch() {
+        return epoch;
+      },
+      query: (async (sql: string, vars?: Record<string, unknown>) => (log('local.query', sql, vars), [])) as Adapters['local']['query'],
+      execute: (async (q: { sql: string }, vars?: Record<string, unknown>) => (log('local.execute', q.sql, vars), undefined)) as Adapters['local']['execute'],
+      select: async (plan, params) => (log('local.select', plan, params), []),
+      getById: async (table, id) => (log('local.getById', table, id), null),
+      upsert: async (table, id, data, mode) => void log('local.upsert', table, id, data, mode),
+      delete: async (table, id) => void log('local.delete', table, id),
+      ...over.local,
+    },
+    remote: {
+      queryResponses: async (sql, vars) => (log('remote.query', sql, vars), []),
+      live: async (table) => (log('remote.live', table), 'live-uuid'),
+      kill: async (uuid) => void log('remote.kill', uuid),
+      ...over.remote,
+    },
+    ssp: {
+      registerQueryPlan: (plan) => (log('ssp.register', plan.queryHash), { queryHash: plan.queryHash, localArray: [] }),
+      unregisterQueryPlan: (hash) => void log('ssp.unregister', hash),
+      ingestMany: (records) => (log('ssp.ingest', records), records),
+      ...over.ssp,
+    },
+    timers: {
+      set: (key, ms, fire) => void timers.pending.set(key, { ms, fire }),
+      clear: (key) => void timers.pending.delete(key),
+    },
+    clock: { now: () => now },
+    ids: { mutation: () => `_00_pending_mutations:${String(++ids).padStart(13, '0')}_0001_tab`, salt: () => `salt-${++ids}` },
+    hash: sha256Hex,
+    services,
+  };
+  return {
+    adapters,
+    calls,
+    timers,
+    names: () => calls.map(([n]) => n),
+    advance(ms: number) {
+      now += ms;
+    },
+    bumpEpoch() {
+      epoch += 1;
+    },
+  };
+}
+
+/** A minimal host: holds state, resolves waits when the predicate holds after an update. */
+export function fakeHost(initial: ClientState = emptyState({ tabId: 'tab-a' })) {
+  let state = initial;
+  const emitted: OutEvent[] = [];
+  const dispatched: RuntimeEvent[] = [];
+  const waiters = new Set<{ until: (s: ClientState) => boolean; resolve: () => void; reject: (e: unknown) => void }>();
+  const check = () => {
+    for (const w of [...waiters]) {
+      if (w.until(state)) {
+        waiters.delete(w);
+        w.resolve();
+      }
+    }
+  };
+  const host: InterpreterHost = {
+    getState: () => state,
+    setState: (next) => {
+      state = next;
+      check();
+    },
+    waitFor: (until, signal) =>
+      new Promise<void>((resolve, reject) => {
+        if (until(state)) return resolve();
+        const w = { until, resolve, reject };
+        waiters.add(w);
+        signal?.addEventListener('abort', () => {
+          waiters.delete(w);
+          reject(new Error('aborted'));
+        });
+      }),
+    emit: (e) => void emitted.push(e),
+    dispatch: (e) => void dispatched.push(e),
+  };
+  return { host, emitted, dispatched, get state() { return state; }, waiters };
+}

package/src/testing/build.ts

@@ -0,0 +1,63 @@
+import { RecordId } from 'surrealdb';
+import type { ClientState, OutboxItem, QueryDefinition, QueryEntry } from '../state/client-state';
+import { emptyState, emptyTelemetry } from '../state/client-state';
+import { seedLifecycle } from '../state/lifecycle';
+import { compose, putQuery } from '../state/reducers';
+import type { Reducer } from '../state/reducers';
+
+type DeepPartial<T> = { [K in keyof T]?: T[K] extends object ? DeepPartial<T[K]> | T[K] : T[K] };
+
+export function buildDefinition(over: Partial<QueryDefinition> = {}): QueryDefinition {
+  const hash = over.hash ?? 'h1';
+  return {
+    id: over.id ?? (new RecordId('_00_query', hash) as any),
+    hash,
+    viewKey: over.viewKey ?? `view-${hash}`,
+    surql: over.surql ?? 'SELECT * FROM thing',
+    params: over.params ?? {},
+    plan: over.plan,
+    ttl: over.ttl ?? '10m',
+    ttlMs: over.ttlMs ?? 600_000,
+    tableName: over.tableName ?? 'thing',
+    createdAt: over.createdAt ?? 1_700_000_000_000,
+  };
+}
+
+export function buildEntry(over: DeepPartial<QueryEntry> & { def?: Partial<QueryDefinition> } = {}): QueryEntry {
+  const def = buildDefinition(over.def ?? {});
+  return {
+    def,
+    lifecycle: { ...seedLifecycle(false), ...(over.lifecycle as object) },
+    remoteArray: (over.remoteArray as QueryEntry['remoteArray']) ?? [],
+    localArray: (over.localArray as QueryEntry['localArray']) ?? [],
+    subqueryRemoteArray: (over.subqueryRemoteArray as QueryEntry['subqueryRemoteArray']) ?? [],
+    records: (over.records as QueryEntry['records']) ?? [],
+    serverState: over.serverState ?? null,
+    subscribers: over.subscribers ?? 0,
+    lastSubscriberLeftAt: over.lastSubscriberLeftAt ?? null,
+    lastHeartbeatAt: over.lastHeartbeatAt ?? null,
+    lastPolledAt: over.lastPolledAt ?? null,
+    registerAttempts: over.registerAttempts ?? 0,
+    viewLostCount: over.viewLostCount ?? 0,
+    viewLostRetryAt: over.viewLostRetryAt ?? null,
+    telemetry: { ...emptyTelemetry(), ...(over.telemetry as object) },
+  };
+}
+
+export function buildOutboxItem(over: Partial<OutboxItem> = {}): OutboxItem {
+  return {
+    id: over.id ?? 'm1',
+    type: over.type ?? 'create',
+    recordId: over.recordId ?? 'thing:1',
+    table: over.table ?? 'thing',
+    status: over.status ?? 'pending',
+    ackedAt: over.ackedAt ?? null,
+    attempts: over.attempts ?? 0,
+  };
+}
+
+/** A state holding the given entries, with `dirty` cleared (as after materialization). */
+export function buildState(entries: QueryEntry[] = [], ...extra: Reducer[]): ClientState {
+  const base = compose(...entries.map(putQuery))(emptyState({ tabId: 'tab-a' }));
+  return compose(...extra)({ ...base, dirty: new Set() });
+}

package/src/testing/fake-services.ts

@@ -0,0 +1,48 @@
+import type { SchemaStructure } from '@spooky-sync/query-builder';
+import type { Services } from '../client/services';
+
+const noop = () => {};
+
+/**
+ * The legacy services the facade constructs around, as inert stubs. Only the
+ * members the facade touches at construction / close time exist; sagas never
+ * see these (they go through the adapters' `service` calls).
+ */
+export function fakeServiceBundle<S extends SchemaStructure>(over: Partial<Services<S>> = {}): Services<S> & {
+  authListeners: Array<(u: string | null) => void>;
+  connectionListeners: Array<(s: string) => void>;
+  receivers: unknown[];
+  /** Fire a store event (`DATABASE_LOCAL_QUERY`, ...) at whoever subscribed. */
+  emitStoreEvent: (type: string, payload: unknown) => void;
+} {
+  const logger: any = { debug: noop, info: noop, warn: noop, error: noop, trace: noop, child: () => logger };
+  const authListeners: Array<(u: string | null) => void> = [];
+  const connectionListeners: Array<(s: string) => void> = [];
+  const receivers: unknown[] = [];
+  const storeListeners = new Map<string, Array<(e: { payload: unknown }) => void>>();
+  const events = {
+    subscribe: (type: string, cb: (e: { payload: unknown }) => void) => {
+      storeListeners.set(type, [...(storeListeners.get(type) ?? []), cb]);
+    },
+  };
+  const emitStoreEvent = (type: string, payload: unknown) => {
+    for (const cb of storeListeners.get(type) ?? []) cb({ payload });
+  };
+  const bundle = {
+    logger,
+    local: { getEvents: () => events, getClient: () => 'local-client', storageHealth: undefined, subscribeToStorageHealth: undefined, close: async () => undefined } as any,
+    remote: { getEvents: () => events, getClient: () => ({ authenticate: async (t: string) => t, invalidate: async () => undefined }), setAuthToken: noop, query: async () => ['remote'], close: async () => undefined } as any,
+    connectionSupervisor: { subscribe: (cb: (s: string) => void) => (connectionListeners.push(cb), noop), dispose: noop } as any,
+    blobs: { stats: () => ({ entries: 0 }), close: async () => undefined } as any,
+    persistence: { set: async () => undefined, get: async () => null, remove: async () => undefined },
+    streamProcessor: { addReceiver: (r: unknown) => void receivers.push(r), checkpoint: async () => undefined, dispose: noop } as any,
+    migrator: {} as any,
+    crdt: { closeAll: noop, dispose: noop, open: async () => 'field', close: noop } as any,
+    auth: { subscribe: (cb: (u: string | null) => void) => (authListeners.push(cb), noop), subscribeImpersonation: () => noop, onBeforeSignOut: () => noop, currentUser: null, isAuthenticated: false, token: null, impersonation: null, eventSystem: { subscribe: noop } } as any,
+    tabs: null,
+    tabsUnsupportedReason: 'test',
+    tabId: 'tab-test',
+    ...over,
+  } as Services<S>;
+  return Object.assign(bundle, { authListeners, connectionListeners, receivers, emitStoreEvent });
+}

package/src/testing/run-pure.test.ts

@@ -0,0 +1,92 @@
+import { describe, expect, it } from 'vitest';
+import { fx } from '../kernel/effects';
+import type { Saga } from '../kernel/saga';
+import { bySqlPrefix, runPure, UnhandledEffectError } from './run-pure';
+import { setFailedCount } from '../state/reducers';
+
+describe('runPure', () => {
+  it('handles state, clock, ids, hash, timers, emit, dispatch', async () => {
+    function* saga(): Saga<Record<string, unknown>> {
+      const before = (yield fx.state.read((s) => s.failedCount)) as number;
+      yield fx.state.update(setFailedCount(3));
+      const after = (yield fx.state.read((s) => s.failedCount)) as number;
+      const now = (yield fx.now()) as number;
+      const id1 = (yield fx.id('mutation')) as string;
+      const id2 = (yield fx.id('salt')) as string;
+      const hash = (yield fx.hash('abc')) as string;
+      yield fx.timer.set('k', 10, { type: 'Drain' });
+      yield fx.timer.set('k', 20, { type: 'Drain' });
+      yield fx.timer.set('j', 5, { type: 'FetchRows' });
+      yield fx.timer.clear('j');
+      yield fx.emit({ type: 'tray:changed', count: 1 });
+      yield fx.dispatch({ type: 'FetchRows' });
+      return { before, after, now, id1, id2, hash };
+    }
+    const out = await runPure(saga(), { now: 5 });
+    expect(out.result).toEqual({
+      before: 0,
+      after: 3,
+      now: 5,
+      id1: 'mutation-1',
+      id2: 'salt-2',
+      hash: 'ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad',
+    });
+    expect(out.state.failedCount).toBe(3);
+    expect([...out.timers.entries()]).toEqual([['k', { ms: 20, event: { type: 'Drain' } }]]);
+    expect(out.emitted).toEqual([{ type: 'tray:changed', count: 1 }]);
+    expect(out.dispatched).toEqual([{ type: 'FetchRows' }]);
+    expect(out.log.map((e) => e.kind)[0]).toBe('state.read');
+  });
+
+  it('state.wait passes when the predicate holds and throws when it would block', async () => {
+    function* ok(): Saga<string> {
+      yield fx.state.wait((s) => s.failedCount === 0);
+      return 'passed';
+    }
+    await expect(runPure(ok())).resolves.toMatchObject({ result: 'passed' });
+    function* blocked(): Saga<void> {
+      yield fx.state.wait((s) => s.failedCount === 9);
+    }
+    await expect(runPure(blocked())).rejects.toThrow(/would block/);
+  });
+
+  it('routes adapter effects to handlers and throws on unhandled ones', async () => {
+    function* saga(): Saga<unknown> {
+      return yield fx.remote.query('RETURN true');
+    }
+    const out = await runPure(saga(), { handlers: { 'remote.query': () => [{ status: 'OK', result: true }] } });
+    expect(out.result).toEqual([{ status: 'OK', result: true }]);
+    await expect(runPure(saga())).rejects.toBeInstanceOf(UnhandledEffectError);
+  });
+
+  it('all returns settled results in order and keeps going after a failure', async () => {
+    function* saga(): Saga<unknown> {
+      return yield fx.all([fx.remote.query('A'), fx.remote.query('B'), fx.now()]);
+    }
+    const out = await runPure(saga(), {
+      now: 1,
+      handlers: {
+        'remote.query': (e) => {
+          if ((e as { sql: string }).sql === 'B') throw new Error('nope');
+          return 'a';
+        },
+      },
+    });
+    expect(out.result).toEqual([
+      { ok: true, value: 'a' },
+      { ok: false, error: new Error('nope') },
+      { ok: true, value: 1 },
+    ]);
+  });
+
+  it('bySqlPrefix answers by prefix and rejects unknown SQL', async () => {
+    const handler = bySqlPrefix([
+      ['SELECT', () => 'rows'],
+      ['DELETE', () => 'gone'],
+    ]);
+    expect(handler(fx.local.query('SELECT * FROM x'), {} as never)).toBe('rows');
+    expect(handler(fx.local.query('DELETE x'), {} as never)).toBe('gone');
+    expect(() => handler(fx.local.query('UPDATE x'), {} as never)).toThrow(/no scripted answer/);
+    expect(() => handler(fx.now(), {} as never)).toThrow(/no scripted answer/);
+  });
+});

package/src/testing/run-pure.ts

@@ -0,0 +1,128 @@
+import { webcrypto } from 'node:crypto';
+import type { Effect, EffectKind, Settled } from '../kernel/effects';
+import type { OutEvent, RuntimeEvent } from '../kernel/events';
+import type { Saga } from '../kernel/saga';
+import { runSaga } from '../kernel/saga';
+import type { ClientState } from '../state/client-state';
+import { emptyState } from '../state/client-state';
+
+export type EffectHandler = (effect: Effect, ctx: PureContext) => unknown | Promise<unknown>;
+
+export interface PureContext {
+  state: ClientState;
+  now: number;
+  log: Effect[];
+  timers: Map<string, { ms: number; event: RuntimeEvent }>;
+  emitted: OutEvent[];
+  dispatched: RuntimeEvent[];
+  ids: number;
+}
+
+export interface RunPureOptions {
+  state?: ClientState;
+  now?: number;
+  /** What `local.epoch` answers; a store-side counter, so it is scripted like `now`. */
+  epoch?: number;
+  handlers?: Partial<Record<EffectKind, EffectHandler>>;
+}
+
+export interface RunPureResult<R> extends PureContext {
+  result: R;
+}
+
+export class UnhandledEffectError extends Error {
+  constructor(public readonly effect: Effect) {
+    super(`runPure: no handler for effect '${effect.kind}'`);
+    this.name = 'UnhandledEffectError';
+  }
+}
+
+export async function sha256Hex(input: string): Promise<string> {
+  const bytes = new TextEncoder().encode(input);
+  const digest = await webcrypto.subtle.digest('SHA-256', bytes);
+  return [...new Uint8Array(digest)].map((b) => b.toString(16).padStart(2, '0')).join('');
+}
+
+/**
+ * Drive a saga with canned effect results. `state.*`, `now`, `id`, `hash`,
+ * `timer.*`, `emit`, `dispatch` and `local.epoch` are handled here; every other
+ * adapter effect (`local.*`, `remote.*`, `ssp.*`) must have a handler or the run throws, so
+ * a test can never pass by an effect silently returning `undefined`.
+ */
+export async function runPure<R>(saga: Saga<R>, opts: RunPureOptions = {}): Promise<RunPureResult<R>> {
+  const ctx: PureContext = {
+    state: opts.state ?? emptyState({ tabId: 'tab-test' }),
+    now: opts.now ?? 1_700_000_000_000,
+    log: [],
+    timers: new Map(),
+    emitted: [],
+    dispatched: [],
+    ids: 0,
+  };
+  const interpret = async (effect: Effect): Promise<unknown> => {
+    ctx.log.push(effect);
+    const custom = opts.handlers?.[effect.kind];
+    if (custom) return custom(effect, ctx);
+    switch (effect.kind) {
+      case 'state.read':
+        return effect.select(ctx.state);
+      case 'state.update':
+        ctx.state = effect.fn(ctx.state);
+        return ctx.state;
+      case 'state.wait':
+        if (effect.until(ctx.state)) return undefined;
+        throw new Error('runPure: state.wait would block; script a handler or prepare the state');
+      case 'now':
+        return ctx.now;
+      case 'local.epoch':
+        return opts.epoch ?? 0;
+      case 'id':
+        ctx.ids += 1;
+        return `${effect.scope}-${ctx.ids}`;
+      case 'hash':
+        return sha256Hex(effect.input);
+      case 'timer.set':
+        ctx.timers.set(effect.key, { ms: effect.ms, event: effect.event });
+        return undefined;
+      case 'timer.clear':
+        ctx.timers.delete(effect.key);
+        return undefined;
+      case 'emit':
+        ctx.emitted.push(effect.event);
+        return undefined;
+      case 'dispatch':
+        ctx.dispatched.push(effect.event);
+        return undefined;
+      case 'service':
+        throw new UnhandledEffectError(effect);
+      case 'all': {
+        const results: Settled[] = [];
+        for (const inner of effect.effects) {
+          try {
+            results.push({ ok: true, value: await interpret(inner) });
+          } catch (error) {
+            results.push({ ok: false, error });
+          }
+        }
+        return results;
+      }
+      default:
+        throw new UnhandledEffectError(effect);
+    }
+  };
+  const result = await runSaga(saga, interpret);
+  return { ...ctx, result };
+}
+
+/** Handler helper: answer effects by SQL prefix (first match wins). */
+export function bySqlPrefix(
+  table: Array<[prefix: string, answer: (effect: Effect & { sql: string }) => unknown]>
+): EffectHandler {
+  return (effect) => {
+    const sql = (effect as { sql?: string }).sql ?? '';
+    for (const [prefix, answer] of table) {
+      if (sql.startsWith(prefix)) return answer(effect as Effect & { sql: string });
+    }
+    throw new Error(`no scripted answer for SQL: ${sql.slice(0, 80)}`);
+  };
+}

package/src/testing/services.ts

@@ -0,0 +1,17 @@
+import type { Effect, ServiceCalls, ServiceName } from '../kernel/effects';
+import type { EffectHandler } from './run-pure';
+
+type Impl = { [N in ServiceName]?: (...args: Parameters<ServiceCalls[N]>) => unknown };
+
+/** Script the `service` effect by name and record every call. */
+export function fakeServices(impl: Impl = {}) {
+  const calls: Array<[ServiceName, unknown[]]> = [];
+  const handler: EffectHandler = (effect: Effect) => {
+    if (effect.kind !== 'service') throw new Error('not a service effect');
+    calls.push([effect.name, effect.args]);
+    const fn = impl[effect.name] as ((...a: unknown[]) => unknown) | undefined;
+    if (!fn) return undefined;
+    return fn(...effect.args);
+  };
+  return { handler, calls, names: () => calls.map(([n]) => n) };
+}