sqlite_graphrag/memory_source.rs
1//! Type-safe enumeration of the `memories.source` column domain.
2//!
3//! The CHECK constraint on the `memories` table accepts exactly five values:
4//! `agent`, `user`, `system`, `import`, `sync`. Any other literal is rejected
5//! at runtime by SQLite with `SQLITE_CONSTRAINT_CHECK`.
6//!
7//! This enum eliminates the silent footgun of `pub source: String` by forcing
8//! every call-site to pick a typed variant that maps deterministically to one
9//! of the five allowed CHECK values via [`MemorySource::as_str`].
10//!
11//! # Examples
12//!
13//! ```
14//! use sqlite_graphrag::memory_source::MemorySource;
15//!
16//! let src = MemorySource::Agent;
17//! assert_eq!(src.as_str(), "agent");
18//!
19//! let parsed = MemorySource::try_from("user").expect("user is valid");
20//! assert_eq!(parsed, MemorySource::User);
21//!
22//! let err = MemorySource::try_from("enrich").unwrap_err();
23//! assert!(format!("{err}").contains("invalid memory source"));
24//! ```
25
26use crate::errors::AppError;
27use serde::{Deserialize, Serialize};
28
29/// Enumerates the five values accepted by the `memories.source` CHECK constraint.
30///
31/// Adding a new variant requires:
32///
33/// 1. Updating the DDL CHECK constraint in `migrations/V001__init.sql`.
34/// 2. Running a migration that backfills any pre-existing values
35/// (`UPDATE memories SET source='agent' WHERE source NOT IN (...)`).
36/// 3. Bumping [`crate::constants::CURRENT_SCHEMA_VERSION`].
37#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
38#[serde(rename_all = "snake_case")]
39pub enum MemorySource {
40 /// Mutated by an LLM agent (remember, edit, rename, body-enrich).
41 Agent,
42 /// Mutated by a human operator.
43 User,
44 /// Mutated by an internal migration or system job.
45 System,
46 /// Inserted by bulk import (ingest, ingest --mode claude-code, ingest --mode codex).
47 Import,
48 /// Inserted by an external sync job.
49 Sync,
50}
51
52impl MemorySource {
53 /// Returns the canonical snake_case string stored in the SQLite column.
54 ///
55 /// The returned slice has `'static` lifetime because all five values are
56 /// ASCII literals known at compile time.
57 pub const fn as_str(self) -> &'static str {
58 match self {
59 Self::Agent => "agent",
60 Self::User => "user",
61 Self::System => "system",
62 Self::Import => "import",
63 Self::Sync => "sync",
64 }
65 }
66
67 /// Returns every variant as a static slice, useful for error messages and docs.
68 pub const ALL: &'static [MemorySource] = &[
69 Self::Agent,
70 Self::User,
71 Self::System,
72 Self::Import,
73 Self::Sync,
74 ];
75}
76
77impl std::fmt::Display for MemorySource {
78 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
79 f.write_str(self.as_str())
80 }
81}
82
83/// Parses a stored `memories.source` string back into a typed variant.
84///
85/// # Errors
86///
87/// Returns [`AppError::Validation`] when the input is not one of the five
88/// canonical values. The error message lists every accepted value so the
89/// caller can self-correct without consulting the schema.
90impl TryFrom<&str> for MemorySource {
91 type Error = AppError;
92
93 fn try_from(value: &str) -> Result<Self, Self::Error> {
94 match value {
95 "agent" => Ok(Self::Agent),
96 "user" => Ok(Self::User),
97 "system" => Ok(Self::System),
98 "import" => Ok(Self::Import),
99 "sync" => Ok(Self::Sync),
100 other => Err(AppError::Validation(crate::i18n::validation::invalid_memory_source(
101 &format!("{other:?}"),
102 &Self::ALL
103 .iter()
104 .map(|v| v.as_str())
105 .collect::<Vec<_>>()
106 .join(", "),
107 ))),
108 }
109 }
110}
111
112impl TryFrom<String> for MemorySource {
113 type Error = AppError;
114
115 fn try_from(value: String) -> Result<Self, Self::Error> {
116 Self::try_from(value.as_str())
117 }
118}
119
120/// Validates a raw `memories.source` string against the CHECK constraint domain.
121///
122/// This is the runtime guard for callers that still take `&str` (legacy
123/// call-sites, FTS rows already in the database, deserialised JSON). The
124/// function returns the canonical slice on success and an [`AppError::Validation`]
125/// on failure, with an actionable message listing every accepted value.
126///
127/// Use this at every boundary that touches the `source` column:
128/// `memories::insert`, `memories::update`, and any new code path that
129/// builds a `NewMemory` from operator-supplied input. It is the safety
130/// net that prevented the original G29 bug from regressing in v1.0.69
131/// when the typed [`MemorySource`] enum was still being rolled out.
132pub fn validate_source(raw: &str) -> Result<&'static str, AppError> {
133 match raw {
134 "agent" => Ok("agent"),
135 "user" => Ok("user"),
136 "system" => Ok("system"),
137 "import" => Ok("import"),
138 "sync" => Ok("sync"),
139 other => Err(AppError::Validation(crate::i18n::validation::invalid_memory_source(
140 &format!("{other:?}"),
141 &MemorySource::ALL
142 .iter()
143 .map(|v| v.as_str())
144 .collect::<Vec<_>>()
145 .join(", "),
146 ))),
147 }
148}
149
150#[cfg(test)]
151mod tests {
152 use super::*;
153
154 #[test]
155 fn as_str_returns_canonical_lowercase() {
156 assert_eq!(MemorySource::Agent.as_str(), "agent");
157 assert_eq!(MemorySource::User.as_str(), "user");
158 assert_eq!(MemorySource::System.as_str(), "system");
159 assert_eq!(MemorySource::Import.as_str(), "import");
160 assert_eq!(MemorySource::Sync.as_str(), "sync");
161 }
162
163 #[test]
164 fn try_from_valid_strings_succeeds() {
165 assert_eq!(
166 MemorySource::try_from("agent").unwrap(),
167 MemorySource::Agent
168 );
169 assert_eq!(MemorySource::try_from("user").unwrap(), MemorySource::User);
170 assert_eq!(
171 MemorySource::try_from("system").unwrap(),
172 MemorySource::System
173 );
174 assert_eq!(
175 MemorySource::try_from("import").unwrap(),
176 MemorySource::Import
177 );
178 assert_eq!(MemorySource::try_from("sync").unwrap(), MemorySource::Sync);
179 }
180
181 #[test]
182 fn try_from_invalid_string_returns_err() {
183 // G29 reproducer: "enrich" is the historical bug.
184 let err = MemorySource::try_from("enrich").unwrap_err();
185 let msg = format!("{err}");
186 assert!(msg.contains("invalid memory source"), "got: {msg}");
187 assert!(msg.contains("\"enrich\""), "got: {msg}");
188 assert!(msg.contains("agent"), "must list agent as valid: {msg}");
189 }
190
191 #[test]
192 fn try_from_empty_string_returns_err() {
193 assert!(MemorySource::try_from("").is_err());
194 }
195
196 #[test]
197 fn try_from_string_owned_works() {
198 let src: MemorySource = String::from("agent").try_into().unwrap();
199 assert_eq!(src, MemorySource::Agent);
200 }
201
202 #[test]
203 fn display_matches_as_str() {
204 for v in MemorySource::ALL {
205 assert_eq!(format!("{v}"), v.as_str());
206 }
207 }
208
209 #[test]
210 fn serialize_round_trip_preserves_variant() {
211 let v = MemorySource::Import;
212 let json = serde_json::to_string(&v).unwrap();
213 assert_eq!(json, "\"import\"");
214 let back: MemorySource = serde_json::from_str(&json).unwrap();
215 assert_eq!(back, v);
216 }
217
218 #[test]
219 fn all_slice_has_exactly_five_variants() {
220 assert_eq!(MemorySource::ALL.len(), 5);
221 }
222}