Nodes are executable capabilities

What belongs in a node

A node packages a Python handler or a provider-backed prompt, declared tools, prerequisites, an optional group, and an optional fallback marker.

Nodes return a NodeResult — output, state_updates, and an optional next_state. That result is a proposal. Nothing a node returns commits state by itself.

The router selects nodes

The backend ranks candidates and proposes one or more nodes arranged as parallel, sequential, hybrid, or fallback execution.

Selecting two nodes does not create two current states. A workflow instance still has one current state, and any state change is committed only after gates pass.

from neosyntropy import FSM, node

@node(id="VerifyIdentity")
def verify_identity(ctx):
    return ctx.result(state_updates={"verified": True})

@node(id="CheckEligibility", prerequisites=("VerifyIdentity",))
def check_eligibility(ctx):
    return ctx.result(state_updates={"eligible": True})

@node(id="OutOfScope", is_fallback=True)
def out_of_scope(ctx):
    return ctx.result(output="No actionable path.")

graph = FSM(nodes=[verify_identity, check_eligibility, out_of_scope], edges=[...])

Tools live on nodes

Tools are capabilities on a node (tools=("lookup_order",)), never graph vertices. Handlers call them through a bound facade that enforces the allow-list fail-closed. Undeclared tool calls are denied fail-closed, not retries.