Skip to content

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

Rust

test(store): pin released V62 checksum provenance

AkitaOnRailse16855e72c54
diff --git a/crates/ai-memory-store/src/migrations.rs b/crates/ai-memory-store/src/migrations.rs
index 6f4c8536..8985b925 100644
--- a/crates/ai-memory-store/src/migrations.rs
+++ b/crates/ai-memory-store/src/migrations.rs
@@ -5,6 +5,10 @@ use crate::error::{StoreError, StoreResult};
refinery::embed_migrations!("migrations");
/// Checksum recorded by refinery for the V62 SQL shipped in v2.2.1.
+///
+/// The historical SQL is pinned in
+/// `testdata/V62__page_ingestion_windows.pre776.sql`; a regression test
+/// derives this value through refinery's own checksum implementation.
const ORIGINAL_V62_CHECKSUM: u64 = 16_518_128_245_137_964_566;
const V62_VERSION: u32 = 62;
const V62_NAME: &str = "page_ingestion_windows";
@@ -1617,6 +1621,18 @@ mod tests {
assert_eq!(previous, ("claude-code".into(), "native-1".into()));
}
+ /// The repair constant comes from the released SQL, not a remembered
+ /// value that could silently drift from its provenance.
+ #[test]
+ fn original_v62_checksum_matches_the_released_sql() {
+ let released_sql = include_str!("testdata/V62__page_ingestion_windows.pre776.sql");
+ let checksum = refinery::Migration::unapplied("V62__page_ingestion_windows", released_sql)
+ .expect("the released V62 fixture must remain a valid migration")
+ .checksum();
+
+ assert_eq!(checksum, ORIGINAL_V62_CHECKSUM);
+ }
+
/// The one known V62 checksum is repaired before the strict runner sees
/// it. An arbitrary mismatch still fails closed.
#[test]
diff --git a/crates/ai-memory-store/src/testdata/V62__page_ingestion_windows.pre776.sql b/crates/ai-memory-store/src/testdata/V62__page_ingestion_windows.pre776.sql
new file mode 100644
index 00000000..28917fb7
--- /dev/null
+++ b/crates/ai-memory-store/src/testdata/V62__page_ingestion_windows.pre776.sql
@@ -0,0 +1,48 @@
+-- Page-grain ingestion windows (issue #656,
+-- docs/design-page-ingestion-windows.md): materialize each page version's
+-- ingestion window so `as_of` can run version-filtered FTS alongside the
+-- V56 entity-link windows. Same dimension, same predicate shape, page
+-- grain: `valid_from` is the version's own `created_at`; `valid_to` is the
+-- superseding version's `created_at` (NULL while the version is latest).
+--
+-- Additive like V56: two nullable columns + index + one-shot backfill. No
+-- row is deleted or rewritten beyond the two new columns, and re-running
+-- the UPDATEs converges on the same values. Like every refinery step, an
+-- older binary fails closed on the migrated store (DataSchemaAhead) —
+-- rollback is the boot-path pre-migration snapshot (serve.rs, #633), not
+-- a downgrade read. No per-migration gate beyond the standard refinery
+-- step, matching V56-V61.
+--
+-- `valid_to`, not `superseded_at`: `pages.superseded_at` already means
+-- the V03 decay-tombstone eviction marker (written exactly when
+-- `supersedes IS NULL`), so reusing the name would conflate "evicted by
+-- the forget sweep" with "replaced by a newer version".
+
+ALTER TABLE pages ADD COLUMN valid_from INTEGER;
+ALTER TABLE pages ADD COLUMN valid_to INTEGER;
+
+UPDATE pages SET valid_from = created_at;
+
+-- Ordinary supersession: close at the earliest successor's birth.
+UPDATE pages SET valid_to = (
+ SELECT MIN(s.created_at) FROM pages s WHERE s.supersedes = pages.id
+) WHERE EXISTS (SELECT 1 FROM pages s WHERE s.supersedes = pages.id);
+
+-- Successor-less retirements (decay tombstones, graveyard merges,
+-- move-regenerate rows — the V58 class): close at the decay eviction
+-- marker when present, else the existing link-window close. Reorg and
+-- move-regenerate recorded their retirement there without updating the
+-- page's updated_at. Only fall back to updated_at when neither grain
+-- retained the retirement instant. Latest versions stay open.
+UPDATE pages SET valid_to = COALESCE(
+ superseded_at,
+ (SELECT MIN(l.superseded_at) FROM entity_page_links l WHERE l.page_id = pages.id),
+ updated_at
+)
+WHERE is_latest = 0 AND valid_to IS NULL
+ AND NOT EXISTS (SELECT 1 FROM pages s WHERE s.supersedes = pages.id);
+
+-- The as_of window scan over page versions: (scope, window) probes ride
+-- this, mirroring idx_entity_page_links_validity at link grain.
+CREATE INDEX idx_pages_validity
+ ON pages(workspace_id, project_id, valid_from, valid_to);
diff --git a/docs/design-memory-aging.md b/docs/design-memory-aging.md
index 15c57686..3d5a6ee5 100644
--- a/docs/design-memory-aging.md
+++ b/docs/design-memory-aging.md
@@ -424,11 +424,11 @@ phase, and encodes the lessons from that incident.
New migrations start at **V65** and are additive. A2's `compacted_at` is an
`ADD COLUMN` (nullable): instant, no table rewrite, no lock on a large store.
No shipped migration's SQL is ever edited in place: doing so trips refinery's
-divergence check, which is exactly why `migrations.rs:33-34` sets
-`set_abort_divergent(false)` (a hash mismatch on an already-applied migration is
-tolerated) while keeping `set_abort_missing(true)` (a store *ahead* of the binary
-fails closed). Any change to a shipped migration must preserve that
-divergence-tolerance handling.
+divergence check. V62 is the historical exception. Its exact v2.2.1 checksum is
+repaired to the embedded checksum before the runner starts (#1443), after which
+`set_abort_divergent(true)` keeps every unknown edit fatal. `set_abort_missing(true)`
+also keeps a store *ahead* of the binary fail-closed. Future changes must never
+edit a shipped migration in place or broaden the narrow V62 repair.
**Any data backfill runs on the boot path, not inside the migration
transaction**: chunked, resumable, and WAL-checkpointed, mirroring the #776
diff --git a/docs/design-page-ingestion-windows.md b/docs/design-page-ingestion-windows.md
index 8d0521bf..95fd2a40 100644
--- a/docs/design-page-ingestion-windows.md
+++ b/docs/design-page-ingestion-windows.md
@@ -22,10 +22,10 @@ invoked from `Store::open` next to the entity-index backfill) that
reproduces the identical end state in bounded batches, checkpoints the
WAL (`TRUNCATE`) between each, logs progress, resumes rather than
restarts if interrupted, and no-ops on a store already backfilled. The
-in-place reshape changes V62's checksum, so the migration runner now
-tolerates a divergent checksum on an already-applied migration
-(`abort_divergent = false`, `abort_missing` unchanged) so
-correctly-migrated stores still open.*
+in-place reshape changed V62's checksum. The migration runner repairs only
+the exact checksum recorded for the SQL shipped in v2.2.1 before running
+strict validation; correctly-migrated stores still open, while every unknown
+checksum divergence remains fatal (#1443).*
## 1. The problem, and why entity-link windows are not enough