@swirls/looms 0.0.1

package/dist/runtime/runtime.d.ts

@@ -0,0 +1,91 @@
+import { Effect } from 'effect';
+import type { EventStoreError, EventStoreFencedError, EventStoreTruncationError } from '@swirls/looms/core';
+import { EventStoreTag, EventStoreTrimmedError, type AnyRuntimeModule, type ComposedRegistry, type EventEnvelope, type EventInput, type EventStore, type JsonValue, type ProjectionDefinition, type ReplayStep, type RunState, type SnapshotStore } from '@swirls/looms/core';
+import { type WakeScheduler } from './wake-scheduler';
+export type { RegisteredDefinition } from '@swirls/looms/core';
+export type { WakeScheduler } from './wake-scheduler';
+export { createTimeoutScheduler } from './wake-scheduler';
+declare const DuplicateEffectDispatchError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "DuplicateEffectDispatchError";
+} & Readonly<A>;
+export declare class DuplicateEffectDispatchError extends DuplicateEffectDispatchError_base<{
+    readonly runId: string;
+    readonly effectId: string;
+    readonly threadId: string;
+    readonly message: string;
+}> {
+    constructor(runId: string, effectId: string, threadId: string);
+}
+declare const MaxWakeIterationsError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "MaxWakeIterationsError";
+} & Readonly<A>;
+export declare class MaxWakeIterationsError extends MaxWakeIterationsError_base<{
+    readonly runId: string;
+    readonly maxIterations: number;
+    readonly message: string;
+}> {
+    constructor(runId: string, maxIterations: number);
+}
+export type WakeError = DuplicateEffectDispatchError | MaxWakeIterationsError | EventStoreTruncationError | EventStoreTrimmedError | EventStoreFencedError | EventStoreError | Error;
+export interface CreateRuntimeOptions<TModules extends readonly AnyRuntimeModule[] = readonly AnyRuntimeModule[]> {
+    readonly modules: TModules;
+    readonly store?: EventStore;
+    /**
+     * Durable events between mid-wake snapshots. Default 200; `0` disables.
+     * A snapshot is always taken when a wake parks, so this only bounds replay
+     * after a crash inside one long wake.
+     */
+    readonly snapshotEvery?: number;
+    readonly maxWakeIterations?: number;
+    /** Defaults to the EventStore's attached store or an in-memory SnapshotStore. */
+    readonly snapshotStore?: SnapshotStore;
+    /** Trim the event log behind the oldest kept snapshot. Also sets how many snapshots to keep. */
+    readonly trimAfterSnapshot?: {
+        keepSnapshots: number;
+    };
+    /**
+     * Cursors to keep in process between calls. Default `0`: every call starts
+     * from the store (snapshot + delta). A cached cursor is validated against
+     * `store.tail` before use.
+     */
+    readonly runCacheSize?: number;
+    /**
+     * Pluggable wake scheduler for timer waits.
+     * Defaults to an in-process setTimeout scheduler.
+     */
+    readonly scheduler?: WakeScheduler;
+}
+export interface StartRunArgs {
+    kind: string;
+    definitionName: string;
+    input?: JsonValue;
+    runId?: string;
+    threadId?: string;
+    idempotencyKey?: string;
+}
+export interface StartResult {
+    runId: string;
+    threadId: string;
+    state: RunState;
+}
+export interface LoomsRuntime<TModules extends readonly AnyRuntimeModule[] = readonly AnyRuntimeModule[]> {
+    readonly modules: TModules;
+    readonly registry: ComposedRegistry;
+    startRun(args: StartRunArgs): Effect.Effect<StartResult, Error | EventStoreError, EventStoreTag>;
+    signal(runId: string, events: ReadonlyArray<EventInput>, options?: {
+        idempotencyKey?: string;
+    }): Effect.Effect<RunState, Error | EventStoreError, EventStoreTag>;
+    wake(runId: string): Effect.Effect<RunState, WakeError, EventStoreTag>;
+    getRun(runId: string): Effect.Effect<RunState, EventStoreTruncationError | EventStoreTrimmedError | EventStoreError, EventStoreTag>;
+    getEvents(runId: string, options?: {
+        fromSeq?: number;
+        limit?: number;
+    }): Effect.Effect<EventEnvelope[], EventStoreError, EventStoreTag>;
+    project<S>(runId: string, definition: ProjectionDefinition<S>): Effect.Effect<S, EventStoreError, EventStoreTag>;
+    replayTo(runId: string, seq: number): Effect.Effect<ReplayStep | null, EventStoreError, EventStoreTag>;
+    cancel(runId: string, threadId?: string): Effect.Effect<RunState, Error | EventStoreError, EventStoreTag>;
+    listRuns(): Effect.Effect<string[], EventStoreError, EventStoreTag>;
+    rescanTimers(): Effect.Effect<number, EventStoreTruncationError | EventStoreTrimmedError | EventStoreError, EventStoreTag>;
+    dispose(): void;
+}
+export declare function createRuntime<const TModules extends readonly AnyRuntimeModule[]>(options: CreateRuntimeOptions<TModules>): LoomsRuntime<TModules>;

package/dist/runtime/runtime.js

@@ -0,0 +1,531 @@
+import { Data, Effect, Option, Predicate } from 'effect';
+import { advanceCursor, assignSequences, composeModules, createCoalescingAppender, createEvent, createThreadId, createRunId, DEFAULT_SNAPSHOT_EVERY, emptyCursor, EventStoreTag, EventStoreTrimmedError, foldRun, hashRunState, isRunTerminal, isWaitOnTimer, project, replayTo, validateEventInput, withdrawnError, } from '@swirls/looms/core';
+import { dispatchEffect } from './dispatch-effect.js';
+import { createEffectFailedEvent, createLiveEvent, groupOutstanding, materializeEffectOutcome, moduleServices, resolveSnapshotStore, RunCursorCache, stripSeq, synthesizedThreadFailed, threadStartedEvents, validateAndCreateEvents, waitSatisfiedEvents, } from './runtime-helpers.js';
+import { createTimeoutScheduler, toEffectVoid } from './wake-scheduler.js';
+export { createTimeoutScheduler } from './wake-scheduler.js';
+export class DuplicateEffectDispatchError extends Data.TaggedError('DuplicateEffectDispatchError') {
+    constructor(runId, effectId, threadId) {
+        super({
+            runId,
+            effectId,
+            threadId,
+            message: `Duplicate effect dispatch detected for effectId "${effectId}" on thread "${threadId}"; refusing to re-dispatch already executed effect`,
+        });
+        this.name = 'DuplicateEffectDispatchError';
+    }
+}
+export class MaxWakeIterationsError extends Data.TaggedError('MaxWakeIterationsError') {
+    constructor(runId, maxIterations) {
+        super({
+            runId,
+            maxIterations,
+            message: `Max wake iterations exceeded (${maxIterations}) for run "${runId}"; possible infinite loop`,
+        });
+        this.name = 'MaxWakeIterationsError';
+    }
+}
+const DEFAULT_RUN_CACHE_SIZE = 0;
+const DEFAULT_KEEP_SNAPSHOTS = 1;
+export function createRuntime(options) {
+    const registry = composeModules(options.modules);
+    const registeredDefinitions = registry.definitions;
+    const definitions = new Map(registeredDefinitions.map((def) => [`${def.kind}:${def.name}`, def]));
+    const services = moduleServices(options.modules);
+    const waking = new Set();
+    /** Coalesce wake requests that arrive while a wake is in flight for the same run. */
+    const wakeAgain = new Set();
+    const snapshotEvery = options.snapshotEvery ?? DEFAULT_SNAPSHOT_EVERY;
+    const maxWakeIterations = options.maxWakeIterations ?? 100;
+    const snapshotStore = resolveSnapshotStore(options.snapshotStore, options.store);
+    const trimAfterSnapshot = options.trimAfterSnapshot;
+    const keepSnapshots = trimAfterSnapshot?.keepSnapshots ?? DEFAULT_KEEP_SNAPSHOTS;
+    const runCache = new RunCursorCache(options.runCacheSize ?? DEFAULT_RUN_CACHE_SIZE);
+    let liveStore = options.store;
+    const liveCount = new Map();
+    const liveAppends = createCoalescingAppender((runId, batch) => {
+        const store = liveStore;
+        if (!store) {
+            return Effect.fail(new Error('Cannot append live events without a store'));
+        }
+        return store.append(runId, batch).pipe(Effect.tap((result) => Effect.sync(() => {
+            liveCount.set(runId, (liveCount.get(runId) ?? 0) + result.sequences.length);
+        })), Effect.asVoid);
+    });
+    const readRemaining = (store, runId, events, expectedTail) => Effect.gen(function* () {
+        let collected = events;
+        while (collected.length > 0) {
+            const lastSeq = collected[collected.length - 1].seq;
+            const target = expectedTail ?? (yield* store.tail(runId));
+            if (lastSeq >= target) {
+                break;
+            }
+            const more = yield* store.read(runId, {
+                fromSeq: lastSeq + 1,
+                limit: expectedTail !== undefined ? Math.max(0, target - lastSeq) : undefined,
+            });
+            if (more.length === 0 || more[0].seq <= lastSeq) {
+                break;
+            }
+            collected = [...collected, ...more];
+        }
+        return collected;
+    });
+    const catchUp = (store, runId, cursor, expectedTail) => Effect.gen(function* () {
+        if (expectedTail !== undefined && cursor.seq === expectedTail) {
+            return cursor;
+        }
+        const fromSeq = cursor.seq + 1;
+        const limit = expectedTail !== undefined ? Math.max(0, expectedTail - cursor.seq) : undefined;
+        let delta = yield* store.read(runId, { fromSeq, limit });
+        if (delta.length === 0) {
+            return cursor;
+        }
+        const firstSeq = delta[0].seq;
+        if (firstSeq > fromSeq) {
+            if (store.bounds) {
+                const bounds = yield* store.bounds(runId);
+                if (bounds.head > fromSeq) {
+                    return yield* Effect.fail(new EventStoreTrimmedError(runId, bounds.head, fromSeq));
+                }
+            }
+            else {
+                return yield* Effect.fail(new EventStoreTrimmedError(runId, firstSeq, fromSeq));
+            }
+        }
+        delta = yield* readRemaining(store, runId, delta, expectedTail);
+        return advanceCursor(cursor, delta, registry);
+    });
+    const loadCursorCold = (store, runId) => Effect.gen(function* () {
+        let cursor = emptyCursor(runId);
+        if (snapshotStore) {
+            const snap = yield* snapshotStore
+                .loadLatest(runId)
+                .pipe(Effect.catch(() => Effect.succeed(Option.none())));
+            if (Option.isSome(snap)) {
+                cursor = {
+                    state: snap.value.state,
+                    seq: snap.value.cursor,
+                    durableSinceSnapshot: 0,
+                };
+            }
+        }
+        const fromSeq = cursor.seq + 1;
+        let delta = yield* store.read(runId, { fromSeq });
+        if (cursor.seq === 0 && delta[0] && delta[0].seq > 1) {
+            if (store.bounds) {
+                const bounds = yield* store.bounds(runId);
+                if (bounds.head > 1) {
+                    return yield* Effect.fail(new EventStoreTrimmedError(runId, bounds.head, 1));
+                }
+            }
+            else {
+                return yield* Effect.fail(new EventStoreTrimmedError(runId, delta[0].seq, 1));
+            }
+        }
+        if (delta.length > 0) {
+            delta = yield* readRemaining(store, runId, delta);
+        }
+        return advanceCursor(cursor, delta, registry);
+    });
+    const loadCursor = (store, runId) => Effect.gen(function* () {
+        const cached = runCache.get(runId);
+        if (cached) {
+            const tail = yield* store.tail(runId);
+            // A tail behind the cursor means the stream was recreated; the cache is poison.
+            if (tail < cached.seq) {
+                runCache.delete(runId);
+                return yield* loadCursorCold(store, runId);
+            }
+            if (tail === cached.seq) {
+                return cached;
+            }
+            const next = yield* catchUp(store, runId, cached, tail).pipe(Effect.catchTag('EventStoreTrimmedError', () => {
+                runCache.delete(runId);
+                return loadCursorCold(store, runId);
+            }));
+            runCache.set(runId, next);
+            return next;
+        }
+        const next = yield* loadCursorCold(store, runId);
+        runCache.set(runId, next);
+        return next;
+    });
+    /**
+     * Save the current state externally, keep only `keepSnapshots`, and optionally
+     * trim the event log behind the oldest kept snapshot. Failures are swallowed:
+     * a snapshot is an optimization, the log stays authoritative.
+     */
+    const persistSnapshot = (store, runId, cursor) => Effect.gen(function* () {
+        if (cursor.durableSinceSnapshot === 0) {
+            return cursor;
+        }
+        yield* snapshotStore.save({
+            runId,
+            cursor: cursor.seq,
+            stateHash: hashRunState(cursor.state),
+            takenAt: Date.now(),
+            state: cursor.state,
+        });
+        if (snapshotStore.prune) {
+            yield* snapshotStore.prune(runId, keepSnapshots);
+        }
+        if (trimAfterSnapshot && store.trim && snapshotStore.listCursors) {
+            const cursors = yield* snapshotStore.listCursors(runId);
+            const oldestKept = cursors[Math.max(0, cursors.length - keepSnapshots)];
+            if (oldestKept !== undefined) {
+                yield* store.trim(runId, oldestKept + 1);
+            }
+        }
+        return { ...cursor, durableSinceSnapshot: 0 };
+    }).pipe(Effect.catch(() => Effect.succeed(cursor)));
+    const applyAppend = (store, runId, cursor, batch, appendResult, commandRecords = 0) => Effect.gen(function* () {
+        const echo = assignSequences(batch, appendResult);
+        const first = echo[0];
+        let next = cursor;
+        if (first && first.seq !== cursor.seq + 1 + commandRecords) {
+            const gap = first.seq - 1 - cursor.seq;
+            const live = liveCount.get(runId) ?? 0;
+            if (live === gap) {
+                next = { ...cursor, seq: first.seq - 1 };
+            }
+            else {
+                next = yield* catchUp(store, runId, cursor, first.seq - 1);
+            }
+        }
+        next = advanceCursor(next, echo, registry);
+        liveCount.set(runId, 0);
+        if (next.seq !== appendResult.tail) {
+            next = yield* catchUp(store, runId, next, appendResult.tail);
+        }
+        runCache.set(runId, next);
+        return next;
+    });
+    let scheduler;
+    const runtime = {
+        modules: options.modules,
+        registry,
+        listRuns: () => Effect.gen(function* () {
+            const store = yield* EventStoreTag;
+            return yield* store.listRuns();
+        }),
+        getEvents: (runId, readOptions) => Effect.gen(function* () {
+            const store = yield* EventStoreTag;
+            return yield* store.read(runId, readOptions);
+        }),
+        getRun: (runId) => Effect.gen(function* () {
+            const store = yield* EventStoreTag;
+            const cursor = yield* loadCursor(store, runId);
+            return cursor.state;
+        }),
+        project: (runId, definition) => Effect.gen(function* () {
+            const events = yield* runtime.getEvents(runId);
+            return project(definition, events);
+        }),
+        replayTo: (runId, seq) => Effect.gen(function* () {
+            const events = yield* runtime.getEvents(runId);
+            return replayTo(events, registry, seq);
+        }),
+        rescanTimers: () => Effect.gen(function* () {
+            const store = yield* EventStoreTag;
+            const runIds = yield* store.listRuns();
+            let count = 0;
+            for (const runId of runIds) {
+                const runState = yield* runtime.getRun(runId);
+                if (isRunTerminal(runState)) {
+                    continue;
+                }
+                let earliestTimerAt = null;
+                for (const waitRecord of Object.values(runState.waits)) {
+                    if (isWaitOnTimer(waitRecord.on)) {
+                        if (earliestTimerAt === null || waitRecord.on.timerAt < earliestTimerAt) {
+                            earliestTimerAt = waitRecord.on.timerAt;
+                        }
+                    }
+                }
+                if (earliestTimerAt !== null) {
+                    yield* toEffectVoid(scheduler.schedule(runId, earliestTimerAt));
+                    count += 1;
+                }
+            }
+            return count;
+        }),
+        startRun: (args) => Effect.gen(function* () {
+            if (!definitions.get(`${args.kind}:${args.definitionName}`)) {
+                return yield* Effect.fail(new Error(`Unknown definition ${args.kind}:${args.definitionName}`));
+            }
+            const store = yield* EventStoreTag;
+            const runId = args.runId ?? createRunId();
+            const existing = yield* loadCursor(store, runId);
+            if (existing.seq > 0) {
+                if ((args.idempotencyKey &&
+                    existing.state.processedIdempotencyKeys?.includes(args.idempotencyKey)) ||
+                    existing.state.rootThreadId) {
+                    return {
+                        runId,
+                        threadId: existing.state.rootThreadId ?? '',
+                        state: existing.state,
+                    };
+                }
+            }
+            const threadId = args.threadId ?? createThreadId();
+            const startedEvents = yield* threadStartedEvents(definitions, {
+                kind: args.kind,
+                definitionName: args.definitionName,
+                input: args.input ?? null,
+                threadId,
+                parentThreadId: null,
+            });
+            const started = startedEvents[0];
+            const startedInput = started && Predicate.isObject(started.payload)
+                ? (started.payload.input ?? null)
+                : (args.input ?? null);
+            const batch = yield* validateAndCreateEvents(registry.catalogs, runId, [
+                {
+                    type: 'runtime.run.started',
+                    payload: {
+                        rootThreadId: threadId,
+                        kind: args.kind,
+                        definitionName: args.definitionName,
+                        input: startedInput,
+                    },
+                    threadId: null,
+                    idempotencyKey: args.idempotencyKey,
+                },
+                ...startedEvents,
+            ], { origin: { type: 'system' } });
+            yield* store.append(runId, stripSeq(batch));
+            const state = yield* runtime.wake(runId);
+            return { runId, threadId, state };
+        }),
+        signal: (runId, events, signalOpts) => Effect.gen(function* () {
+            const store = yield* EventStoreTag;
+            const current = yield* loadCursor(store, runId);
+            const currentState = current.state;
+            if (signalOpts?.idempotencyKey &&
+                currentState.processedIdempotencyKeys?.includes(signalOpts.idempotencyKey)) {
+                return currentState;
+            }
+            const filteredEvents = events.filter((input) => {
+                const key = input.idempotencyKey ?? signalOpts?.idempotencyKey;
+                return !key || !currentState.processedIdempotencyKeys?.includes(key);
+            });
+            if (filteredEvents.length === 0) {
+                return currentState;
+            }
+            const batch = yield* validateAndCreateEvents(registry.catalogs, runId, filteredEvents.map((input) => ({
+                ...input,
+                idempotencyKey: input.idempotencyKey ?? signalOpts?.idempotencyKey,
+            })), { origin: { type: 'external' } });
+            const folded = foldRun(batch, registry, { runId, initial: currentState });
+            const satisfied = waitSatisfiedEvents(folded, batch);
+            const satisfiedEvents = satisfied.map((input) => createEvent(runId, input));
+            yield* store.append(runId, stripSeq([...batch, ...satisfiedEvents]));
+            return yield* runtime.wake(runId);
+        }),
+        cancel: (runId, threadId) => Effect.gen(function* () {
+            const store = yield* EventStoreTag;
+            const targetThreadId = threadId ?? (yield* loadCursor(store, runId)).state.rootThreadId ?? '';
+            return yield* runtime.signal(runId, [
+                {
+                    type: 'runtime.thread.cancelled',
+                    payload: { threadId: targetThreadId, reason: 'cancelled' },
+                    threadId: targetThreadId || null,
+                    origin: { type: 'external' },
+                },
+            ]);
+        }),
+        wake: (runId) => Effect.gen(function* () {
+            // Claim synchronously before any yield so concurrent fibers cannot both pass.
+            if (waking.has(runId)) {
+                wakeAgain.add(runId);
+                return yield* runtime.getRun(runId);
+            }
+            waking.add(runId);
+            const store = yield* EventStoreTag;
+            liveStore = store;
+            try {
+                let finalState;
+                do {
+                    let cursor = yield* loadCursor(store, runId);
+                    if (isRunTerminal(cursor.state)) {
+                        finalState = cursor.state;
+                        break;
+                    }
+                    liveCount.set(runId, 0);
+                    const dispatchedEffectIds = new Set();
+                    let guard = 0;
+                    while (!isRunTerminal(cursor.state)) {
+                        if (guard >= maxWakeIterations) {
+                            return yield* Effect.fail(new MaxWakeIterationsError(runId, maxWakeIterations));
+                        }
+                        guard += 1;
+                        const state = cursor.state;
+                        const now = Date.now();
+                        const due = Object.values(state.waits).filter((record) => isWaitOnTimer(record.on) && record.on.timerAt <= now + 5);
+                        if (due.length > 0) {
+                            const batch = [];
+                            for (const record of due) {
+                                if (!isWaitOnTimer(record.on)) {
+                                    continue;
+                                }
+                                batch.push(createEvent(runId, {
+                                    type: 'runtime.timer.fired',
+                                    payload: { timerId: record.waitId, waitId: record.waitId },
+                                    threadId: record.threadId,
+                                    origin: { type: 'system' },
+                                }));
+                            }
+                            const stateAfterFired = foldRun(batch, registry, { runId, initial: state });
+                            const satisfied = waitSatisfiedEvents(stateAfterFired, batch);
+                            const satisfiedEvents = satisfied.map((input) => createEvent(runId, input));
+                            const fullTimerBatch = [...batch, ...satisfiedEvents];
+                            const appendResult = yield* store.append(runId, stripSeq(fullTimerBatch));
+                            cursor = yield* applyAppend(store, runId, cursor, stripSeq(fullTimerBatch), appendResult);
+                            continue;
+                        }
+                        const outstanding = state.outstandingEffects;
+                        if (outstanding.length === 0) {
+                            break;
+                        }
+                        for (const item of outstanding) {
+                            if (dispatchedEffectIds.has(item.effectId)) {
+                                return yield* Effect.fail(new DuplicateEffectDispatchError(runId, item.effectId, item.threadId));
+                            }
+                        }
+                        for (const item of outstanding) {
+                            dispatchedEffectIds.add(item.effectId);
+                        }
+                        const groupKeys = groupOutstanding(outstanding);
+                        const groupResults = yield* Effect.forEach(groupKeys, (groupKey) => Effect.gen(function* () {
+                            const group = outstanding.filter((item) => `${item.threadId}:${item.causingSeq}` === groupKey);
+                            const groupProduced = [];
+                            let failedEffectId;
+                            for (const item of group) {
+                                if (failedEffectId && item.effect.type === 'runtime.wait') {
+                                    groupProduced.push(createEffectFailedEvent(runId, item, withdrawnError(failedEffectId)));
+                                    continue;
+                                }
+                                const appendLive = async (input) => {
+                                    const validated = await Effect.runPromise(validateEventInput(registry.catalogs, input));
+                                    const liveEvent = createLiveEvent(runId, item, validated);
+                                    if (liveEvent) {
+                                        await Effect.runPromise(liveAppends.push(runId, liveEvent));
+                                    }
+                                };
+                                const outcomes = yield* dispatchEffect(registry, services, definitions, item.effect, {
+                                    effectId: item.effectId,
+                                    runId,
+                                    threadId: item.threadId,
+                                    causingEventId: item.causingEventId,
+                                    emit: appendLive,
+                                });
+                                const before = groupProduced.length;
+                                if (outcomes.length === 0) {
+                                    groupProduced.push(createEffectFailedEvent(runId, item, 'empty-outcome'));
+                                }
+                                for (const input of outcomes) {
+                                    groupProduced.push(yield* materializeEffectOutcome(registry.catalogs, runId, item, input));
+                                }
+                                const groupOutcomes = groupProduced.slice(before);
+                                if (item.effect.type !== 'runtime.wait' &&
+                                    groupOutcomes.some((event) => event.type === 'runtime.effect.failed')) {
+                                    failedEffectId = item.effectId;
+                                }
+                            }
+                            return groupProduced;
+                        }), { concurrency: 'unbounded' });
+                        const produced = groupResults.flat();
+                        if (produced.length === 0) {
+                            break;
+                        }
+                        yield* liveAppends.drain(runId);
+                        const beforeFold = cursor.state;
+                        const intermediateState = foldRun(produced, registry, { runId, initial: beforeFold });
+                        const synthesized = synthesizedThreadFailed(beforeFold, intermediateState, produced);
+                        const synthesizedEvents = synthesized.map((input) => createEvent(runId, input));
+                        const stateAfterSynth = synthesizedEvents.length > 0
+                            ? foldRun(synthesizedEvents, registry, { runId, initial: intermediateState })
+                            : intermediateState;
+                        const allNewEvents = [...produced, ...synthesizedEvents];
+                        const satisfied = waitSatisfiedEvents(stateAfterSynth, allNewEvents);
+                        const satisfiedEvents = satisfied.map((input) => createEvent(runId, input));
+                        const fullBatch = [...allNewEvents, ...satisfiedEvents];
+                        const appendResult = yield* store.append(runId, stripSeq(fullBatch));
+                        cursor = yield* applyAppend(store, runId, cursor, stripSeq(fullBatch), appendResult);
+                        // Bound replay after a crash inside a long wake.
+                        if (snapshotEvery > 0 && cursor.durableSinceSnapshot >= snapshotEvery) {
+                            cursor = yield* persistSnapshot(store, runId, cursor);
+                        }
+                    }
+                    const root = cursor.state.rootThreadId
+                        ? cursor.state.threads[cursor.state.rootThreadId]
+                        : undefined;
+                    if (root &&
+                        (root.status === 'completed' ||
+                            root.status === 'failed' ||
+                            root.status === 'cancelled') &&
+                        !isRunTerminal(cursor.state)) {
+                        const completed = createEvent(runId, {
+                            type: 'runtime.run.completed',
+                            payload: {
+                                output: root.output,
+                                error: root.error,
+                            },
+                            threadId: null,
+                            origin: { type: 'system' },
+                        });
+                        const appendResult = yield* store.append(runId, stripSeq([completed]));
+                        cursor = yield* applyAppend(store, runId, cursor, stripSeq([completed]), appendResult);
+                    }
+                    // Snapshot on park: the next wake (on any instance) starts from here.
+                    cursor = yield* persistSnapshot(store, runId, cursor);
+                    const pendingTimers = Object.values(cursor.state.waits).filter((record) => isWaitOnTimer(record.on) && record.on.timerAt > Date.now());
+                    if (pendingTimers.length > 0 && !isRunTerminal(cursor.state)) {
+                        // SAFETY: pendingTimers is filtered by isWaitOnTimer above.
+                        const earliestTimerAt = Math.min(...pendingTimers.map((r) => r.on.timerAt));
+                        yield* toEffectVoid(scheduler.schedule(runId, earliestTimerAt));
+                    }
+                    else {
+                        yield* toEffectVoid(scheduler.cancel(runId));
+                    }
+                    if (isRunTerminal(cursor.state)) {
+                        runCache.delete(runId);
+                    }
+                    else {
+                        runCache.set(runId, cursor);
+                    }
+                    finalState = cursor.state;
+                } while (wakeAgain.delete(runId));
+                // Lost race: a waiter queued after the drain loop but before unlock.
+                if (wakeAgain.has(runId)) {
+                    waking.delete(runId);
+                    liveAppends.clear(runId);
+                    liveCount.delete(runId);
+                    return yield* runtime.wake(runId);
+                }
+                return finalState;
+            }
+            finally {
+                if (waking.has(runId)) {
+                    waking.delete(runId);
+                }
+                liveAppends.clear(runId);
+                liveCount.delete(runId);
+            }
+        }),
+        dispose: () => {
+            scheduler.dispose?.();
+        },
+    };
+    scheduler =
+        options.scheduler ??
+            createTimeoutScheduler((runId) => {
+                if (options.store) {
+                    Effect.runPromise(Effect.provideService(runtime.wake(runId), EventStoreTag, options.store)).catch((err) => {
+                        console.error('[timer wake error]', err);
+                    });
+                }
+            });
+    return runtime;
+}

package/dist/runtime/server.d.ts

@@ -0,0 +1,17 @@
+import { type EventStore } from '@swirls/looms/core';
+import type { LoomsRuntime } from './runtime';
+export interface FetchHandlerOptions {
+    runtime: LoomsRuntime;
+    store: EventStore;
+}
+export interface RunningServer {
+    port: number;
+    stop: () => void;
+}
+export type LoomsFetchResult = Response | null;
+export declare function isLoomsApiPath(path: string): boolean;
+export declare function createFetchHandler(options: FetchHandlerOptions): (req: Request) => Promise<Response | null>;
+export declare function serveHttp(fetchHandler: (req: Request) => Promise<Response | null>, options?: {
+    port?: number;
+    hostname?: string;
+}): RunningServer;