Skip to main content

agentstategraph_storage/
traits.rs

1//! Storage trait definitions — the pluggable backend contract.
2//!
3//! Any backend that implements these traits can be used with AgentStateGraph.
4//! The in-memory and SQLite backends are provided; custom backends
5//! can be added by implementing these traits.
6
7use agentstategraph_core::{Commit, Epoch, Namespace, Object, ObjectId, Session, SessionStatus};
8use agentstategraph_reminders::ReminderStore;
9use chrono::{DateTime, Utc};
10
11/// Errors from storage operations.
12#[derive(Debug, thiserror::Error)]
13pub enum StorageError {
14    #[error("object not found: {0}")]
15    ObjectNotFound(String),
16
17    #[error("commit not found: {0}")]
18    CommitNotFound(String),
19
20    #[error("ref not found: {0}")]
21    RefNotFound(String),
22
23    #[error("namespace not found: '{0}' (create it with create_namespace before writing refs)")]
24    NamespaceNotFound(String),
25
26    #[error("namespace already exists: '{0}'")]
27    NamespaceAlreadyExists(String),
28
29    #[error("CAS conflict: ref '{name}' expected {expected}, found {actual}")]
30    CasConflict {
31        name: String,
32        expected: String,
33        actual: String,
34    },
35
36    #[error("duplicate ref: {0}")]
37    DuplicateRef(String),
38
39    #[error("storage backend error: {0}")]
40    Backend(String),
41
42    #[error("serialization error: {0}")]
43    Serialization(String),
44
45    #[error("epoch '{id}' is already sealed")]
46    EpochAlreadySealed { id: String },
47
48    #[error("session '{id}' has already ended")]
49    SessionEnded { id: String },
50
51    #[error("invalid operation: {0}")]
52    InvalidOperation(String),
53
54    /// The database was set up by a newer build whose schema this one can't
55    /// use: it needs a build that understands at least `compatible_from`, and
56    /// this one understands up to `supported`. Nothing was changed. (DESIGN.md
57    /// Plan F t-009.)
58    #[error(
59        "the {backend} database is at schema version {found}, which needs a build that understands version {compatible_from} or later; this build understands up to {supported}. Upgrade AgentStateGraph"
60    )]
61    SchemaTooNew {
62        backend: &'static str,
63        found: i32,
64        compatible_from: i32,
65        supported: i32,
66    },
67}
68
69impl StorageError {
70    /// A stable, low-cardinality code for this kind of error (DESIGN.md Plan
71    /// H t-004): for API responses, `error.type` on spans and metrics, and
72    /// for clients to branch on instead of the message.
73    pub fn code(&self) -> &'static str {
74        match self {
75            StorageError::ObjectNotFound(_) => "object_not_found",
76            StorageError::CommitNotFound(_) => "commit_not_found",
77            StorageError::RefNotFound(_) => "ref_not_found",
78            StorageError::NamespaceNotFound(_) => "namespace_not_found",
79            StorageError::NamespaceAlreadyExists(_) => "namespace_already_exists",
80            StorageError::CasConflict { .. } => "write_conflict",
81            StorageError::DuplicateRef(_) => "ref_already_exists",
82            StorageError::Backend(_) => "storage_error",
83            StorageError::Serialization(_) => "serialization_error",
84            StorageError::EpochAlreadySealed { .. } => "epoch_sealed",
85            StorageError::SessionEnded { .. } => "session_ended",
86            StorageError::InvalidOperation(_) => "invalid_operation",
87            StorageError::SchemaTooNew { .. } => "schema_too_new",
88        }
89    }
90}
91
92/// Content-addressed object storage.
93/// Objects are stored and retrieved by their BLAKE3 hash (ObjectId).
94pub trait ObjectStore: Send + Sync {
95    /// Retrieve an object by its ID. Returns None if not found.
96    fn get_object(&self, id: &ObjectId) -> Result<Option<Object>, StorageError>;
97
98    /// Store an object. Returns its ObjectId (which is its content hash).
99    /// Storing an object that already exists is a no-op (idempotent).
100    fn put_object(&self, obj: &Object) -> Result<ObjectId, StorageError>;
101
102    /// Check if an object exists in the store.
103    fn has_object(&self, id: &ObjectId) -> Result<bool, StorageError>;
104
105    /// Retrieve multiple objects at once. Returns None for missing objects.
106    fn batch_get_objects(&self, ids: &[ObjectId]) -> Result<Vec<Option<Object>>, StorageError> {
107        // Default implementation: sequential gets. Backends can optimize.
108        ids.iter().map(|id| self.get_object(id)).collect()
109    }
110
111    /// Store multiple objects at once. Returns their ObjectIds.
112    fn batch_put_objects(&self, objs: &[Object]) -> Result<Vec<ObjectId>, StorageError> {
113        // Default implementation: sequential puts. Backends can optimize.
114        objs.iter().map(|obj| self.put_object(obj)).collect()
115    }
116
117    // ---- Optional leaf-value index (plan perf-slow-endpoints t-006) ----
118    //
119    // An optional, backend-provided index over the string leaves of a ref's
120    // tree, keyed by `(namespace, ref)` and maintained in place: a one-time
121    // backfill, then incremental add/remove as the ref advances. It turns value
122    // search from an un-indexed full DFS (linear in graph size; multi-second on
123    // a large ref) into a trigram substring probe. A backend that does not
124    // implement it reports "not indexed" so callers fall back to the tree walk,
125    // making the whole feature purely additive.
126
127    /// Whether the `(namespace, ref)` leaf set has been built.
128    fn leaf_index_is_built(&self, _namespace: &str, _ref_name: &str) -> Result<bool, StorageError> {
129        Ok(false)
130    }
131
132    /// One-time backfill: replace any existing rows for `(namespace, ref)` with
133    /// `entries` and mark the set built. Called once, from the read path, the
134    /// first time a ref is searched after the feature is enabled.
135    fn leaf_index_build(
136        &self,
137        _namespace: &str,
138        _ref_name: &str,
139        _entries: &[(String, String)],
140    ) -> Result<(), StorageError> {
141        Ok(())
142    }
143
144    /// Incremental maintenance: for a built `(namespace, ref)`, delete the rows
145    /// at `removed_paths` and insert `added` `(path, value)` rows. A no-op if
146    /// the set has not been built (the backfill will pick up the new state).
147    /// Called from the write path as a ref advances.
148    fn leaf_index_apply(
149        &self,
150        _namespace: &str,
151        _ref_name: &str,
152        _removed_paths: &[String],
153        _added: &[(String, String)],
154    ) -> Result<(), StorageError> {
155        Ok(())
156    }
157
158    /// Substring-search the built leaves of `(namespace, ref)`. `Ok(None)` means
159    /// the set is not built / backend has no index (caller falls back to the
160    /// tree walk); `Ok(Some(..))` is authoritative (possibly empty), capped at
161    /// `limit`.
162    fn leaf_index_search(
163        &self,
164        _namespace: &str,
165        _ref_name: &str,
166        _query_lower: &str,
167        _limit: usize,
168    ) -> Result<Option<Vec<(String, String)>>, StorageError> {
169        Ok(None)
170    }
171
172    // ---- Which tree a leaf set reflects (Plan D t-008) ----
173    //
174    // `leaf_index_apply` applies diffs in whatever order writers reach it. Two
175    // writers advancing one ref can apply theirs out of order, and the set
176    // then keeps a value that was overwritten. A backend that records the
177    // state root each set reflects avoids this: a diff applies only to the
178    // tree it was computed from, and a reader can check the set is current
179    // before trusting it, and catch it up when it isn't.
180
181    /// Whether this backend records the state root of each built set, through
182    /// [`leaf_index_root`](Self::leaf_index_root),
183    /// [`leaf_index_build_at`](Self::leaf_index_build_at) and
184    /// [`leaf_index_advance`](Self::leaf_index_advance).
185    fn leaf_index_tracks_roots(&self) -> bool {
186        false
187    }
188
189    /// The state root the `(namespace, ref)` set reflects. `None` when it
190    /// isn't built, was built or changed without a root, or the backend
191    /// doesn't record roots.
192    fn leaf_index_root(
193        &self,
194        _namespace: &str,
195        _ref_name: &str,
196    ) -> Result<Option<ObjectId>, StorageError> {
197        Ok(None)
198    }
199
200    /// [`leaf_index_build`](Self::leaf_index_build) from the tree at `root`,
201    /// recording `root`.
202    fn leaf_index_build_at(
203        &self,
204        namespace: &str,
205        ref_name: &str,
206        _root: &ObjectId,
207        entries: &[(String, String)],
208    ) -> Result<(), StorageError> {
209        self.leaf_index_build(namespace, ref_name, entries)
210    }
211
212    /// Move the set from the tree at `from` to the tree at `to`, by the leaf
213    /// diff between them, only if it is at `from`. Returns whether it moved.
214    /// A backend that doesn't record roots applies the diff unconditionally,
215    /// as [`leaf_index_apply`](Self::leaf_index_apply), and returns `true`.
216    fn leaf_index_advance(
217        &self,
218        namespace: &str,
219        ref_name: &str,
220        _from: &ObjectId,
221        _to: &ObjectId,
222        removed_paths: &[String],
223        added: &[(String, String)],
224    ) -> Result<bool, StorageError> {
225        self.leaf_index_apply(namespace, ref_name, removed_paths, added)?;
226        Ok(true)
227    }
228}
229
230/// One row of the commit-history rollup (Plan A t-001): commit activity for a
231/// single (day, namespace, agent, intent category) bucket.
232#[derive(Debug, Clone, PartialEq)]
233pub struct HistoryRollupRow {
234    pub day: String,
235    pub namespace: String,
236    pub agent_id: String,
237    pub intent_category: String,
238    pub commit_count: i64,
239    pub first_ts: String,
240    pub last_ts: String,
241}
242
243/// One milestone on the distilled history timeline (Plan A t-001).
244///
245/// `state_root` (Plan A t-005) names the snapshot the milestone preserves — the
246/// retention hook Plan B's GC keeps reachable. It is `None` for a milestone that
247/// pins nothing, which is the default: a checkpoint pins its snapshot only when
248/// its intent carries `TAG_PIN_STATE`. (Rows written before t-005 are also
249/// `None`, for the older reason that the column did not exist.) An unpinned
250/// milestone is still a full timeline entry; it just names no snapshot, so a
251/// sweep may reclaim the objects behind it.
252///
253/// `git_sha` is the external revision the commit corresponds to, lifted from the
254/// intent's `TAG_GIT_REVISION` tag. It is what keeps an unpinned milestone
255/// actionable: the snapshot is gone, but the revision that produced it is
256/// recorded, so derived state can be rebuilt from source.
257#[derive(Debug, Clone, PartialEq)]
258pub struct HistoryMilestoneRow {
259    pub commit_id: ObjectId,
260    pub kind: String,
261    pub timestamp: String,
262    pub day: String,
263    pub namespace: String,
264    pub agent_id: String,
265    pub description: String,
266    pub state_root: Option<ObjectId>,
267    pub git_sha: Option<String>,
268}
269
270/// Per-table on-disk size (Plan A t-003), largest first.
271#[derive(Debug, Clone, PartialEq)]
272pub struct TableBytes {
273    pub name: String,
274    pub bytes: i64,
275}
276
277/// Physical shape of the store (Plan A t-003) — the evidence surface Plan B's
278/// GC keys its retention thresholds off: how many objects/commits, how many
279/// bytes, and where they live. `tables` is populated from SQLite's `dbstat`
280/// virtual table when the build exposes it; otherwise only `total_bytes`
281/// (page_count × page_size) is available and `dbstat_available` is false.
282/// Postgres always reports per-table sizes (`dbstat_available` is true): the
283/// bytes the tenant's rows take, since the tables are shared by tenants.
284#[derive(Debug, Clone, Default, PartialEq)]
285pub struct StoreShape {
286    pub objects: i64,
287    pub commits: i64,
288    pub total_bytes: i64,
289    pub tables: Vec<TableBytes>,
290    pub dbstat_available: bool,
291}
292
293/// The trace a commit was made in (DESIGN.md Plan H t-009), as W3C trace
294/// context ids in lowercase hex. It's kept beside the commit, never in it, so
295/// commit ids and sync bundles don't depend on telemetry.
296#[derive(Debug, Clone, PartialEq, Eq)]
297pub struct CommitTrace {
298    /// The trace: 32 hex characters.
299    pub trace_id: String,
300    /// The span that made the commit: 16 hex characters.
301    pub span_id: String,
302}
303
304/// A store's totals, cheap enough to sample on an interval for the store
305/// gauges (DESIGN.md Plan H t-008). Unlike [`StoreShape`], there is no
306/// per-table breakdown, which reads every page.
307#[derive(Debug, Clone, Default, PartialEq, Eq)]
308pub struct StoreTotals {
309    pub objects: i64,
310    pub commits: i64,
311    /// The store's size on disk, where it has a file of its own (SQLite);
312    /// `None` in memory or in a database tenants share (Postgres).
313    pub bytes: Option<i64>,
314}
315
316/// Result of a GC reachability mark (Plan B t-001): how many objects are live
317/// (reachable from the given roots) vs. total, and the reclaimable remainder.
318#[derive(Debug, Clone, Default, PartialEq, Eq)]
319pub struct GcReachability {
320    pub total_objects: i64,
321    pub live_objects: i64,
322    pub reclaimable_objects: i64,
323    /// Root state roots the mark started from.
324    pub roots_walked: usize,
325}
326
327/// Result of a `VACUUM` (Plan B t-004): on-disk bytes before/after and the
328/// space returned to the OS.
329#[derive(Debug, Clone, Default, PartialEq, Eq)]
330pub struct VacuumStats {
331    pub bytes_before: i64,
332    pub bytes_after: i64,
333    pub bytes_reclaimed: i64,
334}
335
336/// Result of a GC sweep (Plan B t-003): how many objects were deleted.
337#[derive(Debug, Clone, Default, PartialEq, Eq)]
338pub struct GcSweep {
339    pub objects_before: i64,
340    pub objects_deleted: i64,
341    pub objects_after: i64,
342    /// Objects the sweep set out to delete (unreachable from the keep-set).
343    /// Equals `objects_deleted` on a complete run.
344    pub deleted_target: i64,
345}
346
347/// Default GC grace period for the SQL backends: a sweep spares unreachable
348/// objects written more recently than this. Every write stores its new
349/// objects before it commits them, so without it a sweep that runs in between
350/// takes a write in flight. See `with_gc_grace` on each backend.
351pub const DEFAULT_GC_GRACE: std::time::Duration = std::time::Duration::from_secs(10 * 60);
352
353/// A stored object that is stored again has its write time refreshed once it
354/// is older than this, so it falls inside any grace period at least this long
355/// (and an object stored over and over isn't rewritten each time).
356pub const GC_FRESHEN_AFTER: std::time::Duration = std::time::Duration::from_secs(60);
357
358/// Namespace recorded for a distilled commit whose namespace could not be
359/// established.
360///
361/// The history extractor attributes a commit through its session's
362/// `scope_namespace`. A commit made outside a scoped session has no such row,
363/// and the extractor used to fall back to `"default"` — which is itself a real
364/// namespace name, so a fallback was indistinguishable from a genuine
365/// attribution. On a store where nothing writes sessions that silently filed
366/// every commit under `"default"`.
367///
368/// Sentinel rather than NULL because `asg_history_commit_rollup.namespace` is
369/// `NOT NULL` and part of the primary key.
370pub const HISTORY_NAMESPACE_UNKNOWN: &str = "unattributed";
371
372/// Outcome of a full-DAG commit walk ([`CommitStore::list_commits_dag`]).
373// No `Eq`: `Commit` is only `PartialEq`.
374#[derive(Debug, Clone, Default, PartialEq)]
375pub struct CommitWalk {
376    /// Commits reached, in breadth-first order from the starting commit.
377    /// Deduplicated: a merge reachable down both sides appears once.
378    pub commits: Vec<Commit>,
379    /// True when `limit` stopped the walk with parents still unexplored.
380    ///
381    /// This is the difference between "that is all of them" and "there are
382    /// more" — without it a caller cannot tell a complete small history from
383    /// a truncated large one, and both look like success.
384    pub truncated: bool,
385}
386
387/// Commit storage. Commits are also content-addressed but stored
388/// separately from objects for efficient history queries.
389pub trait CommitStore: Send + Sync {
390    /// Retrieve a commit by its ID.
391    fn get_commit(&self, id: &ObjectId) -> Result<Option<Commit>, StorageError>;
392
393    /// Store a commit.
394    fn put_commit(&self, commit: &Commit) -> Result<(), StorageError>;
395
396    /// Check if a commit exists.
397    fn has_commit(&self, id: &ObjectId) -> Result<bool, StorageError>;
398
399    /// List commits reachable from a given commit, in reverse chronological order.
400    /// Returns at most `limit` commits.
401    fn list_commits(&self, from: &ObjectId, limit: usize) -> Result<Vec<Commit>, StorageError>;
402
403    /// Walk **every** parent edge from `from`, not just the first.
404    ///
405    /// [`CommitStore::list_commits`] follows `parents[0]`, which is a
406    /// first-parent line: on a store with merges it silently under-reports.
407    /// Measured on the asd store, the first-parent walk reached 4,268 of
408    /// 5,896 commits — the 1,628 it missed being merge second-parents and
409    /// commits no longer reachable from the ref head, which is exactly the
410    /// population a "what would a prune take?" view most needs to see.
411    ///
412    /// `list_commits` is deliberately left alone: a first-parent line is a
413    /// defensible thing to want, and widening it in place would change output
414    /// for every existing caller.
415    ///
416    /// A parent that is absent from the store ends that edge and the walk
417    /// continues — a pruned commit is expected in a swept store, not an error.
418    ///
419    /// The default implementation is a breadth-first walk over
420    /// [`CommitStore::get_commit`], so every backend gets it without change.
421    /// A backend able to do this in one query should override it.
422    fn list_commits_dag(&self, from: &ObjectId, limit: usize) -> Result<CommitWalk, StorageError> {
423        let mut seen: std::collections::HashSet<ObjectId> = std::collections::HashSet::new();
424        let mut frontier: std::collections::VecDeque<ObjectId> =
425            std::collections::VecDeque::from([*from]);
426        let mut commits = Vec::new();
427        let mut truncated = false;
428
429        while let Some(id) = frontier.pop_front() {
430            if commits.len() >= limit {
431                // We popped something, so there was still more to walk.
432                truncated = true;
433                break;
434            }
435            if !seen.insert(id) {
436                continue;
437            }
438            match self.get_commit(&id)? {
439                Some(commit) => {
440                    for p in &commit.parents {
441                        if !seen.contains(p) {
442                            frontier.push_back(*p);
443                        }
444                    }
445                    commits.push(commit);
446                }
447                // Pruned: end this edge, keep walking the rest.
448                None => continue,
449            }
450        }
451
452        Ok(CommitWalk { commits, truncated })
453    }
454
455    /// Return the ids of every commit in the store, unordered.
456    ///
457    /// Unlike [`CommitStore::list_commits`] this is NOT reachability-scoped: it
458    /// includes commits that no ref currently points at (e.g. the tip of a
459    /// deleted branch). Used for prefix-based ref resolution and for recovering
460    /// orphaned historical commits.
461    fn all_commit_ids(&self) -> Result<Vec<ObjectId>, StorageError>;
462
463    // -- Project-history metrics (Plan A t-001) ------------------------------
464    // Derived, rebuildable tables distilled from the commit chain. A backend
465    // that doesn't implement them is simply "no history" — the feature is
466    // purely additive, like `leaf_index_*`.
467
468    /// Fold the next batch of un-processed commits into the `asg_history_*`
469    /// rollup/milestone tables, advancing the stored `commits.rowid` cursor
470    /// atomically. Returns the number of commits processed this call — `0` once
471    /// the extractor has caught up. Idempotent and resumable: the cursor only
472    /// advances inside the same transaction that writes the rows, so a crash
473    /// re-processes the batch rather than double-counting it. Bounded memory:
474    /// at most `batch_size` commits are held at once.
475    fn history_extract_batch(&self, _batch_size: usize) -> Result<usize, StorageError> {
476        Ok(0)
477    }
478
479    /// The last `commits.rowid` folded into the history tables (0 = nothing
480    /// extracted yet).
481    fn history_cursor(&self) -> Result<i64, StorageError> {
482        Ok(0)
483    }
484
485    /// Read the commit-history rollup, ordered by (day, namespace, agent,
486    /// intent category).
487    fn history_rollup(&self) -> Result<Vec<HistoryRollupRow>, StorageError> {
488        Ok(Vec::new())
489    }
490
491    /// Read the milestone timeline in chronological order, most recent first,
492    /// capped at `limit`.
493    fn history_milestones(&self, _limit: usize) -> Result<Vec<HistoryMilestoneRow>, StorageError> {
494        Ok(Vec::new())
495    }
496
497    /// Measure the physical shape of the store (Plan A t-003): object/commit
498    /// counts, total bytes, and per-table bytes when the backend can report
499    /// them. Backends that can't return an empty [`StoreShape`].
500    fn history_store_shape(&self) -> Result<StoreShape, StorageError> {
501        Ok(StoreShape::default())
502    }
503
504    /// The store's totals, for the store gauges. Counting still reads every
505    /// row's key, so sample it on a slow interval. Backends that don't count
506    /// report `None`.
507    fn store_totals(&self) -> Result<Option<StoreTotals>, StorageError> {
508        Ok(None)
509    }
510
511    /// Store `commit` and, when given, the trace it was made in. A backend
512    /// that can does both in one write, which matters on every commit; the
513    /// default stores one after the other.
514    fn put_commit_traced(
515        &self,
516        commit: &Commit,
517        trace: Option<&CommitTrace>,
518    ) -> Result<(), StorageError> {
519        self.put_commit(commit)?;
520        match trace {
521            Some(trace) => self.set_commit_trace(&commit.id, trace),
522            None => Ok(()),
523        }
524    }
525
526    /// Record the trace `commit_id` was made in. The first record for a
527    /// commit stands. Backends that don't keep trace links ignore it.
528    fn set_commit_trace(
529        &self,
530        _commit_id: &ObjectId,
531        _trace: &CommitTrace,
532    ) -> Result<(), StorageError> {
533        Ok(())
534    }
535
536    /// The trace `commit_id` was made in, if one was recorded.
537    fn get_commit_trace(&self, _commit_id: &ObjectId) -> Result<Option<CommitTrace>, StorageError> {
538        Ok(None)
539    }
540
541    // -- Retention hooks for GC (Plan A t-005) ------------------------------
542
543    /// Whether `id`'s commit has been folded into the history tables — i.e. its
544    /// position is at or before the extractor cursor. This is the "already
545    /// captured" predicate Plan B's GC checks before pruning a commit's raw
546    /// snapshot: a distilled commit's signal survives in the metric tables.
547    /// Backends without history report `false` (nothing distilled → prune
548    /// nothing on this basis).
549    fn history_is_commit_distilled(&self, _id: &ObjectId) -> Result<bool, StorageError> {
550        Ok(false)
551    }
552
553    /// State roots the GC must keep reachable: the snapshots preserved by
554    /// recorded milestones (the human-meaningful spine). Distinct, order
555    /// unspecified.
556    fn history_retained_state_roots(&self) -> Result<Vec<ObjectId>, StorageError> {
557        Ok(Vec::new())
558    }
559
560    /// Count commits not yet folded into the history tables — those with a
561    /// rowid beyond the extractor cursor (Plan B t-002). `0` means the
562    /// extractor is caught up, so every commit's signal is distilled and the GC
563    /// can safely make historical state unmaterializable. Backends without
564    /// history report `0` (they have no distillation gate).
565    fn history_undistilled_commit_count(&self) -> Result<i64, StorageError> {
566        Ok(0)
567    }
568
569    /// Mark every object reachable from `roots` (state roots) and report live
570    /// vs. total object counts — the GC reclaimable estimate (Plan B t-001).
571    ///
572    /// Walks the Merkle DAG in bounded memory: the mark set is held **on disk**
573    /// (a temp table), and unexpanded nodes are drained in `batch`-sized chunks,
574    /// so a 14.8M-object store never materializes the full closure in RAM.
575    /// Backends without object storage report all-zero.
576    fn history_gc_reachability(
577        &self,
578        _roots: &[ObjectId],
579        _batch: usize,
580    ) -> Result<GcReachability, StorageError> {
581        Ok(GcReachability::default())
582    }
583
584    /// Sweep: mark the closure of `roots` and DELETE every object outside it
585    /// (Plan B t-003). Destructive; callers gate it (dry-run default, safety
586    /// predicate). Backends without object storage report an empty sweep.
587    ///
588    /// Must keep other writers' work safe from the mark to the last delete, or
589    /// a commit landing mid-sweep loses its objects. A backend can exclude
590    /// writers, or spare recent writes; Postgres does the latter (a grace
591    /// period on each object's write time, refreshed when an object is stored
592    /// again), so its writers never wait for a sweep. The SQLite backend runs the whole
593    /// sweep as one write transaction — deletes are still issued in bounded
594    /// chunks, but a crash rolls the sweep back rather than leaving it half done
595    /// — and joins the caller's transaction when
596    /// [`history_gc_lock_writers`](Self::history_gc_lock_writers) is already
597    /// held. It also keeps every current ref tip whatever `roots` says, since a
598    /// caller's roots can predate a commit made on another connection.
599    fn history_gc_sweep(
600        &self,
601        _roots: &[ObjectId],
602        _batch: usize,
603    ) -> Result<GcSweep, StorageError> {
604        Ok(GcSweep::default())
605    }
606
607    /// Take the store's write lock for a GC sweep, held until
608    /// [`history_gc_unlock_writers`](Self::history_gc_unlock_writers).
609    /// (On Postgres it is a lock against a second sweep only; writers are
610    /// kept safe by the grace period instead, and don't wait.)
611    ///
612    /// A sweep is only correct if nothing commits between the moment its
613    /// keep-set is computed and its last delete, so the caller takes this
614    /// *before* computing the keep-set. Other writers wait (up to the backend's
615    /// busy timeout) and then fail rather than interleave; readers are
616    /// unaffected — including other threads using this same handle, which must
617    /// not join the sweep's transaction (a rolled-back sweep would discard
618    /// their already-acknowledged writes). Backends with a single writer, or
619    /// no object storage, need do nothing.
620    fn history_gc_lock_writers(&self) -> Result<(), StorageError> {
621        Ok(())
622    }
623
624    /// Release the lock taken by
625    /// [`history_gc_lock_writers`](Self::history_gc_lock_writers), committing
626    /// the work done under it or rolling it back. A no-op when nothing is held.
627    fn history_gc_unlock_writers(&self, _commit: bool) -> Result<(), StorageError> {
628        Ok(())
629    }
630
631    /// Record `root` under `key` as reachable-but-uncommitted (an open
632    /// speculation's base or working tree), so a GC sweep — in this process or
633    /// any other sharing the store — keeps every object it references.
634    /// Replaces any earlier root for `key` and refreshes its age.
635    fn gc_pin_root(&self, _key: &str, _root: &ObjectId) -> Result<(), StorageError> {
636        Ok(())
637    }
638
639    /// Remove the pin recorded by [`gc_pin_root`](Self::gc_pin_root). A no-op
640    /// when absent.
641    fn gc_unpin_root(&self, _key: &str) -> Result<(), StorageError> {
642        Ok(())
643    }
644
645    /// Every pinned root refreshed within `max_age`. Older pins belong to a
646    /// process that died with a speculation open, and stop protecting their
647    /// objects once they expire.
648    fn gc_pinned_roots(
649        &self,
650        _max_age: std::time::Duration,
651    ) -> Result<Vec<ObjectId>, StorageError> {
652        Ok(Vec::new())
653    }
654
655    /// Stop pinning snapshots whose checkpoint never asked to be pinned.
656    ///
657    /// Clears `state_root` on every milestone row whose commit's intent lacks
658    /// `TAG_PIN_STATE`. The extractor has only honoured that tag since
659    /// v1.2.2; rows distilled before it pinned every checkpoint, and the cursor
660    /// will not revisit them. This is the explicit, one-time way to bring them
661    /// in line. It unpins; it deletes nothing — the objects stay until a sweep.
662    /// Returns the number of rows unpinned.
663    fn history_unpin_legacy_milestones(&self) -> Result<usize, StorageError> {
664        Ok(0)
665    }
666
667    /// Every commit's `state_root`, newest first (insertion order), for the GC
668    /// retention policy (Plan B t-003) to pick keep-recent + checkpoint-every.
669    fn commit_state_roots_recent_first(&self) -> Result<Vec<ObjectId>, StorageError> {
670        Ok(Vec::new())
671    }
672
673    /// Compact the store, returning freed pages to the OS (Plan B t-004). A full
674    /// `VACUUM` — the sweep frees pages to the freelist, but the file only
675    /// shrinks after this. Reports bytes before/after. Backends without a file
676    /// report zeros.
677    fn history_vacuum(&self) -> Result<VacuumStats, StorageError> {
678        Ok(VacuumStats::default())
679    }
680}
681
682/// Named ref management with atomic compare-and-swap.
683///
684/// All ref operations are scoped to a [`Namespace`]. The storage layer
685/// enforces that refs in different namespaces are completely independent:
686/// `get_ref(ns_a, "main")` and `get_ref(ns_b, "main")` are distinct rows.
687///
688/// Namespaces must be explicitly created with [`RefStore::create_namespace`]
689/// before any ref can be written into them. `set_ref` returns
690/// [`StorageError::NamespaceNotFound`] if the namespace does not exist.
691pub trait RefStore: Send + Sync {
692    /// Create a namespace. Returns `NamespaceAlreadyExists` if it already
693    /// exists — callers that want idempotent creation should check first or
694    /// ignore that variant.
695    fn create_namespace(&self, namespace: &Namespace) -> Result<(), StorageError>;
696
697    /// List all known namespaces.
698    fn list_namespaces(&self) -> Result<Vec<Namespace>, StorageError>;
699
700    /// Get the commit ID a ref points to. Returns None if the ref doesn't
701    /// exist. Returns `NamespaceNotFound` if the namespace doesn't exist.
702    fn get_ref(&self, namespace: &Namespace, name: &str) -> Result<Option<ObjectId>, StorageError>;
703
704    /// Set a ref to point to a commit. Creates the ref if it doesn't exist
705    /// but the namespace must already exist. Returns `NamespaceNotFound` if
706    /// the namespace hasn't been created yet.
707    fn set_ref(
708        &self,
709        namespace: &Namespace,
710        name: &str,
711        target: ObjectId,
712    ) -> Result<(), StorageError>;
713
714    /// Atomic compare-and-swap on a ref.
715    /// Updates the ref only if it currently points to `expected`.
716    /// Returns `true` if the swap succeeded, `false` if the current value
717    /// didn't match `expected`. Returns `NamespaceNotFound` if the namespace
718    /// doesn't exist.
719    fn cas_ref(
720        &self,
721        namespace: &Namespace,
722        name: &str,
723        expected: ObjectId,
724        new: ObjectId,
725    ) -> Result<bool, StorageError>;
726
727    /// Create a ref only if no ref of that name exists yet. Returns `true` if
728    /// it was created, `false` if one already existed (left untouched).
729    /// Returns `NamespaceNotFound` if the namespace doesn't exist.
730    ///
731    /// The built-in backends do this atomically. This default, kept so other
732    /// implementations still compile, checks and then sets: two callers can
733    /// both see the name free, and the later one wins.
734    fn create_ref(
735        &self,
736        namespace: &Namespace,
737        name: &str,
738        target: ObjectId,
739    ) -> Result<bool, StorageError> {
740        if self.get_ref(namespace, name)?.is_some() {
741            return Ok(false);
742        }
743        self.set_ref(namespace, name, target)?;
744        Ok(true)
745    }
746
747    /// Delete a ref only if it still points to `expected`. Returns `true` if
748    /// it was deleted, `false` if it was absent or pointed elsewhere.
749    /// Returns `NamespaceNotFound` if the namespace doesn't exist.
750    ///
751    /// Atomic in the built-in backends; this default checks and then deletes.
752    fn cas_delete_ref(
753        &self,
754        namespace: &Namespace,
755        name: &str,
756        expected: ObjectId,
757    ) -> Result<bool, StorageError> {
758        if self.get_ref(namespace, name)? != Some(expected) {
759            return Ok(false);
760        }
761        self.delete_ref(namespace, name)
762    }
763
764    /// List all refs in `namespace` whose name starts with `prefix`.
765    /// Returns `NamespaceNotFound` if the namespace doesn't exist.
766    fn list_refs(
767        &self,
768        namespace: &Namespace,
769        prefix: &str,
770    ) -> Result<Vec<(String, ObjectId)>, StorageError>;
771
772    /// Delete a ref. Returns `true` if the ref existed. Returns
773    /// `NamespaceNotFound` if the namespace doesn't exist.
774    fn delete_ref(&self, namespace: &Namespace, name: &str) -> Result<bool, StorageError>;
775
776    /// Delete a namespace and all its refs. Returns `true` if the namespace
777    /// existed and was deleted, `false` if it was not found. The "default"
778    /// namespace cannot be deleted and returns `InvalidOperation`.
779    fn delete_namespace(&self, namespace: &Namespace) -> Result<bool, StorageError>;
780}
781
782/// Durable storage of epochs and their association with commits.
783///
784/// Epochs are the compliance-relevant unit of work. Sealing an epoch
785/// records a tamper-evident timestamp and summary; a backend that loses
786/// sealed epochs across restart defeats the audit story.
787pub trait EpochStore: Send + Sync {
788    /// Insert a newly-created epoch. If an epoch with the same id already
789    /// exists, implementations may return `StorageError::Backend` — the
790    /// repo layer is expected to guard uniqueness.
791    fn create_epoch(&self, epoch: &Epoch) -> Result<(), StorageError>;
792
793    /// Seal an epoch: flip its status to `Sealed`, stamp `sealed_at`,
794    /// record the seal summary, and persist the set of commits that
795    /// must remain reachable for seal-violation enforcement (V8).
796    /// Subsequent `set_commit_epoch` calls referencing this id must
797    /// fail with `EpochAlreadySealed`.
798    /// `seal_hash` is the tamper-evident digest over the sealed set; it is
799    /// persisted, not recomputed on read, so a later walk cannot quietly
800    /// produce a different answer than the one that was sealed.
801    fn seal_epoch(
802        &self,
803        id: &str,
804        summary: &str,
805        sealed_at: DateTime<Utc>,
806        sealed_commits: &[ObjectId],
807        seal_hash: &ObjectId,
808    ) -> Result<(), StorageError>;
809
810    /// Assign a workspace to an epoch that does not have one yet.
811    ///
812    /// ASSIGN-ONLY BY DESIGN. Succeeds only when the epoch's namespace is
813    /// currently unset, and returns `false` without modifying anything if it is
814    /// already assigned. This is deliberately not a "move epoch to workspace"
815    /// operation: an epoch binds writes in its own workspace, so a reassign
816    /// would let a caller relabel a sealed epoch into a different workspace and
817    /// change whose writes it guards.
818    ///
819    /// It exists for one job: epochs sealed before the namespace column existed
820    /// have no owner recorded, and read as belonging to the default workspace.
821    /// A caller that knows where they belong — typically from its own id
822    /// convention — can settle it once. Works on sealed and archived epochs,
823    /// which is the whole point: those are exactly the ones that predate the
824    /// column. It does not touch the sealed commit set or the seal hash, so
825    /// what was sealed is unchanged.
826    fn assign_epoch_namespace(&self, id: &str, namespace: &str) -> Result<bool, StorageError>;
827
828    /// List all epochs, most-recent first.
829    fn list_epochs(&self) -> Result<Vec<Epoch>, StorageError>;
830
831    /// Fetch a single epoch by id.
832    fn get_epoch(&self, id: &str) -> Result<Option<Epoch>, StorageError>;
833
834    /// Associate a commit with the given epoch. Must reject if the epoch
835    /// is already sealed.
836    fn set_commit_epoch(&self, commit_id: &ObjectId, epoch_id: &str) -> Result<(), StorageError>;
837
838    /// Transition a sealed epoch to Archived. Fails if the epoch is not
839    /// found or is not in the Sealed state.
840    fn archive_epoch(&self, id: &str) -> Result<(), StorageError>;
841}
842
843/// Durable storage of agent sessions and their association with commits.
844pub trait SessionStore: Send + Sync {
845    /// Insert a newly-created session record.
846    fn create_session(&self, session: &Session) -> Result<(), StorageError>;
847
848    /// End a session: update its status and stamp `ended_at`.
849    fn end_session(
850        &self,
851        id: &str,
852        status: SessionStatus,
853        ended_at: DateTime<Utc>,
854    ) -> Result<(), StorageError>;
855
856    /// List sessions, optionally filtered to those belonging to a
857    /// specific agent id.
858    fn list_sessions(&self, agent_filter: Option<&str>) -> Result<Vec<Session>, StorageError>;
859
860    /// Fetch a single session by id.
861    fn get_session(&self, id: &str) -> Result<Option<Session>, StorageError>;
862
863    /// Associate a commit with the given session. Must reject if the
864    /// session has already ended.
865    fn set_commit_session(
866        &self,
867        commit_id: &ObjectId,
868        session_id: &str,
869    ) -> Result<(), StorageError>;
870}
871
872/// Durable storage of taints, quarantines, and watches (0.7.75 §3).
873///
874/// All six methods have default no-op implementations that return
875/// `StorageError::Backend("taint storage not supported")`. Custom backends
876/// that do not need taint support can rely on the defaults and satisfy the
877/// `Storage` supertrait without additional boilerplate. Backends that do
878/// support taints should override every method.
879pub trait TaintStore: Send + Sync {
880    /// Insert a freshly-created taint record. Storage must enforce
881    /// the `(path, name, kind)` uniqueness invariant among unresolved
882    /// rows — re-creating a resolved taint with the same triple is
883    /// allowed (the old one stays as an audit row).
884    fn create_taint(&self, _taint: &agentstategraph_taint::Taint) -> Result<(), StorageError> {
885        Err(StorageError::Backend("taint storage not supported".into()))
886    }
887
888    /// Mark the taint with id `id` as resolved. Returns
889    /// `StorageError::Backend` (wrapping `AlreadyResolved`) if the
890    /// record is already resolved.
891    fn resolve_taint(
892        &self,
893        _id: &str,
894        _resolved_by: &str,
895        _reason: &str,
896        _proof: Option<&str>,
897        _resolved_at: DateTime<Utc>,
898    ) -> Result<(), StorageError> {
899        Err(StorageError::Backend("taint storage not supported".into()))
900    }
901
902    /// List taints, optionally filtered by path prefix + kind +
903    /// include-resolved flag. Results are most-recently-created
904    /// first.
905    fn list_taints(
906        &self,
907        _path_prefix: Option<&str>,
908        _kind: Option<agentstategraph_taint::TaintKind>,
909        _include_resolved: bool,
910    ) -> Result<Vec<agentstategraph_taint::Taint>, StorageError> {
911        Err(StorageError::Backend("taint storage not supported".into()))
912    }
913
914    /// Return every active taint (unresolved + not expired) whose
915    /// `path` matches `request_path` exactly OR whose `path` is a
916    /// propagating ancestor of `request_path`. The caller feeds the
917    /// result into `agentstategraph_taint::evaluate_access`.
918    fn check_taint(
919        &self,
920        _request_path: &str,
921    ) -> Result<Vec<agentstategraph_taint::Taint>, StorageError> {
922        Err(StorageError::Backend("taint storage not supported".into()))
923    }
924
925    /// Fetch a taint by its id. Returns `None` if missing.
926    fn get_taint(&self, _id: &str) -> Result<Option<agentstategraph_taint::Taint>, StorageError> {
927        Err(StorageError::Backend("taint storage not supported".into()))
928    }
929
930    /// Back-patch the `commit_id` onto a freshly-inserted taint
931    /// after the repository has written the intent commit. A no-op
932    /// if the taint is already resolved.
933    fn set_taint_commit_id(&self, _id: &str, _commit_id: &str) -> Result<(), StorageError> {
934        Err(StorageError::Backend("taint storage not supported".into()))
935    }
936}
937
938/// Combined storage trait for convenience.
939/// A backend that implements all seven sub-traits.
940pub trait Storage:
941    ObjectStore + CommitStore + RefStore + EpochStore + SessionStore + TaintStore + ReminderStore
942{
943}
944
945/// Blanket implementation: anything implementing all seven traits is a Storage.
946impl<
947    T: ObjectStore + CommitStore + RefStore + EpochStore + SessionStore + TaintStore + ReminderStore,
948> Storage for T
949{
950}