Module node 

Node traits — the unit of execution within a graph.

Nodes are where the magic happens. Edges are plumbing. Based on Decisions 4, 11, 16 and Group 31 of the pre-plan.

Execution context

Every node receives a NodeContext alongside the state snapshot. This provides engine-computed, read-only metadata: step count, remaining steps, activation reason, and an extensible metadata map.

Nodes that don’t need context simply ignore the parameter. Nodes that care about convergence use it to decide when to wrap up.

Optional matrix layer

The graph engine works fully without the matrix. When enabled, the optional matrix layer observes execution — it lives between nodes, never inside them:

• Nodes can optionally return ConvergenceSignal instead of plain updates
• Without the matrix: ConvergenceSignal degrades to a normal Update
• With the matrix: signals are observed to learn better routing paths
• ActivationReason provides observability either way (debugging, streaming, HITL visibility) — the matrix just uses it as extra training data

Nodes stay pure computation units regardless of whether the matrix is active.

Structs

ConvergenceSignal

Optional convergence signal — nodes can report quality metadata. Without the matrix layer, only partial_update is used (applied as a normal update). With the matrix layer, actual_contribution, surprise, and quality guide routing.

HumanInput

Human input received after an interrupt

InterruptRequest

Request to pause execution for human input

NodeContext

Execution context injected by the engine into every node call.

Enums

ActivationReason

Why a node was activated in a particular superstep.

NodeResult

What a node can return — unified enum covering all execution outcomes. Every variant works standalone. Converge adds optional matrix data but degrades to Update automatically when the matrix layer isn’t active.

Traits

NodeFn

The core node trait — any async function that takes state and returns a result. Generated by the #[node] macro. Users never implement this manually.

NodeObserver

Observer for node lifecycle events within the execution engine.

ToolObserver

Observer for tool call lifecycle events.

Type Aliases

NodeFuture

Type-erased async future returned by nodes