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

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

@@ -0,0 +1,441 @@
+import type {
+  WorkflowFailureCode,
+  WorkflowFailureDisposition,
+  WorkflowFailureKind,
+  WorkflowFailureRecoverability,
+  RunSnapshot,
+  RunStatus,
+  StageSnapshot,
+} from "../../shared/store-types.js";
+import type { Store } from "../../shared/store.js";
+import type { WorkflowPersistencePort, WorkflowOutputValues } from "../../shared/types.js";
+import type { WorkflowFailure } from "../../shared/workflow-failures.js";
+import { appendRunBlocked, appendRunEnd } from "../../shared/persistence-session-entries.js";
+import type { RunOpts, RunResult } from "./executor-types.js";
+import { safeExecutorAggregateErrorItems } from "./executor-abort.js";
+
+export const EMPTY_WORKFLOW_GRAPH_ERROR_MESSAGE = "Workflow run completed without creating any workflow stages. Create at least one stage with ctx.stage(), ctx.task(), ctx.chain(), ctx.parallel(), or ctx.workflow().";
+
+export function assertWorkflowCreatedStage(runSnapshot: RunSnapshot): void {
+  if (runSnapshot.stages.length > 0) return;
+  throw new Error(EMPTY_WORKFLOW_GRAPH_ERROR_MESSAGE);
+}
+
+export function appendRunEndWhenRecorded(
+  persistence: WorkflowPersistencePort | undefined,
+  recorded: boolean,
+  payload: {
+    readonly runId: string;
+    readonly status: RunStatus;
+    readonly result?: WorkflowOutputValues;
+    readonly error?: string;
+    readonly exited?: boolean;
+    readonly exitReason?: string;
+    readonly failureKind?: WorkflowFailureKind;
+    readonly failureCode?: WorkflowFailureCode;
+    readonly failureRecoverability?: WorkflowFailureRecoverability;
+    readonly failureDisposition?: WorkflowFailureDisposition;
+    readonly failureMessage?: string;
+    readonly failedStageId?: string;
+    readonly resumable?: boolean;
+    readonly retryAfterMs?: number;
+    readonly ts: number;
+  },
+): void {
+  if (!persistence || !recorded) return;
+  appendRunEnd(persistence, payload);
+}
+
+export function isTerminalRunStatus(status: RunStatus): boolean {
+  return status === "completed" ||
+    status === "failed" ||
+    status === "killed" ||
+    status === "skipped" ||
+    status === "cancelled" ||
+    status === "blocked";
+}
+
+export function runResultFromSnapshot(snapshot: RunSnapshot): RunResult {
+  return {
+    runId: snapshot.id,
+    status: snapshot.status,
+    ...(snapshot.result !== undefined ? { result: snapshot.result } : {}),
+    ...(snapshot.error !== undefined ? { error: snapshot.error } : {}),
+    ...(snapshot.exited !== undefined ? { exited: snapshot.exited } : {}),
+    ...(snapshot.exitReason !== undefined ? { exitReason: snapshot.exitReason } : {}),
+    stages: [...snapshot.stages],
+  };
+}
+
+export function reconcileTerminalRunResult(
+  runId: string,
+  runSnapshot: RunSnapshot,
+  activeStore: Store,
+  fallback: Omit<RunResult, "runId" | "stages">,
+  onRunEnd: RunOpts["onRunEnd"],
+): RunResult {
+  const canonical = activeStore.runs().find((snapshot) =>
+    snapshot.id === runId && isTerminalRunStatus(snapshot.status)
+  );
+  const result = canonical !== undefined
+    ? runResultFromSnapshot(canonical)
+    : {
+        runId,
+        ...fallback,
+        stages: [...runSnapshot.stages],
+      };
+  onRunEnd?.(runId, result.status, result.result, result.error, result.exitReason);
+  return result;
+}
+
+export interface RunFailureMetadata {
+  readonly errorMessage: string;
+  readonly failureKind: WorkflowFailureKind;
+  readonly failureCode?: WorkflowFailureCode;
+  readonly failureRecoverability?: WorkflowFailureRecoverability;
+  readonly failureDisposition?: WorkflowFailureDisposition;
+  readonly failureMessage: string;
+  readonly failedStageId?: string;
+  readonly resumable: boolean;
+  readonly retryAfterMs?: number;
+}
+
+export function applyFailureToStage(stage: StageSnapshot, failure: WorkflowFailure): void {
+  stage.status = "failed";
+  stage.error = failure.userMessage;
+  stage.failureKind = failure.kind;
+  stage.failureCode = failure.code;
+  stage.failureRecoverability = failure.recoverability;
+  stage.failureDisposition = failure.disposition;
+  stage.retryAfterMs = failure.retryAfterMs;
+  stage.failureMessage = failure.message;
+}
+
+export function runFailureMetadata(
+  failure: WorkflowFailure,
+  stages: readonly StageSnapshot[],
+): RunFailureMetadata {
+  const failedStage = stages.find((stage) => stage.status === "failed");
+  const failureKind = failedStage?.failureKind ?? failure.kind;
+  const failureCode = failedStage?.failureCode ?? failure.code;
+  const failureRecoverability = failedStage?.failureRecoverability ?? failure.recoverability;
+  const failureDisposition = failedStage?.failureDisposition ?? failure.disposition;
+  const retryAfterMs = failedStage?.retryAfterMs ?? failure.retryAfterMs;
+
+  return {
+    errorMessage: failedStage?.error ?? failure.userMessage,
+    failureKind,
+    ...(failureCode !== undefined ? { failureCode } : {}),
+    failureRecoverability,
+    failureDisposition,
+    failureMessage: failedStage?.failureMessage ?? failure.message,
+    ...(failedStage !== undefined ? { failedStageId: failedStage.id } : {}),
+    resumable: failure.resumable,
+    ...(retryAfterMs !== undefined ? { retryAfterMs } : {}),
+  };
+}
+
+interface SelectedRunFailureMetadata extends RunFailureMetadata {
+  readonly failedStageIds: readonly string[];
+}
+
+function stageDispositionResumable(
+  disposition: WorkflowFailureDisposition | undefined,
+  fallback: boolean,
+): boolean {
+  if (disposition === "terminal_killed") return false;
+  if (disposition === "active_blocked") return true;
+  return fallback;
+}
+
+function runFailureMetadataFromStage(
+  fallbackFailure: WorkflowFailure,
+  stage: StageSnapshot,
+): RunFailureMetadata {
+  const failureKind = stage.failureKind ?? fallbackFailure.kind;
+  const failureCode = stage.failureCode ?? fallbackFailure.code;
+  const failureRecoverability = stage.failureRecoverability ?? fallbackFailure.recoverability;
+  const failureDisposition = stage.failureDisposition ?? fallbackFailure.disposition;
+  const retryAfterMs = stage.retryAfterMs ?? fallbackFailure.retryAfterMs;
+
+  return {
+    errorMessage: stage.error ?? fallbackFailure.userMessage,
+    failureKind,
+    ...(failureCode !== undefined ? { failureCode } : {}),
+    failureRecoverability,
+    failureDisposition,
+    failureMessage: stage.failureMessage ?? fallbackFailure.message,
+    failedStageId: stage.id,
+    resumable: stageDispositionResumable(failureDisposition, fallbackFailure.resumable),
+    ...(retryAfterMs !== undefined ? { retryAfterMs } : {}),
+  };
+}
+
+function runFailureMetadataFromFailure(
+  failure: WorkflowFailure,
+  failedStage: StageSnapshot | undefined,
+): RunFailureMetadata {
+  return {
+    errorMessage: failedStage?.error ?? failure.userMessage,
+    failureKind: failure.kind,
+    ...(failure.code !== undefined ? { failureCode: failure.code } : {}),
+    failureRecoverability: failure.recoverability,
+    failureDisposition: failure.disposition,
+    failureMessage: failedStage?.failureMessage ?? failure.message,
+    ...(failedStage !== undefined ? { failedStageId: failedStage.id } : {}),
+    resumable: failure.resumable,
+    ...(failure.retryAfterMs !== undefined ? { retryAfterMs: failure.retryAfterMs } : {}),
+  };
+}
+
+function aggregateInnerFailures(
+  error: unknown,
+  classifyFailure: (error: unknown) => WorkflowFailure,
+): readonly WorkflowFailure[] {
+  return safeExecutorAggregateErrorItems(error).map((innerError) => classifyFailure(innerError));
+}
+
+type StageFailureCandidate = {
+  readonly source: "stage";
+  readonly stage: StageSnapshot;
+  readonly disposition: WorkflowFailureDisposition;
+  readonly recoverability: WorkflowFailureRecoverability;
+};
+
+type AggregateFailureCandidate = {
+  readonly source: "aggregate";
+  readonly failure: WorkflowFailure;
+  readonly disposition: WorkflowFailureDisposition;
+  readonly recoverability: WorkflowFailureRecoverability;
+};
+
+type OuterFailureCandidate = {
+  readonly source: "outer";
+  readonly failure: WorkflowFailure;
+  readonly disposition: WorkflowFailureDisposition;
+  readonly recoverability: WorkflowFailureRecoverability;
+};
+
+type FailureCandidate = StageFailureCandidate | AggregateFailureCandidate | OuterFailureCandidate;
+
+function stageFailureCandidate(stage: StageSnapshot): StageFailureCandidate {
+  return {
+    source: "stage",
+    stage,
+    disposition: stage.failureDisposition ?? "terminal_failed",
+    recoverability: stage.failureRecoverability ?? "unknown",
+  };
+}
+
+function aggregateFailureCandidate(failure: WorkflowFailure): AggregateFailureCandidate {
+  return {
+    source: "aggregate",
+    failure,
+    disposition: failure.disposition,
+    recoverability: failure.recoverability,
+  };
+}
+
+function outerFailureCandidate(failure: WorkflowFailure): OuterFailureCandidate {
+  return {
+    source: "outer",
+    failure,
+    disposition: failure.disposition,
+    recoverability: failure.recoverability,
+  };
+}
+
+function isRecoverableActiveBlockedCandidate(candidate: FailureCandidate): boolean {
+  return candidate.disposition === "active_blocked" && candidate.recoverability === "recoverable";
+}
+
+function isAggregateWrapper(error: unknown): boolean {
+  return safeExecutorAggregateErrorItems(error).length > 0;
+}
+
+function runFailureMetadataFromCandidate(
+  fallbackFailure: WorkflowFailure,
+  candidate: FailureCandidate,
+  thrownError: unknown,
+): RunFailureMetadata {
+  let metadata: RunFailureMetadata;
+  switch (candidate.source) {
+    case "stage":
+      metadata = runFailureMetadataFromStage(fallbackFailure, candidate.stage);
+      break;
+    case "aggregate":
+    case "outer":
+      metadata = runFailureMetadataFromFailure(candidate.failure, undefined);
+      break;
+  }
+
+  if (candidate.disposition === "terminal_failed" && isAggregateWrapper(thrownError)) {
+    return { ...metadata, errorMessage: fallbackFailure.userMessage };
+  }
+  return metadata;
+}
+
+function failedStageIdsForCandidate(
+  candidate: FailureCandidate,
+  failedStages: readonly StageSnapshot[],
+): readonly string[] {
+  switch (candidate.source) {
+    case "aggregate":
+      return failedStages.map((stage) => stage.id);
+    case "outer":
+      return [];
+    case "stage":
+      return failedStages
+        .filter((stage) => (stage.failureDisposition ?? "terminal_failed") === candidate.disposition)
+        .map((stage) => stage.id);
+  }
+}
+
+function selectedMetadata(metadata: RunFailureMetadata, failedStageIds: readonly string[]): SelectedRunFailureMetadata {
+  return { ...metadata, failedStageIds };
+}
+
+export function selectRunFailureDisposition(input: {
+  readonly outerFailure: WorkflowFailure;
+  readonly thrownError: unknown;
+  readonly stages: readonly StageSnapshot[];
+  readonly classifyFailure: (error: unknown) => WorkflowFailure;
+}): SelectedRunFailureMetadata {
+  const failedStages = input.stages.filter((stage) => stage.status === "failed");
+  const failedStageIds = failedStages.map((stage) => stage.id);
+  const aggregateFailures = aggregateInnerFailures(input.thrownError, input.classifyFailure);
+  const candidates: readonly FailureCandidate[] = [
+    ...failedStages.map(stageFailureCandidate),
+    ...aggregateFailures.map(aggregateFailureCandidate),
+    outerFailureCandidate(input.outerFailure),
+  ];
+
+  const terminalKilledCandidate = candidates.find((candidate) => candidate.disposition === "terminal_killed");
+  if (terminalKilledCandidate !== undefined) {
+    return selectedMetadata(
+      runFailureMetadataFromCandidate(input.outerFailure, terminalKilledCandidate, input.thrownError),
+      failedStageIdsForCandidate(terminalKilledCandidate, failedStages),
+    );
+  }
+
+  const terminalFailedCandidate = candidates.find((candidate) => candidate.disposition === "terminal_failed");
+  if (terminalFailedCandidate !== undefined) {
+    return selectedMetadata(
+      runFailureMetadataFromCandidate(input.outerFailure, terminalFailedCandidate, input.thrownError),
+      failedStageIdsForCandidate(terminalFailedCandidate, failedStages),
+    );
+  }
+
+  const recoverableBlockedCandidate = candidates.find(isRecoverableActiveBlockedCandidate);
+  if (recoverableBlockedCandidate !== undefined && candidates.every(isRecoverableActiveBlockedCandidate)) {
+    return selectedMetadata(
+      runFailureMetadataFromCandidate(input.outerFailure, recoverableBlockedCandidate, input.thrownError),
+      failedStageIds,
+    );
+  }
+
+  return selectedMetadata(runFailureMetadata(input.outerFailure, input.stages), failedStageIds);
+}
+
+export function stageReplayFields(stage: StageSnapshot): Partial<Pick<StageSnapshot, "replayKey" | "replayedFromStageId" | "replayed">> {
+  return {
+    ...(stage.replayKey !== undefined ? { replayKey: stage.replayKey } : {}),
+    ...(stage.replayedFromStageId !== undefined ? { replayedFromStageId: stage.replayedFromStageId } : {}),
+    ...(stage.replayed !== undefined ? { replayed: stage.replayed } : {}),
+  };
+}
+
+export function finalizeKilled(
+  runId: string,
+  runSnapshot: RunSnapshot,
+  activeStore: Store,
+  persistence: WorkflowPersistencePort | undefined,
+  onRunEnd: RunOpts["onRunEnd"],
+): RunResult {
+  const errorMessage = "workflow killed";
+  const metadata = {
+    failureKind: "cancelled" as const,
+    failureCode: "cancelled" as const,
+    failureRecoverability: "non_recoverable" as const,
+    failureDisposition: "terminal_killed" as const,
+    failureMessage: errorMessage,
+    resumable: false,
+  };
+  const recorded = activeStore.recordRunEnd(runId, "killed", undefined, errorMessage, metadata);
+  appendRunEndWhenRecorded(persistence, recorded, {
+    runId,
+    status: "killed",
+    error: errorMessage,
+    ...metadata,
+    ts: Date.now(),
+  });
+  return reconcileTerminalRunResult(runId, runSnapshot, activeStore, { status: "killed", error: errorMessage }, onRunEnd);
+}
+
+export function finalizeKilledByFailure(
+  runId: string,
+  runSnapshot: RunSnapshot,
+  activeStore: Store,
+  persistence: WorkflowPersistencePort | undefined,
+  onRunEnd: RunOpts["onRunEnd"],
+  metadata: RunFailureMetadata,
+): RunResult {
+  const recorded = activeStore.recordRunEnd(runId, "killed", undefined, metadata.errorMessage, metadata);
+  appendRunEndWhenRecorded(persistence, recorded, {
+    runId,
+    status: "killed",
+    error: metadata.errorMessage,
+    failureKind: metadata.failureKind,
+    ...(metadata.failureCode !== undefined ? { failureCode: metadata.failureCode } : {}),
+    ...(metadata.failureRecoverability !== undefined ? { failureRecoverability: metadata.failureRecoverability } : {}),
+    ...(metadata.failureDisposition !== undefined ? { failureDisposition: metadata.failureDisposition } : {}),
+    failureMessage: metadata.failureMessage,
+    ...(metadata.failedStageId !== undefined ? { failedStageId: metadata.failedStageId } : {}),
+    resumable: false,
+    ...(metadata.retryAfterMs !== undefined ? { retryAfterMs: metadata.retryAfterMs } : {}),
+    ts: Date.now(),
+  });
+  return reconcileTerminalRunResult(runId, runSnapshot, activeStore, { status: "killed", error: metadata.errorMessage }, onRunEnd);
+}
+
+export function recordActiveBlockedFailure(
+  runId: string,
+  runSnapshot: RunSnapshot,
+  activeStore: Store,
+  persistence: WorkflowPersistencePort | undefined,
+  metadata: RunFailureMetadata & { readonly failureRecoverability: "recoverable"; readonly failedStageId: string },
+): RunResult {
+  const blockedAt = Date.now();
+  const recorded = activeStore.recordRunBlocked(runId, metadata.errorMessage, {
+    failureKind: metadata.failureKind,
+    ...(metadata.failureCode !== undefined ? { failureCode: metadata.failureCode } : {}),
+    failureRecoverability: "recoverable",
+    ...(metadata.failureDisposition !== undefined ? { failureDisposition: metadata.failureDisposition } : {}),
+    failureMessage: metadata.failureMessage,
+    failedStageId: metadata.failedStageId,
+    resumable: true,
+    ...(metadata.retryAfterMs !== undefined ? { retryAfterMs: metadata.retryAfterMs } : {}),
+    blockedAt,
+  });
+  if (recorded && persistence !== undefined) {
+    appendRunBlocked(persistence, {
+      runId,
+      failedStageId: metadata.failedStageId,
+      error: metadata.errorMessage,
+      failureKind: metadata.failureKind,
+      ...(metadata.failureCode !== undefined ? { failureCode: metadata.failureCode } : {}),
+      failureMessage: metadata.failureMessage,
+      failureRecoverability: "recoverable",
+      ...(metadata.failureDisposition !== undefined ? { failureDisposition: metadata.failureDisposition } : {}),
+      ...(metadata.retryAfterMs !== undefined ? { retryAfterMs: metadata.retryAfterMs } : {}),
+      resumable: true,
+      ts: blockedAt,
+    });
+  }
+  return {
+    runId,
+    status: "running",
+    error: metadata.errorMessage,
+    stages: [...runSnapshot.stages],
+  };
+}

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

@@ -0,0 +1,160 @@
+import { Value } from "typebox/value";
+import type {
+  WorkflowDefinition,
+  WorkflowOutputSchema,
+  WorkflowOutputValues,
+  WorkflowSerializableValue,
+} from "../../shared/types.js";
+import { schemaChoices, schemaFieldKind, schemaIsRequired } from "../../shared/schema-introspection.js";
+import {
+  assertWorkflowSerializableObject,
+  WORKFLOW_SERIALIZABLE_DESCRIPTION,
+  workflowSerializableTypeName,
+  workflowSerializableValidationError,
+} from "../../shared/serializable.js";
+import type { WorkflowExitOutputSnapshot } from "./executor-abort.js";
+import {
+  isWorkflowExitSnapshotInvalidValue,
+  workflowExitSnapshotInvalidValueMessage,
+} from "./executor-abort.js";
+
+function hasOwnWorkflowOutput(record: WorkflowOutputValues | Readonly<Record<string, WorkflowOutputSchema>>, key: string): boolean {
+  return Object.prototype.hasOwnProperty.call(record, key);
+}
+
+function assertWorkflowOutputsExplicit(
+  scope: string,
+  sourceOutput: WorkflowOutputValues,
+  declarations: Readonly<Record<string, WorkflowOutputSchema>>,
+  missingOutputSuffix = "",
+): void {
+  for (const key of Object.keys(sourceOutput)) {
+    if (!hasOwnWorkflowOutput(declarations, key)) {
+      throw new Error(
+        `atomic-workflows: ${scope} returned undeclared output "${key}"; declare it in outputs: { "${key}": Type.... } or remove it from the .run() return`,
+      );
+    }
+  }
+  for (const [key, schema] of Object.entries(declarations)) {
+    if (!(key in sourceOutput)) {
+      if (schemaIsRequired(schema)) {
+        throw new Error(`atomic-workflows: ${scope} missing output "${key}"${missingOutputSuffix}`);
+      }
+      continue;
+    }
+    const value = sourceOutput[key];
+    const kind = schemaFieldKind(schema);
+    if (!Value.Check(schema, value)) {
+      const choices = schemaChoices(schema);
+      if (kind === "select" && choices !== undefined && typeof value === "string") {
+        throw new Error(
+          `atomic-workflows: ${scope} output "${key}" must be one of [${choices.join(", ")}], got ${JSON.stringify(value)}`,
+        );
+      }
+      throw new Error(
+        `atomic-workflows: ${scope} output "${key}" expected ${kind}, got ${workflowSerializableTypeName(value)}`,
+      );
+    }
+    const serializableError = workflowSerializableValidationError(value, `${scope} output "${key}"`);
+    if (serializableError !== undefined) throw new Error(`atomic-workflows: ${serializableError}`);
+  }
+}
+
+function normalizeWorkflowOutputObject(
+  workflowName: string,
+  rawOutput: unknown,
+  label: string,
+): WorkflowOutputValues | undefined {
+  if (rawOutput === undefined) return undefined;
+  const normalized = rawOutput !== null && typeof rawOutput === "object" && !Array.isArray(rawOutput)
+    ? Object.fromEntries(Object.entries(rawOutput as Record<string, unknown>).filter(([, v]) => v !== undefined))
+    : rawOutput;
+  assertWorkflowSerializableObject(normalized, `workflow "${workflowName}" ${label}`);
+  return normalized;
+}
+
+export function normalizeWorkflowRunOutput(
+  workflowName: string,
+  rawOutput: unknown,
+): WorkflowOutputValues | undefined {
+  return normalizeWorkflowOutputObject(workflowName, rawOutput, ".run() return");
+}
+
+export function normalizeWorkflowExitOutput(
+  workflowName: string,
+  snapshot: WorkflowExitOutputSnapshot | undefined,
+): WorkflowOutputValues | undefined {
+  if (snapshot === undefined) return undefined;
+  if (!snapshot.ok) throw snapshot.error;
+  if (isWorkflowExitSnapshotInvalidValue(snapshot.value)) {
+    const invalidMessage = workflowExitSnapshotInvalidValueMessage(
+      `workflow "${workflowName}" ctx.exit() outputs`,
+      snapshot.value,
+    );
+    throw new Error(`atomic-workflows: ${invalidMessage ?? `workflow "${workflowName}" ctx.exit() outputs must be ${WORKFLOW_SERIALIZABLE_DESCRIPTION}, got object`}`);
+  }
+  return normalizeWorkflowOutputObject(workflowName, snapshot.value, "ctx.exit() outputs");
+}
+
+export function assertWorkflowRunOutputs(
+  workflowName: string,
+  result: WorkflowOutputValues | undefined,
+  declaredOutputs: Readonly<Record<string, WorkflowOutputSchema>> | undefined,
+): void {
+  assertWorkflowOutputsExplicit(
+    `workflow "${workflowName}"`,
+    result ?? {},
+    declaredOutputs ?? {},
+  );
+}
+
+export function assertWorkflowExitOutputs(
+  workflowName: string,
+  result: WorkflowOutputValues | undefined,
+  declaredOutputs: Readonly<Record<string, WorkflowOutputSchema>> | undefined,
+): void {
+  const declarations = declaredOutputs ?? {};
+  const sourceOutput = result ?? {};
+  const scope = `workflow "${workflowName}" ctx.exit()`;
+  for (const key of Object.keys(sourceOutput)) {
+    if (!hasOwnWorkflowOutput(declarations, key)) {
+      throw new Error(
+        `atomic-workflows: ${scope} provided undeclared output "${key}"; declare it in outputs: { "${key}": Type.... } or remove it from ctx.exit({ outputs })`,
+      );
+    }
+  }
+  for (const [key, schema] of Object.entries(declarations)) {
+    if (!(key in sourceOutput)) continue;
+    const value = sourceOutput[key];
+    const invalidSnapshotValue = workflowExitSnapshotInvalidValueMessage(`${scope} output "${key}"`, value);
+    if (invalidSnapshotValue !== undefined) throw new Error(`atomic-workflows: ${invalidSnapshotValue}`);
+    const kind = schemaFieldKind(schema);
+    if (!Value.Check(schema, value)) {
+      const choices = schemaChoices(schema);
+      if (kind === "select" && choices !== undefined && typeof value === "string") {
+        throw new Error(
+          `atomic-workflows: ${scope} output "${key}" must be one of [${choices.join(", ")}], got ${JSON.stringify(value)}`,
+        );
+      }
+      throw new Error(
+        `atomic-workflows: ${scope} output "${key}" expected ${kind}, got ${workflowSerializableTypeName(value)}`,
+      );
+    }
+    const serializableError = workflowSerializableValidationError(value, `${scope} output "${key}"`);
+    if (serializableError !== undefined) throw new Error(`atomic-workflows: ${serializableError}`);
+  }
+}
+
+export function selectWorkflowOutputs(
+  child: WorkflowDefinition,
+  rawOutput: WorkflowOutputValues | undefined,
+): WorkflowOutputValues {
+  const declarations = child.outputs ?? {};
+  const sourceOutput = rawOutput ?? {};
+  const selected: Record<string, WorkflowSerializableValue> = {};
+  for (const key of Object.keys(declarations)) {
+    const value = sourceOutput[key];
+    if (value !== undefined) selected[key] = value;
+  }
+  return selected;
+}