@spooky-sync/core 0.0.1-canary.33 → 0.0.1-canary.331

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, IdScope, 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: Record<IdScope, () => 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 adapters.ids[effect.scope]();
+      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 } };
+}