Skip to content

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.md
index 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
### Fixed
diff --git a/crates/ai-memory-store/src/error.rs b/crates/ai-memory-store/src/error.rs
index 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.rs
index 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}");
+ }
+}