Skip to main content

qualia_client_core/wellfair/
checkpoint_store.rs

1//! Durable WellFair checkpoint metadata, DAG history, and `.q42` volume snapshots.
2
3use std::fs;
4use std::path::Path;
5use std::time::{SystemTime, UNIX_EPOCH};
6
7use qualia_core_db::git_bridge::DagStore;
8use qualia_core_db::NQuin;
9use serde::{Deserialize, Serialize};
10
11pub const CHECKPOINT_DIR: &str = "wellfair/checkpoint";
12pub const META_FILE: &str = "wellfair/checkpoint/meta.json";
13pub const DAG_FILE: &str = "wellfair/checkpoint/dag.bin";
14pub const Q42_FILE: &str = "wellfair/checkpoint/vault.q42";
15
16#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
17pub struct CheckpointMeta {
18    pub last_hash_hex: String,
19    pub dag_node_count: u32,
20    pub graph_quin_count: u32,
21    pub checkpoint_unix: u32,
22}
23
24impl Default for CheckpointMeta {
25    fn default() -> Self {
26        Self {
27            last_hash_hex: String::new(),
28            dag_node_count: 0,
29            graph_quin_count: 0,
30            checkpoint_unix: 0,
31        }
32    }
33}
34
35/// Loads meta.
36pub fn load_meta(storage_root: impl AsRef<Path>) -> Option<CheckpointMeta> {
37    let path = storage_root.as_ref().join(META_FILE);
38    let text = fs::read_to_string(path).ok()?;
39    serde_json::from_str(&text).ok()
40}
41
42/// Saves meta.
43pub fn save_meta(storage_root: impl AsRef<Path>, meta: &CheckpointMeta) -> std::io::Result<()> {
44    let path = storage_root.as_ref().join(META_FILE);
45    ensure_parent(&path)?;
46    let text =
47        serde_json::to_string_pretty(meta).map_err(|e| std::io::Error::other(e.to_string()))?;
48    fs::write(path, text)
49}
50
51/// Loads dag.
52pub fn load_dag(storage_root: impl AsRef<Path>) -> DagStore {
53    let path = storage_root.as_ref().join(DAG_FILE);
54    match fs::read(&path) {
55        Ok(bytes) => DagStore::deserialize(&bytes).unwrap_or_default(),
56        Err(_) => DagStore::new(),
57    }
58}
59
60/// Saves dag.
61pub fn save_dag(storage_root: impl AsRef<Path>, dag: &DagStore) -> std::io::Result<()> {
62    let path = storage_root.as_ref().join(DAG_FILE);
63    ensure_parent(&path)?;
64    fs::write(path, dag.serialize())
65}
66
67/// Persists a checkpoint.
68pub fn persist_checkpoint(
69    storage_root: impl AsRef<Path>,
70    dag: &DagStore,
71    hash: [u8; 32],
72    graph_quin_count: usize,
73    batch_quins: &[NQuin],
74    author_did: u64,
75) -> std::io::Result<()> {
76    save_dag(&storage_root, dag)?;
77    let meta = CheckpointMeta {
78        last_hash_hex: hex::encode(hash),
79        dag_node_count: dag.nodes().len() as u32,
80        graph_quin_count: graph_quin_count as u32,
81        checkpoint_unix: SystemTime::now()
82            .duration_since(UNIX_EPOCH)
83            .map(|d| d.as_secs() as u32)
84            .unwrap_or(0),
85    };
86    save_meta(storage_root.as_ref(), &meta)?;
87    write_q42_checkpoint(storage_root.as_ref(), batch_quins, author_did)
88}
89
90#[cfg(not(target_arch = "wasm32"))]
91/// Writes a q42 checkpoint.
92pub fn write_q42_checkpoint(
93    storage_root: &Path,
94    quins: &[NQuin],
95    author_did: u64,
96) -> std::io::Result<()> {
97    if quins.is_empty() {
98        return Ok(());
99    }
100    let path = storage_root.join(Q42_FILE);
101    qualia_core_db::q42_volume::write_sorted_quins_volume_with_author(&path, quins, author_did)?;
102    Ok(())
103}
104
105#[cfg(target_arch = "wasm32")]
106/// Writes a q42 checkpoint.
107pub fn write_q42_checkpoint(
108    _storage_root: &Path,
109    _quins: &[NQuin],
110    _author_did: u64,
111) -> std::io::Result<()> {
112    Ok(())
113}
114
115fn ensure_parent(path: &Path) -> std::io::Result<()> {
116    if let Some(parent) = path.parent() {
117        fs::create_dir_all(parent)?;
118    }
119    Ok(())
120}
121
122#[cfg(test)]
123mod tests {
124    use super::*;
125
126    #[test]
127    fn checkpoint_meta_round_trip() {
128        let dir = tempfile::tempdir().unwrap();
129        let meta = CheckpointMeta {
130            last_hash_hex: "abc123".into(),
131            dag_node_count: 2,
132            graph_quin_count: 10,
133            checkpoint_unix: 1_700_000_000,
134        };
135        save_meta(dir.path(), &meta).unwrap();
136        assert_eq!(load_meta(dir.path()), Some(meta));
137    }
138
139    #[test]
140    fn dag_persist_round_trip() {
141        let dir = tempfile::tempdir().unwrap();
142        let mut dag = DagStore::new();
143        dag.genesis_node(&[], 42, 1000, "genesis");
144        save_dag(dir.path(), &dag).unwrap();
145        let restored = load_dag(dir.path());
146        assert_eq!(restored.nodes().len(), 1);
147    }
148}