Skip to content

Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors

Rust

fix(store): repair the released V62 checksum (#1443)

AkitaOnRails4d10cc1bd531
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index e2ebb86e..10e3f4b7 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -414,6 +414,8 @@ jobs:
- run: scripts/check-changelog-sections.sh
- name: released sections stay frozen
run: scripts/check-changelog-frozen.sh "origin/${{ github.base_ref || github.event.repository.default_branch }}"
+ - name: released database migrations stay frozen
+ run: scripts/check-migrations-immutable.sh "origin/${{ github.base_ref || github.event.repository.default_branch }}"
# End-to-end docker smoke: packages the release-build binary and confirms
# the image runs. Catches Dockerfile drift (missing COPY, bad ENTRYPOINT)
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 5c60054c..37fe4b6c 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -12,6 +12,12 @@ version in [`docs/changelog/`](docs/changelog/):
## [Unreleased]
### Fixed
+- Repaired the exact migration checksum recorded by v2.2.1 for the original
+ V62 page-window migration before running strict migration validation. This
+ removes the false divergence error on every upgraded-server start while
+ keeping unknown migration edits fatal. CI now rejects changes to migration
+ files already present on a PR's base branch.
+ ([#1443](https://github.com/akitaonrails/ai-memory/issues/1443))
- Sent `response_format=json_schema` for structured OpenCode Chat Completions
calls, with the existing tolerant fallback for models that reject it, so
`memory_query answer=true` no longer receives unstructured prose by default.
diff --git a/crates/ai-memory-store/src/migrations.rs b/crates/ai-memory-store/src/migrations.rs
index 7410a0fb..6f4c8536 100644
--- a/crates/ai-memory-store/src/migrations.rs
+++ b/crates/ai-memory-store/src/migrations.rs
@@ -4,6 +4,11 @@ use crate::error::{StoreError, StoreResult};
refinery::embed_migrations!("migrations");
+/// Checksum recorded by refinery for the V62 SQL shipped in v2.2.1.
+const ORIGINAL_V62_CHECKSUM: u64 = 16_518_128_245_137_964_566;
+const V62_VERSION: u32 = 62;
+const V62_NAME: &str = "page_ingestion_windows";
+
/// Run all pending migrations against an open connection.
///
/// # Errors
@@ -14,29 +19,56 @@ refinery::embed_migrations!("migrations");
/// 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<()> {
+ repair_original_v62_checksum(conn)?;
migrations::runner()
- // Tolerate a divergent checksum on an already-applied migration.
- //
- // V62 was reshaped in place (#776) from an in-migration backfill to
- // DDL-only + a chunked boot-path backfill (`ops::backfill_page_windows`).
- // A store that applied the ORIGINAL V62 recorded that migration's
- // checksum in `refinery_schema_history`; the embedded V62 now hashes
- // differently, which refinery's default `abort_divergent = true` would
- // reject as `DivergentVersion`, refusing to open a correctly-migrated
- // store. Those stores already have the columns fully backfilled, so the
- // boot step is inert for them — opening is safe. Relaxing divergence is
- // the intentional cost of an in-place migration reshape.
- //
- // `abort_missing` stays TRUE: a store whose applied version is *ahead*
- // of this binary must still fail closed with the actionable
- // `DataSchemaAhead` error (the schema-version pin), not open silently.
- .set_abort_divergent(false)
+ .set_abort_divergent(true)
.set_abort_missing(true)
.run(conn)
.map_err(classify_run_error)?;
Ok(())
}
+/// Rewrite only the known V62 checksum produced by v2.2.1. The replacement
+/// SQL moved an equivalent backfill to the bounded boot path (#776); stores
+/// that applied the original migration are already in the same end state.
+/// Every other checksum mismatch remains a hard refinery error.
+fn repair_original_v62_checksum(conn: &rusqlite::Connection) -> StoreResult<()> {
+ let has_history: bool = conn.query_row(
+ "SELECT EXISTS(SELECT 1 FROM sqlite_master \
+ WHERE type = 'table' AND name = 'refinery_schema_history')",
+ [],
+ |row| row.get(0),
+ )?;
+ if !has_history {
+ return Ok(());
+ }
+ let Some(current_checksum) = migrations::runner()
+ .get_migrations()
+ .iter()
+ .find(|migration| migration.version() == V62_VERSION)
+ .map(refinery::Migration::checksum)
+ else {
+ return Ok(());
+ };
+ let repaired = conn.execute(
+ "UPDATE refinery_schema_history SET checksum = ?1 \
+ WHERE version = ?2 AND name = ?3 AND checksum = ?4",
+ rusqlite::params![
+ current_checksum.to_string(),
+ V62_VERSION,
+ V62_NAME,
+ ORIGINAL_V62_CHECKSUM.to_string()
+ ],
+ )?;
+ if repaired == 1 {
+ tracing::info!(
+ version = V62_VERSION,
+ "repaired known V62 migration checksum from the v2.2.1 layout"
+ );
+ }
+ Ok(())
+}
+
/// Highest schema version baked into this binary (the max embedded migration).
fn max_supported_version() -> u32 {
migrations::runner()
@@ -1585,25 +1617,24 @@ mod tests {
assert_eq!(previous, ("claude-code".into(), "native-1".into()));
}
- /// V62 was reshaped in place (#776) from an in-migration backfill to
- /// DDL-only + a boot-path backfill, changing its checksum. A store that
- /// applied the ORIGINAL V62 recorded the old checksum; `run` must still
- /// open it (divergence tolerated) rather than aborting with
- /// `DivergentVersion` — while a strict runner would reject it, proving
- /// the relaxation is load-bearing. `abort_missing` stays true, so a
- /// schema that is genuinely *ahead* still fails closed (covered by
- /// `data_ahead_of_binary_reports_schema_ahead_not_raw_refinery`).
+ /// The one known V62 checksum is repaired before the strict runner sees
+ /// it. An arbitrary mismatch still fails closed.
#[test]
- fn reshaped_migration_divergent_checksum_is_tolerated() {
+ fn only_the_original_v62_checksum_is_repaired() {
let mut conn = Connection::open_in_memory().unwrap();
run(&mut conn).unwrap();
+ let current_checksum = migrations::runner()
+ .get_migrations()
+ .iter()
+ .find(|migration| migration.version() == V62_VERSION)
+ .unwrap()
+ .checksum();
+ assert_ne!(current_checksum, ORIGINAL_V62_CHECKSUM);
- // Simulate the original V62's recorded checksum by rewriting the
- // stored value so it no longer matches the embedded migration.
let rewritten = conn
.execute(
- "UPDATE refinery_schema_history SET checksum = '0' WHERE version = 62",
- [],
+ "UPDATE refinery_schema_history SET checksum = ?1 WHERE version = ?2",
+ params![ORIGINAL_V62_CHECKSUM.to_string(), V62_VERSION],
)
.unwrap();
assert_eq!(rewritten, 1, "V62 history row must exist to diverge");
@@ -1618,10 +1649,34 @@ mod tests {
Ok(_) => panic!("strict runner should reject a divergent checksum"),
}
- // The production path tolerates it: the already-migrated store opens.
- run(&mut conn).expect("divergence must be tolerated so migrated stores open");
+ run(&mut conn).expect("the released V62 checksum must be repaired");
+ let repaired: String = conn
+ .query_row(
+ "SELECT checksum FROM refinery_schema_history WHERE version = ?1",
+ [V62_VERSION],
+ |row| row.get(0),
+ )
+ .unwrap();
+ assert_eq!(repaired, current_checksum.to_string());
- // And the boot backfill is inert on such a store (no NULL windows).
+ conn.execute(
+ "UPDATE refinery_schema_history SET checksum = '0' WHERE version = ?1",
+ [V62_VERSION],
+ )
+ .unwrap();
+ match run(&mut conn).unwrap_err() {
+ StoreError::Migration(err) => assert!(matches!(
+ err.kind(),
+ refinery::error::Kind::DivergentVersion(_, _)
+ )),
+ other => panic!("unknown divergence must remain fatal: {other:?}"),
+ }
+
+ conn.execute(
+ "UPDATE refinery_schema_history SET checksum = ?1 WHERE version = ?2",
+ params![current_checksum.to_string(), V62_VERSION],
+ )
+ .unwrap();
let summary = crate::ops::backfill_page_windows(&mut conn).unwrap();
assert_eq!(summary, crate::ops::PageWindowBackfillSummary::default());
}
diff --git a/scripts/check-migrations-immutable.sh b/scripts/check-migrations-immutable.sh
new file mode 100755
index 00000000..360ec022
--- /dev/null
+++ b/scripts/check-migrations-immutable.sh
@@ -0,0 +1,26 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+base_ref=${1:-origin/main}
+if ! git rev-parse --verify --quiet "$base_ref^{commit}" >/dev/null; then
+ echo "check-migrations-immutable: base ref '$base_ref' not found; skipping" >&2
+ exit 0
+fi
+
+merge_base=$(git merge-base "$base_ref" HEAD)
+status=0
+while IFS= read -r path; do
+ [[ -n "$path" ]] || continue
+ if git cat-file -e "$merge_base:$path" 2>/dev/null; then
+ echo "existing migration changed: $path" >&2
+ status=1
+ fi
+done < <(
+ git diff --name-only "$merge_base"...HEAD -- \
+ 'crates/ai-memory-store/migrations/V*.sql'
+)
+
+if (( status != 0 )); then
+ echo "shipped migrations are immutable; add a new Vnn migration instead" >&2
+fi
+exit "$status"