@swirls/looms 0.0.2 → 0.2.0

package/dist/runtime/dispatch-effect.js

@@ -1,6 +1,6 @@
-import { Effect, Schedule } from 'effect';
+import { Effect } from 'effect';
 import { asJson, isPrimitiveEffect, isWaitOnTimer, } from '@swirls/looms/core';
-import { threadStartedEvents } from './runtime-helpers.js';
+import { threadStartedEvents } from './helpers.js';
 export function dispatchEffect(registry, services, definitions, effect, ctx) {
     const currentThreadId = ctx.threadId;
     const baseDispatch = (eff, effCtx) => {
@@ -11,6 +11,7 @@ export function dispatchEffect(registry, services, definitions, effect, ctx) {
                     return threadStartedEvents(definitions, {
                         kind: eff.kind,
                         definitionName: eff.definitionName,
+                        definitionVersion: eff.definitionVersion,
                         input: eff.input,
                         threadId: childThreadId,
                         parentThreadId: currentThreadId,
@@ -83,17 +84,10 @@ export function dispatchEffect(registry, services, definitions, effect, ctx) {
             ]);
         }
         const input = 'input' in eff ? eff.input : {};
-        let execution = handler
-            .execute(input, effCtx)
-            .pipe(Effect.provide(services));
-        if (handler.retry && handler.retry.maxAttempts > 1) {
-            const retryPolicy = handler.retry;
-            const backoff = retryPolicy.backoffMs ?? 100;
-            execution = execution.pipe(Effect.retry({
-                times: retryPolicy.maxAttempts - 1,
-                schedule: Schedule.spaced(backoff),
-            }));
-        }
+        const execution = Effect.gen(function* () {
+            const serviceContext = yield* services.contextEffect;
+            return yield* handler.execute(input, effCtx).pipe(Effect.provide(serviceContext));
+        });
         return execution.pipe(Effect.catch((err) => Effect.succeed([
             {
                 type: 'runtime.effect.failed',

package/dist/runtime/errors.d.ts

@@ -0,0 +1,51 @@
+import type { JsonValue, RunStartIdentity as DurableRunStartIdentity } from '@swirls/looms/core';
+export interface RunStartIdentity {
+    readonly kind: string;
+    readonly definitionName: string;
+    readonly definitionVersion: string;
+    readonly input: JsonValue;
+    readonly requestedThreadId: string | null;
+    readonly idempotencyKey: string | null;
+}
+declare const StartRunConflictError_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: "StartRunConflictError";
+} & Readonly<A>;
+export declare class StartRunConflictError extends StartRunConflictError_base<{
+    readonly runId: string;
+    readonly requested: RunStartIdentity;
+    readonly existing: DurableRunStartIdentity;
+    readonly mismatches: readonly (keyof RunStartIdentity)[];
+    readonly message: string;
+}> {
+    constructor(runId: string, requested: RunStartIdentity, existing: DurableRunStartIdentity, mismatches: readonly (keyof RunStartIdentity)[]);
+}
+declare const DuplicateEffectDispatchError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "DuplicateEffectDispatchError";
+} & Readonly<A>;
+export declare class DuplicateEffectDispatchError extends DuplicateEffectDispatchError_base<{
+    readonly runId: string;
+    readonly effectId: string;
+    readonly threadId: string;
+    readonly message: string;
+}> {
+    constructor(runId: string, effectId: string, threadId: string);
+}
+declare const MaxWakeIterationsError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "MaxWakeIterationsError";
+} & Readonly<A>;
+export declare class MaxWakeIterationsError extends MaxWakeIterationsError_base<{
+    readonly runId: string;
+    readonly maxIterations: number;
+    readonly message: string;
+}> {
+    constructor(runId: string, maxIterations: number);
+}
+declare const RuntimeExecutionError_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: "RuntimeExecutionError";
+} & Readonly<A>;
+export declare class RuntimeExecutionError extends RuntimeExecutionError_base<{
+    readonly message: string;
+}> {
+    constructor(message: string);
+}
+export {};

package/dist/runtime/errors.js

@@ -0,0 +1,39 @@
+import { Data } from 'effect';
+export class StartRunConflictError extends Data.TaggedError('StartRunConflictError') {
+    constructor(runId, requested, existing, mismatches) {
+        super({
+            runId,
+            requested,
+            existing,
+            mismatches,
+            message: `Run "${runId}" already has a different durable start (${mismatches.join(', ')})`,
+        });
+        this.name = 'StartRunConflictError';
+    }
+}
+export class DuplicateEffectDispatchError extends Data.TaggedError('DuplicateEffectDispatchError') {
+    constructor(runId, effectId, threadId) {
+        super({
+            runId,
+            effectId,
+            threadId,
+            message: `Duplicate effect dispatch detected for effectId "${effectId}" on thread "${threadId}"; refusing to re-dispatch already executed effect`,
+        });
+        this.name = 'DuplicateEffectDispatchError';
+    }
+}
+export class MaxWakeIterationsError extends Data.TaggedError('MaxWakeIterationsError') {
+    constructor(runId, maxIterations) {
+        super({
+            runId,
+            maxIterations,
+            message: `Max wake iterations exceeded (${maxIterations}) for run "${runId}"; possible infinite loop`,
+        });
+        this.name = 'MaxWakeIterationsError';
+    }
+}
+export class RuntimeExecutionError extends Data.TaggedError('RuntimeExecutionError') {
+    constructor(message) {
+        super({ message });
+    }
+}

package/dist/runtime/{runtime-helpers.d.ts → helpers.d.ts}

@@ -1,5 +1,18 @@
-import { Effect, Layer } from 'effect';
-import { type AnyRuntimeModule, type AppendableEvent, type EventCatalog, type EventEnvelope, type EventInput, type EventOrigin, type EventStore, type InvalidEventError, type JsonValue, type RegisteredDefinition, type RunCursor, type RunState, type SnapshotStore } from '@swirls/looms/core';
+import { Effect, Layer, type Context } from 'effect';
+import { type AnyRuntimeModule, type AppendableEvent, type EventCatalog, type EventEnvelope, type EventInput, type EventOrigin, type EventStore, InvalidEventError, type JsonValue, type OutstandingEffect, type RegisteredDefinition, type RunCursor, type RunState, type SnapshotStore } from '@swirls/looms/core';
+import type { EffectWorkerTask } from './types';
+export declare function workerTask(runId: string, item: OutstandingEffect, attempt: number): EffectWorkerTask;
+declare const UnknownDefinitionError_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: "UnknownDefinitionError";
+} & Readonly<A>;
+export declare class UnknownDefinitionError extends UnknownDefinitionError_base<{
+    readonly kind: string;
+    readonly definitionName: string;
+    readonly definitionVersion: string;
+    readonly message: string;
+}> {
+    constructor(kind: string, definitionName: string, definitionVersion: string);
+}
 export declare function resolveSnapshotStore(explicit: SnapshotStore | undefined, store: EventStore | undefined): SnapshotStore;
 export declare class RunCursorCache {
     private readonly max;
@@ -10,7 +23,7 @@ export declare class RunCursorCache {
     delete(runId: string): void;
 }
 export declare function stripSeq(events: ReadonlyArray<EventEnvelope>): AppendableEvent[];
-export declare function moduleServices(modules: readonly AnyRuntimeModule[]): Layer.Layer<any>;
+export declare function moduleServices(modules: readonly AnyRuntimeModule[]): Layer.Layer<Context.Service.Any>;
 export declare function groupOutstanding(items: readonly {
     threadId: string;
     causingSeq: number;
@@ -24,10 +37,11 @@ export declare function groupOutstanding(items: readonly {
 export declare function threadStartedEvents(definitions: ReadonlyMap<string, RegisteredDefinition>, args: {
     kind: string;
     definitionName: string;
+    definitionVersion: string;
     input: JsonValue;
     threadId: string;
     parentThreadId: string | null;
-}): Effect.Effect<ReadonlyArray<EventInput>, Error>;
+}): Effect.Effect<ReadonlyArray<EventInput>, UnknownDefinitionError>;
 export declare function synthesizedThreadFailed(before: RunState, after: RunState, written: readonly EventEnvelope[]): EventInput[];
 export declare function waitSatisfiedEvents(state: RunState, events: readonly EventEnvelope[]): EventInput[];
 export declare function createEffectFailedEvent(runId: string, item: {
@@ -45,7 +59,13 @@ export declare function createLiveEvent(runId: string, item: {
     causingEventId: string;
     threadId: string;
 }, validated: EventInput): AppendableEvent | undefined;
+/**
+ * Admit events from an external caller. Runtime protocol events are reserved for the runtime
+ * itself, and external events can never claim an effect outcome or a non-external origin.
+ */
+export declare function admitExternalEvents(events: readonly EventInput[]): Effect.Effect<EventInput[], InvalidEventError>;
 export declare function validateAndCreateEvents(catalogs: readonly EventCatalog[], runId: string, events: readonly EventInput[], defaults: {
     origin: EventOrigin;
     threadId?: string | null;
 }): Effect.Effect<EventEnvelope[], InvalidEventError>;
+export {};

package/dist/runtime/{runtime-helpers.js → helpers.js}

@@ -1,5 +1,25 @@
-import { Effect, Layer, Predicate } from 'effect';
-import { asJson, createEvent, makeMemorySnapshotStore, matchingWaits, snapshotStoreOf, validateEventInput, validateEventsEffect, validateInput, withSnapshotStore, } from '@swirls/looms/core';
+import { Data, Effect, Layer, Predicate } from 'effect';
+import { asJson, createEvent, definitionKey, makeMemorySnapshotStore, matchingWaits, snapshotStoreOf, validateEventInput, validateEventsEffect, validateInputEffect, withSnapshotStore, InvalidEventError, } from '@swirls/looms/core';
+export function workerTask(runId, item, attempt) {
+    return {
+        runId,
+        effectId: item.effectId,
+        attempt,
+        type: item.effect.type,
+        input: 'input' in item.effect ? item.effect.input : null,
+    };
+}
+export class UnknownDefinitionError extends Data.TaggedError('UnknownDefinitionError') {
+    constructor(kind, definitionName, definitionVersion) {
+        super({
+            kind,
+            definitionName,
+            definitionVersion,
+            message: `Unknown definition ${definitionKey(kind, definitionName, definitionVersion)}`,
+        });
+        this.name = 'UnknownDefinitionError';
+    }
+}
 export function resolveSnapshotStore(explicit, store) {
     if (explicit) {
         if (store) {
@@ -52,15 +72,17 @@ export class RunCursorCache {
 export function stripSeq(events) {
     return events.map(({ seq: _seq, ...rest }) => rest);
 }
+// Heterogeneous module service identifiers are intentionally erased after composition.
+// oxlint-disable-next-line effecttsgo/any-unknown-in-error-context
 export function moduleServices(modules) {
-    // SAFETY: Empty layer serves as seed; module service layers are merged in.
-    let merged = Layer.empty;
-    for (const module of modules) {
-        if (module.services) {
-            merged = Layer.merge(merged, module.services());
-        }
+    const layers = modules.flatMap((module) => (module.services ? [module.services()] : []));
+    const [first, ...rest] = layers;
+    if (!first) {
+        // SAFETY: An empty service set satisfies the erased registry boundary.
+        // oxlint-disable-next-line typescript/no-unsafe-type-assertion
+        return Layer.empty;
     }
-    return merged;
+    return rest.reduce((merged, layer) => Layer.merge(merged, layer), first);
 }
 export function groupOutstanding(items) {
     const keys = [];
@@ -83,21 +105,18 @@ export function groupOutstanding(items) {
  */
 export function threadStartedEvents(definitions, args) {
     return Effect.gen(function* () {
-        const def = definitions.get(`${args.kind}:${args.definitionName}`);
+        const def = definitions.get(definitionKey(args.kind, args.definitionName, args.definitionVersion));
         if (!def) {
-            return yield* Effect.fail(new Error(`Unknown definition ${args.kind}:${args.definitionName}`));
+            return yield* new UnknownDefinitionError(args.kind, args.definitionName, args.definitionVersion);
         }
         const raw = args.input ?? null;
         let startedInput = raw;
         let validationError;
         if (def?.input) {
-            const validated = yield* Effect.tryPromise({
-                try: () => {
-                    // SAFETY: RegisteredDefinition.input is a Standard Schema when present.
-                    return validateInput(def.input, raw);
-                },
-                catch: (err) => (err instanceof Error ? err : new Error(String(err))),
-            }).pipe(Effect.map((value) => ({ ok: true, value })), Effect.catch((err) => Effect.succeed({ ok: false, error: err.message })));
+            const validated = yield* validateInputEffect(def.input, raw).pipe(Effect.match({
+                onFailure: (error) => ({ ok: false, error: error.message }),
+                onSuccess: (value) => ({ ok: true, value }),
+            }));
             if (validated.ok) {
                 startedInput = validated.value;
             }
@@ -111,6 +130,7 @@ export function threadStartedEvents(definitions, args) {
                 threadId: args.threadId,
                 kind: args.kind,
                 definitionName: args.definitionName,
+                definitionVersion: args.definitionVersion,
                 input: startedInput,
                 parentThreadId: args.parentThreadId,
             },
@@ -215,12 +235,29 @@ export function createLiveEvent(runId, item, validated) {
         effectId: item.effectId,
         causationId: item.causingEventId,
         threadId: targetThreadId,
-        ephemeral: validated.ephemeral ?? true,
+        ephemeral: true,
         origin: validated.origin ?? { type: 'thread', threadId: item.threadId },
     });
     const [liveEvent] = stripSeq([ephemeral]);
     return liveEvent;
 }
+const EXTERNAL_RUNTIME_EVENT_TYPES = new Set([
+    'runtime.signal.received',
+    'runtime.thread.cancel.requested',
+]);
+/**
+ * Admit events from an external caller. Runtime protocol events are reserved for the runtime
+ * itself, and external events can never claim an effect outcome or a non-external origin.
+ */
+export function admitExternalEvents(events) {
+    return Effect.forEach(events, (input) => input.type.startsWith('runtime.') && !EXTERNAL_RUNTIME_EVENT_TYPES.has(input.type)
+        ? Effect.fail(new InvalidEventError(input.type, `Event type "${input.type}" is reserved for the runtime`))
+        : Effect.succeed({
+            ...input,
+            effectId: null,
+            origin: input.origin?.type === 'external' ? input.origin : { type: 'external' },
+        }));
+}
 export function validateAndCreateEvents(catalogs, runId, events, defaults) {
     return validateEventsEffect(catalogs, events).pipe(Effect.map((validated) => validated.map((input) => createEvent(runId, {
         ...input,

package/dist/runtime/index.d.ts

@@ -1,5 +1,5 @@
-export { createRuntime, createTimeoutScheduler, DuplicateEffectDispatchError, MaxWakeIterationsError, type CreateRuntimeOptions, type LoomsRuntime, type RegisteredDefinition, type StartRunArgs, type WakeError, type WakeScheduler, } from './runtime';
+export { createRuntime, createTimeoutScheduler, DuplicateEffectDispatchError, MaxWakeIterationsError, RunOverloadedError, StartRunConflictError, type CreateRuntimeOptions, type EffectWorker, type EffectWorkerTask, type LoomsRuntime, type RunOperationalStatus, type RegisteredDefinition, type StartRunArgs, type WakeError, type WakeScheduler, type WorkerCallback, type WorkerCallbackInput, } from './runtime';
 export { createLooms, type Looms, type CreateLoomsOptions, type StartResult } from './looms';
-export { serveHttp, createFetchHandler, isLoomsApiPath, type FetchHandlerOptions, type RunningServer, type LoomsFetchResult, } from './server';
-export { handleEventsApi, encodeLoomsEvent, type EncodedLoomsEvent } from './events-api';
+export { serveHttp, createFetchHandler, isLoomsApiPath, type FetchHandlerOptions, authAllowed, authDenied, bearerAuth, defaultAuthorize, type AuthDecision, type AuthorizedAccess, type Authorize, type BearerTokens, type RouteAccess, type RouteInfo, type RunningServer, type LoomsFetchResult, } from './server';
 export { createEventStreamResponse, type EventStreamOptions } from './sse';
+export { notifyObserver, type RuntimeObservation, type RuntimeObserver } from './observer';

package/dist/runtime/index.js

@@ -1,5 +1,5 @@
-export { createRuntime, createTimeoutScheduler, DuplicateEffectDispatchError, MaxWakeIterationsError, } from './runtime.js';
+export { createRuntime, createTimeoutScheduler, DuplicateEffectDispatchError, MaxWakeIterationsError, RunOverloadedError, StartRunConflictError, } from './runtime.js';
 export { createLooms } from './looms.js';
-export { serveHttp, createFetchHandler, isLoomsApiPath, } from './server.js';
-export { handleEventsApi, encodeLoomsEvent } from './events-api.js';
+export { serveHttp, createFetchHandler, isLoomsApiPath, authAllowed, authDenied, bearerAuth, defaultAuthorize, } from './server.js';
 export { createEventStreamResponse } from './sse.js';
+export { notifyObserver } from './observer.js';

package/dist/runtime/ingress.d.ts

@@ -0,0 +1,15 @@
+import { Effect } from 'effect';
+import type { RunExecutionContexts } from './run-execution-context';
+declare const RunOverloadedError_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: "RunOverloadedError";
+} & Readonly<A>;
+export declare class RunOverloadedError extends RunOverloadedError_base<{
+    readonly runId: string;
+    readonly limit: number;
+    readonly message: string;
+}> {
+    constructor(runId: string, limit: number);
+}
+export type RunIngress = <A, E, R>(runId: string, operation: Effect.Effect<A, E, R>) => Effect.Effect<A, E | RunOverloadedError, R>;
+export declare function createRunIngress(executionContexts: RunExecutionContexts, maxPendingRunOperations: number): RunIngress;
+export {};

package/dist/runtime/ingress.js

@@ -0,0 +1,42 @@
+import { Data, Effect } from 'effect';
+export class RunOverloadedError extends Data.TaggedError('RunOverloadedError') {
+    constructor(runId, limit) {
+        super({
+            runId,
+            limit,
+            message: `Run "${runId}" has reached its pending operation limit (${limit})`,
+        });
+        this.name = 'RunOverloadedError';
+    }
+}
+export function createRunIngress(executionContexts, maxPendingRunOperations) {
+    return (runId, operation) => Effect.suspend(() => {
+        const context = executionContexts.get(runId);
+        const current = context.ingress ?? { pending: 0, tail: Promise.resolve() };
+        if (current.pending >= maxPendingRunOperations) {
+            return Effect.fail(new RunOverloadedError(runId, maxPendingRunOperations));
+        }
+        let release;
+        // Promise chaining is the admission queue; the workload itself remains an Effect.
+        // oxlint-disable-next-line effecttsgo/new-promise
+        const own = new Promise((resolve) => {
+            release = resolve;
+        });
+        const previous = current.tail;
+        context.ingress = { pending: current.pending + 1, tail: own };
+        return Effect.promise(() => previous).pipe(Effect.andThen(operation), Effect.ensuring(Effect.sync(() => {
+            release();
+            const latest = context.ingress;
+            if (!latest) {
+                return;
+            }
+            if (latest.pending <= 1) {
+                context.ingress = null;
+            }
+            else {
+                context.ingress = { ...latest, pending: latest.pending - 1 };
+            }
+            executionContexts.releaseIfIdle(runId);
+        })));
+    });
+}

package/dist/runtime/local-effect-executor.d.ts

@@ -0,0 +1,21 @@
+import { Effect, type Context, type ManagedRuntime } from 'effect';
+import { type ComposedRegistry, type EventEnvelope, type OutstandingEffect, type RegisteredDefinition } from '@swirls/looms/core';
+import type { RuntimeObserver } from './observer';
+import type { RuntimeRepository } from './repository';
+import type { RunExecutionContext } from './run-execution-context';
+export interface LocalEffectExecutorOptions {
+    readonly registry: ComposedRegistry;
+    readonly services: ManagedRuntime.ManagedRuntime<Context.Service.Any, never>;
+    readonly definitions: ReadonlyMap<string, RegisteredDefinition>;
+    readonly executionContext: RunExecutionContext;
+    readonly liveAppends: RuntimeRepository['liveAppends'];
+    readonly runInContext: <A, E>(effect: Effect.Effect<A, E>) => Promise<A>;
+    readonly observe: (event: Parameters<RuntimeObserver['observe']>[0]) => void;
+}
+export interface ExecuteLocalEffectsInput {
+    readonly runId: string;
+    readonly outstanding: ReadonlyArray<OutstandingEffect>;
+    readonly attempts: ReadonlyMap<string, number>;
+    readonly now: number;
+}
+export declare function executeLocalEffects(options: LocalEffectExecutorOptions, input: ExecuteLocalEffectsInput): Effect.Effect<ReadonlyArray<EventEnvelope>, Error>;

package/dist/runtime/local-effect-executor.js

@@ -0,0 +1,137 @@
+import { Effect, Option, Predicate } from 'effect';
+import { createEvent, validateEventInput, withdrawnError, } from '@swirls/looms/core';
+import { dispatchEffect } from './dispatch-effect.js';
+import { RuntimeExecutionError } from './errors.js';
+import { createEffectFailedEvent, createLiveEvent, groupOutstanding, materializeEffectOutcome, } from './helpers.js';
+import { planAttemptFailure } from './retry-policy.js';
+function makeAbortController() {
+    return new AbortController();
+}
+/** Completes when the signal aborts, so racing it interrupts a handler that ignores the signal. */
+function abortion(signal) {
+    return Effect.callback((resume) => {
+        const onAbort = () => resume(Effect.succeed({ _tag: 'aborted' }));
+        if (signal.aborted) {
+            onAbort();
+            return Effect.void;
+        }
+        signal.addEventListener('abort', onAbort, { once: true });
+        return Effect.sync(() => signal.removeEventListener('abort', onAbort));
+    });
+}
+export function executeLocalEffects(options, input) {
+    const { registry, services, definitions, executionContext, liveAppends, runInContext, observe } = options;
+    return Effect.forEach(groupOutstanding(input.outstanding), (groupKey) => Effect.gen(function* () {
+        const group = input.outstanding.filter((item) => `${item.threadId}:${item.causingSeq}` === groupKey);
+        const produced = [];
+        let failedEffectId;
+        for (const item of group) {
+            if (failedEffectId && item.effect.type === 'runtime.wait') {
+                produced.push(createEffectFailedEvent(input.runId, item, withdrawnError(failedEffectId)));
+                continue;
+            }
+            const appendLive = (eventInput) => runInContext(Effect.gen(function* () {
+                const validated = yield* validateEventInput(registry.catalogs, eventInput);
+                const liveEvent = createLiveEvent(input.runId, item, validated);
+                if (liveEvent) {
+                    yield* liveAppends.push(input.runId, liveEvent);
+                }
+            }));
+            const controller = makeAbortController();
+            executionContext.activeEffects.set(item.effectId, {
+                controller,
+                threadId: item.threadId,
+            });
+            const retry = registry.effects.get(item.effect.type)?.retry;
+            const dispatched = dispatchEffect(registry, services, definitions, item.effect, {
+                effectId: item.effectId,
+                runId: input.runId,
+                threadId: item.threadId,
+                causingEventId: item.causingEventId,
+                signal: controller.signal,
+                emit: appendLive,
+            }).pipe(Effect.map((outcomes) => ({ _tag: 'completed', outcomes })), Effect.raceFirst(abortion(controller.signal)));
+            const settled = yield* (retry?.startToCloseTimeoutMs
+                ? dispatched.pipe(Effect.timeoutOption(retry.startToCloseTimeoutMs), Effect.map(Option.getOrElse(() => ({ _tag: 'timed-out' }))))
+                : dispatched).pipe(Effect.ensuring(Effect.sync(() => {
+                executionContext.activeEffects.delete(item.effectId);
+            })));
+            if (settled._tag === 'aborted') {
+                continue;
+            }
+            const before = produced.length;
+            if (settled._tag === 'timed-out') {
+                controller.abort(new RuntimeExecutionError('start-to-close timeout'));
+                const attemptNumber = input.attempts.get(item.effectId) ?? 1;
+                observe({
+                    type: 'effect.timeout',
+                    runId: input.runId,
+                    at: input.now,
+                    effectId: item.effectId,
+                    attempt: attemptNumber,
+                    detail: 'start-to-close',
+                });
+                produced.push(createEvent(input.runId, {
+                    type: 'runtime.effect.timed_out',
+                    payload: {
+                        effectId: item.effectId,
+                        attempt: attemptNumber,
+                        timeout: 'start-to-close',
+                    },
+                    threadId: item.threadId,
+                    causationId: item.causingEventId,
+                    origin: { type: 'system' },
+                }), planAttemptFailure({
+                    runId: input.runId,
+                    item,
+                    attempt: attemptNumber,
+                    error: 'start-to-close timeout',
+                    now: input.now,
+                    retry,
+                    origin: { type: 'system' },
+                }).event);
+                failedEffectId = item.effectId;
+                continue;
+            }
+            const { outcomes } = settled;
+            if (outcomes.length === 0) {
+                produced.push(createEffectFailedEvent(input.runId, item, 'empty-outcome'));
+            }
+            for (const outcome of outcomes) {
+                if (outcome.type === 'runtime.effect.failed') {
+                    const attempt = input.attempts.get(item.effectId) ?? 1;
+                    const payload = Predicate.isObject(outcome.payload) ? outcome.payload : {};
+                    const error = Predicate.isString(payload.error) ? payload.error : 'effect failed';
+                    const failure = planAttemptFailure({
+                        runId: input.runId,
+                        item,
+                        attempt,
+                        error,
+                        now: input.now,
+                        retry,
+                        origin: { type: 'system' },
+                    });
+                    if (failure.retrying) {
+                        observe({
+                            type: 'effect.retry',
+                            runId: input.runId,
+                            at: input.now,
+                            effectId: item.effectId,
+                            attempt,
+                            detail: error,
+                        });
+                        produced.push(failure.event);
+                        continue;
+                    }
+                }
+                produced.push(yield* materializeEffectOutcome(registry.catalogs, input.runId, item, outcome));
+            }
+            const itemOutcomes = produced.slice(before);
+            if (item.effect.type !== 'runtime.wait' &&
+                itemOutcomes.some((event) => event.type === 'runtime.effect.failed')) {
+                failedEffectId = item.effectId;
+            }
+        }
+        return produced;
+    }), { concurrency: 'unbounded' }).pipe(Effect.map((groups) => groups.flat()));
+}

package/dist/runtime/looms.d.ts

@@ -1,6 +1,7 @@
-import { type AnyRuntimeModule, type DefinitionInput, type DefinitionRef, type EventEnvelope, type EventInput, type EventStore, type JsonValue, type SnapshotStore, type ProjectionDefinition, type ReplayStep, type RunState } from '@swirls/looms/core';
-import { type LoomsRuntime, type WakeScheduler } from './runtime';
-import { type RunningServer } from './server';
+import { type AnyRuntimeModule, type DebuggerHost, type DefinitionInput, type DefinitionRef, type EventEnvelope, type EventInput, type EventStore, type EventStoreTrimCoverage, type JsonValue, type SnapshotStore, type ProjectionDefinition, type ReplayStep, type RunState } from '@swirls/looms/core';
+import type { RuntimeObserver } from './observer';
+import { type EffectWorker, type LoomsRuntime, type RunOperationalStatus, type WakeScheduler, type WorkerCallbackInput } from './runtime';
+import { type Authorize, type RunningServer } from './server';
 export interface CreateLoomsOptions {
     /** Runtime modules to enable. Pass `agent()`, `workflow()`, `approval()`, and/or your own. */
     readonly modules?: readonly AnyRuntimeModule[];
@@ -10,19 +11,38 @@ export interface CreateLoomsOptions {
         hostname?: string;
     };
     readonly maxWakeIterations?: number;
+    /** Maximum active and queued mutation operations per run. Default 256. */
+    readonly maxPendingRunOperations?: number;
     /** Durable events between mid-wake snapshots. Default 200; `0` disables. Parking always snapshots. */
     readonly snapshotEvery?: number;
     /** Defaults to the EventStore's attached store (S2) or an in-memory SnapshotStore. */
     readonly snapshotStore?: SnapshotStore;
     readonly trimAfterSnapshot?: {
         keepSnapshots: number;
+        coverage?: (runId: string) => EventStoreTrimCoverage | Promise<EventStoreTrimCoverage>;
     };
     /** In-process cursor cache size. Default `0` (stateless between calls). */
     readonly runCacheSize?: number;
     /** Scan existing runs for pending timers on boot. Default true. */
     readonly rescanTimers?: boolean;
-    /** Pluggable wake scheduler for timer waits. Defaults to an in-process setTimeout scheduler. */
+    /** Pluggable wake scheduler for timer waits. Defaults to an in-process Effect fiber scheduler. */
     readonly scheduler?: WakeScheduler;
+    readonly worker?: EffectWorker;
+    /** Failure-isolated runtime observation sink. */
+    readonly observer?: RuntimeObserver;
+    /**
+     * Authorizes HTTP API requests. Without it, run reads and writes are open while worker callback
+     * and operations routes return 503; `bearerAuth({ worker, operations })` enables them.
+     *
+     * A mounted debugger is authorized as `{ access: 'read', name: 'debugger' }`. Bearer tokens on
+     * reads block browser navigation, so hosts that need auth should use a cookie or session policy.
+     */
+    readonly authorize?: Authorize;
+    /**
+     * Serves a debugger UI under `debugger.basePath` (for example `/debugger`). The runtime does not
+     * bundle a UI; pass `debuggerUi()` from `@swirls/looms/debugger/server`.
+     */
+    readonly debugger?: DebuggerHost;
 }
 export interface StartResult {
     readonly runId: string;
@@ -46,6 +66,7 @@ export interface Looms {
     startRun(args: {
         kind: string;
         definitionName: string;
+        definitionVersion?: string;
         input?: JsonValue;
         runId?: string;
         threadId?: string;
@@ -61,9 +82,14 @@ export interface Looms {
     }): Promise<RunState>;
     wake(runId: string): Promise<RunState>;
     rescanTimers(): Promise<number>;
+    recoverDeadlines(): Promise<number>;
+    inspectRun(runId: string): Promise<RunOperationalStatus>;
+    retryEffect(runId: string, effectId: string): Promise<RunState>;
+    listRuns(): Promise<string[]>;
     project<S>(runId: string, definition: ProjectionDefinition<S>): Promise<S>;
     replayTo(runId: string, seq: number): Promise<ReplayStep | null>;
     cancel(runId: string, threadId?: string): Promise<RunState>;
+    workerCallback(runId: string, input: WorkerCallbackInput): Promise<RunState>;
     fetch(req: Request): Promise<Response | null>;
     serve(options?: {
         port?: number;