@bastani/atomic 0.9.10 → 0.9.11-alpha.10

package/dist/builtin/workflows/src/durable/dbos-envelope.ts

@@ -12,17 +12,23 @@
  */
 
 import type { WorkflowSerializableObject, WorkflowSerializableValue } from "../shared/types.js";
+import { DURABLE_FORMAT_VERSION, isCurrentDurableFormat } from "./format-version.js";
+import { workflowToolOutcomeFromValue } from "./tool-outcome.js";
 import {
-  DURABLE_STAGE_TOPOLOGY_VERSION,
-  type DurableCheckpoint,
-  type DurableCheckpointKind,
-  type DurableStageCheckpoint,
-  type DurableStageTopology,
-  type DurableToolCheckpoint,
-  type DurableUiCheckpoint,
-  type UiPromptKind,
+	DURABLE_BOUNDARY_TOPOLOGY_VERSION,
+	DURABLE_STAGE_TOPOLOGY_VERSION,
+	DURABLE_TOOL_TOPOLOGY_VERSION,
+	type DurableCheckpoint,
+	type DurableCheckpointKind,
+	type DurableStageCheckpoint,
+	type DurableStageLifecycleStatus,
+	type DurableStageTopology,
+	type DurableToolCheckpoint,
+	type DurableToolTopology,
+	type DurableUiCheckpoint,
+	type DurableWorkflowBoundaryTopology,
+	type UiPromptKind,
 } from "./types.js";
-import { isCurrentDurableFormat, DURABLE_FORMAT_VERSION } from "./format-version.js";
 
 /** Envelope schema version. */
 export const DBOS_ENVELOPE_VERSION = DURABLE_FORMAT_VERSION;
@@ -36,240 +42,460 @@ const ENVELOPE_MARKER = "__dbos_checkpoint__";
  * `getResult()` / `listWorkflows` on hydration.
  */
 export interface DbosCheckpointEnvelope extends WorkflowSerializableObject {
-  readonly __dbos_checkpoint__: typeof ENVELOPE_MARKER;
-  readonly v: typeof DBOS_ENVELOPE_VERSION;
-  readonly kind: DurableCheckpointKind;
-  readonly checkpointId: string;
-  readonly name?: string;
-  readonly argsHash?: string;
-  readonly promptKind?: UiPromptKind;
-  readonly message?: string;
-  readonly promptHash?: string;
-  readonly replayKey?: string;
-  readonly output?: WorkflowSerializableValue;
-  readonly hasOutput?: boolean;
-  readonly sessionId?: string;
-  readonly sessionFile?: string;
-  readonly completedAt: number;
-  readonly startedAt?: number;
-  readonly endedAt?: number;
-  readonly durationMs?: number;
-  readonly result?: string;
-  readonly model?: string;
-  readonly fastMode?: boolean;
-  readonly attemptedModels?: WorkflowSerializableValue;
-  readonly modelAttempts?: WorkflowSerializableValue;
-  readonly topology?: WorkflowSerializableValue;
+	readonly __dbos_checkpoint__: typeof ENVELOPE_MARKER;
+	readonly v: typeof DBOS_ENVELOPE_VERSION;
+	readonly kind: DurableCheckpointKind;
+	readonly checkpointId: string;
+	readonly name?: string;
+	readonly argsHash?: string;
+	readonly promptKind?: UiPromptKind;
+	readonly outcomeKind?: "return_success" | "return_failure";
+	readonly throwingFailureError?: string;
+	readonly message?: string;
+	readonly promptHash?: string;
+	readonly replayKey?: string;
+	readonly output?: WorkflowSerializableValue;
+	readonly hasOutput?: boolean;
+	readonly sessionId?: string;
+	readonly sessionFile?: string;
+	readonly completedAt: number;
+	readonly startedAt?: number;
+	readonly endedAt?: number;
+	readonly durationMs?: number;
+	readonly result?: string;
+	readonly model?: string;
+	readonly fastMode?: boolean;
+	readonly attemptedModels?: WorkflowSerializableValue;
+	readonly modelAttempts?: WorkflowSerializableValue;
+	readonly topology?: WorkflowSerializableValue;
 }
 
-/**
- * Stage-kind checkpoints from older session-timing writers may omit
- * topology. The current format requires it, so default at every write
- * boundary — persisted records must match the normalized in-memory mirror or
- * a fresh process would reject them as foreign.
- */
+/** Add a compatibility root topology when a legacy/output-only writer omits it. */
 export function withCurrentStageTopology(cp: DurableCheckpoint): DurableCheckpoint {
-  if (cp.kind !== "stage" || cp.topology !== undefined) return cp;
-  return {
-    ...cp,
-    topology: { version: DURABLE_STAGE_TOPOLOGY_VERSION, stageId: cp.checkpointId, parentIds: [] },
-  };
+	if (cp.kind !== "stage" || cp.topology !== undefined) return cp;
+	return {
+		...cp,
+		topology: { version: DURABLE_STAGE_TOPOLOGY_VERSION, stageId: cp.checkpointId, parentIds: [] },
+	};
 }
 
 /**
  * Encode a durable checkpoint into a DBOS step-output envelope.
  */
 export function encodeCheckpoint(checkpoint: DurableCheckpoint): DbosCheckpointEnvelope {
-  const cp = withCurrentStageTopology(checkpoint);
-  const output = checkpointOutputValue(cp);
-  const base: DbosCheckpointEnvelope = {
-    __dbos_checkpoint__: ENVELOPE_MARKER,
-    v: DBOS_ENVELOPE_VERSION,
-    kind: cp.kind,
-    checkpointId: cp.checkpointId,
-    ...(output !== undefined ? { output } : {}),
-    hasOutput: output !== undefined,
-    completedAt: cp.completedAt,
-  };
-  if (cp.kind === "tool") {
-    const t = cp as DurableToolCheckpoint;
-    return { ...base, name: t.name, argsHash: t.argsHash };
-  }
-  if (cp.kind === "ui") {
-    const u = cp as DurableUiCheckpoint;
-    return { ...base, promptKind: u.promptKind, message: u.message, promptHash: u.promptHash };
-  }
-  const s = cp as DurableStageCheckpoint;
-  return {
-    ...base,
-    name: s.name,
-    replayKey: s.replayKey,
-    ...(s.topology !== undefined ? { topology: { version: s.topology.version, stageId: s.topology.stageId, parentIds: [...s.topology.parentIds] } } : {}),
-    ...(s.sessionId !== undefined ? { sessionId: s.sessionId } : {}),
-    ...(s.sessionFile !== undefined ? { sessionFile: s.sessionFile } : {}),
-    ...(s.startedAt !== undefined ? { startedAt: s.startedAt } : {}),
-    ...(s.endedAt !== undefined ? { endedAt: s.endedAt } : {}),
-    ...(s.durationMs !== undefined ? { durationMs: s.durationMs } : {}),
-    ...(s.result !== undefined ? { result: s.result } : {}),
-    ...(s.model !== undefined ? { model: s.model } : {}),
-    ...(s.fastMode !== undefined ? { fastMode: s.fastMode } : {}),
-    ...(s.attemptedModels !== undefined ? { attemptedModels: [...s.attemptedModels] } : {}),
-    ...(s.modelAttempts !== undefined ? { modelAttempts: s.modelAttempts as WorkflowSerializableValue } : {}),
-  };
+	const cp = withCurrentStageTopology(checkpoint);
+	const output = checkpointOutputValue(cp);
+	const base: DbosCheckpointEnvelope = {
+		__dbos_checkpoint__: ENVELOPE_MARKER,
+		v: DBOS_ENVELOPE_VERSION,
+		kind: cp.kind,
+		checkpointId: cp.checkpointId,
+		...(output !== undefined ? { output } : {}),
+		hasOutput: output !== undefined,
+		completedAt: cp.completedAt,
+	};
+	if (cp.kind === "tool") {
+		const t = cp as DurableToolCheckpoint;
+		return {
+			...base,
+			name: t.name,
+			argsHash: t.argsHash,
+			...(t.outcomeKind !== undefined ? { outcomeKind: t.outcomeKind } : {}),
+			...(t.throwingFailureError !== undefined ? { throwingFailureError: t.throwingFailureError } : {}),
+			...(t.topology !== undefined
+				? {
+						topology: {
+							version: t.topology.version,
+							nodeId: t.topology.nodeId,
+							ordinal: t.topology.ordinal,
+							order: t.topology.order,
+							parentIds: [...t.topology.parentIds],
+							...(t.topology.startedAt !== undefined ? { startedAt: t.topology.startedAt } : {}),
+							...(t.topology.endedAt !== undefined ? { endedAt: t.topology.endedAt } : {}),
+							...(t.topology.run !== undefined ? { run: { ...t.topology.run } } : {}),
+						},
+					}
+				: {}),
+		};
+	}
+	if (cp.kind === "ui") {
+		const u = cp as DurableUiCheckpoint;
+		return { ...base, promptKind: u.promptKind, message: u.message, promptHash: u.promptHash };
+	}
+	const s = cp as DurableStageCheckpoint;
+	return {
+		...base,
+		name: s.name,
+		replayKey: s.replayKey,
+		...(s.topology !== undefined
+			? {
+					topology: {
+						version: s.topology.version,
+						stageId: s.topology.stageId,
+						parentIds: [...s.topology.parentIds],
+						...(s.topology.sourceOrder !== undefined ? { sourceOrder: s.topology.sourceOrder } : {}),
+						...(s.topology.occurrenceKey !== undefined ? { occurrenceKey: s.topology.occurrenceKey } : {}),
+						...(s.topology.status !== undefined ? { status: s.topology.status } : {}),
+						...(s.topology.order !== undefined ? { order: s.topology.order } : {}),
+						...(s.topology.run !== undefined ? { run: { ...s.topology.run } } : {}),
+						...(s.topology.boundary !== undefined
+							? {
+									boundary: {
+										...s.topology.boundary,
+										child: { ...s.topology.boundary.child },
+									},
+								}
+							: {}),
+					},
+				}
+			: {}),
+		...(s.sessionId !== undefined ? { sessionId: s.sessionId } : {}),
+		...(s.sessionFile !== undefined ? { sessionFile: s.sessionFile } : {}),
+		...(s.startedAt !== undefined ? { startedAt: s.startedAt } : {}),
+		...(s.endedAt !== undefined ? { endedAt: s.endedAt } : {}),
+		...(s.durationMs !== undefined ? { durationMs: s.durationMs } : {}),
+		...(s.result !== undefined ? { result: s.result } : {}),
+		...(s.model !== undefined ? { model: s.model } : {}),
+		...(s.fastMode !== undefined ? { fastMode: s.fastMode } : {}),
+		...(s.attemptedModels !== undefined ? { attemptedModels: [...s.attemptedModels] } : {}),
+		...(s.modelAttempts !== undefined ? { modelAttempts: s.modelAttempts as WorkflowSerializableValue } : {}),
+	};
 }
 
 /**
  * Type guard: is this value a checkpoint envelope?
  */
 export function isCheckpointEnvelope(value: WorkflowSerializableValue | undefined): value is DbosCheckpointEnvelope {
-  if (!hasCheckpointEnvelopeMarker(value)) return false;
-  return value.v === DBOS_ENVELOPE_VERSION;
+	if (!hasCheckpointEnvelopeMarker(value)) return false;
+	return value.v === DBOS_ENVELOPE_VERSION;
 }
 
-function hasCheckpointEnvelopeMarker(value: WorkflowSerializableValue | undefined): value is Record<string, WorkflowSerializableValue> {
-  if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
-  return (value as Record<string, WorkflowSerializableValue>)[ENVELOPE_MARKER] === ENVELOPE_MARKER;
+function hasCheckpointEnvelopeMarker(
+	value: WorkflowSerializableValue | undefined,
+): value is Record<string, WorkflowSerializableValue> {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+	return (value as Record<string, WorkflowSerializableValue>)[ENVELOPE_MARKER] === ENVELOPE_MARKER;
 }
 export type DbosCheckpointCompatibility =
-  | { readonly kind: "current"; readonly checkpoint: DurableCheckpoint }
-  | { readonly kind: "unknown" };
+	| { readonly kind: "current"; readonly checkpoint: DurableCheckpoint }
+	| { readonly kind: "unknown" };
 
 /** Classify and decode one DBOS checkpoint payload without reinterpreting marked formats. */
 export function classifyCheckpointPayload(
-  workflowId: string,
-  stepName: string,
-  value: WorkflowSerializableValue,
+	workflowId: string,
+	stepName: string,
+	value: WorkflowSerializableValue,
 ): DbosCheckpointCompatibility {
-  if (!hasCheckpointEnvelopeMarker(value) || !isCurrentDurableFormat(value.v)) return { kind: "unknown" };
-  const hasOutput = value["hasOutput"];
-  const containsOutput = value["output"] !== undefined;
-  if (value["checkpointId"] !== stepName || typeof hasOutput !== "boolean" || hasOutput !== containsOutput) {
-    return { kind: "unknown" };
-  }
-  const checkpoint = decodeEnvelope(workflowId, value as DbosCheckpointEnvelope);
-  return checkpoint === undefined ? { kind: "unknown" } : { kind: "current", checkpoint };
+	if (!hasCheckpointEnvelopeMarker(value) || !isCurrentDurableFormat(value.v)) return { kind: "unknown" };
+	const hasOutput = value.hasOutput;
+	const containsOutput = value.output !== undefined;
+	if (value.checkpointId !== stepName || typeof hasOutput !== "boolean" || hasOutput !== containsOutput) {
+		return { kind: "unknown" };
+	}
+	const checkpoint = decodeEnvelope(workflowId, value as DbosCheckpointEnvelope);
+	return checkpoint === undefined ? { kind: "unknown" } : { kind: "current", checkpoint };
 }
 
 /** Decode one current DBOS checkpoint envelope. */
 export function decodeToCheckpoint(
-  workflowId: string,
-  stepName: string,
-  value: WorkflowSerializableValue,
+	workflowId: string,
+	stepName: string,
+	value: WorkflowSerializableValue,
 ): DurableCheckpoint | undefined {
-  const classified = classifyCheckpointPayload(workflowId, stepName, value);
-  return classified.kind === "current" ? classified.checkpoint : undefined;
+	const classified = classifyCheckpointPayload(workflowId, stepName, value);
+	return classified.kind === "current" ? classified.checkpoint : undefined;
 }
 
 function decodeEnvelope(workflowId: string, env: DbosCheckpointEnvelope): DurableCheckpoint | undefined {
-  if (typeof env.checkpointId !== "string" || env.checkpointId.length === 0
-    || typeof env.completedAt !== "number" || !Number.isFinite(env.completedAt)
-    || (env.name !== undefined && typeof env.name !== "string")
-    || (env.hasOutput !== undefined && typeof env.hasOutput !== "boolean")) return undefined;
-  const common = { workflowId, checkpointId: env.checkpointId, completedAt: env.completedAt };
-  if (env.kind === "tool") {
-    if (typeof env.argsHash !== "string" || env.output === undefined) return undefined;
-    return {
-      kind: "tool",
-      ...common,
-      name: env.name ?? "tool",
-      argsHash: env.argsHash,
-      output: env.output,
-    } as DurableToolCheckpoint;
-  }
-  if (env.kind === "ui") {
-    if (typeof env.promptHash !== "string" || !isUiPromptKind(env.promptKind) || env.output === undefined
-      || (env.message !== undefined && typeof env.message !== "string")) return undefined;
-    return {
-      kind: "ui",
-      ...common,
-      promptKind: env.promptKind,
-      message: env.message ?? "",
-      promptHash: env.promptHash,
-      response: env.output,
-    } as DurableUiCheckpoint;
-  }
-  const topology = stageTopology(env.topology);
-  if (env.kind !== "stage" || topology === undefined
-    || (env.replayKey !== undefined && typeof env.replayKey !== "string")
-    || (env.sessionId !== undefined && typeof env.sessionId !== "string")
-    || (env.sessionFile !== undefined && typeof env.sessionFile !== "string")
-    || !isOptionalFiniteNumber(env.startedAt)
-    || !isOptionalFiniteNumber(env.endedAt)
-    || !isOptionalFiniteNumber(env.durationMs)
-    || (env.result !== undefined && typeof env.result !== "string")
-    || (env.model !== undefined && typeof env.model !== "string")
-    || (env.fastMode !== undefined && typeof env.fastMode !== "boolean")
-    || (env.attemptedModels !== undefined && !isStringArray(env.attemptedModels))
-    || (env.modelAttempts !== undefined && !isModelAttempts(env.modelAttempts))) return undefined;
-  return {
-    kind: "stage",
-    ...common,
-    name: env.name ?? "stage",
-    replayKey: env.replayKey ?? env.checkpointId,
-    ...(env.hasOutput !== false && env.output !== undefined ? { output: env.output } : {}),
-    topology,
-    ...(env.sessionId !== undefined ? { sessionId: env.sessionId } : {}),
-    ...(env.sessionFile !== undefined ? { sessionFile: env.sessionFile } : {}),
-    ...(typeof env.startedAt === "number" ? { startedAt: env.startedAt } : {}),
-    ...(typeof env.endedAt === "number" ? { endedAt: env.endedAt } : {}),
-    ...(typeof env.durationMs === "number" ? { durationMs: env.durationMs } : {}),
-    ...(typeof env.result === "string" ? { result: env.result } : {}),
-    ...(typeof env.model === "string" ? { model: env.model } : {}),
-    ...(typeof env.fastMode === "boolean" ? { fastMode: env.fastMode } : {}),
-    ...(isStringArray(env.attemptedModels) ? { attemptedModels: env.attemptedModels } : {}),
-    ...(Array.isArray(env.modelAttempts) ? { modelAttempts: env.modelAttempts as DurableStageCheckpoint["modelAttempts"] } : {}),
-  } as DurableStageCheckpoint;
+	if (
+		typeof env.checkpointId !== "string" ||
+		env.checkpointId.length === 0 ||
+		typeof env.completedAt !== "number" ||
+		!Number.isFinite(env.completedAt) ||
+		(env.name !== undefined && typeof env.name !== "string") ||
+		(env.hasOutput !== undefined && typeof env.hasOutput !== "boolean")
+	)
+		return undefined;
+	const common = { workflowId, checkpointId: env.checkpointId, completedAt: env.completedAt };
+	if (env.kind === "tool") {
+		if (
+			typeof env.argsHash !== "string" ||
+			env.output === undefined ||
+			(env.outcomeKind !== undefined &&
+				env.outcomeKind !== "return_success" &&
+				env.outcomeKind !== "return_failure") ||
+			(env.throwingFailureError !== undefined && typeof env.throwingFailureError !== "string")
+		)
+			return undefined;
+		const outcome = env.outcomeKind === undefined ? undefined : workflowToolOutcomeFromValue(env.output);
+		if (
+			(env.outcomeKind === "return_success" && outcome?.ok !== true) ||
+			(env.outcomeKind === "return_failure" && outcome?.ok !== false)
+		)
+			return undefined;
+		const topology = env.topology === undefined ? undefined : toolTopology(env.topology);
+		if (env.topology !== undefined && topology === undefined) return undefined;
+		return {
+			kind: "tool",
+			...common,
+			name: env.name ?? "tool",
+			argsHash: env.argsHash,
+			output: env.output,
+			...(env.outcomeKind !== undefined ? { outcomeKind: env.outcomeKind } : {}),
+			...(env.throwingFailureError !== undefined ? { throwingFailureError: env.throwingFailureError } : {}),
+			...(topology !== undefined ? { topology } : {}),
+		} as DurableToolCheckpoint;
+	}
+	if (env.kind === "ui") {
+		if (
+			typeof env.promptHash !== "string" ||
+			!isUiPromptKind(env.promptKind) ||
+			env.output === undefined ||
+			(env.message !== undefined && typeof env.message !== "string")
+		)
+			return undefined;
+		return {
+			kind: "ui",
+			...common,
+			promptKind: env.promptKind,
+			message: env.message ?? "",
+			promptHash: env.promptHash,
+			response: env.output,
+		} as DurableUiCheckpoint;
+	}
+	const topology = stageTopology(env.topology);
+	if (
+		env.kind !== "stage" ||
+		topology === undefined ||
+		(env.replayKey !== undefined && typeof env.replayKey !== "string") ||
+		(env.sessionId !== undefined && typeof env.sessionId !== "string") ||
+		(env.sessionFile !== undefined && typeof env.sessionFile !== "string") ||
+		!isOptionalFiniteNumber(env.startedAt) ||
+		!isOptionalFiniteNumber(env.endedAt) ||
+		!isOptionalFiniteNumber(env.durationMs) ||
+		(env.result !== undefined && typeof env.result !== "string") ||
+		(env.model !== undefined && typeof env.model !== "string") ||
+		(env.fastMode !== undefined && typeof env.fastMode !== "boolean") ||
+		(env.attemptedModels !== undefined && !isStringArray(env.attemptedModels)) ||
+		(env.modelAttempts !== undefined && !isModelAttempts(env.modelAttempts))
+	)
+		return undefined;
+	return {
+		kind: "stage",
+		...common,
+		name: env.name ?? "stage",
+		replayKey: env.replayKey ?? env.checkpointId,
+		...(env.hasOutput !== false && env.output !== undefined ? { output: env.output } : {}),
+		topology,
+		...(env.sessionId !== undefined ? { sessionId: env.sessionId } : {}),
+		...(env.sessionFile !== undefined ? { sessionFile: env.sessionFile } : {}),
+		...(typeof env.startedAt === "number" ? { startedAt: env.startedAt } : {}),
+		...(typeof env.endedAt === "number" ? { endedAt: env.endedAt } : {}),
+		...(typeof env.durationMs === "number" ? { durationMs: env.durationMs } : {}),
+		...(typeof env.result === "string" ? { result: env.result } : {}),
+		...(typeof env.model === "string" ? { model: env.model } : {}),
+		...(typeof env.fastMode === "boolean" ? { fastMode: env.fastMode } : {}),
+		...(isStringArray(env.attemptedModels) ? { attemptedModels: env.attemptedModels } : {}),
+		...(Array.isArray(env.modelAttempts)
+			? { modelAttempts: env.modelAttempts as DurableStageCheckpoint["modelAttempts"] }
+			: {}),
+	} as DurableStageCheckpoint;
 }
 
+function toolTopology(value: WorkflowSerializableValue): DurableToolTopology | undefined {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) return undefined;
+	const record = value as Record<string, WorkflowSerializableValue>;
+	if (
+		record.version !== DURABLE_TOOL_TOPOLOGY_VERSION ||
+		typeof record.nodeId !== "string" ||
+		typeof record.ordinal !== "number" ||
+		!Number.isInteger(record.ordinal) ||
+		typeof record.order !== "number" ||
+		!Number.isInteger(record.order) ||
+		!isStringArray(record.parentIds) ||
+		!isOptionalFiniteNumber(record.startedAt) ||
+		!isOptionalFiniteNumber(record.endedAt)
+	)
+		return undefined;
+	const run = stageRunTopology(record.run);
+	if (record.run !== undefined && run === undefined) return undefined;
+	return {
+		version: DURABLE_TOOL_TOPOLOGY_VERSION,
+		nodeId: record.nodeId,
+		ordinal: record.ordinal,
+		order: record.order,
+		parentIds: record.parentIds,
+		...(typeof record.startedAt === "number" ? { startedAt: record.startedAt } : {}),
+		...(typeof record.endedAt === "number" ? { endedAt: record.endedAt } : {}),
+		...(run !== undefined ? { run } : {}),
+	};
+}
 
 function stageTopology(value: WorkflowSerializableValue | undefined): DurableStageTopology | undefined {
-  if (typeof value !== "object" || value === null || Array.isArray(value)) return undefined;
-  const record = value as Record<string, WorkflowSerializableValue>;
-  if (record["version"] !== DURABLE_STAGE_TOPOLOGY_VERSION
-    || typeof record["stageId"] !== "string" || !isStringArray(record["parentIds"])) return undefined;
-  return { version: DURABLE_STAGE_TOPOLOGY_VERSION, stageId: record["stageId"], parentIds: record["parentIds"] };
+	if (typeof value !== "object" || value === null || Array.isArray(value)) return undefined;
+	const record = value as Record<string, WorkflowSerializableValue>;
+	if (
+		record.version !== DURABLE_STAGE_TOPOLOGY_VERSION ||
+		typeof record.stageId !== "string" ||
+		!isStringArray(record.parentIds) ||
+		!isOptionalSourceOrder(record.sourceOrder) ||
+		(record.occurrenceKey !== undefined && typeof record.occurrenceKey !== "string") ||
+		(record.status !== undefined && !isStageLifecycleStatus(record.status))
+	)
+		return undefined;
+	const run = stageRunTopology(record.run);
+	if (record.run !== undefined && run === undefined) return undefined;
+	const boundary = boundaryTopology(record.boundary);
+	if (record.boundary !== undefined && boundary === undefined) return undefined;
+	return {
+		version: DURABLE_STAGE_TOPOLOGY_VERSION,
+		stageId: record.stageId,
+		parentIds: record.parentIds,
+		...(typeof record.sourceOrder === "number" ? { sourceOrder: record.sourceOrder } : {}),
+		...(typeof record.occurrenceKey === "string" ? { occurrenceKey: record.occurrenceKey } : {}),
+		...(isStageLifecycleStatus(record.status) ? { status: record.status } : {}),
+		...(typeof record.order === "number" && Number.isInteger(record.order) ? { order: record.order } : {}),
+		...(run !== undefined ? { run } : {}),
+		...(boundary !== undefined ? { boundary } : {}),
+	};
+}
+
+function boundaryTopology(value: WorkflowSerializableValue | undefined): DurableWorkflowBoundaryTopology | undefined {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) return undefined;
+	const boundary = value as Record<string, WorkflowSerializableValue>;
+	const childValue = boundary.child;
+	const event = boundary.event;
+	const status = boundary.status;
+	const invocationFingerprint = boundary.invocationFingerprint;
+	if (
+		boundary.version !== DURABLE_BOUNDARY_TOPOLOGY_VERSION ||
+		(event !== "start" && event !== "terminal") ||
+		(event === "start"
+			? status !== "running"
+			: status !== "completed" && status !== "failed" && status !== "skipped") ||
+		typeof boundary.replayScope !== "string" ||
+		typeof boundary.alias !== "string" ||
+		typeof boundary.workflow !== "string" ||
+		(invocationFingerprint !== undefined && typeof invocationFingerprint !== "string") ||
+		typeof childValue !== "object" ||
+		childValue === null ||
+		Array.isArray(childValue)
+	)
+		return undefined;
+	const child = childValue as Record<string, WorkflowSerializableValue>;
+	if (
+		!["runId", "runName", "parentRunId", "parentStageId", "rootRunId"].every((key) => typeof child[key] === "string")
+	)
+		return undefined;
+	const identity = {
+		version: DURABLE_BOUNDARY_TOPOLOGY_VERSION,
+		replayScope: boundary.replayScope as string,
+		alias: boundary.alias as string,
+		workflow: boundary.workflow as string,
+		...(typeof invocationFingerprint === "string" ? { invocationFingerprint } : {}),
+		child: {
+			runId: child.runId as string,
+			runName: child.runName as string,
+			parentRunId: child.parentRunId as string,
+			parentStageId: child.parentStageId as string,
+			rootRunId: child.rootRunId as string,
+		},
+	};
+	if (event === "start") return { ...identity, event, status: "running" };
+	return {
+		...identity,
+		event,
+		status: status as Extract<DurableStageLifecycleStatus, "completed" | "failed" | "skipped">,
+	};
+}
+
+function isOptionalSourceOrder(value: WorkflowSerializableValue | undefined): boolean {
+	return value === undefined || (typeof value === "number" && Number.isInteger(value) && value >= 0);
+}
+
+function isStageLifecycleStatus(value: WorkflowSerializableValue | undefined): value is DurableStageLifecycleStatus {
+	return (
+		value === "pending" ||
+		value === "running" ||
+		value === "awaiting_input" ||
+		value === "paused" ||
+		value === "blocked" ||
+		value === "completed" ||
+		value === "failed" ||
+		value === "skipped"
+	);
+}
+
+function stageRunTopology(
+	value: WorkflowSerializableValue | undefined,
+): NonNullable<DurableStageTopology["run"]> | undefined {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) return undefined;
+	const run = value as Record<string, WorkflowSerializableValue>;
+	if (typeof run.runId !== "string" || typeof run.runName !== "string") return undefined;
+	for (const key of ["parentRunId", "parentStageId", "rootRunId"] as const) {
+		if (run[key] !== undefined && typeof run[key] !== "string") return undefined;
+	}
+	return {
+		runId: run.runId,
+		runName: run.runName,
+		...(typeof run.parentRunId === "string" ? { parentRunId: run.parentRunId } : {}),
+		...(typeof run.parentStageId === "string" ? { parentStageId: run.parentStageId } : {}),
+		...(typeof run.rootRunId === "string" ? { rootRunId: run.rootRunId } : {}),
+	};
 }
 
 function isModelAttempts(value: WorkflowSerializableValue | undefined): boolean {
-  return Array.isArray(value) && value.every((attempt) => {
-    if (typeof attempt !== "object" || attempt === null || Array.isArray(attempt)) return false;
-    const record = attempt as Record<string, WorkflowSerializableValue>;
-    return typeof record["model"] === "string"
-      && typeof record["success"] === "boolean"
-      && (record["reasoningLevel"] === undefined || isReasoningLevel(record["reasoningLevel"]))
-      && (record["error"] === undefined || typeof record["error"] === "string")
-      && (record["usage"] === undefined || isModelUsage(record["usage"]));
-  });
+	return (
+		Array.isArray(value) &&
+		value.every((attempt) => {
+			if (typeof attempt !== "object" || attempt === null || Array.isArray(attempt)) return false;
+			const record = attempt as Record<string, WorkflowSerializableValue>;
+			return (
+				typeof record.model === "string" &&
+				typeof record.success === "boolean" &&
+				(record.reasoningLevel === undefined || isReasoningLevel(record.reasoningLevel)) &&
+				(record.error === undefined || typeof record.error === "string") &&
+				(record.usage === undefined || isModelUsage(record.usage))
+			);
+		})
+	);
 }
 
 function isReasoningLevel(value: WorkflowSerializableValue): boolean {
-  return value === "off" || value === "minimal" || value === "low" || value === "medium"
-    || value === "high" || value === "xhigh" || value === "max";
+	return (
+		value === "off" ||
+		value === "minimal" ||
+		value === "low" ||
+		value === "medium" ||
+		value === "high" ||
+		value === "xhigh" ||
+		value === "max"
+	);
 }
 
 function isModelUsage(value: WorkflowSerializableValue): boolean {
-  if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
-  const usage = value as Record<string, WorkflowSerializableValue>;
-  return ["input", "output", "cacheRead", "cacheWrite", "cost", "turns"]
-    .every((key) => usage[key] === undefined || (typeof usage[key] === "number" && Number.isFinite(usage[key])));
+	if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+	const usage = value as Record<string, WorkflowSerializableValue>;
+	return ["input", "output", "cacheRead", "cacheWrite", "cost", "turns"].every(
+		(key) => usage[key] === undefined || (typeof usage[key] === "number" && Number.isFinite(usage[key])),
+	);
 }
 
 function isUiPromptKind(value: WorkflowSerializableValue | undefined): value is UiPromptKind {
-  return value === "input" || value === "confirm" || value === "select"
-    || value === "editor" || value === "custom";
+	return value === "input" || value === "confirm" || value === "select" || value === "editor" || value === "custom";
 }
 
 function isOptionalFiniteNumber(value: WorkflowSerializableValue | undefined): boolean {
-  return value === undefined || (typeof value === "number" && Number.isFinite(value));
+	return value === undefined || (typeof value === "number" && Number.isFinite(value));
 }
 
 function isStringArray(value: WorkflowSerializableValue | undefined): value is readonly string[] {
-  return Array.isArray(value) && value.every((item) => typeof item === "string");
+	return Array.isArray(value) && value.every((item) => typeof item === "string");
 }
 
 function checkpointOutputValue(cp: DurableCheckpoint): WorkflowSerializableValue | undefined {
-  if (cp.kind === "tool") return (cp as DurableToolCheckpoint).output;
-  if (cp.kind === "ui") return (cp as DurableUiCheckpoint).response;
-  const stage = cp as DurableStageCheckpoint;
-  return "output" in stage ? stage.output : undefined;
+	if (cp.kind === "tool") return (cp as DurableToolCheckpoint).output;
+	if (cp.kind === "ui") return (cp as DurableUiCheckpoint).response;
+	const stage = cp as DurableStageCheckpoint;
+	return "output" in stage ? stage.output : undefined;
 }