Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors
Rust
feat(wikisync): conditional sync writes and opt-in deletes (#986 slice 4)
AkitaOnRails7752ab28ef12
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 9daea926..7bf89221 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -15,6 +15,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0current version, and changes nothing. `memory_read_page` returns the versionas `page_id` and `/api/v1` pages as `id`. This is the compare-and-write theteam-wiki sync needed (#986).+- The `ai-memory-wikisync` companion now propagates deletes with+ `sync --propagate-deletes` (#986, slice 4): a file deleted in the repository+ deletes its server page through `memory_delete_page`, and a page deleted on+ the server deletes its file, when the other side is unchanged since the last+ sync. A delete against an edit is a conflict that `--prefer` resolves, more+ than `--max-deletes` (default 10) refuses the run, and a pinned page is+ deleted only with `--prefer repo`. Every sync write and delete now carries+ the page version it was planned against, so a page changed during the run is+ reported and left alone while the rest apply, and `sync --apply` refuses a+ server older than 2.7. Without the flag deletes are still only reported.+ (#986)- `ai-memory doctor` now reports three silent capture failures: an unreachableserver (reported instead of aborting the check), a hook spool that is full andevicting undelivered events, and installed ai-memory Codex hooks that Codexdiff --git a/companions/ai-memory-wikisync/README.md b/companions/ai-memory-wikisync/README.mdindex eee27e40..1795aa49 100644--- a/companions/ai-memory-wikisync/README.md+++ b/companions/ai-memory-wikisync/README.md@@ -2,13 +2,18 @@**Team-wiki sync** companion for[ai-memory](https://github.com/akitaonrails/ai-memory) (issue #986, slices-1 and 3). It keeps explicitly allowlisted page families of a running+1, 3 and 4). It keeps explicitly allowlisted page families of a runningai-memory server in step with a directory inside a project repository, so ateam's shared memory can live as reviewable markdown in git:- `export` copies server pages into the repository (one way).- `sync` also sends repository edits back to the server, through the public- `memory_write_page` MCP tool.+ `memory_write_page` MCP tool, and with `--propagate-deletes` carries+ deletes both ways through `memory_delete_page`.++`sync --apply` needs ai-memory 2.7 or later: every write and delete is+conditional on the page version the plan saw, and an older server would+ignore that condition, so `sync` refuses to write to one.It is a standalone Cargo package (own workspace, own lockfile); the rootai-memory workspace does not build or test it:@@ -37,6 +42,8 @@ ai-memory-wikisync sync ...ai-memory-wikisync sync ... --apply# A page changed on both sides is a conflict until a side is chosen.ai-memory-wikisync sync ... --apply --prefer repo # or --prefer server+# Carry deletes too (at most 10 per run unless --max-deletes says otherwise).+ai-memory-wikisync sync ... --apply --propagate-deletes```- `plan` never writes, not even the state file.@@ -74,8 +81,8 @@ because the tool clears whatever a write omits. Server-generated keysAll local bookkeeping lives in **one** state file,`.ai-memory-wikisync/state.json` (mode 0600, atomically replaced aftereach successful write batch): per page, the SHA-256 of the bytes last-written plus the server `ETag` observed at that write. Nothing else is-stored — no tokens, no server credentials.+written plus the server `ETag` and version id observed at that write.+Nothing else is stored — no tokens, no server credentials.The state is per clone. The state directory carries a `.gitignore` of `*`,so committing the destination never commits the state: two clones that@@ -106,9 +113,9 @@ This section describes `plan` and `export`; `sync` adds the rules underdiverged from both is reported with a diff summary and **refused**; thewhole batch is refused, nothing is written. `--force` overwrites thedivergent files with server content.-- **Never deletes.** Local files and server pages are never deleted,- including brand-new local files inside an allowlisted family. Deletes- are slice 4.+- **Never deletes.** `plan` and `export` never delete local files or server+ pages, including brand-new local files inside an allowlisted family.+ Only `sync --propagate-deletes` deletes (see below).- **Untrusted content.** Page bodies are data: transported verbatim,never executed, never rendered, never interpreted. Paths that wouldescape `--dest` are refused.@@ -125,8 +132,10 @@ and the server page rendered into file bytes.| changed | unchanged | import the file with `memory_write_page` || new file | no page | import (create) || changed | changed | conflict: nothing is written until `--prefer repo` or `--prefer server` |-| deleted | present | reported; the server page is kept |-| present | deleted | reported; the file is kept |+| deleted | unchanged | reported; with `--propagate-deletes`, the server page is deleted |+| unchanged | deleted | reported; with `--propagate-deletes`, the file is deleted |+| deleted | changed | with `--propagate-deletes`, a conflict: `--prefer repo` deletes the page, `--prefer server` re-exports the file |+| changed | deleted | with `--propagate-deletes`, a conflict: `--prefer repo` re-creates the page, `--prefer server` deletes the file |Safety rules:@@ -141,22 +150,36 @@ Safety rules:`generated` and `last_modified_by` (a consolidated page's `summary` or`sources`, an MCP write's `kind` or `abstract`) is never overwritten by animport; the refusal names the keys. Such pages still export.-- **Re-read before each write.** Right before an import the server page is- read again and must still render to the bytes it was classified against.- The MCP write has no compare-and-write, so a write that lands between that- read and the import is the one race left (the case for slice 2).+- **Every write is conditional.** Each import carries the page version the+ plan classified (`expected_page_id`), or `create_only` for a new page, and+ each delete carries the version too. A page that changes on the server+ after it was classified is refused by the server, reported as "changed+ during this run", and left with its old state for the next run; the other+ pages still sync, and the run exits non-zero. A server without these+ preconditions (before ai-memory 2.7) is detected before anything is+ written and refused.- **The server's version wins after an import.** If the server storessomething other than the file (the sanitizer redacting a secret), the fileis rewritten with the server's rendering.-- **Deletes are not synced yet** (slice 4). Pages gone from both sides drop- out of the state.+- **Deletes are opt-in.** Without `--propagate-deletes` a delete is only+ reported, and the page keeps its state entry so the next run reports it+ again. With it, a side is deleted only if it is unchanged since the last+ sync; a delete against an edit is a conflict like any other. Pages gone+ from both sides drop out of the state.+- **Delete safety.** More than `--max-deletes` deletes (default 10) refuses+ the whole run. A pinned server page is never deleted unless `--prefer repo`+ is given. A file is deleted only through the same path checks as a write+ (no symlinked file or directory, nothing outside `--dest`) and only if it+ still holds the bytes the plan classified. The tool never runs git: it+ prints the `git rm` to stage the deletes. Apply order is imports, exports,+ server deletes, file deletes.## Roadmap (#986)1. Read-only export into a project repository (`export`).-2. Conditional mutation seam (compare-and-write) in core, if independently- justified.-3. **This release — two-way sync** (`sync`): repository edits flow back- through the public MCP write tool.-4. Deletes and conflict reporting.+2. Conditional mutation seam (compare-and-write) in core (ai-memory 2.7).+3. Two-way sync (`sync`): repository edits flow back through the public MCP+ write tool.+4. **This release — deletes and conflict reporting** (`--propagate-deletes`,+ conditional writes).5. Post-merge hook / CI integration.diff --git a/companions/ai-memory-wikisync/src/bidi.rs b/companions/ai-memory-wikisync/src/bidi.rsindex d0462620..e5eee8eb 100644--- a/companions/ai-memory-wikisync/src/bidi.rs+++ b/companions/ai-memory-wikisync/src/bidi.rs@@ -1,18 +1,19 @@-//! Two-way sync (#986, slice 3): repository edits flow back to the server-//! through the public `memory_write_page` tool, server edits flow out as in-//! `export`.+//! Two-way sync (#986, slices 3 and 4): repository edits flow back to the+//! server through the public `memory_write_page` and `memory_delete_page`+//! tools, server edits flow out as in `export`.//!//! Every page in an allowlisted family is classified from three versions://! the repository file, the state entry (what the last sync wrote), and the//! server page rendered into file bytes. A change on one side is applied to//! the other; a change on both sides is a conflict that only `--prefer`-//! resolves. Deletes on either side are reported and left alone (slice 4).+//! resolves. Deletes are reported unless `--propagate-deletes` asks for them,+//! and even then only a side unchanged since the last sync is deleted.//!//! Nothing is written unless `--apply` is passed and nothing in the plan is-//! refused. Before each import the server page is read again and must still-//! render to the bytes it was classified against: the MCP write has no-//! compare-and-write, so that re-read narrows the race to the gap between-//! one read and one write (the case for slice 2).+//! refused. Every server write and delete carries the version the plan was+//! classified against (`expected_page_id`, or `create_only` for a new page),+//! so a page that changes between classification and write is refused by the+//! server, reported, and left for the next run.use std::collections::{BTreeMap, BTreeSet};use std::fs;@@ -22,7 +23,7 @@ use anyhow::{Context, Result, bail};use serde_json::Value;use crate::client::{ApiClient, ApiPage};-use crate::mcp::McpClient;+use crate::mcp::{self, McpClient, Precondition, PreconditionFailed, Scope};use crate::page_file::{self, PageMeta};use crate::state::{self, PageState, SyncState};use crate::sync::{self, Mode, RunArgs};@@ -49,6 +50,15 @@ pub enum Prefer {Server,}+/// How `decide` treats conflicts and deletes.+#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]+pub struct Policy {+ /// Which side wins a page changed on both sides.+ pub prefer: Option<Prefer>,+ /// Propagate a delete instead of only reporting it.+ pub propagate_deletes: bool,+}+/// What the server holds for one path.#[derive(Debug, Clone, Copy)]pub enum ServerSide<'a> {@@ -72,11 +82,16 @@ pub enum Action {Import {create: bool,},- /// Changed on both sides, and no `--prefer`.+ /// Changed on both sides (or deleted on one, changed on the other), and+ /// no `--prefer`.Conflict,- /// The server no longer has a page the last sync saw (slice 4).+ /// Delete the server page: the repository deleted the file.+ DeleteOnServer,+ /// Delete the repository file: the server deleted the page.+ DeleteInRepo,+ /// The server no longer has a page the last sync saw; reported only.DeletedOnServer,- /// The repository no longer has a file the last sync wrote (slice 4).+ /// The repository no longer has a file the last sync wrote; reported only.DeletedInRepo,/// Gone from both sides: only the state entry remains, and it is dropped.GoneOnBothSides,@@ -88,18 +103,27 @@ pub fn decide(disk: Option<&[u8]>,base: Option<&PageState>,server: ServerSide<'_>,- prefer: Option<Prefer>,+ policy: Policy,) -> Action {let disk_hash = disk.map(state::sha256_hex);let disk_is_base = matches!((&disk_hash, base), (Some(disk), Some(base)) if *disk == base.hash);+ let prefer = policy.prefer;match server {ServerSide::Absent => match (disk.is_some(), base.is_some()) {(true, false) => Action::Import { create: true },- (true, true) => Action::DeletedOnServer,+ (true, true) if !policy.propagate_deletes => Action::DeletedOnServer,+ (true, true) if disk_is_base => Action::DeleteInRepo,+ (true, true) => match prefer {+ Some(Prefer::Repo) => Action::Import { create: true },+ Some(Prefer::Server) => Action::DeleteInRepo,+ None => Action::Conflict,+ },(false, true) => Action::GoneOnBothSides,(false, false) => Action::Unchanged,},+ // A 304 proves the server unchanged since the base.ServerSide::NotModified => match (disk.is_some(), base.is_some()) {+ (false, true) if policy.propagate_deletes => Action::DeleteOnServer,(false, true) => Action::DeletedInRepo,(false, false) => Action::Unchanged,(true, _) if disk_is_base => Action::Unchanged,@@ -107,14 +131,19 @@ pub fn decide(},ServerSide::Rendered(server) => {let server_hash = state::sha256_hex(server);+ let server_is_base = base.is_some_and(|base| base.hash == server_hash);match disk_hash {- None if base.is_some() => Action::DeletedInRepo,- None => Action::Export { create: true },+ None if base.is_none() => Action::Export { create: true },+ None if !policy.propagate_deletes => Action::DeletedInRepo,+ None if server_is_base => Action::DeleteOnServer,+ None => match prefer {+ Some(Prefer::Repo) => Action::DeleteOnServer,+ Some(Prefer::Server) => Action::Export { create: true },+ None => Action::Conflict,+ },Some(disk) if disk == server_hash => Action::Unchanged,Some(_) if disk_is_base => Action::Export { create: false },- Some(_) if base.is_some_and(|base| base.hash == server_hash) => {- Action::Import { create: false }- }+ Some(_) if server_is_base => Action::Import { create: false },Some(_) => match prefer {Some(Prefer::Repo) => Action::Import { create: false },Some(Prefer::Server) => Action::Export { create: false },@@ -144,6 +173,57 @@ pub fn keys_an_import_would_clear(frontmatter: &Value) -> Vec<String> {pub struct SyncArgs {pub run: RunArgs,pub prefer: Option<Prefer>,+ /// Propagate deletes instead of reporting them.+ pub propagate_deletes: bool,+ /// Ceiling on deletes in one run; more refuses the whole batch.+ pub max_deletes: usize,+}++/// Default `--max-deletes`.+pub const DEFAULT_MAX_DELETES: usize = 10;++/// What `sync` does with its plan.+#[derive(Debug, Clone, Copy, PartialEq, Eq)]+pub enum SyncMode {+ /// Print the plan, write nothing.+ DryRun,+ /// Print the plan and perform it.+ Apply,+ /// Print the plan, write nothing, and report whether anything is pending+ /// (`--check`). A clone without a state file compares the repository with+ /// the server directly.+ Check,+}++/// Whether the repository and the server agree, as `--check` reports it.+#[derive(Debug, Clone, Copy, PartialEq, Eq)]+pub enum CheckStatus {+ InSync,+ /// Imports, exports, deletes or unpropagated deletes are pending.+ Drift,+ /// Conflicts or refusals: a person has to decide.+ Blocked,+}++/// The plan's verdict, returned by every mode.+#[derive(Debug, Clone, Copy, PartialEq, Eq)]+pub struct Outcome {+ /// Pages that differ between the two sides.+ pub pending: usize,+ /// Anything refused (a conflict, an invalid file, the delete ceiling).+ pub blocked: bool,+}++impl Outcome {+ pub fn status(self) -> CheckStatus {+ if self.blocked {+ CheckStatus::Blocked+ } else if self.pending > 0 {+ CheckStatus::Drift+ } else {+ CheckStatus::InSync+ }+ }}struct Import {@@ -152,9 +232,9 @@ struct Import {meta: PageMeta,body: String,disk: Vec<u8>,- /// Hash of the server page's rendering at classification, which must- /// still hold right before the write; `None` for a create.- expected_server: Option<String>,+ /// Server version the plan was classified against, sent as the write's+ /// precondition; `None` for a create, which is sent as `create_only`.+ expected_page_id: Option<String>,}struct Export {@@ -162,6 +242,21 @@ struct Export {create: bool,bytes: String,etag: Option<String>,+ page_id: Option<String>,+}++/// A server page to delete because its file was deleted.+struct ServerDelete {+ path: String,+ /// `None` only from a server that predates version ids.+ expected_page_id: Option<String>,+}++/// A repository file to delete because its page was deleted.+struct FileDelete {+ path: String,+ /// The file must still hash to this right before the delete.+ expected_hash: String,}/// A page the plan refuses to touch; any of these blocks `--apply`.@@ -174,28 +269,79 @@ struct Refusal {struct Plan {imports: Vec<Import>,exports: Vec<Export>,+ server_deletes: Vec<ServerDelete>,+ file_deletes: Vec<FileDelete>,unchanged: Vec<String>,refused: Vec<Refusal>,+ /// A refusal of the whole batch (the delete ceiling).+ batch_refusal: Option<String>,notices: Vec<(String, &'static str)>,+ /// Pages that differ in a `--check` without state, where no base says+ /// which side changed.+ differs: Vec<String>,/// State to keep for pages this run leaves alone or adopts.adopted: BTreeMap<String, PageState>,forget: Vec<String>,}+impl Plan {+ fn outcome(&self) -> Outcome {+ Outcome {+ pending: self.imports.len()+ + self.exports.len()+ + self.server_deletes.len()+ + self.file_deletes.len()+ + self.notices.len()+ + self.differs.len(),+ blocked: !self.refused.is_empty() || self.batch_refusal.is_some(),+ }+ }++ fn deletes(&self) -> usize {+ self.server_deletes.len() + self.file_deletes.len()+ }+}++/// What applying a plan did besides succeeding.+#[derive(Default)]+struct Applied {+ wrote_files: bool,+ deleted_files: Vec<String>,+ /// Pages left alone because they changed after classification.+ raced: Vec<String>,+}+/// Entry point behind `sync`.-pub async fn run(args: &SyncArgs, apply: bool) -> Result<()> {+pub async fn run(args: &SyncArgs, mode: SyncMode) -> Result<Outcome> {let run_args = &args.run;let families = sync::validate_allowlist(&run_args.include)?;- let mode = if apply { Mode::Apply } else { Mode::DryRun };- let dest_root = sync::resolve_dest(&run_args.dest, mode)?;+ let fs_mode = if mode == SyncMode::Apply {+ Mode::Apply+ } else {+ Mode::DryRun+ };+ let dest_root = sync::resolve_dest(&run_args.dest, fs_mode)?;+ let stateless_check = mode == SyncMode::Check && !state::state_path(&dest_root).exists();let old_state = state::load(&dest_root)?;let api = ApiClient::new(&run_args.server, run_args.token.clone())?;- let plan = build_plan(&api, args, &families, &dest_root, &old_state).await?;- print_plan(run_args, &families, &plan, apply);+ let plan = build_plan(+ &api,+ args,+ &families,+ &dest_root,+ &old_state,+ stateless_check,+ )+ .await?;+ print_plan(run_args, &families, &plan, mode);+ let outcome = plan.outcome();- if !apply {- return Ok(());+ if mode != SyncMode::Apply {+ return Ok(outcome);+ }+ if let Some(reason) = &plan.batch_refusal {+ bail!("{reason}");}if !plan.refused.is_empty() {bail!(@@ -205,10 +351,44 @@ pub async fn run(args: &SyncArgs, apply: bool) -> Result<()> {);}let mcp = McpClient::new(&run_args.server, run_args.token.clone())?;- let wrote_files = apply_plan(&api, &mcp, run_args, &dest_root, &old_state, plan).await?;- if wrote_files {+ if !plan.imports.is_empty() || !plan.server_deletes.is_empty() {+ ensure_conditional_writes(&mcp, &plan).await?;+ }+ let applied = apply_plan(&api, &mcp, run_args, &dest_root, &old_state, plan).await?;+ if applied.wrote_files {sync::print_git_hints(run_args);}+ if !applied.deleted_files.is_empty() {+ print_git_rm_hint(run_args, &applied.deleted_files);+ }+ if !applied.raced.is_empty() {+ bail!(+ "{} page(s) changed during this run and were left for the next sync: {}",+ applied.raced.len(),+ applied.raced.join(", ")+ );+ }+ Ok(outcome)+}++/// Refuse to write through a server that would ignore the preconditions:+/// one without `expected_page_id` in its tool schema, or whose `/api/v1`+/// pages carry no version id to send.+async fn ensure_conditional_writes(mcp: &McpClient, plan: &Plan) -> Result<()> {+ let missing_id = plan+ .imports+ .iter()+ .any(|import| !import.create && import.expected_page_id.is_none())+ || plan+ .server_deletes+ .iter()+ .any(|delete| delete.expected_page_id.is_none());+ if missing_id {+ bail!("{}; nothing was written", mcp::server_too_old());+ }+ if let Err(error) = mcp.ensure_conditional_writes().await {+ bail!("{error:#}; nothing was written");+ }Ok(())}@@ -218,8 +398,13 @@ async fn build_plan(families: &[String],dest_root: &Path,old_state: &SyncState,+ stateless_check: bool,) -> Result<Plan> {let run_args = &args.run;+ let policy = Policy {+ prefer: args.prefer,+ propagate_deletes: args.propagate_deletes,+ };let mut plan = Plan::default();let listed = api.list_pages(&run_args.workspace, &run_args.project)@@ -229,6 +414,12 @@ async fn build_plan(.map(|page| page.path).collect();let in_repo = local_pages(dest_root, families, &mut plan.refused)?;+ // A symlink is refused once, by the walk, and never read or deleted.+ let refused_paths: BTreeSet<String> = plan+ .refused+ .iter()+ .map(|refusal| refusal.path.clone())+ .collect();let in_state = old_state.pages.keys()@@ -243,6 +434,7 @@ async fn build_plan(.cloned().chain(in_repo).chain(in_state)+ .filter(|path| !refused_paths.contains(path)).collect();if all.len() > MAX_PAGES {bail!(@@ -286,7 +478,7 @@ async fn build_plan((None, true) => ServerSide::NotModified,(None, false) => ServerSide::Absent,};- match decide(disk.as_deref(), base, server, args.prefer) {+ match decide(disk.as_deref(), base, server, policy) {Action::Unchanged => {if let Some(bytes) = &rendered {plan.adopted.insert(@@ -294,6 +486,7 @@ async fn build_plan(PageState {hash: state::sha256_hex(bytes.as_bytes()),etag,+ page_id: current.and_then(|page| page.id),},);}@@ -308,56 +501,103 @@ async fn build_plan(create,bytes,etag,+ page_id: current.and_then(|page| page.id),});}Action::Import { create } => {let disk = disk.unwrap_or_default();if !create && current.is_none() {// A 304 proved the server unchanged, but the import- // still needs the page's metadata keys and rendering.- let page = api- .read_page(&run_args.workspace, &run_args.project, &path, None)- .await?- .page- .with_context(|| {- format!("server returned 304 for {path} without an ETag")- })?;- current = Some(page);+ // still needs the page's metadata keys and version id.+ current = Some(full_page(api, run_args, &path).await?);}- plan_import(&mut plan, path, create, disk, current.as_ref())?;+ plan_import(&mut plan, path, create, disk, current.as_ref());}+ Action::Conflict if stateless_check && base.is_none() => plan.differs.push(path),Action::Conflict => {- let summary =- sync::diff_summary(disk.as_deref(), rendered.as_deref().map(str::as_bytes));+ let reason = match (&disk, &rendered) {+ (None, _) => "deleted in the repository and changed on the server since \+ the last sync"+ .to_string(),+ (Some(_), None) => "deleted on the server and changed in the repository \+ since the last sync"+ .to_string(),+ (Some(disk), Some(server)) => format!(+ "changed in the repository and on the server since the last sync ({})",+ sync::diff_summary(Some(disk), Some(server.as_bytes()))+ ),+ };plan.refused.push(Refusal {path,- reason: format!(- "changed in the repository and on the server since the last sync \- ({summary}); pass --prefer repo or --prefer server"- ),+ reason: format!("{reason}; pass --prefer repo or --prefer server"),+ });+ }+ Action::DeleteOnServer => {+ let page = match current {+ Some(page) => page,+ None => full_page(api, run_args, &path).await?,+ };+ if page.pinned && args.prefer != Some(Prefer::Repo) {+ plan.refused.push(Refusal {+ path,+ reason: "deleted in the repository, but the server page is pinned; \+ pass --prefer repo to delete it anyway"+ .to_string(),+ });+ } else {+ plan.server_deletes.push(ServerDelete {+ path,+ expected_page_id: page.id,+ });+ }+ }+ Action::DeleteInRepo => {+ let Some(disk) = disk else {+ bail!("cannot delete {path}: the file is already gone");+ };+ plan.file_deletes.push(FileDelete {+ path,+ expected_hash: state::sha256_hex(&disk),});}Action::DeletedOnServer => plan.notices.push((path,- "deleted on the server; the file is kept (deletes are not synced yet)",+ "deleted on the server; the file is kept (pass --propagate-deletes to delete it)",)),Action::DeletedInRepo => plan.notices.push((path,- "deleted in the repository; the server page is kept (deletes are not synced yet)",+ "deleted in the repository; the server page is kept (pass --propagate-deletes \+ to delete it)",)),Action::GoneOnBothSides => plan.forget.push(path),}}+ let deletes = plan.deletes();+ if deletes > args.max_deletes {+ plan.batch_refusal = Some(format!(+ "{deletes} deletes exceed --max-deletes {}; nothing was written. Check the deletes \+ above, then raise --max-deletes if they are intended",+ args.max_deletes+ ));+ }Ok(plan)}+/// The full page, for a decision a `304` cannot settle.+async fn full_page(api: &ApiClient, args: &RunArgs, path: &str) -> Result<ApiPage> {+ api.read_page(&args.workspace, &args.project, path, None)+ .await?+ .page+ .with_context(|| format!("server returned 304 for {path} without an ETag"))+}+fn plan_import(plan: &mut Plan,path: String,create: bool,disk: Vec<u8>,current: Option<&ApiPage>,-) -> Result<()> {+) {let (meta, body) = match page_file::parse(&disk) {Ok(parsed) => parsed,Err(error) => {@@ -365,36 +605,31 @@ fn plan_import(path,reason: format!("cannot import: {error:#}"),});- return Ok(());+ return;}};- let expected_server = match current {- Some(page) => {- let lost = keys_an_import_would_clear(&page.frontmatter);- if !lost.is_empty() {- plan.refused.push(Refusal {- path,- reason: format!(- "cannot import: the server page carries metadata a write would clear \- ({}); edit it through ai-memory instead",- lost.join(", ")- ),- });- return Ok(());- }- Some(state::sha256_hex(sync::render_page(page)?.as_bytes()))+ if let Some(page) = current {+ let lost = keys_an_import_would_clear(&page.frontmatter);+ if !lost.is_empty() {+ plan.refused.push(Refusal {+ path,+ reason: format!(+ "cannot import: the server page carries metadata a write would clear \+ ({}); edit it through ai-memory instead",+ lost.join(", ")+ ),+ });+ return;}- None => None,- };+ }plan.imports.push(Import {path,create,meta,body,disk,- expected_server,+ expected_page_id: current.and_then(|page| page.id.clone()),});- Ok(())}/// Every `.md` file under the allowlisted families. A symlink or a path the@@ -462,8 +697,10 @@ fn local_pages(Ok(found)}-/// Perform the imports, then the exports, then save the state once. The-/// state is also saved when an import fails partway, so the pages already+/// Perform the imports, the exports, the server deletes, then the file+/// deletes, and save the state once. A page whose precondition no longer+/// holds is reported and skipped, keeping its old state entry; any other+/// failure stops the run, saving the state first so the pages already/// written are not re-classified as conflicts on the next run.async fn apply_plan(api: &ApiClient,@@ -472,23 +709,31 @@ async fn apply_plan(dest_root: &Path,old_state: &SyncState,plan: Plan,-) -> Result<bool> {+) -> Result<Applied> {let mut new_state = old_state.clone();new_state.pages.extend(plan.adopted);for path in &plan.forget {new_state.pages.remove(path);}- let mut wrote_files = false;+ let mut applied = Applied::default();+ let scope = Scope {+ workspace: &args.workspace,+ project: &args.project,+ };for import in &plan.imports {- match import_one(api, mcp, args, dest_root, import).await {+ match import_one(api, mcp, &scope, dest_root, import).await {Ok((entry, normalised)) => {- wrote_files |= normalised;+ applied.wrote_files |= normalised;new_state.pages.insert(import.path.clone(), entry);}+ Err(error) if error.is::<PreconditionFailed>() => {+ report_race(&import.path, &error);+ applied.raced.push(import.path.clone());+ }Err(error) => {state::save(dest_root, &new_state)?;return Err(error.context(format!(- "import of {} failed; the pages imported before it are recorded",+ "import of {} failed; the pages synced before it are recorded",import.path)));}@@ -496,60 +741,118 @@ async fn apply_plan(}for export in &plan.exports {sync::atomic_write(dest_root, &export.path, export.bytes.as_bytes())?;- wrote_files = true;+ applied.wrote_files = true;new_state.pages.insert(export.path.clone(),PageState {hash: state::sha256_hex(export.bytes.as_bytes()),etag: export.etag.clone(),+ page_id: export.page_id.clone(),},);}+ for delete in &plan.server_deletes {+ let result = match &delete.expected_page_id {+ Some(expected) => mcp.delete_page(&scope, &delete.path, expected).await,+ None => Err(anyhow::anyhow!(mcp::server_too_old())),+ };+ match result {+ Ok(()) => {+ new_state.pages.remove(&delete.path);+ }+ Err(error) if error.is::<PreconditionFailed>() => {+ report_race(&delete.path, &error);+ applied.raced.push(delete.path.clone());+ }+ Err(error) => {+ state::save(dest_root, &new_state)?;+ return Err(error.context(format!(+ "delete of server page {} failed; the pages synced before it are recorded",+ delete.path+ )));+ }+ }+ }+ for delete in &plan.file_deletes {+ match delete_file(dest_root, delete) {+ Ok(true) => {+ new_state.pages.remove(&delete.path);+ applied.deleted_files.push(delete.path.clone());+ }+ Ok(false) => {+ println!(+ " {:<9} {} — changed in the repository during this run; left for the next sync",+ "CHANGED", delete.path+ );+ applied.raced.push(delete.path.clone());+ }+ Err(error) => {+ state::save(dest_root, &new_state)?;+ return Err(error.context(format!(+ "delete of {} failed; the pages synced before it are recorded",+ delete.path+ )));+ }+ }+ }state::save(dest_root, &new_state)?;- Ok(wrote_files)+ Ok(applied)+}++fn report_race(path: &str, error: &anyhow::Error) {+ println!(+ " {:<9} {path} — {error}; left for the next sync",+ "CHANGED"+ );+}++/// Delete one repository file through the same confinement as every write:+/// a validated path, no symlinked component, a regular file. The file must+/// still be the bytes the plan classified; returns `false` when it is not.+fn delete_file(dest_root: &Path, delete: &FileDelete) -> Result<bool> {+ let target = paths::secure_join(dest_root, &delete.path)?;+ let meta = fs::symlink_metadata(&target)+ .with_context(|| format!("cannot inspect {}", target.display()))?;+ if !meta.is_file() {+ bail!(+ "{} is not a regular file; refusing to delete it",+ target.display()+ );+ }+ let bytes = fs::read(&target).with_context(|| format!("cannot read {}", target.display()))?;+ if state::sha256_hex(&bytes) != delete.expected_hash {+ return Ok(false);+ }+ fs::remove_file(&target).with_context(|| format!("cannot delete {}", target.display()))?;+ Ok(true)}-/// Re-check, write, read back. Returns the new state entry and whether the-/// file was rewritten because the server stored something other than the-/// file's bytes (the sanitizer redacting a secret, for example).+/// Write, then read back. Returns the new state entry and whether the file+/// was rewritten because the server stored something other than the file's+/// bytes (the sanitizer redacting a secret, for example).async fn import_one(api: &ApiClient,mcp: &McpClient,- args: &RunArgs,+ scope: &Scope<'_>,dest_root: &Path,import: &Import,) -> Result<(PageState, bool)> {- let now = api- .read_page_if_exists(&args.workspace, &args.project, &import.path)+ let precondition = match (&import.expected_page_id, import.create) {+ (_, true) => Precondition::Absent,+ (Some(expected), false) => Precondition::Latest(expected),+ (None, false) => bail!(mcp::server_too_old()),+ };+ let written = mcp+ .write_page(+ scope,+ &import.path,+ &import.meta,+ &import.body,+ precondition,+ ).await?;- match (&now, &import.expected_server) {- (Some(_), None) => bail!("{} was created on the server during this run", import.path),- (None, Some(_)) => bail!("{} was deleted on the server during this run", import.path),- (Some(page), Some(expected)) => {- if state::sha256_hex(sync::render_page(page)?.as_bytes()) != *expected {- bail!("{} changed on the server during this run", import.path);- }- let lost = keys_an_import_would_clear(&page.frontmatter);- if !lost.is_empty() {- bail!(- "{} gained metadata a write would clear during this run ({})",- import.path,- lost.join(", ")- );- }- }- (None, None) => {}- }- mcp.write_page(- &args.workspace,- &args.project,- &import.path,- &import.meta,- &import.body,- )- .await?;let read = api- .read_page(&args.workspace, &args.project, &import.path, None)+ .read_page(scope.workspace, scope.project, &import.path, None).await?;let page = read.page.with_context(|| {format!(@@ -557,6 +860,19 @@ async fn import_one(import.path)})?;+ if written.is_some() && page.id != written {+ // Another write landed between ours and this read. Record the file+ // as what this run wrote, so the next run exports the newer version+ // instead of mistaking it for this import's rendering.+ return Ok((+ PageState {+ hash: state::sha256_hex(&import.disk),+ etag: None,+ page_id: written,+ },+ false,+ ));+ }let rendered = sync::render_page(&page)?;let normalised = rendered.as_bytes() != import.disk.as_slice();if normalised {@@ -566,12 +882,26 @@ async fn import_one(PageState {hash: state::sha256_hex(rendered.as_bytes()),etag: read.etag,+ page_id: page.id.or(written),},normalised,))}-fn print_plan(args: &RunArgs, families: &[String], plan: &Plan, apply: bool) {+fn print_git_rm_hint(args: &RunArgs, deleted: &[String]) {+ let dest = args.dest.display();+ let files: Vec<String> = deleted+ .iter()+ .map(|path| format!("{dest}/{path}"))+ .collect();+ println!(+ "this tool never runs git; to commit the deletes you may run:\+ \n git rm --quiet --ignore-unmatch -- {}",+ files.join(" ")+ );+}++fn print_plan(args: &RunArgs, families: &[String], plan: &Plan, mode: SyncMode) {println!("ai-memory-wikisync sync: {}/{} <-> {}",args.workspace,@@ -587,25 +917,56 @@ fn print_plan(args: &RunArgs, families: &[String], plan: &Plan, apply: bool) {let kind = if export.create { "create" } else { "update" };println!(" {:<9} {} (server -> repo, {kind})", "export", export.path);}+ for delete in &plan.server_deletes {+ println!(+ " {:<9} {} (server page; deleted in the repository)",+ "delete", delete.path+ );+ }+ for delete in &plan.file_deletes {+ println!(+ " {:<9} {} (repository file; deleted on the server)",+ "delete", delete.path+ );+ }for path in &plan.unchanged {println!(" {:<9} {path}", "unchanged");}+ for path in &plan.differs {+ println!(+ " {:<9} {path} (no sync state to say which side changed)",+ "differs"+ );+ }for (path, notice) in &plan.notices {println!(" {:<9} {path} — {notice}", "notice");}for refusal in &plan.refused {println!(" {:<9} {} — {}", "REFUSED", refusal.path, refusal.reason);}+ if let Some(reason) = &plan.batch_refusal {+ println!(" {:<9} {reason}", "REFUSED");+ }println!(- " sync: {} import, {} export, {} unchanged, {} notice, {} refused",+ " sync: {} import, {} export, {} delete, {} unchanged, {} notice, {} refused",plan.imports.len(),plan.exports.len(),+ plan.deletes(),plan.unchanged.len(),plan.notices.len(),- plan.refused.len()+ plan.refused.len() + usize::from(plan.batch_refusal.is_some()));- if !apply {- println!(" dry run: nothing was written (pass --apply to sync)");+ match mode {+ SyncMode::DryRun => println!(" dry run: nothing was written (pass --apply to sync)"),+ SyncMode::Check => {+ let verdict = match plan.outcome().status() {+ CheckStatus::InSync => "in sync",+ CheckStatus::Drift => "drift: changes are pending",+ CheckStatus::Blocked => "blocked: conflicts or refusals need a decision",+ };+ println!(" check: {verdict} (nothing was written)");+ }+ SyncMode::Apply => {}}}@@ -618,37 +979,48 @@ mod tests {PageState {hash: state::sha256_hex(bytes),etag: Some("\"e\"".to_string()),+ page_id: Some("v1".to_string()),+ }+ }++ fn policy(prefer: Option<Prefer>, propagate_deletes: bool) -> Policy {+ Policy {+ prefer,+ propagate_deletes,}}+ const PREFERENCES: [Option<Prefer>; 3] = [None, Some(Prefer::Repo), Some(Prefer::Server)];+#[test]fn decide_three_way_matrix() {let old = b"old".as_slice();let repo = b"repo edit".as_slice();let server = b"server edit".as_slice();let rendered = ServerSide::Rendered;+ let none = Policy::default();// One side changed: the other side follows.assert_eq!(- decide(Some(old), Some(&base(old)), rendered(server), None),+ decide(Some(old), Some(&base(old)), rendered(server), none),Action::Export { create: false });assert_eq!(- decide(Some(repo), Some(&base(old)), rendered(old), None),+ decide(Some(repo), Some(&base(old)), rendered(old), none),Action::Import { create: false });assert_eq!(- decide(Some(repo), Some(&base(old)), ServerSide::NotModified, None),+ decide(Some(repo), Some(&base(old)), ServerSide::NotModified, none),Action::Import { create: false });assert_eq!(- decide(Some(old), Some(&base(old)), ServerSide::NotModified, None),+ decide(Some(old), Some(&base(old)), ServerSide::NotModified, none),Action::Unchanged);// Both changed: a conflict, unless --prefer picks a side.assert_eq!(- decide(Some(repo), Some(&base(old)), rendered(server), None),+ decide(Some(repo), Some(&base(old)), rendered(server), none),Action::Conflict);assert_eq!(@@ -656,7 +1028,7 @@ mod tests {Some(repo),Some(&base(old)),rendered(server),- Some(Prefer::Repo)+ policy(Some(Prefer::Repo), false)),Action::Import { create: false });@@ -665,56 +1037,143 @@ mod tests {Some(repo),Some(&base(old)),rendered(server),- Some(Prefer::Server)+ policy(Some(Prefer::Server), false)),Action::Export { create: false });// Both changed to the same bytes: nothing to do.assert_eq!(- decide(Some(server), Some(&base(old)), rendered(server), None),+ decide(Some(server), Some(&base(old)), rendered(server), none),Action::Unchanged);// A file with no base that differs from the server is a conflict// too: nothing says which side is newer.assert_eq!(- decide(Some(repo), None, rendered(server), None),+ decide(Some(repo), None, rendered(server), none),Action::Conflict);assert_eq!(- decide(Some(server), None, rendered(server), None),+ decide(Some(server), None, rendered(server), none),Action::Unchanged);// Creates come from whichever side has the page.assert_eq!(- decide(None, None, rendered(server), None),+ decide(None, None, rendered(server), none),Action::Export { create: true });assert_eq!(- decide(Some(repo), None, ServerSide::Absent, None),+ decide(Some(repo), None, ServerSide::Absent, none),Action::Import { create: true });+ }- // Deletes are reported, never propagated, whatever --prefer says.- for prefer in [None, Some(Prefer::Repo), Some(Prefer::Server)] {+ #[test]+ fn deletes_are_only_reported_without_the_flag() {+ let old = b"old".as_slice();+ let repo = b"repo edit".as_slice();+ let server = b"server edit".as_slice();+ for prefer in PREFERENCES {+ let off = policy(prefer, false);+ for disk in [old, repo] {+ assert_eq!(+ decide(Some(disk), Some(&base(old)), ServerSide::Absent, off),+ Action::DeletedOnServer+ );+ }+ for server in [old, server] {+ assert_eq!(+ decide(None, Some(&base(old)), ServerSide::Rendered(server), off),+ Action::DeletedInRepo+ );+ }+ assert_eq!(+ decide(None, Some(&base(old)), ServerSide::NotModified, off),+ Action::DeletedInRepo+ );assert_eq!(- decide(Some(old), Some(&base(old)), ServerSide::Absent, prefer),- Action::DeletedOnServer+ decide(None, Some(&base(old)), ServerSide::Absent, off),+ Action::GoneOnBothSides);+ }+ }++ #[test]+ fn deletes_propagate_only_from_an_unchanged_side() {+ let old = b"old".as_slice();+ let repo = b"repo edit".as_slice();+ let server = b"server edit".as_slice();+ for prefer in PREFERENCES {+ let on = policy(prefer, true);+ // The other side is unchanged since the last sync: delete it,+ // whatever --prefer says.assert_eq!(- decide(None, Some(&base(old)), rendered(server), prefer),- Action::DeletedInRepo+ decide(None, Some(&base(old)), ServerSide::Rendered(old), on),+ Action::DeleteOnServer);assert_eq!(- decide(None, Some(&base(old)), ServerSide::NotModified, prefer),- Action::DeletedInRepo+ decide(None, Some(&base(old)), ServerSide::NotModified, on),+ Action::DeleteOnServer);assert_eq!(- decide(None, Some(&base(old)), ServerSide::Absent, prefer),+ decide(Some(old), Some(&base(old)), ServerSide::Absent, on),+ Action::DeleteInRepo+ );+ assert_eq!(+ decide(None, Some(&base(old)), ServerSide::Absent, on),Action::GoneOnBothSides);+ // Never synced: nothing was deleted, the page is new.+ assert_eq!(+ decide(Some(repo), None, ServerSide::Absent, on),+ Action::Import { create: true }+ );+ assert_eq!(+ decide(None, None, ServerSide::Rendered(server), on),+ Action::Export { create: true }+ );}++ // Deleted on one side, changed on the other: a conflict until a+ // side is preferred.+ let repo_deleted = |prefer| {+ decide(+ None,+ Some(&base(old)),+ ServerSide::Rendered(server),+ policy(prefer, true),+ )+ };+ assert_eq!(repo_deleted(None), Action::Conflict);+ assert_eq!(repo_deleted(Some(Prefer::Repo)), Action::DeleteOnServer);+ assert_eq!(+ repo_deleted(Some(Prefer::Server)),+ Action::Export { create: true }+ );+ let server_deleted = |prefer| {+ decide(+ Some(repo),+ Some(&base(old)),+ ServerSide::Absent,+ policy(prefer, true),+ )+ };+ assert_eq!(server_deleted(None), Action::Conflict);+ assert_eq!(+ server_deleted(Some(Prefer::Repo)),+ Action::Import { create: true }+ );+ assert_eq!(server_deleted(Some(Prefer::Server)), Action::DeleteInRepo);+ }++ #[test]+ fn check_status_ranks_refusals_over_drift() {+ let outcome = |pending, blocked| Outcome { pending, blocked }.status();+ assert_eq!(outcome(0, false), CheckStatus::InSync);+ assert_eq!(outcome(2, false), CheckStatus::Drift);+ assert_eq!(outcome(0, true), CheckStatus::Blocked);+ assert_eq!(outcome(2, true), CheckStatus::Blocked);}#[test]diff --git a/companions/ai-memory-wikisync/src/client.rs b/companions/ai-memory-wikisync/src/client.rsindex 4099ed4e..1f134c81 100644--- a/companions/ai-memory-wikisync/src/client.rs+++ b/companions/ai-memory-wikisync/src/client.rs@@ -43,6 +43,10 @@ pub struct PageSummary {/// locally.#[derive(Debug, Clone, Deserialize)]pub struct ApiPage {+ /// Latest version id, the token a conditional MCP write or delete+ /// passes back. Servers older than 2.7 do not send it.+ #[serde(default)]+ pub id: Option<String>,pub path: String,pub body_markdown: String,#[serde(default)]@@ -159,46 +163,6 @@ impl ApiClient {check_status(response, url, not_found_hint)}- /// Read one full page, or `None` when the server has no such page. Used- /// right before an import, where absence is an answer, not an error.- pub async fn read_page_if_exists(- &self,- workspace: &str,- project: &str,- path: &str,- ) -> Result<Option<ApiPage>> {- let tail: Vec<&str> = path.split('/').collect();- let url = self.build_page_url(workspace, project, &tail)?;- let mut request = self- .http- .get(url.clone())- .header(reqwest::header::ACCEPT, "application/json");- if let Some(token) = &self.token {- request = request.bearer_auth(token);- }- let response = request- .send()- .await- .map_err(|e| anyhow!("request to {} failed: {e}", url.as_str()))?;- if response.status() == StatusCode::NOT_FOUND {- return Ok(None);- }- let response = check_status(response, &url, "")?;- let page: ApiPage = response.json().await.map_err(|e| {- anyhow!(- "page read from {} returned malformed JSON: {e}",- url.as_str()- )- })?;- if page.path != path {- bail!(- "server answered a read of {path:?} with page {:?}; refusing the mismatch",- page.path- );- }- Ok(Some(page))- }-/// List the project's latest pages via incremental `recent` paging from/// the epoch. Incremental results already exclude superseded and expired/// pages, which is exactly the latest-only projection an export wants.diff --git a/companions/ai-memory-wikisync/src/lib.rs b/companions/ai-memory-wikisync/src/lib.rsindex edca1785..6805d234 100644--- a/companions/ai-memory-wikisync/src/lib.rs+++ b/companions/ai-memory-wikisync/src/lib.rs@@ -1,11 +1,12 @@-//! `ai-memory-wikisync`: team-wiki sync companion (#986, slices 1 and 3).+//! `ai-memory-wikisync`: team-wiki sync companion (#986, slices 1, 3 and 4).//!//! Keeps explicitly allowlisted page families of a running ai-memory server//! in step with a directory inside a project repository. Reads go through-//! the public, read-only `/api/v1` surface; the only write to the server is-//! the public `memory_write_page` MCP tool, used by `sync`. The tool never-//! opens the wiki directory or SQLite, never deletes (deletes are slice 4),-//! and never runs git on the operator's behalf.+//! the public, read-only `/api/v1` surface; the only writes to the server are+//! the public `memory_write_page` and `memory_delete_page` MCP tools, used by+//! `sync` with a version precondition on every call. The tool never opens+//! the wiki directory or SQLite, deletes nothing unless `--propagate-deletes`+//! asks for it, and never runs git on the operator's behalf.//!//! Page bodies are untrusted data: they are transported verbatim into files//! whose validated paths cannot escape the destination directory, and arediff --git a/companions/ai-memory-wikisync/src/main.rs b/companions/ai-memory-wikisync/src/main.rsindex d0ade109..34e9d3bd 100644--- a/companions/ai-memory-wikisync/src/main.rs+++ b/companions/ai-memory-wikisync/src/main.rs@@ -2,7 +2,7 @@use std::path::PathBuf;-use ai_memory_wikisync::bidi::{self, Prefer, SyncArgs};+use ai_memory_wikisync::bidi::{self, DEFAULT_MAX_DELETES, Prefer, SyncArgs, SyncMode};use ai_memory_wikisync::client::DEFAULT_SERVER_URL;use ai_memory_wikisync::sync::{Mode, RunArgs, run};use clap::{Parser, Subcommand, ValueEnum};@@ -39,6 +39,16 @@ struct SyncCliArgs {/// Without it, such a page is a conflict and nothing is written.#[arg(long, value_enum)]prefer: Option<PreferArg>,+ /// Propagate deletes: a file deleted in the repository deletes its+ /// server page, a page deleted on the server deletes its file, as long+ /// as the other side is unchanged since the last sync. Without it,+ /// deletes are only reported.+ #[arg(long)]+ propagate_deletes: bool,+ /// Refuse the whole run when it would delete more than this many pages+ /// and files.+ #[arg(long, value_name = "N", default_value_t = DEFAULT_MAX_DELETES)]+ max_deletes: usize,#[command(flatten)]common: CommonArgs,}@@ -120,6 +130,8 @@ impl From<SyncCliArgs> for SyncArgs {PreferArg::Repo => Prefer::Repo,PreferArg::Server => Prefer::Server,}),+ propagate_deletes: args.propagate_deletes,+ max_deletes: args.max_deletes,}}}@@ -138,8 +150,12 @@ async fn main() -> anyhow::Result<()> {run(&RunArgs::from(args), mode).await}Commands::Sync(args) => {- let apply = args.apply;- bidi::run(&SyncArgs::from(args), apply).await+ let mode = if args.apply {+ SyncMode::Apply+ } else {+ SyncMode::DryRun+ };+ bidi::run(&SyncArgs::from(args), mode).await.map(|_| ())}}}diff --git a/companions/ai-memory-wikisync/src/mcp.rs b/companions/ai-memory-wikisync/src/mcp.rsindex 870ef797..9b19a7e1 100644--- a/companions/ai-memory-wikisync/src/mcp.rs+++ b/companions/ai-memory-wikisync/src/mcp.rs@@ -1,10 +1,16 @@-//! The only write seam: the public `memory_write_page` MCP tool.+//! The only write seam: the public `memory_write_page` and+//! `memory_delete_page` MCP tools.//!-//! Imports never touch the wiki directory or SQLite. They call the same tool-//! an agent calls, so sanitization, admission, attribution and scope-//! resolution all apply. The request carries `workspace` and `project`+//! Imports and deletes never touch the wiki directory or SQLite. They call+//! the same tools an agent calls, so sanitization, admission, attribution and+//! scope resolution all apply. The request carries `workspace` and `project`//! explicitly on every call; this companion has no session to route by.+//!+//! Every write and delete is conditional (`expected_page_id` or+//! `create_only`), so a page that changed after the sync classified it is+//! refused by the server instead of overwritten.+use std::fmt;use std::time::Duration;use anyhow::{Result, anyhow, bail};@@ -16,6 +22,62 @@ use crate::page_file::PageMeta;const REQUEST_TIMEOUT: Duration = Duration::from_secs(30);/// Bound on a tool error echoed to the terminal.const ERROR_PREVIEW: usize = 300;+/// JSON-RPC `invalid_request`, the code a failed precondition carries.+const INVALID_REQUEST: i64 = -32600;+/// The server release that added conditional writes and deletes.+const MIN_SERVER: &str = "2.7";++/// What a conditional write requires of the server's current page.+#[derive(Debug, Clone, Copy, PartialEq, Eq)]+pub enum Precondition<'a> {+ /// The page's latest version must still be this id.+ Latest(&'a str),+ /// No page may exist at the path.+ Absent,+}++/// The server refused a conditional write or delete because the page is no+/// longer the version the sync classified; nothing was changed.+#[derive(Debug, Clone, PartialEq, Eq)]+pub struct PreconditionFailed {+ pub path: String,+ pub expected_page_id: Option<String>,+ pub current_page_id: Option<String>,+}++impl fmt::Display for PreconditionFailed {+ fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {+ write!(+ f,+ "{} changed on the server during this run (expected version {}, now {})",+ preview(&self.path),+ self.expected_page_id+ .as_deref()+ .map_or("none".into(), preview),+ self.current_page_id+ .as_deref()+ .map_or("none".into(), preview),+ )+ }+}++impl std::error::Error for PreconditionFailed {}++/// The typed precondition failure in a JSON-RPC error, if that is what it is.+fn precondition_failure(error: &Value) -> Option<PreconditionFailed> {+ let data = error.get("data")?;+ if error.get("code").and_then(Value::as_i64) != Some(INVALID_REQUEST)+ || data.get("reason").and_then(Value::as_str) != Some("precondition_failed")+ {+ return None;+ }+ let text = |key: &str| data.get(key).and_then(Value::as_str).map(str::to_owned);+ Some(PreconditionFailed {+ path: text("path").unwrap_or_default(),+ expected_page_id: text("expected_page_id"),+ current_page_id: text("current_page_id"),+ })+}pub struct McpClient {http: reqwest::Client,@@ -36,20 +98,40 @@ impl McpClient {Ok(Self { http, url, token })}- /// Replace (or create) one page with exactly `meta` and `body`. The- /// tool clears whatever the call omits, which is why every field the- /// file carries is sent, defaults included.+ /// Refuse a server that predates conditional writes. It would accept+ /// `expected_page_id` as an unknown argument and ignore it, turning every+ /// guarded write into an unconditional one.+ pub async fn ensure_conditional_writes(&self) -> Result<()> {+ let result = self.request("tools/list", json!({})).await?;+ let supported = result+ .get("tools")+ .and_then(Value::as_array)+ .into_iter()+ .flatten()+ .find(|tool| tool.get("name").and_then(Value::as_str) == Some("memory_write_page"))+ .and_then(|tool| tool.pointer("/inputSchema/properties/expected_page_id"))+ .is_some();+ if !supported {+ bail!(server_too_old());+ }+ Ok(())+ }++ /// Replace (or create) one page with exactly `meta` and `body`, only if+ /// `precondition` still holds. The tool clears whatever the call omits,+ /// which is why every field the file carries is sent, defaults included.+ /// Returns the new version id.pub async fn write_page(&self,- workspace: &str,- project: &str,+ scope: &Scope<'_>,path: &str,meta: &PageMeta,body: &str,- ) -> Result<()> {+ precondition: Precondition<'_>,+ ) -> Result<Option<String>> {let mut arguments = json!({- "workspace": workspace,- "project": project,+ "workspace": scope.workspace,+ "project": scope.project,"path": path,"body": body,"tags": meta.tags,@@ -61,15 +143,57 @@ impl McpClient {if let Some(tier) = &meta.tier {arguments["tier"] = json!(tier);}- self.call_tool("memory_write_page", arguments).await+ match precondition {+ Precondition::Latest(id) => arguments["expected_page_id"] = json!(id),+ Precondition::Absent => arguments["create_only"] = json!(true),+ }+ let result = self.call_tool("memory_write_page", arguments).await?;+ Ok(tool_json(&result)+ .and_then(|written| written.get("page_id")?.as_str().map(str::to_owned)))+ }++ /// Delete one page, only if its latest version is still `expected_page_id`.+ pub async fn delete_page(+ &self,+ scope: &Scope<'_>,+ path: &str,+ expected_page_id: &str,+ ) -> Result<()> {+ let arguments = json!({+ "workspace": scope.workspace,+ "project": scope.project,+ "path": path,+ "expected_page_id": expected_page_id,+ });+ self.call_tool("memory_delete_page", arguments).await?;+ Ok(())+ }++ async fn call_tool(&self, name: &str, arguments: Value) -> Result<Value> {+ let result = self+ .request("tools/call", json!({"name": name, "arguments": arguments}))+ .await+ .map_err(|error| match error.downcast::<PreconditionFailed>() {+ Ok(failed) => anyhow::Error::new(failed),+ Err(error) => error.context(format!("MCP {name} failed")),+ })?;+ if result.get("isError").and_then(Value::as_bool) == Some(true) {+ let detail = result+ .pointer("/content/0/text")+ .and_then(Value::as_str)+ .unwrap_or("no detail");+ bail!("MCP {name} refused the call: {}", preview(detail));+ }+ Ok(result)}- async fn call_tool(&self, name: &str, arguments: Value) -> Result<()> {+ /// One JSON-RPC request; its `result`, or the error it answered with.+ async fn request(&self, method: &str, params: Value) -> Result<Value> {let request = json!({"jsonrpc": "2.0","id": 1,- "method": "tools/call",- "params": {"name": name, "arguments": arguments},+ "method": method,+ "params": params,});let mut builder = self.http@@ -88,34 +212,51 @@ impl McpClient {let response = builder.send().await- .map_err(|e| anyhow!("MCP {name} request to {} failed: {e}", self.url))?;+ .map_err(|e| anyhow!("MCP {method} request to {} failed: {e}", self.url))?;let status = response.status();let text = response.text().await- .map_err(|e| anyhow!("reading the MCP {name} response failed: {e}"))?;+ .map_err(|e| anyhow!("reading the MCP {method} response failed: {e}"))?;if !status.is_success() {- bail!("MCP {name} returned HTTP {status}: {}", preview(&text));+ bail!("MCP {method} returned HTTP {status}: {}", preview(&text));}- let message = json_rpc_message(&text)- .ok_or_else(|| anyhow!("MCP {name} answered with no JSON-RPC message"))?;+ let mut message = json_rpc_message(&text)+ .ok_or_else(|| anyhow!("MCP {method} answered with no JSON-RPC message"))?;if let Some(error) = message.get("error") {- bail!("MCP {name} failed: {}", preview(&error.to_string()));- }- let result = message- .get("result")- .ok_or_else(|| anyhow!("MCP {name} answered with no result"))?;- if result.get("isError").and_then(Value::as_bool) == Some(true) {- let detail = result- .pointer("/content/0/text")- .and_then(Value::as_str)- .unwrap_or("no detail");- bail!("MCP {name} refused the write: {}", preview(detail));+ if let Some(failed) = precondition_failure(error) {+ return Err(anyhow::Error::new(failed));+ }+ bail!("MCP {method} failed: {}", preview(&error.to_string()));}- Ok(())+ message+ .get_mut("result")+ .map(Value::take)+ .ok_or_else(|| anyhow!("MCP {method} answered with no result"))}}+/// The explicit scope every call carries.+#[derive(Debug, Clone, Copy)]+pub struct Scope<'a> {+ pub workspace: &'a str,+ pub project: &'a str,+}++/// The refusal for a server without conditional writes.+pub fn server_too_old() -> String {+ format!(+ "server too old for sync --apply; needs ai-memory >= {MIN_SERVER} (conditional \+ page writes)"+ )+}++/// The JSON a tool returned as its first text content, if any.+fn tool_json(result: &Value) -> Option<Value> {+ let text = result.pointer("/content/0/text")?.as_str()?;+ serde_json::from_str(text).ok()+}+/// The JSON-RPC message in a response body: the body itself, or the last/// `data:` frame of an SSE stream.fn json_rpc_message(text: &str) -> Option<Value> {@@ -150,6 +291,33 @@ mod tests {assert!(json_rpc_message("event: ping\n\n").is_none());}+ #[test]+ fn precondition_errors_are_typed() {+ let error = json!({+ "code": -32600,+ "message": "precondition failed",+ "data": {+ "reason": "precondition_failed",+ "path": "notes/a.md",+ "expected_page_id": "v1",+ "current_page_id": null,+ },+ });+ assert_eq!(+ precondition_failure(&error),+ Some(PreconditionFailed {+ path: "notes/a.md".into(),+ expected_page_id: Some("v1".into()),+ current_page_id: None,+ })+ );+ let other_reason = json!({"code": -32600, "data": {"reason": "nope"}});+ assert_eq!(precondition_failure(&other_reason), None);+ let other_code = json!({"code": -32602, "data": {"reason": "precondition_failed"}});+ assert_eq!(precondition_failure(&other_code), None);+ assert_eq!(precondition_failure(&json!({"code": -32600})), None);+ }+#[test]fn previews_are_bounded_and_inert() {let hostile = format!("\u{1b}[31m{}", "x".repeat(1_000));diff --git a/companions/ai-memory-wikisync/src/state.rs b/companions/ai-memory-wikisync/src/state.rsindex e8fb85e8..3b685230 100644--- a/companions/ai-memory-wikisync/src/state.rs+++ b/companions/ai-memory-wikisync/src/state.rs@@ -50,6 +50,10 @@ pub struct PageState {/// Server ETag captured at that write, for `If-None-Match` revalidation.#[serde(default, skip_serializing_if = "Option::is_none")]pub etag: Option<String>,+ /// Server version id (`/api/v1` `id`) at that write. Absent in state+ /// written before conditional writes existed, which still loads.+ #[serde(default, skip_serializing_if = "Option::is_none")]+ pub page_id: Option<String>,}/// The whole state file. `version` guards against silently misreading a@@ -193,6 +197,7 @@ mod tests {PageState {hash: hash.to_string(),etag: etag.map(str::to_owned),+ page_id: None,}}@@ -220,6 +225,25 @@ mod tests {);}+ #[test]+ fn state_without_page_ids_still_loads() {+ let tmp = tempfile::tempdir().unwrap();+ let root = tmp.path().canonicalize().unwrap();+ fs::create_dir_all(root.join(STATE_DIR)).unwrap();+ fs::write(+ state_path(&root),+ r#"{"version":1,"pages":{"notes/a.md":{"hash":"h","etag":"\"e\""}}}"#,+ )+ .unwrap();+ let state = load(&root).unwrap();+ assert_eq!(state.pages["notes/a.md"].page_id, None);++ let mut with_id = state.clone();+ with_id.pages.get_mut("notes/a.md").unwrap().page_id = Some("v1".to_string());+ save(&root, &with_id).unwrap();+ assert_eq!(load(&root).unwrap(), with_id);+ }+#[test]fn state_file_is_owner_only_on_unix() {let tmp = tempfile::tempdir().unwrap();diff --git a/companions/ai-memory-wikisync/src/sync.rs b/companions/ai-memory-wikisync/src/sync.rsindex e0a1b479..c8ff3ace 100644--- a/companions/ai-memory-wikisync/src/sync.rs+++ b/companions/ai-memory-wikisync/src/sync.rs@@ -351,6 +351,7 @@ async fn run_batch(.read_page(&args.workspace, &args.project, &page.path, etag_hint).await?;let mut body = read.page.as_ref().map(render_page).transpose()?;+ let mut page_id = read.page.as_ref().and_then(|page| page.id.clone());let mut decision = classify(disk.as_deref(),base,@@ -363,6 +364,7 @@ async fn run_batch(.read_page(&args.workspace, &args.project, &page.path, None).await?;body = refetch.page.as_ref().map(render_page).transpose()?;+ page_id = refetch.page.as_ref().and_then(|page| page.id.clone());decision = classify(disk.as_deref(),base,@@ -375,7 +377,10 @@ async fn run_batch(page,disk.as_deref(),body,- read.etag,+ Versions {+ etag: read.etag,+ page_id,+ },decision,args.force,)?;@@ -400,6 +405,12 @@ async fn run_batch(Ok((report, new_state, applied))}+/// The server's version markers for one page read.+struct Versions {+ etag: Option<String>,+ page_id: Option<String>,+}+#[allow(clippy::too_many_arguments)]fn record_decision(report: &mut Report,@@ -407,10 +418,11 @@ fn record_decision(page: PageSummary,disk: Option<&[u8]>,body: Option<String>,- etag: Option<String>,+ versions: Versions,decision: Classification,force: bool,) -> Result<()> {+ let Versions { etag, page_id } = versions;match decision {Classification::Unchanged => {if let Some(body) = &body {@@ -421,6 +433,7 @@ fn record_decision(PageState {hash: state::sha256_hex(body.as_bytes()),etag,+ page_id,},);}@@ -439,6 +452,7 @@ fn record_decision(PageState {hash: state::sha256_hex(body.as_bytes()),etag: etag.clone(),+ page_id: page_id.clone(),},);report.writes.push(PlannedWrite {@@ -465,6 +479,7 @@ fn record_decision(PageState {hash: state::sha256_hex(body.as_bytes()),etag: etag.clone(),+ page_id,},);report.writes.push(PlannedWrite {@@ -592,6 +607,7 @@ mod tests {PageState {hash: hash.to_string(),etag: etag.map(str::to_owned),+ page_id: None,}}diff --git a/companions/ai-memory-wikisync/tests/api_server.rs b/companions/ai-memory-wikisync/tests/api_server.rsindex 9124cf9e..79ee96ea 100644--- a/companions/ai-memory-wikisync/tests/api_server.rs+++ b/companions/ai-memory-wikisync/tests/api_server.rs@@ -1,6 +1,8 @@//! Integration tests against a fixture `/api/v1` server (axum, temp port)://! 200/ETag/304/401/404 and incremental-cursor pagination, plus the-//! end-to-end plan/export/local-edit-refusal flow through `run`.+//! end-to-end plan/export/local-edit-refusal flow through `run`, and the+//! sync flow through the fixture's `POST /mcp`, which enforces the+//! server's conditional-write contract.use std::collections::BTreeMap;use std::fs;@@ -9,7 +11,7 @@ use std::path::PathBuf;use std::sync::atomic::{AtomicUsize, Ordering};use std::sync::{Arc, Mutex};-use ai_memory_wikisync::bidi::{self, Prefer, SyncArgs};+use ai_memory_wikisync::bidi::{self, CheckStatus, Outcome, Prefer, SyncArgs, SyncMode};use ai_memory_wikisync::state::{self, SyncState};use ai_memory_wikisync::sync::{Mode, RunArgs, run};use axum::extract::{Path, Query, State};@@ -24,6 +26,8 @@ use tokio::net::TcpListener;/// the fields wikisync reads.#[derive(Clone)]struct FixturePage {+ /// Version id: a new one for every write, like the server's page id.+ id: String,path: String,body: String,title: String,@@ -35,6 +39,7 @@ struct FixturePage {impl FixturePage {fn new(path: &str, body: &str) -> Self {Self {+ id: next_version(),path: path.to_string(),body: body.to_string(),title: format!("title {path}"),@@ -45,6 +50,15 @@ impl FixturePage {}}+/// A fresh version id. Global, so ids never repeat across fixture servers.+fn next_version() -> String {+ static NEXT: AtomicUsize = AtomicUsize::new(1);+ format!(+ "00000000-0000-7000-8000-{:012}",+ NEXT.fetch_add(1, Ordering::SeqCst)+ )+}+/// Fixture server state: pages, optional bearer token, call counters.struct Fixture {/// Pages in listing order.@@ -59,11 +73,20 @@ struct Fixture {edit_on_read: Option<(&'static str, usize)>,/// Text the fixture's write path redacts, like the server's sanitizer.redact: Option<&'static str>,+ /// Edit this page right before an MCP call on it is handled, to simulate+ /// another writer landing between a sync's classification and its write.+ edit_before_mcp: Option<&'static str>,+ /// A server older than 2.7: no `expected_page_id` in the tool schema, no+ /// `id` on pages, and preconditions silently ignored.+ old_server: bool,+ /// Arguments of every MCP tool call, in order.+ mcp_calls: Mutex<Vec<serde_json::Value>>,reads_by_path: Mutex<BTreeMap<String, usize>>,recent_calls: AtomicUsize,page_reads_200: AtomicUsize,page_reads_304: AtomicUsize,mcp_writes: AtomicUsize,+ mcp_deletes: AtomicUsize,}impl Fixture {@@ -84,11 +107,15 @@ impl Fixture {unreachable: None,edit_on_read: None,redact: None,+ edit_before_mcp: None,+ old_server: false,+ mcp_calls: Mutex::new(Vec::new()),reads_by_path: Mutex::new(BTreeMap::new()),recent_calls: AtomicUsize::new(0),page_reads_200: AtomicUsize::new(0),page_reads_304: AtomicUsize::new(0),mcp_writes: AtomicUsize::new(0),+ mcp_deletes: AtomicUsize::new(0),}}@@ -123,6 +150,7 @@ impl Fixture {.find(|page| page.path == path).expect("fixture page");edit(page);+ page.id = next_version();}fn remove(&self, path: &str) {@@ -234,7 +262,8 @@ async fn page_handler(if page.pinned {frontmatter["pinned"] = json!(true);}- let document = json!({+ let mut document = json!({+ "id": page.id,"project": project,"workspace": workspace,"path": path,@@ -250,6 +279,9 @@ async fn page_handler("links": [],"backlinks": [],});+ if fixture.old_server {+ document.as_object_mut().unwrap().remove("id");+ }// Like the server: the ETag covers the whole projection, so a change to// metadata alone also changes it.let etag = format!("\"{}\"", state::sha256_hex(document.to_string().as_bytes()));@@ -278,9 +310,41 @@ async fn page_handler(.into_response()}-/// `POST /mcp` `tools/call memory_write_page` with the server's replace-/// semantics: every field the call omits is cleared, and the stored body-/// passes a redaction step like the server's sanitizer.+fn rpc_result(id: &serde_json::Value, result: serde_json::Value) -> axum::response::Response {+ Json(json!({"jsonrpc": "2.0", "id": id, "result": result})).into_response()+}++fn tool_text(id: &serde_json::Value, is_error: bool, text: String) -> axum::response::Response {+ rpc_result(+ id,+ json!({"isError": is_error, "content": [{"type": "text", "text": text}]}),+ )+}++/// The server's precondition failure: `invalid_request` with typed data.+fn precondition_failed(+ id: &serde_json::Value,+ path: &str,+ expected: Option<&str>,+ current: Option<&str>,+) -> axum::response::Response {+ Json(json!({"jsonrpc": "2.0", "id": id, "error": {+ "code": -32600,+ "message": format!("precondition failed for {path}; nothing was changed"),+ "data": {+ "reason": "precondition_failed",+ "path": path,+ "expected_page_id": expected,+ "current_page_id": current,+ },+ }}))+ .into_response()+}++/// `POST /mcp`: `tools/list`, and `tools/call` of `memory_write_page` (the+/// server's replace semantics: every field the call omits is cleared, and the+/// stored body passes a redaction step like the server's sanitizer) and+/// `memory_delete_page`, both honouring `expected_page_id` / `create_only`.async fn mcp_handler(State(fixture): State<Arc<Fixture>>,headers: HeaderMap,@@ -296,17 +360,65 @@ async fn mcp_handler(if !(accept.contains("application/json") && accept.contains("text/event-stream")) {return StatusCode::NOT_ACCEPTABLE.into_response();}+ let id = &request["id"];+ if request["method"] == "tools/list" {+ let mut properties = json!({"path": {"type": "string"}, "body": {"type": "string"}});+ if !fixture.old_server {+ properties["expected_page_id"] = json!({"type": "string"});+ properties["create_only"] = json!({"type": "boolean"});+ }+ return rpc_result(+ id,+ json!({"tools": [+ {"name": "memory_read_page", "inputSchema": {"type": "object"}},+ {"name": "memory_write_page",+ "inputSchema": {"type": "object", "properties": properties}},+ ]}),+ );+ }+ let name = request["params"]["name"].as_str().unwrap_or_default();let args = &request["params"]["arguments"];- if request["params"]["name"] != "memory_write_page"+ if request["method"] != "tools/call"+ || !matches!(name, "memory_write_page" | "memory_delete_page")|| args["workspace"] != "demo"|| args["project"] != "app"{- return Json(json!({"jsonrpc": "2.0", "id": request["id"],- "result": {"isError": true, "content": [{"type": "text", "text": "bad call"}]}}))- .into_response();+ return tool_text(id, true, "bad call".to_string());}- fixture.mcp_writes.fetch_add(1, Ordering::SeqCst);+ fixture.mcp_calls.lock().unwrap().push(json!({+ "name": name,+ "arguments": args,+ }));let path = args["path"].as_str().unwrap_or_default().to_string();+ if fixture.edit_before_mcp == Some(path.as_str()) && fixture.page(&path).is_some() {+ fixture.update(&path, |page| page.body.push_str("edited concurrently\n"));+ }+ let current = fixture.page(&path).map(|page| page.id);+ let expected = args["expected_page_id"].as_str();+ let create_only = args["create_only"].as_bool() == Some(true);+ if !fixture.old_server {+ let holds = match (expected, create_only) {+ (Some(expected), _) => current.as_deref() == Some(expected),+ (None, true) => current.is_none(),+ (None, false) => true,+ };+ if !holds {+ return precondition_failed(id, &path, expected, current.as_deref());+ }+ }+ if name == "memory_delete_page" {+ if current.is_none() {+ return tool_text(id, true, format!("no page at {path}"));+ }+ fixture.remove(&path);+ fixture.mcp_deletes.fetch_add(1, Ordering::SeqCst);+ return tool_text(+ id,+ false,+ json!({"path": path, "deleted": true}).to_string(),+ );+ }+ fixture.mcp_writes.fetch_add(1, Ordering::SeqCst);let mut body = args["body"].as_str().unwrap_or_default().to_string();if let Some(secret) = fixture.redact {body = body.replace(secret, "[REDACTED]");@@ -322,14 +434,17 @@ async fn mcp_handler(if let Some(tags) = args["tags"].as_array().filter(|tags| !tags.is_empty()) {written.frontmatter = json!({ "tags": tags });}+ let page_id = written.id.clone();{let mut pages = fixture.pages.lock().unwrap();pages.retain(|page| page.path != path);pages.push(written);}- Json(json!({"jsonrpc": "2.0", "id": request["id"],- "result": {"isError": false, "content": [{"type": "text", "text": "{}"}]}}))- .into_response()+ tool_text(+ id,+ false,+ json!({"page_id": page_id, "path": path}).to_string(),+ )}async fn serve(fixture: Fixture) -> (SocketAddr, Arc<Fixture>) {@@ -664,11 +779,20 @@ fn sync_args(addr: SocketAddr, dest: &std::path::Path, prefer: Option<Prefer>) -SyncArgs {run: args(addr, dest, &["decisions"]),prefer,+ propagate_deletes: false,+ max_deletes: bidi::DEFAULT_MAX_DELETES,+ }+}++fn deleting_args(addr: SocketAddr, dest: &std::path::Path, prefer: Option<Prefer>) -> SyncArgs {+ SyncArgs {+ propagate_deletes: true,+ ..sync_args(addr, dest, prefer)}}-async fn sync(addr: SocketAddr, dest: &std::path::Path) -> anyhow::Result<()> {- bidi::run(&sync_args(addr, dest, None), true).await+async fn sync(addr: SocketAddr, dest: &std::path::Path) -> anyhow::Result<Outcome> {+ bidi::run(&sync_args(addr, dest, None), SyncMode::Apply).await}fn decision() -> FixturePage {@@ -714,7 +838,7 @@ async fn sync_imports_a_repo_edit_with_its_metadata() {"---\ntitle: \"DB\"\ntags: [\"db\", \"ops\"]\npinned: true\n---\n# DB\nUse Postgres 17.\n";fs::write(dest.join("decisions/db.md"), edited).unwrap();// Dry-run first: nothing reaches the server.- bidi::run(&sync_args(addr, &dest, None), false)+ bidi::run(&sync_args(addr, &dest, None), SyncMode::DryRun).await.expect("dry run");assert_eq!(fixture.mcp_writes.load(Ordering::SeqCst), 0);@@ -796,9 +920,12 @@ async fn sync_conflicts_until_a_side_is_preferred() {);assert_eq!(fixture.mcp_writes.load(Ordering::SeqCst), 0);- bidi::run(&sync_args(addr, &dest, Some(Prefer::Server)), true)- .await- .expect("prefer server");+ bidi::run(+ &sync_args(addr, &dest, Some(Prefer::Server)),+ SyncMode::Apply,+ )+ .await+ .expect("prefer server");assert!(fs::read_to_string(dest.join("decisions/db.md")).unwrap()@@ -809,7 +936,7 @@ async fn sync_conflicts_until_a_side_is_preferred() {fixture.update("decisions/db.md", |page| {page.body = "# DB\nAgain on the server.\n".into()});- bidi::run(&sync_args(addr, &dest, Some(Prefer::Repo)), true)+ bidi::run(&sync_args(addr, &dest, Some(Prefer::Repo)), SyncMode::Apply).await.expect("prefer repo");assert!(@@ -843,55 +970,181 @@ async fn sync_refuses_to_clear_metadata_it_cannot_round_trip() {}#[tokio::test]-async fn sync_stops_when_the_server_page_changes_before_the_write() {+async fn sync_import_sends_the_classified_version_and_records_the_new_one() {let (addr, fixture) = serve(Fixture::with_pages(vec![decision()])).await;let (_tmp, dest) = temp_dest();sync(addr, &dest).await.expect("first sync");+ let exported = fixture.page("decisions/db.md").unwrap().id;+ assert_eq!(+ state::load(&dest).unwrap().pages["decisions/db.md"]+ .page_id+ .as_deref(),+ Some(exported.as_str()),+ "the export records the version id"+ );+fs::write(dest.join("decisions/db.md"),DECISION_FILE.replace("Use Postgres.", "Repo edit."),).unwrap();+ fs::write(+ dest.join("decisions/new.md"),+ "---\ntitle: \"New\"\n---\n# New\n",+ )+ .unwrap();+ sync(addr, &dest).await.expect("import");- // Reads so far: 1 by the first sync. The second sync classifies with- // read 2 (a 304) and 3 (the full page for the import); read 4 is the- // re-check right before the write, and lands after an edit.- let fixture_with_race = Fixture {- edit_on_read: Some(("decisions/db.md", 4)),- ..Fixture::with_pages(vec![fixture.page("decisions/db.md").unwrap()])+ let calls = fixture.mcp_calls.lock().unwrap().clone();+ let call = |path: &str| {+ calls+ .iter()+ .find(|call| call["arguments"]["path"] == path)+ .unwrap_or_else(|| panic!("no MCP call for {path}"))+ .clone()};- let (race_addr, raced) = serve(fixture_with_race).await;- // Seed the race server's read counter like the first server's.- raced- .reads_by_path- .lock()- .unwrap()- .insert("decisions/db.md".into(), 1);- let err = sync(race_addr, &dest).await.expect_err("race detected");+ let update = call("decisions/db.md");+ assert_eq!(update["arguments"]["expected_page_id"], exported.as_str());+ assert!(update["arguments"].get("create_only").is_none());+ let create = call("decisions/new.md");+ assert_eq!(create["arguments"]["create_only"], true);+ assert!(create["arguments"].get("expected_page_id").is_none());++ let state = state::load(&dest).unwrap();+ for path in ["decisions/db.md", "decisions/new.md"] {+ assert_eq!(+ state.pages[path].page_id,+ Some(fixture.page(path).unwrap().id),+ "{path}: the written version is the new base"+ );+ }+}++/// The race slice 3 could only narrow: another writer lands between the+/// classification read and the write. The server refuses the stale version,+/// the run reports it and fails, and every other page still syncs. Without+/// `expected_page_id` the fixture would accept the write and this fails.+#[tokio::test]+async fn sync_reports_a_page_changed_during_the_run_and_applies_the_rest() {+ let mut other = decision();+ other.path = "decisions/other.md".to_string();+ let (addr, fixture) = serve(Fixture::with_pages(vec![decision(), other])).await;+ let (_tmp, dest) = temp_dest();+ sync(addr, &dest).await.expect("first sync");+ let base = state::load(&dest).unwrap().pages["decisions/db.md"].clone();+ let raced_edit = DECISION_FILE.replace("Use Postgres.", "Repo edit.");+ fs::write(dest.join("decisions/db.md"), &raced_edit).unwrap();+ fs::write(+ dest.join("decisions/other.md"),+ DECISION_FILE.replace("Use Postgres.", "Other edit."),+ )+ .unwrap();++ let racing = Fixture {+ edit_before_mcp: Some("decisions/db.md"),+ ..Fixture::with_pages(vec![+ fixture.page("decisions/db.md").unwrap(),+ fixture.page("decisions/other.md").unwrap(),+ ])+ };+ let (race_addr, raced) = serve(racing).await;+ let err = sync(race_addr, &dest).await.expect_err("race reported");+ let message = format!("{err:#}");+ assert!(message.contains("changed during this run"), "{message}");+ assert!(message.contains("decisions/db.md"), "{message}");++ let page = raced.page("decisions/db.md").unwrap();assert!(- format!("{err:#}").contains("changed on the server during this run"),- "{err:#}"+ page.body.contains("edited concurrently") && !page.body.contains("Repo edit"),+ "the concurrent edit survives: {}",+ page.body+ );+ assert!(+ raced+ .page("decisions/other.md")+ .unwrap()+ .body+ .contains("Other edit"),+ "the other page still synced");+ let state = state::load(&dest).unwrap();assert_eq!(- raced.mcp_writes.load(Ordering::SeqCst),- 0,- "the write never happened"+ state.pages["decisions/db.md"], base,+ "raced state untouched"+ );+ assert_eq!(+ fs::read_to_string(dest.join("decisions/db.md")).unwrap(),+ raced_edit,+ "the repository edit is kept for the next run");}#[tokio::test]-async fn sync_reports_deletes_and_never_propagates_them() {+async fn sync_apply_refuses_a_server_without_conditional_writes() {+ let old = Fixture {+ old_server: true,+ ..Fixture::with_pages(vec![decision()])+ };+ let (addr, fixture) = serve(old).await;+ let (_tmp, dest) = temp_dest();+ sync(addr, &dest)+ .await+ .expect("exports need no precondition");++ fs::write(+ dest.join("decisions/db.md"),+ DECISION_FILE.replace("Use Postgres.", "Repo edit."),+ )+ .unwrap();+ bidi::run(&sync_args(addr, &dest, None), SyncMode::DryRun)+ .await+ .expect("a dry run still plans against an old server");+ let err = sync(addr, &dest).await.expect_err("old server refused");+ assert!(+ format!("{err:#}").contains("server too old for sync --apply"),+ "{err:#}"+ );+ assert_eq!(fixture.mcp_writes.load(Ordering::SeqCst), 0);+ assert!(fixture.mcp_calls.lock().unwrap().is_empty());+}++/// Only the tool schema can tell an old server apart when the plan has+/// nothing but creates, which carry no version id.+#[tokio::test]+async fn sync_apply_checks_the_tool_schema_before_a_create() {+ let old = Fixture {+ old_server: true,+ ..Fixture::with_pages(vec![])+ };+ let (addr, fixture) = serve(old).await;+ let (_tmp, dest) = temp_dest();+ fs::create_dir_all(dest.join("decisions")).unwrap();+ fs::write(+ dest.join("decisions/new.md"),+ "---\ntitle: \"New\"\n---\n# New\n",+ )+ .unwrap();+ let err = sync(addr, &dest).await.expect_err("old server refused");+ assert!(format!("{err:#}").contains("ai-memory >= 2.7"), "{err:#}");+ assert!(fixture.page("decisions/new.md").is_none());+ assert!(fixture.mcp_calls.lock().unwrap().is_empty());+}++#[tokio::test]+async fn sync_only_reports_deletes_without_the_flag() {let mut other = decision();other.path = "decisions/other.md".to_string();let (addr, fixture) = serve(Fixture::with_pages(vec![decision(), other])).await;let (_tmp, dest) = temp_dest();sync(addr, &dest).await.expect("first sync");+ let before = state::load(&dest).unwrap();fixture.remove("decisions/db.md");fs::remove_file(dest.join("decisions/other.md")).unwrap();- sync(addr, &dest)+ let outcome = sync(addr, &dest).await.expect("deletes are notices, not refusals");+ assert_eq!(outcome.status(), CheckStatus::Drift);assert!(dest.join("decisions/db.md").exists(),"server delete not propagated"@@ -900,7 +1153,12 @@ async fn sync_reports_deletes_and_never_propagates_them() {fixture.page("decisions/other.md").is_some(),"repo delete not propagated");- assert_eq!(fixture.mcp_writes.load(Ordering::SeqCst), 0);+ assert!(fixture.mcp_calls.lock().unwrap().is_empty());+ assert_eq!(+ state::load(&dest).unwrap(),+ before,+ "an unpropagated delete keeps its base entry"+ );fs::remove_file(dest.join("decisions/db.md")).unwrap();sync(addr, &dest).await.expect("gone on both sides");@@ -912,6 +1170,213 @@ async fn sync_reports_deletes_and_never_propagates_them() {);}+#[tokio::test]+async fn sync_propagates_deletes_from_an_unchanged_side() {+ let mut other = decision();+ other.path = "decisions/other.md".to_string();+ other.pinned = false;+ let mut kept = decision();+ kept.path = "decisions/kept.md".to_string();+ let (addr, fixture) = serve(Fixture::with_pages(vec![decision(), other, kept])).await;+ let (_tmp, dest) = temp_dest();+ sync(addr, &dest).await.expect("first sync");+ let other_id = fixture.page("decisions/other.md").unwrap().id;++ fixture.remove("decisions/db.md");+ fs::remove_file(dest.join("decisions/other.md")).unwrap();+ // A dry run with the flag still changes nothing.+ bidi::run(&deleting_args(addr, &dest, None), SyncMode::DryRun)+ .await+ .expect("dry run");+ assert!(dest.join("decisions/db.md").exists());+ assert!(fixture.page("decisions/other.md").is_some());++ bidi::run(&deleting_args(addr, &dest, None), SyncMode::Apply)+ .await+ .expect("deletes propagate");+ assert!(+ !dest.join("decisions/db.md").exists(),+ "server delete reached the repository"+ );+ assert!(+ fixture.page("decisions/other.md").is_none(),+ "repository delete reached the server"+ );+ let calls = fixture.mcp_calls.lock().unwrap().clone();+ assert_eq!(calls.len(), 1, "{calls:?}");+ assert_eq!(calls[0]["name"], "memory_delete_page");+ assert_eq!(+ calls[0]["arguments"]["expected_page_id"],+ other_id.as_str(),+ "the delete is conditional on the classified version"+ );+ let state = state::load(&dest).unwrap();+ assert!(!state.pages.contains_key("decisions/db.md"));+ assert!(!state.pages.contains_key("decisions/other.md"));+ assert!(state.pages.contains_key("decisions/kept.md"));+ assert!(+ dest.join("decisions/kept.md").exists(),+ "untouched pages stay"+ );+}++#[tokio::test]+async fn sync_delete_conflicts_follow_prefer() {+ let mut other = decision();+ other.path = "decisions/other.md".to_string();+ other.pinned = false;+ let (addr, fixture) = serve(Fixture::with_pages(vec![decision(), other.clone()])).await;+ let (_tmp, dest) = temp_dest();+ sync(addr, &dest).await.expect("first sync");++ // db.md: deleted in the repository, edited on the server.+ // other.md: deleted on the server, edited in the repository.+ let repo_edit = DECISION_FILE+ .replace("pinned: true\n", "")+ .replace("Use Postgres.", "Repo edit.");+ let setup = |fixture: &Fixture| {+ let _ = fs::remove_file(dest.join("decisions/db.md"));+ fixture.update("decisions/db.md", |page| {+ page.body = "# DB\nServer edit.\n".into()+ });+ fs::write(dest.join("decisions/other.md"), &repo_edit).unwrap();+ fixture.remove("decisions/other.md");+ };+ setup(&fixture);+ let err = bidi::run(&deleting_args(addr, &dest, None), SyncMode::Apply)+ .await+ .expect_err("conflicts refuse the batch");+ assert!(err.to_string().contains("refused"), "{err}");+ assert!(fixture.mcp_calls.lock().unwrap().is_empty());+ assert!(dest.join("decisions/other.md").exists());++ // --prefer server: the server's edit comes back, its delete wins.+ bidi::run(+ &deleting_args(addr, &dest, Some(Prefer::Server)),+ SyncMode::Apply,+ )+ .await+ .expect("prefer server");+ assert!(+ fs::read_to_string(dest.join("decisions/db.md"))+ .unwrap()+ .contains("Server edit"),+ "re-exported"+ );+ assert!(!dest.join("decisions/other.md").exists(), "file deleted");+ assert!(fixture.mcp_calls.lock().unwrap().is_empty());++ // --prefer repo: the repository's delete wins (pinned or not), and its+ // edit is re-created with create_only.+ fixture.pages.lock().unwrap().push(other);+ sync(addr, &dest).await.expect("resettle other.md");+ setup(&fixture);+ bidi::run(+ &deleting_args(addr, &dest, Some(Prefer::Repo)),+ SyncMode::Apply,+ )+ .await+ .expect("prefer repo");+ assert!(fixture.page("decisions/db.md").is_none(), "server deleted");+ let recreated = fixture.page("decisions/other.md").expect("re-created");+ assert!(recreated.body.contains("Repo edit"), "{}", recreated.body);+ let calls = fixture.mcp_calls.lock().unwrap().clone();+ let create = calls+ .iter()+ .find(|call| call["name"] == "memory_write_page")+ .expect("write");+ assert_eq!(create["arguments"]["create_only"], true);+}++#[tokio::test]+async fn sync_never_deletes_a_pinned_page_without_prefer_repo() {+ // decision() is pinned on the server.+ let (addr, fixture) = serve(Fixture::with_pages(vec![decision()])).await;+ let (_tmp, dest) = temp_dest();+ sync(addr, &dest).await.expect("first sync");+ fs::remove_file(dest.join("decisions/db.md")).unwrap();++ for prefer in [None, Some(Prefer::Server)] {+ let err = bidi::run(&deleting_args(addr, &dest, prefer), SyncMode::Apply)+ .await+ .expect_err("pinned page refused");+ assert!(err.to_string().contains("refused"), "{err}");+ }+ assert!(fixture.page("decisions/db.md").is_some());+ assert_eq!(fixture.mcp_deletes.load(Ordering::SeqCst), 0);++ bidi::run(+ &deleting_args(addr, &dest, Some(Prefer::Repo)),+ SyncMode::Apply,+ )+ .await+ .expect("--prefer repo deletes it");+ assert!(fixture.page("decisions/db.md").is_none());+}++#[tokio::test]+async fn sync_refuses_more_deletes_than_the_ceiling() {+ let pages: Vec<FixturePage> = (0..3)+ .map(|n| FixturePage::new(&format!("decisions/d{n}.md"), "# D\n"))+ .collect();+ let (addr, fixture) = serve(Fixture::with_pages(pages)).await;+ let (_tmp, dest) = temp_dest();+ sync(addr, &dest).await.expect("first sync");+ for n in 0..3 {+ fixture.remove(&format!("decisions/d{n}.md"));+ }++ let capped = SyncArgs {+ max_deletes: 2,+ ..deleting_args(addr, &dest, None)+ };+ let err = bidi::run(&capped, SyncMode::Apply)+ .await+ .expect_err("ceiling");+ assert!(err.to_string().contains("--max-deletes 2"), "{err}");+ for n in 0..3 {+ assert!(dest.join(format!("decisions/d{n}.md")).exists());+ }++ let raised = SyncArgs {+ max_deletes: 3,+ ..capped+ };+ bidi::run(&raised, SyncMode::Apply)+ .await+ .expect("within the ceiling");+ for n in 0..3 {+ assert!(!dest.join(format!("decisions/d{n}.md")).exists());+ }+}++#[cfg(unix)]+#[tokio::test]+async fn sync_never_deletes_through_a_symlink() {+ let (addr, fixture) = serve(Fixture::with_pages(vec![decision()])).await;+ let (tmp, dest) = temp_dest();+ sync(addr, &dest).await.expect("first sync");++ let outside = tmp.path().join("outside.md");+ fs::write(&outside, DECISION_FILE).unwrap();+ fs::remove_file(dest.join("decisions/db.md")).unwrap();+ std::os::unix::fs::symlink(&outside, dest.join("decisions/db.md")).unwrap();+ fixture.remove("decisions/db.md");++ let err = bidi::run(&deleting_args(addr, &dest, None), SyncMode::Apply)+ .await+ .expect_err("symlink refused");+ assert!(err.to_string().contains("refused"), "{err}");+ assert!(+ fs::symlink_metadata(dest.join("decisions/db.md"))+ .unwrap()+ .file_type()+ .is_symlink(),+ "the link is left alone"+ );+ assert_eq!(fs::read_to_string(&outside).unwrap(), DECISION_FILE);+}+#[tokio::test]async fn sync_adopts_the_server_rendering_after_an_import() {let fixture = Fixture {@@ -950,6 +1415,7 @@ async fn sync_upgrades_a_slice_one_export_without_importing() {state::PageState {hash: state::sha256_hex(b"# DB\nUse Postgres.\n"),etag: None,+ page_id: None,},);state::save(&dest, &old).unwrap();diff --git a/docs/companion-crates.md b/docs/companion-crates.mdindex 56f9fa9b..ec4d73ac 100644--- a/docs/companion-crates.md+++ b/docs/companion-crates.md@@ -79,8 +79,8 @@ the public MCP write/delete tools. It must never open the wiki directory orSQLite directly. The core read seam is `/api/v1` in API-only mode; the supportedMCP page arguments are documented in [programmatic memory](programmatic-memory.md).-Slice 1 (read-only export) and slice 3 (two-way sync through the MCP write-tool) ship as+Slice 1 (read-only export), slice 3 (two-way sync through the MCP write+tool) and slice 4 (conditional writes and opt-in deletes) ship as[`ai-memory-wikisync`](#ai-memory-wikisync-team-wiki-export-and-sync)below; the remaining slices are tracked in #986.@@ -237,7 +237,7 @@ Re-home by kind:## `ai-memory-wikisync`: team-wiki export and sync-Slices 1 and 3 of the accepted [team-wiki sync](#proposed-team-wiki-sync-986)+Slices 1, 3 and 4 of the accepted [team-wiki sync](#proposed-team-wiki-sync-986)shape, implemented at [`companions/ai-memory-wikisync`](../companions/ai-memory-wikisync)as a standalone Cargo package with its own `[workspace]` (mirroring theimporter): it is not a member of the root workspace and is not covered by@@ -257,9 +257,12 @@ family-scoped and dry-run by default.with cursor paging (legacy array accepted) plus single-page reads with`ETag` / `If-None-Match` revalidation. No admin routes.- `sync` (dry-run unless `--apply`) also writes to the server, and only- through the public `memory_write_page` MCP tool with explicit `workspace`- and `project`, so sanitization, admission and attribution apply. It never- opens the wiki directory or SQLite.+ through the public `memory_write_page` and `memory_delete_page` MCP tools+ with explicit `workspace` and `project`, so sanitization, admission and+ attribution apply. Every call carries the classified page version+ (`expected_page_id`, or `create_only` for a new page). It never opens the+ wiki directory or SQLite, and refuses to write to a server older than 2.7,+ which would ignore the precondition.- `--include FAMILY` is an explicit, repeatable allowlist of top-levelwiki directories; at least one is required and a bare `*` is refused.- Auth is a bearer token via `--token` or `AI_MEMORY_AUTH_TOKEN` only;@@ -278,8 +281,9 @@ family-scoped and dry-run by default.state, server body): files edited locally since the last export arereported with a diff summary and the whole batch is refused without`--force`.-- Never deletes anything (deletes are slice 4); never runs git, commits,- or pushes — it prints the commands the operator may run.+- `plan` and `export` never delete; `sync` deletes only with+ `--propagate-deletes`. It never runs git, commits, or pushes — it prints+ the commands (`git add`, `git rm`) the operator may run.- Destination-path safety: traversal, dotfiles, reserved Windows names,non-portable characters, case-fold collisions, oversized bodies,symlinked destinations/components/state directories, and unknown page@@ -289,13 +293,22 @@ family-scoped and dry-run by default.or rendered.- `sync` changes one side only when the other is unchanged since the lastsync; a page changed on both sides is refused until `--prefer repo` or- `--prefer server`. Deletes are reported, never propagated (slice 4).+ `--prefer server`. Deletes are reported unless `--propagate-deletes` is+ passed; then a side unchanged since the last sync is deleted, and a delete+ against an edit is a conflict that `--prefer` resolves (`repo`: delete the+ page or re-create it with `create_only`; `server`: re-export or delete the+ file). More than `--max-deletes` (default 10) refuses the whole run; a+ pinned server page is deleted only with `--prefer repo`; a file is deleted+ only through the write path checks (no symlinks, confined to `--dest`) and+ only if it still holds the classified bytes. A delete that is not+ propagated keeps its state entry.- An import requires the file's frontmatter (a write clears what it omits),and is refused for a server page carrying any metadata the write cannotcarry (`summary`, `sources`, `kind`, …), naming the keys.-- Right before each import the server page is re-read and must still render- to the classified bytes. MCP has no compare-and-write, so one read-to-write- race window remains; that is the documented case for slice 2.+- Every import and delete is conditional on the page version the plan+ classified, so the server refuses one that changed in between. That page+ is reported as changed during the run and keeps its state; the other pages+ still sync and the run exits non-zero.### Validation@@ -311,8 +324,11 @@ full plan/export flow against a fixture axum server serving `/api/v1`responses (200/ETag/304/401/404 and cursor pagination), and the sync flowagainst the same fixture's `POST /mcp` with the server's replace semantics:imports with metadata, creates, conflicts and `--prefer`, the-metadata-loss refusal, the pre-write race check, delete notices, sanitizer-rewrites and the upgrade of a slice 1 export.+metadata-loss refusal, the version preconditions the fixture enforces (a+stale version is reported while the other pages apply), the old-server+refusal, delete notices and propagated deletes with each `--prefer`, the+delete ceiling, the pinned-page and symlink refusals, sanitizer rewrites and+the upgrade of a slice 1 export.### Roadmap (#986)@@ -322,7 +338,8 @@ rewrites and the upgrade of a slice 1 export.`memory_delete_page`, and the version id on `memory_read_page` and`/api/v1` pages).3. Bidirectional apply through public write tools (shipped as `sync`).-4. Deletes and conflict reporting.+4. Deletes and conflict reporting (shipped: `sync --propagate-deletes`,+ `--max-deletes`, conditional writes and deletes).5. Post-merge hook / CI integration.## `ai-memory-macos`: menu bar wrapper