Skip to main content

Module engine

Module engine 

Source
Expand description

The execution engine.

§Model

  • The Graph is 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-branch edges. Branch nodes take the edges whose handle equals NodeOutput::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: answer is 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 > 0 and the error is NodeError::retryable. The delay is the larger of the policy delay and NodeError::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, else Limits::default_node_timeout_ms) apply per attempt when the clock supports timers. The attempt deadline is also exposed as NodeContext::deadline_ms so nodes that block synchronously can bound themselves.

  • After retries, the error strategy applies:

    • fail: the frame fails. In the root frame the run ends with RunFailed and in-flight nodes are dropped. In a container body, the container node receives SubgraphResult::Failed.
    • fail-branch: outputs error_message / error_type; only fail-branch edges are taken.
    • default-value: outputs are the defaults plus error_message / error_type; non-branch nodes then continue as on success. Branch nodes follow the handle named by a branch default 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::pause stops scheduling everywhere, lets in-flight nodes finish and then ends with RunPaused carrying a Snapshot.
  • A node returning NodeOutcome::Paused pauses 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 new RunInput are applied, pending nodes re-run and paused nodes are resumed with their saved state plus their entry in ResumeFrom::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 iteration review; the frame is PauseReason::frame), then by the plain node id, which applies to every frame.
  • RunHandle::abort drops every in-flight node future immediately.

Structs§

Engine
Executes runs of one graph.
Limits
Resource limits for a run.
ResumeFrom
Resume information.
RunHandle
Controls a running run. Cheap to clone, Send + Sync.
RunInput
Input for a run.
RunStream
Stream of run events. Send + 'static. Dropping it cancels the run.