@swirls/looms 0.3.0 → 0.5.0

package/dist/runtime/helpers.js

@@ -1,13 +1,40 @@
 import { Data, Effect, Layer, Predicate } from 'effect';
-import { asJson, createEvent, definitionKey, descendantThreadIds, isTerminalStatus, makeMemorySnapshotStore, matchingWaits, snapshotStoreOf, validateEventInput, validateEventsEffect, validateInputEffect, withSnapshotStore, InvalidEventError, } from '@swirls/looms/core';
-export function workerTask(runId, item, attempt) {
-    return {
+import { asJson, createEvent, definitionKey, descendantThreadIds, isTerminalStatus, makeMemorySnapshotStore, matchingWaits, snapshotStoreOf, validateEventInput, validateEventsEffect, validateInputEffect, withSnapshotStore, hasEntries, InvalidEventError, } from '@swirls/looms/core';
+export function workerTask(runId, item, attempt, extras = {}) {
+    const task = {
         runId,
         effectId: item.effectId,
         attempt,
         type: item.effect.type,
         input: 'input' in item.effect ? item.effect.input : null,
     };
+    if (extras.details != null) {
+        task.details = extras.details;
+    }
+    if (extras.secrets && hasEntries(extras.secrets)) {
+        task.secrets = extras.secrets;
+    }
+    if (extras.trace) {
+        task.trace = extras.trace;
+    }
+    const deadlines = workerDeadlines(extras);
+    if (deadlines) {
+        task.deadlines = deadlines;
+    }
+    return task;
+}
+function workerDeadlines(extras) {
+    const deadlines = {};
+    if (extras.scheduleToStartAt != null) {
+        deadlines.scheduleToStartAt = extras.scheduleToStartAt;
+    }
+    if (extras.retry?.startToCloseTimeoutMs) {
+        deadlines.startToCloseTimeoutMs = extras.retry.startToCloseTimeoutMs;
+    }
+    if (extras.retry?.heartbeatTimeoutMs) {
+        deadlines.heartbeatTimeoutMs = extras.retry.heartbeatTimeoutMs;
+    }
+    return Object.keys(deadlines).length > 0 ? deadlines : undefined;
 }
 export class UnknownDefinitionError extends Data.TaggedError('UnknownDefinitionError') {
     constructor(kind, definitionName, definitionVersion) {
@@ -105,15 +132,16 @@ export function groupOutstanding(items) {
  */
 export function threadStartedEvents(definitions, args) {
     return Effect.gen(function* () {
-        const def = definitions.get(definitionKey(args.kind, args.definitionName, args.definitionVersion));
+        const def = yield* definitions.resolve(args.kind, args.definitionName, args.definitionVersion);
         if (!def) {
             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* validateInputEffect(def.input, raw).pipe(Effect.match({
+        const input = schemaInputOf(def);
+        if (input) {
+            const validated = yield* validateInputEffect(input, raw).pipe(Effect.match({
                 onFailure: (error) => ({ ok: false, error: error.message }),
                 onSuccess: (value) => ({ ok: true, value }),
             }));
@@ -150,6 +178,18 @@ export function threadStartedEvents(definitions, args) {
         ];
     });
 }
+function schemaInputOf(definition) {
+    if (!('input' in definition)) {
+        return undefined;
+    }
+    return isSchemaInput(definition.input) ? definition.input : undefined;
+}
+function isSchemaInput(value) {
+    if (value === null || (!Predicate.isObject(value) && !Predicate.isFunction(value))) {
+        return false;
+    }
+    return '~standard' in value || 'ast' in value;
+}
 export function synthesizedThreadFailed(before, after, written) {
     const out = [];
     for (const [threadId, thread] of Object.entries(after.threads)) {

package/dist/runtime/index.d.ts

@@ -1,5 +1,7 @@
-export { createRuntime, createTimeoutScheduler, DuplicateEffectDispatchError, ForkConflictError, MaxWakeIterationsError, RunNotFinishedError, RunNotFoundError, RunOverloadedError, RunTerminalError, 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 { createRuntime, createTimeoutScheduler, DuplicateEffectDispatchError, ForkConflictError, MaxWakeIterationsError, RunNotFinishedError, RunNotFoundError, RunOverloadedError, RunTerminalError, StartRunConflictError, type CreateRuntimeOptions, type EffectWorker, type EffectWorkerDeadlines, type EffectWorkerTask, type LoomsRuntime, type RunOperationalStatus, type RegisteredDefinition, type StartRunArgs, type WakeError, type WakeScheduler, type WorkerCallback, type WorkerCallbackInput, type WorkerCallbackResult, } from './runtime';
 export { createLooms, type Looms, type CreateLoomsOptions, type StartResult } from './looms';
-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 { loadSubscriptionOpening, readSubscriptionBounds } from './subscription';
+export { serveHttp, createFetchHandler, isLoomsApiPath, type FetchHandlerOptions, authAllowed, authDenied, authResponse, bearerAuth, defaultAuthorize, grantAuth, issueRunGrant, grantSubprotocol, runGrantToken, verifyRunGrant, GrantError, type GrantAuthOptions, type GrantFailure, type RunGrant, runRouteInfo, type AuthDecision, type AuthorizedAccess, type Authorize, type BearerTokens, type RouteAccess, type RouteInfo, type RunningServer, type LoomsFetchResult, } from './server';
+export { filesystemBlobStore } from './filesystem-blob-store';
 export { createEventStreamResponse, type EventStreamOptions } from './sse';
 export { notifyObserver, type RuntimeObservation, type RuntimeObserver } from './observer';

package/dist/runtime/index.js

@@ -1,5 +1,7 @@
 export { createRuntime, createTimeoutScheduler, DuplicateEffectDispatchError, ForkConflictError, MaxWakeIterationsError, RunNotFinishedError, RunNotFoundError, RunOverloadedError, RunTerminalError, StartRunConflictError, } from './runtime.js';
 export { createLooms } from './looms.js';
-export { serveHttp, createFetchHandler, isLoomsApiPath, authAllowed, authDenied, bearerAuth, defaultAuthorize, } from './server.js';
+export { loadSubscriptionOpening, readSubscriptionBounds } from './subscription.js';
+export { serveHttp, createFetchHandler, isLoomsApiPath, authAllowed, authDenied, authResponse, bearerAuth, defaultAuthorize, grantAuth, issueRunGrant, grantSubprotocol, runGrantToken, verifyRunGrant, GrantError, runRouteInfo, } from './server.js';
+export { filesystemBlobStore } from './filesystem-blob-store.js';
 export { createEventStreamResponse } from './sse.js';
 export { notifyObserver } from './observer.js';

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

@@ -1,19 +1,28 @@
 import { Effect, type Context, type ManagedRuntime } from 'effect';
-import { type ComposedRegistry, type EventEnvelope, type OutstandingEffect, type RegisteredDefinition } from '@swirls/looms/core';
+import { type ComposedRegistry, type EventEnvelope, type DefinitionResolver, type OutstandingEffect, type RunAttributes, type RunLauncher, type SecretContext, type TraceContext } 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 definitionResolver: DefinitionResolver;
     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;
+    readonly launcher: RunLauncher;
+}
+/** Run-level values every effect sees. Runs the effects launch inherit them unless the launch overrides them. */
+export interface RunContext {
+    readonly correlationId: string;
+    readonly attributes: RunAttributes;
+    readonly secrets: SecretContext;
+    readonly trace: TraceContext | null;
 }
 export interface ExecuteLocalEffectsInput {
     readonly runId: string;
+    readonly context: RunContext;
     readonly outstanding: ReadonlyArray<OutstandingEffect>;
     readonly attempts: ReadonlyMap<string, number>;
     readonly now: number;

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

@@ -1,9 +1,64 @@
 import { Effect, Option, Predicate } from 'effect';
-import { createEvent, validateEventInput, withdrawnError, } from '@swirls/looms/core';
+import { createEvent, createRunId, DEFAULT_DEFINITION_VERSION, 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 runLaunchedPayload(args, targetRunId, effectId) {
+    const definitionVersion = args.definitionVersion ?? DEFAULT_DEFINITION_VERSION;
+    const base = {
+        runId: targetRunId,
+        kind: args.kind,
+        definitionName: args.definitionName,
+        definitionVersion,
+        effectId,
+    };
+    if (args.close === undefined) {
+        return base;
+    }
+    return { ...base, close: args.close };
+}
+/**
+ * Stamps every launch with the effect that made it, replacing anything the handler passed, and
+ * records a `runtime.run.launched` event for each launch the target accepts.
+ */
+function launcherFor(launcher, runId, context, item, launched) {
+    const launchedBy = {
+        runId,
+        threadId: item.threadId,
+        effectId: item.effectId,
+        causationId: item.causingEventId,
+        causationSeq: item.causingSeq,
+    };
+    return {
+        launch: (args) => {
+            const targetRunId = args.runId ?? createRunId();
+            return launcher
+                .launch({
+                ...args,
+                runId: targetRunId,
+                launchedBy,
+                correlationId: context.correlationId,
+                attributes: args.attributes ?? context.attributes,
+                secrets: args.secrets ?? context.secrets,
+                trace: args.trace ?? context.trace ?? undefined,
+            })
+                .pipe(Effect.tap(() => Effect.sync(() => {
+                launched.push(createEvent(runId, {
+                    type: 'runtime.run.launched',
+                    payload: runLaunchedPayload(args, targetRunId, item.effectId),
+                    threadId: item.threadId,
+                    causationId: item.causingEventId,
+                    correlationId: context.correlationId,
+                    origin: { type: 'thread', threadId: item.threadId },
+                }));
+            })));
+        },
+        status: launcher.status,
+        signal: (targetRunId, events, options) => launcher.signal(targetRunId, events, options),
+        cancel: (targetRunId) => launcher.cancel(targetRunId),
+    };
+}
 function makeAbortController() {
     return new AbortController();
 }
@@ -20,7 +75,7 @@ function abortion(signal) {
     });
 }
 export function executeLocalEffects(options, input) {
-    const { registry, services, definitions, executionContext, liveAppends, runInContext, observe } = options;
+    const { registry, services, definitionResolver, executionContext, liveAppends, runInContext, observe, launcher, } = options;
     return Effect.forEach(groupOutstanding(input.outstanding), (groupKey) => Effect.gen(function* () {
         const group = input.outstanding.filter((item) => `${item.threadId}:${item.causingSeq}` === groupKey);
         const produced = [];
@@ -43,11 +98,15 @@ export function executeLocalEffects(options, input) {
                 threadId: item.threadId,
             });
             const retry = registry.effects.get(item.effect.type)?.retry;
-            const dispatched = dispatchEffect(registry, services, definitions, item.effect, {
+            const launched = [];
+            const dispatched = dispatchEffect(registry, services, definitionResolver, launcherFor(launcher, input.runId, input.context, item, launched), item.effect, {
                 effectId: item.effectId,
                 runId: input.runId,
                 threadId: item.threadId,
                 causingEventId: item.causingEventId,
+                attributes: input.context.attributes,
+                secrets: input.context.secrets,
+                trace: input.context.trace,
                 signal: controller.signal,
                 emit: appendLive,
             }).pipe(Effect.map((outcomes) => ({ _tag: 'completed', outcomes })), Effect.raceFirst(abortion(controller.signal)));
@@ -56,6 +115,8 @@ export function executeLocalEffects(options, input) {
                 : dispatched).pipe(Effect.ensuring(Effect.sync(() => {
                 executionContext.activeEffects.delete(item.effectId);
             })));
+            // A launch the target accepted happened even if the attempt was later aborted or failed.
+            produced.push(...launched);
             if (settled._tag === 'aborted') {
                 continue;
             }
@@ -94,7 +155,19 @@ export function executeLocalEffects(options, input) {
                 continue;
             }
             const { outcomes } = settled;
-            if (outcomes.length === 0) {
+            const sideEffect = item.effect.type === 'runtime.launch' || item.effect.type === 'runtime.cancelRun';
+            if (outcomes.length === 0 && sideEffect) {
+                const attempt = input.attempts.get(item.effectId) ?? 1;
+                produced.push(createEvent(input.runId, {
+                    type: 'runtime.effect.completed',
+                    payload: { effectId: item.effectId, attempt },
+                    threadId: item.threadId,
+                    effectId: item.effectId,
+                    causationId: item.causingEventId,
+                    origin: { type: 'system' },
+                }));
+            }
+            else if (outcomes.length === 0) {
                 produced.push(createEffectFailedEvent(input.runId, item, 'empty-outcome'));
             }
             for (const outcome of outcomes) {
@@ -102,6 +175,7 @@ export function executeLocalEffects(options, input) {
                     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 retryAfterMs = payload.retryAfterMs;
                     const failure = planAttemptFailure({
                         runId: input.runId,
                         item,
@@ -110,6 +184,8 @@ export function executeLocalEffects(options, input) {
                         now: input.now,
                         retry,
                         origin: { type: 'system' },
+                        nonRetryable: payload.nonRetryable === true,
+                        retryAfterMs: Predicate.isNumber(retryAfterMs) ? retryAfterMs : undefined,
                     });
                     if (failure.retrying) {
                         observe({

package/dist/runtime/looms.d.ts

@@ -1,10 +1,15 @@
-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 AnyRuntimeModule, type DebuggerHost, type DefinitionInput, type DefinitionRef, type DefinitionResolver, type EventEnvelope, type EventInput, type BlobStore, type EventStore, type EventStoreTrimCoverage, type JsonValue, type SnapshotStore, type ProjectionDefinition, type ReplayStep, type RunLauncher, 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 EffectWorker, type LoomsRuntime, type RunOperationalStatus, type StartRunArgs, type WakeScheduler, type WorkerCallbackInput, type WorkerCallbackResult } 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[];
+    /**
+     * Loads a definition that was not registered on a module. Registered definitions are checked
+     * first. A run pins the resolved version on its start event.
+     */
+    readonly definitionResolver?: DefinitionResolver;
     readonly store?: EventStore | Promise<EventStore> | (() => Promise<EventStore>);
     readonly serve?: boolean | {
         port?: number;
@@ -17,6 +22,11 @@ export interface CreateLoomsOptions {
     readonly snapshotEvery?: number;
     /** Defaults to the EventStore's attached store (S2) or an in-memory SnapshotStore. */
     readonly snapshotStore?: SnapshotStore;
+    /**
+     * Content-addressed store for JSON values that would exceed the 1 MiB event limit or the
+     * 8 MiB snapshot limit. Reads resolve references before folds, projections, and callers see them.
+     */
+    readonly blobStore?: BlobStore;
     readonly trimAfterSnapshot?: {
         keepSnapshots: number;
         coverage?: (runId: string) => EventStoreTrimCoverage | Promise<EventStoreTrimCoverage>;
@@ -27,7 +37,11 @@ export interface CreateLoomsOptions {
     readonly rescanTimers?: boolean;
     /** Pluggable wake scheduler for timer waits. Defaults to an in-process Effect fiber scheduler. */
     readonly scheduler?: WakeScheduler;
+    /** Starts runs from effect handlers. Defaults to launching into this runtime's own store. */
+    readonly launcher?: RunLauncher;
     readonly worker?: EffectWorker;
+    /** Maximum concurrent in-flight worker effects dispatched per run (fairness guard). */
+    readonly maxInFlightWorkerEffects?: number;
     /** Failure-isolated runtime observation sink. */
     readonly observer?: RuntimeObserver;
     /**
@@ -35,7 +49,8 @@ export interface CreateLoomsOptions {
      * 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.
+     * reads block browser navigation. `grantAuth` covers a browser EventSource or WebSocket that can
+     * only send a query parameter or a subprotocol.
      */
     readonly authorize?: Authorize;
     /**
@@ -61,6 +76,9 @@ export interface Looms {
         runId?: string;
         threadId?: string;
         idempotencyKey?: string;
+        attributes?: StartRunArgs['attributes'];
+        secrets?: StartRunArgs['secrets'];
+        trace?: StartRunArgs['trace'];
     }): Promise<StartResult>;
     /** Start a run by `{ kind, definitionName }` when you only have names (HTTP bodies, CLIs). */
     startRun(args: {
@@ -71,6 +89,22 @@ export interface Looms {
         runId?: string;
         threadId?: string;
         idempotencyKey?: string;
+        attributes?: StartRunArgs['attributes'];
+        secrets?: StartRunArgs['secrets'];
+        trace?: StartRunArgs['trace'];
+    }): Promise<StartResult>;
+    /** Commit a run's start and schedule a wake without waiting for it. */
+    launchRun(args: {
+        kind: string;
+        definitionName: string;
+        definitionVersion?: string;
+        input?: JsonValue;
+        runId?: string;
+        threadId?: string;
+        idempotencyKey?: string;
+        attributes?: StartRunArgs['attributes'];
+        secrets?: StartRunArgs['secrets'];
+        trace?: StartRunArgs['trace'];
     }): Promise<StartResult>;
     getRun(runId: string): Promise<RunState>;
     getEvents(runId: string, options?: {
@@ -93,7 +127,7 @@ export interface Looms {
     fork(sourceRunId: string, options?: {
         runId?: string;
     }): Promise<StartResult>;
-    workerCallback(runId: string, input: WorkerCallbackInput): Promise<RunState>;
+    workerCallback(runId: string, input: WorkerCallbackInput): Promise<WorkerCallbackResult>;
     fetch(req: Request): Promise<Response | null>;
     serve(options?: {
         port?: number;

package/dist/runtime/looms.js

@@ -1,5 +1,5 @@
 import { Data, Effect, Predicate } from 'effect';
-import { EventStoreTag, makeMemoryEventStore, snapshotStoreOf, SnapshotStoreTag, } from '@swirls/looms/core';
+import { EventStoreTag, makeMemoryEventStore, makeMemorySnapshotStore, snapshotStoreOf, withBlobOffload, SnapshotStoreTag, } from '@swirls/looms/core';
 import { createRuntime, } from './runtime.js';
 import { createFetchHandler, handlesPath, mountDebugger, serveHttp, } from './server.js';
 class LoomsInitializationError extends Data.TaggedError('LoomsInitializationError') {
@@ -20,7 +20,7 @@ export function createLooms(options = {}) {
         if (!initPromise) {
             initPromise = Effect.runPromise(Effect.gen(function* () {
                 const configuredStore = options.store;
-                const store = !configuredStore
+                let store = !configuredStore
                     ? yield* makeMemoryEventStore
                     : Predicate.isFunction(configuredStore)
                         ? yield* Effect.tryPromise({
@@ -33,18 +33,28 @@ export function createLooms(options = {}) {
                                 catch: (cause) => new LoomsInitializationError(cause),
                             })
                             : configuredStore;
+                if (options.blobStore) {
+                    const snapshots = options.snapshotStore ?? snapshotStoreOf(store) ?? (yield* makeMemorySnapshotStore);
+                    store = withBlobOffload(store, options.blobStore, { snapshots });
+                }
                 const runtime = createRuntime({
                     modules,
                     store,
                     maxWakeIterations: options.maxWakeIterations,
                     maxPendingRunOperations: options.maxPendingRunOperations,
                     snapshotEvery: options.snapshotEvery,
-                    snapshotStore: options.snapshotStore ?? snapshotStoreOf(store),
+                    snapshotStore: options.blobStore
+                        ? snapshotStoreOf(store)
+                        : (options.snapshotStore ?? snapshotStoreOf(store)),
                     trimAfterSnapshot: options.trimAfterSnapshot,
                     runCacheSize: options.runCacheSize,
                     scheduler: options.scheduler,
+                    launcher: options.launcher,
+                    localLauncher: options.launcher === undefined,
                     worker: options.worker,
+                    maxInFlightWorkerEffects: options.maxInFlightWorkerEffects,
                     observer: options.observer,
+                    definitionResolver: options.definitionResolver,
                 });
                 if (options.rescanTimers !== false) {
                     yield* runtime.rescanTimers.pipe(Effect.provideService(EventStoreTag, store), Effect.tapError(Effect.logError), Effect.ignore);
@@ -76,6 +86,7 @@ export function createLooms(options = {}) {
         },
         ready: () => getInit().then(({ store, runtime }) => ({ store, runtime })),
         startRun: (args) => runEffect((i) => i.runtime.startRun(args)),
+        launchRun: (args) => runEffect((i) => i.runtime.launchRun(args)),
         start: (definition, input, startOpts) => runEffect((i) => i.runtime.startRun({
             kind: definition.kind,
             definitionName: definition.name,
@@ -85,6 +96,9 @@ export function createLooms(options = {}) {
             runId: startOpts?.runId,
             threadId: startOpts?.threadId,
             idempotencyKey: startOpts?.idempotencyKey,
+            attributes: startOpts?.attributes,
+            secrets: startOpts?.secrets,
+            trace: startOpts?.trace,
         })),
         getRun: (runId) => runEffect((i) => i.runtime.getRun(runId)),
         getEvents: (runId, opts) => runEffect((i) => i.runtime.getEvents(runId, opts)),

package/dist/runtime/repository.d.ts

@@ -1,5 +1,5 @@
 import { Effect } from 'effect';
-import { EventStoreTrimmedError, type AppendableEvent, type AppendResult, type ComposedRegistry, type EventEnvelope, type EventStore, type EventStoreAppendError, type EventStoreError, type EventStoreTrimCoverage, type EventStoreTruncationError, type RunCursor, type SnapshotStore } from '@swirls/looms/core';
+import { EventStoreTrimmedError, type AppendableEvent, type AppendResult, type ComposedRegistry, type DefinitionResolveError, type DefinitionResolver, type EventEnvelope, type EventStore, type EventStoreAppendError, type EventStoreError, type EventStoreTrimCoverage, type EventStoreTruncationError, type RunCursor, type SnapshotStore } from '@swirls/looms/core';
 import { RuntimeExecutionError } from './errors';
 import { type RunCursorCache } from './helpers';
 import { type RuntimeObserver } from './observer';
@@ -35,19 +35,20 @@ export interface RuntimeRepositoryOptions {
     readonly runCache: RunCursorCache;
     readonly executionContexts: RunExecutionContexts;
     readonly observer?: RuntimeObserver;
+    readonly definitionResolver: DefinitionResolver;
 }
 export declare function createRuntimeRepository(options: RuntimeRepositoryOptions): {
     appendObserved: (store: EventStore, runId: string, events: ReadonlyArray<AppendableEvent>, appendOptions?: Parameters<EventStore['append']>[2]) => Effect.Effect<AppendResult, EventStoreAppendError>;
-    commit: <A, E, R>(store: EventStore, runId: string, plan: (cursor: RunCursor) => Effect.Effect<CommitPlan<A>, E, R>) => Effect.Effect<CommitResult<A>, E | RuntimeExecutionError | EventStoreAppendError | EventStoreTruncationError | EventStoreTrimmedError | EventStoreError, R>;
+    commit: <A, E, R>(store: EventStore, runId: string, plan: (cursor: RunCursor) => Effect.Effect<CommitPlan<A>, E, R>) => Effect.Effect<CommitResult<A>, E | RuntimeExecutionError | EventStoreAppendError | EventStoreTruncationError | EventStoreTrimmedError | EventStoreError | DefinitionResolveError, R>;
     liveAppends: {
         push: (key: string, event: AppendableEvent) => Effect.Effect<void, LiveAppendError | EventStoreAppendError, never>;
         drain: (key: string) => Effect.Effect<void>;
         clear: (key?: string) => void;
         size: () => number;
     };
-    loadCursor: (store: EventStore, runId: string) => Effect.Effect<RunCursor, EventStoreTruncationError | EventStoreTrimmedError | EventStoreError>;
+    loadCursor: (store: EventStore, runId: string) => Effect.Effect<RunCursor, EventStoreTruncationError | EventStoreTrimmedError | EventStoreError | DefinitionResolveError>;
     persistSnapshot: (store: EventStore, runId: string, cursor: RunCursor) => Effect.Effect<RunCursor>;
-    applyAppend: (store: EventStore, runId: string, cursor: RunCursor, batch: ReadonlyArray<AppendableEvent>, appendResult: AppendResult, commandRecords?: number) => Effect.Effect<RunCursor, EventStoreTruncationError | EventStoreTrimmedError | EventStoreError>;
+    applyAppend: (store: EventStore, runId: string, cursor: RunCursor, batch: ReadonlyArray<AppendableEvent>, appendResult: AppendResult, commandRecords?: number) => Effect.Effect<RunCursor, EventStoreTruncationError | EventStoreTrimmedError | EventStoreError | DefinitionResolveError>;
     deleteCachedCursor: (runId: string) => void;
     setCachedCursor: (runId: string, cursor: RunCursor) => void;
 };

package/dist/runtime/repository.js

@@ -1,5 +1,5 @@
 import { Clock, Data, Effect, Option } from 'effect';
-import { advanceCursor, assignSequences, createCoalescingAppender, emptyCursor, EventStoreTrimmedError, hashRunState, summarizeRun, trimEventStoreSafely, } from '@swirls/looms/core';
+import { advanceCursor, assignSequences, createCoalescingAppender, emptyCursor, EventStoreTrimmedError, hashRunState, primePinnedDefinitions, summarizeRun, trimEventStoreSafely, } from '@swirls/looms/core';
 import { RuntimeExecutionError } from './errors.js';
 import { stripSeq } from './helpers.js';
 import { notifyObserver } from './observer.js';
@@ -35,7 +35,7 @@ function readRemaining(store, runId, events, expectedTail) {
     });
 }
 export function createRuntimeRepository(options) {
-    const { registry, snapshotStore, trimAfterSnapshot, keepSnapshots, runCache, executionContexts } = options;
+    const { registry, snapshotStore, trimAfterSnapshot, keepSnapshots, runCache, executionContexts, definitionResolver, } = options;
     const headerFingerprints = new Map();
     const observe = (event) => notifyObserver(options.observer, event);
     const rememberHeader = (state) => {
@@ -99,6 +99,7 @@ export function createRuntimeRepository(options) {
             }
         }
         delta = yield* readRemaining(store, runId, delta, expectedTail);
+        yield* primePinnedDefinitions(definitionResolver, delta);
         return advanceCursor(cursor, delta, registry);
     });
     const loadCursorCold = (store, runId) => Effect.gen(function* () {
@@ -155,6 +156,7 @@ export function createRuntimeRepository(options) {
         if (delta.length > 0) {
             delta = yield* readRemaining(store, runId, delta);
         }
+        yield* primePinnedDefinitions(definitionResolver, delta);
         return advanceCursor(cursor, delta, registry);
     });
     const loadCursor = (store, runId) => Effect.gen(function* () {
@@ -249,6 +251,7 @@ export function createRuntimeRepository(options) {
                 next = yield* catchUp(store, runId, cursor, first.seq - 1);
             }
         }
+        yield* primePinnedDefinitions(definitionResolver, echo);
         next = advanceCursor(next, echo, registry);
         executionContexts.get(runId).liveCount = 0;
         if (next.seq !== appendResult.tail) {

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

@@ -1,5 +1,7 @@
 import { type EventEnvelope, type EventOrigin, type OutstandingEffect, type RetryPolicy } from '@swirls/looms/core';
 export declare function retryBackoff(retry: RetryPolicy, attempt: number): number;
+/** Policy backoff, extended when the failed attempt asked to wait longer. */
+export declare function retryDelay(retry: RetryPolicy, attempt: number, retryAfterMs?: number): number;
 export interface AttemptFailurePlan {
     readonly event: EventEnvelope;
     readonly retrying: boolean;
@@ -13,4 +15,7 @@ export declare function planAttemptFailure(input: {
     readonly now: number;
     readonly retry: RetryPolicy | undefined;
     readonly origin: EventOrigin;
+    /** Customer/domain failures must not be retried even when attempts remain. */
+    readonly nonRetryable?: boolean;
+    readonly retryAfterMs?: number;
 }): AttemptFailurePlan;

package/dist/runtime/retry-policy.js

@@ -5,10 +5,18 @@ export function retryBackoff(retry, attempt) {
     const multiplier = Math.max(1, retry.backoffMultiplier ?? 2);
     return Math.min(base * multiplier ** Math.max(0, attempt - 1), retry.maxBackoffMs ?? Number.MAX_SAFE_INTEGER);
 }
+/** Policy backoff, extended when the failed attempt asked to wait longer. */
+export function retryDelay(retry, attempt, retryAfterMs) {
+    const backoff = retryBackoff(retry, attempt);
+    if (retryAfterMs === undefined || !Number.isFinite(retryAfterMs) || retryAfterMs < 0) {
+        return backoff;
+    }
+    return Math.max(backoff, retryAfterMs);
+}
 /** Schedule the next attempt when the retry policy allows one, otherwise fail the effect. */
 export function planAttemptFailure(input) {
     const { runId, item, attempt, error, retry } = input;
-    if (!retry || attempt >= retry.maxAttempts) {
+    if (input.nonRetryable || !retry || attempt >= retry.maxAttempts) {
         return { event: createEffectFailedEvent(runId, item, error), retrying: false };
     }
     return {
@@ -18,7 +26,7 @@ export function planAttemptFailure(input) {
             payload: {
                 effectId: item.effectId,
                 attempt,
-                nextAttemptAt: input.now + retryBackoff(retry, attempt),
+                nextAttemptAt: input.now + retryDelay(retry, attempt, input.retryAfterMs),
                 error,
             },
             threadId: item.threadId,

package/dist/runtime/run-start.d.ts

@@ -1,4 +1,4 @@
 import { Effect } from 'effect';
-import type { RunState } from '@swirls/looms/core';
+import { type RunState } from '@swirls/looms/core';
 import { RuntimeExecutionError, StartRunConflictError, type RunStartIdentity } from './errors';
 export declare function assertSameDurableStart(runId: string, state: RunState, requested: RunStartIdentity): Effect.Effect<string, RuntimeExecutionError | StartRunConflictError>;

package/dist/runtime/run-start.js

@@ -1,4 +1,5 @@
 import { Effect, Predicate } from 'effect';
+import { sameStringRecord } from '@swirls/looms/core';
 import { RuntimeExecutionError, StartRunConflictError } from './errors.js';
 function canonicalJson(value) {
     if (Array.isArray(value)) {
@@ -36,6 +37,15 @@ export function assertSameDurableStart(runId, state, requested) {
     if (existing.idempotencyKey !== requested.idempotencyKey) {
         mismatches.push('idempotencyKey');
     }
+    if (canonicalJson(existing.launchedBy ?? null) !== canonicalJson(requested.launchedBy ?? null)) {
+        mismatches.push('launchedBy');
+    }
+    if (existing.correlationId !== requested.correlationId) {
+        mismatches.push('correlationId');
+    }
+    if (!sameStringRecord(existing.attributes ?? {}, requested.attributes)) {
+        mismatches.push('attributes');
+    }
     return mismatches.length > 0
         ? Effect.fail(new StartRunConflictError(runId, requested, existing, mismatches))
         : Effect.succeed(existing.rootThreadId);

package/dist/runtime/runtime.d.ts

@@ -4,7 +4,7 @@ export type { WakeScheduler } from './wake-scheduler';
 export { createTimeoutScheduler } from './wake-scheduler';
 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';
+export type { CreateRuntimeOptions, EffectWorker, EffectWorkerDeadlines, EffectWorkerTask, LoomsRuntime, RunOperationalStatus, StartResult, StartRunArgs, WakeError, } from './types';
+export type { WorkerCallback, WorkerCallbackInput, WorkerCallbackResult } from '@swirls/looms/core';
 import type { CreateRuntimeOptions, LoomsRuntime } from './types';
 export declare function createRuntime<const TModules extends readonly AnyRuntimeModule[]>(options: CreateRuntimeOptions<TModules>): LoomsRuntime<TModules>;