@lostgradient/weft 0.2.0

package/dist/core/engine/inline-launch-queue.js

@@ -0,0 +1,93 @@
+import { WorkflowStartedEvent } from "../events.js";
+import { startWorkflowExecution } from "./lifecycle.js";
+import { loadWorkflowState } from "./storage-io.js";
+export function queueInlineWorkflowExecutionStart(internals, start, callbacks) {
+  internals.queuedInlineWorkflowStartIds.add(start.workflowId);
+  internals.queuedOrLaunchingInlineWorkflowStartIds.add(start.workflowId);
+  internals.queuedInlineWorkflowStarts.push(start);
+  if (internals.queuedInlineWorkflowStartFlushScheduled)
+    return;
+  internals.queuedInlineWorkflowStartFlushScheduled = !0;
+  if (internals.queuedInlineWorkflowStartChannel !== null) {
+    internals.queuedInlineWorkflowStartChannel.port2.postMessage(void 0);
+    return;
+  }
+  setTimeout(() => {
+    internals.queuedInlineWorkflowStartFlushScheduled = !1;
+    callbacks.swallowPromiseRejection(flushQueuedInlineWorkflowStarts(internals, callbacks));
+  }, 0);
+}
+export async function flushQueuedInlineWorkflowStarts(internals, callbacks) {
+  if (internals.abortController.signal.aborted) {
+    internals.queuedInlineWorkflowStarts = [];
+    return;
+  }
+  if (internals.queuedInlineWorkflowStarts.length === 0)
+    return;
+  const pendingStarts = internals.queuedInlineWorkflowStarts;
+  internals.queuedInlineWorkflowStarts = [];
+  for (const start of pendingStarts)
+    await startQueuedInlineWorkflowExecution(internals, start, callbacks);
+}
+export async function flushQueuedInlineWorkflowStartsDirectly(internals, callbacks) {
+  internals.queuedInlineWorkflowStartFlushScheduled = !1;
+  await flushQueuedInlineWorkflowStarts(internals, callbacks);
+}
+async function startQueuedInlineWorkflowExecution(internals, start, callbacks) {
+  try {
+    const state = await loadWorkflowState(internals, start.workflowId);
+    if (!state || state.status !== "running")
+      return;
+    internals.queuedInlineWorkflowStartIds.delete(start.workflowId);
+    internals.engine.dispatchEvent(new WorkflowStartedEvent(start.workflowId, start.workflowType, start.input));
+    startWorkflowExecution(internals, start.workflowId, start.workflowType, start.input, start.checkpoint, start.nestingDepth, start.executionDeadline, start.executionStateOwnerId);
+    await callbacks.processPendingUpdatesAfterInlineAdvance(start.workflowId);
+  } finally {
+    internals.queuedInlineWorkflowStartIds.delete(start.workflowId);
+    internals.queuedOrLaunchingInlineWorkflowStartIds.delete(start.workflowId);
+  }
+}
+export function dropQueuedInlineWorkflowStart(internals, workflowId) {
+  if (internals.queuedInlineWorkflowStarts.length === 0)
+    return !1;
+  const initialLength = internals.queuedInlineWorkflowStarts.length;
+  internals.queuedInlineWorkflowStarts = internals.queuedInlineWorkflowStarts.filter((start) => start.workflowId !== workflowId);
+  if (internals.queuedInlineWorkflowStarts.length !== initialLength) {
+    internals.queuedInlineWorkflowStartIds.delete(workflowId);
+    internals.queuedOrLaunchingInlineWorkflowStartIds.delete(workflowId);
+  }
+  return internals.queuedInlineWorkflowStarts.length !== initialLength;
+}
+export function disposeQueuedInlineWorkflowStarts(internals) {
+  internals.queuedInlineWorkflowStartFlushScheduled = !1;
+  internals.queuedInlineWorkflowStarts = [];
+  internals.queuedInlineWorkflowStartIds.clear();
+  internals.queuedOrLaunchingInlineWorkflowStartIds.clear();
+  const channel = internals.queuedInlineWorkflowStartChannel;
+  if (channel !== null) {
+    channel.port1.close();
+    channel.port2.close();
+    internals.queuedInlineWorkflowStartChannel = null;
+  }
+}
+export function hasQueuedInlineWorkflowStart(internals, workflowId) {
+  return internals.queuedInlineWorkflowStartIds.has(workflowId);
+}
+export function hasQueuedOrLaunchingInlineWorkflowStart(internals, workflowId) {
+  return internals.queuedOrLaunchingInlineWorkflowStartIds.has(workflowId);
+}
+function workflowStatusCanRetainLocalOwnership(workflowStatus) {
+  return workflowStatus === "running" || workflowStatus === "pending";
+}
+export function isInlineWorkflowLocallyOwned(internals, workflowId, workflowStatus) {
+  if (!workflowStatusCanRetainLocalOwnership(workflowStatus))
+    return !1;
+  if (hasQueuedOrLaunchingInlineWorkflowStart(internals, workflowId))
+    return !0;
+  if (internals.inlineStrategy === null)
+    return !1;
+  return internals.inlineStrategy.getContext(workflowId) !== void 0 || internals.inlineStrategy.waitForWorkflowTurn(workflowId) !== void 0 || internals.parkedInlineWorkflows.has(workflowId);
+}
+export function hasLocalCheckpointOwnership(internals, workflowId, workflowStatus) {
+  return internals.checkpoints.has(workflowId) && workflowStatusCanRetainLocalOwnership(workflowStatus);
+}

package/dist/core/engine/inline-parking.d.ts

@@ -0,0 +1,26 @@
+import type { ContextOperationRequest } from '../context.ts';
+import type { WorkerOutboundMessage, WorkflowState } from '../types.ts';
+import type { EngineInternals } from './internals.ts';
+import { type LifecycleCallbacks } from './lifecycle.ts';
+import { type TerminationCallbacks } from './termination.ts';
+export type ParkedWorkflowResumeDisposition = 'resumable' | 'terminal-or-missing' | 'corrupt';
+export type InlineParkingCallbacks = {
+    createLifecycleCallbacks: () => LifecycleCallbacks;
+    createTerminationCallbacks: () => TerminationCallbacks;
+    evaluateConstraints: (workflowId: string) => Promise<boolean>;
+    getParkedWorkflowResumeDisposition: (workflowId: string) => Promise<ParkedWorkflowResumeDisposition>;
+    hasBufferedSignal: (workflowId: string, signalName: string) => Promise<boolean>;
+    loadWorkflowState: (workflowId: string) => Promise<WorkflowState | null>;
+    parkInlineWorkflowAfterCheckpoint: (workflowId: string, operation: ContextOperationRequest) => Promise<boolean>;
+    persistCheckpoint: (workflowId: string, operation: ContextOperationRequest, workerCheckpointBytes?: ArrayBuffer) => Promise<void>;
+    processOperation: (workflowId: string, operation: ContextOperationRequest) => Promise<void>;
+    readCheckpointBytes: (workflowId: string) => Promise<Uint8Array | null>;
+    resumeParkedInlineWorkflow: (workflowId: string) => Promise<void>;
+    runSerializedWorkflowStateWrite: <Result>(workflowId: string, writeOperation: () => Promise<Result>) => Promise<Result>;
+    translateOperationRequest: (operationRequest: unknown) => ContextOperationRequest;
+    validateDevelopmentCheckpoint: (workflowId: string) => void;
+};
+export declare function parkInlineWorkflowAfterCheckpoint(internals: EngineInternals, workflowId: string, operation: ContextOperationRequest, callbacks: InlineParkingCallbacks): Promise<boolean>;
+export declare function resumeParkedInlineWorkflow(internals: EngineInternals, workflowId: string, callbacks: InlineParkingCallbacks): Promise<void>;
+export declare function getParkedWorkflowResumeDisposition(internals: EngineInternals, workflowId: string, callbacks: InlineParkingCallbacks): Promise<ParkedWorkflowResumeDisposition>;
+export declare function handleStrategyMessage(internals: EngineInternals, message: WorkerOutboundMessage, callbacks: InlineParkingCallbacks): Promise<void>;

package/dist/core/engine/inline-parking.js

@@ -0,0 +1,86 @@
+import {
+  resumeWorkflowFromStorage as resumeWorkflowFromStorageFromLifecycle
+} from "./lifecycle.js";
+import {
+  completeWorkflow as completeWorkflowFromTermination,
+  failWorkflow as failWorkflowFromTermination
+} from "./termination.js";
+export async function parkInlineWorkflowAfterCheckpoint(internals, workflowId, operation, callbacks) {
+  if (operation.type !== "wait-signal" || internals.inlineStrategy === null)
+    return !1;
+  const inlineStrategy = internals.inlineStrategy, context = inlineStrategy.getContext(workflowId);
+  if (context?.hasUpdateHandlers || context?.hasExposedAccessors)
+    return !1;
+  if (await callbacks.hasBufferedSignal(workflowId, operation.signalName))
+    return !1;
+  if (!await callbacks.runSerializedWorkflowStateWrite(workflowId, async () => {
+    const latestState = await callbacks.loadWorkflowState(workflowId);
+    if (internals.terminalizingWorkflows.has(workflowId) || !latestState || latestState.status !== "running")
+      return !1;
+    inlineStrategy.parkWorkflow(workflowId);
+    internals.parkedInlineWorkflows.add(workflowId);
+    return !0;
+  }))
+    return !1;
+  if (await callbacks.hasBufferedSignal(workflowId, operation.signalName))
+    await callbacks.resumeParkedInlineWorkflow(workflowId);
+  return !0;
+}
+export async function resumeParkedInlineWorkflow(internals, workflowId, callbacks) {
+  if (!internals.parkedInlineWorkflows.has(workflowId))
+    return;
+  internals.parkedInlineWorkflows.delete(workflowId);
+  try {
+    await resumeWorkflowFromStorageFromLifecycle(internals, workflowId, !1, callbacks.createLifecycleCallbacks());
+  } catch (error) {
+    const resumeDisposition = await callbacks.getParkedWorkflowResumeDisposition(workflowId);
+    if (resumeDisposition === "resumable") {
+      internals.parkedInlineWorkflows.add(workflowId);
+      throw error;
+    }
+    if (resumeDisposition === "corrupt")
+      throw error;
+  }
+}
+export async function getParkedWorkflowResumeDisposition(internals, workflowId, callbacks) {
+  if (internals.terminalizingWorkflows.has(workflowId))
+    return "terminal-or-missing";
+  const state = await callbacks.loadWorkflowState(workflowId);
+  if (!state || state.status !== "running")
+    return "terminal-or-missing";
+  if (!await callbacks.readCheckpointBytes(workflowId))
+    return "corrupt";
+  return "resumable";
+}
+export async function handleStrategyMessage(internals, message, callbacks) {
+  switch (message.type) {
+    case "completed":
+      await completeWorkflowFromTermination(internals, message.workflowId, message.result, callbacks.createTerminationCallbacks());
+      break;
+    case "failed": {
+      const failedError = Error(message.error);
+      if (message.errorStack)
+        failedError.stack = message.errorStack;
+      await failWorkflowFromTermination(internals, message.workflowId, failedError, callbacks.createTerminationCallbacks(), message.failureCategory ?? "system");
+      break;
+    }
+    case "checkpoint": {
+      const operation = callbacks.translateOperationRequest(message.operationRequest);
+      await callbacks.persistCheckpoint(message.workflowId, operation, message.checkpoint);
+      callbacks.validateDevelopmentCheckpoint(message.workflowId);
+      if (await callbacks.evaluateConstraints(message.workflowId))
+        break;
+      if (await callbacks.parkInlineWorkflowAfterCheckpoint(message.workflowId, operation))
+        break;
+      if (operation.type === "wait-signal" && internals.inlineStrategy === null) {
+        callbacks.processOperation(message.workflowId, operation).catch((error) => {
+          const failedError = error instanceof Error ? error : Error(String(error));
+          return failWorkflowFromTermination(internals, message.workflowId, failedError, callbacks.createTerminationCallbacks(), "system");
+        });
+        break;
+      }
+      await callbacks.processOperation(message.workflowId, operation);
+      break;
+    }
+  }
+}

package/dist/core/engine/internals.d.ts

@@ -0,0 +1,167 @@
+/**
+ * EngineInternals — the shared mutable state object backing every Engine
+ * instance. Engine state lives here, on a WeakMap-backed object reached via
+ * `getInternals(this)`, rather than on `#private` class fields.
+ *
+ * Why a WeakMap instead of `private _field`?  TypeScript's `private` modifier
+ * is class-private, not module-private — sibling modules under
+ * `src/core/engine/` cannot access an Engine's `private _field` even though
+ * they live next to the class. The WeakMap pattern lets every extracted
+ * helper read and write the same mutable kernel state via
+ * `getInternals(engine)`, which type-checks under `strict: true`.
+ *
+ * Why not move state into a sub-service object?  Replay determinism depends
+ * on call ordering and field-access ordering staying identical to the
+ * pre-refactor engine. A single mutable container preserves that; ownership
+ * stays in one place.
+ *
+ * Internal-only.  This module is allow-listed for import only from
+ * `src/core/engine/**` (see documentation/internal-imports-allowlist.json).
+ */
+import type { AlertManager } from '../../alerting/alert-manager.ts';
+import type { Storage as WeftStorage } from '../../storage/interface.ts';
+import type { ActivityWorkerDispatcher } from '../../workers/activity-worker-dispatcher.ts';
+import type { ActivityRegistry } from '../activity-registry.ts';
+import type { EventHeadRecord } from '../event-log.ts';
+import type { ExecutionStrategy } from '../execution-strategy.ts';
+import type { InlineExecutionStrategy } from '../inline-execution-strategy.ts';
+import type { ComposedActivityInterceptor, ComposedWorkflowInterceptor, Interceptor } from '../interceptor.ts';
+import type { HumanReviewResult, ReviewCoordinator } from '../review/index.ts';
+import type { Scheduler } from '../scheduler.ts';
+import type { Checkpoint } from '../types.ts';
+import type { UpdateCoordinator } from '../updates.ts';
+import type { WorkflowVersionTuple } from '../workflow-version-tuple.ts';
+import type { PendingTimelineEntry, QueuedInlineWorkflowExecutionStart, RegistrationEntry, ResolvedOptions, TrackedWaiterKeys, WorkflowResultWaiter } from './engine-internal-types.ts';
+import type { ScheduleHandleEngine, WorkflowHandle, WorkflowHandleEngine } from './handles.ts';
+import type { WorkflowFeedListener } from './index.ts';
+type EngineRuntime = WorkflowHandleEngine & ScheduleHandleEngine;
+export interface EngineInternals {
+    engine: EngineRuntime;
+    storage: WeftStorage;
+    registrations: Map<string, RegistrationEntry>;
+    workflowTypesByHandler: WeakMap<Function, string>;
+    abortController: AbortController;
+    /**
+     * Set to `true` by {@link disposeEngine}. Guards post-dispose entry points
+     * (such as `handle.result()`) so they reject with {@link EngineDisposedError}
+     * instead of registering a waiter the torn-down engine can never settle.
+     */
+    disposed: boolean;
+    scheduler: Scheduler;
+    options: ResolvedOptions;
+    strategy: ExecutionStrategy;
+    inlineStrategy: InlineExecutionStrategy | null;
+    queuedInlineWorkflowStarts: QueuedInlineWorkflowExecutionStart[];
+    queuedInlineWorkflowStartIds: Set<string>;
+    queuedOrLaunchingInlineWorkflowStartIds: Set<string>;
+    queuedInlineWorkflowStartFlushScheduled: boolean;
+    queuedInlineWorkflowStartChannel: MessageChannel | null;
+    handleCache: Map<string, {
+        ref: WeakRef<WorkflowHandle>;
+        unregisterToken: object;
+    }>;
+    finalizationRegistry: FinalizationRegistry<string>;
+    resultResolvers: Map<string, WorkflowResultWaiter>;
+    signalWaiters: Map<string, () => void>;
+    signalWaitersByWorkflow: Map<string, TrackedWaiterKeys>;
+    updateWaiters: Map<string, (payload: unknown) => void>;
+    updateWaitersByWorkflow: Map<string, TrackedWaiterKeys>;
+    sleepResolvers: Map<string, () => void>;
+    sleepResolversByWorkflow: Map<string, Set<string>>;
+    interceptors: Interceptor[];
+    composedWorkflowInterceptor: ComposedWorkflowInterceptor | null | undefined;
+    composedActivityInterceptor: ComposedActivityInterceptor | null | undefined;
+    updateCoordinator: UpdateCoordinator;
+    activityRegistry: ActivityRegistry;
+    /**
+     * Per-workflow activity registries built from
+     * `workflow({ name }).activities({ ... }).execute(...)`. Indexed by workflow
+     * type. Phase 3 wires lookups via `activityRegistriesByWorkflow.get(type)`
+     * first, falling back to {@link EngineInternals.activityRegistry} so the
+     * legacy global path keeps working until Phase 6 removes it. Each registry
+     * is constructed from a defensive deep clone+freeze of the workflow's
+     * `activities` map so post-registration mutation cannot reach the engine.
+     */
+    activityRegistriesByWorkflow: Map<string, ActivityRegistry>;
+    /**
+     * Per-workflow definition references — the actual `WorkflowDefinition`
+     * object passed to `engine.register(workflow)`. Used for collision detection
+     * (same-reference re-register is idempotent; same-name-different-object
+     * throws) and as the canonical record of `BuiltWorkflowDefinition`s for
+     * worker-protocol qualified-name dispatch in Phase 4.
+     */
+    workflowDefinitionsByName: Map<string, object>;
+    /**
+     * In-memory cache of `workflowId -> workflowType` populated when a workflow
+     * starts executing (see lifecycle/start-exec.ts) and cleared on terminal
+     * cleanup. Lets the activity-dispatch hot path resolve the correct
+     * per-workflow registry synchronously without re-reading storage.
+     */
+    workflowTypeByWorkflowId: Map<string, string>;
+    activityWorkerDispatcher: ActivityWorkerDispatcher | null;
+    checkpoints: Map<string, Checkpoint>;
+    broadcastChannel: BroadcastChannel | null;
+    pendingNestingDepth: number | undefined;
+    pendingParentHeaders: Map<string, string> | undefined;
+    pendingExecutionStateOwnerId: string | undefined;
+    workflowNestingDepths: Map<string, number>;
+    workflowHeaders: Map<string, Map<string, string>>;
+    workflowStateWriteChains: Map<string, Promise<void>>;
+    heartbeatDetails: Map<string, unknown>;
+    /**
+     * Activities that called `ctx.completeAsync()` and are awaiting out-of-band
+     * completion via `engine.completeAsyncActivity` / `failAsyncActivity`, keyed
+     * by their durable task token. Mirrored to storage (`KEYS.asyncActivity`) and
+     * reloaded by `recoverAll()`. See `async-activity-completion.ts`.
+     */
+    pendingAsyncActivities: Map<string, import('./async-activity-completion.ts').PendingAsyncActivity>;
+    pendingStarts: Set<string>;
+    pendingScheduleCreations: Set<string>;
+    workflowsNeedingTerminalCleanup: Set<string>;
+    cleanupInterval: ReturnType<typeof setInterval> | null;
+    cleanupIntervalDisposalTracker: {
+        disposed: boolean;
+        cleanupInterval: ReturnType<typeof setInterval> | null;
+    } | null;
+    retentionSweepInterval: ReturnType<typeof setInterval> | null;
+    retentionSweepInFlight: Promise<void> | null;
+    nextRetentionSweepAt: number | null;
+    reviewCoordinator: ReviewCoordinator;
+    reviewWaiters: Map<string, (decision: HumanReviewResult) => void>;
+    reviewWaitersByWorkflow: Map<string, TrackedWaiterKeys>;
+    reviewEscalationHandlers: Map<string, (entry: {
+        id: string;
+        workflowId: string;
+    }) => Promise<boolean>>;
+    workflowReviewIds: Map<string, Set<string>>;
+    parkedInlineWorkflows: Set<string>;
+    terminalizingWorkflows: Set<string>;
+    cancelHandlersByWorkflow: Map<string, Array<() => Promise<void> | void>>;
+    reviewTimerIds: Map<string, string[]>;
+    pendingWebhooks: Set<AbortController>;
+    alertManager: AlertManager | null;
+    eventLogHeads: Map<string, Readonly<EventHeadRecord>>;
+    workflowFeedListeners: Map<string, Set<WorkflowFeedListener>>;
+    workflowVersionTuples: Map<string, WorkflowVersionTuple>;
+    pendingTimelineEntries: Map<string, PendingTimelineEntry>;
+}
+/**
+ * Set up an empty `EngineInternals` skeleton in the WeakMap. The Engine
+ * constructor calls this immediately after `super()`, before any field
+ * write, so subsequent `getInternals(this).fieldName = expr` assignments
+ * succeed.
+ *
+ * The constructor body then runs the same field-initialization expressions
+ * the original `engine.ts` had — preserving the original ordering, which
+ * is load-bearing for replay determinism.
+ */
+export declare function initializeInternals(engine: EngineRuntime): void;
+/**
+ * Look up the `EngineInternals` object for an Engine instance. Throws when
+ * `initializeInternals(engine)` has not been called yet — this only happens
+ * if a method runs before/around `super()` finishes (e.g. an event listener
+ * fires from the EventTarget super class). All Engine methods rely on
+ * internals existing.
+ */
+export declare function getInternals(engine: object): EngineInternals;
+export {};

package/dist/core/engine/internals.js

@@ -0,0 +1,11 @@
+const INTERNALS = new WeakMap;
+export function initializeInternals(engine) {
+  const internals = { engine };
+  INTERNALS.set(engine, internals);
+}
+export function getInternals(engine) {
+  const internals = INTERNALS.get(engine);
+  if (!internals)
+    throw Error("Engine internals not initialized \u2014 initializeInternals(this) was not called in the Engine constructor");
+  return internals;
+}

package/dist/core/engine/lifecycle/fork-helpers.d.ts

@@ -0,0 +1,9 @@
+import type { BatchOperation } from '../../../storage/interface.ts';
+import type { Checkpoint, ForkLineage, SearchAttributeValue, WorkflowState } from '../../types.ts';
+import { type WorkflowVersionTuple } from '../../workflow-version-tuple.ts';
+import type { EngineInternals } from '../internals.ts';
+import { type LifecycleCallbacks } from './shared.ts';
+export declare function createForkLineage(_internals: EngineInternals, sourceWorkflowId: string, checkpoint: Checkpoint, _callbacks: LifecycleCallbacks): ForkLineage;
+export declare function buildForkSearchAttributes(_internals: EngineInternals, checkpoint: Checkpoint, lineage: ForkLineage, _callbacks: LifecycleCallbacks): Record<string, SearchAttributeValue>;
+export declare function createForkedWorkflowState(_internals: EngineInternals, workflowId: string, sourceState: WorkflowState, versionTuple: WorkflowVersionTuple, lineage: ForkLineage, forkedAt: number, _callbacks: LifecycleCallbacks): WorkflowState;
+export declare function buildForkBatchOperations(_internals: EngineInternals, workflowId: string, state: WorkflowState, checkpoint: Checkpoint, serializedCheckpoint: Uint8Array, workflowStartHeaders: Map<string, string> | undefined, _callbacks: LifecycleCallbacks): BatchOperation[];

package/dist/core/engine/lifecycle/fork-helpers.js

@@ -0,0 +1,66 @@
+import { KEYS } from "../../../storage/interface.js";
+import { encode } from "../../codec.js";
+import { buildIndexOperations } from "../../search-attributes.js";
+import { encodeWorkflowStartHeaders } from "../state-utilities.js";
+import { buildWorkflowVisibilityIndexOperations } from "../workflow-indexes.js";
+import { EMPTY_STORAGE_VALUE, FORK_LINEAGE_ATTRIBUTE } from "./shared.js";
+export function createForkLineage(_internals, sourceWorkflowId, checkpoint, _callbacks) {
+  return {
+    workflowId: sourceWorkflowId,
+    step: checkpoint.step
+  };
+}
+export function buildForkSearchAttributes(_internals, checkpoint, lineage, _callbacks) {
+  return {
+    ...checkpoint.searchAttributes,
+    [FORK_LINEAGE_ATTRIBUTE]: lineage.workflowId
+  };
+}
+export function createForkedWorkflowState(_internals, workflowId, sourceState, versionTuple, lineage, forkedAt, _callbacks) {
+  return {
+    id: workflowId,
+    type: sourceState.type,
+    status: "running",
+    input: sourceState.input,
+    version: versionTuple.workflowVersion,
+    executionStateOwnerId: workflowId,
+    createdAt: forkedAt,
+    startedAt: forkedAt,
+    updatedAt: forkedAt,
+    ...versionTuple.agentVersion !== void 0 && {
+      agentVersion: versionTuple.agentVersion
+    },
+    ...versionTuple.toolVersions !== void 0 && {
+      toolVersions: versionTuple.toolVersions
+    },
+    forkedFrom: lineage
+  };
+}
+export function buildForkBatchOperations(_internals, workflowId, state, checkpoint, serializedCheckpoint, workflowStartHeaders, _callbacks) {
+  const operations = [
+    { type: "put", key: KEYS.workflow(workflowId), value: encode(state) },
+    {
+      type: "put",
+      key: KEYS.checkpoint(workflowId),
+      value: serializedCheckpoint
+    },
+    ...buildWorkflowVisibilityIndexOperations(workflowId, null, state).batchOps
+  ];
+  if (Object.keys(checkpoint.searchAttributes).length > 0)
+    operations.push({
+      type: "put",
+      key: KEYS.attribute(workflowId),
+      value: encode(checkpoint.searchAttributes)
+    }, ...buildIndexOperations(workflowId, {}, checkpoint.searchAttributes));
+  if (workflowStartHeaders && workflowStartHeaders.size > 0)
+    operations.push({
+      type: "put",
+      key: KEYS.workflowHeaders(workflowId),
+      value: encodeWorkflowStartHeaders(workflowStartHeaders)
+    }, {
+      type: "put",
+      key: KEYS.terminalCleanupNeeded(workflowId),
+      value: EMPTY_STORAGE_VALUE
+    });
+  return operations;
+}

package/dist/core/engine/lifecycle/persist.d.ts

@@ -0,0 +1,22 @@
+import type { Checkpoint, WorkflowState } from '../../types.ts';
+import { type WorkflowVersionDiff, type WorkflowVersionTuple } from '../../workflow-version-tuple.ts';
+import type { EngineInternals } from '../internals.ts';
+import { type LifecycleCallbacks, type RegistrationEntry } from './shared.ts';
+/** Build a {@link WorkflowVersionTuple} from a {@link RegistrationEntry}. */
+export declare function createWorkflowVersionTuple(_internals: EngineInternals, registration: RegistrationEntry, _callbacks: LifecycleCallbacks): WorkflowVersionTuple;
+export declare function workflowVersionTupleFromState(_internals: EngineInternals, state: WorkflowState, _callbacks: LifecycleCallbacks): WorkflowVersionTuple;
+export declare function workflowStateWithVersionTuple(internals: EngineInternals, state: WorkflowState, versionTuple: WorkflowVersionTuple, _callbacks: LifecycleCallbacks): WorkflowState;
+export declare function derivePreparedExecutionState(internals: EngineInternals, workflowId: string, state: WorkflowState, checkpoint: Checkpoint, registration: RegistrationEntry, callbacks: LifecycleCallbacks): {
+    state: WorkflowState;
+    checkpoint: Checkpoint;
+    versionTuple: WorkflowVersionTuple;
+    shouldPersistPreparedState: boolean;
+};
+export declare function prepareResumeState(internals: EngineInternals, workflowId: string, state: WorkflowState, checkpoint: Checkpoint, checkpointBytes: Uint8Array, registration: RegistrationEntry, callbacks: LifecycleCallbacks): Promise<{
+    state: WorkflowState;
+    checkpoint: Checkpoint;
+    serializedCheckpoint: Uint8Array;
+    versionTuple: WorkflowVersionTuple;
+}>;
+/** Throws a {@link VersionMismatchError} with a full version diff. Never returns. */
+export declare function throwVersionMismatch(_internals: EngineInternals, workflowId: string, state: WorkflowState, registration: RegistrationEntry, versionDiff: WorkflowVersionDiff, _callbacks: LifecycleCallbacks): never;

package/dist/core/engine/lifecycle/persist.js

@@ -0,0 +1,80 @@
+import { serializeCheckpoint } from "../../checkpoint.js";
+import { encode } from "../../codec.js";
+import {
+  VersionMismatchError,
+  buildVersionUpdateOperations,
+  checkVersionCompatibility,
+  migrateCheckpoint
+} from "../../versioning.js";
+import {
+  diffWorkflowVersionTuples
+} from "../../workflow-version-tuple.js";
+import { buildWorkflowVisibilityIndexTransition } from "../workflow-indexes.js";
+export function createWorkflowVersionTuple(_internals, registration, _callbacks) {
+  return {
+    workflowVersion: registration.version
+  };
+}
+export function workflowVersionTupleFromState(_internals, state, _callbacks) {
+  return {
+    workflowVersion: state.version,
+    ...state.agentVersion !== void 0 && { agentVersion: state.agentVersion },
+    ...state.toolVersions !== void 0 && { toolVersions: state.toolVersions }
+  };
+}
+export function workflowStateWithVersionTuple(internals, state, versionTuple, _callbacks) {
+  const {
+    agentVersion: _existingAgentVersion,
+    toolVersions: _existingToolVersions,
+    ...rest
+  } = state;
+  return {
+    ...rest,
+    version: versionTuple.workflowVersion,
+    updatedAt: internals.options.getNow(),
+    ...versionTuple.agentVersion !== void 0 && {
+      agentVersion: versionTuple.agentVersion
+    },
+    ...versionTuple.toolVersions !== void 0 && {
+      toolVersions: versionTuple.toolVersions
+    }
+  };
+}
+export function derivePreparedExecutionState(internals, workflowId, state, checkpoint, registration, callbacks) {
+  const compatibility = checkVersionCompatibility(checkpoint.version, registration.version, !!registration.migrate), registeredVersionTuple = createWorkflowVersionTuple(internals, registration, callbacks), versionDiff = diffWorkflowVersionTuples(workflowVersionTupleFromState(internals, state, callbacks), registeredVersionTuple), hasVersionTupleDrift = versionDiff.workflowVersion !== void 0 || versionDiff.agentVersion !== void 0 || versionDiff.toolVersions !== void 0;
+  if (compatibility === "incompatible" || hasVersionTupleDrift && !registration.migrate)
+    throwVersionMismatch(internals, workflowId, state, registration, versionDiff, callbacks);
+  let preparedState = state, preparedCheckpoint = checkpoint, shouldPersistPreparedState = !1;
+  if ((compatibility === "needs-migration" || hasVersionTupleDrift) && registration.migrate) {
+    const migrated = migrateCheckpoint(checkpoint, checkpoint.version, registration.version, registration.migrate);
+    migrated.version = registeredVersionTuple.workflowVersion;
+    preparedCheckpoint = migrated;
+    preparedState = workflowStateWithVersionTuple(internals, state, registeredVersionTuple, callbacks);
+    shouldPersistPreparedState = !0;
+  }
+  return {
+    state: preparedState,
+    checkpoint: preparedCheckpoint,
+    versionTuple: registeredVersionTuple,
+    shouldPersistPreparedState
+  };
+}
+export async function prepareResumeState(internals, workflowId, state, checkpoint, checkpointBytes, registration, callbacks) {
+  const preparedExecutionState = derivePreparedExecutionState(internals, workflowId, state, checkpoint, registration, callbacks);
+  if (preparedExecutionState.shouldPersistPreparedState) {
+    const versionVisibilityOperations = buildWorkflowVisibilityIndexTransition(workflowId, state, preparedExecutionState.state).batchOps;
+    await internals.storage.batch([
+      ...buildVersionUpdateOperations(workflowId, serializeCheckpoint(preparedExecutionState.checkpoint), preparedExecutionState.versionTuple.workflowVersion, encode(preparedExecutionState.state)),
+      ...versionVisibilityOperations
+    ]);
+  }
+  return {
+    state: preparedExecutionState.state,
+    checkpoint: preparedExecutionState.checkpoint,
+    serializedCheckpoint: preparedExecutionState.shouldPersistPreparedState ? serializeCheckpoint(preparedExecutionState.checkpoint) : checkpointBytes,
+    versionTuple: preparedExecutionState.versionTuple
+  };
+}
+export function throwVersionMismatch(_internals, workflowId, state, registration, versionDiff, _callbacks) {
+  throw new VersionMismatchError(workflowId, state.type, state.version, registration.version, void 0, versionDiff);
+}

package/dist/core/engine/lifecycle/resume.d.ts

@@ -0,0 +1,4 @@
+import { type WorkflowHandle } from '../handles.ts';
+import type { EngineInternals } from '../internals.ts';
+import { type LifecycleCallbacks } from './shared.ts';
+export declare function resumeWorkflowFromStorage(internals: EngineInternals, workflowId: string, dispatchResumedEvent: boolean, callbacks: LifecycleCallbacks): Promise<WorkflowHandle>;