@bastani/atomic 0.9.16-alpha.2 → 0.9.16-alpha.3

package/dist/builtin/workflows/src/shared/authoring-contract-ui.ts

@@ -1,437 +0,0 @@
-/** Workflow authoring UI, builder, run, and result contract types. */
-
-import type { KeybindingsManager, Theme } from "@bastani/atomic";
-import type { Component, OverlayHandle, OverlayOptions, TUI } from "@earendil-works/pi-tui";
-import type { TSchema } from "typebox";
-import type {
-	RunStatus,
-	StageAdapters,
-	StageContext,
-	StageOptions,
-	WorkflowAction,
-	WorkflowActor,
-	WorkflowArtifact,
-	WorkflowChainOptions,
-	WorkflowChildResult,
-	WorkflowContextMode,
-	WorkflowDetailsMode,
-	WorkflowDetailsStatus,
-	WorkflowExecutionMode,
-	WorkflowExitOptions,
-	WorkflowInputSchemaMap,
-	WorkflowInputValues,
-	WorkflowMcpPort,
-	WorkflowModelCatalogPort,
-	WorkflowOutputSchemaMap,
-	WorkflowOutputValues,
-	WorkflowParallelOptions,
-	WorkflowPersistencePort,
-	WorkflowRunChildArgs,
-	WorkflowSerializableObject,
-	WorkflowSerializableValue,
-	WorkflowTaskOptions,
-	WorkflowTaskResult,
-	WorkflowTaskStep,
-} from "./authoring-contract-stage.js";
-import type { EffectiveBudget, WorkflowBudget } from "./budget.js";
-
-export type WorkflowCustomUiComponent = Component & { dispose?(): void };
-export type WorkflowCustomUiTui = TUI;
-export type WorkflowCustomUiTheme = Theme;
-export type WorkflowCustomUiKeybindings = KeybindingsManager;
-export type WorkflowCustomUiOverlayOptions = OverlayOptions;
-export type WorkflowCustomUiOverlayHandle = OverlayHandle;
-
-export type WorkflowCustomUiFactory<T> = (
-	tui: TUI,
-	theme: Theme,
-	keybindings: KeybindingsManager,
-	done: (value: T) => void,
-) => WorkflowCustomUiComponent | Promise<WorkflowCustomUiComponent>;
-
-export interface WorkflowCustomUiOptions {
-	/**
-	 * Ask the host to render as an overlay. Workflow graph hosts accept this: the
-	 * attached stage chat mounts the widget on its ordinary custom-UI slot, which
-	 * already keeps the stage transcript visible behind it, instead of opening a
-	 * nested overlay above the graph chrome.
-	 */
-	readonly overlay?: boolean;
-	/** AbortSignal to programmatically dismiss the custom UI. */
-	readonly signal?: AbortSignal;
-	/** Overlay positioning/sizing options. Can be static or a function for dynamic updates. */
-	readonly overlayOptions?: OverlayOptions | (() => OverlayOptions);
-	/** Called with the real overlay handle after an overlay is shown. */
-	readonly onHandle?: (handle: OverlayHandle) => void;
-	/**
-	 * Workflow-only replay identity. Recommended whenever widget state or
-	 * semantics can change without the callsite changing. Do not include secrets;
-	 * the runtime stores only a hash.
-	 */
-	readonly replayIdentity?: string;
-	/** Safe display-only label for graph/status surfaces. Defaults to "Custom TUI prompt". Not part of replay identity. */
-	readonly label?: string;
-}
-
-export interface WorkflowUIContext {
-	input(prompt: string): Promise<string>;
-	confirm(message: string): Promise<boolean>;
-	select<T extends string>(message: string, options: readonly T[]): Promise<T>;
-	editor(initial?: string): Promise<string>;
-	custom<T>(factory: WorkflowCustomUiFactory<T>, options?: WorkflowCustomUiOptions): Promise<T>;
-}
-
-export interface WorkflowUIAdapter {
-	input(prompt: string): Promise<string>;
-	confirm(message: string): Promise<boolean>;
-	select<T extends string>(message: string, options: readonly T[]): Promise<T>;
-	editor(initial?: string): Promise<string>;
-	custom?<T>(factory: WorkflowCustomUiFactory<T>, options?: WorkflowCustomUiOptions): Promise<T>;
-}
-
-export interface WorkflowRunContext<
-	TInputs extends WorkflowInputValues = WorkflowInputValues,
-	TDefinitionBrand extends object = Record<never, never>,
-	TOutputs extends WorkflowOutputValues = WorkflowOutputValues,
-> {
-	readonly inputs: Readonly<TInputs>;
-	/** Stable owning workflow-run id for durable run-scoped artifacts. */
-	readonly runId?: string;
-	readonly cwd?: string;
-	exit(options?: WorkflowExitOptions<TOutputs>): never;
-	stage<TSchemaDef extends TSchema>(
-		name: string,
-		options: StageOptions<TSchemaDef> & { readonly schema: TSchemaDef },
-	): StageContext<TSchemaDef>;
-	stage(name: string, options?: StageOptions): StageContext;
-	task(name: string, options: WorkflowTaskOptions): Promise<WorkflowTaskResult>;
-	chain(steps: readonly WorkflowTaskStep[], options?: WorkflowChainOptions): Promise<WorkflowTaskResult[]>;
-	parallel(steps: readonly WorkflowTaskStep[], options?: WorkflowParallelOptions): Promise<WorkflowTaskResult[]>;
-	workflow<
-		TChildInputs extends WorkflowInputValues,
-		TChildOutputs extends WorkflowOutputValues,
-		TChildRunInputs extends WorkflowInputValues = TChildInputs,
-	>(
-		definition: WorkflowDefinition<TChildInputs, TChildOutputs, TChildRunInputs> & TDefinitionBrand,
-		...args: WorkflowRunChildArgs<TChildRunInputs>
-	): Promise<WorkflowChildResult<TChildOutputs>>;
-	readonly ui: WorkflowUIContext;
-	/**
-	 * Durable cached tool execution. Runs arbitrary TypeScript code and caches
-	 * the result durably so completed side effects are not repeated on resume.
-	 * Only `ctx.*` blocks (tool, ui, stage, task, chain, parallel, workflow)
-	 * produce durable checkpoints.
-	 *
-	 * cross-ref: issue #1498 — DBOS-backed cross-session resumability.
-	 */
-	tool: WorkflowToolPrimitive;
-}
-
-/** Serializable process details copied from an exhausted `ctx.tool` callback error. */
-export interface WorkflowToolError extends WorkflowSerializableObject {
-	readonly name: string;
-	readonly message: string;
-	readonly exitCode?: number;
-	readonly stdout?: string;
-	readonly stderr?: string;
-}
-
-export interface WorkflowToolSuccess<TValue extends WorkflowSerializableValue> extends WorkflowSerializableObject {
-	readonly ok: true;
-	readonly value: TValue;
-	readonly attempts: number;
-	readonly cached: boolean;
-}
-
-export interface WorkflowToolFailure extends WorkflowSerializableObject {
-	readonly ok: false;
-	readonly error: WorkflowToolError;
-	readonly attempts: number;
-	readonly cached: boolean;
-}
-
-/** Typed result returned when `failureMode: "return"` is selected. */
-export type WorkflowToolOutcome<TValue extends WorkflowSerializableValue> =
-	| WorkflowToolSuccess<TValue>
-	| WorkflowToolFailure;
-
-/** Options for `ctx.tool`. Throwing after exhausted retries remains the default. */
-export interface WorkflowToolOptions {
-	readonly failureMode?: "throw" | "return";
-	readonly retriesAllowed?: boolean;
-	readonly maxAttempts?: number;
-	readonly intervalMs?: number;
-	readonly backoffRate?: number;
-	/** Maximum duration in milliseconds for each callback attempt. */
-	readonly timeoutMs?: number;
-}
-
-export type WorkflowToolReturnOptions = WorkflowToolOptions & { readonly failureMode: "return" };
-export type WorkflowToolThrowOptions = WorkflowToolOptions & { readonly failureMode?: "throw" };
-
-/**
- * Cancellation handle handed to every `ctx.tool` callback.
- *
- * The signal aborts when the run is cancelled, when the run is gracefully quit,
- * or when this single tool node is aborted through `/workflow quit|interrupt`
- * with the node's id or name. Callbacks that forward it to `fetch`, a child
- * process, or a network client unblock promptly; callbacks that ignore it are
- * abandoned after a bounded wait.
- */
-export interface WorkflowToolContext {
-	readonly signal: AbortSignal;
-}
-
-/** `ctx.tool` runs an async function and durably caches its serializable result. */
-export interface WorkflowToolPrimitive {
-	<TValue extends WorkflowSerializableValue>(
-		name: string,
-		args: Readonly<Record<string, WorkflowSerializableValue>>,
-		fn: (toolCtx: WorkflowToolContext) => Promise<TValue>,
-		options: WorkflowToolReturnOptions,
-	): Promise<WorkflowToolOutcome<TValue>>;
-	<TValue extends WorkflowSerializableValue>(
-		name: string,
-		args: Readonly<Record<string, WorkflowSerializableValue>>,
-		fn: (toolCtx: WorkflowToolContext) => Promise<TValue>,
-		options?: WorkflowToolThrowOptions,
-	): Promise<TValue>;
-	<TValue extends WorkflowSerializableValue>(
-		name: string,
-		args: Readonly<Record<string, WorkflowSerializableValue>>,
-		fn: (toolCtx: WorkflowToolContext) => Promise<TValue>,
-		options?: WorkflowToolOptions,
-	): Promise<TValue | WorkflowToolOutcome<TValue>>;
-}
-
-export type WorkflowRunFn<
-	TInputs extends WorkflowInputValues = WorkflowInputValues,
-	TOutputs extends WorkflowOutputValues = WorkflowOutputValues,
-	TDefinitionBrand extends object = Record<never, never>,
-> = (ctx: WorkflowRunContext<TInputs, TDefinitionBrand, TOutputs>) => Promise<TOutputs> | TOutputs;
-
-export interface WorkflowRuntimeConfig {
-	readonly maxDepth: number;
-	readonly defaultConcurrency: number;
-	readonly persistRuns: boolean;
-	readonly statusFile: boolean;
-	readonly statusFilePath?: string;
-	readonly resumeInFlight: "ask" | "auto" | "never";
-	/** Resolved default budget for workflow runs. */
-	readonly budget?: EffectiveBudget;
-	readonly worktree?: {
-		readonly symlinkDirectories: readonly string[];
-	};
-}
-
-export interface WorkflowWorktreeInputBinding {
-	readonly gitWorktreeDir: string;
-	readonly baseBranch?: string;
-}
-
-export interface WorkflowInputBindings {
-	readonly worktree?: WorkflowWorktreeInputBinding;
-}
-
-export interface WorkflowDefinition<
-	TInputs extends WorkflowInputValues = WorkflowInputValues,
-	TOutputs extends WorkflowOutputValues = WorkflowOutputValues,
-	TRunInputs extends WorkflowInputValues = TInputs,
-	TDefinitionBrand extends object = Record<never, never>,
-> {
-	readonly __piWorkflow: true;
-	readonly __runInputs?: TRunInputs;
-	readonly name: string;
-	readonly normalizedName: string;
-	readonly description: string;
-	readonly autoAttach?: true;
-	readonly heartbeatIntervalMinutes: number;
-	/** Optional budget declaration resolved when this workflow runs. */
-	readonly budget?: WorkflowBudget;
-	readonly inputs: WorkflowInputSchemaMap;
-	readonly outputs?: WorkflowOutputSchemaMap;
-	readonly inputBindings?: WorkflowInputBindings;
-	run(ctx: WorkflowRunContext<TInputs, TDefinitionBrand, TOutputs>): Promise<TOutputs> | TOutputs;
-}
-
-export type NoExtraOutputs<TDeclared extends WorkflowOutputValues, TActual extends TDeclared> = TActual &
-	Record<Exclude<keyof TActual, keyof TDeclared>, never>;
-
-export interface WorkflowOverlayAdapter extends WorkflowSerializableObject {}
-export interface RunSnapshot extends WorkflowSerializableObject {}
-export interface ActiveRunEntry {
-	readonly controller: AbortController;
-	readonly children: readonly AbortController[];
-}
-
-export interface CancellationRegistry {
-	register(runId: string, controller: AbortController): void;
-	registerChild(runId: string, controller: AbortController): void;
-	abort(runId: string, reason?: unknown): boolean;
-	abortAll(reason?: unknown): number;
-	unregister(runId: string): void;
-	isAborted(runId: string): boolean;
-}
-
-export interface RunContinuationOpts {
-	readonly source: RunSnapshot;
-	readonly resumeFromStageId: string;
-}
-
-export interface WorkflowParentRunLink {
-	readonly runId: string;
-	readonly stageId: string;
-	readonly rootRunId: string;
-}
-
-export interface RunOpts {
-	readonly adapters?: StageAdapters;
-	readonly cwd?: string;
-	readonly ui?: WorkflowUIAdapter;
-	readonly executionMode?: WorkflowExecutionMode;
-	readonly usePromptNodesForUi?: boolean;
-	readonly confirmStageReadiness?: (request: {
-		readonly runId: string;
-		readonly stageId: string;
-		readonly stageName: string;
-		readonly signal: AbortSignal;
-	}) => Promise<boolean>;
-	readonly store?: object;
-	readonly persistence?: WorkflowPersistencePort;
-	readonly mcp?: WorkflowMcpPort;
-	readonly cancellation?: CancellationRegistry;
-	readonly overlay?: WorkflowOverlayAdapter;
-	readonly signal?: AbortSignal;
-	readonly deferWorkflowStart?: boolean;
-	readonly config?: WorkflowRuntimeConfig;
-	/** Per-run budget override. Each field resolves over definition and config values. */
-	readonly budget?: WorkflowBudget;
-	readonly models?: WorkflowModelCatalogPort;
-	readonly registry?: object;
-	readonly depth?: number;
-	readonly stageControlRegistry?: object;
-	readonly toolControlRegistry?: object;
-	readonly toolAdmissionBoundary?: object;
-	readonly runId?: string;
-	readonly continuation?: RunContinuationOpts;
-	/** Who launched this run. A continuation inherits its source run's origin instead. */
-	readonly origin?: WorkflowActor;
-	/** Who requested the resume that produced this continuation run. */
-	readonly resumeActor?: WorkflowActor;
-	readonly parentRun?: WorkflowParentRunLink;
-	readonly onRunStart?: (snapshot: RunSnapshot) => void;
-	readonly onStageStart?: (runId: string, snapshot: StageSnapshot) => void;
-	readonly onStageEnd?: (runId: string, snapshot: StageSnapshot) => unknown;
-	readonly onRunEnd?: (
-		runId: string,
-		status: RunStatus,
-		result?: WorkflowOutputValues,
-		error?: string,
-		exitReason?: string,
-	) => void;
-}
-
-export interface WorkflowProgressSummary extends WorkflowSerializableObject {
-	readonly completed?: number;
-	readonly total?: number;
-}
-
-export interface WorkflowControlEvent extends WorkflowSerializableObject {
-	readonly type?: "notify" | "needs_attention" | "interrupted" | "resumed";
-	readonly message?: string;
-}
-
-export interface WorkflowIntercomSummary extends WorkflowSerializableObject {
-	readonly enabled?: boolean;
-	readonly delivery?: "off" | "notify" | "result" | "control-and-result";
-	readonly parentSession?: string;
-}
-
-export interface WorkflowDetails extends WorkflowSerializableObject {
-	readonly mode: WorkflowDetailsMode;
-	readonly action?: WorkflowAction;
-	readonly runId?: string;
-	readonly status: WorkflowDetailsStatus;
-	readonly context?: WorkflowContextMode;
-	readonly results?: readonly WorkflowTaskResult[];
-	readonly output?: WorkflowOutputValues;
-	readonly progress?: WorkflowProgressSummary;
-	readonly artifacts?: readonly WorkflowArtifact[];
-	readonly controlEvents?: readonly WorkflowControlEvent[];
-	readonly intercom?: WorkflowIntercomSummary;
-	readonly warnings?: readonly string[];
-	/** Actionable user guidance for accepted background execution. */
-	readonly message?: string;
-	readonly error?: string;
-	/** True when the run reached its terminal status through ctx.exit(). */
-	readonly exited?: boolean;
-	readonly exitReason?: string;
-}
-
-export type StageStatus = RunStatus | "skipped" | "awaiting_input" | "blocked";
-
-export interface StageSnapshot extends WorkflowSerializableObject {
-	readonly id: string;
-	readonly name: string;
-	readonly status: StageStatus;
-	readonly result?: WorkflowSerializableValue;
-	readonly error?: string;
-}
-
-export interface ToolNodeSnapshot extends WorkflowSerializableObject {
-	readonly kind: "tool";
-	/** Stable durable node identity. */
-	readonly id: string;
-	readonly name: string;
-	/** Exact invocation arguments retained for read-only graph inspection. */
-	readonly args?: Readonly<Record<string, WorkflowSerializableValue>>;
-	readonly argsHash: string;
-	readonly ordinal: number;
-	readonly parentIds: readonly string[];
-	readonly status: "pending" | "running" | "completed" | "failed" | "cached" | "cancelled";
-	readonly topologyState?: "unavailable";
-	readonly replayed?: boolean;
-	readonly executionOrder?: number;
-	readonly startedAt?: number;
-	readonly endedAt?: number;
-	readonly durationMs?: number;
-	/** Full serializable callback result, when one was retained. */
-	readonly result?: WorkflowSerializableValue;
-	/** Callback source captured from `fn.toString()` at registration. */
-	readonly source?: string;
-	readonly resultSummary?: string;
-	readonly error?: string;
-	readonly attachable: false;
-}
-
-export interface RunResult<TOutputs extends WorkflowOutputValues = WorkflowOutputValues>
-	extends WorkflowSerializableObject {
-	readonly runId: string;
-	readonly status: RunStatus;
-	readonly result?: Partial<TOutputs>;
-	readonly error?: string;
-	/** Tool node whose rejection supplied the selected terminal failure. */
-	readonly failedToolNodeId?: string;
-	/** True when the run reached its terminal status through ctx.exit(). */
-	readonly exited?: boolean;
-	readonly exitReason?: string;
-	readonly stages: readonly StageSnapshot[];
-	/** Always populated by the runtime; optional for legacy structural literals. */
-	readonly toolNodes?: readonly ToolNodeSnapshot[];
-}
-
-export type ResolvedInputs<TInputs extends WorkflowInputValues = WorkflowInputValues> = Readonly<TInputs> &
-	WorkflowSerializableObject;
-
-export interface GitWorktreeSetupOptions extends WorkflowSerializableObject {
-	readonly gitWorktreeDir: string;
-	readonly baseBranch?: string;
-	readonly cwd: string;
-}
-
-export interface GitWorktreeSetupResult extends WorkflowSerializableObject {
-	readonly worktreeRoot: string;
-	readonly cwd: string;
-	readonly repositoryRoot: string;
-	readonly created: boolean;
-}

package/dist/builtin/workflows/src/shared/budget-meter.ts

@@ -1,34 +0,0 @@
-import { fold_usage } from "../../builtin/verification-usage.js";
-import type { RunSnapshot } from "./store-types.js";
-import { elapsedRunMs } from "./timing.js";
-export type RunMeterCounters = Readonly<Record<"input" | "output" | "cacheRead" | "cacheWrite", number>>;
-export type RunMeters = Readonly<{ durationMs: number; tokens: number; cost: number; perCounter: RunMeterCounters }>;
-/** A run and its nested child scopes, used by the tree-wide usage meter. */
-export type RunUsageTree =
-	| { readonly run: RunSnapshot; readonly children?: readonly RunUsageTree[] }
-	| (RunSnapshot & { readonly children?: readonly RunUsageTree[] });
-type UsageCounters = RunMeterCounters & { readonly cost: number };
-const usageFields = ["input", "output", "cacheRead", "cacheWrite", "cost"] as const;
-const addUsage = (left: UsageCounters, right: UsageCounters): UsageCounters =>
-	Object.fromEntries(usageFields.map((field) => [field, left[field] + right[field]])) as unknown as UsageCounters;
-function foldTreeUsage(tree: RunUsageTree): UsageCounters {
-	const run = "run" in tree ? tree.run : tree;
-	const folded = fold_usage(
-		run.stages
-			.filter((stage) => stage.replayed !== true)
-			.map((stage) => ({ stageName: stage.name, text: stage.result ?? "", modelAttempts: stage.modelAttempts })),
-	);
-	return (tree.children ?? []).reduce<UsageCounters>((total, child) => addUsage(total, foldTreeUsage(child)), folded);
-}
-/** Measure one run scope without mutating it or charging a budget. */
-export function meter_run(tree: RunUsageTree, now: number): RunMeters {
-	const usage = foldTreeUsage(tree);
-	return {
-		durationMs: elapsedRunMs("run" in tree ? tree.run : tree, now),
-		tokens: usage.input + usage.output,
-		cost: usage.cost,
-		perCounter: Object.fromEntries(
-			usageFields.filter((field) => field !== "cost").map((field) => [field, usage[field]]),
-		) as RunMeterCounters,
-	};
-}

package/dist/builtin/workflows/src/shared/budget.d.ts

@@ -1,67 +0,0 @@
-/** Pure workflow run-budget declarations and resolution. */
-export type BudgetDimension = "duration" | "tokens" | "cost";
-export interface BudgetReport {
-    readonly dimension: BudgetDimension;
-    readonly reading: number;
-    readonly ceiling: number;
-    readonly percent: number;
-}
-export type DurationBudgetReport = BudgetReport & {
-    readonly dimension: "duration";
-};
-export type UsageBudgetReport = BudgetReport & {
-    readonly dimension: "tokens" | "cost";
-};
-export interface WorkflowBudget {
-    readonly maxDurationMs?: number;
-    readonly maxTokens?: number;
-    readonly maxCost?: number;
-    readonly warnAtPercent?: number;
-}
-export type DurationBudgetCheck = {
-    readonly kind: "continue";
-    readonly report: DurationBudgetReport;
-    readonly warning: boolean;
-} | {
-    readonly kind: "exhausted";
-    readonly report: DurationBudgetReport;
-};
-export declare function enforceDurationBudget(reading: number, budget: EffectiveBudget, options?: {
-    readonly warned?: boolean;
-}): DurationBudgetCheck;
-export type UsageBudgetCheck = {
-    readonly kind: "continue";
-    readonly report: UsageBudgetReport;
-    readonly warning: boolean;
-} | {
-    readonly kind: "exhausted";
-    readonly report: UsageBudgetReport;
-};
-export declare function enforceUsageBudget(dimension: "tokens" | "cost", reading: number, ceiling: number, warnAtPercent: number, options?: {
-    readonly warned?: boolean;
-}): UsageBudgetCheck;
-/** A fully resolved budget. Create one only with {@link resolve_budget}. */
-declare class ResolvedWorkflowBudget {
-    private readonly brand;
-    readonly maxDurationMs: number;
-    readonly maxTokens: number;
-    readonly maxCost: number;
-    readonly warnAtPercent: number;
-    private constructor();
-    static resolve(layers: ResolveBudgetLayers): ResolvedWorkflowBudget;
-}
-/** A validated, fully resolved workflow budget. */
-export type EffectiveBudget = ResolvedWorkflowBudget;
-/** Budget declarations in precedence order: run > definition > config. */
-export interface ResolveBudgetLayers {
-    readonly config?: WorkflowBudget;
-    readonly definition?: WorkflowBudget;
-    readonly run?: WorkflowBudget;
-}
-/** Return a reason when a budget declaration is invalid. */
-export declare function validateWorkflowBudget(value: unknown, label?: string): string | null;
-/** Reject an invalid optional budget declaration. */
-export declare function assertWorkflowBudget(value: WorkflowBudget | undefined, label?: string): void;
-/** Resolve budget declarations, with later layers winning independently per field. */
-export declare function resolve_budget(layers: ResolveBudgetLayers): EffectiveBudget;
-export {};

package/dist/builtin/workflows/src/shared/budget.ts

@@ -1,127 +0,0 @@
-/** Pure workflow run-budget declarations and resolution. */
-
-export type BudgetDimension = "duration" | "tokens" | "cost";
-export interface BudgetReport {
-	readonly dimension: BudgetDimension;
-	readonly reading: number;
-	readonly ceiling: number;
-	readonly percent: number;
-}
-export type DurationBudgetReport = BudgetReport & { readonly dimension: "duration" };
-export type UsageBudgetReport = BudgetReport & { readonly dimension: "tokens" | "cost" };
-export interface WorkflowBudget {
-	readonly maxDurationMs?: number;
-	readonly maxTokens?: number;
-	readonly maxCost?: number;
-	readonly warnAtPercent?: number;
-}
-
-export type DurationBudgetCheck =
-	| { readonly kind: "continue"; readonly report: DurationBudgetReport; readonly warning: boolean }
-	| { readonly kind: "exhausted"; readonly report: DurationBudgetReport };
-export function enforceDurationBudget(
-	reading: number,
-	budget: EffectiveBudget,
-	options: { readonly warned?: boolean } = {},
-): DurationBudgetCheck {
-	const ceiling = budget.maxDurationMs;
-	const report: DurationBudgetReport = {
-		dimension: "duration",
-		reading,
-		ceiling,
-		percent: ceiling === 0 ? 0 : (reading / ceiling) * 100,
-	};
-	if (ceiling > 0 && reading >= ceiling) return { kind: "exhausted", report };
-	const warning = options.warned !== true && budget.warnAtPercent > 0 && report.percent >= budget.warnAtPercent;
-	return { kind: "continue", report, warning };
-}
-export type UsageBudgetCheck =
-	| { readonly kind: "continue"; readonly report: UsageBudgetReport; readonly warning: boolean }
-	| { readonly kind: "exhausted"; readonly report: UsageBudgetReport };
-export function enforceUsageBudget(
-	dimension: "tokens" | "cost",
-	reading: number,
-	ceiling: number,
-	warnAtPercent: number,
-	options: { readonly warned?: boolean } = {},
-): UsageBudgetCheck {
-	const report: UsageBudgetReport = { dimension, reading, ceiling, percent: ceiling ? (reading / ceiling) * 100 : 0 };
-	if (ceiling > 0 && reading >= ceiling) return { kind: "exhausted", report };
-	const warning = options.warned !== true && warnAtPercent > 0 && report.percent >= warnAtPercent;
-	return { kind: "continue", report, warning };
-}
-/** A fully resolved budget. Create one only with {@link resolve_budget}. */
-class ResolvedWorkflowBudget {
-	private declare readonly brand: undefined;
-	readonly maxDurationMs: number;
-	readonly maxTokens: number;
-	readonly maxCost: number;
-	readonly warnAtPercent: number;
-
-	private constructor(maxDurationMs: number, maxTokens: number, maxCost: number, warnAtPercent: number) {
-		this.maxDurationMs = maxDurationMs;
-		this.maxTokens = maxTokens;
-		this.maxCost = maxCost;
-		this.warnAtPercent = warnAtPercent;
-	}
-
-	static resolve(layers: ResolveBudgetLayers): ResolvedWorkflowBudget {
-		assertWorkflowBudget(layers.config, "config budget");
-		assertWorkflowBudget(layers.definition, "definition budget");
-		assertWorkflowBudget(layers.run, "run budget");
-
-		return new ResolvedWorkflowBudget(
-			layers.run?.maxDurationMs ?? layers.definition?.maxDurationMs ?? layers.config?.maxDurationMs ?? 0,
-			layers.run?.maxTokens ?? layers.definition?.maxTokens ?? layers.config?.maxTokens ?? 0,
-			layers.run?.maxCost ?? layers.definition?.maxCost ?? layers.config?.maxCost ?? 0,
-			layers.run?.warnAtPercent ?? layers.definition?.warnAtPercent ?? layers.config?.warnAtPercent ?? 80,
-		);
-	}
-}
-
-/** A validated, fully resolved workflow budget. */
-export type EffectiveBudget = ResolvedWorkflowBudget;
-
-/** Budget declarations in precedence order: run > definition > config. */
-export interface ResolveBudgetLayers {
-	readonly config?: WorkflowBudget;
-	readonly definition?: WorkflowBudget;
-	readonly run?: WorkflowBudget;
-}
-
-/** Return a reason when a budget declaration is invalid. */
-export function validateWorkflowBudget(value: unknown, label = "budget"): string | null {
-	if (value === null || typeof value !== "object" || Array.isArray(value)) {
-		return `"${label}" must be a JSON object, got ${JSON.stringify(typeof value)}`;
-	}
-
-	const budget = value as Record<string, unknown>;
-	for (const field of ["maxDurationMs", "maxTokens"] as const) {
-		const limit = budget[field];
-		if (
-			field in budget &&
-			(typeof limit !== "number" || !Number.isFinite(limit) || !Number.isInteger(limit) || limit < 0)
-		) {
-			return `"${label}.${field}" must be a non-negative finite integer, got ${JSON.stringify(limit)}`;
-		}
-	}
-	for (const field of ["maxCost", "warnAtPercent"] as const) {
-		const limit = budget[field];
-		if (field in budget && (typeof limit !== "number" || !Number.isFinite(limit) || limit < 0)) {
-			return `"${label}.${field}" must be a non-negative finite number, got ${JSON.stringify(limit)}`;
-		}
-	}
-	return null;
-}
-
-/** Reject an invalid optional budget declaration. */
-export function assertWorkflowBudget(value: WorkflowBudget | undefined, label = "budget"): void {
-	if (value === undefined) return;
-	const reason = validateWorkflowBudget(value, label);
-	if (reason !== null) throw new TypeError(reason);
-}
-
-/** Resolve budget declarations, with later layers winning independently per field. */
-export function resolve_budget(layers: ResolveBudgetLayers): EffectiveBudget {
-	return ResolvedWorkflowBudget.resolve(layers);
-}