salvor_graph/
lib.rs

1//! The Salvor graph document format, strict versioned validation, and JSON
2//! Schema emission.
3//!
4//! A graph is a declarative CONTROL document: authored once, submitted, hashed
5//! into a run, and then frozen. It coordinates nodes the runtime already knows
6//! how to execute (a full `agent` loop, a single `tool` call, a human `gate`, a
7//! `branch`, a `map` fan-out, and a `fold` bounded-iteration loop) and the typed
8//! edges between them. This crate owns four things and no more:
9//!
10//! - the [`document`] model: [`Graph`], [`Node`], the payloads, and [`Edge`],
11//!   parsed strictly (unknown fields rejected) and versioned additively;
12//! - the [`validate`] pass: a set of independent checks that collect every
13//!   error and name the offending node or edge;
14//! - the [`expr`] language: the total, non-Turing-complete condition language a
15//!   `branch` case's expression string is written in, parsed at the submit
16//!   boundary so a malformed condition is a node-precise error, never a runtime
17//!   failure;
18//! - [`graph_schema`]: the graph document's JSON Schema, the single source of
19//!   truth for editors and the future per-language builders.
20//!
21//! # What this crate is NOT
22//!
23//! There is no run-time execution here. `salvor-engine` is the crate that
24//! drives a graph, fans a `map` out, and backs the `POST /v1/graphs` and
25//! `POST /v1/graph-runs` endpoints in `salvor-server`; none of that lives in
26//! this one. Validation PARSES a branch condition (so a bad one fails at
27//! submit) but never EVALUATES one against a routed value; the evaluator
28//! [`expr::Expr::eval`] exists and is total, but it is `salvor-engine` that
29//! calls it, not this crate. Keeping this crate to format-plus-validation is
30//! what keeps it a pure, IO-free leaf: it depends only on `serde`,
31//! `serde_json`, `schemars`, and `thiserror`, drags in no runtime, and so
32//! stays usable from a future wasm dashboard projection.
33//!
34//! # Strict in, additive out
35//!
36//! Parsing rejects a stray field loudly, because a silently dropped field could
37//! drop a gate or an unenforced budget. Validation is likewise strict and fails
38//! at the submit boundary, not at run time. The one forward-compatibility
39//! concession is the additive `schema_version` discipline (see
40//! [`document::SCHEMA_VERSION`]): a graph recorded under an older build still
41//! parses and validates under a newer one.
42
43#![warn(missing_docs)]
44
45pub mod builder;
46pub mod document;
47pub mod expr;
48pub mod validate;
49
50pub use builder::{AgentSpec, BranchSpec, FoldSpec, GateSpec, GraphBuilder, MapSpec, ToolSpec};
51pub use document::{
52    AgentNode, BranchCase, BranchCondition, BranchNode, Edge, FoldBody, FoldJoin, FoldNode,
53    GateNode, Graph, MapBody, MapNode, Node, SCHEMA_VERSION, ToolNode,
54};
55pub use expr::{Expr, ExprError, MAX_EXPRESSION_LEN, parse as parse_expression};
56pub use validate::{GraphError, GraphSummary, MAX_NODE_NAME_LEN, validate};
57
58/// Returns the graph document's JSON Schema as a [`serde_json::Value`].
59///
60/// This is the single source of truth for the document format: editors read it
61/// for autocomplete and inline validation, and the future per-language builders
62/// generate from it so a Rust, Python, or TypeScript author reduces to the same
63/// canonical JSON. It is derived from the [`Graph`] types by `schemars`, so it
64/// can never drift from what this crate actually parses.
65#[must_use]
66pub fn graph_schema() -> serde_json::Value {
67    serde_json::to_value(schemars::schema_for!(Graph))
68        .expect("a schemars-generated schema is always valid JSON")
69}
70
71#[cfg(test)]
72mod tests {
73    use super::*;
74
75    /// The emitted schema is a JSON object that describes the `Graph` type: it
76    /// declares the document's own fields (`schema_version`, `nodes`, `edges`)
77    /// and, through `$defs`, the node payloads.
78    #[test]
79    fn graph_schema_describes_the_document() {
80        let schema = graph_schema();
81        assert!(schema.is_object(), "schema is a JSON object");
82        let text = serde_json::to_string(&schema).expect("serialize");
83        for expected in [
84            "schema_version",
85            "nodes",
86            "edges",
87            "agent_hash",
88            "approval_schema",
89        ] {
90            assert!(
91                text.contains(expected),
92                "schema mentions {expected}: {text}"
93            );
94        }
95    }
96}
salvor_graph/lib.rs

salvor_graph/
lib.rs
