@lostgradient/weft 0.2.0

package/dist/core/inline-execution-strategy.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Inline execution strategy: runs workflows on the main thread.
+ *
+ * This strategy drives async generators directly in the calling context,
+ * emitting {@link WorkerOutboundMessage} to the engine via a callback.
+ * It is the default execution model and preserves the original behavior
+ * where the engine manages generators, abort controllers, and contexts
+ * in-process.
+ *
+ * @module core/inline-execution-strategy
+ */
+import { Context } from './context.ts';
+import type { ExecutionStrategy } from './execution-strategy.ts';
+import type { ComposedWorkflowInterceptor } from './interceptor.ts';
+import type { FailureCategory, OperationOutcome, SearchAttributeSchema, WorkerOutboundMessage, WorkflowFunction } from './types.ts';
+export interface InlineExecutionDependencies {
+    getRegistration: (workflowType: string) => {
+        handler: WorkflowFunction;
+        version: string;
+        searchAttributes?: SearchAttributeSchema;
+    } | undefined;
+    getNow: () => number;
+    resolveWorkflowType?: (target: string | Function) => string;
+    maxNestingDepth: number;
+    development?: boolean;
+    getComposedWorkflowInterceptor?: () => ComposedWorkflowInterceptor | null;
+    registerCancelHandler?: (workflowId: string, handler: () => Promise<void> | void) => () => void;
+}
+type InlineStartWorkflowParameters = {
+    workflowId: string;
+    workflowType: string;
+    input: unknown;
+    checkpoint: ArrayBuffer | Uint8Array;
+    nestingDepth?: number;
+    executionStateOwnerId?: string;
+    startedAt?: number;
+    sleepReferenceTime?: number;
+    deadline?: number;
+    headers?: [string, string][];
+};
+export declare class InlineExecutionStrategy implements ExecutionStrategy {
+    #private;
+    constructor(dependencies: InlineExecutionDependencies);
+    onMessage(handler: (message: WorkerOutboundMessage) => void | Promise<void>): void;
+    startWorkflow(parameters: InlineStartWorkflowParameters): void;
+    resumeWorkflow(parameters: {
+        workflowId: string;
+        checkpoint: ArrayBuffer | Uint8Array;
+        operationResult: OperationOutcome;
+    }): void;
+    cancelWorkflow(workflowId: string): void;
+    parkWorkflow(workflowId: string): void;
+    getContext(workflowId: string): Context | undefined;
+    getAbortController(workflowId: string): AbortController | undefined;
+    waitForWorkflowTurn(workflowId: string): Promise<void> | undefined;
+    waitForWorkflowAdvance(workflowId: string): Promise<void> | undefined;
+    hasGenerator(workflowId: string): boolean;
+    /**
+     * Resume the generator with a value (used by the engine after inline
+     * operation processing like timers, signals, etc.).
+     */
+    continueWorkflow(workflowId: string, value: unknown): void;
+    /**
+     * Throw an error into the generator (used by the engine for propagating
+     * activity failures, etc.).
+     */
+    throwIntoWorkflow(workflowId: string, error: unknown, operationFailureCategory?: FailureCategory): void;
+    /**
+     * Store a context and generator that were created externally (used by
+     * the engine's resume() path where context setup is more complex).
+     */
+    adoptWorkflow(workflowId: string, generator: AsyncGenerator, context: Context, abortController: AbortController): void;
+    [Symbol.dispose](): void;
+    [Symbol.asyncDispose](): Promise<void>;
+}
+export {};

package/dist/core/inline-execution-strategy.js

@@ -0,0 +1,264 @@
+import { Context, setContextWorkflowInterceptor } from "./context.js";
+import {
+  classifyErrorAsFailureCategory,
+  errorFromFailedOperationOutcome
+} from "./failure-categories.js";
+function createInlineContextOptions(dependencies, registration, parameters, workflowAbort) {
+  const { registerCancelHandler } = dependencies;
+  return {
+    workflowId: parameters.workflowId,
+    workflowType: parameters.workflowType,
+    startedAt: parameters.startedAt ?? dependencies.getNow(),
+    abortController: workflowAbort,
+    getNow: dependencies.getNow,
+    nestingDepth: parameters.nestingDepth ?? 0,
+    executionStateOwnerId: parameters.executionStateOwnerId ?? parameters.workflowId,
+    ...parameters.sleepReferenceTime !== void 0 && {
+      sleepReferenceTime: parameters.sleepReferenceTime
+    },
+    ...dependencies.resolveWorkflowType !== void 0 && {
+      resolveWorkflowType: dependencies.resolveWorkflowType
+    },
+    ...registration.searchAttributes && {
+      searchAttributeSchema: registration.searchAttributes
+    },
+    ...parameters.deadline !== void 0 && { deadline: parameters.deadline },
+    ...registerCancelHandler !== void 0 && {
+      registerCancelHandler: (handler) => registerCancelHandler(parameters.workflowId, handler)
+    }
+  };
+}
+
+export class InlineExecutionStrategy {
+  #dependencies;
+  #generators;
+  #abortControllers;
+  #contexts;
+  #workflowAdvances;
+  #workflowTurns;
+  #messageHandler;
+  constructor(dependencies) {
+    this.#dependencies = dependencies;
+    this.#generators = new Map;
+    this.#abortControllers = new Map;
+    this.#contexts = new Map;
+    this.#workflowAdvances = new Map;
+    this.#workflowTurns = new Map;
+    this.#messageHandler = null;
+  }
+  onMessage(handler) {
+    this.#messageHandler = handler;
+  }
+  startWorkflow(parameters) {
+    const registration = this.#dependencies.getRegistration(parameters.workflowType);
+    if (!registration) {
+      this.#emit({
+        type: "failed",
+        workflowId: parameters.workflowId,
+        error: `No workflow registered with name "${parameters.workflowType}"`
+      });
+      return;
+    }
+    const workflowAbort = new AbortController;
+    this.#abortControllers.set(parameters.workflowId, workflowAbort);
+    const context = new Context(createInlineContextOptions(this.#dependencies, registration, parameters, workflowAbort)), workflowInterceptor = this.#dependencies.getComposedWorkflowInterceptor?.() ?? null;
+    setContextWorkflowInterceptor(context, workflowInterceptor);
+    if (this.#dependencies.development)
+      context.explain(!0);
+    this.#contexts.set(parameters.workflowId, context);
+    const generator = registration.handler(context, parameters.input);
+    this.#generators.set(parameters.workflowId, generator);
+    this.#driveGenerator(parameters.workflowId, generator, void 0);
+  }
+  resumeWorkflow(parameters) {
+    const generator = this.#generators.get(parameters.workflowId);
+    if (!generator) {
+      this.#emit({
+        type: "failed",
+        workflowId: parameters.workflowId,
+        error: `No active generator for workflow: ${parameters.workflowId}`
+      });
+      return;
+    }
+    const result = parameters.operationResult.status === "completed" ? parameters.operationResult.value : void 0, operationFailureCategory = parameters.operationResult.status === "failed" ? parameters.operationResult.failureCategory : void 0, error = parameters.operationResult.status === "failed" ? errorFromFailedOperationOutcome(parameters.operationResult) : void 0;
+    if (error)
+      this.#throwIntoGenerator(parameters.workflowId, generator, error, operationFailureCategory);
+    else
+      this.#driveGenerator(parameters.workflowId, generator, result);
+  }
+  cancelWorkflow(workflowId) {
+    const abortController = this.#abortControllers.get(workflowId);
+    if (abortController)
+      abortController.abort();
+    this.#cleanup(workflowId);
+  }
+  parkWorkflow(workflowId) {
+    this.#cleanup(workflowId);
+  }
+  getContext(workflowId) {
+    return this.#contexts.get(workflowId);
+  }
+  getAbortController(workflowId) {
+    return this.#abortControllers.get(workflowId);
+  }
+  waitForWorkflowTurn(workflowId) {
+    return this.#workflowTurns.get(workflowId);
+  }
+  waitForWorkflowAdvance(workflowId) {
+    return this.#workflowAdvances.get(workflowId);
+  }
+  hasGenerator(workflowId) {
+    return this.#generators.has(workflowId);
+  }
+  continueWorkflow(workflowId, value) {
+    const generator = this.#generators.get(workflowId);
+    if (!generator)
+      return;
+    this.#driveGenerator(workflowId, generator, value);
+  }
+  throwIntoWorkflow(workflowId, error, operationFailureCategory) {
+    const generator = this.#generators.get(workflowId);
+    if (!generator)
+      return;
+    this.#throwIntoGenerator(workflowId, generator, error, operationFailureCategory);
+  }
+  adoptWorkflow(workflowId, generator, context, abortController) {
+    this.#generators.set(workflowId, generator);
+    this.#contexts.set(workflowId, context);
+    this.#abortControllers.set(workflowId, abortController);
+  }
+  [Symbol.dispose]() {
+    this.#generators.clear();
+    this.#abortControllers.clear();
+    this.#contexts.clear();
+    this.#workflowAdvances.clear();
+    this.#workflowTurns.clear();
+    this.#messageHandler = null;
+  }
+  async[Symbol.asyncDispose]() {
+    this[Symbol.dispose]();
+  }
+  #driveGenerator(workflowId, generator, lastResult) {
+    return this.#trackWorkflowAdvance(workflowId, (async () => {
+      try {
+        if (this.#abortControllers.get(workflowId)?.signal.aborted)
+          return;
+        const iterationResult = await generator.next(lastResult);
+        if (iterationResult.done) {
+          this.#cleanup(workflowId, {
+            preserveTrackedAdvance: !0,
+            preserveTrackedTurn: !0
+          });
+          this.#emit({
+            type: "completed",
+            workflowId,
+            result: iterationResult.value
+          });
+          return;
+        }
+        const operation = iterationResult.value;
+        this.#emit({
+          type: "checkpoint",
+          workflowId,
+          checkpoint: new ArrayBuffer(0),
+          operationRequest: operation
+        });
+      } catch (error) {
+        this.#cleanup(workflowId, {
+          preserveTrackedAdvance: !0,
+          preserveTrackedTurn: !0
+        });
+        const failedMessage = {
+          type: "failed",
+          workflowId,
+          error: error instanceof Error ? error.message : String(error),
+          failureCategory: classifyErrorAsFailureCategory(error, {
+            defaultErrorCategory: "application"
+          })
+        };
+        if (error instanceof Error && error.stack !== void 0)
+          failedMessage.errorStack = error.stack;
+        this.#emit(failedMessage);
+      }
+    })());
+  }
+  #throwIntoGenerator(workflowId, generator, error, operationFailureCategory) {
+    return this.#trackWorkflowAdvance(workflowId, (async () => {
+      try {
+        if (this.#abortControllers.get(workflowId)?.signal.aborted)
+          return;
+        const iterationResult = await generator.throw(error);
+        if (iterationResult.done) {
+          this.#cleanup(workflowId, {
+            preserveTrackedAdvance: !0,
+            preserveTrackedTurn: !0
+          });
+          this.#emit({
+            type: "completed",
+            workflowId,
+            result: iterationResult.value
+          });
+          return;
+        }
+        const operation = iterationResult.value;
+        this.#emit({
+          type: "checkpoint",
+          workflowId,
+          checkpoint: new ArrayBuffer(0),
+          operationRequest: operation
+        });
+      } catch (innerError) {
+        this.#cleanup(workflowId, {
+          preserveTrackedAdvance: !0,
+          preserveTrackedTurn: !0
+        });
+        const failedMessage = {
+          type: "failed",
+          workflowId,
+          error: innerError instanceof Error ? innerError.message : String(innerError),
+          failureCategory: operationFailureCategory ?? classifyErrorAsFailureCategory(innerError, {
+            defaultErrorCategory: "application"
+          })
+        };
+        if (innerError instanceof Error && innerError.stack !== void 0)
+          failedMessage.errorStack = innerError.stack;
+        this.#emit(failedMessage);
+      }
+    })());
+  }
+  #trackWorkflowAdvance(workflowId, pendingAdvance) {
+    const trackedAdvance = pendingAdvance.finally(() => {
+      if (this.#workflowAdvances.get(workflowId) === trackedAdvance)
+        this.#workflowAdvances.delete(workflowId);
+    });
+    trackedAdvance.catch(() => {});
+    this.#workflowAdvances.set(workflowId, trackedAdvance);
+    return trackedAdvance;
+  }
+  #trackWorkflowTurn(workflowId, pendingTurn) {
+    const trackedTurn = pendingTurn.finally(() => {
+      if (this.#workflowTurns.get(workflowId) === trackedTurn)
+        this.#workflowTurns.delete(workflowId);
+    });
+    trackedTurn.catch(() => {});
+    this.#workflowTurns.set(workflowId, trackedTurn);
+    return trackedTurn;
+  }
+  #emit(message) {
+    const result = this.#messageHandler?.(message);
+    if (result instanceof Promise) {
+      this.#trackWorkflowTurn(message.workflowId, result);
+      return;
+    }
+    this.#workflowTurns.delete(message.workflowId);
+  }
+  #cleanup(workflowId, options) {
+    this.#generators.delete(workflowId);
+    this.#abortControllers.delete(workflowId);
+    this.#contexts.delete(workflowId);
+    if (!options?.preserveTrackedAdvance)
+      this.#workflowAdvances.delete(workflowId);
+    if (!options?.preserveTrackedTurn)
+      this.#workflowTurns.delete(workflowId);
+  }
+}

package/dist/core/interceptor/activity-composition.d.ts

@@ -0,0 +1,20 @@
+import type { ActivityInterceptor, ComposedActivityInterceptor } from './interceptor-interfaces.ts';
+/**
+ * Compose multiple activity interceptors into a single interceptor chain.
+ *
+ * @example
+ * ```ts
+ * import { composeActivityInterceptors, type ActivityInterceptor } from '@lostgradient/weft';
+ *
+ * const retryLogger: ActivityInterceptor = {
+ *   async execute(ctx, next) {
+ *     const result = await next(ctx);
+ *     console.log(ctx.activityName, 'attempt', ctx.attempt, 'succeeded');
+ *     return result;
+ *   },
+ * };
+ * const composed = composeActivityInterceptors([retryLogger]);
+ * void composed;
+ * ```
+ */
+export declare function composeActivityInterceptors(interceptors: ActivityInterceptor[]): ComposedActivityInterceptor;

package/dist/core/interceptor/activity-composition.js

@@ -0,0 +1,17 @@
+export function composeActivityInterceptors(interceptors) {
+  return {
+    async execute(interception, execute) {
+      let chain = execute;
+      for (let i = interceptors.length - 1;i >= 0; i--) {
+        const interceptor = interceptors[i];
+        if (interceptor.execute) {
+          const innerNext = chain, bound = interceptor.execute.bind(interceptor);
+          chain = (ctx) => {
+            return bound(ctx, innerNext);
+          };
+        }
+      }
+      return chain(interception);
+    }
+  };
+}

package/dist/core/interceptor/index.d.ts

@@ -0,0 +1,25 @@
+import type { Interceptor } from './interceptor-interfaces.ts';
+export * from './activity-composition.ts';
+export * from './interception-contexts.ts';
+export * from './interceptor-interfaces.ts';
+export * from './split.ts';
+export * from './workflow-composition.ts';
+/**
+ * Create an interceptor with inference preserved at the declaration site.
+ * The optional `name` field is carried for observability and diagnostics.
+ *
+ * @example
+ * ```ts
+ * import { interceptor } from '@lostgradient/weft';
+ *
+ * const tracer = interceptor({
+ *   name: 'tracer',
+ *   *activity(ctx, next) {
+ *     return yield* next(ctx);
+ *   },
+ * });
+ * ```
+ */
+export declare function interceptor<TInterceptor extends Interceptor & {
+    readonly name?: string;
+}>(spec: TInterceptor): TInterceptor;

package/dist/core/interceptor/index.js

@@ -0,0 +1,8 @@
+export * from "./activity-composition.js";
+export * from "./interception-contexts.js";
+export * from "./interceptor-interfaces.js";
+export * from "./split.js";
+export * from "./workflow-composition.js";
+export function interceptor(spec) {
+  return spec;
+}

package/dist/core/interceptor/interception-contexts.d.ts

@@ -0,0 +1,200 @@
+/**
+ * Context object passed to workflow interceptors when an activity is scheduled.
+ * Read-only snapshot of the activity call — modify via the `next` callback.
+ *
+ * @example
+ * ```ts
+ * import { Engine, type ActivityInterception } from '@lostgradient/weft';
+ * import type { WorkflowInterceptor } from '@lostgradient/weft';
+ *
+ * const loggingInterceptor: WorkflowInterceptor = {
+ *   *activity(ctx: ActivityInterception, next) {
+ *     console.log('activity:', ctx.activityName, 'attempt:', ctx.attempt);
+ *     return yield* next(ctx);
+ *   },
+ * };
+ * // const engine = new Engine(); engine.addInterceptor(loggingInterceptor);
+ * void loggingInterceptor;
+ * ```
+ */
+export interface ActivityInterception {
+    workflowId: string;
+    activityName: string;
+    input: unknown;
+    attempt: number;
+    headers: Map<string, string>;
+}
+/**
+ * Context object passed to a workflow interceptor's `sleep` hook. Contains the
+ * workflow ID, the requested sleep duration in milliseconds, and the outgoing
+ * headers map. Modify headers inside the hook to propagate trace context.
+ *
+ * @example
+ * ```ts
+ * import { Engine, type SleepInterception } from '@lostgradient/weft';
+ * import type { WorkflowInterceptor } from '@lostgradient/weft';
+ *
+ * const tracer: WorkflowInterceptor = {
+ *   *sleep(ctx: SleepInterception, next) {
+ *     console.log('sleep', ctx.duration, 'ms for', ctx.workflowId);
+ *     return yield* next(ctx);
+ *   },
+ * };
+ * void tracer;
+ * ```
+ */
+export interface SleepInterception {
+    workflowId: string;
+    duration: number;
+    headers: Map<string, string>;
+}
+/**
+ * Context object passed to a workflow interceptor's `waitForSignal` hook.
+ * Contains the workflow ID, signal name, optional payload, and outgoing headers.
+ *
+ * @example
+ * ```ts
+ * import { type SignalInterception, type WorkflowInterceptor } from '@lostgradient/weft';
+ *
+ * const tracer: WorkflowInterceptor = {
+ *   *waitForSignal(ctx: SignalInterception, next) {
+ *     console.log('waiting for signal', ctx.signalName);
+ *     return yield* next(ctx);
+ *   },
+ * };
+ * void tracer;
+ * ```
+ */
+export interface SignalInterception {
+    workflowId: string;
+    signalName: string;
+    payload: unknown;
+    headers: Map<string, string>;
+}
+/**
+ * Context object passed to a workflow interceptor's `workflowStart` hook when
+ * a new workflow begins executing. Useful for injecting trace headers or
+ * enforcing policies at start time.
+ *
+ * @example
+ * ```ts
+ * import { type WorkflowStartInterception, type WorkflowInterceptor } from '@lostgradient/weft';
+ *
+ * const tracer: WorkflowInterceptor = {
+ *   workflowStart(ctx: WorkflowStartInterception, next) {
+ *     ctx.headers.set('x-trace-id', crypto.randomUUID());
+ *     next(ctx);
+ *   },
+ * };
+ * void tracer;
+ * ```
+ */
+export interface WorkflowStartInterception {
+    workflowId: string;
+    workflowType: string;
+    input: unknown;
+    headers: Map<string, string>;
+}
+/**
+ * Context object passed to an {@link ActivityInterceptor}'s `execute` hook
+ * during activity execution. Provides the activity name, input, attempt count,
+ * headers, and optional cancellation signal for remote-worker execution.
+ *
+ * @example
+ * ```ts
+ * import { type ActivityExecutionInterception, type ActivityInterceptor } from '@lostgradient/weft';
+ *
+ * const logger: ActivityInterceptor = {
+ *   async execute(ctx: ActivityExecutionInterception, next) {
+ *     console.log('executing', ctx.activityName, 'attempt', ctx.attempt);
+ *     const result = await next(ctx);
+ *     return result;
+ *   },
+ * };
+ * void logger;
+ * ```
+ */
+export interface ActivityExecutionInterception {
+    activityName: string;
+    input: unknown;
+    attempt: number;
+    headers: Map<string, string>;
+    /** Operation identifier, available when executing on a remote worker. */
+    operationId?: string;
+    /** Abort signal for cancellation, available when executing on a remote worker. */
+    signal?: AbortSignal;
+}
+/**
+ * Context object passed to a workflow interceptor's `childWorkflow` hook when
+ * a workflow spawns a child via `ctx.pipe`, `ctx.map`, or `ctx.reduce`.
+ * Includes both the child's own headers and the parent's headers for trace
+ * span linking.
+ *
+ * @example
+ * ```ts
+ * import { type ChildWorkflowInterception, type WorkflowInterceptor } from '@lostgradient/weft';
+ *
+ * const tracer: WorkflowInterceptor = {
+ *   async childWorkflow(ctx: ChildWorkflowInterception, next) {
+ *     console.log('spawning child', ctx.childWorkflowId, 'type:', ctx.workflowType);
+ *     return next(ctx);
+ *   },
+ * };
+ * void tracer;
+ * ```
+ */
+export interface ChildWorkflowInterception {
+    workflowId: string;
+    childWorkflowId: string;
+    workflowType: string;
+    input: unknown;
+    headers: Map<string, string>;
+    /** Headers from the parent workflow, used for span link creation. */
+    parentHeaders: Map<string, string>;
+}
+/**
+ * Context object passed to a workflow interceptor's `query` hook when a
+ * query is evaluated. Modify `headers` to propagate trace context; read
+ * `queryName` for logging.
+ *
+ * @example
+ * ```ts
+ * import { type QueryInterception, type WorkflowInterceptor } from '@lostgradient/weft';
+ *
+ * const tracer: WorkflowInterceptor = {
+ *   *query(ctx: QueryInterception, next) {
+ *     console.log('query:', ctx.queryName);
+ *     return yield* next(ctx);
+ *   },
+ * };
+ * void tracer;
+ * ```
+ */
+export interface QueryInterception {
+    queryName: string;
+    headers: Map<string, string>;
+}
+/**
+ * Context object passed to a workflow interceptor's `signalReceived` hook
+ * when an inbound signal arrives at the workflow. Allows interceptors to
+ * inspect or modify the payload before the workflow handler processes it.
+ *
+ * @example
+ * ```ts
+ * import { type SignalReceivedInterception, type WorkflowInterceptor } from '@lostgradient/weft';
+ *
+ * const tracer: WorkflowInterceptor = {
+ *   signalReceived(ctx: SignalReceivedInterception, next) {
+ *     console.log('signal received:', ctx.signalName, 'for', ctx.workflowId);
+ *     next(ctx);
+ *   },
+ * };
+ * void tracer;
+ * ```
+ */
+export interface SignalReceivedInterception {
+    workflowId: string;
+    signalName: string;
+    payload: unknown;
+    headers: Map<string, string>;
+}