Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors
Rust
fix(store): distinguish migration history gaps from newer schemas
Samir Hanna Verza6262a9b449a2
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 9c12c145..ca18a5fe 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -11,6 +11,13 @@ version in [`docs/changelog/`](docs/changelog/):## [Unreleased]+### Fixed++- Corrected the startup error for a gap in SQLite migration history. A+ skipped earlier migration is now reported as missing from the history,+ instead of claiming the store is newer than the binary. The store still+ refuses to open until its migration history can be reviewed (#1612).+## [3.2.1] - 2026-10-22### Fixeddiff --git a/crates/ai-memory-store/src/error.rs b/crates/ai-memory-store/src/error.rsindex aa86777a..02d2544f 100644--- a/crates/ai-memory-store/src/error.rs+++ b/crates/ai-memory-store/src/error.rs@@ -71,7 +71,7 @@ pub enum StoreError {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+ /// above the highest compiled-in version (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@@ -92,6 +92,20 @@ pub enum StoreError {supported: u32,},+ /// An embedded migration is absent from the store's history even though a+ /// later version is already applied. Opening remains refused; deciding how+ /// to repair a divergent history requires inspecting the actual schema.+ #[error(+ "memory database migration history has a gap: migration {missing} is \+ not recorded, but a later migration is already applied. Back up the \+ data directory and report the migration history for review before \+ attempting a repair."+ )]+ MigrationHistoryGap {+ /// Missing embedded migration, formatted as `V{version} ({name})`.+ missing: String,+ },+/// 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 fb0da788..09aff7fe 100644--- a/crates/ai-memory-store/src/migrations.rs+++ b/crates/ai-memory-store/src/migrations.rs@@ -17,11 +17,10 @@ const V62_NAME: &str = "page_ingestion_windows";////// # Errors/// 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.+/// store is *ahead* of this binary, the error is remapped to+/// [`StoreError::DataSchemaAhead`]. An earlier embedded migration missing from+/// the store's history instead reports [`StoreError::MigrationHistoryGap`].+/// refinery reports both conditions as `MissingVersion`.pub fn run(conn: &mut rusqlite::Connection) -> StoreResult<()> {repair_known_migration_checksums(conn)?;migrations::runner()@@ -128,15 +127,23 @@ fn max_supported_version() -> u32 {.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`].+/// Translate refinery's two `MissingVersion` cases without confusing a+/// skipped migration with a downgrade. Every other failure passes through.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(),- };+ if let refinery::error::Kind::MissingVersion(migration) = err.kind() {+ let identity = format!("V{} ({})", migration.version(), migration.name());+ // refinery returns the embedded (unapplied) migration when an older+ // version was skipped, and the history row when a build lacks it.+ if migration.applied_on().is_none() {+ return StoreError::MigrationHistoryGap { missing: identity };+ }+ let supported = max_supported_version();+ if migration.version() > supported {+ return StoreError::DataSchemaAhead {+ applied: identity,+ supported,+ };+ }}StoreError::Migration(err)}@@ -193,6 +200,55 @@ mod tests {}}+ #[test]+ fn missing_earlier_migration_reports_a_history_gap_without_applying_anything() {+ let mut conn = Connection::open_in_memory().unwrap();+ // Between v2.3.2 and v2.4, main briefly contained V66 before it+ // received V65 from release/2.4 (#1612).+ let historical: Vec<_> = migrations::runner()+ .get_migrations()+ .iter()+ .filter(|migration| migration.version() <= 66 && migration.version() != 65)+ .cloned()+ .collect();+ refinery::Runner::new(&historical).run(&mut conn).unwrap();+ let before = applied_versions(&conn);+ assert_eq!(before.last(), Some(&66));+ assert!(!before.contains(&65));++ let err = run(&mut conn).unwrap_err();+ let rendered = err.to_string();+ assert!(+ rendered.contains("migration history has a gap"),+ "{rendered}"+ );+ assert!(+ rendered.contains("V65 (page_compacted_marker)"),+ "{rendered}"+ );+ assert!(rendered.contains("not recorded"), "{rendered}");+ assert!(!rendered.contains("newer than"), "{rendered}");+ assert_eq!(applied_versions(&conn), before);+ let compacted_column: i64 = conn+ .query_row(+ "SELECT COUNT(*) FROM pragma_table_info('pages') WHERE name = 'compacted_at'",+ [],+ |row| row.get(0),+ )+ .unwrap();+ assert_eq!(compacted_column, 0, "a refused open must not apply V65");+ }++ #[test]+ fn an_ordinary_older_store_migrates_without_a_history_gap() {+ let mut conn = Connection::open_in_memory().unwrap();+ run_to(&mut conn, 64).unwrap();+ run(&mut conn).unwrap();+ let applied = applied_versions(&conn);+ assert!(applied.contains(&65) && applied.contains(&66));+ assert_eq!(applied.last(), Some(&i64::from(max_supported_version())));+ }+/// The rendered message must drop refinery's misleading phrasing and carry/// the operator-facing explanation and remedy.#[test]diff --git a/docs/install.md b/docs/install.mdindex 0f1c5106..e963a7a9 100644--- a/docs/install.md+++ b/docs/install.md@@ -3841,6 +3841,13 @@ will refuse to open that data dir (it fails closed rather than riskcorruption), so take a `ai-memory backup` before upgrading if you might needto roll back to the previous version.+If startup instead reports that the **migration history has a gap**, an+earlier migration is missing even though a later one is recorded. This can+occur with a development build whose migration sequence differed from the+released sequence. Keep a backup and report the missing migration and the+build used to create the store for review; startup does not automatically+repair the history or apply the skipped migration.+### Upgrading to 3.03.0 removes the 1.x `user add`, `user expire`, `user revive` anddiff --git a/docs/lifecycle-ops.md b/docs/lifecycle-ops.mdindex 894c3977..ab0070be 100644--- a/docs/lifecycle-ops.md+++ b/docs/lifecycle-ops.md@@ -1229,6 +1229,10 @@ Failure modes:a snapshot the current binary cannot open** (for example a backup takenby a newer release) → exits with the error; the existing `wiki/` and`db/` are left as they were.+- **Migration history has a gap** → an earlier migration is unrecorded+ although a later one was applied. The staged store is refused, just as at+ normal startup. Keep the backup and report the history for review;+ `--force` does not bypass this check or repair the missing migration.- **Legacy backup has API keys but no pepper verifier** → restore the original`[auth].token_pepper` through the current config/environment and rerun with`--accept-legacy-api-key-pepper`. This flag confirms provenance; it cannot