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

package/dist/builtin/workflows/src/engine/primitives/workflow.ts

@@ -1,219 +0,0 @@
-import type { DurableChildInvocation } from "../../durable/boundary-topology.js";
-import {
-	findWorkflowExitSignal,
-	isWorkflowExitStatus,
-	makeParentWorkflowExitAbortReason,
-} from "../../runs/foreground/executor-abort.js";
-import {
-	isWorkflowDefinition,
-	workflowChildReplaySnapshot,
-	workflowDefinitionRequirementMessage,
-} from "../../runs/foreground/executor-child-helpers.js";
-import { resolveAndValidateInputs } from "../../runs/foreground/executor-inputs.js";
-import { selectWorkflowOutputs } from "../../runs/foreground/executor-outputs.js";
-import type { ResolvedInputs, RunOpts, RunResult } from "../../runs/foreground/executor-types.js";
-import type { WorkflowChildRunRef } from "../../shared/store-types.js";
-import type {
-	WorkflowChildResult,
-	WorkflowDefinition,
-	WorkflowInputValues,
-	WorkflowOutputValues,
-	WorkflowRunChildArgs,
-	WorkflowRunChildOptions,
-} from "../../shared/types.js";
-import type { EngineRuntime } from "../runtime.js";
-import {
-	findWorkflowGracefulQuit,
-	WORKFLOW_GRACEFUL_QUIT_EXIT_REASON,
-	WorkflowGracefulQuitError,
-} from "../workflow-tool-abort.js";
-
-export function createChildWorkflowRunner(input: {
-	readonly runtime: EngineRuntime;
-	readonly resolveWorkflowCwd: () => string;
-	readonly nextWorkflowBoundaryReplayKey: (name: string) => string;
-	/** Consume the identity prepared by the durable outer primitive. */
-	readonly consumeDurableInvocation?: () => DurableChildInvocation | undefined;
-	readonly runWorkflow: <TInputs extends WorkflowInputValues, TRunInputs extends WorkflowInputValues = TInputs>(
-		def: WorkflowDefinition<TInputs, WorkflowOutputValues, TRunInputs>,
-		inputs: ResolvedInputs,
-		opts?: RunOpts,
-	) => Promise<RunResult>;
-}): <
-	TChildInputs extends WorkflowInputValues,
-	TChildOutputs extends WorkflowOutputValues,
-	TChildRunInputs extends WorkflowInputValues = TChildInputs,
->(
-	child: WorkflowDefinition<TChildInputs, TChildOutputs, TChildRunInputs>,
-	...args: WorkflowRunChildArgs<TChildRunInputs>
-) => Promise<WorkflowChildResult<TChildOutputs>> {
-	return async <
-		TChildInputs extends WorkflowInputValues,
-		TChildOutputs extends WorkflowOutputValues,
-		TChildRunInputs extends WorkflowInputValues = TChildInputs,
-	>(
-		child: WorkflowDefinition<TChildInputs, TChildOutputs, TChildRunInputs>,
-		...args: WorkflowRunChildArgs<TChildRunInputs>
-	): Promise<WorkflowChildResult<TChildOutputs>> => {
-		const options: WorkflowRunChildOptions<TChildRunInputs> = args[0] ?? {};
-		const { runtime } = input;
-		runtime.exit.throwIfWorkflowExitSelected();
-		if (!isWorkflowDefinition(child))
-			throw new Error(workflowDefinitionRequirementMessage("ctx.workflow(definition)", child));
-		const childName = child.normalizedName;
-		const boundaryName = options.stageName ?? `workflow:${childName}`;
-		if (runtime.budget.enabled) await runtime.budget.stopAtBoundaryAsync(boundaryName);
-		const boundaryReplayKey = input.nextWorkflowBoundaryReplayKey(boundaryName);
-		const durableInvocation = input.consumeDurableInvocation?.();
-		const boundary = runtime.spawnStage(boundaryName, {
-			kind: "workflow-boundary",
-			replayKey: boundaryReplayKey,
-			...(durableInvocation !== undefined ? { identity: durableInvocation.identity } : {}),
-		}).boundary;
-		if (boundary.replayedChild !== undefined) {
-			durableInvocation?.adoptReplayedChildRunId(boundary.replayedChild.runId);
-		}
-		await durableInvocation?.recordStart(boundary.parentIds, boundary.sourceOrder);
-		let childRunId: string | undefined;
-		let detachParentAbort: (() => void) | undefined;
-		let childControllerForCleanup: AbortController | undefined;
-		try {
-			if (boundary.replayedChild !== undefined) {
-				await Promise.resolve();
-				runtime.exit.throwIfWorkflowExitSelected();
-				boundary.finalizeReplay();
-				await durableInvocation?.recordTerminal("completed", boundary.replayedChild);
-				return boundary.replayedChild as WorkflowChildResult<TChildOutputs>;
-			}
-
-			const childInputs = resolveAndValidateInputs(
-				child.inputs,
-				options.inputs ?? {},
-				`child workflow "${childName}" (${child.name})`,
-			);
-			runtime.exit.throwIfWorkflowExitSelected();
-
-			childRunId = durableInvocation?.identity.childRunId ?? crypto.randomUUID();
-			const childController = new AbortController();
-			childControllerForCleanup = childController;
-			const childRef: WorkflowChildRunRef = { alias: childName, workflow: child.normalizedName, runId: childRunId };
-			boundary.linkChildRun(childRef, childController);
-
-			const abortChildFromParent = (): void => {
-				const parentExit = findWorkflowExitSignal(runtime.signal.reason, runtime.exit.exitScope);
-				childController.abort(
-					parentExit !== undefined ? makeParentWorkflowExitAbortReason(parentExit.reason) : runtime.signal.reason,
-				);
-			};
-			if (runtime.signal.aborted) abortChildFromParent();
-			else {
-				runtime.signal.addEventListener("abort", abortChildFromParent, { once: true });
-				detachParentAbort = () => runtime.signal.removeEventListener("abort", abortChildFromParent);
-			}
-			runtime.exit.throwIfWorkflowExitSelected();
-			runtime.childRunOptions.cancellation?.register(childRunId, childController);
-			runtime.exit.throwIfWorkflowExitSelected();
-
-			// Ordering is intentional: linkChildRun happens before launch so parent
-			// cleanup can abort the child; observeChildRun happens immediately after
-			// promise creation, with no await in between, so cleanup can await teardown.
-			const childRunPromise = input.runWorkflow(child, childInputs, {
-				...runtime.childRunOptions,
-				runId: childRunId,
-				cwd: input.resolveWorkflowCwd(),
-				depth: runtime.depth + 1,
-				parentRun: {
-					runId: runtime.runId,
-					stageId: boundary.id,
-					rootRunId: runtime.parentRootRunId ?? runtime.runId,
-				},
-				signal: childController.signal,
-				budget: options.budget,
-				rootBudget: runtime.rootBudget,
-				deferWorkflowStart: false,
-				...(durableInvocation !== undefined ? { durableScope: durableInvocation.scope } : {}),
-			});
-			boundary.observeChildRun(childRunPromise);
-			const childRun = await childRunPromise;
-			if (runtime.budget.enabled) await runtime.budget.stopAtBoundaryAsync(boundaryName);
-			runtime.exit.throwIfWorkflowExitSelected();
-
-			// A gracefully quit child is a suspension, not a child failure: carry the
-			// quit up so the parent also suspends without a terminal boundary record.
-			if (
-				childRun.status === "paused" &&
-				childRun.exitReason === WORKFLOW_GRACEFUL_QUIT_EXIT_REASON &&
-				childRunId !== undefined
-			) {
-				throw new WorkflowGracefulQuitError(childRunId, `child workflow "${childName}" (${child.name})`);
-			}
-			const childBudgetExceeded = childRun.result?.status === "budget_exceeded";
-			const childExitStatus = isWorkflowExitStatus(childRun.status) ? childRun.status : "blocked";
-			if (
-				(!isWorkflowExitStatus(childRun.status) && !childBudgetExceeded) ||
-				(childRun.status === "failed" && childRun.exited !== true)
-			) {
-				const failedChildStage = childRun.stages.find((stage) => stage.failureKind !== undefined);
-				throw new Error(
-					`atomic-workflows: child workflow "${childName}" (${child.name}) failed with status ${childRun.status}${childRun.error !== undefined ? `: ${childRun.error}` : ""}`,
-					{
-						cause: {
-							...(failedChildStage?.failureKind !== undefined ? { code: failedChildStage.failureKind } : {}),
-							...(failedChildStage?.failureMessage !== undefined
-								? { message: failedChildStage.failureMessage }
-								: {}),
-						},
-					},
-				);
-			}
-
-			const outputs = selectWorkflowOutputs(child, childRun.result);
-			const childExited = childBudgetExceeded || childRun.exited === true || childRun.status !== "completed";
-			const childResult: WorkflowChildResult<TChildOutputs> = childExited
-				? {
-						workflow: child.normalizedName,
-						runId: childRun.runId,
-						status: childBudgetExceeded ? "blocked" : childExitStatus,
-						exited: true,
-						outputs: outputs as Partial<TChildOutputs>,
-						...(childRun.exitReason !== undefined ? { exitReason: childRun.exitReason } : {}),
-					}
-				: {
-						workflow: child.normalizedName,
-						runId: childRun.runId,
-						status: "completed",
-						exited: false,
-						outputs: outputs as TChildOutputs,
-					};
-			const workflowChild = workflowChildReplaySnapshot(childName, childResult);
-			const outputKeys = Object.keys(outputs);
-			boundary.complete(
-				`Workflow "${child.name}" ${childRun.status} (runId: ${childRun.runId}; outputs: ${outputKeys.length > 0 ? outputKeys.join(", ") : "(none)"})`,
-				workflowChild,
-			);
-			await durableInvocation?.recordTerminal("completed", childResult);
-			return childResult;
-		} catch (err) {
-			// Suspension leaves the boundary untouched: quit owns the paused record and
-			// a later resume replays this boundary instead of a failed child.
-			if (findWorkflowGracefulQuit(err) !== undefined) throw err;
-			const exit =
-				findWorkflowExitSignal(err, runtime.exit.exitScope) ??
-				findWorkflowExitSignal(runtime.signal.reason, runtime.exit.exitScope);
-			if (exit !== undefined) {
-				await boundary.skipForWorkflowExit(exit.reason);
-				await durableInvocation?.recordTerminal("skipped");
-				throw exit;
-			}
-			boundary.fail(err);
-			await durableInvocation?.recordTerminal("failed");
-			throw err;
-		} finally {
-			detachParentAbort?.();
-			// Identity-conditional: a stale child finalizer must not evict a newer
-			// registration that reused this child run id.
-			if (childRunId !== undefined && childControllerForCleanup !== undefined)
-				runtime.childRunOptions.cancellation?.unregister(childRunId, childControllerForCleanup);
-		}
-	};
-}

package/dist/builtin/workflows/src/engine/replay.ts

@@ -1,8 +0,0 @@
-export type {
-	ContinuationReplayDecision,
-	ContinuationReplayIndex,
-} from "../runs/foreground/executor-continuation.js";
-export {
-	createContinuationReplayIndex,
-	sameStringSet,
-} from "../runs/foreground/executor-continuation.js";

package/dist/builtin/workflows/src/engine/run-budget.ts

@@ -1,308 +0,0 @@
-import {
-	type BudgetReport,
-	type EffectiveBudget,
-	enforceDurationBudget,
-	enforceUsageBudget,
-} from "../shared/budget.js";
-import { meter_run, type RunMeters, type RunUsageTree } from "../shared/budget-meter.js";
-import type { RunBudgetAccountingState, RunBudgetState, RunSnapshot } from "../shared/store-types.js";
-import { elapsedRunMs } from "../shared/timing.js";
-import type { WorkflowModelUsage } from "../shared/types.js";
-export const BUDGET_WRAP_UP_PROMPT =
-	"The workflow budget is exhausted. Stop substantive work, summarize useful progress, identify remaining work or blockers, and leave a clear next step. Do not start any new stages.";
-export interface BudgetExceededReport extends BudgetReport {
-	readonly frontierStage: string;
-	readonly wrapUpSummary?: string;
-	readonly wrapUpUsage?: WorkflowModelUsage;
-}
-export class WorkflowBudgetExceededError extends Error {
-	readonly report: BudgetExceededReport;
-	constructor(report: BudgetExceededReport) {
-		const unit = report.dimension === "duration" ? "ms" : report.dimension;
-		super(
-			`atomic-workflows: ${report.dimension} budget exceeded (${report.reading}${unit} / ${report.ceiling}${unit}) at ${report.frontierStage}`,
-		);
-		this.name = "WorkflowBudgetExceededError";
-		this.report = report;
-	}
-}
-export interface BudgetCheckpointContinue {
-	readonly kind: "continue";
-}
-export interface BudgetCheckpointWarning {
-	readonly kind: "warn";
-	readonly report: BudgetReport;
-}
-export interface BudgetCheckpointWrapUp {
-	readonly kind: "wrap_up";
-	readonly report: BudgetReport;
-}
-export interface BudgetCheckpointExhausted {
-	readonly kind: "exhausted";
-	readonly report: BudgetExceededReport;
-}
-export type BudgetCheckpoint =
-	| BudgetCheckpointContinue
-	| BudgetCheckpointWarning
-	| BudgetCheckpointWrapUp
-	| BudgetCheckpointExhausted;
-export interface RunBudgetController {
-	readonly enabled: boolean;
-	readonly checkpoint: (frontierStage?: string) => BudgetCheckpoint;
-	readonly registerWrapUp: (frontierStage: string, handler: () => Promise<never>) => () => void;
-	readonly deliverWrapUp: (frontierStage: string) => Promise<never>;
-	readonly finishWrapUp: (
-		frontierStage: string | undefined,
-		summary?: string,
-		usage?: WorkflowModelUsage,
-		delivered?: boolean,
-	) => WorkflowBudgetExceededError;
-	readonly rethrowIfSystemOwnedStop: (frontierStage?: string) => void;
-	readonly stopAtBoundary: (frontierStage?: string) => void;
-	readonly stopAtBoundaryAsync: (frontierStage?: string) => Promise<void>;
-	readonly awaitPendingWrapUp: () => Promise<WorkflowBudgetExceededError | undefined>;
-}
-const withFrontier = (
-	report: BudgetReport,
-	frontierStage: string | undefined,
-	summary?: string,
-	usage?: WorkflowModelUsage,
-): BudgetExceededReport =>
-	Object.assign(
-		{ ...report, frontierStage: frontierStage ?? "workflow frontier" },
-		summary === undefined ? {} : { wrapUpSummary: summary },
-		usage === undefined ? {} : { wrapUpUsage: usage },
-	);
-const usageFields = ["input", "output", "cacheRead", "cacheWrite", "cost"] as const,
-	counterFields = ["input", "output", "cacheRead", "cacheWrite"] as const;
-const mapFields = <F extends string>(fields: readonly F[], fn: (field: F) => number = () => 0): Record<F, number> =>
-	Object.fromEntries(fields.map((field) => [field, fn(field)])) as Record<F, number>;
-export function createRunBudgetController(input: {
-	readonly run: RunSnapshot;
-	readonly budget: EffectiveBudget;
-	readonly usageTree?: () => RunUsageTree;
-	readonly onWarning?: (report: BudgetReport) => void;
-	readonly rootBudget?: RunBudgetController;
-}) {
-	const { run, budget } = input;
-	const ownEnabled = budget.maxDurationMs > 0 || budget.maxTokens > 0 || budget.maxCost > 0;
-	const usageEnabled = budget.maxTokens > 0 || budget.maxCost > 0;
-	const root = input.rootBudget?.enabled === true ? input.rootBudget : undefined;
-	const enabled = ownEnabled || root !== undefined;
-	let state: RunBudgetState | undefined = run.budgetState === undefined ? undefined : { ...run.budgetState };
-	const previousAccounting = state?.accounting;
-	const initial =
-		previousAccounting && usageEnabled ? meter_run(input.usageTree?.() ?? { run }, Date.now()) : undefined;
-	const initialAccounting = initial === undefined ? undefined : { ...initial.perCounter, cost: initial.cost };
-	let baseline = mapFields(usageFields, (field) => initialAccounting?.[field] ?? 0);
-	let charged: RunBudgetAccountingState = {
-		baseline,
-		tokens: previousAccounting?.tokens ?? 0,
-		cost: previousAccounting?.cost ?? 0,
-		perCounter: { ...(previousAccounting?.perCounter ?? mapFields(counterFields)) },
-	};
-	let exhaustedReport: BudgetReport | undefined;
-	let lastReports: readonly BudgetReport[] = [];
-	let wrapUpPromise: Promise<never> | undefined;
-	let rootWrapUpPending = false;
-	const handlers: Array<{ readonly frontierStage: string; readonly handler: () => Promise<never> }> = [];
-	const updateState = (patch: Partial<RunBudgetState>): void => {
-		state = { ...(state ?? {}), ...patch };
-		run.budgetState = state;
-	};
-	const accountUsage = (meters: RunMeters): RunMeters => {
-		const current = { ...meters.perCounter, cost: meters.cost };
-		const delta = mapFields(usageFields, (field) => Math.max(0, current[field] - baseline[field]));
-		baseline = mapFields(usageFields, (field) => Math.max(baseline[field], current[field]));
-		charged = {
-			baseline,
-			tokens: charged.tokens + delta.input + delta.output,
-			cost: charged.cost + delta.cost,
-			perCounter: mapFields(counterFields, (field) => charged.perCounter[field] + delta[field]),
-		};
-		updateState({ accounting: charged });
-		return Object.assign(meters, { tokens: charged.tokens, cost: charged.cost, perCounter: charged.perCounter });
-	};
-	const measure = (): RunMeters => {
-		const durationMs = elapsedRunMs(run);
-		if (!usageEnabled) return { durationMs, tokens: 0, cost: 0, perCounter: mapFields(counterFields) };
-		return { ...accountUsage(meter_run(input.usageTree?.() ?? { run }, Date.now())), durationMs };
-	};
-	const warningWasSent = (report: BudgetReport): boolean =>
-		report.dimension === "duration" ? state?.warned === true : state?.warnings?.[report.dimension] !== undefined;
-	const recordWarning = (report: BudgetReport): void => {
-		updateState({
-			...(report.dimension === "duration" ? { warned: true } : {}),
-			warning: report,
-			warnings: { ...(state?.warnings ?? {}), [report.dimension]: report },
-		});
-		input.onWarning?.(report);
-	};
-	const ceilings = { duration: budget.maxDurationMs, tokens: budget.maxTokens, cost: budget.maxCost };
-	const setReports = (reports: readonly BudgetReport[]): void => {
-		for (const report of reports) {
-			if (ceilings[report.dimension] <= 0) continue;
-			updateState({ [report.dimension]: report } as Partial<RunBudgetState>);
-		}
-	};
-	const finishWrapUp = (
-		frontierStage: string | undefined,
-		summary?: string,
-		usage?: WorkflowModelUsage,
-		delivered = true,
-	): WorkflowBudgetExceededError => {
-		updateState({
-			systemOwnedStop: true,
-			...(delivered ? { wrapUpDelivered: true, wrapUpCompleted: true } : {}),
-			...(delivered && summary !== undefined ? { wrapUpSummary: summary } : {}),
-			...(delivered && usage !== undefined ? { wrapUpUsage: usage } : {}),
-		});
-		const report =
-			exhaustedReport ??
-			lastReports[0] ??
-			state?.duration ??
-			state?.tokens ??
-			state?.cost ??
-			enforceDurationBudget(elapsedRunMs(run), budget).report;
-		setReports([report]);
-		return new WorkflowBudgetExceededError(
-			withFrontier(report, frontierStage, state?.wrapUpSummary, state?.wrapUpUsage),
-		);
-	};
-	const ownCheckpoint = (frontierStage?: string): BudgetCheckpoint => {
-		const usageCheck = (dimension: "tokens" | "cost", reading: number, ceiling: number, warned: boolean) =>
-			ceiling > 0 ? enforceUsageBudget(dimension, reading, ceiling, budget.warnAtPercent, { warned }) : undefined;
-		if (!ownEnabled) return { kind: "continue" };
-		const meters = measure();
-		const checks = [
-			enforceDurationBudget(meters.durationMs, budget, { warned: state?.warned }),
-			usageCheck("tokens", meters.tokens, budget.maxTokens, state?.warnings?.tokens !== undefined),
-			usageCheck("cost", meters.cost, budget.maxCost, state?.warnings?.cost !== undefined),
-		].filter((check): check is Exclude<typeof check, undefined> => check !== undefined);
-		lastReports = checks.map((check) => check.report);
-		setReports(lastReports);
-		let warning: BudgetReport | undefined;
-		for (const check of checks)
-			if (check.kind === "continue" && check.warning && !warningWasSent(check.report)) {
-				warning ??= check.report;
-				recordWarning(check.report);
-			}
-		const exhausted = checks.find((check) => check.kind === "exhausted");
-		if (exhausted === undefined)
-			return warning === undefined ? { kind: "continue" } : { kind: "warn", report: warning };
-		exhaustedReport ??= exhausted.report;
-		if (state?.wrapUpCompleted !== true) return { kind: "wrap_up", report: exhausted.report };
-		return {
-			kind: "exhausted",
-			report: withFrontier(exhaustedReport, frontierStage, state.wrapUpSummary, state.wrapUpUsage),
-		};
-	};
-	const boundaryCheckpoint = (
-		frontierStage?: string,
-	): { readonly check: BudgetCheckpoint; readonly owner?: RunBudgetController } => {
-		const rootCheck = root?.checkpoint(frontierStage);
-		if (rootCheck?.kind === "wrap_up") rootWrapUpPending = true;
-		if (rootCheck?.kind === "wrap_up" || rootCheck?.kind === "exhausted") return { check: rootCheck, owner: root };
-		return { check: ownCheckpoint(frontierStage) };
-	};
-	const checkpoint = (frontierStage?: string): BudgetCheckpoint => boundaryCheckpoint(frontierStage).check;
-	const finishBoundary = (owner: RunBudgetController | undefined, frontierStage: string | undefined): never => {
-		throw (
-			owner?.finishWrapUp(frontierStage, undefined, undefined, false) ??
-			finishWrapUp(frontierStage, undefined, undefined, false)
-		);
-	};
-	const deliverBoundary = (owner: RunBudgetController | undefined, frontierStage: string): void => {
-		void (owner?.deliverWrapUp(frontierStage) ?? deliverWrapUp(frontierStage));
-	};
-	const stopAtBoundary = (frontierStage?: string): void => {
-		const resolvedFrontierStage = frontierStage ?? handlers.at(-1)?.frontierStage;
-		const { check, owner } = boundaryCheckpoint(resolvedFrontierStage);
-		if (check.kind === "wrap_up") {
-			deliverBoundary(owner, resolvedFrontierStage ?? "workflow frontier");
-			finishBoundary(owner, resolvedFrontierStage);
-		}
-		if (check.kind === "exhausted") finishBoundary(owner, resolvedFrontierStage);
-	};
-	const rethrowIfSystemOwnedStop = (frontierStage?: string): void => {
-		root?.rethrowIfSystemOwnedStop(frontierStage);
-		if (state?.systemOwnedStop === true)
-			throw finishWrapUp(frontierStage, state.wrapUpSummary, state.wrapUpUsage, state.wrapUpCompleted === true);
-	};
-	const registerLocalWrapUp = (registration: {
-		readonly frontierStage: string;
-		readonly handler: () => Promise<never>;
-	}): (() => void) => {
-		handlers.push(registration);
-		return () => {
-			const index = handlers.indexOf(registration);
-			if (index >= 0) handlers.splice(index, 1);
-		};
-	};
-	const registerWrapUp = (frontierStage: string, handler: () => Promise<never>): (() => void) => {
-		const registration = { frontierStage, handler };
-		const unregisterOwn = ownEnabled ? registerLocalWrapUp(registration) : undefined;
-		const unregisterRoot = root
-			? root.registerWrapUp(frontierStage, async () => {
-					try {
-						return await handler();
-					} catch (error) {
-						if (!(error instanceof WorkflowBudgetExceededError)) throw error;
-						throw root.finishWrapUp(
-							error.report.frontierStage,
-							error.report.wrapUpSummary,
-							error.report.wrapUpUsage,
-							error.report.wrapUpSummary !== undefined,
-						);
-					}
-				})
-			: undefined;
-		return () => {
-			unregisterOwn?.();
-			unregisterRoot?.();
-		};
-	};
-	const deliverWrapUp = (frontierStage: string): Promise<never> => {
-		if (wrapUpPromise !== undefined) return wrapUpPromise;
-		if (rootWrapUpPending && root !== undefined) return root.deliverWrapUp(frontierStage);
-		if (state?.systemOwnedStop === true && state.wrapUpCompleted !== true)
-			throw finishWrapUp(frontierStage, undefined, undefined, false);
-		const registration = handlers.findLast((entry) => entry.frontierStage === frontierStage) ?? handlers.at(-1);
-		if (registration === undefined) throw finishWrapUp(frontierStage, undefined, undefined, false);
-		wrapUpPromise = registration.handler();
-		return wrapUpPromise;
-	};
-	const stopAtBoundaryAsync = async (frontierStage?: string): Promise<void> => {
-		if (root !== undefined) await root.stopAtBoundaryAsync(frontierStage);
-		const check = ownCheckpoint(frontierStage);
-		if (check.kind === "continue" || check.kind === "warn") return;
-		if (check.kind === "wrap_up") {
-			await deliverWrapUp(frontierStage ?? "workflow frontier");
-			return;
-		}
-		throw finishWrapUp(frontierStage, state?.wrapUpSummary, state?.wrapUpUsage, state?.wrapUpCompleted === true);
-	};
-	const awaitPendingWrapUp = async (): Promise<WorkflowBudgetExceededError | undefined> => {
-		const rootError = await root?.awaitPendingWrapUp();
-		if (rootError !== undefined) return rootError;
-		if (wrapUpPromise === undefined) return undefined;
-		try {
-			await wrapUpPromise;
-		} catch (error) {
-			if (error instanceof WorkflowBudgetExceededError) return error;
-			throw error;
-		}
-		return undefined;
-	};
-	return {
-		enabled,
-		checkpoint,
-		registerWrapUp,
-		deliverWrapUp,
-		finishWrapUp,
-		rethrowIfSystemOwnedStop,
-		stopAtBoundary,
-		stopAtBoundaryAsync,
-		awaitPendingWrapUp,
-	};
-}

package/dist/builtin/workflows/src/engine/run-durable-admission.ts

@@ -1,50 +0,0 @@
-/**
- * Durable root-run registration and startup admission.
- *
- * Root registration/status must be durably persisted before startup admission
- * or workflow code runs: a stopped or unhealthy backend fails here, before
- * any side effects execute (issue #1957).
- */
-
-import type { DurableWorkflowBackend, WorkflowRegistrationInput } from "../durable/backend.js";
-import type { WorkflowSerializableValue } from "../shared/types.js";
-
-/** Build the root registration handle, or `undefined` when the run must not (re-)register. */
-export function durableRootRegistrationForRun(args: {
-	readonly runId: string;
-	readonly name: string;
-	readonly inputs: Readonly<Record<string, unknown>>;
-	readonly createdAt: number;
-	readonly hasPersistence: boolean;
-	readonly isChildRun: boolean;
-	readonly continuationSourceId: string | undefined;
-}): WorkflowRegistrationInput | undefined {
-	const shouldRegister =
-		!args.isChildRun && (args.continuationSourceId === undefined || args.continuationSourceId !== args.runId);
-	if (!shouldRegister) return undefined;
-	return {
-		workflowId: args.runId,
-		name: args.name,
-		inputs: args.inputs as Record<string, WorkflowSerializableValue>,
-		createdAt: args.createdAt,
-		status: "running" as const,
-		rootWorkflowId: args.runId,
-		resumable: true,
-		...(args.hasPersistence ? { sessionFile: undefined } : {}),
-	};
-}
-
-/** Register/mark the root run and flush so admission requires healthy durable persistence. */
-export async function admitDurableRootRun(args: {
-	readonly backend: DurableWorkflowBackend;
-	readonly runId: string;
-	readonly isChildRun: boolean;
-	readonly registration: WorkflowRegistrationInput | undefined;
-}): Promise<void> {
-	if (args.registration !== undefined) {
-		args.backend.registerWorkflow(args.registration);
-	} else if (!args.isChildRun) {
-		args.backend.setWorkflowStatus(args.runId, "running");
-	}
-	if (!args.isChildRun) await args.backend.flush();
-}

package/dist/builtin/workflows/src/engine/run-durable-finalize.ts

@@ -1,97 +0,0 @@
-/**
- * Durable terminal-status finalization for workflow runs.
- *
- * Extracted from `run()` to keep the engine entrypoint under the file-length
- * gate. Persists the final durable status (cancelled/blocked/skipped/failed/
- * killed) for cross-session resume discovery when the run did not complete
- * normally (normal completion is handled in the run try-block).
- *
- * cross-ref: issue #1498.
- */
-
-import type { DurableWorkflowBackend } from "../durable/backend.js";
-import { recordRunTimingCheckpoint } from "../durable/run-timing.js";
-import type { DurableWorkflowStatus } from "../durable/types.js";
-import { effectiveRunStatus } from "../shared/returned-run-status.js";
-import type { RunSnapshot } from "../shared/store-types.js";
-
-export interface DurableTerminalFinalizeInput {
-	readonly runId: string;
-	readonly runSnapshot: RunSnapshot;
-	readonly isRoot: boolean;
-	readonly durableBackend: DurableWorkflowBackend;
-}
-
-/** Persist the terminal durable status and surface DBOS write failures. */
-export async function finalizeDurableTerminalStatus(input: DurableTerminalFinalizeInput): Promise<void> {
-	if (!input.isRoot) return;
-	const status = effectiveRunStatus(input.runSnapshot);
-	const isExitTerminal = input.runSnapshot.exited === true && status !== "running";
-	const isBlocked =
-		status === "blocked" && (input.runSnapshot.endedAt !== undefined || input.runSnapshot.blockedAt !== undefined);
-	if (status !== "failed" && status !== "killed" && !isExitTerminal && !isBlocked) return;
-
-	const durableStatus = toDurableStatus(status);
-	if (durableStatus !== undefined) {
-		// Failed/blocked runs may be resumed cross-session by workflow id; persist
-		// the exact accumulated elapsed so the resumed dashboard total continues
-		// from the prior sessions instead of restarting at zero.
-		if (durableStatus === "failed" || durableStatus === "blocked") {
-			recordRunTimingCheckpoint(input.durableBackend, input.runSnapshot);
-		}
-		const failure =
-			durableStatus === "failed"
-				? {
-						...(input.runSnapshot.error !== undefined ? { error: input.runSnapshot.error } : {}),
-						...(input.runSnapshot.exited === true
-							? {
-									exited: true,
-									...(input.runSnapshot.exitReason !== undefined
-										? { exitReason: input.runSnapshot.exitReason }
-										: {}),
-								}
-							: {}),
-						...(input.runSnapshot.failureKind !== undefined
-							? { failureKind: input.runSnapshot.failureKind }
-							: {}),
-						...(input.runSnapshot.failureCode !== undefined
-							? { failureCode: input.runSnapshot.failureCode }
-							: {}),
-						...(input.runSnapshot.failureRecoverability !== undefined
-							? { failureRecoverability: input.runSnapshot.failureRecoverability }
-							: {}),
-						...(input.runSnapshot.failureDisposition !== undefined
-							? { failureDisposition: input.runSnapshot.failureDisposition }
-							: {}),
-						...(input.runSnapshot.failedToolNodeId !== undefined
-							? { failedToolNodeId: input.runSnapshot.failedToolNodeId }
-							: {}),
-					}
-				: undefined;
-		input.durableBackend.setWorkflowStatus(
-			input.runId,
-			durableStatus,
-			undefined,
-			input.runSnapshot.resumable,
-			failure,
-		);
-	}
-	await input.durableBackend.flush();
-}
-
-function toDurableStatus(status: RunSnapshot["status"]): DurableWorkflowStatus | undefined {
-	switch (status) {
-		case "completed":
-		case "skipped":
-			return "completed";
-		case "cancelled":
-		case "killed":
-			return "cancelled";
-		case "failed":
-			return "failed";
-		case "blocked":
-			return "blocked";
-		default:
-			return undefined;
-	}
-}