@orkestrel/workflow 0.0.10 → 0.0.12

package/dist/src/core/index.js

@@ -1,4 +1,4 @@
-import { createAbort, linkSignal } from "@orkestrel/abort";
+import { createAbort, isAbortSignal, linkSignal } from "@orkestrel/abort";
 import { arrayShape, attempt, cloneJSONRecord, cloneJSONValue, compileGuard, createContract, integerShape, isArray, isBoolean, isContractError, isFiniteNumber, isFunction, isInteger, isJSONValue, isNonEmptyString, isRecord, literalShape, objectShape, optionalShape, rawShape, stringShape } from "@orkestrel/contract";
 import { createDatabase, createMemoryDriver } from "@orkestrel/database";
 import { Emitter } from "@orkestrel/emitter";
@@ -109,6 +109,204 @@ var DEFAULT_PHASE_CONCURRENCY = 1024;
 */
 var MAX_TIMER_MS = 2147483647;
 //#endregion
+//#region src/core/errors.ts
+/**
+* An error raised by the workflow runtime.
+*
+* @remarks
+* Carries a {@link WorkflowErrorCode} and an optional `context` bag naming the
+* offending node id / status / parameter. Raised for an illegal lifecycle transition
+* (`TRANSITION`), a structurally invalid {@link import('./types.js').WorkflowSnapshot}
+* boundary (`RESTORE`), a refused structural/activity edit (`MUTATION`), or a host
+* schedule refused before arming because the caller's `signal` is not a native
+* `AbortSignal` (`SCHEDULE`, delivered as a rejected promise).
+*/
+var WorkflowError = class extends Error {
+	code;
+	context;
+	constructor(code, message, context) {
+		super(message);
+		this.name = "WorkflowError";
+		this.code = code;
+		if (context !== void 0) this.context = context;
+	}
+};
+/**
+* Narrow an unknown caught value to a {@link WorkflowError}.
+*
+* @param value - The value to test (typically a `catch` binding)
+* @returns `true` when `value` is a {@link WorkflowError}
+*
+* @example
+* ```ts
+* try {
+* 	task.complete('done')
+* } catch (error) {
+* 	if (isWorkflowError(error) && error.code === 'TRANSITION') retry()
+* }
+* ```
+*/
+function isWorkflowError(value) {
+	try {
+		return value instanceof WorkflowError;
+	} catch {
+		return false;
+	}
+}
+//#endregion
+//#region src/core/validators.ts
+/** Test the workflow lifecycle vocabulary. */
+function isLifecycleStatus(value) {
+	return value === "pending" || value === "running" || value === "completed" || value === "failed" || value === "skipped" || value === "stopped";
+}
+/** Test a normalized persisted task failure. */
+function isTaskFailure(value) {
+	try {
+		return isRecord(value) && Object.keys(value).every((key) => key === "origin" || key === "message") && (value.origin === "handler" || value.origin === "timeout" || value.origin === "recovery") && isNonEmptyString(value.message);
+	} catch {
+		return false;
+	}
+}
+/**
+* Validate a safe owned JSON graph as a coherent workflow snapshot.
+*
+* @remarks
+* Callers at hostile boundaries use {@link isWorkflowSnapshot}, which owns the
+* graph first so this semantic pass never observes accessors or prototypes.
+*/
+function isOwnedWorkflowSnapshot(value) {
+	try {
+		if (!isRecord(value) || !Object.keys(value).every((key) => key === "id" || key === "name" || key === "description" || key === "status" || key === "override" || key === "bail" || key === "phases" || key === "created" || key === "updated") || !isNonEmptyString(value.id) || !isNonEmptyString(value.name) || value.description !== void 0 && typeof value.description !== "string" || !isLifecycleStatus(value.status) || value.override !== void 0 && value.override !== "completed" && value.override !== "skipped" && value.override !== "stopped" || !isBoolean(value.bail) || !isArray(value.phases) || !isFiniteNumber(value.created) || value.created < 0 || !isFiniteNumber(value.updated) || value.updated < value.created) return false;
+		const phaseIds = /* @__PURE__ */ new Set();
+		const derivations = [];
+		let frontier = false;
+		let running = false;
+		let vacuous = true;
+		for (const phase of value.phases) {
+			if (!isRecord(phase) || !Object.keys(phase).every((key) => key === "id" || key === "name" || key === "description" || key === "status" || key === "override" || key === "bail" || key === "concurrency" || key === "tasks") || !isNonEmptyString(phase.id) || phaseIds.has(phase.id) || !isNonEmptyString(phase.name) || phase.description !== void 0 && typeof phase.description !== "string" || !isLifecycleStatus(phase.status) || phase.override !== void 0 && phase.override !== "skipped" && phase.override !== "stopped" || !isBoolean(phase.bail) || phase.concurrency !== void 0 && (!isInteger(phase.concurrency) || phase.concurrency < 1) || !isArray(phase.tasks)) return false;
+			const forced = phase.override === "skipped" || phase.override === "stopped";
+			const started = phase.status === "running" || phase.status === "completed" || phase.status === "failed";
+			if (!forced && frontier && started || phase.status === "running" && running) return false;
+			if (phase.status === "running") running = true;
+			if (!forced && (phase.status === "pending" || phase.status === "running" || phase.status === "failed" && phase.bail)) frontier = true;
+			phaseIds.add(phase.id);
+			const taskIds = /* @__PURE__ */ new Set();
+			const statuses = [];
+			if (phase.tasks.length > 0) vacuous = false;
+			for (const task of phase.tasks) {
+				if (!isRecord(task) || !Object.keys(task).every((key) => key === "id" || key === "name" || key === "description" || key === "status" || key === "result" || key === "metadata" || key === "attempts" || key === "run" || key === "retries" || key === "timeout" || key === "activity") || !isNonEmptyString(task.id) || taskIds.has(task.id) || !isNonEmptyString(task.name) || task.description !== void 0 && typeof task.description !== "string" || !isLifecycleStatus(task.status) || !isRecord(task.metadata) || !isJSONValue(task.metadata) || !isInteger(task.attempts) || task.attempts < 0 || task.run !== void 0 && !isNonEmptyString(task.run) || task.retries !== void 0 && (!isInteger(task.retries) || task.retries < 0) || task.timeout !== void 0 && (!isInteger(task.timeout) || task.timeout < 0 || task.timeout > 2147483647)) return false;
+				const budget = (task.retries ?? 0) + 1;
+				if (task.attempts > budget || task.status === "pending" && task.attempts >= budget) return false;
+				if (!(task.activity === void 0 || isTaskActivity(task.activity))) return false;
+				if (task.status === "running" || task.status === "completed" || task.status === "failed") {
+					if (task.attempts < 1 || task.activity === void 0) return false;
+				}
+				if (task.status === "pending" && task.activity !== void 0) return false;
+				if (task.status === "completed" || task.status === "failed") {
+					if (!isTaskResult(task.result, value, phase, task)) return false;
+				} else if (task.result !== void 0) return false;
+				taskIds.add(task.id);
+				statuses.push(task.status);
+			}
+			const derived = derivePhaseStatus(statuses);
+			if (phase.status !== (phase.override ?? derived) || phase.override !== void 0 && phase.status !== phase.override) return false;
+			derivations.push({
+				status: phase.status,
+				bail: phase.bail
+			});
+		}
+		const derived = deriveWorkflowStatus(derivations);
+		if (value.override === "completed") return value.status === "completed" && derived === "pending" && vacuous;
+		return value.status === (value.override ?? derived);
+	} catch {
+		return false;
+	}
+}
+/** Total hostile-boundary workflow snapshot guard. */
+function isWorkflowSnapshot(value) {
+	const cloned = attempt(() => cloneJSONValue(value));
+	return cloned.success && isOwnedWorkflowSnapshot(cloned.value);
+}
+/**
+* Test whether an unknown value is a valid whole-frame activity report.
+*/
+function isTaskActivityInput(value) {
+	try {
+		if (!isRecord(value)) return false;
+		const prototype = Object.getPrototypeOf(value);
+		if (prototype !== Object.prototype && prototype !== null || !Object.keys(value).every((key) => key === "note" || key === "progress" || key === "operations" || key === "constraints")) return false;
+		const note = value.note;
+		const progress = value.progress;
+		const operations = value.operations;
+		const constraints = value.constraints;
+		if (note !== void 0 && !isNonEmptyString(note)) return false;
+		if (progress !== void 0) {
+			if (!isRecord(progress)) return false;
+			const progressPrototype = Object.getPrototypeOf(progress);
+			if (progressPrototype !== Object.prototype && progressPrototype !== null || !Object.keys(progress).every((key) => key === "current" || key === "total" || key === "unit")) return false;
+			const current = progress.current;
+			const total = progress.total;
+			const unit = progress.unit;
+			if (!isFiniteNumber(current) || current < 0 || total !== void 0 && (!isFiniteNumber(total) || total < current) || unit !== void 0 && !isNonEmptyString(unit)) return false;
+		}
+		if (operations !== void 0) {
+			if (!isArray(operations)) return false;
+			const ids = /* @__PURE__ */ new Set();
+			for (const operation of operations) {
+				if (!isRecord(operation)) return false;
+				const operationPrototype = Object.getPrototypeOf(operation);
+				if (operationPrototype !== Object.prototype && operationPrototype !== null || !Object.keys(operation).every((key) => key === "id" || key === "name" || key === "started")) return false;
+				const id = operation.id;
+				const name = operation.name;
+				const started = operation.started;
+				if (!isNonEmptyString(id) || !isNonEmptyString(name) || !isFiniteNumber(started) || started < 0 || ids.has(id)) return false;
+				ids.add(id);
+			}
+		}
+		if (constraints !== void 0) {
+			if (!isArray(constraints)) return false;
+			const ids = /* @__PURE__ */ new Set();
+			for (const constraint of constraints) {
+				if (!isRecord(constraint)) return false;
+				const constraintPrototype = Object.getPrototypeOf(constraint);
+				if (constraintPrototype !== Object.prototype && constraintPrototype !== null || !Object.keys(constraint).every((key) => key === "id" || key === "name" || key === "started")) return false;
+				const id = constraint.id;
+				const name = constraint.name;
+				const started = constraint.started;
+				if (!isNonEmptyString(id) || !isNonEmptyString(name) || !isFiniteNumber(started) || started < 0 || ids.has(id)) return false;
+				ids.add(id);
+			}
+		}
+		return true;
+	} catch {
+		return false;
+	}
+}
+/**
+* Test whether an unknown value is valid persisted task activity.
+*/
+function isTaskActivity(value) {
+	try {
+		if (!isRecord(value)) return false;
+		const prototype = Object.getPrototypeOf(value);
+		if (prototype !== Object.prototype && prototype !== null || !Object.keys(value).every((key) => key === "note" || key === "progress" || key === "operations" || key === "constraints" || key === "updated")) return false;
+		const note = value.note;
+		const progress = value.progress;
+		const operations = value.operations;
+		const constraints = value.constraints;
+		const updated = value.updated;
+		if (operations === void 0 || constraints === void 0 || !isFiniteNumber(updated) || updated < 0) return false;
+		return isTaskActivityInput({
+			...note === void 0 ? {} : { note },
+			...progress === void 0 ? {} : { progress },
+			operations,
+			constraints
+		});
+	} catch {
+		return false;
+	}
+}
+//#endregion
 //#region src/core/helpers.ts
 /**
 * Capture every top-level {@link WorkflowOptions} value exactly once into an owned plain bag.
@@ -582,6 +780,53 @@ function recoverWorkflowSnapshot(snapshot) {
 		updated: now
 	};
 }
+/** Compare two optional description values. */
+function matchesDescription(left, right) {
+	return left === right && (left === void 0 || typeof left === "string");
+}
+/** Test a result's lineage against its containing snapshot nodes. */
+function isTaskResult(value, workflow, phase, task) {
+	try {
+		if (!isRecord(value) || !isRecord(workflow) || !isRecord(phase) || !isRecord(task) || !Object.keys(value).every((key) => key === "task" || key === "phase" || key === "workflow" || key === "status" || key === "result" || key === "timestamp") || !isLifecycleStatus(value.status) || value.status !== task.status || !isFiniteNumber(value.timestamp) || value.timestamp < 0 || !isRecord(value.task) || !isRecord(value.phase) || !isRecord(value.workflow) || !Object.keys(value.workflow).every((key) => key === "id" || key === "name" || key === "description") || !Object.keys(value.phase).every((key) => key === "id" || key === "name" || key === "description" || key === "workflow") || !Object.keys(value.task).every((key) => key === "id" || key === "name" || key === "description" || key === "phase")) return false;
+		if (value.task.id !== task.id || value.task.name !== task.name || !matchesDescription(value.task.description, task.description) || value.phase.id !== phase.id || value.phase.name !== phase.name || !matchesDescription(value.phase.description, phase.description) || value.workflow.id !== workflow.id || value.workflow.name !== workflow.name || !matchesDescription(value.workflow.description, workflow.description)) return false;
+		if (!isRecord(value.task.phase) || !isRecord(value.task.phase.workflow) || !isRecord(value.phase.workflow) || !Object.keys(value.task.phase).every((key) => key === "id" || key === "name" || key === "description" || key === "workflow") || !Object.keys(value.task.phase.workflow).every((key) => key === "id" || key === "name" || key === "description") || !Object.keys(value.phase.workflow).every((key) => key === "id" || key === "name" || key === "description")) return false;
+		if (value.task.phase.id !== phase.id || value.task.phase.name !== phase.name || !matchesDescription(value.task.phase.description, phase.description) || value.phase.workflow.id !== workflow.id || value.phase.workflow.name !== workflow.name || !matchesDescription(value.phase.workflow.description, workflow.description) || value.task.phase.workflow.id !== workflow.id || value.task.phase.workflow.name !== workflow.name || !matchesDescription(value.task.phase.workflow.description, workflow.description)) return false;
+		if (value.status === "completed") return isRecord(value.result) && value.result.success === true && Object.keys(value.result).every((key) => key === "success" || key === "value") && isJSONValue(value.result.value);
+		if (value.status === "failed") return isRecord(value.result) && value.result.success === false && Object.keys(value.result).every((key) => key === "success" || key === "error") && isTaskFailure(value.result.error);
+		return false;
+	} catch {
+		return false;
+	}
+}
+function hasWorkflowHandlers(workflow, functions) {
+	if ("destroyed" in workflow) {
+		for (const phase of workflow.phases.phases()) for (const task of phase.tasks.tasks()) if (task.run !== void 0 && !isFunction(task.handler)) return false;
+		return true;
+	}
+	const runs = /* @__PURE__ */ new Set();
+	for (const phase of workflow.phases) for (const task of phase.tasks) {
+		if (task.run === void 0 || runs.has(task.run)) continue;
+		runs.add(task.run);
+		if (!isFunction(functions?.[task.run])) return false;
+	}
+	return true;
+}
+/** Locate the nearest identifiable node for an inconsistent owned snapshot. */
+function workflowSnapshotContext(value) {
+	if (!isRecord(value) || !isArray(value.phases)) return void 0;
+	for (const phase of value.phases) {
+		if (!isRecord(phase)) continue;
+		const phaseContext = isNonEmptyString(phase.id) ? { phase: phase.id } : void 0;
+		if (!isBoolean(phase.bail) || phase.concurrency !== void 0 && (!isInteger(phase.concurrency) || phase.concurrency < 1) || !isArray(phase.tasks)) return phaseContext;
+		for (const task of phase.tasks) {
+			if (!isRecord(task)) continue;
+			if (task.run !== void 0 && !isNonEmptyString(task.run) || task.retries !== void 0 && (!isInteger(task.retries) || task.retries < 0) || task.timeout !== void 0 && (!isInteger(task.timeout) || task.timeout < 0 || task.timeout > 2147483647) || !isInteger(task.attempts) || task.attempts < 0) return {
+				...phaseContext ?? {},
+				...isNonEmptyString(task.id) ? { task: task.id } : {}
+			};
+		}
+	}
+}
 /**
 * Flatten a nested list of per-phase {@link TaskResult} lists into one positional list
 * — the workflow tier of the result tree, built from each phase's `results()`.
@@ -671,6 +916,16 @@ function createDeferred() {
 * Schedule one cancellable host operation behind an owned settlement signal.
 *
 * @remarks
+* A defined `signal` that is not a native `AbortSignal` is refused before anything is armed, as a
+* rejected promise carrying a {@link import('./errors.js').WorkflowError} with the `SCHEDULE` code.
+* Rejecting rather than throwing keeps every caller on one settlement path, so a backend never has
+* to guard the call itself.
+*
+* The guard is necessary but not sufficient, so linking stays contained. A `Proxy` over a native
+* signal passes the guard and can still make linking throw from a trap, and that escape would be
+* synchronous — the one shape every caller here is built not to expect. Containment turns it into
+* the same `SCHEDULE` rejection, so setup has exactly one failure shape however hostile the input.
+*
 * The completion and failure paths each own an {@link AbortController}; their native composite is
 * linked to the optional caller signal before `start` can arm host work. Scheduler backends attach
 * only to that safe composite, so caller mutation of `addEventListener` or `removeEventListener`
@@ -682,16 +937,18 @@ function createDeferred() {
 *
 * @param start - Arm host work and return its cancellation closure
 * @param signal - Optional caller cancellation signal
-* @returns A promise settled exactly once by completion, host failure, or caller abort
+* @returns A promise settled exactly once by an invalid-signal refusal, completion, host failure,
+*   or caller abort
 */
 function scheduleHost(start, signal) {
+	if (signal !== void 0 && !isAbortSignal(signal)) return Promise.reject(new WorkflowError("SCHEDULE", "scheduleHost signal must be an AbortSignal", { signal: typeof signal }));
 	const completion = new AbortController();
 	const failed = new AbortController();
 	let settled;
 	try {
 		settled = linkSignal(AbortSignal.any([completion.signal, failed.signal]), signal);
-	} catch (error) {
-		return Promise.reject(error);
+	} catch {
+		return Promise.reject(new WorkflowError("SCHEDULE", "scheduleHost could not link the caller signal", { signal: typeof signal }));
 	}
 	if (settled.aborted) return Promise.reject(settled.reason);
 	return new Promise((resolve, reject) => {
@@ -814,249 +1071,6 @@ var Scheduler = class {
 	}
 };
 //#endregion
-//#region src/core/errors.ts
-/**
-* An error raised by the workflow runtime.
-*
-* @remarks
-* Carries a {@link WorkflowErrorCode} and an optional `context` bag naming the
-* offending node id / status. Raised for an illegal lifecycle transition
-* (`TRANSITION`), a structurally invalid {@link import('./types.js').WorkflowSnapshot}
-* boundary (`RESTORE`), or a refused structural/activity edit (`MUTATION`).
-*/
-var WorkflowError = class extends Error {
-	code;
-	context;
-	constructor(code, message, context) {
-		super(message);
-		this.name = "WorkflowError";
-		this.code = code;
-		if (context !== void 0) this.context = context;
-	}
-};
-/**
-* Narrow an unknown caught value to a {@link WorkflowError}.
-*
-* @param value - The value to test (typically a `catch` binding)
-* @returns `true` when `value` is a {@link WorkflowError}
-*
-* @example
-* ```ts
-* try {
-* 	task.complete('done')
-* } catch (error) {
-* 	if (isWorkflowError(error) && error.code === 'TRANSITION') retry()
-* }
-* ```
-*/
-function isWorkflowError(value) {
-	try {
-		return value instanceof WorkflowError;
-	} catch {
-		return false;
-	}
-}
-//#endregion
-//#region src/core/validators.ts
-/** Test the workflow lifecycle vocabulary. */
-function isLifecycleStatus(value) {
-	return value === "pending" || value === "running" || value === "completed" || value === "failed" || value === "skipped" || value === "stopped";
-}
-/** Test a normalized persisted task failure. */
-function isTaskFailure(value) {
-	try {
-		return isRecord(value) && Object.keys(value).every((key) => key === "origin" || key === "message") && (value.origin === "handler" || value.origin === "timeout" || value.origin === "recovery") && isNonEmptyString(value.message);
-	} catch {
-		return false;
-	}
-}
-/** Compare two optional description values. */
-function matchesDescription(left, right) {
-	return left === right && (left === void 0 || typeof left === "string");
-}
-/** Test a result's lineage against its containing snapshot nodes. */
-function isTaskResult(value, workflow, phase, task) {
-	try {
-		if (!isRecord(value) || !isRecord(workflow) || !isRecord(phase) || !isRecord(task) || !Object.keys(value).every((key) => key === "task" || key === "phase" || key === "workflow" || key === "status" || key === "result" || key === "timestamp") || !isLifecycleStatus(value.status) || value.status !== task.status || !isFiniteNumber(value.timestamp) || value.timestamp < 0 || !isRecord(value.task) || !isRecord(value.phase) || !isRecord(value.workflow) || !Object.keys(value.workflow).every((key) => key === "id" || key === "name" || key === "description") || !Object.keys(value.phase).every((key) => key === "id" || key === "name" || key === "description" || key === "workflow") || !Object.keys(value.task).every((key) => key === "id" || key === "name" || key === "description" || key === "phase")) return false;
-		if (value.task.id !== task.id || value.task.name !== task.name || !matchesDescription(value.task.description, task.description) || value.phase.id !== phase.id || value.phase.name !== phase.name || !matchesDescription(value.phase.description, phase.description) || value.workflow.id !== workflow.id || value.workflow.name !== workflow.name || !matchesDescription(value.workflow.description, workflow.description)) return false;
-		if (!isRecord(value.task.phase) || !isRecord(value.task.phase.workflow) || !isRecord(value.phase.workflow) || !Object.keys(value.task.phase).every((key) => key === "id" || key === "name" || key === "description" || key === "workflow") || !Object.keys(value.task.phase.workflow).every((key) => key === "id" || key === "name" || key === "description") || !Object.keys(value.phase.workflow).every((key) => key === "id" || key === "name" || key === "description")) return false;
-		if (value.task.phase.id !== phase.id || value.task.phase.name !== phase.name || !matchesDescription(value.task.phase.description, phase.description) || value.phase.workflow.id !== workflow.id || value.phase.workflow.name !== workflow.name || !matchesDescription(value.phase.workflow.description, workflow.description) || value.task.phase.workflow.id !== workflow.id || value.task.phase.workflow.name !== workflow.name || !matchesDescription(value.task.phase.workflow.description, workflow.description)) return false;
-		if (value.status === "completed") return isRecord(value.result) && value.result.success === true && Object.keys(value.result).every((key) => key === "success" || key === "value") && isJSONValue(value.result.value);
-		if (value.status === "failed") return isRecord(value.result) && value.result.success === false && Object.keys(value.result).every((key) => key === "success" || key === "error") && isTaskFailure(value.result.error);
-		return false;
-	} catch {
-		return false;
-	}
-}
-/**
-* Validate a safe owned JSON graph as a coherent workflow snapshot.
-*
-* @remarks
-* Callers at hostile boundaries use {@link isWorkflowSnapshot}, which owns the
-* graph first so this semantic pass never observes accessors or prototypes.
-*/
-function isOwnedWorkflowSnapshot(value) {
-	try {
-		if (!isRecord(value) || !Object.keys(value).every((key) => key === "id" || key === "name" || key === "description" || key === "status" || key === "override" || key === "bail" || key === "phases" || key === "created" || key === "updated") || !isNonEmptyString(value.id) || !isNonEmptyString(value.name) || value.description !== void 0 && typeof value.description !== "string" || !isLifecycleStatus(value.status) || value.override !== void 0 && value.override !== "completed" && value.override !== "skipped" && value.override !== "stopped" || !isBoolean(value.bail) || !isArray(value.phases) || !isFiniteNumber(value.created) || value.created < 0 || !isFiniteNumber(value.updated) || value.updated < value.created) return false;
-		const phaseIds = /* @__PURE__ */ new Set();
-		const derivations = [];
-		let frontier = false;
-		let running = false;
-		let vacuous = true;
-		for (const phase of value.phases) {
-			if (!isRecord(phase) || !Object.keys(phase).every((key) => key === "id" || key === "name" || key === "description" || key === "status" || key === "override" || key === "bail" || key === "concurrency" || key === "tasks") || !isNonEmptyString(phase.id) || phaseIds.has(phase.id) || !isNonEmptyString(phase.name) || phase.description !== void 0 && typeof phase.description !== "string" || !isLifecycleStatus(phase.status) || phase.override !== void 0 && phase.override !== "skipped" && phase.override !== "stopped" || !isBoolean(phase.bail) || phase.concurrency !== void 0 && (!isInteger(phase.concurrency) || phase.concurrency < 1) || !isArray(phase.tasks)) return false;
-			const forced = phase.override === "skipped" || phase.override === "stopped";
-			const started = phase.status === "running" || phase.status === "completed" || phase.status === "failed";
-			if (!forced && frontier && started || phase.status === "running" && running) return false;
-			if (phase.status === "running") running = true;
-			if (!forced && (phase.status === "pending" || phase.status === "running" || phase.status === "failed" && phase.bail)) frontier = true;
-			phaseIds.add(phase.id);
-			const taskIds = /* @__PURE__ */ new Set();
-			const statuses = [];
-			if (phase.tasks.length > 0) vacuous = false;
-			for (const task of phase.tasks) {
-				if (!isRecord(task) || !Object.keys(task).every((key) => key === "id" || key === "name" || key === "description" || key === "status" || key === "result" || key === "metadata" || key === "attempts" || key === "run" || key === "retries" || key === "timeout" || key === "activity") || !isNonEmptyString(task.id) || taskIds.has(task.id) || !isNonEmptyString(task.name) || task.description !== void 0 && typeof task.description !== "string" || !isLifecycleStatus(task.status) || !isRecord(task.metadata) || !isJSONValue(task.metadata) || !isInteger(task.attempts) || task.attempts < 0 || task.run !== void 0 && !isNonEmptyString(task.run) || task.retries !== void 0 && (!isInteger(task.retries) || task.retries < 0) || task.timeout !== void 0 && (!isInteger(task.timeout) || task.timeout < 0 || task.timeout > 2147483647)) return false;
-				const budget = (task.retries ?? 0) + 1;
-				if (task.attempts > budget || task.status === "pending" && task.attempts >= budget) return false;
-				if (!(task.activity === void 0 || isTaskActivity(task.activity))) return false;
-				if (task.status === "running" || task.status === "completed" || task.status === "failed") {
-					if (task.attempts < 1 || task.activity === void 0) return false;
-				}
-				if (task.status === "pending" && task.activity !== void 0) return false;
-				if (task.status === "completed" || task.status === "failed") {
-					if (!isTaskResult(task.result, value, phase, task)) return false;
-				} else if (task.result !== void 0) return false;
-				taskIds.add(task.id);
-				statuses.push(task.status);
-			}
-			const derived = derivePhaseStatus(statuses);
-			if (phase.status !== (phase.override ?? derived) || phase.override !== void 0 && phase.status !== phase.override) return false;
-			derivations.push({
-				status: phase.status,
-				bail: phase.bail
-			});
-		}
-		const derived = deriveWorkflowStatus(derivations);
-		if (value.override === "completed") return value.status === "completed" && derived === "pending" && vacuous;
-		return value.status === (value.override ?? derived);
-	} catch {
-		return false;
-	}
-}
-/** Total hostile-boundary workflow snapshot guard. */
-function isWorkflowSnapshot(value) {
-	const cloned = attempt(() => cloneJSONValue(value));
-	return cloned.success && isOwnedWorkflowSnapshot(cloned.value);
-}
-function hasWorkflowHandlers(workflow, functions) {
-	if ("destroyed" in workflow) {
-		for (const phase of workflow.phases.phases()) for (const task of phase.tasks.tasks()) if (task.run !== void 0 && !isFunction(task.handler)) return false;
-		return true;
-	}
-	const runs = /* @__PURE__ */ new Set();
-	for (const phase of workflow.phases) for (const task of phase.tasks) {
-		if (task.run === void 0 || runs.has(task.run)) continue;
-		runs.add(task.run);
-		if (!isFunction(functions?.[task.run])) return false;
-	}
-	return true;
-}
-/** Locate the nearest identifiable node for an inconsistent owned snapshot. */
-function workflowSnapshotContext(value) {
-	if (!isRecord(value) || !isArray(value.phases)) return void 0;
-	for (const phase of value.phases) {
-		if (!isRecord(phase)) continue;
-		const phaseContext = isNonEmptyString(phase.id) ? { phase: phase.id } : void 0;
-		if (!isBoolean(phase.bail) || phase.concurrency !== void 0 && (!isInteger(phase.concurrency) || phase.concurrency < 1) || !isArray(phase.tasks)) return phaseContext;
-		for (const task of phase.tasks) {
-			if (!isRecord(task)) continue;
-			if (task.run !== void 0 && !isNonEmptyString(task.run) || task.retries !== void 0 && (!isInteger(task.retries) || task.retries < 0) || task.timeout !== void 0 && (!isInteger(task.timeout) || task.timeout < 0 || task.timeout > 2147483647) || !isInteger(task.attempts) || task.attempts < 0) return {
-				...phaseContext ?? {},
-				...isNonEmptyString(task.id) ? { task: task.id } : {}
-			};
-		}
-	}
-}
-/**
-* Test whether an unknown value is a valid whole-frame activity report.
-*/
-function isTaskActivityInput(value) {
-	try {
-		if (!isRecord(value)) return false;
-		const prototype = Object.getPrototypeOf(value);
-		if (prototype !== Object.prototype && prototype !== null || !Object.keys(value).every((key) => key === "note" || key === "progress" || key === "operations" || key === "constraints")) return false;
-		const note = value.note;
-		const progress = value.progress;
-		const operations = value.operations;
-		const constraints = value.constraints;
-		if (note !== void 0 && !isNonEmptyString(note)) return false;
-		if (progress !== void 0) {
-			if (!isRecord(progress)) return false;
-			const progressPrototype = Object.getPrototypeOf(progress);
-			if (progressPrototype !== Object.prototype && progressPrototype !== null || !Object.keys(progress).every((key) => key === "current" || key === "total" || key === "unit")) return false;
-			const current = progress.current;
-			const total = progress.total;
-			const unit = progress.unit;
-			if (!isFiniteNumber(current) || current < 0 || total !== void 0 && (!isFiniteNumber(total) || total < current) || unit !== void 0 && !isNonEmptyString(unit)) return false;
-		}
-		if (operations !== void 0) {
-			if (!isArray(operations)) return false;
-			const ids = /* @__PURE__ */ new Set();
-			for (const operation of operations) {
-				if (!isRecord(operation)) return false;
-				const operationPrototype = Object.getPrototypeOf(operation);
-				if (operationPrototype !== Object.prototype && operationPrototype !== null || !Object.keys(operation).every((key) => key === "id" || key === "name" || key === "started")) return false;
-				const id = operation.id;
-				const name = operation.name;
-				const started = operation.started;
-				if (!isNonEmptyString(id) || !isNonEmptyString(name) || !isFiniteNumber(started) || started < 0 || ids.has(id)) return false;
-				ids.add(id);
-			}
-		}
-		if (constraints !== void 0) {
-			if (!isArray(constraints)) return false;
-			const ids = /* @__PURE__ */ new Set();
-			for (const constraint of constraints) {
-				if (!isRecord(constraint)) return false;
-				const constraintPrototype = Object.getPrototypeOf(constraint);
-				if (constraintPrototype !== Object.prototype && constraintPrototype !== null || !Object.keys(constraint).every((key) => key === "id" || key === "name" || key === "started")) return false;
-				const id = constraint.id;
-				const name = constraint.name;
-				const started = constraint.started;
-				if (!isNonEmptyString(id) || !isNonEmptyString(name) || !isFiniteNumber(started) || started < 0 || ids.has(id)) return false;
-				ids.add(id);
-			}
-		}
-		return true;
-	} catch {
-		return false;
-	}
-}
-/**
-* Test whether an unknown value is valid persisted task activity.
-*/
-function isTaskActivity(value) {
-	try {
-		if (!isRecord(value)) return false;
-		const prototype = Object.getPrototypeOf(value);
-		if (prototype !== Object.prototype && prototype !== null || !Object.keys(value).every((key) => key === "note" || key === "progress" || key === "operations" || key === "constraints" || key === "updated")) return false;
-		const note = value.note;
-		const progress = value.progress;
-		const operations = value.operations;
-		const constraints = value.constraints;
-		const updated = value.updated;
-		if (operations === void 0 || constraints === void 0 || !isFiniteNumber(updated) || updated < 0) return false;
-		return isTaskActivityInput({
-			...note === void 0 ? {} : { note },
-			...progress === void 0 ? {} : { progress },
-			operations,
-			constraints
-		});
-	} catch {
-		return false;
-	}
-}
-//#endregion
 //#region src/core/cloners.ts
 /**
 * Validate and own a workflow snapshot before live construction.
@@ -1313,18 +1327,18 @@ var phaseUpdateShape = objectShape({
 * idle-TTL / eviction — a persisted run-state is durable orchestration state that lives until an
 * explicit `delete`. The public surface is EXACTLY `get` / `set` / `delete` — no extra members (the
 * §22 method bijection with {@link WorkflowStoreInterface}). Restore stays a caller concern: read a
-* snapshot back and rebuild the live tree with {@link import('../factories.js').restoreWorkflow}.
+* snapshot back and rebuild the live tree with {@link import('../factories.js').createRestoredWorkflow}.
 *
 * @example
 * ```ts
 * import { createMemoryDriver } from '@orkestrel/database'
-* import { createDatabaseWorkflowStore, createWorkflow, restoreWorkflow } from '@orkestrel/workflow'
+* import { createDatabaseWorkflowStore, createWorkflow, createRestoredWorkflow } from '@orkestrel/workflow'
 *
 * const store = createDatabaseWorkflowStore(createMemoryDriver()) // a durable driver swaps in here
 * const workflow = createWorkflow(definition)
 * await store.set(workflow.snapshot())            // persist the run state (one JSON column)
 * const snapshot = await store.get(definition.id)
-* const restored = snapshot && restoreWorkflow(snapshot) // an identical live tree
+* const restored = snapshot && createRestoredWorkflow(snapshot) // an identical live tree
 * await store.delete(definition.id)                // drop it
 * ```
 */
@@ -1384,17 +1398,17 @@ var DatabaseWorkflowStore = class {
 *
 * The public surface is EXACTLY `get` / `set` / `delete` — no extra members (the §22 method
 * bijection with {@link WorkflowStoreInterface}). Restore is a caller concern: read a snapshot
-* back and rebuild the live tree with {@link import('../factories.js').restoreWorkflow}.
+* back and rebuild the live tree with {@link import('../factories.js').createRestoredWorkflow}.
 *
 * @example
 * ```ts
-* import { createMemoryWorkflowStore, createWorkflow, restoreWorkflow } from '@orkestrel/workflow'
+* import { createMemoryWorkflowStore, createWorkflow, createRestoredWorkflow } from '@orkestrel/workflow'
 *
 * const store = createMemoryWorkflowStore()
 * const workflow = createWorkflow(definition)
 * await store.set(workflow.snapshot())      // persist the run state
 * const snapshot = await store.get(definition.id)
-* const restored = snapshot && restoreWorkflow(snapshot) // an identical live tree
+* const restored = snapshot && createRestoredWorkflow(snapshot) // an identical live tree
 * await store.delete(definition.id)          // drop it
 * ```
 */
@@ -2236,7 +2250,7 @@ var PhaseManager = class {
 * @remarks
 * - **Construction.** Built from a {@link WorkflowSnapshot} (the unified input —
 *   {@link import('./factories.js').createWorkflow} seeds an initial snapshot from a
-*   {@link import('./types.js').WorkflowDefinition}, {@link import('./factories.js').restoreWorkflow}
+*   {@link import('./types.js').WorkflowDefinition}, {@link import('./factories.js').createRestoredWorkflow}
 *   passes a persisted one). Each child {@link Phase} is wired to escalate to `#recompute`.
 * - **Derived status.** `status` is `#override` when forced, else
 *   {@link deriveWorkflowStatus} over the live phases' statuses feeding `bail`. `failed` is
@@ -2251,7 +2265,7 @@ var PhaseManager = class {
 *   workflow tier; `phase(id)` + each `phase.task(id)` navigate DOWN, a task's `phase` / `workflow`
 *   navigate UP.
 * - **Snapshot.** `snapshot()` serializes the whole live tree to a {@link WorkflowSnapshot} (pure
-*   JSON); {@link import('./factories.js').restoreWorkflow} rebuilds an equivalent live tree.
+*   JSON); {@link import('./factories.js').createRestoredWorkflow} rebuilds an equivalent live tree.
 * - **Observable (AGENTS §13).** The owned {@link emitter} ({@link WorkflowEventMap}) fires
 *   `start` / `complete` / `fail` / `pause` / `resume` / `skip` / `stop` after the
 *   corresponding status or runtime-gate change; the emitter isolates a listener throw and
@@ -2655,7 +2669,7 @@ var WorkflowManager = class {
 			if (!this.#owns(id, mutation, generation)) return this.#resolve(id, generation);
 			let workflow;
 			try {
-				workflow = restoreWorkflow(owned, { ...this.#functions === void 0 ? {} : { functions: this.#functions } });
+				workflow = createRestoredWorkflow(owned, { ...this.#functions === void 0 ? {} : { functions: this.#functions } });
 			} catch (error) {
 				if (!this.#owns(id, mutation, generation)) return this.#resolve(id, generation);
 				throw error;
@@ -3964,12 +3978,12 @@ function createWorkflow(definition, options) {
 	return new Workflow(definitionToSnapshot(definition, captured.bail ?? definition.bail ?? false), captured);
 }
 /**
-* Rebuild an equivalent live W-b entity tree from a {@link WorkflowSnapshot} — the
+* Build an equivalent live W-b entity tree from a {@link WorkflowSnapshot} — the
 * inverse of {@link WorkflowInterface.snapshot}, restoring structure + each node's status
 * + recorded results + positional order + the persisted `#override`.
 *
 * @remarks
-* Round-trip fidelity is paramount: a `snapshot()` → `restoreWorkflow()` reproduces the
+* Round-trip fidelity is paramount: a `snapshot()` → `createRestoredWorkflow()` reproduces the
 * same status at every node (each `#override` restored DIRECTLY from the snapshot's own
 * `override` field, not guessed from a status divergence), the same recorded
 * {@link import('./types.js').TaskResult}s, and the same positional order (an interior
@@ -3989,18 +4003,18 @@ function createWorkflow(definition, options) {
 *
 * @example
 * ```ts
-* import { restoreWorkflow } from '@orkestrel/workflow'
+* import { createRestoredWorkflow } from '@orkestrel/workflow'
 *
-* const restored = restoreWorkflow(workflow.snapshot()) // bail comes from the snapshot
+* const restored = createRestoredWorkflow(workflow.snapshot()) // bail comes from the snapshot
 * restored.status === workflow.status // true
 * ```
 */
-function restoreWorkflow(snapshot, options) {
+function createRestoredWorkflow(snapshot, options) {
 	const captured = captureWorkflowOptions(options);
 	return new Workflow(cloneWorkflowSnapshot(snapshot), captured);
 }
 /**
-* Rebuild an interrupted workflow at its remaining retry budget.
+* Build an interrupted workflow back to life at its remaining retry budget.
 *
 * @remarks
 * Each phase captures every unique initial `run` binding once before constructing tasks. Recovery
@@ -4009,9 +4023,17 @@ function restoreWorkflow(snapshot, options) {
 *
 * @param snapshot - The hostile persisted snapshot
 * @param options - Runtime handlers and entity options
-* @returns A recoverable live workflow
+* @returns A recoverable live {@link WorkflowInterface} root
+*
+* @example
+* ```ts
+* import { createRecoveredWorkflow } from '@orkestrel/workflow'
+*
+* const recovered = createRecoveredWorkflow(snapshot, { functions })
+* recovered.status // 'pending' — interrupted running work returned to its remaining budget
+* ```
 */
-function recoverWorkflow(snapshot, options) {
+function createRecoveredWorkflow(snapshot, options) {
 	const captured = captureWorkflowOptions(options);
 	const owned = cloneWorkflowSnapshot(snapshot);
 	if (owned.override !== void 0 || owned.phases.some((phase) => phase.override !== void 0)) throw new WorkflowError("RESTORE", `workflow '${owned.id}' has a terminal override`, { workflow: owned.id });
@@ -4020,29 +4042,6 @@ function recoverWorkflow(snapshot, options) {
 	return workflow;
 }
 /**
-* Assert that a {@link WorkflowSnapshot} carries a `boolean` `bail` — at the workflow tier AND
-* on every phase — and that its every node's status (and its `override`, when present) is drawn
-* from the lifecycle vocabulary, throwing a `RESTORE` {@link WorkflowError} otherwise.
-*
-* @remarks
-* The boundary-narrowing guard (AGENTS §14) for {@link restoreWorkflow}: a snapshot is
-* untrusted JSON, so a status (or an override) outside
-* {@link import('./constants.js').WORKFLOW_STATUSES} /
-* {@link import('./constants.js').PHASE_STATUSES} / {@link import('./constants.js').TASK_STATUSES},
-* a non-boolean `bail` (the workflow's OR any phase's — both are REQUIRED persisted policy), a
-* present-but-invalid phase `concurrency` (not a positive integer), or a present-but-invalid task
-* `run` (an empty string) / `retries` / `timeout` (not a non-negative integer),
-* is rejected loudly (naming the offending node) rather than silently producing a broken tree.
-* The `override` / `concurrency` / `run` / `retries` / `timeout` are optional, so each is only
-* checked WHEN present. Structural shape beyond these fields is the contract's concern; this
-* guards exactly the fields the live state machine reads back.
-*
-* @param snapshot - The snapshot to validate
-*/
-function assertSnapshot(snapshot) {
-	cloneWorkflowSnapshot(snapshot);
-}
-/**
 * Create the in-memory durable {@link WorkflowStoreInterface} — a process-lifetime
 * {@link MemoryWorkflowStore} persisting {@link WorkflowSnapshot}s by workflow id, the DEFAULT
 * backend behind the W-d persistence seam.
@@ -4055,19 +4054,19 @@ function assertSnapshot(snapshot) {
 * {@link createDatabaseWorkflowStore} (the snapshot as one opaque JSON column over a `databases`
 * table) — for a DURABLE store (run-state surviving a restart) pass it a JSON / SQLite / IndexedDB
 * driver, and it swaps in WITHOUT touching the runner or the entity tree. Restore stays a caller
-* concern: read a snapshot back and rebuild the live tree with {@link restoreWorkflow}.
+* concern: read a snapshot back and rebuild the live tree with {@link createRestoredWorkflow}.
 *
 * @returns A memory-backed {@link WorkflowStoreInterface}
 *
 * @example
 * ```ts
-* import { createMemoryWorkflowStore, createWorkflow, restoreWorkflow } from '@orkestrel/workflow'
+* import { createMemoryWorkflowStore, createWorkflow, createRestoredWorkflow } from '@orkestrel/workflow'
 *
 * const store = createMemoryWorkflowStore()
 * const workflow = createWorkflow(definition)
 * await store.set(workflow.snapshot())          // persist the run state
 * const snapshot = await store.get(definition.id)
-* const restored = snapshot && restoreWorkflow(snapshot)       // an identical live tree
+* const restored = snapshot && createRestoredWorkflow(snapshot)       // an identical live tree
 * ```
 */
 function createMemoryWorkflowStore() {
@@ -4098,13 +4097,13 @@ function createMemoryWorkflowStore() {
 * @example
 * ```ts
 * import { createMemoryDriver } from '@orkestrel/database'
-* import { createDatabaseWorkflowStore, createWorkflow, restoreWorkflow } from '@orkestrel/workflow'
+* import { createDatabaseWorkflowStore, createWorkflow, createRestoredWorkflow } from '@orkestrel/workflow'
 *
 * const store = createDatabaseWorkflowStore(createMemoryDriver()) // a durable driver swaps in here
 * const workflow = createWorkflow(definition)
 * await store.set(workflow.snapshot())          // persist the run state (one JSON column)
 * const snapshot = await store.get(definition.id)
-* const restored = snapshot && restoreWorkflow(snapshot)       // an identical live tree
+* const restored = snapshot && createRestoredWorkflow(snapshot)       // an identical live tree
 * ```
 */
 function createDatabaseWorkflowStore(driver = createMemoryDriver()) {
@@ -4173,11 +4172,11 @@ function createWorkflowRunner(options) {
 * @remarks
 * `options.functions` flows into every workflow the manager mints (`add`, via
 * {@link createWorkflow}) or hydrates (`open`'s registry-miss path, via
-* {@link restoreWorkflow}), so a hydrated workflow is RUNNABLE rather than a dead snapshot
+* {@link createRestoredWorkflow}), so a hydrated workflow is RUNNABLE rather than a dead snapshot
 * mirror. `options.store` is the EXACT analogue of the twins' `store` seam — omitted ⇒ the
 * manager is registry-only (`open` resolves only what is registered, `save` is a no-op). This
 * is PURELY ADDITIVE: direct {@link WorkflowStoreInterface} use and
-* {@link restoreWorkflow} remain valid — the manager is one more caller-driven persistence
+* {@link createRestoredWorkflow} remain valid — the manager is one more caller-driven persistence
 * seam, not a replacement.
 *
 * @param options - The optional `store` seam and the `functions` registry threaded into every mint/hydrate
@@ -4293,6 +4292,6 @@ function createRunner(options) {
 	return new Runner(options);
 }
 //#endregion
-export { Controller, DEFAULT_BAIL, DEFAULT_PHASE_CONCURRENCY, DatabaseWorkflowStore, MAX_TIMER_MS, MemoryWorkflowStore, PHASE_STATUSES, Phase, PhaseManager, Runner, Scheduler, TASK_STATUSES, TASK_TRANSITIONS, TERMINAL_TASK_STATUSES, Task, TaskController, TaskManager, WORKFLOW_STATUSES, Workflow, WorkflowError, WorkflowManager, WorkflowPersistence, WorkflowRunner, assertSnapshot, buildPhaseContext, buildTaskContext, buildWorkflowContext, canTransitionTask, captureWorkflowOptions, cloneTaskActivity, cloneWorkflowSnapshot, collectResults, createDatabaseWorkflowStore, createDeferred, createMemoryWorkflowStore, createRunner, createScheduler, createWorkflow, createWorkflowContract, createWorkflowManager, createWorkflowRunner, definitionToSnapshot, deriveBoundary, derivePhaseStatus, deriveWorkflowStatus, errorToMessage, failure, findFailure, hasWorkflowHandlers, insertEntry, isLifecycleStatus, isOwnedWorkflowSnapshot, isTaskActivity, isTaskActivityInput, isTaskFailure, isTaskResult, isTerminalStatus, isWorkflowError, isWorkflowSnapshot, matchesDescription, moveEntry, parkSignal, phaseDefinitionToSnapshot, phaseShape, phaseUpdateShape, recoverWorkflow, recoverWorkflowSnapshot, resolveTaskSilence, restoreWorkflow, scheduleHost, success, taskDefinitionToSnapshot, taskShape, taskUpdateShape, workflowShape, workflowSnapshotContext };
+export { Controller, DEFAULT_BAIL, DEFAULT_PHASE_CONCURRENCY, DatabaseWorkflowStore, MAX_TIMER_MS, MemoryWorkflowStore, PHASE_STATUSES, Phase, PhaseManager, Runner, Scheduler, TASK_STATUSES, TASK_TRANSITIONS, TERMINAL_TASK_STATUSES, Task, TaskController, TaskManager, WORKFLOW_STATUSES, Workflow, WorkflowError, WorkflowManager, WorkflowPersistence, WorkflowRunner, buildPhaseContext, buildTaskContext, buildWorkflowContext, canTransitionTask, captureWorkflowOptions, cloneTaskActivity, cloneWorkflowSnapshot, collectResults, createDatabaseWorkflowStore, createDeferred, createMemoryWorkflowStore, createRecoveredWorkflow, createRestoredWorkflow, createRunner, createScheduler, createWorkflow, createWorkflowContract, createWorkflowManager, createWorkflowRunner, definitionToSnapshot, deriveBoundary, derivePhaseStatus, deriveWorkflowStatus, errorToMessage, failure, findFailure, hasWorkflowHandlers, insertEntry, isLifecycleStatus, isOwnedWorkflowSnapshot, isTaskActivity, isTaskActivityInput, isTaskFailure, isTaskResult, isTerminalStatus, isWorkflowError, isWorkflowSnapshot, matchesDescription, moveEntry, parkSignal, phaseDefinitionToSnapshot, phaseShape, phaseUpdateShape, recoverWorkflowSnapshot, resolveTaskSilence, scheduleHost, success, taskDefinitionToSnapshot, taskShape, taskUpdateShape, workflowShape, workflowSnapshotContext };
 
 //# sourceMappingURL=index.js.map