@orkestrel/workflow 0.0.11 → 0.0.13

package/dist/src/core/index.cjs

@@ -155,6 +155,159 @@ function isWorkflowError(value) {
 	}
 }
 //#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 (0, _orkestrel_contract.isRecord)(value) && Object.keys(value).every((key) => key === "origin" || key === "message") && (value.origin === "handler" || value.origin === "timeout" || value.origin === "recovery") && (0, _orkestrel_contract.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 (!(0, _orkestrel_contract.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") || !(0, _orkestrel_contract.isNonEmptyString)(value.id) || !(0, _orkestrel_contract.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" || !(0, _orkestrel_contract.isBoolean)(value.bail) || !(0, _orkestrel_contract.isArray)(value.phases) || !(0, _orkestrel_contract.isFiniteNumber)(value.created) || value.created < 0 || !(0, _orkestrel_contract.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 (!(0, _orkestrel_contract.isRecord)(phase) || !Object.keys(phase).every((key) => key === "id" || key === "name" || key === "description" || key === "status" || key === "override" || key === "bail" || key === "concurrency" || key === "tasks") || !(0, _orkestrel_contract.isNonEmptyString)(phase.id) || phaseIds.has(phase.id) || !(0, _orkestrel_contract.isNonEmptyString)(phase.name) || phase.description !== void 0 && typeof phase.description !== "string" || !isLifecycleStatus(phase.status) || phase.override !== void 0 && phase.override !== "skipped" && phase.override !== "stopped" || !(0, _orkestrel_contract.isBoolean)(phase.bail) || phase.concurrency !== void 0 && (!(0, _orkestrel_contract.isInteger)(phase.concurrency) || phase.concurrency < 1) || !(0, _orkestrel_contract.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 (!(0, _orkestrel_contract.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") || !(0, _orkestrel_contract.isNonEmptyString)(task.id) || taskIds.has(task.id) || !(0, _orkestrel_contract.isNonEmptyString)(task.name) || task.description !== void 0 && typeof task.description !== "string" || !isLifecycleStatus(task.status) || !(0, _orkestrel_contract.isRecord)(task.metadata) || !(0, _orkestrel_contract.isJSONValue)(task.metadata) || !(0, _orkestrel_contract.isInteger)(task.attempts) || task.attempts < 0 || task.run !== void 0 && !(0, _orkestrel_contract.isNonEmptyString)(task.run) || task.retries !== void 0 && (!(0, _orkestrel_contract.isInteger)(task.retries) || task.retries < 0) || task.timeout !== void 0 && (!(0, _orkestrel_contract.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 = (0, _orkestrel_contract.attempt)(() => (0, _orkestrel_contract.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 (!(0, _orkestrel_contract.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 && !(0, _orkestrel_contract.isNonEmptyString)(note)) return false;
+		if (progress !== void 0) {
+			if (!(0, _orkestrel_contract.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 (!(0, _orkestrel_contract.isFiniteNumber)(current) || current < 0 || total !== void 0 && (!(0, _orkestrel_contract.isFiniteNumber)(total) || total < current) || unit !== void 0 && !(0, _orkestrel_contract.isNonEmptyString)(unit)) return false;
+		}
+		if (operations !== void 0) {
+			if (!(0, _orkestrel_contract.isArray)(operations)) return false;
+			const ids = /* @__PURE__ */ new Set();
+			for (const operation of operations) {
+				if (!(0, _orkestrel_contract.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 (!(0, _orkestrel_contract.isNonEmptyString)(id) || !(0, _orkestrel_contract.isNonEmptyString)(name) || !(0, _orkestrel_contract.isFiniteNumber)(started) || started < 0 || ids.has(id)) return false;
+				ids.add(id);
+			}
+		}
+		if (constraints !== void 0) {
+			if (!(0, _orkestrel_contract.isArray)(constraints)) return false;
+			const ids = /* @__PURE__ */ new Set();
+			for (const constraint of constraints) {
+				if (!(0, _orkestrel_contract.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 (!(0, _orkestrel_contract.isNonEmptyString)(id) || !(0, _orkestrel_contract.isNonEmptyString)(name) || !(0, _orkestrel_contract.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 (!(0, _orkestrel_contract.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 || !(0, _orkestrel_contract.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.
@@ -628,6 +781,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 (!(0, _orkestrel_contract.isRecord)(value) || !(0, _orkestrel_contract.isRecord)(workflow) || !(0, _orkestrel_contract.isRecord)(phase) || !(0, _orkestrel_contract.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 || !(0, _orkestrel_contract.isFiniteNumber)(value.timestamp) || value.timestamp < 0 || !(0, _orkestrel_contract.isRecord)(value.task) || !(0, _orkestrel_contract.isRecord)(value.phase) || !(0, _orkestrel_contract.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 (!(0, _orkestrel_contract.isRecord)(value.task.phase) || !(0, _orkestrel_contract.isRecord)(value.task.phase.workflow) || !(0, _orkestrel_contract.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 (0, _orkestrel_contract.isRecord)(value.result) && value.result.success === true && Object.keys(value.result).every((key) => key === "success" || key === "value") && (0, _orkestrel_contract.isJSONValue)(value.result.value);
+		if (value.status === "failed") return (0, _orkestrel_contract.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 && !(0, _orkestrel_contract.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 (!(0, _orkestrel_contract.isFunction)(functions?.[task.run])) return false;
+	}
+	return true;
+}
+/** Locate the nearest identifiable node for an inconsistent owned snapshot. */
+function workflowSnapshotContext(value) {
+	if (!(0, _orkestrel_contract.isRecord)(value) || !(0, _orkestrel_contract.isArray)(value.phases)) return void 0;
+	for (const phase of value.phases) {
+		if (!(0, _orkestrel_contract.isRecord)(phase)) continue;
+		const phaseContext = (0, _orkestrel_contract.isNonEmptyString)(phase.id) ? { phase: phase.id } : void 0;
+		if (!(0, _orkestrel_contract.isBoolean)(phase.bail) || phase.concurrency !== void 0 && (!(0, _orkestrel_contract.isInteger)(phase.concurrency) || phase.concurrency < 1) || !(0, _orkestrel_contract.isArray)(phase.tasks)) return phaseContext;
+		for (const task of phase.tasks) {
+			if (!(0, _orkestrel_contract.isRecord)(task)) continue;
+			if (task.run !== void 0 && !(0, _orkestrel_contract.isNonEmptyString)(task.run) || task.retries !== void 0 && (!(0, _orkestrel_contract.isInteger)(task.retries) || task.retries < 0) || task.timeout !== void 0 && (!(0, _orkestrel_contract.isInteger)(task.timeout) || task.timeout < 0 || task.timeout > 2147483647) || !(0, _orkestrel_contract.isInteger)(task.attempts) || task.attempts < 0) return {
+				...phaseContext ?? {},
+				...(0, _orkestrel_contract.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()`.
@@ -872,206 +1072,6 @@ var Scheduler = class {
 	}
 };
 //#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 (0, _orkestrel_contract.isRecord)(value) && Object.keys(value).every((key) => key === "origin" || key === "message") && (value.origin === "handler" || value.origin === "timeout" || value.origin === "recovery") && (0, _orkestrel_contract.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 (!(0, _orkestrel_contract.isRecord)(value) || !(0, _orkestrel_contract.isRecord)(workflow) || !(0, _orkestrel_contract.isRecord)(phase) || !(0, _orkestrel_contract.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 || !(0, _orkestrel_contract.isFiniteNumber)(value.timestamp) || value.timestamp < 0 || !(0, _orkestrel_contract.isRecord)(value.task) || !(0, _orkestrel_contract.isRecord)(value.phase) || !(0, _orkestrel_contract.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 (!(0, _orkestrel_contract.isRecord)(value.task.phase) || !(0, _orkestrel_contract.isRecord)(value.task.phase.workflow) || !(0, _orkestrel_contract.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 (0, _orkestrel_contract.isRecord)(value.result) && value.result.success === true && Object.keys(value.result).every((key) => key === "success" || key === "value") && (0, _orkestrel_contract.isJSONValue)(value.result.value);
-		if (value.status === "failed") return (0, _orkestrel_contract.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 (!(0, _orkestrel_contract.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") || !(0, _orkestrel_contract.isNonEmptyString)(value.id) || !(0, _orkestrel_contract.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" || !(0, _orkestrel_contract.isBoolean)(value.bail) || !(0, _orkestrel_contract.isArray)(value.phases) || !(0, _orkestrel_contract.isFiniteNumber)(value.created) || value.created < 0 || !(0, _orkestrel_contract.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 (!(0, _orkestrel_contract.isRecord)(phase) || !Object.keys(phase).every((key) => key === "id" || key === "name" || key === "description" || key === "status" || key === "override" || key === "bail" || key === "concurrency" || key === "tasks") || !(0, _orkestrel_contract.isNonEmptyString)(phase.id) || phaseIds.has(phase.id) || !(0, _orkestrel_contract.isNonEmptyString)(phase.name) || phase.description !== void 0 && typeof phase.description !== "string" || !isLifecycleStatus(phase.status) || phase.override !== void 0 && phase.override !== "skipped" && phase.override !== "stopped" || !(0, _orkestrel_contract.isBoolean)(phase.bail) || phase.concurrency !== void 0 && (!(0, _orkestrel_contract.isInteger)(phase.concurrency) || phase.concurrency < 1) || !(0, _orkestrel_contract.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 (!(0, _orkestrel_contract.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") || !(0, _orkestrel_contract.isNonEmptyString)(task.id) || taskIds.has(task.id) || !(0, _orkestrel_contract.isNonEmptyString)(task.name) || task.description !== void 0 && typeof task.description !== "string" || !isLifecycleStatus(task.status) || !(0, _orkestrel_contract.isRecord)(task.metadata) || !(0, _orkestrel_contract.isJSONValue)(task.metadata) || !(0, _orkestrel_contract.isInteger)(task.attempts) || task.attempts < 0 || task.run !== void 0 && !(0, _orkestrel_contract.isNonEmptyString)(task.run) || task.retries !== void 0 && (!(0, _orkestrel_contract.isInteger)(task.retries) || task.retries < 0) || task.timeout !== void 0 && (!(0, _orkestrel_contract.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 = (0, _orkestrel_contract.attempt)(() => (0, _orkestrel_contract.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 && !(0, _orkestrel_contract.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 (!(0, _orkestrel_contract.isFunction)(functions?.[task.run])) return false;
-	}
-	return true;
-}
-/** Locate the nearest identifiable node for an inconsistent owned snapshot. */
-function workflowSnapshotContext(value) {
-	if (!(0, _orkestrel_contract.isRecord)(value) || !(0, _orkestrel_contract.isArray)(value.phases)) return void 0;
-	for (const phase of value.phases) {
-		if (!(0, _orkestrel_contract.isRecord)(phase)) continue;
-		const phaseContext = (0, _orkestrel_contract.isNonEmptyString)(phase.id) ? { phase: phase.id } : void 0;
-		if (!(0, _orkestrel_contract.isBoolean)(phase.bail) || phase.concurrency !== void 0 && (!(0, _orkestrel_contract.isInteger)(phase.concurrency) || phase.concurrency < 1) || !(0, _orkestrel_contract.isArray)(phase.tasks)) return phaseContext;
-		for (const task of phase.tasks) {
-			if (!(0, _orkestrel_contract.isRecord)(task)) continue;
-			if (task.run !== void 0 && !(0, _orkestrel_contract.isNonEmptyString)(task.run) || task.retries !== void 0 && (!(0, _orkestrel_contract.isInteger)(task.retries) || task.retries < 0) || task.timeout !== void 0 && (!(0, _orkestrel_contract.isInteger)(task.timeout) || task.timeout < 0 || task.timeout > 2147483647) || !(0, _orkestrel_contract.isInteger)(task.attempts) || task.attempts < 0) return {
-				...phaseContext ?? {},
-				...(0, _orkestrel_contract.isNonEmptyString)(task.id) ? { task: task.id } : {}
-			};
-		}
-	}
-}
-/**
-* Test whether an unknown value is a valid whole-frame activity report.
-*/
-function isTaskActivityInput(value) {
-	try {
-		if (!(0, _orkestrel_contract.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 && !(0, _orkestrel_contract.isNonEmptyString)(note)) return false;
-		if (progress !== void 0) {
-			if (!(0, _orkestrel_contract.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 (!(0, _orkestrel_contract.isFiniteNumber)(current) || current < 0 || total !== void 0 && (!(0, _orkestrel_contract.isFiniteNumber)(total) || total < current) || unit !== void 0 && !(0, _orkestrel_contract.isNonEmptyString)(unit)) return false;
-		}
-		if (operations !== void 0) {
-			if (!(0, _orkestrel_contract.isArray)(operations)) return false;
-			const ids = /* @__PURE__ */ new Set();
-			for (const operation of operations) {
-				if (!(0, _orkestrel_contract.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 (!(0, _orkestrel_contract.isNonEmptyString)(id) || !(0, _orkestrel_contract.isNonEmptyString)(name) || !(0, _orkestrel_contract.isFiniteNumber)(started) || started < 0 || ids.has(id)) return false;
-				ids.add(id);
-			}
-		}
-		if (constraints !== void 0) {
-			if (!(0, _orkestrel_contract.isArray)(constraints)) return false;
-			const ids = /* @__PURE__ */ new Set();
-			for (const constraint of constraints) {
-				if (!(0, _orkestrel_contract.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 (!(0, _orkestrel_contract.isNonEmptyString)(id) || !(0, _orkestrel_contract.isNonEmptyString)(name) || !(0, _orkestrel_contract.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 (!(0, _orkestrel_contract.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 || !(0, _orkestrel_contract.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.
@@ -1328,18 +1328,18 @@ var phaseUpdateShape = (0, _orkestrel_contract.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
 * ```
 */
@@ -1399,17 +1399,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
 * ```
 */
@@ -2251,7 +2251,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
@@ -2266,7 +2266,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
@@ -2670,7 +2670,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;
@@ -3979,12 +3979,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
@@ -4004,18 +4004,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
@@ -4024,9 +4024,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 });
@@ -4035,29 +4043,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.
@@ -4070,19 +4055,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() {
@@ -4113,13 +4098,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 = (0, _orkestrel_database.createMemoryDriver)()) {
@@ -4188,11 +4173,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
@@ -4331,7 +4316,6 @@ exports.WorkflowError = WorkflowError;
 exports.WorkflowManager = WorkflowManager;
 exports.WorkflowPersistence = WorkflowPersistence;
 exports.WorkflowRunner = WorkflowRunner;
-exports.assertSnapshot = assertSnapshot;
 exports.buildPhaseContext = buildPhaseContext;
 exports.buildTaskContext = buildTaskContext;
 exports.buildWorkflowContext = buildWorkflowContext;
@@ -4343,6 +4327,8 @@ exports.collectResults = collectResults;
 exports.createDatabaseWorkflowStore = createDatabaseWorkflowStore;
 exports.createDeferred = createDeferred;
 exports.createMemoryWorkflowStore = createMemoryWorkflowStore;
+exports.createRecoveredWorkflow = createRecoveredWorkflow;
+exports.createRestoredWorkflow = createRestoredWorkflow;
 exports.createRunner = createRunner;
 exports.createScheduler = createScheduler;
 exports.createWorkflow = createWorkflow;
@@ -4373,10 +4359,8 @@ exports.parkSignal = parkSignal;
 exports.phaseDefinitionToSnapshot = phaseDefinitionToSnapshot;
 exports.phaseShape = phaseShape;
 exports.phaseUpdateShape = phaseUpdateShape;
-exports.recoverWorkflow = recoverWorkflow;
 exports.recoverWorkflowSnapshot = recoverWorkflowSnapshot;
 exports.resolveTaskSilence = resolveTaskSilence;
-exports.restoreWorkflow = restoreWorkflow;
 exports.scheduleHost = scheduleHost;
 exports.success = success;
 exports.taskDefinitionToSnapshot = taskDefinitionToSnapshot;