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}