zeph_db/
graph_store.rs

1// SPDX-FileCopyrightText: 2026 Andrei G <bug-ops>
2// SPDX-License-Identifier: MIT OR Apache-2.0
3
4//! Raw graph persistence trait used by the orchestration layer.
5//!
6//! This module contains only the interface (`RawGraphStore`) and metadata types
7//! (`GraphSummary`). The concrete SQLite/PostgreSQL implementation lives in
8//! `zeph-memory::store::graph_store::TaskGraphStore`.
9
10use crate::error::DbError;
11
12/// Summary of a stored task graph (metadata columns only, no full JSON blob).
13///
14/// Returned by [`RawGraphStore::list_graphs`] for listing and filtering without
15/// deserializing the full graph JSON.
16#[derive(Debug, Clone)]
17pub struct GraphSummary {
18    /// String UUID of the graph.
19    pub id: String,
20    /// High-level user goal that was decomposed into this graph.
21    pub goal: String,
22    /// Lifecycle status string (e.g. `"completed"`, `"failed"`).
23    pub status: String,
24    /// ISO-8601 UTC creation timestamp.
25    pub created_at: String,
26    /// ISO-8601 UTC terminal timestamp, or `None` if the graph has not finished.
27    pub finished_at: Option<String>,
28}
29
30/// Raw persistence interface for task graphs.
31///
32/// All graph data is stored as an opaque JSON blob. The orchestration layer in
33/// `zeph-core` / `zeph-orchestration` is responsible for serializing and
34/// deserializing `TaskGraph` values.
35#[allow(async_fn_in_trait)]
36pub trait RawGraphStore: Send + Sync {
37    /// Persist a graph (upsert by `id`).
38    ///
39    /// # Errors
40    ///
41    /// Returns [`DbError`] on database failure.
42    async fn save_graph(
43        &self,
44        id: &str,
45        goal: &str,
46        status: &str,
47        graph_json: &str,
48        created_at: &str,
49        finished_at: Option<&str>,
50    ) -> Result<(), DbError>;
51
52    /// Load a graph by its string UUID.
53    ///
54    /// Returns `None` if the graph does not exist.
55    ///
56    /// # Errors
57    ///
58    /// Returns [`DbError`] on database failure.
59    async fn load_graph(&self, id: &str) -> Result<Option<String>, DbError>;
60
61    /// List graphs ordered by `created_at` descending, limited to `limit` rows.
62    ///
63    /// # Errors
64    ///
65    /// Returns [`DbError`] on database failure.
66    async fn list_graphs(&self, limit: u32) -> Result<Vec<GraphSummary>, DbError>;
67
68    /// Delete a graph by its string UUID.
69    ///
70    /// Returns `true` if a row was deleted.
71    ///
72    /// # Errors
73    ///
74    /// Returns [`DbError`] on database failure.
75    async fn delete_graph(&self, id: &str) -> Result<bool, DbError>;
76}
zeph_db/graph_store.rs

zeph_db/
graph_store.rs
