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

package/dist/builtin/workflows/src/runs/background/cancellation-registry.ts

@@ -1,135 +0,0 @@
-/**
- * CancellationRegistry — tracks active run AbortControllers and children.
- *
- * Responsibilities:
- *   - register(runId, controller)        — attach primary controller for a run
- *   - registerChild(runId, controller)   — attach a subordinate controller
- *   - abort(runId, reason)               — abort primary + all children, returns true if found
- *   - abortAll(reason)                   — abort every registered run, returns count aborted
- *   - unregister(runId)                  — remove run from registry (after run ends)
- *   - isAborted(runId)                   — true if run's primary controller was aborted
- *
- * Does NOT kill processes; only signals abort to registered controllers.
- * cross-ref: spec §8.1 Phase D (kill-runtime-wiring downstream)
- */
-
-import { createSessionScopedSingleton } from "../../shared/session-scoped-singleton.js";
-
-// ---------------------------------------------------------------------------
-// Types
-// ---------------------------------------------------------------------------
-
-export interface ActiveRunEntry {
-	readonly controller: AbortController;
-	readonly children: 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;
-	/**
-	 * Remove a run's registration.
-	 *
-	 * When `expectedController` is supplied the entry is removed only if it is
-	 * still the registered primary, so a stale executor's finalizer cannot evict
-	 * the replacement that now owns this run id. Returns true when it removed.
-	 */
-	unregister(runId: string, expectedController?: AbortController): boolean;
-	isAborted(runId: string): boolean;
-}
-
-// ---------------------------------------------------------------------------
-// Implementation
-// ---------------------------------------------------------------------------
-
-class CancellationRegistryImpl implements CancellationRegistry {
-	private readonly _runs = new Map<string, ActiveRunEntry>();
-
-	register(runId: string, controller: AbortController): void {
-		// If already registered, replace (unregister old entry first without aborting)
-		const existing = this._runs.get(runId);
-		if (existing) {
-			// Preserve children when re-registering same runId
-			this._runs.set(runId, { controller, children: existing.children });
-		} else {
-			this._runs.set(runId, { controller, children: [] });
-		}
-	}
-
-	registerChild(runId: string, controller: AbortController): void {
-		const entry = this._runs.get(runId);
-		if (!entry) {
-			// No primary controller yet — create a placeholder entry with no primary
-			// so children can still be tracked. Callers should call register() first.
-			// Strict: throw to surface misuse.
-			throw new Error(
-				`CancellationRegistry: cannot registerChild for unknown runId "${runId}". Call register() first.`,
-			);
-		}
-		entry.children.push(controller);
-	}
-
-	abort(runId: string, reason?: unknown): boolean {
-		const entry = this._runs.get(runId);
-		if (!entry) return false;
-
-		// Abort children first, then primary
-		for (const child of entry.children) {
-			if (!child.signal.aborted) {
-				child.abort(reason);
-			}
-		}
-		if (!entry.controller.signal.aborted) {
-			entry.controller.abort(reason);
-		}
-		return true;
-	}
-
-	abortAll(reason?: unknown): number {
-		let count = 0;
-		for (const runId of this._runs.keys()) {
-			if (this.abort(runId, reason)) count++;
-		}
-		return count;
-	}
-
-	unregister(runId: string, expectedController?: AbortController): boolean {
-		const entry = this._runs.get(runId);
-		if (entry === undefined) return false;
-		if (expectedController !== undefined && entry.controller !== expectedController) return false;
-		this._runs.delete(runId);
-		return true;
-	}
-
-	isAborted(runId: string): boolean {
-		const entry = this._runs.get(runId);
-		if (!entry) return false;
-		return entry.controller.signal.aborted;
-	}
-}
-
-// ---------------------------------------------------------------------------
-// Factory + singleton
-// ---------------------------------------------------------------------------
-
-/**
- * Create an isolated CancellationRegistry instance (useful for testing).
- */
-export function createCancellationRegistry(): CancellationRegistry {
-	return new CancellationRegistryImpl();
-}
-
-/**
- * Singleton registry for the default runtime. Consumers needing isolation
- * should call createCancellationRegistry() instead.
- */
-const SESSION_KEY = "workflows:cancellation:v1";
-const singleton = createSessionScopedSingleton(SESSION_KEY, createCancellationRegistry);
-
-export const cancellationRegistry: CancellationRegistry = singleton.facade;
-
-export function adoptCancellationRegistry(scope: object): CancellationRegistry {
-	return singleton.adopt(scope);
-}

package/dist/builtin/workflows/src/runs/background/durable-resume-transition.ts

@@ -1,63 +0,0 @@
-import type { DurableWorkflowBackend } from "../../durable/backend.js";
-import { getDurableBackend } from "../../durable/factory.js";
-import {
-	getLoadableDurableWorkflow,
-	transitionDurableWorkflowStatus,
-} from "../../durable/workflow-status-transition.js";
-
-const pendingRunningTransitions = new WeakMap<DurableWorkflowBackend, Set<string>>();
-
-export type DurableResumeTransitionOutcome = "transitioned" | "not_needed" | "refused";
-
-function transitionsFor(backend: DurableWorkflowBackend): Set<string> {
-	let transitions = pendingRunningTransitions.get(backend);
-	if (transitions === undefined) {
-		transitions = new Set();
-		pendingRunningTransitions.set(backend, transitions);
-	}
-	return transitions;
-}
-
-/** Whether a previous visible resume still needs its durable running write. */
-export function hasPendingDurableResumeTransition(runId: string): boolean {
-	return pendingRunningTransitions.get(getDurableBackend())?.has(runId) ?? false;
-}
-
-/** Persist and flush the root running transition after visible local resume. */
-export async function markDurableResumed(runId: string): Promise<DurableResumeTransitionOutcome> {
-	const backend = getDurableBackend();
-	const pending = transitionsFor(backend);
-	const handle = getLoadableDurableWorkflow(backend, runId);
-	if (handle === undefined) {
-		pending.delete(runId);
-		return "not_needed";
-	}
-	if (!pending.has(runId) && handle.status === "running") return "not_needed";
-	if (!pending.has(runId) && handle.status !== "paused") return "refused";
-	if (pending.has(runId) && handle.status !== "paused" && handle.status !== "running") {
-		pending.delete(runId);
-		return "refused";
-	}
-	pending.add(runId);
-	try {
-		// Reissue even when an earlier failed flush already changed the local
-		// mirror to running. Persistent backends need a new queued write to retry.
-		const transitioned = await transitionDurableWorkflowStatus(
-			backend,
-			runId,
-			pending.has(runId) ? ["paused", "running"] : ["paused"],
-			"running",
-		);
-		if (!transitioned) {
-			pending.delete(runId);
-			const authoritative = getLoadableDurableWorkflow(backend, runId);
-			return authoritative?.status === "running" ? "not_needed" : "refused";
-		}
-		await backend.flush();
-		pending.delete(runId);
-		return "transitioned";
-	} catch (error) {
-		const detail = error instanceof Error ? error.message : String(error);
-		throw new Error(`Failed to persist resumed workflow ${runId}: ${detail}`);
-	}
-}

package/dist/builtin/workflows/src/runs/background/job-tracker.ts

@@ -1,125 +0,0 @@
-/**
- * JobTracker — in-memory registry of live background run promises and
- * their AbortControllers.
- *
- * Source of truth for run snapshots/status remains the store.
- * JobTracker only holds the live Promise and AbortController so callers
- * can await completion or cancel without going through the store.
- *
- * cross-ref: spec detached-runner §job-tracker
- */
-
-import { createSessionScopedSingleton } from "../../shared/session-scoped-singleton.js";
-
-// ---------------------------------------------------------------------------
-// Types
-// ---------------------------------------------------------------------------
-
-export interface JobEntry {
-	readonly runId: string;
-	readonly controller: AbortController;
-	/** Settles when the background run resolves or rejects. */
-	readonly promise: Promise<void>;
-}
-
-export interface JobTracker {
-	/**
-	 * Register a background job. `promise` must be the background run promise
-	 * (already void-cast; all rejections must be handled before registering).
-	 *
-	 * Registering over a still-active entry is a programming error: it would
-	 * silently double-dispatch one run id. Detach the stale entry first.
-	 */
-	register(entry: JobEntry): void;
-	/**
-	 * Remove a job from the tracker (called on settle).
-	 *
-	 * When `expected` is supplied the entry is removed only if it is still the
-	 * tracked one, so a stale executor settling late cannot evict the
-	 * replacement that now owns this run id. Returns true when it removed.
-	 */
-	unregister(runId: string, expected?: JobEntry): boolean;
-	/**
-	 * Detach an abandoned entry from active-job lookup without cancelling or
-	 * awaiting its promise.
-	 *
-	 * A quit that abandoned a callback leaves that executor alive but no longer
-	 * authoritative: resume must be free to relaunch under the same run id.
-	 */
-	detach(runId: string, expected?: JobEntry): JobEntry | undefined;
-	/** True if a live job exists for this runId. */
-	has(runId: string): boolean;
-	/** Return entry or undefined. */
-	get(runId: string): JobEntry | undefined;
-	/** All currently tracked runIds. */
-	runIds(): string[];
-}
-
-// ---------------------------------------------------------------------------
-// Implementation
-// ---------------------------------------------------------------------------
-
-class JobTrackerImpl implements JobTracker {
-	private readonly _jobs = new Map<string, JobEntry>();
-
-	register(entry: JobEntry): void {
-		const existing = this._jobs.get(entry.runId);
-		if (existing !== undefined && existing !== entry) {
-			throw new Error(
-				`atomic-workflows: a background job is already registered for run ${entry.runId}; detach the abandoned job before relaunching it`,
-			);
-		}
-		this._jobs.set(entry.runId, entry);
-	}
-
-	unregister(runId: string, expected?: JobEntry): boolean {
-		const existing = this._jobs.get(runId);
-		if (existing === undefined) return false;
-		if (expected !== undefined && existing !== expected) return false;
-		this._jobs.delete(runId);
-		return true;
-	}
-
-	detach(runId: string, expected?: JobEntry): JobEntry | undefined {
-		const existing = this._jobs.get(runId);
-		if (existing === undefined) return undefined;
-		if (expected !== undefined && existing !== expected) return undefined;
-		this._jobs.delete(runId);
-		return existing;
-	}
-
-	has(runId: string): boolean {
-		return this._jobs.has(runId);
-	}
-
-	get(runId: string): JobEntry | undefined {
-		return this._jobs.get(runId);
-	}
-
-	runIds(): string[] {
-		return Array.from(this._jobs.keys());
-	}
-}
-
-// ---------------------------------------------------------------------------
-// Factory + singleton
-// ---------------------------------------------------------------------------
-
-/**
- * Create an isolated JobTracker instance (useful for testing).
- */
-export function createJobTracker(): JobTracker {
-	return new JobTrackerImpl();
-}
-
-/**
- * Singleton tracker for the default runtime.
- */
-const SESSION_KEY = "workflows:job-tracker:v1";
-const singleton = createSessionScopedSingleton(SESSION_KEY, createJobTracker);
-
-export const jobTracker: JobTracker = singleton.facade;
-
-export function adoptJobTracker(scope: object): JobTracker {
-	return singleton.adopt(scope);
-}

package/dist/builtin/workflows/src/runs/background/quit-tool-node.ts

@@ -1,71 +0,0 @@
-/**
- * Targeted abort for a single in-flight `ctx.tool` graph node.
- *
- * This is the tool-node counterpart to interrupting one rogue stage: the node's
- * own controller is aborted, sibling stages and sibling tool nodes keep running,
- * and the run is not paused. The aborted call writes no replayable checkpoint,
- * so a later resume re-executes exactly that callback at the same ordinal.
- *
- * cross-ref: issue #2078.
- */
-
-import {
-	toolControlRegistry as defaultToolControlRegistry,
-	settleAbortedToolNodes,
-	TOOL_QUIT_SETTLEMENT_TIMEOUT_MS,
-	type ToolControlRegistry,
-} from "../../engine/run-tool-control-registry.js";
-import { store as defaultStore } from "../../shared/store.js";
-import type { Store } from "../../shared/store-public-types.js";
-import type { ToolNodeSnapshot } from "../../shared/store-types.js";
-
-export type ToolNodeAbortResult =
-	| {
-			readonly ok: true;
-			readonly runId: string;
-			readonly nodeId: string;
-			readonly name: string;
-			/** The cancelled node once it settled, when the store still retains it. */
-			readonly cancelled?: ToolNodeSnapshot;
-			/** True when the callback ignored its signal within the bounded wait. */
-			readonly abandoned: boolean;
-	  }
-	| { readonly ok: false; readonly runId: string; readonly nodeId: string; readonly reason: "not_running" };
-
-/**
- * Abort one in-flight tool node and wait a bounded interval for its callback.
- *
- * `action` only picks the wording of the abort reason; both `quit` and
- * `interrupt` on a tool node mean the same thing — stop this call now.
- */
-export async function abortToolNode(
-	runId: string,
-	nodeId: string,
-	opts?: { store?: Store; toolControlRegistry?: ToolControlRegistry },
-): Promise<ToolNodeAbortResult> {
-	const activeStore = opts?.store ?? defaultStore;
-	const toolControls = opts?.toolControlRegistry ?? defaultToolControlRegistry;
-	const handle = toolControls.get(runId, nodeId);
-	if (handle === undefined) return { ok: false, runId, nodeId, reason: "not_running" };
-	handle.abort("node");
-	const abandoned = (await settleAbortedToolNodes([handle], TOOL_QUIT_SETTLEMENT_TIMEOUT_MS)).length > 0;
-	if (abandoned) {
-		activeStore.recordToolNodeEnd(runId, nodeId, {
-			status: "cancelled",
-			endedAt: Date.now(),
-			error: `atomic-workflows: ctx.tool ${handle.name} abandoned after abort; the callback ignored its abort signal`,
-		});
-	}
-	const cancelled = activeStore
-		.runs()
-		.find((candidate) => candidate.id === runId)
-		?.toolNodes?.find((candidate) => candidate.id === nodeId);
-	return {
-		ok: true,
-		runId,
-		nodeId,
-		name: handle.name,
-		...(cancelled === undefined ? {} : { cancelled: structuredClone(cancelled) }),
-		abandoned,
-	};
-}