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

package/dist/builtin/workflows/src/durable/resume-eligibility.ts

@@ -1,106 +0,0 @@
-import type { RunSnapshot, RunStatus, WorkflowFailureRecoverability } from "../shared/store-types.js";
-import type { DurableWorkflowStatus } from "./types.js";
-
-/** Metadata required to classify a current DBOS workflow as resumable. */
-export interface DurableResumeCandidate {
-	readonly workflowId: string;
-	readonly status: DurableWorkflowStatus;
-	readonly completedCheckpoints: number;
-	readonly pendingPrompts: number;
-	readonly rootWorkflowId?: string;
-	readonly resumable?: boolean;
-}
-
-/** Live snapshot fields used by every workflow resume surface. */
-export interface WorkflowRunResumeCandidate {
-	readonly status: RunStatus;
-	readonly endedAt?: number;
-	readonly resumable?: boolean;
-	readonly failureRecoverability?: WorkflowFailureRecoverability;
-	readonly exitReason?: string;
-	/** True when a descendant stage is paused/blocked even if the root is still running. */
-	readonly hasPausedState?: boolean;
-	/** Explicitly false when durable state or referenced artifacts are missing. */
-	readonly hasDurableCheckpoint?: boolean;
-	readonly artifactsIntact?: boolean;
-	/** True only for the engine-owned budget_exceeded blocked rail. */
-	readonly budgetSystemOwnedStop?: boolean;
-}
-
-/** Derive the paused/blocked state used by every workflow resume surface. */
-export function workflowRunHasPausedState(run: Pick<RunSnapshot, "status" | "exitReason" | "stages">): boolean {
-	return (
-		run.status === "paused" ||
-		run.exitReason === "quit" ||
-		run.stages.some((stage) => stage.status === "paused" || stage.status === "blocked")
-	);
-}
-
-/**
- * Authoritative live-run resume rule shared by every workflow resume surface.
- * Missing durable state or artifacts is never a resume target even when stale
- * snapshot metadata still says resumable.
- */
-export function isWorkflowRunResumable(candidate: WorkflowRunResumeCandidate): boolean {
-	if (candidate.hasDurableCheckpoint === false || candidate.artifactsIntact === false) return false;
-	if (candidate.hasPausedState === true || candidate.status === "paused" || candidate.exitReason === "quit") {
-		return candidate.resumable !== false;
-	}
-	return (
-		(candidate.status === "failed" && candidate.endedAt !== undefined && candidate.resumable !== false) ||
-		(candidate.resumable === true &&
-			candidate.failureRecoverability === "recoverable" &&
-			(candidate.endedAt === undefined || candidate.budgetSystemOwnedStop === true))
-	);
-}
-
-/** Authoritative status/progress rules for durable workflow resume discovery. */
-export function isDurableWorkflowResumable(candidate: DurableResumeCandidate): boolean {
-	const isRoot = candidate.rootWorkflowId === undefined || candidate.rootWorkflowId === candidate.workflowId;
-	if (!isRoot) return false;
-	if (candidate.status === "failed" || candidate.status === "blocked") return candidate.resumable !== false;
-	const hasResumeProgress = candidate.completedCheckpoints > 0 || candidate.pendingPrompts > 0;
-	return (
-		candidate.resumable !== false &&
-		(candidate.status === "running" || candidate.status === "paused") &&
-		hasResumeProgress
-	);
-}
-
-/**
- * Liveness window for a `running` workflow owned by another Atomic process.
- * Active LM stages refresh durable timing metadata at least every ~30s, so a
- * running handle whose metadata is fresher than this window is treated as
- * genuinely executing in that other session rather than crashed.
- */
-export const FOREIGN_LIVE_WORKFLOW_WINDOW_MS = 120_000;
-
-export interface ForeignLivenessCandidate {
-	readonly status: DurableWorkflowStatus;
-	readonly updatedAt: number;
-	readonly ownerExecutorId?: string;
-}
-
-/** Whether a running workflow appears live in a DIFFERENT Atomic process. */
-export function isForeignLiveWorkflow(
-	candidate: ForeignLivenessCandidate,
-	localExecutorId: string,
-	now: number = Date.now(),
-): boolean {
-	if (candidate.status !== "running") return false;
-	if (candidate.ownerExecutorId === undefined || candidate.ownerExecutorId === localExecutorId) return false;
-	return now - candidate.updatedAt < FOREIGN_LIVE_WORKFLOW_WINDOW_MS;
-}
-
-/**
- * Whether a running workflow appears genuinely live ANYWHERE (any owner).
- * Live-running workflows are never resume targets: offering them would allow
- * double-dispatch across sessions. Only stale-heartbeat (crashed) running
- * workflows surface, presented as crashed rather than running.
- */
-export function isLiveRunningWorkflow(
-	candidate: Pick<ForeignLivenessCandidate, "status" | "updatedAt">,
-	now: number = Date.now(),
-): boolean {
-	return candidate.status === "running" && now - candidate.updatedAt < FOREIGN_LIVE_WORKFLOW_WINDOW_MS;
-}

package/dist/builtin/workflows/src/durable/resume-runtime.ts

@@ -1,344 +0,0 @@
-/**
- * Cross-process workflow resume using DBOS as the sole source of state.
- *
- * Resume semantics (DBOS-aligned):
- *   1. Look up the durable catalog entry (workflow name + cached inputs).
- *   2. Resolve the workflow definition from the registry.
- *   3. Re-dispatch the workflow as a new background run, reusing the ORIGINAL
- *      top-level workflow id as the run id. Because durable checkpoints are
- *      keyed by workflow id, every `ctx.tool` / `ctx.ui` / `ctx.stage` call
- *      inside the resumed run returns its cached result instead of re-executing
- *      — completed side effects are not repeated, exactly like DBOS replay.
- *
- * The adapter deliberately re-dispatches through `runDetached` rather than
- * reconstructing an in-memory snapshot, so it works across processes and
- * sessions without a live store entry.
- *
- * cross-ref: issue #1498 — "/workflow resume connects/attempts resume by
- * top-level workflow id."
- */
-
-import type { JobTracker } from "../runs/background/job-tracker.js";
-import { launchDetachedUntilStartup, workflowStartupFailureMessage } from "../runs/background/startup-admission.js";
-import {
-	isWorkflowDefinition,
-	workflowDefinitionRequirementMessage,
-} from "../runs/foreground/executor-child-helpers.js";
-import { resolveAndValidateInputs } from "../runs/foreground/executor-inputs.js";
-import type { RunOpts } from "../runs/foreground/executor-types.js";
-import { isFullRunId, malformedRunIdMessage } from "../shared/run-id.js";
-import type { RunSnapshot } from "../shared/store-types.js";
-import type { WorkflowDefinition, WorkflowInputValues } from "../shared/types.js";
-import type { WorkflowRegistry } from "../workflows/registry.js";
-import { type DurableWorkflowBackend, resumableEntryFromHandle } from "./backend.js";
-import { getAtomicExecutorId } from "./dbos-sdk-handle.js";
-import { getDurableBackend } from "./factory.js";
-import { isDurableWorkflowResumable, isForeignLiveWorkflow } from "./resume-eligibility.js";
-import type { ResumableWorkflowEntry } from "./types.js";
-
-export type ResumeDurableResult =
-	| { ok: true; runId: string; workflowId: string; name: string; message: string }
-	| {
-			ok: false;
-			reason:
-				| "workflow_not_found"
-				| "not_resumable"
-				| "invalid_inputs"
-				| "not_registered"
-				| "stale"
-				| "startup_failed";
-			message: string;
-	  };
-
-export interface ResumeDurableDeps {
-	readonly registry: WorkflowRegistry;
-	/** Base run options forwarded to the detached runner (store, persistence, …). */
-	readonly baseRunOpts: RunOpts;
-	/** Durable backend override (defaults to the global singleton). */
-	readonly durableBackend?: DurableWorkflowBackend;
-	/** Resolve a definition from its original invocation directory after restart. */
-	readonly resolveDefinition?: (name: string, cwd: string | undefined) => Promise<WorkflowDefinition | undefined>;
-	/** Job tracker used by the detached resume launch. */
-	readonly jobs?: JobTracker;
-}
-
-/** Hydrate current DBOS metadata and checkpoints before synchronous replay reads. */
-export async function prepareDurableResume(
-	workflowId: string | undefined,
-	deps: ResumeDurableDeps,
-): Promise<readonly ResumableWorkflowEntry[]> {
-	const backend = deps.durableBackend ?? getDurableBackend();
-	await backend.hydrateResumableWorkflows();
-	const catalog = backend.listResumableWorkflows();
-	// If a specific target was requested, hydrate that workflow too (it might
-	// be resumable but not yet in the resumable filter — e.g. recently failed).
-	if (workflowId !== undefined) {
-		const resolved = resolveDurableEntry(workflowId, catalog);
-		if (resolved !== undefined && !("kind" in resolved)) {
-			await backend.hydrateWorkflow(resolved.workflowId);
-		}
-	}
-	return backend.listResumableWorkflows();
-}
-
-/**
- * Resolve a current DBOS catalog entry by its full run id.
- *
- * The durable `workflowId` is the live run id, so it takes the same strict
- * contract: a full UUID or nothing. A malformed target is reported separately
- * from an absent one.
- */
-export function resolveDurableEntry(
-	workflowId: string,
-	catalog: readonly ResumableWorkflowEntry[],
-): ResumableWorkflowEntry | { kind: "malformed"; message: string } | undefined {
-	if (!isFullRunId(workflowId)) return { kind: "malformed", message: malformedRunIdMessage(workflowId) };
-	return catalog.find((entry) => entry.workflowId === workflowId);
-}
-
-/** Resume by DBOS workflow id and replay current persisted checkpoints. */
-export async function resumeDurableWorkflow(
-	workflowId: string,
-	deps: ResumeDurableDeps,
-	catalog?: readonly ResumableWorkflowEntry[],
-): Promise<ResumeDurableResult> {
-	const backend = deps.durableBackend ?? getDurableBackend();
-	const resolvedCatalog = catalog ?? backend.listResumableWorkflows();
-	const resolved = resolveDurableEntry(workflowId, resolvedCatalog);
-	if (resolved === undefined) {
-		const direct = backend.getWorkflow(workflowId);
-		if (direct !== undefined && direct.status === "running") {
-			if (hasActiveLiveRun(deps.baseRunOpts.store, direct.workflowId)) {
-				return alreadyRunningResult(direct.name, direct.workflowId, deps.baseRunOpts.store);
-			}
-			if (isForeignLiveWorkflow(direct, getAtomicExecutorId())) {
-				return foreignRunningResult(direct.name, direct.workflowId);
-			}
-		}
-		if (!backend.isWorkflowLoadable(workflowId)) {
-			return {
-				ok: false,
-				reason: "not_registered",
-				message: `Workflow ${workflowId} has no valid current DBOS state.`,
-			};
-		}
-		return {
-			ok: false,
-			reason: "not_registered",
-			message: `No resumable workflow found for id: ${workflowId}`,
-		};
-	}
-	if ("kind" in resolved) {
-		return { ok: false, reason: "not_registered", message: resolved.message };
-	}
-	if (!backend.isWorkflowLoadable(resolved.workflowId)) {
-		return {
-			ok: false,
-			reason: "not_registered",
-			message: `Workflow ${resolved.workflowId} has no valid current DBOS state.`,
-		};
-	}
-	// Revalidate the authoritative DBOS handle before resume. A running handle
-	// is refused when this process still has an actively executing run, or when
-	// fresh ownership metadata shows another Atomic session is executing it.
-	const handle = backend.getWorkflow(resolved.workflowId);
-	if (handle === undefined) {
-		return {
-			ok: false,
-			reason: "stale",
-			message: `Workflow ${resolved.workflowId} has no current DBOS checkpoint state; re-run the workflow to start fresh.`,
-		};
-	}
-
-	if (handle.status === "running") {
-		if (hasActiveLiveRun(deps.baseRunOpts.store, resolved.workflowId)) {
-			return alreadyRunningResult(handle.name, resolved.workflowId, deps.baseRunOpts.store);
-		}
-		if (isForeignLiveWorkflow(handle, getAtomicExecutorId())) {
-			return foreignRunningResult(handle.name, resolved.workflowId);
-		}
-	}
-	if (!isDurableWorkflowResumable(handle)) {
-		return {
-			ok: false,
-			reason: "not_resumable",
-			message: `Workflow ${resolved.workflowId} is ${handle.status}, not resumable.`,
-		};
-	}
-
-	const def =
-		handle.invocationCwd === undefined
-			? deps.registry.get(handle.name)
-			: ((await deps.resolveDefinition?.(handle.name, handle.invocationCwd)) ?? deps.registry.get(handle.name));
-	if (def === undefined) {
-		return { ok: false, reason: "workflow_not_found", message: `Workflow definition not found: ${handle.name}` };
-	}
-	if (!isWorkflowDefinition(def)) {
-		return {
-			ok: false,
-			reason: "workflow_not_found",
-			message: workflowDefinitionRequirementMessage("resumeDurableWorkflow", def),
-		};
-	}
-
-	const inputs: Record<string, unknown> = { ...handle.inputs };
-	try {
-		resolveAndValidateInputs(def.inputs, inputs as WorkflowInputValues, `workflow "${def.name}"`);
-	} catch (err) {
-		return {
-			ok: false,
-			reason: "invalid_inputs",
-			message: `invalid_inputs: ${err instanceof Error ? err.message : String(err)}`,
-		};
-	}
-	removeDurableResumeShadowRuns(deps.baseRunOpts.store, resolved.workflowId);
-
-	// Claim resume against concurrent deletion through the required transition seam.
-	const claimed = await backend.transitionWorkflowStatus(resolved.workflowId, [handle.status], "running");
-	if (!claimed) {
-		return {
-			ok: false,
-			reason: "stale",
-			message: `Workflow ${resolved.workflowId} changed while resume was pending; refresh the workflow list and try again.`,
-		};
-	}
-
-	const resumeRunOpts: RunOpts = {
-		...deps.baseRunOpts,
-		...(handle.invocationCwd !== undefined ? { cwd: handle.invocationCwd } : {}),
-		...(handle.origin !== undefined ? { origin: handle.origin } : {}),
-		runId: resolved.workflowId,
-		durableBackend: backend,
-	};
-
-	let launch: ReturnType<typeof launchDetachedUntilStartup>;
-	try {
-		launch = launchDetachedUntilStartup(def, inputs, {
-			...resumeRunOpts,
-			...(deps.jobs !== undefined ? { jobs: deps.jobs } : {}),
-		});
-	} catch (error) {
-		backend.setWorkflowStatus(resolved.workflowId, handle.status, handle.pendingPrompts, handle.resumable);
-		await backend.flush();
-		return {
-			ok: false,
-			reason: "startup_failed",
-			message: `Failed to resume durable workflow ${resolved.workflowId}: ${error instanceof Error ? error.message : String(error)}`,
-		};
-	}
-	const { accepted } = launch;
-	const admission = await launch.wait;
-	if (!admission.started) {
-		const snapshot = deps.baseRunOpts.store?.runs().find((run) => run.id === accepted.runId);
-		const error = workflowStartupFailureMessage(
-			admission,
-			snapshot?.error,
-			`Workflow ${resolved.workflowId} ended before startup admission`,
-		);
-		deps.baseRunOpts.store?.removeRun(accepted.runId);
-		backend.setWorkflowStatus(resolved.workflowId, handle.status, handle.pendingPrompts, handle.resumable);
-		await backend.flush();
-		return {
-			ok: false,
-			reason: "startup_failed",
-			message: `Failed to resume durable workflow ${resolved.workflowId}: ${error}`,
-		};
-	}
-
-	return {
-		ok: true,
-		runId: accepted.runId,
-		workflowId: resolved.workflowId,
-		name: handle.name,
-		message: `Resuming durable workflow "${handle.name}" (${resolved.workflowId}) — completed checkpoints will be replayed.`,
-	};
-}
-
-function isDurableResumeShadow(run: RunSnapshot): boolean {
-	return run.endedAt !== undefined || run.exitReason === "quit" || run.status === "paused";
-}
-
-function removeDurableResumeShadowRuns(store: RunOpts["store"], workflowId: string): void {
-	if (store === undefined) return;
-	for (;;) {
-		const existing = store.runs().find((run) => run.id === workflowId);
-		if (existing === undefined || !isDurableResumeShadow(existing)) return;
-		if (!store.removeRun(workflowId)) return;
-	}
-}
-function foreignRunningResult(name: string, workflowId: string): ResumeDurableResult {
-	return {
-		ok: false,
-		reason: "not_resumable",
-		message:
-			`Workflow "${name}" (${workflowId}) is actively running in another Atomic session. ` +
-			"Control it from that session; it becomes resumable here only after that session pauses, quits, or crashes.",
-	};
-}
-
-function alreadyRunningResult(name: string, workflowId: string, store: RunOpts["store"]): ResumeDurableResult {
-	const here = store?.runs().some((r) => r.id === workflowId && r.endedAt === undefined) === true;
-	return {
-		ok: false,
-		reason: "not_resumable",
-		message: `Workflow "${name}" (${workflowId}) is already running${
-			here ? " in this session" : " in another session"
-		}. See agents working and chat with or steer each stage using \`/workflow connect ${workflowId}\`; use \`/workflow quit ${workflowId}\` to pause the run for later resume.`,
-	};
-}
-
-/**
- * True when the live run store has an actively-executing (not ended, not quit)
- * run for `workflowId`. This is the only reliable signal that a durable
- * `running` handle is genuinely live in THIS process — distinguishing a real
- * double-resume from cross-session crash recovery.
- */
-function hasActiveLiveRun(store: RunOpts["store"] | undefined, workflowId: string): boolean {
-	if (store === undefined) return false;
-	return store.runs().some((r) => r.id === workflowId && r.endedAt === undefined && r.exitReason !== "quit");
-}
-
-/** Remove local snapshots that do not exist as valid current DBOS workflows. */
-export function purgeSuppressedWorkflowRuns(
-	backend: DurableWorkflowBackend,
-	store: RunOpts["store"],
-): readonly string[] {
-	if (store === undefined) return [];
-	const removed: string[] = [];
-	for (const run of store.runs()) {
-		if (backend.isWorkflowLoadable(run.id)) continue;
-		if (store.removeRun(run.id)) removed.push(run.id);
-	}
-	return removed;
-}
-
-/** Hydrate a bounded set of known DBOS workflow ids. */
-export async function prepareTargetedDurableResumable(
-	backend: DurableWorkflowBackend,
-	workflowIds: readonly string[],
-): Promise<readonly ResumableWorkflowEntry[]> {
-	const entries: ResumableWorkflowEntry[] = [];
-	const seen = new Set<string>();
-	for (const workflowId of workflowIds) {
-		if (seen.has(workflowId)) continue;
-		seen.add(workflowId);
-		await backend.hydrateWorkflow(workflowId);
-		const handle = backend.getLoadableWorkflow(workflowId);
-		if (handle === undefined || !isDurableWorkflowResumable(handle)) continue;
-		entries.push(resumableEntryFromHandle(handle));
-	}
-	return entries;
-}
-
-export async function prepareRuntimeDurableResumable(
-	getBackend: () => DurableWorkflowBackend,
-	workflowId?: string,
-): Promise<readonly ResumableWorkflowEntry[]> {
-	const backend = getBackend();
-	await backend.hydrateResumableWorkflows();
-	if (workflowId !== undefined) {
-		const resolved = resolveDurableEntry(workflowId, backend.listResumableWorkflows());
-		if (resolved !== undefined && !("kind" in resolved)) await backend.hydrateWorkflow(resolved.workflowId);
-	}
-	return backend.listResumableWorkflows();
-}

package/dist/builtin/workflows/src/durable/retention-policy.ts

@@ -1,43 +0,0 @@
-import type { DurableWorkflowBackend } from "./backend.js";
-
-export type DurableWorkflowDeleteOutcome =
-	| { readonly ok: true; readonly message: string }
-	| { readonly ok: false; readonly message: string };
-
-/**
- * `/resume` parity keeps every eligible run regardless of age/count and only
- * removes history after an explicit confirmed action. This helper is the
- * workflow-aware deletion gate used after selector confirmation.
- */
-export async function deleteDurableWorkflowIfSafe(
-	backend: DurableWorkflowBackend,
-	workflowId: string,
-	isInFlight: (workflowId: string) => boolean,
-): Promise<DurableWorkflowDeleteOutcome> {
-	if (isInFlight(workflowId)) {
-		return { ok: false, message: "Cannot delete an in-flight workflow run." };
-	}
-	try {
-		const handle = backend.getLoadableWorkflow(workflowId);
-		if (handle === undefined) {
-			return { ok: false, message: "Workflow durable state is stale or no longer available." };
-		}
-		if (handle.status === "running") {
-			return { ok: false, message: "Cannot delete a workflow marked running; it may be active in another process." };
-		}
-		const result = await backend.deleteWorkflowIfInactive(workflowId);
-		if (!result.ok) {
-			return {
-				ok: false,
-				message:
-					result.reason === "running"
-						? "Cannot delete a workflow that became active while deletion was pending."
-						: "Workflow durable state is stale or no longer available.",
-			};
-		}
-		return { ok: true, message: "Workflow durable history deleted; retained session transcripts were not removed." };
-	} catch (error) {
-		const detail = error instanceof Error ? error.message : String(error);
-		return { ok: false, message: `Failed to delete workflow durable history: ${detail}` };
-	}
-}

package/dist/builtin/workflows/src/durable/run-timing.ts

@@ -1,151 +0,0 @@
-/**
- * Durable run-level elapsed-time checkpoints.
- *
- * Persists the total accumulated elapsed time of a top-level workflow run so a
- * durable `/workflow resume` can seed the new `RunSnapshot` with the prior
- * elapsed time — the main-chat dashboard total then reports prior + current
- * elapsed instead of restarting at zero.
- *
- * Storage shape: a reserved tool-kind checkpoint (name/argsHash
- * `workflow-run-timing`). Tool checkpoints round-trip through the DBOS
- * envelope untouched and are ignored by stage-graph reconstruction, so no
- * phantom stages appear in durable inspection. Repeated updates use distinct
- * checkpoint ids; the latest record (by `completedAt`) wins on hydration
- * because the in-memory mirror replays checkpoints in completion order.
- *
- * cross-ref: packages/workflows/src/shared/timing.ts elapsedRunMs
- */
-
-import { restoreBudgetState } from "../shared/persistence-restore-helpers.js";
-import type { RunBudgetAccountingState, RunSnapshot } from "../shared/store-types.js";
-import { elapsedRunMs } from "../shared/timing.js";
-import type { DurableWorkflowBackend } from "./backend.js";
-import { durableHash } from "./durable-hash.js";
-import type { DurableToolCheckpoint } from "./types.js";
-
-/** Reserved checkpoint names AND args-hashes for run-level meter records. */
-export const RUN_TIMING_CHECKPOINT_NAME = "workflow-run-timing";
-export const RUN_USAGE_CHECKPOINT_NAME = "workflow-run-usage";
-
-/**
- * Debounce granularity for run-timing updates, matching the stage-session
- * duration bucket so piggybacked writes never outpace stage checkpoints.
- */
-export const RUN_TIMING_DURATION_BUCKET_MS = 30_000;
-
-function timingBucket(elapsedMs: number): number {
-	return Math.floor(elapsedMs / RUN_TIMING_DURATION_BUCKET_MS);
-}
-
-/** Prior accumulated run elapsed recorded durably, or undefined when absent. */
-export function priorRunElapsedMs(backend: DurableWorkflowBackend, workflowId: string): number | undefined {
-	const output = backend.getToolOutput(workflowId, RUN_TIMING_CHECKPOINT_NAME);
-	if (typeof output !== "object" || output === null || Array.isArray(output)) return undefined;
-	const elapsedMs = (output as Record<string, unknown>).elapsedMs;
-	if (typeof elapsedMs !== "number" || !Number.isFinite(elapsedMs) || elapsedMs <= 0) return undefined;
-	return elapsedMs;
-}
-
-/** Prior token/cost accounting recorded durably, or undefined when absent/malformed. */
-export function priorRunAccounting(
-	backend: DurableWorkflowBackend,
-	workflowId: string,
-): RunBudgetAccountingState | undefined {
-	const output = backend.getToolOutput(workflowId, RUN_USAGE_CHECKPOINT_NAME);
-	if (typeof output !== "object" || output === null || Array.isArray(output)) return undefined;
-	return restoreBudgetState({ accounting: (output as Record<string, unknown>).accounting })?.accounting;
-}
-/**
- * Record the run's current total elapsed time (prior + this session) durably.
- *
- * Skipped when the workflow has no durable progress yet (a timing record with
- * nothing to resume would only manufacture resumability), when the elapsed
- * value did not grow past the last record, or — with `debounce` — while the
- * value stays inside the last 30 s bucket. Usage shares only the progress guard.
- */
-export function recordRunTimingCheckpoint(
-	backend: DurableWorkflowBackend,
-	run: RunSnapshot,
-	options?: { readonly debounce?: boolean; readonly now?: number },
-): boolean {
-	const checkpoints = [runTimingCheckpoint(backend, run, options), runUsageCheckpoint(backend, run, options?.now)];
-	if (checkpoints.every((checkpoint) => checkpoint === undefined)) return false;
-	for (const checkpoint of checkpoints) if (checkpoint !== undefined) backend.recordCheckpoint(checkpoint);
-	return true;
-}
-
-/** Await the timing and usage writes so an active turn observes persistent storage faults at once. */
-export async function recordRunTimingCheckpointAsync(
-	backend: DurableWorkflowBackend,
-	run: RunSnapshot,
-	options?: { readonly debounce?: boolean; readonly now?: number },
-): Promise<boolean> {
-	const checkpoints = [runTimingCheckpoint(backend, run, options), runUsageCheckpoint(backend, run, options?.now)];
-	if (checkpoints.every((checkpoint) => checkpoint === undefined)) return false;
-	for (const checkpoint of checkpoints) if (checkpoint !== undefined) await backend.recordCheckpointAsync(checkpoint);
-	return true;
-}
-
-function runTimingCheckpoint(
-	backend: DurableWorkflowBackend,
-	run: RunSnapshot,
-	options?: { readonly debounce?: boolean; readonly now?: number },
-): DurableToolCheckpoint | undefined {
-	const now = options?.now ?? Date.now();
-	const elapsedMs = elapsedRunMs(run, now);
-	if (elapsedMs <= 0) return undefined;
-	if (backend.listCheckpoints(run.id).length === 0) return undefined;
-	const recorded = priorRunElapsedMs(backend, run.id);
-	if (recorded !== undefined) {
-		if (elapsedMs <= recorded) return undefined;
-		if (options?.debounce === true && timingBucket(elapsedMs) === timingBucket(recorded)) return undefined;
-	}
-	return {
-		kind: "tool",
-		workflowId: run.id,
-		checkpointId: `run-timing:${elapsedMs}`,
-		name: RUN_TIMING_CHECKPOINT_NAME,
-		argsHash: RUN_TIMING_CHECKPOINT_NAME,
-		output: { elapsedMs },
-		completedAt: now,
-	};
-}
-function runUsageCheckpoint(
-	backend: DurableWorkflowBackend,
-	run: RunSnapshot,
-	now = Date.now(),
-): DurableToolCheckpoint | undefined {
-	const accounting = run.budgetState?.accounting;
-	if (accounting === undefined || backend.listCheckpoints(run.id).length === 0) return undefined;
-	const checkpointId = `run-usage:${durableHash({ accounting })}`;
-	if (backend.getToolCheckpoint(run.id, RUN_USAGE_CHECKPOINT_NAME)?.checkpointId === checkpointId) return undefined;
-	return {
-		kind: "tool",
-		workflowId: run.id,
-		checkpointId,
-		name: RUN_USAGE_CHECKPOINT_NAME,
-		argsHash: RUN_USAGE_CHECKPOINT_NAME,
-		output: { accounting },
-		completedAt: now,
-	};
-}
-
-/**
- * Elapsed time a freshly-created run inherits from its predecessor:
- * continuation resumes measure the live source snapshot; durable re-dispatch
- * resumes (same run id, no continuation) read the persisted timing record.
- */
-export function inheritedRunElapsedMs(input: {
-	readonly backend: DurableWorkflowBackend;
-	readonly runId: string;
-	readonly continuationSource?: RunSnapshot;
-	readonly now?: number;
-}): number | undefined {
-	const now = input.now ?? Date.now();
-	const source = input.continuationSource;
-	const inherited =
-		source !== undefined
-			? elapsedRunMs(source, source.endedAt ?? now)
-			: priorRunElapsedMs(input.backend, input.runId);
-	return inherited !== undefined && inherited > 0 ? inherited : undefined;
-}