Skip to content

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.md
index 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
### Fixed
diff --git a/crates/ai-memory-store/src/error.rs b/crates/ai-memory-store/src/error.rs
index 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.rs
index 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.md
index 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 risk
corruption), so take a `ai-memory backup` before upgrading if you might need
to 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.0
3.0 removes the 1.x `user add`, `user expire`, `user revive` and
diff --git a/docs/lifecycle-ops.md b/docs/lifecycle-ops.md
index 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 taken
by 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