@bastani/atomic 0.8.31-alpha.4 → 0.9.0-alpha.1

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

@@ -0,0 +1,195 @@
+import type { StageSnapshot } from "../../shared/store-types.js";
+import type { WorkflowExitOptions } from "../../shared/types.js";
+import type { WorkflowExitCleanup } from "./executor-types.js";
+import { workflowSerializableTypeName } from "../../shared/serializable.js";
+import {
+  captureWorkflowExitOutputSnapshot,
+  describeWorkflowExitOptionValue,
+  findWorkflowExitSignal,
+  freezeWorkflowExitOutputSnapshot,
+  isWorkflowExitStatus,
+  makeWorkflowExitSignal,
+  parentWorkflowExitAbortReason,
+  readWorkflowExitOption,
+  type WorkflowExitSignal,
+} from "./executor-abort.js";
+
+export interface WorkflowExitAbortReason {
+  readonly reason?: string;
+}
+
+export interface WorkflowExitManager {
+  readonly exitScope: symbol;
+  getSelectedExit(): WorkflowExitSignal | undefined;
+  currentWorkflowExitAbortReason(): WorkflowExitAbortReason | undefined;
+  workflowExitSkippedReason(reason?: string): string;
+  isWorkflowExitSkippedReason(reason: string | undefined): boolean;
+  preserveWorkflowExitSkippedReason(stage: StageSnapshot, fallback: string): void;
+  registerWorkflowExitCleanup(stageId: string, cleanup: WorkflowExitCleanup): () => void;
+  runWorkflowExitCleanups(reason?: string): void;
+  drainWorkflowExitCleanups(reason?: string): Promise<void>;
+  throwIfWorkflowExitSelected(): void;
+  exit(options?: WorkflowExitOptions): never;
+}
+
+export function createWorkflowExitManager(input: {
+  readonly runId: string;
+  readonly exitScope: symbol;
+  readonly controller: AbortController;
+}): WorkflowExitManager {
+  let selectedExit: WorkflowExitSignal | undefined;
+  const exitCleanups = new Map<string, WorkflowExitCleanup>();
+  const workflowExitCleanupPromises = new Set<Promise<void>>();
+
+  const workflowExitSkippedReason = (reason?: string): string =>
+    reason === undefined || reason.length === 0 ? "workflow-exit" : `workflow-exit: ${reason}`;
+  const isWorkflowExitSkippedReason = (reason: string | undefined): boolean =>
+    reason === "workflow-exit" || reason?.startsWith("workflow-exit: ") === true;
+  const currentWorkflowExitAbortReason = (): WorkflowExitAbortReason | undefined => {
+    const scopedExit = selectedExit ?? findWorkflowExitSignal(input.controller.signal.reason, input.exitScope);
+    if (scopedExit !== undefined) {
+      return scopedExit.reason === undefined ? {} : { reason: scopedExit.reason };
+    }
+    const parentExit = parentWorkflowExitAbortReason(input.controller.signal.reason);
+    if (parentExit !== undefined) {
+      return parentExit.workflowExitReason === undefined ? {} : { reason: parentExit.workflowExitReason };
+    }
+    return undefined;
+  };
+  const preserveWorkflowExitSkippedReason = (stage: StageSnapshot, fallback: string): void => {
+    if (isWorkflowExitSkippedReason(stage.skippedReason)) return;
+    const workflowExitAbort = currentWorkflowExitAbortReason();
+    stage.skippedReason = workflowExitAbort !== undefined
+      ? workflowExitSkippedReason(workflowExitAbort.reason)
+      : fallback;
+  };
+  const trackWorkflowExitCleanup = (operation: void | Promise<void>): void => {
+    if (operation === undefined) return;
+    let tracked: Promise<void>;
+    tracked = Promise.resolve(operation)
+      .catch(() => {
+        // Cleanup is best-effort and must never convert ctx.exit into failure.
+      })
+      .finally(() => {
+        workflowExitCleanupPromises.delete(tracked);
+      });
+    workflowExitCleanupPromises.add(tracked);
+  };
+  const invokeWorkflowExitCleanup = (cleanup: WorkflowExitCleanup, reason?: string): void => {
+    try {
+      trackWorkflowExitCleanup(cleanup.skipForWorkflowExit(reason));
+    } catch (err) {
+      trackWorkflowExitCleanup(Promise.reject(err));
+    }
+  };
+  const registerWorkflowExitCleanup = (stageId: string, cleanup: WorkflowExitCleanup): (() => void) => {
+    if (selectedExit !== undefined) {
+      invokeWorkflowExitCleanup(cleanup, selectedExit.reason);
+      return () => undefined;
+    }
+    exitCleanups.set(stageId, cleanup);
+    return () => {
+      if (exitCleanups.get(stageId) === cleanup) exitCleanups.delete(stageId);
+    };
+  };
+  const runWorkflowExitCleanups = (reason?: string): void => {
+    for (const cleanup of [...exitCleanups.values()]) invokeWorkflowExitCleanup(cleanup, reason);
+  };
+  const drainWorkflowExitCleanups = async (reason?: string): Promise<void> => {
+    runWorkflowExitCleanups(reason);
+    while (workflowExitCleanupPromises.size > 0) {
+      await Promise.all([...workflowExitCleanupPromises]);
+    }
+  };
+  const throwIfWorkflowExitSelected = (): void => {
+    if (selectedExit !== undefined) {
+      if (!input.controller.signal.aborted) input.controller.abort(selectedExit);
+      runWorkflowExitCleanups(selectedExit.reason);
+      throw selectedExit;
+    }
+    if (input.controller.signal.aborted) {
+      throw input.controller.signal.reason ?? new DOMException("workflow killed", "AbortError");
+    }
+  };
+
+  const exit = (options?: WorkflowExitOptions): never => {
+    if (selectedExit !== undefined) {
+      if (!input.controller.signal.aborted) input.controller.abort(selectedExit);
+      runWorkflowExitCleanups(selectedExit.reason);
+      throw selectedExit;
+    }
+    if (input.controller.signal.aborted) {
+      throw input.controller.signal.reason ?? new DOMException("workflow killed", "AbortError");
+    }
+
+    const throwNestedSelectedExit = (): void => {
+      if (selectedExit === undefined) return;
+      if (!input.controller.signal.aborted) input.controller.abort(selectedExit);
+      runWorkflowExitCleanups(selectedExit.reason);
+      throw selectedExit;
+    };
+    const rawOptions = options as Pick<WorkflowExitOptions, "status" | "reason" | "outputs"> | null | undefined;
+    let validationError: Error | undefined;
+    const captureValidationError = (error: Error): void => {
+      validationError ??= error;
+    };
+
+    const statusRead = readWorkflowExitOption(rawOptions, "status");
+    throwNestedSelectedExit();
+    const rawStatus = statusRead.ok ? statusRead.value ?? "completed" : "completed";
+    if (!statusRead.ok) {
+      captureValidationError(statusRead.error);
+    } else if (!isWorkflowExitStatus(rawStatus)) {
+      captureValidationError(new TypeError(
+        `atomic-workflows: ctx.exit() status must be one of completed, skipped, cancelled, blocked; got ${describeWorkflowExitOptionValue(rawStatus)}`,
+      ));
+    }
+    const status = isWorkflowExitStatus(rawStatus) ? rawStatus : "completed";
+
+    const reasonRead = readWorkflowExitOption(rawOptions, "reason");
+    throwNestedSelectedExit();
+    const rawReason = reasonRead.ok ? reasonRead.value : undefined;
+    if (!reasonRead.ok) {
+      captureValidationError(reasonRead.error);
+    } else if (rawReason !== undefined && typeof rawReason !== "string") {
+      captureValidationError(new TypeError(
+        `atomic-workflows: ctx.exit() reason must be a string when provided; got ${workflowSerializableTypeName(rawReason)}`,
+      ));
+    }
+    const reason = typeof rawReason === "string" ? rawReason : undefined;
+
+    const outputsRead = readWorkflowExitOption(rawOptions, "outputs");
+    throwNestedSelectedExit();
+    const outputSnapshot = !outputsRead.ok
+      ? freezeWorkflowExitOutputSnapshot({ ok: false, error: outputsRead.error })
+      : outputsRead.value !== undefined
+        ? captureWorkflowExitOutputSnapshot(outputsRead.value)
+        : undefined;
+    throwNestedSelectedExit();
+
+    selectedExit = Object.freeze(makeWorkflowExitSignal({
+      scope: input.exitScope,
+      status,
+      ...(reason !== undefined ? { reason } : {}),
+      ...(outputSnapshot !== undefined ? { outputSnapshot } : {}),
+      ...(validationError !== undefined ? { validationError } : {}),
+    }));
+    input.controller.abort(selectedExit);
+    runWorkflowExitCleanups(reason);
+    throw selectedExit;
+  };
+
+  return {
+    exitScope: input.exitScope,
+    getSelectedExit: () => selectedExit,
+    currentWorkflowExitAbortReason,
+    workflowExitSkippedReason,
+    isWorkflowExitSkippedReason,
+    preserveWorkflowExitSkippedReason,
+    registerWorkflowExitCleanup,
+    runWorkflowExitCleanups,
+    drainWorkflowExitCleanups,
+    throwIfWorkflowExitSelected,
+    exit,
+  };
+}

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

@@ -0,0 +1,368 @@
+import { createHash } from "node:crypto";
+import { createAskUserQuestionToolDefinition } from "@bastani/atomic";
+import { stageUiBroker } from "../../shared/stage-ui-broker.js";
+import { buildStagePromptAdapter } from "../../shared/stage-prompt.js";
+import type {
+  WorkflowCustomUiFactory,
+  WorkflowCustomUiOptions,
+  WorkflowUIAdapter,
+  WorkflowUIContext,
+} from "../../shared/types.js";
+import type { PendingPrompt, CustomPromptIdentitySource } from "../../shared/store-types.js";
+import { selectPromptCallsiteFrame } from "../shared/prompt-callsite.js";
+
+export type PrimitivePromptDescriptor =
+  | { readonly kind: "input"; readonly message: string; readonly initial?: string }
+  | { readonly kind: "confirm"; readonly message: string }
+  | { readonly kind: "select"; readonly message: string; readonly choices: readonly string[] }
+  | { readonly kind: "editor"; readonly message: string; readonly initial?: string };
+
+export interface CustomPromptDescriptor<T> {
+  readonly kind: "custom";
+  readonly message: string;
+  readonly factory: WorkflowCustomUiFactory<T>;
+  readonly options?: WorkflowCustomUiOptions;
+  readonly customIdentityHash: string;
+  readonly customIdentitySource: CustomPromptIdentitySource;
+}
+
+export type PromptDescriptor<T = unknown> = PrimitivePromptDescriptor | CustomPromptDescriptor<T>;
+
+export function isCustomPromptDescriptor<T>(descriptor: PromptDescriptor<T>): descriptor is CustomPromptDescriptor<T> {
+  return descriptor.kind === "custom";
+}
+
+export function fallbackForPromptDescriptor(descriptor: PrimitivePromptDescriptor): unknown {
+  switch (descriptor.kind) {
+    case "input":
+    case "editor":
+      return descriptor.initial ?? "";
+    case "confirm":
+      return false;
+    case "select":
+      return descriptor.choices[0] ?? "";
+  }
+}
+
+export function makePrompt(descriptor: PromptDescriptor): PendingPrompt {
+  return {
+    id: `hil-${crypto.randomUUID()}`,
+    kind: descriptor.kind,
+    message: descriptor.message,
+    ...(!isCustomPromptDescriptor(descriptor) && descriptor.kind === "select" ? { choices: descriptor.choices } : {}),
+    ...(!isCustomPromptDescriptor(descriptor) && (descriptor.kind === "input" || descriptor.kind === "editor") && descriptor.initial !== undefined ? { initial: descriptor.initial } : {}),
+    ...(isCustomPromptDescriptor(descriptor) ? {
+      customIdentityHash: descriptor.customIdentityHash,
+      customIdentitySource: descriptor.customIdentitySource,
+    } : {}),
+    createdAt: Date.now(),
+  };
+}
+
+function stableHash(value: unknown): string {
+  return createHash("sha256").update(JSON.stringify(value)).digest("hex").slice(0, 32);
+}
+
+function promptDescriptorHash(descriptor: PromptDescriptor): string {
+  if (isCustomPromptDescriptor(descriptor)) {
+    return stableHash({
+      kind: "custom",
+      customIdentityHash: descriptor.customIdentityHash,
+    });
+  }
+  return stableHash({
+    kind: descriptor.kind,
+    message: descriptor.message,
+    choices: descriptor.kind === "select" ? descriptor.choices : [],
+    initial: descriptor.kind === "input" || descriptor.kind === "editor" ? descriptor.initial ?? null : null,
+  });
+}
+
+export function promptReplayKey(descriptor: PromptDescriptor): string {
+  return `prompt:${descriptor.kind}:${promptDescriptorHash(descriptor)}:${promptCallsiteHash()}`;
+}
+
+function promptCallsiteHash(): string {
+  const frame = selectPromptCallsiteFrame(new Error().stack ?? "") ?? "unknown";
+  return stableHash(frame);
+}
+
+export function hilAbortError(signal: AbortSignal): Error {
+  return signal.reason instanceof Error
+    ? signal.reason
+    : new Error("atomic-workflows: HIL aborted");
+}
+
+function resolveCustomPromptIdentity<T>(
+  factory: WorkflowCustomUiFactory<T>,
+  options: WorkflowCustomUiOptions | undefined,
+): Pick<CustomPromptDescriptor<T>, "customIdentityHash" | "customIdentitySource"> {
+  const replayIdentity = options?.replayIdentity?.trim();
+  if (replayIdentity !== undefined && replayIdentity.length > 0) {
+    return {
+      customIdentityHash: stableHash({ source: "caller", value: replayIdentity }),
+      customIdentitySource: "caller",
+    };
+  }
+  if (factory.name.trim().length > 0) {
+    return {
+      customIdentityHash: stableHash({ source: "factory", value: factory.name }),
+      customIdentitySource: "factory",
+    };
+  }
+  try {
+    const source = Function.prototype.toString.call(factory);
+    if (source.trim().length > 0) {
+      return {
+        customIdentityHash: stableHash({ source: "factory", value: source }),
+        customIdentitySource: "factory",
+      };
+    }
+  } catch {
+    // Fall through to callsite-only identity below.
+  }
+  return {
+    customIdentityHash: stableHash({ source: "callsite" }),
+    customIdentitySource: "callsite",
+  };
+}
+
+export function customPromptDescriptor<T>(
+  factory: WorkflowCustomUiFactory<T>,
+  options: WorkflowCustomUiOptions | undefined,
+): CustomPromptDescriptor<T> {
+  const label = options?.label?.trim();
+  return {
+    kind: "custom",
+    message: label && label.length > 0 ? label : "Custom TUI prompt",
+    factory,
+    ...(options !== undefined ? { options } : {}),
+    ...resolveCustomPromptIdentity(factory, options),
+  };
+}
+
+export interface MergedHilSignal {
+  readonly signal: AbortSignal;
+  readonly dispose: () => void;
+}
+
+export function mergeHilSignals(primary: AbortSignal, secondary: AbortSignal | undefined): MergedHilSignal {
+  if (secondary === undefined) return { signal: primary, dispose: () => undefined };
+  const controller = new AbortController();
+  const abortFrom = (source: AbortSignal): void => {
+    if (!controller.signal.aborted) controller.abort(source.reason);
+  };
+  const onPrimaryAbort = (): void => abortFrom(primary);
+  const onSecondaryAbort = (): void => abortFrom(secondary);
+  primary.addEventListener("abort", onPrimaryAbort, { once: true });
+  secondary.addEventListener("abort", onSecondaryAbort, { once: true });
+  if (primary.aborted) abortFrom(primary);
+  else if (secondary.aborted) abortFrom(secondary);
+  return {
+    signal: controller.signal,
+    dispose: () => {
+      primary.removeEventListener("abort", onPrimaryAbort);
+      secondary.removeEventListener("abort", onSecondaryAbort);
+    },
+  };
+}
+
+function makeRejectingUIContext(msg: (primitive: string) => string): WorkflowUIContext {
+  return {
+    input: () => Promise.reject(new Error(msg("input"))),
+    confirm: () => Promise.reject(new Error(msg("confirm"))),
+    select: () => Promise.reject(new Error(msg("select"))),
+    editor: () => Promise.reject(new Error(msg("editor"))),
+    custom: () => Promise.reject(new Error(msg("custom"))),
+  };
+}
+
+function makeUnavailableUIContext(): WorkflowUIContext {
+  return makeRejectingUIContext(
+    (primitive) =>
+      `atomic-workflows: HIL ctx.ui.${primitive} is unavailable because Atomic runtime did not provide a UI adapter`,
+  );
+}
+
+export function makeHeadlessUnavailableUIContext(): WorkflowUIContext {
+  return makeRejectingUIContext(
+    (primitive) =>
+      `atomic-workflows: interactive ctx.ui.${primitive} is unavailable in headless (non-interactive) mode; run the workflow in interactive mode or remove the interactive prompt from this stage`,
+  );
+}
+
+export function normalizeUIContext(adapter: WorkflowUIAdapter | undefined): WorkflowUIContext {
+  const unavailable = makeUnavailableUIContext();
+  if (adapter === undefined) return unavailable;
+  return {
+    input(prompt) {
+      return typeof adapter.input === "function"
+        ? adapter.input.call(adapter, prompt)
+        : unavailable.input(prompt);
+    },
+    confirm(message) {
+      return typeof adapter.confirm === "function"
+        ? adapter.confirm.call(adapter, message)
+        : unavailable.confirm(message);
+    },
+    select<T extends string>(message: string, options: readonly T[]): Promise<T> {
+      return typeof adapter.select === "function"
+        ? adapter.select.call(adapter, message, options) as Promise<T>
+        : unavailable.select(message, options);
+    },
+    editor(initial) {
+      return typeof adapter.editor === "function"
+        ? adapter.editor.call(adapter, initial)
+        : unavailable.editor(initial);
+    },
+    custom<T>(factory: WorkflowCustomUiFactory<T>, options?: WorkflowCustomUiOptions): Promise<T> {
+      return typeof adapter.custom === "function"
+        ? adapter.custom.call(adapter, factory, options) as Promise<T>
+        : unavailable.custom(factory, options);
+    },
+  };
+}
+
+type AskUserQuestionToolEvent =
+  | { phase: "start"; callId?: string; args?: unknown }
+  | { phase: "end"; callId?: string; nameMatched: boolean };
+
+function stringField(value: Record<string, unknown>, keys: readonly string[]): string | undefined {
+  for (const key of keys) {
+    const candidate = value[key];
+    if (typeof candidate === "string" && candidate.length > 0) return candidate;
+  }
+  return undefined;
+}
+
+function isAskUserQuestionToolName(name: string | undefined): boolean {
+  if (name === undefined) return false;
+  return name.toLowerCase().replace(/[^a-z0-9]/g, "") === "askuserquestion";
+}
+
+export function askUserQuestionToolEvent(event: unknown): AskUserQuestionToolEvent | undefined {
+  if (event === null || typeof event !== "object") return undefined;
+  const record = event as Record<string, unknown>;
+  const type = typeof record["type"] === "string" ? record["type"] : "";
+  const toolName = stringField(record, ["toolName", "tool_name", "name"]);
+  const callId = stringField(record, ["toolCallId", "tool_call_id", "toolUseId", "tool_use_id", "id"]);
+
+  if (type === "tool_execution_start" && isAskUserQuestionToolName(toolName)) {
+    return { phase: "start", callId, args: record["args"] };
+  }
+  if (type === "tool_execution_end" || type === "tool_execution_error" || type === "tool_result") {
+    return { phase: "end", callId, nameMatched: isAskUserQuestionToolName(toolName) };
+  }
+  return undefined;
+}
+
+export const READINESS_GATE_ADVANCE_LABEL = "I'm ready to move on to the next workflow stage.";
+
+const READINESS_GATE_ADVANCE_NORMALIZED = READINESS_GATE_ADVANCE_LABEL.trim().toLowerCase();
+
+export const READINESS_GATE_QUESTION_PARAMS = {
+  questions: [
+    {
+      question: "Any additional points to explore before moving on?",
+      header: "Continue?",
+      options: [
+        {
+          label: READINESS_GATE_ADVANCE_LABEL,
+          description: "Complete this stage and advance the workflow.",
+        },
+        {
+          label: "I have more to explore or ask about.",
+          description: "Stay in this stage and keep working in the chat composer.",
+        },
+      ],
+    },
+  ],
+};
+
+export function readinessResultMeansAdvance(result: unknown): boolean {
+  if (result === null || typeof result !== "object") return false;
+  const details = (result as {
+    details?: {
+      answers?: ReadonlyArray<{ answer?: unknown; selected?: ReadonlyArray<unknown> }>;
+      cancelled?: boolean;
+    };
+  }).details;
+  if (details === undefined || details.cancelled === true) return false;
+  const first = details.answers?.[0];
+  if (first === undefined) return false;
+  const candidates: unknown[] = [first.answer];
+  if (Array.isArray(first.selected)) candidates.push(...first.selected);
+  return candidates.some(
+    (candidate) =>
+      typeof candidate === "string" &&
+      candidate.trim().toLowerCase() === READINESS_GATE_ADVANCE_NORMALIZED,
+  );
+}
+
+export function toolResultHasChatAnswer(result: unknown): boolean {
+  if (result === null || typeof result !== "object") return false;
+  const details = (result as Record<string, unknown>)["details"];
+  if (details === null || typeof details !== "object") return false;
+  const answers = (details as Record<string, unknown>)["answers"];
+  if (!Array.isArray(answers)) return false;
+  return answers.some(
+    (a) => a !== null && typeof a === "object" && (a as Record<string, unknown>)["kind"] === "chat",
+  );
+}
+
+export const RESUME_CONTINUATION_PROMPT = "Continue where you left off.";
+
+export function shouldInjectResumeContinuation(state: {
+  readonly resumeOccurred: boolean;
+  readonly gateEnabled: boolean;
+  readonly aborted: boolean;
+}): boolean {
+  return state.resumeOccurred && state.gateEnabled && !state.aborted;
+}
+
+let cachedReadinessGateTool: ReturnType<typeof createAskUserQuestionToolDefinition> | undefined;
+function readinessGateTool(): ReturnType<typeof createAskUserQuestionToolDefinition> {
+  return (cachedReadinessGateTool ??= createAskUserQuestionToolDefinition());
+}
+
+export async function askReadinessViaStageBroker(
+  runId: string,
+  stageId: string,
+  signal: AbortSignal,
+): Promise<"advance" | "stay"> {
+  const execute = readinessGateTool().execute;
+  if (execute === undefined) return "advance";
+  const gateContext = {
+    hasUI: true,
+    ui: {
+      custom: (factory: unknown, options?: unknown): Promise<unknown> =>
+        stageUiBroker.requestCustomUi(
+          runId,
+          stageId,
+          factory as Parameters<typeof stageUiBroker.requestCustomUi>[2],
+          options as Parameters<typeof stageUiBroker.requestCustomUi>[3],
+          signal,
+        ),
+    },
+  };
+  const gatePromptId = `readiness-gate-${stageId}-${crypto.randomUUID()}`;
+  const gateAdapter = buildStagePromptAdapter(
+    gatePromptId,
+    "readiness_gate",
+    READINESS_GATE_QUESTION_PARAMS,
+    Date.now(),
+  );
+  if (gateAdapter) stageUiBroker.provideStagePrompt(runId, stageId, gateAdapter);
+  try {
+    const result = await execute(
+      gatePromptId,
+      READINESS_GATE_QUESTION_PARAMS as Parameters<typeof execute>[1],
+      signal,
+      undefined,
+      gateContext as unknown as Parameters<typeof execute>[4],
+    );
+    return readinessResultMeansAdvance(result) ? "advance" : "stay";
+  } finally {
+    stageUiBroker.clearStagePrompt(runId, stageId);
+  }
+}

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

@@ -0,0 +1,83 @@
+import { Type, type TSchema } from "typebox";
+import { Value } from "typebox/value";
+import type { WorkflowDefinition, WorkflowInputSchema, StageOptions, WorkflowSerializableValue } from "../../shared/types.js";
+import { schemaFieldKind, schemaIsRequired } from "../../shared/schema-introspection.js";
+import { validateInputs, type ValidationError } from "../shared/validate-inputs.js";
+import type { ResolvedInputs } from "./executor-types.js";
+
+export function resolveInputs(
+  schema: Readonly<Record<string, WorkflowInputSchema>>,
+  provided: Readonly<Record<string, unknown>>,
+): ResolvedInputs {
+  const resolved: Record<string, WorkflowSerializableValue> = {};
+  for (const [key, value] of Object.entries(provided)) {
+    if (value !== undefined) resolved[key] = value as WorkflowSerializableValue;
+  }
+
+  const withDefaults = Value.Default(
+    Type.Object(schema as Record<string, TSchema>, { additionalProperties: true }),
+    resolved,
+  ) as Record<string, WorkflowSerializableValue>;
+  for (const [key, value] of Object.entries(withDefaults)) {
+    if (value !== undefined) resolved[key] = value;
+  }
+
+  for (const [key, schemaDef] of Object.entries(schema)) {
+    if (schemaIsRequired(schemaDef) && resolved[key] === undefined) {
+      throw new TypeError(`atomic-workflows: required input "${key}" not provided`);
+    }
+  }
+
+  return resolved;
+}
+
+export function resolveInputConcurrency(
+  schema: Readonly<Record<string, WorkflowInputSchema>>,
+  resolvedInputs: ResolvedInputs,
+): number | undefined {
+  const concurrencySchema = schema["max_concurrency"];
+  if (concurrencySchema === undefined || schemaFieldKind(concurrencySchema) !== "number") {
+    return undefined;
+  }
+
+  const value = resolvedInputs["max_concurrency"];
+  if (typeof value !== "number" || !Number.isFinite(value) || value < 1) return undefined;
+
+  return Math.floor(value);
+}
+
+export function resolveInputRuntimeDefaults(
+  def: Pick<WorkflowDefinition, "inputBindings">,
+  resolvedInputs: ResolvedInputs,
+): Partial<StageOptions> {
+  const defaults: Partial<StageOptions> = {};
+  const worktree = def.inputBindings?.worktree;
+  if (worktree !== undefined) {
+    const gitWorktreeDir = resolvedInputs[worktree.gitWorktreeDir];
+    if (typeof gitWorktreeDir === "string" && gitWorktreeDir.trim().length > 0) {
+      defaults.gitWorktreeDir = gitWorktreeDir;
+      const baseBranch = worktree.baseBranch === undefined ? undefined : resolvedInputs[worktree.baseBranch];
+      if (typeof baseBranch === "string") defaults.baseBranch = baseBranch;
+    }
+  }
+  return defaults;
+}
+
+function formatValidationErrors(errors: readonly ValidationError[]): string {
+  return errors.map((error) => `  - ${error.key}: ${error.reason}`).join("\n");
+}
+
+export function resolveAndValidateInputs(
+  schema: Readonly<Record<string, WorkflowInputSchema>>,
+  provided: Readonly<Record<string, unknown>>,
+  scope: string,
+): ResolvedInputs {
+  const resolved = resolveInputs(schema, provided);
+  const errors = validateInputs(schema, resolved);
+  if (errors.length > 0) {
+    throw new TypeError(
+      `atomic-workflows: invalid inputs for ${scope}:\n${formatValidationErrors(errors)}`,
+    );
+  }
+  return resolved;
+}