context_forge/
traits.rs

1use crate::entry::{ContextEntry, ScoredEntry};
2use crate::error::Error;
3
4/// Result type alias for crate operations.
5pub type Result<T> = std::result::Result<T, Error>;
6
7/// Trait for persisting and retrieving context entries.
8///
9/// Implementations must be thread-safe (`Send + Sync`) to support
10/// concurrent access from multiple worker threads.
11pub trait ContextStorage: Send + Sync {
12    /// Persist a single entry.
13    ///
14    /// # Security
15    ///
16    /// Implementations persist `entry.content` verbatim — secret scrubbing
17    /// happens only in [`ContextForge::save`](crate::ContextForge::save).
18    /// Callers writing through this trait directly are responsible for
19    /// scrubbing first (see [`scrub_secrets`](crate::scrub_secrets)).
20    ///
21    /// # Errors
22    ///
23    /// Returns an error if the underlying storage write fails.
24    fn save(&self, entry: &ContextEntry) -> Result<()>;
25
26    /// Return the top-k entries (most recent or highest priority).
27    ///
28    /// # Errors
29    ///
30    /// Returns an error if the underlying storage read fails.
31    fn get_top_k(&self, k: usize) -> Result<Vec<ContextEntry>>;
32
33    /// Return every stored entry.
34    ///
35    /// # Errors
36    ///
37    /// Returns an error if the underlying storage read fails.
38    fn get_all(&self) -> Result<Vec<ContextEntry>>;
39
40    /// Delete an entry by id. Returns `true` if an entry was removed.
41    ///
42    /// # Errors
43    ///
44    /// Returns an error if the underlying storage delete fails.
45    fn delete(&self, id: &str) -> Result<bool>;
46
47    /// Remove all entries. Returns the number of entries removed.
48    ///
49    /// # Errors
50    ///
51    /// Returns an error if the underlying storage delete fails.
52    fn clear(&self) -> Result<usize>;
53
54    /// Remove all entries within a given scope. Returns the number of entries removed.
55    ///
56    /// # Errors
57    ///
58    /// Returns an error if the underlying storage delete fails.
59    fn clear_scope(&self, scope: &str) -> Result<usize>;
60
61    /// Return the total number of stored entries.
62    ///
63    /// # Errors
64    ///
65    /// Returns an error if the underlying storage read fails.
66    fn count(&self) -> Result<usize>;
67}
68
69/// Trait for searching context entries by relevance.
70///
71/// Implementations must be thread-safe (`Send + Sync`) to support
72/// concurrent access from multiple worker threads.
73pub trait Searcher: Send + Sync {
74    /// Search for entries matching `query`, optionally restricted to `scope`,
75    /// returning at most `limit` results ordered by descending relevance score.
76    ///
77    /// `scope = None` searches every entry regardless of scope (global recall).
78    /// `scope = Some(s)` restricts results to entries whose `scope` equals `s`.
79    ///
80    /// `query` is treated as natural-language text: implementations should
81    /// split it into terms and OR-match them (e.g. via FTS5 bm25 ranking)
82    /// rather than requiring every term to match. Query-language operator
83    /// syntax (`AND`, `OR`, `NEAR`, prefix `*`, quoted phrases, column
84    /// filters, etc.) must **not** be interpreted from `query` — operator
85    /// characters are treated as term separators, so arbitrary text never
86    /// produces a syntax error. A query with no usable terms (empty or
87    /// punctuation-only) returns an empty result set, not an error. The
88    /// special value [`crate::engine::MATCH_ALL_QUERY`] (`"*"`) matches every
89    /// entry.
90    ///
91    /// # Errors
92    ///
93    /// Returns an error if the underlying search fails.
94    fn search(&self, query: &str, scope: Option<&str>, limit: usize) -> Result<Vec<ScoredEntry>>;
95}
context_forge/traits.rs

context_forge/
traits.rs
