@spooky-sync/core 0.0.1-canary.25 → 0.0.1-canary.255

package/src/kernel/effects.ts

@@ -0,0 +1,159 @@
+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;
+  'local.connect': (bucketId: string) => Promise<void>;
+  'local.switchStore': (bucketId: string) => Promise<void>;
+  'local.beginSwitch': () => () => void;
+  'local.currentBucketId': () => string;
+  'local.usesSurqlSchema': () => boolean;
+  '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;
+  '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,55 @@
+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: 'ReadMembership'; hashes: QueryHash[] }
+  | { type: 'FetchRows' }
+  | { type: 'Materialize'; hash: QueryHash }
+  | { type: 'MaterializeDirty' }
+  | { type: 'LifecycleTick' }
+  | { type: 'GcTick' }
+  | { type: 'Drain' }
+  | { type: 'FlushWrite'; key: string }
+  | { 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: 'devtools'; name: string; data?: 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;
+}

package/src/kernel/saga.test.ts

@@ -0,0 +1,89 @@
+import { describe, expect, it } from 'vitest';
+import type { Effect } from './effects';
+import { fx } from './effects';
+import { acquire, emptyLanes, release, runSaga } from './saga';
+import type { Saga } from './saga';
+
+describe('runSaga', () => {
+  it('threads effect results back into the generator in order', async () => {
+    const seen: Effect[] = [];
+    function* saga(): Saga<number> {
+      const a = (yield fx.now()) as number;
+      const b = (yield fx.hash('x')) as number;
+      return a + b;
+    }
+    const result = await runSaga(saga(), async (e) => {
+      seen.push(e);
+      return e.kind === 'now' ? 1 : 2;
+    });
+    expect(result).toBe(3);
+    expect(seen.map((e) => e.kind)).toEqual(['now', 'hash']);
+  });
+
+  it('throws a rejected effect into the saga so it can catch it', async () => {
+    function* saga(): Saga<string> {
+      try {
+        yield fx.now();
+        return 'unreachable';
+      } catch (err) {
+        return `caught:${(err as Error).message}`;
+      }
+    }
+    await expect(runSaga(saga(), async () => Promise.reject(new Error('boom')))).resolves.toBe('caught:boom');
+  });
+
+  it('propagates an error the saga does not catch', async () => {
+    function* saga(): Saga<void> {
+      yield fx.now();
+    }
+    await expect(runSaga(saga(), async () => Promise.reject(new Error('boom')))).rejects.toThrow('boom');
+  });
+
+  it('returns immediately for a saga that yields nothing', async () => {
+    // oxlint-disable-next-line require-yield
+    function* saga(): Saga<number> {
+      return 7;
+    }
+    await expect(runSaga(saga(), async () => undefined)).resolves.toBe(7);
+  });
+});
+
+describe('lanes', () => {
+  it('serial: first acquires, second waits, release hands over, final release frees', () => {
+    const lane = { kind: 'serial', key: 'outbox' } as const;
+    const a = acquire(emptyLanes(), lane);
+    expect(a.decision).toBe('start');
+    const b = acquire(a.state, lane);
+    expect(b.decision).toBe('wait');
+    const c = acquire(b.state, lane);
+    expect(c.decision).toBe('wait');
+    expect(c.state.waiting.get('outbox')).toBe(2);
+    const r1 = release(c.state, 'outbox');
+    expect(r1.startNext).toBe(true);
+    expect(r1.state.waiting.get('outbox')).toBe(1);
+    expect(r1.state.running.has('outbox')).toBe(true);
+    const r2 = release(r1.state, 'outbox');
+    expect(r2.startNext).toBe(true);
+    expect(r2.state.waiting.has('outbox')).toBe(false);
+    const r3 = release(r2.state, 'outbox');
+    expect(r3.startNext).toBe(false);
+    expect(r3.state.running.has('outbox')).toBe(false);
+  });
+
+  it('dedupe: a request during a run joins it and does not queue', () => {
+    const lane = { kind: 'dedupe', key: 'mat:h' } as const;
+    const a = acquire(emptyLanes(), lane);
+    const b = acquire(a.state, lane);
+    expect(b.decision).toBe('join');
+    expect(b.state).toBe(a.state);
+    const r = release(b.state, 'mat:h');
+    expect(r.startNext).toBe(false);
+    expect(r.state.running.size).toBe(0);
+  });
+
+  it('keys are independent', () => {
+    const a = acquire(emptyLanes(), { kind: 'serial', key: 'x' });
+    const b = acquire(a.state, { kind: 'serial', key: 'y' });
+    expect(b.decision).toBe('start');
+  });
+});

package/src/kernel/saga.ts

@@ -0,0 +1,73 @@
+import type { Effect } from './effects';
+
+/**
+ * A saga is a generator that yields effects and receives their results. It
+ * holds no references to adapters or state, so it can be driven by the real
+ * interpreter or by `testing/run-pure` with canned results.
+ */
+export type Saga<R> = Generator<Effect, R, any>;
+export type Interpret = (effect: Effect) => Promise<unknown>;
+
+/**
+ * Drive a saga to completion. A rejected effect is thrown back into the saga
+ * at the `yield`, so sagas use ordinary `try/catch`; an error the saga does
+ * not catch propagates to the caller.
+ */
+export async function runSaga<R>(saga: Saga<R>, interpret: Interpret): Promise<R> {
+  let step = saga.next();
+  while (!step.done) {
+    let result: unknown;
+    try {
+      result = await interpret(step.value);
+    } catch (error) {
+      step = saga.throw(error);
+      continue;
+    }
+    step = saga.next(result);
+  }
+  return step.value;
+}
+
+/**
+ * Lanes bound concurrency without a queue object per lane:
+ * - `serial`: runs strictly one at a time per key, in arrival order.
+ * - `dedupe`: a request while one run is active joins that run instead of
+ *   starting another.
+ * The bookkeeping is a pure value so the policy is unit-testable; the runtime
+ * owns the promises.
+ */
+export type Lane = { kind: 'serial'; key: string } | { kind: 'dedupe'; key: string };
+
+export interface LaneState {
+  readonly running: ReadonlySet<string>;
+  readonly waiting: ReadonlyMap<string, number>;
+}
+
+export const emptyLanes = (): LaneState => ({ running: new Set(), waiting: new Map() });
+
+export type LaneDecision = 'start' | 'wait' | 'join';
+
+export function acquire(state: LaneState, lane: Lane): { decision: LaneDecision; state: LaneState } {
+  if (!state.running.has(lane.key)) {
+    const running = new Set(state.running);
+    running.add(lane.key);
+    return { decision: 'start', state: { running, waiting: state.waiting } };
+  }
+  if (lane.kind === 'dedupe') return { decision: 'join', state };
+  const waiting = new Map(state.waiting);
+  waiting.set(lane.key, (waiting.get(lane.key) ?? 0) + 1);
+  return { decision: 'wait', state: { running: state.running, waiting } };
+}
+
+export function release(state: LaneState, key: string): { startNext: boolean; state: LaneState } {
+  const pending = state.waiting.get(key) ?? 0;
+  if (pending > 0) {
+    const waiting = new Map(state.waiting);
+    if (pending === 1) waiting.delete(key);
+    else waiting.set(key, pending - 1);
+    return { startNext: true, state: { running: state.running, waiting } };
+  }
+  const running = new Set(state.running);
+  running.delete(key);
+  return { startNext: false, state: { running, waiting: state.waiting } };
+}