Crate salvor_graph 

The Salvor graph document format, strict versioned validation, and JSON Schema emission.

A graph is a declarative CONTROL document: authored once, submitted, hashed into a run, and then frozen. It coordinates nodes the runtime already knows how to execute (a full agent loop, a single tool call, a human gate, a branch, a map fan-out, and a fold bounded-iteration loop) and the typed edges between them. This crate owns four things and no more:

• the document model: Graph, Node, the payloads, and Edge, parsed strictly (unknown fields rejected) and versioned additively;
• the [validate] pass: a set of independent checks that collect every error and name the offending node or edge;
• the expr language: the total, non-Turing-complete condition language a branch case’s expression string is written in, parsed at the submit boundary so a malformed condition is a node-precise error, never a runtime failure;
• graph_schema: the graph document’s JSON Schema, the single source of truth for editors and the future per-language builders.

What this crate is NOT

There is no run-time execution here. No engine drives a graph, no scheduler fans out a map, and no server endpoint submits one. Validation PARSES a branch condition (so a bad one fails at submit) but never EVALUATES one against a routed value; the evaluator expr::Expr::eval exists and is total, but it is the future engine that calls it, not this crate. Keeping this crate to format-plus-validation is what keeps it a pure, IO-free leaf: it depends only on serde, serde_json, schemars, and thiserror, drags in no runtime, and so stays usable from a future wasm dashboard projection.

Strict in, additive out

Parsing rejects a stray field loudly, because a silently dropped field could drop a gate or an unenforced budget. Validation is likewise strict and fails at the submit boundary, not at run time. The one forward-compatibility concession is the additive schema_version discipline (see document::SCHEMA_VERSION): a graph recorded under an older build still parses and validates under a newer one.

Re-exports

pub use builder::AgentSpec;

pub use builder::BranchSpec;

pub use builder::FoldSpec;

pub use builder::GateSpec;

pub use builder::GraphBuilder;

pub use builder::MapSpec;

pub use builder::ToolSpec;

pub use document::AgentNode;

pub use document::BranchCase;

pub use document::BranchCondition;

pub use document::BranchNode;

pub use document::Edge;

pub use document::FoldBody;

pub use document::FoldJoin;

pub use document::FoldNode;

pub use document::GateNode;

pub use document::Graph;

pub use document::MapBody;

pub use document::MapNode;

pub use document::Node;

pub use document::SCHEMA_VERSION;

pub use document::ToolNode;

pub use expr::Expr;

pub use expr::ExprError;

pub use expr::MAX_EXPRESSION_LEN;

pub use expr::parse as parse_expression;

pub use validate::GraphError;

pub use validate::GraphSummary;

pub use validate::MAX_NODE_NAME_LEN;

pub use validate::validate;

Modules

builder

A fluent, typed builder for a graph Graph document.

document

The graph document format: the Graph envelope, the six node kinds, the edges that connect them, and the small payload types a node carries.

expr

The branch-condition expression language: a small, TOTAL, non-Turing-complete language that gives meaning to the opaque string inside a crate::document::BranchCondition::Expression.

validate

Strict, versioned validation of a graph document.

Functions

graph_schema

Returns the graph document’s JSON Schema as a serde_json::Value.