Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors
Rust
fix(store): clear error when data schema is newer than the binary
zapatala270d5deb00c
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 68e2fa06..9b5f93f7 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -7,6 +7,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0## [Unreleased]+### Fixed+- Opening a store whose schema is *newer* than the running binary now fails+ with an actionable error instead of refinery's raw "migration V… is missing+ from the filesystem" wording. When an applied migration is absent from the+ binary's compiled-in set (the data was migrated by a newer ai-memory build),+ the store layer now returns `DataSchemaAhead`, which names the offending+ migration, reports the highest schema version this build ships, and tells the+ operator to run a build at least as new as the one that wrote the data. Every+ other migration failure is unchanged.+## [1.13.0] - 2026-07-14### Fixeddiff --git a/crates/ai-memory-store/src/error.rs b/crates/ai-memory-store/src/error.rsindex 4cf8ff86..3965ab89 100644--- a/crates/ai-memory-store/src/error.rs+++ b/crates/ai-memory-store/src/error.rs@@ -19,6 +19,28 @@ pub enum StoreError {#[error("migration: {0}")]Migration(#[from] refinery::Error),+ /// The store's schema is newer than this binary: an applied migration is+ /// absent from the compiled-in set (refinery reports this as+ /// `MissingVersion`). The data was written by a newer ai-memory build than+ /// the one now running, so the store is left untouched rather than opened+ /// against a schema this binary does not understand. This replaces+ /// refinery's misleading raw wording ("migration V… is missing from the+ /// filesystem"), which reads as if a file were deleted.+ #[error(+ "memory database schema is newer than this ai-memory build: the store \+ has migration {applied} applied, but this build only ships migrations \+ through V{supported}. Run an ai-memory release at least as new as the \+ one that wrote this data; a newer store cannot be opened by an older \+ binary."+ )]+ DataSchemaAhead {+ /// The applied migration this binary does not know about, formatted as+ /// `V{version} ({name})` (e.g. `V28 (sessions_devin_agent_kind)`).+ applied: String,+ /// The highest schema version this binary ships.+ supported: u32,+ },+/// I/O failed (e.g. opening the DB file).#[error(transparent)]Io(#[from] std::io::Error),diff --git a/crates/ai-memory-store/src/migrations.rs b/crates/ai-memory-store/src/migrations.rsindex 389dd798..5d5677a0 100644--- a/crates/ai-memory-store/src/migrations.rs+++ b/crates/ai-memory-store/src/migrations.rs@@ -1,16 +1,46 @@//! refinery-driven schema migrations.+use crate::error::{StoreError, StoreResult};+refinery::embed_migrations!("migrations");/// Run all pending migrations against an open connection.////// # Errors-/// Propagates the underlying refinery error if a migration fails.-pub fn run(conn: &mut rusqlite::Connection) -> Result<(), refinery::Error> {- migrations::runner().run(conn)?;+/// Propagates the underlying refinery error if a migration fails. When the+/// store is *ahead* of this binary — an applied migration is absent from the+/// compiled-in set, which refinery reports as `MissingVersion` with the+/// misleading text "migration V… is missing from the filesystem" — the error+/// is remapped to [`StoreError::DataSchemaAhead`], which names the offending+/// migration and points the operator at the fix.+pub fn run(conn: &mut rusqlite::Connection) -> StoreResult<()> {+ migrations::runner().run(conn).map_err(classify_run_error)?;Ok(())}+/// Highest schema version baked into this binary (the max embedded migration).+fn max_supported_version() -> u32 {+ migrations::runner()+ .get_migrations()+ .iter()+ .map(refinery::Migration::version)+ .max()+ .unwrap_or(0)+}++/// Translate refinery's raw error into a store-domain error. The only variant+/// reshaped is `MissingVersion` (the store's schema is ahead of this binary);+/// every other refinery failure passes through as [`StoreError::Migration`].+fn classify_run_error(err: refinery::Error) -> StoreError {+ if let refinery::error::Kind::MissingVersion(applied) = err.kind() {+ return StoreError::DataSchemaAhead {+ applied: format!("V{} ({})", applied.version(), applied.name()),+ supported: max_supported_version(),+ };+ }+ StoreError::Migration(err)+}+#[cfg(test)]pub(crate) fn run_to(conn: &mut rusqlite::Connection, target: u32) -> Result<(), refinery::Error> {migrations::runner()@@ -18,3 +48,67 @@ pub(crate) fn run_to(conn: &mut rusqlite::Connection, target: u32) -> Result<(),.run(conn)?;Ok(())}++#[cfg(test)]+mod tests {+ use super::*;+ use rusqlite::{Connection, params};++ /// A store migrated by a newer build (an applied version above anything+ /// this binary embeds) must fail to open with the actionable+ /// `DataSchemaAhead` error, not refinery's raw "missing from the+ /// filesystem" wording.+ #[test]+ fn data_ahead_of_binary_reports_schema_ahead_not_raw_refinery() {+ let tmp = tempfile::TempDir::new().unwrap();+ let db_path = tmp.path().join("memory.sqlite");+ let mut conn = Connection::open(&db_path).unwrap();++ // Bring the store up to this binary's current schema.+ run(&mut conn).unwrap();++ // Simulate data written by a *newer* build: forge an applied migration+ // whose version sits above the embedded ceiling. refinery stores+ // `applied_on` as RFC3339 and `checksum` as a u64 string, and parses+ // both eagerly, so the row must be well-formed.+ let future = max_supported_version() + 100;+ conn.execute(+ "INSERT INTO refinery_schema_history (version, name, applied_on, checksum) \+ VALUES (?1, ?2, ?3, ?4)",+ params![future, "future_feature", "2026-07-14T00:00:00Z", "0"],+ )+ .unwrap();++ let err = run(&mut conn).unwrap_err();+ match err {+ StoreError::DataSchemaAhead { applied, supported } => {+ assert!(applied.contains(&format!("V{future}")), "applied={applied}");+ assert!(applied.contains("future_feature"), "applied={applied}");+ assert_eq!(supported, max_supported_version());+ }+ other => panic!("expected DataSchemaAhead, got: {other:?}"),+ }+ }++ /// The rendered message must drop refinery's misleading phrasing and carry+ /// the operator-facing explanation and remedy.+ #[test]+ fn schema_ahead_message_is_actionable() {+ let rendered = StoreError::DataSchemaAhead {+ applied: "V99 (future_feature)".to_string(),+ supported: 28,+ }+ .to_string();++ assert!(+ !rendered.contains("missing from the filesystem"),+ "must not leak refinery's raw wording: {rendered}"+ );+ assert!(+ rendered.contains("newer than this ai-memory build"),+ "{rendered}"+ );+ assert!(rendered.contains("V99 (future_feature)"), "{rendered}");+ assert!(rendered.contains("through V28"), "{rendered}");+ }+}