@spooky-sync/core 0.0.1-canary.240 → 0.0.1-canary.241

package/src/sync/poll.saga.test.ts

@@ -0,0 +1,51 @@
+import { describe, expect, it } from 'vitest';
+import { RecordId } from 'surrealdb';
+import { runPure } from '../testing/run-pure';
+import { buildEntry, buildOutboxItem, buildState } from '../testing/build';
+import * as R from '../state/reducers';
+import { defaultEnv } from '../query/env';
+import { pollTick } from './poll.saga';
+
+const env = defaultEnv({ tables: [] } as any);
+const ok = (result: unknown) => ({ status: 'OK', result });
+
+describe('pollTick', () => {
+  it('with no queries: probes connectivity, backs off while idle', async () => {
+    const out = await runPure(pollTick(env), { state: R.patchSync({ pollIdleStreak: 2 })(buildState()), handlers: { 'remote.query': () => [ok(true)] } });
+    expect(out.dispatched).toEqual([{ type: 'SyncOutcome', ok: true }]);
+    expect(out.state.sync.pollIdleStreak).toBe(3);
+    expect(out.timers.get('poll')).toEqual({ ms: 4000, event: { type: 'PollTick' } });
+    const failed = await runPure(pollTick(env), {
+      state: buildState(),
+      handlers: {
+        'remote.query': () => {
+          throw new Error('offline');
+        },
+      },
+    });
+    expect(failed.dispatched).toEqual([{ type: 'SyncOutcome', ok: false, error: new Error('offline') }]);
+  });
+  it('with queries: reads membership; a change or an acked write resets the streak', async () => {
+    const entry = buildEntry({ def: { hash: 'a', id: new RecordId('_00_query', 'a') }, lifecycle: { phase: 'live' }, serverState: 'ready' });
+    const changed = await runPure(pollTick(env), {
+      state: R.patchSync({ pollIdleStreak: 5 })(buildState([entry])),
+      handlers: {
+        'remote.query': () => [ok([{ out: new RecordId('thing', '1'), version: 1 }]), ok({ rowCount: 1, state: 'ready' }), ok([])],
+        'local.upsert': () => undefined,
+      },
+    });
+    expect(changed.state.sync.pollIdleStreak).toBe(0);
+    expect(changed.timers.get('poll')!.ms).toBe(500);
+    const quiet = await runPure(pollTick(env), {
+      state: R.patchSync({ pollIdleStreak: 1 })(buildState([entry])),
+      handlers: { 'remote.query': () => [ok([]), ok({ rowCount: 0, state: 'ready' }), ok([])], 'local.upsert': () => undefined },
+    });
+    expect(quiet.state.sync.pollIdleStreak).toBe(2);
+    expect(quiet.timers.get('poll')!.ms).toBe(2000);
+    const acked = await runPure(pollTick(env), {
+      state: buildState([entry], R.patchSync({ pollIdleStreak: 4 }), R.outboxReplace([buildOutboxItem({ status: 'acked', ackedAt: 1 })])),
+      handlers: { 'remote.query': () => [ok([]), ok({ rowCount: 0, state: 'ready' }), ok([])], 'local.upsert': () => undefined },
+    });
+    expect(acked.state.sync.pollIdleStreak).toBe(0);
+  });
+});

package/src/sync/poll.saga.ts

@@ -0,0 +1,36 @@
+import type { Saga } from '../kernel/saga';
+import { fx } from '../kernel/effects';
+import * as R from '../state/reducers';
+import { activeHashes, hasAckedWrites } from '../state/selectors';
+import type { SagaEnv } from '../query/env';
+import { readMembership } from '../query/membership.saga';
+import { listRefPollDelayMs } from './policy';
+
+/**
+ * The `_00_list_ref` poll: the safety net under LIVE. Reads every active
+ * query's membership on a backoff that snaps to the base cadence whenever
+ * something changed (or an acked write still waits for membership) and
+ * coasts up to the cap while quiet. With no queries it probes connectivity.
+ */
+export function* pollTick(env: SagaEnv): Saga<void> {
+  const [hashes, streak, acked] = (yield fx.state.read((s) => [activeHashes(s), s.sync.pollIdleStreak, hasAckedWrites(s)])) as [
+    string[],
+    number,
+    boolean,
+  ];
+  let changed = false;
+  if (hashes.length === 0) {
+    try {
+      yield fx.remote.query('RETURN true', undefined, env.remoteTimeoutMs);
+      yield fx.dispatch({ type: 'SyncOutcome', ok: true });
+    } catch (error) {
+      yield fx.dispatch({ type: 'SyncOutcome', ok: false, error });
+    }
+  } else {
+    const result = yield* readMembership(env, hashes);
+    changed = result.changed;
+  }
+  const idleStreak = changed || acked ? 0 : streak + 1;
+  yield fx.state.update(R.patchSync({ pollIdleStreak: idleStreak }));
+  yield fx.timer.set('poll', listRefPollDelayMs({ idleStreak, baseIntervalMs: env.pollBaseMs }), { type: 'PollTick' });
+}

package/src/sync/tabs.saga.test.ts

@@ -0,0 +1,74 @@
+import { describe, expect, it } from 'vitest';
+import { runPure } from '../testing/run-pure';
+import { buildEntry, buildOutboxItem, buildState } from '../testing/build';
+import * as R from '../state/reducers';
+import { defaultEnv } from '../query/env';
+import { setRole, tabMessage } from './tabs.saga';
+
+const env = defaultEnv({ tables: [] } as any);
+
+describe('setRole', () => {
+  it('leader: loads the outbox and starts live/poll/registrations; follower: stops its timers; same role is a no-op', async () => {
+    const leader = await runPure(setRole(env, 'leader'), { state: buildState(), handlers: { 'local.query': () => [] } });
+    expect(leader.state.tabRole).toBe('leader');
+    expect(leader.dispatched).toEqual([{ type: 'LiveStart' }, { type: 'PollTick' }, { type: 'EnsureRegistered' }]);
+    const follower = await runPure(setRole(env, 'follower'), { state: R.patchSync({ liveUuid: 'u' })(buildState()) });
+    expect(follower.state.tabRole).toBe('follower');
+    expect(follower.state.sync.liveUuid).toBeNull();
+    expect(follower.log.filter((e) => e.kind === 'timer.clear').map((e) => (e as any).key)).toEqual(['poll', 'outbox']);
+    const same = await runPure(setRole(env, 'solo'), { state: buildState() });
+    expect(same.log).toHaveLength(1);
+  });
+});
+
+describe('tabMessage', () => {
+  const s = () => buildState([buildEntry({ def: { hash: 'a', tableName: 'thing' } })], R.outboxReplace([buildOutboxItem({ id: 'm1', recordId: 'thing:1' })]));
+  it('ignores junk', async () => {
+    for (const junk of [null, 'x', {}, { type: 'weird' }, { type: 'ingest', records: [] }, { type: 'membership-dirty' }, { type: 'failed-mutations-changed' }]) {
+      const out = await runPure(tabMessage(env, junk), { state: s() });
+      expect(out.emitted).toEqual([]);
+    }
+  });
+  it('ingest: feeds the circuit, tracks versions, dirties tables; a failing ingest is logged', async () => {
+    const msg = {
+      type: 'ingest',
+      records: [
+        { table: 'thing', op: 'CREATE', id: 'thing:2', record: { _00_rv: 3 } },
+        { table: 'thing', op: 'DELETE', id: 'thing:1', record: {} },
+        { table: 'other', op: 'UPDATE', id: 'other:1', record: {} },
+      ],
+    };
+    const out = await runPure(tabMessage(env, msg), { state: R.setVersions([['thing:1', 1]])(s()), handlers: { 'ssp.ingest': () => undefined } });
+    expect(out.state.versions.get('thing:2')).toBe(3);
+    expect(out.state.versions.get('other:1')).toBe(0);
+    expect(out.state.versions.has('thing:1')).toBe(false);
+    expect(out.state.dirty.has('a')).toBe(true);
+    const failing = await runPure(tabMessage(env, msg), {
+      state: s(),
+      handlers: {
+        'ssp.ingest': () => {
+          throw new Error('wasm');
+        },
+      },
+    });
+    expect(failing.emitted).toEqual([expect.objectContaining({ level: 'warn' })]);
+  });
+  it('membership-dirty, outbox-changed (leader only), settled, rolled-back, tray count', async () => {
+    const dirty = await runPure(tabMessage(env, { type: 'membership-dirty', hashes: ['a'] }), { state: { ...s(), tabRole: 'follower' } });
+    expect(dirty.state.membershipDirty.has('a')).toBe(true);
+    const ob = await runPure(tabMessage(env, { type: 'outbox-changed', mutationId: 'm' }), { state: { ...s(), tabRole: 'leader' }, handlers: { 'local.query': () => [] } });
+    expect(ob.log.some((e) => e.kind === 'local.query')).toBe(true);
+    const obFollower = await runPure(tabMessage(env, { type: 'outbox-changed', mutationId: 'm' }), { state: { ...s(), tabRole: 'follower' } });
+    expect(obFollower.log.some((e) => e.kind === 'local.query')).toBe(false);
+    const settled = await runPure(tabMessage(env, { type: 'mutation-settled', mutationId: 'm1', recordId: 'thing:1', eventType: 'create' }), { state: s(), now: 9 });
+    expect(settled.state.outbox[0]).toMatchObject({ status: 'acked', ackedAt: 9 });
+    expect(settled.emitted).toEqual([{ type: 'mutation:settled', mutationId: 'm1', recordId: 'thing:1', eventType: 'create' }]);
+    const rolled = await runPure(tabMessage(env, { type: 'mutation-rolled-back', mutationId: 'm1', recordId: 'thing:1', eventType: 'create', error: 'denied' }), { state: s() });
+    expect(rolled.state.outbox).toEqual([]);
+    expect(rolled.state.dirty.has('a')).toBe(true);
+    expect(rolled.emitted[0]).toMatchObject({ type: 'mutation:rolled-back', error: 'denied' });
+    const tray = await runPure(tabMessage(env, { type: 'failed-mutations-changed', count: 4 }), { state: s() });
+    expect(tray.state.failedCount).toBe(4);
+    expect(tray.emitted).toEqual([{ type: 'tray:changed', count: 4 }]);
+  });
+});

package/src/sync/tabs.saga.ts

@@ -0,0 +1,92 @@
+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))
+        )
+      );
+      return;
+    }
+    case 'membership-dirty':
+      if (Array.isArray(msg.hashes)) yield* liveChange(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,61 @@
+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,
+    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,34 @@
+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[] } {
+  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 events = { subscribe: noop };
+  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), currentUser: null, isAuthenticated: false, eventSystem: { subscribe: noop } } as any,
+    tabs: null,
+    tabsUnsupportedReason: 'test',
+    tabId: 'tab-test',
+    ...over,
+  } as Services<S>;
+  return Object.assign(bundle, { authListeners, connectionListeners, receivers });
+}

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