@lostgradient/weft 0.2.0

package/dist/core/engine/operations-activity.js

@@ -0,0 +1,194 @@
+import { assertPayloadWithinLimit } from "../payload-size.js";
+import {
+  buildActivityReconciliationReference,
+  buildActivityVerificationContext,
+  createCompletedActivityReconciliationRecord,
+  resolveActivityIdempotencyKey,
+  resolveStartedActivityReconciliationRecord,
+  validateActivityResultForReconciliation,
+  writeActivityReconciliationTransition
+} from "./activity-reconciliation.js";
+import {
+  AsyncActivityDeferral,
+  deriveAsyncActivityToken,
+  driveWorkflowInterceptorGenerator,
+  parkDeferredAsyncActivity
+} from "./async-activity-completion.js";
+import { ActivityResolutionError } from "./errors.js";
+import { callActivityFunction } from "./state-utilities.js";
+function resolveActivityViaRegistries(internals, workflowId, activityName) {
+  const workflowType = internals.workflowTypeByWorkflowId.get(workflowId);
+  if (workflowType !== void 0) {
+    const perWorkflow = internals.activityRegistriesByWorkflow.get(workflowType);
+    if (perWorkflow !== void 0) {
+      const perWorkflowFn = perWorkflow.resolve(activityName);
+      if (perWorkflowFn)
+        return { fn: perWorkflowFn, workflowType };
+    }
+    const globalFn = internals.activityRegistry.resolve(activityName);
+    if (globalFn)
+      return { fn: globalFn, workflowType };
+    return;
+  }
+  const globalFn = internals.activityRegistry.resolve(activityName);
+  if (globalFn)
+    return { fn: globalFn, workflowType: "<unknown>" };
+  return;
+}
+export function getActivityFunctionWithMetadata(internals, workflowId, operation) {
+  const resolved = resolveActivityViaRegistries(internals, workflowId, operation.activityName);
+  if (resolved)
+    return resolved.fn;
+  if (typeof operation.fn === "function")
+    return operation.fn;
+  return;
+}
+export function resolveActivityFunction(internals, workflowId, operation) {
+  const resolved = resolveActivityViaRegistries(internals, workflowId, operation.activityName);
+  if (resolved)
+    return resolved.fn;
+  if (operation.fn)
+    return operation.fn;
+  const workflowType = internals.workflowTypeByWorkflowId.get(workflowId) ?? "<unknown>";
+  throw new ActivityResolutionError(workflowType, operation.activityName);
+}
+export function buildActivityVerification(_internals, activityName, verify, context, result) {
+  return (async () => {
+    const verified = await verify?.(result, context);
+    if (typeof verified !== "boolean")
+      throw Error(`Verification failed for activity "${activityName}"`);
+    if (!verified)
+      throw Error(`Verification failed for activity "${activityName}"`);
+  })();
+}
+export function buildActivityCompensation(internals, workflowId, operation, result) {
+  const activity = getActivityFunctionWithMetadata(internals, workflowId, operation);
+  if (!activity?.compensate)
+    return;
+  return async () => {
+    await activity.compensate?.(operation.input, result);
+  };
+}
+export async function invokeWorkerActivity(internals, operationId, activityName, input, attempt) {
+  const dispatcher = internals.activityWorkerDispatcher;
+  if (!dispatcher)
+    throw Error(`No activity worker dispatcher available for "${activityName}"`);
+  const result = await dispatcher.execute({
+    operationId,
+    activityName,
+    input,
+    attempt
+  });
+  if (result.status === "failed") {
+    const error = Error(result.error);
+    if (result.errorName !== void 0)
+      error.name = result.errorName;
+    throw error;
+  }
+  return result.value;
+}
+export function invokeInlineActivity(internals, workflowId, operation, activityContext, _activityName, input) {
+  const activityFunction = resolveActivityFunction(internals, workflowId, operation);
+  return callActivityFunction(activityFunction, input, activityContext);
+}
+function copyActivityHeadersToOperation(operation, headers) {
+  if (headers.size > 0)
+    operation.headers = [...headers.entries()];
+}
+function getActivityAttempt(operation) {
+  const attempt = operation.attempt;
+  return typeof attempt === "number" && Number.isInteger(attempt) && attempt > 0 ? attempt : 1;
+}
+export async function executeActivity(internals, workflowId, operation, callbacks, attempt = getActivityAttempt(operation)) {
+  const activityInput = operation.input, abortController = internals.inlineStrategy?.getAbortController(workflowId), asyncToken = deriveAsyncActivityToken(workflowId, operation.step ?? 0, attempt), activityContext = {
+    signal: abortController?.signal ?? new AbortController().signal,
+    heartbeat: (details) => {
+      internals.heartbeatDetails.set(workflowId, details);
+    },
+    completeAsync: () => {
+      throw new AsyncActivityDeferral(asyncToken);
+    }
+  }, invokeActivity = internals.activityWorkerDispatcher ? (activityName, input) => invokeWorkerActivity(internals, operation.operationId, activityName, input, attempt) : (activityName, input) => invokeInlineActivity(internals, workflowId, operation, activityContext, activityName, input), composedActivity = callbacks.getComposedActivityInterceptor(), executeWithActivityInterceptors = async (activityName, input, headers) => {
+    if (!composedActivity)
+      return invokeActivity(activityName, input);
+    const activityInterception = {
+      workflowId,
+      activityName,
+      input,
+      attempt,
+      headers
+    };
+    return await composedActivity.execute(activityInterception, async (interception) => {
+      return invokeActivity(activityName, interception.input);
+    });
+  }, composedWorkflow = callbacks.getComposedWorkflowInterceptor();
+  if (composedWorkflow) {
+    const interception = {
+      workflowId,
+      activityName: operation.activityName,
+      input: activityInput,
+      attempt,
+      headers: new Map
+    };
+    function* execute() {
+      return yield executeWithActivityInterceptors(operation.activityName, interception.input, interception.headers);
+    }
+    const generator = composedWorkflow.activity(interception, execute), value = await driveWorkflowInterceptorGenerator(generator);
+    copyActivityHeadersToOperation(operation, interception.headers);
+    return value;
+  }
+  const headers = new Map, result = await executeWithActivityInterceptors(operation.activityName, activityInput, headers);
+  copyActivityHeadersToOperation(operation, headers);
+  return result;
+}
+export async function executeActivityOperationResult(internals, workflowId, operation, callbacks, speculativeState) {
+  const activity = getActivityFunctionWithMetadata(internals, workflowId, operation), idempotencyKey = resolveActivityIdempotencyKey(activity, operation), operationAttempt = getActivityAttempt(operation);
+  if (idempotencyKey !== void 0) {
+    const reference = await buildActivityReconciliationReference(workflowId, operation.activityName, idempotencyKey), started = await resolveStartedActivityReconciliationRecord(internals, workflowId, operation, reference, activity, idempotencyKey, operationAttempt);
+    if ("completedResult" in started) {
+      validateActivityResultForReconciliation(started.completedResult, internals.options.payloadSizePolicy.maxBytes);
+      return started.completedResult;
+    }
+    const result = await executeActivity(internals, workflowId, operation, callbacks, started.attempt);
+    validateActivityResultForReconciliation(result, internals.options.payloadSizePolicy.maxBytes);
+    await finalizeActivityResult(internals, workflowId, operation, result, activity, idempotencyKey, started.attempt, speculativeState, !0);
+    const completedRecord = createCompletedActivityReconciliationRecord(started, result, internals.options.getNow());
+    await writeActivityReconciliationTransition(internals.storage, reference, started, completedRecord);
+    return result;
+  }
+  const result = await executeActivity(internals, workflowId, operation, callbacks, operationAttempt);
+  assertPayloadWithinLimit(result, internals.options.payloadSizePolicy.maxBytes, "activity result");
+  await finalizeActivityResult(internals, workflowId, operation, result, activity, idempotencyKey, operationAttempt, speculativeState);
+  return result;
+}
+async function finalizeActivityResult(internals, workflowId, operation, result, activity, idempotencyKey, attempt, speculativeState, awaitSpeculativeVerification = !1) {
+  const compensation = speculativeState ? buildActivityCompensation(internals, workflowId, operation, result) : void 0;
+  if (compensation)
+    speculativeState?.recordCompensation(compensation);
+  if (activity?.verify) {
+    const context = buildActivityVerificationContext("post-execution-validation", workflowId, operation.operationId, operation.activityName, operation.input, idempotencyKey, attempt), verification = buildActivityVerification(internals, operation.activityName, activity.verify, context, result);
+    if (speculativeState) {
+      speculativeState.recordVerification(verification);
+      if (awaitSpeculativeVerification)
+        await verification;
+    } else
+      await verification;
+  }
+}
+export async function processActivityOperation(internals, workflowId, operation, callbacks) {
+  return callbacks.runOperationWithResult(workflowId, operation, async () => {
+    try {
+      return await executeActivityOperationResult(internals, workflowId, operation, callbacks);
+    } catch (error) {
+      if (error instanceof AsyncActivityDeferral)
+        return parkDeferredAsyncActivity(internals, error, {
+          workflowId,
+          activityName: operation.activityName,
+          operationId: operation.operationId,
+          step: operation.step ?? 0,
+          attempt: getActivityAttempt(operation)
+        });
+      throw error;
+    }
+  });
+}

package/dist/core/engine/operations-coordination.d.ts

@@ -0,0 +1,39 @@
+import type { ContextOperationRequest } from '../context.ts';
+import type { EngineInternals } from './internals.ts';
+import { type ActivityFunctionWithMetadata, type ActivityOperationCallbacks } from './operations-activity.ts';
+import type { OperationWithCallerStack } from './operations-router.ts';
+import type { SpeculativeExecutionState } from './speculative-execution-state.ts';
+type WaitSignalOperation = Extract<ContextOperationRequest, {
+    type: 'wait-signal';
+}>;
+type ParallelOperation = Extract<ContextOperationRequest, {
+    type: 'parallel';
+}>;
+type RaceOperation = Extract<ContextOperationRequest, {
+    type: 'race';
+}>;
+type RunAllOperation = Extract<ContextOperationRequest, {
+    type: 'run-all';
+}>;
+export type CoordinationOperationCallbacks = {
+    completeOperation: (workflowId: string, value: unknown) => void;
+    runOperationWithResult: (workflowId: string, operation: OperationWithCallerStack, execute: () => Promise<unknown>) => Promise<void>;
+    executeSubOperation: (workflowId: string, operation: ContextOperationRequest, signal?: AbortSignal, speculativeState?: SpeculativeExecutionState) => Promise<unknown>;
+    getActivityOperationCallbacks: () => ActivityOperationCallbacks;
+};
+export declare function processWaitSignalOperation(internals: EngineInternals, workflowId: string, operation: WaitSignalOperation, callbacks: Pick<CoordinationOperationCallbacks, 'completeOperation'>): Promise<void>;
+export declare function processParallelOperation(internals: EngineInternals, workflowId: string, operation: ParallelOperation, callbacks: Pick<CoordinationOperationCallbacks, 'executeSubOperation' | 'runOperationWithResult'>): Promise<void>;
+export declare function processRaceOperation(_internals: EngineInternals, workflowId: string, operation: RaceOperation, callbacks: Pick<CoordinationOperationCallbacks, 'executeSubOperation' | 'runOperationWithResult'>): Promise<void>;
+export declare function processRunAllOperation(internals: EngineInternals, workflowId: string, operation: RunAllOperation, callbacks: Pick<CoordinationOperationCallbacks, 'runOperationWithResult'>): Promise<void>;
+export declare function isConfiguredInlineActivity(fn: Function): fn is RunAllOperation['branches'][string][0] & ActivityFunctionWithMetadata;
+/**
+ * Used by `executeSubOperation`'s `'run-all'` case (nested run-all inside
+ * another sub-operation). Speculative-execution path retained for
+ * `ctx.speculate` callers that need verification/compensation tracking.
+ *
+ * This path does NOT write a partial cache entry — it's only invoked for
+ * nested run-alls whose results live inside the outer parent's slot. The
+ * outer parent's partial-persistence handles durability.
+ */
+export declare function executeRunAllOperationResult(internals: EngineInternals, workflowId: string, operation: RunAllOperation, callbacks: Pick<CoordinationOperationCallbacks, 'getActivityOperationCallbacks'>, speculativeState?: SpeculativeExecutionState): Promise<Record<string, unknown>>;
+export {};

package/dist/core/engine/operations-coordination.js

@@ -0,0 +1,162 @@
+import {
+  isParallelOperationCacheEntry
+} from "../context/parallel-operations.js";
+import {
+  executeRunAllBranches,
+  executeRunAllBranchesSettled
+} from "../engine-helpers.js";
+import {
+  executeActivityOperationResult as executeActivityOperationResultFromInternals
+} from "./operations-activity.js";
+import {
+  buildEntryFromSlots,
+  dispatchBranchesAllSettled,
+  valuesFromSlots
+} from "./parallel-dispatch.js";
+import { consumeSignal, trackWaiterKey, untrackWaiterKey } from "./signals.js";
+import { callActivityFunction } from "./state-utilities.js";
+export async function processWaitSignalOperation(internals, workflowId, operation, callbacks) {
+  const abortSignal = internals.abortController.signal, waiterKey = `${workflowId}:${operation.signalName}`;
+  while (!0) {
+    if (abortSignal.aborted)
+      return;
+    const existingPayload = await consumeSignal(internals, workflowId, operation.signalName);
+    if (existingPayload.found) {
+      callbacks.completeOperation(workflowId, existingPayload.payload);
+      return;
+    }
+    const { promise, resolve } = Promise.withResolvers();
+    internals.signalWaiters.set(waiterKey, resolve);
+    trackWaiterKey(internals.signalWaitersByWorkflow, workflowId, waiterKey);
+    if (abortSignal.aborted) {
+      internals.signalWaiters.delete(waiterKey);
+      untrackWaiterKey(internals.signalWaitersByWorkflow, workflowId, waiterKey);
+      return;
+    }
+    const bufferedPayload = await consumeSignal(internals, workflowId, operation.signalName);
+    if (bufferedPayload.found) {
+      if (internals.signalWaiters.get(waiterKey) === resolve) {
+        internals.signalWaiters.delete(waiterKey);
+        untrackWaiterKey(internals.signalWaitersByWorkflow, workflowId, waiterKey);
+      }
+      callbacks.completeOperation(workflowId, bufferedPayload.payload);
+      return;
+    }
+    await promise;
+    if (abortSignal.aborted)
+      return;
+  }
+}
+export async function processParallelOperation(internals, workflowId, operation, callbacks) {
+  return callbacks.runOperationWithResult(workflowId, operation, async () => {
+    const resumedSlots = extractResumedSlots(operation.resumedCacheEntry), operationIds = operation.operations.map((sub, i) => typeof sub.operationId === "string" ? sub.operationId : `parallel:${operation.step}:${i}`), { slots, hasFirstError, firstError } = await dispatchBranchesAllSettled(operationIds, resumedSlots, (index) => callbacks.executeSubOperation(workflowId, operation.operations[index])), entry = buildEntryFromSlots("all", slots), partialEntryWritten = writePartialEntry(internals, workflowId, operation.step, entry);
+    if (hasFirstError) {
+      assertPartialFailurePersistenceSupported(partialEntryWritten, slots, "ctx.all", "worker execution mode");
+      throw firstError;
+    }
+    return valuesFromSlots(slots);
+  });
+}
+function extractResumedSlots(resumedCacheEntry) {
+  if (!isParallelOperationCacheEntry(resumedCacheEntry))
+    return;
+  return resumedCacheEntry.branches;
+}
+function writePartialEntry(internals, workflowId, step, entry) {
+  const context = internals.inlineStrategy?.getContext(workflowId);
+  if (context === void 0)
+    return !1;
+  context.accumulatedResults.set(step, entry);
+  return !0;
+}
+function assertPartialFailurePersistenceSupported(partialEntryWritten, slots, operationName, executionMode) {
+  if (partialEntryWritten || !slots.some((slot) => slot.status === "fulfilled"))
+    return;
+  throw Error(`${operationName} partial-failure preservation is not supported in ${executionMode}: the engine cannot persist fulfilled branch slots after a sibling branch fails. Run the workflow inline or make branch side effects idempotent.`);
+}
+export async function processRaceOperation(_internals, workflowId, operation, callbacks) {
+  return callbacks.runOperationWithResult(workflowId, operation, async () => {
+    const controller = new AbortController, subOperations = operation.operations.map((subOperation) => callbacks.executeSubOperation(workflowId, subOperation, controller.signal));
+    Promise.allSettled(subOperations);
+    try {
+      return await Promise.race(subOperations);
+    } finally {
+      controller.abort();
+    }
+  });
+}
+export async function processRunAllOperation(internals, workflowId, operation, callbacks) {
+  return callbacks.runOperationWithResult(workflowId, operation, async () => {
+    const branchNames = Object.keys(operation.branches), operationIds = branchNames.map((name) => `run-all:${operation.step}:${name}`), resumedSlots = extractResumedSlots(operation.resumedCacheEntry), resumedSlotsByName = mapResumedSlotsByName(resumedSlots, branchNames), branchesToRun = filterBranchesToRun(operation.branches, branchNames, resumedSlotsByName), { outcomes, hasFirstError, firstError } = await executeRunAllBranchesSettled(branchesToRun, (fn, input) => callActivityFunction(fn, input)), slots = mergeRunAllSlots(branchNames, operationIds, resumedSlotsByName, outcomes), entry = buildEntryFromSlots("run-all", slots, branchNames), partialEntryWritten = writePartialEntry(internals, workflowId, operation.step, entry);
+    if (hasFirstError) {
+      assertPartialFailurePersistenceSupported(partialEntryWritten, slots, "ctx.runAll", "worker execution mode");
+      throw firstError;
+    }
+    return reconstructRunAllRecord(branchNames, slots);
+  });
+}
+function filterBranchesToRun(branches, branchNames, resumedSlotsByName) {
+  const result = {};
+  for (const name of branchNames)
+    if (resumedSlotsByName?.get(name)?.status !== "fulfilled") {
+      const branch = branches[name];
+      if (branch !== void 0)
+        result[name] = branch;
+    }
+  return result;
+}
+function mergeRunAllSlots(branchNames, operationIds, resumedSlotsByName, outcomes) {
+  const outcomesByName = new Map;
+  for (const outcome of outcomes)
+    outcomesByName.set(outcome.name, outcome);
+  return branchNames.map((name, i) => {
+    const operationId = operationIds[i], resumed = resumedSlotsByName?.get(name);
+    if (resumed?.status === "fulfilled")
+      return resumed;
+    const outcome = outcomesByName.get(name);
+    if (outcome.status === "fulfilled")
+      return { status: "fulfilled", value: outcome.value, operationId };
+    const reasonError = outcome.reason instanceof Error ? outcome.reason : Error(String(outcome.reason));
+    return {
+      status: "rejected",
+      reason: { name: reasonError.name, message: reasonError.message },
+      operationId
+    };
+  });
+}
+function reconstructRunAllRecord(branchNames, slots) {
+  const result = {};
+  for (let i = 0;i < branchNames.length; i++) {
+    const slot = slots[i];
+    if (slot?.status === "fulfilled")
+      result[branchNames[i]] = slot.value;
+  }
+  return result;
+}
+function mapResumedSlotsByName(resumedSlots, branchNames) {
+  if (resumedSlots === void 0)
+    return;
+  const result = new Map;
+  for (let i = 0;i < branchNames.length; i++) {
+    const name = branchNames[i], slot = resumedSlots[i];
+    if (name !== void 0 && slot !== void 0)
+      result.set(name, slot);
+  }
+  return result;
+}
+export function isConfiguredInlineActivity(fn) {
+  return typeof fn.execute === "function";
+}
+export async function executeRunAllOperationResult(internals, workflowId, operation, callbacks, speculativeState) {
+  return executeRunAllBranches(operation.branches, (fn, input) => {
+    if (!speculativeState || !isConfiguredInlineActivity(fn))
+      return callActivityFunction(fn, input);
+    return executeActivityOperationResultFromInternals(internals, workflowId, {
+      type: "activity",
+      operationId: crypto.randomUUID(),
+      activityName: fn.name,
+      fn,
+      input
+    }, callbacks.getActivityOperationCallbacks(), speculativeState);
+  });
+}

package/dist/core/engine/operations-data.d.ts

@@ -0,0 +1,23 @@
+import type { ContextOperationRequest } from '../context.ts';
+import type { EngineInternals } from './internals.ts';
+import type { OperationWithCallerStack } from './operations-router.ts';
+type MemoOperation = Extract<ContextOperationRequest, {
+    type: 'memo';
+}>;
+type OffloadOperation = Extract<ContextOperationRequest, {
+    type: 'offload';
+}>;
+type LoadOperation = Extract<ContextOperationRequest, {
+    type: 'load';
+}>;
+type ArchiveOperation = Extract<ContextOperationRequest, {
+    type: 'archive';
+}>;
+export type DataOperationCallbacks = {
+    runOperationWithResult: (workflowId: string, operation: OperationWithCallerStack, execute: () => Promise<unknown>) => Promise<void>;
+};
+export declare function processMemoOperation(_internals: EngineInternals, workflowId: string, operation: MemoOperation, callbacks: DataOperationCallbacks): Promise<void>;
+export declare function processOffloadOperation(internals: EngineInternals, workflowId: string, operation: OffloadOperation, callbacks: DataOperationCallbacks): Promise<void>;
+export declare function processLoadOperation(internals: EngineInternals, workflowId: string, operation: LoadOperation, callbacks: DataOperationCallbacks): Promise<void>;
+export declare function processArchiveOperation(internals: EngineInternals, workflowId: string, operation: ArchiveOperation, callbacks: DataOperationCallbacks): Promise<void>;
+export {};

package/dist/core/engine/operations-data.js

@@ -0,0 +1,38 @@
+import { KEYS } from "../../storage/interface.js";
+import { decode, encode } from "../codec.js";
+import { callMemoFunction } from "./state-utilities.js";
+export async function processMemoOperation(_internals, workflowId, operation, callbacks) {
+  return callbacks.runOperationWithResult(workflowId, operation, async () => callMemoFunction(operation.fn));
+}
+export async function processOffloadOperation(internals, workflowId, operation, callbacks) {
+  return callbacks.runOperationWithResult(workflowId, operation, async () => {
+    const data = await operation.fn(), encoded = encode(data);
+    await internals.storage.put(KEYS.offload(workflowId, operation.key), encoded);
+    return {
+      key: operation.key,
+      workflowId,
+      sizeBytes: encoded.byteLength
+    };
+  });
+}
+export async function processLoadOperation(internals, workflowId, operation, callbacks) {
+  return callbacks.runOperationWithResult(workflowId, operation, async () => {
+    const { workflowId: referenceWorkflowId, key: referenceKey, sizeBytes } = operation.reference;
+    if (typeof referenceWorkflowId !== "string" || referenceWorkflowId !== workflowId)
+      throw Error("ctx.load() can only read offloaded data from the current workflow");
+    if (typeof referenceKey !== "string" || referenceKey.length === 0)
+      throw Error("ctx.load() requires a non-empty offload reference key");
+    if (typeof sizeBytes !== "number" || !Number.isFinite(sizeBytes) || sizeBytes < 0)
+      throw Error("ctx.load() requires a valid offload reference size");
+    const raw = await internals.storage.get(KEYS.offload(referenceWorkflowId, referenceKey));
+    if (raw === null)
+      throw Error(`Offloaded data not found for key "${referenceKey}" in workflow "${referenceWorkflowId}"`);
+    return decode(raw);
+  });
+}
+export async function processArchiveOperation(internals, workflowId, operation, callbacks) {
+  return callbacks.runOperationWithResult(workflowId, operation, async () => {
+    await internals.storage.put(KEYS.archive(workflowId, operation.key), encode(operation.data));
+    return;
+  });
+}

package/dist/core/engine/operations-router.d.ts

@@ -0,0 +1,75 @@
+import type { ContextOperationRequest } from '../context.ts';
+import type { OperationOutcome } from '../types.ts';
+import type { EngineInternals } from './internals.ts';
+import type { CapturedRejectionReason } from './strategy-helpers.ts';
+export type OperationWithCallerStack = {
+    callerStack?: string;
+};
+export type OperationRouterCallbacks = {
+    processActivityOperation: (workflowId: string, operation: Extract<ContextOperationRequest, {
+        type: 'activity';
+    }>) => Promise<void>;
+    processSleepOperation: (workflowId: string, operation: Extract<ContextOperationRequest, {
+        type: 'sleep';
+    }>) => Promise<void>;
+    processWaitSignalOperation: (workflowId: string, operation: Extract<ContextOperationRequest, {
+        type: 'wait-signal';
+    }>) => Promise<void>;
+    processWaitUpdateOperation: (workflowId: string, operation: Extract<ContextOperationRequest, {
+        type: 'wait-update';
+    }>) => Promise<void>;
+    processParallelOperation: (workflowId: string, operation: Extract<ContextOperationRequest, {
+        type: 'parallel';
+    }>) => Promise<void>;
+    processRaceOperation: (workflowId: string, operation: Extract<ContextOperationRequest, {
+        type: 'race';
+    }>) => Promise<void>;
+    processMemoOperation: (workflowId: string, operation: Extract<ContextOperationRequest, {
+        type: 'memo';
+    }>) => Promise<void>;
+    processChildWorkflowOperation: (workflowId: string, operation: Extract<ContextOperationRequest, {
+        type: 'child-workflow';
+    }>) => Promise<void>;
+    processOffloadOperation: (workflowId: string, operation: Extract<ContextOperationRequest, {
+        type: 'offload';
+    }>) => Promise<void>;
+    processLoadOperation: (workflowId: string, operation: Extract<ContextOperationRequest, {
+        type: 'load';
+    }>) => Promise<void>;
+    processArchiveOperation: (workflowId: string, operation: Extract<ContextOperationRequest, {
+        type: 'archive';
+    }>) => Promise<void>;
+    processStateReadOperation: (workflowId: string, operation: Extract<ContextOperationRequest, {
+        type: 'state-read';
+    }>) => Promise<void>;
+    processStateCommitOperation: (workflowId: string, operation: Extract<ContextOperationRequest, {
+        type: 'state-commit';
+    }>) => Promise<void>;
+    processRunAllOperation: (workflowId: string, operation: Extract<ContextOperationRequest, {
+        type: 'run-all';
+    }>) => Promise<void>;
+    processSpeculateOperation: (workflowId: string, operation: Extract<ContextOperationRequest, {
+        type: 'speculate';
+    }>) => Promise<void>;
+    processStreamOperation: (workflowId: string, operation: Extract<ContextOperationRequest, {
+        type: 'stream';
+    }>) => Promise<void>;
+    processWaitReviewOperation: (workflowId: string, operation: Extract<ContextOperationRequest, {
+        type: 'wait-review';
+    }>) => Promise<void>;
+    finalizePendingTimelineEntry: (workflowId: string, status: 'completed' | 'failed', value: unknown) => void;
+    feedOperationResult: (workflowId: string, result: OperationOutcome, originalReason?: CapturedRejectionReason) => void;
+};
+/**
+ * Translate an operation request from a strategy into a {@link ContextOperationRequest}.
+ *
+ * The inline strategy already produces `ContextOperationRequest` (with `type`).
+ * The worker protocol produces `OperationRequest` (with `kind`). This function
+ * normalizes both shapes so `processOperation` can switch on `type`.
+ */
+export declare function translateOperationRequest(_internals: EngineInternals, operationRequest: unknown): ContextOperationRequest;
+export declare function processOperation(internals: EngineInternals, workflowId: string, operation: ContextOperationRequest, callbacks: OperationRouterCallbacks): Promise<void>;
+export declare function completeOperation(_internals: EngineInternals, workflowId: string, value: unknown, callbacks: Pick<OperationRouterCallbacks, 'finalizePendingTimelineEntry' | 'feedOperationResult'>): void;
+export declare function failOperation(_internals: EngineInternals, workflowId: string, operation: OperationWithCallerStack, error: unknown, callbacks: Pick<OperationRouterCallbacks, 'finalizePendingTimelineEntry' | 'feedOperationResult'>): void;
+export declare function runOperationWithResult(internals: EngineInternals, workflowId: string, operation: OperationWithCallerStack, execute: () => Promise<unknown>, callbacks: OperationRouterCallbacks): Promise<void>;
+export declare function runOperationWithoutResult(internals: EngineInternals, workflowId: string, operation: OperationWithCallerStack, execute: () => Promise<void>, callbacks: OperationRouterCallbacks): Promise<void>;

package/dist/core/engine/operations-router.js

@@ -0,0 +1,90 @@
+import { classifyErrorAsFailureCategory } from "../failure-categories.js";
+export function translateOperationRequest(_internals, operationRequest) {
+  const operation = operationRequest;
+  if (operation == null || typeof operation !== "object")
+    throw Error("Invalid operation request received from execution strategy");
+  if ("type" in operation && typeof operation.type === "string")
+    return operation;
+  if ("kind" in operation && typeof operation.kind === "string") {
+    const kind = operation.kind, type = {
+      activity: "activity",
+      timer: "sleep",
+      "signal-wait": "wait-signal",
+      "child-workflow": "child-workflow"
+    }[kind] ?? kind;
+    return {
+      ...operation,
+      type,
+      operationId: operation.id ?? crypto.randomUUID(),
+      activityName: operation.activityName ?? "",
+      input: operation.input
+    };
+  }
+  throw Error("Unsupported operation request shape received from execution strategy");
+}
+export async function processOperation(internals, workflowId, operation, callbacks) {
+  const operationProcessor = resolveOperationProcessor(operation, callbacks);
+  if (operationProcessor)
+    return operationProcessor(workflowId, operation);
+  const unsupportedType = String(operation.type);
+  failOperation(internals, workflowId, operation, Error(`Unsupported operation type: ${unsupportedType}`), callbacks);
+}
+function operationProcessors(callbacks) {
+  return {
+    activity: callbacks.processActivityOperation,
+    sleep: callbacks.processSleepOperation,
+    "wait-signal": callbacks.processWaitSignalOperation,
+    "wait-update": callbacks.processWaitUpdateOperation,
+    parallel: callbacks.processParallelOperation,
+    race: callbacks.processRaceOperation,
+    memo: callbacks.processMemoOperation,
+    "child-workflow": callbacks.processChildWorkflowOperation,
+    offload: callbacks.processOffloadOperation,
+    load: callbacks.processLoadOperation,
+    archive: callbacks.processArchiveOperation,
+    "state-read": callbacks.processStateReadOperation,
+    "state-commit": callbacks.processStateCommitOperation,
+    "run-all": callbacks.processRunAllOperation,
+    speculate: callbacks.processSpeculateOperation,
+    stream: callbacks.processStreamOperation,
+    "wait-review": callbacks.processWaitReviewOperation
+  };
+}
+function resolveOperationProcessor(operation, callbacks) {
+  return operationProcessors(callbacks)[operation.type];
+}
+export function completeOperation(_internals, workflowId, value, callbacks) {
+  callbacks.finalizePendingTimelineEntry(workflowId, "completed", value);
+  callbacks.feedOperationResult(workflowId, { status: "completed", value });
+}
+export function failOperation(_internals, workflowId, operation, error, callbacks) {
+  if (error instanceof Error && operation.callerStack)
+    error.stack = `${error.stack}
+    --- workflow call site ---
+${operation.callerStack}`;
+  const errorMessage = error instanceof Error ? error.message : String(error);
+  callbacks.finalizePendingTimelineEntry(workflowId, "failed", errorMessage);
+  callbacks.feedOperationResult(workflowId, {
+    status: "failed",
+    error: errorMessage,
+    ...error instanceof Error ? { errorName: error.name } : {},
+    failureCategory: classifyErrorAsFailureCategory(error, {
+      defaultErrorCategory: "application"
+    })
+  }, { value: error });
+}
+export async function runOperationWithResult(internals, workflowId, operation, execute, callbacks) {
+  try {
+    const value = await execute();
+    completeOperation(internals, workflowId, value, callbacks);
+  } catch (error) {
+    failOperation(internals, workflowId, operation, error, callbacks);
+  }
+}
+export async function runOperationWithoutResult(internals, workflowId, operation, execute, callbacks) {
+  try {
+    await execute();
+  } catch (error) {
+    failOperation(internals, workflowId, operation, error, callbacks);
+  }
+}

package/dist/core/engine/operations-speculate.d.ts

@@ -0,0 +1,16 @@
+import type { ContextOperationRequest } from '../context.ts';
+import type { EngineInternals } from './internals.ts';
+import type { OperationWithCallerStack } from './operations-router.ts';
+import { SpeculativeExecutionState } from './speculative-execution-state.ts';
+type SpeculateOperation = Extract<ContextOperationRequest, {
+    type: 'speculate';
+}>;
+type SpeculativeOperationGenerator = Generator<ContextOperationRequest, unknown, unknown> | AsyncGenerator<ContextOperationRequest, unknown, unknown>;
+export type SpeculateOperationCallbacks = {
+    runOperationWithResult: (workflowId: string, operation: OperationWithCallerStack, execute: () => Promise<unknown>) => Promise<void>;
+    executeSubOperation: (workflowId: string, operation: ContextOperationRequest, signal?: AbortSignal, speculativeState?: SpeculativeExecutionState) => Promise<unknown>;
+};
+export declare function processSpeculateOperation(internals: EngineInternals, workflowId: string, operation: SpeculateOperation, callbacks: SpeculateOperationCallbacks): Promise<void>;
+export declare function executeSpeculativeBranch(internals: EngineInternals, workflowId: string, operation: SpeculateOperation, callbacks: Pick<SpeculateOperationCallbacks, 'executeSubOperation'>): Promise<unknown>;
+export declare function driveSpeculativeGenerator(workflowId: string, generator: SpeculativeOperationGenerator, speculativeState: SpeculativeExecutionState, callbacks: Pick<SpeculateOperationCallbacks, 'executeSubOperation'>): Promise<unknown>;
+export {};