@swirls/looms 0.0.1 → 0.1.0

package/dist/runtime/looms.js

@@ -1,53 +1,70 @@
-import { Effect, Predicate } from 'effect';
+import { Data, Effect, Predicate } from 'effect';
 import { EventStoreTag, makeMemoryEventStore, snapshotStoreOf, SnapshotStoreTag, } from '@swirls/looms/core';
-import { createRuntime } from './runtime.js';
-import { createFetchHandler, isLoomsApiPath, serveHttp } from './server.js';
+import { createRuntime, } from './runtime.js';
+import { createFetchHandler, isLoomsApiPath, serveHttp, } from './server.js';
+class LoomsInitializationError extends Data.TaggedError('LoomsInitializationError') {
+    constructor(cause) {
+        super({
+            cause,
+            message: cause instanceof Error ? cause.message : String(cause),
+        });
+        this.name = 'LoomsInitializationError';
+    }
+}
 export function createLooms(options = {}) {
     const modules = options.modules ?? [];
     let initPromise;
     let runningServer;
     const getInit = () => {
         if (!initPromise) {
-            initPromise = (async () => {
-                let store;
-                if (!options.store) {
-                    store = await Effect.runPromise(makeMemoryEventStore);
-                }
-                else if (Predicate.isFunction(options.store)) {
-                    store = await options.store();
-                }
-                else {
-                    store = await options.store;
-                }
+            initPromise = Effect.runPromise(Effect.gen(function* () {
+                const configuredStore = options.store;
+                const store = !configuredStore
+                    ? yield* makeMemoryEventStore
+                    : Predicate.isFunction(configuredStore)
+                        ? yield* Effect.tryPromise({
+                            try: configuredStore,
+                            catch: (cause) => new LoomsInitializationError(cause),
+                        })
+                        : configuredStore instanceof Promise
+                            ? yield* Effect.tryPromise({
+                                try: () => configuredStore,
+                                catch: (cause) => new LoomsInitializationError(cause),
+                            })
+                            : configuredStore;
                 const runtime = createRuntime({
                     modules,
                     store,
                     maxWakeIterations: options.maxWakeIterations,
+                    maxPendingRunOperations: options.maxPendingRunOperations,
                     snapshotEvery: options.snapshotEvery,
                     snapshotStore: options.snapshotStore ?? snapshotStoreOf(store),
                     trimAfterSnapshot: options.trimAfterSnapshot,
                     runCacheSize: options.runCacheSize,
                     scheduler: options.scheduler,
+                    worker: options.worker,
+                    observer: options.observer,
                 });
                 if (options.rescanTimers !== false) {
-                    await Effect.runPromise(Effect.provideService(runtime.rescanTimers(), EventStoreTag, store)).catch((err) => {
-                        console.error('[rescan timers error]', err);
-                    });
+                    yield* runtime.rescanTimers.pipe(Effect.provideService(EventStoreTag, store), Effect.tapError(Effect.logError), Effect.ignore);
                 }
-                const fetchHandler = createFetchHandler({ runtime, store });
+                const fetchHandler = createFetchHandler({
+                    runtime,
+                    store,
+                    authorize: options.authorize,
+                });
                 return { runtime, store, snapshotStore: snapshotStoreOf(store), fetchHandler };
-            })();
+            }));
         }
         return initPromise;
     };
-    const runEffect = async (fn) => {
-        const init = await getInit();
+    const runEffect = (fn) => getInit().then((init) => {
         let provided = Effect.provideService(fn(init), EventStoreTag, init.store);
         if (init.snapshotStore) {
             provided = Effect.provideService(provided, SnapshotStoreTag, init.snapshotStore);
         }
         return Effect.runPromise(provided);
-    };
+    });
     const looms = {
         get runtime() {
             return getInit().then((i) => i.runtime);
@@ -55,14 +72,12 @@ export function createLooms(options = {}) {
         get store() {
             return getInit().then((i) => i.store);
         },
-        ready: async () => {
-            const init = await getInit();
-            return { store: init.store, runtime: init.runtime };
-        },
+        ready: () => getInit().then(({ store, runtime }) => ({ store, runtime })),
         startRun: (args) => runEffect((i) => i.runtime.startRun(args)),
         start: (definition, input, startOpts) => runEffect((i) => i.runtime.startRun({
             kind: definition.kind,
             definitionName: definition.name,
+            definitionVersion: definition.version,
             // SAFETY: input is validated against the definition's schema inside startRun.
             input: input,
             runId: startOpts?.runId,
@@ -73,16 +88,20 @@ export function createLooms(options = {}) {
         getEvents: (runId, opts) => runEffect((i) => i.runtime.getEvents(runId, opts)),
         signal: (runId, events, signalOpts) => runEffect((i) => i.runtime.signal(runId, events, signalOpts)),
         wake: (runId) => runEffect((i) => i.runtime.wake(runId)),
-        rescanTimers: () => runEffect((i) => i.runtime.rescanTimers()),
+        rescanTimers: () => runEffect((i) => i.runtime.rescanTimers),
+        recoverDeadlines: () => runEffect((i) => i.runtime.recoverDeadlines),
+        inspectRun: (runId) => runEffect((i) => i.runtime.inspectRun(runId)),
+        retryEffect: (runId, effectId) => runEffect((i) => i.runtime.retryEffect(runId, effectId)),
+        listRuns: () => runEffect((i) => i.runtime.listRuns),
         project: (runId, definition) => runEffect((i) => i.runtime.project(runId, definition)),
         replayTo: (runId, seq) => runEffect((i) => i.runtime.replayTo(runId, seq)),
         cancel: (runId, threadId) => runEffect((i) => i.runtime.cancel(runId, threadId)),
-        fetch: async (req) => {
+        workerCallback: (runId, input) => runEffect((i) => i.runtime.workerCallback(runId, input)),
+        fetch: (req) => {
             if (!isLoomsApiPath(new URL(req.url).pathname)) {
-                return null;
+                return Promise.resolve(null);
             }
-            const { fetchHandler } = await getInit();
-            return fetchHandler(req);
+            return getInit().then(({ fetchHandler }) => fetchHandler(req));
         },
         serve: (serveOpts) => {
             if (runningServer) {
@@ -91,15 +110,14 @@ export function createLooms(options = {}) {
             runningServer = serveHttp((req) => looms.fetch(req), serveOpts);
             return runningServer;
         },
-        stop: async () => {
+        stop: () => {
             if (runningServer) {
                 runningServer.stop();
                 runningServer = undefined;
             }
-            if (initPromise) {
-                const init = await initPromise;
-                init.runtime.dispose();
-            }
+            return initPromise
+                ? initPromise.then(({ runtime }) => Effect.runPromise(runtime.dispose))
+                : Promise.resolve();
         },
     };
     if (options.serve) {

package/dist/runtime/observer.d.ts

@@ -0,0 +1,45 @@
+export type RuntimeObservation = {
+    readonly type: 'run.start';
+    readonly runId: string;
+    readonly at: number;
+} | {
+    readonly type: 'run.wake';
+    readonly runId: string;
+    readonly at: number;
+} | {
+    readonly type: 'run.park' | 'run.terminal';
+    readonly runId: string;
+    readonly at: number;
+    readonly status: string;
+} | {
+    readonly type: 'event.append';
+    readonly runId: string;
+    readonly at: number;
+    readonly eventCount: number;
+    readonly latencyMs: number;
+    readonly outcome: 'ok' | 'conflict' | 'error';
+} | {
+    readonly type: 'snapshot.load' | 'snapshot.save' | 'snapshot.trim';
+    readonly runId: string;
+    readonly at: number;
+    readonly latencyMs: number;
+    readonly outcome: 'ok' | 'miss' | 'error';
+    readonly cursor?: number;
+} | {
+    readonly type: 'timer.late';
+    readonly runId: string;
+    readonly at: number;
+    readonly timerId: string;
+    readonly latenessMs: number;
+} | {
+    readonly type: 'effect.attempt' | 'effect.retry' | 'effect.timeout' | 'effect.heartbeat' | 'effect.cancellation';
+    readonly runId: string;
+    readonly at: number;
+    readonly effectId: string;
+    readonly attempt: number;
+    readonly detail?: string;
+};
+export interface RuntimeObserver {
+    observe(event: RuntimeObservation): void | Promise<void>;
+}
+export declare function notifyObserver(observer: RuntimeObserver | undefined, event: RuntimeObservation): void;

package/dist/runtime/observer.js

@@ -0,0 +1,11 @@
+export function notifyObserver(observer, event) {
+    if (!observer) {
+        return;
+    }
+    try {
+        Promise.resolve(observer.observe(event)).catch(() => undefined);
+    }
+    catch {
+        // Observability must never change runtime behavior.
+    }
+}

package/dist/runtime/repository.d.ts

@@ -0,0 +1,55 @@
+import { Effect } from 'effect';
+import { EventStoreTrimmedError, type AppendableEvent, type AppendResult, type ComposedRegistry, type EventEnvelope, type EventStore, type EventStoreAppendError, type EventStoreError, type EventStoreTrimCoverage, type EventStoreTruncationError, type RunCursor, type SnapshotStore } from '@swirls/looms/core';
+import { RuntimeExecutionError } from './errors';
+import { type RunCursorCache } from './helpers';
+import { type RuntimeObserver } from './observer';
+import type { RunExecutionContexts } from './run-execution-context';
+declare const LiveAppendError_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: "LiveAppendError";
+} & Readonly<A>;
+declare class LiveAppendError extends LiveAppendError_base<{
+    readonly message: string;
+}> {
+    constructor();
+}
+export interface CommitPlan<A> {
+    readonly events: ReadonlyArray<EventEnvelope>;
+    readonly value: A;
+    readonly idempotencyKey?: string | undefined;
+}
+export interface CommitResult<A> {
+    readonly value: A;
+    /** The durable state the committed batch was planned against. */
+    readonly cursor: RunCursor;
+    /** `null` when the plan had nothing to append. */
+    readonly append: AppendResult | null;
+}
+export interface RuntimeRepositoryOptions {
+    readonly registry: ComposedRegistry;
+    readonly snapshotStore: SnapshotStore;
+    readonly trimAfterSnapshot?: {
+        readonly keepSnapshots: number;
+        readonly coverage?: (runId: string) => EventStoreTrimCoverage | Promise<EventStoreTrimCoverage>;
+    };
+    readonly keepSnapshots: number;
+    readonly runCache: RunCursorCache;
+    readonly executionContexts: RunExecutionContexts;
+    readonly observer?: RuntimeObserver;
+}
+export declare function createRuntimeRepository(options: RuntimeRepositoryOptions): {
+    appendObserved: (store: EventStore, runId: string, events: ReadonlyArray<AppendableEvent>, appendOptions?: Parameters<EventStore['append']>[2]) => Effect.Effect<AppendResult, EventStoreAppendError>;
+    commit: <A, E, R>(store: EventStore, runId: string, plan: (cursor: RunCursor) => Effect.Effect<CommitPlan<A>, E, R>) => Effect.Effect<CommitResult<A>, E | RuntimeExecutionError | EventStoreAppendError | EventStoreTruncationError | EventStoreTrimmedError | EventStoreError, R>;
+    liveAppends: {
+        push: (key: string, event: AppendableEvent) => Effect.Effect<void, LiveAppendError | EventStoreAppendError, never>;
+        drain: (key: string) => Effect.Effect<void>;
+        clear: (key?: string) => void;
+        size: () => number;
+    };
+    loadCursor: (store: EventStore, runId: string) => Effect.Effect<RunCursor, EventStoreTruncationError | EventStoreTrimmedError | EventStoreError>;
+    persistSnapshot: (store: EventStore, runId: string, cursor: RunCursor) => Effect.Effect<RunCursor>;
+    applyAppend: (store: EventStore, runId: string, cursor: RunCursor, batch: ReadonlyArray<AppendableEvent>, appendResult: AppendResult, commandRecords?: number) => Effect.Effect<RunCursor, EventStoreTruncationError | EventStoreTrimmedError | EventStoreError>;
+    deleteCachedCursor: (runId: string) => void;
+    setCachedCursor: (runId: string, cursor: RunCursor) => void;
+};
+export type RuntimeRepository = ReturnType<typeof createRuntimeRepository>;
+export {};

package/dist/runtime/repository.js

@@ -0,0 +1,278 @@
+import { Clock, Data, Effect, Option } from 'effect';
+import { advanceCursor, assignSequences, createCoalescingAppender, emptyCursor, EventStoreTrimmedError, hashRunState, trimEventStoreSafely, } from '@swirls/looms/core';
+import { RuntimeExecutionError } from './errors.js';
+import { stripSeq } from './helpers.js';
+import { notifyObserver } from './observer.js';
+class LiveAppendError extends Data.TaggedError('LiveAppendError') {
+    constructor() {
+        super({ message: 'Cannot append live events without a store' });
+        this.name = 'LiveAppendError';
+    }
+}
+function currentTimeMillis() {
+    return Math.floor(performance.timeOrigin + performance.now());
+}
+const MAX_COMMIT_CONFLICTS = 16;
+function readRemaining(store, runId, events, expectedTail) {
+    return 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;
+    });
+}
+export function createRuntimeRepository(options) {
+    const { registry, snapshotStore, trimAfterSnapshot, keepSnapshots, runCache, executionContexts } = options;
+    const observe = (event) => notifyObserver(options.observer, event);
+    const appendObserved = (store, runId, events, appendOptions) => Effect.suspend(() => {
+        const startedAt = currentTimeMillis();
+        return store.append(runId, events, appendOptions).pipe(Effect.tap(() => Effect.sync(() => observe({
+            type: 'event.append',
+            runId,
+            at: currentTimeMillis(),
+            eventCount: events.length,
+            latencyMs: currentTimeMillis() - startedAt,
+            outcome: 'ok',
+        }))), Effect.tapError((error) => Effect.sync(() => observe({
+            type: 'event.append',
+            runId,
+            at: currentTimeMillis(),
+            eventCount: events.length,
+            latencyMs: currentTimeMillis() - startedAt,
+            outcome: error._tag === 'EventStoreConflictError' ? 'conflict' : 'error',
+        }))));
+    });
+    const liveAppends = createCoalescingAppender((runId, batch) => {
+        const context = executionContexts.peek(runId);
+        if (!context?.liveStore) {
+            return Effect.fail(new LiveAppendError());
+        }
+        const store = context.liveStore;
+        return appendObserved(store, runId, batch).pipe(Effect.tap((result) => Effect.sync(() => {
+            context.liveCount += result.sequences.length;
+        })), Effect.asVoid);
+    });
+    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* new EventStoreTrimmedError(runId, bounds.head, fromSeq);
+                }
+            }
+            else {
+                return yield* 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 loadStartedAt = currentTimeMillis();
+            const snap = yield* snapshotStore.loadLatest(runId).pipe(Effect.tapError((error) => Effect.sync(() => {
+                observe({
+                    type: 'snapshot.load',
+                    runId,
+                    at: currentTimeMillis(),
+                    latencyMs: currentTimeMillis() - loadStartedAt,
+                    outcome: 'error',
+                });
+            }).pipe(Effect.andThen(Effect.logWarning(`Snapshot load failed for run "${runId}"; replaying the log`, error)))), Effect.orElseSucceed(() => Option.none()));
+            if (Option.isSome(snap)) {
+                observe({
+                    type: 'snapshot.load',
+                    runId,
+                    at: currentTimeMillis(),
+                    latencyMs: currentTimeMillis() - loadStartedAt,
+                    outcome: 'ok',
+                    cursor: snap.value.cursor,
+                });
+                cursor = {
+                    state: snap.value.state,
+                    seq: snap.value.cursor,
+                    durableSinceSnapshot: 0,
+                };
+            }
+            else {
+                observe({
+                    type: 'snapshot.load',
+                    runId,
+                    at: currentTimeMillis(),
+                    latencyMs: currentTimeMillis() - loadStartedAt,
+                    outcome: 'miss',
+                });
+            }
+        }
+        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* new EventStoreTrimmedError(runId, bounds.head, 1);
+                }
+            }
+            else {
+                return yield* 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;
+        }
+        const takenAt = yield* Clock.currentTimeMillis;
+        const saveStartedAt = currentTimeMillis();
+        yield* snapshotStore.save({
+            runId,
+            cursor: cursor.seq,
+            stateHash: hashRunState(cursor.state),
+            takenAt,
+            state: cursor.state,
+        });
+        observe({
+            type: 'snapshot.save',
+            runId,
+            at: currentTimeMillis(),
+            latencyMs: currentTimeMillis() - saveStartedAt,
+            outcome: 'ok',
+            cursor: cursor.seq,
+        });
+        if (snapshotStore.prune) {
+            yield* snapshotStore.prune(runId, keepSnapshots);
+        }
+        const coverageForRun = trimAfterSnapshot?.coverage;
+        if (coverageForRun && store.trim && snapshotStore.listCursors) {
+            const cursors = yield* snapshotStore.listCursors(runId);
+            const oldestKept = cursors[Math.max(0, cursors.length - keepSnapshots)];
+            if (oldestKept !== undefined) {
+                const trimStartedAt = currentTimeMillis();
+                const coverage = yield* Effect.tryPromise({
+                    try: () => Promise.resolve(coverageForRun(runId)),
+                    catch: (cause) => new RuntimeExecutionError(cause instanceof Error ? cause.message : String(cause)),
+                });
+                yield* trimEventStoreSafely(store, runId, oldestKept + 1, coverage);
+                observe({
+                    type: 'snapshot.trim',
+                    runId,
+                    at: currentTimeMillis(),
+                    latencyMs: currentTimeMillis() - trimStartedAt,
+                    outcome: 'ok',
+                    cursor: oldestKept,
+                });
+            }
+        }
+        return { ...cursor, durableSinceSnapshot: 0 };
+    }).pipe(Effect.tapError((error) => Effect.logWarning(`Snapshot persistence failed for run "${runId}"`, error)), Effect.orElseSucceed(() => 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 context = executionContexts.get(runId);
+            if (context.liveCount === gap) {
+                next = { ...cursor, seq: first.seq - 1 };
+            }
+            else {
+                next = yield* catchUp(store, runId, cursor, first.seq - 1);
+            }
+        }
+        next = advanceCursor(next, echo, registry);
+        executionContexts.get(runId).liveCount = 0;
+        if (next.seq !== appendResult.tail) {
+            next = yield* catchUp(store, runId, next, appendResult.tail);
+        }
+        runCache.set(runId, next);
+        return next;
+    });
+    /**
+     * Plan a batch against the latest durable state and append it with optimistic concurrency,
+     * replanning from fresh state whenever another writer got there first.
+     */
+    const commit = (store, runId, plan) => Effect.gen(function* () {
+        for (let conflicts = 0; conflicts < MAX_COMMIT_CONFLICTS; conflicts += 1) {
+            const cursor = yield* loadCursor(store, runId);
+            const planned = yield* plan(cursor);
+            if (planned.events.length === 0) {
+                return { value: planned.value, cursor, append: null };
+            }
+            const append = yield* appendObserved(store, runId, stripSeq(planned.events), {
+                expectedTail: cursor.seq,
+                idempotency: planned.idempotencyKey ? { key: planned.idempotencyKey } : undefined,
+            }).pipe(Effect.asSome, Effect.catchTag('EventStoreConflictError', () => Effect.succeedNone));
+            if (Option.isSome(append)) {
+                return { value: planned.value, cursor, append: append.value };
+            }
+            runCache.delete(runId);
+        }
+        return yield* new RuntimeExecutionError(`Could not commit to run "${runId}" after ${MAX_COMMIT_CONFLICTS} conflicts`);
+    });
+    return {
+        appendObserved,
+        commit,
+        liveAppends,
+        loadCursor,
+        persistSnapshot,
+        applyAppend,
+        deleteCachedCursor: (runId) => runCache.delete(runId),
+        setCachedCursor: (runId, cursor) => runCache.set(runId, cursor),
+    };
+}

package/dist/runtime/retry-policy.d.ts

@@ -0,0 +1,16 @@
+import { type EventEnvelope, type EventOrigin, type OutstandingEffect, type RetryPolicy } from '@swirls/looms/core';
+export declare function retryBackoff(retry: RetryPolicy, attempt: number): number;
+export interface AttemptFailurePlan {
+    readonly event: EventEnvelope;
+    readonly retrying: boolean;
+}
+/** Schedule the next attempt when the retry policy allows one, otherwise fail the effect. */
+export declare function planAttemptFailure(input: {
+    readonly runId: string;
+    readonly item: OutstandingEffect;
+    readonly attempt: number;
+    readonly error: string;
+    readonly now: number;
+    readonly retry: RetryPolicy | undefined;
+    readonly origin: EventOrigin;
+}): AttemptFailurePlan;

package/dist/runtime/retry-policy.js

@@ -0,0 +1,29 @@
+import { createEvent, } from '@swirls/looms/core';
+import { createEffectFailedEvent } from './helpers.js';
+export function retryBackoff(retry, attempt) {
+    const base = Math.max(1, retry.backoffMs ?? 100);
+    const multiplier = Math.max(1, retry.backoffMultiplier ?? 2);
+    return Math.min(base * multiplier ** Math.max(0, attempt - 1), retry.maxBackoffMs ?? Number.MAX_SAFE_INTEGER);
+}
+/** Schedule the next attempt when the retry policy allows one, otherwise fail the effect. */
+export function planAttemptFailure(input) {
+    const { runId, item, attempt, error, retry } = input;
+    if (!retry || attempt >= retry.maxAttempts) {
+        return { event: createEffectFailedEvent(runId, item, error), retrying: false };
+    }
+    return {
+        retrying: true,
+        event: createEvent(runId, {
+            type: 'runtime.effect.retry.scheduled',
+            payload: {
+                effectId: item.effectId,
+                attempt,
+                nextAttemptAt: input.now + retryBackoff(retry, attempt),
+                error,
+            },
+            threadId: item.threadId,
+            causationId: item.causingEventId,
+            origin: input.origin,
+        }),
+    };
+}

package/dist/runtime/run-execution-context.d.ts

@@ -0,0 +1,30 @@
+import type { Exit } from 'effect';
+import type { EventStore, RunState } from '@swirls/looms/core';
+import type { WakeError } from './types';
+export type WakeCompletion = Exit.Exit<RunState, WakeError>;
+export interface ActiveEffect {
+    readonly controller: AbortController;
+    readonly threadId: string;
+}
+export interface RunIngressState {
+    readonly pending: number;
+    readonly tail: Promise<void>;
+}
+export interface RunExecutionContext {
+    readonly activeEffects: Map<string, ActiveEffect>;
+    waking: boolean;
+    wakeAgain: boolean;
+    wakeCompletion: Promise<WakeCompletion> | null;
+    resolveWakeCompletion: ((completion: WakeCompletion) => void) | null;
+    ingress: RunIngressState | null;
+    liveStore: EventStore | undefined;
+    liveCount: number;
+}
+export declare class RunExecutionContexts {
+    private readonly runs;
+    get(runId: string): RunExecutionContext;
+    peek(runId: string): RunExecutionContext | undefined;
+    /** Abort in-process effects owned by the given threads. */
+    abort(runId: string, threadIds: ReadonlySet<string>, message: string): void;
+    releaseIfIdle(runId: string): void;
+}