agentstategraph-storage 1.3.2

Pluggable storage backends for AgentStateGraph
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
//! Storage trait definitions — the pluggable backend contract.
//!
//! Any backend that implements these traits can be used with AgentStateGraph.
//! The in-memory and SQLite backends are provided; custom backends
//! can be added by implementing these traits.

use agentstategraph_core::{Commit, Epoch, Namespace, Object, ObjectId, Session, SessionStatus};
use agentstategraph_reminders::ReminderStore;
use chrono::{DateTime, Utc};

/// Errors from storage operations.
#[derive(Debug, thiserror::Error)]
pub enum StorageError {
    #[error("object not found: {0}")]
    ObjectNotFound(String),

    #[error("commit not found: {0}")]
    CommitNotFound(String),

    #[error("ref not found: {0}")]
    RefNotFound(String),

    #[error("namespace not found: '{0}' (create it with create_namespace before writing refs)")]
    NamespaceNotFound(String),

    #[error("namespace already exists: '{0}'")]
    NamespaceAlreadyExists(String),

    #[error("CAS conflict: ref '{name}' expected {expected}, found {actual}")]
    CasConflict {
        name: String,
        expected: String,
        actual: String,
    },

    #[error("duplicate ref: {0}")]
    DuplicateRef(String),

    #[error("storage backend error: {0}")]
    Backend(String),

    #[error("serialization error: {0}")]
    Serialization(String),

    #[error("epoch '{id}' is already sealed")]
    EpochAlreadySealed { id: String },

    #[error("session '{id}' has already ended")]
    SessionEnded { id: String },

    #[error("invalid operation: {0}")]
    InvalidOperation(String),
}

impl StorageError {
    /// A stable, low-cardinality code for this kind of error (DESIGN.md Plan
    /// H t-004): for API responses, `error.type` on spans and metrics, and
    /// for clients to branch on instead of the message.
    pub fn code(&self) -> &'static str {
        match self {
            StorageError::ObjectNotFound(_) => "object_not_found",
            StorageError::CommitNotFound(_) => "commit_not_found",
            StorageError::RefNotFound(_) => "ref_not_found",
            StorageError::NamespaceNotFound(_) => "namespace_not_found",
            StorageError::NamespaceAlreadyExists(_) => "namespace_already_exists",
            StorageError::CasConflict { .. } => "write_conflict",
            StorageError::DuplicateRef(_) => "ref_already_exists",
            StorageError::Backend(_) => "storage_error",
            StorageError::Serialization(_) => "serialization_error",
            StorageError::EpochAlreadySealed { .. } => "epoch_sealed",
            StorageError::SessionEnded { .. } => "session_ended",
            StorageError::InvalidOperation(_) => "invalid_operation",
        }
    }
}

/// Content-addressed object storage.
/// Objects are stored and retrieved by their BLAKE3 hash (ObjectId).
pub trait ObjectStore: Send + Sync {
    /// Retrieve an object by its ID. Returns None if not found.
    fn get_object(&self, id: &ObjectId) -> Result<Option<Object>, StorageError>;

    /// Store an object. Returns its ObjectId (which is its content hash).
    /// Storing an object that already exists is a no-op (idempotent).
    fn put_object(&self, obj: &Object) -> Result<ObjectId, StorageError>;

    /// Check if an object exists in the store.
    fn has_object(&self, id: &ObjectId) -> Result<bool, StorageError>;

    /// Retrieve multiple objects at once. Returns None for missing objects.
    fn batch_get_objects(&self, ids: &[ObjectId]) -> Result<Vec<Option<Object>>, StorageError> {
        // Default implementation: sequential gets. Backends can optimize.
        ids.iter().map(|id| self.get_object(id)).collect()
    }

    /// Store multiple objects at once. Returns their ObjectIds.
    fn batch_put_objects(&self, objs: &[Object]) -> Result<Vec<ObjectId>, StorageError> {
        // Default implementation: sequential puts. Backends can optimize.
        objs.iter().map(|obj| self.put_object(obj)).collect()
    }

    // ---- Optional leaf-value index (plan perf-slow-endpoints t-006) ----
    //
    // An optional, backend-provided index over the string leaves of a ref's
    // tree, keyed by `(namespace, ref)` and maintained in place: a one-time
    // backfill, then incremental add/remove as the ref advances. It turns value
    // search from an un-indexed full DFS (linear in graph size; multi-second on
    // a large ref) into a trigram substring probe. A backend that does not
    // implement it reports "not indexed" so callers fall back to the tree walk,
    // making the whole feature purely additive.

    /// Whether the `(namespace, ref)` leaf set has been built.
    fn leaf_index_is_built(&self, _namespace: &str, _ref_name: &str) -> Result<bool, StorageError> {
        Ok(false)
    }

    /// One-time backfill: replace any existing rows for `(namespace, ref)` with
    /// `entries` and mark the set built. Called once, from the read path, the
    /// first time a ref is searched after the feature is enabled.
    fn leaf_index_build(
        &self,
        _namespace: &str,
        _ref_name: &str,
        _entries: &[(String, String)],
    ) -> Result<(), StorageError> {
        Ok(())
    }

    /// Incremental maintenance: for a built `(namespace, ref)`, delete the rows
    /// at `removed_paths` and insert `added` `(path, value)` rows. A no-op if
    /// the set has not been built (the backfill will pick up the new state).
    /// Called from the write path as a ref advances.
    fn leaf_index_apply(
        &self,
        _namespace: &str,
        _ref_name: &str,
        _removed_paths: &[String],
        _added: &[(String, String)],
    ) -> Result<(), StorageError> {
        Ok(())
    }

    /// Substring-search the built leaves of `(namespace, ref)`. `Ok(None)` means
    /// the set is not built / backend has no index (caller falls back to the
    /// tree walk); `Ok(Some(..))` is authoritative (possibly empty), capped at
    /// `limit`.
    fn leaf_index_search(
        &self,
        _namespace: &str,
        _ref_name: &str,
        _query_lower: &str,
        _limit: usize,
    ) -> Result<Option<Vec<(String, String)>>, StorageError> {
        Ok(None)
    }

    // ---- Which tree a leaf set reflects (Plan D t-008) ----
    //
    // `leaf_index_apply` applies diffs in whatever order writers reach it. Two
    // writers advancing one ref can apply theirs out of order, and the set
    // then keeps a value that was overwritten. A backend that records the
    // state root each set reflects avoids this: a diff applies only to the
    // tree it was computed from, and a reader can check the set is current
    // before trusting it, and catch it up when it isn't.

    /// Whether this backend records the state root of each built set, through
    /// [`leaf_index_root`](Self::leaf_index_root),
    /// [`leaf_index_build_at`](Self::leaf_index_build_at) and
    /// [`leaf_index_advance`](Self::leaf_index_advance).
    fn leaf_index_tracks_roots(&self) -> bool {
        false
    }

    /// The state root the `(namespace, ref)` set reflects. `None` when it
    /// isn't built, was built or changed without a root, or the backend
    /// doesn't record roots.
    fn leaf_index_root(
        &self,
        _namespace: &str,
        _ref_name: &str,
    ) -> Result<Option<ObjectId>, StorageError> {
        Ok(None)
    }

    /// [`leaf_index_build`](Self::leaf_index_build) from the tree at `root`,
    /// recording `root`.
    fn leaf_index_build_at(
        &self,
        namespace: &str,
        ref_name: &str,
        _root: &ObjectId,
        entries: &[(String, String)],
    ) -> Result<(), StorageError> {
        self.leaf_index_build(namespace, ref_name, entries)
    }

    /// Move the set from the tree at `from` to the tree at `to`, by the leaf
    /// diff between them, only if it is at `from`. Returns whether it moved.
    /// A backend that doesn't record roots applies the diff unconditionally,
    /// as [`leaf_index_apply`](Self::leaf_index_apply), and returns `true`.
    fn leaf_index_advance(
        &self,
        namespace: &str,
        ref_name: &str,
        _from: &ObjectId,
        _to: &ObjectId,
        removed_paths: &[String],
        added: &[(String, String)],
    ) -> Result<bool, StorageError> {
        self.leaf_index_apply(namespace, ref_name, removed_paths, added)?;
        Ok(true)
    }
}

/// One row of the commit-history rollup (Plan A t-001): commit activity for a
/// single (day, namespace, agent, intent category) bucket.
#[derive(Debug, Clone, PartialEq)]
pub struct HistoryRollupRow {
    pub day: String,
    pub namespace: String,
    pub agent_id: String,
    pub intent_category: String,
    pub commit_count: i64,
    pub first_ts: String,
    pub last_ts: String,
}

/// One milestone on the distilled history timeline (Plan A t-001).
///
/// `state_root` (Plan A t-005) names the snapshot the milestone preserves — the
/// retention hook Plan B's GC keeps reachable. It is `None` for a milestone that
/// pins nothing, which is the default: a checkpoint pins its snapshot only when
/// its intent carries `TAG_PIN_STATE`. (Rows written before t-005 are also
/// `None`, for the older reason that the column did not exist.) An unpinned
/// milestone is still a full timeline entry; it just names no snapshot, so a
/// sweep may reclaim the objects behind it.
///
/// `git_sha` is the external revision the commit corresponds to, lifted from the
/// intent's `TAG_GIT_REVISION` tag. It is what keeps an unpinned milestone
/// actionable: the snapshot is gone, but the revision that produced it is
/// recorded, so derived state can be rebuilt from source.
#[derive(Debug, Clone, PartialEq)]
pub struct HistoryMilestoneRow {
    pub commit_id: ObjectId,
    pub kind: String,
    pub timestamp: String,
    pub day: String,
    pub namespace: String,
    pub agent_id: String,
    pub description: String,
    pub state_root: Option<ObjectId>,
    pub git_sha: Option<String>,
}

/// Per-table on-disk size (Plan A t-003), largest first.
#[derive(Debug, Clone, PartialEq)]
pub struct TableBytes {
    pub name: String,
    pub bytes: i64,
}

/// Physical shape of the store (Plan A t-003) — the evidence surface Plan B's
/// GC keys its retention thresholds off: how many objects/commits, how many
/// bytes, and where they live. `tables` is populated from SQLite's `dbstat`
/// virtual table when the build exposes it; otherwise only `total_bytes`
/// (page_count × page_size) is available and `dbstat_available` is false.
/// Postgres always reports per-table sizes (`dbstat_available` is true): the
/// bytes the tenant's rows take, since the tables are shared by tenants.
#[derive(Debug, Clone, Default, PartialEq)]
pub struct StoreShape {
    pub objects: i64,
    pub commits: i64,
    pub total_bytes: i64,
    pub tables: Vec<TableBytes>,
    pub dbstat_available: bool,
}

/// The trace a commit was made in (DESIGN.md Plan H t-009), as W3C trace
/// context ids in lowercase hex. It's kept beside the commit, never in it, so
/// commit ids and sync bundles don't depend on telemetry.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct CommitTrace {
    /// The trace: 32 hex characters.
    pub trace_id: String,
    /// The span that made the commit: 16 hex characters.
    pub span_id: String,
}

/// A store's totals, cheap enough to sample on an interval for the store
/// gauges (DESIGN.md Plan H t-008). Unlike [`StoreShape`], there is no
/// per-table breakdown, which reads every page.
#[derive(Debug, Clone, Default, PartialEq, Eq)]
pub struct StoreTotals {
    pub objects: i64,
    pub commits: i64,
    /// The store's size on disk, where it has a file of its own (SQLite);
    /// `None` in memory or in a database tenants share (Postgres).
    pub bytes: Option<i64>,
}

/// Result of a GC reachability mark (Plan B t-001): how many objects are live
/// (reachable from the given roots) vs. total, and the reclaimable remainder.
#[derive(Debug, Clone, Default, PartialEq, Eq)]
pub struct GcReachability {
    pub total_objects: i64,
    pub live_objects: i64,
    pub reclaimable_objects: i64,
    /// Root state roots the mark started from.
    pub roots_walked: usize,
}

/// Result of a `VACUUM` (Plan B t-004): on-disk bytes before/after and the
/// space returned to the OS.
#[derive(Debug, Clone, Default, PartialEq, Eq)]
pub struct VacuumStats {
    pub bytes_before: i64,
    pub bytes_after: i64,
    pub bytes_reclaimed: i64,
}

/// Result of a GC sweep (Plan B t-003): how many objects were deleted.
#[derive(Debug, Clone, Default, PartialEq, Eq)]
pub struct GcSweep {
    pub objects_before: i64,
    pub objects_deleted: i64,
    pub objects_after: i64,
    /// Objects the sweep set out to delete (unreachable from the keep-set).
    /// Equals `objects_deleted` on a complete run.
    pub deleted_target: i64,
}

/// Default GC grace period for the SQL backends: a sweep spares unreachable
/// objects written more recently than this. Every write stores its new
/// objects before it commits them, so without it a sweep that runs in between
/// takes a write in flight. See `with_gc_grace` on each backend.
pub const DEFAULT_GC_GRACE: std::time::Duration = std::time::Duration::from_secs(10 * 60);

/// A stored object that is stored again has its write time refreshed once it
/// is older than this, so it falls inside any grace period at least this long
/// (and an object stored over and over isn't rewritten each time).
pub const GC_FRESHEN_AFTER: std::time::Duration = std::time::Duration::from_secs(60);

/// Namespace recorded for a distilled commit whose namespace could not be
/// established.
///
/// The history extractor attributes a commit through its session's
/// `scope_namespace`. A commit made outside a scoped session has no such row,
/// and the extractor used to fall back to `"default"` — which is itself a real
/// namespace name, so a fallback was indistinguishable from a genuine
/// attribution. On a store where nothing writes sessions that silently filed
/// every commit under `"default"`.
///
/// Sentinel rather than NULL because `asg_history_commit_rollup.namespace` is
/// `NOT NULL` and part of the primary key.
pub const HISTORY_NAMESPACE_UNKNOWN: &str = "unattributed";

/// Outcome of a full-DAG commit walk ([`CommitStore::list_commits_dag`]).
// No `Eq`: `Commit` is only `PartialEq`.
#[derive(Debug, Clone, Default, PartialEq)]
pub struct CommitWalk {
    /// Commits reached, in breadth-first order from the starting commit.
    /// Deduplicated: a merge reachable down both sides appears once.
    pub commits: Vec<Commit>,
    /// True when `limit` stopped the walk with parents still unexplored.
    ///
    /// This is the difference between "that is all of them" and "there are
    /// more" — without it a caller cannot tell a complete small history from
    /// a truncated large one, and both look like success.
    pub truncated: bool,
}

/// Commit storage. Commits are also content-addressed but stored
/// separately from objects for efficient history queries.
pub trait CommitStore: Send + Sync {
    /// Retrieve a commit by its ID.
    fn get_commit(&self, id: &ObjectId) -> Result<Option<Commit>, StorageError>;

    /// Store a commit.
    fn put_commit(&self, commit: &Commit) -> Result<(), StorageError>;

    /// Check if a commit exists.
    fn has_commit(&self, id: &ObjectId) -> Result<bool, StorageError>;

    /// List commits reachable from a given commit, in reverse chronological order.
    /// Returns at most `limit` commits.
    fn list_commits(&self, from: &ObjectId, limit: usize) -> Result<Vec<Commit>, StorageError>;

    /// Walk **every** parent edge from `from`, not just the first.
    ///
    /// [`CommitStore::list_commits`] follows `parents[0]`, which is a
    /// first-parent line: on a store with merges it silently under-reports.
    /// Measured on the asd store, the first-parent walk reached 4,268 of
    /// 5,896 commits — the 1,628 it missed being merge second-parents and
    /// commits no longer reachable from the ref head, which is exactly the
    /// population a "what would a prune take?" view most needs to see.
    ///
    /// `list_commits` is deliberately left alone: a first-parent line is a
    /// defensible thing to want, and widening it in place would change output
    /// for every existing caller.
    ///
    /// A parent that is absent from the store ends that edge and the walk
    /// continues — a pruned commit is expected in a swept store, not an error.
    ///
    /// The default implementation is a breadth-first walk over
    /// [`CommitStore::get_commit`], so every backend gets it without change.
    /// A backend able to do this in one query should override it.
    fn list_commits_dag(&self, from: &ObjectId, limit: usize) -> Result<CommitWalk, StorageError> {
        let mut seen: std::collections::HashSet<ObjectId> = std::collections::HashSet::new();
        let mut frontier: std::collections::VecDeque<ObjectId> =
            std::collections::VecDeque::from([*from]);
        let mut commits = Vec::new();
        let mut truncated = false;

        while let Some(id) = frontier.pop_front() {
            if commits.len() >= limit {
                // We popped something, so there was still more to walk.
                truncated = true;
                break;
            }
            if !seen.insert(id) {
                continue;
            }
            match self.get_commit(&id)? {
                Some(commit) => {
                    for p in &commit.parents {
                        if !seen.contains(p) {
                            frontier.push_back(*p);
                        }
                    }
                    commits.push(commit);
                }
                // Pruned: end this edge, keep walking the rest.
                None => continue,
            }
        }

        Ok(CommitWalk { commits, truncated })
    }

    /// Return the ids of every commit in the store, unordered.
    ///
    /// Unlike [`CommitStore::list_commits`] this is NOT reachability-scoped: it
    /// includes commits that no ref currently points at (e.g. the tip of a
    /// deleted branch). Used for prefix-based ref resolution and for recovering
    /// orphaned historical commits.
    fn all_commit_ids(&self) -> Result<Vec<ObjectId>, StorageError>;

    // -- Project-history metrics (Plan A t-001) ------------------------------
    // Derived, rebuildable tables distilled from the commit chain. A backend
    // that doesn't implement them is simply "no history" — the feature is
    // purely additive, like `leaf_index_*`.

    /// Fold the next batch of un-processed commits into the `asg_history_*`
    /// rollup/milestone tables, advancing the stored `commits.rowid` cursor
    /// atomically. Returns the number of commits processed this call — `0` once
    /// the extractor has caught up. Idempotent and resumable: the cursor only
    /// advances inside the same transaction that writes the rows, so a crash
    /// re-processes the batch rather than double-counting it. Bounded memory:
    /// at most `batch_size` commits are held at once.
    fn history_extract_batch(&self, _batch_size: usize) -> Result<usize, StorageError> {
        Ok(0)
    }

    /// The last `commits.rowid` folded into the history tables (0 = nothing
    /// extracted yet).
    fn history_cursor(&self) -> Result<i64, StorageError> {
        Ok(0)
    }

    /// Read the commit-history rollup, ordered by (day, namespace, agent,
    /// intent category).
    fn history_rollup(&self) -> Result<Vec<HistoryRollupRow>, StorageError> {
        Ok(Vec::new())
    }

    /// Read the milestone timeline in chronological order, most recent first,
    /// capped at `limit`.
    fn history_milestones(&self, _limit: usize) -> Result<Vec<HistoryMilestoneRow>, StorageError> {
        Ok(Vec::new())
    }

    /// Measure the physical shape of the store (Plan A t-003): object/commit
    /// counts, total bytes, and per-table bytes when the backend can report
    /// them. Backends that can't return an empty [`StoreShape`].
    fn history_store_shape(&self) -> Result<StoreShape, StorageError> {
        Ok(StoreShape::default())
    }

    /// The store's totals, for the store gauges. Counting still reads every
    /// row's key, so sample it on a slow interval. Backends that don't count
    /// report `None`.
    fn store_totals(&self) -> Result<Option<StoreTotals>, StorageError> {
        Ok(None)
    }

    /// Store `commit` and, when given, the trace it was made in. A backend
    /// that can does both in one write, which matters on every commit; the
    /// default stores one after the other.
    fn put_commit_traced(
        &self,
        commit: &Commit,
        trace: Option<&CommitTrace>,
    ) -> Result<(), StorageError> {
        self.put_commit(commit)?;
        match trace {
            Some(trace) => self.set_commit_trace(&commit.id, trace),
            None => Ok(()),
        }
    }

    /// Record the trace `commit_id` was made in. The first record for a
    /// commit stands. Backends that don't keep trace links ignore it.
    fn set_commit_trace(
        &self,
        _commit_id: &ObjectId,
        _trace: &CommitTrace,
    ) -> Result<(), StorageError> {
        Ok(())
    }

    /// The trace `commit_id` was made in, if one was recorded.
    fn get_commit_trace(&self, _commit_id: &ObjectId) -> Result<Option<CommitTrace>, StorageError> {
        Ok(None)
    }

    // -- Retention hooks for GC (Plan A t-005) ------------------------------

    /// Whether `id`'s commit has been folded into the history tables — i.e. its
    /// position is at or before the extractor cursor. This is the "already
    /// captured" predicate Plan B's GC checks before pruning a commit's raw
    /// snapshot: a distilled commit's signal survives in the metric tables.
    /// Backends without history report `false` (nothing distilled → prune
    /// nothing on this basis).
    fn history_is_commit_distilled(&self, _id: &ObjectId) -> Result<bool, StorageError> {
        Ok(false)
    }

    /// State roots the GC must keep reachable: the snapshots preserved by
    /// recorded milestones (the human-meaningful spine). Distinct, order
    /// unspecified.
    fn history_retained_state_roots(&self) -> Result<Vec<ObjectId>, StorageError> {
        Ok(Vec::new())
    }

    /// Count commits not yet folded into the history tables — those with a
    /// rowid beyond the extractor cursor (Plan B t-002). `0` means the
    /// extractor is caught up, so every commit's signal is distilled and the GC
    /// can safely make historical state unmaterializable. Backends without
    /// history report `0` (they have no distillation gate).
    fn history_undistilled_commit_count(&self) -> Result<i64, StorageError> {
        Ok(0)
    }

    /// Mark every object reachable from `roots` (state roots) and report live
    /// vs. total object counts — the GC reclaimable estimate (Plan B t-001).
    ///
    /// Walks the Merkle DAG in bounded memory: the mark set is held **on disk**
    /// (a temp table), and unexpanded nodes are drained in `batch`-sized chunks,
    /// so a 14.8M-object store never materializes the full closure in RAM.
    /// Backends without object storage report all-zero.
    fn history_gc_reachability(
        &self,
        _roots: &[ObjectId],
        _batch: usize,
    ) -> Result<GcReachability, StorageError> {
        Ok(GcReachability::default())
    }

    /// Sweep: mark the closure of `roots` and DELETE every object outside it
    /// (Plan B t-003). Destructive; callers gate it (dry-run default, safety
    /// predicate). Backends without object storage report an empty sweep.
    ///
    /// Must keep other writers' work safe from the mark to the last delete, or
    /// a commit landing mid-sweep loses its objects. A backend can exclude
    /// writers, or spare recent writes; Postgres does the latter (a grace
    /// period on each object's write time, refreshed when an object is stored
    /// again), so its writers never wait for a sweep. The SQLite backend runs the whole
    /// sweep as one write transaction — deletes are still issued in bounded
    /// chunks, but a crash rolls the sweep back rather than leaving it half done
    /// — and joins the caller's transaction when
    /// [`history_gc_lock_writers`](Self::history_gc_lock_writers) is already
    /// held. It also keeps every current ref tip whatever `roots` says, since a
    /// caller's roots can predate a commit made on another connection.
    fn history_gc_sweep(
        &self,
        _roots: &[ObjectId],
        _batch: usize,
    ) -> Result<GcSweep, StorageError> {
        Ok(GcSweep::default())
    }

    /// Take the store's write lock for a GC sweep, held until
    /// [`history_gc_unlock_writers`](Self::history_gc_unlock_writers).
    /// (On Postgres it is a lock against a second sweep only; writers are
    /// kept safe by the grace period instead, and don't wait.)
    ///
    /// A sweep is only correct if nothing commits between the moment its
    /// keep-set is computed and its last delete, so the caller takes this
    /// *before* computing the keep-set. Other writers wait (up to the backend's
    /// busy timeout) and then fail rather than interleave; readers are
    /// unaffected — including other threads using this same handle, which must
    /// not join the sweep's transaction (a rolled-back sweep would discard
    /// their already-acknowledged writes). Backends with a single writer, or
    /// no object storage, need do nothing.
    fn history_gc_lock_writers(&self) -> Result<(), StorageError> {
        Ok(())
    }

    /// Release the lock taken by
    /// [`history_gc_lock_writers`](Self::history_gc_lock_writers), committing
    /// the work done under it or rolling it back. A no-op when nothing is held.
    fn history_gc_unlock_writers(&self, _commit: bool) -> Result<(), StorageError> {
        Ok(())
    }

    /// Record `root` under `key` as reachable-but-uncommitted (an open
    /// speculation's base or working tree), so a GC sweep — in this process or
    /// any other sharing the store — keeps every object it references.
    /// Replaces any earlier root for `key` and refreshes its age.
    fn gc_pin_root(&self, _key: &str, _root: &ObjectId) -> Result<(), StorageError> {
        Ok(())
    }

    /// Remove the pin recorded by [`gc_pin_root`](Self::gc_pin_root). A no-op
    /// when absent.
    fn gc_unpin_root(&self, _key: &str) -> Result<(), StorageError> {
        Ok(())
    }

    /// Every pinned root refreshed within `max_age`. Older pins belong to a
    /// process that died with a speculation open, and stop protecting their
    /// objects once they expire.
    fn gc_pinned_roots(
        &self,
        _max_age: std::time::Duration,
    ) -> Result<Vec<ObjectId>, StorageError> {
        Ok(Vec::new())
    }

    /// Stop pinning snapshots whose checkpoint never asked to be pinned.
    ///
    /// Clears `state_root` on every milestone row whose commit's intent lacks
    /// `TAG_PIN_STATE`. The extractor has only honoured that tag since
    /// v1.2.2; rows distilled before it pinned every checkpoint, and the cursor
    /// will not revisit them. This is the explicit, one-time way to bring them
    /// in line. It unpins; it deletes nothing — the objects stay until a sweep.
    /// Returns the number of rows unpinned.
    fn history_unpin_legacy_milestones(&self) -> Result<usize, StorageError> {
        Ok(0)
    }

    /// Every commit's `state_root`, newest first (insertion order), for the GC
    /// retention policy (Plan B t-003) to pick keep-recent + checkpoint-every.
    fn commit_state_roots_recent_first(&self) -> Result<Vec<ObjectId>, StorageError> {
        Ok(Vec::new())
    }

    /// Compact the store, returning freed pages to the OS (Plan B t-004). A full
    /// `VACUUM` — the sweep frees pages to the freelist, but the file only
    /// shrinks after this. Reports bytes before/after. Backends without a file
    /// report zeros.
    fn history_vacuum(&self) -> Result<VacuumStats, StorageError> {
        Ok(VacuumStats::default())
    }
}

/// Named ref management with atomic compare-and-swap.
///
/// All ref operations are scoped to a [`Namespace`]. The storage layer
/// enforces that refs in different namespaces are completely independent:
/// `get_ref(ns_a, "main")` and `get_ref(ns_b, "main")` are distinct rows.
///
/// Namespaces must be explicitly created with [`RefStore::create_namespace`]
/// before any ref can be written into them. `set_ref` returns
/// [`StorageError::NamespaceNotFound`] if the namespace does not exist.
pub trait RefStore: Send + Sync {
    /// Create a namespace. Returns `NamespaceAlreadyExists` if it already
    /// exists — callers that want idempotent creation should check first or
    /// ignore that variant.
    fn create_namespace(&self, namespace: &Namespace) -> Result<(), StorageError>;

    /// List all known namespaces.
    fn list_namespaces(&self) -> Result<Vec<Namespace>, StorageError>;

    /// Get the commit ID a ref points to. Returns None if the ref doesn't
    /// exist. Returns `NamespaceNotFound` if the namespace doesn't exist.
    fn get_ref(&self, namespace: &Namespace, name: &str) -> Result<Option<ObjectId>, StorageError>;

    /// Set a ref to point to a commit. Creates the ref if it doesn't exist
    /// but the namespace must already exist. Returns `NamespaceNotFound` if
    /// the namespace hasn't been created yet.
    fn set_ref(
        &self,
        namespace: &Namespace,
        name: &str,
        target: ObjectId,
    ) -> Result<(), StorageError>;

    /// Atomic compare-and-swap on a ref.
    /// Updates the ref only if it currently points to `expected`.
    /// Returns `true` if the swap succeeded, `false` if the current value
    /// didn't match `expected`. Returns `NamespaceNotFound` if the namespace
    /// doesn't exist.
    fn cas_ref(
        &self,
        namespace: &Namespace,
        name: &str,
        expected: ObjectId,
        new: ObjectId,
    ) -> Result<bool, StorageError>;

    /// Create a ref only if no ref of that name exists yet. Returns `true` if
    /// it was created, `false` if one already existed (left untouched).
    /// Returns `NamespaceNotFound` if the namespace doesn't exist.
    ///
    /// The built-in backends do this atomically. This default, kept so other
    /// implementations still compile, checks and then sets: two callers can
    /// both see the name free, and the later one wins.
    fn create_ref(
        &self,
        namespace: &Namespace,
        name: &str,
        target: ObjectId,
    ) -> Result<bool, StorageError> {
        if self.get_ref(namespace, name)?.is_some() {
            return Ok(false);
        }
        self.set_ref(namespace, name, target)?;
        Ok(true)
    }

    /// Delete a ref only if it still points to `expected`. Returns `true` if
    /// it was deleted, `false` if it was absent or pointed elsewhere.
    /// Returns `NamespaceNotFound` if the namespace doesn't exist.
    ///
    /// Atomic in the built-in backends; this default checks and then deletes.
    fn cas_delete_ref(
        &self,
        namespace: &Namespace,
        name: &str,
        expected: ObjectId,
    ) -> Result<bool, StorageError> {
        if self.get_ref(namespace, name)? != Some(expected) {
            return Ok(false);
        }
        self.delete_ref(namespace, name)
    }

    /// List all refs in `namespace` whose name starts with `prefix`.
    /// Returns `NamespaceNotFound` if the namespace doesn't exist.
    fn list_refs(
        &self,
        namespace: &Namespace,
        prefix: &str,
    ) -> Result<Vec<(String, ObjectId)>, StorageError>;

    /// Delete a ref. Returns `true` if the ref existed. Returns
    /// `NamespaceNotFound` if the namespace doesn't exist.
    fn delete_ref(&self, namespace: &Namespace, name: &str) -> Result<bool, StorageError>;

    /// Delete a namespace and all its refs. Returns `true` if the namespace
    /// existed and was deleted, `false` if it was not found. The "default"
    /// namespace cannot be deleted and returns `InvalidOperation`.
    fn delete_namespace(&self, namespace: &Namespace) -> Result<bool, StorageError>;
}

/// Durable storage of epochs and their association with commits.
///
/// Epochs are the compliance-relevant unit of work. Sealing an epoch
/// records a tamper-evident timestamp and summary; a backend that loses
/// sealed epochs across restart defeats the audit story.
pub trait EpochStore: Send + Sync {
    /// Insert a newly-created epoch. If an epoch with the same id already
    /// exists, implementations may return `StorageError::Backend` — the
    /// repo layer is expected to guard uniqueness.
    fn create_epoch(&self, epoch: &Epoch) -> Result<(), StorageError>;

    /// Seal an epoch: flip its status to `Sealed`, stamp `sealed_at`,
    /// record the seal summary, and persist the set of commits that
    /// must remain reachable for seal-violation enforcement (V8).
    /// Subsequent `set_commit_epoch` calls referencing this id must
    /// fail with `EpochAlreadySealed`.
    /// `seal_hash` is the tamper-evident digest over the sealed set; it is
    /// persisted, not recomputed on read, so a later walk cannot quietly
    /// produce a different answer than the one that was sealed.
    fn seal_epoch(
        &self,
        id: &str,
        summary: &str,
        sealed_at: DateTime<Utc>,
        sealed_commits: &[ObjectId],
        seal_hash: &ObjectId,
    ) -> Result<(), StorageError>;

    /// Assign a workspace to an epoch that does not have one yet.
    ///
    /// ASSIGN-ONLY BY DESIGN. Succeeds only when the epoch's namespace is
    /// currently unset, and returns `false` without modifying anything if it is
    /// already assigned. This is deliberately not a "move epoch to workspace"
    /// operation: an epoch binds writes in its own workspace, so a reassign
    /// would let a caller relabel a sealed epoch into a different workspace and
    /// change whose writes it guards.
    ///
    /// It exists for one job: epochs sealed before the namespace column existed
    /// have no owner recorded, and read as belonging to the default workspace.
    /// A caller that knows where they belong — typically from its own id
    /// convention — can settle it once. Works on sealed and archived epochs,
    /// which is the whole point: those are exactly the ones that predate the
    /// column. It does not touch the sealed commit set or the seal hash, so
    /// what was sealed is unchanged.
    fn assign_epoch_namespace(&self, id: &str, namespace: &str) -> Result<bool, StorageError>;

    /// List all epochs, most-recent first.
    fn list_epochs(&self) -> Result<Vec<Epoch>, StorageError>;

    /// Fetch a single epoch by id.
    fn get_epoch(&self, id: &str) -> Result<Option<Epoch>, StorageError>;

    /// Associate a commit with the given epoch. Must reject if the epoch
    /// is already sealed.
    fn set_commit_epoch(&self, commit_id: &ObjectId, epoch_id: &str) -> Result<(), StorageError>;

    /// Transition a sealed epoch to Archived. Fails if the epoch is not
    /// found or is not in the Sealed state.
    fn archive_epoch(&self, id: &str) -> Result<(), StorageError>;
}

/// Durable storage of agent sessions and their association with commits.
pub trait SessionStore: Send + Sync {
    /// Insert a newly-created session record.
    fn create_session(&self, session: &Session) -> Result<(), StorageError>;

    /// End a session: update its status and stamp `ended_at`.
    fn end_session(
        &self,
        id: &str,
        status: SessionStatus,
        ended_at: DateTime<Utc>,
    ) -> Result<(), StorageError>;

    /// List sessions, optionally filtered to those belonging to a
    /// specific agent id.
    fn list_sessions(&self, agent_filter: Option<&str>) -> Result<Vec<Session>, StorageError>;

    /// Fetch a single session by id.
    fn get_session(&self, id: &str) -> Result<Option<Session>, StorageError>;

    /// Associate a commit with the given session. Must reject if the
    /// session has already ended.
    fn set_commit_session(
        &self,
        commit_id: &ObjectId,
        session_id: &str,
    ) -> Result<(), StorageError>;
}

/// Durable storage of taints, quarantines, and watches (0.7.75 §3).
///
/// All six methods have default no-op implementations that return
/// `StorageError::Backend("taint storage not supported")`. Custom backends
/// that do not need taint support can rely on the defaults and satisfy the
/// `Storage` supertrait without additional boilerplate. Backends that do
/// support taints should override every method.
pub trait TaintStore: Send + Sync {
    /// Insert a freshly-created taint record. Storage must enforce
    /// the `(path, name, kind)` uniqueness invariant among unresolved
    /// rows — re-creating a resolved taint with the same triple is
    /// allowed (the old one stays as an audit row).
    fn create_taint(&self, _taint: &agentstategraph_taint::Taint) -> Result<(), StorageError> {
        Err(StorageError::Backend("taint storage not supported".into()))
    }

    /// Mark the taint with id `id` as resolved. Returns
    /// `StorageError::Backend` (wrapping `AlreadyResolved`) if the
    /// record is already resolved.
    fn resolve_taint(
        &self,
        _id: &str,
        _resolved_by: &str,
        _reason: &str,
        _proof: Option<&str>,
        _resolved_at: DateTime<Utc>,
    ) -> Result<(), StorageError> {
        Err(StorageError::Backend("taint storage not supported".into()))
    }

    /// List taints, optionally filtered by path prefix + kind +
    /// include-resolved flag. Results are most-recently-created
    /// first.
    fn list_taints(
        &self,
        _path_prefix: Option<&str>,
        _kind: Option<agentstategraph_taint::TaintKind>,
        _include_resolved: bool,
    ) -> Result<Vec<agentstategraph_taint::Taint>, StorageError> {
        Err(StorageError::Backend("taint storage not supported".into()))
    }

    /// Return every active taint (unresolved + not expired) whose
    /// `path` matches `request_path` exactly OR whose `path` is a
    /// propagating ancestor of `request_path`. The caller feeds the
    /// result into `agentstategraph_taint::evaluate_access`.
    fn check_taint(
        &self,
        _request_path: &str,
    ) -> Result<Vec<agentstategraph_taint::Taint>, StorageError> {
        Err(StorageError::Backend("taint storage not supported".into()))
    }

    /// Fetch a taint by its id. Returns `None` if missing.
    fn get_taint(&self, _id: &str) -> Result<Option<agentstategraph_taint::Taint>, StorageError> {
        Err(StorageError::Backend("taint storage not supported".into()))
    }

    /// Back-patch the `commit_id` onto a freshly-inserted taint
    /// after the repository has written the intent commit. A no-op
    /// if the taint is already resolved.
    fn set_taint_commit_id(&self, _id: &str, _commit_id: &str) -> Result<(), StorageError> {
        Err(StorageError::Backend("taint storage not supported".into()))
    }
}

/// Combined storage trait for convenience.
/// A backend that implements all seven sub-traits.
pub trait Storage:
    ObjectStore + CommitStore + RefStore + EpochStore + SessionStore + TaintStore + ReminderStore
{
}

/// Blanket implementation: anything implementing all seven traits is a Storage.
impl<
    T: ObjectStore + CommitStore + RefStore + EpochStore + SessionStore + TaintStore + ReminderStore,
> Storage for T
{
}