@orkestrel/workflow 0.0.1

package/dist/src/core/index.d.ts

@@ -0,0 +1,3179 @@
+import { AbortInterface } from '@orkestrel/abort';
+import { AgentInterface } from '@orkestrel/agent';
+import { ArrayShape } from '@orkestrel/contract';
+import { BudgetInterface } from '@orkestrel/budget';
+import { ContractInterface } from '@orkestrel/contract';
+import { DriverInterface } from '@orkestrel/database';
+import { EmitterErrorHandler } from '@orkestrel/emitter';
+import { EmitterHooks } from '@orkestrel/emitter';
+import { EmitterInterface } from '@orkestrel/emitter';
+import { LiteralShape } from '@orkestrel/contract';
+import { NumberShape } from '@orkestrel/contract';
+import { ObjectShape } from '@orkestrel/contract';
+import { OptionalShape } from '@orkestrel/contract';
+import { Result } from '@orkestrel/contract';
+import { StringShape } from '@orkestrel/contract';
+import { TableInterface } from '@orkestrel/database';
+import { TokenUsage } from '@orkestrel/budget';
+import { ToolInterface } from '@orkestrel/agent';
+import { ToolManagerInterface } from '@orkestrel/agent';
+import { UnionShape } from '@orkestrel/contract';
+
+/**
+ * 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>`)
+ */
+export declare function agentTag(name: string): string;
+
+/**
+ * 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
+ */
+export declare function assertSnapshot(snapshot: WorkflowSnapshot): void;
+
+/**
+ * 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}
+ */
+export declare function buildPhaseContext(workflow: WorkflowContext, node: WorkflowContext): PhaseContext;
+
+/**
+ * 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}
+ */
+export declare function buildTaskContext(phase: PhaseContext, node: WorkflowContext): TaskContext;
+
+/**
+ * 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}
+ */
+export declare function buildWorkflowContext(node: WorkflowContext): WorkflowContext;
+
+/**
+ * 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
+ */
+export declare function canTransitionTask(from: TaskStatus, to: TaskStatus): boolean;
+
+/**
+ * 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
+ */
+export declare function collectResults(phases: readonly (readonly TaskResult[])[]): readonly TaskResult[];
+
+/**
+ * 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
+ */
+export declare function completeDraft(draft: WorkflowDraft): WorkflowDefinition;
+
+/**
+ * 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}
+ */
+export declare function completePhaseDraft(phase: PhaseDraft, index: number): PhaseDefinition;
+
+/**
+ * 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}
+ */
+export declare function completeTaskDraft(task: TaskDraft, phaseId: string, index: number): TaskDefinition;
+
+/**
+ * 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).
+ */
+export declare class Controller<TInput, TResult> implements ControllerInterface<TInput, TResult> {
+    #private;
+    readonly id: string;
+    readonly input: TInput;
+    readonly signal: AbortSignal;
+    constructor(id: string, input: TInput, abort: AbortInterface, signal: AbortSignal, spawn: (input: TInput) => Promise<TResult>);
+    get aborted(): boolean;
+    wait(): Promise<void>;
+    spawn(input: TInput): Promise<TResult>;
+    abort(reason?: unknown): void;
+}
+
+/**
+ * The per-unit handle a {@link RunnerHandler} receives — the running unit's
+ * identity, input, cancellation, and the controls to cooperate with the run.
+ *
+ * @remarks
+ * One `Controller` is built per unit the {@link RunnerInterface} runs (a declared
+ * input or a `spawn`ed sibling). It exposes:
+ * - `id` — the unit's identifier (a random UUID).
+ * - `input` — the unit's work payload.
+ * - `signal` — the unit's cancellation: fires on the unit's own `abort()`, a
+ *   runner-level `abort` (the runner aborts every unit), or this attempt's timeout
+ *   expiring (it reflects the underlying queue attempt's signal, which ANY-combines
+ *   all three).
+ * - `aborted` — whether the unit's cancellation has fired.
+ *
+ * @typeParam TInput - The unit's work input
+ * @typeParam TResult - The value a unit resolves
+ */
+export declare interface ControllerInterface<TInput, TResult> {
+    readonly id: string;
+    readonly input: TInput;
+    /** Fires on the unit's own `abort()`, a runner-level abort, or this attempt's timeout. */
+    readonly signal: AbortSignal;
+    readonly aborted: boolean;
+    /**
+     * Park until this unit's `signal` aborts — **promise-parked**, never a timer.
+     *
+     * @remarks
+     * Resolves the moment the unit's `signal` fires (unit abort, runner abort, or
+     * timeout) and resolves immediately if it has already fired. It registers a
+     * one-shot `'abort'` listener and never polls — no `setTimeout`, no `delay`, no
+     * busy-yield — so a parked unit consumes no CPU until it is actually cancelled.
+     *
+     * @returns A promise that resolves once the unit's `signal` aborts
+     */
+    wait(): Promise<void>;
+    /**
+     * Add a sibling unit to the run; returns its result promise.
+     *
+     * @remarks
+     * **Fire-and-track.** The spawned unit is routed through the same backing queue
+     * as every declared unit, so it actually runs (in FIFO wake order) and its result
+     * joins the run's ordered output after the declared units, in spawn order. The
+     * runner's `execute` awaits the full transitive spawn closure (it tracks an
+     * outstanding-unit count, not a one-time snapshot), so a caller does NOT need to
+     * await the returned promise to make the sibling run.
+     *
+     * **Deadlock caveat.** On a bounded-`concurrency` runner, do NOT `await` a
+     * `spawn`ed promise *inline* from within a handler — the handler holds a queue
+     * slot while it awaits, and if every slot is held by a handler awaiting its own
+     * spawn, no slot is free to run the spawns and the run deadlocks. The intended
+     * pattern is fan-out: `spawn` siblings and return, letting the runner drain them.
+     *
+     * @param input - The sibling unit's work payload
+     * @returns The sibling's result promise (it runs regardless of whether it's awaited)
+     */
+    spawn(input: TInput): Promise<TResult>;
+    /**
+     * Cancel this unit — fires its `signal` with the optional reason.
+     *
+     * @param reason - An optional cancellation reason carried on the signal
+     */
+    abort(reason?: unknown): void;
+}
+
+/**
+ * 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
+ * ```
+ */
+export declare function createDatabaseWorkflowStore(driver?: DriverInterface): WorkflowStoreInterface;
+
+/**
+ * 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`
+ */
+export declare function createDeferred<T>(): DeferredInterface<T>;
+
+/**
+ * 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
+ * ```
+ */
+export declare function createMemoryWorkflowStore(): WorkflowStoreInterface;
+
+/**
+ * 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)
+ * ```
+ */
+export declare function createRunner<TInput, TResult>(options: RunnerOptions<TInput, TResult>): RunnerInterface<TInput, TResult>;
+
+/**
+ * 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)
+ * }
+ * ```
+ */
+export declare function createScheduler(): SchedulerInterface;
+
+/**
+ * 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)
+ * ```
+ */
+export declare function createWorkflow(definition: WorkflowDefinition, options?: WorkflowOptions): WorkflowInterface;
+
+/**
+ * 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)
+ * ```
+ */
+export declare function createWorkflowContract(): ContractInterface<WorkflowDefinition>;
+
+/**
+ * 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
+ * ```
+ */
+export declare function createWorkflowDraftContract(): ContractInterface<WorkflowDraft>;
+
+/**
+ * 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'
+ * ```
+ */
+export declare function createWorkflowRunner(options?: WorkflowRunnerOptions): WorkflowRunnerInterface;
+
+/**
+ * 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
+ * ```
+ */
+export declare function createWorkflowTool(definition: WorkflowDefinition, runner: WorkflowRunnerInterface, options?: WorkflowToolOptions): ToolInterface;
+
+/**
+ * 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
+ * ```
+ */
+export declare class DatabaseWorkflowStore implements WorkflowStoreInterface {
+    #private;
+    /**
+     * 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: TableInterface<WorkflowSnapshotRow>);
+    /** Resolve the persisted snapshot for `id`, narrowing the opaque JSON column back to a `WorkflowSnapshot`. */
+    get(id: string): Promise<WorkflowSnapshot | undefined>;
+    /** Insert or replace under the snapshot's OWN `id` (no separate id param) — the row is `{ id, snapshot }`. */
+    set(snapshot: WorkflowSnapshot): Promise<void>;
+    /** Drop a snapshot by id; an absent id is a no-op (no throw). */
+    delete(id: string): Promise<void>;
+}
+
+/** The default {@link import('./types.js').WorkflowDefinition.bail} — graceful (continue on a leaf failure). */
+export declare const DEFAULT_BAIL = false;
+
+/**
+ * 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".
+ */
+export declare const DEFAULT_PHASE_CONCURRENCY = 1000000;
+
+/**
+ * A promise paired with its externally-callable `resolve`/`reject` — the settle path
+ * is exposed to the caller instead of being buried in an executor closure.
+ *
+ * @typeParam T - The value the deferred's `promise` resolves
+ */
+export declare interface DeferredInterface<T> {
+    readonly promise: Promise<T>;
+    resolve(value: T): void;
+    reject(reason: unknown): void;
+}
+
+/**
+ * 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}
+ */
+export declare function definitionToSnapshot(definition: WorkflowDefinition, bail?: boolean): WorkflowSnapshot;
+
+/**
+ * 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}
+ */
+export declare function derivePhaseStatus(tasks: readonly TaskStatus[]): PhaseStatus;
+
+/**
+ * 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}
+ */
+export declare function deriveWorkflowStatus(phases: readonly PhaseDerivation[]): WorkflowStatus;
+
+/**
+ * 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)
+ */
+export declare function expandSteps(flat: WorkflowSteps): WorkflowDefinition;
+
+/**
+ * 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'`
+ */
+export declare function isAgentTask(form: TaskForm): form is {
+    readonly via: 'agent';
+    readonly name: string;
+};
+
+/**
+ * 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'`
+ */
+export declare function isFunctionTask(form: TaskForm): form is {
+    readonly via: 'function';
+    readonly name: string;
+};
+
+/**
+ * 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
+ */
+export declare function isTerminalStatus(status: LifecycleStatus): boolean;
+
+/**
+ * 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'`
+ */
+export declare function isToolTask(form: TaskForm): form is {
+    readonly via: 'tool';
+    readonly name: string;
+};
+
+/**
+ * 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()
+ * }
+ * ```
+ */
+export declare function isWorkflowError(value: unknown): value is WorkflowError;
+
+/**
+ * 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}
+ */
+export declare function isWorkflowSnapshot(value: unknown): value is WorkflowSnapshot;
+
+/**
+ * The shared lifecycle vocabulary every tier draws from — `pending` before it runs,
+ * `running` while in flight, then one of the terminal states `completed` / `failed` /
+ * `skipped` / `stopped`.
+ *
+ * @remarks
+ * The ONE literal set behind the three semantic tiers ({@link TaskStatus} /
+ * {@link PhaseStatus} / {@link WorkflowStatus}), which alias it so each keeps its own
+ * name + doc while the vocabulary lives in one place (AGENTS §4.4 "one concept = one
+ * word"). It also types the single runtime terminal check
+ * {@link import('./helpers.js').isTerminalStatus} — every tier's value is a
+ * `LifecycleStatus`, so the one predicate accepts them all. The tiers stay distinct
+ * types (a phase status is not a task status) even though they currently share a body.
+ */
+export declare type LifecycleStatus = 'pending' | 'running' | 'completed' | 'failed' | 'skipped' | 'stopped';
+
+/**
+ * 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.
+ */
+export declare const MAX_WORKFLOW_DEPTH = 8;
+
+/**
+ * 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
+ * ```
+ */
+export declare class MemoryWorkflowStore implements WorkflowStoreInterface {
+    #private;
+    get(id: string): Promise<WorkflowSnapshot | undefined>;
+    set(snapshot: WorkflowSnapshot): Promise<void>;
+    delete(id: string): Promise<void>;
+}
+
+/**
+ * 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}.
+ */
+export declare class Phase implements PhaseInterface {
+    #private;
+    constructor(snapshot: PhaseSnapshot, workflow: WorkflowInterface, escalate: () => void, options?: PhaseOptions, bail?: boolean);
+    get emitter(): EmitterInterface<PhaseEventMap>;
+    get id(): string;
+    get name(): string;
+    get description(): string | undefined;
+    get context(): PhaseContext;
+    get workflow(): WorkflowInterface;
+    get bail(): boolean;
+    get status(): PhaseStatus;
+    get tasks(): TaskManagerInterface;
+    task(id: string): TaskInterface | undefined;
+    results(): readonly TaskResult[];
+    skip(): void;
+    stop(): void;
+    snapshot(): PhaseSnapshot;
+}
+
+/** Every {@link PhaseStatus} value, frozen — the lifecycle vocabulary of a phase. */
+export declare const PHASE_STATUSES: readonly PhaseStatus[];
+
+/**
+ * The ambient context of a phase — its own identity plus a back-reference to the
+ * workflow it belongs to.
+ *
+ * @remarks
+ * Extends {@link WorkflowContext} (so the phase carries its own `id` / `name`) and
+ * adds `workflow`, the parent's context — the lineage pointer back UP the tree.
+ */
+export declare interface PhaseContext extends WorkflowContext {
+    readonly workflow: WorkflowContext;
+}
+
+/**
+ * The serializable definition of one phase — its identity, its ordered tasks, and
+ * an optional resource throttle.
+ *
+ * @remarks
+ * Pure JSON DATA. `tasks` are the phase's tasks, which run CONCURRENTLY (the fixed
+ * determinism principle). `concurrency` is the optional per-phase resource throttle
+ * — the maximum number of tasks in flight at once (a positive integer); omitted ⇒
+ * unbounded. It is a throttle, NOT a sequencing control: phases are always
+ * sequential, tasks within a phase always concurrent.
+ */
+export declare interface PhaseDefinition {
+    readonly id: string;
+    readonly name: string;
+    readonly description?: string;
+    readonly tasks: readonly TaskDefinition[];
+    /** Max tasks in flight at once (a resource throttle); omitted ⇒ unbounded. */
+    readonly concurrency?: number;
+    /**
+     * @remarks
+     * The per-phase failure-policy OVERRIDE (AGENTS §4.4). Omitted ⇒ the phase INHERITS the
+     * workflow `bail`; supplied, it wins (`effectiveBail = phase.bail ?? workflow.bail`). A
+     * `bail: true` phase HALTS the run on its first task failure even under a graceful workflow
+     * default; a `bail: false` phase does NOT halt even under a strict workflow default.
+     */
+    readonly bail?: boolean;
+}
+
+/**
+ * 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}
+ */
+export declare function phaseDefinitionToSnapshot(phase: WorkflowDefinition['phases'][number], workflowBail: boolean): PhaseSnapshot;
+
+/**
+ * One phase's contribution to the workflow-status derivation — its {@link PhaseStatus} paired
+ * with the EFFECTIVE `bail` policy it ran under (`phase.bail ?? workflow.bail`, AGENTS §4.4).
+ *
+ * @remarks
+ * The input shape of {@link import('./helpers.js').deriveWorkflowStatus}: since `bail` is now a
+ * per-phase override, the workflow `failed` derivation is per-phase-bail-aware, so each phase
+ * must carry its OWN effective policy rather than the derivation taking one scalar `bail`. A
+ * `failed` phase propagates `failed` to the workflow only when ITS `bail` is `true`; a `failed`
+ * phase whose `bail` is `false` folds into completion. {@link import('./Workflow.js').Workflow}
+ * builds one per live phase (`{ status: phase.status, bail: phase.bail }`).
+ */
+export declare interface PhaseDerivation {
+    readonly status: PhaseStatus;
+    readonly bail: boolean;
+}
+
+/** A draft phase — a {@link PhaseDefinition} with OPTIONAL `id` / `name` and {@link TaskDraft} tasks. */
+export declare interface PhaseDraft {
+    readonly id?: string;
+    readonly name?: string;
+    readonly description?: string;
+    readonly tasks: readonly TaskDraft[];
+    /** Max tasks in flight at once (a resource throttle); omitted ⇒ unbounded. */
+    readonly concurrency?: number;
+    /** The per-phase failure-policy OVERRIDE; omitted ⇒ inherits the workflow `bail` (`effectiveBail = phase.bail ?? workflow.bail`). */
+    readonly bail?: boolean;
+}
+
+/**
+ * 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.
+ */
+export declare const phaseDraftShape: ObjectShape<{
+    id: OptionalShape<StringShape>;
+    name: OptionalShape<StringShape>;
+    description: OptionalShape<StringShape>;
+    tasks: ArrayShape<ObjectShape<{
+        id: OptionalShape<StringShape>;
+        name: OptionalShape<StringShape>;
+        description: OptionalShape<StringShape>;
+        run: UnionShape<[ ObjectShape<{
+            via: LiteralShape<readonly ["function"]>;
+            name: StringShape;
+        }>, ObjectShape<{
+            via: LiteralShape<readonly ["tool"]>;
+            name: StringShape;
+        }>, ObjectShape<{
+            via: LiteralShape<readonly ["agent"]>;
+            name: StringShape;
+        }>]>;
+        retries: OptionalShape<NumberShape>;
+        timeout: OptionalShape<NumberShape>;
+    }>>;
+    concurrency: OptionalShape<NumberShape>;
+    bail: OptionalShape<LiteralShape<readonly [true, false]>>;
+}>;
+
+/**
+ * The push observation surface (AGENTS §13) of the phase entity (W-b) — analogous
+ * to {@link WorkflowEventMap}, scoped to one phase.
+ *
+ * @remarks
+ * `start` fires when the phase begins; `complete` when all its tasks settled
+ * successfully; `fail` when a task failed under `bail` (carrying the
+ * {@link TaskResult}); `stop` when the phase was ended. A throwing listener is
+ * isolated by the emitter and routed to its `error` handler, not the domain surface
+ * (AGENTS §13). A `type` alias (AGENTS §4.5) so it satisfies `EventMap`.
+ */
+export declare type PhaseEventMap = {
+    /** The phase began — its `id`. */
+    readonly start: readonly [id: string];
+    /** Every task in the phase settled successfully. */
+    readonly complete: readonly [];
+    /** A task failed under `bail` — the failing task's result. */
+    readonly fail: readonly [result: TaskResult];
+    /** The phase was permanently stopped. */
+    readonly stop: readonly [];
+};
+
+/** Initial {@link PhaseEventMap} listeners — the reserved `on` option (AGENTS §8). */
+export declare type PhaseHooks = EmitterHooks<PhaseEventMap>;
+
+/** The minimal data to create a phase context — a partial {@link PhaseContext}. */
+export declare type PhaseInput = Partial<PhaseContext>;
+
+/**
+ * The live derived state machine (W-b) for one {@link PhaseDefinition} — an
+ * observable (AGENTS §13) phase whose {@link PhaseStatus} is DERIVED from its tasks
+ * (never set directly) and recomputed reactively as a task transitions (the cascade).
+ *
+ * @remarks
+ * - **Derived status.** `status` is computed via
+ *   {@link import('./helpers.js').derivePhaseStatus} over the live tasks' statuses,
+ *   UNLESS an override is in force. It recomputes whenever a child task transitions; a
+ *   CHANGE emits.
+ * - **Children.** `tasks` is the lean {@link TaskManagerInterface} (AGENTS §9 — an
+ *   accessor + `count`, no batch matrix); `task(id)` / `tasks().tasks()` read in positional
+ *   order. `results` collects the settled tasks' {@link TaskResult}s (the phase tier of the
+ *   result tree); `workflow` navigates UP to the live parent.
+ * - **Override.** `skip` / `stop` (AGENTS §10) FORCE the phase's status, overriding the
+ *   derived value (e.g. skipping a whole phase); the override survives a snapshot.
+ * - **Observable (AGENTS §13).** The owned {@link emitter} ({@link PhaseEventMap}) 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).
+ */
+export declare interface PhaseInterface {
+    readonly emitter: EmitterInterface<PhaseEventMap>;
+    readonly id: string;
+    readonly name: string;
+    readonly description?: string;
+    readonly context: PhaseContext;
+    readonly workflow: WorkflowInterface;
+    readonly status: PhaseStatus;
+    /** The RESOLVED effective failure policy this phase runs under (`phase.bail ?? workflow.bail`); mirrors {@link WorkflowInterface.bail}. */
+    readonly bail: boolean;
+    readonly tasks: TaskManagerInterface;
+    /** Look up one live task by its `id`. */
+    task(id: string): TaskInterface | undefined;
+    /** The settled tasks' results, in positional order — the phase tier of the result tree. */
+    results(): readonly TaskResult[];
+    skip(): void;
+    stop(): void;
+    snapshot(): PhaseSnapshot;
+}
+
+/**
+ * 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
+ * ```
+ */
+export declare class PhaseManager implements PhaseManagerInterface {
+    #private;
+    get count(): number;
+    append(phase: PhaseInterface): void;
+    phase(id: string): PhaseInterface | undefined;
+    phases(): readonly PhaseInterface[];
+}
+
+/**
+ * The lean child manager (AGENTS §9) of a {@link WorkflowInterface}'s live phases —
+ * positional accessors plus `count`, the phase analogue of {@link TaskManagerInterface}.
+ *
+ * @remarks
+ * `append` adds one live {@link PhaseInterface} at the end; `phase(id)` looks one up;
+ * `phases()` lists them in positional order; `count` is the tally. No batch matrix.
+ */
+export declare interface PhaseManagerInterface {
+    readonly count: number;
+    append(phase: PhaseInterface): void;
+    phase(id: string): PhaseInterface | undefined;
+    phases(): readonly PhaseInterface[];
+}
+
+/**
+ * The runtime options for a {@link PhaseInterface} — the construction bag the live
+ * derived phase state machine (W-b) carries.
+ *
+ * @remarks
+ * The reserved `on` (AGENTS §8) wires initial {@link PhaseEventMap} listeners.
+ * `tasks` keys per-task {@link TaskOptions} by task `id`, so {@link createWorkflow}
+ * can thread a leaf's options (its `on` / `metadata`) down through the phase when it
+ * builds the whole tree.
+ */
+export declare interface PhaseOptions {
+    readonly on?: PhaseHooks;
+    /** The emitter's listener-error handler (AGENTS §13) — a listener throw routes here, not to a domain event. */
+    readonly error?: EmitterErrorHandler;
+    /** Per-task {@link TaskOptions}, keyed by the task's `id`. */
+    readonly tasks?: Readonly<Record<string, TaskOptions>>;
+}
+
+/**
+ * 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).
+ */
+export declare const phaseShape: ObjectShape<{
+    id: StringShape;
+    name: StringShape;
+    description: OptionalShape<StringShape>;
+    tasks: ArrayShape<ObjectShape<{
+        id: StringShape;
+        name: StringShape;
+        description: OptionalShape<StringShape>;
+        run: UnionShape<[ ObjectShape<{
+            via: LiteralShape<readonly ["function"]>;
+            name: StringShape;
+        }>, ObjectShape<{
+            via: LiteralShape<readonly ["tool"]>;
+            name: StringShape;
+        }>, ObjectShape<{
+            via: LiteralShape<readonly ["agent"]>;
+            name: StringShape;
+        }>]>;
+        retries: OptionalShape<NumberShape>;
+        timeout: OptionalShape<NumberShape>;
+    }>>;
+    concurrency: OptionalShape<NumberShape>;
+    bail: OptionalShape<LiteralShape<readonly [true, false]>>;
+}>;
+
+/**
+ * A JSON-serializable snapshot of one phase's state — its identity, status, its forced
+ * override (if any), and its nested task snapshots.
+ *
+ * @remarks
+ * Pure JSON DATA. `status` is the EFFECTIVE status (override-or-derived) at snapshot time.
+ * `override` is the forced status of a whole-phase `skip` / `stop` (AGENTS §10) — PRESENT only
+ * when one is in force, so a restore reinstates it DIRECTLY (no fragile derivation comparison)
+ * and a genuinely-derived phase carries none. A leaf {@link TaskSnapshot} needs no `override`
+ * field — a task's terminal status IS its forced marker. `tasks` are the phase's
+ * {@link TaskSnapshot}s in order.
+ */
+export declare interface PhaseSnapshot {
+    readonly id: string;
+    readonly name: string;
+    readonly description?: string;
+    readonly status: PhaseStatus;
+    /** The forced status of a whole-phase `skip` / `stop`; present only when an override is in force. */
+    readonly override?: PhaseStatus;
+    /**
+     * The EFFECTIVE failure policy this phase ran under (`phase.bail ?? workflow.bail`, AGENTS §4.4)
+     * — persisted (REQUIRED, like {@link WorkflowSnapshot.bail}) so a restore reinstates the same
+     * per-phase policy identically without a silent default.
+     */
+    readonly bail: boolean;
+    readonly tasks: readonly TaskSnapshot[];
+}
+
+/**
+ * The lifecycle status of a phase — the same vocabulary as {@link TaskStatus},
+ * derived from its tasks' statuses.
+ *
+ * @remarks
+ * A semantic tier of the shared {@link LifecycleStatus} vocabulary. A phase is
+ * `failed` only when a task failed AND the workflow's `bail` policy is in force (a
+ * failure under graceful mode is data, not a phase failure). `stopped` propagates
+ * when every task was stopped. See {@link import('./helpers.js').derivePhaseStatus}.
+ */
+export declare type PhaseStatus = LifecycleStatus;
+
+/**
+ * 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
+ * ```
+ */
+export declare function restoreWorkflow(snapshot: WorkflowSnapshot, options?: WorkflowOptions): WorkflowInterface;
+
+/**
+ * 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.
+ */
+export declare class Runner<TInput, TResult> implements RunnerInterface<TInput, TResult> {
+    #private;
+    constructor(options: RunnerOptions<TInput, TResult>);
+    get emitter(): EmitterInterface<RunnerEventMap<TResult>>;
+    get active(): number;
+    get stopped(): boolean;
+    execute(inputs: readonly TInput[]): Promise<readonly TResult[]>;
+    abort(reason?: unknown): void;
+    destroy(): void;
+}
+
+/**
+ * The per-entry reliability OVERRIDES for one unit — its extra attempts on failure and its
+ * per-attempt deadline, resolved from the unit's input via {@link RunnerOptions.entries}.
+ *
+ * @remarks
+ * The unit's `id` and `signal` stay Runner-managed (it mints the id and owns the per-unit
+ * abort), so only the two reliability knobs are exposed here. Each field OVERRIDES the
+ * runner-level `retries` / `timeout` default for that one unit; an omitted field falls back
+ * to the default. This is the per-unit slice of the backing Queue's
+ * `@orkestrel/queue` `QueueEntryOptions` surfaced cleanly — the Queue already
+ * resolves default→override.
+ */
+export declare interface RunnerEntryOptions {
+    readonly retries?: number;
+    readonly timeout?: number;
+}
+
+/**
+ * The push observation surface of a {@link RunnerInterface} (AGENTS §13) — the run
+ * lifecycle a fire-and-forget observer (logging, metrics, tracing) subscribes to,
+ * ALONGSIDE the eventual `execute` result.
+ *
+ * @typeParam TResult - The value a unit resolves; the `finish` payload is the run's ordered
+ *   `readonly TResult[]`, so the map is `RunnerEventMap<TResult>` — mirroring how the
+ *   {@link RunnerInterface} is generic.
+ *
+ * @remarks
+ * Listener isolation is the emitter's (AGENTS §13): every event is emitted directly and a
+ * listener throw is routed to the emitter's OWN `error` handler (the `error` option), never
+ * onto this domain map and never into the one-shot / fail-fast / spawn-tracking engine — so a
+ * buggy observer can never reorder, throw into, or corrupt the run. Every emit sits AFTER the
+ * relevant unit-launch / settle / drain transition, so a throwing observer cannot unbalance
+ * the outstanding-unit count gate or break fail-fast. Subscribe via `runner.emitter.on(...)`.
+ *
+ * Declared as a `type` alias (not `interface extends EventMap`, §4.5 — `EventMap` is a
+ * `type` kind): a type-literal satisfies the `EventMap` constraint
+ * (`Record<string, readonly unknown[]>`) structurally, whereas an interface lacks the
+ * required index signature.
+ */
+export declare type RunnerEventMap<TResult> = {
+    /** `execute` began — emitted once at the top of a non-empty run. */
+    readonly start: readonly [];
+    /** A unit's handler began running — the unit's id (declared or spawned). */
+    readonly unit: readonly [id: string];
+    /** A sub-unit was spawned — its id + the spawning parent's id (when known). */
+    readonly spawn: readonly [id: string, parent: string | undefined];
+    /** A unit completed successfully — its id (after its outcome was recorded). */
+    readonly settle: readonly [id: string];
+    /** A unit failed — its id + the error (always `unknown`). */
+    readonly fail: readonly [id: string, error: unknown];
+    /** The batch settled — the run's ordered results (the same array `execute` resolves). */
+    readonly finish: readonly [results: readonly TResult[]];
+    /** The run was aborted (fail-fast, a user `abort`, or `destroy`) — the cancel reason. */
+    readonly abort: readonly [reason: unknown];
+};
+
+/**
+ * Runs one unit's work, given its {@link ControllerInterface}.
+ *
+ * @typeParam TInput - The unit's work input
+ * @typeParam TResult - The value the handler resolves for a unit
+ */
+export declare type RunnerHandler<TInput, TResult> = (controller: ControllerInterface<TInput, TResult>) => Promise<TResult> | TResult;
+
+/**
+ * A thin generic orchestrator that drives declared units — plus any they `spawn` —
+ * through a bounded-concurrency queue, collecting their results in order.
+ *
+ * @remarks
+ * One-shot: `execute` runs the unit set once and resolves their results. A `Runner`
+ * does not reimplement concurrency or retries — it composes the workers `Queue`
+ * (the backpressure + retry + timeout engine), routing every unit (declared and
+ * spawned) through it so spawned work actually runs.
+ *
+ * Exposes a typed {@link emitter} (AGENTS §13) carrying its run lifecycle moments
+ * ({@link RunnerEventMap}) for fire-and-forget observers, ALONGSIDE the eventual `execute`
+ * result. Emitting is observation-only — every event fires AFTER the relevant unit-launch /
+ * settle / drain transition, so a buggy observer can never reorder or corrupt the one-shot /
+ * fail-fast / spawn-tracking engine: the emitter isolates a listener throw and routes it to
+ * its `error` handler (the `error` option), never the run. Subscribe via
+ * `runner.emitter.on(...)`.
+ *
+ * @typeParam TInput - The unit's work input
+ * @typeParam TResult - The value a unit resolves
+ */
+export declare interface RunnerInterface<TInput, TResult> {
+    readonly emitter: EmitterInterface<RunnerEventMap<TResult>>;
+    readonly active: number;
+    readonly stopped: boolean;
+    /**
+     * Run all `inputs` — and anything they `spawn` — to completion; resolve their
+     * results in order: the declared inputs first (in input order), then the spawned
+     * units (in spawn order).
+     *
+     * @remarks
+     * One-shot — a second call throws. **Fail-fast** — the first unit failure (after
+     * its retries) aborts every other in-flight + pending unit and rejects the run
+     * with that error; later failures are ignored. An empty `inputs` resolves to `[]`.
+     *
+     * @param inputs - The declared units to run
+     * @returns The units' results, in order (declared first, then spawns)
+     */
+    execute(inputs: readonly TInput[]): Promise<readonly TResult[]>;
+    /**
+     * Cancel every in-flight + pending unit (and the backing queue), making a running
+     * `execute` reject.
+     *
+     * @param reason - An optional cancellation reason propagated to every unit's signal
+     */
+    abort(reason?: unknown): void;
+    /** Tear the runner down — `abort` plus stop the backing queue; idempotent. */
+    destroy(): void;
+}
+
+/**
+ * Options for `createRunner`.
+ *
+ * @remarks
+ * - `handler` — runs each unit's work against its {@link ControllerInterface};
+ *   rejecting fails the unit (and, after retries are exhausted, fails the run).
+ * - `concurrency` — the maximum units in flight at once; defaults to `1` (ordered,
+ *   one-at-a-time). Floored at `1`.
+ * - `retries` — the default extra attempts per unit on failure (or a per-attempt
+ *   timeout); defaults to `0`.
+ * - `timeout` — the per-attempt deadline in milliseconds; defaults to none (a
+ *   non-positive value means no deadline).
+ * - `entries` — per-entry `retries` / `timeout` overrides, resolved from each
+ *   input; falls back to the runner-level `retries` / `timeout` defaults.
+ * - `on` — the reserved {@link EmitterHooks} key (§8): initial listeners for the runner's
+ *   {@link RunnerEventMap}, wired at construction (e.g. `{ finish: (r) => log(r) }`).
+ */
+export declare interface RunnerOptions<TInput, TResult> {
+    readonly on?: EmitterHooks<RunnerEventMap<TResult>>;
+    /** The emitter's listener-error handler (AGENTS §13) — a listener throw routes here, not to a domain event. */
+    readonly error?: EmitterErrorHandler;
+    readonly handler: RunnerHandler<TInput, TResult>;
+    readonly concurrency?: number;
+    readonly retries?: number;
+    readonly timeout?: number;
+    /** Per-entry `retries` / `timeout` overrides, resolved from each input; falls back to the runner-level defaults. */
+    readonly entries?: (input: TInput) => RunnerEntryOptions;
+}
+
+/**
+ * One unit the {@link RunnerInterface} is tracking: the queue payload it was enqueued
+ * with — its `id` (a random UUID) keys it in the runner's ordered launch list and value
+ * map, and `input` is the unit's work payload handed to the handler's `Controller`.
+ *
+ * @remarks
+ * The runner's internal bookkeeping shape, published through the barrel because §5
+ * centralizes every file-local type — declared or spawned, every unit flows through the
+ * one queue as a `RunnerUnit`, so backpressure / ordering / retries / timeout stay the
+ * Queue's behavior and the runner adds only orchestration.
+ *
+ * @typeParam TInput - The unit's work input
+ */
+export declare interface RunnerUnit<TInput> {
+    readonly id: string;
+    readonly input: TInput;
+}
+
+/**
+ * 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
+ * }
+ * ```
+ */
+export declare class Scheduler implements SchedulerInterface {
+    #private;
+    /**
+     * 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?: SchedulerOptions): Promise<void>;
+    /**
+     * 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: number, options?: SchedulerOptions): Promise<void>;
+}
+
+/**
+ * A cooperative host-yield primitive: a loop decides WHAT to do; the scheduler
+ * decides WHEN the host regains control. Abort-aware — a pending yield/delay
+ * rejects with the signal's reason when aborted.
+ */
+export declare interface SchedulerInterface {
+    /**
+     * Yield control back to the host so other tasks (I/O, timers, rendering) can
+     * run, then resume.
+     */
+    yield(options?: SchedulerOptions): Promise<void>;
+    /** Resume after at least `ms` milliseconds. */
+    delay(ms: number, options?: SchedulerOptions): Promise<void>;
+}
+
+/** Options for a single cooperative yield/delay. */
+export declare interface SchedulerOptions {
+    /**
+     * A relative urgency hint. Honoured by environment backends; the
+     * cross-environment default treats all priorities the same.
+     */
+    readonly priority?: SchedulerPriority;
+    /** A signal whose abort rejects a pending yield/delay with its `reason`. */
+    readonly signal?: AbortSignal;
+}
+
+/**
+ * Relative urgency hint for cooperative scheduling. Honoured by environment
+ * backends; the cross-environment default treats all priorities uniformly.
+ */
+export declare type SchedulerPriority = 'user' | 'normal' | 'background';
+
+/**
+ * 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}).
+ */
+export declare const stepShape: ObjectShape<{
+    name: StringShape;
+    via: OptionalShape<LiteralShape<readonly ["function", "tool", "agent"]>>;
+}>;
+
+/**
+ * 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
+ */
+export declare function stepToForm(step: WorkflowStep): TaskForm;
+
+/**
+ * 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.
+ */
+export declare class Task implements TaskInterface {
+    #private;
+    constructor(context: TaskContext, phase: PhaseInterface, workflow: WorkflowInterface, recompute: () => void, options?: TaskOptions, status?: TaskStatus, result?: TaskResult);
+    get emitter(): EmitterInterface<TaskEventMap>;
+    get id(): string;
+    get name(): string;
+    get description(): string | undefined;
+    get context(): TaskContext;
+    get phase(): PhaseInterface;
+    get workflow(): WorkflowInterface;
+    get status(): TaskStatus;
+    get result(): TaskResult | undefined;
+    start(): void;
+    complete(value: unknown): void;
+    fail(error: unknown): void;
+    skip(): void;
+    stop(): void;
+    snapshot(): TaskSnapshot;
+}
+
+/**
+ * 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.
+ */
+export declare const TASK_STATUSES: readonly TaskStatus[];
+
+/**
+ * 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.
+ */
+export declare const TASK_TRANSITIONS: Readonly<Record<TaskStatus, readonly TaskStatus[]>>;
+
+/**
+ * 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.
+ */
+export declare const TASK_VIAS: readonly TaskVia[];
+
+/**
+ * The ambient context of a task — its own identity plus a back-reference to the
+ * phase (and, transitively, the workflow) it belongs to.
+ *
+ * @remarks
+ * Extends {@link WorkflowContext} and adds `phase`, the parent {@link PhaseContext}
+ * — so a task carries its FULL lineage (workflow → phase → task) for a
+ * {@link TaskResult} or a runner.
+ */
+export declare interface TaskContext extends WorkflowContext {
+    readonly phase: PhaseContext;
+}
+
+/**
+ * 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.
+ */
+export declare class TaskController implements TaskControllerInterface {
+    #private;
+    readonly signal: AbortSignal;
+    readonly input: Readonly<Record<string, unknown>>;
+    readonly task: TaskContext;
+    constructor(signal: AbortSignal, input: Readonly<Record<string, unknown>>, task: TaskContext, results: () => readonly TaskResult[]);
+    get aborted(): boolean;
+    results(): readonly TaskResult[];
+}
+
+/**
+ * The per-task handle a {@link WorkflowFunction} receives — the running task's
+ * cancellation, its input, its lineage, and read-UP access to the result tree.
+ *
+ * @remarks
+ * A NEW, lean handle (NOT the runner `Controller` — it carries no `spawn` / `wait`; a
+ * workflow task is a leaf of the declarative tree, not a fan-out unit). It exposes:
+ * - `signal` — the task's folded cancellation: 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). A handler races its work against it.
+ * - `aborted` — whether `signal` has fired.
+ * - `input` — the task's `metadata` bag (the open consumer payload from its
+ *   {@link TaskInput}); `{}` when none.
+ * - `task` — the task's full {@link TaskContext} (so `task.phase` / `task.phase.workflow`
+ *   navigate UP the lineage).
+ * - `results()` — every settled task's {@link TaskResult} across already-finished phases,
+ *   so a `function` task can read an earlier phase's output (the W-b result tree, read-only).
+ */
+export declare interface TaskControllerInterface {
+    /** Fires on a workflow-level abort / timeout / budget, or a sibling failure under `bail: true`. */
+    readonly signal: AbortSignal;
+    readonly aborted: boolean;
+    /** The task's open `metadata` bag (its {@link TaskInput} payload); `{}` when none. */
+    readonly input: Readonly<Record<string, unknown>>;
+    readonly task: TaskContext;
+    /** Every settled task's result across already-finished phases — the result tree, read-only. */
+    results(): readonly TaskResult[];
+}
+
+/**
+ * The serializable definition of one task — its identity plus the behavior it runs
+ * (a {@link TaskForm}, referenced by name).
+ *
+ * @remarks
+ * Pure JSON DATA: a UI or an LLM authors it, it round-trips through the contract
+ * (factories.ts), and it carries NO functions. `id` is the positional identity
+ * within its phase; `name` is the human label; `description` is optional prose;
+ * `run` is the {@link TaskForm} naming the registered behavior.
+ */
+export declare interface TaskDefinition {
+    readonly id: string;
+    readonly name: string;
+    readonly description?: string;
+    readonly run: TaskForm;
+    /**
+     * @remarks
+     * Extra attempts after the first on failure (a non-negative integer); the runner threads it
+     * to this task's substrate unit, OVERRIDING the phase Runner's `retries` default. Omitted ⇒
+     * the default (no extra attempts). Execution-only: it is NOT persisted in a snapshot.
+     */
+    readonly retries?: number;
+    /**
+     * @remarks
+     * The per-attempt deadline in milliseconds (a non-negative integer); the runner threads it to
+     * this task's substrate unit, OVERRIDING the phase Runner's `timeout` default. Omitted (or a
+     * non-positive value) ⇒ no deadline. Execution-only: it is NOT persisted in a snapshot.
+     */
+    readonly timeout?: number;
+}
+
+/**
+ * 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}
+ */
+export declare function taskDefinitionToSnapshot(task: WorkflowDefinition['phases'][number]['tasks'][number]): TaskSnapshot;
+
+/**
+ * A draft task — a {@link TaskDefinition} with OPTIONAL `id` / `name`.
+ *
+ * @remarks
+ * The tool synthesizes a missing `id` positionally and defaults a missing `name` to
+ * its `id` ({@link import('./helpers.js').completeDraft}). A PROVIDED `id` / `name` is
+ * preserved verbatim (and must be non-empty — the draft contract's `minLength: 1`).
+ */
+export declare interface TaskDraft {
+    readonly id?: string;
+    readonly name?: string;
+    readonly description?: string;
+    readonly run: TaskForm;
+    /** Extra attempts after the first on failure (a non-negative integer); overrides the phase Runner default. Execution-only. */
+    readonly retries?: number;
+    /** The per-attempt deadline in milliseconds (a non-negative integer); overrides the phase Runner default. Execution-only. */
+    readonly timeout?: number;
+}
+
+/**
+ * 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.
+ */
+export declare const taskDraftShape: ObjectShape<{
+    id: OptionalShape<StringShape>;
+    name: OptionalShape<StringShape>;
+    description: OptionalShape<StringShape>;
+    run: UnionShape<[ ObjectShape<{
+        via: LiteralShape<readonly ["function"]>;
+        name: StringShape;
+    }>, ObjectShape<{
+        via: LiteralShape<readonly ["tool"]>;
+        name: StringShape;
+    }>, ObjectShape<{
+        via: LiteralShape<readonly ["agent"]>;
+        name: StringShape;
+    }>]>;
+    retries: OptionalShape<NumberShape>;
+    timeout: OptionalShape<NumberShape>;
+}>;
+
+/**
+ * The push observation surface (AGENTS §13) of the task entity (W-b) — the
+ * lifecycle moments of one task.
+ *
+ * @remarks
+ * `start` fires when the task begins; `complete` when it finishes successfully
+ * (carrying its {@link TaskResult}); `fail` when it errors (carrying the result);
+ * `skip` when it is intentionally not executed; `stop` when it is ended early. A
+ * throwing listener is isolated by the emitter and routed to its `error` handler,
+ * not the domain surface (AGENTS §13). A `type` alias (AGENTS §4.5) so it satisfies
+ * `EventMap`.
+ */
+export declare type TaskEventMap = {
+    /** The task began — its `id`. */
+    readonly start: readonly [id: string];
+    /** The task finished successfully — its result. */
+    readonly complete: readonly [result: TaskResult];
+    /** The task failed — its result. */
+    readonly fail: readonly [result: TaskResult];
+    /** The task was intentionally skipped. */
+    readonly skip: readonly [];
+    /** The task was permanently stopped. */
+    readonly stop: readonly [];
+};
+
+/**
+ * A {@link TaskDefinition}'s behavior reference — a descriptive tagged union over
+ * the three execution forms a task can take, discriminated by `via` (the axis is
+ * the execution MECHANISM, never a bare `kind`; AGENTS §4.4). Each form references
+ * its behavior BY NAME through a registry (the runner resolves the name at W-b);
+ * a definition NEVER inlines a function, so the whole tree stays JSON-serializable.
+ *
+ * @remarks
+ * - `function` — a registered function the runner invokes directly.
+ * - `tool` — a registered {@link ToolInterface} the
+ *   runner executes as a tool call.
+ * - `agent` — a registered agent (a subagent). It will later carry a depth/cycle
+ *   guard (W-c, bounded by {@link import('./constants.js').MAX_WORKFLOW_DEPTH}); in
+ *   W-a it is purely the typed reference.
+ *
+ * `name` is the registry key (it identifies the behavior the form runs). A
+ * descriptive `via` literal (not `kind`) names the axis that varies, and the
+ * `is*` guards narrow on `run.via` cleanly.
+ */
+export declare type TaskForm = {
+    readonly via: 'function';
+    readonly name: string;
+} | {
+    readonly via: 'tool';
+    readonly name: string;
+} | {
+    readonly via: 'agent';
+    readonly name: string;
+};
+
+/**
+ * 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`.
+ */
+export declare const taskFormShape: UnionShape<[ ObjectShape<{
+    via: LiteralShape<readonly ["function"]>;
+    name: StringShape;
+}>, ObjectShape<{
+    via: LiteralShape<readonly ["tool"]>;
+    name: StringShape;
+}>, ObjectShape<{
+    via: LiteralShape<readonly ["agent"]>;
+    name: StringShape;
+}>]>;
+
+/** Initial {@link TaskEventMap} listeners — the reserved `on` option (AGENTS §8). */
+export declare type TaskHooks = EmitterHooks<TaskEventMap>;
+
+/**
+ * The minimal data to create a task context — a partial {@link TaskContext} plus
+ * any creation-only fields.
+ *
+ * @remarks
+ * `metadata` is an open consumer bag the workflow system stores and carries into a
+ * {@link TaskSnapshot} but never interprets. All members are optional (the storing
+ * layer fills identity / lineage).
+ */
+export declare interface TaskInput extends Partial<TaskContext> {
+    /** An open consumer bag — stored and snapshotted, never interpreted by the workflow. */
+    readonly metadata?: Readonly<Record<string, unknown>>;
+}
+
+/**
+ * The live leaf state machine (W-b) for one {@link TaskDefinition} — an observable
+ * (AGENTS §13), guarded synchronous task whose explicit {@link TaskStatus} advances
+ * through the AGENTS §10 transitions.
+ *
+ * @remarks
+ * - **Identity + lineage.** `id` / `name` / `description` mirror the definition;
+ *   `context` is the task's full {@link TaskContext} (so `context.phase` /
+ *   `context.phase.workflow` navigate UP the tree), and `phase` / `workflow` are the
+ *   live parent entities for direct lineage navigation.
+ * - **State machine (AGENTS §10).** `status` is the explicit current state. `start`
+ *   moves `pending → running`; the terminal transitions are `complete(value)` (records
+ *   a {@link import('@orkestrel/contract').Success}), `fail(error)` (records a
+ *   {@link import('@orkestrel/contract').Failure}), `skip` (AGENTS §10 — intentionally not run),
+ *   and `stop` (AGENTS §10 — ended early). Each is GUARDED: an illegal transition (e.g.
+ *   completing a non-`running` task) throws a {@link import('./errors.js').WorkflowError}.
+ *   `skip` / `stop` set the override so the leaf's terminal state survives a snapshot.
+ * - **Result.** `result` is the recorded {@link TaskResult} once the task settled with an
+ *   outcome (`completed` / `failed`), else `undefined` — the lineage-navigable leaf of the
+ *   result tree.
+ * - **Observable (AGENTS §13).** The owned {@link emitter} ({@link TaskEventMap}) fires
+ *   `start` / `complete` / `fail` / `skip` / `stop` strictly AFTER each transition; the
+ *   emitter isolates a listener throw and routes it to its `error` handler (the `error` option).
+ */
+export declare interface TaskInterface {
+    readonly emitter: EmitterInterface<TaskEventMap>;
+    readonly id: string;
+    readonly name: string;
+    readonly description?: string;
+    readonly context: TaskContext;
+    readonly phase: PhaseInterface;
+    readonly workflow: WorkflowInterface;
+    readonly status: TaskStatus;
+    /** The recorded outcome once the task settled with one (`completed` / `failed`), else `undefined`. */
+    readonly result: TaskResult | undefined;
+    start(): void;
+    complete(value: unknown): void;
+    fail(error: unknown): void;
+    skip(): void;
+    stop(): void;
+    snapshot(): TaskSnapshot;
+}
+
+/**
+ * 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
+ * ```
+ */
+export declare class TaskManager implements TaskManagerInterface {
+    #private;
+    get count(): number;
+    append(task: TaskInterface): void;
+    task(id: string): TaskInterface | undefined;
+    tasks(): readonly TaskInterface[];
+}
+
+/**
+ * The lean child manager (AGENTS §9) of a {@link PhaseInterface}'s live tasks —
+ * positional accessors plus `count`, backed by an insertion-ordered store so order
+ * is preserved across an interior `skip` / `remove`.
+ *
+ * @remarks
+ * `append` adds one live {@link TaskInterface} at the end (the build-time wiring path);
+ * `task(id)` looks one up; `tasks()` lists them in positional order; `count` is the
+ * tally. No batch matrix (AGENTS §9.2 is deliberately omitted — a phase's tasks are a
+ * fixed positional set, not a bulk-mutated collection).
+ */
+export declare interface TaskManagerInterface {
+    readonly count: number;
+    append(task: TaskInterface): void;
+    task(id: string): TaskInterface | undefined;
+    tasks(): readonly TaskInterface[];
+}
+
+/**
+ * The runtime options for a {@link TaskInterface} — the construction bag the live
+ * leaf state machine (W-b) carries that the W-a {@link TaskDefinition} did not.
+ *
+ * @remarks
+ * The reserved `on` (AGENTS §8) wires initial {@link TaskEventMap} listeners; a
+ * {@link createTask}-built tree threads each level's `on` from its parent options.
+ * `metadata` is the open consumer bag carried verbatim into a {@link TaskSnapshot}
+ * (mirrors {@link TaskInput.metadata}), never interpreted by the workflow.
+ */
+export declare interface TaskOptions {
+    readonly on?: TaskHooks;
+    /** The emitter's listener-error handler (AGENTS §13) — a listener throw routes here, not to a domain event. */
+    readonly error?: EmitterErrorHandler;
+    /** An open consumer bag — stored and snapshotted, never interpreted by the workflow. */
+    readonly metadata?: Readonly<Record<string, unknown>>;
+}
+
+/**
+ * The structured outcome of a task execution — its full lineage, its terminal
+ * status, the moment it settled, and its boxed produced outcome.
+ *
+ * @remarks
+ * Carries the complete lineage (`task` / `phase` / `workflow` contexts) so a result
+ * is self-describing wherever it travels. `status` is the terminal state this
+ * result records. `result` BOXES the produced outcome in a {@link Result}: it is
+ * PRESENT exactly when `status` is `completed` (a {@link import('@orkestrel/contract').Success})
+ * or `failed` (a {@link import('@orkestrel/contract').Failure}), and ABSENT when `status` is
+ * `skipped` or `stopped` (terminal, but produced no outcome) — a pending/running
+ * task has no result at all (a non-terminal status, per
+ * {@link import('./helpers.js').isTerminalStatus}). This boxed `result` REPLACES separate
+ * `value?` / `error?` fields: a success's payload is `result.value`, a failure's reason is `result.error`.
+ * `timestamp` is when the result was created (ms since epoch).
+ */
+export declare interface TaskResult {
+    readonly task: TaskContext;
+    readonly phase: PhaseContext;
+    readonly workflow: WorkflowContext;
+    readonly status: TaskStatus;
+    /** The boxed outcome — present for `completed` (Success) / `failed` (Failure), absent otherwise. */
+    readonly result?: Result<unknown>;
+    readonly timestamp: number;
+}
+
+/**
+ * The shape of a {@link import('./types.js').TaskDefinition} — identity plus the
+ * behavior reference ({@link taskFormShape}). `description` is optional prose.
+ */
+export declare const taskShape: ObjectShape<{
+    id: StringShape;
+    name: StringShape;
+    description: OptionalShape<StringShape>;
+    run: UnionShape<[ ObjectShape<{
+        via: LiteralShape<readonly ["function"]>;
+        name: StringShape;
+    }>, ObjectShape<{
+        via: LiteralShape<readonly ["tool"]>;
+        name: StringShape;
+    }>, ObjectShape<{
+        via: LiteralShape<readonly ["agent"]>;
+        name: StringShape;
+    }>]>;
+    retries: OptionalShape<NumberShape>;
+    timeout: OptionalShape<NumberShape>;
+}>;
+
+/**
+ * A JSON-serializable snapshot of one task's state — the leaf of the snapshot tree
+ * the durable store (W-d) persists.
+ *
+ * @remarks
+ * Pure JSON DATA (no class instances, no functions). `result` is the task's
+ * {@link TaskResult} when it has settled with an outcome, else `undefined`.
+ * `metadata` is the open consumer bag carried from the task's {@link TaskInput}.
+ */
+export declare interface TaskSnapshot {
+    readonly id: string;
+    readonly name: string;
+    readonly description?: string;
+    readonly status: TaskStatus;
+    readonly result?: TaskResult;
+    readonly metadata: Readonly<Record<string, unknown>>;
+}
+
+/**
+ * The lifecycle status of a task — `pending` before it runs, `running` while in
+ * flight, then one of the terminal states: `completed` (a success), `failed` (a
+ * genuine error), `skipped` (intentionally not executed, AGENTS §10 `skip`), or
+ * `stopped` (permanently ended, AGENTS §10 `stop`).
+ *
+ * @remarks
+ * A semantic tier of the shared {@link LifecycleStatus} vocabulary. Uses `running` /
+ * `failed` (the project vocabulary), and keeps `skipped` and `stopped` DISTINCT — a
+ * skip is "deliberately not run", a stop is "ended early". The terminal members are
+ * exactly those for which a {@link TaskResult} is meaningful: `completed` / `failed`
+ * box a {@link Result}, while `skipped` / `stopped` are terminal WITHOUT a boxed
+ * outcome. See {@link import('./helpers.js').isTerminalStatus}.
+ */
+export declare type TaskStatus = LifecycleStatus;
+
+/** The discriminant literal of a {@link TaskForm} — the execution mechanism axis. */
+export declare type TaskVia = TaskForm['via'];
+
+/**
+ * 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.
+ */
+export declare const TERMINAL_TASK_STATUSES: readonly TaskStatus[];
+
+/**
+ * One unit's settled outcome — a discriminated union so a value of `undefined` is still
+ * a success (`{ ok: true, value: undefined }`), never mistaken for a failure or an
+ * absent result.
+ *
+ * @remarks
+ * The runner records each settled unit's outcome through this shape: a success boxes the
+ * resolved `value` (presence tracked by the union tag, so `undefined` is a valid result),
+ * a failure carries the `error` (always `unknown`). The FIRST failure is fail-fast.
+ *
+ * @typeParam TResult - The value a unit resolves
+ */
+export declare type UnitOutcome<TResult> = {
+    readonly ok: true;
+    readonly value: TResult;
+} | {
+    readonly ok: false;
+    readonly error: unknown;
+};
+
+/**
+ * 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}.
+ */
+export declare class Workflow implements WorkflowInterface {
+    #private;
+    constructor(snapshot: WorkflowSnapshot, options?: WorkflowOptions);
+    get emitter(): EmitterInterface<WorkflowEventMap>;
+    get id(): string;
+    get name(): string;
+    get description(): string | undefined;
+    get context(): WorkflowContext;
+    get bail(): boolean;
+    get status(): WorkflowStatus;
+    get phases(): PhaseManagerInterface;
+    phase(id: string): PhaseInterface | undefined;
+    results(): readonly TaskResult[];
+    skip(): void;
+    stop(): void;
+    complete(): void;
+    snapshot(): WorkflowSnapshot;
+}
+
+/** Every {@link WorkflowStatus} value, frozen — the lifecycle vocabulary of a workflow. */
+export declare const WORKFLOW_STATUSES: readonly WorkflowStatus[];
+
+/**
+ * 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).
+ */
+export declare const WORKFLOW_TOOL_DESCRIPTION: string;
+
+/**
+ * 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.
+ */
+export declare const WORKFLOW_TOOL_FLAT_EXAMPLE: WorkflowSteps;
+
+/**
+ * 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.
+ */
+export declare const WORKFLOW_TOOL_NAME = "workflow";
+
+/**
+ * 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.
+ */
+export declare const WORKFLOW_TOOL_NESTED_EXAMPLE: WorkflowDefinition;
+
+/**
+ * The `agent`-task behavior resolver (W-c2) — resolves a registered agent BY NAME to a
+ * live {@link AgentInterface} the runner runs as a subagent.
+ *
+ * @remarks
+ * The `agent` analogue of the {@link WorkflowFunctions} registry / the
+ * {@link ToolManagerInterface} the other two forms dispatch through: the runner resolves
+ * an `agent`-form {@link TaskForm}'s `name` here. A name absent from the resolver is the
+ * no-handler case — the task AUTO-COMPLETES (the ROADMAP rule), exactly like an
+ * unregistered `function` / `tool`.
+ *
+ * **Resolve a FRESH agent per call.** A phase's tasks run CONCURRENTLY, so two `agent`
+ * tasks naming the same agent are resolved concurrently — and the runner BINDS a
+ * depth/cycle-aware workflow tool onto each resolved agent's `context.tools` (the
+ * propagation seam — see {@link WorkflowToolOptions}). An implementation that returns the
+ * SAME instance for both would have them race on that mutation, so it must mint a fresh
+ * agent each call (exactly as `AgentRegistry.build` does). A function resolver
+ * (`(name) => …`) is the minimal shape; the agents module's `AgentRegistry` is not a
+ * direct fit (its `build` rehydrates from a serializable `AgentJobInput`, not a bare
+ * name), so a small adapter `(name) => registry.build({ provider, ... })` bridges it.
+ *
+ * @param name - The agent's registry key (the `agent`-form's `name`)
+ * @returns The resolved live agent, or `undefined` when the name is unregistered
+ */
+export declare type WorkflowAgents = (name: string) => AgentInterface | undefined;
+
+/**
+ * The ambient context of a workflow — the identity every level inherits.
+ *
+ * @remarks
+ * The root of the context chain: a {@link PhaseContext} and {@link TaskContext}
+ * both extend it, so a task at the leaf still sees the workflow's `id` / `name`.
+ * `description` is optional (it mirrors the optional definition field).
+ */
+export declare interface WorkflowContext {
+    readonly id: string;
+    readonly name: string;
+    readonly description?: string;
+}
+
+/**
+ * The serializable definition of a whole workflow — its identity, its ordered
+ * phases, and the `bail` failure policy.
+ *
+ * @remarks
+ * Pure JSON DATA — the root a UI/LLM authors and the contract validates. `phases`
+ * are the workflow's phases, which run SEQUENTIALLY. `bail` is the failure policy
+ * (a boolean behavioral toggle, AGENTS §4.4): `false` (the default) is GRACEFUL —
+ * a failed leaf task is recorded as data and the workflow still completes; `true`
+ * is a database-transaction HALT — a single failed task propagates `failed` to the
+ * whole workflow. See {@link import('./helpers.js').deriveWorkflowStatus}.
+ */
+export declare interface WorkflowDefinition {
+    readonly id: string;
+    readonly name: string;
+    readonly description?: string;
+    readonly phases: readonly PhaseDefinition[];
+    /** Failure policy: `false` (default) continues gracefully, `true` halts on the first failure. */
+    readonly bail?: boolean;
+}
+
+/**
+ * A draft workflow — a {@link WorkflowDefinition} with OPTIONAL `id` / `name` at all
+ * three levels (workflow / phase / task).
+ *
+ * @remarks
+ * The lenient authoring form `createWorkflowDraftContract` validates and
+ * {@link import('./helpers.js').completeDraft} completes into a strict
+ * {@link WorkflowDefinition}. `run` stays required; the `bail` policy carries over.
+ */
+export declare interface WorkflowDraft {
+    readonly id?: string;
+    readonly name?: string;
+    readonly description?: string;
+    readonly phases: readonly PhaseDraft[];
+    /** Failure policy: `false` (default) continues gracefully, `true` halts on the first failure. */
+    readonly bail?: boolean;
+}
+
+/**
+ * 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.
+ */
+export declare const workflowDraftShape: ObjectShape<{
+    id: OptionalShape<StringShape>;
+    name: OptionalShape<StringShape>;
+    description: OptionalShape<StringShape>;
+    phases: ArrayShape<ObjectShape<{
+        id: OptionalShape<StringShape>;
+        name: OptionalShape<StringShape>;
+        description: OptionalShape<StringShape>;
+        tasks: ArrayShape<ObjectShape<{
+            id: OptionalShape<StringShape>;
+            name: OptionalShape<StringShape>;
+            description: OptionalShape<StringShape>;
+            run: UnionShape<[ ObjectShape<{
+                via: LiteralShape<readonly ["function"]>;
+                name: StringShape;
+            }>, ObjectShape<{
+                via: LiteralShape<readonly ["tool"]>;
+                name: StringShape;
+            }>, ObjectShape<{
+                via: LiteralShape<readonly ["agent"]>;
+                name: StringShape;
+            }>]>;
+            retries: OptionalShape<NumberShape>;
+            timeout: OptionalShape<NumberShape>;
+        }>>;
+        concurrency: OptionalShape<NumberShape>;
+        bail: OptionalShape<LiteralShape<readonly [true, false]>>;
+    }>>;
+    bail: OptionalShape<LiteralShape<readonly [true, false]>>;
+}>;
+
+/**
+ * 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).
+ */
+export declare class WorkflowError extends Error {
+    readonly code: WorkflowErrorCode;
+    readonly context?: Readonly<Record<string, unknown>>;
+    constructor(code: WorkflowErrorCode, message: string, context?: Readonly<Record<string, unknown>>);
+}
+
+/**
+ * The machine-readable code of a {@link import('./errors.js').WorkflowError} — the
+ * fault the live W-b state machine raises (AGENTS §12).
+ *
+ * @remarks
+ * - `TRANSITION` — an illegal state-machine transition (e.g. `start`ing a task that is
+ *   not `pending`, or `complete`/`fail`ing one that is not `running`); the guard names
+ *   the offending current status + requested transition in the error `context`.
+ * - `RESTORE` — a {@link import('./factories.js').restoreWorkflow} given a structurally
+ *   invalid {@link WorkflowSnapshot} (a status outside the lifecycle vocabulary).
+ * - `DEPTH` — a nested-workflow dispatch (W-c2) that the runner's depth / cycle guard
+ *   rejected: running it would push the nested-workflow chain past
+ *   {@link import('./constants.js').MAX_WORKFLOW_DEPTH}, OR its target agent (or a
+ *   workflow it would author) is already an ancestor of the current run (a re-entry
+ *   cycle). Raised on BOTH seams of the W-c2 recursion — an `agent`-task dispatch
+ *   (`fail`ed with this code; it never runs) AND the
+ *   {@link import('./factories.js').createWorkflowTool} handler (thrown, then ISOLATED
+ *   by the `@orkestrel/agent` package's `ToolManager` into the tool
+ *   result's `error`). The error `context` names the offending agent / workflow id + the depth.
+ * - `TOOL` — the {@link import('./factories.js').createWorkflowTool} handler was handed
+ *   a MALFORMED / over-constraint authored args blob (e.g. an empty `id`, `concurrency: 0`)
+ *   that the contract rejected, so no workflow ran. The handler THROWS it (rather than
+ *   returning a failure result), and the `@orkestrel/agent` package's `ToolManager`
+ *   ISOLATES the throw into the canonical tool result's top-level `error` (AGENTS §14 — the
+ *   universal tool-handler contract); the error `context` names the wrapped workflow id.
+ */
+export declare type WorkflowErrorCode = 'TRANSITION' | 'RESTORE' | 'DEPTH' | 'TOOL';
+
+/**
+ * The push observation surface (AGENTS §13) of the workflow entity (W-b) — the
+ * lifecycle moments a fire-and-forget observer subscribes to via
+ * `workflow.emitter.on`.
+ *
+ * @remarks
+ * Present-tense events with arg tuples. `start` fires when the workflow begins;
+ * `complete` when every phase settled successfully; `fail` when a phase failed
+ * under `bail` (carrying the failing {@link TaskResult}); `stop` when the workflow
+ * was permanently ended. A throwing listener never reaches the domain surface — the
+ * emitter isolates it and routes it to its OWN `error` handler (the `error` option,
+ * AGENTS §13). Declared as a `type` alias (not `interface extends EventMap`, AGENTS
+ * §4.5) so the type-literal satisfies `EventMap` structurally.
+ */
+export declare type WorkflowEventMap = {
+    /** The workflow began — its `id`. */
+    readonly start: readonly [id: string];
+    /** Every phase settled successfully. */
+    readonly complete: readonly [];
+    /** A phase failed under `bail` — the failing task's result. */
+    readonly fail: readonly [result: TaskResult];
+    /** The workflow was permanently stopped. */
+    readonly stop: readonly [];
+};
+
+/**
+ * A registered workflow function — the behavior a `function`-form
+ * {@link TaskDefinition} runs, resolved BY NAME through the {@link WorkflowFunctions}
+ * registry (AGENTS §4.5 — a `Handler` function type the framework invokes).
+ *
+ * @remarks
+ * Receives a {@link TaskControllerInterface} — the running task's folded `signal`, its
+ * `input` (the task's `metadata` bag), its lineage {@link TaskContext}, and read-UP access
+ * to earlier phases' {@link TaskResult}s. A returned value becomes the task's
+ * {@link import('@orkestrel/contract').Success} ({@link TaskInterface.complete}); a throw / rejection
+ * becomes its {@link import('@orkestrel/contract').Failure} ({@link TaskInterface.fail}). Long work
+ * should honour `controller.signal` (a workflow-level abort / timeout / budget, or — under
+ * `bail: true` — a sibling's failure, fires it) so a cancel stops it promptly.
+ */
+export declare type WorkflowFunction = (controller: TaskControllerInterface) => Promise<unknown> | unknown;
+
+/**
+ * The `function`-task behavior registry — workflow function names mapped to their
+ * {@link WorkflowFunction} handlers.
+ *
+ * @remarks
+ * The runner resolves a `function`-form {@link TaskForm}'s `name` here. A name absent
+ * from the registry is the no-handler case — the task AUTO-COMPLETES (the ROADMAP rule),
+ * exactly like an unsupported form. A plain record (not a manager) — the registry is a
+ * lookup, with no lifecycle of its own.
+ */
+export declare type WorkflowFunctions = Readonly<Record<string, WorkflowFunction>>;
+
+/** Initial {@link WorkflowEventMap} listeners — the reserved `on` option (AGENTS §8). */
+export declare type WorkflowHooks = EmitterHooks<WorkflowEventMap>;
+
+/** The minimal data to create a workflow context — a partial {@link WorkflowContext}. */
+export declare type WorkflowInput = Partial<WorkflowContext>;
+
+/**
+ * The live derived state machine (W-b) for a whole {@link WorkflowDefinition} — the
+ * observable (AGENTS §13) root whose {@link WorkflowStatus} is DERIVED from its phases
+ * under the `bail` policy and recomputed reactively as the cascade propagates up.
+ *
+ * @remarks
+ * - **Derived status.** `status` is computed via
+ *   {@link import('./helpers.js').deriveWorkflowStatus} over the live phases' statuses,
+ *   feeding the definition's `bail`, UNLESS an override is in force. It recomputes when a
+ *   phase's status changes (the top of the cascade); a CHANGE emits — `fail` carries the
+ *   failing {@link TaskResult} (under `bail: true`).
+ * - **Children.** `phases` is the lean {@link PhaseManagerInterface} (AGENTS §9);
+ *   `phase(id)` / `phases().phases()` read in positional order. `results` collects ALL
+ *   tasks' results across every phase (the workflow tier of the result tree).
+ * - **Override.** `skip` / `stop` (AGENTS §10) FORCE the workflow's status; the override
+ *   survives a snapshot.
+ * - **Snapshot.** `snapshot()` serializes the whole live tree to a {@link WorkflowSnapshot}
+ *   (pure JSON — structure + each node's status + recorded results + positional order);
+ *   {@link 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).
+ */
+export declare interface WorkflowInterface {
+    readonly emitter: EmitterInterface<WorkflowEventMap>;
+    readonly id: string;
+    readonly name: string;
+    readonly description?: string;
+    readonly context: WorkflowContext;
+    readonly bail: boolean;
+    readonly status: WorkflowStatus;
+    readonly phases: PhaseManagerInterface;
+    /** Look up one live phase by its `id`. */
+    phase(id: string): PhaseInterface | undefined;
+    /** Every settled task's result across all phases, in positional order — the workflow tier of the result tree. */
+    results(): readonly TaskResult[];
+    skip(): void;
+    stop(): void;
+    complete(): void;
+    snapshot(): WorkflowSnapshot;
+}
+
+/**
+ * The runtime options for a {@link WorkflowInterface} — the construction bag the
+ * live derived workflow state machine (W-b) carries, the root {@link createWorkflow}
+ * accepts.
+ *
+ * @remarks
+ * The reserved `on` (AGENTS §8) wires initial {@link WorkflowEventMap} listeners.
+ * `phases` keys per-phase {@link PhaseOptions} by phase `id`, so the whole tree's
+ * initial listeners + per-task metadata can be supplied in one nested bag (the
+ * AGENTS §8 "entity is the key" grouping), each leaf reachable by its lineage of ids.
+ */
+export declare interface WorkflowOptions {
+    readonly on?: WorkflowHooks;
+    /**
+     * The failure policy (AGENTS §4.4) the live tree applies — the same boolean toggle as
+     * {@link WorkflowDefinition.bail}, fed to {@link import('./helpers.js').deriveWorkflowStatus}.
+     * {@link import('./factories.js').createWorkflow} defaults it to the definition's `bail`. A
+     * {@link WorkflowSnapshot} PERSISTS the policy, so {@link import('./factories.js').restoreWorkflow}
+     * takes it from the snapshot (the source of truth); an explicit `options.bail` on restore still
+     * wins when supplied. Omitted on a fresh build ⇒ the graceful {@link import('./constants.js').DEFAULT_BAIL}.
+     */
+    readonly bail?: boolean;
+    /** The emitter's listener-error handler (AGENTS §13) — a listener throw routes here, not to a domain event. */
+    readonly error?: EmitterErrorHandler;
+    /** Per-phase {@link PhaseOptions}, keyed by the phase's `id`. */
+    readonly phases?: Readonly<Record<string, PhaseOptions>>;
+}
+
+/**
+ * The structured outcome of a {@link WorkflowRunnerInterface.execute} run — the settled
+ * live workflow, its final status, and the flattened result tree.
+ *
+ * @remarks
+ * Boxes the settled {@link WorkflowInterface} itself (so a caller can navigate the whole
+ * live tree — every phase / task's final `status`, its recorded {@link TaskResult}, its
+ * lineage) ALONGSIDE the two read-throughs the run produced: `status` is the workflow's
+ * derived {@link WorkflowStatus} at settle (`completed` under graceful mode even with
+ * failed leaves; `failed` under `bail: true`; `stopped` on a workflow-level abort /
+ * timeout / budget), and `results` is the workflow-tier {@link TaskResult} list (every
+ * settled task across all phases, in positional order — the same array `workflow.results()`
+ * yields). Returning the live `workflow` (not just a snapshot) keeps the entity tree the
+ * source of truth — the runner adds only the convenience `status` / `results` projections.
+ */
+export declare interface WorkflowResult {
+    readonly workflow: WorkflowInterface;
+    readonly status: WorkflowStatus;
+    readonly results: readonly TaskResult[];
+}
+
+/**
+ * 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.
+ */
+export declare class WorkflowRunner implements WorkflowRunnerInterface {
+    #private;
+    constructor(functions: WorkflowFunctions, tools: ToolManagerInterface | undefined, agents: WorkflowAgents | undefined, scheduler: SchedulerInterface, workflowTool: WorkflowToolBinder | undefined);
+    execute(definition: WorkflowDefinition, options?: WorkflowRunOptions): Promise<WorkflowResult>;
+}
+
+/**
+ * A thin orchestrator that EXECUTES a live {@link WorkflowInterface} tree by composing the
+ * shipped substrate — phases sequential, tasks concurrent, dispatched by name under the
+ * `bail` policy.
+ *
+ * @remarks
+ * `execute(definition, options?)` BUILDS the live W-b entity tree from the definition itself
+ * (via {@link import('./factories.js').createWorkflow}) and drives it to a terminal
+ * {@link WorkflowResult} — phases SEQUENTIALLY and, within each phase, the tasks CONCURRENTLY
+ * through ONE substrate {@link RunnerInterface} (concurrency =
+ * the phase's {@link PhaseDefinition.concurrency}). The definition is the SINGLE source of
+ * truth: the runner owns both the declarative state (the live tree it constructs) and the
+ * EXECUTION-ONLY fields the snapshot deliberately dropped — each task's {@link TaskForm}
+ * (`run`) and each phase's `concurrency` (so there is no separately-supplied workflow to drift
+ * from the definition). The freshly-built live tree is returned in {@link WorkflowResult.workflow}.
+ * Each task is dispatched by its {@link TaskForm} — a `function` through the
+ * {@link WorkflowFunctions} registry, a `tool` through the {@link ToolManagerInterface}; a
+ * task whose handler is not found AUTO-COMPLETES. The runner DRIVES the live entity (`start`
+ * → `complete` / `fail`), never re-implementing status. The `bail` policy maps onto the
+ * substrate's fail-fast (`bail: true` — the first failure aborts in-flight siblings and skips
+ * the rest) vs settle-all (`bail: false` — failures are recorded and the run finishes). The
+ * {@link WorkflowOptions} half of the options is forwarded to `createWorkflow` (initial
+ * listeners, a `bail` override, per-node options); the Abort / Timeout / Budget bounds fold
+ * per run via `AbortSignal.any`, halting the run and `stop`ping the workflow.
+ */
+export declare interface WorkflowRunnerInterface {
+    /**
+     * Execute a workflow definition to completion — BUILD its live tree, run the phases
+     * sequentially with each phase's tasks concurrent — resolving its terminal
+     * {@link WorkflowResult} (whose `workflow` is the freshly-built live tree).
+     *
+     * @remarks
+     * One-shot. The runner BUILDS the live tree from `definition` internally (one source of
+     * truth — the per-task {@link TaskForm} (`run`) and per-phase `concurrency` come from the
+     * same definition the tree is constructed from, so the executed tree can never drift from
+     * the form/throttle metadata). The {@link WorkflowOptions} part of `options` (initial `on`
+     * listeners, a `bail` override, the per-node `phases` bag) is forwarded to the build.
+     * Under `bail: false` (graceful) every task settles (a failure is recorded on its
+     * {@link TaskInterface}) and the workflow reaches `completed`; under `bail: true` (halt)
+     * the first failure aborts the in-flight sibling tasks AND `skip`s the remaining tasks /
+     * phases, settling the workflow `failed`. A {@link WorkflowRunOptions} abort / timeout /
+     * budget fires every in-flight task's signal and `stop`s the run. `execute` resolves
+     * (never rejects) on a cancel — the partial outcome is read from the returned
+     * {@link WorkflowResult} (its `workflow` / `status` / `results`). A run-level cancel
+     * (abort / timeout / budget) that fires on the SAME tick as a genuine task failure resolves
+     * the run as `stopped` — the cancel supersedes the same-tick failure, and that task's error
+     * is not recorded.
+     *
+     * @param definition - The {@link WorkflowDefinition} to build the live tree from and drive
+     * @param options - The construction options ({@link WorkflowOptions}: `on` / `bail` /
+     *   `phases`) PLUS the per-run bounds (`signal` / `timeout` / `budget`)
+     * @returns The run's terminal {@link WorkflowResult} (its `workflow` is the built tree)
+     */
+    execute(definition: WorkflowDefinition, options?: WorkflowRunOptions): Promise<WorkflowResult>;
+}
+
+/**
+ * The options for `createWorkflowRunner` — the behavior registries the runner dispatches
+ * a task BY NAME through, plus the optional pacing scheduler.
+ *
+ * @remarks
+ * - `functions` — the {@link WorkflowFunctions} registry for `function`-form tasks. A name
+ *   absent here is the no-handler case (the task auto-completes). Omitted ⇒ an empty
+ *   registry (every `function` task auto-completes).
+ * - `tools` — the {@link ToolManagerInterface} (the shipped tool registry) a `tool`-form
+ *   task is dispatched through: the runner resolves `run.name` via `tools.tool(name)` and
+ *   invokes it with the task's input. An unregistered tool name is the no-handler case
+ *   (auto-completes). Omitted ⇒ every `tool` task auto-completes.
+ * - `agents` — the {@link WorkflowAgents} resolver (W-c2) an `agent`-form task is dispatched
+ *   through: the runner resolves `run.name` to a live
+ *   {@link AgentInterface}, BINDS a depth/cycle-aware workflow
+ *   tool onto its `context.tools` (the propagation seam), folds the task's cancellation into
+ *   the agent run, and drives it (success → `complete`, throw → `fail`), all behind the
+ *   depth + cycle guard. An unregistered agent name is the no-handler case (auto-completes).
+ *   Omitted ⇒ every `agent` task auto-completes.
+ * - `scheduler` — the {@link SchedulerInterface} that paces the tree (a cooperative
+ *   `yield` between phases). Omitted ⇒ the shipped cross-environment default
+ *   ({@link createScheduler}).
+ *
+ * The reserved `on` key (AGENTS §8) is intentionally ABSENT: the runner is THIN and drives
+ * the W-b entities' OWN emitters (subscribe via `workflow.emitter` / `phase.emitter` /
+ * `task.emitter`), so it owns no event map of its own — there is nothing for an `on` to
+ * wire. A future runner-level emitter would introduce its own `EmitterHooks` here.
+ */
+export declare interface WorkflowRunnerOptions {
+    readonly functions?: WorkflowFunctions;
+    readonly tools?: ToolManagerInterface;
+    /** The {@link WorkflowAgents} resolver for `agent`-form tasks (W-c2); omitted ⇒ every `agent` task auto-completes. */
+    readonly agents?: WorkflowAgents;
+    readonly scheduler?: SchedulerInterface;
+}
+
+/**
+ * The options for one {@link WorkflowRunnerInterface.execute} call — the live tree's
+ * CONSTRUCTION options ({@link WorkflowOptions}) PLUS the per-run BOUNDS (an external abort,
+ * a deadline, and a cost ceiling), each bound folded into every task's cancellation.
+ *
+ * @remarks
+ * `execute` is single-source: it BUILDS the live tree from the definition internally (via
+ * {@link import('./factories.js').createWorkflow}), so these options carry BOTH halves of
+ * that one call —
+ * - the **construction** half is {@link WorkflowOptions} (`on` initial listeners, the `bail`
+ *   override, the per-node `phases` bag); `execute` forwards it straight to `createWorkflow`,
+ *   so construction-time emitter listeners, a `bail` override, and per-node options all apply
+ *   to the tree it builds (`createWorkflow` resolves `bail` as `options.bail ?? definition.bail
+ *   ?? DEFAULT_BAIL`); and
+ * - the **run-control** half is the three bounds below, used only for the run-level fold.
+ *
+ * The three bounds compose via `AbortSignal.any` (exactly as the agent runtime folds its
+ * own): a fire of ANY of them cancels every in-flight task (its
+ * {@link TaskControllerInterface.signal} fires) and HALTS the run — the remaining tasks
+ * and phases are `skip`ped and the workflow settles `stopped`.
+ * - `signal` — an external cancellation (a caller `AbortController`).
+ * - `timeout` — a whole-run deadline in milliseconds. A non-positive value (`0` or negative)
+ *   ⇒ NO deadline (the runner arms an `@orkestrel/timeout` `TimeoutInterface`
+ *   only when `timeout > 0`).
+ * - `budget` — a whole-run cost ceiling (a {@link BudgetInterface} over {@link TokenUsage}
+ *   — its `signal` fires when a task-reported usage crosses `max`); the runner folds its
+ *   `signal` and `start`s it. (A `max: 0` budget is exhausted from its first `start`, so it
+ *   cancels the run at entry — a DIFFERENT primitive from the `timeout: 0` "no deadline" case.)
+ *
+ * The last two are the W-c2 DEPTH / CYCLE bookkeeping — the run's position in a nested
+ * workflow→agent→workflow chain, threaded across the
+ * `execute → agent-task → createWorkflowTool → nested execute` boundary so the guard can
+ * bound recursion. A TOP-LEVEL `execute` omits both (depth `0`, empty ancestry); only the
+ * runner-bound workflow tool ({@link import('./factories.js').createWorkflowTool}) supplies
+ * them, incrementing the depth and extending the ancestry for each nested run.
+ * - `depth` — the run's nesting depth (default `0`). An `agent` task is REJECTED (a typed
+ *   `DEPTH` `task.fail`) when running it would push the chain past
+ *   {@link import('./constants.js').MAX_WORKFLOW_DEPTH}.
+ * - `ancestry` — the identifiers of the workflows + agents already in this run chain
+ *   (e.g. `workflow:<id>` / `agent:<name>`). An `agent` task whose target agent — or the
+ *   workflow it would author — is already present is a CYCLE and is likewise rejected.
+ *   Default empty.
+ */
+export declare type WorkflowRunOptions = WorkflowOptions & {
+    readonly signal?: AbortSignal;
+    readonly timeout?: number;
+    readonly budget?: BudgetInterface<TokenUsage>;
+    /** The run's nesting depth (W-c2); default `0`. Threaded by the bound workflow tool, never by a top-level caller. */
+    readonly depth?: number;
+    /** The workflow / agent identifiers already in this run chain (W-c2 cycle guard); default empty. */
+    readonly ancestry?: readonly string[];
+};
+
+/**
+ * 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).
+ */
+export declare const workflowShape: ObjectShape<{
+    id: StringShape;
+    name: StringShape;
+    description: OptionalShape<StringShape>;
+    phases: ArrayShape<ObjectShape<{
+        id: StringShape;
+        name: StringShape;
+        description: OptionalShape<StringShape>;
+        tasks: ArrayShape<ObjectShape<{
+            id: StringShape;
+            name: StringShape;
+            description: OptionalShape<StringShape>;
+            run: UnionShape<[ ObjectShape<{
+                via: LiteralShape<readonly ["function"]>;
+                name: StringShape;
+            }>, ObjectShape<{
+                via: LiteralShape<readonly ["tool"]>;
+                name: StringShape;
+            }>, ObjectShape<{
+                via: LiteralShape<readonly ["agent"]>;
+                name: StringShape;
+            }>]>;
+            retries: OptionalShape<NumberShape>;
+            timeout: OptionalShape<NumberShape>;
+        }>>;
+        concurrency: OptionalShape<NumberShape>;
+        bail: OptionalShape<LiteralShape<readonly [true, false]>>;
+    }>>;
+    bail: OptionalShape<LiteralShape<readonly [true, false]>>;
+}>;
+
+/**
+ * A JSON-serializable snapshot of a whole workflow's state — its identity, status, its
+ * forced override (if any), the `bail` policy it ran under, its nested phase snapshots,
+ * and creation / update timestamps.
+ *
+ * @remarks
+ * Pure JSON DATA — the COMPLETE, SELF-CONTAINED payload the durable store (W-d) persists,
+ * designed in full at W-a so its shape is fixed from the start. It can be written to disk,
+ * sent to a prompt companion, loaded across conversations, or reviewed by an agent. Because
+ * it is self-contained, it carries the policy it ran under: `bail` (AGENTS §4.4) is the
+ * failure policy, so {@link import('./factories.js').restoreWorkflow} re-derives status
+ * IDENTICALLY without a silent default. `status` is the EFFECTIVE status (override-or-derived)
+ * at snapshot time; `override` is the forced status of a whole-workflow `skip` / `stop`,
+ * PRESENT only when one is in force (so a restore reinstates it DIRECTLY rather than guessing
+ * from a status divergence). `phases` are the workflow's {@link PhaseSnapshot}s in order;
+ * `created` / `updated` are ms since epoch.
+ */
+export declare interface WorkflowSnapshot {
+    readonly id: string;
+    readonly name: string;
+    readonly description?: string;
+    readonly status: WorkflowStatus;
+    /** The forced status of a whole-workflow `skip` / `stop`; present only when an override is in force. */
+    readonly override?: WorkflowStatus;
+    /** The failure policy the workflow ran under (AGENTS §4.4) — persisted so a restore re-derives identically. */
+    readonly bail: boolean;
+    readonly phases: readonly PhaseSnapshot[];
+    readonly created: number;
+    readonly updated: number;
+}
+
+/**
+ * One row of the table a {@link import('./stores/DatabaseWorkflowStore.js').DatabaseWorkflowStore}
+ * persists — a workflow `id` plus its {@link WorkflowSnapshot} held as ONE OPAQUE JSON column.
+ *
+ * @remarks
+ * The Database twin of {@link WorkflowStoreInterface} stores the snapshot whole (the `snapshot`
+ * column is a `rawShape`, an opaque JSON blob — exactly as
+ * `@orkestrel/queue`'s `StoredEntry` stores a queue entry's `input`), so the row
+ * type stays FLAT and the deeply-nested snapshot shape (workflow → phases → tasks → results) never
+ * forces the contract to `Infer` it — sidestepping a TS2589 instantiation-depth blow-up. The column
+ * therefore reads back as the broad `unknown`; the store narrows it to a {@link WorkflowSnapshot} on
+ * `get` ({@link import('./helpers.js').isWorkflowSnapshot}, the AGENTS §14 boundary narrow). `id`
+ * mirrors {@link WorkflowSnapshot.id} (the primary key), so a `set` writes `{ id: snapshot.id, snapshot }`.
+ */
+export declare interface WorkflowSnapshotRow {
+    readonly id: string;
+    /** The whole {@link WorkflowSnapshot} as one opaque JSON blob — read back as `unknown`, narrowed on `get`. */
+    readonly snapshot: unknown;
+}
+
+/**
+ * The lifecycle status of a workflow — the same vocabulary as {@link TaskStatus},
+ * derived from its phases' statuses under the `bail` policy.
+ *
+ * @remarks
+ * A semantic tier of the shared {@link LifecycleStatus} vocabulary. `failed` is
+ * reachable ONLY under `bail: true` (a single failed task halts the whole workflow);
+ * under `bail: false` a workflow `completed`s even with failed leaf tasks. See
+ * {@link import('./helpers.js').deriveWorkflowStatus}.
+ */
+export declare type WorkflowStatus = LifecycleStatus;
+
+/**
+ * One flat step — `{ name, via? }` — the building block of a {@link WorkflowSteps} blob.
+ *
+ * @remarks
+ * `name` is the REGISTERED behavior name the step runs (it becomes the task's `run.name`,
+ * NOT a human label). `via` is the optional execution mechanism — `'function'` (the
+ * default when omitted), `'tool'`, or `'agent'`.
+ */
+export declare interface WorkflowStep {
+    /** The registered behavior name this step runs (becomes the task's `run.name`). */
+    readonly name: string;
+    /** How to run it — `'function'` (default), `'tool'`, or `'agent'`. */
+    readonly via?: TaskVia;
+}
+
+/**
+ * The FLAT authoring blob `createWorkflowTool` advertises — `{ name?, steps }` — the
+ * simplest surface a small model can fill.
+ *
+ * @remarks
+ * Each {@link WorkflowStep} becomes a one-task phase, in order
+ * ({@link import('./helpers.js').expandSteps}); `name` is the optional workflow name
+ * (defaulted when omitted). The expanded tree is validated against the STRICT
+ * {@link import('./factories.js').createWorkflowContract} gate before running.
+ */
+export declare interface WorkflowSteps {
+    readonly name?: string;
+    readonly steps: readonly WorkflowStep[];
+}
+
+/**
+ * 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.
+ */
+export declare const workflowStepsShape: ObjectShape<{
+    name: OptionalShape<StringShape>;
+    steps: ArrayShape<ObjectShape<{
+        name: StringShape;
+        via: OptionalShape<LiteralShape<readonly ["function", "tool", "agent"]>>;
+    }>>;
+}>;
+
+/**
+ * The durable persistence seam for a {@link WorkflowSnapshot} — three async primitives
+ * (`get` / `set` / `delete`) keyed by a workflow id, the snapshot analogue of
+ * the server package's `SessionStoreInterface` (and the
+ * {@link QueueStoreInterface} driver-swap pattern).
+ *
+ * @remarks
+ * The store persists the W-a {@link WorkflowSnapshot} — the COMPLETE, self-contained,
+ * pure-JSON run state — so a JSON / SQLite / IndexedDB backend swaps in WITHOUT touching the
+ * runner or the entity tree: the in-memory default
+ * {@link import('./stores/MemoryWorkflowStore.js').MemoryWorkflowStore} and its driver-pluggable
+ * twin {@link import('./stores/DatabaseWorkflowStore.js').DatabaseWorkflowStore} (the snapshot as
+ * one opaque JSON column) share THIS one interface. Restore is NOT a store concern — a caller reads
+ * a snapshot back and rebuilds the live tree with the shipped {@link import('./factories.js').restoreWorkflow}.
+ *
+ * Every primitive is async (a `Promise`), so a durable backend (a database round-trip) fits the
+ * same shape as the memory one. The snapshot carries its OWN id, so `set` takes no separate id
+ * param (mirroring {@link QueueStoreInterface.save} / the server package's
+ * `SessionStoreInterface.set`, which key off the value's own
+ * `id`). UNLIKE a session store there is NO idle-TTL / eviction — a persisted workflow run-state
+ * lives until an explicit `delete`, never silently expiring (it is durable orchestration state,
+ * not an ephemeral session). It is concrete over {@link WorkflowSnapshot} — no generic parameter
+ * (AGENTS §21 minimal-interface), since the snapshot is the ONE payload a workflow store persists.
+ */
+export declare interface WorkflowStoreInterface {
+    /**
+     * Resolve the persisted snapshot for `id`, or `undefined` if none is stored.
+     *
+     * @param id - The workflow id to resolve (a {@link WorkflowSnapshot.id})
+     * @returns The persisted snapshot, or `undefined` if absent
+     */
+    get(id: string): Promise<WorkflowSnapshot | undefined>;
+    /**
+     * Insert or replace a snapshot under its own `snapshot.id` (no separate id param —
+     * mirroring {@link QueueStoreInterface.save}).
+     *
+     * @param snapshot - The snapshot to store (keyed by its `id`)
+     */
+    set(snapshot: WorkflowSnapshot): Promise<void>;
+    /**
+     * Drop a snapshot by id; an absent id is a no-op (no throw).
+     *
+     * @param id - The workflow id to drop
+     */
+    delete(id: string): Promise<void>;
+}
+
+/**
+ * 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>`)
+ */
+export declare function workflowTag(id: string): string;
+
+/**
+ * The workflow-tool binder — the signature of {@link import('./factories.js').createWorkflowTool},
+ * threaded into the {@link WorkflowRunnerInterface} at construction (W-c2) so the runner can BIND a
+ * depth/cycle-aware workflow tool onto a dispatched subagent.
+ *
+ * @remarks
+ * The runner receives a REFERENCE to `createWorkflowTool` rather than importing it, because
+ * `createWorkflowTool` lives in `factories.ts` which imports the runner CLASS (the
+ * factories→classes direction); importing the factory back into the class would be a cycle. The
+ * factory (which legitimately owns `createWorkflowContract`) is passed as a value at construction,
+ * and the runner invokes it with `this` as the `runner` argument — keeping the cycle-free seam an
+ * explicit, typed contract rather than a hidden dependency.
+ *
+ * @param definition - The workflow the bound tool runs when called with no authored args
+ * @param runner - The runner that executes the (nested) workflow (the runner passes `this`)
+ * @param options - The depth + ancestry the nested workflow runs under (see {@link WorkflowToolOptions})
+ * @returns The bound {@link ToolInterface}
+ */
+export declare type WorkflowToolBinder = (definition: WorkflowDefinition, runner: WorkflowRunnerInterface, options?: WorkflowToolOptions) => ToolInterface;
+
+/**
+ * Options for {@link import('./factories.js').createWorkflowTool} — the depth + ancestry the
+ * wrapped {@link WorkflowDefinition} runs the NESTED workflow at when an LLM invokes the tool.
+ *
+ * @remarks
+ * This is the PROPAGATION carrier across the agent/tool boundary. A `Tool`'s handler receives
+ * ONLY the model-supplied `args` (no ambient context, no signal — see
+ * the `@orkestrel/agent` package's `ToolOptions`), so the run's position in the
+ * workflow→agent→workflow chain CANNOT be threaded through a tool call at runtime. Instead the
+ * runner CLOSES it over the tool at BIND time: when it dispatches an `agent` task at depth `D`
+ * with ancestry `A`, it builds the agent's workflow tool with `{ depth: D, ancestry: A }`, so
+ * the handler's closure carries them. On invocation the handler runs the nested workflow at
+ * `depth: D + 1` with `ancestry: A ∪ { workflow:<id> }` — bounded by
+ * {@link import('./constants.js').MAX_WORKFLOW_DEPTH} (an over-deep / cyclic nested run THROWS a
+ * typed `DEPTH` {@link import('./errors.js').WorkflowError}, which the `ToolManager` isolates into
+ * the tool result's top-level `error`, AGENTS §14).
+ *
+ * Both fields are OPTIONAL: a workflow tool built for a TOP-LEVEL caller (not by the runner's
+ * agent-task binding) omits them — its nested run starts the chain at depth `1` with the bare
+ * `workflow:<id>` ancestry.
+ */
+export declare interface WorkflowToolOptions {
+    /** The depth the INVOKING agent runs at; the nested workflow runs at `depth + 1`. Default `0`. */
+    readonly depth?: number;
+    /** The ancestry of the invoking run; the nested run extends it with its own `workflow:<id>`. Default empty. */
+    readonly ancestry?: readonly string[];
+}
+
+/**
+ * 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 }`
+ */
+export declare function workflowToolSummary(result: WorkflowResult): Readonly<{
+    status: WorkflowStatus;
+    count: number;
+}>;
+
+export { }