Skip to main content

graphrt_core/
snapshot.rs

1//! Persistable run state for pause / resume.
2//!
3//! A snapshot never contains the graph, environment variables or secrets. To
4//! resume, the host rebuilds the same graph (checked via
5//! [`Snapshot::graph_fingerprint`]) and supplies env variables again.
6
7use indexmap::IndexMap;
8use serde::{Deserialize, Serialize};
9
10use crate::event::Usage;
11use crate::pool::{PoolSnapshot, Selector};
12use crate::value::Value;
13
14/// Current snapshot format version.
15pub const SNAPSHOT_FORMAT: u32 = 1;
16
17/// Complete persisted state of a paused run.
18#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
19pub struct Snapshot {
20    pub format: u32,
21    pub run_id: String,
22    /// Fingerprint of the graph the snapshot was taken from.
23    pub graph_fingerprint: String,
24    pub elapsed_ms: u64,
25    pub steps: u64,
26    pub usage: Usage,
27    pub handled_errors: u32,
28    pub root: FrameSnapshot,
29}
30
31/// Persisted state of one execution frame (the root graph, or one container body run).
32#[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize)]
33pub struct FrameSnapshot {
34    pub pool: PoolSnapshot,
35    /// Per-node state, keyed by node id. Nodes absent from the map have not been reached.
36    pub nodes: IndexMap<String, NodeSnapshot>,
37    /// Edge states, keyed by edge id.
38    pub edges: IndexMap<String, EdgeStatus>,
39    /// Accumulated response outputs of this frame (answer text, end outputs).
40    pub outputs: IndexMap<String, Value>,
41    /// Writes to namespaces outside this frame's scope, in commit order (child frames only).
42    #[serde(default, skip_serializing_if = "Vec::is_empty")]
43    pub writes: Vec<(Selector, Value)>,
44    /// Whether a `loop-end` node completed in this frame.
45    #[serde(default, skip_serializing_if = "std::ops::Not::not")]
46    pub broke: bool,
47    /// Usage accumulated by this frame's nodes.
48    #[serde(default)]
49    pub usage: Usage,
50}
51
52/// Lifecycle state of a node inside a frame.
53#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
54#[serde(rename_all = "snake_case")]
55#[non_exhaustive]
56pub enum NodeStatus {
57    /// Ready to run (or was running when the frame paused and must be re-run).
58    Pending,
59    /// Paused by the node itself; it will be resumed with its saved state.
60    Paused,
61    Succeeded,
62    Failed,
63    Skipped,
64}
65
66/// Persisted state of one node.
67#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
68pub struct NodeSnapshot {
69    pub status: NodeStatus,
70    pub exec_id: String,
71    pub attempt: u32,
72    /// Node-owned resume state (for nodes that paused themselves, e.g. human input
73    /// or a container holding the snapshots of its child frames).
74    #[serde(default, skip_serializing_if = "Option::is_none")]
75    pub resume_state: Option<serde_json::Value>,
76}
77
78/// Traversal state of an edge.
79#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
80#[serde(rename_all = "snake_case")]
81#[non_exhaustive]
82pub enum EdgeStatus {
83    Unknown,
84    Taken,
85    Skipped,
86}
87
88impl Snapshot {
89    /// Encode as JSON.
90    pub fn to_json(&self) -> Result<String, serde_json::Error> {
91        serde_json::to_string(self)
92    }
93
94    /// Decode from JSON.
95    pub fn from_json(text: &str) -> Result<Self, serde_json::Error> {
96        serde_json::from_str(text)
97    }
98}