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

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

@@ -1,65 +0,0 @@
-import { recordRunTimingCheckpointAsync } from "../durable/run-timing.js";
-import { type DurableStageDeps, recordStageSessionCheckpoint } from "../durable/stage-primitive.js";
-import { recordWorkflowHeartbeatAnchor } from "../durable/workflow-heartbeat-anchor.js";
-import type { StageSessionCheckpointOptions } from "../runs/foreground/executor-types.js";
-import type { RunSnapshot, StageSnapshot } from "../shared/store-types.js";
-
-export interface DurableStageSessionRecorderInput {
-	readonly runId: string;
-	readonly deps: DurableStageDeps;
-	readonly onStageSession?: (
-		runId: string,
-		snapshot: StageSnapshot,
-		options?: StageSessionCheckpointOptions,
-	) => unknown;
-	/**
-	 * Live root-run snapshot. When present, stage-session checkpoints also
-	 * refresh the debounced run-level elapsed record so a durable resume can
-	 * seed the total workflow duration. Omitted for child runs — run timing is
-	 * only tracked for the root workflow.
-	 */
-	readonly runSnapshot?: RunSnapshot;
-	/** Cadence declared by the live definition that minted `runSnapshot`. */
-	readonly heartbeatIntervalMinutes: number;
-}
-
-export function createDurableStageSessionRecorder(
-	input: DurableStageSessionRecorderInput,
-): (stageRunId: string, snapshot: StageSnapshot, options?: StageSessionCheckpointOptions) => Promise<void> {
-	return async (stageRunId, snapshot, options) => {
-		if (stageRunId === input.runId) {
-			await recordStageSessionCheckpoint(input.deps, snapshot, { force: options?.forceDurable === true });
-			if (input.runSnapshot !== undefined) {
-				await recordRunTimingCheckpointAsync(input.deps.backend, input.runSnapshot, {
-					debounce: options?.forceDurable !== true,
-				});
-				// Any checkpoint above can be the first one that makes the run
-				// resumable, and the scheduler's own launch-record write is
-				// asynchronous and best-effort: it is guarded against runs with no
-				// durable progress, so it can only be issued *after* resumability
-				// already exists. A process that exits inside that window leaves a
-				// resumable run with no record of what it launched with, and the next
-				// process then reads a freshly minted `startedAt` and whatever cadence
-				// the definition currently declares — shifting both phase and cadence
-				// under a run already in flight.
-				//
-				// Awaiting the write here closes that window: the record is durable
-				// before this checkpoint is acknowledged to its caller. It is
-				// write-once and returns early once present, so later passes cost one
-				// mirror read. A forced pause/quit capture additionally has no further
-				// active schedule pass to retry in, which is why this must not be
-				// limited to the ordinary path either.
-				const intervalMinutes = input.heartbeatIntervalMinutes;
-				if (Number.isFinite(intervalMinutes * 60_000)) {
-					await recordWorkflowHeartbeatAnchor(input.deps.backend, {
-						runId: input.runId,
-						anchorAt: input.runSnapshot.startedAt,
-						intervalMinutes,
-						now: input.deps.now?.() ?? Date.now(),
-					});
-				}
-			}
-		}
-		await input.onStageSession?.(stageRunId, snapshot, options);
-	};
-}

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

@@ -1,295 +0,0 @@
-import { type DurableWorkflowBackend, durableHash } from "../durable/backend.js";
-import { DurableNestedTopologyError } from "../durable/boundary-topology.js";
-import { durableCompletedNestedRunSubtree } from "../durable/completed-subtree.js";
-import {
-	type DurableCompletedStageCheckpoint,
-	type DurableStageDeps,
-	recordCachedStageWithTracker,
-	recordStageCheckpoint,
-} from "../durable/stage-primitive.js";
-import { durableStageCheckpointMetadata } from "../durable/stage-topology.js";
-import { promptOccurrenceIdentityError } from "../durable/stage-topology-validation.js";
-import type { DurableStageCheckpoint, DurableStageRunTopology, DurableStageTopology } from "../durable/types.js";
-import { parseLegacyWorkflowChildResult, parseWorkflowChildResult } from "../durable/workflow-child-result.js";
-import type { ParallelFailFastScope, RunOpts } from "../runs/foreground/executor-types.js";
-import type { Store } from "../shared/store.js";
-import type { RunSnapshot, StageSnapshot } from "../shared/store-types.js";
-import { authoritativeWorkflowChildRunId, reciprocalWorkflowRootRunId } from "../shared/workflow-run-ownership.js";
-import type { GraphFrontierTracker } from "./graph-inference.js";
-
-export function durableRunTopology(run: RunSnapshot): DurableStageRunTopology {
-	return {
-		runId: run.id,
-		runName: run.name,
-		...(run.parentRunId !== undefined ? { parentRunId: run.parentRunId } : {}),
-		...(run.parentStageId !== undefined ? { parentStageId: run.parentStageId } : {}),
-		...(run.rootRunId !== undefined ? { rootRunId: run.rootRunId } : {}),
-	};
-}
-
-export function createDurableStageDeps(input: {
-	readonly backend: DurableWorkflowBackend;
-	readonly run: RunSnapshot;
-	readonly nextCheckpointId: () => string;
-	readonly nextReplayKey: (stageName: string) => string;
-	readonly completedReplayKeys: Map<string, string>;
-}): DurableStageDeps {
-	return {
-		workflowId: input.run.id,
-		backend: input.backend,
-		nextCheckpointId: input.nextCheckpointId,
-		nextReplayKey: input.nextReplayKey,
-		replayKeyForCompletedStage: (stage) => input.completedReplayKeys.get(stage.id),
-		runTopology: durableRunTopology(input.run),
-		sourceOrderForStage: (stage) => {
-			const order = input.run.stages.findIndex((candidate) => candidate.id === stage.id);
-			return order >= 0 ? order : undefined;
-		},
-	};
-}
-
-export function createDurableStageEndRecorder(input: {
-	readonly rootRunId: string;
-	readonly deps: DurableStageDeps;
-	readonly user?: RunOpts["onStageEnd"];
-	readonly metadataOnly?: boolean;
-}): (runId: string, snapshot: StageSnapshot) => Promise<void> {
-	return async (runId, snapshot): Promise<void> => {
-		if (runId === input.rootRunId) {
-			await recordStageCheckpoint(input.deps, snapshot, { metadataOnly: input.metadataOnly });
-		}
-		await input.user?.(runId, snapshot);
-	};
-}
-
-/** Snapshot prior-process stage identities so live writes cannot be mistaken for resume topology. */
-export function createDurableStageTopologyResolver(
-	backend: DurableWorkflowBackend,
-	workflowId: string,
-): (replayKey: string) => DurableStageTopology | undefined {
-	const byReplayKey = new Map<string, Map<string, DurableStageTopology>>();
-	const ownedStages: DurableStageCheckpoint[] = [];
-	for (const checkpoint of backend.listCheckpoints(workflowId)) {
-		if (checkpoint.kind !== "stage" || checkpoint.topology === undefined) continue;
-		const topology = checkpoint.topology;
-		if (topology.run !== undefined && topology.run.runId !== workflowId) continue;
-		ownedStages.push(checkpoint);
-		const byStage = byReplayKey.get(checkpoint.replayKey) ?? new Map<string, DurableStageTopology>();
-		byStage.set(topology.stageId, topology);
-		byReplayKey.set(checkpoint.replayKey, byStage);
-	}
-	const occurrenceError = promptOccurrenceIdentityError(ownedStages);
-	const queues = new Map<string, readonly DurableStageTopology[]>();
-	for (const [replayKey, byStage] of byReplayKey) {
-		const stages = [...byStage.values()];
-		const sourceOrders = stages.map((stage) => stage.sourceOrder);
-		const safe =
-			stages.length <= 1 ||
-			(sourceOrders.every((order) => order !== undefined) && new Set(sourceOrders).size === sourceOrders.length);
-		queues.set(
-			replayKey,
-			safe ? stages.sort((left, right) => (left.sourceOrder ?? 0) - (right.sourceOrder ?? 0)) : [],
-		);
-	}
-	const indexes = new Map<string, number>();
-	return (replayKey): DurableStageTopology | undefined => {
-		if (occurrenceError !== undefined) throw new DurableNestedTopologyError(occurrenceError);
-		const index = indexes.get(replayKey) ?? 0;
-		indexes.set(replayKey, index + 1);
-		return queues.get(replayKey)?.[index];
-	};
-}
-
-/** Persist an in-progress stage identity before an external wait can outlive this process. */
-export async function recordDurableActiveStage(deps: DurableStageDeps, stage: StageSnapshot): Promise<boolean> {
-	if (
-		stage.replayKey === undefined ||
-		stage.status === "completed" ||
-		stage.status === "failed" ||
-		stage.status === "skipped"
-	)
-		return false;
-	await deps.backend.recordCheckpointAsync({
-		kind: "stage",
-		workflowId: deps.workflowId,
-		checkpointId: `stage-active-meta:${durableHash({ replayKey: stage.replayKey, stageId: stage.id })}`,
-		name: stage.name,
-		replayKey: stage.replayKey,
-		completedAt: Date.now(),
-		...durableStageCheckpointMetadata(stage, deps.runTopology, deps.sourceOrderForStage?.(stage)),
-	});
-	return true;
-}
-
-export function createDurableCachedStageRecorder(input: {
-	readonly store: Store;
-	readonly tracker: GraphFrontierTracker;
-	readonly run: RunSnapshot;
-	readonly backend: DurableWorkflowBackend;
-	readonly rootBackend: DurableWorkflowBackend;
-	readonly completedStageReplayKeys: Map<string, string>;
-	readonly sourceToReplayedNodeIds: Map<string, string>;
-}): {
-	readonly record: (
-		name: string,
-		replayKey: string,
-		checkpoint: DurableCompletedStageCheckpoint,
-		scope?: ParallelFailFastScope,
-	) => void;
-	readonly metadata: (replayKey: string) => Partial<DurableCompletedStageCheckpoint>;
-} {
-	const replaySourceOrders = new Map<string, number>();
-	return {
-		record(name, replayKey, checkpoint, scope): void {
-			const cachedChildRunId = workflowChildRunId(checkpoint);
-			const runById = new Map(input.store.runs().map((run) => [run.id, run]));
-			if (!runById.has(input.run.id)) runById.set(input.run.id, input.run);
-			const durableRootId = reciprocalWorkflowRootRunId(runById, input.run.id);
-			const cachedDescendants =
-				cachedChildRunId === undefined || durableRootId === undefined
-					? undefined
-					: durableCompletedNestedRunSubtree(input.rootBackend, durableRootId, cachedChildRunId);
-			if (cachedChildRunId !== undefined && durableRootId !== undefined && cachedDescendants === undefined) {
-				throw new DurableNestedTopologyError(
-					`cached completed child subtree is incomplete or inconsistent at ${replayKey}`,
-				);
-			}
-			recordCachedStageWithTracker(
-				input.store,
-				input.tracker,
-				input.run.id,
-				name,
-				replayKey,
-				checkpoint,
-				input.completedStageReplayKeys,
-				scope,
-				input.sourceToReplayedNodeIds,
-			);
-			const sourceOrder = checkpoint.topology?.sourceOrder;
-			if (sourceOrder !== undefined) {
-				const replayedStage = input.run.stages.find((candidate) => candidate.replayKey === replayKey);
-				if (replayedStage !== undefined) replaySourceOrders.set(replayedStage.id, sourceOrder);
-				input.run.stages.sort(
-					(left, right) =>
-						(replaySourceOrders.get(left.id) ?? Number.MAX_SAFE_INTEGER) -
-						(replaySourceOrders.get(right.id) ?? Number.MAX_SAFE_INTEGER),
-				);
-			}
-			const stage = input.store
-				.runs()
-				.find((run) => run.id === input.run.id)
-				?.stages.find((candidate) => candidate.replayKey === replayKey);
-			if (stage !== undefined) {
-				input.backend.recordCheckpoint({
-					kind: "stage",
-					workflowId: input.run.id,
-					checkpointId: `stage-replay-meta:${durableHash({ replayKey, stageId: stage.id, parentIds: stage.parentIds })}`,
-					name,
-					replayKey,
-					completedAt: Date.now(),
-					...durableStageCheckpointMetadata(
-						stage,
-						durableRunTopology(input.run),
-						sourceOrder ?? input.run.stages.findIndex((candidate) => candidate.id === stage.id),
-					),
-				});
-			}
-			for (const childRun of cachedDescendants ?? []) {
-				const existingRun = input.store.runs().find((candidate) => candidate.id === childRun.id);
-				const isDirectChild =
-					childRun.id === cachedChildRunId &&
-					childRun.parentRunId === input.run.id &&
-					stage?.workflowChild?.runId === cachedChildRunId;
-				if (existingRun !== undefined) {
-					if (stage !== undefined && isDirectChild) {
-						reconcileCachedDirectChildParentStage({
-							store: input.store,
-							parentRun: input.run,
-							catalogRun: childRun,
-							checkpointChildRunId: cachedChildRunId!,
-							boundary: stage,
-						});
-					}
-					continue;
-				}
-				const hydratedRun =
-					isDirectChild && stage !== undefined ? { ...childRun, parentStageId: stage.id } : childRun;
-				input.store.recordRunStart(hydratedRun);
-			}
-		},
-		metadata(replayKey) {
-			const stage = input.run.stages.find((candidate) => candidate.replayKey === replayKey);
-			return stage === undefined
-				? {}
-				: durableStageCheckpointMetadata(
-						stage,
-						durableRunTopology(input.run),
-						input.run.stages.findIndex((candidate) => candidate.id === stage.id),
-					);
-		},
-	};
-}
-
-export function reconcileCachedDirectChildParentStage(input: {
-	readonly store: Store;
-	readonly parentRun: RunSnapshot;
-	readonly catalogRun: RunSnapshot;
-	readonly checkpointChildRunId: string;
-	readonly boundary: StageSnapshot;
-}): boolean {
-	const existingRun = input.store.runs().find((run) => run.id === input.checkpointChildRunId);
-	if (existingRun === undefined) return false;
-	const runById = new Map(input.store.runs().map((run) => [run.id, run]));
-	const storedParentRun = runById.get(input.parentRun.id);
-	if (
-		storedParentRun !== undefined &&
-		(storedParentRun.parentRunId !== input.parentRun.parentRunId ||
-			storedParentRun.parentStageId !== input.parentRun.parentStageId)
-	)
-		return false;
-	if (storedParentRun === undefined) runById.set(input.parentRun.id, input.parentRun);
-	const expectedRootRunId = reciprocalWorkflowRootRunId(runById, input.parentRun.id);
-	if (expectedRootRunId === undefined) return false;
-	const storedBoundary = storedParentRun?.stages.find((stage) => stage.id === input.boundary.id);
-	const cachedChildStatusMatches =
-		(existingRun?.status === "completed" && input.catalogRun.status === "completed") ||
-		(input.boundary.workflowChild?.exited === true &&
-			input.boundary.workflowChild.runId === input.checkpointChildRunId &&
-			existingRun?.status === input.catalogRun.status &&
-			input.boundary.workflowChild.status === input.catalogRun.status);
-
-	if (
-		!rootMatches(input.parentRun.rootRunId, expectedRootRunId) ||
-		!rootMatches(storedParentRun?.rootRunId, expectedRootRunId) ||
-		authoritativeWorkflowChildRunId(input.boundary) !== input.checkpointChildRunId ||
-		(storedParentRun !== undefined &&
-			authoritativeWorkflowChildRunId(storedBoundary) !== input.checkpointChildRunId) ||
-		input.catalogRun.id !== input.checkpointChildRunId ||
-		!cachedChildStatusMatches ||
-		existingRun.parentRunId !== input.parentRun.id ||
-		input.catalogRun.parentRunId !== input.parentRun.id ||
-		input.catalogRun.parentStageId === undefined ||
-		existingRun.parentStageId !== input.catalogRun.parentStageId ||
-		!rootMatches(existingRun.rootRunId, expectedRootRunId) ||
-		!rootMatches(input.catalogRun.rootRunId, expectedRootRunId)
-	)
-		return false;
-	return input.store.reconcileRunParentStage(existingRun.id, input.catalogRun.parentStageId, input.boundary.id);
-}
-
-function rootMatches(rootRunId: string | undefined, expectedRootRunId: string): boolean {
-	return rootRunId === undefined || rootRunId === expectedRootRunId;
-}
-
-function workflowChildRunId(checkpoint: DurableCompletedStageCheckpoint): string | undefined {
-	const topology = checkpoint.topology;
-	const hasCurrentIdentity =
-		topology?.sourceOrder !== undefined ||
-		topology?.status !== undefined ||
-		topology?.occurrenceKey !== undefined ||
-		topology?.boundary !== undefined;
-	return (
-		parseWorkflowChildResult(checkpoint.output) ??
-		(hasCurrentIdentity ? undefined : parseLegacyWorkflowChildResult(checkpoint.output))
-	)?.runId;
-}

package/dist/builtin/workflows/src/engine/run-returned-status.ts

@@ -1,86 +0,0 @@
-import {
-	actionableReturnedStatusText,
-	isReturnedBlockedWorkflowStatus,
-	isReturnedResumableBlockedWorkflowStatus,
-	normalizeReturnedWorkflowStatus,
-	structuredRecoverableWorkflowFailure,
-} from "../shared/returned-run-status.js";
-import type { RunEndMetadata } from "../shared/store-public-types.js";
-import type { RunSnapshot } from "../shared/store-types.js";
-import type { WorkflowOutputValues } from "../shared/types.js";
-
-export interface ReturnedRunStatus {
-	readonly status: "completed" | "failed" | "blocked";
-	readonly error?: string;
-	readonly metadata?: RunEndMetadata;
-}
-
-export function classifyReturnedRunStatus(
-	result: WorkflowOutputValues | undefined,
-	runSnapshot?: RunSnapshot,
-): ReturnedRunStatus {
-	const structuredFailure = runSnapshot !== undefined ? structuredRecoverableWorkflowFailure(runSnapshot) : undefined;
-	if (structuredFailure !== undefined) {
-		return {
-			status: "blocked",
-			error: structuredFailure.error,
-			metadata: structuredFailure.metadata,
-		};
-	}
-	const returnedStatus = normalizeReturnedWorkflowStatus(result?.status);
-	if (
-		returnedStatus === "budget_exceeded" &&
-		(runSnapshot?.budgetState?.wrapUpCompleted !== true ||
-			runSnapshot.failureDisposition !== "active_blocked" ||
-			runSnapshot.failureRecoverability !== "recoverable")
-	)
-		// Only the system-owned budget door may produce this status.
-		return { status: "completed" };
-	if (returnedStatus === undefined || returnedStatus === "completed" || returnedStatus === "complete") {
-		return { status: "completed" };
-	}
-
-	const error = returnedStatusError(result, returnedStatus);
-	if (returnedStatus === "failed") {
-		return {
-			status: "failed",
-			error,
-			metadata: returnedFailureMetadata(error),
-		};
-	}
-	if (isReturnedBlockedWorkflowStatus(returnedStatus)) {
-		const metadata = isReturnedResumableBlockedWorkflowStatus(returnedStatus)
-			? returnedRecoverableBlockedMetadata(error)
-			: { resumable: false };
-		return {
-			status: "blocked",
-			error,
-			metadata,
-		};
-	}
-
-	return { status: "completed" };
-}
-
-function returnedStatusError(result: WorkflowOutputValues | undefined, returnedStatus: string): string {
-	return actionableReturnedStatusText(result) ?? `Workflow returned status ${JSON.stringify(returnedStatus)}.`;
-}
-
-function returnedFailureMetadata(error: string): RunEndMetadata {
-	return {
-		failureKind: "unknown",
-		failureRecoverability: "non_recoverable",
-		failureDisposition: "terminal_failed",
-		failureMessage: error,
-		resumable: false,
-	};
-}
-
-function returnedRecoverableBlockedMetadata(error: string): RunEndMetadata {
-	return {
-		failureRecoverability: "recoverable",
-		failureDisposition: "active_blocked",
-		failureMessage: error,
-		resumable: true,
-	};
-}

package/dist/builtin/workflows/src/engine/run-terminal-event.ts

@@ -1,39 +0,0 @@
-export type RunTerminalEvent =
-	| { readonly kind: "failure"; readonly error: unknown; readonly nodeId?: string }
-	| { readonly kind: "cancellation"; readonly reason: unknown };
-
-export interface RunTerminalEventArbiter {
-	selectFailure(error: unknown, nodeId?: string): RunTerminalEvent;
-	selectCancellation(reason: unknown): RunTerminalEvent;
-	winner(): RunTerminalEvent | undefined;
-	register(): void;
-	dispose(): void;
-}
-
-const activeArbiters = new Map<string, RunTerminalEventArbiter>();
-
-/** Latches the first executor failure or real run cancellation for one live run. */
-export function createRunTerminalEventArbiter(runId: string): RunTerminalEventArbiter {
-	let selected: RunTerminalEvent | undefined;
-	const select = (event: RunTerminalEvent): RunTerminalEvent => {
-		selected ??= event;
-		return selected;
-	};
-	const arbiter: RunTerminalEventArbiter = {
-		selectFailure: (error, nodeId) => select({ kind: "failure", error, ...(nodeId === undefined ? {} : { nodeId }) }),
-		selectCancellation: (reason) => select({ kind: "cancellation", reason }),
-		winner: () => selected,
-		register() {
-			activeArbiters.set(runId, arbiter);
-		},
-		dispose() {
-			if (activeArbiters.get(runId) === arbiter) activeArbiters.delete(runId);
-		},
-	};
-	return arbiter;
-}
-
-/** Read the selected event so an external kill cannot overwrite an earlier failure. */
-export function selectedRunTerminalEvent(runId: string): RunTerminalEvent | undefined {
-	return activeArbiters.get(runId)?.winner();
-}

package/dist/builtin/workflows/src/engine/run-terminal-failure.ts

@@ -1,53 +0,0 @@
-import {
-	appendRunEndWhenRecorded,
-	reconcileTerminalRunResult,
-	type SelectedRunFailureMetadata,
-} from "../runs/foreground/executor-lifecycle.js";
-import type { RunOpts, RunResult } from "../runs/foreground/executor-types.js";
-import type { Store } from "../shared/store.js";
-import type { RunSnapshot } from "../shared/store-types.js";
-import type { WorkflowPersistencePort } from "../shared/types.js";
-
-/** Record, persist, and return one ordinary terminal workflow failure. */
-export function finalizeTerminalFailure(input: {
-	readonly runId: string;
-	readonly runSnapshot: RunSnapshot;
-	readonly store: Store;
-	readonly persistence?: WorkflowPersistencePort;
-	readonly metadata: SelectedRunFailureMetadata & { readonly failedToolNodeId?: string };
-	readonly onRunEnd: RunOpts["onRunEnd"];
-}): RunResult {
-	const { runId, runSnapshot, store, persistence, metadata, onRunEnd } = input;
-	const failedToolNode =
-		metadata.failedToolNodeId === undefined
-			? undefined
-			: runSnapshot.toolNodes?.find((node) => node.id === metadata.failedToolNodeId);
-	const recorded = store.recordRunEnd(runId, "failed", undefined, metadata.errorMessage, metadata);
-	appendRunEndWhenRecorded(persistence, recorded, {
-		runId,
-		status: "failed",
-		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 } : {}),
-		...(metadata.failedToolNodeId !== undefined ? { failedToolNodeId: metadata.failedToolNodeId } : {}),
-		...(failedToolNode !== undefined ? { failedToolNode } : {}),
-		resumable: metadata.resumable,
-		...(metadata.retryAfterMs !== undefined ? { retryAfterMs: metadata.retryAfterMs } : {}),
-		...(runSnapshot.endedAt !== undefined ? { endedAt: runSnapshot.endedAt } : {}),
-		...(runSnapshot.durationMs !== undefined ? { durationMs: runSnapshot.durationMs } : {}),
-		ts: Date.now(),
-	});
-	return reconcileTerminalRunResult(
-		runId,
-		runSnapshot,
-		store,
-		{ status: "failed", error: metadata.errorMessage },
-		onRunEnd,
-	);
-}

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

@@ -1,99 +0,0 @@
-/**
- * Root-shared `ctx.tool` admission boundary for graceful quit.
- *
- * Rescanning live tool handles cannot make quit an exact durability boundary on
- * its own: `markDurableQuit()` awaits backend work, so a callback admitted
- * after the last scan would still be running when the paused/resumable
- * transition is published. A bounded rescan loop cannot fix that either — it
- * either misses a late admission or spins while author continuations keep
- * admitting calls.
- *
- * This boundary supplies the missing invariant instead:
- *
- * > Once quit closes admission, no root or nested run can admit another
- * > `ctx.tool` callback, so the collected handle set can only shrink.
- *
- * `admit()` opens a short *registration section*, not the callback's lifetime.
- * `ctx.tool` releases its lease as soon as the call has published its live node
- * controller (or resolved as cached/refused without a live callback), so
- * `closeForQuit()` waits microseconds rather than for callback settlement.
- *
- * cross-ref: issue #2078.
- */
-
-import type { WorkflowGracefulQuitError } from "./workflow-tool-abort.js";
-
-export interface ToolAdmissionLease {
-	/** Idempotent; the registration section ends on the first call. */
-	release(): void;
-}
-
-export type ToolAdmissionResult =
-	| { readonly accepted: true; readonly lease: ToolAdmissionLease }
-	| { readonly accepted: false; readonly error: WorkflowGracefulQuitError };
-
-export interface ToolAdmissionBoundary {
-	/** Enter a registration section, or refuse once quit has closed admission. */
-	admit(): ToolAdmissionResult;
-	/**
-	 * Refuse every future admission and wait only for registration sections that
-	 * were already open. Idempotent and safe to call concurrently.
-	 */
-	closeForQuit(reason: WorkflowGracefulQuitError): Promise<void>;
-	readonly closed: boolean;
-	/**
-	 * The reason a whole-run quit closed this workflow tree, when one did.
-	 *
-	 * This is the authoritative signal that quit owns the run's outcome, even
-	 * when author code caught the tool rejection: `run()` reads it on both the
-	 * success and failure paths so a later author return cannot convert an
-	 * operator-selected quit into a terminal completion.
-	 */
-	readonly quitReason: WorkflowGracefulQuitError | undefined;
-	/** True while a `ctx.tool` call is between admission and node registration. */
-	readonly hasPendingAdmissions: boolean;
-}
-
-export function createToolAdmissionBoundary(): ToolAdmissionBoundary {
-	let closedReason: WorkflowGracefulQuitError | undefined;
-	let openSections = 0;
-	let drained: PromiseWithResolvers<void> | undefined;
-
-	const settleWhenDrained = (): void => {
-		if (closedReason !== undefined && openSections === 0) drained?.resolve();
-	};
-
-	return {
-		get closed(): boolean {
-			return closedReason !== undefined;
-		},
-		get quitReason(): WorkflowGracefulQuitError | undefined {
-			return closedReason;
-		},
-		get hasPendingAdmissions(): boolean {
-			return openSections > 0;
-		},
-		admit(): ToolAdmissionResult {
-			if (closedReason !== undefined) return { accepted: false, error: closedReason };
-			openSections += 1;
-			let released = false;
-			return {
-				accepted: true,
-				lease: {
-					release(): void {
-						if (released) return;
-						released = true;
-						openSections -= 1;
-						settleWhenDrained();
-					},
-				},
-			};
-		},
-		async closeForQuit(reason: WorkflowGracefulQuitError): Promise<void> {
-			closedReason ??= reason;
-			if (openSections === 0) return;
-			drained ??= Promise.withResolvers<void>();
-			await drained.promise;
-		},
-	};
-}