Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors
Rust
fix(wiki): auto-commits stage what the wiki wrote, with the repository kept open
gbdd7ad3fb96df
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex aa6dd1dd..d5be5dcc 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -7,6 +7,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0## [Unreleased]+### Fixed+- Wiki auto-commits stage what the wiki wrote instead of walking the+ whole tree, keep the repository open between commits, and no longer+ drop the commit when another session is writing a file at the same+ time. A session end now costs what it wrote, not the size of the wiki,+ and the git history no longer silently misses snapshots under+ concurrent sessions (#674).+## [2.1.1] - 2026-09-07### Changeddiff --git a/crates/ai-memory-hooks/src/log.rs b/crates/ai-memory-hooks/src/log.rsindex 80303ddc..7090238a 100644--- a/crates/ai-memory-hooks/src/log.rs+++ b/crates/ai-memory-hooks/src/log.rs@@ -20,8 +20,6 @@//! `forget-sweep --logs --older-than 12m` could delete cold files if//! it becomes worthwhile.-use std::io::Write;-use ai_memory_core::{ProjectId, WorkspaceId};use ai_memory_wiki::Wiki;use jiff::{Timestamp, tz::TimeZone};@@ -52,23 +50,10 @@ pub fn append_event(event: HookEvent,title: &str,) -> std::io::Result<()> {- let log_path = wiki- .project_root(workspace_id, project_id)- .join(log_filename_for(when));+ let file_name = log_filename_for(when);let line = format_line(when, event, title);- debug!(path = %log_path.display(), bytes = line.len(), "appending log entry");-- if let Some(parent) = log_path.parent()- && !parent.as_os_str().is_empty()- {- std::fs::create_dir_all(parent)?;- }- let mut file = std::fs::OpenOptions::new()- .create(true)- .append(true)- .open(&log_path)?;- file.write_all(line.as_bytes())?;- file.sync_data()?;+ let path = wiki.append_under_project(workspace_id, project_id, &file_name, line.as_bytes())?;+ debug!(path = %path.display(), bytes = line.len(), "appended log entry");Ok(())}diff --git a/crates/ai-memory-wiki/clippy.toml b/crates/ai-memory-wiki/clippy.tomlnew file mode 100644index 00000000..690ada9a--- /dev/null+++ b/crates/ai-memory-wiki/clippy.toml@@ -0,0 +1,14 @@+# A write into the wiki tree must report its path (GitAdapter::mark_written)+# or the next auto-commit does not stage it. Write through the adapter's+# methods; a site that reports another way carries an `allow` with the reason.+disallowed-methods = [+ { path = "std::fs::write", reason = "report the write: GitAdapter::write_atomic" },+ { path = "std::fs::rename", reason = "report the move: GitAdapter::rename" },+ { path = "std::fs::remove_file", reason = "report the removal: GitAdapter::remove_file" },+ { path = "std::fs::remove_dir_all", reason = "report the removal: GitAdapter::remove_dir_all" },+ { path = "std::fs::copy", reason = "report the write: GitAdapter::write_atomic" },+ { path = "ai_memory_wiki::atomic::write_atomic", reason = "report the write: GitAdapter::write_atomic" },+ { path = "ai_memory_wiki::atomic::persist_with_retry", reason = "report the write: GitAdapter::persist" },+ { path = "tempfile::NamedTempFile::persist", reason = "report the write: GitAdapter::persist" },+ { path = "tempfile::NamedTempFile::persist_noclobber", reason = "report the write: GitAdapter::persist" },+]diff --git a/crates/ai-memory-wiki/src/atomic.rs b/crates/ai-memory-wiki/src/atomic.rsindex fb9e2a90..07fe2428 100644--- a/crates/ai-memory-wiki/src/atomic.rs+++ b/crates/ai-memory-wiki/src/atomic.rs@@ -3,6 +3,8 @@//! Every file the wiki owns is written via a tmp + rename + fsync dance.//! Two payoffs: a crash mid-write never produces a torn file, and the//! upcoming watcher (M1-D) can ignore "own writes" by inode tracking.+// The write primitive itself; every reporting wrapper is built on it.+#![allow(clippy::disallowed_methods)]use std::fs::File;use std::io::Write;diff --git a/crates/ai-memory-wiki/src/backup.rs b/crates/ai-memory-wiki/src/backup.rsindex c4ed8438..3dc1c5c0 100644--- a/crates/ai-memory-wiki/src/backup.rs+++ b/crates/ai-memory-wiki/src/backup.rs@@ -6,6 +6,8 @@//! 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.+// Backups are written outside the wiki tree and are not part of its history.+#![allow(clippy::disallowed_methods)]use std::fs::File;use std::io::{BufReader, BufWriter};diff --git a/crates/ai-memory-wiki/src/git.rs b/crates/ai-memory-wiki/src/git.rsindex 7674ebcb..38c06a8e 100644--- a/crates/ai-memory-wiki/src/git.rs+++ b/crates/ai-memory-wiki/src/git.rs@@ -4,9 +4,18 @@//! a repo. Auto-commits fire from the hook router on `SessionEnd` and//! from the M7 consolidator. Author/email are fixed so the wiki history//! can't accidentally leak the maintainer's git identity.+//!+//! A commit stages the paths reported through `mark_written` since the+//! last one; the adapter's own write methods report for their caller and+//! the crate's `clippy.toml` refuses the raw calls. The full walk is the+//! safety net, decided in `take_staging`. The repository stays open+//! between commits: reopening it dropped libgit2's index tree cache, so+//! every commit rebuilt every directory tree.+use std::collections::BTreeSet;use std::path::{Path, PathBuf};-use std::sync::{Arc, Mutex};+use std::sync::{Arc, Mutex, MutexGuard};+use std::time::{Duration, Instant};use git2::{ErrorCode, IndexAddOption, ObjectType, Repository, Signature};use tracing::{debug, warn};@@ -25,9 +34,68 @@ pub const COMMIT_AUTHOR_EMAIL: &str = "ai-memory@local";pub struct GitAdapter {root: PathBuf,/// One commit at a time per repository: libgit2 fails a concurrent- /// commit with "the index is locked" instead of waiting. Clones share- /// the lock; a second adapter opened on the same root does not.- commit_lock: Arc<Mutex<()>>,+ /// commit with "the index is locked" instead of waiting. Also holds+ /// the repository kept open between commits. Clones share it; a+ /// second adapter opened on the same root does not.+ commit_lock: Arc<Mutex<Option<Open>>>,+ /// Paths written since the last commit; shared by clones like the lock.+ written: Arc<Mutex<Written>>,+}++/// The repository kept open between commits, so libgit2's cached index+/// (tree cache included) survives them. `Index` itself is not `Send`.+struct Open {+ repo: Repository,+ commits_since_index_write: u32,+ /// HEAD as this adapter last left it; moved by another writer, the+ /// kept index is re-read and the next commit walks.+ head: Option<git2::Oid>,+}++/// The index file is written after a walk and every this many+/// path-scoped commits.+const INDEX_WRITE_EVERY: u32 = 50;++#[derive(Debug, Default)]+struct Written {+ /// Relative to the root; a directory covers its subtree.+ paths: BTreeSet<PathBuf>,+ walk_needed: bool,+ /// `None` before the first commit, which walks.+ last_walk: Option<Instant>,+ /// Everything reported since the last walk, so the walk can name+ /// what nobody reported.+ since_walk: BTreeSet<PathBuf>,+ unreported_writes: u64,+ last_unreported: Vec<PathBuf>,+}++/// A path-scoped commit this long after the last walk walks instead.+const SWEEP_INTERVAL: Duration = Duration::from_secs(600);++const UNREPORTED_SAMPLE: usize = 5;++/// Retries for a commit whose staging read a file mid-write.+const RACY_READ_ATTEMPTS: u32 = 4;+const RACY_READ_BACKOFF: Duration = Duration::from_millis(25);++/// libgit2's "file changed before we could read it": a writer was mid-write.+fn is_racy_read(e: &git2::Error) -> bool {+ e.class() == git2::ErrorClass::Filesystem && e.message().contains("changed before")+}++/// Writes that reached the tree without a report: a writer bypassed the wiki.+#[derive(Debug, Clone, Default, PartialEq, Eq)]+pub struct SweepSnapshot {+ /// Over the adapter's life.+ pub unreported_writes: u64,+ /// Up to [`UNREPORTED_SAMPLE`] of them from the last walk.+ pub last_unreported: Vec<PathBuf>,+}++enum Staging {+ Everything,+ Paths(BTreeSet<PathBuf>),}/// One git checkpoint in the wiki repository.@@ -63,19 +131,76 @@ impl GitAdapter {}Ok(Self {root: root.to_path_buf(),- commit_lock: Arc::new(Mutex::new(())),+ commit_lock: Arc::new(Mutex::new(None)),+ written: Arc::new(Mutex::new(Written::default())),})}+ fn written(&self) -> MutexGuard<'_, Written> {+ self.written.lock().unwrap_or_else(|e| e.into_inner())+ }++ /// Report a path written, moved or removed (absolute or relative to+ /// the root); the next commit stages it. A path outside the root is+ /// a caller's bug: logged, and the next commit walks.+ pub fn mark_written(&self, path: &Path) {+ let rel = if path.is_absolute() {+ path.strip_prefix(&self.root).ok()+ } else {+ Some(path)+ };+ // The watcher reports git's own writes too; never stage them.+ if rel.is_some_and(|rel| rel.starts_with(".git")) {+ return;+ }+ let mut written = self.written();+ match rel {+ Some(rel) if !rel.as_os_str().is_empty() => {+ written.paths.insert(rel.to_path_buf());+ written.since_walk.insert(rel.to_path_buf());+ }+ _ => {+ warn!(path = %path.display(), "reported path is not under the wiki root");+ written.walk_needed = true;+ }+ }+ }++ /// Drop the kept repository, as a restart would.+ #[cfg(test)]+ pub(crate) fn close(&self) {+ *self.commit_lock.lock().unwrap_or_else(|e| e.into_inner()) = None;+ }++ /// Make the next path-scoped commit walk, as if the sweep were due.+ #[cfg(test)]+ pub(crate) fn age_last_walk(&self) {+ self.written().last_walk = Instant::now().checked_sub(SWEEP_INTERVAL);+ }++ /// What the sweeps found; see [`SweepSnapshot`].+ #[must_use]+ pub fn sweep_snapshot(&self) -> SweepSnapshot {+ let written = self.written();+ SweepSnapshot {+ unreported_writes: written.unreported_writes,+ last_unreported: written.last_unreported.clone(),+ }+ }+ #[cfg(test)]+ pub(crate) fn written_paths(&self) -> Vec<PathBuf> {+ self.written().paths.iter().cloned().collect()+ }+/// Path of the wiki root.#[must_use]pub fn root(&self) -> &Path {&self.root}- /// Stage *everything* in the wiki root, then commit with `message`.- /// Returns `Ok(None)` if there were no changes to commit (working- /// tree clean), or `Ok(Some(commit_oid))` on a successful commit.+ /// Stage the reported paths (or walk the tree; see `take_staging`)+ /// and commit with `message`. Returns `Ok(None)` when nothing+ /// changed, `Ok(Some(commit_oid))` on a commit.////// # Errors/// Propagates any underlying libgit2 error.@@ -90,9 +215,117 @@ impl GitAdapter {}fn commit_all_git2(&self, message: &str) -> Result<Option<git2::Oid>, CommitGit2Error> {- let _one_at_a_time = self.commit_lock.lock().unwrap_or_else(|e| e.into_inner());- let repo = Repository::open(&self.root).map_err(CommitGit2Error::Open)?;+ let mut slot = self.commit_lock.lock().unwrap_or_else(|e| e.into_inner());+ if slot.is_none() {+ let repo = Repository::open(&self.root).map_err(CommitGit2Error::Open)?;+ *slot = Some(Open {+ repo,+ commits_since_index_write: 0,+ head: None,+ });+ }+ let open = slot.as_mut().expect("opened above");+ let head_now = open.repo.head().ok().and_then(|h| h.target());+ if open.head.is_some() && open.head != head_now {+ warn!("HEAD moved under the kept index; re-reading it and walking");+ open.repo+ .index()+ .and_then(|mut index| index.read(true))+ .map_err(CommitGit2Error::Other)?;+ self.written().walk_needed = true;+ }+ let staging = self.take_staging();+ let mut attempt = 0u32;+ let result = loop {+ attempt += 1;+ match self.commit_staged(open, message, &staging) {+ // A writer outside the lock was mid-write; it settles in+ // milliseconds.+ Err(CommitGit2Error::Other(e))+ if is_racy_read(&e) && attempt < RACY_READ_ATTEMPTS =>+ {+ debug!(attempt, "a file changed under the commit; retrying");+ std::thread::sleep(RACY_READ_BACKOFF);+ }+ other => break other,+ }+ };+ if let Ok(oid) = &result {+ open.head = oid.or(head_now);+ }+ if let Err(e) = &result {+ *slot = None;+ let racy = matches!(e, CommitGit2Error::Other(e) if is_racy_read(e));+ self.keep_pending(staging, racy);+ }+ result+ }++ /// After a failed commit: the paths stay reported, and unless the+ /// failure was a racy read the next commit walks.+ fn keep_pending(&self, staging: Staging, racy: bool) {+ let mut written = self.written();+ if let Staging::Paths(paths) = staging {+ written.since_walk.extend(paths.iter().cloned());+ written.paths.extend(paths);+ }+ written.walk_needed |= !racy;+ }+ /// Walk when told to, when nothing was reported, or when the sweep is+ /// due; otherwise stage the reported paths. Called under the commit lock.+ fn take_staging(&self) -> Staging {+ let mut written = self.written();+ let sweep_due = written+ .last_walk+ .is_none_or(|at| at.elapsed() >= SWEEP_INTERVAL);+ if written.walk_needed || written.paths.is_empty() || sweep_due {+ written.walk_needed = false;+ written.paths.clear();+ Staging::Everything+ } else {+ Staging::Paths(std::mem::take(&mut written.paths))+ }+ }+ /// After a walk: name what nobody reported since the last one and+ /// start the next interval. The first walk has nothing to compare+ /// against.+ fn record_walk(&self, walked: &[PathBuf]) {+ let mut written = self.written();+ if written.last_walk.is_some() {+ // A report covers its subtree.+ let mut unreported: Vec<PathBuf> = walked+ .iter()+ .filter(|path| !path.ancestors().any(|a| written.since_walk.contains(a)))+ .cloned()+ .collect();+ if !unreported.is_empty() {+ warn!(+ count = unreported.len(),+ first = ?unreported.iter().take(UNREPORTED_SAMPLE).collect::<Vec<_>>(),+ "the sweep staged writes nobody reported: a writer bypassed the wiki"+ );+ }+ written.unreported_writes += unreported.len() as u64;+ unreported.truncate(UNREPORTED_SAMPLE);+ written.last_unreported = unreported;+ }+ written.since_walk.clear();+ written.last_walk = Some(Instant::now());+ }++ fn commit_staged(+ &self,+ open: &mut Open,+ message: &str,+ staging: &Staging,+ ) -> Result<Option<git2::Oid>, CommitGit2Error> {+ let Open {+ repo,+ commits_since_index_write,+ ..+ } = open;+ let mut index = repo.index().map_err(CommitGit2Error::Other)?;// Stage through libgit2's stat cache: an entry whose size and mtime// are unchanged keeps its cached blob OID and is not re-read, so a// commit costs what changed rather than the whole tree. The cache can@@ -101,9 +334,34 @@ impl GitAdapter {// `write_tree` fails, and through the wiki migration that crash-looped// the server at boot (#594). That is the recovery path: drop the index// and hash every file again, once.- let mut index = repo.index().map_err(CommitGit2Error::Other)?;- let touched = stage_working_tree(&mut index).map_err(CommitGit2Error::Other)?;- debug!(touched, "staged working tree");+ let touched = match staging {+ Staging::Everything => {+ let walked = stage_working_tree(&mut index).map_err(CommitGit2Error::Other)?;+ self.record_walk(&walked);+ walked.len()+ }+ Staging::Paths(paths) => {+ stage_paths(&self.root, &mut index, paths).map_err(CommitGit2Error::Other)?+ }+ };+ // The index file is the stat cache across restarts; serializing it+ // costs the size of the tree, so not per commit.+ let write_index = match staging {+ Staging::Everything => true,+ Staging::Paths(_) => {+ *commits_since_index_write += 1;+ *commits_since_index_write >= INDEX_WRITE_EVERY+ }+ };+ if write_index {+ index.write().map_err(CommitGit2Error::Other)?;+ *commits_since_index_write = 0;+ }+ debug!(+ touched,+ walked = matches!(staging, Staging::Everything),+ "staged"+ );let tree_oid = match index.write_tree() {Ok(oid) => oid,Err(e) => {@@ -113,6 +371,7 @@ impl GitAdapter {);index.clear().map_err(CommitGit2Error::Other)?;stage_working_tree(&mut index).map_err(CommitGit2Error::Other)?;+ index.write().map_err(CommitGit2Error::Other)?;index.write_tree().map_err(CommitGit2Error::Other)?}};@@ -236,26 +495,144 @@ impl GitAdapter {}}+/// The writes into the tree, each reporting its path; `clippy.toml`+/// refuses the raw calls. Each holds the commit lock for the write, so a+/// commit never reads a file mid-write ("file changed before we could+/// read it" would drop the commit).+#[allow(clippy::disallowed_methods)]+impl GitAdapter {+ fn writing(&self) -> MutexGuard<'_, Option<Open>> {+ self.commit_lock.lock().unwrap_or_else(|e| e.into_inner())+ }++ /// Write `bytes` to `path` atomically (tmp, rename, fsync).+ ///+ /// # Errors+ /// Propagates the filesystem error.+ pub fn write_atomic(&self, path: &Path, bytes: &[u8]) -> WikiResult<()> {+ let _writing = self.writing();+ crate::atomic::write_atomic(path, bytes)?;+ self.mark_written(path);+ Ok(())+ }++ /// Persist a temp file over `path` and return the persisted file.+ pub(crate) fn persist(+ &self,+ tmp: tempfile::NamedTempFile,+ path: &Path,+ ) -> Result<std::fs::File, tempfile::PersistError> {+ let _writing = self.writing();+ let file = crate::atomic::persist_with_retry(tmp, path)?;+ self.mark_written(path);+ Ok(file)+ }++ /// Append `bytes` to `path`, creating it and its parent as needed.+ ///+ /// # Errors+ /// Propagates the filesystem error.+ pub fn append(&self, path: &Path, bytes: &[u8]) -> std::io::Result<()> {+ let _writing = self.writing();+ use std::io::Write as _;+ if let Some(parent) = path.parent()+ && !parent.as_os_str().is_empty()+ {+ std::fs::create_dir_all(parent)?;+ }+ let mut file = std::fs::OpenOptions::new()+ .create(true)+ .append(true)+ .open(path)?;+ file.write_all(bytes)?;+ file.sync_data()?;+ self.mark_written(path);+ Ok(())+ }++ /// Move `from` to `to`.+ ///+ /// # Errors+ /// Propagates the filesystem error.+ pub fn rename(&self, from: &Path, to: &Path) -> std::io::Result<()> {+ let _writing = self.writing();+ std::fs::rename(from, to)?;+ self.mark_written(from);+ self.mark_written(to);+ Ok(())+ }++ /// Remove one file.+ ///+ /// # Errors+ /// Propagates the filesystem error.+ pub fn remove_file(&self, path: &Path) -> std::io::Result<()> {+ let _writing = self.writing();+ std::fs::remove_file(path)?;+ self.mark_written(path);+ Ok(())+ }++ /// Remove a directory and everything under it.+ ///+ /// # Errors+ /// Propagates the filesystem error.+ pub fn remove_dir_all(&self, path: &Path) -> std::io::Result<()> {+ let _writing = self.writing();+ std::fs::remove_dir_all(path)?;+ self.mark_written(path);+ Ok(())+ }+}++/// Forward slashes whatever the platform, for pathspecs and page paths.+pub(crate) fn slash_path(rel: &Path) -> String {+ rel.to_string_lossy().replace('\\', "/")+}+/// Bring the index in line with the working tree: refresh modified/// entries, drop deleted ones, add untracked files. libgit2 does all three-/// from one index-to-workdir diff. Returns how many paths that diff-/// touched; the index file is rewritten only when it touched some, so a-/// clean commit does not serialize every entry.-fn stage_working_tree(index: &mut git2::Index) -> Result<usize, git2::Error> {- let mut touched = 0usize;+/// from one index-to-workdir diff. Returns the paths touched; does not+/// write the index file.+fn stage_working_tree(index: &mut git2::Index) -> Result<Vec<PathBuf>, git2::Error> {+ let mut touched = Vec::new();index.add_all(["*"].iter(),IndexAddOption::DEFAULT,- Some(&mut |_: &Path, _: &[u8]| {- touched += 1;+ Some(&mut |path: &Path, _: &[u8]| {+ touched.push(path.to_path_buf());0}),)?;- if touched > 0 {- index.write()?;- }Ok(touched)}+/// Stage only `paths`: a file by path, a directory with its subtree, a+/// gone path by removing its entries. Does not write the index file.+fn stage_paths(+ root: &Path,+ index: &mut git2::Index,+ paths: &BTreeSet<PathBuf>,+) -> Result<usize, git2::Error> {+ for rel in paths {+ let abs = root.join(rel);+ if abs.is_dir() {+ let spec = slash_path(rel);+ index.add_all(+ [spec.as_str()].iter(),+ IndexAddOption::DISABLE_PATHSPEC_MATCH,+ None,+ )?;+ } else if abs.is_file() {+ index.add_path(rel)?;+ } else if index.get_path(rel, 0).is_some() {+ index.remove_path(rel)?;+ } else {+ // Gone and not a file in the index: a directory, or nothing.+ index.remove_dir(rel, 0)?;+ }+ }+ Ok(paths.len())+}#[cfg(windows)]fn commit_all_fallback(@@ -392,7 +769,7 @@ fn file_at_rev_fallback(original: WikiError,) -> WikiResult<Vec<u8>> {warn!(error = %original, root = %root.display(), "libgit2 show failed; trying git CLI fallback");- let rel = path.to_string_lossy().replace('\\', "/");+ let rel = slash_path(path);let spec = format!("{rev}:{rel}");let out = git_output(root, ["show", &spec])?;Ok(out.stdout)@@ -482,6 +859,7 @@ fn map_git_err(e: git2::Error) -> WikiError {}#[cfg(test)]+#[allow(clippy::disallowed_methods)]mod tests {use super::*;use tempfile::TempDir;@@ -575,7 +953,9 @@ mod tests {let staged = |root: &Path| {let repo = Repository::open(root).unwrap();let mut index = repo.index().unwrap();- stage_working_tree(&mut index).unwrap()+ let touched = stage_working_tree(&mut index).unwrap().len();+ index.write().unwrap();+ touched};assert_eq!(staged(&root), 0, "a clean tree stages nothing");std::fs::write(root.join("page-7.md"), "page 7, revised").unwrap();@@ -587,6 +967,362 @@ mod tests {assert_eq!(adapter.commit_count(), 2);}+ fn head_blob(adapter: &GitAdapter, rel: &str) -> Option<String> {+ adapter+ .file_at_rev("HEAD", Path::new(rel))+ .ok()+ .map(|bytes| String::from_utf8_lossy(&bytes).into_owned())+ }++ fn write(root: &Path, rel: &str, body: &str) {+ let path = root.join(rel);+ std::fs::create_dir_all(path.parent().unwrap()).unwrap();+ std::fs::write(path, body).unwrap();+ }++ /// `files` committed by the fixture's own walk.+ fn committed(files: &[(&str, &str)]) -> (TempDir, PathBuf, GitAdapter) {+ let tmp = tempdir();+ let root = tmp.path().join("wiki");+ let adapter = GitAdapter::open_or_init(&root).unwrap();+ for (rel, body) in files {+ write(&root, rel, body);+ }+ adapter.commit_all("initial").unwrap();+ (tmp, root, adapter)+ }++ #[test]+ fn a_commit_stages_the_reported_paths_only() {+ let (_tmp, root, adapter) = committed(&[("page-7.md", "page 7"), ("page-8.md", "page 8")]);+ write(&root, "page-7.md", "seven, revised");+ write(&root, "page-8.md", "eight, revised");+ adapter.mark_written(&root.join("page-7.md"));+ assert_eq!(adapter.written_paths(), vec![PathBuf::from("page-7.md")]);+ assert!(adapter.commit_all("seven").unwrap().is_some());+ assert_eq!(+ head_blob(&adapter, "page-7.md").as_deref(),+ Some("seven, revised")+ );+ assert_eq!(+ head_blob(&adapter, "page-8.md").as_deref(),+ Some("page 8"),+ "the unreported edit is not in this commit"+ );+ assert!(adapter.written_paths().is_empty(), "the report is consumed");++ // Nothing reported: the tree is walked and the edit lands.+ assert!(adapter.commit_all("sweep").unwrap().is_some());+ assert_eq!(+ head_blob(&adapter, "page-8.md").as_deref(),+ Some("eight, revised")+ );+ }++ #[test]+ fn reported_deletions_and_directories_are_staged() {+ let (_tmp, root, adapter) =+ committed(&[("ws/proj/sessions/a.md", "a"), ("gone.md", "gone")]);+ std::fs::remove_file(root.join("gone.md")).unwrap();+ write(&root, "ws/proj/sessions/b.md", "b");+ adapter.mark_written(Path::new("gone.md"));+ adapter.mark_written(&root.join("ws/proj/sessions"));+ assert!(adapter.commit_all("delete and add").unwrap().is_some());+ assert!(head_blob(&adapter, "gone.md").is_none());+ assert_eq!(+ head_blob(&adapter, "ws/proj/sessions/b.md").as_deref(),+ Some("b")+ );+ }++ #[test]+ fn the_repository_directory_is_never_reported() {+ let (_tmp, root, adapter) = committed(&[("a.md", "a")]);+ adapter.mark_written(Path::new(".git/logs/HEAD"));+ adapter.mark_written(&root.join(".git/index"));+ adapter.mark_written(Path::new(".git"));+ assert!(adapter.written_paths().is_empty());+ }++ #[test]+ fn the_adapters_writes_report_their_paths() {+ let (_tmp, root, adapter) = committed(&[("a.md", "a")]);+ adapter.write_atomic(&root.join("b.md"), b"b").unwrap();+ adapter.append(&root.join("log.md"), b"line\n").unwrap();+ adapter+ .rename(&root.join("a.md"), &root.join("c.md"))+ .unwrap();+ adapter.remove_file(&root.join("b.md")).unwrap();+ let reported: Vec<PathBuf> = adapter.written_paths();+ assert_eq!(+ reported,+ ["a.md", "b.md", "c.md", "log.md"]+ .map(PathBuf::from)+ .to_vec()+ );+ adapter.commit_all("writes").unwrap();+ assert!(head_blob(&adapter, "a.md").is_none());+ assert!(head_blob(&adapter, "b.md").is_none());+ assert_eq!(head_blob(&adapter, "c.md").as_deref(), Some("a"));+ assert_eq!(head_blob(&adapter, "log.md").as_deref(), Some("line\n"));+ }++ #[test]+ fn the_tree_is_swept_on_the_interval_and_when_a_report_is_untrusted() {+ let (tmp, root, adapter) = committed(&[("tracked.md", "0"), ("bypassed.md", "old")]);+ write(&root, "bypassed.md", "edited behind the wiki");+ write(&root, "tracked.md", "1");+ adapter.mark_written(Path::new("tracked.md"));+ adapter.commit_all("session 1").unwrap();+ assert_eq!(+ head_blob(&adapter, "bypassed.md").as_deref(),+ Some("old"),+ "a path-scoped commit within the interval leaves the bypassed edit"+ );++ adapter.age_last_walk();+ write(&root, "tracked.md", "2");+ adapter.mark_written(Path::new("tracked.md"));+ adapter.commit_all("session 2").unwrap();+ assert_eq!(+ head_blob(&adapter, "bypassed.md").as_deref(),+ Some("edited behind the wiki"),+ "the sweep walks the tree"+ );++ write(&root, "bypassed.md", "edited again");+ write(&root, "tracked.md", "x");+ adapter.mark_written(Path::new("tracked.md"));+ adapter.mark_written(tmp.path().join("elsewhere.md").as_path());+ adapter.commit_all("untrusted report").unwrap();+ assert_eq!(+ head_blob(&adapter, "bypassed.md").as_deref(),+ Some("edited again"),+ "a report naming a path outside the root walks the tree"+ );+ }++ /// A directory report covers its subtree.+ #[test]+ fn the_sweep_names_the_writes_nobody_reported() {+ let (_tmp, root, adapter) = committed(&[("ws/proj/a.md", "a")]);+ assert_eq!(adapter.sweep_snapshot(), SweepSnapshot::default());++ write(&root, "ws/proj/a.md", "a2");+ write(&root, "ws/proj/b.md", "nobody reported this");+ adapter.mark_written(Path::new("ws/proj/a.md"));+ adapter.age_last_walk();+ adapter.commit_all("sweep").unwrap();+ assert_eq!(+ adapter.sweep_snapshot(),+ SweepSnapshot {+ unreported_writes: 1,+ last_unreported: vec![PathBuf::from("ws/proj/b.md")],+ }+ );++ write(&root, "ws/proj/c.md", "c");+ adapter.mark_written(Path::new("ws/proj"));+ adapter.age_last_walk();+ adapter.commit_all("sweep again").unwrap();+ let snapshot = adapter.sweep_snapshot();+ assert_eq!(snapshot.unreported_writes, 1, "the count is cumulative");+ assert!(snapshot.last_unreported.is_empty());+ }++ #[test]+ fn concurrent_appends_do_not_fail_a_commit() {+ let (_tmp, root, adapter) = committed(&[("ws/proj/log.md", "")]);+ let ledger = root.join("ws/proj/log.md");+ let stop = Arc::new(std::sync::atomic::AtomicBool::new(false));+ let writers: Vec<_> = (0..3)+ .map(|_| {+ let adapter = adapter.clone();+ let ledger = ledger.clone();+ let stop = Arc::clone(&stop);+ std::thread::spawn(move || {+ while !stop.load(std::sync::atomic::Ordering::Relaxed) {+ adapter+ .append(&ledger, b"2026-09-08T00:00:00Z stop x\n")+ .unwrap();+ }+ })+ })+ .collect();+ for i in 0..30 {+ std::thread::sleep(Duration::from_millis(2));+ adapter.mark_written(&ledger);+ adapter+ .commit_all(&format!("session {i}"))+ .unwrap_or_else(|e| panic!("commit {i} failed: {e}"));+ }+ stop.store(true, std::sync::atomic::Ordering::Relaxed);+ for w in writers {+ w.join().unwrap();+ }+ assert!(adapter.commit_count() >= 2);+ }++ /// Not a test: run by hand with `--ignored --nocapture`.+ #[test]+ #[ignore]+ fn measure_commit_cost_on_a_large_tree() {+ let tmp = tempdir();+ let root = tmp.path().join("wiki");+ let adapter = GitAdapter::open_or_init(&root).unwrap();+ let projects = 120usize;+ let per_project = 150usize;+ for p in 0..projects {+ let dir = root.join(format!("ws/proj-{p:04}/sessions"));+ std::fs::create_dir_all(&dir).unwrap();+ for f in 0..per_project {+ std::fs::write(dir.join(format!("s-{f:04}.md")), "# session\n\nbody\n").unwrap();+ }+ }+ let t = Instant::now();+ adapter.commit_all("initial walk").unwrap();+ println!(+ "files {}: initial walk {:?}",+ projects * per_project,+ t.elapsed()+ );++ let t = Instant::now();+ adapter.commit_all("clean walk").unwrap();+ println!("clean walk (nothing reported) {:?}", t.elapsed());++ let mut scoped = Vec::new();+ for i in 0..10 {+ let rel = format!("ws/proj-{:04}/sessions/new-{i}.md", i % projects);+ std::fs::write(root.join(&rel), "# new\n\nbody\n").unwrap();+ adapter.mark_written(Path::new(&rel));+ let t = Instant::now();+ adapter.commit_all(&format!("scoped {i}")).unwrap();+ scoped.push(t.elapsed());+ }+ println!("path-scoped commits: {scoped:?}");+ }+ /// A later adapter's first commit walks from the stale index file+ /// and still commits everything.+ #[test]+ fn a_stale_index_file_costs_a_later_adapter_only_a_walk() {+ let (_tmp, root, adapter) = committed(&[("a.md", "a")]);+ for i in 0..3 {+ write(&root, "a.md", &format!("a{i}"));+ adapter.mark_written(Path::new("a.md"));+ adapter.commit_all(&format!("scoped {i}")).unwrap();+ }+ assert_eq!(head_blob(&adapter, "a.md").as_deref(), Some("a2"));+ write(&root, "b.md", "b");+ let later = GitAdapter::open_or_init(&root).unwrap();+ assert!(later.commit_all("from a fresh adapter").unwrap().is_some());+ assert_eq!(head_blob(&later, "a.md").as_deref(), Some("a2"));+ assert_eq!(head_blob(&later, "b.md").as_deref(), Some("b"));+ // The first adapter's kept index predates that commit.+ write(&root, "a.md", "a3");+ adapter.mark_written(Path::new("a.md"));+ adapter.commit_all("after the other adapter").unwrap();+ assert_eq!(head_blob(&adapter, "a.md").as_deref(), Some("a3"));+ assert_eq!(head_blob(&adapter, "b.md").as_deref(), Some("b"));+ }++ #[test]+ fn a_racy_read_is_the_filesystem_error_that_names_it() {+ let racy = git2::Error::new(+ ErrorCode::GenericError,+ git2::ErrorClass::Filesystem,+ "file changed before we could read it",+ );+ assert!(is_racy_read(&racy));+ let other_class = git2::Error::new(+ ErrorCode::GenericError,+ git2::ErrorClass::Os,+ "file changed before we could read it",+ );+ assert!(!is_racy_read(&other_class));+ let other_message = git2::Error::new(+ ErrorCode::GenericError,+ git2::ErrorClass::Filesystem,+ "failed to open",+ );+ assert!(!is_racy_read(&other_message));+ }++ /// A racy read keeps the commit path-scoped; any other failure walks.+ #[test]+ fn a_racy_read_failure_does_not_escalate_to_a_walk() {+ let (_tmp, _root, adapter) = committed(&[("a.md", "a")]);+ adapter.mark_written(Path::new("a.md"));+ let staging = adapter.take_staging();+ assert!(matches!(staging, Staging::Paths(_)));+ adapter.keep_pending(staging, true);+ assert_eq!(adapter.written_paths(), vec![PathBuf::from("a.md")]);+ let staging = adapter.take_staging();+ assert!(matches!(&staging, Staging::Paths(p) if p.len() == 1));++ adapter.keep_pending(staging, false);+ assert_eq!(adapter.written_paths(), vec![PathBuf::from("a.md")]);+ assert!(matches!(adapter.take_staging(), Staging::Everything));+ }++ #[test]+ fn persist_and_remove_dir_all_report_their_paths() {+ let (_tmp, root, adapter) = committed(&[("d/x.md", "x"), ("d/y.md", "y")]);+ let mut tmp = tempfile::NamedTempFile::new_in(&root).unwrap();+ std::io::Write::write_all(&mut tmp, b"p").unwrap();+ adapter.persist(tmp, &root.join("p.md")).unwrap();+ adapter.remove_dir_all(&root.join("d")).unwrap();+ assert_eq!(+ adapter.written_paths(),+ ["d", "p.md"].map(PathBuf::from).to_vec()+ );+ assert!(adapter.commit_all("persist and remove").unwrap().is_some());+ assert_eq!(head_blob(&adapter, "p.md").as_deref(), Some("p"));+ assert!(head_blob(&adapter, "d/x.md").is_none());+ assert!(head_blob(&adapter, "d/y.md").is_none());+ }++ #[test]+ fn the_index_file_is_written_after_a_walk_and_every_fifty_commits() {+ let (_tmp, root, adapter) = committed(&[("a.md", "a")]);+ let index_file = root.join(".git/index");+ let after_walk = std::fs::read(&index_file).unwrap();+ for i in 1..=INDEX_WRITE_EVERY {+ let rel = format!("n-{i}.md");+ write(&root, &rel, "n");+ adapter.mark_written(Path::new(&rel));+ assert!(adapter.commit_all(&rel).unwrap().is_some());+ let now = std::fs::read(&index_file).unwrap();+ if i < INDEX_WRITE_EVERY {+ assert_eq!(now, after_walk, "commit {i} wrote the index file");+ } else {+ assert_ne!(now, after_walk, "commit {i} did not write the index file");+ }+ }+ let before_walk = std::fs::read(&index_file).unwrap();+ write(&root, "b.md", "b");+ adapter.mark_written(Path::new("b.md"));+ adapter.age_last_walk();+ assert!(adapter.commit_all("sweep").unwrap().is_some());+ assert_ne!(std::fs::read(&index_file).unwrap(), before_walk);+ assert_eq!(head_blob(&adapter, "b.md").as_deref(), Some("b"));+ }++ #[test]+ fn a_failed_commit_keeps_the_reported_paths() {+ let (_tmp, root, adapter) = committed(&[("a.md", "a")]);+ write(&root, "a.md", "a2");+ adapter.mark_written(Path::new("a.md"));+ // Break the repository; the kept one is dropped first, as a restart would.+ adapter.close();+ let git_dir = root.join(".git");+ std::fs::rename(&git_dir, root.join(".git-parked")).unwrap();+ assert!(adapter.commit_all("broken").is_err());+ std::fs::rename(root.join(".git-parked"), &git_dir).unwrap();+ assert_eq!(adapter.written_paths(), vec![PathBuf::from("a.md")]);+ assert!(adapter.commit_all("retry").unwrap().is_some());+ assert_eq!(head_blob(&adapter, "a.md").as_deref(), Some("a2"));+ }/// The stat cache's blind spot: a file rewritten with the same size and/// an mtime no newer than the index looks unchanged by stat alone. git/// treats an entry whose mtime is not older than the index as "racy"diff --git a/crates/ai-memory-wiki/src/lib.rs b/crates/ai-memory-wiki/src/lib.rsindex b0d10c4c..7321a21d 100644--- a/crates/ai-memory-wiki/src/lib.rs+++ b/crates/ai-memory-wiki/src/lib.rs@@ -35,5 +35,6 @@ pub use wiki::{MoveSessionOutcome, SessionPageFile, Wiki, WritePageRequest};#[cfg(test)]extern crate self as ai_memory_wiki;#[cfg(test)]+#[allow(clippy::disallowed_methods)]#[path = "../tests/suite/mod.rs"]mod integration;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.rsindex eed55476..7beff69d 100644--- a/crates/ai-memory-wiki/src/migrations/m2026_09_okf_conformance.rs+++ b/crates/ai-memory-wiki/src/migrations/m2026_09_okf_conformance.rs@@ -17,7 +17,6 @@//!//! 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;@@ -173,9 +172,9 @@ impl WikiMigration for OkfConformance {// 4. File pass.for file in file_pending {- conform_file(wiki_root, &file, &at_by_page)?;+ conform_file(&git, &file, &at_by_page)?;}- ensure_bundle_indexes(wiki_root)?;+ ensure_bundle_indexes(&git)?;// 5. One commit for the whole rewrite.git.commit_all("okf-migration: conform wiki to OKF v0.2")?;@@ -260,11 +259,11 @@ fn is_ledger_file(path: &Path) -> bool {/// (`_meta.md`) get their `type` only — they are identity records, not/// concept pages with provenance.fn conform_file(- wiki_root: &Path,+ git: &crate::git::GitAdapter,rel: &Path,at_by_page: &std::collections::HashMap<(String, String, String), String>,) -> WikiResult<()> {- let abs = wiki_root.join(rel);+ let abs = git.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()),@@ -306,9 +305,7 @@ fn conform_file(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)?;+ git.write_atomic(&abs, emitted.as_bytes())?;}Ok(())}@@ -327,8 +324,8 @@ fn mtime_iso(path: &Path) -> 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 {+fn ensure_bundle_indexes(git: &crate::git::GitAdapter) -> WikiResult<()> {+ let Ok(workspaces) = std::fs::read_dir(git.root()) else {return Ok(());};for ws in workspaces.flatten() {@@ -362,13 +359,14 @@ fn ensure_bundle_indexes(wiki_root: &Path) -> WikiResult<()> {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)?;+ git.write_atomic(&index, content.as_bytes())?;}}Ok(())}#[cfg(test)]+#[allow(clippy::disallowed_methods)]mod tests {use ai_memory_core::{PagePath, Tier};use ai_memory_store::Store;@@ -577,7 +575,8 @@ mod tests {std::fs::create_dir_all(abs.parent().unwrap()).unwrap();std::fs::write(&abs, "\u{FEFF}# Hand written\n\nBody.\n").unwrap();- conform_file(tmp.path(), rel, &std::collections::HashMap::new()).unwrap();+ let git = crate::git::GitAdapter::open_or_init(tmp.path()).unwrap();+ conform_file(&git, rel, &std::collections::HashMap::new()).unwrap();let conformed = std::fs::read_to_string(&abs).unwrap();assert!(diff --git a/crates/ai-memory-wiki/src/watcher.rs b/crates/ai-memory-wiki/src/watcher.rsindex 2daed57f..4b7a5a97 100644--- a/crates/ai-memory-wiki/src/watcher.rs+++ b/crates/ai-memory-wiki/src/watcher.rs@@ -196,7 +196,22 @@ async fn run_loop(}}+/// Inside the wiki's own git directory: neither indexed nor reported.+fn is_git_internal(root: &Path, path: &Path) -> bool {+ path.strip_prefix(root)+ .is_ok_and(|rel| rel.starts_with(".git"))+}+async fn handle_event(wiki: &Wiki, event: notify_debouncer_full::DebouncedEvent) {+ // Nothing to index, but the next auto-commit must stage it.+ if matches!(event.kind, EventKind::Remove(_)) {+ for raw_path in &event.paths {+ if !is_tempfile(raw_path) && !is_git_internal(wiki.root(), raw_path) {+ wiki.git().mark_written(raw_path);+ }+ }+ return;+ }if !matches!(event.kind,EventKind::Create(_) | EventKind::Modify(_) | EventKind::Other@@ -204,6 +219,9 @@ async fn handle_event(wiki: &Wiki, event: notify_debouncer_full::DebouncedEvent)return;}for raw_path in &event.paths {+ if is_git_internal(wiki.root(), raw_path) {+ continue;+ }let Ok(metadata) = std::fs::symlink_metadata(raw_path) else {// Likely a transient state (mv, atomic rename in flight).continue;@@ -219,15 +237,15 @@ async fn handle_event(wiki: &Wiki, event: notify_debouncer_full::DebouncedEvent)reindex_project_dir(wiki, ws, proj, proj_root).await;continue;}- if !ft.is_file() {+ if !ft.is_file() || is_tempfile(raw_path) {continue;}+ // Reported before the indexer's filters, which skip ledgers,+ // pending and non-markdown files.+ wiki.git().mark_written(raw_path);if !is_markdown(raw_path) {continue;}- if is_tempfile(raw_path) {- continue;- }let Some((ws, proj, page_path)) = extract_project_ids(wiki.root(), raw_path) else {continue;};@@ -425,7 +443,7 @@ pub(crate) fn extract_project_ids(// Rejoin remaining segments as the page path.let page_rel: std::path::PathBuf = components.collect();- let page_str = page_rel.to_string_lossy().replace('\\', "/");+ let page_str = crate::git::slash_path(&page_rel);if page_str.is_empty() {return None;}@@ -539,11 +557,11 @@ fn is_reserved_page_file(abs: &Path, page_path: &PagePath) -> bool {fn page_path_relative_to(root: &Path, abs: &Path) -> Option<PagePath> {let rel: &Path = abs.strip_prefix(root).ok()?;- let s = rel.to_string_lossy().replace('\\', "/");- PagePath::new(s).ok()+ PagePath::new(crate::git::slash_path(rel)).ok()}#[cfg(test)]+#[allow(clippy::disallowed_methods)]mod tests {use super::*;use ai_memory_store::Store;@@ -731,6 +749,43 @@ mod tests {assert_eq!(hits[0].path.as_str(), "external.md");}+ /// The watcher reports what the next auto-commit must stage: removals,+ /// and files the indexer skips; never the wiki's own git directory.+ #[tokio::test(flavor = "multi_thread", worker_threads = 2)]+ async fn events_report_their_paths_for_the_next_commit() {+ let (_tmp, _store, wiki, ws, proj) = setup().await;+ let proj_dir = wiki.root().join(ws.to_string()).join(proj.to_string());+ std::fs::create_dir_all(&proj_dir).unwrap();+ let ledger = proj_dir.join("events.jsonl");+ std::fs::write(&ledger, "{}\n").unwrap();+ let git_log = wiki.root().join(".git/logs/HEAD");+ std::fs::create_dir_all(git_log.parent().unwrap()).unwrap();+ std::fs::write(&git_log, "ref\n").unwrap();+ let gone = proj_dir.join("gone.md");++ for (kind, path) in [+ (EventKind::Create(notify::event::CreateKind::File), &ledger),+ (EventKind::Modify(notify::event::ModifyKind::Any), &git_log),+ (EventKind::Remove(notify::event::RemoveKind::File), &gone),+ (EventKind::Remove(notify::event::RemoveKind::File), &git_log),+ ] {+ let event = notify_debouncer_full::DebouncedEvent::new(+ notify::Event::new(kind).add_path(path.clone()),+ std::time::Instant::now(),+ );+ handle_event(&wiki, event).await;+ }++ let reported = wiki.git().written_paths();+ let rel = |p: &Path| p.strip_prefix(wiki.root()).unwrap().to_path_buf();+ assert!(reported.contains(&rel(&ledger)), "{reported:?}");+ assert!(reported.contains(&rel(&gone)), "{reported:?}");+ assert!(+ !reported.iter().any(|p| p.starts_with(".git")),+ "{reported:?}"+ );+ }+#[tokio::test(flavor = "multi_thread", worker_threads = 2)]async fn reconcile_picks_up_file_added_while_watcher_offline() {let (tmp, store, wiki, ws, proj) = setup().await;diff --git a/crates/ai-memory-wiki/src/wiki.rs b/crates/ai-memory-wiki/src/wiki.rsindex 88068c8d..85ab938b 100644--- a/crates/ai-memory-wiki/src/wiki.rs+++ b/crates/ai-memory-wiki/src/wiki.rs@@ -17,7 +17,6 @@ use ai_memory_store::{use tokio::sync::RwLock;use crate::admission::{AdmissionChain, AdmissionContext, AdmissionOp};-use crate::atomic;use crate::error::{WikiError, WikiResult};use crate::git::{Checkpoint, GitAdapter};use crate::markdown::{Markdown, derive_title, emit, parse};@@ -252,6 +251,22 @@ impl Wiki {self.git.commit_all(message)}+ /// Append `bytes` to `<project root>/<file_name>` (the hook ledger)+ /// and report the write.+ ///+ /// # Errors+ /// Propagates the filesystem error.+ pub fn append_under_project(+ &self,+ workspace_id: WorkspaceId,+ project_id: ProjectId,+ file_name: &str,+ bytes: &[u8],+ ) -> std::io::Result<PathBuf> {+ let path = self.project_root(workspace_id, project_id).join(file_name);+ self.git.append(&path, bytes)?;+ Ok(path)+ }/// Return the most recent wiki git checkpoints, newest first.////// # Errors@@ -348,7 +363,7 @@ impl Wiki {if let Some(parent) = dst.parent() {std::fs::create_dir_all(parent)?;}- std::fs::rename(&src, &dst)?;+ self.git.rename(&src, &dst)?;true} else {// Nothing on disk to move (a project with zero written pages).@@ -371,7 +386,7 @@ impl Wiki {if let Some(parent) = src.parent() {std::fs::create_dir_all(parent)?;}- if let Err(rollback_err) = std::fs::rename(&dst, &src) {+ if let Err(rollback_err) = self.git.rename(&dst, &src) {return Err(crate::WikiError::Io(std::io::Error::other(format!("INCONSISTENT STATE: files moved but DB re-stamp failed ({e}) and dir rename-back also failed ({rollback_err}); manually move {} -> {} or finish the re-stamp",dst.display(),@@ -453,7 +468,7 @@ impl Wiki {if let Some(parent) = target.parent() {std::fs::create_dir_all(parent)?;}- std::fs::rename(&src, &target)?;+ self.git.rename(&src, &target)?;Some(target)} else {None@@ -471,7 +486,7 @@ impl Wiki {(Some(tmp), PagesMode::Regenerate) => {// The rows are retired; a leftover temp file is// ignored by the watcher, so this is best-effort.- if let Err(e) = std::fs::remove_file(tmp) {+ if let Err(e) = self.git.remove_file(tmp) {tracing::warn!(error = %e,path = %tmp.display(),@@ -488,7 +503,7 @@ impl Wiki {}Err(e) => {if let Some(target) = parked- && let Err(rollback_err) = std::fs::rename(&target, &src)+ && let Err(rollback_err) = self.git.rename(&target, &src){return Err(WikiError::Io(std::io::Error::other(format!("INCONSISTENT STATE: session page file moved but DB re-stamp failed ({e}) and moving it back also failed ({rollback_err}); manually move {} -> {}",@@ -574,11 +589,14 @@ impl Wiki {if let Some(repo_path) = scope.repo_path {project_fm["repo_path"] = serde_json::Value::String(repo_path);}- let written = Self::write_scope_manifest(- &ws_dir,- serde_json::json!({ "workspace": scope.workspace_name }),- )- .and_then(|_| Self::write_scope_manifest(&ws_dir.join(project_id.to_string()), project_fm));+ let written = self+ .write_scope_manifest(+ &ws_dir,+ serde_json::json!({ "workspace": scope.workspace_name }),+ )+ .and_then(|_| {+ self.write_scope_manifest(&ws_dir.join(project_id.to_string()), project_fm)+ });match written {Ok(_) => {self.manifested_scopes@@ -659,7 +677,7 @@ impl Wiki {if let Some(parent) = abs.parent() {std::fs::create_dir_all(parent)?;}- atomic::write_atomic(&abs, raw.as_bytes())?;+ self.git.write_atomic(&abs, raw.as_bytes())?;let id = self.writer.upsert_page(NewPage {@@ -853,7 +871,7 @@ impl Wiki {resolved_ctx = Some(ctx);}let abs = self.abs_path(workspace_id, project_id, path);- let quarantined = match quarantine_file(&abs) {+ let quarantined = match quarantine_file(&self.git, &abs) {Ok(path) => path,Err(e) if e.kind() == std::io::ErrorKind::NotFound => None,Err(e) => return Err(crate::WikiError::Io(e)),@@ -890,17 +908,17 @@ impl Wiki {let deleted = match delete_result {Ok(deleted) => deleted,Err(e) => {- restore_quarantined_file(&quarantined, &abs, path);+ restore_quarantined_file(&self.git, &quarantined, &abs, path);return Err(e.into());}};if !deleted {- restore_quarantined_file(&quarantined, &abs, path);+ restore_quarantined_file(&self.git, &quarantined, &abs, path);return Ok(false);}if let Some(quarantine) = quarantined {- std::fs::remove_file(&quarantine)?;+ self.git.remove_file(&quarantine)?;}if let (Some(chain), Some(ctx)) = (&self.admission_chain, &resolved_ctx) {@@ -1165,7 +1183,7 @@ impl Wiki {) -> WikiResult<()> {let _guard = self.mutation_lock.write().await;let root = self.project_root(workspace_id, project_id);- match std::fs::remove_dir_all(&root) {+ match self.git.remove_dir_all(&root) {Ok(()) => Ok(()),Err(e) if e.kind() == std::io::ErrorKind::NotFound => Ok(()),Err(e) => Err(crate::WikiError::Io(e)),@@ -1181,7 +1199,7 @@ impl Wiki {pub async fn remove_workspace_dir(&self, workspace_id: WorkspaceId) -> WikiResult<()> {let _guard = self.mutation_lock.write().await;let root = self.root.join(workspace_id.to_string());- match std::fs::remove_dir_all(&root) {+ match self.git.remove_dir_all(&root) {Ok(()) => Ok(()),Err(e) if e.kind() == std::io::ErrorKind::NotFound => Ok(()),Err(e) => Err(crate::WikiError::Io(e)),@@ -1204,7 +1222,7 @@ impl Wiki {) -> WikiResult<bool> {let _guard = self.mutation_lock.write().await;let abs = self.abs_path(workspace_id, project_id, path);- match std::fs::remove_file(&abs) {+ match self.git.remove_file(&abs) {Ok(()) => {sync_parent_best_effort(&abs);Ok(true)@@ -1264,7 +1282,7 @@ impl Wiki {let _guard = self.mutation_lock.read().await;self.ensure_project_workspace(workspace_id, project_id).await?;- atomic::write_atomic(&path, content.as_bytes())?;+ self.git.write_atomic(&path, content.as_bytes())?;Ok(path)}@@ -1362,7 +1380,8 @@ impl Wiki {self.ensure_project_workspace(workspace_id, project_id).await?;let abs = self.abs_path(workspace_id, project_id, &path);- let installed = replace_file_with_rollback_snapshot(&abs, emitted.as_bytes())?;+ let installed =+ replace_file_with_rollback_snapshot(&self.git, &abs, emitted.as_bytes())?;match self.writer.approve_auto_improve_proposal(ApproveAutoImproveProposal {@@ -1381,13 +1400,14 @@ impl Wiki {}Ok(ApproveAutoImproveProposalResult::Conflict) => {rollback_or_inconsistent(+ &self.git,std::slice::from_ref(&installed),&"proposal conflict",)?;ApproveAutoImproveProposalResult::Conflict}Err(e) => {- rollback_or_inconsistent(std::slice::from_ref(&installed), &e)?;+ rollback_or_inconsistent(&self.git, std::slice::from_ref(&installed), &e)?;return Err(e.into());}}@@ -1602,7 +1622,11 @@ impl Wiki {/// Write a `_meta.md` scope manifest under `dir` from `frontmatter`,/// idempotently — unchanged content is left untouched so a startup/// backfill never churns the wiki git history. Returns `true` if written.- fn write_scope_manifest(dir: &Path, mut frontmatter: serde_json::Value) -> WikiResult<bool> {+ fn write_scope_manifest(+ &self,+ dir: &Path,+ mut frontmatter: serde_json::Value,+ ) -> WikiResult<bool> {// OKF conformance at the manifest choke point: every non-reserved// .md needs a `type`, and the startup backfill's byte-compare must// agree with what the OKF migration writes — a typeless emit here@@ -1634,7 +1658,7 @@ impl Wiki {Ok(_) | Err(_) => {}}std::fs::create_dir_all(dir)?;- crate::atomic::write_atomic(&path, content.as_bytes())?;+ self.git.write_atomic(&path, content.as_bytes())?;Ok(true)}@@ -1656,7 +1680,7 @@ impl Wiki {let mut written = 0;for ws in workspaces {let ws_dir = self.root().join(ws.workspace_id.to_string());- if Self::write_scope_manifest(+ if self.write_scope_manifest(&ws_dir,serde_json::json!({ "workspace": ws.workspace_name }),)? {@@ -1669,7 +1693,7 @@ impl Wiki {if let Some(rp) = s.repo_path {fm["repo_path"] = serde_json::Value::String(rp);}- if Self::write_scope_manifest(&ws_dir.join(s.project_id.to_string()), fm)? {+ if self.write_scope_manifest(&ws_dir.join(s.project_id.to_string()), fm)? {written += 1;}}@@ -1817,10 +1841,10 @@ impl Wiki {let mut installed = Vec::with_capacity(staged_files.len());let mut dispatches = Vec::with_capacity(staged_files.len());for (req, tmp, abs, ctx) in staged_files {- let install = match persist_tmp_with_rollback_snapshot(tmp, &abs) {+ let install = match persist_tmp_with_rollback_snapshot(&self.git, tmp, &abs) {Ok(install) => install,Err(e) => {- rollback_or_inconsistent(&installed, &e)?;+ rollback_or_inconsistent(&self.git, &installed, &e)?;return Err(e);}};@@ -1831,7 +1855,7 @@ impl Wiki {let ids = match self.writer.upsert_pages_batch(pages).await {Ok(ids) => ids,Err(e) => {- rollback_or_inconsistent(&installed, &e)?;+ rollback_or_inconsistent(&self.git, &installed, &e)?;return Err(e.into());}};@@ -2022,7 +2046,8 @@ impl Wiki {if let Some(parent) = abs.parent() {std::fs::create_dir_all(parent)?;}- let installed = replace_file_with_rollback_snapshot(&abs, emitted.as_bytes())?;+ let installed =+ replace_file_with_rollback_snapshot(&self.git, &abs, emitted.as_bytes())?;match self.writer@@ -2044,7 +2069,7 @@ impl Wiki {{Ok(id) => id,Err(e) => {- rollback_or_inconsistent(std::slice::from_ref(&installed), &e)?;+ rollback_or_inconsistent(&self.git, std::slice::from_ref(&installed), &e)?;return Err(e.into());}}@@ -2398,11 +2423,12 @@ fn sync_parent_best_effort(path: &Path) {}fn persist_tmp_with_rollback_snapshot(+ git: &GitAdapter,tmp: tempfile::NamedTempFile,path: &Path,) -> WikiResult<InstalledFile> {let previous = snapshot_existing_file(path)?;- let persisted = crate::atomic::persist_with_retry(tmp, path)?;+ let persisted = git.persist(tmp, path)?;persisted.sync_data()?;sync_parent_best_effort(path);Ok(InstalledFile {@@ -2411,22 +2437,24 @@ fn persist_tmp_with_rollback_snapshot(})}-fn replace_file_with_rollback_snapshot(path: &Path, bytes: &[u8]) -> WikiResult<InstalledFile> {+fn replace_file_with_rollback_snapshot(+ git: &GitAdapter,+ path: &Path,+ bytes: &[u8],+) -> WikiResult<InstalledFile> {let previous = snapshot_existing_file(path)?;- atomic::write_atomic(path, bytes)?;+ git.write_atomic(path, bytes)?;Ok(InstalledFile {path: path.to_path_buf(),previous,})}-fn rollback_installed_files(installed: &[InstalledFile]) -> WikiResult<()> {+fn rollback_installed_files(git: &GitAdapter, installed: &[InstalledFile]) -> WikiResult<()> {for file in installed.iter().rev() {match &file.previous {- Some(bytes) => {- atomic::write_atomic(&file.path, bytes)?;- }- None => match std::fs::remove_file(&file.path) {+ Some(bytes) => git.write_atomic(&file.path, bytes)?,+ None => match git.remove_file(&file.path) {Ok(()) => sync_parent_best_effort(&file.path),Err(e) if e.kind() == std::io::ErrorKind::NotFound => {}Err(e) => return Err(WikiError::Io(e)),@@ -2437,10 +2465,11 @@ fn rollback_installed_files(installed: &[InstalledFile]) -> WikiResult<()> {}fn rollback_or_inconsistent<E: std::fmt::Display>(+ git: &GitAdapter,installed: &[InstalledFile],cause: &E,) -> WikiResult<()> {- if let Err(rollback_err) = rollback_installed_files(installed) {+ if let Err(rollback_err) = rollback_installed_files(git, installed) {return Err(WikiError::Io(std::io::Error::other(format!("INCONSISTENT STATE: wiki files changed but store write failed ({cause}) and rollback failed ({rollback_err})"))));@@ -2448,7 +2477,7 @@ fn rollback_or_inconsistent<E: std::fmt::Display>(Ok(())}-fn quarantine_file(path: &Path) -> std::io::Result<Option<PathBuf>> {+fn quarantine_file(git: &GitAdapter, path: &Path) -> std::io::Result<Option<PathBuf>> {let Some(parent) = path.parent() else {return Err(std::io::Error::other("page path has no parent (cannot quarantine delete)",@@ -2458,19 +2487,24 @@ fn quarantine_file(path: &Path) -> std::io::Result<Option<PathBuf>> {.prefix(".ai-memory-delete.").tempfile_in(parent)?;let (_file, quarantine) = tmp.keep().map_err(|e| e.error)?;- std::fs::remove_file(&quarantine)?;- match std::fs::rename(path, &quarantine) {+ git.remove_file(&quarantine)?;+ match git.rename(path, &quarantine) {Ok(()) => Ok(Some(quarantine)),Err(e) => {- let _ = std::fs::remove_file(&quarantine);+ let _ = git.remove_file(&quarantine);Err(e)}}}-fn restore_quarantined_file(quarantined: &Option<PathBuf>, path: &Path, page_path: &PagePath) {+fn restore_quarantined_file(+ git: &GitAdapter,+ quarantined: &Option<PathBuf>,+ path: &Path,+ page_path: &PagePath,+) {if let Some(quarantine) = quarantined- && let Err(error) = std::fs::rename(quarantine, path)+ && let Err(error) = git.rename(quarantine, path){tracing::error!(path = %page_path.as_str(),@@ -2551,6 +2585,7 @@ fn is_slot_path(path: &PagePath) -> bool {}#[cfg(test)]+#[allow(clippy::disallowed_methods)]mod tests {use super::*;use crate::admission::{FailurePolicy, WebhookConfig};