@lostgradient/weft 0.2.0

package/dist/core/context/operation-request.d.ts

@@ -0,0 +1,160 @@
+import type { AtomicStateScope } from '../atomic-state.ts';
+import type { HumanReviewOptions } from '../review/index.ts';
+import type { ChildWorkflowOptions } from '../types.ts';
+import type { Context } from './index.ts';
+import type { OffloadReference, StreamSink } from './types.ts';
+/**
+ * Discriminated union of all operation descriptors that a workflow generator
+ * can yield to the engine. Each variant corresponds to one durable operation.
+ *
+ * @example
+ * ```ts
+ * import { activity, Context, type ContextOperationRequest } from '@lostgradient/weft';
+ *
+ * const ping = activity({ name: 'ping', execute: async (input: unknown) => input });
+ * const ctx = new Context({
+ *   workflowId: 'wf-demo',
+ *   workflowType: 'demo',
+ *   startedAt: Date.now(),
+ *   abortController: new AbortController(),
+ * });
+ * const generator = ctx.run(ping, 'hello');
+ * const first = generator.next();
+ * const request: ContextOperationRequest | undefined = first.done ? undefined : first.value;
+ * void request;
+ * ```
+ */
+export type ContextOperationRequest = {
+    type: 'activity';
+    operationId: string;
+    activityName: string;
+    fn?: (input: unknown, context?: unknown) => unknown;
+    input: unknown;
+    callerStack?: string;
+    options?: Record<string, unknown>;
+    /** Dispatch attempt used for worker payloads, interceptors, and reconciliation verifiers. */
+    attempt?: number;
+    /**
+     * Deterministic workflow step index for this activity call. Stable across
+     * replay (unlike `operationId`, which is regenerated each yield), so it
+     * anchors the durable async-completion task token to a fixed activity.
+     */
+    step?: number;
+    /** Serialized interceptor headers (Map entries) for remote worker propagation. */
+    headers?: [string, string][];
+} | {
+    type: 'sleep';
+    operationId: string;
+    duration: number;
+    scheduledFireAt: number;
+    callerStack?: string;
+} | {
+    type: 'wait-signal';
+    operationId: string;
+    signalName: string;
+    callerStack?: string;
+} | {
+    type: 'wait-update';
+    operationId: string;
+    updateName: string;
+    callerStack?: string;
+} | {
+    type: 'parallel';
+    operationId: string;
+    operations: ContextOperationRequest[];
+    /**
+     * Workflow step index where this parallel op lives. The engine
+     * writes the partial cache entry to `context.accumulatedResults[step]`
+     * after settlement so on retry the workflow generator can reuse
+     * fulfilled branches.
+     */
+    step: number;
+    /**
+     * Resumed parallel-operation cache entry from a prior attempt. Engine
+     * uses this to skip dispatch for fulfilled branch slots and re-dispatch
+     * the rest. Typed as `unknown` here to avoid a circular import with
+     * `./parallel-operations.ts` where the entry shape is defined; the
+     * engine validates the shape via `isParallelOperationCacheEntry`.
+     */
+    resumedCacheEntry?: unknown;
+    callerStack?: string;
+} | {
+    type: 'race';
+    operationId: string;
+    operations: ContextOperationRequest[];
+    callerStack?: string;
+} | {
+    type: 'memo';
+    operationId: string;
+    key: string;
+    fn: () => unknown;
+    callerStack?: string;
+} | {
+    type: 'child-workflow';
+    operationId: string;
+    workflowType: string;
+    input: unknown;
+    callerStack?: string;
+    options?: ChildWorkflowOptions;
+} | {
+    type: 'offload';
+    operationId: string;
+    key: string;
+    fn: () => Promise<unknown>;
+    callerStack?: string;
+} | {
+    type: 'load';
+    operationId: string;
+    reference: OffloadReference;
+    callerStack?: string;
+} | {
+    type: 'archive';
+    operationId: string;
+    key: string;
+    data: unknown;
+    callerStack?: string;
+} | {
+    type: 'state-read';
+    operationId: string;
+    scope: AtomicStateScope;
+    key: string;
+    initial?: unknown;
+    callerStack?: string;
+} | {
+    type: 'state-commit';
+    operationId: string;
+    scope: AtomicStateScope;
+    key: string;
+    expectedVersion: number;
+    mode: 'set' | 'delete';
+    value?: unknown;
+    callerStack?: string;
+} | {
+    type: 'run-all';
+    operationId: string;
+    branches: Record<string, readonly [Function] | readonly [Function, unknown]>;
+    /** Workflow step index — see note on `parallel.step`. */
+    step: number;
+    /**
+     * Resumed run-all cache entry from a prior attempt. See note on
+     * `parallel.resumedCacheEntry` for why this is typed as `unknown`.
+     */
+    resumedCacheEntry?: unknown;
+    callerStack?: string;
+} | {
+    type: 'speculate';
+    operationId: string;
+    execute: (context: Context) => Generator<ContextOperationRequest, unknown, unknown> | AsyncGenerator<unknown, unknown, unknown>;
+    callerStack?: string;
+} | {
+    type: 'stream';
+    operationId: string;
+    key: string;
+    fn: (sink: StreamSink) => AsyncGenerator<unknown, void, unknown>;
+    callerStack?: string;
+} | {
+    type: 'wait-review';
+    operationId: string;
+    reviewOptions: HumanReviewOptions;
+    callerStack?: string;
+};

package/dist/core/context/parallel-cache-entry.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Cache entry shape and validators for parallel operations
+ * (`ctx.all` / `ctx.race` / `ctx.runAll`). Lives in its own module so
+ * `parallel-operations.ts` (the generators) stays under the file-size
+ * cap — the generator logic and the cache-entry shape are independently
+ * reviewable.
+ *
+ * The v2 `ParallelOperationCacheEntry` shape is what gets written into
+ * the workflow's `accumulatedResults` map. It carries per-branch slots
+ * (pending/fulfilled/rejected/aborted) so partial-failure preservation
+ * can be reconstructed across retries — see `parallel-execution.md`
+ * for the durability contract.
+ */
+import { WeftError } from '../weft-error.ts';
+/**
+ * One slot in a {@link ParallelOperationCacheEntry}'s `branches` table.
+ *
+ * - `pending`: branch was dispatched but never observed to settle (e.g., the
+ *   process crashed before its result was recorded). Re-dispatched on retry.
+ * - `fulfilled`: branch completed successfully. Reused on retry; never re-runs.
+ * - `rejected`: branch threw. Metadata only — never reused on retry; the
+ *   branch re-dispatches just like a `pending` slot. The `reason` is a
+ *   normalized `{ name, message }` because raw `Error` objects don't
+ *   round-trip through MessagePack.
+ * - `aborted`: reserved for `ctx.race` losers. Never produced by
+ *   `ctx.all`/`ctx.runAll` because they don't cancel siblings on failure.
+ */
+export type ParallelBranchSlot = {
+    status: 'pending';
+    operationId: string;
+} | {
+    status: 'fulfilled';
+    value: unknown;
+    operationId: string;
+} | {
+    status: 'rejected';
+    reason: {
+        name: string;
+        message: string;
+    };
+    operationId: string;
+} | {
+    status: 'aborted';
+    operationId: string;
+};
+/**
+ * Persistent record of a parallel operation's per-branch outcomes. Stored
+ * in `accumulatedResults` at the parent operation's step. On retry, the
+ * generator inspects this entry and lets fulfilled branches skip dispatch
+ * while non-fulfilled branches re-execute.
+ *
+ * `formatVersion: 2` is the v2 shape — the only shape v2-aware engines
+ * write or read.
+ */
+export type ParallelOperationCacheEntry = {
+    __weftParallelOperationCache: true;
+    formatVersion: 2;
+    variant: 'all' | 'race' | 'run-all';
+    branches: ParallelBranchSlot[];
+    /** Ordered key list for `run-all`; absent for `all` and `race`. */
+    branchNames?: string[];
+    subOperationCount: number;
+};
+/**
+ * Thrown when the workflow's branch topology (count for `ctx.all`, ordered
+ * key list for `ctx.runAll`) differs from the cached entry on retry.
+ * Indicates non-deterministic workflow code — branches must be stable
+ * across retries.
+ */
+export declare class BranchTopologyChangedError extends WeftError<'BranchTopologyChangedError'> {
+    constructor(message: string);
+}
+/** Type guard for the v2 parallel-operation cache entry shape. */
+export declare function isParallelOperationCacheEntry(value: unknown): value is ParallelOperationCacheEntry;
+/**
+ * Throw `BranchTopologyChangedError` if the value carries the
+ * parallel-operation cache marker but doesn't pass the full v2 shape
+ * check. Used to surface malformed entries (e.g. checkpoints written
+ * by a future engine version) instead of silently producing wrong
+ * replay behavior.
+ *
+ * NOT an `asserts` predicate: a value without the marker is also a
+ * valid input here (it just means the cache slot held a non-parallel
+ * legacy value). Callers still narrow via `isParallelOperationCacheEntry`
+ * after calling this — using `asserts` would over-narrow plain
+ * non-parallel cached values and mark the legacy fallback paths
+ * (`return cached as unknown[]`) as dead code in TypeScript.
+ */
+export declare function assertValidParallelOperationCacheEntry(value: unknown): void;
+/** Build a fresh v2 cache entry with the given branch slots. */
+export declare function createParallelOperationCacheEntry(variant: 'all' | 'race' | 'run-all', branches: ParallelBranchSlot[], subOperationCount: number, branchNames?: string[]): ParallelOperationCacheEntry;

package/dist/core/context/parallel-cache-entry.js

@@ -0,0 +1,92 @@
+import { WeftError } from "../weft-error.js";
+
+export class BranchTopologyChangedError extends WeftError {
+  constructor(message) {
+    super("BranchTopologyChangedError", message);
+  }
+}
+function isValidVariant(value) {
+  return value === "all" || value === "race" || value === "run-all";
+}
+function isValidSlotStatus(value) {
+  return value === "pending" || value === "fulfilled" || value === "rejected" || value === "aborted";
+}
+function isValidRejectionReason(value) {
+  if (value === null || typeof value !== "object")
+    return !1;
+  const reason = value;
+  return typeof reason.name === "string" && typeof reason.message === "string";
+}
+function isValidBranchSlot(value) {
+  if (value === null || typeof value !== "object")
+    return !1;
+  const slot = value;
+  if (!isValidSlotStatus(slot.status))
+    return !1;
+  if (typeof slot.operationId !== "string")
+    return !1;
+  if (slot.status === "rejected" && !isValidRejectionReason(slot.reason))
+    return !1;
+  return !0;
+}
+function isValidBranchNames(value) {
+  if (value === void 0)
+    return !0;
+  return Array.isArray(value) && value.every((name) => typeof name === "string");
+}
+function isValidSubOperationCount(value) {
+  return typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
+}
+function hasParallelOperationCacheMarker(value) {
+  return value !== null && typeof value === "object" && value.__weftParallelOperationCache === !0;
+}
+function hasValidBranchTopology(variant, branches, subOperationCount, branchNames) {
+  if (variant === "race") {
+    if (branches.length !== 1 || subOperationCount < 1)
+      return !1;
+    const winner = branches[0];
+    if (winner == null || typeof winner !== "object")
+      return !1;
+    return winner.status === "fulfilled" && branchNames === void 0;
+  }
+  if (branches.length !== subOperationCount)
+    return !1;
+  if (variant === "run-all")
+    return Array.isArray(branchNames) && branchNames.length === subOperationCount;
+  return branchNames === void 0;
+}
+export function isParallelOperationCacheEntry(value) {
+  if (value === null || typeof value !== "object")
+    return !1;
+  const record = value;
+  if (record.__weftParallelOperationCache !== !0)
+    return !1;
+  if (record.formatVersion !== 2)
+    return !1;
+  if (!isValidVariant(record.variant))
+    return !1;
+  if (!Array.isArray(record.branches))
+    return !1;
+  if (!isValidSubOperationCount(record.subOperationCount))
+    return !1;
+  if (!isValidBranchNames(record.branchNames))
+    return !1;
+  const subOperationCount = record.subOperationCount;
+  if (!hasValidBranchTopology(record.variant, record.branches, subOperationCount, record.branchNames))
+    return !1;
+  return record.branches.every(isValidBranchSlot);
+}
+export function assertValidParallelOperationCacheEntry(value) {
+  if (hasParallelOperationCacheMarker(value) && !isParallelOperationCacheEntry(value))
+    throw new BranchTopologyChangedError("Parallel operation cache entry is malformed or incompatible with this engine version.");
+}
+export function createParallelOperationCacheEntry(variant, branches, subOperationCount, branchNames) {
+  return {
+    __weftParallelOperationCache: !0,
+    formatVersion: 2,
+    variant,
+    branches,
+    ...branchNames !== void 0 ? { branchNames } : {},
+    subOperationCount
+  };
+}

package/dist/core/context/parallel-operations.d.ts

@@ -0,0 +1,9 @@
+import type { Context } from './index.ts';
+import type { ContextInternals } from './internals.ts';
+import type { ContextOperationRequest } from './operation-request.ts';
+import { assertValidParallelOperationCacheEntry, BranchTopologyChangedError, createParallelOperationCacheEntry, isParallelOperationCacheEntry, type ParallelBranchSlot, type ParallelOperationCacheEntry } from './parallel-cache-entry.ts';
+export { assertValidParallelOperationCacheEntry, BranchTopologyChangedError, createParallelOperationCacheEntry, isParallelOperationCacheEntry, type ParallelBranchSlot, type ParallelOperationCacheEntry, };
+export declare function all(context: Context, internals: ContextInternals, operations: Generator<ContextOperationRequest, unknown, unknown>[]): Generator<ContextOperationRequest, unknown[], unknown>;
+export declare function race(context: Context, internals: ContextInternals, operations: Generator<ContextOperationRequest, unknown, unknown>[]): Generator<ContextOperationRequest, unknown, unknown>;
+export declare function memo<T>(context: Context, internals: ContextInternals, key: string, fn: () => T | Promise<T>): Generator<ContextOperationRequest, T, unknown>;
+export declare function runAll<T extends Record<string, readonly [Function] | readonly [Function, unknown]>>(context: Context, internals: ContextInternals, branches: T): Generator<ContextOperationRequest, Record<keyof T, unknown>, unknown>;

package/dist/core/context/parallel-operations.js

@@ -0,0 +1,202 @@
+import { primeParallelOperations } from "./child-workflow-pipe.js";
+import {
+  assertValidParallelOperationCacheEntry,
+  BranchTopologyChangedError,
+  createParallelOperationCacheEntry,
+  isParallelOperationCacheEntry
+} from "./parallel-cache-entry.js";
+import { captureCallerStack } from "./validation.js";
+
+export {
+  assertValidParallelOperationCacheEntry,
+  BranchTopologyChangedError,
+  createParallelOperationCacheEntry,
+  isParallelOperationCacheEntry
+};
+function reconstructAllResult(entry) {
+  return entry.branches.map((slot) => {
+    if (slot.status !== "fulfilled")
+      throw Error(`Cannot reconstruct ctx.all result: branch slot is ${slot.status}, not fulfilled`);
+    return slot.value;
+  });
+}
+function reconstructRunAllResult(entry) {
+  const names = entry.branchNames;
+  if (names === void 0)
+    throw Error("Cannot reconstruct ctx.runAll result: cache entry missing branchNames");
+  const result = {};
+  for (let i = 0;i < names.length; i++) {
+    const slot = entry.branches[i];
+    if (slot?.status !== "fulfilled")
+      throw Error(`Cannot reconstruct ctx.runAll result: branch '${names[i]}' is ${slot?.status ?? "missing"}`);
+    result[names[i]] = slot.value;
+  }
+  return result;
+}
+function isEntryFullyFulfilled(entry) {
+  return entry.branches.every((slot) => slot.status === "fulfilled");
+}
+export function* all(context, internals, operations) {
+  const step = internals.stepIndex++;
+  if (internals.accumulatedResults?.has(step)) {
+    const cached = internals.accumulatedResults.get(step);
+    assertValidParallelOperationCacheEntry(cached);
+    if (isParallelOperationCacheEntry(cached)) {
+      if (cached.variant !== "all")
+        throw new BranchTopologyChangedError(`ctx.all step ${step} found a cached entry of variant '${cached.variant}'. The same step must use the same parallel primitive across retries.`);
+      if (operations.length !== cached.subOperationCount)
+        throw new BranchTopologyChangedError(`ctx.all branch count changed across retry: expected ${cached.subOperationCount}, got ${operations.length}. Branch count must be deterministic.`);
+      if (isEntryFullyFulfilled(cached)) {
+        internals.stepIndex += cached.subOperationCount;
+        return reconstructAllResult(cached);
+      }
+      const subOperations = primeParallelOperations(operations);
+      stampDeterministicOperationIds(subOperations, `parallel:${step}`);
+      const callerStack = captureCallerStack();
+      return yield {
+        type: "parallel",
+        operationId: `parallel:${step}`,
+        operations: subOperations,
+        step,
+        resumedCacheEntry: cached,
+        callerStack
+      };
+    }
+    return cached;
+  }
+  const subOperations = primeParallelOperations(operations), operationId = `parallel:${step}`;
+  stampDeterministicOperationIds(subOperations, operationId);
+  const callerStack = captureCallerStack(), values = yield {
+    type: "parallel",
+    operationId,
+    operations: subOperations,
+    step,
+    callerStack
+  };
+  context.accumulatedResults.set(step, buildFulfilledAllEntry(values, operationId, subOperations.length));
+  return values;
+}
+function buildFulfilledAllEntry(values, operationId, subOperationCount) {
+  return createParallelOperationCacheEntry("all", values.map((value, i) => ({
+    status: "fulfilled",
+    value,
+    operationId: `${operationId}:${i}`
+  })), subOperationCount);
+}
+export function* race(context, internals, operations) {
+  const step = internals.stepIndex++;
+  if (internals.accumulatedResults?.has(step)) {
+    const cached = internals.accumulatedResults.get(step);
+    assertValidParallelOperationCacheEntry(cached);
+    if (isParallelOperationCacheEntry(cached)) {
+      if (cached.variant !== "race")
+        throw new BranchTopologyChangedError(`ctx.race step ${step} found a cached entry of variant '${cached.variant}'. The same step must use the same parallel primitive across retries.`);
+      if (operations.length !== cached.subOperationCount)
+        throw new BranchTopologyChangedError(`ctx.race branch count changed across retry: expected ${cached.subOperationCount}, got ${operations.length}. Branch count must be deterministic.`);
+      const winner = cached.branches[0];
+      if (winner?.status !== "fulfilled")
+        throw new BranchTopologyChangedError(`ctx.race step ${step} cached entry has no fulfilled winner slot \u2014 entry is malformed.`);
+      internals.stepIndex += cached.subOperationCount;
+      return winner.value;
+    }
+    return cached;
+  }
+  const subOperations = primeParallelOperations(operations), operationId = `race:${step}`;
+  stampDeterministicOperationIds(subOperations, operationId);
+  const callerStack = captureCallerStack(), result = yield {
+    type: "race",
+    operationId,
+    operations: subOperations,
+    callerStack
+  };
+  context.accumulatedResults.set(step, {
+    __weftParallelOperationCache: !0,
+    formatVersion: 2,
+    variant: "race",
+    branches: [{ status: "fulfilled", value: result, operationId: `${operationId}:winner` }],
+    subOperationCount: subOperations.length
+  });
+  return result;
+}
+function stampDeterministicOperationIds(subOperations, parentOperationId) {
+  for (let i = 0;i < subOperations.length; i++) {
+    const op = subOperations[i];
+    if (op !== void 0)
+      op.operationId = `${parentOperationId}:${i}`;
+  }
+}
+export function* memo(context, internals, key, fn) {
+  const step = internals.stepIndex++;
+  if (internals.memoCache?.has(key))
+    return internals.memoCache.get(key);
+  if (internals.accumulatedResults?.has(step)) {
+    const cached = internals.accumulatedResults.get(step);
+    internals.memoCache ??= new Map;
+    internals.memoCache.set(key, cached);
+    return cached;
+  }
+  const operationId = crypto.randomUUID(), callerStack = captureCallerStack(), result = yield {
+    type: "memo",
+    operationId,
+    key,
+    fn,
+    callerStack
+  };
+  internals.memoCache ??= new Map;
+  internals.memoCache.set(key, result);
+  context.accumulatedResults.set(step, result);
+  return result;
+}
+function validateRunAllTopology(cached, branchNames, step) {
+  if (cached.variant !== "run-all")
+    throw new BranchTopologyChangedError(`ctx.runAll step ${step} found a cached entry of variant '${cached.variant}'. The same step must use the same parallel primitive across retries.`);
+  const cachedNames = cached.branchNames ?? [];
+  if (cachedNames.length !== branchNames.length)
+    throw new BranchTopologyChangedError(`ctx.runAll branch count changed across retry: expected ${cachedNames.length}, got ${branchNames.length}`);
+  for (let i = 0;i < branchNames.length; i++)
+    if (cachedNames[i] !== branchNames[i])
+      throw new BranchTopologyChangedError(`ctx.runAll branch order changed across retry: expected '${cachedNames[i]}' at index ${i}, got '${branchNames[i]}'. Branch names must appear in the same order across retries.`);
+}
+export function* runAll(context, internals, branches) {
+  const step = internals.stepIndex++, branchNames = Object.keys(branches);
+  if (internals.accumulatedResults?.has(step)) {
+    const cached = internals.accumulatedResults.get(step);
+    assertValidParallelOperationCacheEntry(cached);
+    if (isParallelOperationCacheEntry(cached)) {
+      validateRunAllTopology(cached, branchNames, step);
+      if (isEntryFullyFulfilled(cached))
+        return reconstructRunAllResult(cached);
+      const operationId = `run-all:${step}`, callerStack = captureCallerStack();
+      return yield {
+        type: "run-all",
+        operationId,
+        branches,
+        step,
+        resumedCacheEntry: cached,
+        callerStack
+      };
+    }
+    return cached;
+  }
+  if (internals.explainMode) {
+    console.log(`[weft] ctx.runAll({ ${branchNames.join(", ")} })`);
+    console.log(`  \u2192 Creating checkpoint at step ${step}`);
+    console.log(`  \u2192 Running ${branchNames.length} named branches in parallel`);
+  }
+  const operationId = `run-all:${step}`, callerStack = captureCallerStack(), result = yield {
+    type: "run-all",
+    operationId,
+    branches,
+    step,
+    callerStack
+  }, record = result;
+  context.accumulatedResults.set(step, buildFulfilledRunAllEntry(record, branchNames, operationId));
+  return result;
+}
+function buildFulfilledRunAllEntry(record, branchNames, operationId) {
+  return createParallelOperationCacheEntry("run-all", branchNames.map((name) => ({
+    status: "fulfilled",
+    value: record[name],
+    operationId: `${operationId}:${name}`
+  })), branchNames.length, branchNames);
+}

package/dist/core/context/run-operation.d.ts

@@ -0,0 +1,21 @@
+import { type RetryPolicy } from '../types.ts';
+import type { Context } from './index.ts';
+import type { ContextOperationRequest } from './operation-request.ts';
+type ActivityInput = string | (Function & {
+    retry?: RetryPolicy;
+});
+type ActivityOperationRequest = Extract<ContextOperationRequest, {
+    type: 'activity';
+}>;
+interface RunActivityRequest<TResult> {
+    request: ActivityOperationRequest;
+    step: number;
+    hasCachedResult: boolean;
+    cachedResult?: TResult;
+    retryAttempt: number;
+    retryPolicy?: RetryPolicy;
+}
+export declare function shouldRetryActivityError(error: unknown, policy: RetryPolicy | undefined, attempt: number): policy is RetryPolicy;
+export declare function createRunActivityRequest<TResult>(context: Context, activity: ActivityInput, rest: readonly unknown[]): RunActivityRequest<TResult>;
+export declare function runActivityWithRetry<TResult>(context: Context, activity: ActivityInput, rest: readonly unknown[]): Generator<ContextOperationRequest, TResult, unknown>;
+export {};