@lostgradient/weft 0.12.0 → 0.14.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

@@ -58,19 +58,22 @@ export type RecoverAllOptions = {
      */
     onRecoveredWorkflow?: (info: RecoveredWorkflowInfo) => void | Promise<void>;
     /**
-     * Policy for a recovered workflow whose stored {@link WorkflowVersionTuple}
-     * (or legacy checkpoint `version`) no longer matches the registered
-     * {@link WorkflowDefinition.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.
+     * 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'`: preserve the pre-#702 behavior — rethrow the
-     *   {@link VersionMismatchError} out of `recoverAll()` immediately, aborting
-     *   recovery for every workflow not yet processed in this batch.
+     * - `'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';
 };

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/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;
 /**

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

@@ -1,6 +1,6 @@
 import {
   isParallelOperationCacheEntry
-} from "../context/parallel-operations.js";
+} from "../context/parallel-cache-entry.js";
 import {
   executeRunAllBranches,
   executeRunAllBranchesSettled
@@ -21,6 +21,12 @@ import {
   untrackWaiterKey
 } from "./signals.js";
 import { callActivityFunction } from "./state-utilities.js";
+import {
+  parallelTimelineDetails,
+  raceTimelineDetails,
+  recordTimelineBranches,
+  runAllTimelineDetails
+} from "./timeline-coordinator-detail.js";
 export function assertSupportedSignalBranches(operations) {
   const seen = new Set, walk = (subOperations) => {
     for (const subOperation of subOperations)
@@ -74,6 +80,7 @@ export async function processParallelOperation(internals, workflowId, operation,
     await finalizeFulfilledSlots(slots);
     const entry = buildEntryFromSlots("all", slots);
     writePartialEntry(internals, workflowId, operation.step, entry);
+    recordTimelineBranches(internals, workflowId, parallelTimelineDetails(operation.operations, slots));
     if (hasFirstError)
       throw firstError;
     return valuesFromSlots(slots);
@@ -111,8 +118,22 @@ export async function processRaceOperation(internals, workflowId, operation, cal
   return callbacks.runOperationWithResult(workflowId, operation, async () => {
     assertSupportedSignalBranches(operation.operations);
     assertValidRaceBranchNames(operation);
-    const winner = await executeRaceSubOperations(internals, workflowId, operation.operations, (subOperation, signal) => callbacks.executeSubOperation(workflowId, subOperation, signal), void 0, (winnerIndex, value) => wrapRaceWinner(operation, winnerIndex, value));
-    return finalizeAndUnwrap(winner);
+    let winnerIndex, winnerError;
+    try {
+      const winner = await executeRaceSubOperations(internals, workflowId, operation.operations, (subOperation, signal) => callbacks.executeSubOperation(workflowId, subOperation, signal), void 0, (selectedIndex, value) => wrapRaceWinner(operation, selectedIndex, value), (selectedIndex, error) => {
+        winnerIndex = selectedIndex;
+        winnerError = error;
+      });
+      try {
+        return await finalizeAndUnwrap(winner);
+      } catch (error) {
+        winnerError = error;
+        throw error;
+      }
+    } finally {
+      if (winnerIndex !== void 0)
+        recordTimelineBranches(internals, workflowId, raceTimelineDetails(operation.operations, winnerIndex, operation.branchNames, winnerError));
+    }
   });
 }
 export function assertValidRaceBranchNames(operation) {
@@ -123,21 +144,46 @@ export function wrapRaceWinner(operation, winnerIndex, value) {
   const key = operation.branchNames?.[winnerIndex];
   return key === void 0 ? value : createKeyedRaceResultEnvelope(key, value);
 }
-export async function executeRaceSubOperations(internals, workflowId, operations, execute, parentSignal, wrapWinner) {
+function createRaceWinnerObservers(wrapWinner, observeWinner) {
+  const observers = {};
+  if (wrapWinner !== void 0)
+    observers.wrapWinner = wrapWinner;
+  if (observeWinner !== void 0)
+    observers.observeWinner = observeWinner;
+  return observers;
+}
+async function settleRaceBranch(operation, index, signal, execute) {
+  try {
+    return { index, status: "fulfilled", value: await execute(operation, signal) };
+  } catch (error) {
+    return { error, index, status: "rejected" };
+  }
+}
+function resolveRaceSettlement(settlement, observers) {
+  if (settlement.status === "rejected") {
+    observers.observeWinner?.(settlement.index, settlement.error);
+    throw settlement.error;
+  }
+  observers.observeWinner?.(settlement.index);
+  return observers.wrapWinner === void 0 ? settlement.value : observers.wrapWinner(settlement.index, settlement.value);
+}
+async function executeBufferedRaceWinner(bufferedSignal, signal, execute, observers) {
+  const settlement = await settleRaceBranch(bufferedSignal.operation, bufferedSignal.index, signal, execute);
+  return resolveRaceSettlement(settlement, observers);
+}
+export async function executeRaceSubOperations(internals, workflowId, operations, execute, parentSignal, wrapWinner, observeWinner) {
   parentSignal?.throwIfAborted();
-  const controller = new AbortController, abortFromParent = () => controller.abort(parentSignal?.reason);
+  const controller = new AbortController, abortFromParent = () => controller.abort(parentSignal?.reason), observers = createRaceWinnerObservers(wrapWinner, observeWinner);
   parentSignal?.addEventListener("abort", abortFromParent, { once: !0 });
   try {
     const bufferedSignal = await findBufferedSignalDrainBranch(internals, workflowId, operations);
     parentSignal?.throwIfAborted();
-    if (bufferedSignal !== void 0) {
-      const value = await execute(bufferedSignal.operation, controller.signal);
-      return wrapWinner === void 0 ? value : wrapWinner(bufferedSignal.index, value);
-    }
-    const subOperations = operations.map((operation, index) => execute(operation, controller.signal).then((value) => ({ index, value })));
+    if (bufferedSignal !== void 0)
+      return await executeBufferedRaceWinner(bufferedSignal, controller.signal, execute, observers);
+    const subOperations = operations.map((operation, index) => settleRaceBranch(operation, index, controller.signal, execute));
     Promise.allSettled(subOperations);
     const winner = await Promise.race(subOperations);
-    return wrapWinner === void 0 ? winner.value : wrapWinner(winner.index, winner.value);
+    return resolveRaceSettlement(winner, observers);
   } finally {
     parentSignal?.removeEventListener("abort", abortFromParent);
     controller.abort();
@@ -156,6 +202,7 @@ async function findBufferedSignalDrainBranch(internals, workflowId, operations)
 export async function processRunAllOperation(internals, workflowId, operation, callbacks) {
   return callbacks.runOperationWithResult(workflowId, operation, async () => {
     const branchNames = Object.keys(operation.branches), operationIds = branchNames.map((name) => `run-all:${operation.step}:${name}`), resumedSlots = extractResumedSlots(operation.resumedCacheEntry), resumedSlotsByName = mapResumedSlotsByName(resumedSlots, branchNames), branchesToRun = filterBranchesToRun(operation.branches, branchNames, resumedSlotsByName), { outcomes, hasFirstError, firstError } = await executeRunAllBranchesSettled(branchesToRun, (fn, input) => callActivityFunction(fn, input)), slots = mergeRunAllSlots(branchNames, operationIds, resumedSlotsByName, outcomes), entry = buildEntryFromSlots("run-all", slots, branchNames), partialEntryWritten = writePartialEntry(internals, workflowId, operation.step, entry);
+    recordTimelineBranches(internals, workflowId, runAllTimelineDetails(branchNames, slots, operation.branches));
     if (hasFirstError) {
       assertPartialFailurePersistenceSupported(partialEntryWritten, slots, "ctx.runAll", "worker execution mode");
       throw firstError;

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

@@ -12,5 +12,5 @@ export type SpeculateOperationCallbacks = {
 };
 export declare function processSpeculateOperation(internals: EngineInternals, workflowId: string, operation: SpeculateOperation, callbacks: SpeculateOperationCallbacks): Promise<void>;
 export declare function executeSpeculativeBranch(internals: EngineInternals, workflowId: string, operation: SpeculateOperation, callbacks: Pick<SpeculateOperationCallbacks, 'executeSubOperation'>): Promise<unknown>;
-export declare function driveSpeculativeGenerator(workflowId: string, generator: SpeculativeOperationGenerator, speculativeState: SpeculativeExecutionState, callbacks: Pick<SpeculateOperationCallbacks, 'executeSubOperation'>): Promise<unknown>;
+export declare function driveSpeculativeGenerator(workflowId: string, generator: SpeculativeOperationGenerator, speculativeState: SpeculativeExecutionState, callbacks: Pick<SpeculateOperationCallbacks, 'executeSubOperation'>, observeChild?: (operation: ContextOperationRequest, index: number, error?: unknown) => void): Promise<unknown>;
 export {};

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

@@ -1,6 +1,10 @@
 import { finalizeAndUnwrap } from "./deferred-consume-envelope.js";
 import { assertSupportedSignalBranches } from "./operations-coordination.js";
 import { SpeculativeExecutionState } from "./speculative-execution-state.js";
+import {
+  operationTimelineDetail,
+  recordTimelineSpeculation
+} from "./timeline-coordinator-detail.js";
 export async function processSpeculateOperation(internals, workflowId, operation, callbacks) {
   return callbacks.runOperationWithResult(workflowId, operation, () => executeSpeculativeBranch(internals, workflowId, operation, callbacks));
 }
@@ -11,32 +15,42 @@ export async function executeSpeculativeBranch(internals, workflowId, operation,
   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);
+  const speculativeContext = parentContext.createSpeculativeChild(), speculativeState = new SpeculativeExecutionState, generator = createSpeculativeOperationGenerator(operation, speculativeContext), children = [];
   try {
-    const result = await driveSpeculativeGenerator(workflowId, generator, speculativeState, callbacks);
+    const result = await driveSpeculativeGenerator(workflowId, generator, speculativeState, callbacks, (child, index, error) => {
+      children.push(operationTimelineDetail(child, index, error === void 0 ? "fulfilled" : "rejected", error === void 0 ? {} : { error }));
+    });
     await speculativeState.drainVerifications();
     parentContext.commitSpeculativeChild(speculativeContext);
+    recordTimelineSpeculation(internals, workflowId, children, "committed");
     return result;
   } catch (error) {
-    await speculativeState.rollback();
+    try {
+      await speculativeState.rollback();
+    } finally {
+      recordTimelineSpeculation(internals, workflowId, children, "rolled-back");
+    }
     throw error;
   }
 }
 function createSpeculativeOperationGenerator(operation, speculativeContext) {
   return operation.execute(speculativeContext);
 }
-export async function driveSpeculativeGenerator(workflowId, generator, speculativeState, callbacks) {
+export async function driveSpeculativeGenerator(workflowId, generator, speculativeState, callbacks, observeChild) {
+  let childIndex = 0;
   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;
+    const nextOperation = iterationResult.value, currentChildIndex = childIndex++;
     try {
       if (nextOperation.type === "race" || nextOperation.type === "parallel")
         assertSupportedSignalBranches(nextOperation.operations);
       const nextResult = await callbacks.executeSubOperation(workflowId, nextOperation, void 0, speculativeState), finalizedResult = await finalizeAndUnwrap(nextResult);
+      observeChild?.(nextOperation, currentChildIndex);
       return advance(finalizedResult, void 0);
     } catch (error) {
+      observeChild?.(nextOperation, currentChildIndex, error);
       return advance(lastResult, error instanceof Error ? error : Error(String(error)));
     }
   };

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

@@ -25,7 +25,7 @@
  * checkpoint-write machinery — see the `parallel-execution.md` guide
  * for the precise durability contract.
  */
-import type { ParallelBranchSlot, ParallelOperationCacheEntry } from '../context/parallel-operations.ts';
+import type { ParallelBranchSlot, ParallelOperationCacheEntry } from '../context/parallel-cache-entry.ts';
 export type ParallelDispatchResult = {
     /** Final slot table — every entry is `fulfilled` or `rejected`. */
     slots: ParallelBranchSlot[];

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

@@ -1,4 +1,4 @@
-import { createParallelOperationCacheEntry } from "../context/parallel-operations.js";
+import { createParallelOperationCacheEntry } from "../context/parallel-cache-entry.js";
 export function createFirstRejectionCapture() {
   return { hasFirstError: !1, firstError: void 0 };
 }

package/dist/core/engine/registration.js

@@ -59,8 +59,22 @@ function applyOptionalRegistrationFields(entry, registration) {
 function buildRegistrationEntry(name, registration) {
   const entry = buildBaseRegistrationEntry(name, registration);
   applyOptionalRegistrationFields(entry, registration);
+  if (isBuilderWorkflowDefinition(registration)) {
+    entry.signals = normalizeMessageDefinitions(name, "signal", registration.signals);
+    entry.updates = normalizeMessageDefinitions(name, "update", registration.updates);
+    entry.queries = normalizeMessageDefinitions(name, "query", registration.queries);
+  }
   return entry;
 }
+function normalizeMessageDefinitions(workflowType, messageKind, definitions) {
+  const normalized = Object.create(null), sortedDefinitions = Object.values(definitions).toSorted((left, right) => left.name < right.name ? -1 : left.name > right.name ? 1 : 0);
+  for (const definition of sortedDefinitions) {
+    if (Object.hasOwn(normalized, definition.name))
+      throw Error(`Duplicate ${messageKind} runtime name "${definition.name}" in workflow "${workflowType}"`);
+    normalized[definition.name] = definition;
+  }
+  return normalized;
+}
 function commitWorkflowDefinition(internals, definition, callbacks) {
   const name = definition.name;
   validateWorkflowOrActivityName(name, "workflow");

package/dist/core/engine/review-list-entries.d.ts

@@ -1,4 +1,4 @@
-import type { HumanReviewResult, ReviewRequest } from '../review/index.ts';
+import { type HumanReviewResult, type ReviewRequest } from '../review/index.ts';
 import type { CompletedReviewEntry, PendingReviewEntry } from '../types.ts';
 export declare function toPendingReviewEntry(review: ReviewRequest): PendingReviewEntry;
 export declare function parseStoredReviewRequest(value: Uint8Array): ReviewRequest | null;