Skip to content

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.md
index 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
### Changed
diff --git a/crates/ai-memory-hooks/src/log.rs b/crates/ai-memory-hooks/src/log.rs
index 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.toml
new file mode 100644
index 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.rs
index 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.rs
index 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.rs
index 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.rs
index 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.rs
index 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.rs
index 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.rs
index 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};