Skip to content

Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors

Rust
32.7 KB
Raw Blame
//! The plan/export engine: three-way classification and batched writes.
//!
//! For every allowlisted page the tool compares three versions — the
//! destination file (mine), the state entry (base: what this tool last
//! wrote), and the server body (theirs, revalidated through the ETag) — and
//! refuses to choose a winner when the destination has diverged from both.
//! Writes happen only in one batch per run, and the state file is replaced
//! atomically after the whole batch succeeds, so a crash at any point leaves
//! a consistent (old) state that the next run re-classifies safely.

use std::fs;
use std::io::Write;
use std::path::{Path, PathBuf};

use anyhow::{Context, Result, bail};

use crate::client::{ApiClient, ApiPage, PageSummary};
use crate::page_file::{self, PageMeta};
use crate::paths;
use crate::state::{self, PageState, SyncState};
use crate::{MAX_BODY_BYTES, MAX_PAGES};

/// Why a planned write touches the file.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum WriteKind {
    /// No destination file: the server body creates one.
    Create,
    /// Destination still equals the base state: fast-forward to the server.
    Update,
    /// Destination diverged and `--force` chose the server version.
    Forced,
}

impl WriteKind {
    fn label(self) -> &'static str {
        match self {
            Self::Create => "create",
            Self::Update => "update",
            Self::Forced => "forced",
        }
    }
}

/// Why a destination file refuses to be overwritten.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum DivergentReason {
    /// Edited locally since the last export.
    LocalEdit,
    /// Present on disk but never written by this tool.
    UnknownFile,
}

impl DivergentReason {
    fn describe(self) -> &'static str {
        match self {
            Self::LocalEdit => "edited locally since the last export",
            Self::UnknownFile => "exists on disk but was never written by wikisync",
        }
    }
}

/// What a page's classification means for the filesystem.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum Classification {
    /// Destination matches the server byte-for-byte: nothing to do.
    Unchanged,
    /// Safe to write the server body (see [`WriteKind`]).
    Write(WriteKind),
    /// Destination differs from both base and server: a local edit this
    /// tool refuses to overwrite without `--force`.
    Divergent(DivergentReason),
}

/// One planned or performed write.
#[derive(Debug, Clone)]
pub struct PlannedWrite {
    pub kind: WriteKind,
    pub path: String,
    pub title: String,
    pub body: String,
    pub etag: Option<String>,
    /// Hash of the repository file the plan read, or `None` if it was absent.
    pub expected_disk: Option<String>,
}

/// A destination file that diverged, with a bounded diff summary.
#[derive(Debug, Clone)]
pub struct Divergence {
    pub path: String,
    pub reason: DivergentReason,
    pub summary: String,
}

/// Everything one run decided, for printing (and for tests).
#[derive(Debug, Default)]
pub struct Report {
    pub writes: Vec<PlannedWrite>,
    pub unchanged: Vec<String>,
    pub divergent: Vec<Divergence>,
    pub listed: usize,
    pub matched: usize,
    /// Total bytes the batch would write.
    pub bytes_to_write: u64,
}

impl Report {
    fn count(&self, kind: WriteKind) -> usize {
        self.writes
            .iter()
            .filter(|write| write.kind == kind)
            .count()
    }
}

/// How the run treats the filesystem.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum Mode {
    /// `plan`: never writes anything, not even the state file.
    Plan,
    /// `export` without `--apply`: still a dry-run.
    DryRun,
    /// `export --apply`.
    Apply,
}

/// Arguments shared by `plan` and `export`.
#[derive(Debug, Clone)]
pub struct RunArgs {
    pub server: String,
    pub token: Option<String>,
    pub workspace: String,
    pub project: String,
    pub dest: PathBuf,
    /// Explicit family allowlist. Must be non-empty; `*` is refused.
    pub include: Vec<String>,
    /// Overwrite files that diverged locally since the last export.
    pub force: bool,
    /// Take over a destination whose baseline belongs to another server,
    /// workspace or project: the baseline is discarded, so this run treats
    /// the destination as a fresh export (#1708). Without it a scope change
    /// refuses before anything is written.
    pub adopt_scope: bool,
}

/// Refuse to reuse a baseline recorded for another scope (#1708).
///
/// Reusing it made every page of the previous project look "deleted on the
/// server", which `--propagate-deletes --apply` then removed. Returns the
/// state a run should use: cleared when `--adopt-scope` takes the
/// destination over, stamped with this run's scope so the next save records
/// it.
pub fn baseline_for(
    mut state: state::SyncState,
    scope: &state::SyncScope,
    adopt: bool,
) -> Result<state::SyncState> {
    match state::check_scope(&state, scope) {
        state::ScopeCheck::Match => {}
        state::ScopeCheck::Adopted => {
            if !state.pages.is_empty() {
                eprintln!(
                    "ai-memory-wikisync: this destination's baseline predates origin tracking; \
                     adopting it for {}/{}. A baseline from another project cannot be detected, \
                     so check the plan before --apply.",
                    scope.workspace, scope.project
                );
            }
            state.scope = Some(scope.clone());
        }
        state::ScopeCheck::Mismatch { recorded } => {
            if !adopt {
                bail!(
                    "this destination's baseline belongs to {} ({}/{}), not {}/{}. \
                     Reusing it would read that project's pages as deletions here; re-run with \
                     --adopt-scope to discard the baseline and export fresh",
                    recorded.server,
                    recorded.workspace,
                    recorded.project,
                    scope.workspace,
                    scope.project
                );
            }
            eprintln!(
                "ai-memory-wikisync: discarding the baseline recorded for {}/{}, adopting this \
                 destination for {}/{}",
                recorded.workspace, recorded.project, scope.workspace, scope.project
            );
            state = state::SyncState {
                scope: Some(scope.clone()),
                ..state::SyncState::default()
            };
        }
    }
    Ok(state)
}

/// Classify one page from its three versions. Pure: all IO happens around
/// it, which is what makes the three-way rules testable.
pub fn classify(
    disk: Option<&[u8]>,
    base: Option<&PageState>,
    server: Option<&[u8]>,
) -> Classification {
    let disk_hash = disk.map(state::sha256_hex);
    let server_hash = server.map(state::sha256_hex);
    // Order matters: a byte-identical server match is Unchanged even with
    // no base entry (the file may be left over from an interrupted run
    // after the write but before the state save).
    let disk_equals_server = disk_hash.is_some() && disk_hash == server_hash;
    let disk_equals_base = match (&disk_hash, base) {
        (Some(disk), Some(base)) => disk == &base.hash,
        _ => false,
    };
    match (disk, base) {
        (None, _) => Classification::Write(WriteKind::Create),
        (Some(_), _) if disk_equals_server => Classification::Unchanged,
        (Some(_), Some(_)) if disk_equals_base => match server {
            // Server unchanged since the base (304): the file is current.
            None => Classification::Unchanged,
            Some(_) => Classification::Write(WriteKind::Update),
        },
        (Some(_), None) => Classification::Divergent(DivergentReason::UnknownFile),
        (Some(_), Some(_)) => Classification::Divergent(DivergentReason::LocalEdit),
    }
}

/// The file bytes for a server page: its round-trippable metadata as
/// frontmatter, then the body verbatim. Export and sync write the same
/// bytes, so the two never disagree about whether a file is current.
pub fn render_page(page: &ApiPage) -> Result<String> {
    if page.body_markdown.len() > MAX_BODY_BYTES {
        bail!(
            "page {} is {} bytes; refusing bodies over {MAX_BODY_BYTES} bytes",
            page.path,
            page.body_markdown.len()
        );
    }
    let meta = PageMeta::from_server(&page.title, &page.tier, page.pinned, &page.frontmatter);
    Ok(page_file::render(&meta, &page.body_markdown))
}

/// Bounded, printable diff summary for a divergent file: sizes, line counts
/// and the first differing line, with control characters neutralised so a
/// page body cannot smuggle terminal escapes into the output.
pub fn diff_summary(disk: Option<&[u8]>, server: Option<&[u8]>) -> String {
    let Some(disk) = disk else {
        return "no local file".to_string();
    };
    let Some(server) = server else {
        return "server content unchanged since the last export (revalidated by ETag)".to_string();
    };
    let local_lines = line_count(disk);
    let server_lines = line_count(server);
    // Compare the first missing line too, even when the shared prefix is identical.
    let first_difference = disk
        .split(|byte| *byte == b'\n')
        .map(Some)
        .chain(std::iter::once(None))
        .zip(
            server
                .split(|byte| *byte == b'\n')
                .map(Some)
                .chain(std::iter::once(None)),
        )
        .position(|(local, remote)| local != remote)
        .map_or(0, |index| index + 1);
    let local_line = disk
        .split(|byte| *byte == b'\n')
        .nth(first_difference.saturating_sub(1));
    let server_line = server
        .split(|byte| *byte == b'\n')
        .nth(first_difference.saturating_sub(1));
    format!(
        "local {} bytes/{} lines vs server {} bytes/{} lines; first difference at line \
         {}: local {} vs server {}",
        disk.len(),
        local_lines,
        server.len(),
        server_lines,
        first_difference,
        preview(local_line),
        preview(server_line),
    )
}

/// Lines in a file's bytes. Content not ending in a newline still has a
/// final line, which the first-difference position below also counts, so
/// the two numbers in one summary cannot contradict each other.
fn line_count(bytes: &[u8]) -> usize {
    let newlines = bytes.iter().filter(|byte| **byte == b'\n').count();
    newlines + usize::from(!bytes.is_empty() && !bytes.ends_with(b"\n"))
}

fn preview(line: Option<&[u8]>) -> String {
    let Some(line) = line else {
        return "<end of file>".to_string();
    };
    let text: String = line
        .iter()
        .take(60)
        .map(|byte| {
            if byte.is_ascii_graphic() || *byte == b' ' {
                *byte as char
            } else {
                '?'
            }
        })
        .collect();
    format!("{text:?}")
}

/// Atomic file replacement inside the destination: write a hidden tmp file
/// next to the target, fsync, rename. The tmp name is namespaced by this
/// tool so a crash never leaves an ambiguous artifact next to page files.
pub fn atomic_write(dest_root: &Path, rel: &str, bytes: &[u8]) -> Result<()> {
    let target = paths::secure_join(dest_root, rel)?;
    if let Some(parent) = target.parent() {
        fs::create_dir_all(parent)
            .with_context(|| format!("cannot create directory {}", parent.display()))?;
    }
    let file_name = target
        .file_name()
        .map(|name| name.to_string_lossy().into_owned())
        .unwrap_or_else(|| "page.md".to_string());
    let tmp = target
        .parent()
        .unwrap_or(dest_root)
        .join(format!(".wikisync-tmp-{file_name}"));
    {
        let mut file =
            fs::File::create(&tmp).with_context(|| format!("cannot create {}", tmp.display()))?;
        file.write_all(bytes)
            .with_context(|| format!("cannot write {}", tmp.display()))?;
        file.sync_all()
            .with_context(|| format!("cannot sync {}", tmp.display()))?;
    }
    fs::rename(&tmp, &target)
        .with_context(|| format!("cannot move {} into place", tmp.display()))?;
    Ok(())
}

/// Validate the allowlist: explicit, concrete families only.
pub fn validate_allowlist(include: &[String]) -> Result<Vec<String>> {
    if include.is_empty() {
        bail!(
            "at least one --include FAMILY is required; the family allowlist must be \
             explicit (for example --include _rules --include decisions)"
        );
    }
    let mut families = Vec::new();
    for family in include {
        paths::validate_family(family)?;
        if !families.contains(family) {
            families.push(family.clone());
        }
    }
    Ok(families)
}

/// Select, validate and bound the server listing down to the allowlisted
/// families. Deduplicates by path: incremental paging can legitimately
/// re-deliver a page that was updated mid-iteration.
pub fn select_pages(summaries: Vec<PageSummary>, families: &[String]) -> Result<Vec<PageSummary>> {
    let mut by_path: std::collections::BTreeMap<String, PageSummary> =
        std::collections::BTreeMap::new();
    for summary in summaries {
        if !families
            .iter()
            .any(|family| paths::family_of(&summary.path) == family.as_str())
        {
            continue;
        }
        paths::validate_page_path(&summary.path)?;
        by_path.insert(summary.path.clone(), summary);
    }
    let selected: Vec<PageSummary> = by_path.into_values().collect();
    if selected.len() > MAX_PAGES {
        bail!(
            "{} allowlisted pages exceed the per-run ceiling of {MAX_PAGES}; narrow --include",
            selected.len()
        );
    }
    let paths: Vec<String> = selected.iter().map(|page| page.path.clone()).collect();
    paths::ensure_no_case_fold_collisions(&paths)?;
    Ok(selected)
}

pub(crate) fn read_disk(dest_root: &Path, path: &str) -> Result<Option<Vec<u8>>> {
    let target = paths::secure_join(dest_root, path)?;
    match fs::read(&target) {
        Ok(bytes) => Ok(Some(bytes)),
        Err(e) if e.kind() == std::io::ErrorKind::NotFound => Ok(None),
        Err(e) => Err(anyhow::Error::new(e)).context(format!("cannot read {}", target.display())),
    }
}

/// Write `bytes` over a repository file only while it is still the file the
/// plan classified: `expected` is that file's hash, or `None` when there was
/// no file. Returns `false`, writing nothing, when an edit landed after the
/// plan. The check and atomic replacement are deliberately adjacent.
pub(crate) fn write_if_unchanged(
    dest_root: &Path,
    rel: &str,
    expected: Option<&str>,
    bytes: &[u8],
) -> Result<bool> {
    let current = read_disk(dest_root, rel)?;
    if current.as_deref().map(state::sha256_hex).as_deref() != expected {
        return Ok(false);
    }
    atomic_write(dest_root, rel, bytes)?;
    Ok(true)
}

/// Fetch and classify every allowlisted page. In [`Mode::Apply`] (and only
/// when allowed past the divergence guard) also performs the write batch
/// and persists the new state atomically.
async fn run_batch(
    client: &ApiClient,
    args: &RunArgs,
    dest_root: &Path,
    old_state: &SyncState,
    mode: Mode,
) -> Result<(Report, SyncState, bool)> {
    let summaries = client.list_pages(&args.workspace, &args.project).await?;
    let listed = summaries.len();
    let selected = select_pages(summaries, &args.include)?;

    let mut report = Report {
        listed,
        matched: selected.len(),
        ..Report::default()
    };
    let mut new_state = old_state.clone();

    for page in selected {
        let disk = read_disk(dest_root, &page.path)?;
        let base = old_state.pages.get(&page.path);
        // A 304 can only prove something when there is a file to compare
        // against; a missing file always needs the full body.
        let etag_hint = if disk.is_some() {
            base.and_then(|entry| entry.etag.as_deref())
        } else {
            None
        };
        let read = client
            .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,
            body.as_deref().map(|b: &str| b.as_bytes()),
        );
        if matches!(decision, Classification::Divergent(_)) && args.force && body.is_none() {
            // A 304 proves the server is unchanged, but --force still needs
            // the bytes to overwrite the divergent file.
            let refetch = client
                .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,
                body.as_deref().map(|b: &str| b.as_bytes()),
            );
        }
        record_decision(
            &mut report,
            &mut new_state,
            page,
            disk.as_deref(),
            body,
            Versions {
                etag: read.etag,
                page_id,
            },
            decision,
            args.force,
        )?;
    }

    report.bytes_to_write = report
        .writes
        .iter()
        .map(|write| write.body.len() as u64)
        .sum();

    let applied = mode == Mode::Apply && (report.divergent.is_empty() || args.force);
    if applied {
        for write in &report.writes {
            if !write_if_unchanged(
                dest_root,
                &write.path,
                write.expected_disk.as_deref(),
                write.body.as_bytes(),
            )? {
                bail!(
                    "{} changed in the repository during this run; left untouched. \
                     Earlier exports may have completed; export state was not advanced",
                    write.path
                );
            }
        }
        // Only after the whole batch is on disk does the state move: a
        // crash mid-batch leaves the old state, and the next run's
        // classification adopts any file that already matches the server.
        state::save(dest_root, &new_state)?;
    }
    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,
    new_state: &mut SyncState,
    page: PageSummary,
    disk: Option<&[u8]>,
    body: Option<String>,
    versions: Versions,
    decision: Classification,
    force: bool,
) -> Result<()> {
    let Versions { etag, page_id } = versions;
    match decision {
        Classification::Unchanged => {
            if let Some(body) = &body {
                // The file already equals the server (for example after a
                // crash between write and state save): adopt it.
                new_state.pages.insert(
                    page.path.clone(),
                    PageState {
                        hash: state::sha256_hex(body.as_bytes()),
                        etag,
                        page_id,
                    },
                );
            }
            report.unchanged.push(page.path.clone());
        }
        Classification::Write(kind) => {
            let Some(body) = body else {
                bail!(
                    "server returned 304 Not Modified for {} although no destination \
                     file exists; cannot classify the page",
                    page.path
                );
            };
            new_state.pages.insert(
                page.path.clone(),
                PageState {
                    hash: state::sha256_hex(body.as_bytes()),
                    etag: etag.clone(),
                    page_id: page_id.clone(),
                },
            );
            report.writes.push(PlannedWrite {
                kind,
                path: page.path.clone(),
                title: page.title,
                body,
                etag,
                expected_disk: disk.map(state::sha256_hex),
            });
        }
        Classification::Divergent(reason) => {
            let summary = diff_summary(disk, body.as_deref().map(|b: &str| b.as_bytes()));
            report.divergent.push(Divergence {
                path: page.path.clone(),
                reason,
                summary,
            });
            if force {
                // --force only ever overwrites with server content; the
                // tool still never deletes anything.
                if let Some(body) = &body {
                    new_state.pages.insert(
                        page.path.clone(),
                        PageState {
                            hash: state::sha256_hex(body.as_bytes()),
                            etag: etag.clone(),
                            page_id,
                        },
                    );
                    report.writes.push(PlannedWrite {
                        kind: WriteKind::Forced,
                        path: page.path.clone(),
                        title: page.title.clone(),
                        body: body.clone(),
                        etag,
                        expected_disk: disk.map(state::sha256_hex),
                    });
                }
            }
        }
    }
    Ok(())
}

fn print_report(args: &RunArgs, report: &Report, mode: Mode, families: &[String], applied: bool) {
    println!(
        "ai-memory-wikisync: {}/{} -> {}",
        args.workspace,
        args.project,
        args.dest.display()
    );
    println!(
        "  allowlist: {}; server listed {} page(s), {} in allowlisted families",
        families.join(", "),
        report.listed,
        report.matched
    );
    for write in &report.writes {
        println!(
            "  {:<9} {} ({} bytes) {:?}",
            write.kind.label(),
            write.path,
            write.body.len(),
            write.title
        );
    }
    for path in &report.unchanged {
        println!("  {:<9} {path}", "unchanged");
    }
    for divergence in &report.divergent {
        println!(
            "  {:<9} {} — {} ({})",
            "REFUSED",
            divergence.path,
            divergence.reason.describe(),
            divergence.summary
        );
    }
    println!(
        "  plan: {} create, {} update, {} unchanged, {} refused; {} bytes to write",
        report.count(WriteKind::Create),
        report.count(WriteKind::Update),
        report.unchanged.len(),
        report.divergent.len(),
        report.bytes_to_write
    );
    match mode {
        Mode::Plan => println!("  dry run: `plan` never writes files or state"),
        Mode::DryRun => println!("  dry run: no files were written (pass --apply to export)"),
        Mode::Apply if applied => {}
        Mode::Apply => println!("  nothing was written"),
    }
}

pub(crate) fn print_git_hints(args: &RunArgs) {
    println!(
        "this tool never runs git; to commit the export you may run:\
         \n  git add -- {}\
         \n  git commit -m \"chore(wikisync): export team wiki from {}/{}\"\
         \n  git push",
        args.dest.display(),
        args.workspace,
        args.project
    );
}

/// Validate the destination root. `Apply` creates a missing directory;
/// dry-run modes never touch the filesystem, so for them a missing
/// destination is simply an empty destination (validated only lexically).
pub(crate) fn resolve_dest(dest: &Path, mode: Mode) -> Result<PathBuf> {
    match mode {
        Mode::Apply => paths::prepare_dest(dest),
        Mode::Plan | Mode::DryRun => {
            if dest.exists() {
                paths::prepare_dest(dest)
            } else {
                Ok(paths::lexical_absolute(dest))
            }
        }
    }
}

/// Entry point behind both CLI subcommands.
pub async fn run(args: &RunArgs, mode: Mode) -> Result<()> {
    let families = validate_allowlist(&args.include)?;
    let dest_root = resolve_dest(&args.dest, mode)?;
    let _write_lock = (mode == Mode::Apply)
        .then(|| state::acquire_write_lock(&dest_root))
        .transpose()?;
    let scope = state::SyncScope::of(&args.server, &args.workspace, &args.project);
    let old_state = baseline_for(state::load(&dest_root)?, &scope, args.adopt_scope)?;
    let client = ApiClient::new(&args.server, args.token.clone())?;

    let (report, _new_state, applied) =
        run_batch(&client, args, &dest_root, &old_state, mode).await?;

    print_report(args, &report, mode, &families, applied);

    if mode == Mode::Apply && !report.divergent.is_empty() && !args.force {
        bail!(
            "{} file(s) diverged locally since the last export; nothing was written. \
             Inspect the diff summaries above, restore the files, or re-run with --force",
            report.divergent.len()
        );
    }
    if mode == Mode::Apply && applied {
        print_git_hints(args);
    }
    Ok(())
}

#[cfg(test)]
mod tests {
    use super::*;

    fn base(hash: &str, etag: Option<&str>) -> PageState {
        PageState {
            hash: hash.to_string(),
            etag: etag.map(str::to_owned),
            page_id: None,
        }
    }

    #[test]
    fn classify_three_way_matrix() {
        let disk = b"# page\nbody\n";
        let disk_hash = state::sha256_hex(disk);
        let server = b"# page\nbody\n";
        let edited = b"# page\nedited\n";

        // No file: always a create, even when the server is unchanged.
        assert_eq!(
            classify(None, None, Some(server)),
            Classification::Write(WriteKind::Create)
        );
        assert_eq!(
            classify(None, Some(&base(&disk_hash, None)), Some(server)),
            Classification::Write(WriteKind::Create)
        );

        // File equals server: unchanged, with or without a base entry.
        assert_eq!(
            classify(Some(disk), None, Some(server)),
            Classification::Unchanged
        );
        assert_eq!(
            classify(Some(disk), Some(&base("other", None)), Some(server)),
            Classification::Unchanged
        );

        // File equals base: 304 keeps it current, a new body fast-forwards.
        assert_eq!(
            classify(Some(disk), Some(&base(&disk_hash, None)), None),
            Classification::Unchanged
        );
        assert_eq!(
            classify(Some(disk), Some(&base(&disk_hash, None)), Some(edited)),
            Classification::Write(WriteKind::Update)
        );

        // File differs from base and server: divergent, never a winner.
        assert_eq!(
            classify(Some(edited), Some(&base(&disk_hash, None)), Some(server)),
            Classification::Divergent(DivergentReason::LocalEdit)
        );
        assert_eq!(
            classify(Some(edited), Some(&base(&disk_hash, None)), None),
            Classification::Divergent(DivergentReason::LocalEdit)
        );
        assert_eq!(
            classify(Some(edited), None, Some(server)),
            Classification::Divergent(DivergentReason::UnknownFile)
        );
    }

    #[test]
    fn diff_summary_points_at_first_difference() {
        let disk = b"one\ntwo local\nthree\n";
        let server = b"one\ntwo server\nthree\n";
        let summary = diff_summary(Some(disk), Some(server));
        assert!(summary.contains("line 2"), "{summary}");
        assert!(summary.contains("local"), "{summary}");
        let revalidated = diff_summary(Some(disk), None);
        assert!(revalidated.contains("revalidated by ETag"), "{revalidated}");
    }

    #[test]
    fn diff_summary_reports_appended_and_removed_lines() {
        type Case<'a> = (&'a [u8], &'a [u8], usize, &'a str, &'a str);
        let cases: &[Case<'_>] = &[
            (b"one", b"one\nextra", 2, "<end of file>", "\"extra\""),
            (b"one\nextra", b"one", 2, "\"extra\"", "<end of file>"),
            (b"one\n", b"one\nextra\n", 2, "\"\"", "\"extra\""),
            (b"one\nextra\n", b"one\n", 2, "\"extra\"", "\"\""),
            (b"", b"extra", 1, "\"\"", "\"extra\""),
            (b"extra", b"", 1, "\"extra\"", "\"\""),
            (b"one", b"one\n", 2, "<end of file>", "\"\""),
            (b"one\n", b"one", 2, "\"\"", "<end of file>"),
            (b"", b"\n", 2, "<end of file>", "\"\""),
            (b"\n", b"", 2, "\"\"", "<end of file>"),
            (
                b"one",
                b"one\n<end of file>",
                2,
                "<end of file>",
                "\"<end of file>\"",
            ),
        ];
        for (disk, server, line, local_preview, server_preview) in cases {
            let summary = diff_summary(Some(disk), Some(server));
            let expected = format!(
                "first difference at line {line}: local {local_preview} vs server {server_preview}"
            );
            assert!(summary.ends_with(&expected), "{summary}");
        }
    }

    #[test]
    fn diff_summary_counts_a_final_unterminated_line() {
        type Case<'a> = (&'a [u8], &'a [u8], &'a str);
        let cases: &[Case<'_>] = &[
            (
                b"one",
                b"one\nextra",
                "local 3 bytes/1 lines vs server 9 bytes/2 lines",
            ),
            (
                b"one\n",
                b"one\nextra\n",
                "local 4 bytes/1 lines vs server 10 bytes/2 lines",
            ),
            // Control: an empty file has no final line to count.
            (
                b"",
                b"extra",
                "local 0 bytes/0 lines vs server 5 bytes/1 lines",
            ),
        ];
        for (disk, server, expected) in cases {
            let summary = diff_summary(Some(disk), Some(server));
            assert!(summary.starts_with(expected), "{summary}");
        }

        // A difference inside both files must not sit past a reported count.
        let summary = diff_summary(Some(b"---\n---\nbody"), Some(b"---\n---\nbodyX"));
        assert!(
            summary.starts_with("local 12 bytes/3 lines vs server 13 bytes/3 lines"),
            "{summary}"
        );
        assert!(summary.contains("first difference at line 3"), "{summary}");
    }

    #[test]
    fn diff_summary_keeps_previews_bounded_and_printable() {
        let mut disk = vec![b'a'; 57];
        disk.extend_from_slice("é\x1b[31mhidden".as_bytes());
        let summary = diff_summary(Some(&disk), Some(b"changed"));
        let expected = format!("local \"{}???\" vs server \"changed\"", "a".repeat(57));
        assert!(summary.ends_with(&expected), "{summary}");
        assert!(!summary.contains('\x1b'), "{summary}");
    }

    #[test]
    fn atomic_write_replaces_and_never_deletes_siblings() {
        let tmp = tempfile::tempdir().unwrap();
        let root = tmp.path().canonicalize().unwrap();
        atomic_write(&root, "notes/a.md", b"v1").unwrap();
        assert_eq!(fs::read(root.join("notes/a.md")).unwrap(), b"v1");
        atomic_write(&root, "notes/a.md", b"v2").unwrap();
        assert_eq!(fs::read(root.join("notes/a.md")).unwrap(), b"v2");
        // No tmp artifacts left next to the page.
        let names: Vec<String> = fs::read_dir(root.join("notes"))
            .unwrap()
            .flatten()
            .map(|entry| entry.file_name().to_string_lossy().into_owned())
            .collect();
        assert_eq!(names, vec!["a.md".to_string()]);
    }

    #[test]
    fn allowlist_must_be_explicit() {
        assert!(validate_allowlist(&[]).is_err());
        let err = validate_allowlist(&["*".to_string()])
            .unwrap_err()
            .to_string();
        assert!(err.contains("must be explicit"), "{err}");
        let both = validate_allowlist(&[
            "notes".to_string(),
            "notes".to_string(),
            "decisions".to_string(),
        ])
        .unwrap();
        assert_eq!(both, vec!["notes".to_string(), "decisions".to_string()]);
    }

    fn summary(path: &str) -> PageSummary {
        PageSummary {
            path: path.to_string(),
            title: format!("title {path}"),
            kind: "note".to_string(),
            tier: "semantic".to_string(),
            updated_at: "2026-10-01T00:00:00Z".to_string(),
        }
    }

    #[test]
    fn select_pages_filters_families_and_dedupes() {
        let families = vec!["notes".to_string()];
        let selected = select_pages(
            vec![
                summary("notes/a.md"),
                summary("notes/a.md"),
                summary("decisions/skip.md"),
                summary("notes/b.md"),
            ],
            &families,
        )
        .unwrap();
        let paths: Vec<&str> = selected.iter().map(|p| p.path.as_str()).collect();
        assert_eq!(paths, vec!["notes/a.md", "notes/b.md"]);

        // A hostile server cannot smuggle traversal through the listing.
        let err = select_pages(vec![summary("notes/../escape.md")], &families)
            .unwrap_err()
            .to_string();
        assert!(err.contains("refused"), "{err}");
    }
}