@bastani/atomic 0.8.31-alpha.5 → 0.9.0-alpha.2

package/dist/builtin/workflows/src/runs/foreground/executor-abort.ts

@@ -0,0 +1,431 @@
+import type { WorkflowExitOptions, WorkflowExitStatus } from "../../shared/types.js";
+import {
+  WORKFLOW_SERIALIZABLE_DESCRIPTION,
+  workflowSerializableTypeName,
+} from "../../shared/serializable.js";
+
+const WORKFLOW_EXIT_SIGNAL = Symbol("atomic-workflows.workflow-exit-signal");
+const WORKFLOW_EXIT_STATUSES: ReadonlySet<WorkflowExitStatus> = new Set([
+  "completed",
+  "skipped",
+  "cancelled",
+  "blocked",
+]);
+
+export type WorkflowExitOutputSnapshot =
+  | {
+      readonly ok: true;
+      readonly value: unknown;
+    }
+  | {
+      readonly ok: false;
+      readonly error: Error;
+    };
+
+export interface WorkflowExitSignal {
+  readonly [WORKFLOW_EXIT_SIGNAL]: true;
+  readonly scope: symbol;
+  readonly status: WorkflowExitStatus;
+  readonly reason?: string;
+  readonly outputSnapshot?: WorkflowExitOutputSnapshot;
+  readonly validationError?: Error;
+}
+
+export function makeWorkflowExitSignal(input: {
+  readonly scope: symbol;
+  readonly status: WorkflowExitStatus;
+  readonly reason?: string;
+  readonly outputSnapshot?: WorkflowExitOutputSnapshot;
+  readonly validationError?: Error;
+}): WorkflowExitSignal {
+  return {
+    [WORKFLOW_EXIT_SIGNAL]: true,
+    scope: input.scope,
+    status: input.status,
+    ...(input.reason !== undefined ? { reason: input.reason } : {}),
+    ...(input.outputSnapshot !== undefined ? { outputSnapshot: input.outputSnapshot } : {}),
+    ...(input.validationError !== undefined ? { validationError: input.validationError } : {}),
+  };
+}
+
+const WORKFLOW_EXIT_SNAPSHOT_INVALID_VALUE = Symbol("atomic-workflows.workflow-exit-snapshot-invalid-value");
+
+interface WorkflowExitSnapshotInvalidValue {
+  readonly [WORKFLOW_EXIT_SNAPSHOT_INVALID_VALUE]: true;
+  readonly typeName: string;
+}
+
+export type SafePropertyRead =
+  | { readonly ok: true; readonly value: unknown }
+  | { readonly ok: false };
+
+export function safeGetProperty(value: object, key: PropertyKey): SafePropertyRead {
+  try {
+    return { ok: true, value: (value as Record<PropertyKey, unknown>)[key] };
+  } catch {
+    return { ok: false };
+  }
+}
+
+export function unknownErrorMessage(error: unknown): string {
+  if (error !== null && (typeof error === "object" || typeof error === "function")) {
+    const message = safeGetProperty(error, "message");
+    if (message.ok && typeof message.value === "string" && message.value.length > 0) {
+      return message.value;
+    }
+  }
+  if (typeof error === "string") return error;
+  try {
+    return String(error);
+  } catch {
+    return "<unprintable thrown value>";
+  }
+}
+
+function workflowExitSnapshotError(message: string, cause: unknown): Error {
+  return new Error(`${message}: ${unknownErrorMessage(cause)}`, { cause });
+}
+
+function workflowExitOptionReadError(key: "status" | "reason" | "outputs", cause: unknown): Error {
+  return workflowExitSnapshotError(`atomic-workflows: ctx.exit() ${key} option could not be read`, cause);
+}
+
+export function readWorkflowExitOption(
+  options: Pick<WorkflowExitOptions, "status" | "reason" | "outputs"> | null | undefined,
+  key: "status" | "reason" | "outputs",
+): { readonly ok: true; readonly value: unknown } | { readonly ok: false; readonly error: Error } {
+  try {
+    return { ok: true, value: options?.[key] };
+  } catch (err) {
+    return { ok: false, error: workflowExitOptionReadError(key, err) };
+  }
+}
+
+export function describeWorkflowExitOptionValue(value: unknown): string {
+  try {
+    const json = JSON.stringify(value);
+    if (json !== undefined) return json;
+  } catch {
+    // Diagnostic-only fallback below.
+  }
+  return workflowSerializableTypeName(value);
+}
+
+function isPlainWorkflowExitSnapshotObject(value: object): boolean {
+  const proto = Object.getPrototypeOf(value);
+  return proto === Object.prototype || proto === null;
+}
+
+function makeWorkflowExitSnapshotInvalidValue(typeName: string): WorkflowExitSnapshotInvalidValue {
+  const marker = {} as { [WORKFLOW_EXIT_SNAPSHOT_INVALID_VALUE]?: true; typeName?: string };
+  Object.defineProperty(marker, WORKFLOW_EXIT_SNAPSHOT_INVALID_VALUE, {
+    value: true,
+    enumerable: false,
+  });
+  Object.defineProperty(marker, "typeName", {
+    value: typeName,
+    enumerable: false,
+  });
+  return Object.freeze(marker) as WorkflowExitSnapshotInvalidValue;
+}
+
+export function isWorkflowExitSnapshotInvalidValue(value: unknown): value is WorkflowExitSnapshotInvalidValue {
+  return value !== null && typeof value === "object" &&
+    (value as Record<PropertyKey, unknown>)[WORKFLOW_EXIT_SNAPSHOT_INVALID_VALUE] === true;
+}
+
+function cloneWorkflowExitSnapshotValue(
+  value: unknown,
+  seen: Map<object, unknown>,
+  stack: Set<object> = new Set(),
+): unknown {
+  if (value === null) return null;
+  const valueType = typeof value;
+  if (valueType !== "object") {
+    return valueType === "function"
+      ? makeWorkflowExitSnapshotInvalidValue("function")
+      : value;
+  }
+
+  const objectValue = value as object;
+  const previousClone = seen.get(objectValue);
+  if (previousClone !== undefined) {
+    return stack.has(objectValue)
+      ? makeWorkflowExitSnapshotInvalidValue("circular object")
+      : previousClone;
+  }
+
+  if (Array.isArray(value)) {
+    const clone: unknown[] = [];
+    seen.set(objectValue, clone);
+    stack.add(objectValue);
+    try {
+      for (let index = 0; index < value.length; index += 1) {
+        clone[index] = cloneWorkflowExitSnapshotValue(value[index], seen, stack);
+      }
+    } finally {
+      stack.delete(objectValue);
+    }
+    return clone;
+  }
+
+  if (!isPlainWorkflowExitSnapshotObject(objectValue)) {
+    return makeWorkflowExitSnapshotInvalidValue(workflowSerializableTypeName(value));
+  }
+
+  const clone: Record<string, unknown> = {};
+  seen.set(objectValue, clone);
+  stack.add(objectValue);
+  try {
+    for (const key of Object.keys(value as Record<string, unknown>)) {
+      clone[key] = cloneWorkflowExitSnapshotValue((value as Record<string, unknown>)[key], seen, stack);
+    }
+  } finally {
+    stack.delete(objectValue);
+  }
+  return clone;
+}
+
+function deepFreezeWorkflowExitSnapshotValue(value: unknown): void {
+  if (value === null || typeof value !== "object" || Object.isFrozen(value)) return;
+  Object.freeze(value);
+  if (Array.isArray(value)) {
+    for (const item of value) deepFreezeWorkflowExitSnapshotValue(item);
+    return;
+  }
+  for (const key of Object.keys(value as Record<string, unknown>)) {
+    deepFreezeWorkflowExitSnapshotValue((value as Record<string, unknown>)[key]);
+  }
+}
+
+export function freezeWorkflowExitOutputSnapshot(snapshot: WorkflowExitOutputSnapshot): WorkflowExitOutputSnapshot {
+  return Object.freeze(snapshot);
+}
+
+export function captureWorkflowExitOutputSnapshot(rawOutputs: unknown): WorkflowExitOutputSnapshot {
+  let snapshot: WorkflowExitOutputSnapshot;
+  try {
+    const value = cloneWorkflowExitSnapshotValue(rawOutputs, new Map());
+    deepFreezeWorkflowExitSnapshotValue(value);
+    snapshot = { ok: true, value };
+  } catch (err) {
+    snapshot = {
+      ok: false,
+      error: workflowExitSnapshotError("atomic-workflows: ctx.exit() outputs could not be snapshotted", err),
+    };
+  }
+  return freezeWorkflowExitOutputSnapshot(snapshot);
+}
+
+function formatWorkflowExitSnapshotPath(parent: string, key: string): string {
+  const segment = /^\d+$/.test(key)
+    ? `[${key}]`
+    : /^[A-Za-z_$][\w$]*$/.test(key)
+      ? (parent.length > 0 ? `.${key}` : key)
+      : `[${JSON.stringify(key)}]`;
+  return `${parent}${segment}`;
+}
+
+function findWorkflowExitSnapshotInvalidValue(
+  value: unknown,
+  path = "",
+  seen = new Set<unknown>(),
+): { readonly path: string; readonly typeName: string } | undefined {
+  if (isWorkflowExitSnapshotInvalidValue(value)) {
+    return { path, typeName: value.typeName };
+  }
+  if (value === null || typeof value !== "object") return undefined;
+  if (seen.has(value)) return undefined;
+  seen.add(value);
+
+  if (Array.isArray(value)) {
+    for (let index = 0; index < value.length; index += 1) {
+      const found = findWorkflowExitSnapshotInvalidValue(value[index], `${path}[${index}]`, seen);
+      if (found !== undefined) return found;
+    }
+    return undefined;
+  }
+
+  for (const key of Object.keys(value as Record<string, unknown>)) {
+    const found = findWorkflowExitSnapshotInvalidValue(
+      (value as Record<string, unknown>)[key],
+      formatWorkflowExitSnapshotPath(path, key),
+      seen,
+    );
+    if (found !== undefined) return found;
+  }
+  return undefined;
+}
+
+export function workflowExitSnapshotInvalidValueMessage(label: string, value: unknown): string | undefined {
+  const invalid = findWorkflowExitSnapshotInvalidValue(value);
+  if (invalid === undefined) return undefined;
+  const location = invalid.path.length > 0 ? ` at ${invalid.path}` : "";
+  return `${label}${location} must be ${WORKFLOW_SERIALIZABLE_DESCRIPTION}, got ${invalid.typeName}`;
+}
+
+const PARENT_WORKFLOW_EXIT_ABORT = Symbol("atomic-workflows.parent-workflow-exit-abort");
+
+interface ParentWorkflowExitAbortReason extends Error {
+  readonly [PARENT_WORKFLOW_EXIT_ABORT]: true;
+  readonly workflowExitReason?: string;
+}
+
+export function parentWorkflowExitRunReason(reason?: string): string {
+  return reason === undefined || reason.length === 0
+    ? "parent workflow exited"
+    : `parent workflow exited: ${reason}`;
+}
+
+export function makeParentWorkflowExitAbortReason(reason?: string): ParentWorkflowExitAbortReason {
+  const error = new Error(parentWorkflowExitRunReason(reason)) as ParentWorkflowExitAbortReason & {
+    [PARENT_WORKFLOW_EXIT_ABORT]: true;
+    workflowExitReason?: string;
+  };
+  Object.defineProperty(error, PARENT_WORKFLOW_EXIT_ABORT, {
+    value: true,
+    enumerable: false,
+  });
+  if (reason !== undefined) error.workflowExitReason = reason;
+  return error;
+}
+
+export interface ParentWorkflowExitAbortProbe {
+  readonly workflowExitReason?: string;
+}
+
+export function parentWorkflowExitAbortReason(value: unknown): ParentWorkflowExitAbortProbe | undefined {
+  if (value === null || (typeof value !== "object" && typeof value !== "function")) return undefined;
+  const marker = safeGetProperty(value, PARENT_WORKFLOW_EXIT_ABORT);
+  if (!marker.ok || marker.value !== true) return undefined;
+
+  const reason = safeGetProperty(value, "workflowExitReason");
+  return reason.ok && typeof reason.value === "string"
+    ? { workflowExitReason: reason.value }
+    : {};
+}
+
+export function isWorkflowExitStatus(value: unknown): value is WorkflowExitStatus {
+  return typeof value === "string" && WORKFLOW_EXIT_STATUSES.has(value as WorkflowExitStatus);
+}
+
+function safeErrorValue(value: unknown): Error {
+  try {
+    if (value instanceof Error) return value;
+  } catch {
+    // Fall through to a safe wrapper below.
+  }
+  return new Error(unknownErrorMessage(value));
+}
+
+function readWorkflowExitOutputSnapshot(value: unknown): WorkflowExitOutputSnapshot | undefined {
+  if (value === undefined) return undefined;
+  if (value === null || (typeof value !== "object" && typeof value !== "function")) return undefined;
+  const ok = safeGetProperty(value, "ok");
+  if (!ok.ok) return undefined;
+  if (ok.value === true) {
+    const snapshotValue = safeGetProperty(value, "value");
+    return snapshotValue.ok ? { ok: true, value: snapshotValue.value } : undefined;
+  }
+  if (ok.value === false) {
+    const error = safeGetProperty(value, "error");
+    return error.ok ? { ok: false, error: safeErrorValue(error.value) } : undefined;
+  }
+  return undefined;
+}
+
+function readWorkflowExitSignalCandidate(value: object, scope: symbol): WorkflowExitSignal | undefined {
+  const marker = safeGetProperty(value, WORKFLOW_EXIT_SIGNAL);
+  if (!marker.ok || marker.value !== true) return undefined;
+
+  const signalScope = safeGetProperty(value, "scope");
+  if (!signalScope.ok || signalScope.value !== scope) return undefined;
+
+  const status = safeGetProperty(value, "status");
+  if (!status.ok || !isWorkflowExitStatus(status.value)) return undefined;
+
+  const reason = safeGetProperty(value, "reason");
+  if (!reason.ok || (reason.value !== undefined && typeof reason.value !== "string")) return undefined;
+
+  const outputSnapshotValue = safeGetProperty(value, "outputSnapshot");
+  if (!outputSnapshotValue.ok) return undefined;
+  const outputSnapshot = readWorkflowExitOutputSnapshot(outputSnapshotValue.value);
+  if (outputSnapshotValue.value !== undefined && outputSnapshot === undefined) return undefined;
+
+  const validationError = safeGetProperty(value, "validationError");
+  if (!validationError.ok) return undefined;
+
+  return {
+    [WORKFLOW_EXIT_SIGNAL]: true,
+    scope,
+    status: status.value,
+    ...(reason.value !== undefined ? { reason: reason.value } : {}),
+    ...(outputSnapshot !== undefined ? { outputSnapshot } : {}),
+    ...(validationError.value !== undefined ? { validationError: safeErrorValue(validationError.value) } : {}),
+  };
+}
+
+export function findWorkflowExitSignal(error: unknown, scope: symbol, seen = new Set<unknown>()): WorkflowExitSignal | undefined {
+  if (error === null || (typeof error !== "object" && typeof error !== "function")) return undefined;
+  if (seen.has(error)) return undefined;
+  seen.add(error);
+
+  const directSignal = readWorkflowExitSignalCandidate(error, scope);
+  if (directSignal !== undefined) return directSignal;
+
+  const errors = safeExecutorAggregateErrorItems(error);
+  for (const item of errors) {
+    const signal = findWorkflowExitSignal(item, scope, seen);
+    if (signal !== undefined) return signal;
+  }
+
+  const cause = safeGetProperty(error, "cause");
+  if (cause.ok) {
+    const causeSignal = findWorkflowExitSignal(cause.value, scope, seen);
+    if (causeSignal !== undefined) return causeSignal;
+  }
+
+  const reason = safeGetProperty(error, "reason");
+  return reason.ok ? findWorkflowExitSignal(reason.value, scope, seen) : undefined;
+}
+
+function safeArrayItems(value: unknown): readonly unknown[] {
+  try {
+    if (!Array.isArray(value)) return [];
+    const items: unknown[] = [];
+    const { length } = value;
+    for (let index = 0; index < length; index += 1) {
+      try {
+        items.push(value[index]);
+      } catch {
+        // Ignore inaccessible aggregate items while preserving readable ones.
+      }
+    }
+    return items;
+  } catch {
+    return [];
+  }
+}
+
+export function safeExecutorAggregateErrorItems(error: unknown): readonly unknown[] {
+  if (error === null || (typeof error !== "object" && typeof error !== "function")) return [];
+  const errors = safeGetProperty(error, "errors");
+  return errors.ok ? safeArrayItems(errors.value) : [];
+}
+
+export function raceAbort<T>(promise: Promise<T>, signal: AbortSignal): Promise<T> {
+  if (signal.aborted) {
+    void promise.catch(() => {});
+    return Promise.reject(signal.reason ?? new DOMException("workflow killed", "AbortError"));
+  }
+  return new Promise<T>((resolve, reject) => {
+    const onAbort = (): void => {
+      reject(signal.reason ?? new DOMException("workflow killed", "AbortError"));
+    };
+    signal.addEventListener("abort", onAbort, { once: true });
+    promise.then(
+      (val) => { signal.removeEventListener("abort", onAbort); resolve(val); },
+      (err: unknown) => { signal.removeEventListener("abort", onAbort); reject(err); },
+    );
+  });
+}

package/dist/builtin/workflows/src/runs/foreground/executor-child-boundary.ts

@@ -0,0 +1,232 @@
+import type { RunSnapshot, StageSnapshot, WorkflowChildReplaySnapshot, WorkflowChildRunRef } from "../../shared/store-types.js";
+import type { Store } from "../../shared/store.js";
+import type { WorkflowChildResult } from "../../shared/types.js";
+import { appendStageEnd, appendStageStart } from "../../shared/persistence-session-entries.js";
+import { elapsedStageMs } from "../../shared/timing.js";
+import type { WorkflowFailure } from "../../shared/workflow-failures.js";
+import type { EngineWorkflowBoundaryOptions } from "../../engine/options.js";
+import type { ContinuationReplayIndex } from "./executor-continuation.js";
+import { sameStringSet } from "./executor-continuation.js";
+import { applyFailureToStage, stageReplayFields } from "./executor-lifecycle.js";
+import { cloneWorkflowChildReplaySnapshot, cloneWorkflowChildValue } from "./executor-child-helpers.js";
+import type { GraphFrontierTracker } from "../../engine/graph-inference.js";
+import type { WorkflowExitCleanup } from "./executor-types.js";
+import { makeParentWorkflowExitAbortReason } from "./executor-abort.js";
+
+interface LinkedChildWorkflowExitState {
+  readonly ref: WorkflowChildRunRef;
+  readonly controller: AbortController;
+  runPromise?: Promise<unknown>;
+}
+
+export interface WorkflowBoundaryStage {
+  readonly id: string;
+  readonly replayedChild?: WorkflowChildResult;
+  finalizeReplay(): void;
+  linkChildRun(ref: WorkflowChildRunRef, childController: AbortController): void;
+  observeChildRun(promise: Promise<unknown>): void;
+  complete(summary: string, workflowChild: WorkflowChildReplaySnapshot): void;
+  skipForWorkflowExit(reason?: string): Promise<void>;
+  fail(error: unknown): void;
+}
+
+function workflowChildResultFromReplay(snapshot: WorkflowChildReplaySnapshot): WorkflowChildResult {
+  const outputs = cloneWorkflowChildValue(snapshot.outputs);
+  if (snapshot.exited === true || snapshot.status !== "completed") {
+    return {
+      workflow: snapshot.workflow,
+      runId: snapshot.runId,
+      status: snapshot.status,
+      exited: true,
+      outputs,
+      ...(snapshot.exitReason !== undefined ? { exitReason: snapshot.exitReason } : {}),
+    };
+  }
+  return {
+    workflow: snapshot.workflow,
+    runId: snapshot.runId,
+    status: "completed",
+    exited: false,
+    outputs,
+  };
+}
+
+function requestLinkedChildWorkflowExit(linkedChild: LinkedChildWorkflowExitState, reason?: string): void {
+  if (!linkedChild.controller.signal.aborted) {
+    linkedChild.controller.abort(makeParentWorkflowExitAbortReason(reason));
+  }
+}
+
+async function waitForLinkedChildWorkflowExit(linkedChild: LinkedChildWorkflowExitState): Promise<void> {
+  const childRun = linkedChild.runPromise;
+  if (childRun === undefined) return;
+  try {
+    await childRun;
+  } catch {
+    // Parent exit cleanup intentionally swallows child teardown failures.
+  }
+}
+
+export function createWorkflowBoundaryFactory(input: {
+  readonly runId: string;
+  readonly runSnapshot: RunSnapshot;
+  readonly activeStore: Store;
+  readonly opts: EngineWorkflowBoundaryOptions;
+  readonly tracker: GraphFrontierTracker;
+  readonly replayIndex: ContinuationReplayIndex;
+  readonly registerWorkflowExitCleanup: (stageId: string, cleanup: WorkflowExitCleanup) => () => void;
+  readonly workflowExitSkippedReason: (reason?: string) => string;
+  readonly classifyExecutorFailure: (error: unknown) => WorkflowFailure;
+}): (name: string, replayKey: string) => WorkflowBoundaryStage {
+  return (name: string, replayKey: string): WorkflowBoundaryStage => {
+    const stageId = crypto.randomUUID();
+    const provisionalParentIds = input.tracker.onSpawn(stageId, name);
+    const replayDecision = input.replayIndex.decide({
+      displayName: name,
+      replayKey,
+      parentIds: provisionalParentIds,
+      stageId,
+      kind: "workflow",
+    });
+    const parentIds = replayDecision.parentIds;
+    if (!sameStringSet(parentIds, provisionalParentIds)) input.tracker.replaceParents(stageId, parentIds);
+    const replaySource = replayDecision.source;
+    const replayChildSnapshot = replayDecision.kind === "replay" ? replayDecision.source.workflowChild : undefined;
+    const replayedChild = replayChildSnapshot !== undefined ? workflowChildResultFromReplay(replayChildSnapshot) : undefined;
+    const startedAt = Date.now();
+    const stageSnapshot: StageSnapshot = {
+      id: stageId,
+      name,
+      replayKey,
+      status: replayedChild !== undefined ? "completed" : "running",
+      parentIds: Object.freeze([...parentIds]),
+      startedAt,
+      toolEvents: [],
+      attachable: false,
+      ...(replaySource !== undefined ? { replayedFromStageId: replaySource.id, replayed: replayedChild !== undefined } : {}),
+      ...(replayedChild !== undefined && replayChildSnapshot !== undefined ? {
+        endedAt: startedAt,
+        durationMs: 0,
+        ...(replayDecision.kind === "replay" && replayDecision.source.result !== undefined ? { result: replayDecision.source.result } : {}),
+        workflowChild: cloneWorkflowChildReplaySnapshot(replayChildSnapshot),
+      } : {}),
+    };
+    let finalized = false;
+    let unregisterWorkflowExitCleanup = (): void => {};
+    let linkedChild: LinkedChildWorkflowExitState | undefined;
+
+    const appendStageStartOnce = (): void => {
+      if (!input.opts.persistence) return;
+      appendStageStart(input.opts.persistence, {
+        runId: input.runId,
+        stageId,
+        name,
+        parentIds: stageSnapshot.parentIds,
+        ...stageReplayFields(stageSnapshot),
+        ts: startedAt,
+      });
+    };
+
+    const appendStageEndForSnapshot = (): void => {
+      if (!input.opts.persistence) return;
+      appendStageEnd(input.opts.persistence, {
+        runId: input.runId,
+        stageId,
+        status: stageSnapshot.status,
+        durationMs: stageSnapshot.durationMs,
+        ...(stageSnapshot.error !== undefined ? { error: stageSnapshot.error } : {}),
+        ...(stageSnapshot.failureKind !== undefined ? { failureKind: stageSnapshot.failureKind } : {}),
+        ...(stageSnapshot.failureCode !== undefined ? { failureCode: stageSnapshot.failureCode } : {}),
+        ...(stageSnapshot.failureRecoverability !== undefined ? { failureRecoverability: stageSnapshot.failureRecoverability } : {}),
+        ...(stageSnapshot.failureDisposition !== undefined ? { failureDisposition: stageSnapshot.failureDisposition } : {}),
+        ...(stageSnapshot.failureMessage !== undefined ? { failureMessage: stageSnapshot.failureMessage } : {}),
+        ...(stageSnapshot.retryAfterMs !== undefined ? { retryAfterMs: stageSnapshot.retryAfterMs } : {}),
+        ...(stageSnapshot.skippedReason !== undefined ? { skippedReason: stageSnapshot.skippedReason } : {}),
+        ...(stageSnapshot.sessionId !== undefined ? { sessionId: stageSnapshot.sessionId } : {}),
+        ...(stageSnapshot.sessionFile !== undefined ? { sessionFile: stageSnapshot.sessionFile } : {}),
+        ...(stageSnapshot.result !== undefined && stageSnapshot.status === "completed" ? { summary: stageSnapshot.result } : {}),
+        ...stageReplayFields(stageSnapshot),
+        ...(stageSnapshot.status === "completed" && stageSnapshot.workflowChild !== undefined ? { workflowChild: stageSnapshot.workflowChild } : {}),
+      });
+    };
+
+    const clearBoundaryChildMetadata = (): void => {
+      delete stageSnapshot.workflowChildRun;
+      delete stageSnapshot.workflowChild;
+    };
+
+    const finalize = (status: "completed" | "failed" | "skipped", summaryOrError: string, workflowChild?: WorkflowChildReplaySnapshot, failureError?: unknown): void => {
+      if (finalized) return;
+      finalized = true;
+      unregisterWorkflowExitCleanup();
+      stageSnapshot.status = status;
+      if (status === "completed") {
+        stageSnapshot.result = summaryOrError;
+        if (workflowChild !== undefined) stageSnapshot.workflowChild = workflowChild;
+      } else if (status === "skipped") {
+        clearBoundaryChildMetadata();
+        stageSnapshot.skippedReason = summaryOrError;
+      } else {
+        clearBoundaryChildMetadata();
+        applyFailureToStage(stageSnapshot, input.classifyExecutorFailure(failureError));
+      }
+      stageSnapshot.endedAt = Date.now();
+      stageSnapshot.durationMs = elapsedStageMs(stageSnapshot, stageSnapshot.endedAt);
+      input.activeStore.recordStageEnd(input.runId, stageSnapshot);
+      input.opts.onStageEnd?.(input.runId, stageSnapshot);
+      appendStageEndForSnapshot();
+      input.tracker.onSettle(stageId);
+    };
+
+    input.activeStore.recordStageStart(input.runId, stageSnapshot);
+    input.opts.onStageStart?.(input.runId, stageSnapshot);
+    appendStageStartOnce();
+
+    unregisterWorkflowExitCleanup = input.registerWorkflowExitCleanup(stageId, {
+      async skipForWorkflowExit(reason?: string): Promise<void> {
+        const child = linkedChild;
+        if (child !== undefined) requestLinkedChildWorkflowExit(child, reason);
+        finalize("skipped", input.workflowExitSkippedReason(reason));
+        if (child !== undefined) await waitForLinkedChildWorkflowExit(child);
+      },
+    });
+
+    const finalizeReplay = (): void => {
+      if (replayedChild === undefined || finalized) return;
+      finalized = true;
+      unregisterWorkflowExitCleanup();
+      input.activeStore.recordStageEnd(input.runId, stageSnapshot);
+      input.opts.onStageEnd?.(input.runId, stageSnapshot);
+      appendStageEndForSnapshot();
+      input.tracker.onSettle(stageId);
+    };
+
+    return {
+      id: stageId,
+      ...(replayedChild !== undefined ? { replayedChild } : {}),
+      finalizeReplay,
+      linkChildRun(ref: WorkflowChildRunRef, childController: AbortController): void {
+        if (finalized) return;
+        linkedChild = { ref: { ...ref }, controller: childController };
+        stageSnapshot.workflowChildRun = { ...ref };
+        input.activeStore.recordStageWorkflowChildRun(input.runId, stageId, ref);
+      },
+      observeChildRun(promise: Promise<unknown>): void {
+        if (linkedChild === undefined || finalized) return;
+        linkedChild.runPromise = promise;
+      },
+      complete(summary: string, workflowChild: WorkflowChildReplaySnapshot): void {
+        finalize("completed", summary, workflowChild);
+      },
+      async skipForWorkflowExit(reason?: string): Promise<void> {
+        const child = linkedChild;
+        if (child !== undefined) requestLinkedChildWorkflowExit(child, reason);
+        finalize("skipped", input.workflowExitSkippedReason(reason));
+        if (child !== undefined) await waitForLinkedChildWorkflowExit(child);
+      },
+      fail(error: unknown): void {
+        finalize("failed", error instanceof Error ? error.message : String(error), undefined, error);
+      },
+    };
+  };
+}