/**
 * Graph Execution Engine v2 — Generic Node Lifecycle State Machine
 *
 * Version: 2.0
 * Date: 2026-07-24
 *
 * Every node in the graph follows this single generic lifecycle. There are NO
 * per-type state machines — no branching on node agent, prompt, or role. Node
 * identity is an `{agent, prompt}` tuple, and its semantics emerge purely from
 * that tuple; the state machine itself only ever reads `NodeRuntimeState.status`.
 *
 *  Lifecycle:
 *
 *     pending → ready → running → completed → done
 *                  │        │            │
 *                  │        ├──→ escalate → done (error)
 *                  │        ├──→ timeout → done (error)
 *                  │        ├──→ cancelled → done
 *                  │        └──→ blocked (needs_approval) → completed (approve)
 *                  │               └──→ ready (reject, revision feedback)
 *                  │                    └──→ escalate (reject, no loop group)
 *                  └──→ cancelled → done
 *                  completed → ready  (revise-driven loop re-entry)
 *
  *  `completed → ready` is the loop-group re-entry edge: when a convergence
   *  node emits `revise_needed` with findings, failed upstream nodes re-enter
   *  `ready` (bounded by the loop-group `max_traversals` counter). See
   *  `.rolebox/design/orchestration-patterns.md` §1.6.
   *
 *  `completed → escalate` is the revision-cap edge: when a reviewer completes
 *  its `revise_needed` pass but the loop group's `max_traversals` is already
 *  exhausted, the revision escalates instead of looping (failure-resilience.md
 *  §1.6). `escalate → ready` is the automatic-retry edge: an escalating node
 *  re-enters `ready` for a retry when its effective escalate-retry budget — the
 *  max of `budget.max_retries` and the `retry.max` of any OUTBOUND or INCOMING
 *  edge — still allows another attempt (`retryCount < max`, graph-model.md
 *  §5.3). `pending → escalate` is the
 *  cascade-abort edge: a node that never started is escalated by an escalation
 *  cascading into its convergence node, so it stops blocking termination.
 *
 *  Pause path (Phase 3):  running → blocked (needs_approval), then
 *    blocked → completed (approve), blocked → ready (reject, revision feedback
 *    re-entry), or blocked → escalate (reject with no loop group).
 *
 * Design reference: `.rolebox/design/engine-state-machine.md` §2.
 * NodeStatus vocabulary: `src/constants.ts` (`NodeStatus`, lines 183-198).
 */
import { NodeStatus } from "../../constants.ts";
import type { EngineState, NodeRuntimeState } from "../../types.engine-v2.ts";
/** Whether `from → to` is a legal node-lifecycle transition. */
export declare function canTransitionNode(from: NodeStatus, to: NodeStatus): boolean;
/**
 * Throw unless `from → to` is a legal node-lifecycle transition.
 */
export declare function assertValidNodeTransition(from: NodeStatus, to: NodeStatus): void;
/** Optional metadata carried into a transition. */
export interface TransitionOptions {
    /** Dispatch task ID (set when a node enters `running`). */
    dispatchTaskId?: string;
    /** Dispatch session ID (set when a node enters `running`). */
    dispatchSessionId?: string;
    /** Materialized result ref (set when a node becomes `completed`). */
    result?: NodeRuntimeState["result"];
    /** Error reason (set for `escalate` / `timeout` / error `done`). */
    errorReason?: string;
}
/**
 * Apply a node status transition after validating it against the generic
 * transition table. Illegal transitions throw. Performs status-coupled
 * bookkeeping (spawn counters, task ids, timing) along the way.
 */
export declare function transitionNode(state: EngineState, node: NodeRuntimeState, to: NodeStatus, opts?: TransitionOptions): NodeRuntimeState;
/**
 * Transition a node into the `blocked` (needs_approval) state.
 *
 * A blocked node awaits human approval before it can continue its lifecycle.
 * The engine pauses graph advancement for this node's downstream subgraph
 * until a `graph_approve` call resolves or rejects the block.
 */
export declare function markNodeBlocked(state: EngineState, node: NodeRuntimeState): NodeRuntimeState;
/** pending → ready. */
export declare function markReady(state: EngineState, node: NodeRuntimeState): NodeRuntimeState;
/** ready → running, recording the dispatch ids. */
export declare function markRunning(state: EngineState, node: NodeRuntimeState, opts?: Pick<TransitionOptions, "dispatchTaskId" | "dispatchSessionId">): NodeRuntimeState;
/** running → completed. */
export declare function markCompleted(state: EngineState, node: NodeRuntimeState, opts?: Pick<TransitionOptions, "result">): NodeRuntimeState;
/** running → escalate, with a required error reason. */
export declare function markEscalated(state: EngineState, node: NodeRuntimeState, errorReason: string): NodeRuntimeState;
/** running → timeout, with an optional error reason. */
export declare function markTimedOut(state: EngineState, node: NodeRuntimeState, errorReason?: string): NodeRuntimeState;
/** pending | ready | running → cancelled. */
export declare function markCancelled(state: EngineState, node: NodeRuntimeState, errorReason?: string): NodeRuntimeState;
/** escalate | timeout | cancelled | completed → done. */
export declare function markDone(state: EngineState, node: NodeRuntimeState, errorReason?: string): NodeRuntimeState;
//# sourceMappingURL=node-lifecycle.d.ts.map