@swirls/looms 0.4.0 → 0.5.0

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>;