@orkestrel/workflow 0.0.1

package/dist/src/core/index.js

@@ -0,0 +1,2734 @@
+import { createTool } from "@orkestrel/agent";
+import { arrayShape, createContract, integerShape, isArray, isBoolean, isNumber, isRecord, isString, literalShape, objectShape, optionalShape, rawShape, schemaToParameters, stringShape, unionShape } from "@orkestrel/contract";
+import { createDatabase, createMemoryDriver } from "@orkestrel/database";
+import { Emitter } from "@orkestrel/emitter";
+import { createAbort } from "@orkestrel/abort";
+import { createTimeout } from "@orkestrel/timeout";
+import { createQueue } from "@orkestrel/queue";
+//#region src/core/Scheduler.ts
+/**
+* The safe cross-environment cooperative-yield default — a {@link SchedulerInterface}
+* built on `setTimeout` / `clearTimeout` alone, so it runs unchanged in both the
+* browser and Node.
+*
+* @remarks
+* - **Cross-environment.** Uses ONLY `setTimeout` / `clearTimeout` — universally
+*   available. It deliberately avoids env-specific fast paths (`setImmediate`,
+*   `scheduler.yield`, `requestAnimationFrame`, `node:timers/promises`,
+*   `MessageChannel`); those belong to the environment backends, built with the
+*   agent loop that consumes them.
+* - **`yield` is a macrotask host-turn, not a microtask.** `yield()` waits on a
+*   `setTimeout(0)`, NOT `queueMicrotask`. A microtask drains before the host
+*   regains control, so it would not actually let pending I/O, timers, or
+*   rendering run — it only defers within the current task. A zero-delay timer is
+*   the correct cross-environment "give the host a turn".
+* - **Abort-aware.** A pending `yield` / `delay` rejects with `signal.reason` when
+*   the signal aborts (the standard `AbortSignal` convention). An already-aborted
+*   signal rejects immediately without arming a timer. Either settle path clears
+*   the timer and removes the abort listener — no leaked timer, no leaked
+*   listener, and no double-settle.
+* - **Priority is accepted but uniform.** `options.priority` is part of the
+*   contract, but a `setTimeout`-based default cannot act on urgency, so it treats
+*   every priority the same. Environment backends honour it.
+* - **Event-free.** A pure functional primitive — no Emitter, no events.
+*
+* @example
+* ```ts
+* const scheduler = new Scheduler()
+* while (!signal.aborted) {
+* 	doSomeWork()
+* 	await scheduler.yield({ signal }) // let the host run between work units
+* }
+* ```
+*/
+var Scheduler = class {
+	/**
+	* Yield control back to the host so other tasks (I/O, timers, rendering) can
+	* run, then resume — a macrotask turn via `setTimeout(0)` (NOT a microtask,
+	* which would resume before the host regains control).
+	*/
+	yield(options) {
+		return this.#sleep(0, options?.signal);
+	}
+	/**
+	* Resume after at least `ms` milliseconds; abort rejects with `signal.reason`.
+	*
+	* @remarks
+	* `ms` should be a non-negative finite number. The primitive stays minimal and
+	* does no validation: it passes `ms` straight to the host `setTimeout`, which
+	* clamps a negative value or `NaN` to ~0 — so an out-of-domain `ms` resolves on
+	* the next host turn rather than throwing.
+	*/
+	delay(ms, options) {
+		return this.#sleep(ms, options?.signal);
+	}
+	#sleep(ms, signal) {
+		if (signal?.aborted === true) return Promise.reject(signal.reason);
+		return new Promise((resolve, reject) => {
+			const onAbort = () => {
+				clearTimeout(handle);
+				reject(signal?.reason);
+			};
+			const handle = setTimeout(() => {
+				signal?.removeEventListener("abort", onAbort);
+				resolve();
+			}, ms);
+			signal?.addEventListener("abort", onAbort, { once: true });
+		});
+	}
+};
+//#endregion
+//#region src/core/constants.ts
+/** The default {@link import('./types.js').WorkflowDefinition.bail} — graceful (continue on a leaf failure). */
+var DEFAULT_BAIL = false;
+/**
+* The three task-form mechanisms (the {@link TaskVia} discriminant), frozen.
+*
+* @remarks
+* The runtime source of truth for the `via` axis — drive the contract's literal
+* shape and any guard from this array rather than repeating the literals.
+*/
+var TASK_VIAS = Object.freeze([
+	"function",
+	"tool",
+	"agent"
+]);
+/**
+* Every {@link TaskStatus} value, frozen — the lifecycle vocabulary of a task.
+*
+* @remarks
+* Ordered pending → running → terminal (`completed` / `failed` / `skipped` /
+* `stopped`). The source of truth for the union; compose guards / shapes from it.
+*/
+var TASK_STATUSES = Object.freeze([
+	"pending",
+	"running",
+	"completed",
+	"failed",
+	"skipped",
+	"stopped"
+]);
+/** Every {@link PhaseStatus} value, frozen — the lifecycle vocabulary of a phase. */
+var PHASE_STATUSES = Object.freeze([
+	"pending",
+	"running",
+	"completed",
+	"failed",
+	"skipped",
+	"stopped"
+]);
+/** Every {@link WorkflowStatus} value, frozen — the lifecycle vocabulary of a workflow. */
+var WORKFLOW_STATUSES = Object.freeze([
+	"pending",
+	"running",
+	"completed",
+	"failed",
+	"skipped",
+	"stopped"
+]);
+/**
+* The {@link TaskStatus} values that are TERMINAL — a task in one of these will
+* not transition further, frozen.
+*
+* @remarks
+* The source of truth behind {@link import('./helpers.js').isTerminalStatus}.
+* `pending` and `running` are the only non-terminal members.
+*/
+var TERMINAL_TASK_STATUSES = Object.freeze([
+	"completed",
+	"failed",
+	"skipped",
+	"stopped"
+]);
+/**
+* The legal {@link TaskStatus} transition graph of the live W-b task state machine —
+* each current status mapped to the statuses it may move to directly, frozen.
+*
+* @remarks
+* The source of truth behind {@link import('./helpers.js').canTransitionTask} and the
+* `TRANSITION` guard ({@link import('./errors.js').WorkflowError}). A `pending` task may
+* `start` (→ `running`), `skip` (→ `skipped`), or `stop` (→ `stopped`); a `running` task
+* may `complete` (→ `completed`), `fail` (→ `failed`), `skip` (→ `skipped`), or `stop`
+* (→ `stopped`). Every terminal status maps to an empty list — a settled task never
+* transitions again. So completing a non-`running` task, or starting a settled one, is
+* rejected.
+*/
+var TASK_TRANSITIONS = Object.freeze({
+	pending: [
+		"running",
+		"skipped",
+		"stopped"
+	],
+	running: [
+		"completed",
+		"failed",
+		"skipped",
+		"stopped"
+	],
+	completed: [],
+	failed: [],
+	skipped: [],
+	stopped: []
+});
+/**
+* The default per-phase task concurrency the {@link import('./factories.js').createWorkflowRunner}
+* runner applies when a {@link import('./types.js').PhaseDefinition} omits its `concurrency`
+* throttle — a large cap that is effectively unbounded for any realistic phase.
+*
+* @remarks
+* The determinism principle fixes that a phase's tasks run CONCURRENTLY; `concurrency` is
+* only an optional resource throttle (max-in-flight). With none declared, the runner runs
+* all of a phase's tasks at once — modelled as this large finite cap so the value flows
+* straight into the substrate {@link import('./types.js').RunnerInterface}'s
+* `concurrency` (which expects a positive integer) without a special unbounded branch. No
+* realistic phase declares enough tasks to reach it, so it behaves as "run them all".
+*/
+var DEFAULT_PHASE_CONCURRENCY = 1e6;
+/**
+* The maximum nesting depth a workflow's `agent` task may spawn into (W-c) — the
+* bound the runner's depth/cycle guard enforces.
+*
+* @remarks
+* The limit lives in ONE place. The `agent` {@link import('./types.js').TaskForm} is
+* bounded by it when the {@link import('./WorkflowRunner.js').WorkflowRunner} resolves a
+* subagent: an agent running at this depth can no longer author + run a nested workflow
+* (that would be depth `MAX_WORKFLOW_DEPTH + 1`), so the over-deep `agent` task is
+* rejected (a typed `DEPTH` `task.fail`). The chain therefore nests workflows down to
+* this depth, and the `agent` task in the depth-`MAX_WORKFLOW_DEPTH` workflow fails.
+*/
+var MAX_WORKFLOW_DEPTH = 8;
+/**
+* The name under which the {@link import('./WorkflowRunner.js').WorkflowRunner} BINDS the
+* depth/cycle-aware workflow tool onto a dispatched `agent` task's
+* `AgentContextInterface` (the future `@orkestrel/agent` package, W-c2).
+*
+* @remarks
+* The propagation seam's well-known key: before running an `agent` task, the runner adds a
+* {@link import('./factories.js').createWorkflowTool}-built tool under this name to the
+* resolved agent's `context.tools`, so the subagent can author + run a NESTED workflow
+* (bounded by {@link MAX_WORKFLOW_DEPTH}). A subagent that wants to fan out into a workflow
+* calls this tool by this name; the bound handler runs the nested workflow at depth + 1.
+*/
+var WORKFLOW_TOOL_NAME = "workflow";
+/**
+* A complete FLAT authoring example — the PRIMARY way a small model authors a workflow
+* through {@link import('./factories.js').createWorkflowTool}: `{ name, steps: [{ name, via }] }`.
+*
+* @remarks
+* Each step becomes a one-task phase, in order; a step's `name` is a REGISTERED behavior name
+* (not a label) and `via` is the execution mechanism. The tool expands this
+* ({@link import('./helpers.js').expandSteps}) into a valid {@link WorkflowDefinition}. It
+* is embedded VERBATIM in {@link WORKFLOW_TOOL_DESCRIPTION} and guarded by a parity test
+* (it must expand to a tree the STRICT contract accepts), so the doc example can never drift.
+*/
+var WORKFLOW_TOOL_FLAT_EXAMPLE = Object.freeze({
+	name: "release",
+	steps: Object.freeze([Object.freeze({
+		name: "compile",
+		via: "function"
+	}), Object.freeze({
+		name: "publish",
+		via: "tool"
+	})])
+});
+/**
+* A minimal NESTED authoring example — the ADVANCED escape-hatch form a model may use
+* instead of the flat shape: a full {@link WorkflowDefinition}.
+*
+* @remarks
+* The full four-level form, documented in {@link WORKFLOW_TOOL_DESCRIPTION} as the advanced
+* alternative. It is embedded VERBATIM and guarded by a parity test (`createWorkflowContract().is`
+* must accept it), so the doc example can never drift from a valid definition.
+*/
+var WORKFLOW_TOOL_NESTED_EXAMPLE = Object.freeze({
+	id: "release",
+	name: "Release",
+	phases: Object.freeze([Object.freeze({
+		id: "build",
+		name: "Build",
+		tasks: Object.freeze([Object.freeze({
+			id: "compile",
+			name: "Compile",
+			run: Object.freeze({
+				via: "function",
+				name: "compile"
+			})
+		})])
+	})])
+});
+/**
+* The DESCRIPTION {@link import('./factories.js').createWorkflowTool} advertises — a
+* multi-line guide that teaches a small model how to author a complete workflow tree.
+*
+* @remarks
+* Presents the SIMPLE flat shape (`{ name, steps: [{ name, via }] }`) as the PRIMARY way with
+* one complete worked example ({@link WORKFLOW_TOOL_FLAT_EXAMPLE}), names the three `via`
+* values + that a step's `name` is a REGISTERED name (not a human label), and documents the full nested
+* {@link WorkflowDefinition} as the ADVANCED form with a minimal example
+* ({@link WORKFLOW_TOOL_NESTED_EXAMPLE}). Both examples are interpolated VERBATIM from the
+* validated constants, so a parity test pins them — the description can never drift from a
+* real, contract-valid example. The `parameters` the tool advertises are the FLAT shape's
+* schema; the nested form is the documented escape-hatch (the tool accepts both).
+*/
+var WORKFLOW_TOOL_DESCRIPTION = [
+	"Author and run a workflow (phases run sequentially, the tasks within a phase run concurrently) in one call.",
+	"",
+	"SIMPLEST way — a flat list of steps. Each step runs one registered behavior; steps run one after another:",
+	"  { \"name\": \"<workflow name>\", \"steps\": [ { \"name\": \"<registered name>\", \"via\": \"function|tool|agent\" }, ... ] }",
+	"- a step's \"name\" is a REGISTERED behavior name (a registry key), NOT a human label.",
+	"- \"via\" is how to run it: \"function\" (the default if omitted), \"tool\", or \"agent\".",
+	"- the top-level \"name\" (the workflow name) is optional. Ids are filled in for you.",
+	"Example:",
+	JSON.stringify(WORKFLOW_TOOL_FLAT_EXAMPLE),
+	"",
+	"ADVANCED — the full nested form, for multi-task phases or explicit ids. A workflow has phases; a phase has tasks; a task has a \"run\" of { \"via\", \"name\" }:",
+	JSON.stringify(WORKFLOW_TOOL_NESTED_EXAMPLE),
+	"In the nested form you may omit any \"id\"/\"name\" and they are filled in positionally; a provided one is kept."
+].join("\n");
+//#endregion
+//#region src/core/errors.ts
+/**
+* An error thrown by the workflow entity + W-c2 recursion layer.
+*
+* @remarks
+* Carries a {@link WorkflowErrorCode} and an optional `context` bag naming the
+* offending node id / status. Thrown for an illegal lifecycle transition
+* (`TRANSITION`), a structurally invalid {@link import('./types.js').WorkflowSnapshot}
+* passed to {@link import('./factories.js').restoreWorkflow} (`RESTORE`), an over-deep /
+* cyclic nested-workflow dispatch (`DEPTH`), and a malformed
+* {@link import('./factories.js').createWorkflowTool} args blob (`TOOL`). On the
+* workflow-tool seam the `DEPTH` / `TOOL` throw is ISOLATED by the
+* `@orkestrel/agent` package's `ToolManager` into the tool result's
+* top-level `error` (AGENTS §14 — the universal tool-handler contract).
+*/
+var WorkflowError = class extends Error {
+	code;
+	context;
+	constructor(code, message, context) {
+		super(message);
+		this.name = "WorkflowError";
+		this.code = code;
+		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) {
+	return value instanceof WorkflowError;
+}
+//#endregion
+//#region src/core/helpers.ts
+/**
+* Narrow a {@link TaskForm} to the `function` form — a task that runs a registered
+* function.
+*
+* @param form - The task form to test
+* @returns `true` when `form.via` is `'function'`
+*/
+function isFunctionTask(form) {
+	return form.via === "function";
+}
+/**
+* Narrow a {@link TaskForm} to the `tool` form — a task that runs a registered tool.
+*
+* @param form - The task form to test
+* @returns `true` when `form.via` is `'tool'`
+*/
+function isToolTask(form) {
+	return form.via === "tool";
+}
+/**
+* Narrow a {@link TaskForm} to the `agent` form — a task that runs a registered
+* agent (a subagent).
+*
+* @param form - The task form to test
+* @returns `true` when `form.via` is `'agent'`
+*/
+function isAgentTask(form) {
+	return form.via === "agent";
+}
+/**
+* The ancestry identifier of a workflow run — `workflow:<id>`.
+*
+* @remarks
+* The {@link import('./WorkflowRunner.js').WorkflowRunner}'s cycle guard records one of
+* these per workflow in the current nested run chain (carried on
+* {@link import('./types.js').WorkflowRunOptions.ancestry}). Tagging the bare id keeps a
+* workflow id and an {@link agentTag} agent name in ONE namespaced set without collision,
+* so re-entering a workflow OR an agent already in the chain is a single `includes` check.
+*
+* @param id - The workflow definition's `id`
+* @returns The namespaced ancestry tag (`workflow:<id>`)
+*/
+function workflowTag(id) {
+	return `workflow:${id}`;
+}
+/**
+* The ancestry identifier of an agent in a run chain — `agent:<name>`.
+*
+* @remarks
+* The agent counterpart of {@link workflowTag}: the runner adds one when it dispatches an
+* `agent` task, and rejects the task (a typed `DEPTH` `task.fail`) when the same tag is
+* already in the ancestry (a re-entry cycle). The `agent:` namespace keeps it distinct
+* from a same-string workflow id.
+*
+* @param name - The agent's registry name (the `agent`-form's `name`)
+* @returns The namespaced ancestry tag (`agent:<name>`)
+*/
+function agentTag(name) {
+	return `agent:${name}`;
+}
+/**
+* Test whether a {@link LifecycleStatus} is TERMINAL — a node in this state will not
+* transition further.
+*
+* @remarks
+* The ONE terminal check across all three tiers (AGENTS §4.4 "one concept = one word"):
+* a task, a phase, and a workflow share the same {@link LifecycleStatus} vocabulary, so a
+* single predicate covers them — {@link derivePhaseStatus} and {@link deriveWorkflowStatus}
+* both consult it to tell a settled node from an in-flight one. Terminal: `completed` /
+* `failed` / `skipped` / `stopped`; the only non-terminal states are `pending` and
+* `running`.
+*
+* @param status - The lifecycle status to test (a task / phase / workflow status)
+* @returns `true` when the status is terminal
+*/
+function isTerminalStatus(status) {
+	return status === "completed" || status === "failed" || status === "skipped" || status === "stopped";
+}
+/**
+* Derive a phase's status from its tasks' statuses (tasks are concurrent, so this
+* is an order-insensitive reduction).
+*
+* @remarks
+* The truth table (most-severe terminal wins; `bail`-agnostic — a phase surfaces a
+* task failure as `failed` so the workflow's `bail` policy can decide):
+* - no tasks ⇒ `pending`.
+* - any task `running`, OR a mix of started-and-unsettled tasks (some non-`pending`
+*   but not all terminal) ⇒ `running`.
+* - every task `pending` ⇒ `pending`.
+* - all terminal: any `failed` ⇒ `failed`; else any `stopped` ⇒ `stopped`; else any
+*   `completed` ⇒ `completed`; else (all `skipped`) ⇒ `skipped`.
+*
+* So an all-`skipped` phase is `skipped`, an all-`stopped` phase is `stopped`, a
+* phase with completed tasks and some skips is `completed`, and a single failed
+* task makes the phase `failed`.
+*
+* @param tasks - The phase's task statuses, in any order
+* @returns The derived {@link PhaseStatus}
+*/
+function derivePhaseStatus(tasks) {
+	if (tasks.length === 0) return "pending";
+	if (tasks.every((status) => status === "pending")) return "pending";
+	if (!tasks.every((status) => isTerminalStatus(status))) return "running";
+	if (tasks.some((status) => status === "failed")) return "failed";
+	if (tasks.some((status) => status === "stopped")) return "stopped";
+	if (tasks.some((status) => status === "completed")) return "completed";
+	return "skipped";
+}
+/**
+* Derive a workflow's status from its phases' {@link PhaseDerivation}s — each phase's status
+* paired with the EFFECTIVE `bail` it ran under (`phase.bail ?? workflow.bail`) — so the
+* failure outcome is PER-PHASE-bail-aware (phases are sequential, but the derivation is an
+* order-insensitive reduction over the settled set).
+*
+* @remarks
+* `bail` is now a per-phase override (AGENTS §4.4), so it is carried on each
+* {@link PhaseDerivation} rather than passed as one scalar. It is the ONLY axis that changes
+* the failure outcome, decided per phase:
+* - **A `failed` phase whose effective `bail` is `true` (halt)** propagates ⇒ the workflow is
+*   `failed` (the database-transaction halt) — even when the workflow default is graceful.
+* - **A `failed` phase whose effective `bail` is `false` (graceful)** is DATA, not a workflow
+*   failure — it folds into completion like a settled phase. A graceful failed phase NEVER
+*   makes the workflow `failed` — even when the workflow default is strict.
+*
+* The rest of the table is shared:
+* - no phases ⇒ `pending`.
+* - any phase `running`, OR a mix of started-and-unsettled phases (some non-`pending`
+*   but not all terminal) ⇒ `running`.
+* - every phase `pending` ⇒ `pending`.
+* - all terminal (a `failed` phase counts as terminal here): any `stopped` ⇒ `stopped`; else
+*   any `completed` (or any graceful-bail `failed`, folded into completion) ⇒ `completed`;
+*   else (all `skipped`) ⇒ `skipped`.
+*
+* @param phases - The workflow's per-phase {@link PhaseDerivation}s (status + effective bail), in any order
+* @returns The derived {@link WorkflowStatus}
+*/
+function deriveWorkflowStatus(phases) {
+	if (phases.length === 0) return "pending";
+	if (phases.some((phase) => phase.status === "failed" && phase.bail)) return "failed";
+	if (phases.every((phase) => phase.status === "pending")) return "pending";
+	if (!phases.every((phase) => isTerminalStatus(phase.status))) return "running";
+	if (phases.some((phase) => phase.status === "stopped")) return "stopped";
+	if (phases.some((phase) => phase.status === "completed" || phase.status === "failed" && !phase.bail)) return "completed";
+	return "skipped";
+}
+/**
+* Test whether the live W-b task state machine may move directly from one
+* {@link TaskStatus} to another — the legal-transition guard.
+*
+* @remarks
+* Reads the {@link import('./constants.js').TASK_TRANSITIONS} graph: `true` only when
+* `to` is listed under `from`. A settled (terminal) `from` has no legal targets, so any
+* transition off it is `false`. The W-b `Task` consults this before every transition and
+* throws a `TRANSITION` {@link import('./errors.js').WorkflowError} when it returns `false`.
+*
+* @param from - The task's current status
+* @param to - The status the transition would move it to
+* @returns `true` when the move is legal
+*/
+function canTransitionTask(from, to) {
+	return TASK_TRANSITIONS[from].includes(to);
+}
+/**
+* Build a {@link WorkflowContext} — the identity every level inherits — from a node's
+* `id` / `name` / optional `description`.
+*
+* @remarks
+* The root of the context chain a live {@link import('./Workflow.js').Workflow} exposes;
+* {@link buildPhaseContext} / {@link buildTaskContext} extend it down the tree. Accepts a
+* structural node (a definition or a snapshot node — both carry the three identity fields).
+*
+* @param node - The node's identity (`id` / `name` / optional `description`)
+* @returns The {@link WorkflowContext}
+*/
+function buildWorkflowContext(node) {
+	return {
+		id: node.id,
+		name: node.name,
+		...node.description === void 0 ? {} : { description: node.description }
+	};
+}
+/**
+* Build a {@link PhaseContext} — a phase's own identity plus a back-reference to its
+* workflow — from the parent {@link WorkflowContext} and the phase node's identity.
+*
+* @param workflow - The parent workflow context (the lineage pointer UP the tree)
+* @param node - The phase's identity (`id` / `name` / optional `description`)
+* @returns The {@link PhaseContext}
+*/
+function buildPhaseContext(workflow, node) {
+	return {
+		...buildWorkflowContext(node),
+		workflow
+	};
+}
+/**
+* Build a {@link TaskContext} — a task's own identity plus a back-reference to its phase
+* (and, transitively, its workflow) — from the parent {@link PhaseContext} and the task
+* node's identity.
+*
+* @param phase - The parent phase context (carrying the full lineage UP the tree)
+* @param node - The task's identity (`id` / `name` / optional `description`)
+* @returns The {@link TaskContext}
+*/
+function buildTaskContext(phase, node) {
+	return {
+		...buildWorkflowContext(node),
+		phase
+	};
+}
+/**
+* Narrow an `unknown` to a {@link WorkflowSnapshot} — the AGENTS §14 boundary guard for an
+* UNTRUSTED snapshot read (a storage row a {@link import('./stores/DatabaseWorkflowStore.js').DatabaseWorkflowStore}
+* reads back from its opaque JSON column, a snapshot loaded from disk).
+*
+* @remarks
+* A total guard (it NEVER throws — adversarial input returns `false`, AGENTS §14). It checks the
+* snapshot's SHAPE — `id` / `name` / `status` strings, a `boolean` `bail`, an array of `phases`,
+* `created` / `updated` numbers — enough to safely impose the {@link WorkflowSnapshot} type at a
+* storage boundary WITHOUT a cast. It is complementary to
+* {@link import('./factories.js').assertSnapshot}, which validates the DEEPER invariant (every
+* node's status / override drawn from the lifecycle vocabulary) and THROWS a `RESTORE`
+* {@link import('./errors.js').WorkflowError} — the deep gate a {@link import('./factories.js').restoreWorkflow}
+* applies. A boundary read narrows shape with this guard; a restore validates vocabulary with `assertSnapshot`.
+*
+* @param value - The value to test (an opaque storage read)
+* @returns `true` when `value` has the structural shape of a {@link WorkflowSnapshot}
+*/
+function isWorkflowSnapshot(value) {
+	return isRecord(value) && isString(value.id) && isString(value.name) && isString(value.status) && isBoolean(value.bail) && isArray(value.phases) && isNumber(value.created) && isNumber(value.updated);
+}
+/**
+* Convert a {@link WorkflowDefinition} into an INITIAL {@link WorkflowSnapshot} — every
+* node `pending`, no results, empty metadata — so the live W-b tree has ONE construction
+* path (snapshot-driven) for both a fresh build and a restore.
+*
+* @remarks
+* The structural fields (`id` / `name` / `description` + the ordered phases / tasks)
+* carry over verbatim; the W-b live tree is the DECLARATIVE state machine, so the
+* execution-only definition fields (per-phase `run` / `concurrency`, per-task `retries` /
+* `timeout`) are intentionally dropped (W-c reads them from the definition when it drives
+* transitions). The `bail` policy carries over — at the workflow tier AND, per phase, the
+* EFFECTIVE policy (`phase.bail ?? workflowBail`) on each {@link PhaseSnapshot} — so the seeded
+* snapshot is self-contained; a fresh seed has no `override`. `created` / `updated` are stamped now.
+* {@link import('./factories.js').createWorkflow} builds from this.
+*
+* The optional `bail` override is the EFFECTIVE workflow policy the tree will run under
+* (`createWorkflow` / the runner resolve `options.bail ?? definition.bail ?? DEFAULT_BAIL` and
+* pass it here), so an `options.bail` override reaches BOTH the workflow tier AND the
+* inheritance default of every phase that declares no `bail` of its own — otherwise the
+* per-phase seeds would silently ignore the override. Omitted ⇒ the definition's own `bail`
+* (defaulting to the graceful {@link import('./constants.js').DEFAULT_BAIL}).
+*
+* @param definition - The workflow definition to seed from
+* @param bail - The EFFECTIVE workflow bail to seed both tiers with (defaults to the definition's)
+* @returns An initial, all-`pending` {@link WorkflowSnapshot}
+*/
+function definitionToSnapshot(definition, bail) {
+	const now = Date.now();
+	const workflowBail = bail ?? definition.bail ?? false;
+	return {
+		id: definition.id,
+		name: definition.name,
+		...definition.description === void 0 ? {} : { description: definition.description },
+		status: "pending",
+		bail: workflowBail,
+		phases: definition.phases.map((phase) => phaseDefinitionToSnapshot(phase, workflowBail)),
+		created: now,
+		updated: now
+	};
+}
+/**
+* Convert one {@link import('./types.js').PhaseDefinition} into an initial, all-`pending`
+* {@link PhaseSnapshot} — the per-phase step of {@link definitionToSnapshot}.
+*
+* @remarks
+* The snapshot persists the EFFECTIVE failure policy this phase runs under: the phase's own
+* `bail` when it declares one, else the `workflowBail` it inherits — so a restore reinstates
+* the same per-phase policy without a silent default (`effectiveBail = phase.bail ?? workflowBail`).
+*
+* @param phase - The phase definition to seed from
+* @param workflowBail - The workflow-level `bail` default the phase inherits when it declares none
+* @returns An initial {@link PhaseSnapshot}
+*/
+function phaseDefinitionToSnapshot(phase, workflowBail) {
+	return {
+		id: phase.id,
+		name: phase.name,
+		...phase.description === void 0 ? {} : { description: phase.description },
+		status: "pending",
+		bail: phase.bail ?? workflowBail,
+		tasks: phase.tasks.map((task) => taskDefinitionToSnapshot(task))
+	};
+}
+/**
+* Convert one {@link import('./types.js').TaskDefinition} into an initial, `pending`
+* {@link TaskSnapshot} — the per-task leaf step of {@link definitionToSnapshot} (no
+* result yet, empty metadata).
+*
+* @param task - The task definition to seed from
+* @returns An initial {@link TaskSnapshot}
+*/
+function taskDefinitionToSnapshot(task) {
+	return {
+		id: task.id,
+		name: task.name,
+		...task.description === void 0 ? {} : { description: task.description },
+		status: "pending",
+		metadata: {}
+	};
+}
+/**
+* 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()`.
+*
+* @remarks
+* Pure and order-preserving: phases in order, each phase's task results in order. The
+* W-b `Workflow.results()` calls this over its phases' `results()`; a phase's own
+* `results()` is the per-phase list this consumes.
+*
+* @param phases - The per-phase result lists, in phase order
+* @returns One flattened {@link TaskResult} list, in positional order
+*/
+function collectResults(phases) {
+	return phases.flat();
+}
+/**
+* Summarize a terminal {@link WorkflowResult} into the PLAIN value a
+* {@link import('./factories.js').createWorkflowTool} handler returns on success.
+*
+* @remarks
+* This is the run summary the handler returns DIRECTLY — NOT a `ToolResult` (the future `@orkestrel/agent` package).
+* The handler conforms to the universal tool-handler contract (AGENTS §14): it returns the plain value
+* (and throws on failure), so the `@orkestrel/agent` package's `ToolManager` performs
+* the ONE canonical wrap (`{ id, name, value }`) and the model reads exactly this summary — once,
+* identically — over BOTH the agent loop and MCP. The summary is LEAN: the workflow's terminal `status`
+* and the COUNT of settled task results — enough for a caller / model to react without serializing the
+* whole live tree. (It carries no synthetic `id` / `name`: a tool handler has no call id; the manager
+* supplies the canonical envelope's identity.)
+*
+* @param result - The terminal {@link WorkflowResult} the run produced
+* @returns The plain success summary — `{ status, count }`
+*/
+function workflowToolSummary(result) {
+	return {
+		status: result.status,
+		count: result.results.length
+	};
+}
+/**
+* Complete a {@link WorkflowDraft} into a strict {@link WorkflowDefinition} — synthesize
+* any MISSING `id` deterministically + positionally, and default any MISSING `name` to
+* its (now-resolved) `id`.
+*
+* @remarks
+* The positional id scheme is stable and human-legible: the workflow is `wf`, phase `i`
+* is `phase-<i>`, and task `j` of that phase is `<phaseId>-task-<j>` (so a provided phase
+* id flows into its tasks' synthesized ids). A PROVIDED `id` / `name` at any level is kept
+* VERBATIM — synthesis touches only the omitted ones. A missing `name` defaults to the
+* resolved `id` (never the other way round), so the result always has both. `run`,
+* `description`, the per-phase `concurrency` / `bail`, the per-task `retries` / `timeout`, and
+* the workflow `bail` carry over unchanged. The result is a complete
+* {@link WorkflowDefinition}; the caller still validates it against the STRICT contract.
+*
+* @param draft - The draft workflow (id/name optional at all three levels)
+* @returns A complete {@link WorkflowDefinition} with every id/name filled
+*/
+function completeDraft(draft) {
+	const id = draft.id ?? "wf";
+	return {
+		id,
+		name: draft.name ?? id,
+		...draft.description === void 0 ? {} : { description: draft.description },
+		phases: draft.phases.map((phase, index) => completePhaseDraft(phase, index)),
+		...draft.bail === void 0 ? {} : { bail: draft.bail }
+	};
+}
+/**
+* Complete one {@link PhaseDraft} into a strict {@link PhaseDefinition} — the per-phase
+* step of {@link completeDraft} (phase `index` → `phase-<index>` when its id is omitted).
+*
+* @param phase - The draft phase
+* @param index - The phase's positional index in the workflow
+* @returns A complete {@link PhaseDefinition}
+*/
+function completePhaseDraft(phase, index) {
+	const id = phase.id ?? `phase-${index}`;
+	return {
+		id,
+		name: phase.name ?? id,
+		...phase.description === void 0 ? {} : { description: phase.description },
+		tasks: phase.tasks.map((task, taskIndex) => completeTaskDraft(task, id, taskIndex)),
+		...phase.concurrency === void 0 ? {} : { concurrency: phase.concurrency },
+		...phase.bail === void 0 ? {} : { bail: phase.bail }
+	};
+}
+/**
+* Complete one {@link TaskDraft} into a strict {@link TaskDefinition} — the per-task leaf
+* step of {@link completeDraft} (task `index` of phase `<phaseId>` → `<phaseId>-task-<index>`
+* when its id is omitted).
+*
+* @param task - The draft task
+* @param phaseId - The (resolved) parent phase id, so the synthesized task id nests under it
+* @param index - The task's positional index within its phase
+* @returns A complete {@link TaskDefinition}
+*/
+function completeTaskDraft(task, phaseId, index) {
+	const id = task.id ?? `${phaseId}-task-${index}`;
+	return {
+		id,
+		name: task.name ?? id,
+		...task.description === void 0 ? {} : { description: task.description },
+		run: task.run,
+		...task.retries === void 0 ? {} : { retries: task.retries },
+		...task.timeout === void 0 ? {} : { timeout: task.timeout }
+	};
+}
+/**
+* Expand a flat {@link WorkflowSteps} blob into a strict {@link WorkflowDefinition} — each
+* step becomes a one-task phase, IN ORDER.
+*
+* @remarks
+* The expansion of the tool's ADVERTISED surface (AGENTS §21 — the simplest form a small
+* model can author). Each {@link WorkflowStep} maps to a phase holding exactly one task:
+* the step's `name` becomes the task's `run.name`, and its `via` becomes the task's `run.via`
+* (defaulting to `'function'` when omitted). Ids/names are auto-filled positionally — it
+* builds an ids-omitted {@link WorkflowDraft} and delegates to {@link completeDraft}, so the
+* two lenient surfaces share ONE synthesis path (step `i` → phase `phase-<i>`, its task
+* `phase-<i>-task-0`). The optional `name` becomes the workflow's `name`. The result is a
+* complete definition the caller validates against the STRICT contract before running.
+*
+* @param flat - The flat steps blob (`{ name?, steps: [{ name, via? }] }`)
+* @returns A complete {@link WorkflowDefinition} (one one-task phase per step)
+*/
+function expandSteps(flat) {
+	return completeDraft({
+		...flat.name === void 0 ? {} : { name: flat.name },
+		phases: flat.steps.map((step) => ({ tasks: [{ run: stepToForm(step) }] }))
+	});
+}
+/**
+* Convert one flat {@link WorkflowStep} into a {@link TaskForm} — `name` → the form's `name`,
+* `via` → the form's discriminant (defaulting to `'function'`).
+*
+* @param step - The flat step
+* @returns The {@link TaskForm} the step's task runs
+*/
+function stepToForm(step) {
+	return {
+		via: step.via ?? "function",
+		name: step.name
+	};
+}
+/**
+* Create a {@link DeferredInterface} — a promise whose settlement is driven
+* externally, so a caller can resolve/reject it from outside the executor.
+*
+* @typeParam T - The value the deferred promise resolves
+* @returns A deferred `promise` plus its `resolve` / `reject`
+*/
+function createDeferred() {
+	let resolve = () => {};
+	let reject = () => {};
+	return {
+		promise: new Promise((res, rej) => {
+			resolve = res;
+			reject = rej;
+		}),
+		resolve,
+		reject
+	};
+}
+//#endregion
+//#region src/core/shapers.ts
+/**
+* The shape of a {@link import('./types.js').TaskForm} — a descriptive tagged union
+* over the three execution mechanisms, discriminated by the `via` literal (never a
+* bare `kind`; AGENTS §4.4). Each variant pairs the `via` discriminant with a `name`
+* (the registry key for the behavior).
+*
+* @remarks
+* The union and each `via` literal + `name` carry a `description` so the emitted JSON
+* Schema spells out what the discriminant means and that `name` is a REGISTERED key
+* (not a human label) — the field-level guidance a small model needs to fill `run`.
+*/
+var taskFormShape = unionShape(objectShape({
+	via: literalShape(["function"], { description: "Run a registered workflow FUNCTION by name." }),
+	name: stringShape({
+		min: 1,
+		description: "The registered function name to invoke (a registry key, not a label)."
+	})
+}), objectShape({
+	via: literalShape(["tool"], { description: "Run a registered TOOL by name." }),
+	name: stringShape({
+		min: 1,
+		description: "The registered tool name to invoke (a registry key, not a label)."
+	})
+}), objectShape({
+	via: literalShape(["agent"], { description: "Run a registered AGENT (a subagent) by name." }),
+	name: stringShape({
+		min: 1,
+		description: "The registered agent name to invoke (a registry key, not a label)."
+	})
+}));
+/**
+* The shape of a {@link import('./types.js').TaskDefinition} — identity plus the
+* behavior reference ({@link taskFormShape}). `description` is optional prose.
+*/
+var taskShape = objectShape({
+	id: stringShape({
+		min: 1,
+		description: "Unique task id within its phase."
+	}),
+	name: stringShape({
+		min: 1,
+		description: "Human-readable task name."
+	}),
+	description: optionalShape(stringShape({ description: "Optional task description." })),
+	run: taskFormShape,
+	retries: optionalShape(integerShape({
+		min: 0,
+		description: "Extra attempts after the first on failure; overrides the phase default. Omitted means none."
+	})),
+	timeout: optionalShape(integerShape({
+		min: 0,
+		description: "Per-attempt deadline in milliseconds; overrides the phase default. Omitted means no deadline."
+	}))
+});
+/**
+* The shape of a {@link import('./types.js').PhaseDefinition} — identity, its ordered
+* {@link taskShape} tasks, and an optional positive-integer `concurrency` throttle
+* (max tasks in flight; omitted ⇒ unbounded).
+*/
+var phaseShape = objectShape({
+	id: stringShape({
+		min: 1,
+		description: "Unique phase id within the workflow."
+	}),
+	name: stringShape({
+		min: 1,
+		description: "Human-readable phase name."
+	}),
+	description: optionalShape(stringShape({ description: "Optional phase description." })),
+	tasks: arrayShape(taskShape, { description: "The phase tasks; they run CONCURRENTLY." }),
+	concurrency: optionalShape(integerShape({
+		min: 1,
+		description: "Max tasks in flight at once (a resource throttle); omitted means unbounded."
+	})),
+	bail: optionalShape(literalShape([true, false], { description: "Per-phase failure-policy override; omitted inherits the workflow bail." }))
+});
+/**
+* The shape of a {@link import('./types.js').WorkflowDefinition} — the contract root:
+* identity, its ordered {@link phaseShape} phases, and the optional `bail` boolean
+* failure policy (the literal pair `true`/`false`, the runtime mirror of the boolean
+* toggle; omitted ⇒ the graceful default).
+*/
+var workflowShape = objectShape({
+	id: stringShape({
+		min: 1,
+		description: "Unique workflow id."
+	}),
+	name: stringShape({
+		min: 1,
+		description: "Human-readable workflow name."
+	}),
+	description: optionalShape(stringShape({ description: "Optional workflow description." })),
+	phases: arrayShape(phaseShape, { description: "The workflow phases; they run SEQUENTIALLY, in order." }),
+	bail: optionalShape(literalShape([true, false], { description: "Failure policy: false (default) continues gracefully, true halts on the first failure." }))
+});
+/**
+* The shape of a TASK in a draft workflow — identical to {@link taskShape} EXCEPT `id`
+* and `name` are OPTIONAL (the tool synthesizes any missing one positionally).
+*
+* @remarks
+* A PROVIDED `id` / `name` still carries `minLength: 1`, so an explicitly-empty `id: ''`
+* is INVALID (rejected by the draft contract), never auto-filled — keeping "garbage"
+* distinct from "omitted". `run` stays required.
+*/
+var taskDraftShape = objectShape({
+	id: optionalShape(stringShape({
+		min: 1,
+		description: "Task id; auto-filled when omitted."
+	})),
+	name: optionalShape(stringShape({
+		min: 1,
+		description: "Task name; defaults to the id when omitted."
+	})),
+	description: optionalShape(stringShape({ description: "Optional task description." })),
+	run: taskFormShape,
+	retries: optionalShape(integerShape({
+		min: 0,
+		description: "Extra attempts after the first on failure; overrides the phase default. Omitted means none."
+	})),
+	timeout: optionalShape(integerShape({
+		min: 0,
+		description: "Per-attempt deadline in milliseconds; overrides the phase default. Omitted means no deadline."
+	}))
+});
+/**
+* The shape of a PHASE in a draft workflow — identical to {@link phaseShape} EXCEPT
+* `id` and `name` are OPTIONAL, and its tasks are {@link taskDraftShape}s.
+*/
+var phaseDraftShape = objectShape({
+	id: optionalShape(stringShape({
+		min: 1,
+		description: "Phase id; auto-filled when omitted."
+	})),
+	name: optionalShape(stringShape({
+		min: 1,
+		description: "Phase name; defaults to the id when omitted."
+	})),
+	description: optionalShape(stringShape({ description: "Optional phase description." })),
+	tasks: arrayShape(taskDraftShape, { description: "The phase tasks; they run CONCURRENTLY." }),
+	concurrency: optionalShape(integerShape({
+		min: 1,
+		description: "Max tasks in flight at once (a resource throttle); omitted means unbounded."
+	})),
+	bail: optionalShape(literalShape([true, false], { description: "Per-phase failure-policy override; omitted inherits the workflow bail." }))
+});
+/**
+* The shape of a DRAFT workflow — identical to {@link workflowShape} EXCEPT `id` and
+* `name` are OPTIONAL at all three levels (workflow / phase / task), so a small model
+* can omit the six identity strings and let the tool synthesize them positionally.
+*
+* @remarks
+* The lenient counterpart {@link import('./factories.js').createWorkflowDraftContract}
+* compiles. `run` stays required; a provided `id` / `name` still has `minLength: 1` (so an
+* explicitly-empty `id: ''` is REJECTED, not auto-filled). After
+* {@link import('./helpers.js').completeDraft} fills the missing ids/names, the result is
+* validated against the STRICT {@link import('./factories.js').createWorkflowContract} gate
+* before running.
+*/
+var workflowDraftShape = objectShape({
+	id: optionalShape(stringShape({
+		min: 1,
+		description: "Workflow id; auto-filled when omitted."
+	})),
+	name: optionalShape(stringShape({
+		min: 1,
+		description: "Workflow name; defaults to the id when omitted."
+	})),
+	description: optionalShape(stringShape({ description: "Optional workflow description." })),
+	phases: arrayShape(phaseDraftShape, { description: "The workflow phases; they run SEQUENTIALLY, in order." }),
+	bail: optionalShape(literalShape([true, false], { description: "Failure policy: false (default) continues gracefully, true halts on the first failure." }))
+});
+/**
+* The shape of ONE flat step — `{ name, via? }` — the building block of
+* {@link workflowStepsShape}.
+*
+* @remarks
+* `name` is the REGISTERED behavior name the step runs (it becomes the task's `run.name`);
+* `via` is the optional execution mechanism (defaults to `'function'` when omitted). The
+* tool expands each step into a one-task phase, in order
+* ({@link import('./helpers.js').expandSteps}).
+*/
+var stepShape = objectShape({
+	name: stringShape({
+		min: 1,
+		description: "The registered behavior name this step runs (becomes the task run.name)."
+	}),
+	via: optionalShape(literalShape([
+		"function",
+		"tool",
+		"agent"
+	], { description: "How to run it: function (default), tool, or agent." }))
+});
+/**
+* The FLAT authoring shape `createWorkflowTool` advertises as its `parameters` — the
+* simplest surface a small model can fill: `{ name?, steps: [{ name, via? }] }`.
+*
+* @remarks
+* The deliberately-reduced surface (AGENTS §21): a flat ordered list of steps, each a
+* `{ name, via? }`. The tool EXPANDS it ({@link import('./helpers.js').expandSteps}) into a
+* full {@link import('./types.js').WorkflowDefinition} — one one-task phase per step, in
+* order — then validates against the STRICT
+* {@link import('./factories.js').createWorkflowContract} gate. The full nested form is
+* STILL accepted by the tool (it branches on the args' shape) and is documented as the
+* advanced escape-hatch in the tool's description — but THIS is what `parameters` advertises.
+*/
+var workflowStepsShape = objectShape({
+	name: optionalShape(stringShape({
+		min: 1,
+		description: "Optional workflow name."
+	})),
+	steps: arrayShape(stepShape, { description: "The ordered steps to run, one after another (each becomes a one-task phase)." })
+});
+//#endregion
+//#region src/core/stores/DatabaseWorkflowStore.ts
+/**
+* A {@link WorkflowStoreInterface} backed by one table of the `databases` layer — a
+* workflow's durable run-state IS a row, so persistence reduces to keyed point-access
+* (`get` / `set` / `delete`) over a `TableInterface`, the driver-pluggable twin of the
+* plain-`Map` {@link import('./MemoryWorkflowStore.js').MemoryWorkflowStore}.
+*
+* @remarks
+* The store is driver-agnostic: it holds a single {@link TableInterface} whose backend
+* (memory, JSON, SQLite, IndexedDB) is chosen by whoever builds it (the factories), so a
+* JSON / SQLite / IndexedDB backend swaps in WITHOUT touching the runner or the entity tree
+* — the same seam as `@orkestrel/queue`'s `DatabaseQueueStore`.
+* The driver defaults to memory ({@link import('../factories.js').createDatabaseWorkflowStore}
+* passes `createMemoryDriver()`), so it ALSO works in memory out of the box; you opt into the
+* durable plumbing by passing a JSON / SQLite / IndexedDB driver.
+*
+* The {@link WorkflowSnapshot} is stored as ONE OPAQUE JSON COLUMN — the table is a row of
+* `{ id; snapshot }` ({@link WorkflowSnapshotRow}), the snapshot the whole JSON blob (a `rawShape`
+* column the factory builds) — exactly as `DatabaseQueueStore` stores its `input`. The snapshot is
+* already a COMPLETE, self-contained, pure-JSON payload, so storing it whole is lossless AND
+* sidesteps a TS2589 instantiation-depth blow-up: a structured multi-column table would force the
+* contract to `Infer` the deeply-nested snapshot shape (workflow → phases → tasks → results),
+* tripping the compiler — one JSON column keeps the row type flat (`snapshot` reads back as `unknown`).
+*
+* - **`set(snapshot)` upserts under the snapshot's OWN `id`** (no separate id param) — it writes
+*   the row `{ id: snapshot.id, snapshot }`.
+* - **`get(id)` resolves the stored snapshot for an id**, narrowing the opaque JSON column back to
+*   a {@link WorkflowSnapshot} ({@link import('../helpers.js').isWorkflowSnapshot} — the AGENTS §14
+*   boundary narrow for an untrusted storage read), or `undefined` if none is stored.
+* - **`delete(id)` drops a snapshot by id**; an absent id is a no-op (no throw).
+*
+* UNLIKE the server package's `SessionStoreInterface` there is NO
+* 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}.
+*
+* @example
+* ```ts
+* import { createDatabaseWorkflowStore, createMemoryDriver, createWorkflow, restoreWorkflow } from '@src/core'
+*
+* 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
+* await store.delete(definition.id)                // drop it
+* ```
+*/
+var DatabaseWorkflowStore = class {
+	#table;
+	/**
+	* Wrap a table as a workflow store.
+	*
+	* @param table - The {@link TableInterface} holding the snapshots — its row is the
+	*   {@link WorkflowSnapshotRow} `{ id; snapshot }` shape (the snapshot one opaque JSON column)
+	*/
+	constructor(table) {
+		this.#table = table;
+	}
+	/** Resolve the persisted snapshot for `id`, narrowing the opaque JSON column back to a `WorkflowSnapshot`. */
+	async get(id) {
+		const row = await this.#table.get(id);
+		if (row === void 0) return void 0;
+		return isWorkflowSnapshot(row.snapshot) ? row.snapshot : void 0;
+	}
+	/** Insert or replace under the snapshot's OWN `id` (no separate id param) — the row is `{ id, snapshot }`. */
+	async set(snapshot) {
+		await this.#table.set({
+			id: snapshot.id,
+			snapshot
+		});
+	}
+	/** Drop a snapshot by id; an absent id is a no-op (no throw). */
+	async delete(id) {
+		await this.#table.remove(id);
+	}
+};
+//#endregion
+//#region src/core/stores/MemoryWorkflowStore.ts
+/**
+* The in-memory {@link WorkflowStoreInterface} — a process-lifetime `Map` of
+* {@link WorkflowSnapshot}s keyed by workflow id, the DEFAULT store
+* {@link import('../factories.js').createMemoryWorkflowStore} builds.
+*
+* @remarks
+* A plain `Map<string, WorkflowSnapshot>` (AGENTS §21 — the snapshot is already pure,
+* self-contained JSON, so no encoding is needed for the memory tier). UNLIKE the server
+* package's `SessionStoreInterface`'s memory store there is
+* NO idle-TTL and NO eviction: a persisted workflow run-state is durable orchestration state
+* that lives until an explicit `delete`, never silently aging out (a run that vanished
+* mid-flight would be a silent data loss, not a freed session). A durable backend (JSON /
+* SQLite / IndexedDB) swaps in through the SAME interface without touching the runner or the
+* entity tree — its driver-pluggable twin is
+* {@link import('./DatabaseWorkflowStore.js').DatabaseWorkflowStore} (the snapshot as one opaque
+* JSON column), exactly as `@orkestrel/queue`'s `MemoryQueueStore`
+* twins `DatabaseQueueStore`.
+*
+* - **`get` resolves the persisted snapshot for an id**, or `undefined` if none is stored.
+* - **`set` inserts / replaces under the snapshot's OWN `id`** (no separate id param).
+* - **`delete` drops a snapshot by id**; an absent id is a no-op (no throw).
+*
+* 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}.
+*
+* @example
+* ```ts
+* import { createMemoryWorkflowStore, createWorkflow, restoreWorkflow } from '@src/core'
+*
+* 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
+* await store.delete(definition.id)          // drop it
+* ```
+*/
+var MemoryWorkflowStore = class {
+	#snapshots = /* @__PURE__ */ new Map();
+	get(id) {
+		return Promise.resolve(this.#snapshots.get(id));
+	}
+	set(snapshot) {
+		this.#snapshots.set(snapshot.id, snapshot);
+		return Promise.resolve();
+	}
+	delete(id) {
+		this.#snapshots.delete(id);
+		return Promise.resolve();
+	}
+};
+//#endregion
+//#region src/core/tasks/Task.ts
+/**
+* The live leaf state machine (W-b) for one task — an observable (AGENTS §13), guarded
+* synchronous task whose explicit {@link TaskStatus} advances through the AGENTS §10
+* transitions, recording a {@link TaskResult} on a terminal outcome.
+*
+* @remarks
+* - **Guarded transitions (AGENTS §10).** `start` (→ `running`), then `complete(value)`
+*   (→ `completed`, records a {@link import('@orkestrel/contract').Success}), `fail(error)`
+*   (→ `failed`, records a {@link import('@orkestrel/contract').Failure}), `skip` (→ `skipped`),
+*   `stop` (→ `stopped`). Each consults {@link canTransitionTask} FIRST and throws a
+*   `TRANSITION` {@link WorkflowError} on an illegal move (e.g. completing a non-`running`
+*   task) — the legal graph is the single source of truth, so the leaf can never reach an
+*   impossible state.
+* - **Override (snapshot fidelity).** `skip` / `stop` set `#override` to the forced terminal
+*   status, so a RESTORE can tell a forced leaf (`skipped` / `stopped`) from a run-produced
+*   one and reinstate it AS an override — preserving the round-trip.
+* - **The cascade.** Every status change records its boxed result (when any), fires the leaf's
+*   OWN event, THEN calls the parent phase's `#recompute` (injected at construction) so the
+*   transition propagates UP (Task → Phase → Workflow re-derive). The own-event-before-cascade
+*   order means an observer sees the CAUSE (this leaf changed) before the EFFECT (the parents
+*   re-derive) — the project precedent (`Runner.#settle` emits its own `fail` before propagating).
+* - **Observable (AGENTS §13).** The owned {@link emitter} ({@link TaskEventMap}) fires the
+*   matching event strictly AFTER the state change, BEFORE the cascade; the emitter isolates
+*   a listener throw and routes it to its `error` handler (the `error` option), so a buggy
+*   observer can never corrupt a transition.
+*/
+var Task = class {
+	#context;
+	#phase;
+	#workflow;
+	#recompute;
+	#metadata;
+	#emitter;
+	#status;
+	#result;
+	constructor(context, phase, workflow, recompute, options, status = "pending", result) {
+		this.#context = context;
+		this.#phase = phase;
+		this.#workflow = workflow;
+		this.#recompute = recompute;
+		this.#metadata = options?.metadata ?? {};
+		this.#emitter = new Emitter({
+			on: options?.on,
+			error: options?.error
+		});
+		this.#status = status;
+		this.#result = result;
+	}
+	get emitter() {
+		return this.#emitter;
+	}
+	get id() {
+		return this.#context.id;
+	}
+	get name() {
+		return this.#context.name;
+	}
+	get description() {
+		return this.#context.description;
+	}
+	get context() {
+		return this.#context;
+	}
+	get phase() {
+		return this.#phase;
+	}
+	get workflow() {
+		return this.#workflow;
+	}
+	get status() {
+		return this.#status;
+	}
+	get result() {
+		return this.#result;
+	}
+	start() {
+		this.#transition("running");
+		this.#emitter.emit("start", this.id);
+		this.#escalate();
+	}
+	complete(value) {
+		this.#transition("completed");
+		const result = this.#record("completed", {
+			success: true,
+			value
+		});
+		this.#emitter.emit("complete", result);
+		this.#escalate();
+	}
+	fail(error) {
+		this.#transition("failed");
+		const reason = error instanceof Error ? error : new Error(String(error), { cause: error });
+		const result = this.#record("failed", {
+			success: false,
+			error: reason
+		});
+		this.#emitter.emit("fail", result);
+		this.#escalate();
+	}
+	skip() {
+		this.#transition("skipped");
+		this.#emitter.emit("skip");
+		this.#escalate();
+	}
+	stop() {
+		this.#transition("stopped");
+		this.#emitter.emit("stop");
+		this.#escalate();
+	}
+	snapshot() {
+		return {
+			id: this.id,
+			name: this.name,
+			...this.description === void 0 ? {} : { description: this.description },
+			status: this.#status,
+			...this.#result === void 0 ? {} : { result: this.#result },
+			metadata: this.#metadata
+		};
+	}
+	#transition(to) {
+		if (!canTransitionTask(this.#status, to)) throw new WorkflowError("TRANSITION", `task '${this.id}' cannot transition from '${this.#status}' to '${to}'`, {
+			task: this.id,
+			from: this.#status,
+			to
+		});
+		this.#status = to;
+	}
+	#record(status, result) {
+		const record = {
+			task: this.#context,
+			phase: this.#context.phase,
+			workflow: this.#context.phase.workflow,
+			status,
+			...result === void 0 ? {} : { result },
+			timestamp: Date.now()
+		};
+		this.#result = record;
+		return record;
+	}
+	#escalate() {
+		this.#recompute();
+	}
+};
+//#endregion
+//#region src/core/tasks/TaskManager.ts
+/**
+* The lean child manager (AGENTS §9) of a {@link import('../phases/Phase.js').Phase}'s live
+* tasks — an insertion-ordered registry keyed by task `id`, so positional order is
+* preserved across an interior `skip` / `remove`.
+*
+* @remarks
+* - **Positional store.** Tasks live in an insertion-ordered `Map` keyed by `id`;
+*   `append` adds one at the end (the build-time wiring path), `task(id)` looks one up,
+*   `tasks()` lists them in positional order, `count` is the size. A `skip` is a STATUS
+*   change on a stored task (never a removal), so order survives it; a snapshot RESTORE
+*   re-`append`s in the snapshot's order, reproducing it exactly.
+* - **No batch matrix.** A phase's tasks are a fixed positional set, so AGENTS §9.2 (the
+*   bulk verb overloads) is deliberately omitted — there is no `remove` family here.
+* - **Event-free.** A purely structural container — the live {@link TaskInterface}s own
+*   their own emitters; the manager observes nothing.
+*
+* @example
+* ```ts
+* const tasks = new TaskManager()
+* tasks.append(task) // a live Task
+* tasks.task(task.id) // the same task
+* tasks.count // 1
+* ```
+*/
+var TaskManager = class {
+	#tasks = /* @__PURE__ */ new Map();
+	get count() {
+		return this.#tasks.size;
+	}
+	append(task) {
+		this.#tasks.set(task.id, task);
+	}
+	task(id) {
+		return this.#tasks.get(id);
+	}
+	tasks() {
+		return [...this.#tasks.values()];
+	}
+};
+//#endregion
+//#region src/core/phases/Phase.ts
+/**
+* The live DERIVED state machine (W-b) for one phase — an observable (AGENTS §13) whose
+* {@link PhaseStatus} is computed from its tasks (never set directly) and recomputed
+* reactively as a task transitions (the middle tier of the cascade).
+*
+* @remarks
+* - **Derived status.** `status` is `#override` when one is in force, else
+*   {@link derivePhaseStatus} over the live tasks' statuses. {@link #recompute} (passed to
+*   each child {@link Task}) re-derives on every child transition; a CHANGE emits the matching
+*   event AND escalates to the workflow ({@link #escalate}, the upward step of the cascade).
+* - **Override (AGENTS §10).** `skip` / `stop` FORCE the phase's status (e.g. skipping a whole
+*   phase), overriding the derived value; the override is PERSISTED in the snapshot's own
+*   `override` field and restored DIRECTLY (no divergence guess), so a forced phase round-trips.
+* - **Children (AGENTS §9).** `tasks` is the lean {@link TaskManager} (an accessor + `count`,
+*   no batch matrix); built positionally from the snapshot so order survives an interior `skip`.
+*   `results()` collects the settled tasks' {@link TaskResult}s (the phase tier of the result
+*   tree); `workflow` navigates UP to the live parent.
+* - **Observable (AGENTS §13).** The owned {@link emitter} ({@link PhaseEventMap}) fires
+*   `start` / `complete` / `fail` / `stop` on a derived-status CHANGE, strictly AFTER the
+*   recompute + escalate; the emitter isolates a listener throw and routes it to its `error`
+*   handler (the `error` option); `fail` carries the failing task's {@link TaskResult}.
+*/
+var Phase = class {
+	#context;
+	#workflow;
+	#escalateUp;
+	#tasks = new TaskManager();
+	#bail;
+	#emitter;
+	#status;
+	#override;
+	constructor(snapshot, workflow, escalate, options, bail) {
+		this.#context = {
+			id: snapshot.id,
+			name: snapshot.name,
+			workflow: workflow.context
+		};
+		if (snapshot.description !== void 0) this.#context = {
+			...this.#context,
+			description: snapshot.description
+		};
+		this.#workflow = workflow;
+		this.#escalateUp = escalate;
+		this.#bail = bail ?? snapshot.bail;
+		this.#emitter = new Emitter({
+			on: options?.on,
+			error: options?.error
+		});
+		for (const task of snapshot.tasks) this.#append(task, options);
+		this.#override = snapshot.override;
+		this.#status = this.status;
+	}
+	get emitter() {
+		return this.#emitter;
+	}
+	get id() {
+		return this.#context.id;
+	}
+	get name() {
+		return this.#context.name;
+	}
+	get description() {
+		return this.#context.description;
+	}
+	get context() {
+		return this.#context;
+	}
+	get workflow() {
+		return this.#workflow;
+	}
+	get bail() {
+		return this.#bail;
+	}
+	get status() {
+		return this.#override ?? derivePhaseStatus(this.#statuses());
+	}
+	get tasks() {
+		return this.#tasks;
+	}
+	task(id) {
+		return this.#tasks.task(id);
+	}
+	results() {
+		const results = [];
+		for (const task of this.#tasks.tasks()) if (task.result !== void 0) results.push(task.result);
+		return results;
+	}
+	skip() {
+		this.#force("skipped");
+	}
+	stop() {
+		this.#force("stopped");
+	}
+	snapshot() {
+		return {
+			id: this.id,
+			name: this.name,
+			...this.description === void 0 ? {} : { description: this.description },
+			status: this.status,
+			...this.#override === void 0 ? {} : { override: this.#override },
+			bail: this.#bail,
+			tasks: this.#tasks.tasks().map((task) => task.snapshot())
+		};
+	}
+	#recompute() {
+		const next = this.status;
+		if (next === this.#status) {
+			this.#escalateUp();
+			return;
+		}
+		this.#status = next;
+		this.#emitFor(next);
+		this.#escalateUp();
+	}
+	#force(status) {
+		this.#override = status;
+		this.#recompute();
+	}
+	#emitFor(status) {
+		if (status === "running") this.#emitter.emit("start", this.id);
+		else if (status === "completed") this.#emitter.emit("complete");
+		else if (status === "failed") this.#emitter.emit("fail", this.#failure());
+		else if (status === "stopped") this.#emitter.emit("stop");
+	}
+	#failure() {
+		for (const task of this.#tasks.tasks()) {
+			const result = task.result;
+			if (result?.result?.success === false) return result;
+		}
+		throw new Error(`phase '${this.id}' derived failed with no failing task result`);
+	}
+	#append(task, options) {
+		const created = new Task(buildTaskContext(this.#context, task), this, this.#workflow, () => this.#recompute(), options?.tasks?.[task.id], task.status, task.result);
+		this.#tasks.append(created);
+	}
+	#statuses() {
+		return this.#tasks.tasks().map((task) => task.status);
+	}
+};
+//#endregion
+//#region src/core/phases/PhaseManager.ts
+/**
+* The lean child manager (AGENTS §9) of a {@link import('../Workflow.js').Workflow}'s
+* live phases — an insertion-ordered registry keyed by phase `id`, the phase analogue
+* of {@link import('../tasks/TaskManager.js').TaskManager}.
+*
+* @remarks
+* - **Positional store.** Phases live in an insertion-ordered `Map` keyed by `id`;
+*   `append` adds one at the end, `phase(id)` looks one up, `phases()` lists them in
+*   positional order, `count` is the size. A snapshot RESTORE re-`append`s in the
+*   snapshot's order, reproducing it exactly.
+* - **No batch matrix.** A workflow's phases are a fixed positional set, so AGENTS §9.2
+*   is deliberately omitted.
+* - **Event-free.** A purely structural container — the live {@link PhaseInterface}s own
+*   their own emitters.
+*
+* @example
+* ```ts
+* const phases = new PhaseManager()
+* phases.append(phase) // a live Phase
+* phases.phase(phase.id) // the same phase
+* phases.count // 1
+* ```
+*/
+var PhaseManager = class {
+	#phases = /* @__PURE__ */ new Map();
+	get count() {
+		return this.#phases.size;
+	}
+	append(phase) {
+		this.#phases.set(phase.id, phase);
+	}
+	phase(id) {
+		return this.#phases.get(id);
+	}
+	phases() {
+		return [...this.#phases.values()];
+	}
+};
+//#endregion
+//#region src/core/Workflow.ts
+/**
+* The live DERIVED state machine (W-b) for a whole workflow — the observable (AGENTS §13)
+* ROOT whose {@link WorkflowStatus} is computed from its phases under the `bail` policy and
+* recomputed reactively as the cascade propagates up from a task transition.
+*
+* @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}
+*   passes a persisted one). Each child {@link Phase} is wired to escalate to {@link #recompute}.
+* - **Derived status.** `status` is `#override` when forced, else
+*   {@link deriveWorkflowStatus} over the live phases' statuses feeding `bail`. `failed` is
+*   reachable ONLY under `bail: true` (a single failed task halts the workflow); under
+*   `bail: false` a failed phase folds into `completed`. {@link #recompute} diffs on each phase
+*   change; a CHANGE emits.
+* - **Override (AGENTS §10).** `skip` / `stop` FORCE the status; the override is PERSISTED in the
+*   snapshot's own `override` field and restored DIRECTLY (no divergence guess). The snapshot also
+*   persists `bail`, so a restore re-derives status identically without a silent policy default.
+* - **Result tree.** `results()` flattens every phase's `results()` ({@link collectResults}) — the
+*   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.
+* - **Observable (AGENTS §13).** The owned {@link emitter} ({@link WorkflowEventMap}) fires
+*   `start` / `complete` / `fail` / `stop` on a derived-status CHANGE; the emitter isolates a
+*   listener throw and routes it to its `error` handler (the `error` option); `fail` carries
+*   the failing task's {@link TaskResult}.
+*/
+var Workflow = class {
+	#context;
+	#bail;
+	#bailOverride;
+	#phases = new PhaseManager();
+	#emitter;
+	#created;
+	#updated;
+	#status;
+	#override;
+	constructor(snapshot, options) {
+		this.#context = buildWorkflowContext(snapshot);
+		this.#bail = options?.bail ?? snapshot.bail;
+		this.#bailOverride = options?.bail;
+		this.#emitter = new Emitter({
+			on: options?.on,
+			error: options?.error
+		});
+		this.#created = snapshot.created;
+		this.#updated = snapshot.updated;
+		for (const phase of snapshot.phases) this.#append(phase, options);
+		this.#override = snapshot.override;
+		this.#status = this.status;
+	}
+	get emitter() {
+		return this.#emitter;
+	}
+	get id() {
+		return this.#context.id;
+	}
+	get name() {
+		return this.#context.name;
+	}
+	get description() {
+		return this.#context.description;
+	}
+	get context() {
+		return this.#context;
+	}
+	get bail() {
+		return this.#bail;
+	}
+	get status() {
+		return this.#override ?? deriveWorkflowStatus(this.#statuses());
+	}
+	get phases() {
+		return this.#phases;
+	}
+	phase(id) {
+		return this.#phases.phase(id);
+	}
+	results() {
+		return collectResults(this.#phases.phases().map((phase) => phase.results()));
+	}
+	skip() {
+		this.#force("skipped");
+	}
+	stop() {
+		this.#force("stopped");
+	}
+	complete() {
+		this.#force("completed");
+	}
+	snapshot() {
+		return {
+			id: this.id,
+			name: this.name,
+			...this.description === void 0 ? {} : { description: this.description },
+			status: this.status,
+			...this.#override === void 0 ? {} : { override: this.#override },
+			bail: this.#bail,
+			phases: this.#phases.phases().map((phase) => phase.snapshot()),
+			created: this.#created,
+			updated: this.#updated
+		};
+	}
+	#recompute() {
+		const next = this.status;
+		if (next === this.#status) return;
+		this.#status = next;
+		this.#updated = Date.now();
+		this.#emitFor(next);
+	}
+	#force(status) {
+		this.#override = status;
+		this.#recompute();
+	}
+	#emitFor(status) {
+		if (status === "running") this.#emitter.emit("start", this.id);
+		else if (status === "completed") this.#emitter.emit("complete");
+		else if (status === "failed") this.#emitter.emit("fail", this.#failure());
+		else if (status === "stopped") this.#emitter.emit("stop");
+	}
+	#failure() {
+		for (const result of this.results()) if (result.result?.success === false) return result;
+		throw new Error(`workflow '${this.id}' derived failed with no failing task result`);
+	}
+	#append(phase, options) {
+		const created = new Phase(phase, this, () => this.#recompute(), options?.phases?.[phase.id], this.#bailOverride);
+		this.#phases.append(created);
+	}
+	#statuses() {
+		return this.#phases.phases().map((phase) => ({
+			status: phase.status,
+			bail: phase.bail
+		}));
+	}
+};
+//#endregion
+//#region src/core/Controller.ts
+/**
+* The per-unit handle a runner handler receives — wraps the unit's identity,
+* input, cancellation, and the run controls (`wait` / `spawn` / `abort`).
+*
+* @remarks
+* - **Built by the Runner per unit.** The runner constructs one `Controller` per
+*   unit it dispatches, handing it the unit's `id`, `input`, the unit's `Abort`
+*   handle, the queue attempt's `signal`, and a `spawn` callback that launches a
+*   sibling through the same queue.
+* - **Signal.** `signal` is the queue attempt's signal, which ANY-combines the
+*   unit's own abort, the runner-level abort (the runner aborts every unit), and
+*   the per-attempt timeout — so it fires on any of the three. `aborted` and
+*   `abort(reason)` delegate to the unit's `Abort` (the cancellation source of
+*   truth); since the attempt signal ANY-includes that abort, `abort()` fires
+*   `signal` too.
+* - **`wait` promise-parks (never a timer).** It resolves the instant the unit's
+*   `signal` fires (immediately if already aborted) via a one-shot listener — no
+*   `setTimeout`, no polling, no busy-yield — so a parked unit costs no CPU.
+* - **`spawn` is fire-and-track.** It delegates to the runner's launch-a-sibling
+*   callback, which routes the sibling through the queue; the runner's `execute`
+*   awaits the spawn closure, so the sibling runs whether or not its promise is
+*   awaited. (Inline-awaiting a spawn from a slot-holding handler on a bounded
+*   runner can deadlock — fan out instead; see {@link ControllerInterface.spawn}.)
+* - **Event-free by design.** The per-unit handle carries no Emitter; observe the
+*   {@link RunnerInterface.emitter} instead (`unit` / `spawn` / `settle` / `fail` carry the id).
+*/
+var Controller = class {
+	id;
+	input;
+	signal;
+	#abort;
+	#spawn;
+	constructor(id, input, abort, signal, spawn) {
+		this.id = id;
+		this.input = input;
+		this.#abort = abort;
+		this.signal = signal;
+		this.#spawn = spawn;
+	}
+	get aborted() {
+		return this.#abort.aborted;
+	}
+	wait() {
+		if (this.signal.aborted) return Promise.resolve();
+		return new Promise((resolve) => {
+			this.signal.addEventListener("abort", () => resolve(), { once: true });
+		});
+	}
+	spawn(input) {
+		return this.#spawn(input);
+	}
+	abort(reason) {
+		this.#abort.abort(reason);
+	}
+};
+//#endregion
+//#region src/core/Runner.ts
+/**
+* A thin generic orchestrator that drives declared units — and any they `spawn` —
+* through a bounded-concurrency {@link createQueue}, collecting ordered results.
+*
+* @remarks
+* - **Drives the Queue (no reimplemented concurrency).** Every unit (declared or
+*   spawned) is `enqueue`d on one internal `Queue`, so backpressure, FIFO ordering,
+*   bounded concurrency, retries, and the per-attempt timeout are all the Queue's —
+*   the Runner adds only orchestration (launching, ordering, draining, fail-fast).
+* - **Spawns actually run, results stay ordered (the B2 fix).** Declared inputs and
+*   `spawn`ed siblings flow through the SAME `#launch`, which appends the unit's `id`
+*   to an ordered `#order` list and records its settled value into `#values` by `id`.
+*   Results are read back as `#order.map(id => #values.get(id))` — declared first (in
+*   input order), then spawns (in spawn order). There is no one-time task snapshot,
+*   so a unit spawned mid-handler is run and ordered like any other.
+* - **`execute` awaits the full spawn closure via a count gate.** `#launch` increments
+*   an outstanding-unit `#count` BEFORE enqueuing and every settle decrements it,
+*   resolving the `#drained` deferred at zero. Because `spawn` calls `#launch` (so
+*   `#count += 1`) before the parent handler returns, the count never reaches zero
+*   mid-run — `execute` parks on `#drained` and so awaits the entire transitive
+*   closure, not just the declared units.
+* - **`spawn` is fire-and-track.** A spawned unit runs through the queue regardless of
+*   whether its promise is awaited; the Runner never awaits a spawned promise from
+*   within a handler's slot (it awaits the count gate instead), so a slot-holding
+*   handler can fan out without the Runner deadlocking it. (An inline `await` of a
+*   spawn by a bounded handler can still deadlock — that caveat is the caller's.)
+* - **Per-unit Controller + signal.** Each unit gets a `Controller` carrying its `id`,
+*   `input`, the unit's `Abort` (so `aborted` / `abort` delegate to it), and the queue
+*   attempt's `signal` (which ANY-combines the unit abort + runner abort + timeout). A
+*   `spawn` callback is injected so `controller.spawn(input)` delegates to `#launch`.
+* - **One-shot + fail-fast.** `execute` runs once (a second call throws). The first
+*   unit failure (after its retries) records the error and `abort()`s the run, so every
+*   sibling's signal fires; later failures are ignored and `execute` rejects with the
+*   first error. A user `abort(reason)` likewise rejects a running `execute`.
+* - **Observable (§13).** The owned {@link emitter} ({@link RunnerEventMap}) carries the run
+*   lifecycle — `start` / `unit` / `spawn` / `settle` / `fail` / `finish` / `abort` — for
+*   fire-and-forget observers. Every event is emitted directly, strictly AFTER the relevant
+*   launch / settle / drain transition; the emitter isolates a listener throw and routes it
+*   to its `error` handler (the `error` option), so a buggy observer can NEVER reorder, throw
+*   into, or corrupt the one-shot / fail-fast / spawn-tracking engine: the outstanding-unit
+*   count gate stays balanced and fail-fast still fires regardless of what a listener does.
+*   Observation is purely a side-channel.
+*/
+var Runner = class {
+	#handler;
+	#entries;
+	#queue;
+	#emitter;
+	#aborts = /* @__PURE__ */ new Map();
+	#order = [];
+	#values = /* @__PURE__ */ new Map();
+	#count = 0;
+	#drained;
+	#started = false;
+	#running = false;
+	#stopped = false;
+	#failure;
+	constructor(options) {
+		this.#handler = options.handler;
+		this.#entries = options.entries;
+		this.#emitter = new Emitter({
+			on: options?.on,
+			error: options?.error
+		});
+		this.#queue = createQueue({
+			handler: (unit, execution) => this.#dispatch(unit, execution),
+			concurrency: options.concurrency,
+			retries: options.retries,
+			timeout: options.timeout
+		});
+	}
+	get emitter() {
+		return this.#emitter;
+	}
+	get active() {
+		return this.#count;
+	}
+	get stopped() {
+		return this.#stopped;
+	}
+	async execute(inputs) {
+		if (this.#started) throw new Error("runner has already executed");
+		if (this.#stopped) throw new Error("runner is stopped");
+		this.#started = true;
+		this.#running = true;
+		this.#emitter.emit("start");
+		if (inputs.length === 0) {
+			this.#running = false;
+			this.#emitter.emit("finish", []);
+			return [];
+		}
+		const drained = createDeferred();
+		this.#drained = drained;
+		for (const input of inputs) this.#launch(input);
+		await drained.promise;
+		this.#running = false;
+		if (this.#failure !== void 0) throw this.#failure.error;
+		const results = this.#collect();
+		this.#emitter.emit("finish", results);
+		return results;
+	}
+	abort(reason) {
+		if (this.#stopped) return;
+		if (this.#running && this.#failure === void 0) this.#failure = { error: reason === void 0 ? /* @__PURE__ */ new Error("runner aborted") : reason };
+		this.#cancel(reason);
+		this.#queue.abort(reason);
+		this.#stopped = true;
+		this.#emitter.emit("abort", reason);
+	}
+	destroy() {
+		if (this.#stopped) {
+			this.#queue.destroy();
+			return;
+		}
+		this.abort();
+		this.#queue.destroy();
+	}
+	#launch(input, parent) {
+		const id = crypto.randomUUID();
+		const abort = createAbort();
+		this.#aborts.set(id, abort);
+		this.#order.push(id);
+		this.#count += 1;
+		if (parent !== void 0) this.#emitter.emit("spawn", id, parent);
+		const promise = this.#queue.enqueue({
+			id,
+			input
+		}, {
+			id,
+			signal: abort.signal,
+			...this.#entries?.(input)
+		});
+		promise.then((value) => this.#settle(id, {
+			ok: true,
+			value
+		}), (error) => this.#settle(id, {
+			ok: false,
+			error
+		}));
+		return promise;
+	}
+	#dispatch(unit, execution) {
+		const abort = this.#aborts.get(unit.id);
+		if (abort === void 0) throw new Error("unit abort missing");
+		const controller = new Controller(unit.id, unit.input, abort, execution.signal, (input) => this.#spawn(input, unit.id));
+		this.#emitter.emit("unit", unit.id);
+		return this.#handler(controller);
+	}
+	#spawn(input, parent) {
+		if (!this.#running) throw new Error("spawn is unavailable outside an active run");
+		return this.#launch(input, parent);
+	}
+	#settle(id, outcome) {
+		if (outcome.ok) {
+			this.#values.set(id, { value: outcome.value });
+			this.#emitter.emit("settle", id);
+		} else if (this.#failure === void 0) {
+			this.#failure = { error: outcome.error };
+			this.#emitter.emit("fail", id, outcome.error);
+			this.abort(outcome.error);
+		}
+		this.#count -= 1;
+		if (this.#count === 0) this.#drained?.resolve();
+	}
+	#collect() {
+		const results = [];
+		for (const id of this.#order) {
+			const box = this.#values.get(id);
+			if (box !== void 0) results.push(box.value);
+		}
+		return results;
+	}
+	#cancel(reason) {
+		for (const abort of this.#aborts.values()) abort.abort(reason);
+	}
+};
+//#endregion
+//#region src/core/tasks/TaskController.ts
+/**
+* The lean per-task handle a {@link import('./types.js').WorkflowFunction} receives — the
+* running task's folded cancellation, its input, its lineage, and read-UP access to the
+* result tree.
+*
+* @remarks
+* - **A leaf handle, NOT the runner `Controller`.** A workflow task is a leaf of the
+*   declarative W-b tree, not a fan-out unit, so this carries none of the runner
+*   `Controller`'s `spawn` / `wait` — only what a leaf needs.
+* - **Folded signal.** `signal` is the cancellation the runner folds for THIS run: it fires
+*   on a workflow-level abort / timeout / budget ceiling, or — under `bail: true` — when a
+*   sibling task fails (the runner aborts the in-flight siblings via the substrate's
+*   fail-fast). A handler races its work against it; `aborted` reads it.
+* - **Input + lineage.** `input` is the task's open `metadata` bag (its
+*   {@link import('./types.js').TaskInput} payload, `{}` when none); `task` is the full
+*   {@link TaskContext}, so `task.phase` / `task.phase.workflow` navigate UP the lineage.
+* - **Read-up results.** `results()` returns every settled task's {@link TaskResult} across
+*   the phases that have already finished (a closure over the live
+*   {@link import('./types.js').WorkflowInterface}), so a `function` task can read an earlier
+*   phase's output. Read-only — a task records its OWN outcome by returning / throwing, not
+*   by mutating the tree.
+* - **Event-free.** Like the runner `Controller`, the per-task handle carries no Emitter;
+*   observe the W-b entities' own emitters (`task.emitter` / `phase.emitter`) instead.
+*/
+var TaskController = class {
+	signal;
+	input;
+	task;
+	#results;
+	constructor(signal, input, task, results) {
+		this.signal = signal;
+		this.input = input;
+		this.task = task;
+		this.#results = results;
+	}
+	get aborted() {
+		return this.signal.aborted;
+	}
+	results() {
+		return this.#results();
+	}
+};
+//#endregion
+//#region src/core/WorkflowRunner.ts
+/**
+* The thin orchestrator that EXECUTES a live W-b workflow tree by COMPOSING the shipped
+* substrate — phases sequential, tasks concurrent — dispatching each task BY NAME under the
+* `bail` policy, including the W-c2 `agent` form behind a depth + cycle guard.
+*
+* @remarks
+* - **Composes, never re-implements.** Per-phase bounded concurrency is one
+*   {@link createRunner} per phase (the substrate {@link RunnerInterface} over the workers
+*   `Queue`); `bail` maps onto that Runner's fail-fast vs settle-all; the run-level abort /
+*   timeout / budget fold through {@link createAbort} / {@link createTimeout} +
+*   `AbortSignal.any` (exactly as the agent runtime folds its bounds); pacing is the shipped
+*   {@link SchedulerInterface}. The runner writes ZERO concurrency / retry / abort logic of
+*   its own — it only sequences phases, dispatches a task, and drives the live entity.
+* - **Phases sequential, tasks concurrent.** `#execute` awaits the phases in order (phase
+*   N+1 starts only once phase N has fully settled). Within a phase, ALL its tasks are the
+*   one Runner's `inputs`, run at `concurrency` = the phase's
+*   {@link PhaseDefinition.concurrency} (default {@link DEFAULT_PHASE_CONCURRENCY}).
+* - **Dispatch by name.** `#dispatch` branches on the task's
+*   {@link import('./types.js').TaskForm} (read from the `definition`, correlated by `id`):
+*   `function` → the {@link WorkflowFunctions} registry, `tool` → the
+*   {@link ToolManagerInterface}, `agent` → the {@link WorkflowAgents} resolver (W-c2). A
+*   handler that is NOT found (an unregistered name for ANY form) AUTO-COMPLETES — the
+*   ROADMAP no-handler rule.
+* - **`agent` form + depth/cycle guard (W-c2).** An `agent` task resolves its subagent via
+*   `agents`, BINDS a depth/cycle-aware workflow tool onto the subagent's `context.tools`
+*   (the propagation seam), folds the task's cancellation into the agent run (a workflow
+*   cancel `abort`s the subagent), and drives it: success → `complete(result)`, throw →
+*   `fail(error)`. Before running, the guard REJECTS the task into a typed `DEPTH`
+*   {@link WorkflowError} (`fail`) when running it would push the nested chain past
+*   {@link MAX_WORKFLOW_DEPTH}, OR when its target agent is already an ancestor (a cycle).
+*   The rejected task never runs the agent.
+* - **`bail` → substrate.** Under `bail: true` (halt) a genuine task failure `fail`s the leaf
+*   THEN re-throws, so the substrate Runner fail-fasts — it aborts the in-flight siblings
+*   (their `controller.signal` fires; a mid-flight sibling `skip`s) and rejects the phase run;
+*   `#execute` then `skip`s the remaining tasks / phases (the workflow derives `failed`).
+*   Under `bail: false` (graceful) a failure `fail`s the leaf and RESOLVES (never throws), so
+*   the Runner settles every unit (allSettled) and the run finishes (the workflow derives
+*   `completed`, the failure recorded in the result tree).
+* - **Abort / Timeout / Budget fold.** `#execute` folds the run's external `signal`, a
+*   {@link TimeoutInterface}, and the `@orkestrel/budget` package's `BudgetInterface`'s
+*   `signal` into one `runSignal` (`AbortSignal.any`); a fire aborts the active phase's Runner
+*   (cancelling every in-flight task) and HALTS the run — the remaining tasks / phases `skip`
+*   and the workflow is force-`stop`ped (settles `stopped`). Each task's
+*   {@link TaskController} signal `AbortSignal.any`-combines the substrate per-unit signal with
+*   `runSignal`, so a handler observes either cause directly.
+* - **Re-entrant-safe.** No shared per-run mutable field: the active-Runner holder is LOCAL to
+*   each `#execute`, so a nested `execute` (the bound workflow tool re-entering this instance
+*   while the outer run is suspended on an `agent` task) cannot clobber the outer run's state.
+*/
+var WorkflowRunner = class {
+	#functions;
+	#tools;
+	#agents;
+	#scheduler;
+	#workflowTool;
+	constructor(functions, tools, agents, scheduler, workflowTool) {
+		this.#functions = functions;
+		this.#tools = tools;
+		this.#agents = agents;
+		this.#scheduler = scheduler;
+		this.#workflowTool = workflowTool;
+	}
+	execute(definition, options) {
+		const workflow = new Workflow(definitionToSnapshot(definition, options?.bail ?? definition.bail ?? false), options);
+		const depth = options?.depth ?? 0;
+		const ancestry = [...options?.ancestry ?? [], workflowTag(definition.id)];
+		return this.#execute(workflow, definition, options, depth, ancestry);
+	}
+	async #execute(workflow, definition, options, depth, ancestry) {
+		const ms = options?.timeout;
+		const timeout = ms !== void 0 && ms > 0 ? createTimeout({ ms }) : void 0;
+		timeout?.start();
+		options?.budget?.start();
+		const runSignal = this.#fold(options, timeout);
+		const holder = { runner: void 0 };
+		const onCancel = () => holder.runner?.abort(runSignal?.reason);
+		if (runSignal !== void 0) if (runSignal.aborted) onCancel();
+		else runSignal.addEventListener("abort", onCancel, { once: true });
+		try {
+			const phases = workflow.phases.phases();
+			for (let index = 0; index < phases.length; index += 1) {
+				const phase = phases[index];
+				if (phase === void 0) continue;
+				if (this.#cancelled(runSignal) || this.#halted(workflow)) {
+					this.#skipFrom(phases, index);
+					break;
+				}
+				if (await this.#runPhase(workflow, phase, this.#phaseOf(definition, phase.id), runSignal, holder, depth, ancestry)) {
+					this.#skipFrom(phases, index + 1);
+					break;
+				}
+				if (index < phases.length - 1 && !this.#cancelled(runSignal)) try {
+					await this.#scheduler.yield(runSignal === void 0 ? void 0 : { signal: runSignal });
+				} catch {}
+			}
+			if (this.#cancelled(runSignal)) {
+				this.#skipFrom(workflow.phases.phases(), 0);
+				if (this.#stoppable(workflow)) workflow.stop();
+			} else if (this.#completable(workflow)) workflow.complete();
+			return {
+				workflow,
+				status: workflow.status,
+				results: workflow.results()
+			};
+		} finally {
+			timeout?.clear();
+			runSignal?.removeEventListener("abort", onCancel);
+		}
+	}
+	async #runPhase(workflow, phase, definition, runSignal, holder, depth, ancestry) {
+		const tasks = phase.tasks.tasks();
+		if (tasks.length === 0) return false;
+		const bail = definition?.bail ?? workflow.bail;
+		const concurrency = definition?.concurrency !== void 0 && definition.concurrency > 0 ? definition.concurrency : DEFAULT_PHASE_CONCURRENCY;
+		const attempts = /* @__PURE__ */ new Map();
+		const runner = new Runner({
+			concurrency,
+			entries: (task) => {
+				const def = this.#taskOf(definition, task.id);
+				return {
+					retries: def?.retries,
+					timeout: def?.timeout
+				};
+			},
+			handler: (controller) => this.#runTask(workflow, controller.input, this.#taskOf(definition, controller.input.id), controller, runSignal, bail, attempts, depth, ancestry)
+		});
+		holder.runner = runner;
+		try {
+			await runner.execute(tasks);
+			return false;
+		} catch {
+			return !this.#cancelled(runSignal);
+		} finally {
+			runner.destroy();
+			holder.runner = void 0;
+		}
+	}
+	async #runTask(workflow, task, definition, controller, runSignal, bail, attempts, depth, ancestry) {
+		const signal = this.#taskSignal(controller.signal, runSignal);
+		const attempt = (attempts.get(task.id) ?? 0) + 1;
+		attempts.set(task.id, attempt);
+		const last = attempt > Math.max(0, definition?.retries ?? 0);
+		if (task.status === "pending") task.start();
+		if (this.#skipping(controller, runSignal)) {
+			this.#skip(task);
+			return;
+		}
+		const handle = new TaskController(signal, task.snapshot().metadata, task.context, () => workflow.results());
+		try {
+			const value = await this.#dispatch(definition, handle, depth, ancestry);
+			if (task.status !== "running" || this.#skipping(controller, runSignal)) {
+				this.#skip(task);
+				return;
+			}
+			if (signal.aborted) {
+				this.#timedOut(task, last);
+				return;
+			}
+			task.complete(value);
+		} catch (error) {
+			if (task.status !== "running" || this.#skipping(controller, runSignal)) {
+				this.#skip(task);
+				return;
+			}
+			if (signal.aborted) {
+				this.#timedOut(task, last);
+				return;
+			}
+			if (!last) throw error;
+			task.fail(error);
+			if (bail) throw error;
+		}
+	}
+	#timedOut(task, last) {
+		if (!last) return;
+		task.fail(/* @__PURE__ */ new Error(`task '${task.id}' timed out`));
+	}
+	async #dispatch(definition, controller, depth, ancestry) {
+		const form = definition?.run;
+		if (form !== void 0 && isFunctionTask(form)) {
+			const handler = this.#functions[form.name];
+			if (handler !== void 0) return handler(controller);
+			return;
+		}
+		if (form !== void 0 && isToolTask(form)) {
+			const tools = this.#tools;
+			if (tools === void 0) return void 0;
+			if (tools.tool(form.name) === void 0) return void 0;
+			const result = await tools.execute({
+				id: controller.task.id,
+				name: form.name,
+				arguments: controller.input
+			});
+			if (result.error !== void 0) throw new Error(result.error);
+			return result.value;
+		}
+		if (form !== void 0 && isAgentTask(form)) return this.#dispatchAgent(form.name, controller, depth, ancestry);
+	}
+	async #dispatchAgent(name, controller, depth, ancestry) {
+		const resolve = this.#agents;
+		if (resolve === void 0) return void 0;
+		const agent = resolve(name);
+		if (agent === void 0) return void 0;
+		if (depth + 1 > 8) throw new WorkflowError("DEPTH", `agent '${name}' exceeds max workflow depth`, {
+			agent: name,
+			depth,
+			max: 8
+		});
+		const tag = agentTag(name);
+		if (ancestry.includes(tag)) throw new WorkflowError("DEPTH", `agent '${name}' is already an ancestor (cycle)`, {
+			agent: name,
+			ancestry: [...ancestry]
+		});
+		this.#bindWorkflowTool(agent, depth, [...ancestry, tag], controller.task.phase.workflow.id);
+		return this.#runAgent(agent, controller.signal);
+	}
+	#bindWorkflowTool(agent, depth, ancestry, workflowId) {
+		const bind = this.#workflowTool;
+		if (bind === void 0) return;
+		const wrapped = {
+			id: workflowId,
+			name: workflowId,
+			phases: []
+		};
+		agent.context.tools.add(bind(wrapped, this, {
+			depth,
+			ancestry
+		}));
+	}
+	async #runAgent(agent, signal) {
+		const onAbort = () => agent.abort(signal.reason);
+		if (signal.aborted) agent.abort(signal.reason);
+		else signal.addEventListener("abort", onAbort, { once: true });
+		try {
+			return await agent.generate();
+		} finally {
+			signal.removeEventListener("abort", onAbort);
+		}
+	}
+	#taskSignal(unitSignal, runSignal) {
+		if (runSignal === void 0) return unitSignal;
+		return createAbort({ signal: AbortSignal.any([unitSignal, runSignal]) }).signal;
+	}
+	#fold(options, timeout) {
+		const signals = [];
+		if (options?.signal !== void 0) signals.push(options.signal);
+		if (timeout !== void 0) signals.push(timeout.signal);
+		if (options?.budget !== void 0) signals.push(options.budget.signal);
+		if (signals.length === 0) return void 0;
+		if (signals.length === 1) return signals[0];
+		return AbortSignal.any(signals);
+	}
+	#skipFrom(phases, index) {
+		for (let cursor = index; cursor < phases.length; cursor += 1) {
+			const phase = phases[cursor];
+			if (phase === void 0) continue;
+			for (const task of phase.tasks.tasks()) this.#skip(task);
+		}
+	}
+	#skip(task) {
+		if (task.status === "pending" || task.status === "running") task.skip();
+	}
+	#skipping(controller, runSignal) {
+		return controller.aborted || runSignal?.aborted === true;
+	}
+	#cancelled(runSignal) {
+		return runSignal?.aborted === true;
+	}
+	#halted(workflow) {
+		const status = workflow.status;
+		return status === "failed" || status === "skipped" || status === "stopped";
+	}
+	#stoppable(workflow) {
+		const status = workflow.status;
+		return status !== "failed" && status !== "stopped";
+	}
+	#completable(workflow) {
+		return workflow.status === "pending";
+	}
+	#phaseOf(definition, id) {
+		return definition.phases.find((phase) => phase.id === id);
+	}
+	#taskOf(phase, id) {
+		return phase?.tasks.find((task) => task.id === id);
+	}
+};
+//#endregion
+//#region src/core/factories.ts
+/**
+* Compile the workflow definition contract — the JSON Schema, guard, parser, and
+* seeded generator for a {@link WorkflowDefinition}, all derived from one shape and
+* kept in lockstep.
+*
+* @remarks
+* The returned {@link ContractInterface}:
+* - `schema` — the emitted JSON Schema for a workflow definition.
+* - `is` — a total guard that narrows `unknown` to a valid {@link WorkflowDefinition}
+*   (malformed input returns `false`, never throws).
+* - `parse` — coerces `unknown` to a {@link WorkflowDefinition}, or `undefined` when
+*   it does not match.
+* - `generate` — produces a deterministic valid {@link WorkflowDefinition} from an
+*   optional seeded random source.
+*
+* @returns The compiled {@link WorkflowDefinition} contract
+*
+* @example
+* ```ts
+* import { createWorkflowContract } from '@src/core'
+*
+* const contract = createWorkflowContract()
+* const definition = contract.generate()       // a valid WorkflowDefinition
+* contract.is(definition)                       // true
+* contract.parse({ id: '', phases: [] })        // undefined (malformed)
+* ```
+*/
+function createWorkflowContract() {
+	const contract = createContract(workflowShape);
+	return {
+		schema: contract.schema,
+		is: contract.is,
+		generate: (random) => contract.generate(random),
+		parse: (value) => contract.parse(value)
+	};
+}
+/**
+* Compile the LENIENT workflow DRAFT contract — identical to
+* {@link createWorkflowContract} EXCEPT `id` and `name` are OPTIONAL at all three levels
+* (workflow / phase / task), so a small model can omit the six identity strings.
+*
+* @remarks
+* The widened authoring surface {@link createWorkflowTool} parses an authored blob through
+* before {@link import('./helpers.js').completeDraft} fills the missing ids/names. It does
+* NOT relax the canonical contract — {@link createWorkflowContract} stays byte-for-byte
+* unchanged and STRICT, and the completed draft is re-validated against THAT strict gate
+* before running (soundness preserved). A PROVIDED `id` / `name` still carries `minLength: 1`,
+* so an explicitly-empty `id: ''` is REJECTED (parses to `undefined`), never auto-filled —
+* keeping "garbage" distinct from "omitted". `run` stays required.
+*
+* @returns The compiled {@link WorkflowDraft} contract
+*
+* @example
+* ```ts
+* import { createWorkflowDraftContract, completeDraft } from '@src/core'
+*
+* const draft = createWorkflowDraftContract()
+* const parsed = draft.parse({ phases: [{ tasks: [{ run: { via: 'function', name: 'f' } }] }] })
+* const definition = parsed && completeDraft(parsed) // ids/names filled positionally
+* draft.parse({ id: '', phases: [] })                // undefined — an explicit empty id is rejected
+* ```
+*/
+function createWorkflowDraftContract() {
+	const contract = createContract(workflowDraftShape);
+	return {
+		schema: contract.schema,
+		is: contract.is,
+		generate: (random) => contract.generate(random),
+		parse: (value) => contract.parse(value)
+	};
+}
+/**
+* Build the live W-b entity tree from a {@link WorkflowDefinition} — the whole
+* {@link WorkflowInterface} → {@link import('./types.js').PhaseInterface} →
+* {@link import('./types.js').TaskInterface} tree, each level wired with its lineage
+* context, its emitter, and the cascade.
+*
+* @remarks
+* The definition is the DECLARATIVE blueprint; this seeds an initial all-`pending`
+* {@link WorkflowSnapshot} from it ({@link definitionToSnapshot}) and constructs the live
+* tree over that one path. The `bail` failure policy resolves to `options.bail`, else the
+* definition's `bail`, else the graceful {@link import('./constants.js').DEFAULT_BAIL}; it
+* feeds {@link import('./helpers.js').deriveWorkflowStatus}. Per-phase / per-task initial
+* listeners + metadata travel through `options.phases[id].on` /
+* `options.phases[id].tasks[id]` (the AGENTS §8 nested-by-id bag). The W-b tree is the
+* state machine ONLY — it does not execute tasks (W-c drives the transitions).
+*
+* @param definition - The workflow definition to bring to life
+* @param options - Runtime options (initial listeners, `bail` override, per-node options)
+* @returns The live {@link WorkflowInterface} root
+*
+* @example
+* ```ts
+* import { createWorkflow } from '@src/core'
+*
+* const workflow = createWorkflow(definition, { on: { complete: () => done() } })
+* const phase = workflow.phase('phase-build')
+* phase?.task('task-compile')?.start()    // pending → running (cascades up)
+* ```
+*/
+function createWorkflow(definition, options) {
+	return new Workflow(definitionToSnapshot(definition, options?.bail ?? definition.bail ?? false), options);
+}
+/**
+* Rebuild 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
+* 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
+* `skip` / `remove` survives). The snapshot is SELF-CONTAINED — it persists the `bail`
+* policy it ran under, so the restore re-derives status IDENTICALLY without a silent
+* default; the snapshot's `bail` is the source of truth, while an explicit `options.bail`
+* still wins when supplied (to deliberately re-run under a different policy). A structurally
+* invalid snapshot (a status — or override — outside the lifecycle vocabulary, or a
+* non-boolean `bail`) throws a `RESTORE` {@link WorkflowError}.
+*
+* @param snapshot - The snapshot to restore (carries its own `bail` + `override`)
+* @param options - Runtime options (initial listeners, an optional `bail` override, per-node options)
+* @returns The restored live {@link WorkflowInterface} root
+*
+* @example
+* ```ts
+* import { restoreWorkflow } from '@src/core'
+*
+* const restored = restoreWorkflow(workflow.snapshot()) // bail comes from the snapshot
+* restored.status === workflow.status // true
+* ```
+*/
+function restoreWorkflow(snapshot, options) {
+	assertSnapshot(snapshot);
+	return new Workflow(snapshot, options);
+}
+/**
+* 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},
+* or a non-boolean `bail` (the workflow's OR any phase's — both are REQUIRED persisted policy),
+* is rejected loudly (naming the offending node) rather than silently producing a broken tree.
+* The `override` is optional, so it 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) {
+	if (typeof snapshot.bail !== "boolean") throw new WorkflowError("RESTORE", `workflow '${snapshot.id}' has a non-boolean bail`, {
+		workflow: snapshot.id,
+		bail: snapshot.bail
+	});
+	if (!WORKFLOW_STATUSES.includes(snapshot.status)) throw new WorkflowError("RESTORE", `workflow '${snapshot.id}' has an invalid status`, {
+		workflow: snapshot.id,
+		status: snapshot.status
+	});
+	if (snapshot.override !== void 0 && !WORKFLOW_STATUSES.includes(snapshot.override)) throw new WorkflowError("RESTORE", `workflow '${snapshot.id}' has an invalid override`, {
+		workflow: snapshot.id,
+		override: snapshot.override
+	});
+	for (const phase of snapshot.phases) {
+		if (typeof phase.bail !== "boolean") throw new WorkflowError("RESTORE", `phase '${phase.id}' has a non-boolean bail`, {
+			phase: phase.id,
+			bail: phase.bail
+		});
+		if (!PHASE_STATUSES.includes(phase.status)) throw new WorkflowError("RESTORE", `phase '${phase.id}' has an invalid status`, {
+			phase: phase.id,
+			status: phase.status
+		});
+		if (phase.override !== void 0 && !PHASE_STATUSES.includes(phase.override)) throw new WorkflowError("RESTORE", `phase '${phase.id}' has an invalid override`, {
+			phase: phase.id,
+			override: phase.override
+		});
+		for (const task of phase.tasks) if (!TASK_STATUSES.includes(task.status)) throw new WorkflowError("RESTORE", `task '${task.id}' has an invalid status`, {
+			task: task.id,
+			status: task.status
+		});
+	}
+}
+/**
+* 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.
+*
+* @remarks
+* The snapshot analogue of the server package's `createMemorySessionStore`
+* (and the {@link createMemoryQueueStore} family), but LEANER — there is no idle-TTL, so no
+* options bag (AGENTS §21 minimal): a persisted run-state lives until an explicit `delete`. This is
+* the zero-plumbing DEFAULT (a plain `Map`); its driver-pluggable twin is
+* {@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}.
+*
+* @returns A memory-backed {@link WorkflowStoreInterface}
+*
+* @example
+* ```ts
+* import { createMemoryWorkflowStore, createWorkflow, restoreWorkflow } from '@src/core'
+*
+* 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
+* ```
+*/
+function createMemoryWorkflowStore() {
+	return new MemoryWorkflowStore();
+}
+/**
+* Create a {@link DatabaseWorkflowStore} over any {@link DriverInterface} — the durable,
+* driver-pluggable backing for the W-d persistence seam, the opt-in twin of
+* {@link createMemoryWorkflowStore}.
+*
+* @remarks
+* Builds a one-table database (`snapshots`, keyed by `id`) over the supplied driver, the snapshot
+* held as ONE OPAQUE JSON COLUMN — the column map is `{ id; snapshot }` where `snapshot` is a
+* `rawShape` (a JSON blob), exactly as {@link createDatabaseQueueStore} stores its `input`. The
+* snapshot is already a COMPLETE, self-contained, pure-JSON payload, so storing it whole is lossless
+* AND keeps the row type FLAT — a structured multi-column snapshot table would force the contract to
+* `Infer` the deeply-nested snapshot shape (workflow → phases → tasks → results) and trip TS2589;
+* the opaque column sidesteps it (the column reads back as `unknown`, narrowed on `get` by
+* {@link import('./helpers.js').isWorkflowSnapshot}). The `driver` DEFAULTS to
+* {@link createMemoryDriver}, so the store ALSO works in memory out of the box; pass a server
+* `createJSONDriver` / `createSQLiteDriver` (or a browser IndexedDB driver) for a persistent one —
+* the durability is the driver's job, the store engine is shared. It swaps in behind
+* {@link WorkflowStoreInterface} WITHOUT touching the runner or the entity tree.
+*
+* @param driver - The storage backend the snapshots persist to (defaults to {@link createMemoryDriver})
+* @returns A {@link WorkflowStoreInterface} over the driver
+*
+* @example
+* ```ts
+* import { createDatabaseWorkflowStore, createMemoryDriver, createWorkflow, restoreWorkflow } from '@src/core'
+*
+* 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
+* ```
+*/
+function createDatabaseWorkflowStore(driver = createMemoryDriver()) {
+	return new DatabaseWorkflowStore(createDatabase({
+		driver,
+		tables: { snapshots: {
+			id: stringShape(),
+			snapshot: rawShape({})
+		} }
+	}).table("snapshots"));
+}
+/**
+* Create a workflow runner — a {@link WorkflowRunnerInterface} that EXECUTES a live W-b
+* workflow tree by COMPOSING the shipped substrate: phases sequential, tasks concurrent,
+* each task dispatched BY NAME under the workflow's `bail` policy.
+*
+* @remarks
+* The runner is THIN — it re-implements no concurrency / retry / abort logic. Per-phase
+* bounded concurrency is one {@link createRunner} per phase;
+* `bail` maps onto that Runner's fail-fast (`true` — the first failure aborts the in-flight
+* siblings + skips the rest) vs settle-all (`false` — failures are recorded, the run
+* finishes); the run-level abort / timeout / budget ({@link import('./types.js').WorkflowRunOptions})
+* fold through `AbortSignal.any` (the agent runtime's pattern); pacing is the shipped
+* scheduler. `execute(definition, options?)` BUILDS the live tree from the definition itself
+* (via {@link createWorkflow} — one source of truth, returned in `WorkflowResult.workflow`),
+* drives the live entity (`start` → `complete` / `fail`), and resolves a
+* {@link import('./types.js').WorkflowResult}.
+*
+* A task is dispatched on its {@link import('./types.js').TaskForm}: `function` → the
+* `functions` registry, `tool` → the `tools` {@link ToolManagerInterface}, `agent` → the
+* `agents` {@link import('./types.js').WorkflowAgents} resolver (W-c2), behind a depth + cycle
+* guard. A task whose handler is NOT found (an unregistered name for ANY form) AUTO-COMPLETES
+* (the ROADMAP no-handler rule).
+*
+* The runner is constructed with a reference to {@link createWorkflowTool} (the workflow-tool
+* binder) so it can BIND a depth/cycle-aware workflow tool onto a dispatched subagent's context
+* — the propagation seam — WITHOUT this module's classes importing its own `factories.ts` (the
+* factories→classes direction; the binder is injected as a value at construction).
+*
+* @param options - The behavior registries (`functions` / `tools` / `agents`) the runner
+*   dispatches a task by name through, plus an optional pacing `scheduler` (default the shipped
+*   cross-environment one). Omitting `functions` / `tools` / `agents` makes those task forms
+*   auto-complete (no handler). See {@link WorkflowRunnerOptions}.
+* @returns A working {@link WorkflowRunnerInterface}
+*
+* @example
+* ```ts
+* import { createWorkflowRunner, createToolManager } from '@src/core'
+*
+* const tools = createToolManager()
+* const runner = createWorkflowRunner({
+* 	functions: { compile: async (controller) => `built ${controller.task.id}` },
+* 	tools,
+* })
+* const definition = { id: 'w', name: 'W', phases: [{ id: 'p', name: 'P', tasks: [
+* 	{ id: 't', name: 'T', run: { via: 'function', name: 'compile' } },
+* ] }] }
+* const result = await runner.execute(definition) // builds + drives the tree
+* result.status // 'completed'
+* result.workflow.phase('p')?.task('t')?.status // 'completed'
+* ```
+*/
+function createWorkflowRunner(options) {
+	return new WorkflowRunner(options?.functions ?? {}, options?.tools, options?.agents, options?.scheduler ?? createScheduler(), createWorkflowTool);
+}
+/**
+* Wrap a {@link WorkflowDefinition} as an LLM-callable {@link ToolInterface} — it ADVERTISES
+* the SIMPLE flat authoring shape (`{ name?, steps: [{ name, via? }] }`) as its `parameters` so
+* even a small model can author a complete tree, and its handler EXPANDS / COMPLETES the
+* authored blob, validates it against the STRICT contract, runs it through `runner`, and
+* returns the run SUMMARY (throwing a typed {@link WorkflowError} on failure).
+*
+* @remarks
+* A plain {@link ToolManagerInterface}-compatible tool (so `createMCPServer` / `createMCPRoutes`
+* expose it for free — nothing MCP is wired here). It is ALSO the propagation carrier the
+* {@link WorkflowRunner} binds onto a dispatched subagent (W-c2): because a tool handler receives
+* ONLY the model-supplied `args` (no ambient context, no signal), the run's depth + ancestry are
+* CLOSED OVER at bind time via {@link WorkflowToolOptions}, and the handler runs the nested
+* workflow at `depth + 1` with the extended ancestry.
+*
+* **Widened authoring surface (additive — the canonical contract + runner stay STRICT and
+* unchanged).** A 2B model reliably CALLS the tool but cannot reliably emit the full four-level
+* nested {@link WorkflowDefinition} (six required `id`/`name` strings, a nested tagged union,
+* all-or-nothing). So the tool ACCEPTS three authoring forms and converges them on the SAME
+* strict {@link createWorkflowContract} gate before running (soundness preserved):
+* - the FLAT shape `{ name?, steps: [{ name, via? }] }` — the ADVERTISED `parameters` (the simplest
+*   form, {@link import('./helpers.js').expandSteps}'d into one one-task phase per step);
+* - a nested DRAFT with any `id`/`name` OMITTED — {@link createWorkflowDraftContract}-parsed then
+*   {@link import('./helpers.js').completeDraft}'d (missing ids synthesized positionally);
+* - the full nested {@link WorkflowDefinition} — the advanced escape-hatch (documented in the
+*   description), accepted as the draft super-set.
+*
+* The handler conforms to the universal tool-handler contract (AGENTS §14): it returns the PLAIN
+* run-summary VALUE on success and THROWS a typed {@link WorkflowError} on every failure path. It
+* does NOT build a {@link ToolResult} itself — the `@orkestrel/agent` package's `ToolManager`
+* performs the ONE canonical wrap (`{ id, name, value }` on a return; `{ id, name, error }` on a
+* throw, ISOLATED so nothing escapes the run), so the outcome appears EXACTLY ONCE, identically,
+* over BOTH the agent loop and MCP (a throw → MCP `isError: true`):
+* - **No authored args** (an empty `arguments`) ⇒ runs the WRAPPED `definition`.
+* - **A `steps` array** ⇒ the FLAT form: parse it, {@link import('./helpers.js').expandSteps} it.
+* - **Otherwise** ⇒ the nested form: {@link createWorkflowDraftContract}-parse it,
+*   {@link import('./helpers.js').completeDraft} it.
+* - **Strict gate** ⇒ the expanded / completed result is validated against
+*   {@link createWorkflowContract}.`is`; a blob that can't expand, or whose result fails the strict
+*   gate (e.g. an explicit empty `id`, `concurrency: 0`) ⇒ THROW a `TOOL` {@link WorkflowError} (no run).
+* - **Over-deep / cyclic** ⇒ THROW a `DEPTH` {@link WorkflowError} when the nested run would exceed
+*   {@link MAX_WORKFLOW_DEPTH}, or the target workflow id is already an ancestor (a cycle) — the
+*   same `code` the agent-task guard raises.
+* - **Otherwise** ⇒ `runner.execute(target, { depth: depth + 1, ancestry: … })`, RETURNING the
+*   plain summary of the terminal run (`{ status, count }`, via {@link workflowToolSummary}).
+*
+* @param definition - The workflow the tool runs when called with no authored args
+* @param runner - The {@link WorkflowRunnerInterface} that executes the (nested) workflow
+* @param options - The depth + ancestry to run the nested workflow under (see
+*   {@link WorkflowToolOptions}); omitted ⇒ depth `0` / empty ancestry (a top-level wrap)
+* @returns A {@link ToolInterface} (named {@link import('./constants.js').WORKFLOW_TOOL_NAME})
+*   whose `parameters` advertise the FLAT authoring schema (the nested form stays accepted)
+*
+* @example
+* ```ts
+* import { createWorkflowRunner, createWorkflowTool, createToolManager } from '@src/core'
+*
+* const runner = createWorkflowRunner()
+* const tool = createWorkflowTool(definition, runner)
+* const tools = createToolManager()
+* tools.add(tool) // a model can now author + run a workflow in one call
+* ```
+*/
+function createWorkflowTool(definition, runner, options) {
+	const strict = createWorkflowContract();
+	const draft = createWorkflowDraftContract();
+	const steps = createContract(workflowStepsShape);
+	const depth = options?.depth ?? 0;
+	const ancestry = options?.ancestry ?? [];
+	return createTool({
+		name: WORKFLOW_TOOL_NAME,
+		description: WORKFLOW_TOOL_DESCRIPTION,
+		parameters: schemaToParameters(steps.schema),
+		execute: async (args) => {
+			let target;
+			if (Object.keys(args).length === 0) target = definition;
+			else if (Array.isArray(args.steps)) {
+				const flat = steps.parse(args);
+				target = flat === void 0 ? void 0 : expandSteps(flat);
+			} else {
+				const parsed = draft.parse(args);
+				target = parsed === void 0 ? void 0 : completeDraft(parsed);
+			}
+			if (target === void 0 || !strict.is(target)) throw new WorkflowError("TOOL", "malformed workflow definition", { workflow: definition.id });
+			if (depth + 1 > 8) throw new WorkflowError("DEPTH", `nested workflow exceeds max depth 8`, {
+				workflow: target.id,
+				depth,
+				max: 8
+			});
+			const tag = workflowTag(target.id);
+			if (ancestry.includes(tag)) throw new WorkflowError("DEPTH", `workflow '${target.id}' is already an ancestor (cycle)`, {
+				workflow: target.id,
+				ancestry: [...ancestry]
+			});
+			return workflowToolSummary(await runner.execute(target, {
+				depth: depth + 1,
+				ancestry: [...ancestry, tag]
+			}));
+		}
+	});
+}
+/**
+* Create the safe cross-environment cooperative-yield default — a
+* {@link SchedulerInterface} built on `setTimeout` / `clearTimeout` alone, so it
+* runs unchanged in both the browser and Node.
+*
+* @remarks
+* `yield()` gives the host a turn via a zero-delay macrotask (so pending I/O,
+* timers, and rendering actually run — a microtask would not); `delay(ms)` resumes
+* after at least `ms`. Pass `options.signal` to make a pending yield/delay reject
+* with the signal's `reason` on abort (with full timer/listener cleanup).
+* `options.priority` is accepted for contract compliance but treated uniformly by
+* this default — environment backends honour it.
+*
+* @returns A working {@link SchedulerInterface}
+*
+* @example
+* ```ts
+* import { createAbort, createScheduler } from '@src/core'
+*
+* const abort = createAbort()
+* const scheduler = createScheduler()
+*
+* // A cooperative loop: do a unit of work, then hand the host a turn.
+* while (!abort.signal.aborted) {
+* 	doSomeWork()
+* 	await scheduler.yield({ signal: abort.signal })
+* }
+* ```
+*
+* @example
+* ```ts
+* import { createScheduler } from '@src/core'
+*
+* // A backoff: wait a growing interval between retries.
+* const scheduler = createScheduler()
+* for (let attempt = 0; attempt < 5; attempt += 1) {
+* 	if (await tryOnce()) break
+* 	await scheduler.delay(2 ** attempt * 100)
+* }
+* ```
+*/
+function createScheduler() {
+	return new Scheduler();
+}
+/**
+* Create a thin generic orchestrator that drives declared units — and any they
+* `spawn` — through a bounded-concurrency queue, collecting their results in order.
+*
+* @remarks
+* The Runner composes the workers `Queue` for backpressure, FIFO ordering, bounded
+* concurrency, retries, and the per-attempt timeout — it adds only orchestration, not
+* a second concurrency engine. `execute(inputs)` runs the unit set ONCE (a second call
+* throws) and resolves the units' results in order: the declared inputs first, then
+* any `spawn`ed siblings in spawn order. Each unit's handler gets a `Controller` — its
+* `id` / `input`, a `signal` that fires on the unit's `abort`, a runner-level `abort`,
+* or the attempt's timeout, a promise-parked `wait()`, and `spawn(input)` to fan out
+* sibling units. The run is **fail-fast**: the first unit failure (after retries)
+* aborts every other unit and rejects `execute` with that error. **Observable (§13):** a
+* typed `emitter` surfaces `start` / `unit` / `spawn` / `settle` / `fail` / `finish` / `abort`.
+*
+* Because `spawn` is fire-and-track (the runner awaits the whole spawn closure via an
+* outstanding-unit count, not a one-time snapshot), a handler need NOT await its spawns
+* for them to run — and on a bounded runner it should NOT `await` a spawn inline (a
+* slot-holding handler awaiting its own spawn can deadlock); fan out and return instead.
+*
+* @typeParam TInput - The work input each unit carries
+* @typeParam TResult - The value a unit's handler resolves
+* @param options - The `handler` plus optional `concurrency` (default `1`), `retries`
+*   (default `0`), and a default per-attempt `timeout` in milliseconds
+* @returns A working {@link RunnerInterface}
+*
+* @example
+* ```ts
+* import { createRunner } from '@src/core'
+*
+* // A handler that fans out one sibling per declared unit, then returns its own value.
+* const runner = createRunner<number, number>({
+* 	concurrency: 4,
+* 	handler: (controller) => {
+* 		if (controller.input < 10) controller.spawn(controller.input + 100) // fire-and-track
+* 		return controller.input
+* 	},
+* })
+*
+* const results = await runner.execute([1, 2, 3])
+* // [1, 2, 3, 101, 102, 103] — declared inputs first (in order), then spawns (in order)
+* ```
+*/
+function createRunner(options) {
+	return new Runner(options);
+}
+//#endregion
+export { Controller, DEFAULT_BAIL, DEFAULT_PHASE_CONCURRENCY, DatabaseWorkflowStore, MAX_WORKFLOW_DEPTH, MemoryWorkflowStore, PHASE_STATUSES, Phase, PhaseManager, Runner, Scheduler, TASK_STATUSES, TASK_TRANSITIONS, TASK_VIAS, TERMINAL_TASK_STATUSES, Task, TaskController, TaskManager, WORKFLOW_STATUSES, WORKFLOW_TOOL_DESCRIPTION, WORKFLOW_TOOL_FLAT_EXAMPLE, WORKFLOW_TOOL_NAME, WORKFLOW_TOOL_NESTED_EXAMPLE, Workflow, WorkflowError, WorkflowRunner, agentTag, assertSnapshot, buildPhaseContext, buildTaskContext, buildWorkflowContext, canTransitionTask, collectResults, completeDraft, completePhaseDraft, completeTaskDraft, createDatabaseWorkflowStore, createDeferred, createMemoryWorkflowStore, createRunner, createScheduler, createWorkflow, createWorkflowContract, createWorkflowDraftContract, createWorkflowRunner, createWorkflowTool, definitionToSnapshot, derivePhaseStatus, deriveWorkflowStatus, expandSteps, isAgentTask, isFunctionTask, isTerminalStatus, isToolTask, isWorkflowError, isWorkflowSnapshot, phaseDefinitionToSnapshot, phaseDraftShape, phaseShape, restoreWorkflow, stepShape, stepToForm, taskDefinitionToSnapshot, taskDraftShape, taskFormShape, taskShape, workflowDraftShape, workflowShape, workflowStepsShape, workflowTag, workflowToolSummary };
+
+//# sourceMappingURL=index.js.map