@lostgradient/weft 0.2.0

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

@@ -0,0 +1,40 @@
+import { SpeculativeExecutionState } from "./speculative-execution-state.js";
+export async function processSpeculateOperation(internals, workflowId, operation, callbacks) {
+  return callbacks.runOperationWithResult(workflowId, operation, () => executeSpeculativeBranch(internals, workflowId, operation, callbacks));
+}
+export async function executeSpeculativeBranch(internals, workflowId, operation, callbacks) {
+  const inlineStrategy = internals.inlineStrategy;
+  if (!inlineStrategy)
+    throw Error("ctx.speculate() requires inline execution mode");
+  const parentContext = inlineStrategy.getContext(workflowId);
+  if (!parentContext)
+    throw Error(`No active inline context for workflow "${workflowId}"`);
+  const speculativeContext = parentContext.createSpeculativeChild(), speculativeState = new SpeculativeExecutionState, generator = createSpeculativeOperationGenerator(operation, speculativeContext);
+  try {
+    const result = await driveSpeculativeGenerator(workflowId, generator, speculativeState, callbacks);
+    await speculativeState.drainVerifications();
+    parentContext.commitSpeculativeChild(speculativeContext);
+    return result;
+  } catch (error) {
+    await speculativeState.rollback();
+    throw error;
+  }
+}
+function createSpeculativeOperationGenerator(operation, speculativeContext) {
+  return operation.execute(speculativeContext);
+}
+export async function driveSpeculativeGenerator(workflowId, generator, speculativeState, callbacks) {
+  const advance = async (lastResult, errorToThrow) => {
+    const iterationResult = errorToThrow === void 0 ? await generator.next(lastResult) : await generator.throw(errorToThrow);
+    if (iterationResult.done)
+      return iterationResult.value;
+    const nextOperation = iterationResult.value;
+    try {
+      const nextResult = await callbacks.executeSubOperation(workflowId, nextOperation, void 0, speculativeState);
+      return advance(nextResult, void 0);
+    } catch (error) {
+      return advance(lastResult, error instanceof Error ? error : Error(String(error)));
+    }
+  };
+  return advance(void 0, void 0);
+}

package/dist/core/engine/operations-state.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';
+type StateReadOperation = Extract<ContextOperationRequest, {
+    type: 'state-read';
+}>;
+type StateCommitOperation = Extract<ContextOperationRequest, {
+    type: 'state-commit';
+}>;
+export type StateOperationCallbacks = {
+    runOperationWithResult: (workflowId: string, operation: OperationWithCallerStack, execute: () => Promise<unknown>) => Promise<void>;
+    ensureTerminalCleanupTracked: (workflowId: string) => Promise<void>;
+};
+export declare function processStateReadOperation(internals: EngineInternals, workflowId: string, operation: StateReadOperation, callbacks: StateOperationCallbacks): Promise<void>;
+export declare function processStateCommitOperation(internals: EngineInternals, workflowId: string, operation: StateCommitOperation, callbacks: StateOperationCallbacks): Promise<void>;
+export {};

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

@@ -0,0 +1,27 @@
+import {
+  atomicStateDataKey,
+  commitAtomicStateDelete,
+  commitAtomicStateValue,
+  readAtomicStateSnapshot
+} from "../atomic-state.js";
+export async function processStateReadOperation(internals, workflowId, operation, callbacks) {
+  return callbacks.runOperationWithResult(workflowId, operation, async () => {
+    const dataKey = atomicStateDataKey(operation.scope, operation.key);
+    return readAtomicStateSnapshot(internals.storage, dataKey, operation);
+  });
+}
+export async function processStateCommitOperation(internals, workflowId, operation, callbacks) {
+  return callbacks.runOperationWithResult(workflowId, operation, async () => {
+    const dataKey = atomicStateDataKey(operation.scope, operation.key);
+    if (operation.mode === "delete") {
+      const result = await commitAtomicStateDelete(internals.storage, dataKey, operation.expectedVersion);
+      if (result.applied && operation.scope.type === "execution")
+        await callbacks.ensureTerminalCleanupTracked(operation.scope.ownerWorkflowId);
+      return result;
+    }
+    const result = await commitAtomicStateValue(internals.storage, dataKey, operation.expectedVersion, operation.value);
+    if (result.applied && operation.scope.type === "execution")
+      await callbacks.ensureTerminalCleanupTracked(operation.scope.ownerWorkflowId);
+    return result;
+  });
+}

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

@@ -0,0 +1,20 @@
+import type { ContextOperationRequest, StoredStreamChunk, StreamReference } from '../context.ts';
+import type { EngineInternals } from './internals.ts';
+type StreamOperation = Extract<ContextOperationRequest, {
+    type: 'stream';
+}>;
+export type StreamOperationCallbacks = {
+    runOperationWithResult: (workflowId: string, operation: StreamOperation, execute: () => Promise<unknown>) => Promise<void>;
+    handleCleanupError: (source: string, error: unknown, workflowId?: string) => void;
+};
+export declare function getStreamChunksFromInternals(internals: EngineInternals, workflowId: string, key: string, options?: {
+    after?: number;
+}): Promise<StoredStreamChunk[]>;
+export declare function processStreamOperation(internals: EngineInternals, workflowId: string, operation: StreamOperation, callbacks: StreamOperationCallbacks): Promise<void>;
+export declare function createStreamReferenceFromInternals(internals: EngineInternals, workflowId: string, operation: StreamOperation, callbacks: Pick<StreamOperationCallbacks, 'handleCleanupError'>): Promise<StreamReference>;
+export declare function writeStreamChunksFromInternals(internals: EngineInternals, workflowId: string, operation: StreamOperation, asyncGenerator: AsyncGenerator<unknown, void, unknown>, writtenKeys: string[]): Promise<{
+    chunkCount: number;
+    totalSizeBytes: number;
+}>;
+export declare function cleanupStreamChunksFromInternals(internals: EngineInternals, workflowId: string, key: string, writtenKeys: string[], callbacks: Pick<StreamOperationCallbacks, 'handleCleanupError'>): Promise<void>;
+export {};

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

@@ -0,0 +1,54 @@
+import { KEYS } from "../../storage/interface.js";
+import { encode } from "../codec.js";
+import { cleanupPartialStreamChunks, createCleanupErrorReporter } from "../engine-helpers.js";
+import { loadStoredStreamChunks } from "./stream-chunk-loading.js";
+import { STREAM_CHUNK_KIND, TOKENS_STREAM_KEY, notifyWorkflowFeedCommit } from "./workflow-feed.js";
+export async function getStreamChunksFromInternals(internals, workflowId, key, options) {
+  return loadStoredStreamChunks(internals.storage, workflowId, key, options);
+}
+export async function processStreamOperation(internals, workflowId, operation, callbacks) {
+  return callbacks.runOperationWithResult(workflowId, operation, () => createStreamReferenceFromInternals(internals, workflowId, operation, callbacks));
+}
+export async function createStreamReferenceFromInternals(internals, workflowId, operation, callbacks) {
+  const sink = {
+    heartbeat: (details) => {
+      internals.heartbeatDetails.set(workflowId, details);
+    }
+  }, writtenKeys = [];
+  try {
+    const streamSummary = await writeStreamChunksFromInternals(internals, workflowId, operation, operation.fn(sink), writtenKeys), reference = {
+      key: operation.key,
+      workflowId,
+      chunkCount: streamSummary.chunkCount,
+      totalSizeBytes: streamSummary.totalSizeBytes
+    };
+    await internals.storage.put(KEYS.streamMetadata(workflowId, operation.key), encode(reference));
+    return reference;
+  } catch (error) {
+    await cleanupStreamChunksFromInternals(internals, workflowId, operation.key, writtenKeys, callbacks);
+    throw error;
+  }
+}
+export async function writeStreamChunksFromInternals(internals, workflowId, operation, asyncGenerator, writtenKeys) {
+  let chunkCount = 0, totalSizeBytes = 0;
+  for await (const chunk of asyncGenerator) {
+    const encoded = encode(chunk), sequence = chunkCount, chunkKey = KEYS.streamChunk(workflowId, operation.key, sequence);
+    await internals.storage.put(chunkKey, encoded);
+    writtenKeys.push(chunkKey);
+    totalSizeBytes += encoded.byteLength;
+    chunkCount++;
+    if (operation.key === TOKENS_STREAM_KEY)
+      notifyWorkflowFeedCommit(internals, workflowId, "tokens", {
+        workflowId,
+        selector: "tokens",
+        kind: STREAM_CHUNK_KIND,
+        sequence,
+        timestamp: Date.now(),
+        payload: chunk
+      });
+  }
+  return { chunkCount, totalSizeBytes };
+}
+export async function cleanupStreamChunksFromInternals(internals, workflowId, key, writtenKeys, callbacks) {
+  await cleanupPartialStreamChunks(internals.storage, workflowId, key, writtenKeys, createCleanupErrorReporter(callbacks.handleCleanupError, workflowId));
+}

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

@@ -0,0 +1,28 @@
+import type { ContextOperationRequest } from '../context.ts';
+import type { Checkpoint, Duration, StartOptions, TimerEntry, WorkflowState } from '../types.ts';
+import type { WorkflowVersionTuple } from '../workflow-version-tuple.ts';
+import type { EngineInternals } from './internals.ts';
+type RegistrationEntry = EngineInternals['registrations'] extends Map<string, infer Entry> ? Entry : never;
+type SleepOperation = Extract<ContextOperationRequest, {
+    type: 'sleep';
+}>;
+export type TimeOperationCallbacks = {
+    completeOperation: (workflowId: string, value: unknown) => void;
+    loadWorkflowState: (workflowId: string) => Promise<WorkflowState | null>;
+    failWorkflow: (workflowId: string, error: Error) => Promise<void>;
+    runSerializedWorkflowStateWrite: <Result>(workflowId: string, writeOperation: () => Promise<Result>) => Promise<Result>;
+    beginWorkflowExecution: (workflowId: string, workflowType: string, input: unknown, checkpoint: Checkpoint, executionDeadline: number | undefined, executionStateOwnerId: string, registration: RegistrationEntry) => void;
+    workflowVersionTupleFromState: (state: WorkflowState) => WorkflowVersionTuple;
+    setWorkflowStartHeaders: (workflowId: string, headers: Map<string, string> | undefined) => void;
+    loadWorkflowStartHeaders: (workflowId: string) => Promise<Map<string, string> | undefined>;
+    parseStartOptionDuration: (value: Duration, fieldName: 'options.executionTimeout' | 'options.startAfter') => number;
+    runDeferredTerminalCleanup: (workflowId: string, timerId: string) => Promise<void>;
+    handleScheduleTimer: (entry: TimerEntry) => Promise<void>;
+    timeout: (workflowId: string) => Promise<void>;
+};
+export declare function createDelayedStartTimerEntry(_internals: EngineInternals, workflowId: string, scheduledStartAt: number, options: StartOptions | undefined, callbacks: Pick<TimeOperationCallbacks, 'parseStartOptionDuration'>): TimerEntry;
+export declare function processSleepOperation(internals: EngineInternals, workflowId: string, operation: SleepOperation, callbacks: Pick<TimeOperationCallbacks, 'completeOperation' | 'loadWorkflowState'>): Promise<void>;
+export declare function registerSleepResolver(internals: EngineInternals, workflowId: string, operationId: string, resolve: () => void): void;
+export declare function startDelayedWorkflow(internals: EngineInternals, entry: TimerEntry, callbacks: Pick<TimeOperationCallbacks, 'beginWorkflowExecution' | 'failWorkflow' | 'loadWorkflowStartHeaders' | 'loadWorkflowState' | 'runSerializedWorkflowStateWrite' | 'setWorkflowStartHeaders' | 'workflowVersionTupleFromState'>): Promise<void>;
+export declare function handleTimerFired(internals: EngineInternals, entry: TimerEntry, callbacks: Pick<TimeOperationCallbacks, 'failWorkflow' | 'loadWorkflowStartHeaders' | 'loadWorkflowState' | 'runDeferredTerminalCleanup' | 'runSerializedWorkflowStateWrite' | 'handleScheduleTimer' | 'setWorkflowStartHeaders' | 'timeout' | 'beginWorkflowExecution' | 'workflowVersionTupleFromState'>): Promise<void>;
+export {};

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

@@ -0,0 +1,167 @@
+import { KEYS } from "../../storage/interface.js";
+import { deserializeCheckpoint } from "../checkpoint.js";
+import { encode } from "../codec.js";
+import { buildTimerBatchOperations, normalizeStorageTimestamp } from "../scheduler.js";
+import { buildWorkflowVisibilityIndexTransition } from "./workflow-indexes.js";
+export function createDelayedStartTimerEntry(_internals, workflowId, scheduledStartAt, options, callbacks) {
+  return {
+    id: `delayed-start:${workflowId}`,
+    workflowId,
+    fireAt: scheduledStartAt,
+    kind: "delayed-start",
+    ...options?.executionTimeout !== void 0 && {
+      executionTimeoutMs: callbacks.parseStartOptionDuration(options.executionTimeout, "options.executionTimeout")
+    }
+  };
+}
+export async function processSleepOperation(internals, workflowId, operation, callbacks) {
+  if (operation.scheduledFireAt <= internals.options.getNow()) {
+    callbacks.completeOperation(workflowId, void 0);
+    return;
+  }
+  const { promise, resolve } = Promise.withResolvers();
+  await internals.scheduler.schedule({
+    id: `sleep:${operation.operationId}`,
+    workflowId,
+    fireAt: operation.scheduledFireAt,
+    kind: "sleep"
+  });
+  registerSleepResolver(internals, workflowId, operation.operationId, resolve);
+  await promise;
+  if ((await callbacks.loadWorkflowState(workflowId))?.status === "running")
+    callbacks.completeOperation(workflowId, void 0);
+}
+export function registerSleepResolver(internals, workflowId, operationId, resolve) {
+  internals.sleepResolvers.set(`${workflowId}:${operationId}`, resolve);
+  let workflowOperations = internals.sleepResolversByWorkflow.get(workflowId);
+  if (!workflowOperations) {
+    workflowOperations = new Set;
+    internals.sleepResolversByWorkflow.set(workflowId, workflowOperations);
+  }
+  workflowOperations.add(operationId);
+}
+export async function startDelayedWorkflow(internals, entry, callbacks) {
+  const state = await callbacks.loadWorkflowState(entry.workflowId);
+  if (!state || state.status !== "pending")
+    return;
+  const checkpoint = await loadDelayedWorkflowCheckpoint(internals, entry, callbacks);
+  if (!checkpoint)
+    return;
+  const registration = internals.registrations.get(state.type);
+  if (!registration) {
+    await callbacks.failWorkflow(entry.workflowId, Error(`No workflow registered with name "${state.type}"`));
+    return;
+  }
+  const now = internals.options.getNow(), executionDeadline = await resolveDelayedExecutionDeadline(entry, now, callbacks);
+  if (executionDeadline === "invalid")
+    return;
+  const runningState = await callbacks.runSerializedWorkflowStateWrite(entry.workflowId, async () => {
+    const latestState = await callbacks.loadWorkflowState(entry.workflowId);
+    if (!latestState || latestState.status !== "pending")
+      return null;
+    const nextRunningState = {
+      ...latestState,
+      status: "running",
+      startedAt: now,
+      updatedAt: now,
+      ...executionDeadline !== void 0 && { executionDeadline }
+    }, operations = [
+      {
+        type: "put",
+        key: KEYS.workflow(entry.workflowId),
+        value: encode(nextRunningState)
+      },
+      ...buildWorkflowVisibilityIndexTransition(entry.workflowId, latestState, nextRunningState).batchOps
+    ];
+    if (executionDeadline !== void 0)
+      operations.push(...buildTimerBatchOperations({
+        id: `deadline:${entry.workflowId}`,
+        workflowId: entry.workflowId,
+        fireAt: executionDeadline,
+        kind: "execution-deadline"
+      }));
+    await internals.storage.batch(operations);
+    return nextRunningState;
+  });
+  if (!runningState)
+    return;
+  internals.checkpoints.set(entry.workflowId, checkpoint);
+  internals.workflowVersionTuples.set(entry.workflowId, callbacks.workflowVersionTupleFromState(runningState));
+  callbacks.setWorkflowStartHeaders(entry.workflowId, await callbacks.loadWorkflowStartHeaders(entry.workflowId));
+  callbacks.beginWorkflowExecution(entry.workflowId, runningState.type, runningState.input, checkpoint, executionDeadline, runningState.executionStateOwnerId ?? entry.workflowId, registration);
+}
+async function loadDelayedWorkflowCheckpoint(internals, entry, callbacks) {
+  const checkpointBytes = await internals.storage.get(KEYS.checkpoint(entry.workflowId));
+  if (!checkpointBytes) {
+    await callbacks.failWorkflow(entry.workflowId, Error(`Checkpoint not found for delayed workflow "${entry.workflowId}"`));
+    return null;
+  }
+  return deserializeCheckpoint(checkpointBytes);
+}
+async function resolveDelayedExecutionDeadline(entry, now, callbacks) {
+  if (entry.executionTimeoutMs === void 0)
+    return;
+  if (!Number.isFinite(entry.executionTimeoutMs) || entry.executionTimeoutMs < 0) {
+    await failInvalidDelayedExecutionTimeout(entry, callbacks);
+    return "invalid";
+  }
+  try {
+    return normalizeStorageTimestamp(now + entry.executionTimeoutMs, `Delayed execution timeout for workflow "${entry.workflowId}"`);
+  } catch {
+    await failInvalidDelayedExecutionTimeout(entry, callbacks);
+    return "invalid";
+  }
+}
+async function failInvalidDelayedExecutionTimeout(entry, callbacks) {
+  await callbacks.failWorkflow(entry.workflowId, Error(`Invalid delayed execution timeout for workflow "${entry.workflowId}"`));
+}
+export async function handleTimerFired(internals, entry, callbacks) {
+  if (entry.id.startsWith("review-escalation:") || entry.id.startsWith("review-timeout:")) {
+    await handleReviewTimer(internals, entry, callbacks);
+    return;
+  }
+  if (entry.kind === "delayed-start") {
+    await startDelayedWorkflow(internals, entry, callbacks);
+    return;
+  }
+  if (entry.kind === "terminal-cleanup") {
+    await callbacks.runDeferredTerminalCleanup(entry.workflowId, entry.id);
+    return;
+  }
+  if (entry.kind === "schedule") {
+    await callbacks.handleScheduleTimer(entry);
+    return;
+  }
+  if (entry.kind === "sleep")
+    resolveSleepTimer(internals, entry);
+  else if (entry.kind === "execution-deadline")
+    await callbacks.timeout(entry.workflowId);
+}
+async function handleReviewTimer(internals, entry, callbacks) {
+  const reviewId = entry.id.split(":")[1];
+  if (!reviewId)
+    return;
+  const handler = internals.reviewEscalationHandlers.get(reviewId);
+  if (!handler)
+    return;
+  const state = await callbacks.loadWorkflowState(entry.workflowId);
+  if (!state || state.status !== "running")
+    return;
+  await handler(entry);
+}
+function resolveSleepTimer(internals, entry) {
+  const operationId = entry.id.replace("sleep:", ""), resolverKey = `${entry.workflowId}:${operationId}`, resolver = internals.sleepResolvers.get(resolverKey);
+  if (!resolver)
+    return;
+  internals.sleepResolvers.delete(resolverKey);
+  untrackSleepResolver(internals, entry.workflowId, operationId);
+  resolver();
+}
+function untrackSleepResolver(internals, workflowId, operationId) {
+  const workflowOperations = internals.sleepResolversByWorkflow.get(workflowId);
+  if (!workflowOperations)
+    return;
+  workflowOperations.delete(operationId);
+  if (workflowOperations.size === 0)
+    internals.sleepResolversByWorkflow.delete(workflowId);
+}

package/dist/core/engine/parallel-dispatch.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Shared dispatch helper for top-level `ctx.all` and `ctx.runAll`. Runs
+ * branches with `Promise.allSettled` semantics, captures every branch's
+ * outcome, and returns the slot table plus the first observed rejection
+ * reason. Callers (`processParallelOperation` for `ctx.all`,
+ * `processRunAllOperation` for `ctx.runAll`) build the v2 cache entry
+ * from those slots and persist it to the workflow's
+ * `accumulatedResults`.
+ *
+ * The helper itself has no access to a `Context` and does not mutate
+ * any workflow state directly — slot construction is its only job. The
+ * "persist before rethrow" contract lives in the callers.
+ *
+ * Nested `ctx.all` (inside another sub-operation, like `ctx.race`) does
+ * NOT go through this helper. `executeSubOperation` keeps `Promise.all`
+ * semantics for that case so the outer parent's slot captures the inner
+ * value verbatim — partial-failure preservation is documented as
+ * top-level only.
+ *
+ * Persistence model in the callers: the engine writes the partial entry
+ * into `context.accumulatedResults` in place at the operation's parent
+ * step; the existing checkpoint-persistence path picks it up on the
+ * next yield boundary. This trades some durability under hard process
+ * crashes for a much smaller blast radius into the engine's
+ * checkpoint-write machinery — see the `parallel-execution.md` guide
+ * for the precise durability contract.
+ */
+import type { ParallelBranchSlot, ParallelOperationCacheEntry } from '../context/parallel-operations.ts';
+export type ParallelDispatchResult = {
+    /** Final slot table — every entry is `fulfilled` or `rejected`. */
+    slots: ParallelBranchSlot[];
+    /**
+     * Whether at least one branch rejected. Distinguishes "no rejection"
+     * from "rejected with `undefined`" — the latter is rare but valid in
+     * `Promise.all` semantics.
+     */
+    hasFirstError: boolean;
+    /**
+     * The first rejection observed by settlement timing, in its original
+     * shape. `Promise.all` rethrows whatever was thrown — including
+     * non-`Error` values like strings, numbers, or `undefined`. Callers
+     * rethrow this as-is to preserve that contract.
+     */
+    firstError: unknown;
+};
+/**
+ * Mutable accumulator for the first rejection observed across a fan-out
+ * dispatch. Shared by `dispatchBranchesAllSettled` here and by
+ * `executeRunAllBranchesSettled` in `engine-helpers.ts` so both
+ * Promise.all-style settled dispatches use the same capture logic and
+ * don't drift in the contract for "first rejection wins" semantics.
+ *
+ * `Promise.all` rethrows whatever was thrown — including non-`Error`
+ * values like strings, numbers, or `undefined`. The accumulator
+ * preserves the original `unknown` value so callers can rethrow it
+ * verbatim.
+ */
+export type FirstRejectionCapture = {
+    hasFirstError: boolean;
+    firstError: unknown;
+};
+/** Create a fresh first-rejection accumulator. */
+export declare function createFirstRejectionCapture(): FirstRejectionCapture;
+/** Record a rejection, keeping only the first one observed by settlement timing. */
+export declare function captureFirstRejection(capture: FirstRejectionCapture, reason: unknown): void;
+export type DispatchOneBranch = (index: number) => Promise<unknown>;
+/**
+ * Run every branch via `executeOne(index)`, capturing per-branch outcomes
+ * in a slot table. Reused fulfilled slots (passed in via `resumedSlots`)
+ * skip dispatch entirely; missing/rejected/aborted slots dispatch fresh.
+ *
+ * The promise NEVER rejects — callers receive a `slots` array, a
+ * `hasFirstError` flag, and the original `firstError` value. Callers
+ * translate that into rejection of the parent operation themselves so
+ * they can write the partial entry first. Persisted rejection metadata
+ * is normalized to `{ name, message }` because raw `Error` objects
+ * don't round-trip through MessagePack, but the value rethrown to the
+ * workflow generator is the original `unknown` reason.
+ */
+export declare function dispatchBranchesAllSettled(operationIds: string[], resumedSlots: ParallelBranchSlot[] | undefined, executeOne: DispatchOneBranch): Promise<ParallelDispatchResult>;
+/**
+ * Build a v2 cache entry from the result of `dispatchBranchesAllSettled`.
+ * Convenience wrapper used by every dispatch site.
+ */
+export declare function buildEntryFromSlots(variant: 'all' | 'race' | 'run-all', slots: ParallelBranchSlot[], branchNames?: string[]): ParallelOperationCacheEntry;
+/**
+ * Reconstruct the user-visible array result from a fully-fulfilled slot
+ * table. Throws if any slot is non-fulfilled — callers must check
+ * `firstError` first and throw it instead of calling this on a partial
+ * result.
+ */
+export declare function valuesFromSlots(slots: ParallelBranchSlot[]): unknown[];

package/dist/core/engine/parallel-dispatch.js

@@ -0,0 +1,45 @@
+import { createParallelOperationCacheEntry } from "../context/parallel-operations.js";
+export function createFirstRejectionCapture() {
+  return { hasFirstError: !1, firstError: void 0 };
+}
+export function captureFirstRejection(capture, reason) {
+  if (!capture.hasFirstError) {
+    capture.hasFirstError = !0;
+    capture.firstError = reason;
+  }
+}
+export async function dispatchBranchesAllSettled(operationIds, resumedSlots, executeOne) {
+  const slots = operationIds.map((operationId, i) => {
+    const cached = resumedSlots?.[i];
+    if (cached?.status === "fulfilled")
+      return cached;
+    return { status: "pending", operationId };
+  }), capture = createFirstRejectionCapture();
+  await Promise.all(operationIds.map(async (operationId, index) => {
+    if (slots[index]?.status === "fulfilled")
+      return;
+    try {
+      const value = await executeOne(index);
+      slots[index] = { status: "fulfilled", value, operationId };
+    } catch (error) {
+      const reasonError = error instanceof Error ? error : Error(String(error));
+      slots[index] = {
+        status: "rejected",
+        reason: { name: reasonError.name, message: reasonError.message },
+        operationId
+      };
+      captureFirstRejection(capture, error);
+    }
+  }));
+  return { slots, hasFirstError: capture.hasFirstError, firstError: capture.firstError };
+}
+export function buildEntryFromSlots(variant, slots, branchNames) {
+  return createParallelOperationCacheEntry(variant, slots, slots.length, branchNames);
+}
+export function valuesFromSlots(slots) {
+  return slots.map((slot, i) => {
+    if (slot.status !== "fulfilled")
+      throw Error(`Branch slot ${i} is ${slot.status}, not fulfilled`);
+    return slot.value;
+  });
+}

package/dist/core/engine/pending-updates.d.ts

@@ -0,0 +1,18 @@
+import type { EngineInternals } from './internals.ts';
+type PendingUpdateCallbacks = {
+    dispatchEvent: (event: Event) => boolean;
+    broadcast: (message: {
+        type: 'update:completed';
+        workflowId: string;
+        updateId: string;
+    }) => void;
+};
+export declare function invokeUpdateHandler(internals: EngineInternals, name: string, handler: (payload: unknown) => unknown, payload: unknown): Promise<unknown>;
+/**
+ * After an inline workflow advances, wait for its current generator turn to
+ * expose update handlers before draining pending coordinated updates.
+ */
+export declare function processPendingUpdatesAfterInlineAdvance(internals: EngineInternals, workflowId: string, callbacks: PendingUpdateCallbacks): Promise<void>;
+export declare function schedulePendingInlineUpdateDrain(internals: EngineInternals, workflowId: string, callbacks: PendingUpdateCallbacks): void;
+export declare function processPendingUpdatesForHandlers(internals: EngineInternals, workflowId: string, callbacks: PendingUpdateCallbacks): Promise<void>;
+export {};

package/dist/core/engine/pending-updates.js

@@ -0,0 +1,109 @@
+import { UpdateCompletedEvent, UpdateReceivedEvent } from "../events.js";
+import { UpdateValidationError } from "../updates.js";
+import {
+  extractStandardSchemaIssues,
+  invokeUpdateHandler as invokeUpdateHandlerFromInternals
+} from "./updates.js";
+async function waitForNextMacrotask() {
+  await new Promise((resolve) => {
+    setTimeout(resolve, 0);
+  });
+}
+async function waitForRegisteredUpdateHandlers(internals, workflowId) {
+  const inlineStrategy = internals.inlineStrategy;
+  if (inlineStrategy === null)
+    return !1;
+  let context = inlineStrategy.getContext(workflowId);
+  if (context && context.updateHandlers.size > 0)
+    return !0;
+  const pendingAdvance = inlineStrategy.waitForWorkflowAdvance(workflowId);
+  if (pendingAdvance) {
+    await pendingAdvance;
+    context = inlineStrategy.getContext(workflowId);
+    if (context && context.updateHandlers.size > 0)
+      return !0;
+  }
+  for (let attempt = 0;attempt < 5; attempt++) {
+    await waitForNextMacrotask();
+    context = inlineStrategy.getContext(workflowId);
+    if (context && context.updateHandlers.size > 0)
+      return !0;
+  }
+  return !1;
+}
+export async function invokeUpdateHandler(internals, name, handler, payload) {
+  return invokeUpdateHandlerFromInternals(internals, name, handler, payload);
+}
+export async function processPendingUpdatesAfterInlineAdvance(internals, workflowId, callbacks) {
+  if ((await internals.updateCoordinator.getPendingUpdates(workflowId)).length === 0)
+    return;
+  if (!await waitForRegisteredUpdateHandlers(internals, workflowId))
+    return;
+  await processPendingUpdatesForHandlers(internals, workflowId, callbacks);
+}
+export function schedulePendingInlineUpdateDrain(internals, workflowId, callbacks) {
+  if (internals.inlineStrategy === null)
+    return;
+  setTimeout(() => {
+    processPendingUpdatesForHandlers(internals, workflowId, callbacks).catch(() => {});
+  }, 0);
+}
+async function runPendingUpdateValidator(validator, updateName, payload) {
+  let result;
+  try {
+    result = await validator(payload);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return new UpdateValidationError(updateName, [{ message }]).message;
+  }
+  const issues = extractStandardSchemaIssues(result);
+  if (issues !== null && issues.length > 0)
+    return new UpdateValidationError(updateName, issues).message;
+  return null;
+}
+export async function processPendingUpdatesForHandlers(internals, workflowId, callbacks) {
+  const context = internals.inlineStrategy?.getContext(workflowId);
+  if (!context)
+    return;
+  const handlers = context.updateHandlers;
+  if (handlers.size === 0)
+    return;
+  const pendingUpdates = await internals.updateCoordinator.getPendingUpdates(workflowId);
+  if (pendingUpdates.length === 0)
+    return;
+  for (const update of pendingUpdates) {
+    const handler = handlers.get(update.name);
+    if (!handler)
+      continue;
+    const validatorRejectionError = await runValidatorIfPresent(context, update);
+    if (validatorRejectionError !== null) {
+      await rejectPendingUpdate(internals, workflowId, update, validatorRejectionError, callbacks);
+      continue;
+    }
+    await deliverPendingUpdate(internals, workflowId, update, handler, callbacks);
+  }
+}
+async function runValidatorIfPresent(context, update) {
+  const validator = context.updateValidators?.get(update.name);
+  if (validator === void 0)
+    return null;
+  return runPendingUpdateValidator(validator, update.name, update.payload);
+}
+async function rejectPendingUpdate(internals, workflowId, update, errorMessage, callbacks) {
+  const responseOperations = internals.updateCoordinator.buildResponseOperations(update.updateId, workflowId, void 0, errorMessage, update.idempotencyKey);
+  await internals.storage.batch(responseOperations);
+  callbacks.broadcast({ type: "update:completed", workflowId, updateId: update.updateId });
+}
+async function deliverPendingUpdate(internals, workflowId, update, handler, callbacks) {
+  callbacks.dispatchEvent(new UpdateReceivedEvent(update.updateId, workflowId, update.name, update.payload));
+  let result, error;
+  try {
+    result = await invokeUpdateHandler(internals, update.name, handler, update.payload);
+  } catch (handlerError) {
+    error = handlerError instanceof Error ? handlerError.message : String(handlerError);
+  }
+  const responseOperations = internals.updateCoordinator.buildResponseOperations(update.updateId, workflowId, result, error, update.idempotencyKey);
+  await internals.storage.batch(responseOperations);
+  callbacks.dispatchEvent(new UpdateCompletedEvent(update.updateId, workflowId, update.name, result, error));
+  callbacks.broadcast({ type: "update:completed", workflowId, updateId: update.updateId });
+}

package/dist/core/engine/persisted-data-version.d.ts

@@ -0,0 +1,24 @@
+import type { Storage as WeftStorage } from '../../storage/interface.ts';
+/**
+ * Read the persisted-data schema-version sentinel and throw
+ * {@link PersistedDataIncompatibleError} when it is older (or newer) than the
+ * engine's {@link CURRENT_PERSISTED_DATA_SCHEMA_VERSION}.
+ *
+ * Three cases:
+ *
+ * 1. Sentinel exists and matches: no-op.
+ * 2. Sentinel exists but is missing, unparseable, or disagrees with the
+ *    current version: throw `PersistedDataIncompatibleError`.
+ * 3. Sentinel is absent. Only stamp the storage when it carries no user
+ *    workflow data. Stamping a database that already holds workflow records,
+ *    schedules, checkpoints, or any other `wf:` / `op:` / `schedule:` / `ev:`
+ *    prefixed key would silently classify pre-versioned data (written by an
+ *    older Weft binary or by the `new Engine({ storage })` constructor path
+ *    before the sentinel was introduced) as schema-current and risk replaying
+ *    incompatible records. When user data is already present without a
+ *    sentinel, fail with `PersistedDataIncompatibleError(null, …)` so the
+ *    operator can choose explicitly whether to wipe and start fresh.
+ */
+export declare function assertCompatiblePersistedDataVersion(storage: WeftStorage, options?: {
+    allowLegacyData?: boolean;
+}): Promise<void>;