@swirls/looms 0.0.2 → 0.2.0

package/dist/runtime/runtime.js

@@ -1,213 +1,153 @@
-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';
+import { Clock, Effect, ManagedRuntime, Predicate } from 'effect';
+import { composeModules, createEvent, createThreadId, createRunId, DEFAULT_DEFINITION_VERSION, DEFAULT_SNAPSHOT_EVERY, definitionKey, EventStoreTag, foldRun, project, replayTo, summarizeRun, } from '@swirls/looms/core';
+import { createCancellation } from './cancellation.js';
+import { nextRuntimeDeadline } from './deadline-transition-planner.js';
+import { RuntimeExecutionError } from './errors.js';
+import { admitExternalEvents, moduleServices, resolveSnapshotStore, RunCursorCache, threadStartedEvents, UnknownDefinitionError, validateAndCreateEvents, waitSatisfiedEvents, } from './helpers.js';
+import { createRunIngress } from './ingress.js';
+import { notifyObserver } from './observer.js';
+import { createRuntimeRepository } from './repository.js';
+import { RunExecutionContexts } from './run-execution-context.js';
+import { assertSameDurableStart } from './run-start.js';
+import { createWakeEngine } from './wake-engine.js';
+import { createTimeoutScheduler } from './wake-scheduler.js';
+import { createWorkerCallbacks } from './worker-callbacks.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 { DuplicateEffectDispatchError, MaxWakeIterationsError, StartRunConflictError, } from './errors.js';
+export { RunOverloadedError } from './ingress.js';
+function currentTimeMillis() {
+    return Math.floor(performance.timeOrigin + performance.now());
 }
-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';
+/** Threads whose in-process effects an admitted signal interrupts. */
+function interruptedThreadIds(events, rules) {
+    const threadIds = new Set();
+    for (const event of events) {
+        const payload = Predicate.isObject(event.payload) ? event.payload : {};
+        if (event.type === 'runtime.thread.cancel.requested' && Predicate.isString(payload.threadId)) {
+            threadIds.add(payload.threadId);
+        }
+        for (const rule of rules) {
+            for (const threadId of rule(event)) {
+                threadIds.add(threadId);
+            }
+        }
     }
+    return threadIds;
 }
 const DEFAULT_RUN_CACHE_SIZE = 0;
+const RESCAN_CONCURRENCY = 16;
 const DEFAULT_KEEP_SNAPSHOTS = 1;
+const DEFAULT_MAX_PENDING_RUN_OPERATIONS = 256;
 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 definitions = new Map(registeredDefinitions.map((def) => [definitionKey(def.kind, def.name, def.version), def]));
+    // Module composition erases the heterogeneous service identifier union at this host boundary.
+    // oxlint-disable-next-line effecttsgo/any-unknown-in-error-context
+    const services = ManagedRuntime.make(moduleServices(options.modules));
+    const executionContexts = new RunExecutionContexts();
+    const maxPendingRunOperations = options.maxPendingRunOperations ?? DEFAULT_MAX_PENDING_RUN_OPERATIONS;
     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 observe = (event) => notifyObserver(options.observer, event);
+    const withRunIngress = createRunIngress(executionContexts, maxPendingRunOperations);
+    const repository = createRuntimeRepository({
+        registry,
+        snapshotStore,
+        trimAfterSnapshot,
+        keepSnapshots,
+        runCache,
+        executionContexts,
+        observer: options.observer,
     });
-    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));
+    const { commit, loadCursor } = repository;
+    const signalAdmitted = (runId, events, signalOpts) => Effect.gen(function* () {
+        const store = yield* EventStoreTag;
+        const signalKey = signalOpts?.idempotencyKey;
+        const committed = yield* commit(store, runId, (current) => Effect.gen(function* () {
+            const processed = current.state.processedIdempotencyKeys;
+            const filteredEvents = signalKey && processed.includes(signalKey)
+                ? []
+                : events.filter((input) => {
+                    const key = input.idempotencyKey ?? signalKey;
+                    return !key || !processed.includes(key);
+                });
+            if (filteredEvents.length === 0) {
+                return { events: [], value: current.state };
             }
+            const batch = yield* validateAndCreateEvents(registry.catalogs, runId, filteredEvents.map((input) => ({
+                ...input,
+                idempotencyKey: input.idempotencyKey ?? signalKey,
+            })), { origin: { type: 'external' } });
+            const folded = foldRun(batch, registry, { runId, initial: current.state });
+            const satisfiedEvents = waitSatisfiedEvents(folded, batch).map((input) => createEvent(runId, input));
+            return {
+                events: [...batch, ...satisfiedEvents],
+                value: current.state,
+                idempotencyKey: signalKey ? `signal:${signalKey}` : undefined,
+            };
+        }));
+        if (committed.append) {
+            executionContexts.abort(runId, interruptedThreadIds(events, registry.interruptRules), 'Effect interrupted');
         }
-        delta = yield* readRemaining(store, runId, delta, expectedTail);
-        return advanceCursor(cursor, delta, registry);
+        return committed.value;
     });
-    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);
+    let scheduler;
+    let runtime;
+    const wakeEngine = createWakeEngine({
+        registry,
+        services,
+        definitions,
+        executionContexts,
+        repository,
+        snapshotEvery,
+        maxWakeIterations,
+        worker: options.worker,
+        observer: options.observer,
+        scheduler: () => scheduler,
     });
-    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;
+    const workerCallbacks = createWorkerCallbacks({
+        registry,
+        repository,
+        withRunIngress,
+        observer: options.observer,
+        wake: wakeEngine,
     });
-    /**
-     * 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;
+    const cancellation = createCancellation({
+        registry,
+        repository,
+        executionContexts,
+        worker: options.worker,
+        observer: options.observer,
+        wake: wakeEngine,
+        withRunIngress,
     });
-    let scheduler;
-    const runtime = {
+    runtime = {
         modules: options.modules,
         registry,
-        listRuns: () => Effect.gen(function* () {
+        ...workerCallbacks,
+        listRuns: Effect.gen(function* () {
             const store = yield* EventStoreTag;
-            return yield* store.listRuns();
+            return yield* store.listRuns;
+        }),
+        listRunSummaries: Effect.gen(function* () {
+            const store = yield* EventStoreTag;
+            const runIds = yield* store.listRuns;
+            const indexed = yield* snapshotStore.listHeaders;
+            const byId = new Map(indexed.map((header) => [header.runId, header]));
+            const missing = runIds.filter((runId) => !byId.has(runId));
+            const filled = yield* Effect.forEach(missing, (runId) => runtime.getRun(runId).pipe(Effect.map(summarizeRun)), { concurrency: 8 });
+            for (const header of filled) {
+                byId.set(header.runId, header);
+            }
+            return runIds.flatMap((runId) => {
+                const header = byId.get(runId);
+                return header ? [header] : [];
+            });
         }),
         getEvents: (runId, readOptions) => Effect.gen(function* () {
             const store = yield* EventStoreTag;
@@ -226,306 +166,144 @@ export function createRuntime(options) {
             const events = yield* runtime.getEvents(runId);
             return replayTo(events, registry, seq);
         }),
-        rescanTimers: () => Effect.gen(function* () {
+        inspectRun: (runId) => 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;
+            const state = yield* runtime.getRun(runId);
+            const tail = yield* store.tail(runId);
+            const bounds = store.bounds ? yield* store.bounds(runId) : { head: 1, tail };
+            const effects = state.outstandingEffects.map((item) => {
+                const execution = state.effectExecutions[item.effectId];
+                return {
+                    effectId: item.effectId,
+                    threadId: item.threadId,
+                    type: item.effect.type,
+                    attempt: execution?.attempt ?? 0,
+                    status: execution?.status ?? 'pending',
+                    deadlineAt: execution?.deadlineAt ?? null,
+                    lastError: execution?.lastError ?? null,
+                };
+            });
+            return { runId, state, head: bounds.head, tail, effects };
         }),
-        startRun: (args) => Effect.gen(function* () {
-            if (!definitions.get(`${args.kind}:${args.definitionName}`)) {
-                return yield* Effect.fail(new Error(`Unknown definition ${args.kind}:${args.definitionName}`));
-            }
+        retryEffect: (runId, effectId) => withRunIngress(runId, Effect.gen(function* () {
             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,
-                    };
+            yield* commit(store, runId, (cursor) => Effect.gen(function* () {
+                const execution = cursor.state.effectExecutions[effectId];
+                const item = cursor.state.outstandingEffects.find((candidate) => candidate.effectId === effectId);
+                if (!execution || !item) {
+                    return yield* new RuntimeExecutionError(`Unknown outstanding effect "${effectId}"`);
                 }
-            }
-            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',
+                if (execution.status !== 'ambiguous' &&
+                    execution.status !== 'timed_out' &&
+                    execution.status !== 'cancel_requested') {
+                    return yield* new RuntimeExecutionError(`Effect "${effectId}" cannot be retried from status "${execution.status}"`);
+                }
+                const now = yield* Clock.currentTimeMillis;
+                const retryEvent = createEvent(runId, {
+                    type: 'runtime.effect.retry.scheduled',
                     payload: {
-                        rootThreadId: threadId,
-                        kind: args.kind,
-                        definitionName: args.definitionName,
-                        input: startedInput,
+                        effectId,
+                        attempt: execution.attempt,
+                        nextAttemptAt: now,
+                        error: `operator retry from ${execution.status}`,
                     },
-                    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* () {
+                    threadId: item.threadId,
+                    causationId: item.causingEventId,
+                    origin: { type: 'external', actorId: 'operator' },
+                });
+                return { events: [retryEvent], value: undefined };
+            }));
+        })).pipe(Effect.andThen(runtime.wake(runId))),
+        rescanTimers: 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' },
-                },
-            ]);
+            const runIds = yield* store.listRuns;
+            const scheduled = yield* Effect.forEach(runIds, (runId) => Effect.gen(function* () {
+                const deadline = nextRuntimeDeadline(yield* runtime.getRun(runId));
+                if (deadline === undefined) {
+                    return false;
+                }
+                yield* scheduler.schedule(runId, deadline);
+                return true;
+            }), { concurrency: RESCAN_CONCURRENCY });
+            return scheduled.filter(Boolean).length;
         }),
-        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',
+        recoverDeadlines: Effect.suspend(() => runtime.rescanTimers),
+        startRun: (args) => {
+            const runId = args.runId ?? createRunId();
+            return withRunIngress(runId, Effect.gen(function* () {
+                const definitionVersion = args.definitionVersion ?? DEFAULT_DEFINITION_VERSION;
+                if (!definitions.get(definitionKey(args.kind, args.definitionName, definitionVersion))) {
+                    return yield* new UnknownDefinitionError(args.kind, args.definitionName, definitionVersion);
+                }
+                const store = yield* EventStoreTag;
+                observe({ type: 'run.start', runId, at: currentTimeMillis() });
+                const threadId = args.threadId ?? createThreadId();
+                const startedEvents = yield* threadStartedEvents(definitions, {
+                    kind: args.kind,
+                    definitionName: args.definitionName,
+                    definitionVersion,
+                    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 requestedIdentity = {
+                    kind: args.kind,
+                    definitionName: args.definitionName,
+                    definitionVersion,
+                    input: startedInput,
+                    requestedThreadId: args.threadId ?? null,
+                    idempotencyKey: args.idempotencyKey ?? null,
+                };
+                const committed = yield* commit(store, runId, (existing) => existing.seq > 0
+                    ? assertSameDurableStart(runId, existing.state, requestedIdentity).pipe(Effect.map((rootThreadId) => ({ events: [], value: rootThreadId })))
+                    : validateAndCreateEvents(registry.catalogs, runId, [
+                        {
+                            type: 'runtime.run.started',
                             payload: {
-                                output: root.output,
-                                error: root.error,
+                                rootThreadId: threadId,
+                                kind: args.kind,
+                                definitionName: args.definitionName,
+                                definitionVersion,
+                                input: startedInput,
+                                requestedThreadId: args.threadId ?? null,
                             },
                             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);
+                            idempotencyKey: args.idempotencyKey,
+                        },
+                        ...startedEvents,
+                    ], { origin: { type: 'system' } }).pipe(Effect.map((batch) => ({
+                        events: batch,
+                        value: threadId,
+                        idempotencyKey: args.idempotencyKey
+                            ? `start:${args.idempotencyKey}`
+                            : undefined,
+                    }))));
+                if (!committed.append?.deduplicated) {
+                    return committed.value;
                 }
-                liveAppends.clear(runId);
-                liveCount.delete(runId);
-            }
-        }),
-        dispose: () => {
-            scheduler.dispose?.();
+                const durable = yield* loadCursor(store, runId);
+                return yield* assertSameDurableStart(runId, durable.state, requestedIdentity);
+            })).pipe(Effect.flatMap((threadId) => runtime.wake(runId).pipe(Effect.map((state) => ({
+                runId,
+                threadId: state.rootThreadId ?? threadId,
+                state,
+            })))));
         },
+        signal: (runId, events, signalOpts) => admitExternalEvents(events).pipe(Effect.flatMap((admitted) => withRunIngress(runId, signalAdmitted(runId, admitted, signalOpts))), Effect.andThen(runtime.wake(runId))),
+        cancel: cancellation,
+        wake: wakeEngine,
+        dispose: Effect.sync(() => scheduler.dispose?.()).pipe(Effect.andThen(services.disposeEffect)),
     };
     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);
-                    });
-                }
-            });
+            createTimeoutScheduler((runId) => options.store
+                ? runtime
+                    .wake(runId)
+                    .pipe(Effect.provideService(EventStoreTag, options.store), Effect.tapError(Effect.logError), Effect.ignore)
+                : Effect.void);
     return runtime;
 }