@swirls/looms 0.1.0 → 0.3.0

package/dist/runtime/looms.js

@@ -1,7 +1,7 @@
 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 { createFetchHandler, handlesPath, mountDebugger, serveHttp, } from './server.js';
 class LoomsInitializationError extends Data.TaggedError('LoomsInitializationError') {
     constructor(cause) {
         super({
@@ -13,6 +13,7 @@ class LoomsInitializationError extends Data.TaggedError('LoomsInitializationErro
 }
 export function createLooms(options = {}) {
     const modules = options.modules ?? [];
+    const debuggerMount = options.debugger ? mountDebugger(options.debugger) : undefined;
     let initPromise;
     let runningServer;
     const getInit = () => {
@@ -52,6 +53,7 @@ export function createLooms(options = {}) {
                     runtime,
                     store,
                     authorize: options.authorize,
+                    debugger: debuggerMount,
                 });
                 return { runtime, store, snapshotStore: snapshotStoreOf(store), fetchHandler };
             }));
@@ -96,9 +98,10 @@ export function createLooms(options = {}) {
         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)),
+        fork: (sourceRunId, forkOpts) => runEffect((i) => i.runtime.fork(sourceRunId, forkOpts)),
         workerCallback: (runId, input) => runEffect((i) => i.runtime.workerCallback(runId, input)),
         fetch: (req) => {
-            if (!isLoomsApiPath(new URL(req.url).pathname)) {
+            if (!handlesPath(new URL(req.url).pathname, debuggerMount)) {
                 return Promise.resolve(null);
             }
             return getInit().then(({ fetchHandler }) => fetchHandler(req));

package/dist/runtime/repository.js

@@ -1,5 +1,5 @@
 import { Clock, Data, Effect, Option } from 'effect';
-import { advanceCursor, assignSequences, createCoalescingAppender, emptyCursor, EventStoreTrimmedError, hashRunState, trimEventStoreSafely, } from '@swirls/looms/core';
+import { advanceCursor, assignSequences, createCoalescingAppender, emptyCursor, EventStoreTrimmedError, hashRunState, summarizeRun, trimEventStoreSafely, } from '@swirls/looms/core';
 import { RuntimeExecutionError } from './errors.js';
 import { stripSeq } from './helpers.js';
 import { notifyObserver } from './observer.js';
@@ -36,7 +36,18 @@ function readRemaining(store, runId, events, expectedTail) {
 }
 export function createRuntimeRepository(options) {
     const { registry, snapshotStore, trimAfterSnapshot, keepSnapshots, runCache, executionContexts } = options;
+    const headerFingerprints = new Map();
     const observe = (event) => notifyObserver(options.observer, event);
+    const rememberHeader = (state) => {
+        const header = summarizeRun(state);
+        const fingerprint = `${header.status}\0${header.kind ?? ''}\0${header.definitionName ?? ''}`;
+        if (headerFingerprints.get(header.runId) === fingerprint) {
+            return Effect.void;
+        }
+        return snapshotStore.saveHeader(header).pipe(Effect.tap(() => Effect.sync(() => {
+            headerFingerprints.set(header.runId, fingerprint);
+        })), Effect.catch((error) => Effect.logWarning(`Run header persistence failed for "${header.runId}"`, error)));
+    };
     const appendObserved = (store, runId, events, appendOptions) => Effect.suspend(() => {
         const startedAt = currentTimeMillis();
         return store.append(runId, events, appendOptions).pipe(Effect.tap(() => Effect.sync(() => observe({
@@ -156,6 +167,7 @@ export function createRuntimeRepository(options) {
                 return yield* loadCursorCold(store, runId);
             }
             if (tail === cached.seq) {
+                yield* rememberHeader(cached.state);
                 return cached;
             }
             const next = yield* catchUp(store, runId, cached, tail).pipe(Effect.catchTag('EventStoreTrimmedError', () => {
@@ -163,10 +175,12 @@ export function createRuntimeRepository(options) {
                 return loadCursorCold(store, runId);
             }));
             runCache.set(runId, next);
+            yield* rememberHeader(next.state);
             return next;
         }
         const next = yield* loadCursorCold(store, runId);
         runCache.set(runId, next);
+        yield* rememberHeader(next.state);
         return next;
     });
     /**
@@ -241,6 +255,7 @@ export function createRuntimeRepository(options) {
             next = yield* catchUp(store, runId, next, appendResult.tail);
         }
         runCache.set(runId, next);
+        yield* rememberHeader(next.state);
         return next;
     });
     /**

package/dist/runtime/run-start.js

@@ -5,9 +5,7 @@ function canonicalJson(value) {
         return `[${value.map(canonicalJson).join(',')}]`;
     }
     if (Predicate.isObject(value)) {
-        const keys = Object.keys(value);
-        // oxlint-disable-next-line unicorn/no-array-sort
-        keys.sort();
+        const keys = Object.keys(value).toSorted();
         return `{${keys
             .map((key) => `${JSON.stringify(key)}:${canonicalJson(value[key] ?? null)}`)
             .join(',')}}`;

package/dist/runtime/runtime.d.ts

@@ -2,7 +2,7 @@ import { type AnyRuntimeModule } from '@swirls/looms/core';
 export type { RegisteredDefinition } from '@swirls/looms/core';
 export type { WakeScheduler } from './wake-scheduler';
 export { createTimeoutScheduler } from './wake-scheduler';
-export { DuplicateEffectDispatchError, MaxWakeIterationsError, StartRunConflictError, } from './errors';
+export { DuplicateEffectDispatchError, ForkConflictError, MaxWakeIterationsError, RunNotFinishedError, RunNotFoundError, RunTerminalError, StartRunConflictError, } from './errors';
 export { RunOverloadedError } from './ingress';
 export type { CreateRuntimeOptions, EffectWorker, EffectWorkerTask, LoomsRuntime, RunOperationalStatus, StartResult, StartRunArgs, WakeError, } from './types';
 export type { WorkerCallback, WorkerCallbackInput } from '@swirls/looms/core';

package/dist/runtime/runtime.js

@@ -1,8 +1,8 @@
 import { Clock, Effect, ManagedRuntime, Predicate } from 'effect';
-import { composeModules, createEvent, createThreadId, createRunId, DEFAULT_DEFINITION_VERSION, DEFAULT_SNAPSHOT_EVERY, definitionKey, EventStoreTag, foldRun, project, replayTo, } from '@swirls/looms/core';
+import { composeModules, createEvent, createThreadId, createRunId, DEFAULT_DEFINITION_VERSION, DEFAULT_SNAPSHOT_EVERY, definitionKey, descendantThreadIds, EventStoreTag, foldRun, isRunTerminal, planFork, 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 { ForkConflictError, RunNotFinishedError, RunNotFoundError, RunTerminalError, 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';
@@ -13,26 +13,21 @@ 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 { DuplicateEffectDispatchError, MaxWakeIterationsError, StartRunConflictError, } from './errors.js';
+export { DuplicateEffectDispatchError, ForkConflictError, MaxWakeIterationsError, RunNotFinishedError, RunNotFoundError, RunTerminalError, StartRunConflictError, } from './errors.js';
 export { RunOverloadedError } from './ingress.js';
 function currentTimeMillis() {
     return Math.floor(performance.timeOrigin + performance.now());
 }
-/** Threads whose in-process effects an admitted signal interrupts. */
-function interruptedThreadIds(events, rules) {
-    const threadIds = new Set();
-    for (const event of events) {
+/** Threads whose in-process effects an admitted signal interrupts: each named one and its subtree. */
+function interruptedThreadIds(events, rules, state) {
+    const named = events.flatMap((event) => {
         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 cancelled = event.type === 'runtime.thread.cancel.requested' && Predicate.isString(payload.threadId)
+            ? [payload.threadId]
+            : [];
+        return [...cancelled, ...rules.flatMap((rule) => rule(event))];
+    });
+    return new Set(named.flatMap((threadId) => [threadId, ...descendantThreadIds(state, threadId)]));
 }
 const DEFAULT_RUN_CACHE_SIZE = 0;
 const RESCAN_CONCURRENCY = 16;
@@ -83,6 +78,9 @@ export function createRuntime(options) {
                 ...input,
                 idempotencyKey: input.idempotencyKey ?? signalKey,
             })), { origin: { type: 'external' } });
+            if (isRunTerminal(current.state)) {
+                return yield* new RunTerminalError(runId, current.state.status);
+            }
             const folded = foldRun(batch, registry, { runId, initial: current.state });
             const satisfiedEvents = waitSatisfiedEvents(folded, batch).map((input) => createEvent(runId, input));
             return {
@@ -92,7 +90,7 @@ export function createRuntime(options) {
             };
         }));
         if (committed.append) {
-            executionContexts.abort(runId, interruptedThreadIds(events, registry.interruptRules), 'Effect interrupted');
+            executionContexts.abort(runId, interruptedThreadIds(events, registry.interruptRules, committed.value), 'Effect interrupted');
         }
         return committed.value;
     });
@@ -134,6 +132,21 @@ export function createRuntime(options) {
             const store = yield* EventStoreTag;
             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;
             return yield* store.read(runId, readOptions);
@@ -280,6 +293,35 @@ export function createRuntime(options) {
         },
         signal: (runId, events, signalOpts) => admitExternalEvents(events).pipe(Effect.flatMap((admitted) => withRunIngress(runId, signalAdmitted(runId, admitted, signalOpts))), Effect.andThen(runtime.wake(runId))),
         cancel: cancellation,
+        fork: (sourceRunId, forkOptions) => {
+            const runId = forkOptions?.runId ?? createRunId();
+            return withRunIngress(runId, Effect.gen(function* () {
+                const store = yield* EventStoreTag;
+                const source = yield* loadCursor(store, sourceRunId);
+                if (source.seq === 0) {
+                    return yield* new RunNotFoundError(sourceRunId);
+                }
+                if (!isRunTerminal(source.state)) {
+                    return yield* new RunNotFinishedError(sourceRunId, source.state.status);
+                }
+                const plan = yield* planFork({
+                    sourceRunId,
+                    runId,
+                    events: yield* store.read(sourceRunId),
+                    registry,
+                });
+                // Appending at tail 0 numbers the copied events 1..n, the seqs they had in the source.
+                yield* commit(store, runId, (existing) => {
+                    if (existing.seq === 0) {
+                        return Effect.succeed({ events: plan.events, value: undefined });
+                    }
+                    return existing.state.forkedFrom?.runId === sourceRunId
+                        ? Effect.succeed({ events: [], value: undefined })
+                        : Effect.fail(new ForkConflictError(runId, sourceRunId));
+                });
+                return plan.rootThreadId;
+            })).pipe(Effect.flatMap((threadId) => runtime.wake(runId).pipe(Effect.map((state) => ({ runId, threadId, state })))));
+        },
         wake: wakeEngine,
         dispose: Effect.sync(() => scheduler.dispose?.()).pipe(Effect.andThen(services.disposeEffect)),
     };

package/dist/runtime/server/auth.d.ts

@@ -22,6 +22,7 @@ export type AuthDecision = {
 export type Authorize = (request: Request, route: RouteInfo) => Effect.Effect<AuthDecision>;
 export declare const authAllowed: AuthDecision;
 export declare function authDenied(status: number, error: string): AuthDecision;
+export declare function authResponse(decision: AuthDecision): Response | null;
 /**
  * Used when a host supplies no `authorize`: run reads and writes stay open, while worker callbacks
  * and operational endpoints are unavailable until a host opts in.

package/dist/runtime/server/auth.js

@@ -3,6 +3,11 @@ export const authAllowed = { allowed: true };
 export function authDenied(status, error) {
     return { allowed: false, status, error };
 }
+export function authResponse(decision) {
+    return decision.allowed
+        ? null
+        : Response.json({ error: decision.error }, { status: decision.status });
+}
 const unauthorized = authDenied(401, 'Unauthorized');
 function notConfigured(access) {
     return authDenied(503, access === 'worker'

package/dist/runtime/server/debugger-host.d.ts

@@ -0,0 +1,11 @@
+import { Effect } from 'effect';
+import type { DebuggerHost } from '@swirls/looms/core';
+import { type Authorize } from './auth';
+export interface DebuggerMount {
+    readonly basePath: string;
+    readonly host: DebuggerHost;
+}
+export declare function mountDebugger(host: DebuggerHost): DebuggerMount;
+/** Path below the mount, or null when `pathname` is outside it. */
+export declare function debuggerPath(mount: DebuggerMount, pathname: string): string | null;
+export declare function serveDebugger(req: Request, mount: DebuggerMount, path: string, authorize: Authorize): Effect.Effect<Response | null>;

package/dist/runtime/server/debugger-host.js

@@ -0,0 +1,32 @@
+import { Effect } from 'effect';
+import { authResponse } from './auth.js';
+import { isLoomsApiPath } from './http.js';
+export function mountDebugger(host) {
+    const path = host.basePath;
+    if (!path.startsWith('/') || path.includes('//') || path.split('/').includes('..')) {
+        throw new Error(`debugger basePath must be an absolute URL path: ${path}`);
+    }
+    const basePath = path.endsWith('/') ? path.slice(0, -1) : path;
+    if (basePath === '') {
+        throw new Error('debugger basePath must not be /');
+    }
+    if (isLoomsApiPath(basePath)) {
+        throw new Error(`debugger basePath overlaps the HTTP API: ${basePath}`);
+    }
+    return { basePath, host };
+}
+/** Path below the mount, or null when `pathname` is outside it. */
+export function debuggerPath(mount, pathname) {
+    if (pathname === mount.basePath) {
+        return '';
+    }
+    return pathname.startsWith(`${mount.basePath}/`) ? pathname.slice(mount.basePath.length) : null;
+}
+export function serveDebugger(req, mount, path, authorize) {
+    return authorize(req, { access: 'read', name: 'debugger' }).pipe(Effect.flatMap((decision) => {
+        const denied = authResponse(decision);
+        return denied
+            ? Effect.succeed(denied)
+            : Effect.promise(() => mount.host.fetch(req, { basePath: mount.basePath, path }));
+    }));
+}

package/dist/runtime/server/fetch-handler.d.ts

@@ -1,6 +1,7 @@
 import type { EventStore } from '@swirls/looms/core';
 import type { LoomsRuntime } from '../runtime';
 import { type Authorize } from './auth';
+import { type DebuggerMount } from './debugger-host';
 export interface FetchHandlerOptions {
     readonly runtime: LoomsRuntime;
     readonly store: EventStore;
@@ -9,6 +10,9 @@ export interface FetchHandlerOptions {
      * operations routes unavailable; use `bearerAuth` or your own policy to change that.
      */
     readonly authorize?: Authorize;
+    /** Debugger UI served beside the API and authorized as `{ access: 'read', name: 'debugger' }`. */
+    readonly debugger?: DebuggerMount;
 }
-export declare function isLoomsApiPath(path: string): boolean;
+/** Whether the fetch handler answers `pathname`: the HTTP API or the debugger mount. */
+export declare function handlesPath(pathname: string, mount: DebuggerMount | undefined): boolean;
 export declare function createFetchHandler(options: FetchHandlerOptions): (req: Request) => Promise<Response | null>;

package/dist/runtime/server/fetch-handler.js

@@ -1,12 +1,19 @@
 import { Effect, Predicate } from 'effect';
-import { defaultAuthorize } from './auth.js';
-import { acceptsEventStream, toErrorResponse } from './http.js';
+import { authResponse, defaultAuthorize } from './auth.js';
+import { debuggerPath, serveDebugger } from './debugger-host.js';
+import { acceptsEventStream, isLoomsApiPath, toErrorResponse } from './http.js';
 import { matchRoute } from './route-table.js';
+import { definitionRoutes } from './routes/definitions.js';
 import { effectRoutes } from './routes/effects.js';
 import { operationRoutes } from './routes/operations.js';
 import { runRoutes } from './routes/runs.js';
 function createRoutes(options) {
-    return [...runRoutes(options), ...effectRoutes(options), ...operationRoutes(options)];
+    return [
+        ...definitionRoutes(options),
+        ...runRoutes(options),
+        ...effectRoutes(options),
+        ...operationRoutes(options),
+    ];
 }
 function authorizeRoute(req, matched, authorize) {
     const { access, name } = matched.route;
@@ -14,21 +21,22 @@ function authorizeRoute(req, matched, authorize) {
         return Effect.succeed(null);
     }
     const runId = matched.params.runId;
-    return authorize(req, Predicate.isString(runId) ? { access, name, runId } : { access, name }).pipe(Effect.map((decision) => decision.allowed
-        ? null
-        : Response.json({ error: decision.error }, { status: decision.status })));
+    return authorize(req, Predicate.isString(runId) ? { access, name, runId } : { access, name }).pipe(Effect.map(authResponse));
 }
-export function isLoomsApiPath(path) {
-    return (path === '/health' ||
-        path === '/runs' ||
-        path.startsWith('/runs/') ||
-        path.startsWith('/operations/'));
+/** Whether the fetch handler answers `pathname`: the HTTP API or the debugger mount. */
+export function handlesPath(pathname, mount) {
+    return isLoomsApiPath(pathname) || (mount !== undefined && debuggerPath(mount, pathname) !== null);
 }
 export function createFetchHandler(options) {
     const routes = createRoutes(options);
     const authorize = options.authorize ?? defaultAuthorize;
+    const mount = options.debugger;
     return (req) => {
         const url = new URL(req.url);
+        const mountedPath = mount ? debuggerPath(mount, url.pathname) : null;
+        if (mount && mountedPath !== null) {
+            return respond(serveDebugger(req, mount, mountedPath, authorize));
+        }
         if (!isLoomsApiPath(url.pathname)) {
             return Promise.resolve(null);
         }
@@ -36,7 +44,7 @@ export function createFetchHandler(options) {
         if (req.method === 'GET' && accept.includes('text/html') && !acceptsEventStream(req)) {
             return Promise.resolve(null);
         }
-        return Effect.runPromise(Effect.gen(function* () {
+        return respond(Effect.gen(function* () {
             const matched = matchRoute(routes, req.method, url.pathname);
             if (!matched) {
                 return new Response('Not Found', { status: 404 });
@@ -46,6 +54,9 @@ export function createFetchHandler(options) {
                 return denied;
             }
             return yield* matched.route.handle({ req, url, params: matched.params });
-        }).pipe(Effect.catch((error) => Effect.succeed(toErrorResponse(error))), Effect.catchCause((cause) => Effect.logError('[@swirls/looms/runtime] request failed', cause).pipe(Effect.as(Response.json({ error: 'Internal server error' }, { status: 500 }))))));
+        }));
     };
 }
+function respond(effect) {
+    return Effect.runPromise(effect.pipe(Effect.catch((error) => Effect.succeed(toErrorResponse(error))), Effect.catchCause((cause) => Effect.logError('[@swirls/looms/runtime] request failed', cause).pipe(Effect.as(Response.json({ error: 'Internal server error' }, { status: 500 }))))));
+}

package/dist/runtime/server/http.d.ts

@@ -26,8 +26,11 @@ export declare const EventInputBodySchema: Schema.Struct<{
     readonly payload: Schema.Codec<Schema.Json, Schema.Json, never, never>;
     readonly threadId: Schema.optional<Schema.NullOr<Schema.String>>;
 }>;
+export declare function isLoomsApiPath(path: string): boolean;
 export declare function provideStore<A, E>(effect: Effect.Effect<A, E, EventStoreTag>, store: EventStore): Effect.Effect<A, E>;
 export declare const readJson: (req: Request) => Effect.Effect<JsonValue, RequestBodyError>;
+/** `readJson` for routes whose body is optional: a request without one reads as `{}`. */
+export declare const readOptionalJson: (req: Request) => Effect.Effect<JsonValue, RequestBodyError>;
 export declare function extractIdempotencyKey(req: Request, bodyKey?: string): string | undefined;
 export declare function acceptsEventStream(req: Request): boolean;
 export declare function readIntegerQuery(url: URL, name: string, options: {

package/dist/runtime/server/http.js

@@ -1,6 +1,6 @@
 import { Data, Effect, Schema } from 'effect';
-import { EventStoreTag, InvalidEventError, InvalidInputError, JsonValueSchema, } from '@swirls/looms/core';
-import { RunOverloadedError, StartRunConflictError } from '../runtime.js';
+import { EventStoreTag, ForkSourceError, InvalidEventError, InvalidInputError, JsonValueSchema, } from '@swirls/looms/core';
+import { ForkConflictError, RunNotFinishedError, RunNotFoundError, RunOverloadedError, RunTerminalError, StartRunConflictError, } from '../runtime.js';
 export class RequestBodyError extends Data.TaggedError('RequestBodyError') {
     constructor(cause) {
         super({ cause, message: 'Invalid JSON request body' });
@@ -14,6 +14,10 @@ export const EventInputBodySchema = Schema.Struct({
     payload: JsonValueSchema,
     threadId: Schema.optional(Schema.NullOr(Schema.String)),
 });
+const LOOMS_API_ROOTS = ['/health', '/runs', '/definitions', '/operations'];
+export function isLoomsApiPath(path) {
+    return LOOMS_API_ROOTS.some((root) => path === root || path.startsWith(`${root}/`));
+}
 export function provideStore(effect, store) {
     return Effect.provideService(effect, EventStoreTag, store);
 }
@@ -21,6 +25,10 @@ export const readJson = (req) => Effect.tryPromise({
     try: () => req.json(),
     catch: (cause) => new RequestBodyError(cause),
 }).pipe(Effect.flatMap(Schema.decodeUnknownEffect(JsonValueSchema)), Effect.mapError((cause) => cause instanceof RequestBodyError ? cause : new RequestBodyError(cause)));
+/** `readJson` for routes whose body is optional: a request without one reads as `{}`. */
+export const readOptionalJson = (req) => req.body === null || req.headers.get('content-length') === '0'
+    ? Effect.succeed({})
+    : readJson(req);
 export function extractIdempotencyKey(req, bodyKey) {
     return (bodyKey ??
         req.headers.get('idempotency-key') ??
@@ -55,8 +63,19 @@ export function toErrorResponse(err) {
     if (err instanceof RunOverloadedError) {
         return Response.json({ error: err.message }, { status: 429 });
     }
+    if (err instanceof RunNotFoundError) {
+        return Response.json({ error: err.message }, { status: 404 });
+    }
+    if (err instanceof RunTerminalError) {
+        return Response.json({ error: err.message, status: err.status }, { status: 409 });
+    }
     if (err instanceof StartRunConflictError) {
         return Response.json({ error: err.message, mismatches: err.mismatches }, { status: 409 });
     }
+    if (err instanceof RunNotFinishedError ||
+        err instanceof ForkConflictError ||
+        err instanceof ForkSourceError) {
+        return Response.json({ error: err.message }, { status: 409 });
+    }
     return Response.json({ error: err.message }, { status: 500 });
 }

package/dist/runtime/server/routes/definitions.d.ts

@@ -0,0 +1,3 @@
+import type { RouteOptions } from '../http';
+import { type Route } from '../route-table';
+export declare function definitionRoutes({ runtime }: RouteOptions): readonly Route[];

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

@@ -0,0 +1,20 @@
+import { Effect } from 'effect';
+import { publishDefinition } from '@swirls/looms/core';
+import { route } from '../route-table.js';
+export function definitionRoutes({ runtime }) {
+    return [
+        route({
+            method: 'GET',
+            path: '/definitions',
+            name: 'definitions.list',
+            access: 'read',
+            handle: () => {
+                const catalog = {
+                    definitions: runtime.registry.definitions.map(publishDefinition),
+                    projections: [...runtime.registry.projections.keys()],
+                };
+                return Effect.succeed(Response.json(catalog));
+            },
+        }),
+    ];
+}

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

@@ -1,7 +1,7 @@
 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 { acceptsEventStream, EventInputBodySchema, extractIdempotencyKey, provideStore, readIntegerQuery, readJson, readOptionalJson, RequestQueryError, } from '../http.js';
 import { route } from '../route-table.js';
 const StartRunBodySchema = Schema.Struct({
     kind: Schema.optional(Schema.String),
@@ -19,6 +19,12 @@ const SignalBodySchema = Schema.Struct({
     threadId: Schema.optional(Schema.NullOr(Schema.String)),
     idempotencyKey: Schema.optional(Schema.String),
 });
+const CancelBodySchema = Schema.Struct({
+    threadId: Schema.optional(Schema.String),
+});
+const ForkBodySchema = Schema.Struct({
+    runId: Schema.optional(Schema.String),
+});
 function wantsRunStream(req, url) {
     return url.searchParams.get('stream') === 'true' || acceptsEventStream(req);
 }
@@ -72,7 +78,14 @@ export function runRoutes({ runtime, store }) {
             path: '/runs',
             name: 'runs.list',
             access: 'read',
-            handle: () => provideStore(runtime.listRuns, store).pipe(Effect.map((runIds) => Response.json({ runIds }))),
+            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',
@@ -186,7 +199,34 @@ export function runRoutes({ runtime, store }) {
             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 }))),
+            handle: ({ params }) => Effect.gen(function* () {
+                const before = yield* store.tail(params.runId);
+                const state = yield* provideStore(runtime.wake(params.runId), store);
+                const appended = (yield* store.tail(params.runId)) - before;
+                return Response.json({ runId: params.runId, state, appended });
+            }),
+        }),
+        route({
+            method: 'POST',
+            path: '/runs/:runId/cancel',
+            name: 'runs.cancel',
+            access: 'write',
+            handle: ({ req, params }) => Effect.gen(function* () {
+                const body = yield* readOptionalJson(req).pipe(Effect.flatMap(Schema.decodeUnknownEffect(CancelBodySchema)));
+                const state = yield* provideStore(runtime.cancel(params.runId, body.threadId), store);
+                return Response.json({ runId: params.runId, state });
+            }),
+        }),
+        route({
+            method: 'POST',
+            path: '/runs/:runId/fork',
+            name: 'runs.fork',
+            access: 'write',
+            handle: ({ req, params }) => Effect.gen(function* () {
+                const body = yield* readOptionalJson(req).pipe(Effect.flatMap(Schema.decodeUnknownEffect(ForkBodySchema)));
+                const result = yield* provideStore(runtime.fork(params.runId, { runId: body.runId }), store);
+                return Response.json(result);
+            }),
         }),
     ];
 }

package/dist/runtime/server.d.ts

@@ -1,4 +1,6 @@
-export { createFetchHandler, isLoomsApiPath, type FetchHandlerOptions, } from './server/fetch-handler';
+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;

package/dist/runtime/server.js

@@ -1,4 +1,6 @@
-export { createFetchHandler, isLoomsApiPath, } from './server/fetch-handler.js';
+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;

package/dist/runtime/types.d.ts

@@ -1,5 +1,5 @@
 import type { Effect } from 'effect';
-import type { AnyRuntimeModule, ComposedRegistry, EventEnvelope, EventInput, WorkerCallbackInput, EventStore, EventStoreAppendError, EventStoreError, EventStoreFencedError, EventStoreTag, EventStoreTrimCoverage, EventStoreTruncationError, JsonValue, ProjectionDefinition, ReplayStep, RunState, SnapshotStore } from '@swirls/looms/core';
+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';
@@ -105,9 +105,19 @@ export interface LoomsRuntime<TModules extends readonly AnyRuntimeModule[] = rea
     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>;
+    /**
+     * Start a new run that continues where a finished run ended. The fork copies the source's
+     * history up to the point it finished and re-issues the effects outstanding there. Retrying
+     * with the same `runId` returns the existing fork.
+     */
+    fork(sourceRunId: string, options?: {
+        runId?: string;
+    }): Effect.Effect<StartResult, 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>;

package/dist/runtime/wake-engine.js

@@ -2,7 +2,7 @@ import { Clock, Effect, Exit, Option } from 'effect';
 import { createEvent, EventStoreTag, foldRun, isRunTerminal, } from '@swirls/looms/core';
 import { nextRuntimeDeadline, planDeadlineTransitions, planTerminalCancellationTransitions, } from './deadline-transition-planner.js';
 import { DuplicateEffectDispatchError, MaxWakeIterationsError, RuntimeExecutionError, } from './errors.js';
-import { stripSeq, synthesizedThreadFailed, waitSatisfiedEvents } from './helpers.js';
+import { cascadedCancellations, stripSeq, synthesizedThreadFailed, waitSatisfiedEvents, } from './helpers.js';
 import { executeLocalEffects } from './local-effect-executor.js';
 import { notifyObserver } from './observer.js';
 import { dispatchWorkerEffect, isWorkerEffect, planWorkerEffects } from './worker-effect-dispatch.js';
@@ -225,7 +225,10 @@ export function createWakeEngine(options) {
                     yield* liveAppends.drain(runId);
                     const beforeFold = cursor.state;
                     const intermediateState = foldRun(produced, registry, { runId, initial: beforeFold });
-                    const synthesized = synthesizedThreadFailed(beforeFold, intermediateState, produced);
+                    const synthesized = [
+                        ...synthesizedThreadFailed(beforeFold, intermediateState, produced),
+                        ...cascadedCancellations(intermediateState, produced),
+                    ];
                     const synthesizedEvents = synthesized.map((input) => createEvent(runId, input));
                     const stateAfterSynth = synthesizedEvents.length > 0
                         ? foldRun(synthesizedEvents, registry, { runId, initial: intermediateState })