@swirls/looms 0.0.2 → 0.2.0

package/dist/runtime/server/routes/runs.js

@@ -0,0 +1,199 @@
+import { Effect, Schema } from 'effect';
+import { createRunId, EventStoreTag, JsonValueSchema, stringifyJson, } from '@swirls/looms/core';
+import { createEventStreamResponse } from '../../sse.js';
+import { acceptsEventStream, EventInputBodySchema, extractIdempotencyKey, provideStore, readIntegerQuery, readJson, RequestQueryError, } from '../http.js';
+import { route } from '../route-table.js';
+const StartRunBodySchema = Schema.Struct({
+    kind: Schema.optional(Schema.String),
+    definitionName: Schema.optional(Schema.String),
+    definitionVersion: Schema.optional(Schema.String),
+    name: Schema.optional(Schema.String),
+    input: Schema.optional(JsonValueSchema),
+    runId: Schema.optional(Schema.String),
+    idempotencyKey: Schema.optional(Schema.String),
+});
+const SignalBodySchema = Schema.Struct({
+    events: Schema.optional(Schema.Array(EventInputBodySchema)),
+    type: Schema.optional(Schema.String),
+    payload: Schema.optional(JsonValueSchema),
+    threadId: Schema.optional(Schema.NullOr(Schema.String)),
+    idempotencyKey: Schema.optional(Schema.String),
+});
+function wantsRunStream(req, url) {
+    return url.searchParams.get('stream') === 'true' || acceptsEventStream(req);
+}
+function wantsEventStream(req, url) {
+    const live = url.searchParams.get('live');
+    return live === 'true' || live === '1' || acceptsEventStream(req);
+}
+function readEventStreamFromSeq(req, url) {
+    const lastEventId = req.headers.get('last-event-id');
+    if (lastEventId !== null && lastEventId.trim() !== '') {
+        const value = Number(lastEventId);
+        if (!Number.isSafeInteger(value) || value < 0) {
+            return Effect.fail(new RequestQueryError({
+                message: 'Last-Event-ID must be a non-negative integer',
+            }));
+        }
+        return Effect.succeed(value + 1);
+    }
+    return readIntegerQuery(url, 'fromSeq', { minimum: 1 }).pipe(Effect.map((fromSeq) => fromSeq ?? 1));
+}
+function streamStartRun(req, runtime, store, args) {
+    return createEventStreamResponse({
+        signal: req.signal,
+        request: req,
+        store,
+        runId: args.runId,
+        fromSeq: 1,
+        onStart: (write, close) => runtime
+            .startRun({
+            kind: args.kind,
+            definitionName: args.definitionName,
+            definitionVersion: args.definitionVersion,
+            input: args.input,
+            runId: args.runId,
+            idempotencyKey: args.idempotencyKey,
+        })
+            .pipe(Effect.provideService(EventStoreTag, store), Effect.tap((result) => Effect.sync(() => write(`event: done\ndata: ${stringifyJson(result)}\n\n`))), Effect.catch((error) => Effect.sync(() => write(`event: error\ndata: ${stringifyJson({ error: error.message })}\n\n`))), Effect.ensuring(Effect.sync(close)), Effect.asVoid),
+    });
+}
+export function runRoutes({ runtime, store }) {
+    return [
+        route({
+            method: 'GET',
+            path: '/health',
+            name: 'health',
+            access: 'public',
+            handle: () => Effect.succeed(Response.json({ ok: true })),
+        }),
+        route({
+            method: 'GET',
+            path: '/runs',
+            name: 'runs.list',
+            access: 'read',
+            handle: () => provideStore(runtime.listRuns.pipe(Effect.map((runIds) => Response.json({ runIds }))), store),
+        }),
+        route({
+            method: 'GET',
+            path: '/runs/summaries',
+            name: 'runs.summaries',
+            access: 'read',
+            handle: () => provideStore(runtime.listRunSummaries.pipe(Effect.map((runs) => Response.json({ runs }))), store),
+        }),
+        route({
+            method: 'POST',
+            path: '/runs',
+            name: 'runs.start',
+            access: 'write',
+            handle: ({ req, url }) => Effect.gen(function* () {
+                const body = yield* readJson(req).pipe(Effect.flatMap(Schema.decodeUnknownEffect(StartRunBodySchema)));
+                const definitionName = body.definitionName ?? body.name;
+                const kind = body.kind;
+                if (!definitionName || !kind) {
+                    return Response.json({ error: 'kind and definitionName required' }, { status: 400 });
+                }
+                const runId = body.runId ?? createRunId();
+                const idempotencyKey = extractIdempotencyKey(req, body.idempotencyKey);
+                const args = {
+                    kind,
+                    definitionName,
+                    definitionVersion: body.definitionVersion,
+                    input: body.input ?? null,
+                    runId,
+                    idempotencyKey,
+                };
+                if (wantsRunStream(req, url)) {
+                    return streamStartRun(req, runtime, store, args);
+                }
+                const result = yield* provideStore(runtime.startRun(args), store);
+                return Response.json(result);
+            }),
+        }),
+        route({
+            method: 'GET',
+            path: '/runs/:runId/replay',
+            name: 'runs.replay',
+            access: 'read',
+            handle: ({ url, params }) => provideStore(runtime.replayTo(params.runId, Number(url.searchParams.get('seq') ?? '0')), store).pipe(Effect.map((step) => Response.json({ runId: params.runId, step }))),
+        }),
+        route({
+            method: 'GET',
+            path: '/runs/:runId/status',
+            name: 'runs.status',
+            access: 'read',
+            handle: ({ params }) => provideStore(runtime.inspectRun(params.runId), store).pipe(Effect.map((status) => Response.json(status))),
+        }),
+        route({
+            method: 'GET',
+            path: '/runs/:runId/projections/:projectionName',
+            name: 'runs.projection',
+            access: 'read',
+            handle: ({ params }) => {
+                const definition = runtime.registry.projections.get(params.projectionName);
+                if (!definition) {
+                    return Effect.succeed(Response.json({ error: `Unknown projection: ${params.projectionName}` }, { status: 404 }));
+                }
+                return provideStore(runtime.project(params.runId, definition), store).pipe(Effect.map((value) => Response.json({ runId: params.runId, name: params.projectionName, value })));
+            },
+        }),
+        route({
+            method: 'GET',
+            path: '/runs/:runId/events',
+            name: 'runs.events',
+            access: 'read',
+            handle: ({ req, url, params }) => Effect.gen(function* () {
+                if (wantsEventStream(req, url)) {
+                    return createEventStreamResponse({
+                        signal: req.signal,
+                        request: req,
+                        store,
+                        runId: params.runId,
+                        fromSeq: yield* readEventStreamFromSeq(req, url),
+                    });
+                }
+                const fromSeq = (yield* readIntegerQuery(url, 'fromSeq', { minimum: 1 })) ?? undefined;
+                const limit = (yield* readIntegerQuery(url, 'limit', { minimum: 1 })) ?? undefined;
+                const events = yield* provideStore(runtime.getEvents(params.runId, { fromSeq, limit }), store);
+                return Response.json({ runId: params.runId, events }, { headers: { vary: 'accept' } });
+            }),
+        }),
+        route({
+            method: 'GET',
+            path: '/runs/:runId/threads',
+            name: 'runs.threads',
+            access: 'read',
+            handle: ({ params }) => provideStore(runtime.getRun(params.runId), store).pipe(Effect.map((state) => Response.json({ runId: params.runId, threads: state.threads }))),
+        }),
+        route({
+            method: 'GET',
+            path: '/runs/:runId',
+            name: 'runs.get',
+            access: 'read',
+            handle: ({ params }) => provideStore(runtime.getRun(params.runId), store).pipe(Effect.map((state) => Response.json({ runId: params.runId, state }))),
+        }),
+        route({
+            method: 'POST',
+            path: '/runs/:runId/events',
+            name: 'runs.signal',
+            access: 'write',
+            handle: ({ req, params }) => Effect.gen(function* () {
+                const body = yield* readJson(req).pipe(Effect.flatMap(Schema.decodeUnknownEffect(SignalBodySchema)));
+                const events = body.events ??
+                    (body.type
+                        ? [{ type: body.type, payload: body.payload ?? null, threadId: body.threadId }]
+                        : []);
+                const idempotencyKey = extractIdempotencyKey(req, body.idempotencyKey);
+                const state = yield* provideStore(runtime.signal(params.runId, events, { idempotencyKey }), store);
+                return Response.json({ runId: params.runId, state });
+            }),
+        }),
+        route({
+            method: 'POST',
+            path: '/runs/:runId/wake',
+            name: 'runs.wake',
+            access: 'write',
+            handle: ({ params }) => provideStore(runtime.wake(params.runId), store).pipe(Effect.map((state) => Response.json({ runId: params.runId, state }))),
+        }),
+    ];
+}

package/dist/runtime/server.d.ts

@@ -1,16 +1,12 @@
-import { type EventStore } from '@swirls/looms/core';
-import type { LoomsRuntime } from './runtime';
-export interface FetchHandlerOptions {
-    runtime: LoomsRuntime;
-    store: EventStore;
-}
+export { createFetchHandler, handlesPath, type FetchHandlerOptions } from './server/fetch-handler';
+export { isLoomsApiPath } from './server/http';
+export { mountDebugger, type DebuggerMount } from './server/debugger-host';
+export { authAllowed, authDenied, bearerAuth, defaultAuthorize, type AuthDecision, type AuthorizedAccess, type Authorize, type BearerTokens, type RouteAccess, type RouteInfo, } from './server/auth';
 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;

package/dist/runtime/server.js

@@ -1,208 +1,7 @@
-import { Effect, Schema } from 'effect';
-import { createRunId, EventStoreTag, InvalidEventError, InvalidInputError, JsonValueSchema, } from '@swirls/looms/core';
-import { handleEventsApi } from './events-api.js';
-import { createEventStreamResponse } from './sse.js';
-const StartRunBodySchema = Schema.Struct({
-    kind: Schema.optional(Schema.String),
-    definitionName: Schema.optional(Schema.String),
-    name: Schema.optional(Schema.String),
-    input: Schema.optional(JsonValueSchema),
-    runId: Schema.optional(Schema.String),
-    idempotencyKey: Schema.optional(Schema.String),
-});
-const SignalBodySchema = Schema.Struct({
-    events: Schema.optional(Schema.Array(Schema.Struct({
-        type: Schema.String,
-        payload: JsonValueSchema,
-        threadId: Schema.optional(Schema.NullOr(Schema.String)),
-    }))),
-    type: Schema.optional(Schema.String),
-    payload: Schema.optional(JsonValueSchema),
-    threadId: Schema.optional(Schema.NullOr(Schema.String)),
-    idempotencyKey: Schema.optional(Schema.String),
-});
-function extractIdempotencyKey(req, bodyKey) {
-    return (bodyKey ??
-        req.headers.get('idempotency-key') ??
-        req.headers.get('x-idempotency-key') ??
-        undefined);
-}
-function run(effect, store) {
-    return Effect.runPromise(Effect.provideService(effect, EventStoreTag, store));
-}
-function wantsRunStream(req, url) {
-    const accept = req.headers.get('accept') ?? '';
-    return url.searchParams.get('stream') === 'true' || accept.includes('text/event-stream');
-}
-function streamStartRun(req, runtime, store, args) {
-    return createEventStreamResponse({
-        signal: req.signal,
-        request: req,
-        store,
-        runId: args.runId,
-        fromSeq: 1,
-        onStart: async (write, close) => {
-            try {
-                const result = await run(runtime.startRun({
-                    kind: args.kind,
-                    definitionName: args.definitionName,
-                    input: args.input,
-                    runId: args.runId,
-                    idempotencyKey: args.idempotencyKey,
-                }), store);
-                write(`event: done\ndata: ${JSON.stringify(result)}\n\n`);
-            }
-            catch (cause) {
-                const error = cause instanceof Error ? cause.message : String(cause);
-                write(`event: error\ndata: ${JSON.stringify({ error })}\n\n`);
-            }
-            finally {
-                close();
-            }
-        },
-    });
-}
-async function readJson(req) {
-    try {
-        const value = await req.json();
-        return Schema.decodeUnknownSync(JsonValueSchema)(value);
-    }
-    catch {
-        return {};
-    }
-}
-export function isLoomsApiPath(path) {
-    return path === '/health' || path.startsWith('/api/events') || path.startsWith('/runs');
-}
-function toErrorResponse(err) {
-    if (err instanceof InvalidInputError || err instanceof InvalidEventError) {
-        return Response.json({ error: err.message, issues: err.issues }, { status: 400 });
-    }
-    return Response.json({ error: err.message }, { status: 500 });
-}
-export function createFetchHandler(options) {
-    const { runtime, store } = options;
-    return async (req) => {
-        const url = new URL(req.url);
-        const path = url.pathname;
-        if (!isLoomsApiPath(path)) {
-            return null;
-        }
-        const accept = req.headers.get('accept') ?? '';
-        if (req.method === 'GET' && accept.includes('text/html') && !path.startsWith('/api/')) {
-            return null;
-        }
-        if (path === '/health') {
-            return Response.json({ ok: true });
-        }
-        if (path.startsWith('/api/events')) {
-            return handleEventsApi(req, runtime, store);
-        }
-        try {
-            if (req.method === 'GET' && path === '/runs') {
-                const runIds = await run(runtime.listRuns(), store);
-                return Response.json({ runIds });
-            }
-            if (req.method === 'POST' && path === '/runs') {
-                const body = Schema.decodeUnknownSync(StartRunBodySchema)(await readJson(req));
-                const definitionName = body.definitionName ?? body.name;
-                const kind = body.kind;
-                if (!definitionName || !kind) {
-                    return Response.json({ error: 'kind and definitionName required' }, { status: 400 });
-                }
-                const runId = body.runId ?? createRunId();
-                const idempotencyKey = extractIdempotencyKey(req, body.idempotencyKey);
-                if (wantsRunStream(req, url)) {
-                    return streamStartRun(req, runtime, store, {
-                        kind,
-                        definitionName,
-                        input: body.input ?? null,
-                        runId,
-                        idempotencyKey,
-                    });
-                }
-                const result = await run(runtime.startRun({
-                    kind,
-                    definitionName,
-                    input: body.input ?? null,
-                    runId,
-                    idempotencyKey,
-                }), store);
-                return Response.json(result);
-            }
-            const replayMatch = path.match(/^\/runs\/([^/]+)\/replay$/);
-            if (req.method === 'GET' && replayMatch) {
-                const runId = decodeURIComponent(replayMatch[1]);
-                const seq = Number(url.searchParams.get('seq') ?? '0');
-                const step = await run(runtime.replayTo(runId, seq), store);
-                return Response.json({ runId, step });
-            }
-            const projectionMatch = path.match(/^\/runs\/([^/]+)\/projections\/([^/]+)$/);
-            if (req.method === 'GET' && projectionMatch) {
-                const runId = decodeURIComponent(projectionMatch[1]);
-                const name = decodeURIComponent(projectionMatch[2]);
-                const definition = runtime.registry.projections.get(name);
-                if (!definition) {
-                    return Response.json({ error: `Unknown projection: ${name}` }, { status: 404 });
-                }
-                const value = await run(runtime.project(runId, definition), store);
-                return Response.json({ runId, name, value });
-            }
-            const eventsMatch = path.match(/^\/runs\/([^/]+)\/events$/);
-            if (req.method === 'POST' && eventsMatch) {
-                const runId = decodeURIComponent(eventsMatch[1]);
-                const body = Schema.decodeUnknownSync(SignalBodySchema)(await readJson(req));
-                const events = body.events ??
-                    (body.type
-                        ? [
-                            {
-                                type: body.type,
-                                payload: body.payload ?? null,
-                                threadId: body.threadId,
-                            },
-                        ]
-                        : []);
-                const idempotencyKey = extractIdempotencyKey(req, body.idempotencyKey);
-                const state = await run(runtime.signal(runId, events, { idempotencyKey }), store);
-                return Response.json({ runId, state });
-            }
-            if (req.method === 'GET' && eventsMatch) {
-                const runId = decodeURIComponent(eventsMatch[1]);
-                const fromSeq = url.searchParams.get('fromSeq')
-                    ? Number(url.searchParams.get('fromSeq'))
-                    : undefined;
-                const limit = url.searchParams.get('limit')
-                    ? Number(url.searchParams.get('limit'))
-                    : undefined;
-                const events = await run(runtime.getEvents(runId, { fromSeq, limit }), store);
-                return Response.json({ runId, events });
-            }
-            const threadsMatch = path.match(/^\/runs\/([^/]+)\/(threads)$/);
-            if (req.method === 'GET' && threadsMatch) {
-                const runId = decodeURIComponent(threadsMatch[1]);
-                const state = await run(runtime.getRun(runId), store);
-                return Response.json({ runId, threads: state.threads });
-            }
-            const wakeMatch = path.match(/^\/runs\/([^/]+)\/wake$/);
-            if (req.method === 'POST' && wakeMatch) {
-                const runId = decodeURIComponent(wakeMatch[1]);
-                const state = await run(runtime.wake(runId), store);
-                return Response.json({ runId, state });
-            }
-            const runMatch = path.match(/^\/runs\/([^/]+)$/);
-            if (req.method === 'GET' && runMatch) {
-                const runId = decodeURIComponent(runMatch[1]);
-                const state = await run(runtime.getRun(runId), store);
-                return Response.json({ runId, state });
-            }
-            return new Response('Not Found', { status: 404 });
-        }
-        catch (rawErr) {
-            const err = rawErr instanceof Error ? rawErr : new Error(String(rawErr));
-            return toErrorResponse(err);
-        }
-    };
-}
+export { createFetchHandler, handlesPath } from './server/fetch-handler.js';
+export { isLoomsApiPath } from './server/http.js';
+export { mountDebugger } from './server/debugger-host.js';
+export { authAllowed, authDenied, bearerAuth, defaultAuthorize, } from './server/auth.js';
 export function serveHttp(fetchHandler, options) {
     const port = options?.port ?? 8787;
     const hostname = options?.hostname ?? '0.0.0.0';
@@ -210,13 +9,9 @@ export function serveHttp(fetchHandler, options) {
         port,
         hostname,
         idleTimeout: 0,
-        async fetch(req, srv) {
+        fetch(req, srv) {
             srv.timeout(req, 0);
-            const result = await fetchHandler(req);
-            if (result === null) {
-                return new Response('Not Found', { status: 404 });
-            }
-            return result;
+            return fetchHandler(req).then((result) => result ?? new Response('Not Found', { status: 404 }));
         },
     });
     return {

package/dist/runtime/sse.d.ts

@@ -1,3 +1,4 @@
+import { Effect } from 'effect';
 import { type EventStore } from '@swirls/looms/core';
 export interface EventStreamOptions {
     signal: AbortSignal;
@@ -5,7 +6,7 @@ export interface EventStreamOptions {
     runId: string;
     fromSeq?: number;
     heartbeatMs?: number;
-    onStart?: (write: (text: string) => void, close: () => void) => Promise<void> | void;
+    onStart?: (write: (text: string) => void, close: () => void) => void | Promise<void> | Effect.Effect<void>;
     request?: Request;
 }
 /**

package/dist/runtime/sse.js

@@ -1,5 +1,5 @@
-import { Effect, Fiber, Stream } from 'effect';
-import { encodeLoomsEvent } from '@swirls/looms/core';
+import { Effect, Fiber, Schedule, Stream } from 'effect';
+import { encodeLoomsEvent, stringifyJson } from '@swirls/looms/core';
 function disableBunSocketTimeout(request) {
     if (!request) {
         return;
@@ -24,19 +24,23 @@ export function createEventStreamResponse(options) {
     const { signal, store, runId, fromSeq = 1, heartbeatMs = 3_000, onStart, request } = options;
     disableBunSocketTimeout(request);
     let closed = false;
-    let heartbeat;
-    let fiber;
+    let heartbeatFiber;
+    let startFiber;
+    let subscriptionFiber;
     let streamController;
     const close = () => {
         if (closed) {
             return;
         }
         closed = true;
-        if (heartbeat !== undefined) {
-            clearInterval(heartbeat);
+        if (heartbeatFiber) {
+            Effect.runFork(Fiber.interrupt(heartbeatFiber));
         }
-        if (fiber) {
-            Effect.runFork(Fiber.interrupt(fiber));
+        if (startFiber) {
+            Effect.runFork(Fiber.interrupt(startFiber));
+        }
+        if (subscriptionFiber) {
+            Effect.runFork(Fiber.interrupt(subscriptionFiber));
         }
         try {
             streamController?.close();
@@ -60,19 +64,21 @@ export function createEventStreamResponse(options) {
                     close();
                 }
             };
-            fiber = Effect.runFork(store.subscribe(runId, { fromSeq }).pipe(Stream.tap((event) => Effect.sync(() => {
-                write(`id: ${event.seq}\ndata: ${JSON.stringify({ batch: [encodeLoomsEvent(event)] })}\n\n`);
+            subscriptionFiber = Effect.runFork(store.subscribe(runId, { fromSeq }).pipe(Stream.tap((event) => Effect.sync(() => {
+                write(`id: ${event.seq}\ndata: ${stringifyJson({ batch: [encodeLoomsEvent(event)] })}\n\n`);
             })), Stream.runDrain));
             // Send an immediate keepalive so bytes and headers flush over the wire immediately,
             // preventing dev server proxies and Bun.serve from aborting quiet connections.
             write(': keepalive\n\n');
-            heartbeat = setInterval(() => write(': keepalive\n\n'), heartbeatMs);
-            if (onStart) {
-                Promise.resolve(onStart(write, close)).catch((cause) => {
-                    const error = cause instanceof Error ? cause.message : String(cause);
-                    write(`event: error\ndata: ${JSON.stringify({ error })}\n\n`);
-                    close();
-                });
+            heartbeatFiber = Effect.runFork(Effect.repeat(Effect.sleep(heartbeatMs).pipe(Effect.andThen(Effect.sync(() => write(': keepalive\n\n')))), Schedule.forever).pipe(Effect.asVoid));
+            const startResult = onStart?.(write, close);
+            const startEffect = Effect.isEffect(startResult)
+                ? startResult
+                : startResult
+                    ? Effect.promise(() => startResult)
+                    : undefined;
+            if (startEffect) {
+                startFiber = Effect.runFork(startEffect);
             }
             if (signal.aborted) {
                 close();
@@ -90,6 +96,7 @@ export function createEventStreamResponse(options) {
             'content-type': 'text/event-stream',
             'cache-control': 'no-cache, no-transform',
             connection: 'keep-alive',
+            vary: 'accept',
             'x-accel-buffering': 'no',
         },
     });

package/dist/runtime/types.d.ts

@@ -0,0 +1,117 @@
+import type { Effect } from 'effect';
+import type { AnyRuntimeModule, ComposedRegistry, EventEnvelope, EventInput, WorkerCallbackInput, EventStore, EventStoreAppendError, EventStoreError, EventStoreFencedError, EventStoreTag, EventStoreTrimCoverage, EventStoreTruncationError, JsonValue, ProjectionDefinition, ReplayStep, RunState, RunSummary, SnapshotStore, SnapshotStoreError } from '@swirls/looms/core';
+import type { EventStoreTrimmedError } from '@swirls/looms/core';
+import type { DuplicateEffectDispatchError, MaxWakeIterationsError } from './errors';
+import type { RuntimeObserver } from './observer';
+import type { WakeScheduler } from './wake-scheduler';
+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;
+    /** Maximum active and queued mutation operations per run. Default 256. */
+    readonly maxPendingRunOperations?: 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;
+        /**
+         * Required proof that history remains rebuildable. Trimming is rejected
+         * unless an archive covers the cut or every configured projector checkpoint does.
+         */
+        coverage?: (runId: string) => EventStoreTrimCoverage | Promise<EventStoreTrimCoverage>;
+    };
+    /**
+     * 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 Effect fiber scheduler.
+     */
+    readonly scheduler?: WakeScheduler;
+    readonly worker?: EffectWorker;
+    /** Failure-isolated, framework-neutral operational event sink. */
+    readonly observer?: RuntimeObserver;
+}
+export interface EffectWorkerTask {
+    readonly runId: string;
+    readonly effectId: string;
+    readonly attempt: number;
+    readonly type: string;
+    readonly input: JsonValue;
+}
+export interface EffectWorker {
+    /** Effect types this worker claims, even when a local handler exists. */
+    readonly handles?: ReadonlyArray<string> | ((type: string) => boolean);
+    /** Per-task claim, checked with attempt 0 before the runtime assigns an attempt. */
+    readonly canDispatch?: (task: EffectWorkerTask) => boolean;
+    dispatch(task: EffectWorkerTask): void | Promise<void>;
+    cancel?(task: EffectWorkerTask): void | Promise<void>;
+}
+export interface StartRunArgs {
+    kind: string;
+    definitionName: string;
+    definitionVersion?: string;
+    input?: JsonValue;
+    runId?: string;
+    threadId?: string;
+    idempotencyKey?: string;
+}
+export interface StartResult {
+    runId: string;
+    threadId: string;
+    state: RunState;
+}
+export interface RunOperationalStatus {
+    readonly runId: string;
+    readonly state: RunState;
+    readonly head: number;
+    readonly tail: number;
+    readonly effects: ReadonlyArray<{
+        readonly effectId: string;
+        readonly threadId: string;
+        readonly type: string;
+        readonly attempt: number;
+        readonly status: string;
+        readonly deadlineAt: number | null;
+        readonly lastError: string | null;
+    }>;
+}
+export interface LoomsRuntime<TModules extends readonly AnyRuntimeModule[] = readonly AnyRuntimeModule[]> {
+    readonly modules: TModules;
+    readonly registry: ComposedRegistry;
+    startRun(args: StartRunArgs): Effect.Effect<StartResult, Error | EventStoreAppendError | EventStoreError, EventStoreTag>;
+    signal(runId: string, events: ReadonlyArray<EventInput>, options?: {
+        idempotencyKey?: string;
+    }): Effect.Effect<RunState, Error | EventStoreAppendError | 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>;
+    inspectRun(runId: string): Effect.Effect<RunOperationalStatus, EventStoreError | EventStoreTrimmedError | EventStoreTruncationError, EventStoreTag>;
+    retryEffect(runId: string, effectId: string): Effect.Effect<RunState, Error | EventStoreAppendError | EventStoreError, EventStoreTag>;
+    cancel(runId: string, threadId?: string): Effect.Effect<RunState, Error | EventStoreAppendError | EventStoreError, EventStoreTag>;
+    /** Applies a worker's report about one effect attempt; stale or foreign reports are ignored. */
+    workerCallback(runId: string, input: WorkerCallbackInput): Effect.Effect<RunState, Error | EventStoreAppendError | EventStoreError, EventStoreTag>;
+    readonly listRuns: Effect.Effect<string[], EventStoreError, EventStoreTag>;
+    /** Indexed run rows. Folds a run only when its header has not been written yet. */
+    readonly listRunSummaries: Effect.Effect<readonly RunSummary[], EventStoreError | EventStoreTrimmedError | EventStoreTruncationError | SnapshotStoreError, EventStoreTag>;
+    readonly rescanTimers: Effect.Effect<number, EventStoreTruncationError | EventStoreTrimmedError | EventStoreError, EventStoreTag>;
+    /** Reschedule every durable timer and effect deadline after restart or repair. */
+    readonly recoverDeadlines: Effect.Effect<number, EventStoreTruncationError | EventStoreTrimmedError | EventStoreError, EventStoreTag>;
+    readonly dispose: Effect.Effect<void>;
+}

package/dist/runtime/types.js

@@ -0,0 +1 @@
+export {};