@lostgradient/weft 0.2.0

package/dist/workers/pool.js

@@ -0,0 +1,174 @@
+export class WorkerPool {
+  #workers;
+  #available;
+  #queue;
+  #specificWorkerQueue;
+  #concurrency;
+  #workerUrl;
+  #smol;
+  #disposed;
+  #asyncDisposeResolve;
+  constructor(options) {
+    this.#workers = new Set;
+    this.#available = [];
+    this.#queue = [];
+    this.#specificWorkerQueue = new Map;
+    this.#concurrency = options.concurrency;
+    this.#workerUrl = options.workerUrl;
+    this.#smol = options.smol ?? !1;
+    this.#disposed = !1;
+    this.#asyncDisposeResolve = null;
+  }
+  async acquire() {
+    if (this.#disposed)
+      throw Error("WorkerPool has been disposed");
+    const available = this.#available.pop();
+    if (available)
+      return available;
+    if (this.#workers.size < this.#concurrency)
+      return this.#createWorker();
+    return new Promise((resolve, reject) => {
+      this.#queue.push({ resolve, reject });
+    });
+  }
+  async acquireSpecificWorker(worker) {
+    if (this.#disposed)
+      throw Error("WorkerPool has been disposed");
+    if (!this.#workers.has(worker))
+      throw Error("Worker does not belong to this WorkerPool");
+    const availableIndex = this.#available.indexOf(worker);
+    if (availableIndex >= 0) {
+      this.#available.splice(availableIndex, 1);
+      return worker;
+    }
+    return new Promise((resolve, reject) => {
+      const waiters = this.#specificWorkerQueue.get(worker) ?? [];
+      waiters.push({ resolve, reject });
+      this.#specificWorkerQueue.set(worker, waiters);
+    });
+  }
+  discard(worker) {
+    if (!this.#workers.has(worker))
+      return;
+    this.#workers.delete(worker);
+    this.#removeAvailableWorker(worker);
+    this.#rejectSpecificWorkerWaiters(worker, Error("Worker was discarded from this WorkerPool"));
+    worker.terminate();
+    this.#drainGenericQueue();
+    this.#checkAsyncDispose();
+  }
+  release(worker) {
+    if (this.#disposed && !this.#asyncDisposeResolve)
+      return;
+    const specificPending = this.#specificWorkerQueue.get(worker);
+    if (specificPending && specificPending.length > 0) {
+      const pending = specificPending.shift();
+      if (specificPending.length === 0)
+        this.#specificWorkerQueue.delete(worker);
+      pending.resolve(worker);
+      return;
+    }
+    const pending = this.#queue.shift();
+    if (pending) {
+      pending.resolve(worker);
+      return;
+    }
+    this.#available.push(worker);
+    this.#checkAsyncDispose();
+  }
+  get availableCount() {
+    return this.#available.length;
+  }
+  get totalCount() {
+    return this.#workers.size;
+  }
+  get pendingCount() {
+    let specificPendingCount = 0;
+    for (const waiters of this.#specificWorkerQueue.values())
+      specificPendingCount += waiters.length;
+    return this.#queue.length + specificPendingCount;
+  }
+  [Symbol.dispose]() {
+    if (this.#disposed)
+      return;
+    this.#disposed = !0;
+    this.#terminateAll();
+  }
+  async[Symbol.asyncDispose]() {
+    if (this.#disposed)
+      return;
+    this.#disposed = !0;
+    this.#rejectAllWaiters(Error("WorkerPool has been disposed"));
+    if (this.#available.length === this.#workers.size) {
+      this.#terminateAll();
+      return;
+    }
+    return new Promise((resolve) => {
+      this.#asyncDisposeResolve = () => {
+        this.#terminateAll();
+        resolve();
+      };
+    });
+  }
+  #createWorker() {
+    const options = {};
+    if (this.#smol)
+      options.smol = !0;
+    const worker = new Worker(this.#workerUrl, options);
+    this.#workers.add(worker);
+    return worker;
+  }
+  #terminateAll() {
+    this.#rejectAllWaiters(Error("WorkerPool has been disposed"));
+    for (const worker of this.#workers)
+      worker.terminate();
+    this.#workers.clear();
+    this.#available.length = 0;
+    this.#queue.length = 0;
+    this.#specificWorkerQueue.clear();
+  }
+  #removeAvailableWorker(worker) {
+    const availableIndex = this.#available.indexOf(worker);
+    if (availableIndex >= 0)
+      this.#available.splice(availableIndex, 1);
+  }
+  #rejectSpecificWorkerWaiters(worker, error) {
+    const waiters = this.#specificWorkerQueue.get(worker);
+    if (!waiters)
+      return;
+    this.#specificWorkerQueue.delete(worker);
+    for (const waiter of waiters)
+      waiter.reject(error);
+  }
+  #rejectAllWaiters(error) {
+    const genericWaiters = this.#queue.splice(0);
+    for (const waiter of genericWaiters)
+      waiter.reject(error);
+    for (const waiters of this.#specificWorkerQueue.values())
+      for (const waiter of waiters)
+        waiter.reject(error);
+    this.#specificWorkerQueue.clear();
+  }
+  #drainGenericQueue() {
+    if (this.#disposed)
+      return;
+    while (this.#queue.length > 0) {
+      const available = this.#available.shift();
+      if (available) {
+        this.#queue.shift()?.resolve(available);
+        continue;
+      }
+      if (this.#workers.size < this.#concurrency) {
+        this.#queue.shift()?.resolve(this.#createWorker());
+        continue;
+      }
+      return;
+    }
+  }
+  #checkAsyncDispose() {
+    if (this.#asyncDisposeResolve && this.#available.length === this.#workers.size) {
+      this.#asyncDisposeResolve();
+      this.#asyncDisposeResolve = null;
+    }
+  }
+}

package/dist/workers/workflow-runner.d.ts

@@ -0,0 +1,79 @@
+import type { Checkpoint, OperationOutcome, WorkerOutboundMessage, WorkerReplayOperationFailure, WorkflowContext, WorkflowStateNamespace } from '../core/types.ts';
+import { type WorkerReplayOperationSignature } from '../core/worker-protocol.ts';
+/**
+ * Subset of {@link WorkflowContext} that the worker-side runner can build
+ * locally from the `run` message. Engine-side fields (`executionTimeRemaining`
+ * in particular) are stub values because the worker has no clock authority —
+ * any user code reading them will see static numbers, not live deadlines.
+ */
+export type WorkerWorkflowContext = Pick<WorkflowContext, 'workflowId' | 'signal' | 'startedAt'> & {
+    readonly state: WorkflowStateNamespace;
+};
+interface RunMessageShape {
+    workflowId: string;
+    workflowType: string;
+    input: unknown;
+    executionStateOwnerId?: string;
+    deadline?: number;
+    headers?: [string, string][];
+}
+/**
+ * Construct the worker-side `ctx` argument that gets passed as the first
+ * positional parameter to a registered workflow handler. Engine-side fields
+ * not represented in the `run` message are intentionally omitted — only the
+ * `Pick`-ed subset above is populated.
+ */
+export declare function createWorkerWorkflowContext(message: RunMessageShape, controller: AbortController): WorkerWorkflowContext;
+export interface WorkflowRunnerContext {
+    generators: Map<string, AsyncGenerator>;
+    abortControllers: Map<string, AbortController>;
+    replayStates: Map<string, WorkerReplayState>;
+}
+interface WorkerReplayState {
+    checkpoint: Checkpoint;
+    accumulatedResults: Map<number, unknown>;
+    signatures: Map<number, WorkerReplayOperationSignature>;
+    failedOutcomes: Map<number, WorkerReplayOperationFailure>;
+    nextStepIndex: number;
+    pendingStepIndex: number | null;
+    maxProtocolMessageBytes: number | undefined;
+}
+export declare function createWorkflowRunnerContext(): WorkflowRunnerContext;
+export declare function handleRunMessage(context: WorkflowRunnerContext, message: {
+    workflowId: string;
+    workflowType: string;
+    input: unknown;
+    checkpoint?: ArrayBuffer;
+    maxProtocolMessageBytes?: number;
+    executionStateOwnerId?: string;
+    deadline?: number;
+    headers?: [string, string][];
+}, getWorkflowHandler: (type: string) => ((ctx: WorkerWorkflowContext, input: unknown) => AsyncGenerator) | undefined): Promise<WorkerOutboundMessage>;
+export declare function handleResumeMessage(context: WorkflowRunnerContext, message: {
+    workflowId: string;
+    result: unknown;
+    operationResult?: OperationOutcome;
+    maxProtocolMessageBytes?: number;
+}): Promise<WorkerOutboundMessage>;
+/**
+ * Handle a `cancel` message: abort the workflow's {@link AbortController},
+ * run the generator's `finally` blocks by calling `generator.return()`, and
+ * tear down the runner's in-memory state. The `return()` call is wrapped in a
+ * try/catch because a well-behaved workflow's `finally` block may still throw
+ * on cancellation (e.g. a `using` disposer), and we must never let that
+ * prevent the rest of cleanup from running.
+ *
+ * The function is async (it awaits `generator.return()` so the workflow's
+ * `finally` blocks actually complete before cleanup), which opens a narrow
+ * race window: while awaiting, the worker message loop can process another
+ * message for the same workflow ID — most dangerously a `run` that installs
+ * a brand-new generator and controller into the context maps. We must not
+ * clobber that state when this cancel handler resumes. The cleanup below
+ * therefore only deletes the cached entries if they still point at the
+ * *same* generator/controller we captured before the await.
+ */
+export declare function handleCancelMessage(context: WorkflowRunnerContext, message: {
+    workflowId: string;
+}): Promise<void>;
+export declare function cleanupWorkflowRunnerState(context: WorkflowRunnerContext, workflowId: string): void;
+export {};

package/dist/workers/workflow-runner.js

@@ -0,0 +1,245 @@
+import {
+  advanceCheckpoint,
+  createCheckpoint,
+  deserializeCheckpoint,
+  serializeCheckpoint
+} from "../core/checkpoint.js";
+import { WorkflowAtomicStateHandle } from "../core/context/state-namespace.js";
+import {
+  classifyErrorAsFailureCategory,
+  errorFromFailedOperationOutcome
+} from "../core/failure-categories.js";
+import {
+  createWorkerReplayOperationSignature,
+  workerReplayOperationSignaturesEqual
+} from "../core/worker-protocol.js";
+export function createWorkerWorkflowContext(message, controller) {
+  return {
+    workflowId: message.workflowId,
+    signal: controller.signal,
+    startedAt: Date.now(),
+    state: createWorkerStateNamespace(message)
+  };
+}
+function createWorkerStateNamespace(message) {
+  return {
+    session: (_key) => {
+      throw Error("ctx.state.session() is not supported in worker execution mode. Construct the engine without `workerExecution` to use session state.");
+    },
+    execution: (key, options) => new WorkflowAtomicStateHandle({
+      type: "execution",
+      ownerWorkflowId: message.executionStateOwnerId ?? message.workflowId
+    }, key, options),
+    workflow: (key, options) => new WorkflowAtomicStateHandle({ type: "workflow", workflowType: message.workflowType }, key, options)
+  };
+}
+export function createWorkflowRunnerContext() {
+  return {
+    generators: new Map,
+    abortControllers: new Map,
+    replayStates: new Map
+  };
+}
+export async function handleRunMessage(context, message, getWorkflowHandler) {
+  const handler = getWorkflowHandler(message.workflowType);
+  if (!handler)
+    return {
+      type: "failed",
+      workflowId: message.workflowId,
+      error: `Unknown workflow type: ${message.workflowType}`,
+      failureCategory: "system"
+    };
+  const controller = new AbortController;
+  context.abortControllers.set(message.workflowId, controller);
+  try {
+    const workerContext = createWorkerWorkflowContext(message, controller), generator = handler(workerContext, message.input);
+    context.replayStates.set(message.workflowId, createReplayState(message));
+    const step = await generator.next();
+    return await processGeneratorStep(context, message.workflowId, generator, step);
+  } catch (error) {
+    cleanupWorkflowRunnerState(context, message.workflowId);
+    return {
+      type: "failed",
+      workflowId: message.workflowId,
+      error: formatError(error),
+      failureCategory: classifyErrorAsFailureCategory(error, {
+        defaultErrorCategory: "application"
+      })
+    };
+  }
+}
+export async function handleResumeMessage(context, message) {
+  const generator = context.generators.get(message.workflowId), replayState = context.replayStates.get(message.workflowId);
+  if (!generator || !replayState)
+    return {
+      type: "failed",
+      workflowId: message.workflowId,
+      error: `No active generator for workflow: ${message.workflowId}`,
+      failureCategory: "system"
+    };
+  const outcome = operationOutcomeFromResumeMessage(message), operationFailureCategory = operationFailureCategoryFromOutcome(outcome);
+  try {
+    recordOperationOutcome(replayState, outcome);
+    if (message.maxProtocolMessageBytes !== void 0)
+      replayState.maxProtocolMessageBytes = message.maxProtocolMessageBytes;
+    const step = await resumeGeneratorWithOutcome(generator, outcome, message.result);
+    return await processGeneratorStep(context, message.workflowId, generator, step);
+  } catch (error) {
+    cleanupWorkflowRunnerState(context, message.workflowId);
+    return {
+      type: "failed",
+      workflowId: message.workflowId,
+      error: formatError(error),
+      failureCategory: operationFailureCategory ?? classifyErrorAsFailureCategory(error, { defaultErrorCategory: "application" })
+    };
+  }
+}
+function operationOutcomeFromResumeMessage(message) {
+  return message.operationResult ?? { status: "completed", value: message.result };
+}
+function operationFailureCategoryFromOutcome(outcome) {
+  return outcome.status === "failed" ? outcome.failureCategory : void 0;
+}
+async function resumeGeneratorWithOutcome(generator, outcome, result) {
+  if (outcome.status === "failed")
+    return await generator.throw(errorFromFailedOperationOutcome(outcome));
+  return await generator.next(result);
+}
+export async function handleCancelMessage(context, message) {
+  const capturedController = context.abortControllers.get(message.workflowId), capturedGenerator = context.generators.get(message.workflowId), capturedReplayState = context.replayStates.get(message.workflowId);
+  if (capturedController)
+    capturedController.abort();
+  if (capturedGenerator)
+    try {
+      await capturedGenerator.return(void 0);
+    } catch {}
+  if (context.generators.get(message.workflowId) === capturedGenerator)
+    context.generators.delete(message.workflowId);
+  if (context.abortControllers.get(message.workflowId) === capturedController)
+    context.abortControllers.delete(message.workflowId);
+  if (context.replayStates.get(message.workflowId) === capturedReplayState)
+    context.replayStates.delete(message.workflowId);
+}
+async function processGeneratorStep(context, workflowId, generator, step) {
+  const replayState = context.replayStates.get(workflowId);
+  let currentStep = step;
+  while (!0) {
+    if (currentStep.done) {
+      cleanupWorkflowRunnerState(context, workflowId);
+      return {
+        type: "completed",
+        workflowId,
+        result: currentStep.value
+      };
+    }
+    const operationRequest = currentStep.value, stepIndex = replayState.nextStepIndex, signature = await createWorkerReplayOperationSignature(operationRequest, replayState.maxProtocolMessageBytes ?? Number.MAX_SAFE_INTEGER);
+    if (hasCachedWorkerOutcome(replayState, stepIndex)) {
+      const persistedSignature = replayState.signatures.get(stepIndex);
+      if (!persistedSignature) {
+        cleanupWorkflowRunnerState(context, workflowId);
+        return {
+          type: "failed",
+          workflowId,
+          error: `Worker checkpoint is missing replay signature for step ${stepIndex}`,
+          failureCategory: "system"
+        };
+      }
+      if (!workerReplayOperationSignaturesEqual(signature, persistedSignature)) {
+        cleanupWorkflowRunnerState(context, workflowId);
+        return {
+          type: "failed",
+          workflowId,
+          error: `Worker checkpoint replay signature mismatch at step ${stepIndex}`,
+          failureCategory: "system"
+        };
+      }
+      replayState.nextStepIndex = stepIndex + 1;
+      currentStep = await replayGeneratorStep(generator, replayState, stepIndex);
+      continue;
+    }
+    const persistedPendingSignature = replayState.signatures.get(stepIndex);
+    if (persistedPendingSignature) {
+      if (!workerReplayOperationSignaturesEqual(signature, persistedPendingSignature)) {
+        cleanupWorkflowRunnerState(context, workflowId);
+        return {
+          type: "failed",
+          workflowId,
+          error: `Worker checkpoint replay signature mismatch at pending step ${stepIndex}`,
+          failureCategory: "system"
+        };
+      }
+    } else {
+      replayState.signatures.set(stepIndex, signature);
+      replayState.checkpoint = advanceWorkerCheckpoint(replayState);
+    }
+    replayState.pendingStepIndex = stepIndex;
+    context.generators.set(workflowId, generator);
+    return {
+      type: "checkpoint",
+      workflowId,
+      checkpoint: toArrayBuffer(serializeCheckpoint(replayState.checkpoint)),
+      operationRequest
+    };
+  }
+}
+function createReplayState(message) {
+  const checkpoint = message.checkpoint && message.checkpoint.byteLength > 0 ? deserializeCheckpoint(new Uint8Array(message.checkpoint)) : createCheckpoint(message.workflowId, "worker");
+  return {
+    checkpoint,
+    accumulatedResults: new Map(checkpoint.accumulatedResults),
+    signatures: new Map(checkpoint.workerReplaySignatures ?? []),
+    failedOutcomes: new Map(checkpoint.workerReplayFailures ?? []),
+    nextStepIndex: 0,
+    pendingStepIndex: null,
+    maxProtocolMessageBytes: message.maxProtocolMessageBytes
+  };
+}
+function recordOperationOutcome(replayState, outcome) {
+  const pendingStepIndex = replayState.pendingStepIndex;
+  if (pendingStepIndex === null || !outcome)
+    return;
+  if (outcome.status === "failed") {
+    replayState.failedOutcomes.set(pendingStepIndex, outcome);
+    replayState.accumulatedResults.delete(pendingStepIndex);
+  } else {
+    replayState.accumulatedResults.set(pendingStepIndex, outcome.value);
+    replayState.failedOutcomes.delete(pendingStepIndex);
+  }
+  replayState.nextStepIndex = pendingStepIndex + 1;
+  replayState.pendingStepIndex = null;
+}
+function hasCachedWorkerOutcome(replayState, stepIndex) {
+  return replayState.accumulatedResults.has(stepIndex) || replayState.failedOutcomes.has(stepIndex);
+}
+async function replayGeneratorStep(generator, replayState, stepIndex) {
+  const failedOutcome = replayState.failedOutcomes.get(stepIndex);
+  if (failedOutcome)
+    return await generator.throw(errorFromFailedOperationOutcome(failedOutcome));
+  return await generator.next(replayState.accumulatedResults.get(stepIndex));
+}
+function advanceWorkerCheckpoint(replayState) {
+  const advanced = advanceCheckpoint(replayState.checkpoint, replayState.checkpoint.locals, {
+    accumulatedResults: [...replayState.accumulatedResults]
+  }), workerReplayFailures = [...replayState.failedOutcomes], advancedCheckpoint = { ...advanced };
+  delete advancedCheckpoint.workerReplayFailures;
+  return {
+    ...advancedCheckpoint,
+    workerReplaySignatures: [...replayState.signatures],
+    ...workerReplayFailures.length === 0 ? {} : { workerReplayFailures }
+  };
+}
+function toArrayBuffer(bytes) {
+  const copy = new Uint8Array(bytes.byteLength);
+  copy.set(bytes);
+  return copy.buffer;
+}
+export function cleanupWorkflowRunnerState(context, workflowId) {
+  context.generators.delete(workflowId);
+  context.abortControllers.delete(workflowId);
+  context.replayStates.delete(workflowId);
+}
+function formatError(error) {
+  if (error instanceof Error)
+    return error.message;
+  return String(error);
+}

package/dist/workers/workflow-worker-entry.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Web Worker entry point for workflow execution.
+ *
+ * Sets up `self.onmessage` to handle {@link WorkerInboundMessage} and posts
+ * back {@link WorkerOutboundMessage} via `self.postMessage`. Uses the
+ * existing runner helpers from `workflow-runner.ts`.
+ *
+ * @module workers/workflow-worker-entry
+ */
+import type { WorkerWorkflowContext } from './workflow-runner.ts';
+/**
+ * Factory that resolves a workflow type name to its handler. Handlers receive
+ * a worker-side {@link WorkerWorkflowContext} as the first argument so they
+ * can read `ctx.workflowId` exactly like inline-mode handlers do.
+ */
+export type WorkflowHandlerFactory = (type: string) => ((ctx: WorkerWorkflowContext, input: unknown) => AsyncGenerator) | undefined;
+/**
+ * Initialize the worker message loop. Call this from within a Web Worker
+ * to wire up the message protocol.
+ *
+ * @param getWorkflowHandler - Factory that resolves a workflow type name to
+ *   its async generator function. Typically backed by a registration map.
+ */
+export declare function initializeWorkerMessageLoop(getWorkflowHandler: WorkflowHandlerFactory): void;

package/dist/workers/workflow-worker-entry.js

@@ -0,0 +1,70 @@
+import {
+  assertWorkerProtocolMessageWithinLimit,
+  createBoundedWorkerFailureMessage,
+  WORKER_PROTOCOL_VERSION
+} from "../core/worker-protocol.js";
+import {
+  cleanupWorkflowRunnerState,
+  createWorkflowRunnerContext,
+  handleCancelMessage,
+  handleResumeMessage,
+  handleRunMessage
+} from "./workflow-runner.js";
+const workerPostMessage = self.postMessage.bind(self), workerClose = "close" in self && typeof self.close === "function" ? self.close.bind(self) : void 0;
+export function initializeWorkerMessageLoop(getWorkflowHandler) {
+  const runnerContext = createWorkflowRunnerContext();
+  self.addEventListener("message", async (event) => {
+    const message = event.data;
+    switch (message.type) {
+      case "run": {
+        const response = await handleRunMessage(runnerContext, message, getWorkflowHandler);
+        postOutboundMessage(runnerContext, response, message);
+        break;
+      }
+      case "resume": {
+        const resultValue = message.operationResult.status === "completed" ? message.operationResult.value : void 0, resumeMessage = {
+          workflowId: message.workflowId,
+          result: resultValue,
+          operationResult: message.operationResult,
+          ...message.maxProtocolMessageBytes === void 0 ? {} : { maxProtocolMessageBytes: message.maxProtocolMessageBytes }
+        }, response = await handleResumeMessage(runnerContext, resumeMessage);
+        postOutboundMessage(runnerContext, response, message);
+        break;
+      }
+      case "cancel": {
+        await handleCancelMessage(runnerContext, message);
+        break;
+      }
+    }
+  });
+}
+function postOutboundMessage(runnerContext, message, inboundMessage) {
+  const outboundMessage = attachWorkerProtocol(message, inboundMessage);
+  try {
+    assertWorkerProtocolMessageWithinLimit(outboundMessage, inboundMessage.maxProtocolMessageBytes);
+    if (outboundMessage.type === "checkpoint")
+      workerPostMessage(outboundMessage, [outboundMessage.checkpoint]);
+    else
+      workerPostMessage(outboundMessage);
+  } catch (error) {
+    cleanupWorkflowRunnerState(runnerContext, inboundMessage.workflowId);
+    const failedMessage = createBoundedWorkerFailureMessage({
+      workflowId: inboundMessage.workflowId,
+      error: error instanceof Error ? error.message : String(error),
+      failureCategory: "resource",
+      ...inboundMessage.turnId === void 0 ? {} : { turnId: inboundMessage.turnId }
+    });
+    try {
+      workerPostMessage(failedMessage);
+    } catch {
+      workerClose?.();
+    }
+  }
+}
+function attachWorkerProtocol(message, inboundMessage) {
+  return {
+    ...message,
+    protocolVersion: WORKER_PROTOCOL_VERSION,
+    ...inboundMessage.turnId === void 0 ? {} : { turnId: inboundMessage.turnId }
+  };
+}