Skip to content

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.md
index 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.0
current version, and changes nothing. `memory_read_page` returns the version
as `page_id` and `/api/v1` pages as `id`. This is the compare-and-write the
team-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 unreachable
server (reported instead of aborting the check), a hook spool that is full and
evicting undelivered events, and installed ai-memory Codex hooks that Codex
diff --git a/companions/ai-memory-wikisync/README.md b/companions/ai-memory-wikisync/README.md
index 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 running
ai-memory server in step with a directory inside a project repository, so a
team'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 root
ai-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 keys
All local bookkeeping lives in **one** state file,
`.ai-memory-wikisync/state.json` (mode 0600, atomically replaced after
each 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 under
diverged from both is reported with a diff summary and **refused**; the
whole batch is refused, nothing is written. `--force` overwrites the
divergent 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 would
escape `--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 an
import; 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 stores
something other than the file (the sanitizer redacting a secret), the file
is 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.rs
index 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.rs
index 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.rs
index 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 are
diff --git a/companions/ai-memory-wikisync/src/main.rs b/companions/ai-memory-wikisync/src/main.rs
index 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.rs
index 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.rs
index 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.rs
index 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.rs
index 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.md
index 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 or
SQLite directly. The core read seam is `/api/v1` in API-only mode; the supported
MCP 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 the
importer): 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-level
wiki 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 are
reported 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 last
sync; 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 cannot
carry (`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 flow
against 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