Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors
Rust
feat(okf): backup-gated in-place migration of existing stores
AkitaOnRails0f516283edf5
diff --git a/Cargo.lock b/Cargo.lockindex e2134155..0618c42f 100644--- a/Cargo.lock+++ b/Cargo.lock@@ -273,15 +273,19 @@ dependencies = ["anyhow","async-trait","axum",+ "dirs",+ "flate2","futures-util","git2","jiff","notify","notify-debouncer-full","reqwest 0.12.28",+ "rusqlite","serde","serde_json","serde_yaml",+ "tar","tempfile","thiserror 2.0.18","tokio",diff --git a/crates/ai-memory-store/src/lib.rs b/crates/ai-memory-store/src/lib.rsindex 4b8bca8c..f25f51be 100644--- a/crates/ai-memory-store/src/lib.rs+++ b/crates/ai-memory-store/src/lib.rs@@ -51,8 +51,8 @@ pub use maintenance::MaintenanceJob;pub use ops::{AdmittedSession, CompactSummary, Compaction, DeleteWorkspaceSummary, EmbedOutcome,EmbeddingWrite, HookSessionAdmission, IngestObservationOutcome, LifecycleOnlyEndOutcome,- MoveSessionSummary, MoveSummary, ObservationPruneOutcome, PagesMode, PurgeSessionSummary,- PurgeSummary, ReorgSummary, purge_session, record_embed_failure,+ MoveSessionSummary, MoveSummary, ObservationPruneOutcome, OkfMigratedPage, PagesMode,+ PurgeSessionSummary, PurgeSummary, ReorgSummary, purge_session, record_embed_failure,};pub use reader::{ActivityWindow, AgentSessionCount, AuditEvent, AuditLogFilter, AutoImproveCandidateSession,diff --git a/crates/ai-memory-store/src/ops.rs b/crates/ai-memory-store/src/ops.rsindex def06169..b9b07f06 100644--- a/crates/ai-memory-store/src/ops.rs+++ b/crates/ai-memory-store/src/ops.rs@@ -598,6 +598,98 @@ pub(crate) fn path_search_text(path: &str) -> String {format!("{segments} {words}")}+/// Count latest page rows whose frontmatter is not yet OKF-conformant+/// (missing `type` or `generated.at`). Read-only; the migration uses it+/// to decide whether the backup gate must engage at all.+pub fn okf_nonconformant_latest_pages(conn: &Connection) -> StoreResult<u64> {+ let mut stmt = conn.prepare("SELECT path, frontmatter_json FROM pages WHERE is_latest = 1")?;+ let rows: Vec<(String, String)> = stmt+ .query_map([], |row| Ok((row.get(0)?, row.get(1)?)))?+ .collect::<Result<_, _>>()?;+ let mut pending = 0u64;+ for (path, fm_str) in rows {+ let fm: serde_json::Value = serde_json::from_str(&fm_str).unwrap_or_default();+ let mut conformed = fm.clone();+ ai_memory_core::okf::conform_frontmatter(&path, &mut conformed);+ if conformed != fm || ai_memory_core::okf::generated_at(&fm).is_none() {+ pending += 1;+ }+ }+ Ok(pending)+}++/// One latest-page row rewritten in place by [`okf_migrate_latest_pages`].+#[derive(Debug, Clone)]+pub struct OkfMigratedPage {+ /// Owning workspace.+ pub workspace_id: ai_memory_core::WorkspaceId,+ /// Owning project.+ pub project_id: ai_memory_core::ProjectId,+ /// Wiki-relative page path.+ pub path: String,+ /// The `generated.at` stamped from the row's own `updated_at`.+ pub generated_at: String,+}++/// One-shot OKF migration of every latest page row (docs/okf.md): conform+/// the frontmatter IN PLACE — same id, same version row, `updated_at`+/// untouched, body untouched — stamping `generated.at` from the row's own+/// `updated_at` so nothing looks freshly written. Historical versions+/// (`is_latest = 0`) stay as they were. Idempotent: conformed rows are+/// left alone, so a re-run rewrites zero pages.+pub fn okf_migrate_latest_pages(conn: &mut Connection) -> StoreResult<Vec<OkfMigratedPage>> {+ type LatestPageRow = (Vec<u8>, Vec<u8>, Vec<u8>, String, String, i64);+ let tx = conn.transaction()?;+ let mut migrated = Vec::new();+ {+ let mut stmt = tx.prepare(+ "SELECT id, workspace_id, project_id, path, frontmatter_json, updated_at FROM pages WHERE is_latest = 1",+ )?;+ let rows: Vec<LatestPageRow> = stmt+ .query_map([], |row| {+ Ok((+ row.get(0)?,+ row.get(1)?,+ row.get(2)?,+ row.get(3)?,+ row.get(4)?,+ row.get(5)?,+ ))+ })?+ .collect::<Result<_, _>>()?;+ drop(stmt);+ for (id, ws, proj, path, fm_str, updated_at) in rows {+ let fm: serde_json::Value = serde_json::from_str(&fm_str).unwrap_or_default();+ let mut conformed = fm.clone();+ ai_memory_core::okf::conform_frontmatter(&path, &mut conformed);+ let at = jiff::Timestamp::from_microsecond(updated_at)+ .unwrap_or(jiff::Timestamp::UNIX_EPOCH)+ .strftime("%Y-%m-%dT%H:%M:%SZ")+ .to_string();+ if ai_memory_core::okf::generated_at(&conformed).is_none() {+ ai_memory_core::okf::stamp_generated_at(&mut conformed, &at);+ }+ if conformed == fm {+ continue;+ }+ tx.execute(+ "UPDATE pages SET frontmatter_json = ?1 WHERE id = ?2",+ params![serde_json::to_string(&conformed)?, id],+ )?;+ migrated.push(OkfMigratedPage {+ workspace_id: ai_memory_core::WorkspaceId::from_slice(&ws)?,+ project_id: ai_memory_core::ProjectId::from_slice(&proj)?,+ path,+ generated_at: ai_memory_core::okf::generated_at(&conformed)+ .unwrap_or(&at)+ .to_string(),+ });+ }+ }+ tx.commit()?;+ Ok(migrated)+}+/// Stamp the per-version `generated.at` (write time, UTC) onto conformed/// frontmatter and serialize it. Runs only on the paths that create a new/// version row — the idempotent short-circuit above never reaches it, sodiff --git a/crates/ai-memory-store/src/writer.rs b/crates/ai-memory-store/src/writer.rsindex 1fdcab0e..daa63d55 100644--- a/crates/ai-memory-store/src/writer.rs+++ b/crates/ai-memory-store/src/writer.rs@@ -386,6 +386,14 @@ pub(crate) enum WriteCmd {author_id: Option<ai_memory_core::UserId>,reply: oneshot::Sender<StoreResult<()>>,},+ /// One-shot in-place OKF conformance of every latest page row.+ OkfMigrateLatestPages {+ reply: oneshot::Sender<StoreResult<Vec<ops::OkfMigratedPage>>>,+ },+ /// Read-only count of latest rows still lacking OKF conformance.+ OkfNonconformantCount {+ reply: oneshot::Sender<StoreResult<u64>>,+ },/// Record a successfully-applied wiki-structure migration.InsertWikiMigration {name: String,@@ -1602,6 +1610,31 @@ impl WriterHandle {rx.await.map_err(|_| StoreError::WriterClosed)?}+ /// Conform every latest page row to OKF in place (docs/okf.md);+ /// returns the rewritten pages so the wiki layer can align files.+ ///+ /// # Errors+ /// Returns [`StoreError::WriterClosed`] if the actor has shut down, or+ /// propagates the SQL error.+ pub async fn okf_migrate_latest_pages(&self) -> StoreResult<Vec<ops::OkfMigratedPage>> {+ let (tx, rx) = oneshot::channel();+ self.send(WriteCmd::OkfMigrateLatestPages { reply: tx })+ .await?;+ rx.await.map_err(|_| StoreError::WriterClosed)?+ }++ /// Count latest page rows still lacking OKF conformance (read-only).+ ///+ /// # Errors+ /// Returns [`StoreError::WriterClosed`] if the actor has shut down, or+ /// propagates the SQL error.+ pub async fn okf_nonconformant_count(&self) -> StoreResult<u64> {+ let (tx, rx) = oneshot::channel();+ self.send(WriteCmd::OkfNonconformantCount { reply: tx })+ .await?;+ rx.await.map_err(|_| StoreError::WriterClosed)?+ }+/// Record a wiki-structure migration as successfully applied.////// Called by the wiki migration runner immediately after [`WikiMigration::up`]@@ -2863,6 +2896,14 @@ fn worker_loop(mut conn: Connection, mut rx: mpsc::Receiver<WriteCmd>) {);send_or_warn(reply, result, "rename_project");}+ WriteCmd::OkfMigrateLatestPages { reply } => {+ let result = ops::okf_migrate_latest_pages(&mut conn);+ send_or_warn(reply, result, "okf_migrate_latest_pages");+ }+ WriteCmd::OkfNonconformantCount { reply } => {+ let result = ops::okf_nonconformant_latest_pages(&conn);+ send_or_warn(reply, result, "okf_nonconformant_count");+ }WriteCmd::InsertWikiMigration {name,applied_at,diff --git a/crates/ai-memory-wiki/Cargo.toml b/crates/ai-memory-wiki/Cargo.tomlindex b3aa61f7..8d8df69c 100644--- a/crates/ai-memory-wiki/Cargo.toml+++ b/crates/ai-memory-wiki/Cargo.toml@@ -19,6 +19,9 @@ serde_json.workspace = trueserde_yaml.workspace = truetempfile.workspace = truejiff.workspace = true+tar.workspace = true+flate2.workspace = true+dirs.workspace = truetracing.workspace = truetokio.workspace = truenotify.workspace = true@@ -36,6 +39,8 @@ winapi-util = { workspace = true }# Mock HTTP server for admission chain integration tests.axum.workspace = truetower.workspace = true+# Direct DB access to fabricate legacy (pre-OKF) stores in migration tests.+rusqlite.workspace = true[lints]workspace = truediff --git a/crates/ai-memory-wiki/src/backup.rs b/crates/ai-memory-wiki/src/backup.rsnew file mode 100644index 00000000..be1e5d12--- /dev/null+++ b/crates/ai-memory-wiki/src/backup.rs@@ -0,0 +1,194 @@+//! Pre-migration backup of the entire data directory (docs/okf.md).+//!+//! The OKF migration's first step — and its gate: no verified archive,+//! no migration. The archive lands OUTSIDE the data dir, in the user's+//! home (`AI_MEMORY_BACKUP_DIR` overrides the destination for machines+//! where home is small), and a receipt is recorded at+//! `<data_dir>/pre-migration-backup.json` so the wiki homepage can show+//! where it is until the user deletes it.++use std::fs::File;+use std::io::{BufReader, BufWriter};+use std::path::{Path, PathBuf};++use serde::{Deserialize, Serialize};++use crate::error::{WikiError, WikiResult};++/// File name of the receipt inside the data dir.+pub const BACKUP_RECEIPT_FILE: &str = "pre-migration-backup.json";++/// What the backup step produced; persisted as the receipt.+#[derive(Debug, Clone, Serialize, Deserialize)]+pub struct BackupReceipt {+ /// Absolute path of the archive.+ pub archive_path: PathBuf,+ /// Archive size in bytes.+ pub size_bytes: u64,+ /// Entries in the archive (files archived).+ pub entries: usize,+ /// ISO-8601 creation instant.+ pub created_at: String,+ /// What the backup was taken for (e.g. "okf-v0.2-migration").+ pub label: String,+}++impl BackupReceipt {+ /// Read the receipt from `data_dir`, if one exists and parses.+ #[must_use]+ pub fn load(data_dir: &Path) -> Option<Self> {+ let raw = std::fs::read(data_dir.join(BACKUP_RECEIPT_FILE)).ok()?;+ serde_json::from_slice(&raw).ok()+ }++ /// Whether the archive the receipt points at still exists on disk.+ #[must_use]+ pub fn archive_present(&self) -> bool {+ self.archive_path.exists()+ }+}++/// Destination directory for archives: the explicit override when given+/// (callers read `AI_MEMORY_BACKUP_DIR`), else the user's home. Erroring+/// (rather than falling back into the data dir) is deliberate: a backup+/// inside the tree it protects is not a backup.+fn destination_dir(dest_override: Option<&Path>) -> WikiResult<PathBuf> {+ if let Some(dir) = dest_override {+ return Ok(dir.to_path_buf());+ }+ dirs::home_dir().ok_or_else(|| {+ WikiError::Io(std::io::Error::other(+ "no home directory found for the pre-migration backup; \+ set AI_MEMORY_BACKUP_DIR to a directory outside the data dir",+ ))+ })+}++/// Compress `data_dir` into a timestamped tar.gz in the destination dir,+/// verify the archive is readable and complete, write the receipt, and+/// return it. Any failure aborts (the caller must not migrate).+pub fn create_pre_migration_backup(+ data_dir: &Path,+ label: &str,+ dest_override: Option<&Path>,+) -> WikiResult<BackupReceipt> {+ let dest_dir = destination_dir(dest_override)?;+ std::fs::create_dir_all(&dest_dir)?;+ let stamp = jiff::Timestamp::now().strftime("%Y%m%d-%H%M%S").to_string();+ let archive_path = dest_dir.join(format!("ai-memory-backup-{label}-{stamp}.tar.gz"));++ // The migration runs at server startup before any traffic, so the+ // SQLite files (db + WAL/SHM) are quiescent and archived as a set.+ let mut expected = 0usize;+ {+ let file = BufWriter::new(File::create(&archive_path)?);+ let enc = flate2::write::GzEncoder::new(file, flate2::Compression::default());+ let mut tar = tar::Builder::new(enc);+ tar.follow_symlinks(false);+ let mut stack = vec![data_dir.to_path_buf()];+ while let Some(dir) = stack.pop() {+ for entry in std::fs::read_dir(&dir)? {+ let entry = entry?;+ let path = entry.path();+ let rel = path+ .strip_prefix(data_dir)+ .map_err(|e| WikiError::Io(std::io::Error::other(e)))?;+ let ft = entry.file_type()?;+ if ft.is_dir() {+ stack.push(path);+ } else if ft.is_file() {+ tar.append_path_with_name(&path, rel)?;+ expected += 1;+ }+ // Symlinks are skipped: nothing in a data dir should be+ // one, and following one out of the tree must not happen.+ }+ }+ tar.into_inner()?.finish()?;+ }++ // Verify: re-open and count entries; a torn or unreadable archive+ // fails here and the caller aborts the migration.+ let mut counted = 0usize;+ {+ let file = BufReader::new(File::open(&archive_path)?);+ let dec = flate2::read::GzDecoder::new(file);+ let mut ar = tar::Archive::new(dec);+ for entry in ar.entries()? {+ entry?;+ counted += 1;+ }+ }+ let size_bytes = std::fs::metadata(&archive_path)?.len();+ if counted != expected || size_bytes == 0 {+ let _ = std::fs::remove_file(&archive_path);+ return Err(WikiError::Io(std::io::Error::other(format!(+ "backup verification failed: archived {expected} files but the \+ archive lists {counted} (size {size_bytes}); refusing to migrate"+ ))));+ }++ let receipt = BackupReceipt {+ archive_path,+ size_bytes,+ entries: counted,+ created_at: jiff::Timestamp::now()+ .strftime("%Y-%m-%dT%H:%M:%SZ")+ .to_string(),+ label: label.to_string(),+ };+ let tmp = data_dir.join(format!("{BACKUP_RECEIPT_FILE}.tmp"));+ std::fs::write(&tmp, serde_json::to_vec_pretty(&receipt)?)?;+ std::fs::rename(&tmp, data_dir.join(BACKUP_RECEIPT_FILE))?;+ Ok(receipt)+}++#[cfg(test)]+mod tests {+ use super::*;+ use tempfile::TempDir;++ fn data_dir_with_content() -> TempDir {+ let tmp = TempDir::new().unwrap();+ std::fs::create_dir_all(tmp.path().join("wiki/ws/proj/notes")).unwrap();+ std::fs::write(tmp.path().join("wiki/ws/proj/notes/a.md"), "---\n---\nbody").unwrap();+ std::fs::write(tmp.path().join("db.sqlite"), b"not really a db").unwrap();+ tmp+ }++ #[test]+ fn a_backup_archives_everything_and_writes_a_receipt() {+ let data = data_dir_with_content();+ let dest = TempDir::new().unwrap();+ let receipt = create_pre_migration_backup(data.path(), "test", Some(dest.path())).unwrap();+ assert!(receipt.archive_path.starts_with(dest.path()));+ assert_eq!(receipt.entries, 2);+ assert!(receipt.size_bytes > 0);+ assert!(receipt.archive_present());+ let loaded = BackupReceipt::load(data.path()).unwrap();+ assert_eq!(loaded.archive_path, receipt.archive_path);+ }++ #[test]+ fn an_unwritable_destination_aborts_instead_of_falling_back() {+ let data = data_dir_with_content();+ let dest = TempDir::new().unwrap();+ let blocked = dest.path().join("blocked-file");+ std::fs::write(&blocked, b"a file, not a dir").unwrap();+ let err = create_pre_migration_backup(data.path(), "test", Some(&blocked));+ assert!(err.is_err(), "backup must fail when it cannot write");+ assert!(+ BackupReceipt::load(data.path()).is_none(),+ "no receipt without an archive"+ );+ }++ #[test]+ fn a_deleted_archive_is_reported_absent() {+ let data = data_dir_with_content();+ let dest = TempDir::new().unwrap();+ let receipt = create_pre_migration_backup(data.path(), "test", Some(dest.path())).unwrap();+ std::fs::remove_file(&receipt.archive_path).unwrap();+ assert!(!receipt.archive_present());+ }+}diff --git a/crates/ai-memory-wiki/src/error.rs b/crates/ai-memory-wiki/src/error.rsindex c440f8a2..59ac702e 100644--- a/crates/ai-memory-wiki/src/error.rs+++ b/crates/ai-memory-wiki/src/error.rs@@ -43,6 +43,18 @@ pub enum WikiError {#[error("destination dir already exists: {0}")]DestinationExists(String),+ /// The `wiki_migrations` table records a migration this binary does+ /// not know: the wiki was migrated by a newer ai-memory. Refusing to+ /// open it read-write prevents silent format mixing.+ #[error(+ "this wiki was migrated by a newer ai-memory (unknown wiki migration `{migration}`). \+ Upgrade the binary, or restore the pre-migration backup archive to go back."+ )]+ NewerWikiFormat {+ /// The unknown migration name found in `wiki_migrations`.+ migration: String,+ },+/// A move-session refused to overwrite an existing page file at the/// destination (`<wiki_root>/<ws>/<proj>/sessions/<id>.md`). Surfaced as/// `409 Conflict` at the admin layer.diff --git a/crates/ai-memory-wiki/src/lib.rs b/crates/ai-memory-wiki/src/lib.rsindex 4fee256b..85dae69d 100644--- a/crates/ai-memory-wiki/src/lib.rs+++ b/crates/ai-memory-wiki/src/lib.rs@@ -7,6 +7,7 @@pub mod admission;mod atomic;+pub mod backup;mod error;mod git;mod markdown;diff --git a/crates/ai-memory-wiki/src/migrations/m2026_09_okf_conformance.rs b/crates/ai-memory-wiki/src/migrations/m2026_09_okf_conformance.rsnew file mode 100644index 00000000..74dd16dc--- /dev/null+++ b/crates/ai-memory-wiki/src/migrations/m2026_09_okf_conformance.rs@@ -0,0 +1,508 @@+//! One-shot migration of an existing store to native OKF v0.2+//! (docs/okf.md). Order is fixed and each step gates the next:+//!+//! 1. **verified backup of the whole data dir, or no migration at all**;+//! 2. git checkpoint of the wiki tree;+//! 3. DB pass: conform every latest page row IN PLACE (same id, same+//! version row, `updated_at` untouched);+//! 4. file pass: conform every wiki `.md` in place (body untouched),+//! `generated.at` from the row's `updated_at` when the page is+//! indexed, else the file's mtime; scope `_meta.md` manifests get+//! their `type` only; each project bundle root gains an `index.md`+//! declaring `okf_version` when absent;+//! 5. single "okf-migration" git commit.+//!+//! Idempotent: on a conformant store both passes find nothing and the+//! backup gate never engages (fresh installs never create archives).++use std::path::{Path, PathBuf};++use ai_memory_store::WriterHandle;++use super::WikiMigration;+use crate::error::{WikiError, WikiResult};+use crate::markdown::{Markdown, emit, parse};++pub struct OkfConformance {+ /// Where the backup archive lands; `None` = the user's home. The+ /// registry fills it from `AI_MEMORY_BACKUP_DIR`; tests inject a+ /// tempdir directly.+ pub dest_override: Option<PathBuf>,+}++impl OkfConformance {+ /// Construct with the destination taken from `AI_MEMORY_BACKUP_DIR`.+ #[must_use]+ pub fn from_env() -> Self {+ Self {+ dest_override: std::env::var("AI_MEMORY_BACKUP_DIR")+ .ok()+ .filter(|v| !v.trim().is_empty())+ .map(PathBuf::from),+ }+ }+}++const BACKUP_LABEL: &str = "okf-v0.2";++#[async_trait::async_trait]+impl WikiMigration for OkfConformance {+ fn name(&self) -> &'static str {+ "2026_09_01T18_00_okf_v02_conformance"+ }++ fn description(&self) -> &'static str {+ "conform wiki pages and index rows to OKF v0.2 (backup-gated, in place)"+ }++ async fn up(&self, writer: &WriterHandle, wiki_root: &Path) -> WikiResult<()> {+ let data_dir = wiki_root.parent().ok_or_else(|| {+ WikiError::Io(std::io::Error::other("wiki root has no parent data dir"))+ })?;++ let db_pending = writer.okf_nonconformant_count().await?;+ let file_pending = nonconformant_files(wiki_root)?;+ if db_pending == 0 && file_pending.is_empty() {+ // Fresh install or already conformant: nothing to protect,+ // nothing to rewrite, no archive.+ return Ok(());+ }+ tracing::info!(+ db_rows = db_pending,+ files = file_pending.len(),+ "OKF migration: taking the pre-migration backup first"+ );++ // 1. Backup gate.+ let receipt = crate::backup::create_pre_migration_backup(+ data_dir,+ BACKUP_LABEL,+ self.dest_override.as_deref(),+ )?;+ tracing::info!(+ archive = %receipt.archive_path.display(),+ size_bytes = receipt.size_bytes,+ entries = receipt.entries,+ "pre-migration backup verified"+ );++ // 2. Checkpoint whatever the tree holds before touching it.+ let git = crate::git::GitAdapter::open_or_init(wiki_root)?;+ git.commit_all("pre-okf-migration checkpoint")?;++ // 3. DB pass — in place, through the single writer.+ let migrated = writer.okf_migrate_latest_pages().await?;+ let at_by_page: std::collections::HashMap<(String, String, String), String> = migrated+ .iter()+ .map(|m| {+ (+ (+ m.workspace_id.to_string(),+ m.project_id.to_string(),+ m.path.clone(),+ ),+ m.generated_at.clone(),+ )+ })+ .collect();++ // 4. File pass.+ for file in file_pending {+ conform_file(wiki_root, &file, &at_by_page)?;+ }+ ensure_bundle_indexes(wiki_root)?;++ // 5. One commit for the whole rewrite.+ git.commit_all("okf-migration: conform wiki to OKF v0.2")?;+ tracing::info!(+ rows = migrated.len(),+ "OKF migration complete; homepage will show the backup notice \+ until the archive is deleted"+ );+ Ok(())+ }+}++/// Wiki-relative paths of `.md` files that still need the file pass.+fn nonconformant_files(wiki_root: &Path) -> WikiResult<Vec<PathBuf>> {+ let mut pending = Vec::new();+ let mut stack = vec![wiki_root.to_path_buf()];+ while let Some(dir) = stack.pop() {+ let entries = match std::fs::read_dir(&dir) {+ Ok(e) => e,+ Err(e) if e.kind() == std::io::ErrorKind::NotFound => continue,+ Err(e) => return Err(e.into()),+ };+ for entry in entries {+ let entry = entry?;+ let path = entry.path();+ let ft = entry.file_type()?;+ if ft.is_dir() {+ if path.file_name().is_some_and(|n| n == ".git") {+ continue;+ }+ stack.push(path);+ } else if ft.is_file()+ && path.extension().is_some_and(|e| e == "md")+ && path.file_name().is_none_or(|n| n != "index.md")+ {+ let Ok(raw) = std::fs::read_to_string(&path) else {+ continue;+ };+ let fm = parse(&raw).map(|m| m.frontmatter).unwrap_or_default();+ let conformant = if is_meta_manifest(&path) {+ ai_memory_core::okf::is_conformant(&fm)+ } else {+ ai_memory_core::okf::is_conformant(&fm)+ && ai_memory_core::okf::generated_at(&fm).is_some()+ };+ if !conformant {+ pending.push(path.strip_prefix(wiki_root).unwrap_or(&path).to_path_buf());+ }+ }+ }+ }+ pending.sort();+ Ok(pending)+}++fn is_meta_manifest(path: &Path) -> bool {+ path.file_name().is_some_and(|n| n == "_meta.md")+}++/// Conform one file in place: same body, frontmatter filled. Manifests+/// (`_meta.md`) get their `type` only — they are identity records, not+/// concept pages with provenance.+fn conform_file(+ wiki_root: &Path,+ rel: &Path,+ at_by_page: &std::collections::HashMap<(String, String, String), String>,+) -> WikiResult<()> {+ let abs = wiki_root.join(rel);+ let raw = std::fs::read_to_string(&abs)?;+ let mut md = parse(&raw).unwrap_or_else(|_| Markdown {+ frontmatter: serde_json::Value::Object(serde_json::Map::new()),+ body: raw.clone(),+ });++ if is_meta_manifest(&abs) {+ if let Some(map) = md.frontmatter.as_object_mut() {+ map.entry("type".to_string())+ .or_insert(serde_json::Value::String("Scope Manifest".into()));+ }+ } else {+ // Page-relative path (strip `<ws>/<proj>/`) drives type derivation+ // and the row lookup.+ let components: Vec<String> = rel+ .components()+ .map(|c| c.as_os_str().to_string_lossy().into_owned())+ .collect();+ let (page_rel, row_key) = if components.len() >= 3 {+ (+ components[2..].join("/"),+ Some((+ components[0].clone(),+ components[1].clone(),+ components[2..].join("/"),+ )),+ )+ } else {+ (components.join("/"), None)+ };+ ai_memory_core::okf::conform_frontmatter(&page_rel, &mut md.frontmatter);+ if ai_memory_core::okf::generated_at(&md.frontmatter).is_none() {+ let at = row_key+ .and_then(|k| at_by_page.get(&k).cloned())+ .unwrap_or_else(|| mtime_iso(&abs));+ ai_memory_core::okf::stamp_generated_at(&mut md.frontmatter, &at);+ }+ }++ let emitted = emit(&md)?;+ if emitted != raw {+ let tmp = tempfile::NamedTempFile::new_in(abs.parent().unwrap_or(wiki_root))?;+ std::fs::write(tmp.path(), emitted.as_bytes())?;+ crate::atomic::persist_with_retry(tmp, &abs)?;+ }+ Ok(())+}++fn mtime_iso(path: &Path) -> String {+ std::fs::metadata(path)+ .and_then(|m| m.modified())+ .ok()+ .and_then(|t| t.duration_since(std::time::UNIX_EPOCH).ok())+ .and_then(|d| jiff::Timestamp::from_second(d.as_secs() as i64).ok())+ .unwrap_or(jiff::Timestamp::UNIX_EPOCH)+ .strftime("%Y-%m-%dT%H:%M:%SZ")+ .to_string()+}++/// Each project directory is one OKF bundle: give it an `index.md`+/// declaring `okf_version` when absent (the only place index.md may+/// carry frontmatter, per spec).+fn ensure_bundle_indexes(wiki_root: &Path) -> WikiResult<()> {+ let Ok(workspaces) = std::fs::read_dir(wiki_root) else {+ return Ok(());+ };+ for ws in workspaces.flatten() {+ if !ws.file_type().map(|t| t.is_dir()).unwrap_or(false) || ws.file_name() == ".git" {+ continue;+ }+ let Ok(projects) = std::fs::read_dir(ws.path()) else {+ continue;+ };+ for proj in projects.flatten() {+ if !proj.file_type().map(|t| t.is_dir()).unwrap_or(false) {+ continue;+ }+ let index = proj.path().join("index.md");+ if index.exists() {+ continue;+ }+ let mut families: Vec<String> = std::fs::read_dir(proj.path())+ .map(|it| {+ it.flatten()+ .filter(|e| e.file_type().map(|t| t.is_dir()).unwrap_or(false))+ .map(|e| e.file_name().to_string_lossy().into_owned())+ .collect()+ })+ .unwrap_or_default();+ families.sort();+ let listing = families+ .iter()+ .map(|f| format!("- [{f}/]({f}/)\n"))+ .collect::<String>();+ let body =+ format!("# Bundle index\n\nConcept files live in these directories:\n\n{listing}");+ let content = format!("---\nokf_version: \"0.2\"\n---\n\n{body}");+ std::fs::write(&index, content)?;+ }+ }+ Ok(())+}++#[cfg(test)]+mod tests {+ use ai_memory_core::{PagePath, Tier};+ use ai_memory_store::Store;+ use tempfile::TempDir;++ use super::*;+ use crate::wiki::{Wiki, WritePageRequest};++ /// Build a data dir that looks like a 1.x store: pages written+ /// through the current stack, then stripped of every OKF key in+ /// both the row and the file — exactly what a pre-2.0 install holds.+ async fn legacy_store() -> (+ TempDir,+ Store,+ ai_memory_core::WorkspaceId,+ ai_memory_core::ProjectId,+ ) {+ let tmp = TempDir::new().unwrap();+ let store = Store::open(tmp.path()).unwrap();+ let ws = store.writer.get_or_create_workspace("w").await.unwrap();+ let proj = store+ .writer+ .get_or_create_project(ws, "p", None)+ .await+ .unwrap();+ let wiki = Wiki::new(tmp.path(), store.writer.clone()).unwrap();+ for (path, body) in [+ ("gotchas/linker.md", "mind the linker"),+ ("notes/setup.md", "how it was set up"),+ ] {+ wiki.write_page(WritePageRequest {+ workspace_id: ws,+ project_id: proj,+ path: PagePath::new(path).unwrap(),+ frontmatter: serde_json::json!({"title": path}),+ body: body.into(),+ tier: Tier::Semantic,+ pinned: false,+ title: None,+ admission_ctx: None,+ author_id: None,+ actor: ai_memory_core::ActorContext::anonymous(),+ })+ .await+ .unwrap();+ }++ // Strip OKF keys from rows (second connection; the writer is idle).+ let db = rusqlite::Connection::open(tmp.path().join("db").join("memory.sqlite")).unwrap();+ let rows: Vec<(Vec<u8>, String)> = db+ .prepare("SELECT id, frontmatter_json FROM pages")+ .unwrap()+ .query_map([], |r| Ok((r.get(0)?, r.get(1)?)))+ .unwrap()+ .collect::<Result<_, _>>()+ .unwrap();+ for (id, fm_str) in rows {+ let mut fm: serde_json::Value = serde_json::from_str(&fm_str).unwrap();+ if let Some(map) = fm.as_object_mut() {+ for key in ["type", "generated", "sources", "stale_after", "description"] {+ map.remove(key);+ }+ }+ db.execute(+ "UPDATE pages SET frontmatter_json = ?1 WHERE id = ?2",+ rusqlite::params![serde_json::to_string(&fm).unwrap(), id],+ )+ .unwrap();+ }+ drop(db);++ // Strip the same keys from the files.+ let proj_dir = tmp+ .path()+ .join("wiki")+ .join(ws.to_string())+ .join(proj.to_string());+ for rel in ["gotchas/linker.md", "notes/setup.md"] {+ let abs = proj_dir.join(rel);+ let mut md = parse(&std::fs::read_to_string(&abs).unwrap()).unwrap();+ if let Some(map) = md.frontmatter.as_object_mut() {+ for key in ["type", "generated", "sources", "stale_after", "description"] {+ map.remove(key);+ }+ }+ std::fs::write(&abs, emit(&md).unwrap()).unwrap();+ }+ (tmp, store, ws, proj)+ }++ fn page_rows(data_dir: &Path) -> Vec<(Vec<u8>, String, i64, String)> {+ let db = rusqlite::Connection::open(data_dir.join("db").join("memory.sqlite")).unwrap();+ db.prepare(+ "SELECT id, path, updated_at, frontmatter_json FROM pages \+ WHERE is_latest = 1 ORDER BY path",+ )+ .unwrap()+ .query_map([], |r| Ok((r.get(0)?, r.get(1)?, r.get(2)?, r.get(3)?)))+ .unwrap()+ .collect::<Result<_, _>>()+ .unwrap()+ }++ #[tokio::test]+ async fn a_legacy_store_is_migrated_in_place_with_a_verified_backup() {+ let (tmp, store, ws, proj) = legacy_store().await;+ let before = page_rows(tmp.path());+ let dest = TempDir::new().unwrap();+ let migration = OkfConformance {+ dest_override: Some(dest.path().to_path_buf()),+ };+ migration+ .up(&store.writer, &tmp.path().join("wiki"))+ .await+ .unwrap();++ // No-churn: same ids, same updated_at, one row per page.+ let after = page_rows(tmp.path());+ assert_eq!(before.len(), after.len());+ for (b, a) in before.iter().zip(after.iter()) {+ assert_eq!(b.0, a.0, "page id changed");+ assert_eq!(b.2, a.2, "updated_at changed");+ let fm: serde_json::Value = serde_json::from_str(&a.3).unwrap();+ assert!(ai_memory_core::okf::is_conformant(&fm), "{}", a.1);+ assert!(ai_memory_core::okf::generated_at(&fm).is_some());+ }++ // Files conformant, bundle index declared.+ let proj_dir = tmp+ .path()+ .join("wiki")+ .join(ws.to_string())+ .join(proj.to_string());+ let fm = parse(&std::fs::read_to_string(proj_dir.join("gotchas/linker.md")).unwrap())+ .unwrap()+ .frontmatter;+ assert_eq!(fm["type"], "Gotcha");+ assert!(ai_memory_core::okf::generated_at(&fm).is_some());+ let index = std::fs::read_to_string(proj_dir.join("index.md")).unwrap();+ assert!(index.contains("okf_version: \"0.2\""));++ // Backup exists, receipt recorded, archive present.+ let receipt = crate::backup::BackupReceipt::load(tmp.path()).unwrap();+ assert!(receipt.archive_present());+ assert!(receipt.entries > 0);+ }++ #[tokio::test]+ async fn a_second_run_migrates_nothing_and_takes_no_second_backup() {+ let (tmp, store, _ws, _proj) = legacy_store().await;+ let dest = TempDir::new().unwrap();+ let migration = OkfConformance {+ dest_override: Some(dest.path().to_path_buf()),+ };+ migration+ .up(&store.writer, &tmp.path().join("wiki"))+ .await+ .unwrap();+ let archives_after_first = std::fs::read_dir(dest.path()).unwrap().count();+ let rows_after_first = page_rows(tmp.path());++ migration+ .up(&store.writer, &tmp.path().join("wiki"))+ .await+ .unwrap();+ assert_eq!(+ std::fs::read_dir(dest.path()).unwrap().count(),+ archives_after_first,+ "idempotent re-run took another backup"+ );+ assert_eq!(rows_after_first, page_rows(tmp.path()));+ }++ #[tokio::test]+ async fn a_fresh_store_skips_the_backup_entirely() {+ let tmp = TempDir::new().unwrap();+ let store = Store::open(tmp.path()).unwrap();+ std::fs::create_dir_all(tmp.path().join("wiki")).unwrap();+ let dest = TempDir::new().unwrap();+ let migration = OkfConformance {+ dest_override: Some(dest.path().to_path_buf()),+ };+ migration+ .up(&store.writer, &tmp.path().join("wiki"))+ .await+ .unwrap();+ assert_eq!(+ std::fs::read_dir(dest.path()).unwrap().count(),+ 0,+ "fresh install created a backup archive"+ );+ assert!(crate::backup::BackupReceipt::load(tmp.path()).is_none());+ }++ /// The gate itself: when the backup cannot be written, the migration+ /// must fail and leave every row and file untouched.+ #[tokio::test]+ async fn a_failing_backup_aborts_before_anything_is_touched() {+ let (tmp, store, ws, proj) = legacy_store().await;+ let before = page_rows(tmp.path());+ let dest = TempDir::new().unwrap();+ let blocked = dest.path().join("blocked-file");+ std::fs::write(&blocked, b"a file, not a dir").unwrap();+ let migration = OkfConformance {+ dest_override: Some(blocked),+ };+ let result = migration.up(&store.writer, &tmp.path().join("wiki")).await;+ assert!(result.is_err(), "migration must refuse without a backup");+ assert_eq!(before, page_rows(tmp.path()), "rows were touched");+ let proj_dir = tmp+ .path()+ .join("wiki")+ .join(ws.to_string())+ .join(proj.to_string());+ let fm = parse(&std::fs::read_to_string(proj_dir.join("gotchas/linker.md")).unwrap())+ .unwrap()+ .frontmatter;+ assert!(+ !ai_memory_core::okf::is_conformant(&fm),+ "files were touched despite the failed backup"+ );+ }+}diff --git a/crates/ai-memory-wiki/src/migrations/mod.rs b/crates/ai-memory-wiki/src/migrations/mod.rsindex 6069602b..d713203a 100644--- a/crates/ai-memory-wiki/src/migrations/mod.rs+++ b/crates/ai-memory-wiki/src/migrations/mod.rs@@ -39,6 +39,7 @@//! - **No SQL outside the writer actor.** Use [`WriterHandle`] methods so all//! writes go through the single-writer channel (invariant #2).+mod m2026_09_okf_conformance;mod runner;use std::path::Path;@@ -95,8 +96,7 @@ pub trait WikiMigration: Send + Sync {/// of pre-existing data.#[must_use]pub fn registry() -> Vec<Box<dyn WikiMigration>> {- // Keep this empty until a structural change actually needs migrating- // existing installs. Appending to an empty vec is a zero-diff PR for- // future contributors.- vec![]+ vec![Box::new(+ m2026_09_okf_conformance::OkfConformance::from_env(),+ )]}diff --git a/crates/ai-memory-wiki/src/migrations/runner.rs b/crates/ai-memory-wiki/src/migrations/runner.rsindex ee9f9bf8..3486361a 100644--- a/crates/ai-memory-wiki/src/migrations/runner.rs+++ b/crates/ai-memory-wiki/src/migrations/runner.rs@@ -55,6 +55,17 @@ pub async fn run_pending(let applied = applied_names(reader).await?;+ // Generation guard (docs/okf.md): a name in `wiki_migrations` that+ // this binary's registry does not know means the wiki was migrated+ // by a NEWER ai-memory. Opening it read-write with an older binary+ // would mix formats silently; refuse with the recovery options.+ let known: Vec<&str> = registry.iter().map(|m| m.name()).collect();+ if let Some(unknown) = applied.iter().find(|n| !known.contains(&n.as_str())) {+ return Err(WikiError::NewerWikiFormat {+ migration: unknown.clone(),+ });+ }+for migration in registry {let name = migration.name();if applied.iter().any(|n| n == name) {