Skip to content

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.lock
index 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.rs
index 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.rs
index 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, so
diff --git a/crates/ai-memory-store/src/writer.rs b/crates/ai-memory-store/src/writer.rs
index 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.toml
index b3aa61f7..8d8df69c 100644
--- a/crates/ai-memory-wiki/Cargo.toml
+++ b/crates/ai-memory-wiki/Cargo.toml
@@ -19,6 +19,9 @@ serde_json.workspace = true
serde_yaml.workspace = true
tempfile.workspace = true
jiff.workspace = true
+tar.workspace = true
+flate2.workspace = true
+dirs.workspace = true
tracing.workspace = true
tokio.workspace = true
notify.workspace = true
@@ -36,6 +39,8 @@ winapi-util = { workspace = true }
# Mock HTTP server for admission chain integration tests.
axum.workspace = true
tower.workspace = true
+# Direct DB access to fabricate legacy (pre-OKF) stores in migration tests.
+rusqlite.workspace = true
[lints]
workspace = true
diff --git a/crates/ai-memory-wiki/src/backup.rs b/crates/ai-memory-wiki/src/backup.rs
new file mode 100644
index 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.rs
index 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.rs
index 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.rs
new file mode 100644
index 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.rs
index 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.rs
index 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) {