Expand description
The execution engine.
§Model
- The
Graphis immutable and shared; each run keeps its own per-frame node and edge state. - A node becomes ready once every incoming edge is resolved and at
least one is taken. A node whose incoming edges are all skipped is
skipped too (
NodeSkipped), and the skip propagates downstream. - Non-branch nodes take every outgoing edge except
fail-branchedges. Branch nodes take the edges whose handle equalsNodeOutput::branch; a branch node that selects no handle fails (subject to its error strategy). A selected handle with no edges simply skips every outgoing path. - Response nodes (answer / end) merge their outputs into the frame outputs:
answeris concatenated, other keys overwrite. The root frame outputs are the run outputs. - Nodes of one frame run concurrently (up to
Limits::max_concurrency) as futures polled by the run itself. Nothing is spawned, so the engine runs on any executor, including single-threaded and wasm ones.
§Run bootstrap
The root pool receives env.* (document defaults coerced to their declared
types, overridden by RunInput::env), conversation.* (same rule; missing
values get their type’s zero value), sys.* from RunInput::sys plus
sys.run_id. RunInput::inputs are written into the namespace of the
root entry node (normally the start node) before it runs; the start
node validates them and re-emits them as its outputs. Inputs are never
copied into sys, so an input cannot shadow a system variable.
§Failures
-
Retries apply to every node kind when
retry.max_retries > 0and the error isNodeError::retryable. The delay is the larger of the policy delay andNodeError::retry_after_ms(capped at five minutes), awaited inside the node’s own future, so other nodes keep running. The execution id is stable across attempts, and a retry that eventually succeeds is not a handled error. -
Timeouts (
timeout_ms, elseLimits::default_node_timeout_ms) apply per attempt when the clock supports timers. The attempt deadline is also exposed asNodeContext::deadline_msso nodes that block synchronously can bound themselves. -
After retries, the error strategy applies:
fail: the frame fails. In the root frame the run ends withRunFailedand in-flight nodes are dropped. In a container body, the container node receivesSubgraphResult::Failed.fail-branch: outputserror_message/error_type; onlyfail-branchedges are taken.default-value: outputs are the defaults pluserror_message/error_type; non-branch nodes then continue as on success. Branch nodes follow the handle named by abranchdefault value, or skip every outgoing path if there is none.
Handled failures are counted in
RunSucceeded::handled_errors. -
A panicking node fails with error type
panic(when unwinding is enabled).
§Limits
max_steps counts every node attempt in every frame and persists across
pause / resume. max_duration_ms covers the whole run (including time before
a pause) and is enforced by a timer race. max_depth bounds container nesting.
§Containers
Container nodes receive NodeContext::subgraph,
which runs the container’s body as a child frame ("<parent>/<container>[i]")
with the same scheduler, event sink, step budget and control signals. Writes
to namespaces outside the body (container variables, conversation variables)
are returned in SubgraphResult::Completed::writes; broke reports whether a
loop-end node completed. Usage of container nodes themselves is not added
to the run total (their children are already counted).
§Pause / resume / abort
RunHandle::pausestops scheduling everywhere, lets in-flight nodes finish and then ends withRunPausedcarrying aSnapshot.- A node returning
NodeOutcome::Pausedpauses only itself: independent branches keep running until nothing else can make progress, then the run pauses. - On resume (
RunInput::resume) the snapshot’s graph fingerprint and format are verified, env / sys / conversation values from the newRunInputare applied, pending nodes re-run and paused nodes are resumed with their saved state plus their entry inResumeFrom::inputs. Inputs are looked up by the frame-qualified key"<frame>/<node_id>"first (e.g."review[2]/approve"for a node paused inside the third item of iterationreview; the frame isPauseReason::frame), then by the plain node id, which applies to every frame. RunHandle::abortdrops every in-flight node future immediately.