@lostgradient/weft 0.11.0 → 0.13.0

package/dist/core/engine/index.js

@@ -22,7 +22,10 @@ import {
   completeAsyncActivity as completeAsyncActivityFromInternals,
   failAsyncActivity as failAsyncActivityFromInternals
 } from "./async-activity-completion.js";
-import { recoverPendingAsyncActivities } from "./async-activity-records.js";
+import {
+  listPendingAsyncActivities as listPendingAsyncActivitiesFromInternals,
+  recoverPendingAsyncActivities
+} from "./async-activity-records.js";
 import { broadcast as broadcastFromInternals } from "./broadcast.js";
 import {
   cancelAll as cancelAllWorkflows,
@@ -81,6 +84,7 @@ import {
 } from "./errors.js";
 import { assertLeaseHeldForEngineWork, commitFencedEngineWrite } from "./fenced-write.js";
 import { recordFinalizerState } from "./finalizer-state.js";
+import { getFinalizerStatus as getFinalizerStatusFromInternals } from "./finalizer-status.js";
 import {
   createWorkflowHandleWithResultPromise as createWorkflowHandleWithResultPromiseFromInternals,
   getWorkflowResultPromise as getWorkflowResultPromiseFromInternals
@@ -134,6 +138,7 @@ import {
   submitReview as submitReviewFromInternals
 } from "./reviews.js";
 import { ScheduleHandle } from "./schedule-handle.js";
+import { decodeScheduleRunMetadata } from "./schedule-run-metadata.js";
 import {
   cancelSchedule as cancelScheduleFromInternals,
   listSchedules as listSchedulesFromInternals,
@@ -306,9 +311,12 @@ export class Engine extends EventTarget {
     getInternals(this).pendingNestingDepth = void 0;
     getInternals(this).pendingParentHeaders = void 0;
     getInternals(this).pendingExecutionStateOwnerId = void 0;
+    getInternals(this).pendingParentWorkflowId = void 0;
+    getInternals(this).pendingParentWorkflowExecutionToken = void 0;
     getInternals(this).workflowNestingDepths = new Map;
     getInternals(this).workflowHeaders = new Map;
     getInternals(this).workflowStateWriteChains = new Map;
+    getInternals(this).scheduleStateOperationChains = new Map;
     getInternals(this).finalizationRegistry = new FinalizationRegistry(createHandleCacheFinalizer(getInternals(this).handleCache));
     getInternals(this).options = resolvedOptions;
     getInternals(this).scheduler = new Scheduler({
@@ -641,11 +649,13 @@ export class Engine extends EventTarget {
     return untagAllWorkflows(getInternals(this), filter, tags, options);
   }
   async schedule(typeOrDefinition, input, spec, options) {
+    const internals = getInternals(this);
+    assertLeaseHeldForEngineWork(internals);
     if (typeof typeOrDefinition === "object")
-      return scheduleDefinitionFromInternals(getInternals(this), typeOrDefinition);
+      return scheduleDefinitionFromInternals(internals, typeOrDefinition);
     if (spec === void 0)
       throw Error("A cron string or schedule spec must be provided when scheduling by workflow type.");
-    return scheduleFromInternals(getInternals(this), typeOrDefinition, input, spec, options);
+    return scheduleFromInternals(internals, typeOrDefinition, input, spec, options);
   }
   async getSchedule(scheduleId) {
     const normalizedScheduleId = coerceScheduleId(scheduleId, "scheduleId"), state = await loadScheduleState(getInternals(this), normalizedScheduleId);
@@ -655,16 +665,24 @@ export class Engine extends EventTarget {
     return listSchedulesFromInternals(getInternals(this), filter);
   }
   async pauseSchedule(scheduleId) {
-    return pauseScheduleFromInternals(getInternals(this), scheduleId);
+    const internals = getInternals(this);
+    assertLeaseHeldForEngineWork(internals);
+    return pauseScheduleFromInternals(internals, scheduleId);
   }
   async resumeSchedule(scheduleId) {
-    return resumeScheduleFromInternals(getInternals(this), scheduleId);
+    const internals = getInternals(this);
+    assertLeaseHeldForEngineWork(internals);
+    return resumeScheduleFromInternals(internals, scheduleId);
   }
   async cancelSchedule(scheduleId) {
-    return cancelScheduleFromInternals(getInternals(this), scheduleId);
+    const internals = getInternals(this);
+    assertLeaseHeldForEngineWork(internals);
+    return cancelScheduleFromInternals(internals, scheduleId);
   }
-  async updateSchedule(scheduleId, newSpec) {
-    return updateScheduleFromInternals(getInternals(this), scheduleId, newSpec);
+  async updateSchedule(scheduleId, newSpec, options) {
+    const internals = getInternals(this);
+    assertLeaseHeldForEngineWork(internals);
+    return updateScheduleFromInternals(internals, scheduleId, newSpec, options);
   }
   [HANDLE_RESULT_PROMISE](workflowId) {
     return getWorkflowResultPromiseFromInternals(getInternals(this), workflowId);
@@ -721,6 +739,9 @@ export class Engine extends EventTarget {
       finalizeTimeline: (workflowId, status, output) => finalizePendingTimelineEntry(getInternals(this), workflowId, status, output)
     });
   }
+  async listPendingAsyncActivities(workflowId, options) {
+    return listPendingAsyncActivitiesFromInternals(getInternals(this), workflowId, options);
+  }
   async failAsyncActivity(token, error) {
     await failAsyncActivityFromInternals(getInternals(this), token, error, {
       feedOperationResult: (workflowId, outcome, originalReason) => feedOperationResult(getInternals(this), workflowId, outcome, originalReason),
@@ -742,6 +763,48 @@ export class Engine extends EventTarget {
       return { ...state, status: "pending" };
     return state;
   }
+  async getScheduleProvenance(workflowId) {
+    const bytes = await getInternals(this).storage.get(KEYS.scheduleRunLink(workflowId));
+    if (bytes === null)
+      return null;
+    const metadata = decodeScheduleRunMetadata(bytes);
+    if (metadata === null)
+      return null;
+    return {
+      scheduleId: metadata.id,
+      ...metadata.occurrence === void 0 ? {} : { occurrence: metadata.occurrence }
+    };
+  }
+  async getFinalizerStatus(workflowId) {
+    const internals = getInternals(this), state = await loadWorkflowState(internals, workflowId);
+    return getFinalizerStatusFromInternals(internals, workflowId, state);
+  }
+  getLeaseHealth() {
+    const internals = getInternals(this);
+    if (internals.options.ownershipMode === "none")
+      return { mode: "none", status: "disabled", holdsLease: !1 };
+    if (internals.deposed) {
+      const lastKnownLease = internals.leaseManager?.health();
+      if (lastKnownLease !== void 0 && lastKnownLease.status !== "no-lease")
+        return {
+          mode: "lease",
+          ...lastKnownLease,
+          status: "contested",
+          holdsLease: !1,
+          lossReason: "deposed"
+        };
+      return {
+        mode: "lease",
+        status: "contested",
+        holdsLease: !1,
+        lossReason: "deposed"
+      };
+    }
+    return {
+      mode: "lease",
+      ...internals.leaseManager?.health() ?? { status: "no-lease", holdsLease: !1 }
+    };
+  }
   async getCurrentCheckpointStep(workflowId) {
     const inMemory = getInternals(this).checkpoints.get(workflowId);
     if (inMemory !== void 0)

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

@@ -175,9 +175,12 @@ export interface EngineInternals {
     pendingNestingDepth: number | undefined;
     pendingParentHeaders: Map<string, string> | undefined;
     pendingExecutionStateOwnerId: string | null | undefined;
+    pendingParentWorkflowId: string | undefined;
+    pendingParentWorkflowExecutionToken: string | undefined;
     workflowNestingDepths: Map<string, number>;
     workflowHeaders: Map<string, Map<string, string>>;
     workflowStateWriteChains: Map<string, Promise<void>>;
+    scheduleStateOperationChains: Map<string, Promise<void>>;
     heartbeatDetails: Map<string, unknown>;
     /**
      * Last heartbeat payload PER ACTIVITY STEP, so a retry of a step can read the

package/dist/core/engine/lease-health.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Why a holder lost its lease while running. `deposed` is confirmed ownership
+ * loss; `renewal-unconfirmable` means storage failures outlasted the last
+ * confirmed lease expiry.
+ *
+ * @example
+ * ```ts
+ * import type { LeaseLostReason } from '@lostgradient/weft';
+ *
+ * function requiresImmediateHandoff(reason: LeaseLostReason): boolean {
+ *   return reason === 'deposed';
+ * }
+ * void requiresImmediateHandoff;
+ * ```
+ */
+export type LeaseLostReason = 'deposed' | 'renewal-unconfirmable';
+/** Process-local, last-known ownership state exposed through the operator API. */
+export type LeaseManagerHealth = {
+    status: 'no-lease';
+    holdsLease: false;
+} | {
+    status: 'healthy';
+    holdsLease: true;
+    holderId: string;
+    heldSince: number;
+    expiresAt: number;
+    lastRenewedAt: number;
+    fencingEpoch: number;
+} | {
+    status: 'contested';
+    holdsLease: false;
+    lossReason?: LeaseLostReason;
+    holderId: string;
+    heldSince: number;
+    expiresAt: number;
+    lastRenewedAt: number;
+    fencingEpoch: number;
+};
+/**
+ * Public engine ownership-health snapshot returned by
+ * {@link Engine.getLeaseHealth} and `weft.system.lease`.
+ *
+ * @example
+ * ```ts
+ * import type { EngineLeaseHealth } from '@lostgradient/weft';
+ *
+ * function needsOperatorAttention(health: EngineLeaseHealth): boolean {
+ *   return health.status === 'contested';
+ * }
+ * void needsOperatorAttention;
+ * ```
+ */
+export type EngineLeaseHealth = {
+    mode: 'none';
+    status: 'disabled';
+    holdsLease: false;
+} | ({
+    mode: 'lease';
+} & LeaseManagerHealth) | {
+    mode: 'lease';
+    status: 'contested';
+    holdsLease: false;
+    lossReason: 'deposed';
+};

package/dist/core/engine/lease-manager.d.ts

@@ -44,8 +44,8 @@
  * @module core/engine/lease-manager
  */
 import { type Storage } from '../../storage/interface.ts';
-/** Why a holder lost its lease — surfaced to {@link LeaseManagerOptions.onLeaseLost}. */
-export type LeaseLostReason = 'deposed' | 'renewal-unconfirmable';
+import type { LeaseLostReason, LeaseManagerHealth } from './lease-health.ts';
+export type { LeaseLostReason } from './lease-health.ts';
 /** Options for {@link createLeaseManager}. */
 export type LeaseManagerOptions = {
     storage: Storage;
@@ -102,6 +102,8 @@ export type LeaseManager = {
     startRenewal(): void;
     renewOnce(): Promise<void>;
     currentEpochBytes(): Uint8Array | null;
+    /** Return a defensive, synchronous view of this process's last-known lease state. */
+    health(): LeaseManagerHealth;
     release(): Promise<void>;
     stop(): void;
 };

package/dist/core/engine/lease-manager.js

@@ -9,12 +9,13 @@ import { EngineLeaseAcquisitionTimeoutError, EngineLeaseCorruptedError } from ".
 const DEFAULT_ACQUIRE_POLL_INTERVAL_MS = 1000;
 export function createLeaseManager(options) {
   const { storage, holderId, getNow, ttlMs, renewIntervalMs, waitTimeoutMs } = options, acquirePollIntervalMs = options.acquirePollIntervalMs ?? DEFAULT_ACQUIRE_POLL_INTERVAL_MS;
-  let stopped = !1, heldEpoch = null, heldEpochBytes = null, lastHolderBytes = null, renewalInterval = null, leaseLost = !1, inFlightRenewal = null;
+  let stopped = !1, heldEpoch = null, heldEpochBytes = null, lastHolderBytes = null, renewalInterval = null, leaseLost = !1, leaseLostReason = null, heldSince = null, lastRenewedAt = null, inFlightRenewal = null;
   const delay = options.delay ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
   function reportLeaseLost(reason) {
     if (leaseLost)
       return;
     leaseLost = !0;
+    leaseLostReason = reason;
     options.onLeaseLost?.(reason);
   }
   async function readState() {
@@ -27,7 +28,7 @@ export function createLeaseManager(options) {
     };
   }
   async function takeOwnership(expectedEpochBytes, expectedHolderBytes, nextEpoch) {
-    const expiresAt = getNow() + ttlMs, holderBytes = encodeHolder({ holderId, expiresAt, epoch: nextEpoch }), committed = await storageConditionalBatch(storage, [
+    const acquiredAt = getNow(), expiresAt = acquiredAt + ttlMs, holderBytes = encodeHolder({ holderId, expiresAt, epoch: nextEpoch }), committed = await storageConditionalBatch(storage, [
       { key: KEYS.leaseEpoch(), expectedValue: expectedEpochBytes },
       { key: KEYS.leaseHolder(), expectedValue: expectedHolderBytes }
     ], [
@@ -38,6 +39,8 @@ export function createLeaseManager(options) {
       heldEpoch = nextEpoch;
       heldEpochBytes = encodeEpoch(nextEpoch);
       lastHolderBytes = holderBytes;
+      heldSince = acquiredAt;
+      lastRenewedAt = acquiredAt;
     }
     return committed;
   }
@@ -75,7 +78,7 @@ export function createLeaseManager(options) {
   async function renewOnce() {
     if (stopped || leaseLost || heldEpoch === null || lastHolderBytes === null)
       return;
-    const expiresAt = getNow() + ttlMs, holderBytes = encodeHolder({ holderId, expiresAt, epoch: heldEpoch });
+    const renewedAt = getNow(), expiresAt = renewedAt + ttlMs, holderBytes = encodeHolder({ holderId, expiresAt, epoch: heldEpoch });
     let committed;
     try {
       committed = await storageConditionalBatch(storage, [{ key: KEYS.leaseHolder(), expectedValue: lastHolderBytes }], [{ type: "put", key: KEYS.leaseHolder(), value: holderBytes }]);
@@ -87,6 +90,7 @@ export function createLeaseManager(options) {
     }
     if (committed) {
       lastHolderBytes = holderBytes;
+      lastRenewedAt = renewedAt;
       return;
     }
     reportLeaseLost("deposed");
@@ -109,6 +113,30 @@ export function createLeaseManager(options) {
   function currentEpochBytes() {
     return heldEpochBytes === null ? null : heldEpochBytes.slice();
   }
+  function health() {
+    if (stopped)
+      return { status: "no-lease", holdsLease: !1 };
+    const holder = lastHolderBytes === null ? null : decodeHolder(lastHolderBytes);
+    if (holder === null || heldEpoch === null || heldSince === null || lastRenewedAt === null)
+      return { status: "no-lease", holdsLease: !1 };
+    const lastKnownLease = {
+      holderId: holder.holderId,
+      heldSince,
+      expiresAt: holder.expiresAt,
+      lastRenewedAt,
+      fencingEpoch: heldEpoch
+    };
+    if (leaseLostReason !== null)
+      return {
+        status: "contested",
+        holdsLease: !1,
+        lossReason: leaseLostReason,
+        ...lastKnownLease
+      };
+    if (getNow() >= holder.expiresAt)
+      return { status: "contested", holdsLease: !1, ...lastKnownLease };
+    return { status: "healthy", holdsLease: !0, ...lastKnownLease };
+  }
   function clearRenewal() {
     if (renewalInterval !== null) {
       clearInterval(renewalInterval);
@@ -131,5 +159,5 @@ export function createLeaseManager(options) {
     stopped = !0;
     clearRenewal();
   }
-  return { acquire, startRenewal, renewOnce, currentEpochBytes, release, stop };
+  return { acquire, startRenewal, renewOnce, currentEpochBytes, health, release, stop };
 }

package/dist/core/engine/lifecycle/recovered-services.js

@@ -80,7 +80,5 @@ async function scheduleFromWorkflowState(internals, state) {
     return metadata;
   if (metadata.occurrence !== void 0 && scheduleState.nextFireAt === metadata.occurrence)
     return metadata;
-  if (metadata.occurrence === void 0 && scheduleState.overlap === "queue" && scheduleState.queuedRuns > 0)
-    return metadata;
   return null;
 }

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

@@ -57,6 +57,25 @@ export type RecoverAllOptions = {
      * recovery continues with its siblings.
      */
     onRecoveredWorkflow?: (info: RecoveredWorkflowInfo) => void | Promise<void>;
+    /**
+     * Policy for a recovered workflow whose persisted
+     * {@link WorkflowVersionTuple} or checkpoint `version` no longer matches the
+     * registered {@link WorkflowDefinition.version}. Recovery checks both
+     * persisted records against the registered version so current workflow-state
+     * metadata cannot mask a stale checkpoint version. The mismatch is detected
+     * before `resolveWorkflowServices` and `onRecoveredWorkflow` run for that
+     * workflow, so a mismatched run never re-provides services or invokes the
+     * hook.
+     *
+     * - `'fail-run'` (default): fail only the mismatched run to a terminal
+     *   `failed` state with a `system` failure category carrying the
+     *   {@link VersionMismatchError} message, then continue recovering its
+     *   siblings. The run never advances user workflow code.
+     * - `'throw'`: use fail-fast recovery — rethrow the
+     *   {@link VersionMismatchError} out of `recoverAll()` immediately, leaving
+     *   every workflow not yet processed in this batch unresumed.
+     */
+    versionMismatchPolicy?: 'fail-run' | 'throw';
 };
 export type LifecycleCallbacks = {
     dispatchEvent: (event: Event) => void;
@@ -97,6 +116,15 @@ export type LifecycleCallbacks = {
      * other workflows from the same storage backend.
      */
     failWorkflowForCheckpointDecodeError: (workflowId: string, error: Error) => Promise<void>;
+    /**
+     * Force a recovered workflow to a terminal `failed` state because its
+     * persisted version metadata no longer matches the registered
+     * `WorkflowDefinition.version` (a {@link VersionMismatchError}). Fails just
+     * this run with a `system` failure category so `recoverAll()` can continue
+     * recovering other workflows under the default `'fail-run'`
+     * {@link RecoverAllOptions.versionMismatchPolicy}.
+     */
+    failWorkflowForVersionMismatch: (workflowId: string, error: Error) => Promise<void>;
 };
 /**
  * Pre-replay history circuit breaker. Called at every restore-from-checkpoint

package/dist/core/engine/lifecycle/start-batch.js

@@ -19,6 +19,7 @@ export function buildStartBatchOperations(_internals, workflowId, state, checkpo
     },
     ...visibilityIndexOperations,
     ...buildWorkflowTagIndexOperations(workflowId, void 0, state.tags),
+    ...buildChildWorkflowIndexOperations(state),
     ...buildInitialSearchAttributeOperations(_internals, workflowId, registration, options?.searchAttributes, callbacks),
     ...buildPerRunScratchOperations(workflowId, options, workflowStartHeaders),
     ...additionalOperations ?? []
@@ -34,6 +35,17 @@ export function buildStartBatchOperations(_internals, workflowId, state, checkpo
     operations.push(...buildTimerBatchOperations(delayedStartTimer));
   return operations;
 }
+function buildChildWorkflowIndexOperations(state) {
+  if (state.parentWorkflowId === void 0)
+    return [];
+  return [
+    {
+      type: "put",
+      key: KEYS.childWorkflowByParent(state.parentWorkflowId, state.parentWorkflowExecutionToken, state.id),
+      value: EMPTY_STORAGE_VALUE
+    }
+  ];
+}
 function buildPerRunScratchOperations(workflowId, options, workflowStartHeaders) {
   const hasHeaders = workflowStartHeaders !== void 0 && workflowStartHeaders.size > 0, hasServices = options?.services !== void 0, operations = [];
   if (hasHeaders)

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

@@ -9,5 +9,5 @@ export declare function start(internals: EngineInternals, type: string, input: u
 export declare function startWorkflow(internals: EngineInternals, type: string, input: unknown, options: StartWorkflowOptions | undefined, additionalStartOperations: BatchOperation[] | undefined, callbacks: LifecycleCallbacks, buildIdempotentStartOperations?: BuildIdempotentStartOperations): Promise<WorkflowHandle>;
 export declare function resolveScheduledStartAt(internals: EngineInternals, options: StartOptions | undefined, submissionTime: number, callbacks: LifecycleCallbacks): number | undefined;
 export declare function parseStartOptionDuration(_internals: EngineInternals, duration: Duration, fieldName: 'options.executionTimeout' | 'options.startAfter', _callbacks: LifecycleCallbacks): number;
-export declare function createInitialWorkflowState(internals: EngineInternals, workflowId: string, type: string, input: unknown, versionTuple: WorkflowVersionTuple, options: StartOptions | undefined, tags: string[] | undefined, executionStateOwnerId: string | undefined, delayedStartTimer: TimerEntry | undefined, callbacks: LifecycleCallbacks): WorkflowState;
+export declare function createInitialWorkflowState(internals: EngineInternals, workflowId: string, type: string, input: unknown, versionTuple: WorkflowVersionTuple, options: StartOptions | undefined, tags: string[] | undefined, executionStateOwnerId: string | undefined, parentWorkflowId: string | undefined, parentWorkflowExecutionToken: string | undefined, delayedStartTimer: TimerEntry | undefined, callbacks: LifecycleCallbacks): WorkflowState;
 export declare function createInitialCheckpoint(internals: EngineInternals, workflowId: string, workflowVersion: string, options: StartOptions | undefined, _callbacks: LifecycleCallbacks): Checkpoint;

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

@@ -38,6 +38,10 @@ function prepareStartWorkflow(internals, options, callbacks) {
   internals.pendingParentHeaders = void 0;
   const pendingExecutionStateOwnerId = internals.pendingExecutionStateOwnerId, executionStateOwnerId = pendingExecutionStateOwnerId === null ? void 0 : pendingExecutionStateOwnerId ?? workflowId;
   internals.pendingExecutionStateOwnerId = void 0;
+  const parentWorkflowId = internals.pendingParentWorkflowId;
+  internals.pendingParentWorkflowId = void 0;
+  const parentWorkflowExecutionToken = internals.pendingParentWorkflowExecutionToken;
+  internals.pendingParentWorkflowExecutionToken = void 0;
   const submissionTime = internals.options.getNow(), scheduledStartAt = resolveScheduledStartAt(internals, options, submissionTime, callbacks), normalizedTags = normalizeStartWorkflowTags(internals, options?.tags, void 0, callbacks), delayedStartTimer = scheduledStartAt !== void 0 && scheduledStartAt > submissionTime ? createDelayedStartTimerEntry(internals, workflowId, scheduledStartAt, options, {
     parseStartOptionDuration: (value, fieldName) => parseStartOptionDuration(internals, value, fieldName, callbacks)
   }) : void 0;
@@ -46,6 +50,8 @@ function prepareStartWorkflow(internals, options, callbacks) {
     callerProvidedId,
     parentHeaders,
     executionStateOwnerId,
+    parentWorkflowId,
+    parentWorkflowExecutionToken,
     submissionTime,
     delayedStartTimer,
     normalizedTags
@@ -70,7 +76,15 @@ export async function startWorkflow(internals, type, input, options, additionalS
   const workflowConcurrency = registration.concurrency;
   assertServicesSupportedForMode(internals, options);
   assertValidOnTerminalConflict(options);
-  const preparation = prepareStartWorkflow(internals, options, callbacks), { workflowId, callerProvidedId, parentHeaders, executionStateOwnerId, delayedStartTimer } = preparation;
+  const preparation = prepareStartWorkflow(internals, options, callbacks), {
+    workflowId,
+    callerProvidedId,
+    parentHeaders,
+    executionStateOwnerId,
+    parentWorkflowId,
+    parentWorkflowExecutionToken,
+    delayedStartTimer
+  } = preparation;
   assertDeferSupported(internals, options, Boolean(delayedStartTimer));
   if (internals.pendingStarts.has(workflowId))
     throw new WorkflowAlreadyExistsError(workflowId);
@@ -79,7 +93,9 @@ export async function startWorkflow(internals, type, input, options, additionalS
   try {
     const terminalRunToPurge = callerProvidedId ? await resolveTerminalConflictForRestart(internals, workflowId, options) : null;
     assertPayloadWithinLimit(input, internals.options.payloadSizePolicy.maxBytes, "workflow input");
-    const versionTuple = createWorkflowVersionTuple(internals, registration, callbacks), state = createInitialWorkflowState(internals, workflowId, type, input, versionTuple, options, preparation.normalizedTags, executionStateOwnerId, delayedStartTimer, callbacks), checkpoint = createInitialCheckpoint(internals, workflowId, versionTuple.workflowVersion, options, callbacks), workflowStartHeaders = runWorkflowStartInterceptor(internals, workflowId, type, input, parentHeaders, callbacks), persistedWorkflowStartHeaders = selectPersistedWorkflowStartHeaders(workflowStartHeaders), purgeDeleteOperations = terminalRunToPurge !== null ? await prepareTerminalRunPurge(internals, terminalRunToPurge, callbacks) : void 0;
+    const versionTuple = createWorkflowVersionTuple(internals, registration, callbacks), state = createInitialWorkflowState(internals, workflowId, type, input, versionTuple, options, preparation.normalizedTags, executionStateOwnerId, parentWorkflowId, parentWorkflowExecutionToken, delayedStartTimer, callbacks);
+    applyRestartLineage(state, terminalRunToPurge);
+    const checkpoint = createInitialCheckpoint(internals, workflowId, versionTuple.workflowVersion, options, callbacks), workflowStartHeaders = runWorkflowStartInterceptor(internals, workflowId, type, input, parentHeaders, callbacks), persistedWorkflowStartHeaders = selectPersistedWorkflowStartHeaders(workflowStartHeaders), purgeDeleteOperations = terminalRunToPurge !== null ? await prepareTerminalRunPurge(internals, terminalRunToPurge, callbacks) : void 0;
     internals.checkpoints.set(workflowId, checkpoint);
     setWorkflowStartHeaders(internals, workflowId, workflowStartHeaders, callbacks);
     internals.workflowVersionTuples.set(workflowId, versionTuple);
@@ -121,6 +137,17 @@ export async function startWorkflow(internals, type, input, options, additionalS
       rollbackTransientStartState(internals, workflowId);
   }
 }
+function applyRestartLineage(state, displacedState) {
+  if (displacedState === null)
+    return;
+  state.restartedFrom = {
+    workflowId: displacedState.id,
+    ...displacedState.workflowExecutionToken !== void 0 && {
+      workflowExecutionToken: displacedState.workflowExecutionToken
+    },
+    replacedAt: state.createdAt
+  };
+}
 export function resolveScheduledStartAt(internals, options, submissionTime, callbacks) {
   assertExclusiveStartWorkflowOptions(options?.startAt, options?.startAfter);
   if (options?.startAt !== void 0)
@@ -138,7 +165,7 @@ export function resolveScheduledStartAt(internals, options, submissionTime, call
 export function parseStartOptionDuration(_internals, duration, fieldName, _callbacks) {
   return parseStartWorkflowDuration(duration, fieldName);
 }
-function buildInitialIdentitySlice(workflowId, type, input, versionTuple, executionStateOwnerId, delayedStartTimer, now, tags) {
+function buildInitialIdentitySlice(workflowId, type, input, versionTuple, executionStateOwnerId, parentWorkflowId, parentWorkflowExecutionToken, delayedStartTimer, now, tags) {
   return {
     id: workflowId,
     type,
@@ -147,6 +174,8 @@ function buildInitialIdentitySlice(workflowId, type, input, versionTuple, execut
     versionTuple,
     workflowExecutionToken: crypto.randomUUID(),
     ...executionStateOwnerId !== void 0 && { executionStateOwnerId },
+    ...parentWorkflowId !== void 0 && { parentWorkflowId },
+    ...parentWorkflowExecutionToken !== void 0 && { parentWorkflowExecutionToken },
     createdAt: now,
     ...!delayedStartTimer && { startedAt: now },
     updatedAt: now,
@@ -163,8 +192,8 @@ function resolveInitialExecutionDeadline(internals, options, delayedStartTimer,
     throw new StartWorkflowValidationError("options.executionTimeout must resolve to a finite, non-negative deadline");
   }
 }
-export function createInitialWorkflowState(internals, workflowId, type, input, versionTuple, options, tags, executionStateOwnerId, delayedStartTimer, callbacks) {
-  const now = internals.options.getNow(), state = buildInitialIdentitySlice(workflowId, type, input, versionTuple, executionStateOwnerId, delayedStartTimer, now, tags), executionDeadline = resolveInitialExecutionDeadline(internals, options, delayedStartTimer, now, callbacks);
+export function createInitialWorkflowState(internals, workflowId, type, input, versionTuple, options, tags, executionStateOwnerId, parentWorkflowId, parentWorkflowExecutionToken, delayedStartTimer, callbacks) {
+  const now = internals.options.getNow(), state = buildInitialIdentitySlice(workflowId, type, input, versionTuple, executionStateOwnerId, parentWorkflowId, parentWorkflowExecutionToken, delayedStartTimer, now, tags), executionDeadline = resolveInitialExecutionDeadline(internals, options, delayedStartTimer, now, callbacks);
   if (executionDeadline !== void 0)
     state.executionDeadline = executionDeadline;
   return state;

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

@@ -4,6 +4,7 @@ import { RegExpExtensionDecodeError } from "../../codec/extension-codec.js";
 import { Context, setContextWorkflowInterceptor } from "../../context.js";
 import { EMPTY_EVENT_HEAD } from "../../event-log.js";
 import { WorkflowRecoverySkippedEvent, WorkflowStartedEvent } from "../../events.js";
+import { VersionMismatchError } from "../../versioning.js";
 import { createCancelHandlerRegistration, resetCancelHandlers } from "../cancel-handlers.js";
 import { forgetCommittedCheckpointBytes } from "../checkpoint-commit-snapshots.js";
 import { hydrateCheckpointReplayState } from "../checkpoint-replay.js";
@@ -60,6 +61,21 @@ async function preflightRecoverAll(internals, callbacks) {
   }
   return result;
 }
+async function recoverEntryOrIsolateFailure(internals, workflowId, callbacks, options) {
+  try {
+    return await resume(internals, workflowId, callbacks, options?.onRecoveredWorkflow);
+  } catch (error) {
+    if (error instanceof RegExpExtensionDecodeError) {
+      await callbacks.failWorkflowForCheckpointDecodeError(workflowId, error);
+      return null;
+    }
+    if (error instanceof VersionMismatchError && options?.versionMismatchPolicy !== "throw") {
+      await callbacks.failWorkflowForVersionMismatch(workflowId, error);
+      return null;
+    }
+    throw error;
+  }
+}
 export async function recoverAll(internals, callbacks, options) {
   const preflight = await preflightRecoverAll(internals, callbacks), handles = [];
   if (preflight.missingWorkflows.length > 0 && options?.acknowledgeUnknownWorkflowTypes !== !0)
@@ -76,15 +92,9 @@ export async function recoverAll(internals, callbacks, options) {
       callbacks.dispatchEvent(new WorkflowRecoverySkippedEvent(entry.workflow.workflowId, entry.workflow.type, "type-not-registered"));
       continue;
     }
-    try {
-      handles.push(await resume(internals, entry.workflowId, callbacks, options?.onRecoveredWorkflow));
-    } catch (error) {
-      if (error instanceof RegExpExtensionDecodeError) {
-        await callbacks.failWorkflowForCheckpointDecodeError(entry.workflowId, error);
-        continue;
-      }
-      throw error;
-    }
+    const handle = await recoverEntryOrIsolateFailure(internals, entry.workflowId, callbacks, options);
+    if (handle !== null)
+      handles.push(handle);
   }
   return handles;
 }

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

@@ -36,18 +36,7 @@ export declare function processParallelOperation(internals: EngineInternals, wor
 export declare function processRaceOperation(internals: EngineInternals, workflowId: string, operation: RaceOperation, callbacks: Pick<CoordinationOperationCallbacks, 'executeSubOperation' | 'runOperationWithResult'>): Promise<void>;
 export declare function assertValidRaceBranchNames(operation: RaceOperation): void;
 export declare function wrapRaceWinner(operation: RaceOperation, winnerIndex: number, value: unknown): unknown;
-/**
- * Execute race branches while giving an already-buffered signal priority over a
- * literal zero-duration sleep. The preflight is non-destructive: the selected
- * wait-signal branch still returns its deferred-consume envelope, so the owning
- * coordinator remains the only place that consumes the durable record.
- *
- * Positive-duration sleeps deliberately bypass this preflight, including when
- * their deadline becomes past-due before dispatch. That keeps ordinary timeout
- * races on the existing Promise.race path and limits the stronger ordering
- * guarantee to the explicit non-blocking-drain idiom.
- */
-export declare function executeRaceSubOperations(internals: EngineInternals, workflowId: string, operations: readonly ContextOperationRequest[], execute: (operation: ContextOperationRequest, signal: AbortSignal) => Promise<unknown>, parentSignal?: AbortSignal, wrapWinner?: (winnerIndex: number, value: unknown) => unknown): Promise<unknown>;
+export declare function executeRaceSubOperations(internals: EngineInternals, workflowId: string, operations: readonly ContextOperationRequest[], execute: (operation: ContextOperationRequest, signal: AbortSignal) => Promise<unknown>, parentSignal?: AbortSignal, wrapWinner?: (winnerIndex: number, value: unknown) => unknown, observeWinner?: (winnerIndex: number, error?: unknown) => void): Promise<unknown>;
 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;
 /**