Skip to main content

graphrt_core/
dsl.rs

1//! Workflow documents: the portable, serializable description of a workflow.
2//!
3//! A document is plain data (JSON or YAML). It is turned into an executable
4//! [`crate::graph::Graph`] by [`crate::graph::Graph::build`] using a
5//! [`crate::node::Registry`]. The format is frozen as version `1`; see
6//! `docs/workflow-format.md` for the stability promise and
7//! `schema/workflow-v1.schema.json` for the JSON Schema.
8//!
9//! ```yaml
10//! version: "1"
11//! name: hello
12//! env:
13//!   - { name: API_KEY, type: secret }
14//! graph:
15//!   nodes:
16//!     - id: start
17//!       type: start
18//!       variables: [{ variable: name, type: string, required: true }]
19//!     - id: greet
20//!       type: template-transform
21//!       template: "Hello {{ name }}"
22//!       variables: [{ variable: name, value_selector: [start, name] }]
23//!     - id: end
24//!       type: end
25//!       outputs: [{ variable: greeting, value_selector: [greet, output] }]
26//!   edges:
27//!     - { source: start, target: greet }
28//!     - { source: greet, target: end }
29//! ```
30//!
31//! v1 documents are strict: unknown fields are errors (keys starting with
32//! `x-` are free for tools and ignored). For interoperability the loader also
33//! accepts an *import layout*, checked leniently: nodes in the "node with a
34//! `data` object" shape (`{id, parentId, data: {type, title, ...}}`), camelCase
35//! edge handles (`sourceHandle`) and documents wrapped in a top-level
36//! `workflow` key.
37
38use indexmap::IndexMap;
39use serde::{Deserialize, Serialize};
40
41use crate::source_map::DocPath;
42use crate::validate::{Diagnostic, suggest};
43use crate::value::{Value, ValueType};
44
45/// The document format version this build reads and writes.
46pub const FORMAT_VERSION: &str = "1";
47
48/// Error raised while decoding a workflow document.
49#[derive(Debug, thiserror::Error)]
50#[non_exhaustive]
51pub enum DocumentError {
52    #[error("invalid JSON workflow document: {0}")]
53    Json(#[from] serde_json::Error),
54    /// Only produced when the `yaml` feature is enabled (the variant always exists
55    /// so enabling the feature never breaks downstream matches).
56    #[error("invalid YAML workflow document: {0}")]
57    Yaml(String),
58    #[error("invalid node `{id}`: {message}")]
59    Node { id: String, message: String },
60    /// A problem outside any node, at a document path such as `graph.edges[0].source`.
61    #[error("{path}: {message}")]
62    Field { path: String, message: String },
63}
64
65/// A complete workflow document.
66#[derive(Clone, Debug, Default, Serialize)]
67pub struct Workflow {
68    /// Document format version.
69    pub version: String,
70    pub name: Option<String>,
71    pub description: Option<String>,
72    /// Environment variables (`env.*`). Values may be omitted and supplied by the host at run time.
73    pub env: Vec<VariableDecl>,
74    /// Conversation variables (`conversation.*`), persisted by the host between runs.
75    pub conversation: Vec<VariableDecl>,
76    pub graph: GraphDoc,
77}
78
79/// Declaration of an env or conversation variable.
80#[derive(Clone, Debug, Serialize, Deserialize)]
81pub struct VariableDecl {
82    pub name: String,
83    #[serde(rename = "type", alias = "value_type", default = "any_type")]
84    pub ty: ValueType,
85    #[serde(default)]
86    pub value: Option<Value>,
87    #[serde(default)]
88    pub description: Option<String>,
89}
90
91fn any_type() -> ValueType {
92    ValueType::Any
93}
94
95/// Nodes and edges.
96#[derive(Clone, Debug, Default, Serialize)]
97pub struct GraphDoc {
98    pub nodes: Vec<NodeDoc>,
99    pub edges: Vec<EdgeDoc>,
100}
101
102/// One node. Node-specific settings live in `config`.
103///
104/// Serializes to the flat layout the loader accepts (`id`, `type`, `title`,
105/// `parent`, `on_error`, `retry`, `timeout_ms`, then the config keys), so a
106/// document survives a serialize / parse round trip unchanged.
107#[derive(Clone, Debug)]
108pub struct NodeDoc {
109    pub id: String,
110    /// Node kind, e.g. `llm`, `if-else`, `http-request`.
111    pub kind: String,
112    pub title: Option<String>,
113    /// Owning container (iteration / loop) for nodes inside a container body.
114    pub parent: Option<String>,
115    pub policy: NodePolicy,
116    /// Remaining node-specific configuration.
117    pub config: serde_json::Map<String, serde_json::Value>,
118    /// Whether unknown config fields are errors (judged by the node kind's
119    /// catalog schema). True for v1 documents and programmatic nodes; false for
120    /// nodes read from the import layout, which carry foreign builder fields.
121    pub strict: bool,
122}
123
124impl NodeDoc {
125    /// Minimal constructor, mainly for programmatic graph building and tests.
126    pub fn new(id: impl Into<String>, kind: impl Into<String>, config: serde_json::Value) -> Self {
127        let config = match config {
128            serde_json::Value::Object(map) => map,
129            _ => serde_json::Map::new(),
130        };
131        Self {
132            id: id.into(),
133            kind: kind.into(),
134            title: None,
135            parent: None,
136            policy: NodePolicy::default(),
137            config,
138            strict: true,
139        }
140    }
141
142    /// Set the owning container.
143    pub fn with_parent(mut self, parent: impl Into<String>) -> Self {
144        self.parent = Some(parent.into());
145        self
146    }
147
148    /// Set the failure policy.
149    pub fn with_policy(mut self, policy: NodePolicy) -> Self {
150        self.policy = policy;
151        self
152    }
153
154    /// Deserialize `config` into a node-specific config struct.
155    pub fn parse_config<T: serde::de::DeserializeOwned>(&self) -> Result<T, DocumentError> {
156        parse_config_at(&self.config)
157            .map_err(|(path, e)| DocumentError::Node { id: self.id.clone(), message: with_field(&path, &e) })
158    }
159
160    /// Human-readable label.
161    pub fn label(&self) -> &str {
162        self.title.as_deref().unwrap_or(&self.id)
163    }
164}
165
166/// Deserialize a config map, reporting the path of the offending field
167/// (`variables[0].value_selector`, or `.` for the config itself).
168pub(crate) fn parse_config_at<T: serde::de::DeserializeOwned>(
169    config: &serde_json::Map<String, serde_json::Value>,
170) -> Result<T, (String, serde_json::Error)> {
171    let value = serde_json::Value::Object(config.clone());
172    serde_path_to_error::deserialize(value).map_err(|e| (e.path().to_string(), e.into_inner()))
173}
174
175fn with_field(path: &str, error: &serde_json::Error) -> String {
176    if path == "." { error.to_string() } else { format!("{path}: {error}") }
177}
178
179/// Failure handling, retries and timeouts for one node.
180#[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize)]
181pub struct NodePolicy {
182    #[serde(default)]
183    pub on_error: ErrorStrategy,
184    #[serde(default)]
185    pub retry: RetryPolicy,
186    /// Per-attempt timeout in milliseconds. `None` uses the engine default.
187    #[serde(default)]
188    pub timeout_ms: Option<u64>,
189}
190
191/// What happens when a node fails after exhausting retries.
192#[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize)]
193#[serde(tag = "strategy", rename_all = "kebab-case")]
194#[non_exhaustive]
195pub enum ErrorStrategy {
196    /// Fail the frame (and the run, unless a container handles it).
197    #[default]
198    Fail,
199    /// Route through outgoing edges whose handle is [`crate::graph::FAIL_BRANCH`];
200    /// outputs are `error_message` and `error_type`.
201    FailBranch,
202    /// Continue normally with these outputs, plus `error_message` and `error_type`.
203    DefaultValue {
204        #[serde(default)]
205        values: IndexMap<String, Value>,
206    },
207}
208
209/// Retry policy. Applies to every node kind.
210#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
211pub struct RetryPolicy {
212    #[serde(default)]
213    pub max_retries: u32,
214    /// Delay before the first retry, in milliseconds.
215    #[serde(default)]
216    pub interval_ms: u64,
217    /// Multiplier applied to the delay after each retry (1.0 = constant).
218    #[serde(default = "one")]
219    pub backoff: f64,
220}
221
222fn one() -> f64 {
223    1.0
224}
225
226impl Default for RetryPolicy {
227    fn default() -> Self {
228        Self { max_retries: 0, interval_ms: 0, backoff: 1.0 }
229    }
230}
231
232impl RetryPolicy {
233    /// Delay before retry number `attempt` (1-based).
234    pub fn delay_ms(&self, attempt: u32) -> u64 {
235        let factor = self.backoff.max(1.0).powi(i32::try_from(attempt.saturating_sub(1)).unwrap_or(i32::MAX));
236        #[allow(clippy::cast_possible_truncation, clippy::cast_sign_loss, clippy::cast_precision_loss)]
237        let ms = (self.interval_ms as f64 * factor).min(3_600_000.0) as u64;
238        ms
239    }
240}
241
242/// A directed edge. `handle` selects the branch of the source node (default `source`).
243#[derive(Clone, Debug, Serialize, Deserialize)]
244pub struct EdgeDoc {
245    #[serde(default)]
246    pub id: Option<String>,
247    pub source: String,
248    pub target: String,
249    #[serde(default, alias = "sourceHandle", alias = "source_handle", skip_serializing_if = "Option::is_none")]
250    pub handle: Option<String>,
251}
252
253impl EdgeDoc {
254    pub fn new(source: impl Into<String>, target: impl Into<String>) -> Self {
255        Self { id: None, source: source.into(), target: target.into(), handle: None }
256    }
257
258    pub fn with_handle(mut self, handle: impl Into<String>) -> Self {
259        self.handle = Some(handle.into());
260        self
261    }
262}
263
264impl Workflow {
265    /// Parse a JSON document.
266    pub fn from_json(text: &str) -> Result<Self, DocumentError> {
267        let raw: serde_json::Value = serde_json::from_str(text)?;
268        Self::from_value(raw)
269    }
270
271    /// Parse a YAML document.
272    #[cfg(feature = "yaml")]
273    pub fn from_yaml(text: &str) -> Result<Self, DocumentError> {
274        // YAML 1.2 booleans only: `yes`, `no`, `y`, `n`, `on`, `off` stay strings.
275        let options = serde_saphyr::options! { strict_booleans: true };
276        let raw: serde_json::Value =
277            serde_saphyr::from_str_with_options(text, options).map_err(|e| DocumentError::Yaml(e.to_string()))?;
278        Self::from_value(raw)
279    }
280
281    /// Parse JSON or YAML, detecting the format from the first non-blank character.
282    pub fn parse(text: &str) -> Result<Self, DocumentError> {
283        let first = text.trim_start().chars().next();
284        if matches!(first, Some('{')) {
285            return Self::from_json(text);
286        }
287        #[cfg(feature = "yaml")]
288        {
289            Self::from_yaml(text)
290        }
291        #[cfg(not(feature = "yaml"))]
292        {
293            Self::from_json(text)
294        }
295    }
296
297    /// Build from an already-decoded JSON value. Fails with the first error;
298    /// [`crate::validate::validate_text`] reports all of them.
299    pub fn from_value(raw: serde_json::Value) -> Result<Self, DocumentError> {
300        let decoded = decode(raw);
301        match decoded.diagnostics.into_iter().find(Diagnostic::is_error) {
302            None => Ok(decoded.workflow),
303            Some(d) => {
304                let message = match &d.suggestion {
305                    Some(s) => format!("{}; did you mean `{s}`?", d.message),
306                    None => d.message,
307                };
308                Err(match d.node {
309                    Some(id) => DocumentError::Node { id, message },
310                    None => DocumentError::Field { path: d.path.to_string(), message },
311                })
312            }
313        }
314    }
315}
316
317/// A decoded document plus where each node and edge came from and every
318/// finding made while decoding.
319pub(crate) struct Decoded {
320    pub workflow: Workflow,
321    /// Source path of each node in `workflow.graph.nodes`.
322    pub node_paths: Vec<DocPath>,
323    /// Source path of each edge in `workflow.graph.edges`.
324    pub edge_paths: Vec<DocPath>,
325    pub diagnostics: Vec<Diagnostic>,
326}
327
328/// Which keys an object may have.
329struct KeyRules<'a> {
330    what: &'a str,
331    known: &'a [&'a str],
332    /// `(old, new)`: accepted with a warning.
333    deprecated: &'a [(&'a str, &'a str)],
334    /// Reserved for future versions of the format.
335    reserved: &'a [&'a str],
336}
337
338const TOP_LEVEL: KeyRules<'static> = KeyRules {
339    what: "the document",
340    known: &["version", "name", "description", "env", "conversation", "graph"],
341    deprecated: &[("environment_variables", "env"), ("conversation_variables", "conversation")],
342    reserved: &["imports", "inputs", "outputs", "triggers", "metadata", "requires", "subgraphs"],
343};
344
345const GRAPH_KEYS: KeyRules<'static> =
346    KeyRules { what: "`graph`", known: &["nodes", "edges"], deprecated: &[], reserved: &[] };
347
348/// Node-level keys other than `id`/`type`/`title` and the node config.
349const NODE_KEYS: KeyRules<'static> = KeyRules {
350    what: "a node",
351    known: &[],
352    deprecated: &[
353        ("parentId", "parent"),
354        ("container_id", "parent"),
355        ("iteration_id", "parent"),
356        ("loop_id", "parent"),
357        ("error_strategy", "on_error"),
358        ("default_value", "on_error"),
359        ("retry_config", "retry"),
360    ],
361    reserved: &["disabled", "cache", "metadata"],
362};
363
364/// Fields every node has, whatever its type.
365pub const COMMON_NODE_FIELDS: &[&str] = &["id", "type", "title", "parent", "retry", "timeout_ms", "on_error"];
366
367/// Node fields reserved for future versions; node configs may not use them.
368pub const RESERVED_NODE_FIELDS: &[&str] = NODE_KEYS.reserved;
369
370const EDGE_KEYS: KeyRules<'static> = KeyRules {
371    what: "an edge",
372    known: &["id", "source", "target", "handle"],
373    deprecated: &[("sourceHandle", "handle"), ("source_handle", "handle")],
374    reserved: &[],
375};
376
377const DECL_KEYS: KeyRules<'static> = KeyRules {
378    what: "a variable declaration",
379    known: &["name", "type", "value", "description"],
380    deprecated: &[("value_type", "type")],
381    reserved: &[],
382};
383
384const RETRY_KEYS: KeyRules<'static> =
385    KeyRules { what: "`retry`", known: &["max_retries", "interval_ms", "backoff"], deprecated: &[], reserved: &[] };
386
387const ON_ERROR_KEYS: KeyRules<'static> =
388    KeyRules { what: "`on_error`", known: &["strategy", "values"], deprecated: &[], reserved: &[] };
389
390const STRATEGIES: &[&str] = &["fail", "fail-branch", "default-value"];
391
392/// Keys written by visual builders. Ignored (new tools should use `x-` keys).
393const BUILDER_KEYS: &[&str] = &[
394    "desc",
395    "selected",
396    "position",
397    "positionAbsolute",
398    "width",
399    "height",
400    "sourcePosition",
401    "targetPosition",
402    "zIndex",
403    "isInIteration",
404    "isInLoop",
405];
406
407/// Whether `key` is an extension key (`x-...`), free for tools and ignored.
408pub fn is_extension_key(key: &str) -> bool {
409    key.starts_with("x-")
410}
411
412/// Check the keys of a strict object. With `unknown_is_error` false only
413/// deprecated and reserved keys are reported (for objects that mix fixed
414/// fields with open config).
415fn check_keys(
416    obj: &serde_json::Map<String, serde_json::Value>,
417    path: &DocPath,
418    rules: &KeyRules<'_>,
419    unknown_is_error: bool,
420    out: &mut Vec<Diagnostic>,
421) {
422    for key in obj.keys() {
423        let key_path = path.key(key);
424        if is_extension_key(key) || rules.known.contains(&key.as_str()) {
425            continue;
426        }
427        if let Some((_, new)) = rules.deprecated.iter().find(|(old, _)| old == key) {
428            out.push(
429                Diagnostic::warning("deprecated", key_path, format!("`{key}` in {} is deprecated", rules.what))
430                    .at_key()
431                    .with_suggestion(Some((*new).to_owned())),
432            );
433        } else if rules.reserved.contains(&key.as_str()) {
434            out.push(
435                Diagnostic::error(
436                    "reserved-field",
437                    key_path,
438                    format!("`{key}` in {} is reserved for a future version of the format", rules.what),
439                )
440                .at_key()
441                .with_help("keys starting with `x-` are free for tools and ignored"),
442            );
443        } else if unknown_is_error {
444            out.push(
445                Diagnostic::error("unknown-field", key_path, format!("unknown field `{key}` in {}", rules.what))
446                    .at_key()
447                    .with_suggestion(suggest(key, rules.known.iter().copied()))
448                    .with_help(format!("expected one of: {}", rules.known.join(", "))),
449            );
450        }
451    }
452}
453
454/// Decode a raw document, collecting every finding instead of stopping at the first.
455pub(crate) fn decode(raw: serde_json::Value) -> Decoded {
456    let mut out = Vec::new();
457    let mut decoded = Decoded {
458        workflow: Workflow { version: FORMAT_VERSION.to_owned(), ..Workflow::default() },
459        node_paths: Vec::new(),
460        edge_paths: Vec::new(),
461        diagnostics: Vec::new(),
462    };
463    let serde_json::Value::Object(mut root) = raw else {
464        out.push(Diagnostic::error("invalid-value", DocPath::root(), "a workflow document must be an object"));
465        decoded.diagnostics = out;
466        return decoded;
467    };
468    // Import layout: everything nested under `workflow`, app metadata under `app`.
469    let import = matches!(root.get("workflow"), Some(serde_json::Value::Object(_))) || root.contains_key("app");
470    let strict = !import;
471    let mut inner_keys = std::collections::HashSet::new();
472    if let Some(serde_json::Value::Object(inner)) = root.remove("workflow") {
473        for (k, v) in inner {
474            if !root.contains_key(&k) {
475                inner_keys.insert(k.clone());
476                root.insert(k, v);
477            }
478        }
479    }
480    let at = |key: &str| {
481        if inner_keys.contains(key) { DocPath::root().key("workflow").key(key) } else { DocPath::root().key(key) }
482    };
483    if strict {
484        check_keys(&root, &DocPath::root(), &TOP_LEVEL, true, &mut out);
485    }
486
487    let wf = &mut decoded.workflow;
488    if strict {
489        wf.version = check_version(root.get("version"), &at("version"), &mut out);
490    } else if let Some(v) = str_field(&root, "version") {
491        wf.version = v;
492    }
493    let app = root.get("app").and_then(|a| a.as_object());
494    wf.name =
495        text_field(&root, "name", &at("name"), strict, &mut out).or_else(|| app.and_then(|a| str_field(a, "name")));
496    wf.description = text_field(&root, "description", &at("description"), strict, &mut out)
497        .or_else(|| app.and_then(|a| str_field(a, "description")));
498
499    for (field, legacy) in [("env", "environment_variables"), ("conversation", "conversation_variables")] {
500        let (key, raw) = match root.remove(field) {
501            Some(v) => (field, Some(v)),
502            None => (legacy, root.remove(legacy)),
503        };
504        let decls = decode_decls(raw, &at(key), strict, &mut out);
505        if field == "env" {
506            wf.env = decls;
507        } else {
508            wf.conversation = decls;
509        }
510    }
511
512    let graph_path = at("graph");
513    let graph = match root.remove("graph") {
514        Some(serde_json::Value::Object(g)) => g,
515        Some(_) => {
516            out.push(Diagnostic::error(
517                "invalid-value",
518                graph_path,
519                "`graph` must be an object with `nodes` and `edges`",
520            ));
521            decoded.diagnostics = out;
522            return decoded;
523        }
524        None => {
525            out.push(
526                Diagnostic::error("missing-field", DocPath::root(), "missing `graph`")
527                    .with_help("a workflow needs `graph: {nodes: [...], edges: [...]}`"),
528            );
529            decoded.diagnostics = out;
530            return decoded;
531        }
532    };
533    if strict {
534        check_keys(&graph, &graph_path, &GRAPH_KEYS, true, &mut out);
535    }
536    for (i, raw) in list_field(&graph, "nodes", &graph_path, &mut out).into_iter().enumerate() {
537        let path = graph_path.key("nodes").index(i);
538        if let Some(doc) = NodeDoc::decode(raw, &path, strict, &mut out) {
539            wf.graph.nodes.push(doc);
540            decoded.node_paths.push(path);
541        }
542    }
543    for (i, raw) in list_field(&graph, "edges", &graph_path, &mut out).into_iter().enumerate() {
544        let path = graph_path.key("edges").index(i);
545        if let Some(edge) = decode_edge(raw, &path, strict, &mut out) {
546            wf.graph.edges.push(edge);
547            decoded.edge_paths.push(path);
548        }
549    }
550    decoded.diagnostics = out;
551    decoded
552}
553
554/// `version` of a v1 document: absent (defaults to `"1"`), `"1"` or `1`.
555fn check_version(raw: Option<&serde_json::Value>, path: &DocPath, out: &mut Vec<Diagnostic>) -> String {
556    match raw {
557        None => FORMAT_VERSION.to_owned(),
558        Some(serde_json::Value::String(s)) if s == FORMAT_VERSION => s.clone(),
559        Some(serde_json::Value::Number(n)) if n.as_u64() == Some(1) => FORMAT_VERSION.to_owned(),
560        Some(other) => {
561            let shown = other.as_str().map_or_else(|| other.to_string(), str::to_owned);
562            out.push(
563                Diagnostic::error(
564                    "unsupported-version",
565                    path.clone(),
566                    format!("unsupported document version `{shown}`; this build reads version \"{FORMAT_VERSION}\""),
567                )
568                .with_help("newer documents need a newer graphrt"),
569            );
570            shown
571        }
572    }
573}
574
575fn str_field(map: &serde_json::Map<String, serde_json::Value>, key: &str) -> Option<String> {
576    map.get(key).and_then(|v| v.as_str()).map(str::to_owned)
577}
578
579/// An optional string field; a non-string is an error in strict documents.
580fn text_field(
581    map: &serde_json::Map<String, serde_json::Value>,
582    key: &str,
583    path: &DocPath,
584    strict: bool,
585    out: &mut Vec<Diagnostic>,
586) -> Option<String> {
587    match map.get(key) {
588        None | Some(serde_json::Value::Null) => None,
589        Some(serde_json::Value::String(s)) => Some(s.clone()),
590        Some(_) => {
591            if strict {
592                out.push(Diagnostic::error("invalid-value", path.clone(), format!("`{key}` must be a string")));
593            }
594            None
595        }
596    }
597}
598
599/// The items of an optional array field.
600fn list_field(
601    map: &serde_json::Map<String, serde_json::Value>,
602    key: &str,
603    parent: &DocPath,
604    out: &mut Vec<Diagnostic>,
605) -> Vec<serde_json::Value> {
606    match map.get(key) {
607        None | Some(serde_json::Value::Null) => Vec::new(),
608        Some(serde_json::Value::Array(items)) => items.clone(),
609        Some(_) => {
610            out.push(Diagnostic::error("invalid-value", parent.key(key), format!("`{key}` must be a list")));
611            Vec::new()
612        }
613    }
614}
615
616fn decode_decls(
617    raw: Option<serde_json::Value>,
618    path: &DocPath,
619    strict: bool,
620    out: &mut Vec<Diagnostic>,
621) -> Vec<VariableDecl> {
622    let items = match raw {
623        None | Some(serde_json::Value::Null) => return Vec::new(),
624        Some(serde_json::Value::Array(items)) => items,
625        Some(_) => {
626            out.push(Diagnostic::error("invalid-value", path.clone(), "variable declarations must be a list"));
627            return Vec::new();
628        }
629    };
630    let mut decls: Vec<VariableDecl> = Vec::with_capacity(items.len());
631    for (i, item) in items.into_iter().enumerate() {
632        let item_path = path.index(i);
633        if strict {
634            if let serde_json::Value::Object(obj) = &item {
635                check_keys(obj, &item_path, &DECL_KEYS, true, out);
636            }
637        }
638        match serde_json::from_value::<VariableDecl>(item) {
639            Ok(decl) => {
640                if decls.iter().any(|d| d.name == decl.name) {
641                    out.push(Diagnostic::error(
642                        "duplicate-variable",
643                        item_path.key("name"),
644                        format!("variable `{}` is declared twice", decl.name),
645                    ));
646                }
647                decls.push(decl);
648            }
649            Err(e) => {
650                out.push(Diagnostic::error("invalid-value", item_path, format!("invalid variable declaration: {e}")))
651            }
652        }
653    }
654    decls
655}
656
657fn decode_edge(raw: serde_json::Value, path: &DocPath, strict: bool, out: &mut Vec<Diagnostic>) -> Option<EdgeDoc> {
658    let serde_json::Value::Object(mut obj) = raw else {
659        out.push(Diagnostic::error("invalid-value", path.clone(), "an edge must be an object `{source, target}`"));
660        return None;
661    };
662    if strict {
663        check_keys(&obj, path, &EDGE_KEYS, true, out);
664    }
665    obj.retain(|k, _| !is_extension_key(k));
666    let mut ok = true;
667    for end in ["source", "target"] {
668        match obj.get(end) {
669            Some(serde_json::Value::String(s)) if !s.is_empty() => {}
670            Some(_) => {
671                out.push(Diagnostic::error("invalid-value", path.key(end), format!("edge `{end}` must be a node id")));
672                ok = false;
673            }
674            None => {
675                out.push(Diagnostic::error("missing-field", path.clone(), format!("edge is missing `{end}`")));
676                ok = false;
677            }
678        }
679    }
680    if !ok {
681        return None;
682    }
683    match serde_json::from_value::<EdgeDoc>(serde_json::Value::Object(obj)) {
684        Ok(edge) => Some(edge),
685        Err(e) => {
686            out.push(Diagnostic::error("invalid-value", path.clone(), format!("invalid edge: {e}")));
687            None
688        }
689    }
690}
691
692/// Keys handled by [`NodeDoc`] itself and therefore removed from `config`.
693const POLICY_KEYS: &[&str] = &["on_error", "error_strategy", "default_value", "retry", "retry_config", "timeout_ms"];
694
695impl NodeDoc {
696    /// Normalize a raw node object. Returns `Ok(None)` for annotation-only nodes (notes).
697    pub fn from_raw(raw: serde_json::Value) -> Result<Option<Self>, DocumentError> {
698        let mut out = Vec::new();
699        let doc = Self::decode(raw, &DocPath::root(), true, &mut out);
700        match out.into_iter().find(Diagnostic::is_error) {
701            Some(d) => Err(DocumentError::Node {
702                id: d.node.unwrap_or_else(|| "<node>".to_owned()),
703                message: match d.suggestion {
704                    Some(s) => format!("{}; did you mean `{s}`?", d.message),
705                    None => d.message,
706                },
707            }),
708            None => Ok(doc),
709        }
710    }
711
712    /// Decode one node at `path`, collecting findings. `None` for notes and for
713    /// nodes too broken to keep (no usable `id` or `type`).
714    fn decode(raw: serde_json::Value, path: &DocPath, strict_doc: bool, out: &mut Vec<Diagnostic>) -> Option<Self> {
715        let serde_json::Value::Object(mut obj) = raw else {
716            out.push(Diagnostic::error("invalid-value", path.clone(), "a node must be an object `{id, type, ...}`"));
717            return None;
718        };
719        let id = match obj.remove("id") {
720            Some(serde_json::Value::String(s)) if !s.is_empty() => s,
721            Some(_) => {
722                out.push(Diagnostic::error("invalid-value", path.key("id"), "node `id` must be a non-empty string"));
723                return None;
724            }
725            None => {
726                out.push(Diagnostic::error("missing-field", path.clone(), "node is missing `id`"));
727                return None;
728            }
729        };
730        let wrapped = matches!(obj.get("data"), Some(serde_json::Value::Object(_)));
731        let strict = strict_doc && !wrapped;
732        if strict {
733            let before = out.len();
734            check_keys(&obj, path, &NODE_KEYS, false, out);
735            for d in out.iter_mut().skip(before) {
736                d.node = Some(id.clone());
737            }
738        }
739        let legacy_parent = obj.remove("parentId").and_then(as_string);
740        let mut parent = obj.remove("parent").and_then(as_string).or(legacy_parent);
741        // Flatten the `data` wrapper layout.
742        if let Some(serde_json::Value::Object(data)) = obj.remove("data") {
743            for (k, v) in data {
744                obj.insert(k, v);
745            }
746        }
747        for key in ["container_id", "iteration_id", "loop_id"] {
748            let v = obj.remove(key).and_then(as_string);
749            if parent.is_none() {
750                parent = v;
751            }
752        }
753        let kind = match obj.remove("type") {
754            Some(serde_json::Value::String(s)) if !s.is_empty() => s,
755            Some(_) => {
756                out.push(
757                    Diagnostic::error("invalid-value", path.key("type"), "node `type` must be a non-empty string")
758                        .with_node(&id),
759                );
760                return None;
761            }
762            None => {
763                out.push(Diagnostic::error("missing-field", path.clone(), "node is missing `type`").with_node(&id));
764                return None;
765            }
766        };
767        if kind == "custom-note" || kind == "note" {
768            return None;
769        }
770        let title = match obj.remove("title") {
771            Some(serde_json::Value::String(s)) if !s.is_empty() => Some(s),
772            None | Some(serde_json::Value::Null | serde_json::Value::String(_)) => None,
773            Some(_) => {
774                if strict {
775                    out.push(
776                        Diagnostic::error("invalid-value", path.key("title"), "node `title` must be a string")
777                            .with_node(&id),
778                    );
779                }
780                None
781            }
782        };
783        let policy = extract_policy(&id, &mut obj, path, strict, out);
784        for k in BUILDER_KEYS {
785            obj.remove(*k);
786        }
787        obj.retain(|k, _| !is_extension_key(k));
788        Some(Self { id, kind, title, parent, policy, config: obj, strict })
789    }
790}
791
792fn as_string(v: serde_json::Value) -> Option<String> {
793    match v {
794        serde_json::Value::String(s) if !s.is_empty() => Some(s),
795        _ => None,
796    }
797}
798
799fn extract_policy(
800    id: &str,
801    obj: &mut serde_json::Map<String, serde_json::Value>,
802    path: &DocPath,
803    strict: bool,
804    out: &mut Vec<Diagnostic>,
805) -> NodePolicy {
806    let mut policy = NodePolicy::default();
807    let mut push = |d: Diagnostic| out.push(d.with_node(id));
808
809    if let Some(v) = obj.remove("on_error") {
810        let at = path.key("on_error");
811        if let serde_json::Value::Object(map) = &v {
812            if strict {
813                let mut found = Vec::new();
814                check_keys(map, &at, &ON_ERROR_KEYS, true, &mut found);
815                found.into_iter().for_each(&mut push);
816            }
817        }
818        let strategy = v.get("strategy").and_then(serde_json::Value::as_str).map(str::to_owned);
819        match (&strategy, serde_json::from_value::<ErrorStrategy>(v)) {
820            (_, Ok(s)) => policy.on_error = s,
821            (Some(name), Err(_)) if !STRATEGIES.contains(&name.as_str()) => push(
822                Diagnostic::error("invalid-value", at.key("strategy"), format!("unknown `on_error` strategy `{name}`"))
823                    .with_suggestion(suggest(name, STRATEGIES.iter().copied()))
824                    .with_help("expected `fail`, `fail-branch` or `default-value`"),
825            ),
826            (_, Err(e)) => push(
827                Diagnostic::error("invalid-value", at, format!("invalid `on_error`: {e}"))
828                    .with_help("expected `{strategy: fail | fail-branch | default-value, values: {...}}`"),
829            ),
830        }
831    } else if let Some(serde_json::Value::String(strategy)) = obj.remove("error_strategy") {
832        policy.on_error = match strategy.as_str() {
833            "fail-branch" => ErrorStrategy::FailBranch,
834            "" | "none" | "fail" => ErrorStrategy::Fail,
835            "default-value" => {
836                // Accept `[{key, type, value}]` lists or plain maps.
837                let values = match obj.remove("default_value") {
838                    Some(serde_json::Value::Array(items)) => items
839                        .into_iter()
840                        .filter_map(|item| {
841                            let key = item.get("key")?.as_str()?.to_owned();
842                            let declared = item.get("type").and_then(|t| t.as_str()).unwrap_or("any").to_owned();
843                            let value = item.get("value").cloned().unwrap_or(serde_json::Value::Null);
844                            Some((key, default_value(&declared, value)))
845                        })
846                        .collect(),
847                    Some(serde_json::Value::Object(map)) => {
848                        map.into_iter().map(|(k, v)| (k, Value::from_json(v))).collect()
849                    }
850                    _ => IndexMap::new(),
851                };
852                ErrorStrategy::DefaultValue { values }
853            }
854            other => {
855                push(
856                    Diagnostic::error(
857                        "invalid-value",
858                        path.key("error_strategy"),
859                        format!("unknown error_strategy `{other}` (expected `fail`, `fail-branch` or `default-value`)"),
860                    )
861                    .with_suggestion(suggest(other, STRATEGIES.iter().copied())),
862                );
863                ErrorStrategy::Fail
864            }
865        };
866    }
867    obj.remove("default_value");
868
869    if let Some(v) = obj.remove("retry") {
870        let at = path.key("retry");
871        if let serde_json::Value::Object(map) = &v {
872            if strict {
873                let mut found = Vec::new();
874                check_keys(map, &at, &RETRY_KEYS, true, &mut found);
875                found.into_iter().for_each(&mut push);
876            }
877        }
878        match serde_json::from_value(v) {
879            Ok(retry) => policy.retry = retry,
880            Err(e) => push(Diagnostic::error("invalid-value", at, format!("invalid `retry`: {e}"))),
881        }
882    } else if let Some(serde_json::Value::Object(cfg)) = obj.remove("retry_config") {
883        let enabled = cfg.get("retry_enabled").and_then(serde_json::Value::as_bool).unwrap_or(false);
884        if enabled {
885            policy.retry.max_retries = cfg
886                .get("max_retries")
887                .and_then(serde_json::Value::as_u64)
888                .and_then(|n| u32::try_from(n).ok())
889                .unwrap_or(0);
890            policy.retry.interval_ms = cfg.get("retry_interval").and_then(serde_json::Value::as_u64).unwrap_or(0);
891        }
892    }
893    match obj.remove("timeout_ms") {
894        None | Some(serde_json::Value::Null) => {}
895        Some(v) => match v.as_u64() {
896            Some(ms) => policy.timeout_ms = Some(ms),
897            None => push(Diagnostic::error(
898                "invalid-value",
899                path.key("timeout_ms"),
900                format!("timeout_ms must be a non-negative integer number of milliseconds, got {v}"),
901            )),
902        },
903    }
904    for k in POLICY_KEYS {
905        obj.remove(*k);
906    }
907    policy
908}
909
910/// Default values may arrive as JSON-encoded strings for non-string types.
911fn default_value(declared: &str, value: serde_json::Value) -> Value {
912    match (declared, value) {
913        ("string", v) => Value::from_json(v),
914        (_, serde_json::Value::String(s)) => match serde_json::from_str::<serde_json::Value>(&s) {
915            Ok(parsed) => Value::from_json(parsed),
916            Err(_) => Value::from(s),
917        },
918        (_, v) => Value::from_json(v),
919    }
920}
921
922#[cfg(test)]
923mod tests {
924    use super::*;
925
926    #[test]
927    fn parses_flat_layout() {
928        let doc = Workflow::from_json(
929            r#"{"graph":{"nodes":[{"id":"s","type":"start","variables":[]},
930                {"id":"h","type":"http-request","retry":{"max_retries":2,"interval_ms":10},"timeout_ms":500}],
931                "edges":[{"source":"s","target":"h"}]}}"#,
932        );
933        let doc = doc.unwrap();
934        assert_eq!(doc.graph.nodes.len(), 2);
935        let h = &doc.graph.nodes[1];
936        assert_eq!(h.policy.retry.max_retries, 2);
937        assert_eq!(h.policy.timeout_ms, Some(500));
938        assert!(!h.config.contains_key("retry"));
939    }
940
941    #[test]
942    fn parses_data_wrapper_layout() {
943        let doc = Workflow::from_json(
944            r#"{"workflow":{"environment_variables":[{"name":"K","value_type":"secret","value":"x"}],
945              "graph":{"nodes":[
946                {"id":"a","type":"custom","data":{"type":"llm","title":"LLM","error_strategy":"default-value",
947                  "default_value":[{"key":"n","type":"number","value":"42"}],
948                  "retry_config":{"retry_enabled":true,"max_retries":3,"retry_interval":100}}},
949                {"id":"b","type":"custom","parentId":"it","data":{"type":"code"}},
950                {"id":"note","type":"custom-note","data":{"type":"custom-note"}}],
951              "edges":[{"source":"a","target":"b","sourceHandle":"source"}]}}}"#,
952        );
953        let doc = doc.unwrap();
954        assert_eq!(doc.env.len(), 1);
955        assert_eq!(doc.env[0].ty, ValueType::Secret);
956        assert_eq!(doc.graph.nodes.len(), 2);
957        let a = &doc.graph.nodes[0];
958        assert_eq!(a.kind, "llm");
959        assert_eq!(a.title.as_deref(), Some("LLM"));
960        assert_eq!(a.policy.retry.max_retries, 3);
961        match &a.policy.on_error {
962            ErrorStrategy::DefaultValue { values } => assert_eq!(values.get("n"), Some(&Value::Int(42))),
963            other => panic!("unexpected {other:?}"),
964        }
965        assert_eq!(doc.graph.nodes[1].parent.as_deref(), Some("it"));
966        assert_eq!(doc.graph.edges[0].handle.as_deref(), Some("source"));
967    }
968
969    #[test]
970    fn backoff_delay() {
971        let p = RetryPolicy { max_retries: 3, interval_ms: 100, backoff: 2.0 };
972        assert_eq!(p.delay_ms(1), 100);
973        assert_eq!(p.delay_ms(3), 400);
974    }
975
976    #[cfg(feature = "yaml")]
977    #[test]
978    fn parses_yaml() {
979        let doc = Workflow::parse("graph:\n  nodes:\n    - {id: s, type: start}\n  edges: []\n");
980        assert!(matches!(doc, Ok(d) if d.graph.nodes.len() == 1));
981    }
982
983    #[cfg(feature = "yaml")]
984    #[test]
985    fn yaml_uses_strict_booleans() {
986        let doc = Workflow::parse("graph:\n  nodes:\n    - {id: s, type: start, label: n, flag: true}\n").unwrap();
987        let cfg = &doc.graph.nodes[0].config;
988        assert_eq!(cfg.get("label"), Some(&serde_json::json!("n")));
989        assert_eq!(cfg.get("flag"), Some(&serde_json::json!(true)));
990    }
991}
992
993impl Serialize for NodeDoc {
994    fn serialize<S: serde::Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error> {
995        use serde::ser::{Error as _, SerializeMap};
996        let mut map = serializer.serialize_map(None)?;
997        map.serialize_entry("id", &self.id)?;
998        map.serialize_entry("type", &self.kind)?;
999        if let Some(title) = &self.title {
1000            map.serialize_entry("title", title)?;
1001        }
1002        if let Some(parent) = &self.parent {
1003            map.serialize_entry("parent", parent)?;
1004        }
1005        if self.policy.on_error != ErrorStrategy::Fail {
1006            map.serialize_entry("on_error", &self.policy.on_error)?;
1007        }
1008        if self.policy.retry != RetryPolicy::default() {
1009            map.serialize_entry("retry", &self.policy.retry)?;
1010        }
1011        if let Some(ms) = self.policy.timeout_ms {
1012            map.serialize_entry("timeout_ms", &ms)?;
1013        }
1014        for (key, value) in &self.config {
1015            if matches!(key.as_str(), "id" | "type" | "title" | "parent") || POLICY_KEYS.contains(&key.as_str()) {
1016                return Err(S::Error::custom(format!("node `{}`: config key `{key}` is reserved", self.id)));
1017            }
1018            map.serialize_entry(key, value)?;
1019        }
1020        map.end()
1021    }
1022}
1023
1024impl Workflow {
1025    /// Serialize to JSON in the same layout [`Workflow::from_json`] accepts.
1026    pub fn to_json(&self) -> Result<String, DocumentError> {
1027        Ok(serde_json::to_string(self)?)
1028    }
1029
1030    /// Canonical JSON of the graph section (object keys sorted recursively).
1031    /// Used for fingerprints, so key order in the source document does not matter.
1032    pub fn canonical_graph_json(&self) -> Result<String, DocumentError> {
1033        let value = serde_json::to_value(&self.graph)?;
1034        Ok(serde_json::to_string(&canonicalize(value))?)
1035    }
1036}
1037
1038/// Recursively sort object keys.
1039fn canonicalize(value: serde_json::Value) -> serde_json::Value {
1040    match value {
1041        serde_json::Value::Object(map) => {
1042            let mut entries: Vec<(String, serde_json::Value)> = map.into_iter().collect();
1043            entries.sort_by(|a, b| a.0.cmp(&b.0));
1044            serde_json::Value::Object(entries.into_iter().map(|(k, v)| (k, canonicalize(v))).collect())
1045        }
1046        serde_json::Value::Array(items) => serde_json::Value::Array(items.into_iter().map(canonicalize).collect()),
1047        other => other,
1048    }
1049}
1050
1051#[cfg(test)]
1052mod roundtrip_tests {
1053    use super::*;
1054
1055    const DOC: &str = r#"{"name":"demo","env":[{"name":"K","type":"secret"}],"graph":{"nodes":[
1056        {"id":"s","type":"start","variables":[]},
1057        {"id":"h","type":"custom","data":{"type":"http-request","title":"Call","url":"https://x",
1058          "error_strategy":"default-value","default_value":{"body":"none"},
1059          "retry_config":{"retry_enabled":true,"max_retries":2,"retry_interval":10},"timeout_ms":500}},
1060        {"id":"b","type":"code","parentId":"it"}],
1061        "edges":[{"source":"s","target":"h","sourceHandle":"source"}]}}"#;
1062
1063    #[test]
1064    fn workflow_round_trips() {
1065        let a = Workflow::from_json(DOC).unwrap();
1066        let text = a.to_json().unwrap();
1067        let b = Workflow::from_json(&text).unwrap();
1068        assert_eq!(text, b.to_json().unwrap());
1069        let h = &b.graph.nodes[1];
1070        assert_eq!(h.kind, "http-request");
1071        assert_eq!(h.title.as_deref(), Some("Call"));
1072        assert_eq!(h.policy, a.graph.nodes[1].policy);
1073        assert_eq!(h.policy.timeout_ms, Some(500));
1074        assert_eq!(h.config.get("url"), Some(&serde_json::json!("https://x")));
1075        assert!(!h.config.contains_key("config"));
1076        assert_eq!(b.graph.nodes[2].parent.as_deref(), Some("it"));
1077        assert_eq!(a.canonical_graph_json().unwrap(), b.canonical_graph_json().unwrap());
1078    }
1079
1080    #[test]
1081    fn canonical_json_ignores_key_order() {
1082        let a = Workflow::from_json(r#"{"graph":{"nodes":[{"id":"s","type":"start","x":1,"y":2}],"edges":[]}}"#);
1083        let b = Workflow::from_json(r#"{"graph":{"nodes":[{"y":2,"x":1,"type":"start","id":"s"}],"edges":[]}}"#);
1084        assert_eq!(a.unwrap().canonical_graph_json().unwrap(), b.unwrap().canonical_graph_json().unwrap());
1085    }
1086
1087    #[test]
1088    fn typos_are_errors() {
1089        let bad_strategy = r#"{"graph":{"nodes":[{"id":"s","type":"start","error_strategy":"fail-brnch"}]}}"#;
1090        assert!(matches!(Workflow::from_json(bad_strategy), Err(DocumentError::Node { .. })));
1091        let bad_timeout = r#"{"graph":{"nodes":[{"id":"s","type":"start","timeout_ms":"5s"}]}}"#;
1092        assert!(matches!(Workflow::from_json(bad_timeout), Err(DocumentError::Node { .. })));
1093        let none = r#"{"graph":{"nodes":[{"id":"s","type":"start","error_strategy":"none"}]}}"#;
1094        assert!(Workflow::from_json(none).is_ok());
1095    }
1096}