Skip to content

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

Rust
382 KB
Raw Blame
//! [`Wiki`] — the only correct write path for the markdown source-of-truth.

use std::collections::{HashMap, HashSet};
use std::path::{Path, PathBuf};
use std::sync::{Arc, Mutex};

use ai_memory_core::{
    ActorContext, AutoImproveProposalId, NewPage, PageId, PagePath, ProjectId, Sanitizer,
    SessionId, Tier, UserId, WorkspaceId,
};
use ai_memory_llm::Embedder;
use ai_memory_store::{
    ApproveAutoImproveProposal, ApproveAutoImproveProposalResult, AutoImproveProposalDetail,
    ConditionalBatchUpsert, ConditionalUpsert, FailAutoImproveProposal, MergeProjectPage,
    MoveSessionSummary, MoveSummary, PagePrecondition, PagesMode, PurgeSessionSummary, ReaderPool,
    ScopeRow, WriterHandle, artifact_path_for, f32_vec_to_bytes,
};
use tokio::sync::RwLock;

use crate::admission::{AdmissionChain, AdmissionContext, AdmissionOp, is_admission_unavailable};
use crate::confinement::{
    Prepare, project_path, project_root as confined_project_root, tree_path, workspace_path,
};
use crate::error::{WikiError, WikiResult};
use crate::git::{Checkpoint, GitAdapter};
use crate::markdown::{Markdown, derive_title, emit, parse};
use crate::watcher::is_pending_path;

/// Store deletion and best-effort file cleanup from [`Wiki::purge_session`].
#[derive(Debug, Clone)]
pub struct PurgeSessionOutcome {
    /// Committed database deletion counts and paths.
    pub summary: PurgeSessionSummary,
    /// Paths successfully removed from disk.
    pub files_deleted: Vec<PagePath>,
    /// Paths whose file cleanup failed after the database committed.
    pub files_failed: Vec<PagePath>,
}

/// One hook event ledger (`log-YYYY-MM.md`) found in a project's wiki
/// directory by [`Wiki::list_event_ledgers`].
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct EventLedgerFile {
    /// File name inside the project directory, e.g. `log-2026-07.md`.
    pub file_name: String,
    /// Size on disk, in bytes.
    pub bytes: u64,
}

/// One source page prepared for [`Wiki::merge_project`].
#[derive(Debug, Clone)]
pub struct MergeProjectFile {
    /// Store-level compare-and-write and merged-version plan.
    pub store: MergeProjectPage,
    /// Fully emitted Markdown for a same-path collision. `None` means the
    /// source file is installed unchanged at the target path.
    pub merged_markdown: Option<String>,
}

fn copy_tree(git: &GitAdapter, source: &Path, target: &Path) -> WikiResult<()> {
    if !source.exists() {
        return Ok(());
    }
    std::fs::create_dir_all(target)?;
    for entry in std::fs::read_dir(source)? {
        let entry = entry?;
        let metadata = entry.file_type()?;
        if metadata.is_symlink() {
            return Err(WikiError::Io(std::io::Error::other(format!(
                "refusing symlink while copying project tree: {}",
                entry.path().display()
            ))));
        }
        let destination = target.join(entry.file_name());
        if metadata.is_dir() {
            copy_tree(git, &entry.path(), &destination)?;
        } else if metadata.is_file() {
            git.write_atomic(&destination, &std::fs::read(entry.path())?)?;
        }
    }
    Ok(())
}

fn copy_tree_missing(git: &GitAdapter, source: &Path, target: &Path) -> WikiResult<()> {
    if !source.exists() {
        return Ok(());
    }
    std::fs::create_dir_all(target)?;
    for entry in std::fs::read_dir(source)? {
        let entry = entry?;
        let metadata = entry.file_type()?;
        if metadata.is_symlink() {
            return Err(WikiError::Io(std::io::Error::other(format!(
                "refusing symlink while merging project tree: {}",
                entry.path().display()
            ))));
        }
        let destination = target.join(entry.file_name());
        if metadata.is_dir() {
            copy_tree_missing(git, &entry.path(), &destination)?;
        } else if metadata.is_file() && !destination.exists() {
            git.write_atomic(&destination, &std::fs::read(entry.path())?)?;
        } else if metadata.is_file()
            && entry
                .file_name()
                .to_str()
                .is_some_and(|name| name.starts_with("log-") && name.ends_with(".md"))
        {
            let bytes = std::fs::read(entry.path())?;
            git.append(&destination, &bytes)?;
        }
    }
    Ok(())
}

fn event_ledger_metadata(abs: &Path) -> WikiResult<Option<std::fs::Metadata>> {
    let metadata = match std::fs::symlink_metadata(abs) {
        Ok(metadata) => metadata,
        Err(e) if e.kind() == std::io::ErrorKind::NotFound => return Ok(None),
        Err(e) => return Err(e.into()),
    };
    if !metadata.is_file()
        || crate::confinement::is_link_like(&metadata)
        || !crate::ledger::opens_with_log_ledger(abs)
    {
        return Ok(None);
    }
    Ok(Some(metadata))
}

/// Summary of a [`Wiki::reindex_all`] run.
#[derive(Debug, Default, Clone)]
pub struct ReindexSummary {
    /// Workspaces recreated from `_meta.md`.
    pub workspaces: usize,
    /// Projects recreated from `_meta.md`.
    pub projects: usize,
    /// Pages reindexed from the wiki tree.
    pub pages: usize,
    /// Project directories skipped because their scope was purged and
    /// tombstoned (#607) — a purge whose on-disk removal did not complete.
    /// Their pages are deliberately not resurrected.
    pub skipped_purged: usize,
    /// Session pages skipped because the session was purged and tombstoned
    /// (#701) — the same case one level down, for a purge whose page-file
    /// removal did not complete.
    pub skipped_purged_sessions: usize,
    /// Pages skipped because another page in the same scope differs from them
    /// only by case or Unicode normalization. A wiki authored on a
    /// case-sensitive filesystem can hold such a pair; indexing both is what
    /// the write guard now refuses, and one bad pair must not fail the whole
    /// rebuild.
    pub skipped_collisions: usize,
}

/// The session a page belongs to, for paths that name one.
///
/// Pure path shape, no I/O. Used to keep session-summary paths out of the
/// missing-file retirement safety net. Reindex ownership and tombstone
/// checks belong to the store transaction, not this path-only classifier.
pub(crate) fn session_id_for_page(path: &PagePath) -> Option<SessionId> {
    path.as_str()
        .strip_prefix("sessions/")
        .and_then(|rest| rest.strip_suffix(".md"))
        .and_then(|id| id.parse::<SessionId>().ok())
}

enum PageStoreRemoval {
    Delete {
        author_id: Option<UserId>,
        expected_latest_id: Option<PageId>,
    },
    Decay {
        expected_latest_id: PageId,
    },
}

/// Most commits [`Wiki::page_checkpoints`] inspects for one page. A
/// checkpoint is one commit per write or consolidation pass, so this covers a
/// long history while keeping a lookup on a page nobody touched lately bounded.
pub const PAGE_CHECKPOINT_WALK_LIMIT: usize = 5_000;

/// Body + optional L0 abstract text a caller of `reindex_page_locked` should
/// embed once it is safe to do so (i.e. after releasing whatever lock it
/// took to call in). Captured before `upsert_page` moves `md.body` /
/// `md.frontmatter`, and only constructed when the reindex actually produced
/// a new page version worth embedding.
struct PendingEmbed {
    body: String,
    abstract_text: Option<String>,
}

/// What [`Wiki::move_session_page`] did with the on-disk
/// `sessions/<session_id>.md` file of the moved session.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum SessionPageFile {
    /// Renamed from the source project directory into the destination one
    /// ([`PagesMode::Move`]).
    Moved,
    /// Removed from the source project directory ([`PagesMode::Regenerate`]),
    /// so the watcher cannot re-index it as a live page after its rows were
    /// retired; the next consolidation writes a fresh page in the destination.
    Removed,
    /// No file existed in the source project directory.
    Absent,
}

/// Result of [`Wiki::move_session_page`]: the store summary plus what
/// happened to the page file.
#[derive(Debug, Clone)]
pub struct MoveSessionOutcome {
    /// Row counts and scopes as reported by the store re-stamp.
    pub summary: MoveSessionSummary,
    /// Disposition of the on-disk session page file.
    pub file: SessionPageFile,
}

/// Wiki filesystem handle.
///
/// Owns the path of the wiki root (`<data_dir>/wiki/`) and a cloneable
/// [`WriterHandle`] so that every public mutation writes the markdown
/// file *and* sends a `WriteCmd::UpsertPage` to the store in a single
/// call — no background-task indexing-after-return (basic-memory #763
/// lesson).
///
/// ## On-disk layout
///
/// Pages are stored at `<wiki_root>/<workspace_id>/<project_id>/<page-path>`.
/// Each of `workspace_id` and `project_id` is a UUID string. This layout is
/// the single canonical namespace; all path construction must go through
/// [`Wiki::project_root`] or [`Wiki::abs_path`] — never hand-rolled joins.
#[derive(Clone)]
pub struct Wiki {
    root: PathBuf,
    writer: WriterHandle,
    git: GitAdapter,
    embedder: Option<Arc<dyn Embedder>>,
    /// Privacy strip applied to every page body before persistence.
    /// Defence-in-depth: any caller path (LLM consolidation, manual
    /// write-page CLI, agent-supplied tool input) still gets scrubbed
    /// at the wiki boundary even if upstream forgot.
    sanitizer: Sanitizer,
    /// Optional HTTP webhook chain invoked just before page persistence.
    /// When configured, each `write_page` call POSTs the (path, frontmatter,
    /// body, ctx) tuple to every webhook subscribing to the op; webhooks
    /// may mutate frontmatter/body before the atomic write hits disk.
    /// Set via [`Wiki::with_admission_chain`]; see [`crate::admission`].
    admission_chain: Option<AdmissionChain>,
    /// Optional store reader used to resolve `workspace_id`/`project_id`
    /// into human names for the [`AdmissionContext`] passed to webhooks.
    /// Set via [`Wiki::with_store_reader`]; when unset, webhooks receive
    /// empty `workspace`/`project` strings and must fall back to
    /// IDs/headers/`_unscoped` paths.
    store_reader: Option<ReaderPool>,
    /// Process-local gate around filesystem mutations. Page writes/reindexes
    /// take a shared guard; project true-move takes the exclusive guard across
    /// the directory rename and SQLite re-stamp so stale writes cannot land
    /// files under the old workspace while the project is in flight.
    mutation_lock: Arc<RwLock<()>>,
    /// Per-page write serialization (#607, item 3). Two concurrent writes to
    /// the *same* `(ws, proj, path)` would otherwise interleave their
    /// file-rename and DB-upsert under the shared `mutation_lock` read guard,
    /// transiently leaving on-disk markdown disagreeing with the DB `latest`
    /// row. Each path gets its own async mutex, so same-path writers serialize
    /// while different paths still run concurrently. The map is GC'd
    /// opportunistically — entries no writer currently holds are dropped on the
    /// next acquisition — so it stays bounded to currently-contended paths.
    /// Reindexes share it from disk read through SQL upsert.
    page_locks: Arc<std::sync::Mutex<HashMap<PageKey, Arc<tokio::sync::Mutex<()>>>>>,
    #[cfg(test)]
    reindex_read_barrier: Option<Arc<tokio::sync::Barrier>>,
    /// Scopes this process has already materialized `_meta.md` manifests for.
    /// Keeps [`Wiki::ensure_scope_manifests`] to one hash lookup per page
    /// write after the scope's first — the store query and the two manifest
    /// reads happen once per scope per process, never per page.
    manifested_scopes: Arc<Mutex<HashSet<(WorkspaceId, ProjectId)>>>,
    /// `[maintenance] reconcile_tombstones_deleted_pages` (#929), read once by
    /// `Config::load` and threaded here via [`Wiki::with_reconcile_tombstones_deleted_pages`].
    /// OFF by default: with this `false`, the watcher's reconcile pass never
    /// tombstones a page whose file vanished — deletions still require
    /// `ai-memory delete-page`, unchanged from before this feature existed.
    reconcile_tombstones_deleted_pages: bool,
}

/// Key uniquely identifying a page for per-path write serialization.
type PageKey = (WorkspaceId, ProjectId, PagePath);

impl Wiki {
    /// Construct a wiki handle rooted at `<data_dir>/wiki/`. Creates the
    /// directory if absent and initialises a git repo inside it.
    ///
    /// # Errors
    /// Returns [`WikiError::Io`] if the wiki root or git repo cannot be
    /// created.
    pub fn new(data_dir: &Path, writer: WriterHandle) -> WikiResult<Self> {
        let root = data_dir.join("wiki");
        crate::confinement::initialize_root(&root)?;
        let git = GitAdapter::open_or_init(&root)?;
        Ok(Self {
            root,
            writer,
            git,
            embedder: None,
            sanitizer: Sanitizer::builtin(),
            admission_chain: None,
            store_reader: None,
            mutation_lock: Arc::new(RwLock::new(())),
            page_locks: Arc::new(std::sync::Mutex::new(HashMap::new())),
            #[cfg(test)]
            reindex_read_barrier: None,
            manifested_scopes: Arc::new(Mutex::new(HashSet::new())),
            reconcile_tombstones_deleted_pages: false,
        })
    }

    /// Attach an admission webhook chain. When set, every `write_page` call
    /// invokes the chain after the [`Markdown`] is built but before the
    /// atomic write — webhooks may mutate frontmatter/body. An empty chain
    /// is a no-op (skipped without HTTP overhead).
    #[must_use]
    pub fn with_admission_chain(mut self, chain: AdmissionChain) -> Self {
        if !chain.is_empty() {
            self.admission_chain = Some(chain);
        }
        self
    }

    /// Attach a store reader so the admission chain receives
    /// human-readable `workspace`/`project` names in its context, resolved
    /// from the `workspace_id`/`project_id` carried on the
    /// [`WritePageRequest`]. Without this, those fields stay empty and
    /// external webhooks must fall back to header introspection or use
    /// `_unscoped` placeholders.
    ///
    /// The reader is also what makes a scope self-describing: the names a
    /// `_meta.md` manifest carries are resolved through it, so without one
    /// neither [`Self::backfill_scope_manifests`] nor the manifest written
    /// with a scope's first page can run, and both become no-ops. For the
    /// admission chain specifically the reader is still only consulted when
    /// a chain is configured and would actually fire.
    #[must_use]
    pub fn with_store_reader(mut self, reader: ReaderPool) -> Self {
        self.store_reader = Some(reader);
        self
    }

    /// Opt into the watcher reconcile pass's tombstone-on-missing-file safety
    /// net (`[maintenance] reconcile_tombstones_deleted_pages`, #929). `false`
    /// (the default from [`Wiki::new`]) leaves reconcile's behavior exactly
    /// as it was before this feature: deletions require `ai-memory
    /// delete-page`.
    #[must_use]
    pub fn with_reconcile_tombstones_deleted_pages(mut self, enabled: bool) -> Self {
        self.reconcile_tombstones_deleted_pages = enabled;
        self
    }

    /// Whether the watcher's reconcile pass may tombstone a page whose file
    /// disappeared. See [`Wiki::with_reconcile_tombstones_deleted_pages`].
    #[must_use]
    pub(crate) fn reconcile_tombstones_deleted_pages(&self) -> bool {
        self.reconcile_tombstones_deleted_pages
    }

    /// Replace the default built-in-only sanitizer with one carrying
    /// the operator's `[sanitize].extra_patterns` + `allowlist`.
    #[must_use]
    pub fn with_sanitizer(mut self, sanitizer: Sanitizer) -> Self {
        self.sanitizer = sanitizer;
        self
    }

    /// Borrow the configured sanitizer, so components holding a `Wiki`
    /// (e.g. the consolidator scrubbing project-provided prompt
    /// preferences) reuse the operator's patterns instead of
    /// constructing a second, built-in-only instance.
    #[must_use]
    pub fn sanitizer(&self) -> &Sanitizer {
        &self.sanitizer
    }

    /// Send a browser-composed message through sanitization, admission and
    /// the single writer. Callers must authorize both project coordinates.
    pub async fn send_agent_message(
        &self,
        mut message: ai_memory_core::NewAgentMessage,
        actor: ActorContext,
    ) -> WikiResult<ai_memory_core::MessageId> {
        message.body = self
            .sanitizer
            .scrub(&message.body)
            .chars()
            .take(8_000)
            .collect();
        message.subject = message
            .subject
            .map(|s| self.sanitizer.scrub(&s).chars().take(200).collect());
        let admission = self
            .authorize_operation(
                message.to_workspace_id,
                message.to_project_id,
                AdmissionOp::MessageSend,
                actor,
                Vec::new(),
            )
            .await?;
        let id = self.writer.insert_message(message).await?;
        if let Some(ctx) = admission.as_ref() {
            self.notify_operation_observers(ctx);
        }
        Ok(id)
    }

    /// Take a pending message out of its recipient's queue so its sender can
    /// edit it. Until it is saved or released no harness can collect it.
    /// Returns `None` when the message is not pending in that project.
    /// Callers must authorize both project coordinates.
    pub async fn begin_agent_message_edit(
        &self,
        to_workspace_id: ai_memory_core::WorkspaceId,
        to_project_id: ai_memory_core::ProjectId,
        id: ai_memory_core::MessageId,
    ) -> WikiResult<Option<ai_memory_core::AgentMessage>> {
        Ok(self
            .writer
            .begin_message_edit(to_workspace_id, to_project_id, id)
            .await?)
    }

    /// Return a held message to the queue unchanged. Returns `false` when it
    /// is not being edited in that project.
    pub async fn release_agent_message_edit(
        &self,
        to_workspace_id: ai_memory_core::WorkspaceId,
        to_project_id: ai_memory_core::ProjectId,
        id: ai_memory_core::MessageId,
    ) -> WikiResult<bool> {
        Ok(self
            .writer
            .finish_message_edit(to_workspace_id, to_project_id, id, None)
            .await?)
    }

    /// Save new text for a held message and return it to the queue. The text
    /// goes through the same sanitization, size caps and `message_send`
    /// admission as a new message. Returns `false` when the message is not
    /// being edited in that project.
    pub async fn save_agent_message_edit(
        &self,
        to_workspace_id: ai_memory_core::WorkspaceId,
        to_project_id: ai_memory_core::ProjectId,
        id: ai_memory_core::MessageId,
        subject: Option<String>,
        body: String,
        actor: ActorContext,
    ) -> WikiResult<bool> {
        let body: String = self.sanitizer.scrub(&body).chars().take(8_000).collect();
        let subject =
            subject.map(|s| -> String { self.sanitizer.scrub(&s).chars().take(200).collect() });
        let admission = self
            .authorize_operation(
                to_workspace_id,
                to_project_id,
                AdmissionOp::MessageSend,
                actor,
                Vec::new(),
            )
            .await?;
        let saved = self
            .writer
            .finish_message_edit(to_workspace_id, to_project_id, id, Some((subject, body)))
            .await?;
        if saved && let Some(ctx) = admission.as_ref() {
            self.notify_operation_observers(ctx);
        }
        Ok(saved)
    }

    /// Attach an embedder. When set, every page-writing path (`write_page`,
    /// `apply_batch`, auto-improvement approval, checkpoint restore and the
    /// watcher's reindex) computes + stores an embedding for the new version
    /// on the caller's task, after its mutation guard is released; a
    /// provider failure is recorded and leaves the page to admin or
    /// scheduled embedding backfill. Without an embedder,
    /// vector search is skipped and `ReaderPool::hybrid_search` uses
    /// FTS5 + entity + graph expansion.
    #[must_use]
    pub fn with_embedder(mut self, embedder: Arc<dyn Embedder>) -> Self {
        self.embedder = Some(embedder);
        self
    }

    /// Borrow the optional embedder (used by the `ai-memory embed`
    /// backfill command).
    #[must_use]
    pub fn embedder(&self) -> Option<&Arc<dyn Embedder>> {
        self.embedder.as_ref()
    }

    /// Return a clone-friendly handle with the embedder detached, so
    /// `write_page` skips the per-page `embed_document` call. Used by
    /// bulk copy paths (e.g. `move-project`) that carry the source page's
    /// existing embedding over verbatim instead of recomputing it — the
    /// caller is then responsible for `store_embedding` on the new page.
    #[must_use]
    pub fn without_embedder(mut self) -> Self {
        self.embedder = None;
        self
    }

    /// Borrow the git adapter (for callers wiring auto-commit).
    #[must_use]
    pub fn git(&self) -> &GitAdapter {
        &self.git
    }

    /// Stage + commit the entire wiki tree. Returns `Ok(None)` if there
    /// was nothing to commit.
    ///
    /// # Errors
    /// Propagates [`WikiError`] from the git adapter.
    pub fn commit_all(&self, message: &str) -> WikiResult<Option<git2::Oid>> {
        self.inspect_wiki_tree()?;
        self.git.commit_all(message)
    }

    /// Append `bytes` to `<project root>/<file_name>` (the hook ledger)
    /// and report the write.
    ///
    /// # Errors
    /// Propagates the filesystem error.
    pub fn append_under_project(
        &self,
        workspace_id: WorkspaceId,
        project_id: ProjectId,
        file_name: &str,
        bytes: &[u8],
    ) -> std::io::Result<PathBuf> {
        self.append_under_project_checked(workspace_id, project_id, file_name, bytes)
            .map_err(crate::error::into_io_error)
    }

    pub(crate) fn append_under_project_checked(
        &self,
        workspace_id: WorkspaceId,
        project_id: ProjectId,
        file_name: &str,
        bytes: &[u8],
    ) -> WikiResult<PathBuf> {
        let path = project_path(
            &self.root,
            workspace_id,
            project_id,
            Path::new(file_name),
            Prepare::Parents,
        )?;
        self.git.append_checked(&path, bytes)?;
        Ok(path)
    }
    /// Return the most recent wiki git checkpoints, newest first.
    ///
    /// # Errors
    /// Propagates [`WikiError`] from the git adapter.
    pub fn recent_checkpoints(&self, limit: usize) -> WikiResult<Vec<Checkpoint>> {
        self.git.recent_checkpoints(limit)
    }

    /// Checkpoints, newest first, that changed one page (including the one
    /// that deleted it), so a caller can pick a `rev` to restore from.
    ///
    /// The history walk runs on the blocking pool and inspects at most
    /// [`PAGE_CHECKPOINT_WALK_LIMIT`] commits.
    ///
    /// # Errors
    /// Returns [`WikiError`] when the path escapes the project tree or git
    /// cannot be read.
    pub async fn page_checkpoints(
        &self,
        workspace_id: WorkspaceId,
        project_id: ProjectId,
        path: &PagePath,
        limit: usize,
    ) -> WikiResult<Vec<Checkpoint>> {
        self.confined_page_path(workspace_id, project_id, path, Prepare::Inspect)?;
        let rel = PathBuf::from(workspace_id.to_string())
            .join(project_id.to_string())
            .join(path.as_str());
        let git = self.git.clone();
        tokio::task::spawn_blocking(move || {
            git.path_checkpoints(&rel, limit, PAGE_CHECKPOINT_WALK_LIMIT)
        })
        .await
        .map_err(|e| WikiError::Io(std::io::Error::other(e.to_string())))?
    }

    /// Parse one page as stored at checkpoint `rev`, without touching the
    /// live tree or the index.
    ///
    /// # Errors
    /// Returns [`WikiError`] when the revision/path does not exist or the
    /// stored bytes are not parseable UTF-8 markdown.
    pub async fn page_at_checkpoint(
        &self,
        workspace_id: WorkspaceId,
        project_id: ProjectId,
        path: &PagePath,
        rev: &str,
    ) -> WikiResult<Markdown> {
        self.confined_page_path(workspace_id, project_id, path, Prepare::Inspect)?;
        let rel = PathBuf::from(workspace_id.to_string())
            .join(project_id.to_string())
            .join(path.as_str());
        let git = self.git.clone();
        let rev_owned = rev.to_owned();
        let bytes = tokio::task::spawn_blocking(move || git.file_at_rev(&rev_owned, &rel))
            .await
            .map_err(|e| WikiError::Io(std::io::Error::other(e.to_string())))??;
        let raw = String::from_utf8(bytes).map_err(|e| {
            WikiError::Io(std::io::Error::other(format!(
                "{} at {rev} is not valid UTF-8 markdown: {e}",
                path.as_str()
            )))
        })?;
        parse(&raw)
    }

    /// Create the one-time baseline checkpoint for an existing wiki tree that
    /// was created before git recovery checkpoints existed.
    ///
    /// Existing repos with any commit are left untouched. Fresh empty repos
    /// return `Ok(None)` because there is nothing to commit.
    ///
    /// # Errors
    /// Propagates [`WikiError`] from the git adapter.
    pub fn ensure_upgrade_baseline_checkpoint(&self) -> WikiResult<Option<git2::Oid>> {
        if self.git.commit_count_checked()? == 0 {
            self.commit_all("upgrade baseline: existing wiki tree before recovery checkpoints")
        } else {
            Ok(None)
        }
    }

    /// Path of the wiki root on disk.
    #[must_use]
    pub fn root(&self) -> &Path {
        &self.root
    }

    /// The data directory this wiki lives under (`<data_dir>/wiki` is
    /// the root, so this is its parent). Used by the web layer to read
    /// the pre-migration backup receipt.
    #[must_use]
    pub fn data_dir(&self) -> &Path {
        self.root.parent().unwrap_or(&self.root)
    }

    /// Resolve the on-disk root for a project: `<wiki_root>/<ws>/<proj>`.
    /// All page files for this project live under this directory.
    #[must_use]
    pub fn project_root(&self, workspace_id: WorkspaceId, project_id: ProjectId) -> PathBuf {
        self.root
            .join(workspace_id.to_string())
            .join(project_id.to_string())
    }

    /// Losslessly move a project to another workspace: rename its on-disk
    /// directory and re-stamp every store row that carries `workspace_id`, while
    /// keeping the same `project_id`.
    ///
    /// The exclusive mutation guard is held across both filesystem and store
    /// phases. That keeps in-process page writes/reindexes from observing the
    /// project half-moved; stale callers that still carry `(from_workspace,
    /// project_id)` only resume after the DB re-stamp and then fail the pair
    /// validator before touching disk.
    ///
    /// Ordering is rename-first, SQL-last so the DB is never ahead of disk. If
    /// the SQL re-stamp fails after a rename, the directory is renamed back.
    ///
    /// # Errors
    /// Returns [`WikiError`] if the destination directory already exists, the
    /// rename fails, the SQL re-stamp fails, or rollback fails.
    pub async fn move_project_workspace(
        &self,
        project_id: ProjectId,
        from_workspace: WorkspaceId,
        to_workspace: WorkspaceId,
        admission_ctx: Option<AdmissionContext>,
    ) -> WikiResult<MoveSummary> {
        self.inspect_project_tree(from_workspace, project_id)?;
        self.inspect_project_tree(to_workspace, project_id)?;
        let _guard = self.mutation_lock.write().await;
        self.inspect_project_tree(from_workspace, project_id)?;
        self.inspect_project_tree(to_workspace, project_id)?;
        let resolved_ctx = if let Some(chain) = &self.admission_chain {
            let mut ctx = admission_ctx.unwrap_or_default();
            ctx.op = AdmissionOp::MoveProject;
            self.resolve_admission_names(from_workspace, project_id, &mut ctx)
                .await;
            chain.notify(None, &ctx).await?;
            Some(ctx)
        } else {
            None
        };

        let src = self.confined_project_root(from_workspace, project_id, Prepare::Inspect)?;
        let dst = self.confined_project_root(to_workspace, project_id, Prepare::Parents)?;

        if dst.exists() {
            return Err(crate::WikiError::DestinationExists(
                dst.display().to_string(),
            ));
        }

        let renamed = if src.exists() {
            self.git.rename_checked(&src, &dst)?;
            true
        } else {
            // Nothing on disk to move (a project with zero written pages).
            false
        };

        match self
            .writer
            .move_project_workspace(project_id, from_workspace, to_workspace)
            .await
        {
            Ok(summary) => {
                if let (Some(chain), Some(ctx)) = (&self.admission_chain, &resolved_ctx) {
                    chain.dispatch_async(None, &serde_json::Value::Null, "", ctx);
                }
                Ok(summary)
            }
            Err(e) => {
                if renamed && let Err(rollback_err) = self.git.rename_checked(&dst, &src) {
                    return Err(crate::WikiError::Io(std::io::Error::other(format!(
                        "INCONSISTENT STATE: files moved but DB re-stamp failed ({e}) and dir rename-back also failed ({rollback_err}); manually move {} -> {} or finish the re-stamp",
                        dst.display(),
                        src.display()
                    ))));
                }
                Err(e.into())
            }
        }
    }

    /// Merge a source project tree into a target project in the same
    /// workspace while [`WriterHandle::merge_project`] atomically re-homes the
    /// indexed history. The target tree is snapshotted before files change and
    /// restored if the writer refuses, so disk never remains ahead of SQLite.
    ///
    /// # Errors
    /// Returns [`WikiError`] for an unsafe tree, I/O failure, admission
    /// rejection, or store precondition failure.
    pub async fn merge_project(
        &self,
        workspace_id: WorkspaceId,
        source_project: ProjectId,
        target_project: ProjectId,
        pages: Vec<MergeProjectFile>,
        admission_ctx: Option<AdmissionContext>,
    ) -> WikiResult<ai_memory_store::MergeProjectSummary> {
        let _guard = self.mutation_lock.write().await;
        self.inspect_project_tree(workspace_id, source_project)?;
        self.inspect_project_tree(workspace_id, target_project)?;
        let resolved_ctx = if let Some(chain) = &self.admission_chain {
            let mut ctx = admission_ctx.unwrap_or_default();
            ctx.op = AdmissionOp::MoveProject;
            self.resolve_admission_names(workspace_id, source_project, &mut ctx)
                .await;
            chain.notify(None, &ctx).await?;
            Some(ctx)
        } else {
            None
        };

        let source = self.confined_project_root(workspace_id, source_project, Prepare::Inspect)?;
        let target = self.confined_project_root(workspace_id, target_project, Prepare::Parents)?;
        let backup = target.with_file_name(format!(
            ".ai-memory-tmp.merge-{}-{}",
            target_project,
            PageId::new()
        ));
        let parked_source = source.with_file_name(format!(
            ".ai-memory-tmp.merge-source-{}-{}",
            source_project,
            PageId::new()
        ));
        if backup.exists() {
            return Err(WikiError::DestinationExists(backup.display().to_string()));
        }
        if parked_source.exists() {
            return Err(WikiError::DestinationExists(
                parked_source.display().to_string(),
            ));
        }
        if target.exists()
            && let Err(error) = copy_tree(&self.git, &target, &backup)
        {
            if backup.exists()
                && let Err(cleanup) = self.git.remove_dir_all(&backup)
            {
                tracing::warn!(
                    %cleanup,
                    path = %backup.display(),
                    "merge-project target snapshot failed and partial backup cleanup failed"
                );
            }
            return Err(error);
        }
        if source.exists()
            && let Err(error) = self.git.rename(&source, &parked_source)
        {
            if backup.exists()
                && let Err(cleanup) = self.git.remove_dir_all(&backup)
            {
                tracing::warn!(
                    %cleanup,
                    path = %backup.display(),
                    "merge-project source park failed and target backup cleanup failed"
                );
            }
            return Err(error.into());
        }

        let result = async {
            // Preserve non-page project artifacts too. Existing target files
            // win here; the explicit page plan below then installs every
            // source page or combined collision deterministically.
            if parked_source.exists() {
                copy_tree_missing(&self.git, &parked_source, &target)?;
            }
            for page in &pages {
                let destination = self.confined_page_path(
                    workspace_id,
                    target_project,
                    &page.store.path,
                    Prepare::Parents,
                )?;
                if let Some(rendered) = &page.merged_markdown {
                    self.git.write_atomic(&destination, rendered.as_bytes())?;
                } else {
                    let source_path = parked_source.join(page.store.path.as_str());
                    let bytes = std::fs::read(source_path)?;
                    self.git.write_atomic(&destination, &bytes)?;
                }
            }
            self.writer
                .merge_project(
                    workspace_id,
                    source_project,
                    target_project,
                    pages.iter().map(|page| page.store.clone()).collect(),
                    true,
                )
                .await
                .map_err(WikiError::Store)
        }
        .await;

        match result {
            Ok(summary) => {
                if parked_source.exists()
                    && let Err(error) = self.git.remove_dir_all(&parked_source)
                {
                    tracing::warn!(
                        %error,
                        path = %parked_source.display(),
                        "merge-project committed but watcher-ignored source cleanup failed"
                    );
                }
                if backup.exists()
                    && let Err(error) = self.git.remove_dir_all(&backup)
                {
                    tracing::warn!(
                        %error,
                        path = %backup.display(),
                        "merge-project committed but watcher-ignored target backup cleanup failed"
                    );
                }
                if let (Some(chain), Some(ctx)) = (&self.admission_chain, &resolved_ctx) {
                    chain.dispatch_async(None, &serde_json::Value::Null, "", ctx);
                }
                Ok(summary)
            }
            Err(error) => {
                let mut rollback_errors = Vec::new();
                if parked_source.exists()
                    && let Err(rollback) = self.git.rename(&parked_source, &source)
                {
                    rollback_errors
                        .push(format!("restore source {}: {rollback}", source.display()));
                }
                if target.exists()
                    && let Err(rollback) = self.git.remove_dir_all(&target)
                {
                    rollback_errors.push(format!(
                        "remove staged target {}: {rollback}",
                        target.display()
                    ));
                }
                if backup.exists()
                    && !target.exists()
                    && let Err(rollback) = self.git.rename(&backup, &target)
                {
                    rollback_errors
                        .push(format!("restore target {}: {rollback}", target.display()));
                }
                if rollback_errors.is_empty() {
                    Err(error)
                } else {
                    Err(WikiError::Io(std::io::Error::other(format!(
                        "INCONSISTENT STATE: merge-project failed ({error}) and rollback was incomplete: {}",
                        rollback_errors.join("; ")
                    ))))
                }
            }
        }
    }

    /// Move one session to another project: relocate its `sessions/<id>.md`
    /// file on disk and re-stamp its store rows in one transaction
    /// ([`WriterHandle::move_session`]).
    ///
    /// Same critical section and ordering as [`Self::move_project_workspace`]:
    /// the exclusive mutation guard is held across the admission chain, the
    /// file step and the store step; disk goes first and SQL last, so the DB
    /// is never ahead of disk. Under [`PagesMode::Move`] the file is renamed
    /// into the destination project directory (refused when a file already
    /// sits there). Under [`PagesMode::Regenerate`] the file is first parked
    /// under the watcher-ignored `.ai-memory-tmp.` prefix and deleted once the
    /// rows are retired: left in place, the next reconciliation pass would
    /// re-index it as a fresh latest page in the source scope. A store failure
    /// puts the file back where it was in both modes. When `from == to` (a
    /// re-home of a session already rooted in the destination) there is no
    /// file to relocate: the file step is skipped and only the store sweep
    /// runs.
    ///
    /// # Errors
    /// Returns [`WikiError::DestinationPageExists`] when the destination
    /// already holds a page file at that path, [`WikiError::Store`] for store
    /// refusals (`NotFound`, `PagePathTaken`), or an I/O error when the file
    /// step or its rollback fails.
    pub async fn move_session_page(
        &self,
        session_id: SessionId,
        from: (WorkspaceId, ProjectId),
        to: (WorkspaceId, ProjectId),
        pages: PagesMode,
        author_id: Option<UserId>,
        admission_ctx: Option<AdmissionContext>,
    ) -> WikiResult<MoveSessionOutcome> {
        self.inspect_project_tree(from.0, from.1)?;
        self.inspect_project_tree(to.0, to.1)?;
        let _guard = self.mutation_lock.write().await;
        self.inspect_project_tree(from.0, from.1)?;
        self.inspect_project_tree(to.0, to.1)?;
        let resolved_ctx = if let Some(chain) = &self.admission_chain {
            let mut ctx = admission_ctx.unwrap_or_default();
            ctx.op = AdmissionOp::MoveSession;
            self.resolve_admission_names(from.0, from.1, &mut ctx).await;
            chain.notify(None, &ctx).await?;
            Some(ctx)
        } else {
            None
        };

        let file_name = format!("{session_id}.md");
        let src = project_path(
            &self.root,
            from.0,
            from.1,
            &PathBuf::from("sessions").join(&file_name),
            Prepare::Inspect,
        )?;
        let parked = if from != to && src.is_file() {
            let target = match pages {
                PagesMode::Move => {
                    let dst = project_path(
                        &self.root,
                        to.0,
                        to.1,
                        &PathBuf::from("sessions").join(&file_name),
                        Prepare::Parents,
                    )?;
                    if dst.exists() {
                        return Err(WikiError::DestinationPageExists(dst.display().to_string()));
                    }
                    dst
                }
                // Same directory, watcher-ignored name: invisible to
                // reindex/reconcile, trivially renamed back on failure.
                PagesMode::Regenerate => {
                    src.with_file_name(format!(".ai-memory-tmp.move-session.{file_name}"))
                }
            };
            self.git.rename_checked(&src, &target)?;
            Some(target)
        } else {
            None
        };

        match self
            .writer
            .move_session(session_id, to.0, to.1, pages, author_id, true)
            .await
        {
            Ok(summary) => {
                let file = match (&parked, pages) {
                    (None, _) => SessionPageFile::Absent,
                    (Some(_), PagesMode::Move) => SessionPageFile::Moved,
                    (Some(tmp), PagesMode::Regenerate) => {
                        // The rows are retired; a leftover temp file is
                        // ignored by the watcher, so this is best-effort.
                        if let Err(e) = self.git.remove_file_checked(tmp) {
                            tracing::warn!(
                                error = %e,
                                path = %tmp.display(),
                                "move-session: could not remove parked session page file"
                            );
                        }
                        SessionPageFile::Removed
                    }
                };
                if let (Some(chain), Some(ctx)) = (&self.admission_chain, &resolved_ctx) {
                    chain.dispatch_async(None, &serde_json::Value::Null, "", ctx);
                }
                Ok(MoveSessionOutcome { summary, file })
            }
            Err(e) => {
                if let Some(target) = parked
                    && let Err(rollback_err) = self.git.rename_checked(&target, &src)
                {
                    return Err(WikiError::Io(std::io::Error::other(format!(
                        "INCONSISTENT STATE: session page file moved but DB re-stamp failed ({e}) and moving it back also failed ({rollback_err}); manually move {} -> {}",
                        target.display(),
                        src.display()
                    ))));
                }
                Err(e.into())
            }
        }
    }

    /// Ensure the store rows for a scope exist **and** that the scope is
    /// self-describing on disk. Every wiki write path funnels through here,
    /// which is what guarantees a project directory never outlives its
    /// `_meta.md`: the directory comes into existence with the first page
    /// written into it, and this runs first.
    pub(crate) async fn ensure_project_workspace(
        &self,
        workspace_id: WorkspaceId,
        project_id: ProjectId,
    ) -> WikiResult<()> {
        self.ensure_project_scope_rows(workspace_id, project_id)
            .await?;
        self.ensure_scope_manifests(workspace_id, project_id).await;
        Ok(())
    }

    /// Ensure the store rows for a scope exist, without touching the wiki
    /// tree. The watcher's two orphan guards want this — the reconcile pass
    /// and the directory-event path. Both run before `reindex_page` takes
    /// the mutation guard, so creating a file there could drop a manifest
    /// into a directory a concurrent project move is renaming away, and both
    /// only ever see directories that already exist, whose manifests were
    /// written with their first page or by the startup backfill.
    pub(crate) async fn ensure_project_scope_rows(
        &self,
        workspace_id: WorkspaceId,
        project_id: ProjectId,
    ) -> WikiResult<()> {
        self.writer
            .ensure_project_workspace(workspace_id, project_id)
            .await?;
        Ok(())
    }

    /// Write the workspace and project `_meta.md` manifests the first time
    /// this process writes into a scope, so a project that first materializes
    /// *while the server is up* is rebuildable immediately instead of only
    /// after the next startup backfill (#643). In that window `reindex` could
    /// not rebuild the scope at all: it walks the directories that exist on
    /// disk, and the directory exists from the first page write onward.
    ///
    /// Best-effort on purpose. A manifest that cannot be written must not
    /// fail the page write that triggered it — the page is the operator's
    /// data, the manifest is derived, and
    /// [`Self::backfill_scope_manifests`] rewrites it on the next start.
    async fn ensure_scope_manifests(&self, workspace_id: WorkspaceId, project_id: ProjectId) {
        let Some(reader) = &self.store_reader else {
            return;
        };
        let key = (workspace_id, project_id);
        if self
            .manifested_scopes
            .lock()
            .unwrap_or_else(|e| e.into_inner())
            .contains(&key)
        {
            return;
        }
        let scope = match reader.scope_row_by_ids(workspace_id, project_id).await {
            Ok(Some(scope)) => scope,
            // No row to describe: the scope was purged or moved between the
            // ensure above and this lookup. The next write re-checks.
            Ok(None) => return,
            Err(e) => {
                tracing::warn!(error = %e, "scope-manifest lookup failed (non-fatal)");
                return;
            }
        };
        let ws_dir = match workspace_path(&self.root, workspace_id, Prepare::Directory) {
            Ok(path) => path,
            Err(error) => {
                tracing::warn!(%error, "scope-manifest path confinement failed (non-fatal)");
                return;
            }
        };
        let workspace_name = scope.workspace_name.clone();
        let project_fm = match Self::project_scope_frontmatter(scope) {
            Ok(frontmatter) => frontmatter,
            Err(e) => {
                tracing::warn!(error = %e, "scope-manifest identity is invalid (non-fatal)");
                return;
            }
        };
        let written = self
            .write_scope_manifest(&ws_dir, serde_json::json!({ "workspace": workspace_name }))
            .and_then(|_| {
                let project_dir =
                    self.confined_project_root(workspace_id, project_id, Prepare::Directory)?;
                self.write_scope_manifest(&project_dir, project_fm)
            });
        match written {
            Ok(_) => {
                self.manifested_scopes
                    .lock()
                    .unwrap_or_else(|e| e.into_inner())
                    .insert(key);
            }
            Err(e) => tracing::warn!(error = %e, "scope-manifest write failed (non-fatal)"),
        }
    }

    /// Absolute on-disk path for a page within a specific project.
    #[must_use]
    pub fn abs_path(
        &self,
        workspace_id: WorkspaceId,
        project_id: ProjectId,
        path: &PagePath,
    ) -> PathBuf {
        self.project_root(workspace_id, project_id)
            .join(path.as_str())
    }

    /// Read the page at `path` from disk for the given project.
    ///
    /// # Errors
    /// Returns [`WikiError::Io`] if the file is missing or unreadable, or
    /// [`WikiError::Yaml`] if the frontmatter block is malformed.
    pub fn read_page(
        &self,
        workspace_id: WorkspaceId,
        project_id: ProjectId,
        path: &PagePath,
    ) -> WikiResult<Markdown> {
        let abs = self.confined_page_path(workspace_id, project_id, path, Prepare::Inspect)?;
        let raw = std::fs::read_to_string(&abs)?;
        parse(&raw)
    }

    /// Build one compare-and-write file plan for a same-workspace project
    /// merge from the Markdown source of truth.
    pub fn prepare_project_merge_file(
        &self,
        workspace_id: WorkspaceId,
        source_project: ProjectId,
        target_project: ProjectId,
        mut store: MergeProjectPage,
        source_label: &str,
    ) -> WikiResult<MergeProjectFile> {
        if store.target_page_id.is_none() {
            return Ok(MergeProjectFile {
                store,
                merged_markdown: None,
            });
        }
        let path = &store.path;
        let source = self.read_page(workspace_id, source_project, path)?;
        let target = self.read_page(workspace_id, target_project, path)?;
        let mut frontmatter = target.frontmatter;
        if (source.frontmatter.get("expires_at").is_none()
            || frontmatter.get("expires_at").is_none())
            && let Some(object) = frontmatter.as_object_mut()
        {
            object.remove("expires_at");
            object.remove("stale_after");
        }
        let body = format!(
            "{}\n\n<!-- ai-memory:merged-from {source_label} -->\n\n{}",
            target.body, source.body
        );
        let metadata = derive_index_metadata(path, &frontmatter)?;
        let title = derive_title(&frontmatter, &body, path);
        let markdown = Markdown {
            frontmatter: frontmatter.clone(),
            body: body.clone(),
        };
        let merged_page = NewPage {
            workspace_id,
            project_id: target_project,
            path: path.clone(),
            title,
            body,
            tier: metadata.tier,
            frontmatter_json: frontmatter,
            pinned: metadata.pinned,
            links: crate::markdown::extract_all_links(&markdown.frontmatter, &markdown.body, path),
            author_id: None,
            expires_at: metadata.expires_at,
            entities: metadata.entities,
            evidence: Vec::new(),
        };
        store.merged_page = Some(merged_page);
        Ok(MergeProjectFile {
            store,
            merged_markdown: Some(emit(&markdown)?),
        })
    }

    /// Whether the calling agent wrote `sessions/<session_id>.md` itself,
    /// through `memory_write_page` with that session's id: the page carries
    /// `consolidated_by: agent`. The automatic session-page writers leave such
    /// a page alone, because it was compiled by the model the user was
    /// working with. A missing page is `false`.
    ///
    /// # Errors
    /// Propagates [`Self::read_page`] errors other than a missing file.
    pub fn session_page_written_by_agent(
        &self,
        workspace_id: WorkspaceId,
        project_id: ProjectId,
        session_id: SessionId,
    ) -> WikiResult<bool> {
        let path = PagePath::new(format!("sessions/{session_id}.md"))?;
        let frontmatter = match self.read_page(workspace_id, project_id, &path) {
            Ok(md) => md.frontmatter,
            Err(WikiError::Io(err)) if err.kind() == std::io::ErrorKind::NotFound => {
                return Ok(false);
            }
            Err(err) => return Err(err),
        };
        Ok(frontmatter
            .get("consolidated_by")
            .and_then(serde_json::Value::as_str)
            == Some("agent"))
    }

    fn confined_project_root(
        &self,
        workspace_id: WorkspaceId,
        project_id: ProjectId,
        prepare: Prepare,
    ) -> WikiResult<PathBuf> {
        confined_project_root(&self.root, workspace_id, project_id, prepare)
    }

    /// Refuse a project tree containing a symbolic link or reparse point.
    ///
    /// # Errors
    /// Returns [`WikiError::Confinement`] for any linked component.
    pub fn validate_project_tree(
        &self,
        workspace_id: WorkspaceId,
        project_id: ProjectId,
    ) -> WikiResult<()> {
        self.inspect_project_tree(workspace_id, project_id)
    }

    pub(crate) fn validate_project_root(
        &self,
        workspace_id: WorkspaceId,
        project_id: ProjectId,
    ) -> WikiResult<()> {
        self.confined_project_root(workspace_id, project_id, Prepare::Inspect)
            .map(|_| ())
    }

    pub(crate) fn validate_page_path(
        &self,
        workspace_id: WorkspaceId,
        project_id: ProjectId,
        path: &PagePath,
    ) -> WikiResult<()> {
        self.confined_page_path(workspace_id, project_id, path, Prepare::Inspect)
            .map(|_| ())
    }

    /// Refuse a workspace tree containing a symbolic link or reparse point.
    ///
    /// # Errors
    /// Returns [`WikiError::Confinement`] for any linked component.
    pub fn validate_workspace_tree(&self, workspace_id: WorkspaceId) -> WikiResult<()> {
        self.inspect_workspace_tree(workspace_id)
    }

    fn inspect_wiki_tree(&self) -> WikiResult<()> {
        let git_dir = crate::confinement::inspect_git_directory(&self.root)?;
        crate::confinement::inspect_tree_except(&self.root, &[git_dir.as_path()])
    }

    fn inspect_project_tree(
        &self,
        workspace_id: WorkspaceId,
        project_id: ProjectId,
    ) -> WikiResult<()> {
        let root = self.confined_project_root(workspace_id, project_id, Prepare::Inspect)?;
        crate::confinement::inspect_tree_if_present(&root)
    }

    fn inspect_workspace_tree(&self, workspace_id: WorkspaceId) -> WikiResult<()> {
        let root = workspace_path(&self.root, workspace_id, Prepare::Inspect)?;
        crate::confinement::inspect_tree_if_present(&root)
    }

    fn confined_page_path(
        &self,
        workspace_id: WorkspaceId,
        project_id: ProjectId,
        path: &PagePath,
        prepare: Prepare,
    ) -> WikiResult<PathBuf> {
        project_path(
            &self.root,
            workspace_id,
            project_id,
            Path::new(path.as_str()),
            prepare,
        )
    }

    /// Restore one page from a git checkpoint and reindex it into the store.
    ///
    /// The checkpoint path is resolved through the UUID-backed wiki layout, so
    /// callers address pages by `(workspace_id, project_id, page_path)` while
    /// git still stores the exact markdown file. The restored file is parsed
    /// before it is written so a malformed checkpoint cannot replace the live
    /// disk copy and then fail during indexing.
    ///
    /// # Errors
    /// Returns [`WikiError`] when the revision/path does not exist, the stored
    /// bytes are not UTF-8 markdown, parsing fails, or the filesystem/store
    /// update fails.
    pub async fn restore_page_from_checkpoint(
        &self,
        workspace_id: WorkspaceId,
        project_id: ProjectId,
        path: PagePath,
        rev: &str,
    ) -> WikiResult<PageId> {
        self.confined_page_path(workspace_id, project_id, &path, Prepare::Inspect)?;
        let rel = PathBuf::from(workspace_id.to_string())
            .join(project_id.to_string())
            .join(path.as_str());
        let bytes = self.git.file_at_rev(rev, &rel)?;
        let raw = String::from_utf8(bytes).map_err(|e| {
            WikiError::Io(std::io::Error::other(format!(
                "{} at {rev} is not valid UTF-8 markdown: {e}",
                path.as_str()
            )))
        })?;
        let md = parse(&raw)?;
        self.restore_page_markdown(workspace_id, project_id, path, md, true)
            .await
    }

    /// Restore one retained SQLite page version as the new latest version.
    /// This complements checkpoint restore for histories that moved from
    /// another project path during `merge-project`.
    pub async fn restore_page_from_version(
        &self,
        workspace_id: WorkspaceId,
        project_id: ProjectId,
        path: PagePath,
        version_id: PageId,
    ) -> WikiResult<PageId> {
        let reader = self
            .store_reader
            .as_ref()
            .ok_or_else(|| ai_memory_wiki_error("page-version restore requires a store reader"))?;
        let version = reader
            .page_version_body(
                workspace_id,
                project_id,
                path.as_str().to_owned(),
                version_id,
            )
            .await?
            .ok_or_else(|| {
                WikiError::Store(ai_memory_store::StoreError::NotFound(
                    "page version not found in the requested scope".into(),
                ))
            })?;
        let tier = version
            .tier
            .parse::<Tier>()
            .map_err(|error| ai_memory_wiki_error(&error.to_string()))?;
        let frontmatter = canonicalize_index_frontmatter(version.frontmatter, tier, version.pinned);
        self.restore_page_markdown(
            workspace_id,
            project_id,
            path,
            Markdown {
                frontmatter,
                body: version.body,
            },
            true,
        )
        .await
    }

    async fn restore_page_markdown(
        &self,
        workspace_id: WorkspaceId,
        project_id: ProjectId,
        path: PagePath,
        mut md: Markdown,
        keep_own_generated_at: bool,
    ) -> WikiResult<PageId> {
        let (id, body, abstract_text) = {
            let _guard = self.mutation_lock.read().await;
            // Restore shares the writer/reindex lock, including the disk read
            // that chooses generated.at and any rollback after a refused upsert.
            let _page_guard = self.lock_page(workspace_id, project_id, &path).await;
            let abs = self.confined_page_path(workspace_id, project_id, &path, Prepare::Inspect)?;
            // Conform like the three sibling write paths (`write_page_inner`,
            // `apply_batch`, `approve_auto_improve_proposal`) do: the row this
            // upserts is conformed at the store's write choke point either way,
            // so writing the historical bytes verbatim left the file behind the
            // row. Restoring the pre-OKF checkpoint every migrated install
            // carries then failed `export-okf` for the whole project with "run
            // the server once to migrate" — which the one-shot wiki migration
            // never does again — and made each `serve` boot re-archive the data
            // dir once the migration archive was deleted. Conformance is
            // idempotent modulo `generated.at`. When the file on disk already
            // holds the same content, its timestamp still wins, so the file keeps
            // matching the row the store's idempotent upsert reuses. Otherwise
            // the disk holds a newer version and would leave only `now()`; an
            // already-conformant checkpoint keeps its own `generated.at` instead,
            // so it restores byte-exact whatever the clock.
            conform_frontmatter_for_disk_keeping(
                &abs,
                path.as_str(),
                &mut md,
                keep_own_generated_at,
            );
            let raw = emit(&md)?;
            let title = derive_title(&md.frontmatter, &md.body, &path);
            let links = crate::markdown::extract_all_links(&md.frontmatter, &md.body, &path);
            let meta = derive_index_metadata(&path, &md.frontmatter)?;
            let body = md.body.clone();
            let abstract_text = frontmatter_abstract(&md.frontmatter).map(str::to_owned);

            self.ensure_project_workspace(workspace_id, project_id)
                .await?;
            let abs = self.confined_page_path(workspace_id, project_id, &path, Prepare::Parents)?;
            let installed = replace_file_with_rollback_snapshot(&self.git, &abs, raw.as_bytes())?;
            let id = match self
                .writer
                .upsert_page(NewPage {
                    workspace_id,
                    project_id,
                    path,
                    title,
                    body: md.body,
                    tier: meta.tier,
                    frontmatter_json: md.frontmatter,
                    pinned: meta.pinned,
                    links,
                    author_id: None,
                    expires_at: meta.expires_at,
                    entities: meta.entities,
                    evidence: Vec::new(),
                })
                .await
            {
                Ok(id) => id,
                Err(e) => {
                    rollback_or_inconsistent(&self.git, std::slice::from_ref(&installed), &e)?;
                    return Err(e.into());
                }
            };
            (id, body, abstract_text)
        };
        // Embed the restored version like `write_page` does; without this it
        // ranked FTS-only until a backfill. The watcher's reindex of the file
        // just written hits the unchanged-content short-circuit and does not
        // embed it either.
        self.embed_page_version(id, &body, abstract_text.as_deref())
            .await?;
        Ok(id)
    }

    /// Delete the on-disk file for `path` within the given project.
    ///
    /// Returns `Ok(())` when the file was removed or did not exist (idempotent).
    /// The file watcher will observe the deletion; the sha256 short-circuit in
    /// the watcher's reindex path means a missing file produces a graceful
    /// no-op rather than an error.
    ///
    /// # Errors
    /// Returns [`WikiError::Io`] for any OS error other than "not found".
    /// Best-effort fill of `ctx.workspace`/`ctx.project` from ids via the
    /// store reader, so webhooks address pages by the same human names the
    /// engine uses. Mirrors the inline resolution in [`Self::write_page`].
    async fn resolve_admission_names(
        &self,
        workspace_id: WorkspaceId,
        project_id: ProjectId,
        ctx: &mut AdmissionContext,
    ) {
        if let Some(reader) = &self.store_reader {
            if ctx.workspace.is_empty()
                && let Ok(Some(name)) = reader.workspace_name_by_id(workspace_id).await
            {
                ctx.workspace = name;
            }
            if ctx.project.is_empty()
                && let Ok(Some(name)) = reader.project_name_by_id(workspace_id, project_id).await
            {
                ctx.project = name;
            }
        }
    }

    /// Best-effort fill of `ctx.workspace` from a workspace id via the store
    /// reader. Workspace-wide ops have no project id to resolve.
    async fn resolve_workspace_name(&self, workspace_id: WorkspaceId, ctx: &mut AdmissionContext) {
        if let Some(reader) = &self.store_reader
            && ctx.workspace.is_empty()
            && let Ok(Some(name)) = reader.workspace_name_by_id(workspace_id).await
        {
            ctx.workspace = name;
        }
    }

    /// Delete a single page file. When an admission chain is attached, it is
    /// notified (`op=delete`) BEFORE the file is removed, so a mirror can
    /// `git rm` the same path. A `Reject`-policy webhook aborts the delete.
    ///
    /// # Errors
    /// Returns [`WikiError`] on a filesystem error or a rejecting webhook.
    pub async fn delete_page(
        &self,
        workspace_id: WorkspaceId,
        project_id: ProjectId,
        path: &PagePath,
        admission_ctx: Option<AdmissionContext>,
        author_id: Option<ai_memory_core::UserId>,
    ) -> WikiResult<()> {
        self.confined_page_path(workspace_id, project_id, path, Prepare::Inspect)?;
        let _guard = self.mutation_lock.read().await;
        self.confined_page_path(workspace_id, project_id, path, Prepare::Inspect)?;
        self.ensure_project_workspace(workspace_id, project_id)
            .await?;
        self.remove_page_locked(
            workspace_id,
            project_id,
            path,
            admission_ctx,
            PageStoreRemoval::Delete {
                author_id,
                expected_latest_id: None,
            },
        )
        .await
        .map(|_| ())
    }

    /// Delete a page only when `expected_latest_id` is still its latest
    /// indexed version. Used by retention so a stale expiry candidate cannot
    /// delete a page that was refreshed after the sweep selected it.
    ///
    /// The exclusive mutation guard keeps normal wiki writes out between the
    /// pre-admission comparison and file quarantine; the writer repeats the
    /// comparison in the delete transaction as the final authority check.
    ///
    /// # Errors
    /// Returns [`WikiError`] when the store reader is unavailable, or on a
    /// filesystem, store, or rejecting-webhook error.
    pub async fn delete_page_if_latest(
        &self,
        workspace_id: WorkspaceId,
        project_id: ProjectId,
        path: &PagePath,
        expected_latest_id: PageId,
        admission_ctx: Option<AdmissionContext>,
        author_id: Option<UserId>,
    ) -> WikiResult<bool> {
        self.confined_page_path(workspace_id, project_id, path, Prepare::Inspect)?;
        let _guard = self.mutation_lock.write().await;
        self.ensure_project_workspace(workspace_id, project_id)
            .await?;
        let reader = self.store_reader.as_ref().ok_or_else(|| {
            ai_memory_wiki_error("conditional page delete requires a store reader")
        })?;
        let current = reader
            .latest_page_id_by_ids(workspace_id, project_id, path.as_str().to_string())
            .await?;
        if current != Some(expected_latest_id) {
            return Ok(false);
        }
        self.remove_page_locked(
            workspace_id,
            project_id,
            path,
            admission_ctx,
            PageStoreRemoval::Delete {
                author_id,
                expected_latest_id: Some(expected_latest_id),
            },
        )
        .await
    }

    /// Remove the authoritative file and tombstone the expected latest page.
    /// A stale candidate leaves both disk and store
    /// untouched.
    ///
    /// # Errors
    /// Returns [`WikiError`] when the store reader is unavailable, or on a
    /// filesystem, store, or rejecting-webhook error.
    pub async fn evict_page_if_latest(
        &self,
        workspace_id: WorkspaceId,
        project_id: ProjectId,
        path: &PagePath,
        expected_latest_id: PageId,
        admission_ctx: Option<AdmissionContext>,
    ) -> WikiResult<bool> {
        self.confined_page_path(workspace_id, project_id, path, Prepare::Inspect)?;
        let _guard = self.mutation_lock.write().await;
        self.ensure_project_workspace(workspace_id, project_id)
            .await?;
        let reader = self.store_reader.as_ref().ok_or_else(|| {
            ai_memory_wiki_error("conditional page eviction requires a store reader")
        })?;
        let current = reader
            .latest_page_id_by_ids(workspace_id, project_id, path.as_str().to_string())
            .await?;
        if current != Some(expected_latest_id) {
            return Ok(false);
        }
        self.remove_page_locked(
            workspace_id,
            project_id,
            path,
            admission_ctx,
            PageStoreRemoval::Decay { expected_latest_id },
        )
        .await
    }

    /// `(PageId, PagePath)` of every `is_latest = 1` page in a scope, for the
    /// watcher's reconcile-delete safety net (#929) to snapshot before it
    /// walks the wiki tree.
    ///
    /// # Errors
    /// Returns [`WikiError`] when the store reader is unavailable, or on a
    /// store error.
    pub(crate) async fn latest_page_ids(
        &self,
        workspace_id: WorkspaceId,
        project_id: ProjectId,
    ) -> WikiResult<Vec<(PageId, PagePath)>> {
        let reader = self.store_reader.as_ref().ok_or_else(|| {
            ai_memory_wiki_error("reconcile-delete candidate snapshot requires a store reader")
        })?;
        reader
            .latest_page_ids(workspace_id, project_id)
            .await
            .map_err(Into::into)
    }

    /// Tombstone the expected latest page after the watcher's reconcile pass
    /// found its file missing on two consecutive passes (opt-in, #929;
    /// `[maintenance] reconcile_tombstones_deleted_pages`).
    ///
    /// Deliberately does NOT go through [`Wiki::remove_page_locked`]: unlike
    /// `evict_page_if_latest` (decay) or `delete_page_if_latest` (explicit
    /// delete), this is a background safety net reacting to a file that is
    /// already gone, not a user-initiated action, so it never runs the
    /// BLOCKING admission gate (`AdmissionChain::notify`/`authorize`) —
    /// nothing gets to refuse it — and it never touches the filesystem —
    /// there is nothing on disk to quarantine or remove. It DOES
    /// fire-and-forget the chain's non-blocking observer/mirror webhooks on
    /// success (#929 review, S6), same as `remove_page_locked`'s post-write
    /// `dispatch_async`, so a mirror learns about the tombstone instead of
    /// silently diverging from the source of truth.
    ///
    /// Re-checks both the store's latest-id and the file's actual absence
    /// while holding the exclusive mutation guard, immediately before
    /// writing — the final gate design item #6 calls for, closing the window
    /// between the reconcile pass's second "missing" observation and this
    /// call (e.g. a concurrent `write_page` recreating the path).
    ///
    /// # Errors
    /// Returns [`WikiError`] when the store reader is unavailable, or on a
    /// filesystem or store error.
    pub(crate) async fn tombstone_missing_page_if_latest(
        &self,
        workspace_id: WorkspaceId,
        project_id: ProjectId,
        path: &PagePath,
        expected_latest_id: PageId,
    ) -> WikiResult<bool> {
        self.confined_page_path(workspace_id, project_id, path, Prepare::Inspect)?;
        let _guard = self.mutation_lock.write().await;
        self.ensure_project_workspace(workspace_id, project_id)
            .await?;
        let reader = self
            .store_reader
            .as_ref()
            .ok_or_else(|| ai_memory_wiki_error("reconcile tombstone requires a store reader"))?;
        let current = reader
            .latest_page_id_by_ids(workspace_id, project_id, path.as_str().to_string())
            .await?;
        if current != Some(expected_latest_id) {
            return Ok(false);
        }
        let abs = self.confined_page_path(workspace_id, project_id, path, Prepare::Inspect)?;
        if abs.try_exists()? {
            // The file came back (e.g. a slow atomic-save pattern beyond the
            // two-pass window, or a deliberate rewrite mid-check). Leave the
            // page alone; the next reconcile tick reindexes it normally.
            return Ok(false);
        }
        let tombstoned = self
            .writer
            .soft_delete_for_reconcile_if_latest(
                workspace_id,
                project_id,
                path.clone(),
                expected_latest_id,
            )
            .await?;
        if tombstoned && let Some(chain) = &self.admission_chain {
            // Non-blocking observers/mirrors only (#929 review, S6) — never
            // the blocking `notify`/`authorize` gate: this is a background
            // safety net, not a user-initiated delete, so nothing gets to
            // refuse it. But a mirror that never hears about the tombstone
            // silently diverges from the source of truth, which is a real
            // correctness issue too; fire-and-forget informs it the same way
            // `remove_page_locked` does for `evict_page_if_latest` and
            // `delete_page_if_latest`, just skipping their blocking half.
            let mut ctx = AdmissionContext {
                op: AdmissionOp::Delete,
                ..Default::default()
            };
            self.resolve_admission_names(workspace_id, project_id, &mut ctx)
                .await;
            chain.dispatch_async(Some(path.as_str()), &serde_json::Value::Null, "", &ctx);
        }
        Ok(tombstoned)
    }

    async fn remove_page_locked(
        &self,
        workspace_id: WorkspaceId,
        project_id: ProjectId,
        path: &PagePath,
        admission_ctx: Option<AdmissionContext>,
        removal: PageStoreRemoval,
    ) -> WikiResult<bool> {
        self.confined_page_path(workspace_id, project_id, path, Prepare::Inspect)?;
        let mut resolved_ctx = None;
        if let Some(chain) = &self.admission_chain {
            let mut ctx = admission_ctx.unwrap_or_default();
            ctx.op = AdmissionOp::Delete;
            self.resolve_admission_names(workspace_id, project_id, &mut ctx)
                .await;
            chain.notify(Some(path.as_str()), &ctx).await?;
            resolved_ctx = Some(ctx);
        }
        let abs = self.confined_page_path(workspace_id, project_id, path, Prepare::Inspect)?;
        let quarantined = match quarantine_file(&self.git, &abs) {
            Ok(path) => path,
            Err(WikiError::Io(e)) if e.kind() == std::io::ErrorKind::NotFound => None,
            Err(e) => return Err(e),
        };

        let delete_result = match removal {
            PageStoreRemoval::Delete {
                author_id,
                expected_latest_id: Some(expected),
            } => {
                self.writer
                    .delete_page_if_latest(
                        workspace_id,
                        project_id,
                        path.clone(),
                        expected,
                        author_id,
                    )
                    .await
            }
            PageStoreRemoval::Delete {
                author_id,
                expected_latest_id: None,
            } => self
                .writer
                .delete_page(workspace_id, project_id, path.clone(), author_id)
                .await
                .map(|()| true),
            PageStoreRemoval::Decay { expected_latest_id } => {
                self.writer
                    .soft_delete_for_decay_if_latest(
                        workspace_id,
                        project_id,
                        path.clone(),
                        expected_latest_id,
                    )
                    .await
            }
        };
        let deleted = match delete_result {
            Ok(deleted) => deleted,
            Err(e) => {
                restore_quarantined_file(&self.git, &quarantined, &abs, path);
                return Err(e.into());
            }
        };
        if !deleted {
            restore_quarantined_file(&self.git, &quarantined, &abs, path);
            return Ok(false);
        }

        if let Some(quarantine) = quarantined {
            self.git.remove_file_checked(&quarantine)?;
        }

        if let (Some(chain), Some(ctx)) = (&self.admission_chain, &resolved_ctx) {
            chain.dispatch_async(Some(path.as_str()), &serde_json::Value::Null, "", ctx);
        }
        Ok(true)
    }

    /// Permanently delete one aged decay tombstone and its ancestry chain.
    ///
    /// An existing Markdown file is always preserved. If the watcher has not
    /// indexed it yet (including a legacy pre-fix eviction or an external
    /// recreation), this method reindexes it under the exclusive mutation
    /// guard before deleting only the old chain rooted at `tombstone_id`.
    /// The writer repeats the observed latest-id check so a concurrent store
    /// mutation fails closed.
    ///
    /// # Errors
    /// Returns [`WikiError`] when the store reader is unavailable, or on a
    /// filesystem, store, or rejecting-webhook error.
    pub async fn hard_delete_decay_tombstone(
        &self,
        workspace_id: WorkspaceId,
        project_id: ProjectId,
        path: &PagePath,
        tombstone_id: PageId,
        cutoff_us: i64,
    ) -> WikiResult<usize> {
        self.confined_page_path(workspace_id, project_id, path, Prepare::Inspect)?;
        let _guard = self.mutation_lock.write().await;
        self.ensure_project_workspace(workspace_id, project_id)
            .await?;
        let reader = self
            .store_reader
            .as_ref()
            .ok_or_else(|| ai_memory_wiki_error("decay cleanup requires a store reader"))?;
        let mut current_latest = reader
            .latest_page_id_by_ids(workspace_id, project_id, path.as_str().to_string())
            .await?;
        let abs = self.confined_page_path(workspace_id, project_id, path, Prepare::Inspect)?;
        if current_latest.is_none() && abs.try_exists()? {
            // Deliberately drops any `PendingEmbed`: this whole function runs
            // under the exclusive write lock (`_guard` above, held until
            // return), and embedding must never happen while that lock is
            // held (#929) — it can block on the configured provider for an
            // unbounded time, stalling every other wiki write meanwhile. The
            // resurrected page's embedding (if any) is recovered later by
            // `ai-memory embed` / the scheduled backfill, same as any other
            // gap in `page_embeddings`.
            let (id, _pending_embed) = self
                .reindex_page_locked(workspace_id, project_id, path.clone())
                .await?;
            current_latest = Some(id);
        }

        self.writer
            .hard_delete_decayed_page_chain(
                workspace_id,
                project_id,
                path.clone(),
                tombstone_id,
                current_latest,
                cutoff_us,
            )
            .await
            .map_err(Into::into)
    }

    /// Purge a whole project's wiki directory. When an admission chain is
    /// attached, it is notified (`op=purge_project`, no page path) BEFORE the
    /// directory is removed, so a mirror can drop the project. A `Reject`
    /// webhook aborts the purge. Routes the on-disk removal through the
    /// namespaced [`Self::project_root`] (invariant: never hand-roll paths).
    ///
    /// # Errors
    /// Returns [`WikiError`] on a filesystem error or a rejecting webhook.
    pub async fn purge_project(
        &self,
        workspace_id: WorkspaceId,
        project_id: ProjectId,
        admission_ctx: Option<AdmissionContext>,
    ) -> WikiResult<()> {
        self.inspect_project_tree(workspace_id, project_id)?;
        let ctx = self
            .admit_purge_project(workspace_id, project_id, admission_ctx)
            .await?;
        self.remove_project_dir(workspace_id, project_id).await?;
        self.dispatch_purge(ctx.as_ref());
        Ok(())
    }

    /// Run the blocking admission notification for a project purge without
    /// removing files. Admin callers use this before the DB purge so a
    /// `failure_policy = reject` webhook can still abort all destructive work.
    ///
    /// # Errors
    /// Returns [`WikiError`] when a reject-policy webhook fails.
    pub async fn admit_purge_project(
        &self,
        workspace_id: WorkspaceId,
        project_id: ProjectId,
        admission_ctx: Option<AdmissionContext>,
    ) -> WikiResult<Option<AdmissionContext>> {
        self.inspect_project_tree(workspace_id, project_id)?;
        if let Some(chain) = &self.admission_chain {
            let mut ctx = admission_ctx.unwrap_or_default();
            ctx.op = AdmissionOp::PurgeProject;
            self.resolve_admission_names(workspace_id, project_id, &mut ctx)
                .await;
            chain.notify(None, &ctx).await?;
            Ok(Some(ctx))
        } else {
            Ok(None)
        }
    }

    /// Run the admission chain for a single-session purge, before any row is
    /// deleted, so a scope-guard webhook can refuse it while the data is
    /// still intact.
    ///
    /// # Errors
    /// Propagates a webhook rejection as [`WikiError`].
    pub async fn admit_purge_session(
        &self,
        workspace_id: WorkspaceId,
        project_id: ProjectId,
        admission_ctx: Option<AdmissionContext>,
    ) -> WikiResult<Option<AdmissionContext>> {
        self.inspect_project_tree(workspace_id, project_id)?;
        if let Some(chain) = &self.admission_chain {
            let mut ctx = admission_ctx.unwrap_or_default();
            ctx.op = AdmissionOp::PurgeSession;
            self.resolve_admission_names(workspace_id, project_id, &mut ctx)
                .await;
            chain.notify(None, &ctx).await?;
            Ok(Some(ctx))
        } else {
            Ok(None)
        }
    }

    /// Run the blocking admission notification for a workspace purge without
    /// removing files. Admin callers use this before the DB purge so a
    /// `failure_policy = reject` webhook can still abort all destructive work.
    ///
    /// # Errors
    /// Returns [`WikiError`] when a reject-policy webhook fails.
    pub async fn admit_purge_workspace(
        &self,
        workspace_id: WorkspaceId,
        admission_ctx: Option<AdmissionContext>,
    ) -> WikiResult<Option<AdmissionContext>> {
        self.inspect_workspace_tree(workspace_id)?;
        if let Some(chain) = &self.admission_chain {
            let mut ctx = admission_ctx.unwrap_or_default();
            ctx.op = AdmissionOp::PurgeWorkspace;
            self.resolve_workspace_name(workspace_id, &mut ctx).await;
            ctx.project.clear();
            chain.notify(None, &ctx).await?;
            Ok(Some(ctx))
        } else {
            Ok(None)
        }
    }

    /// Ask the admission chain about an operation that has no page and no body
    /// — a handoff lifecycle event.
    ///
    /// Handoffs live outside the wiki tree (they have their own table), so they
    /// never passed through `write_page` and were invisible to admission
    /// webhooks. That left the operations that move prompt-derived text between
    /// operators unauthorizable: a webhook that decides who may touch which
    /// scope could not see them at all.
    ///
    /// Only the webhooks that can refuse the operation are awaited — that is
    /// what the caller has to know before doing destructive work, and a
    /// `reject` policy is the operator asking to be waited for. The observers
    /// are handed back with the resolved context: pass it to
    /// [`Self::notify_operation_observers`] once the operation is durable, or
    /// drop it if the operation was abandoned, so no webhook is told about work
    /// that never happened. Every path that raises one of these ops owes its
    /// webhooks the same three steps in the same order — decide, act, notify —
    /// or the same event reaches a mirror from one caller and not from another.
    ///
    /// Returns `None` when no chain is attached (nothing left to notify).
    ///
    /// # Errors
    /// Returns [`WikiError`] when a reject-policy webhook refuses.
    pub async fn authorize_operation(
        &self,
        workspace_id: WorkspaceId,
        project_id: ProjectId,
        op: AdmissionOp,
        actor: ActorContext,
        skip_webhooks: Vec<String>,
    ) -> WikiResult<Option<AdmissionContext>> {
        let Some(chain) = &self.admission_chain else {
            return Ok(None);
        };
        let ctx = self
            .operation_admission_ctx(workspace_id, project_id, op, actor, skip_webhooks)
            .await;
        chain.authorize(None, &ctx).await?;
        Ok(Some(ctx))
    }

    /// Fire-and-forget the observer webhooks for an operation previously gated
    /// by [`Self::authorize_operation`] and since committed.
    pub fn notify_operation_observers(&self, ctx: &AdmissionContext) {
        if let Some(chain) = &self.admission_chain {
            chain.dispatch_notify_observers(None, ctx);
        }
    }

    async fn operation_admission_ctx(
        &self,
        workspace_id: WorkspaceId,
        project_id: ProjectId,
        op: AdmissionOp,
        actor: ActorContext,
        skip_webhooks: Vec<String>,
    ) -> AdmissionContext {
        let mut ctx = AdmissionContext {
            op,
            actor,
            skip_webhooks,
            ..Default::default()
        };
        self.resolve_admission_names(workspace_id, project_id, &mut ctx)
            .await;
        ctx
    }

    /// Run just the blocking admission chain for a would-be write, without
    /// touching the store, disk, or any upstream cost (e.g. an LLM call). A
    /// `failure_policy = reject` webhook can still abort here, so callers use
    /// this to fail fast on a scope/actor that admission would refuse anyway.
    ///
    /// The webhook receives an empty placeholder body: the blocking chain
    /// decides on `ctx` (op / actor / workspace / project + path), not on
    /// content, so no real body is needed and any mutation it returns is
    /// discarded. Returns `Ok(())` when no chain is attached (nothing to gate).
    ///
    /// # Errors
    /// Returns [`WikiError`] when a reject-policy webhook refuses the write.
    pub async fn preflight_admission(
        &self,
        workspace_id: WorkspaceId,
        project_id: ProjectId,
        path: &PagePath,
        op: AdmissionOp,
        actor: ActorContext,
    ) -> WikiResult<()> {
        self.confined_page_path(workspace_id, project_id, path, Prepare::Inspect)?;
        if let Some(chain) = &self.admission_chain {
            let mut ctx = AdmissionContext {
                op,
                actor,
                ..Default::default()
            };
            self.resolve_admission_names(workspace_id, project_id, &mut ctx)
                .await;
            chain.notify(Some(path.as_str()), &ctx).await?;
        }
        Ok(())
    }

    /// Remove the project's on-disk directory without running admission.
    ///
    /// # Errors
    /// Returns [`WikiError::Io`] on filesystem errors other than NotFound.
    pub async fn remove_project_dir(
        &self,
        workspace_id: WorkspaceId,
        project_id: ProjectId,
    ) -> WikiResult<()> {
        let _guard = self.mutation_lock.write().await;
        self.inspect_project_tree(workspace_id, project_id)?;
        let root = self.confined_project_root(workspace_id, project_id, Prepare::Inspect)?;
        match self.git.remove_dir_all_checked(&root) {
            Ok(()) => Ok(()),
            Err(WikiError::Io(e)) if e.kind() == std::io::ErrorKind::NotFound => Ok(()),
            Err(e) => Err(e),
        }
    }

    /// Remove a workspace's on-disk directory (`<wiki_root>/<ws>`), including
    /// every project under it, without running admission. Best-effort: a
    /// missing dir is not an error.
    ///
    /// # Errors
    /// Returns [`WikiError::Io`] on filesystem errors other than NotFound.
    pub async fn remove_workspace_dir(&self, workspace_id: WorkspaceId) -> WikiResult<()> {
        let _guard = self.mutation_lock.write().await;
        self.inspect_workspace_tree(workspace_id)?;
        let root = workspace_path(&self.root, workspace_id, Prepare::Inspect)?;
        match self.git.remove_dir_all_checked(&root) {
            Ok(()) => Ok(()),
            Err(WikiError::Io(e)) if e.kind() == std::io::ErrorKind::NotFound => Ok(()),
            Err(e) => Err(e),
        }
    }

    /// List the rotated hook event ledgers (`log-YYYY-MM.md`) directly under a
    /// project's wiki directory, in file-name order.
    ///
    /// A file qualifies only when its name has the rotated-ledger shape AND its
    /// content opens like a ledger (the [`ai_memory_core::log_ledger`]
    /// predicates, the same gate the indexer, the OKF migration and the OKF
    /// export apply): an ordinary page named `log-2025-01.md` is not listed.
    /// The unrotated `log.md` is never listed. Symbolic links and anything
    /// that is not a regular file are skipped. A project with no directory yet
    /// lists nothing.
    ///
    /// # Errors
    /// Returns [`WikiError::Confinement`] when the project tree crosses a
    /// symbolic link, or [`WikiError::Io`] when the directory cannot be read.
    pub fn list_event_ledgers(
        &self,
        workspace_id: WorkspaceId,
        project_id: ProjectId,
    ) -> WikiResult<Vec<EventLedgerFile>> {
        self.inspect_project_tree(workspace_id, project_id)?;
        let root = self.confined_project_root(workspace_id, project_id, Prepare::Inspect)?;
        let entries = match std::fs::read_dir(&root) {
            Ok(entries) => entries,
            Err(e) if e.kind() == std::io::ErrorKind::NotFound => return Ok(Vec::new()),
            Err(e) => return Err(e.into()),
        };
        let mut ledgers = Vec::new();
        for entry in entries {
            let entry = entry?;
            let Some(file_name) = entry.file_name().to_str().map(str::to_owned) else {
                continue;
            };
            if !crate::ledger::is_rotated_log_filename(&file_name) {
                continue;
            }
            let metadata = match std::fs::symlink_metadata(entry.path()) {
                Ok(metadata) => metadata,
                // Removed between the listing and the stat: not a ledger now.
                Err(e) if e.kind() == std::io::ErrorKind::NotFound => continue,
                Err(e) => return Err(e.into()),
            };
            if !metadata.is_file()
                || crate::confinement::is_link_like(&metadata)
                || !crate::ledger::opens_with_log_ledger(&entry.path())
            {
                continue;
            }
            ledgers.push(EventLedgerFile {
                file_name,
                bytes: metadata.len(),
            });
        }
        ledgers.sort_by(|a, b| a.file_name.cmp(&b.file_name));
        Ok(ledgers)
    }

    /// Delete one rotated hook event ledger (`log-YYYY-MM.md`) from a
    /// project's wiki directory and report the file's size.
    ///
    /// The only wiki path that removes a ledger: a ledger is not a page, so
    /// none of the page-delete helpers (which address `pages` rows) fit. It
    /// takes the exclusive mutation guard, then re-checks under it what the
    /// caller may have decided from a stale listing: the name must have the
    /// rotated-ledger shape (never `log.md`, never a path) and the file must be
    /// a regular, non-linked file whose content still opens like a ledger, so
    /// an ordinary page that carries the name is never deleted.
    ///
    /// Then it runs the same blocking admission check a page delete gets
    /// (`remove_page_locked`): webhooks subscribed to `delete_event_ledger`
    /// are notified with the ledger's file name BEFORE the removal, and a
    /// `Reject`-policy webhook refuses the delete — the file is left in place
    /// and the error propagates. Only after the file is gone are the chain's
    /// non-blocking observers dispatched, the way page deletes tell them.
    ///
    /// The hook ledger appender does not take the mutation guard, so an append
    /// that lands after the final check and before removal is deleted with the
    /// file. Callers pass only old months; a late-delivered event may append
    /// during the sweep or recreate a small ledger afterward. Never touches
    /// the store: a legacy `pages` row for the ledger is left alone.
    ///
    /// Returns `Ok(Some(bytes))` when the file was deleted and `Ok(None)` when
    /// there was nothing deletable: no such file, or one that is not a ledger.
    ///
    /// # Errors
    /// Returns [`WikiError::Confinement`] when the project tree crosses a
    /// symbolic link, [`WikiError::Io`] when `file_name` is not a rotated
    /// ledger name, when a `reject`-policy webhook refuses the removal, or
    /// when the filesystem fails.
    pub async fn delete_event_ledger(
        &self,
        workspace_id: WorkspaceId,
        project_id: ProjectId,
        file_name: &str,
    ) -> WikiResult<Option<u64>> {
        if !crate::ledger::is_rotated_log_filename(file_name) {
            return Err(ai_memory_wiki_error(
                "only a rotated event ledger (log-YYYY-MM.md) can be deleted",
            ));
        }
        let _guard = self.mutation_lock.write().await;
        self.inspect_project_tree(workspace_id, project_id)?;
        let abs = project_path(
            &self.root,
            workspace_id,
            project_id,
            Path::new(file_name),
            Prepare::Inspect,
        )?;
        let Some(_metadata) = event_ledger_metadata(&abs)? else {
            return Ok(None);
        };
        // The blocking half, exactly as `remove_page_locked` runs it for a
        // page delete: a `reject`-policy webhook refuses before anything is
        // removed, and the refusal propagates with the file left in place.
        let resolved_ctx = if let Some(chain) = &self.admission_chain {
            let mut ctx = AdmissionContext {
                op: AdmissionOp::DeleteEventLedger,
                ..Default::default()
            };
            self.resolve_admission_names(workspace_id, project_id, &mut ctx)
                .await;
            chain.notify(Some(file_name), &ctx).await?;
            Some(ctx)
        } else {
            None
        };
        // Admission is an external await point. Re-check afterward so a
        // webhook or concurrent editor cannot replace the inspected ledger
        // with an ordinary page and have that page removed by pathname.
        let Some(metadata) = event_ledger_metadata(&abs)? else {
            return Ok(None);
        };
        match self.git.remove_file_checked(&abs) {
            Ok(()) => {
                if let (Some(chain), Some(ctx)) = (&self.admission_chain, &resolved_ctx) {
                    chain.dispatch_async(Some(file_name), &serde_json::Value::Null, "", ctx);
                }
                Ok(Some(metadata.len()))
            }
            Err(WikiError::Io(e)) if e.kind() == std::io::ErrorKind::NotFound => Ok(None),
            Err(e) => Err(e),
        }
    }

    /// Session ids this scope has tombstoned, for lifecycle inspection.
    /// Reindex enforces these tombstones in its store write transaction,
    /// rather than authorizing a write from an earlier snapshot of this set.
    ///
    /// # Errors
    /// Propagates the store error.
    pub async fn purged_sessions(
        &self,
        workspace_id: WorkspaceId,
        project_id: ProjectId,
    ) -> WikiResult<HashSet<SessionId>> {
        Ok(self
            .writer
            .purged_session_ids(workspace_id, project_id)
            .await?
            .into_iter()
            .collect())
    }

    /// Purge a session and its page files under one exclusive mutation guard.
    /// Admission must run before this call. File failures do not roll back the
    /// committed database purge and are returned for partial-failure reporting.
    /// Holding the guard before submitting SQL prevents a watcher reindex,
    /// page write or project move from landing between SQL and file cleanup.
    ///
    /// # Errors
    /// Returns [`WikiError::Store`] without removing files if the database
    /// purge fails.
    pub async fn purge_session(
        &self,
        workspace_id: WorkspaceId,
        project_id: ProjectId,
        session_id: SessionId,
        author_id: Option<UserId>,
        compaction: ai_memory_store::Compaction,
    ) -> WikiResult<PurgeSessionOutcome> {
        self.purge_session_with_owner(
            workspace_id,
            project_id,
            session_id,
            author_id,
            compaction,
            None,
        )
        .await
    }

    /// Purge an operator's own session through the canonical disk/SQL mutation path.
    /// Shared sessions and cross-project cascades require the admin path.
    ///
    /// # Errors
    /// Returns store ownership/scope failures before removing files.
    pub async fn purge_owned_session(
        &self,
        workspace_id: WorkspaceId,
        project_id: ProjectId,
        session_id: SessionId,
        owner: ai_memory_core::IdentityKey,
        author_id: Option<UserId>,
    ) -> WikiResult<PurgeSessionOutcome> {
        self.purge_session_with_owner(
            workspace_id,
            project_id,
            session_id,
            author_id,
            ai_memory_store::Compaction::Skip,
            Some(owner),
        )
        .await
    }

    #[allow(clippy::too_many_arguments)]
    async fn purge_session_with_owner(
        &self,
        workspace_id: WorkspaceId,
        project_id: ProjectId,
        session_id: SessionId,
        author_id: Option<UserId>,
        compaction: ai_memory_store::Compaction,
        owner: Option<ai_memory_core::IdentityKey>,
    ) -> WikiResult<PurgeSessionOutcome> {
        self.inspect_project_tree(workspace_id, project_id)?;
        let _guard = self.mutation_lock.write().await;
        self.inspect_project_tree(workspace_id, project_id)?;
        // Always `Commit`: a caller that only wants a preview (the HTTP
        // handler's `dry_run` branch) goes straight through
        // `WriterHandle::purge_session` instead, bypassing this wrapper
        // entirely, so the file-removal loop below never runs over paths
        // that a preview only *predicts* would be removed.
        let summary = if let Some(owner) = owner {
            self.writer
                .purge_owned_session(
                    workspace_id,
                    project_id,
                    session_id,
                    owner,
                    author_id,
                    ai_memory_store::PurgeMode::Commit,
                )
                .await?
        } else {
            self.writer
                .purge_session(
                    workspace_id,
                    project_id,
                    session_id,
                    author_id,
                    compaction,
                    ai_memory_store::PurgeMode::Commit,
                )
                .await?
        };
        let mut files_deleted = Vec::with_capacity(summary.removed_paths.len());
        let mut files_failed = Vec::new();
        for path in &summary.removed_paths {
            let abs = self.abs_path(workspace_id, project_id, path);
            match self.git.remove_file_checked(&abs) {
                Ok(()) => {
                    sync_parent_best_effort(&abs);
                    files_deleted.push(path.clone());
                }
                Err(WikiError::Io(e)) if e.kind() == std::io::ErrorKind::NotFound => {}
                Err(error) => {
                    tracing::warn!(
                        operation = "purge-session",
                        path = path.as_str(),
                        error = %error,
                        "session purge failed to remove wiki page file",
                    );
                    files_failed.push(path.clone());
                }
            }
        }
        Ok(PurgeSessionOutcome {
            summary,
            files_deleted,
            files_failed,
        })
    }

    /// Dispatch non-blocking purge webhooks after the caller's purge has
    /// completed its durable DB/filesystem work. The purge kind (project,
    /// session, workspace) travels in `ctx.op`, set by the matching `admit_*`.
    pub fn dispatch_purge(&self, admission_ctx: Option<&AdmissionContext>) {
        if let (Some(chain), Some(ctx)) = (&self.admission_chain, admission_ctx) {
            chain.dispatch_async(None, &serde_json::Value::Null, "", ctx);
        }
    }

    /// Cloneable handle to the underlying store writer.
    #[must_use]
    pub fn writer(&self) -> &WriterHandle {
        &self.writer
    }

    /// Absolute on-disk path for an auto-improvement proposal sidecar.
    #[must_use]
    pub fn auto_improve_sidecar_path(
        &self,
        workspace_id: WorkspaceId,
        project_id: ProjectId,
        proposal_id: AutoImproveProposalId,
    ) -> PathBuf {
        self.project_root(workspace_id, project_id)
            .join(artifact_path_for(proposal_id))
    }

    /// Write a human-reviewable non-indexed sidecar for a staged proposal.
    ///
    /// This intentionally bypasses [`Self::write_page`]: pending proposal
    /// artifacts are review aids, not durable wiki pages, and must not create
    /// rows in `pages`/FTS/embeddings.
    pub async fn write_auto_improve_sidecar(
        &self,
        workspace_id: WorkspaceId,
        project_id: ProjectId,
        proposal_id: AutoImproveProposalId,
    ) -> WikiResult<PathBuf> {
        project_path(
            &self.root,
            workspace_id,
            project_id,
            Path::new(&artifact_path_for(proposal_id)),
            Prepare::Inspect,
        )?;
        let reader = self.store_reader.as_ref().ok_or_else(|| {
            ai_memory_wiki_error("auto-improve sidecar write requires a store reader")
        })?;
        let detail = reader
            .auto_improve_proposal_detail(workspace_id, project_id, proposal_id)
            .await?
            .ok_or_else(|| ai_memory_wiki_error("auto-improve proposal not found in scope"))?;
        let path = self.auto_improve_sidecar_path(workspace_id, project_id, proposal_id);
        let content = self.sanitizer.scrub(&render_auto_improve_sidecar(&detail)?);
        let _guard = self.mutation_lock.read().await;
        self.ensure_project_workspace(workspace_id, project_id)
            .await?;
        self.git.write_atomic(&path, content.as_bytes())?;
        Ok(path)
    }

    /// Approve a staged auto-improvement proposal by applying its stored body
    /// through the normal wiki write pipeline, then atomically marking the DB
    /// proposal approved.
    pub async fn approve_auto_improve_proposal(
        &self,
        workspace_id: WorkspaceId,
        project_id: ProjectId,
        proposal_id: AutoImproveProposalId,
        actor: ActorContext,
        author_id: Option<UserId>,
        admission_ctx: Option<AdmissionContext>,
    ) -> WikiResult<ApproveAutoImproveProposalResult> {
        self.inspect_project_tree(workspace_id, project_id)?;
        let reader = self
            .store_reader
            .as_ref()
            .ok_or_else(|| ai_memory_wiki_error("auto-improve approval requires a store reader"))?;
        let detail = reader
            .auto_improve_proposal_detail(workspace_id, project_id, proposal_id)
            .await?
            .ok_or_else(|| ai_memory_wiki_error("auto-improve proposal not found in scope"))?;

        let path = detail.summary.target_path.clone();
        path.ensure_portable()?;
        self.confined_page_path(workspace_id, project_id, &path, Prepare::Inspect)?;
        let mut frontmatter = serde_json::json!({
            "kind": detail.summary.kind,
            "title": detail.summary.title,
            "auto_improve_proposal_id": proposal_id.to_string(),
            "auto_improve_run_id": detail.summary.run_id.to_string(),
        });
        frontmatter = stamp_last_modified_by(frontmatter, &actor);
        let body = self.sanitizer.scrub(&detail.body_markdown);
        let mut markdown = Markdown { frontmatter, body };
        let mut resolved_ctx = None;
        if let Some(chain) = &self.admission_chain {
            let mut ctx = admission_ctx.unwrap_or_default();
            ctx.actor = actor.clone();
            self.resolve_admission_names(workspace_id, project_id, &mut ctx)
                .await;
            match chain.run(&path, &mut markdown, &ctx).await {
                Ok(()) => resolved_ctx = Some(ctx),
                Err(e) => {
                    let reason = e.to_string();
                    self.writer
                        .fail_auto_improve_proposal(FailAutoImproveProposal {
                            workspace_id,
                            project_id,
                            proposal_id,
                            reason,
                            // An outage is not a verdict on the proposal; keep
                            // it out of the reviewer's "avoid repeating" context.
                            record_rejection: !is_admission_unavailable(&e),
                            actor,
                            author_id,
                        })
                        .await?;
                    return Err(e);
                }
            }
        }
        markdown.body = self.sanitizer.scrub(&markdown.body);
        scrub_frontmatter_strings(&mut markdown.frontmatter, &self.sanitizer);
        // Approved pages must land conformant like every other write —
        // this emit skipped the disk conformance seam, leaving files
        // without type/generated that blocked export-okf and, worse,
        // phantom-superseded on the first reindex after a binary upgrade
        // (the row was conformed with the approving binary's version, the
        // file with the reindexing one's). Post-audit finding.
        conform_frontmatter_for_disk(
            &self.abs_path(workspace_id, project_id, &path),
            path.as_str(),
            &mut markdown,
        );
        let title = self.sanitizer.scrub(&detail.summary.title);
        let links =
            crate::markdown::extract_all_links(&markdown.frontmatter, &markdown.body, &path);
        let expires_at = parse_expires_at(&path, &markdown.frontmatter)?;
        let entities = parse_entities(&path, &markdown.frontmatter)?;
        let emitted = emit(&markdown)?;
        let page = NewPage {
            workspace_id,
            project_id,
            path: path.clone(),
            title,
            body: markdown.body.clone(),
            tier: Tier::Semantic,
            frontmatter_json: markdown.frontmatter.clone(),
            pinned: is_slot_path(&path),
            links,
            author_id,
            expires_at,
            entities,
            evidence: Vec::new(),
        };

        let result = {
            let _guard = self.mutation_lock.write().await;
            self.confined_page_path(workspace_id, project_id, &path, Prepare::Inspect)?;
            self.ensure_project_workspace(workspace_id, project_id)
                .await?;
            let abs = self.confined_page_path(workspace_id, project_id, &path, Prepare::Parents)?;
            let installed =
                replace_file_with_rollback_snapshot(&self.git, &abs, emitted.as_bytes())?;
            match self
                .writer
                .approve_auto_improve_proposal(ApproveAutoImproveProposal {
                    workspace_id,
                    project_id,
                    proposal_id,
                    page,
                    actor: actor.clone(),
                    author_id,
                    checkpoint: None,
                })
                .await
            {
                Ok(ApproveAutoImproveProposalResult::Approved { page_id }) => {
                    ApproveAutoImproveProposalResult::Approved { page_id }
                }
                Ok(ApproveAutoImproveProposalResult::Conflict) => {
                    rollback_or_inconsistent(
                        &self.git,
                        std::slice::from_ref(&installed),
                        &"proposal conflict",
                    )?;
                    ApproveAutoImproveProposalResult::Conflict
                }
                Err(e) => {
                    rollback_or_inconsistent(&self.git, std::slice::from_ref(&installed), &e)?;
                    return Err(e.into());
                }
            }
        };

        // Embed the applied version like `write_page` does, after the
        // mutation guard is released (the provider call may block). Without
        // this, approved pages stayed vectorless until a backfill ran: the
        // watcher's reindex of the file we just wrote hits the store's
        // unchanged-content short-circuit, so it never embeds them either.
        if let ApproveAutoImproveProposalResult::Approved { page_id } = &result {
            let abstract_text = frontmatter_abstract(&markdown.frontmatter);
            self.embed_page_version(*page_id, &markdown.body, abstract_text)
                .await?;
        }

        if let (Some(chain), Some(ctx)) = (&self.admission_chain, &resolved_ctx) {
            chain.dispatch_async(
                Some(path.as_str()),
                &markdown.frontmatter,
                &markdown.body,
                ctx,
            );
        }
        Ok(result)
    }

    /// Re-index the page on disk at `path` into the store *without*
    /// rewriting the file.
    ///
    /// Called by the watcher when an external editor (Obsidian, vim) has
    /// changed a file we did not write. The store-side sha256 short-circuit
    /// makes this idempotent: if the on-disk content already matches the
    /// latest version, no supersession happens.
    ///
    /// # Errors
    /// Returns [`WikiError`] for any filesystem, parsing, or store error.
    pub async fn reindex_page(
        &self,
        workspace_id: WorkspaceId,
        project_id: ProjectId,
        path: PagePath,
    ) -> WikiResult<PageId> {
        self.confined_page_path(workspace_id, project_id, &path, Prepare::Inspect)?;
        if is_pending_path(&path) {
            return Err(ai_memory_wiki_error(
                "refusing to index pending proposal sidecar",
            ));
        }
        // Scoped so both mutation guards are dropped before the embed call
        // below — same shape as `write_page` (#607/#929): embedding calls
        // out to the configured provider, and holding the guard across that
        // would block every other write in the wiki for its duration.
        let (id, pending_embed) = {
            let _guard = self.mutation_lock.read().await;
            self.confined_page_path(workspace_id, project_id, &path, Prepare::Inspect)?;
            self.ensure_project_workspace(workspace_id, project_id)
                .await?;
            self.reindex_page_locked(workspace_id, project_id, path)
                .await?
        };
        // A failed `store_embedding` here is caught and recorded inside
        // `embed_page_version` (`record_embed_failure`), not retried by the
        // watcher; `ai-memory embed` (manual) or the scheduled backfill tick
        // is what recovers it.
        if let Some(pending) = pending_embed {
            self.embed_page_version(id, &pending.body, pending.abstract_text.as_deref())
                .await?;
        }
        Ok(id)
    }

    /// Reindex `path` from disk into the store, returning the resulting page
    /// id and — when the reindex produced a new version worth embedding —
    /// the inputs for that embed. Embedding itself is deferred to the
    /// caller, which must not call [`Wiki::embed_page_version`] while
    /// holding a lock this function was called under: it may block on the
    /// configured embedder for an arbitrary amount of time, and this path
    /// has two very different callers with two different locking needs
    /// (`reindex_page`'s brief read guard; `hard_delete_decay_tombstone`'s
    /// long-lived write guard, which must never embed at all — see there).
    /// The caller already holds the global mutation guard (shared or
    /// exclusive); acquire only the page mutex here, always after that guard.
    async fn reindex_page_locked(
        &self,
        workspace_id: WorkspaceId,
        project_id: ProjectId,
        path: PagePath,
    ) -> WikiResult<(PageId, Option<PendingEmbed>)> {
        let _page_guard = self.lock_page(workspace_id, project_id, &path).await;
        let abs = self.confined_page_path(workspace_id, project_id, &path, Prepare::Inspect)?;
        let raw = std::fs::read_to_string(&abs)?;
        let md = parse(&raw)?;
        let title = derive_title(&md.frontmatter, &md.body, &path);
        let links = crate::markdown::extract_all_links(&md.frontmatter, &md.body, &path);
        // Markdown is the source of truth: preserve explicit tier/pinned
        // metadata on reindex instead of forcing every page back to semantic.
        let meta = derive_index_metadata(&path, &md.frontmatter)?;

        // The watcher's own writes never go through `write_page` (it must
        // never touch disk — see `crate::watcher`'s module docs), so this is
        // the only place that can embed a page an external editor created or
        // rewrote. Resolve the pre-upsert latest id (when an embedder and a
        // store reader are both available) so a no-op reindex — the
        // reconcile pass walks every page every 30s — never re-embeds a
        // stable tree; only a genuine new/rewritten version, recognised by
        // `upsert_page` minting a fresh id, does.
        //
        // Fails CLOSED, unlike most of this crate's reconcile-adjacent
        // lookups: without a reader there is no cheap way to tell "new
        // version" from "unchanged", and guessing wrong the open way (embed
        // unconditionally) would re-embed the entire tree every
        // `RECONCILE_INTERVAL` for as long as no reader is attached, which
        // is worse than the rare bare `Wiki::new` fixture simply not getting
        // watcher-driven embeddings. Skipped up front when no embedder is
        // configured too, so the zero-LLM default path (invariant #13)
        // never pays for the extra lookup.
        let previous_id_and_body = match (&self.embedder, &self.store_reader) {
            (Some(_), Some(reader)) => {
                let previous_id = reader
                    .latest_page_id_by_ids(workspace_id, project_id, path.as_str().to_string())
                    .await?;
                Some((
                    previous_id,
                    md.body.clone(),
                    frontmatter_abstract(&md.frontmatter).map(str::to_owned),
                ))
            }
            _ => None,
        };

        #[cfg(test)]
        if let Some(barrier) = &self.reindex_read_barrier {
            barrier.wait().await;
            barrier.wait().await;
        }

        let id = self
            .writer
            .upsert_page_from_disk(NewPage {
                workspace_id,
                project_id,
                path,
                title,
                body: md.body,
                tier: meta.tier,
                frontmatter_json: md.frontmatter,
                pinned: meta.pinned,
                links,
                author_id: None,
                expires_at: meta.expires_at,
                entities: meta.entities,
                evidence: Vec::new(),
            })
            .await?;

        let pending_embed = previous_id_and_body.and_then(|(previous_id, body, abstract_text)| {
            (previous_id != Some(id)).then_some(PendingEmbed {
                body,
                abstract_text,
            })
        });
        Ok((id, pending_embed))
    }

    fn project_scope_frontmatter(scope: ScopeRow) -> WikiResult<serde_json::Value> {
        let project_id = scope.project_id;
        let identity = match (scope.identity.as_deref(), scope.identity_source.as_deref()) {
            (Some(identity), Some(source)) => Some(
                ai_memory_core::repository_identity::accept_wire_identity(identity, source)
                    .ok_or_else(|| {
                        WikiError::Io(std::io::Error::other(format!(
                            "project {} has an invalid identity/source pair",
                            scope.project_id
                        )))
                    })?,
            ),
            (None, None) => None,
            _ => {
                return Err(WikiError::Io(std::io::Error::other(format!(
                    "project {} has an incomplete identity/source pair",
                    scope.project_id
                ))));
            }
        };
        let canonical_name = identity
            .as_ref()
            .and_then(ai_memory_core::repository_identity::path_style_name);
        let legacy_name = identity
            .as_ref()
            .and_then(ai_memory_core::repository_identity::legacy_basename_name);
        if scope.canonical_name != canonical_name || scope.legacy_name != legacy_name {
            return Err(WikiError::Io(std::io::Error::other(format!(
                "project {project_id} has coordinate keys inconsistent with its identity"
            ))));
        }
        let manifest = ai_memory_core::repository_identity::ProjectManifest {
            project: scope.project_name,
            repo_path: scope.repo_path,
            identity: identity.as_ref().map(|value| value.identity.clone()),
            identity_source: identity.map(|value| value.source),
            canonical_name,
            legacy_name,
        };
        serde_json::to_value(manifest).map_err(WikiError::from)
    }

    /// Read a `_meta.md` scope-manifest's frontmatter from `dir`.
    fn read_scope_meta(dir: &Path) -> WikiResult<serde_json::Value> {
        let path = dir.join("_meta.md");
        let meta = std::fs::symlink_metadata(&path).map_err(|error| {
            let message = if error.kind() == std::io::ErrorKind::NotFound {
                format!("scope manifest {} is missing", path.display())
            } else {
                format!(
                    "could not inspect scope manifest {}: {error}",
                    path.display()
                )
            };
            WikiError::Io(std::io::Error::new(error.kind(), message))
        })?;
        if crate::confinement::is_link_like(&meta) {
            return Err(WikiError::Io(std::io::Error::other(format!(
                "refusing to read symlinked scope manifest {}",
                path.display()
            ))));
        }
        let raw = std::fs::read_to_string(&path).map_err(|error| {
            WikiError::Io(std::io::Error::new(
                error.kind(),
                format!("could not read scope manifest {}: {error}", path.display()),
            ))
        })?;
        Ok(parse(&raw)?.frontmatter)
    }

    /// Rebuild the **entire** store index from the on-disk wiki tree — the
    /// "DB is rebuildable from files" guarantee made concrete. Walks every
    /// `<ws-uuid>/<proj-uuid>/` directory, recreates workspace/project rows and
    /// optional repository identity from each self-describing `_meta.md`
    /// manifest (preserving the ids
    /// the tree is keyed by, via [`WriterHandle::ensure_workspace_with_id`] /
    /// [`ensure_project_with_id`]), then reindexes every page. Pages are
    /// detected by content (a frontmatter file named `log.md` is a page; the
    /// raw `## [..]` ledger, `_meta.md` and `bootstrap.md` are skipped).
    ///
    /// Intended for a freshly-migrated (clean) store, e.g. to move a data dir
    /// onto a different migration lineage without carrying the old
    /// `refinery_schema_history`. DB-only episodic state (sessions,
    /// observations, handoffs, decay counters) is NOT reconstructed — it is not
    /// in the markdown; embeddings can be recomputed separately via `embed`.
    ///
    /// # Errors
    /// Returns [`WikiError`] for filesystem/parse/store errors, including a
    /// scope directory that lacks its `_meta.md` (the wiki is not
    /// self-describing). Scopes written by this engine always have one: it
    /// is materialized with the scope's first page, and
    /// [`Self::backfill_scope_manifests`] repairs trees written by older
    /// ones on every start.
    pub async fn reindex_all(&self) -> WikiResult<ReindexSummary> {
        self.inspect_wiki_tree()?;
        let root = self.root().to_path_buf();
        let project_dirs =
            tokio::task::spawn_blocking(move || crate::watcher::walk_project_dirs(&root))
                .await
                .map_err(|e| WikiError::Io(std::io::Error::other(e.to_string())))??;

        let mut summary = ReindexSummary::default();
        let mut seen_ws = std::collections::HashSet::new();

        for (ws, proj, proj_root) in project_dirs {
            // A purged scope must not be resurrected from an on-disk directory
            // its purge failed to remove (#607). The tombstone is terminal:
            // skip the whole directory rather than recreating the scope row and
            // reindexing its pages. The files stay inert (the watcher skips
            // them too, #613) until a later purge or manual cleanup removes
            // them; reindex stays non-destructive.
            if self.writer.scope_is_purged(ws, proj).await? {
                tracing::debug!(
                    workspace = %ws,
                    project = %proj,
                    "skipping reindex of a purged (tombstoned) scope",
                );
                summary.skipped_purged += 1;
                continue;
            }
            if seen_ws.insert(ws) {
                let ws_dir = proj_root
                    .parent()
                    .unwrap_or(proj_root.as_path())
                    .to_path_buf();
                let meta = Self::read_scope_meta(&ws_dir)?;
                let name = meta
                    .get("workspace")
                    .and_then(|v| v.as_str())
                    .ok_or_else(|| {
                        WikiError::Io(std::io::Error::other(format!(
                            "{}/_meta.md is missing the `workspace` name",
                            ws_dir.display()
                        )))
                    })?;
                self.writer.ensure_workspace_with_id(ws, name).await?;
                summary.workspaces += 1;
            }

            let meta = Self::read_scope_meta(&proj_root)?;
            if meta
                .get("project")
                .and_then(|value| value.as_str())
                .is_none()
            {
                return Err(WikiError::Io(std::io::Error::other(format!(
                    "{}/_meta.md is missing the `project` name",
                    proj_root.display()
                ))));
            }
            let manifest: ai_memory_core::repository_identity::ProjectManifest =
                serde_json::from_value(meta)?;
            let identity = match (manifest.identity.as_deref(), manifest.identity_source) {
                (Some(identity), Some(source)) => Some(
                    ai_memory_core::repository_identity::accept_wire_identity(
                        identity,
                        source.as_str(),
                    )
                    .ok_or_else(|| {
                        WikiError::Io(std::io::Error::other(format!(
                            "{}/_meta.md has an invalid repository identity/source pair",
                            proj_root.display()
                        )))
                    })?,
                ),
                (None, None) => None,
                _ => {
                    return Err(WikiError::Io(std::io::Error::other(format!(
                        "{}/_meta.md must provide identity and identity_source together",
                        proj_root.display()
                    ))));
                }
            };
            let derived_canonical = identity
                .as_ref()
                .and_then(ai_memory_core::repository_identity::path_style_name);
            let derived_legacy = identity
                .as_ref()
                .and_then(ai_memory_core::repository_identity::legacy_basename_name);
            let has_coordinate_assertion =
                manifest.canonical_name.is_some() || manifest.legacy_name.is_some();
            if has_coordinate_assertion
                && (manifest.canonical_name != derived_canonical
                    || manifest.legacy_name != derived_legacy)
            {
                return Err(WikiError::Io(std::io::Error::other(format!(
                    "{}/_meta.md repository coordinate keys do not match its identity",
                    proj_root.display()
                ))));
            }
            self.writer
                .ensure_project_with_id(proj, ws, manifest.project, manifest.repo_path, identity)
                .await?;
            summary.projects += 1;

            let pr = proj_root.clone();
            let pages = tokio::task::spawn_blocking(move || crate::watcher::walk_markdown(&pr))
                .await
                .map_err(|e| WikiError::Io(std::io::Error::other(e.to_string())))??;
            for path in pages {
                match self.reindex_page(ws, proj, path).await {
                    Ok(_) => summary.pages += 1,
                    Err(WikiError::Store(ai_memory_store::StoreError::SessionPurged(_))) => {
                        summary.skipped_purged_sessions += 1;
                    }
                    Err(WikiError::Store(ai_memory_store::StoreError::PagePathCollides {
                        requested,
                        existing,
                    })) => {
                        tracing::warn!(
                            path = %requested,
                            existing = %existing,
                            "skipping page: it differs from an already-indexed page only by case \
                             or Unicode normalization, so both cannot coexist on macOS/Windows",
                        );
                        summary.skipped_collisions += 1;
                    }
                    Err(e) => return Err(e),
                }
            }
        }
        Ok(summary)
    }

    /// Write a `_meta.md` scope manifest under `dir` from `frontmatter`,
    /// idempotently — unchanged content is left untouched so a startup
    /// backfill never churns the wiki git history. Returns `true` if written.
    fn write_scope_manifest(
        &self,
        dir: &Path,
        mut frontmatter: serde_json::Value,
    ) -> WikiResult<bool> {
        let relative = dir
            .strip_prefix(&self.root)
            .map_err(|_| WikiError::Confinement {
                path: dir.to_path_buf(),
                reason: "scope manifest directory is outside the wiki root",
            })?;
        let dir = tree_path(&self.root, relative, Prepare::Directory)?;
        // OKF conformance at the manifest choke point: every non-reserved
        // .md needs a `type`, and the startup backfill's byte-compare must
        // agree with what the OKF migration writes — a typeless emit here
        // silently reverted migrated manifests on the same boot
        // (post-audit finding). `type` is appended last, matching the
        // migration's entry-insertion order, so the two emitters converge
        // on identical bytes.
        if let Some(map) = frontmatter.as_object_mut() {
            map.entry("type".to_string())
                .or_insert(serde_json::Value::String("Scope Manifest".into()));
        }
        let content = emit(&Markdown {
            frontmatter,
            body: String::new(),
        })?;
        let path = dir.join("_meta.md");
        match std::fs::symlink_metadata(&path) {
            Ok(meta) if crate::confinement::is_link_like(&meta) => {
                return Err(WikiError::Io(std::io::Error::other(format!(
                    "refusing to update symlinked scope manifest {}",
                    path.display()
                ))));
            }
            Ok(meta) if meta.is_file() => {
                if std::fs::read_to_string(&path).is_ok_and(|existing| existing == content) {
                    return Ok(false);
                }
            }
            Ok(_) | Err(_) => {}
        }
        self.git.write_atomic(&path, content.as_bytes())?;
        Ok(true)
    }

    /// Refresh one committed renamed scope from its current store row and checkpoint it.
    ///
    /// # Errors
    /// Returns [`WikiError`] for store, filesystem, or checkpoint errors.
    pub async fn refresh_renamed_scope(
        &self,
        workspace_id: WorkspaceId,
        project_id: ProjectId,
    ) -> WikiResult<Option<String>> {
        let reader = self.store_reader.as_ref().ok_or_else(|| {
            WikiError::Io(std::io::Error::other(
                "scope refresh requires a store reader",
            ))
        })?;
        let _guard = self.mutation_lock.write().await;
        self.manifested_scopes
            .lock()
            .unwrap_or_else(|error| error.into_inner())
            .remove(&(workspace_id, project_id));
        let scope = reader
            .scope_row_by_ids(workspace_id, project_id)
            .await?
            .ok_or_else(|| {
                WikiError::Io(std::io::Error::other("renamed scope no longer exists"))
            })?;
        let ws_dir = self.root.join(workspace_id.to_string());
        self.write_scope_manifest(
            &ws_dir,
            serde_json::json!({ "workspace": scope.workspace_name }),
        )?;
        let project_fm = Self::project_scope_frontmatter(scope)?;
        self.write_scope_manifest(&ws_dir.join(project_id.to_string()), project_fm)?;
        let checkpoint = self
            .commit_all(&format!("rename-project {workspace_id}/{project_id}"))?
            .map(|oid| oid.to_string());
        self.manifested_scopes
            .lock()
            .unwrap_or_else(|error| error.into_inner())
            .insert((workspace_id, project_id));
        Ok(checkpoint)
    }

    /// Ensure every workspace/project scope has its self-describing `_meta.md`
    /// manifest on disk (names, `repo_path`, and optional repository identity
    /// coordinates). Idempotent, safe at startup, and a no-op without a store
    /// reader.
    ///
    /// # Errors
    /// Returns [`WikiError`] for store or filesystem errors.
    pub async fn backfill_scope_manifests(&self) -> WikiResult<usize> {
        let Some(reader) = &self.store_reader else {
            return Ok(0);
        };
        let _guard = self.mutation_lock.write().await;
        let workspaces = reader.list_all_workspace_scopes().await?;
        let scopes = reader.list_all_scopes().await?;
        let mut written = 0;
        for ws in workspaces {
            let ws_dir = workspace_path(&self.root, ws.workspace_id, Prepare::Directory)?;
            if self.write_scope_manifest(
                &ws_dir,
                serde_json::json!({ "workspace": ws.workspace_name }),
            )? {
                written += 1;
            }
        }
        for s in scopes {
            let project_dir =
                self.confined_project_root(s.workspace_id, s.project_id, Prepare::Directory)?;
            let fm = Self::project_scope_frontmatter(s)?;
            if self.write_scope_manifest(&project_dir, fm)? {
                written += 1;
            }
        }
        Ok(written)
    }

    /// Repair the OKF `stale_after` that builds before this one copied
    /// verbatim from a date-only `expires_at` (docs/okf.md): the index rows
    /// in place through the writer, then each page's file, body and
    /// `generated.at` untouched, in one git commit. Idempotent and cheap on
    /// a repaired store (only pages with a date-only TTL are read); safe to
    /// run on every startup. Returns `(rows, files)` repaired.
    ///
    /// # Errors
    /// Returns [`WikiError`] for store, filesystem or git errors.
    pub async fn repair_date_only_stale_after(&self) -> WikiResult<(u64, usize)> {
        self.inspect_wiki_tree()?;
        let _guard = self.mutation_lock.write().await;
        self.inspect_wiki_tree()?;
        let repair = self.writer.repair_date_only_stale_after().await?;
        let mut files = 0;
        for page in &repair.date_only_pages {
            let page_path = PagePath::new(&page.path)?;
            let abs = self.confined_page_path(
                page.workspace_id,
                page.project_id,
                &page_path,
                Prepare::Inspect,
            )?;
            let raw = match std::fs::read_to_string(&abs) {
                Ok(raw) => raw,
                Err(e) if e.kind() == std::io::ErrorKind::NotFound => continue,
                Err(e) => return Err(e.into()),
            };
            let Ok(mut markdown) = parse(&raw) else {
                continue;
            };
            if ai_memory_core::okf::repair_date_only_stale_after(&mut markdown.frontmatter) {
                self.git.write_atomic(&abs, emit(&markdown)?.as_bytes())?;
                files += 1;
            }
        }
        if files > 0 {
            self.commit_all("okf: repair date-only stale_after on existing pages")?;
        }
        Ok((repair.rows_repaired, files))
    }

    /// Atomically apply a batch of page writes. Either all pages land
    /// (one SQL transaction) and their files are renamed into place.
    /// Files are installed before the SQL batch so markdown remains the source
    /// of truth; if the SQL batch fails at runtime, installed files are rolled
    /// back best-effort to their prior contents.
    ///
    /// # Errors
    /// Returns [`WikiError`] for any filesystem, parsing, or store
    /// error.
    pub async fn apply_batch(&self, requests: Vec<WritePageRequest>) -> WikiResult<Vec<PageId>> {
        match self.apply_batch_inner(requests, None).await? {
            ConditionalBatchWrite::Written(ids) => Ok(ids),
            ConditionalBatchWrite::Mismatch { .. } => Err(ai_memory_wiki_error(
                "an unconditional page batch reported a precondition mismatch",
            )),
        }
    }

    /// Atomically apply a batch only when every page is still at the version
    /// the caller derived its replacement from. One mismatch writes nothing.
    ///
    /// # Errors
    /// As [`Self::apply_batch`].
    pub async fn apply_batch_if(
        &self,
        requests: Vec<(WritePageRequest, PagePrecondition)>,
    ) -> WikiResult<ConditionalBatchWrite> {
        let (requests, preconditions): (Vec<_>, Vec<_>) = requests.into_iter().unzip();
        self.apply_batch_inner(requests, Some(preconditions)).await
    }

    async fn apply_batch_inner(
        &self,
        requests: Vec<WritePageRequest>,
        preconditions: Option<Vec<PagePrecondition>>,
    ) -> WikiResult<ConditionalBatchWrite> {
        if requests.is_empty() {
            return Ok(ConditionalBatchWrite::Written(Vec::new()));
        }
        // Reject any path that cannot be materialised and checkpointed on every
        // supported platform, before anything is written.
        for req in &requests {
            req.path.ensure_portable()?;
            self.confined_page_path(
                req.workspace_id,
                req.project_id,
                &req.path,
                Prepare::Inspect,
            )?;
        }
        // Pre-compute markdown for each request. Filesystem work happens only
        // after the mutation guard + project/workspace validation below.
        let mut staged: Vec<(
            WritePageRequest,
            String,
            std::path::PathBuf,
            Option<AdmissionContext>,
        )> = Vec::with_capacity(requests.len());
        for mut req in requests {
            // Defence-in-depth scrub at the batch boundary too.
            req.body = self.sanitizer.scrub(&req.body);
            if let Some(t) = req.title.take() {
                req.title = Some(self.sanitizer.scrub(&t));
            }

            req.frontmatter = stamp_last_modified_by(req.frontmatter, &req.actor);
            let mut markdown = Markdown {
                frontmatter: req.frontmatter,
                body: req.body,
            };

            let resolved_ctx = if let Some(chain) = &self.admission_chain {
                let mut ctx = req.admission_ctx.take().unwrap_or_default();
                ctx.actor = req.actor.clone();
                self.resolve_admission_names(req.workspace_id, req.project_id, &mut ctx)
                    .await;
                chain.run(&req.path, &mut markdown, &ctx).await?;
                Some(ctx)
            } else {
                None
            };

            markdown.body = self.sanitizer.scrub(&markdown.body);
            scrub_frontmatter_strings(&mut markdown.frontmatter, &self.sanitizer);
            req.pinned = req.pinned
                || is_slot_path(&req.path)
                || markdown
                    .frontmatter
                    .get("pinned")
                    .and_then(|v| v.as_bool())
                    .unwrap_or(false);
            markdown.frontmatter =
                canonicalize_index_frontmatter(markdown.frontmatter, req.tier, req.pinned);
            conform_frontmatter_for_disk(
                &self.abs_path(req.workspace_id, req.project_id, &req.path),
                req.path.as_str(),
                &mut markdown,
            );

            let title = req
                .title
                .take()
                .unwrap_or_else(|| derive_title(&markdown.frontmatter, &markdown.body, &req.path));
            let emitted = emit(&markdown)?;
            let abs = self.abs_path(req.workspace_id, req.project_id, &req.path);
            req.frontmatter = markdown.frontmatter;
            req.body = markdown.body;
            let req_with_title = WritePageRequest {
                title: Some(title),
                ..req
            };
            staged.push((req_with_title, emitted, abs, resolved_ctx));
        }

        let (ids, dispatches) = {
            let _guard = self.mutation_lock.read().await;
            for (req, _, _, _) in &staged {
                self.confined_page_path(
                    req.workspace_id,
                    req.project_id,
                    &req.path,
                    Prepare::Inspect,
                )?;
            }
            // Serialize every path in this batch against concurrent single-page
            // or batch writers to the same path (#607). Sorted acquisition
            // keeps a batch deadlock-free against any other writer.
            let batch_keys: Vec<PageKey> = staged
                .iter()
                .map(|(req, _, _, _)| (req.workspace_id, req.project_id, req.path.clone()))
                .collect();
            let _page_guards = self.lock_pages(&batch_keys).await;
            if let (Some(preconditions), Some(reader)) = (&preconditions, &self.store_reader) {
                for (index, ((req, _, _, _), precondition)) in
                    staged.iter().zip(preconditions).enumerate()
                {
                    let current = reader
                        .latest_page_id_by_ids(
                            req.workspace_id,
                            req.project_id,
                            req.path.as_str().to_string(),
                        )
                        .await?;
                    if !precondition_holds(*precondition, current) {
                        return Ok(ConditionalBatchWrite::Mismatch { index, current });
                    }
                }
            }
            let mut staged_files: Vec<(
                WritePageRequest,
                tempfile::NamedTempFile,
                std::path::PathBuf,
                Option<AdmissionContext>,
            )> = Vec::with_capacity(staged.len());
            for (req, emitted, _abs, ctx) in staged {
                self.ensure_project_workspace(req.workspace_id, req.project_id)
                    .await?;
                let abs = self.confined_page_path(
                    req.workspace_id,
                    req.project_id,
                    &req.path,
                    Prepare::Parents,
                )?;
                let parent = abs.parent().ok_or_else(|| {
                    ai_memory_wiki_error("page path has no parent (cannot stage tempfile)")
                })?;
                let mut tmp = tempfile::Builder::new()
                    .prefix(".ai-memory-tmp.")
                    .tempfile_in(parent)?;
                use std::io::Write as _;
                tmp.write_all(emitted.as_bytes())?;
                tmp.as_file().sync_data()?;
                staged_files.push((req, tmp, abs, ctx));
            }

            // Build NewPage batch with the precomputed titles.
            let pages: Vec<ai_memory_core::NewPage> = staged_files
                .iter()
                .map(|(req, _, _, _)| {
                    Ok(ai_memory_core::NewPage {
                        workspace_id: req.workspace_id,
                        project_id: req.project_id,
                        path: req.path.clone(),
                        title: req.title.clone().unwrap_or_default(),
                        body: req.body.clone(),
                        tier: req.tier,
                        frontmatter_json: req.frontmatter.clone(),
                        pinned: req.pinned,
                        links: crate::markdown::extract_all_links(
                            &req.frontmatter,
                            &req.body,
                            &req.path,
                        ),
                        author_id: req.author_id,
                        expires_at: parse_expires_at(&req.path, &req.frontmatter)?,
                        entities: parse_entities(&req.path, &req.frontmatter)?,
                        evidence: req.evidence.clone(),
                    })
                })
                .collect::<WikiResult<Vec<_>>>()?;

            // Install files first so the DB is never ahead of markdown. If the
            // SQL batch fails below, rollback restores the prior disk state;
            // if the process crashes in this window, startup/reindex repairs
            // the derived DB from the markdown source of truth.
            let mut installed = Vec::with_capacity(staged_files.len());
            let mut dispatches = Vec::with_capacity(staged_files.len());
            for (req, tmp, abs, ctx) in staged_files {
                let install = match persist_tmp_with_rollback_snapshot(&self.git, tmp, &abs) {
                    Ok(install) => install,
                    Err(e) => {
                        rollback_or_inconsistent(&self.git, &installed, &e)?;
                        return Err(e);
                    }
                };
                installed.push(install);
                dispatches.push((req.path, req.frontmatter, req.body, ctx));
            }

            let write = match &preconditions {
                Some(preconditions) => {
                    let pages = pages
                        .into_iter()
                        .zip(preconditions.iter().copied())
                        .collect();
                    self.writer.upsert_pages_batch_if(pages).await
                }
                None => self
                    .writer
                    .upsert_pages_batch(pages)
                    .await
                    .map(ConditionalBatchUpsert::Upserted),
            };
            let ids = match write {
                Ok(ConditionalBatchUpsert::Upserted(ids)) => ids,
                Ok(ConditionalBatchUpsert::Mismatch { index, current }) => {
                    rollback_or_inconsistent(
                        &self.git,
                        &installed,
                        &ai_memory_wiki_error("conditional page batch changed during write"),
                    )?;
                    return Ok(ConditionalBatchWrite::Mismatch { index, current });
                }
                Err(e) => {
                    rollback_or_inconsistent(&self.git, &installed, &e)?;
                    return Err(e.into());
                }
            };

            (ids, dispatches)
        };

        // Embed each applied version like `write_page` does, after the
        // guards are released. Unlike `write_page`, a store error while
        // persisting a vector is logged rather than returned: the batch has
        // committed, and callers (consolidation, sweep, dream, bootstrap)
        // record per-page outcomes from these ids, so an `Err` here would
        // report written pages as failed. The vector-less page is picked up
        // by the next embedding backfill.
        for (id, (path, frontmatter, body, _)) in ids.iter().zip(&dispatches) {
            if let Err(error) = self
                .embed_page_version(*id, body, frontmatter_abstract(frontmatter))
                .await
            {
                tracing::warn!(%error, path = %path.as_str(), "batch page indexed without its embedding");
            }
        }

        if let Some(chain) = &self.admission_chain {
            for (path, frontmatter, body, ctx) in &dispatches {
                if let Some(ctx) = ctx {
                    chain.dispatch_async(Some(path.as_str()), frontmatter, body, ctx);
                }
            }
        }

        Ok(ConditionalBatchWrite::Written(ids))
    }

    /// Acquire the per-path write lock for one page, serializing concurrent
    /// writers to the same `(ws, proj, path)` while different paths run
    /// concurrently. See [`Wiki::page_locks`].
    async fn lock_page(
        &self,
        workspace_id: WorkspaceId,
        project_id: ProjectId,
        path: &PagePath,
    ) -> tokio::sync::OwnedMutexGuard<()> {
        let lock = {
            let mut map = self.page_locks.lock().expect("page_locks mutex poisoned");
            // Opportunistic GC under the same short critical section that hands
            // out locks: an entry whose only remaining strong ref is the map's
            // own (count == 1) has no live guard and no waiter, so drop it.
            map.retain(|_, v| Arc::strong_count(v) > 1);
            Arc::clone(
                map.entry((workspace_id, project_id, path.clone()))
                    .or_insert_with(|| Arc::new(tokio::sync::Mutex::new(()))),
            )
        };
        lock.lock_owned().await
    }

    /// Acquire per-path write locks for a batch of pages in a deterministic
    /// global order (sorted by id/path bytes, deduped) so a batch write and any
    /// concurrent single-page or batch writer can never deadlock. See
    /// [`Wiki::page_locks`].
    async fn lock_pages(&self, keys: &[PageKey]) -> Vec<tokio::sync::OwnedMutexGuard<()>> {
        let mut ordered: Vec<PageKey> = keys.to_vec();
        // The id newtypes are not `Ord`, so order by their byte / string
        // representation — any total order works, it only has to be consistent
        // across all acquirers.
        ordered.sort_by(|a, b| {
            (a.0.as_bytes(), a.1.as_bytes(), a.2.as_str()).cmp(&(
                b.0.as_bytes(),
                b.1.as_bytes(),
                b.2.as_str(),
            ))
        });
        ordered.dedup();
        let mut guards = Vec::with_capacity(ordered.len());
        for (ws, proj, path) in ordered {
            guards.push(self.lock_page(ws, proj, &path).await);
        }
        guards
    }

    /// Write `body` (with optional `frontmatter`) atomically to
    /// `<wiki_root>/<workspace_id>/<project_id>/<path>` and upsert the
    /// matching page row in the store.
    ///
    /// The store side does the sha256 short-circuit + supersession dance.
    /// Returns the id of the page version that is now `is_latest = 1`.
    ///
    /// # Errors
    /// Returns [`WikiError`] for any filesystem, parsing, or store error.
    pub async fn write_page(&self, req: WritePageRequest) -> WikiResult<PageId> {
        match self.write_page_inner(req, None).await? {
            ConditionalWrite::Written(id) => Ok(id),
            ConditionalWrite::Mismatch { .. } => Err(ai_memory_wiki_error(
                "an unconditional page write reported a precondition mismatch",
            )),
        }
    }

    /// [`Self::write_page`] only when `precondition` holds for the page's
    /// latest version. A mismatch writes nothing: no file change, no new
    /// version, no webhook dispatch.
    ///
    /// Checked twice under the page lock: before the file is replaced, so a
    /// normal mismatch never touches disk, and again in the store transaction
    /// that writes the version, which is the authority (a plain delete takes
    /// only the shared mutation lock and can land between the two); a
    /// mismatch there restores the file.
    ///
    /// # Errors
    /// As [`Self::write_page`].
    pub async fn write_page_if(
        &self,
        req: WritePageRequest,
        precondition: PagePrecondition,
    ) -> WikiResult<ConditionalWrite> {
        self.write_page_inner(req, Some(precondition)).await
    }

    async fn write_page_inner(
        &self,
        req: WritePageRequest,
        precondition: Option<PagePrecondition>,
    ) -> WikiResult<ConditionalWrite> {
        self.confined_page_path(
            req.workspace_id,
            req.project_id,
            &req.path,
            Prepare::Inspect,
        )?;
        // Reject a path that cannot be materialised and checkpointed on every
        // supported platform, before anything is written.
        //
        // This is the single funnel every page creation passes through, and
        // it is the moment the two failing operations happen: the file hits
        // the filesystem and libgit2 checkpoints it. Catching it earlier (in
        // `PagePath::new`) would break reads of already-stored pages, and
        // catching it later leaves the worst outcome observed in #462 — a
        // page written successfully but uncheckpointable and undeletable
        // through the normal API.
        req.path.ensure_portable()?;

        let WritePageRequest {
            workspace_id,
            project_id,
            path,
            frontmatter,
            body,
            tier,
            pinned,
            title: explicit_title,
            admission_ctx,
            author_id,
            actor,
            evidence,
        } = req;

        // Defence-in-depth: scrub the body before we touch disk or the
        // store, regardless of caller. The hook ingress already scrubs
        // observation text; this catches LLM-rewritten consolidation
        // bodies, manual `write-page` CLI inputs, and anything an MCP
        // tool slips through.
        let body = self.sanitizer.scrub(&body);

        let mut pinned = pinned || is_slot_path(&path);
        // Multi-user attribution (P1.6): stamp `last_modified_by` into the
        // frontmatter BEFORE building the markdown, so both the admission
        // chain and the on-disk file see the resolved author. Rung 0
        // (anonymous) → no block, no disk-shape change for single-user.
        let frontmatter = stamp_last_modified_by(frontmatter, &actor);
        let mut markdown = Markdown { frontmatter, body };

        // Admission webhook chain runs after the initial scrub, before emit +
        // atomic write. Mutations to
        // frontmatter/body here propagate to both the on-disk markdown
        // (via emit below) and the store's `frontmatter_json` / `body`
        // (via the upsert below) atomically. See `crate::admission`.
        let resolved_ctx = if let Some(chain) = &self.admission_chain {
            let mut ctx = admission_ctx.unwrap_or_default();
            // Single identity source: the webhook actor is the same
            // `ActorContext` used for on-disk attribution (req.actor),
            // populated by the auth layer — not a separate header bridge.
            ctx.actor = actor.clone();
            self.resolve_admission_names(workspace_id, project_id, &mut ctx)
                .await;
            // Blocking webhooks run synchronously (they may mutate / reject).
            chain.run(&path, &mut markdown, &ctx).await?;
            Some(ctx)
        } else {
            None
        };

        // Webhook mutations are external input too. Scrub again so a webhook
        // cannot reintroduce secrets after the caller body was sanitized.
        markdown.body = self.sanitizer.scrub(&markdown.body);
        scrub_frontmatter_strings(&mut markdown.frontmatter, &self.sanitizer);
        pinned = pinned
            || markdown
                .frontmatter
                .get("pinned")
                .and_then(|v| v.as_bool())
                .unwrap_or(false);
        markdown.frontmatter = canonicalize_index_frontmatter(markdown.frontmatter, tier, pinned);
        conform_frontmatter_for_disk(
            &self.abs_path(workspace_id, project_id, &path),
            path.as_str(),
            &mut markdown,
        );

        // Re-derive title + links from the (possibly mutated) markdown.
        // We do this after the chain so explicit title overrides survive
        // mutations and webhooks that rename or restructure the body
        // still get the right title/links extracted.
        let title = explicit_title
            .clone()
            .map(|t| self.sanitizer.scrub(&t))
            .unwrap_or_else(|| derive_title(&markdown.frontmatter, &markdown.body, &path));
        let links =
            crate::markdown::extract_all_links(&markdown.frontmatter, &markdown.body, &path);
        let expires_at = parse_expires_at(&path, &markdown.frontmatter)?;
        let entities = parse_entities(&path, &markdown.frontmatter)?;
        // Read before the destructuring move below: the embed step needs the
        // L0 `abstract:` line out of the final frontmatter.
        let abstract_text = frontmatter_abstract(&markdown.frontmatter).map(str::to_owned);

        let Markdown {
            frontmatter: final_frontmatter,
            body: final_body,
        } = markdown;
        let path_for_dispatch = path.clone();
        let frontmatter_for_dispatch = final_frontmatter.clone();
        let emitted = emit(&Markdown {
            frontmatter: final_frontmatter.clone(),
            body: final_body.clone(),
        })?;

        let page_id = {
            let _guard = self.mutation_lock.read().await;
            // Serialize with any concurrent write to this same path, so the
            // file-rename and DB-upsert below cannot interleave with another
            // writer's and leave disk disagreeing with the DB `latest` row
            // (#607). Different paths still proceed concurrently.
            let _page_guard = self.lock_page(workspace_id, project_id, &path).await;
            self.confined_page_path(workspace_id, project_id, &path, Prepare::Inspect)?;
            self.ensure_project_workspace(workspace_id, project_id)
                .await?;
            if let (Some(precondition), Some(reader)) = (precondition, &self.store_reader) {
                let current = reader
                    .latest_page_id_by_ids(workspace_id, project_id, path.as_str().to_string())
                    .await?;
                if !precondition_holds(precondition, current) {
                    return Ok(ConditionalWrite::Mismatch { current });
                }
            }
            let abs = self.confined_page_path(workspace_id, project_id, &path, Prepare::Parents)?;
            let installed =
                replace_file_with_rollback_snapshot(&self.git, &abs, emitted.as_bytes())?; // lgtm [rust/path-injection]

            let page = NewPage {
                workspace_id,
                project_id,
                path,
                title,
                body: final_body.clone(),
                tier,
                frontmatter_json: final_frontmatter,
                pinned,
                links,
                author_id,
                expires_at,
                entities,
                evidence,
            };
            let written = match precondition {
                None => self
                    .writer
                    .upsert_page(page)
                    .await
                    .map(ConditionalUpsert::Upserted),
                Some(precondition) => self.writer.upsert_page_if(page, precondition).await,
            };
            match written {
                Ok(ConditionalUpsert::Upserted(id)) => id,
                Ok(ConditionalUpsert::Mismatch { current }) => {
                    rollback_or_inconsistent(
                        &self.git,
                        std::slice::from_ref(&installed),
                        &"a page write precondition no longer held",
                    )?;
                    return Ok(ConditionalWrite::Mismatch { current });
                }
                Err(e) => {
                    rollback_or_inconsistent(&self.git, std::slice::from_ref(&installed), &e)?;
                    return Err(e.into());
                }
            }
        };
        // Embed if configured. We do this on the caller's task so the
        // tool reply still happens "indexes commit in the same
        // transaction" (basic-memory #763 lesson): no fire-and-forget
        // background embedding.
        self.embed_page_version(page_id, &final_body, abstract_text.as_deref())
            .await?;

        // Non-blocking webhooks fire-and-forget only after the page has landed
        // on disk and the DB/index write has succeeded. They observe the final
        // persisted page and cannot mutate or reject it.
        if let (Some(chain), Some(ctx)) = (&self.admission_chain, &resolved_ctx) {
            chain.dispatch_async(
                Some(path_for_dispatch.as_str()),
                &frontmatter_for_dispatch,
                &final_body,
                ctx,
            );
        }
        Ok(ConditionalWrite::Written(page_id))
    }

    /// Embed `body` (and its L0 `abstract:` line, if present) into
    /// `page_id`'s vectors, when an embedder is configured.
    ///
    /// Called after the upsert, outside the mutation guard, by every path
    /// that writes a page version: [`Wiki::write_page`] (every version
    /// written through the API), [`Wiki::reindex_page`] (external file
    /// writes and rewrites picked up by the watcher), auto-improvement
    /// approval, [`Wiki::apply_batch`] and checkpoint restore. A page version
    /// becomes hybrid-searchable through the same mechanism regardless of
    /// which path produced it; the watcher cannot cover the others, because
    /// its reindex of a file the wiki just wrote hits the unchanged-content
    /// short-circuit. Before this was pulled out, only `write_page` embedded —
    /// a watcher-driven rewrite got a new page id (the supersession chain
    /// worked) but no embedding until a manual `ai-memory embed` (issue
    /// #929): hybrid search silently fell back to FTS-only ranking for
    /// every rewritten page.
    ///
    /// Best-effort: provider and embedding-store failures are logged and
    /// recorded but never propagated. The page mutation has already committed
    /// before this method runs, so reporting the whole operation as failed
    /// would invite a duplicate retry and can skip later post-commit work such
    /// as admission-webhook dispatch.
    async fn embed_page_version(
        &self,
        page_id: PageId,
        body: &str,
        abstract_text: Option<&str>,
    ) -> WikiResult<()> {
        let Some(embedder) = &self.embedder else {
            return Ok(());
        };
        match embedder.embed_document(body).await {
            Ok(vec) => {
                let bytes = f32_vec_to_bytes(&vec);
                if let Err(e) = self
                    .writer
                    .store_embedding(
                        page_id,
                        bytes,
                        embedder.provider().to_string(),
                        // Not `.model()`: a configured document prefix must land
                        // under a distinct stored identity so a prefix change is
                        // never silently mixed with vectors embedded under a
                        // different (or no) prefix. See `Embedder::model_identity`.
                        embedder.model_identity(),
                        embedder.dim(),
                    )
                    .await
                {
                    tracing::warn!(error = %e, path = %page_id, "embedding store failed; page indexed without it");
                    let _ = self
                        .writer
                        .record_embed_failure(
                            page_id,
                            ai_memory_store::EmbedOutcome::Failed,
                            Some(e.to_string()),
                        )
                        .await;
                }
            }
            Err(e) => {
                tracing::warn!(error = %e, path = %page_id, "embedding failed; page indexed without it");
                // The warning alone dies with the container. Record it so
                // the page is attributable later (#528); best-effort,
                // because failing to note a failure must not fail the
                // write that already succeeded.
                let _ = self
                    .writer
                    .record_embed_failure(
                        page_id,
                        ai_memory_store::EmbedOutcome::Failed,
                        Some(e.to_string()),
                    )
                    .await;
            }
        }
        // L0 abstract: the frontmatter `abstract:` line is embedded on
        // its own so the opt-in abstract stream can rank on the sharp
        // one-line summary. A page rewritten without the key has its
        // stale abstract row removed, mirroring the body row's
        // replace-on-write semantics.
        match abstract_text {
            Some(abstract_text) => match embedder.embed_document(abstract_text).await {
                Ok(vec) => {
                    if let Err(e) = self
                        .writer
                        .store_abstract_embeddings(vec![ai_memory_store::EmbeddingWrite {
                            page_id,
                            vector_bytes: f32_vec_to_bytes(&vec),
                            provider: embedder.provider().to_string(),
                            // See the body-embedding write above.
                            model: embedder.model_identity(),
                            dim: embedder.dim(),
                        }])
                        .await
                    {
                        tracing::warn!(error = %e, path = %page_id, "abstract embedding store failed; page indexed without it");
                        let _ = self
                            .writer
                            .record_embed_failure(
                                page_id,
                                ai_memory_store::EmbedOutcome::Failed,
                                Some(e.to_string()),
                            )
                            .await;
                    }
                }
                Err(e) => {
                    tracing::warn!(error = %e, path = %page_id, "abstract embedding failed; page indexed without it");
                    let _ = self
                        .writer
                        .record_embed_failure(
                            page_id,
                            ai_memory_store::EmbedOutcome::Failed,
                            Some(e.to_string()),
                        )
                        .await;
                }
            },
            None => {
                if let Err(e) = self.writer.delete_abstract_embedding(page_id).await {
                    tracing::warn!(error = %e, path = %page_id, "stale abstract embedding cleanup failed");
                    let _ = self
                        .writer
                        .record_embed_failure(
                            page_id,
                            ai_memory_store::EmbedOutcome::Failed,
                            Some(e.to_string()),
                        )
                        .await;
                }
            }
        }
        Ok(())
    }
}

/// The outcome of [`Wiki::write_page_if`].
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum ConditionalWrite {
    /// The precondition held and the page was written; the id is current.
    Written(PageId),
    /// The precondition did not hold and nothing was written.
    Mismatch {
        /// The latest version id at the path, `None` when there is none.
        current: Option<PageId>,
    },
}

/// Outcome of an atomic conditional page batch.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum ConditionalBatchWrite {
    /// Every precondition held and all page versions were written.
    Written(Vec<PageId>),
    /// One precondition changed, so no page version was written.
    Mismatch {
        /// Index of the refused request in the supplied batch.
        index: usize,
        /// Current latest page version, if the path exists.
        current: Option<PageId>,
    },
}

/// Input bundle for [`Wiki::write_page`]. Carries the full 3-tuple
/// identity (`workspace_id`, `project_id`, `path`) plus body & metadata.
#[derive(Debug, Clone)]
pub struct WritePageRequest {
    /// Owning workspace.
    pub workspace_id: WorkspaceId,
    /// Owning project.
    pub project_id: ProjectId,
    /// Relative wiki path.
    pub path: PagePath,
    /// Optional frontmatter (JSON object). May be `Null` for no frontmatter.
    pub frontmatter: serde_json::Value,
    /// Markdown body (excluding any frontmatter block).
    pub body: String,
    /// Tier classification.
    pub tier: Tier,
    /// `true` if the user has pinned this page.
    pub pinned: bool,
    /// Optional pre-derived title (used by `apply_batch` to share the
    /// title between the staged markdown file + the store row).
    #[doc(hidden)]
    pub title: Option<String>,
    /// Optional admission webhook context (op + loop-prevention skip
    /// list + resolved workspace/project names). Populated by
    /// authenticated callers (MCP tool, admin endpoint); left `None` by
    /// internal callers (CLI bootstrap, consolidator from hooks, tests)
    /// — when the chain is configured, `None` is treated as a default
    /// [`AdmissionContext`]. The actor that rides in the webhook payload
    /// comes from [`Self::actor`], not from here (single source of
    /// identity since the v0.8 multi-user merge).
    pub admission_ctx: Option<AdmissionContext>,
    /// Multi-user attribution: the registered user (rung-2) who made
    /// this write, when resolved by the auth middleware. Propagates to
    /// `pages.author_id` and the on-disk frontmatter `last_modified_by`
    /// block (the latter is built from the broader `ActorContext` —
    /// see [`Self::actor`] — so root + anonymous writes also get
    /// frontmatter even though they leave `author_id` NULL). Defaults
    /// to `None` for backward compat with internal callers
    /// (consolidator, lint rewriters) that build `WritePageRequest`
    /// without an HTTP request layer.
    pub author_id: Option<ai_memory_core::UserId>,
    /// Evidence sources backing this write (P2,
    /// docs/design-hindsight-borrowings.md §3), forwarded verbatim to
    /// [`ai_memory_core::NewPage::evidence`]. Populated by the
    /// consolidator from the session(s) it drew on; empty for every
    /// other caller (MCP tool, admin endpoints, lint rewriters).
    pub evidence: Vec<ai_memory_core::PageEvidence>,
    /// Identity carried in the on-disk frontmatter's `last_modified_by`
    /// block AND the admission webhook payload's `ctx.actor`. The auth
    /// middleware fills this from the four-rung resolution (injected as
    /// `Extension<ai_memory_core::ActorContext>`): rung 1 supplies the
    /// configured root template, rung 2 supplies the row's
    /// user/name/email. Defaults to anonymous for backward compat.
    pub actor: ai_memory_core::ActorContext,
}

fn ai_memory_wiki_error(msg: &str) -> crate::WikiError {
    crate::WikiError::Io(std::io::Error::other(msg.to_string()))
}

fn derive_index_metadata(
    path: &PagePath,
    frontmatter: &serde_json::Value,
) -> WikiResult<IndexMetadata> {
    let tier = match frontmatter.get("tier") {
        None => Tier::Semantic,
        Some(serde_json::Value::String(s)) => s.parse::<Tier>().map_err(|e| {
            ai_memory_wiki_error(&format!(
                "invalid tier in frontmatter for {}: {e}",
                path.as_str()
            ))
        })?,
        Some(_) => {
            return Err(ai_memory_wiki_error(&format!(
                "invalid non-string tier in frontmatter for {}",
                path.as_str()
            )));
        }
    };
    let pinned = is_slot_path(path)
        || frontmatter
            .get("pinned")
            .and_then(|v| v.as_bool())
            .unwrap_or(false);
    let expires_at = parse_expires_at(path, frontmatter)?;
    let entities = parse_entities(path, frontmatter)?;
    Ok(IndexMetadata {
        tier,
        pinned,
        expires_at,
        entities,
    })
}

/// Index-relevant metadata derived from a page's frontmatter. Markdown
/// is the source of truth; every field here is rebuildable by a reindex.
struct IndexMetadata {
    tier: Tier,
    pinned: bool,
    expires_at: Option<jiff::Timestamp>,
    entities: Vec<String>,
}

/// Derive a page's indexed entities — the salient nouns it is *about* —
/// from its frontmatter, for the entity retrieval stream and the `as_of`
/// entity-timeline queries (docs/temporal.md).
///
/// Two sources, merged and normalised:
///
/// 1. The explicit `entities:` list an LLM consolidator emits when it
///    runs. Highest precision, but absent on the bulk of a real store —
///    bootstrapped pages predate it and stable pages are never
///    re-consolidated, so relying on it alone leaves the entity index
///    (and therefore `as_of`) empty on any mature deployment.
/// 2. The frontmatter `tags:` list, which nearly every page carries and
///    which is, by construction, "what this page is about" — the same
///    thing entities are meant to capture. Deriving from tags populates
///    the index deterministically, with no LLM and no re-consolidation,
///    for the whole corpus. Broad tags do not distort ranking: the
///    entity stream weights each match by inverse page-frequency, so a
///    tag shared by many pages contributes proportionally little.
///
/// Explicit entities come first so they win the per-page cap
/// ([`normalize_entities`] dedupes and bounds the result). A non-array
/// `entities` value is still a structural error; `tags` is treated
/// leniently (a malformed or missing list simply contributes nothing),
/// because a bad tag must never fail a page write.
pub(crate) fn parse_entities(
    path: &PagePath,
    frontmatter: &serde_json::Value,
) -> WikiResult<Vec<String>> {
    // Strict structural check on the write path only: a non-array
    // `entities` value is a mistake worth surfacing. `tags` stays lenient
    // (see below); the derivation itself is shared with the store's
    // one-shot backfill so the two never drift.
    match frontmatter.get("entities") {
        None | Some(serde_json::Value::Null | serde_json::Value::Array(_)) => {}
        Some(_) => {
            return Err(ai_memory_wiki_error(&format!(
                "invalid non-array entities in frontmatter for {}",
                path.as_str()
            )));
        }
    }
    Ok(ai_memory_core::frontmatter_entity_names(frontmatter))
}

/// Parse the optional frontmatter `expires_at:` key. Accepts RFC3339
/// (`2026-09-01T12:00:00Z`) or a bare date (`2026-09-01` = end of that
/// day, UTC). Anything else is rejected in the same style as an
/// invalid `tier`, so a typo can't silently mean "never expires".
pub(crate) fn parse_expires_at(
    path: &PagePath,
    frontmatter: &serde_json::Value,
) -> WikiResult<Option<jiff::Timestamp>> {
    let raw = match frontmatter.get("expires_at") {
        None | Some(serde_json::Value::Null) => return Ok(None),
        Some(serde_json::Value::String(s)) => s.trim(),
        Some(_) => {
            return Err(ai_memory_wiki_error(&format!(
                "invalid non-string expires_at in frontmatter for {}",
                path.as_str()
            )));
        }
    };
    if raw.is_empty() {
        return Ok(None);
    }
    if let Some(ts) = ai_memory_core::parse_expires_at_instant(raw) {
        return Ok(Some(ts));
    }
    Err(ai_memory_wiki_error(&format!(
        "invalid expires_at in frontmatter for {} (want RFC3339 or YYYY-MM-DD): {raw}",
        path.as_str()
    )))
}

/// OKF conformance for the on-disk file (docs/okf.md): fill the
/// deterministic keys, then stamp `generated.at` — inheriting the
/// current file's value when nothing but the timestamp would change, so
/// an idempotent rewrite emits byte-identical markdown (no git churn,
/// and the store's modulo-`generated.at` comparison keeps the row).
/// The frontmatter `abstract:` line, when it is a non-empty string.
fn frontmatter_abstract(frontmatter: &serde_json::Value) -> Option<&str> {
    frontmatter
        .get("abstract")
        .and_then(serde_json::Value::as_str)
        .map(str::trim)
        .filter(|s| !s.is_empty())
}

fn conform_frontmatter_for_disk(abs: &Path, page_path: &str, markdown: &mut Markdown) {
    conform_frontmatter_for_disk_keeping(abs, page_path, markdown, false);
}

/// [`conform_frontmatter_for_disk`], optionally keeping the markdown's own
/// `generated.at` when the file on disk has other content and conformance
/// changed nothing but the timestamp: a checkpoint restore, whose source is
/// a historical version rather than a new write.
fn conform_frontmatter_for_disk_keeping(
    abs: &Path,
    page_path: &str,
    markdown: &mut Markdown,
    keep_own_generated_at: bool,
) {
    let own_at = ai_memory_core::okf::generated_at(&markdown.frontmatter).map(str::to_string);
    let unconformed = ai_memory_core::okf::strip_generated_at(&markdown.frontmatter);
    ai_memory_core::okf::conform_frontmatter(page_path, &mut markdown.frontmatter);
    let own_at = own_at.filter(|_| {
        keep_own_generated_at
            && ai_memory_core::okf::strip_generated_at(&markdown.frontmatter) == unconformed
    });
    let inherited = std::fs::read_to_string(abs)
        .ok()
        .and_then(|s| crate::markdown::parse(&s).ok())
        .filter(|cur| {
            ai_memory_core::okf::strip_generated_at(&cur.frontmatter)
                == ai_memory_core::okf::strip_generated_at(&markdown.frontmatter)
                && cur.body == markdown.body
        })
        .and_then(|cur| ai_memory_core::okf::generated_at(&cur.frontmatter).map(str::to_string));
    let at = inherited.or(own_at).unwrap_or_else(|| {
        jiff::Timestamp::now()
            .strftime("%Y-%m-%dT%H:%M:%SZ")
            .to_string()
    });
    ai_memory_core::okf::stamp_generated_at(&mut markdown.frontmatter, &at);
}

fn canonicalize_index_frontmatter(
    frontmatter: serde_json::Value,
    tier: Tier,
    pinned: bool,
) -> serde_json::Value {
    let mut obj = match frontmatter {
        serde_json::Value::Object(m) => m,
        serde_json::Value::Null => serde_json::Map::new(),
        other => return other,
    };
    obj.insert(
        "tier".to_string(),
        serde_json::Value::String(tier.as_str().to_string()),
    );
    if pinned {
        obj.insert("pinned".to_string(), serde_json::Value::Bool(true));
    } else if obj.get("pinned").and_then(|v| v.as_bool()) == Some(true) {
        obj.remove("pinned");
    }
    serde_json::Value::Object(obj)
}

fn render_auto_improve_sidecar(detail: &AutoImproveProposalDetail) -> WikiResult<String> {
    let evidence = serde_json::to_string_pretty(&detail.evidence_json)?;
    let patch = detail
        .patch_json
        .as_ref()
        .map(serde_json::to_string_pretty)
        .transpose()?
        .unwrap_or_else(|| "null".into());
    let expected_base = detail
        .expected_base_body_sha256
        .map(|hash| hash.iter().map(|b| format!("{b:02x}")).collect::<String>())
        .unwrap_or_else(|| "none".into());
    Ok(format!(
        "# Pending auto-improvement proposal\n\n\
         - proposal_id: `{}`\n\
         - run_id: `{}`\n\
         - operation: `{}`\n\
         - target_path: `{}`\n\
         - kind: `{}`\n\
         - title: `{}`\n\
         - confidence: `{}`\n\
         - edit_mode: `{}`\n\
         - expected_base_body_sha256: `{}`\n\
         - staged_at: `{}`\n\n\
         ## Rationale\n\n{}\n\n\
         ## Evidence\n\n```json\n{}\n```\n\n\
         ## Patch metadata\n\n```json\n{}\n```\n\n\
         ## Proposed body\n\n{}\n",
        detail.summary.id,
        detail.summary.run_id,
        detail.summary.operation.as_str(),
        detail.summary.target_path.as_str(),
        detail.summary.kind,
        detail.summary.title,
        detail.summary.confidence,
        detail.edit_mode,
        expected_base,
        detail.summary.staged_at,
        detail.rationale,
        evidence,
        patch,
        detail.body_markdown,
    ))
}

#[derive(Debug)]
struct InstalledFile {
    path: PathBuf,
    previous: Option<Vec<u8>>,
}

fn snapshot_existing_file(path: &Path) -> WikiResult<Option<Vec<u8>>> {
    match std::fs::read(path) {
        Ok(bytes) => Ok(Some(bytes)),
        Err(e) if e.kind() == std::io::ErrorKind::NotFound => Ok(None),
        Err(e) => Err(WikiError::Io(e)),
    }
}

fn sync_parent_best_effort(path: &Path) {
    if let Some(parent) = path.parent()
        && let Ok(dir) = std::fs::File::open(parent)
    {
        let _ = dir.sync_all();
    }
}

fn persist_tmp_with_rollback_snapshot(
    git: &GitAdapter,
    tmp: tempfile::NamedTempFile,
    path: &Path,
) -> WikiResult<InstalledFile> {
    let previous = snapshot_existing_file(path)?;
    let persisted = git.persist(tmp, path)?;
    persisted.sync_data()?;
    sync_parent_best_effort(path);
    Ok(InstalledFile {
        path: path.to_path_buf(),
        previous,
    })
}

fn replace_file_with_rollback_snapshot(
    git: &GitAdapter,
    path: &Path,
    bytes: &[u8],
) -> WikiResult<InstalledFile> {
    let previous = snapshot_existing_file(path)?;
    git.write_atomic(path, bytes)?;
    Ok(InstalledFile {
        path: path.to_path_buf(),
        previous,
    })
}

fn rollback_installed_files(git: &GitAdapter, installed: &[InstalledFile]) -> WikiResult<()> {
    for file in installed.iter().rev() {
        match &file.previous {
            Some(bytes) => git.write_atomic(&file.path, bytes)?,
            None => match git.remove_file_checked(&file.path) {
                Ok(()) => sync_parent_best_effort(&file.path),
                Err(WikiError::Io(e)) if e.kind() == std::io::ErrorKind::NotFound => {}
                Err(e) => return Err(e),
            },
        }
    }
    Ok(())
}

fn precondition_holds(precondition: PagePrecondition, current: Option<PageId>) -> bool {
    match precondition {
        PagePrecondition::Absent => current.is_none(),
        PagePrecondition::Latest(expected) => current == Some(expected),
    }
}

fn rollback_or_inconsistent<E: std::fmt::Display>(
    git: &GitAdapter,
    installed: &[InstalledFile],
    cause: &E,
) -> WikiResult<()> {
    if let Err(rollback_err) = rollback_installed_files(git, installed) {
        return Err(WikiError::Io(std::io::Error::other(format!(
            "INCONSISTENT STATE: wiki files changed but store write failed ({cause}) and rollback failed ({rollback_err})"
        ))));
    }
    Ok(())
}

fn quarantine_file(git: &GitAdapter, path: &Path) -> WikiResult<Option<PathBuf>> {
    let Some(parent) = path.parent() else {
        return Err(WikiError::Io(std::io::Error::other(
            "page path has no parent (cannot quarantine delete)",
        )));
    };
    let tmp = tempfile::Builder::new()
        .prefix(".ai-memory-delete.")
        .tempfile_in(parent)?;
    let (_file, quarantine) = tmp.keep().map_err(|e| e.error)?;
    git.remove_file_checked(&quarantine)?;
    match git.rename_checked(path, &quarantine) {
        Ok(()) => Ok(Some(quarantine)),
        Err(e) => {
            let _ = git.remove_file_checked(&quarantine);
            Err(e)
        }
    }
}

fn restore_quarantined_file(
    git: &GitAdapter,
    quarantined: &Option<PathBuf>,
    path: &Path,
    page_path: &PagePath,
) {
    if let Some(quarantine) = quarantined
        && let Err(error) = git.rename_checked(quarantine, path)
    {
        tracing::error!(
            path = %page_path.as_str(),
            quarantine = %quarantine.display(),
            %error,
            "page removal: conditional store mutation failed and restoring quarantined file also failed"
        );
    }
}

fn scrub_frontmatter_strings(value: &mut serde_json::Value, sanitizer: &Sanitizer) {
    match value {
        serde_json::Value::String(s) => {
            *s = sanitizer.scrub(s);
        }
        serde_json::Value::Array(items) => {
            for item in items {
                scrub_frontmatter_strings(item, sanitizer);
            }
        }
        serde_json::Value::Object(map) => {
            for item in map.values_mut() {
                scrub_frontmatter_strings(item, sanitizer);
            }
        }
        serde_json::Value::Null | serde_json::Value::Bool(_) | serde_json::Value::Number(_) => {}
    }
}

/// Append a `last_modified_by` block to the page's frontmatter when the
/// auth middleware resolved a non-anonymous actor. The block carries the
/// stable `username` plus optional `name` + `email`. Designed to be
/// **idempotent on the keys** (the value replaces any prior version), so
/// repeated writes by different users always reflect the latest one
/// rather than accumulating history — historical authorship lives in
/// `pages.author_id` + the supersession chain, not in frontmatter.
///
/// When the actor is anonymous (rung 0) the input is returned
/// untouched — pre-multi-user installs see zero disk-shape change.
fn stamp_last_modified_by(
    frontmatter: serde_json::Value,
    actor: &ai_memory_core::ActorContext,
) -> serde_json::Value {
    let Some(username) = actor.user.as_ref().filter(|s| !s.is_empty()) else {
        return frontmatter;
    };
    let mut obj = match frontmatter {
        serde_json::Value::Object(m) => m,
        serde_json::Value::Null => serde_json::Map::new(),
        // Frontmatter is conventionally an object; preserve a non-null
        // non-object value by NOT mutating it (operator wrote something
        // exotic; we shouldn't clobber it on every write).
        other => return other,
    };
    let mut author = serde_json::Map::new();
    author.insert(
        "username".to_string(),
        serde_json::Value::String(username.clone()),
    );
    if let Some(name) = &actor.name {
        author.insert("name".to_string(), serde_json::Value::String(name.clone()));
    }
    if let Some(email) = &actor.email {
        author.insert(
            "email".to_string(),
            serde_json::Value::String(email.clone()),
        );
    }
    obj.insert(
        "last_modified_by".to_string(),
        serde_json::Value::Object(author),
    );
    serde_json::Value::Object(obj)
}

fn is_slot_path(path: &PagePath) -> bool {
    path.as_str().starts_with("_slots/")
}

#[cfg(test)]
#[allow(clippy::disallowed_methods)]
mod tests {
    use super::*;
    use crate::admission::{FailurePolicy, WebhookConfig};
    use ai_memory_store::{
        AutoImproveProposalOperation, AutoImproveProposalStatus, NewAutoImproveProposal,
        StageAutoImproveRun, Store,
    };
    use tempfile::TempDir;

    struct StoreFailingEmbedder {
        db_path: PathBuf,
        broke_body_table: std::sync::atomic::AtomicBool,
    }

    #[async_trait::async_trait]
    impl Embedder for StoreFailingEmbedder {
        fn provider(&self) -> &'static str {
            "store-failure-test"
        }

        fn model(&self) -> &str {
            "store-failure-test-v1"
        }

        fn dim(&self) -> u32 {
            4
        }

        async fn embed(&self, _text: &str) -> ai_memory_llm::LlmResult<Vec<f32>> {
            if !self
                .broke_body_table
                .swap(true, std::sync::atomic::Ordering::SeqCst)
            {
                rusqlite::Connection::open(&self.db_path)
                    .unwrap()
                    .execute_batch("DROP TABLE page_embeddings")
                    .unwrap();
            }
            Ok(vec![0.5; 4])
        }
    }

    fn store_failing_embedder(store: &Store) -> Arc<dyn Embedder> {
        Arc::new(StoreFailingEmbedder {
            db_path: store.db_path().to_owned(),
            broke_body_table: std::sync::atomic::AtomicBool::new(false),
        })
    }

    #[test]
    fn expires_at_accepts_rfc3339_and_date_only_utc() {
        let path = PagePath::new("notes/ttl.md").unwrap();
        let rfc3339 = serde_json::json!({"expires_at": "2026-08-01T12:00:00-03:00"});
        assert_eq!(
            parse_expires_at(&path, &rfc3339).unwrap().unwrap(),
            "2026-08-01T15:00:00Z".parse::<jiff::Timestamp>().unwrap()
        );

        let date_only = serde_json::json!({"expires_at": "2026-08-01"});
        assert_eq!(
            parse_expires_at(&path, &date_only).unwrap().unwrap(),
            "2026-08-01T23:59:59.999999Z"
                .parse::<jiff::Timestamp>()
                .unwrap()
        );
    }

    #[test]
    fn expires_at_fails_closed_for_invalid_values() {
        let path = PagePath::new("notes/ttl.md").unwrap();
        assert!(
            parse_expires_at(&path, &serde_json::json!({}))
                .unwrap()
                .is_none()
        );
        assert!(
            parse_expires_at(&path, &serde_json::json!({"expires_at": "  "}))
                .unwrap()
                .is_none()
        );
        assert!(parse_expires_at(&path, &serde_json::json!({"expires_at": "soon"})).is_err());
        assert!(parse_expires_at(&path, &serde_json::json!({"expires_at": 7})).is_err());
    }

    #[cfg(windows)]
    fn create_test_symlink_file(target: &Path, link: &Path) -> bool {
        match std::os::windows::fs::symlink_file(target, link) {
            Ok(()) => true,
            Err(e) if e.raw_os_error() == Some(1314) => {
                eprintln!("skipping symlink assertion: Windows symlink privilege unavailable");
                false
            }
            Err(e) => panic!("failed to create symlink {}: {e}", link.display()),
        }
    }

    #[cfg(unix)]
    fn create_test_symlink_file(target: &Path, link: &Path) -> bool {
        std::os::unix::fs::symlink(target, link).unwrap();
        true
    }

    #[tokio::test]
    async fn project_root_is_wiki_root_joined_with_ws_and_proj() {
        let tmp = TempDir::new().unwrap();
        let store = Store::open(tmp.path()).unwrap();
        let wiki = Wiki::new(tmp.path(), store.writer.clone()).unwrap();
        let ws = WorkspaceId::new();
        let proj = ProjectId::new();
        assert_eq!(
            wiki.project_root(ws, proj),
            tmp.path()
                .join("wiki")
                .join(ws.to_string())
                .join(proj.to_string()),
        );
    }

    /// The file a consumer reads off disk is the OKF concept file
    /// (docs/okf.md): required `type`, a `generated {by, at}` stanza,
    /// provenance — emitted by the wiki, not just stored in the index.
    #[tokio::test]
    async fn written_files_are_okf_conformant_on_disk() {
        let tmp = TempDir::new().unwrap();
        let store = Store::open(tmp.path()).unwrap();
        let ws = store.writer.get_or_create_workspace("w").await.unwrap();
        let proj = store
            .writer
            .get_or_create_project(ws, "p", None)
            .await
            .unwrap();
        let wiki = Wiki::new(tmp.path(), store.writer.clone()).unwrap();

        wiki.write_page(req(
            ws,
            proj,
            "gotchas/linker.md",
            "mind the linker",
            serde_json::json!({"title": "Linker gotcha"}),
        ))
        .await
        .unwrap();

        let raw =
            std::fs::read_to_string(wiki.project_root(ws, proj).join("gotchas/linker.md")).unwrap();
        let parsed = crate::markdown::parse(&raw).unwrap();
        assert_eq!(parsed.frontmatter["type"], "Gotcha");
        assert!(
            parsed.frontmatter["generated"]["by"]
                .as_str()
                .unwrap()
                .starts_with("process:ai-memory/")
        );
        assert!(
            parsed.frontmatter["generated"]["at"]
                .as_str()
                .unwrap()
                .ends_with('Z')
        );
        assert!(ai_memory_core::okf::is_conformant(&parsed.frontmatter));
    }

    /// A `[[project:path]]` written as inline code is an example, not a
    /// dependency: the page shows it as code. Indexing it made lint report a
    /// broken cross-project link on a page that has none.
    #[tokio::test]
    async fn a_cross_project_link_in_inline_code_is_not_a_dangling_dependency() {
        let tmp = TempDir::new().unwrap();
        let store = Store::open(tmp.path()).unwrap();
        let ws = store.writer.get_or_create_workspace("w").await.unwrap();
        let proj = store
            .writer
            .get_or_create_project(ws, "p", None)
            .await
            .unwrap();
        let wiki = Wiki::new(tmp.path(), store.writer.clone()).unwrap();

        wiki.write_page(req(
            ws,
            proj,
            "notes/linking.md",
            "Link across projects with `[[other-project:notes/example]]`.\n\
             This page depends on [[other-project:notes/real]].\n",
            serde_json::json!({"title": "Linking"}),
        ))
        .await
        .unwrap();

        let dangling = store
            .reader
            .dangling_cross_project_links(ws, proj)
            .await
            .unwrap();
        let paths: Vec<&str> = dangling.iter().map(|d| d.path.as_str()).collect();
        assert_eq!(paths, vec!["notes/real.md"]);
    }

    /// OKF requires every timestamp to carry an explicit UTC offset, while
    /// the TTL key also accepts a bare date. The file on disk must name the
    /// instant the TTL machinery hides the page, not the date as typed.
    #[tokio::test]
    async fn a_date_only_ttl_lands_on_disk_as_an_okf_stale_after_instant() {
        let tmp = TempDir::new().unwrap();
        let store = Store::open(tmp.path()).unwrap();
        let ws = store.writer.get_or_create_workspace("w").await.unwrap();
        let proj = store
            .writer
            .get_or_create_project(ws, "p", None)
            .await
            .unwrap();
        let wiki = Wiki::new(tmp.path(), store.writer.clone()).unwrap();

        let frontmatter = serde_json::json!({"title": "Freeze", "expires_at": "2099-08-01"});
        wiki.write_page(req(
            ws,
            proj,
            "notes/freeze.md",
            "release freeze",
            frontmatter.clone(),
        ))
        .await
        .unwrap();

        let raw =
            std::fs::read_to_string(wiki.project_root(ws, proj).join("notes/freeze.md")).unwrap();
        let parsed = crate::markdown::parse(&raw).unwrap();
        assert_eq!(parsed.frontmatter["expires_at"], "2099-08-01");
        assert_eq!(
            parsed.frontmatter["stale_after"],
            "2099-08-01T23:59:59.999999Z"
        );
        let path = PagePath::new("notes/freeze.md").unwrap();
        let ttl = parse_expires_at(&path, &frontmatter).unwrap().unwrap();
        assert_eq!(
            parsed.frontmatter["stale_after"]
                .as_str()
                .unwrap()
                .parse::<jiff::Timestamp>()
                .unwrap(),
            ttl
        );
    }

    /// Put `notes/<name>.md` back in the state a pre-fix build left it:
    /// `stale_after` copied verbatim from the date-only `expires_at`, in both
    /// the index row and the file. Returns the row's `(id, updated_at)`.
    fn regress_to_date_only_stale_after(
        tmp: &TempDir,
        wiki: &Wiki,
        ws: WorkspaceId,
        proj: ProjectId,
        rel: &str,
        row: bool,
        file: bool,
    ) -> (Vec<u8>, i64) {
        let db = rusqlite::Connection::open(tmp.path().join("db").join("memory.sqlite")).unwrap();
        let (id, updated_at, fm_str): (Vec<u8>, i64, String) = db
            .query_row(
                "SELECT id, updated_at, frontmatter_json FROM pages \
                 WHERE path = ?1 AND is_latest = 1",
                [rel],
                |r| Ok((r.get(0)?, r.get(1)?, r.get(2)?)),
            )
            .unwrap();
        let regress = |fm: &mut serde_json::Value| {
            let expires = fm["expires_at"].clone();
            fm["stale_after"] = expires;
        };
        if row {
            let mut fm: serde_json::Value = serde_json::from_str(&fm_str).unwrap();
            regress(&mut fm);
            db.execute(
                "UPDATE pages SET frontmatter_json = ?1 WHERE id = ?2",
                rusqlite::params![serde_json::to_string(&fm).unwrap(), id],
            )
            .unwrap();
        }
        if file {
            let abs = wiki.project_root(ws, proj).join(rel);
            let mut md = crate::markdown::parse(&std::fs::read_to_string(&abs).unwrap()).unwrap();
            regress(&mut md.frontmatter);
            std::fs::write(&abs, crate::markdown::emit(&md).unwrap()).unwrap();
        }
        (id, updated_at)
    }

    fn latest_row(tmp: &TempDir, rel: &str) -> (Vec<u8>, i64, serde_json::Value) {
        let db = rusqlite::Connection::open(tmp.path().join("db").join("memory.sqlite")).unwrap();
        let (id, updated_at, fm_str): (Vec<u8>, i64, String) = db
            .query_row(
                "SELECT id, updated_at, frontmatter_json FROM pages \
                 WHERE path = ?1 AND is_latest = 1",
                [rel],
                |r| Ok((r.get(0)?, r.get(1)?, r.get(2)?)),
            )
            .unwrap();
        (id, updated_at, serde_json::from_str(&fm_str).unwrap())
    }

    /// Stores written before the `stale_after` fix hold the bare date the old
    /// derivation copied. The startup repair rewrites row and file in place
    /// (same version row, same `updated_at`, same `generated.at`, same body),
    /// leaves a `stale_after` that is not that copy alone, finishes a file
    /// whose row an interrupted run already repaired, and then does nothing.
    #[tokio::test]
    async fn startup_repair_fixes_a_date_only_stale_after_in_place() {
        let tmp = TempDir::new().unwrap();
        let store = Store::open(tmp.path()).unwrap();
        let ws = store.writer.get_or_create_workspace("w").await.unwrap();
        let proj = store
            .writer
            .get_or_create_project(ws, "p", None)
            .await
            .unwrap();
        let wiki = Wiki::new(tmp.path(), store.writer.clone()).unwrap();
        for (rel, fm) in [
            (
                "notes/freeze.md",
                serde_json::json!({"title": "Freeze", "expires_at": "2099-08-01"}),
            ),
            (
                "notes/interrupted.md",
                serde_json::json!({"title": "Interrupted", "expires_at": "2099-09-01"}),
            ),
            (
                "notes/authored.md",
                serde_json::json!({
                    "title": "Authored",
                    "expires_at": "2099-10-01",
                    "stale_after": "2099-07-01",
                }),
            ),
        ] {
            wiki.write_page(req(ws, proj, rel, "body stays", fm))
                .await
                .unwrap();
        }
        let (freeze_id, freeze_updated) =
            regress_to_date_only_stale_after(&tmp, &wiki, ws, proj, "notes/freeze.md", true, true);
        regress_to_date_only_stale_after(
            &tmp,
            &wiki,
            ws,
            proj,
            "notes/interrupted.md",
            false,
            true,
        );
        let freeze_path = wiki.project_root(ws, proj).join("notes/freeze.md");
        let before =
            crate::markdown::parse(&std::fs::read_to_string(&freeze_path).unwrap()).unwrap();
        assert_eq!(before.frontmatter["stale_after"], "2099-08-01");
        let commits = wiki.git.commit_count();

        assert_eq!(wiki.repair_date_only_stale_after().await.unwrap(), (1, 2));

        let after =
            crate::markdown::parse(&std::fs::read_to_string(&freeze_path).unwrap()).unwrap();
        assert_eq!(
            after.frontmatter["stale_after"],
            "2099-08-01T23:59:59.999999Z"
        );
        assert_eq!(
            after.frontmatter["generated"],
            before.frontmatter["generated"]
        );
        assert_eq!(after.body, before.body);
        let (id, updated_at, row_fm) = latest_row(&tmp, "notes/freeze.md");
        assert_eq!(id, freeze_id, "the repair must not mint a new version");
        assert_eq!(updated_at, freeze_updated);
        assert_eq!(row_fm["stale_after"], "2099-08-01T23:59:59.999999Z");

        let interrupted = crate::markdown::parse(
            &std::fs::read_to_string(wiki.project_root(ws, proj).join("notes/interrupted.md"))
                .unwrap(),
        )
        .unwrap();
        assert_eq!(
            interrupted.frontmatter["stale_after"],
            "2099-09-01T23:59:59.999999Z"
        );
        let (_, _, authored) = latest_row(&tmp, "notes/authored.md");
        assert_eq!(authored["stale_after"], "2099-07-01");
        assert_eq!(wiki.git.commit_count(), commits + 1);

        assert_eq!(wiki.repair_date_only_stale_after().await.unwrap(), (0, 0));
        assert_eq!(wiki.git.commit_count(), commits + 1);
    }

    /// Refused on every platform, not only the case-insensitive ones: the
    /// wiki is synced between them, so what it accepts cannot depend on the
    /// filesystem underneath.
    #[tokio::test]
    async fn a_case_only_path_variant_cannot_destroy_an_existing_page() {
        let tmp = TempDir::new().unwrap();
        let store = Store::open(tmp.path()).unwrap();
        let ws = store.writer.get_or_create_workspace("w").await.unwrap();
        let proj = store
            .writer
            .get_or_create_project(ws, "p", None)
            .await
            .unwrap();
        let wiki = Wiki::new(tmp.path(), store.writer.clone()).unwrap();

        wiki.write_page(req(
            ws,
            proj,
            "concepts/alpha.md",
            "the original alpha body",
            serde_json::json!({"title": "Alpha"}),
        ))
        .await
        .unwrap();

        let collision = wiki
            .write_page(req(
                ws,
                proj,
                "concepts/Alpha.md",
                "a different page entirely",
                serde_json::json!({"title": "Alpha Upper"}),
            ))
            .await;

        let err = collision.expect_err("case-only variant must be refused");
        let msg = err.to_string();
        assert!(
            msg.contains("concepts/alpha.md") && msg.contains("concepts/Alpha.md"),
            "the error must name both pages so the caller can act on it: {msg}"
        );
        let raw =
            std::fs::read_to_string(wiki.project_root(ws, proj).join("concepts/alpha.md")).unwrap();
        assert!(
            raw.contains("the original alpha body"),
            "the existing page's file must survive the refused write: {raw}"
        );
    }

    /// The same collision through Unicode normalization rather than case.
    #[tokio::test]
    async fn an_nfd_path_variant_cannot_destroy_its_nfc_page() {
        let tmp = TempDir::new().unwrap();
        let store = Store::open(tmp.path()).unwrap();
        let ws = store.writer.get_or_create_workspace("w").await.unwrap();
        let proj = store
            .writer
            .get_or_create_project(ws, "p", None)
            .await
            .unwrap();
        let wiki = Wiki::new(tmp.path(), store.writer.clone()).unwrap();

        let nfc = "concepts/caf\u{00e9}.md";
        let nfd = "concepts/cafe\u{0301}.md";

        wiki.write_page(req(
            ws,
            proj,
            nfc,
            "the composed page body",
            serde_json::json!({"title": "Cafe NFC"}),
        ))
        .await
        .unwrap();

        let collision = wiki
            .write_page(req(
                ws,
                proj,
                nfd,
                "a different page entirely",
                serde_json::json!({"title": "Cafe NFD"}),
            ))
            .await;

        assert!(
            collision.is_err(),
            "a decomposed variant of an existing composed path must be refused"
        );
        let raw = std::fs::read_to_string(wiki.project_root(ws, proj).join(nfc)).unwrap();
        assert!(
            raw.contains("the composed page body"),
            "the existing page's file must survive the refused write: {raw}"
        );
    }

    /// The guard must not turn page paths into case-insensitive keys.
    #[tokio::test]
    async fn distinct_paths_are_unaffected_by_the_collision_guard() {
        let tmp = TempDir::new().unwrap();
        let store = Store::open(tmp.path()).unwrap();
        let ws = store.writer.get_or_create_workspace("w").await.unwrap();
        let proj = store
            .writer
            .get_or_create_project(ws, "p", None)
            .await
            .unwrap();
        let wiki = Wiki::new(tmp.path(), store.writer.clone()).unwrap();

        for path in [
            "concepts/alpha.md",
            "concepts/alphabet.md",
            "concepts/nested/alpha.md",
            "decisions/alpha.md",
        ] {
            wiki.write_page(req(ws, proj, path, "body", serde_json::json!({})))
                .await
                .unwrap_or_else(|e| panic!("{path} must be accepted: {e}"));
        }

        // A rewrite is a supersede, not a collision.
        wiki.write_page(req(
            ws,
            proj,
            "concepts/alpha.md",
            "revised body",
            serde_json::json!({}),
        ))
        .await
        .unwrap();
    }

    /// An unchanged rewrite must emit byte-identical markdown: the
    /// `generated.at` inheritance keeps the timestamp, so neither git
    /// nor the store sees a phantom new version.
    #[tokio::test]
    async fn an_idempotent_rewrite_keeps_the_file_bytes_and_the_row() {
        let tmp = TempDir::new().unwrap();
        let store = Store::open(tmp.path()).unwrap();
        let ws = store.writer.get_or_create_workspace("w").await.unwrap();
        let proj = store
            .writer
            .get_or_create_project(ws, "p", None)
            .await
            .unwrap();
        let wiki = Wiki::new(tmp.path(), store.writer.clone()).unwrap();

        let request = || {
            req(
                ws,
                proj,
                "notes/idem.md",
                "stable body",
                serde_json::json!({"title": "Idem"}),
            )
        };
        let id1 = wiki.write_page(request()).await.unwrap();
        let abs = wiki.project_root(ws, proj).join("notes/idem.md");
        let bytes1 = std::fs::read(&abs).unwrap();

        // Far enough apart that a re-stamped `generated.at` would differ.
        tokio::time::sleep(std::time::Duration::from_millis(1100)).await;
        let id2 = wiki.write_page(request()).await.unwrap();
        let bytes2 = std::fs::read(&abs).unwrap();

        assert_eq!(id1, id2, "identical rewrite superseded the page");
        assert_eq!(bytes1, bytes2, "identical rewrite changed the file bytes");
    }

    /// A real content change updates `generated.at` — inheritance only
    /// covers the unchanged case.
    #[tokio::test]
    async fn a_content_change_updates_generated_at() {
        let tmp = TempDir::new().unwrap();
        let store = Store::open(tmp.path()).unwrap();
        let ws = store.writer.get_or_create_workspace("w").await.unwrap();
        let proj = store
            .writer
            .get_or_create_project(ws, "p", None)
            .await
            .unwrap();
        let wiki = Wiki::new(tmp.path(), store.writer.clone()).unwrap();

        wiki.write_page(req(
            ws,
            proj,
            "notes/evolving.md",
            "v1",
            serde_json::json!({"title": "Evolving"}),
        ))
        .await
        .unwrap();
        let abs = wiki.project_root(ws, proj).join("notes/evolving.md");
        let at1 = ai_memory_core::okf::generated_at(
            &crate::markdown::parse(&std::fs::read_to_string(&abs).unwrap())
                .unwrap()
                .frontmatter,
        )
        .unwrap()
        .to_string();

        tokio::time::sleep(std::time::Duration::from_millis(1100)).await;
        wiki.write_page(req(
            ws,
            proj,
            "notes/evolving.md",
            "v2 - changed",
            serde_json::json!({"title": "Evolving"}),
        ))
        .await
        .unwrap();
        let at2 = ai_memory_core::okf::generated_at(
            &crate::markdown::parse(&std::fs::read_to_string(&abs).unwrap())
                .unwrap()
                .frontmatter,
        )
        .unwrap()
        .to_string();
        assert_ne!(at1, at2, "content change kept the old generated.at");
    }

    #[tokio::test]
    async fn upgrade_baseline_checkpoint_commits_existing_uncommitted_tree_once() {
        let tmp = TempDir::new().unwrap();
        let store = Store::open(tmp.path()).unwrap();
        let ws = store
            .writer
            .get_or_create_workspace("default")
            .await
            .unwrap();
        let proj = store
            .writer
            .get_or_create_project(ws, "scratch", None)
            .await
            .unwrap();
        let wiki = Wiki::new(tmp.path(), store.writer.clone()).unwrap();

        wiki.write_page(req(
            ws,
            proj,
            "notes/baseline.md",
            "existing page before recovery checkpoints",
            serde_json::json!({ "title": "Baseline" }),
        ))
        .await
        .unwrap();

        assert_eq!(wiki.git().commit_count(), 0);
        let oid = wiki
            .ensure_upgrade_baseline_checkpoint()
            .unwrap()
            .expect("existing wiki content should be checkpointed");
        assert_eq!(wiki.git().commit_count(), 1);
        assert!(wiki.ensure_upgrade_baseline_checkpoint().unwrap().is_none());
        assert_eq!(wiki.git().commit_count(), 1);

        let checkpoints = wiki.recent_checkpoints(1).unwrap();
        assert_eq!(checkpoints[0].oid, oid.to_string());
        assert_eq!(
            checkpoints[0].summary,
            "upgrade baseline: existing wiki tree before recovery checkpoints"
        );
    }

    fn req(
        ws: WorkspaceId,
        proj: ProjectId,
        path: &str,
        body: &str,
        fm: serde_json::Value,
    ) -> WritePageRequest {
        WritePageRequest {
            workspace_id: ws,
            project_id: proj,
            path: PagePath::new(path).unwrap(),
            frontmatter: fm,
            body: body.into(),
            tier: Tier::Semantic,
            pinned: false,
            title: None,
            admission_ctx: None,
            author_id: None,
            actor: ai_memory_core::ActorContext::anonymous(),
            evidence: Vec::new(),
        }
    }

    fn proposal(
        path: &str,
        op: AutoImproveProposalOperation,
        body: &str,
    ) -> NewAutoImproveProposal {
        NewAutoImproveProposal {
            operation: op,
            target_path: PagePath::new(path).unwrap(),
            kind: "note".into(),
            title: "Proposed".into(),
            confidence: 0.9,
            rationale: "test rationale".into(),
            evidence_json: serde_json::json!([{ "source": "test" }]),
            body_markdown: body.into(),
            artifact_sha256: None,
            edit_mode: None,
            patch_json: None,
            expected_base_body_sha256: None,
        }
    }

    fn proposal_with_fields(
        path: &str,
        body: &str,
        rationale: &str,
        evidence_json: serde_json::Value,
    ) -> NewAutoImproveProposal {
        NewAutoImproveProposal {
            rationale: rationale.into(),
            evidence_json,
            ..proposal(path, AutoImproveProposalOperation::Create, body)
        }
    }

    async fn stage_one(
        store: &Store,
        ws: WorkspaceId,
        proj: ProjectId,
        path: &str,
        body: &str,
    ) -> AutoImproveProposalId {
        stage_one_op(
            store,
            ws,
            proj,
            proposal(path, AutoImproveProposalOperation::Create, body),
        )
        .await
    }

    async fn stage_one_op(
        store: &Store,
        ws: WorkspaceId,
        proj: ProjectId,
        proposal: NewAutoImproveProposal,
    ) -> AutoImproveProposalId {
        store
            .writer
            .stage_auto_improve_run(StageAutoImproveRun {
                workspace_id: ws,
                project_id: proj,
                session_id: None,
                provider: Some("test".into()),
                model: Some("model".into()),
                summary: Some("summary".into()),
                warnings_json: serde_json::json!([]),
                rejected_candidates_json: serde_json::json!([]),
                config_json: serde_json::json!({}),
                proposal_actor: ActorContext {
                    agent: Some("auto_improve".into()),
                    ..ActorContext::default()
                },
                proposals: vec![proposal],
            })
            .await
            .unwrap()
            .proposal_ids[0]
    }

    async fn scoped(tmp: &TempDir) -> (Store, Wiki, WorkspaceId, ProjectId) {
        let store = Store::open(tmp.path()).unwrap();
        let ws = store
            .writer
            .get_or_create_workspace("default")
            .await
            .unwrap();
        let proj = store
            .writer
            .get_or_create_project(ws, "scratch", None)
            .await
            .unwrap();
        let wiki = Wiki::new(tmp.path(), store.writer.clone())
            .unwrap()
            .with_store_reader(store.reader.clone());
        (store, wiki, ws, proj)
    }

    #[test]
    fn append_under_project_public_api_remains_io_result() {
        let method: fn(&Wiki, WorkspaceId, ProjectId, &str, &[u8]) -> std::io::Result<PathBuf> =
            Wiki::append_under_project;
        let _ = method;
    }

    #[cfg(unix)]
    fn symlink(target: &Path, link: &Path) {
        std::os::unix::fs::symlink(target, link).unwrap();
    }

    #[cfg(unix)]
    fn assert_confined<T>(result: WikiResult<T>) {
        assert!(
            matches!(result, Err(WikiError::Confinement { .. })),
            "expected confinement refusal"
        );
    }

    #[cfg(unix)]
    #[tokio::test]
    async fn page_reads_refuse_leaf_and_ancestor_symlinks_without_fallback_classification() {
        let tmp = TempDir::new().unwrap();
        let (_store, wiki, ws, proj) = scoped(&tmp).await;
        let outside = TempDir::new().unwrap();
        let outside_page = outside.path().join("page.md");
        std::fs::write(&outside_page, "# Outside\n\ncanary\n").unwrap();
        let project = wiki.project_root(ws, proj);
        std::fs::create_dir_all(&project).unwrap();

        let leaf = PagePath::new("leaf.md").unwrap();
        symlink(&outside_page, &wiki.abs_path(ws, proj, &leaf));
        let leaf_error = wiki.read_page(ws, proj, &leaf).unwrap_err();
        assert!(matches!(leaf_error, WikiError::Confinement { .. }));
        assert!(
            !matches!(leaf_error, WikiError::Io(ref error) if error.kind() == std::io::ErrorKind::NotFound)
        );

        let outside_dir = outside.path().join("tree");
        std::fs::create_dir(&outside_dir).unwrap();
        std::fs::write(outside_dir.join("page.md"), "# Outside ancestor\n").unwrap();
        symlink(&outside_dir, &project.join("linked"));
        assert_confined(wiki.read_page(ws, proj, &PagePath::new("linked/page.md").unwrap()));

        let dangling = PagePath::new("dangling.md").unwrap();
        symlink(
            &outside.path().join("missing.md"),
            &wiki.abs_path(ws, proj, &dangling),
        );
        assert_confined(wiki.read_page(ws, proj, &dangling));
    }

    #[cfg(unix)]
    #[tokio::test]
    async fn page_mutations_refuse_ancestor_symlink_and_leave_outside_and_store_unchanged() {
        let tmp = TempDir::new().unwrap();
        let (store, wiki, ws, proj) = scoped(&tmp).await;
        let outside = TempDir::new().unwrap();
        let project = wiki.project_root(ws, proj);
        std::fs::create_dir_all(&project).unwrap();
        std::fs::write(outside.path().join("write.md"), "outside canary").unwrap();
        symlink(outside.path(), &project.join("linked"));

        assert_confined(
            wiki.write_page(req(
                ws,
                proj,
                "linked/write.md",
                "blocked",
                serde_json::json!({}),
            ))
            .await,
        );
        assert_confined(
            wiki.apply_batch(vec![req(
                ws,
                proj,
                "linked/batch.md",
                "blocked",
                serde_json::json!({}),
            )])
            .await,
        );
        assert_confined(
            wiki.delete_page(
                ws,
                proj,
                &PagePath::new("linked/write.md").unwrap(),
                None,
                None,
            )
            .await,
        );
        assert_eq!(
            std::fs::read_to_string(outside.path().join("write.md")).unwrap(),
            "outside canary"
        );
        assert!(!outside.path().join("batch.md").exists());
        assert!(
            store
                .reader
                .search_pages("blocked".into(), 10, None)
                .await
                .unwrap()
                .is_empty()
        );
    }

    #[cfg(unix)]
    #[tokio::test]
    async fn confinement_refusal_happens_before_blocking_and_observer_admission() {
        use axum::Router;
        use axum::extract::State;
        use axum::http::StatusCode;
        use axum::routing::post;
        use std::sync::atomic::{AtomicUsize, Ordering};

        let calls = Arc::new(AtomicUsize::new(0));
        let app = Router::new()
            .route(
                "/observe",
                post(|State(calls): State<Arc<AtomicUsize>>| async move {
                    calls.fetch_add(1, Ordering::SeqCst);
                    StatusCode::NO_CONTENT
                }),
            )
            .with_state(calls.clone());
        let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();
        let address = listener.local_addr().unwrap();
        tokio::spawn(async move { axum::serve(listener, app).await.unwrap() });

        let tmp = TempDir::new().unwrap();
        let (_store, wiki, ws, proj) = scoped(&tmp).await;
        let outside = TempDir::new().unwrap();
        let project = wiki.project_root(ws, proj);
        std::fs::create_dir_all(&project).unwrap();
        symlink(outside.path(), &project.join("linked"));
        let wiki = wiki.with_admission_chain(
            AdmissionChain::new(vec![WebhookConfig {
                name: "observer".into(),
                url: format!("http://{address}/observe"),
                timeout_ms: 1_000,
                failure_policy: FailurePolicy::Ignore,
                events: vec![AdmissionOp::WritePage, AdmissionOp::Delete],
                blocking: true,
            }])
            .unwrap(),
        );

        assert_confined(
            wiki.write_page(req(
                ws,
                proj,
                "linked/write.md",
                "blocked",
                serde_json::json!({}),
            ))
            .await,
        );
        assert_confined(
            wiki.delete_page(
                ws,
                proj,
                &PagePath::new("linked/delete.md").unwrap(),
                None,
                None,
            )
            .await,
        );
        tokio::time::sleep(std::time::Duration::from_millis(50)).await;
        assert_eq!(calls.load(Ordering::SeqCst), 0);
    }

    #[cfg(unix)]
    #[tokio::test]
    async fn restore_and_reindex_refuse_ancestor_symlink_without_touching_canary_or_db() {
        let tmp = TempDir::new().unwrap();
        let (store, wiki, ws, proj) = scoped(&tmp).await;
        let committed = PagePath::new("notes/source.md").unwrap();
        wiki.write_page(req(
            ws,
            proj,
            committed.as_str(),
            "safe",
            serde_json::json!({}),
        ))
        .await
        .unwrap();
        wiki.commit_all("fixture").unwrap();

        let outside = TempDir::new().unwrap();
        let canary = outside.path().join("target.md");
        std::fs::write(&canary, "canary").unwrap();
        symlink(outside.path(), &wiki.project_root(ws, proj).join("linked"));
        let linked = PagePath::new("linked/target.md").unwrap();
        assert_confined(wiki.reindex_page(ws, proj, linked.clone()).await);
        assert_confined(
            wiki.restore_page_from_checkpoint(ws, proj, linked.clone(), "HEAD")
                .await,
        );
        assert_eq!(std::fs::read_to_string(&canary).unwrap(), "canary");
        assert!(
            store
                .reader
                .page_body_by_ids(ws, proj, linked.as_str())
                .await
                .unwrap()
                .is_none()
        );
    }

    #[cfg(unix)]
    #[test]
    fn linked_wiki_root_is_refused_during_construction() {
        let tmp = TempDir::new().unwrap();
        let outside = TempDir::new().unwrap();
        symlink(outside.path(), &tmp.path().join("wiki"));
        let store = Store::open(tmp.path()).unwrap();
        assert!(matches!(
            Wiki::new(tmp.path(), store.writer.clone()),
            Err(WikiError::Confinement { .. })
        ));
    }

    #[cfg(unix)]
    #[tokio::test]
    async fn linked_or_dangling_scope_roots_are_refused_but_real_roots_work() {
        let tmp = TempDir::new().unwrap();
        let (store, wiki, ws, proj) = scoped(&tmp).await;
        wiki.write_page(req(
            ws,
            proj,
            "notes/control.md",
            "control",
            serde_json::json!({}),
        ))
        .await
        .unwrap();

        let outside = TempDir::new().unwrap();
        let linked_ws = WorkspaceId::new();
        symlink(outside.path(), &wiki.root().join(linked_ws.to_string()));
        assert_confined(
            wiki.write_page(req(
                linked_ws,
                ProjectId::new(),
                "notes/refused.md",
                "blocked",
                serde_json::json!({}),
            ))
            .await,
        );

        let workspace = wiki.root().join(ws.to_string());
        let linked_project = ProjectId::new();
        symlink(outside.path(), &workspace.join(linked_project.to_string()));
        assert_confined(
            wiki.write_page(req(
                ws,
                linked_project,
                "notes/refused.md",
                "blocked",
                serde_json::json!({}),
            ))
            .await,
        );

        let dangling_project = ProjectId::new();
        symlink(
            &outside.path().join("missing"),
            &workspace.join(dangling_project.to_string()),
        );
        assert_confined(
            wiki.write_page(req(
                ws,
                dangling_project,
                "notes/refused.md",
                "blocked",
                serde_json::json!({}),
            ))
            .await,
        );
        assert_eq!(
            wiki.read_page(ws, proj, &PagePath::new("notes/control.md").unwrap())
                .unwrap()
                .body,
            "control"
        );
        assert!(
            store
                .reader
                .search_pages("blocked".into(), 10, None)
                .await
                .unwrap()
                .is_empty()
        );
    }

    #[tokio::test]
    async fn write_page_embeds_frontmatter_abstract_and_cleans_stale_rows() {
        let tmp = TempDir::new().unwrap();
        let (store, wiki, ws, proj) = scoped(&tmp).await;
        let embedder: Arc<dyn ai_memory_llm::Embedder> =
            Arc::new(ai_memory_llm::SyntheticEmbedder::new(64));
        let wiki = wiki.with_embedder(embedder);
        let write_abs = |frontmatter: serde_json::Value| {
            wiki.write_page(WritePageRequest {
                workspace_id: ws,
                project_id: proj,
                path: PagePath::new("notes/abs.md").unwrap(),
                frontmatter,
                body: "alpha bravo".to_string(),
                tier: Tier::Semantic,
                pinned: false,
                title: None,
                admission_ctx: None,
                author_id: None,
                actor: ActorContext::anonymous(),
                evidence: Vec::new(),
            })
        };

        write_abs(serde_json::json!({"title": "abs", "abstract": "one-line summary"}))
            .await
            .unwrap();
        let ids = store
            .reader
            .abstract_embedded_page_ids(
                ws,
                proj,
                "synthetic".to_string(),
                "bag-of-words-v1".to_string(),
                64,
            )
            .await
            .unwrap();
        assert_eq!(ids.len(), 1, "abstract embedded at write time");

        // Rewriting without the key leaves the latest version without an
        // abstract row; the superseded version's row stays behind, matching
        // the body embedding's versioning semantics.
        write_abs(serde_json::json!({"title": "abs"}))
            .await
            .unwrap();
        let ids = store
            .reader
            .abstract_embedded_page_ids(
                ws,
                proj,
                "synthetic".to_string(),
                "bag-of-words-v1".to_string(),
                64,
            )
            .await
            .unwrap();
        assert!(
            ids.is_empty(),
            "latest version must not carry an abstract row"
        );
    }

    #[tokio::test]
    async fn auto_improve_sidecar_writes_non_indexed_review_file() {
        let tmp = TempDir::new().unwrap();
        let (store, wiki, ws, proj) = scoped(&tmp).await;
        let id = stage_one(&store, ws, proj, "notes/proposed.md", "proposed body").await;
        let sidecar = wiki.write_auto_improve_sidecar(ws, proj, id).await.unwrap();
        assert_eq!(
            sidecar,
            wiki.project_root(ws, proj)
                .join(format!("_pending/auto-improve/{id}.md"))
        );
        let content = std::fs::read_to_string(sidecar).unwrap();
        assert!(content.contains("Pending auto-improvement proposal"));
        assert!(content.contains("proposed body"));
        assert!(
            store
                .reader
                .search_pages_for_project(ws, proj, "proposed body".into(), 10, None)
                .await
                .unwrap()
                .is_empty()
        );
    }

    #[tokio::test]
    async fn auto_improve_sidecar_scrubs_stored_proposal_secrets() {
        let tmp = TempDir::new().unwrap();
        let (store, wiki, ws, proj) = scoped(&tmp).await;
        let id = stage_one_op(
            &store,
            ws,
            proj,
            proposal_with_fields(
                "notes/leaky-proposal.md",
                "body has ANTHROPIC_API_KEY=sk-ant-leak-1234567890abcdef",
                "rationale has postgres://admin:[email protected]/prod",
                serde_json::json!([{ "secret": "GH_TOKEN=ghp_FAKEAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA" }]),
            ),
        )
        .await;
        let sidecar = wiki.write_auto_improve_sidecar(ws, proj, id).await.unwrap();
        let content = std::fs::read_to_string(sidecar).unwrap();
        assert!(content.contains("[REDACTED:"));
        assert!(!content.contains("sk-ant-leak"));
        assert!(!content.contains("hunter2"));
        assert!(!content.contains("ghp_"));
    }

    #[tokio::test]
    async fn reindex_page_refuses_pending_auto_improve_sidecar() {
        let tmp = TempDir::new().unwrap();
        let (_store, wiki, ws, proj) = scoped(&tmp).await;
        let path = PagePath::new("_pending/auto-improve/x.md").unwrap();
        let abs = wiki.abs_path(ws, proj, &path);
        std::fs::create_dir_all(abs.parent().unwrap()).unwrap();
        std::fs::write(&abs, "---\ntitle: pending\n---\nbody").unwrap();
        assert!(wiki.reindex_page(ws, proj, path).await.is_err());
    }

    #[tokio::test]
    async fn reindex_page_derives_tier_and_pinned_from_frontmatter() {
        // Regression: the watcher's reindex_page must honour the on-disk
        // frontmatter tier/pinned (as synth.rs writes for session pages),
        // not hardcode Tier::Semantic / is_slot_path. Hardcoding flipped
        // episodic session pages to semantic (so they never decayed) and
        // dropped the frontmatter pin, churning a spurious version per write.
        let tmp = TempDir::new().unwrap();
        let (store, wiki, ws, proj) = scoped(&tmp).await;

        // Episodic + pinned page on disk, exactly like a synth session page.
        let path = PagePath::new("sessions/abc.md").unwrap();
        let abs = wiki.abs_path(ws, proj, &path);
        std::fs::create_dir_all(abs.parent().unwrap()).unwrap();
        std::fs::write(
            &abs,
            "---\ntitle: S\ntier: episodic\npinned: true\n---\nbody",
        )
        .unwrap();

        let id1 = wiki.reindex_page(ws, proj, path.clone()).await.unwrap();
        let meta = store
            .reader
            .page_meta("default", "scratch", path.as_str())
            .await
            .unwrap()
            .unwrap();
        assert_eq!(
            meta.tier, "episodic",
            "reindex must keep the frontmatter tier, not force semantic"
        );
        assert!(meta.pinned, "reindex must keep the frontmatter pinned flag");

        // Idempotent: re-running on the unchanged file must not supersede.
        let id2 = wiki.reindex_page(ws, proj, path).await.unwrap();
        assert_eq!(
            id1, id2,
            "reindex of an unchanged page must be a no-op (no spurious version)"
        );

        // Backward-compat: a page with no tier in frontmatter defaults to semantic.
        let plain = PagePath::new("notes/plain.md").unwrap();
        let pabs = wiki.abs_path(ws, proj, &plain);
        std::fs::create_dir_all(pabs.parent().unwrap()).unwrap();
        std::fs::write(&pabs, "---\ntitle: P\n---\nbody").unwrap();
        wiki.reindex_page(ws, proj, plain.clone()).await.unwrap();
        let pmeta = store
            .reader
            .page_meta("default", "scratch", plain.as_str())
            .await
            .unwrap()
            .unwrap();
        assert_eq!(
            pmeta.tier, "semantic",
            "a page without a frontmatter tier must default to semantic"
        );

        let invalid = PagePath::new("notes/bad-tier.md").unwrap();
        let iabs = wiki.abs_path(ws, proj, &invalid);
        std::fs::write(&iabs, "---\ntitle: Bad\ntier: episdoic\n---\nbody").unwrap();
        assert!(
            wiki.reindex_page(ws, proj, invalid).await.is_err(),
            "malformed tier frontmatter must fail closed instead of silently becoming semantic"
        );

        let non_string = PagePath::new("notes/non-string-tier.md").unwrap();
        let ns_abs = wiki.abs_path(ws, proj, &non_string);
        std::fs::write(&ns_abs, "---\ntitle: Bad\ntier: 7\n---\nbody").unwrap();
        assert!(
            wiki.reindex_page(ws, proj, non_string).await.is_err(),
            "non-string tier frontmatter must fail closed"
        );
    }

    /// The same page saved with CRLF line endings (a Windows editor, or a
    /// wiki checked out with `core.autocrlf=true`) must index the same way:
    /// its frontmatter is still the source of truth for tier/pinned/title,
    /// not body text ahead of the H1.
    #[tokio::test]
    async fn reindex_page_reads_crlf_frontmatter() {
        let tmp = TempDir::new().unwrap();
        let (store, wiki, ws, proj) = scoped(&tmp).await;

        let path = PagePath::new("sessions/crlf.md").unwrap();
        let abs = wiki.abs_path(ws, proj, &path);
        std::fs::create_dir_all(abs.parent().unwrap()).unwrap();
        std::fs::write(
            &abs,
            "---\r\ntitle: S\r\ntier: episodic\r\npinned: true\r\n---\r\nbody\r\n",
        )
        .unwrap();

        wiki.reindex_page(ws, proj, path.clone()).await.unwrap();
        let meta = store
            .reader
            .page_meta("default", "scratch", path.as_str())
            .await
            .unwrap()
            .unwrap();
        assert_eq!(meta.title, "S", "the frontmatter title must win");
        assert_eq!(meta.tier, "episodic");
        assert!(meta.pinned, "a CRLF `pinned: true` must still pin the page");
    }

    #[tokio::test]
    async fn write_paths_persist_index_metadata_for_reindex_round_trip() {
        let tmp = TempDir::new().unwrap();
        let (store, wiki, ws, proj) = scoped(&tmp).await;

        let path = PagePath::new("notes/episodic.md").unwrap();
        let mut request = req(
            ws,
            proj,
            path.as_str(),
            "episodic body",
            serde_json::json!({"title": "Episodic"}),
        );
        request.tier = Tier::Episodic;
        request.pinned = true;
        let id = wiki.write_page(request).await.unwrap();

        let md = wiki.read_page(ws, proj, &path).unwrap();
        assert_eq!(md.frontmatter["tier"], "episodic");
        assert_eq!(md.frontmatter["pinned"], true);
        let id2 = wiki.reindex_page(ws, proj, path.clone()).await.unwrap();
        assert_eq!(id, id2, "write then reindex should be idempotent");
        let meta = store
            .reader
            .page_meta("default", "scratch", path.as_str())
            .await
            .unwrap()
            .unwrap();
        assert_eq!(meta.tier, "episodic");
        assert!(meta.pinned);

        let batch_path = PagePath::new("notes/procedural.md").unwrap();
        let mut batch_req = req(
            ws,
            proj,
            batch_path.as_str(),
            "procedure body",
            serde_json::json!({"title": "Procedure"}),
        );
        batch_req.tier = Tier::Procedural;
        wiki.apply_batch(vec![batch_req]).await.unwrap();
        let md = wiki.read_page(ws, proj, &batch_path).unwrap();
        assert_eq!(md.frontmatter["tier"], "procedural");
        wiki.reindex_page(ws, proj, batch_path.clone())
            .await
            .unwrap();
        let meta = store
            .reader
            .page_meta("default", "scratch", batch_path.as_str())
            .await
            .unwrap()
            .unwrap();
        assert_eq!(meta.tier, "procedural");
        assert!(!meta.pinned);

        let frontmatter_pinned_path = PagePath::new("notes/frontmatter-pinned.md").unwrap();
        let mut frontmatter_pinned_req = req(
            ws,
            proj,
            frontmatter_pinned_path.as_str(),
            "frontmatter pinned body",
            serde_json::json!({"title": "Frontmatter Pinned", "pinned": true}),
        );
        frontmatter_pinned_req.pinned = false;
        wiki.write_page(frontmatter_pinned_req).await.unwrap();
        wiki.reindex_page(ws, proj, frontmatter_pinned_path.clone())
            .await
            .unwrap();
        let meta = store
            .reader
            .page_meta("default", "scratch", frontmatter_pinned_path.as_str())
            .await
            .unwrap()
            .unwrap();
        assert!(meta.pinned);
    }

    #[tokio::test]
    async fn restore_page_from_checkpoint_preserves_frontmatter_metadata() {
        let tmp = TempDir::new().unwrap();
        let (store, wiki, ws, proj) = scoped(&tmp).await;
        let path = PagePath::new("sessions/restored.md").unwrap();
        let abs = wiki.abs_path(ws, proj, &path);
        std::fs::create_dir_all(abs.parent().unwrap()).unwrap();
        std::fs::write(
            &abs,
            "---\ntitle: Restored\ntier: episodic\npinned: true\n---\nold",
        )
        .unwrap();
        let rev = wiki.commit_all("checkpoint").unwrap().unwrap().to_string();
        std::fs::write(&abs, "---\ntitle: Restored\ntier: semantic\n---\nnew").unwrap();

        wiki.restore_page_from_checkpoint(ws, proj, path.clone(), &rev)
            .await
            .unwrap();
        let meta = store
            .reader
            .page_meta("default", "scratch", path.as_str())
            .await
            .unwrap()
            .unwrap();
        assert_eq!(meta.tier, "episodic");
        assert!(meta.pinned);
        let md = wiki.read_page(ws, proj, &path).unwrap();
        assert_eq!(md.body.trim(), "old");
    }

    #[tokio::test]
    async fn restore_page_collision_keeps_disk_and_store_unchanged() {
        let tmp = TempDir::new().unwrap();
        let (store, wiki, ws, proj) = scoped(&tmp).await;
        let historical = PagePath::new("notes/A.md").unwrap();
        let current = PagePath::new("notes/a.md").unwrap();
        wiki.write_page(req(
            ws,
            proj,
            historical.as_str(),
            "historical",
            serde_json::json!({}),
        ))
        .await
        .unwrap();
        let rev = wiki.commit_all("checkpoint").unwrap().unwrap().to_string();
        wiki.delete_page(ws, proj, &historical, None, None)
            .await
            .unwrap();
        let current_id = wiki
            .write_page(req(
                ws,
                proj,
                current.as_str(),
                "current",
                serde_json::json!({}),
            ))
            .await
            .unwrap();
        let current_abs = wiki.abs_path(ws, proj, &current);
        let historical_abs = wiki.abs_path(ws, proj, &historical);
        let before = std::fs::read(&current_abs).unwrap();
        // On case-folding filesystems these paths already address one file;
        // on case-sensitive filesystems the rejected restore must not create A.md.
        let historical_existed = historical_abs.exists();

        let err = wiki
            .restore_page_from_checkpoint(ws, proj, historical.clone(), &rev)
            .await
            .unwrap_err();

        assert!(
            err.to_string().contains("collides with existing page"),
            "{err}"
        );
        assert_eq!(std::fs::read(&current_abs).unwrap(), before);
        assert_eq!(historical_abs.exists(), historical_existed);
        assert_eq!(
            store
                .reader
                .latest_page_id_by_ids(ws, proj, current.as_str().into())
                .await
                .unwrap(),
            Some(current_id)
        );
        assert_eq!(
            store
                .reader
                .latest_page_id_by_ids(ws, proj, historical.as_str().into())
                .await
                .unwrap(),
            None
        );
        assert_eq!(
            store
                .reader
                .page_body_by_ids(ws, proj, current.as_str())
                .await
                .unwrap()
                .unwrap()
                .body,
            "current"
        );
    }

    #[tokio::test]
    async fn restore_page_store_failure_rolls_back_replacement_and_new_file() {
        for existing in [true, false] {
            let tmp = TempDir::new().unwrap();
            let (store, wiki, ws, proj) = scoped(&tmp).await;
            let path = PagePath::new("notes/restore.md").unwrap();
            wiki.write_page(req(
                ws,
                proj,
                path.as_str(),
                "historical",
                serde_json::json!({}),
            ))
            .await
            .unwrap();
            let rev = wiki.commit_all("checkpoint").unwrap().unwrap().to_string();
            let expected_id = if existing {
                Some(
                    wiki.write_page(req(
                        ws,
                        proj,
                        path.as_str(),
                        "current",
                        serde_json::json!({}),
                    ))
                    .await
                    .unwrap(),
                )
            } else {
                wiki.delete_page(ws, proj, &path, None, None).await.unwrap();
                None
            };
            let abs = wiki.abs_path(ws, proj, &path);
            let before = snapshot_existing_file(&abs).unwrap();
            // Reject the real store transaction after restore installs the file.
            // Both rollback branches must work regardless of filesystem casing.
            let db = rusqlite::Connection::open(tmp.path().join("db/memory.sqlite")).unwrap();
            db.execute_batch(
                "CREATE TRIGGER reject_restore BEFORE INSERT ON pages \
                WHEN NEW.path = 'notes/restore.md' BEGIN \
                SELECT RAISE(ABORT, 'injected restore failure'); END;",
            )
            .unwrap();

            let err = wiki
                .restore_page_from_checkpoint(ws, proj, path.clone(), &rev)
                .await
                .unwrap_err();

            assert!(
                err.to_string().contains("injected restore failure"),
                "{err}"
            );
            assert_eq!(snapshot_existing_file(&abs).unwrap(), before);
            assert_eq!(
                store
                    .reader
                    .latest_page_id_by_ids(ws, proj, path.as_str().into())
                    .await
                    .unwrap(),
                expected_id
            );
            if existing {
                assert_eq!(
                    store
                        .reader
                        .page_body_by_ids(ws, proj, path.as_str())
                        .await
                        .unwrap()
                        .unwrap()
                        .body,
                    "current"
                );
            }

            db.execute_batch("DROP TRIGGER reject_restore;").unwrap();
            wiki.restore_page_from_checkpoint(ws, proj, path.clone(), &rev)
                .await
                .unwrap();
            assert_eq!(wiki.read_page(ws, proj, &path).unwrap().body, "historical");
            assert_eq!(
                store
                    .reader
                    .page_body_by_ids(ws, proj, path.as_str())
                    .await
                    .unwrap()
                    .unwrap()
                    .body,
                "historical"
            );
        }
    }

    #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
    async fn restore_page_lock_waits_before_conformance_and_allows_another_path() {
        let tmp = TempDir::new().unwrap();
        let (_store, wiki, ws, proj) = scoped(&tmp).await;
        let path = PagePath::new("notes/held-restore.md").unwrap();
        let abs = wiki.abs_path(ws, proj, &path);
        wiki.write_page(req(
            ws,
            proj,
            path.as_str(),
            "historical",
            serde_json::json!({}),
        ))
        .await
        .unwrap();
        let mut checkpoint_md = wiki.read_page(ws, proj, &path).unwrap();
        ai_memory_core::okf::stamp_generated_at(
            &mut checkpoint_md.frontmatter,
            "2020-01-01T00:00:00Z",
        );
        std::fs::write(&abs, emit(&checkpoint_md).unwrap()).unwrap();
        let rev = wiki.commit_all("checkpoint").unwrap().unwrap().to_string();
        wiki.write_page(req(ws, proj, path.as_str(), "newer", serde_json::json!({})))
            .await
            .unwrap();

        let global = wiki.mutation_lock.read().await;
        let page = wiki.lock_page(ws, proj, &path).await;
        // Queue an ordinary writer first, then the restore. The restore must
        // conform against the bytes that writer commits, not the old disk view.
        let write = wiki.write_page(req(
            ws,
            proj,
            path.as_str(),
            "historical",
            serde_json::json!({}),
        ));
        tokio::pin!(write);
        wait_for_page_waiter(&wiki, &(ws, proj, path.clone()), write.as_mut()).await;
        let restore = wiki.restore_page_from_checkpoint(ws, proj, path.clone(), &rev);
        tokio::pin!(restore);
        wait_for_page_waiter(&wiki, &(ws, proj, path.clone()), restore.as_mut()).await;
        finish_lock_test(wiki.write_page(req(
            ws,
            proj,
            "notes/independent.md",
            "control",
            serde_json::json!({}),
        )))
        .await
        .unwrap();
        assert_eq!(wiki.read_page(ws, proj, &path).unwrap().body, "newer");

        drop(page);
        drop(global);
        let written = finish_lock_test(write).await.unwrap();
        let committed = std::fs::read(&abs).unwrap();
        let restored = finish_lock_test(restore).await.unwrap();
        assert_eq!(
            restored, written,
            "restoring the same content reuses the current row"
        );
        assert_eq!(std::fs::read(&abs).unwrap(), committed);
        let disk = wiki.read_page(ws, proj, &path).unwrap();
        let row = latest_row(&tmp, path.as_str()).2;
        assert_eq!(
            ai_memory_core::okf::generated_at(&disk.frontmatter),
            ai_memory_core::okf::generated_at(&row)
        );
        assert_ne!(
            ai_memory_core::okf::generated_at(&disk.frontmatter),
            Some("2020-01-01T00:00:00Z")
        );
    }

    // The newer file on disk has another body, so the disk-inheritance rule
    // cannot supply `generated.at`; a past timestamp makes the restore fail
    // on every run without the checkpoint's own value, not only when the
    // write and the restore straddle a second.
    #[tokio::test]
    async fn restoring_a_conformant_checkpoint_keeps_its_generated_at() {
        let tmp = TempDir::new().unwrap();
        let (_store, wiki, ws, proj) = scoped(&tmp).await;
        let path = PagePath::new("notes/conformant.md").unwrap();
        let abs = wiki.abs_path(ws, proj, &path);
        wiki.write_page(req(
            ws,
            proj,
            path.as_str(),
            "first",
            serde_json::json!({ "title": "Conformant" }),
        ))
        .await
        .unwrap();
        let mut md = parse(&std::fs::read_to_string(&abs).unwrap()).unwrap();
        ai_memory_core::okf::stamp_generated_at(&mut md.frontmatter, "2020-01-01T00:00:00Z");
        std::fs::write(&abs, emit(&md).unwrap()).unwrap();
        let checkpointed = std::fs::read(&abs).unwrap();
        let rev = wiki.commit_all("checkpoint").unwrap().unwrap().to_string();

        wiki.write_page(req(
            ws,
            proj,
            path.as_str(),
            "second",
            serde_json::json!({ "title": "Conformant" }),
        ))
        .await
        .unwrap();
        wiki.commit_all("later").unwrap();
        assert_ne!(std::fs::read(&abs).unwrap(), checkpointed);

        wiki.restore_page_from_checkpoint(ws, proj, path.clone(), &rev)
            .await
            .unwrap();

        assert_eq!(
            String::from_utf8(std::fs::read(&abs).unwrap()).unwrap(),
            String::from_utf8(checkpointed).unwrap(),
            "restoring an already-conformant page rewrote its bytes"
        );
    }

    // A, B, then A again: the current version already holds the checkpoint's
    // content, so the store's idempotent upsert keeps that row and its
    // `generated.at`. The file must keep the same timestamp rather than the
    // checkpoint's, or disk and row diverge until the next real edit.
    #[tokio::test]
    async fn restoring_content_the_current_version_already_holds_keeps_disk_and_row_aligned() {
        let tmp = TempDir::new().unwrap();
        let (_store, wiki, ws, proj) = scoped(&tmp).await;
        let path = PagePath::new("notes/roundtrip.md").unwrap();
        let abs = wiki.abs_path(ws, proj, &path);
        let write = |body: &'static str| {
            req(
                ws,
                proj,
                path.as_str(),
                body,
                serde_json::json!({ "title": "RoundTrip" }),
            )
        };
        wiki.write_page(write("first")).await.unwrap();
        let mut md = parse(&std::fs::read_to_string(&abs).unwrap()).unwrap();
        ai_memory_core::okf::stamp_generated_at(&mut md.frontmatter, "2020-01-01T00:00:00Z");
        std::fs::write(&abs, emit(&md).unwrap()).unwrap();
        let rev = wiki.commit_all("checkpoint").unwrap().unwrap().to_string();
        wiki.write_page(write("second")).await.unwrap();
        let latest = wiki.write_page(write("first")).await.unwrap();
        let current_at = ai_memory_core::okf::generated_at(&latest_row(&tmp, path.as_str()).2)
            .map(str::to_string);
        assert_ne!(current_at.as_deref(), Some("2020-01-01T00:00:00Z"));

        let restored = wiki
            .restore_page_from_checkpoint(ws, proj, path.clone(), &rev)
            .await
            .unwrap();

        assert_eq!(restored, latest, "the upsert reuses the current version");
        let disk = parse(&std::fs::read_to_string(&abs).unwrap()).unwrap();
        let row = latest_row(&tmp, path.as_str()).2;
        assert_eq!(
            ai_memory_core::okf::generated_at(&disk.frontmatter),
            ai_memory_core::okf::generated_at(&row),
            "restore left disk and row with different generated.at"
        );
        assert_eq!(
            ai_memory_core::okf::generated_at(&disk.frontmatter),
            current_at.as_deref()
        );
    }

    // Control: a pre-OKF checkpoint still gets the deterministic keys and a
    // fresh `generated.at`, even when it carries a stale one, because
    // conformance changed more than the timestamp.
    #[tokio::test]
    async fn restoring_a_pre_okf_checkpoint_still_conforms_and_restamps() {
        let tmp = TempDir::new().unwrap();
        let (_store, wiki, ws, proj) = scoped(&tmp).await;
        let path = PagePath::new("notes/legacy.md").unwrap();
        let abs = wiki.abs_path(ws, proj, &path);
        std::fs::create_dir_all(abs.parent().unwrap()).unwrap();
        let legacy = "---\ntitle: Legacy\ngenerated:\n  at: '2020-01-01T00:00:00Z'\n---\nold";
        std::fs::write(&abs, legacy).unwrap();
        let rev = wiki.commit_all("checkpoint").unwrap().unwrap().to_string();
        std::fs::write(&abs, "---\ntitle: Legacy\n---\nnew").unwrap();

        wiki.restore_page_from_checkpoint(ws, proj, path.clone(), &rev)
            .await
            .unwrap();

        let restored = parse(&std::fs::read_to_string(&abs).unwrap()).unwrap();
        assert_eq!(restored.body.trim(), "old");
        assert!(ai_memory_core::okf::is_conformant(&restored.frontmatter));
        let at = ai_memory_core::okf::generated_at(&restored.frontmatter)
            .expect("the restore stamps generated.at");
        assert_ne!(at, "2020-01-01T00:00:00Z", "a conformed page is restamped");
    }

    #[tokio::test]
    async fn auto_improve_approval_writes_target_and_marks_approved() {
        let tmp = TempDir::new().unwrap();
        let (store, wiki, ws, proj) = scoped(&tmp).await;
        let id = stage_one(&store, ws, proj, "notes/approved.md", "approved body").await;
        let result = wiki
            .approve_auto_improve_proposal(
                ws,
                proj,
                id,
                ActorContext {
                    user: Some("reviewer".into()),
                    ..ActorContext::default()
                },
                None,
                None,
            )
            .await
            .unwrap();
        assert!(matches!(
            result,
            ApproveAutoImproveProposalResult::Approved { .. }
        ));
        assert_eq!(
            store
                .reader
                .page_body_by_ids(ws, proj, "notes/approved.md")
                .await
                .unwrap()
                .unwrap()
                .body,
            "approved body"
        );
        let detail = store
            .reader
            .auto_improve_proposal_detail(ws, proj, id)
            .await
            .unwrap()
            .unwrap();
        assert_eq!(detail.summary.status, AutoImproveProposalStatus::Approved);
        assert_eq!(detail.events[0].event, "staged");
        assert_eq!(detail.events[0].actor_json["agent"], "auto_improve");
        assert_eq!(detail.events.last().unwrap().event, "approved");
        assert_eq!(detail.events.last().unwrap().actor_json["user"], "reviewer");
    }

    #[tokio::test]
    async fn auto_improve_approval_update_path_supersedes_existing_page() {
        let tmp = TempDir::new().unwrap();
        let (store, wiki, ws, proj) = scoped(&tmp).await;
        wiki.write_page(req(
            ws,
            proj,
            "notes/update-proposal.md",
            "old body",
            serde_json::json!({ "title": "Old" }),
        ))
        .await
        .unwrap();
        let id = stage_one_op(
            &store,
            ws,
            proj,
            proposal(
                "notes/update-proposal.md",
                AutoImproveProposalOperation::Update,
                "new proposal body",
            ),
        )
        .await;
        let result = wiki
            .approve_auto_improve_proposal(ws, proj, id, ActorContext::default(), None, None)
            .await
            .unwrap();
        assert!(matches!(
            result,
            ApproveAutoImproveProposalResult::Approved { .. }
        ));
        assert_eq!(
            store
                .reader
                .page_body_by_ids(ws, proj, "notes/update-proposal.md")
                .await
                .unwrap()
                .unwrap()
                .body,
            "new proposal body"
        );
    }

    /// An approved auto-improvement page is embedded on approval, like every
    /// `write_page` version. Before, nothing on the write path embedded it:
    /// the page stayed out of the vector stream until an embedding backfill
    /// (startup, scheduled or `ai-memory embed`) found it.
    #[tokio::test]
    async fn auto_improve_approval_embeds_the_applied_page() {
        let tmp = TempDir::new().unwrap();
        let (store, wiki, ws, proj) = scoped(&tmp).await;
        let embedder: Arc<dyn ai_memory_llm::Embedder> =
            Arc::new(ai_memory_llm::SyntheticEmbedder::new(32));
        let wiki = wiki.with_embedder(embedder);
        let id = stage_one(&store, ws, proj, "notes/embedded.md", "approved body").await;
        let result = wiki
            .approve_auto_improve_proposal(ws, proj, id, ActorContext::default(), None, None)
            .await
            .unwrap();
        let ApproveAutoImproveProposalResult::Approved { page_id } = result else {
            panic!("expected approval, got {result:?}");
        };
        let embedded = store
            .reader
            .embedded_page_ids(ws, proj, "synthetic".into(), "bag-of-words-v1".into(), 32)
            .await
            .unwrap();
        assert!(
            embedded.contains(&page_id),
            "the approved page version must be embedded by the approval itself"
        );
    }

    #[tokio::test]
    async fn auto_improve_approval_stays_successful_when_embedding_storage_fails() {
        let tmp = TempDir::new().unwrap();
        let (store, wiki, ws, proj) = scoped(&tmp).await;
        let id = stage_one(&store, ws, proj, "notes/approved-store-failure.md", "kept").await;
        let wiki = wiki.with_embedder(store_failing_embedder(&store));

        let result = wiki
            .approve_auto_improve_proposal(ws, proj, id, ActorContext::default(), None, None)
            .await
            .unwrap();

        assert!(matches!(
            result,
            ApproveAutoImproveProposalResult::Approved { .. }
        ));
        assert_eq!(
            store
                .reader
                .page_body_by_ids(ws, proj, "notes/approved-store-failure.md")
                .await
                .unwrap()
                .unwrap()
                .body,
            "kept"
        );
    }

    /// Body and abstract vector sets for the synthetic test embedder.
    async fn synthetic_embedded(
        store: &Store,
        ws: WorkspaceId,
        proj: ProjectId,
    ) -> (Vec<PageId>, Vec<PageId>) {
        let (provider, model) = ("synthetic".to_string(), "bag-of-words-v1".to_string());
        let body = store
            .reader
            .embedded_page_ids(ws, proj, provider.clone(), model.clone(), 32)
            .await
            .unwrap();
        let abstracts = store
            .reader
            .abstract_embedded_page_ids(ws, proj, provider, model, 32)
            .await
            .unwrap();
        (body, abstracts)
    }

    /// Batch writes (consolidation, sweep, dream, bootstrap) embed every
    /// applied version, abstract included, like `write_page`. Before, they
    /// stayed out of the vector stream until an embedding backfill.
    #[tokio::test]
    async fn apply_batch_embeds_every_applied_page() {
        let tmp = TempDir::new().unwrap();
        let (store, wiki, ws, proj) = scoped(&tmp).await;
        let embedder: Arc<dyn ai_memory_llm::Embedder> =
            Arc::new(ai_memory_llm::SyntheticEmbedder::new(32));
        let wiki = wiki.with_embedder(embedder);
        let ids = wiki
            .apply_batch(vec![
                req(
                    ws,
                    proj,
                    "notes/plain.md",
                    "plain batch body",
                    serde_json::json!({}),
                ),
                req(
                    ws,
                    proj,
                    "notes/summarized.md",
                    "summarized batch body",
                    serde_json::json!({"abstract": "one-line batch summary"}),
                ),
            ])
            .await
            .unwrap();
        let (body, abstracts) = synthetic_embedded(&store, ws, proj).await;
        assert!(
            ids.iter().all(|id| body.contains(id)),
            "every batch page must be embedded by the batch itself: {ids:?} vs {body:?}"
        );
        assert_eq!(abstracts, vec![ids[1]], "only the page with an abstract");
    }

    /// A checkpoint restore writes a new latest version and must embed it;
    /// before, the restored version had no vectors until a backfill.
    #[tokio::test]
    async fn restore_from_checkpoint_embeds_the_restored_version() {
        let tmp = TempDir::new().unwrap();
        let (store, wiki, ws, proj) = scoped(&tmp).await;
        let path = "notes/restored.md";
        // Both earlier versions are written with no embedder, so only the
        // restore itself can produce the vectors checked below.
        wiki.write_page(req(
            ws,
            proj,
            path,
            "checkpointed body",
            serde_json::json!({"abstract": "checkpointed summary"}),
        ))
        .await
        .unwrap();
        let rev = wiki.commit_all("checkpoint").unwrap().unwrap().to_string();
        wiki.write_page(req(ws, proj, path, "later body", serde_json::json!({})))
            .await
            .unwrap();
        let embedder: Arc<dyn ai_memory_llm::Embedder> =
            Arc::new(ai_memory_llm::SyntheticEmbedder::new(32));
        let wiki = wiki.with_embedder(embedder);
        let id = wiki
            .restore_page_from_checkpoint(ws, proj, PagePath::new(path).unwrap(), &rev)
            .await
            .unwrap();
        let (body, abstracts) = synthetic_embedded(&store, ws, proj).await;
        assert_eq!(body, vec![id], "the restored version is embedded");
        assert_eq!(abstracts, vec![id], "with its restored abstract");
    }

    #[tokio::test]
    async fn checkpoint_restore_stays_successful_when_embedding_storage_fails() {
        let tmp = TempDir::new().unwrap();
        let (store, wiki, ws, proj) = scoped(&tmp).await;
        let path = PagePath::new("notes/restored-store-failure.md").unwrap();
        wiki.write_page(req(
            ws,
            proj,
            path.as_str(),
            "checkpoint body",
            serde_json::json!({}),
        ))
        .await
        .unwrap();
        let rev = wiki.commit_all("checkpoint").unwrap().unwrap().to_string();
        wiki.write_page(req(
            ws,
            proj,
            path.as_str(),
            "later body",
            serde_json::json!({}),
        ))
        .await
        .unwrap();
        let wiki = wiki.with_embedder(store_failing_embedder(&store));

        wiki.restore_page_from_checkpoint(ws, proj, path.clone(), &rev)
            .await
            .unwrap();

        assert_eq!(
            wiki.read_page(ws, proj, &path).unwrap().body,
            "checkpoint body"
        );
    }

    #[tokio::test]
    async fn auto_improve_approval_admission_mutation_is_persisted_and_scrubbed() {
        use axum::http::StatusCode;
        use axum::routing::post;
        use axum::{Json, Router};
        use tokio::net::TcpListener;

        let app = Router::new().route(
            "/mutate",
            post(|Json(_payload): Json<serde_json::Value>| async move {
                (
                    StatusCode::OK,
                    Json(serde_json::json!({
                        "page": { "body": "mutated ANTHROPIC_API_KEY=sk-ant-leak-1234567890abcdef" }
                    })),
                )
            }),
        );
        let listener = TcpListener::bind("127.0.0.1:0").await.unwrap();
        let addr = listener.local_addr().unwrap();
        tokio::spawn(async move { axum::serve(listener, app).await.unwrap() });

        let tmp = TempDir::new().unwrap();
        let (store, wiki, ws, proj) = scoped(&tmp).await;
        let wiki = wiki.with_admission_chain(
            AdmissionChain::new(vec![WebhookConfig {
                name: "mutator".into(),
                url: format!("http://{addr}/mutate"),
                timeout_ms: 1000,
                failure_policy: FailurePolicy::Reject,
                events: vec![AdmissionOp::WritePage],
                blocking: true,
            }])
            .unwrap(),
        );
        let id = stage_one(&store, ws, proj, "notes/mutated.md", "original body").await;
        wiki.approve_auto_improve_proposal(ws, proj, id, ActorContext::default(), None, None)
            .await
            .unwrap();
        let stored = store
            .reader
            .page_body_by_ids(ws, proj, "notes/mutated.md")
            .await
            .unwrap()
            .unwrap();
        assert!(stored.body.contains("[REDACTED:"));
        assert!(!stored.body.contains("sk-ant-leak"));
        assert!(
            std::fs::read_to_string(wiki.abs_path(
                ws,
                proj,
                &PagePath::new("notes/mutated.md").unwrap()
            ))
            .unwrap()
            .contains("[REDACTED:")
        );
    }

    #[tokio::test]
    async fn auto_improve_approval_conflict_rolls_back_target_file() {
        let tmp = TempDir::new().unwrap();
        let (store, wiki, ws, proj) = scoped(&tmp).await;
        let id = stage_one(&store, ws, proj, "notes/conflict.md", "proposal body").await;
        wiki.write_page(req(
            ws,
            proj,
            "notes/conflict.md",
            "external body",
            serde_json::json!({ "title": "External" }),
        ))
        .await
        .unwrap();
        let result = wiki
            .approve_auto_improve_proposal(ws, proj, id, ActorContext::default(), None, None)
            .await
            .unwrap();
        assert_eq!(result, ApproveAutoImproveProposalResult::Conflict);
        assert!(
            std::fs::read_to_string(wiki.abs_path(
                ws,
                proj,
                &PagePath::new("notes/conflict.md").unwrap()
            ))
            .unwrap()
            .contains("external body")
        );
        assert_eq!(
            store
                .reader
                .page_body_by_ids(ws, proj, "notes/conflict.md")
                .await
                .unwrap()
                .unwrap()
                .body,
            "external body"
        );
    }

    #[tokio::test]
    async fn auto_improve_admission_rejection_marks_failed_without_writing_target() {
        let tmp = TempDir::new().unwrap();
        let (store, wiki, ws, proj) = scoped(&tmp).await;
        let wiki = wiki.with_admission_chain(
            AdmissionChain::new(vec![WebhookConfig {
                name: "rejector".into(),
                url: "http://127.0.0.1:9/reject".into(),
                timeout_ms: 50,
                failure_policy: FailurePolicy::Reject,
                events: vec![AdmissionOp::WritePage],
                blocking: true,
            }])
            .unwrap(),
        );
        let id = stage_one(&store, ws, proj, "notes/rejected.md", "body").await;
        assert!(
            wiki.approve_auto_improve_proposal(ws, proj, id, ActorContext::default(), None, None)
                .await
                .is_err()
        );
        assert!(
            !wiki
                .abs_path(ws, proj, &PagePath::new("notes/rejected.md").unwrap())
                .exists()
        );
        let detail = store
            .reader
            .auto_improve_proposal_detail(ws, proj, id)
            .await
            .unwrap()
            .unwrap();
        assert_eq!(detail.summary.status, AutoImproveProposalStatus::Failed);
        assert_eq!(detail.events.last().unwrap().event, "failed");
    }

    #[tokio::test]
    async fn write_page_writes_file_and_indexes_in_store() {
        let tmp = TempDir::new().unwrap();
        let store = Store::open(tmp.path()).unwrap();
        let ws = store
            .writer
            .get_or_create_workspace("default")
            .await
            .unwrap();
        let proj = store
            .writer
            .get_or_create_project(ws, "scratch", None)
            .await
            .unwrap();
        let wiki = Wiki::new(tmp.path(), store.writer.clone()).unwrap();

        let id = wiki
            .write_page(req(
                ws,
                proj,
                "notes/karpathy.md",
                "Karpathy says: compile, do not retrieve.\n",
                serde_json::json!({ "title": "Karpathy LLM Wiki" }),
            ))
            .await
            .unwrap();
        let _ = id; // any non-zero PageId is sufficient

        // File is on disk at the per-project location.
        let on_disk = std::fs::read_to_string(wiki.abs_path(
            ws,
            proj,
            &PagePath::new("notes/karpathy.md").unwrap(),
        ))
        .unwrap();
        assert!(on_disk.starts_with("---\n"));
        assert!(on_disk.contains("title: Karpathy LLM Wiki"));
        assert!(on_disk.contains("Karpathy says"));

        // FTS5 finds it via the store reader.
        let hits = store
            .reader
            .search_pages("karpathy".into(), 5, None)
            .await
            .unwrap();
        assert_eq!(hits.len(), 1);
        assert_eq!(hits[0].title, "Karpathy LLM Wiki");
        assert!(hits[0].snippet.contains("compile"));
    }

    #[tokio::test]
    async fn decay_eviction_refuses_a_stale_latest_id_without_touching_disk() {
        let tmp = TempDir::new().unwrap();
        let (store, wiki, ws, proj) = scoped(&tmp).await;
        let path = PagePath::new("sessions/stale-decay.md").unwrap();
        let stale = wiki
            .write_page(req(
                ws,
                proj,
                path.as_str(),
                "old candidate",
                serde_json::json!({"tier": "episodic"}),
            ))
            .await
            .unwrap();
        let current = wiki
            .write_page(req(
                ws,
                proj,
                path.as_str(),
                "new current body",
                serde_json::json!({"tier": "episodic"}),
            ))
            .await
            .unwrap();

        assert!(
            !wiki
                .evict_page_if_latest(ws, proj, &path, stale, None)
                .await
                .unwrap()
        );
        assert!(
            std::fs::read_to_string(wiki.abs_path(ws, proj, &path))
                .unwrap()
                .contains("new current body")
        );
        assert_eq!(
            store
                .reader
                .latest_page_id_by_ids(ws, proj, path.as_str().to_string())
                .await
                .unwrap(),
            Some(current),
        );
    }

    #[tokio::test]
    async fn rejecting_delete_admission_leaves_decay_candidate_live() {
        use axum::Router;
        use axum::http::StatusCode;
        use axum::routing::post;
        use tokio::net::TcpListener;

        let app = Router::new().route(
            "/reject",
            post(|| async { (StatusCode::FORBIDDEN, "retention denied") }),
        );
        let listener = TcpListener::bind("127.0.0.1:0").await.unwrap();
        let addr = listener.local_addr().unwrap();
        tokio::spawn(async move { axum::serve(listener, app).await.unwrap() });

        let tmp = TempDir::new().unwrap();
        let (store, wiki, ws, proj) = scoped(&tmp).await;
        let path = PagePath::new("sessions/admission-decay.md").unwrap();
        let page_id = wiki
            .write_page(req(
                ws,
                proj,
                path.as_str(),
                "must remain live",
                serde_json::json!({"tier": "episodic"}),
            ))
            .await
            .unwrap();
        let wiki = wiki.with_admission_chain(
            AdmissionChain::new(vec![WebhookConfig {
                name: "retention-guard".into(),
                url: format!("http://{addr}/reject"),
                timeout_ms: 1_000,
                failure_policy: FailurePolicy::Reject,
                events: vec![AdmissionOp::Delete],
                blocking: true,
            }])
            .unwrap(),
        );

        assert!(
            wiki.evict_page_if_latest(ws, proj, &path, page_id, None)
                .await
                .is_err()
        );
        assert!(wiki.abs_path(ws, proj, &path).exists());
        assert_eq!(
            store
                .reader
                .latest_page_id_by_ids(ws, proj, path.as_str().to_string())
                .await
                .unwrap(),
            Some(page_id),
        );
    }

    // --- #929: reconcile-delete tombstone op (`tombstone_missing_page_if_latest`) ---

    #[tokio::test]
    async fn reconcile_tombstone_refuses_a_stale_latest_id() {
        let tmp = TempDir::new().unwrap();
        let (store, wiki, ws, proj) = scoped(&tmp).await;
        let path = PagePath::new("sessions/stale-reconcile.md").unwrap();
        let stale = wiki
            .write_page(req(
                ws,
                proj,
                path.as_str(),
                "old candidate",
                serde_json::json!({}),
            ))
            .await
            .unwrap();
        let current = wiki
            .write_page(req(
                ws,
                proj,
                path.as_str(),
                "new current body",
                serde_json::json!({}),
            ))
            .await
            .unwrap();
        std::fs::remove_file(wiki.abs_path(ws, proj, &path)).unwrap();

        assert!(
            !wiki
                .tombstone_missing_page_if_latest(ws, proj, &path, stale)
                .await
                .unwrap(),
            "a stale expected id must leave the current version untouched"
        );
        assert_eq!(
            store
                .reader
                .latest_page_id_by_ids(ws, proj, path.as_str().to_string())
                .await
                .unwrap(),
            Some(current),
        );
    }

    /// Design item #6: the final recheck, immediately before acting, must
    /// refuse when the file has actually come back — even though the caller
    /// (the watcher's reconcile pass) only calls this after two consecutive
    /// "missing" observations, a page can still be recreated in the narrow
    /// window between the second observation and this call.
    #[tokio::test]
    async fn reconcile_tombstone_refuses_when_the_file_still_exists() {
        let tmp = TempDir::new().unwrap();
        let (store, wiki, ws, proj) = scoped(&tmp).await;
        let path = PagePath::new("sessions/present-reconcile.md").unwrap();
        let page_id = wiki
            .write_page(req(
                ws,
                proj,
                path.as_str(),
                "still here",
                serde_json::json!({}),
            ))
            .await
            .unwrap();

        assert!(
            !wiki
                .tombstone_missing_page_if_latest(ws, proj, &path, page_id)
                .await
                .unwrap(),
            "the file exists on disk; the final recheck must refuse to tombstone it"
        );
        assert_eq!(
            store
                .reader
                .latest_page_id_by_ids(ws, proj, path.as_str().to_string())
                .await
                .unwrap(),
            Some(page_id),
        );
        assert!(wiki.abs_path(ws, proj, &path).exists());
    }

    /// The tombstone op is a background safety net reacting to a file that is
    /// already gone, not a user-initiated delete: it must never run the
    /// BLOCKING admission gate, which could refuse it. A webhook configured
    /// to reject every `Delete` event proves this by NOT blocking the
    /// tombstone — if `tombstone_missing_page_if_latest` went through the
    /// same path as `evict_page_if_latest`/`delete_page_if_latest`, this
    /// webhook would turn the call into an error
    /// (`rejecting_delete_admission_leaves_decay_candidate_live` shows
    /// exactly that for the decay path). It DOES still fire-and-forget any
    /// non-blocking observer/mirror webhook on success — see
    /// `reconcile_tombstone_dispatches_non_blocking_observer_webhook` below
    /// (#929 review, S6).
    #[tokio::test]
    async fn reconcile_tombstone_does_not_dispatch_admission_webhook() {
        use axum::Router;
        use axum::http::StatusCode;
        use axum::routing::post;
        use tokio::net::TcpListener;

        let app = Router::new().route(
            "/reject",
            post(|| async { (StatusCode::FORBIDDEN, "must never be called") }),
        );
        let listener = TcpListener::bind("127.0.0.1:0").await.unwrap();
        let addr = listener.local_addr().unwrap();
        tokio::spawn(async move { axum::serve(listener, app).await.unwrap() });

        let tmp = TempDir::new().unwrap();
        let (store, wiki, ws, proj) = scoped(&tmp).await;
        let path = PagePath::new("sessions/webhook-reconcile.md").unwrap();
        let page_id = wiki
            .write_page(req(
                ws,
                proj,
                path.as_str(),
                "vanishing",
                serde_json::json!({}),
            ))
            .await
            .unwrap();
        std::fs::remove_file(wiki.abs_path(ws, proj, &path)).unwrap();
        let wiki = wiki.with_admission_chain(
            AdmissionChain::new(vec![WebhookConfig {
                name: "reconcile-guard".into(),
                url: format!("http://{addr}/reject"),
                timeout_ms: 1_000,
                failure_policy: FailurePolicy::Reject,
                events: vec![AdmissionOp::Delete],
                blocking: true,
            }])
            .unwrap(),
        );

        assert!(
            wiki.tombstone_missing_page_if_latest(ws, proj, &path, page_id)
                .await
                .unwrap(),
            "no admission dispatch means the rejecting webhook is never consulted"
        );
        assert_eq!(
            store
                .reader
                .latest_page_id_by_ids(ws, proj, path.as_str().to_string())
                .await
                .unwrap(),
            None,
            "the page is no longer latest",
        );
    }

    /// S6 (#929 review): the tombstone op skips the BLOCKING admission gate
    /// (proven above), but a mirror that never hears about the tombstone at
    /// all would silently diverge from the source of truth — a real
    /// correctness issue on its own. A non-blocking observer webhook must
    /// still be fired, fire-and-forget, on a successful tombstone.
    #[tokio::test]
    async fn reconcile_tombstone_dispatches_non_blocking_observer_webhook() {
        use axum::Router;
        use axum::extract::State;
        use axum::http::StatusCode;
        use axum::routing::post;
        use std::sync::Arc;
        use std::sync::atomic::{AtomicBool, Ordering};
        use tokio::net::TcpListener;

        let observed = Arc::new(AtomicBool::new(false));
        let app = Router::new()
            .route(
                "/observe",
                post(|State(flag): State<Arc<AtomicBool>>| async move {
                    flag.store(true, Ordering::SeqCst);
                    StatusCode::OK
                }),
            )
            .with_state(observed.clone());
        let listener = TcpListener::bind("127.0.0.1:0").await.unwrap();
        let addr = listener.local_addr().unwrap();
        tokio::spawn(async move { axum::serve(listener, app).await.unwrap() });

        let tmp = TempDir::new().unwrap();
        let (_store, wiki, ws, proj) = scoped(&tmp).await;
        let path = PagePath::new("notes/mirror-reconcile.md").unwrap();
        let page_id = wiki
            .write_page(req(
                ws,
                proj,
                path.as_str(),
                "vanishing",
                serde_json::json!({}),
            ))
            .await
            .unwrap();
        std::fs::remove_file(wiki.abs_path(ws, proj, &path)).unwrap();
        let wiki = wiki.with_admission_chain(
            AdmissionChain::new(vec![WebhookConfig {
                name: "mirror-observer".into(),
                url: format!("http://{addr}/observe"),
                timeout_ms: 1_000,
                failure_policy: FailurePolicy::Ignore,
                events: vec![AdmissionOp::Delete],
                blocking: false,
            }])
            .unwrap(),
        );

        assert!(
            wiki.tombstone_missing_page_if_latest(ws, proj, &path, page_id)
                .await
                .unwrap()
        );

        // `dispatch_async` fires the request off the caller's path; give it a
        // bounded window to land instead of asserting immediately.
        let mut delivered = false;
        for _ in 0..50 {
            if observed.load(Ordering::SeqCst) {
                delivered = true;
                break;
            }
            tokio::time::sleep(std::time::Duration::from_millis(20)).await;
        }
        assert!(
            delivered,
            "the non-blocking observer webhook must be notified of the tombstone"
        );
    }

    /// The op never touches the filesystem (design item #7: there is nothing
    /// to touch — the file is already gone). Proven by the project
    /// directory's file listing being byte-for-byte identical before and
    /// after the call: no quarantine artifact, no recreated file, nothing.
    #[tokio::test]
    async fn reconcile_tombstone_never_touches_the_filesystem() {
        let tmp = TempDir::new().unwrap();
        let (_store, wiki, ws, proj) = scoped(&tmp).await;
        let path = PagePath::new("notes/vanishing-fs.md").unwrap();
        let page_id = wiki
            .write_page(req(
                ws,
                proj,
                path.as_str(),
                "gone soon",
                serde_json::json!({}),
            ))
            .await
            .unwrap();
        let proj_dir = wiki.project_root(ws, proj);
        std::fs::remove_file(wiki.abs_path(ws, proj, &path)).unwrap();

        let listing_before = list_dir_recursive(&proj_dir);
        assert!(
            wiki.tombstone_missing_page_if_latest(ws, proj, &path, page_id)
                .await
                .unwrap()
        );
        let listing_after = list_dir_recursive(&proj_dir);
        assert_eq!(
            listing_before, listing_after,
            "the tombstone op must not create, remove, or rename any file"
        );
    }

    /// `restore-page`/wiki history depend on this: a reconcile tombstone is
    /// `is_latest = 0` + `superseded_at`, mirroring decay eviction exactly —
    /// and is picked up by the SAME aged-tombstone sweep decay eviction uses
    /// (`hard_delete_after_days`, tier/pin-agnostic), not exempted from it.
    /// Proven by fetching the row back through the same query that sweep
    /// uses ([`ai_memory_store::ReaderPool::decay_tombstones_before`]): if
    /// the row were gone, or if only `is_latest` had flipped without
    /// `superseded_at`, it would not show up there. What actually protects a
    /// reconcile tombstone from that sweep permanently destroying a
    /// self-healed false positive is `upsert_page_in_tx`'s resurrection path
    /// (`ops.rs`): if the file comes back, the new version re-links onto
    /// this chain and clears `superseded_at`, which is covered separately by
    /// `reconcile_tombstone_resurrects_instead_of_orphaning_on_recreate`.
    #[tokio::test]
    async fn reconcile_tombstone_is_a_soft_delete_visible_to_normal_retention() {
        let tmp = TempDir::new().unwrap();
        let (store, wiki, ws, proj) = scoped(&tmp).await;
        let path = PagePath::new("notes/tombstone-shape.md").unwrap();
        let page_id = wiki
            .write_page(req(
                ws,
                proj,
                path.as_str(),
                "about to vanish",
                serde_json::json!({}),
            ))
            .await
            .unwrap();
        std::fs::remove_file(wiki.abs_path(ws, proj, &path)).unwrap();

        assert!(
            wiki.tombstone_missing_page_if_latest(ws, proj, &path, page_id)
                .await
                .unwrap()
        );

        // is_latest = 0: no longer the scope's current version.
        assert_eq!(
            store
                .reader
                .latest_page_id_by_ids(ws, proj, path.as_str().to_string())
                .await
                .unwrap(),
            None,
        );
        // superseded_at set (not just is_latest): the row surfaces through the
        // exact query the decay retention sweep uses to find eligible aged
        // tombstones — proving it is a real tombstone, not merely hidden, and
        // that hard cleanup is left to that same normal retention path.
        let far_future = jiff::Timestamp::now().as_microsecond() + 365 * 24 * 3_600 * 1_000_000;
        let tombstones = store
            .reader
            .decay_tombstones_before(ws, proj, far_future)
            .await
            .unwrap();
        assert!(
            tombstones.iter().any(|t| t.id == page_id && t.path == path),
            "the reconcile tombstone must be indistinguishable from a decay tombstone to the \
             retention sweep: {tombstones:?}",
        );
    }

    fn list_dir_recursive(root: &Path) -> Vec<String> {
        fn walk(dir: &Path, root: &Path, out: &mut Vec<String>) {
            let Ok(entries) = std::fs::read_dir(dir) else {
                return;
            };
            for entry in entries.flatten() {
                let path = entry.path();
                if path.is_dir() {
                    walk(&path, root, out);
                } else {
                    out.push(
                        path.strip_prefix(root)
                            .unwrap_or(&path)
                            .to_string_lossy()
                            .into_owned(),
                    );
                }
            }
        }
        let mut out = Vec::new();
        walk(root, root, &mut out);
        out.sort();
        out
    }

    #[tokio::test]
    async fn decay_cleanup_refuses_to_reindex_a_symlinked_recreation() {
        let tmp = TempDir::new().unwrap();
        let (store, wiki, ws, proj) = scoped(&tmp).await;
        let path = PagePath::new("sessions/symlink-decay.md").unwrap();
        let page_id = wiki
            .write_page(req(
                ws,
                proj,
                path.as_str(),
                "evicted body",
                serde_json::json!({}),
            ))
            .await
            .unwrap();
        assert!(
            wiki.evict_page_if_latest(ws, proj, &path, page_id, None)
                .await
                .unwrap()
        );

        let outside = tmp.path().join("outside.md");
        std::fs::write(&outside, "outside secret must not be indexed").unwrap();
        let linked = wiki.abs_path(ws, proj, &path);
        if !create_test_symlink_file(&outside, &linked) {
            return;
        }

        let error = wiki
            .hard_delete_decay_tombstone(ws, proj, &path, page_id, i64::MAX)
            .await
            .expect_err("symlinked recreation must fail closed");
        assert!(matches!(error, WikiError::Confinement { .. }), "{error}");
        assert_eq!(
            store
                .reader
                .latest_page_id_by_ids(ws, proj, path.as_str().to_string())
                .await
                .unwrap(),
            None,
        );
        assert_eq!(
            std::fs::read_to_string(&outside).unwrap(),
            "outside secret must not be indexed"
        );
        assert_eq!(
            store
                .reader
                .decay_tombstones_before(ws, proj, i64::MAX)
                .await
                .unwrap()
                .len(),
            1,
            "cleanup failure must leave the tombstone for a safe retry"
        );
    }

    /// #929: the reindex `hard_delete_decay_tombstone` performs when a
    /// decayed page's file survived and was rewritten externally must NOT
    /// embed the resurrected version. That whole function runs under the
    /// exclusive write lock (`mutation_lock.write()`, held for the entire
    /// call), and embedding can block on the configured provider for an
    /// unbounded time — doing it there would stall every other wiki write
    /// for as long as the provider call takes.
    #[tokio::test]
    async fn decay_cleanup_reindex_does_not_embed_under_the_exclusive_lock() {
        let tmp = TempDir::new().unwrap();
        let (store, wiki, ws, proj) = scoped(&tmp).await;
        let embedder: Arc<dyn ai_memory_llm::Embedder> =
            Arc::new(ai_memory_llm::SyntheticEmbedder::new(32));
        let wiki = wiki.with_embedder(embedder);

        let path = PagePath::new("sessions/decay-embed.md").unwrap();
        let page_id = wiki
            .write_page(req(
                ws,
                proj,
                path.as_str(),
                "original decayed body",
                serde_json::json!({}),
            ))
            .await
            .unwrap();
        assert!(
            wiki.evict_page_if_latest(ws, proj, &path, page_id, None)
                .await
                .unwrap(),
            "precondition: the page is tombstoned by decay"
        );

        // The file survives the tombstone (`evict_page_if_latest` never
        // touches disk) and is rewritten externally before the cleanup
        // runs, so `hard_delete_decay_tombstone` must reindex it fresh
        // rather than reuse the tombstoned version.
        std::fs::write(wiki.abs_path(ws, proj, &path), "resurrected body content\n").unwrap();

        wiki.hard_delete_decay_tombstone(ws, proj, &path, page_id, i64::MAX)
            .await
            .unwrap();

        let resurrected_id = store
            .reader
            .latest_page_id_by_ids(ws, proj, path.as_str().to_string())
            .await
            .unwrap()
            .expect("the resurrected version must be indexed");
        assert_ne!(
            resurrected_id, page_id,
            "the rewrite must have produced a new version, not reused the tombstone"
        );

        let embedded = store
            .reader
            .embedded_page_ids(ws, proj, "synthetic".into(), "bag-of-words-v1".into(), 32)
            .await
            .unwrap();
        assert!(
            !embedded.contains(&resurrected_id),
            "reindexing inside hard_delete_decay_tombstone must not embed \
             while the exclusive lock is held"
        );
    }

    #[tokio::test]
    async fn write_page_rolls_back_file_when_store_upsert_fails() {
        let tmp = TempDir::new().unwrap();
        let store = Store::open(tmp.path()).unwrap();
        let ws = store
            .writer
            .get_or_create_workspace("default")
            .await
            .unwrap();
        let proj = store
            .writer
            .get_or_create_project(ws, "scratch", None)
            .await
            .unwrap();
        let wiki = Wiki::new(tmp.path(), store.writer.clone()).unwrap();
        let path = PagePath::new("notes/rollback.md").unwrap();

        wiki.write_page(req(
            ws,
            proj,
            path.as_str(),
            "old body",
            serde_json::json!({ "title": "Old" }),
        ))
        .await
        .unwrap();

        let mut bad = req(
            ws,
            proj,
            path.as_str(),
            "new body should not remain",
            serde_json::json!({ "title": "New" }),
        );
        bad.author_id = Some(ai_memory_core::UserId::new());
        let err = wiki.write_page(bad).await.unwrap_err();
        assert!(
            err.to_string().contains("FOREIGN KEY") || err.to_string().contains("constraint"),
            "expected FK failure, got {err}"
        );

        let on_disk = std::fs::read_to_string(wiki.abs_path(ws, proj, &path)).unwrap();
        assert!(on_disk.contains("old body"));
        assert!(!on_disk.contains("new body should not remain"));

        let stored = store
            .reader
            .page_body_by_ids(ws, proj, path.as_str())
            .await
            .unwrap()
            .expect("old row should remain latest");
        assert_eq!(stored.body, "old body");
        assert_eq!(stored.title, "Old");
    }

    /// Defence-in-depth: anything that reaches `write_page` gets
    /// scrubbed at the wiki boundary, even if upstream callers (LLM
    /// consolidation output, manual `write-page` CLI input, MCP tool
    /// args) skipped the hook-ingress sanitizer.
    #[tokio::test]
    async fn write_page_scrubs_secrets_at_the_wiki_boundary() {
        let tmp = TempDir::new().unwrap();
        let store = Store::open(tmp.path()).unwrap();
        let ws = store
            .writer
            .get_or_create_workspace("default")
            .await
            .unwrap();
        let proj = store
            .writer
            .get_or_create_project(ws, "scratch", None)
            .await
            .unwrap();
        let wiki = Wiki::new(tmp.path(), store.writer.clone()).unwrap();

        let body = "we agreed to use ANTHROPIC_API_KEY=sk-ant-leak-1234567890abcdef \
                    and the canary id sk-canary-LEAK_ME_PLEASE_xxxxxxxxxxxx — see \
                    postgres://admin:[email protected]/prod for details";
        wiki.write_page(req(
            ws,
            proj,
            "notes/leaky.md",
            body,
            serde_json::json!({ "title": "leaky" }),
        ))
        .await
        .unwrap();

        let on_disk = std::fs::read_to_string(wiki.abs_path(
            ws,
            proj,
            &PagePath::new("notes/leaky.md").unwrap(),
        ))
        .unwrap();
        // The on-disk page must not contain any of the planted
        // secrets; each should have been replaced with [REDACTED].
        assert!(
            on_disk.contains("[REDACTED:"),
            "expected redaction in: {on_disk}"
        );
        assert!(
            !on_disk.contains("sk-ant-leak"),
            "anthropic key leaked: {on_disk}"
        );
        assert!(
            !on_disk.contains("LEAK_ME_PLEASE"),
            "canary leaked: {on_disk}"
        );
        assert!(
            !on_disk.contains("hunter2"),
            "DB password leaked: {on_disk}"
        );

        // The store-indexed body must also be scrubbed (so FTS5 + the
        // MCP query path never surface the raw secret either).
        let hits = store
            .reader
            .search_pages("REDACTED".into(), 5, None)
            .await
            .unwrap();
        assert_eq!(hits.len(), 1);
        assert!(!hits[0].snippet.contains("sk-ant-leak"));
        assert!(!hits[0].snippet.contains("hunter2"));
    }

    #[tokio::test]
    async fn slot_pages_are_pinned_automatically() {
        let tmp = TempDir::new().unwrap();
        let store = Store::open(tmp.path()).unwrap();
        let ws = store
            .writer
            .get_or_create_workspace("default")
            .await
            .unwrap();
        let proj = store
            .writer
            .get_or_create_project(ws, "scratch", None)
            .await
            .unwrap();
        let wiki = Wiki::new(tmp.path(), store.writer.clone()).unwrap();

        wiki.write_page(req(
            ws,
            proj,
            "_slots/current_focus.md",
            "Keep this tiny and durable.",
            serde_json::json!({ "title": "Current focus", "kind": "slot" }),
        ))
        .await
        .unwrap();

        let candidates = store.reader.decay_candidates(ws, proj).await.unwrap();
        assert_eq!(candidates.len(), 1);
        assert!(candidates[0].pinned, "slot pages should be decay-immune");
    }

    #[tokio::test]
    async fn apply_batch_persists_all_pages_in_one_transaction() {
        let tmp = TempDir::new().unwrap();
        let store = Store::open(tmp.path()).unwrap();
        let ws = store
            .writer
            .get_or_create_workspace("default")
            .await
            .unwrap();
        let proj = store
            .writer
            .get_or_create_project(ws, "scratch", None)
            .await
            .unwrap();
        let wiki = Wiki::new(tmp.path(), store.writer.clone()).unwrap();
        let batch: Vec<_> = (0..5)
            .map(|i| WritePageRequest {
                workspace_id: ws,
                project_id: proj,
                path: PagePath::new(format!("batch/{i}.md")).unwrap(),
                frontmatter: serde_json::json!({"title": format!("Page {i}")}),
                body: format!("batch page {i} body line"),
                tier: Tier::Semantic,
                pinned: false,
                title: None,
                admission_ctx: None,
                author_id: None,
                actor: ai_memory_core::ActorContext::anonymous(),
                evidence: Vec::new(),
            })
            .collect();
        let ids = wiki.apply_batch(batch).await.unwrap();
        assert_eq!(ids.len(), 5);
        for i in 0..5 {
            let path = wiki.abs_path(ws, proj, &PagePath::new(format!("batch/{i}.md")).unwrap());
            assert!(path.is_file(), "missing file {i}");
            let body = std::fs::read_to_string(&path).unwrap();
            assert!(body.contains(&format!("Page {i}")));
        }
        let counts = store.reader.status_counts().await.unwrap();
        assert_eq!(counts.pages_latest, 5);
        let hits = store
            .reader
            .search_pages("batch".into(), 10, None)
            .await
            .unwrap();
        assert_eq!(hits.len(), 5);
    }

    #[tokio::test]
    async fn conditional_batch_rejects_every_page_when_one_version_changed() {
        let tmp = TempDir::new().unwrap();
        let store = Store::open(tmp.path()).unwrap();
        let ws = store
            .writer
            .get_or_create_workspace("default")
            .await
            .unwrap();
        let proj = store
            .writer
            .get_or_create_project(ws, "scratch", None)
            .await
            .unwrap();
        let wiki = Wiki::new(tmp.path(), store.writer.clone())
            .unwrap()
            .with_store_reader(store.reader.clone());
        let first = PagePath::new("batch/first.md").unwrap();
        let second = PagePath::new("batch/second.md").unwrap();
        let first_id = wiki
            .write_page(req(
                ws,
                proj,
                first.as_str(),
                "first original",
                serde_json::json!({"title": "First"}),
            ))
            .await
            .unwrap();
        let stale_second_id = wiki
            .write_page(req(
                ws,
                proj,
                second.as_str(),
                "second original",
                serde_json::json!({"title": "Second"}),
            ))
            .await
            .unwrap();
        let current_second_id = wiki
            .write_page(req(
                ws,
                proj,
                second.as_str(),
                "second concurrent update",
                serde_json::json!({"title": "Second"}),
            ))
            .await
            .unwrap();

        let outcome = wiki
            .apply_batch_if(vec![
                (
                    req(
                        ws,
                        proj,
                        first.as_str(),
                        "first stale replacement",
                        serde_json::json!({"title": "First"}),
                    ),
                    PagePrecondition::Latest(first_id),
                ),
                (
                    req(
                        ws,
                        proj,
                        second.as_str(),
                        "second stale replacement",
                        serde_json::json!({"title": "Second"}),
                    ),
                    PagePrecondition::Latest(stale_second_id),
                ),
            ])
            .await
            .unwrap();

        assert_eq!(
            outcome,
            ConditionalBatchWrite::Mismatch {
                index: 1,
                current: Some(current_second_id),
            }
        );
        assert_eq!(
            wiki.read_page(ws, proj, &first).unwrap().body,
            "first original"
        );
        assert_eq!(
            wiki.read_page(ws, proj, &second).unwrap().body,
            "second concurrent update"
        );
        assert_eq!(
            store
                .reader
                .page_body_by_ids(ws, proj, first.as_str())
                .await
                .unwrap()
                .unwrap()
                .body,
            "first original"
        );
    }

    #[tokio::test]
    async fn apply_batch_rolls_back_files_when_sql_batch_fails() {
        let tmp = TempDir::new().unwrap();
        let store = Store::open(tmp.path()).unwrap();
        let ws = store
            .writer
            .get_or_create_workspace("default")
            .await
            .unwrap();
        let proj = store
            .writer
            .get_or_create_project(ws, "scratch", None)
            .await
            .unwrap();
        let wiki = Wiki::new(tmp.path(), store.writer.clone()).unwrap();
        let existing = PagePath::new("batch/existing.md").unwrap();
        let created = PagePath::new("batch/new.md").unwrap();

        wiki.write_page(req(
            ws,
            proj,
            existing.as_str(),
            "old batch body",
            serde_json::json!({ "title": "Old Batch" }),
        ))
        .await
        .unwrap();

        let mut replace_existing = req(
            ws,
            proj,
            existing.as_str(),
            "new batch body should roll back",
            serde_json::json!({ "title": "New Batch" }),
        );
        replace_existing.author_id = Some(ai_memory_core::UserId::new());
        let mut create_new = req(
            ws,
            proj,
            created.as_str(),
            "new file should be removed",
            serde_json::json!({ "title": "Created" }),
        );
        create_new.author_id = Some(ai_memory_core::UserId::new());

        let err = wiki
            .apply_batch(vec![replace_existing, create_new])
            .await
            .unwrap_err();
        assert!(
            err.to_string().contains("FOREIGN KEY") || err.to_string().contains("constraint"),
            "expected FK failure, got {err}"
        );

        let existing_body = std::fs::read_to_string(wiki.abs_path(ws, proj, &existing)).unwrap();
        assert!(existing_body.contains("old batch body"));
        assert!(!existing_body.contains("new batch body should roll back"));
        assert!(!wiki.abs_path(ws, proj, &created).exists());

        let counts = store.reader.status_counts().await.unwrap();
        assert_eq!(counts.pages_latest, 1);
        let stored = store
            .reader
            .page_body_by_ids(ws, proj, existing.as_str())
            .await
            .unwrap()
            .expect("old row should remain latest");
        assert_eq!(stored.body, "old batch body");
        assert!(
            store
                .reader
                .page_body_by_ids(ws, proj, created.as_str())
                .await
                .unwrap()
                .is_none()
        );
    }

    #[tokio::test]
    async fn apply_batch_runs_admission_and_scrubs_webhook_mutations() {
        use crate::admission::{
            AdmissionChain, AdmissionContext, AdmissionOp, FailurePolicy, WebhookConfig,
        };
        use axum::http::StatusCode;
        use axum::routing::post;
        use axum::{Json, Router};
        use tokio::net::TcpListener;

        let app = Router::new().route(
            "/mutate",
            post(|Json(_payload): Json<serde_json::Value>| async move {
                (
                    StatusCode::OK,
                    Json(serde_json::json!({
                        "page": {
                            "frontmatter": { "title": "leaked sk-1234567890abcdef" },
                            "body": "webhook returned sk-1234567890abcdef"
                        }
                    })),
                )
            }),
        );
        let listener = TcpListener::bind("127.0.0.1:0").await.unwrap();
        let addr = listener.local_addr().unwrap();
        tokio::spawn(async move {
            axum::serve(listener, app).await.unwrap();
        });

        let tmp = TempDir::new().unwrap();
        let store = Store::open(tmp.path()).unwrap();
        let ws = store
            .writer
            .get_or_create_workspace("default")
            .await
            .unwrap();
        let proj = store
            .writer
            .get_or_create_project(ws, "scratch", None)
            .await
            .unwrap();
        let chain = AdmissionChain::new(vec![WebhookConfig {
            name: "mutator".into(),
            url: format!("http://{addr}/mutate"),
            timeout_ms: 1_000,
            failure_policy: FailurePolicy::Reject,
            events: vec![AdmissionOp::Consolidate],
            blocking: true,
        }])
        .unwrap();
        let wiki = Wiki::new(tmp.path(), store.writer.clone())
            .unwrap()
            .with_admission_chain(chain)
            .with_store_reader(store.reader.clone());

        let ids = wiki
            .apply_batch(vec![WritePageRequest {
                workspace_id: ws,
                project_id: proj,
                path: PagePath::new("batch/admitted.md").unwrap(),
                frontmatter: serde_json::json!({"title": "before"}),
                body: "before".into(),
                tier: Tier::Semantic,
                pinned: false,
                title: None,
                admission_ctx: Some(AdmissionContext {
                    op: AdmissionOp::Consolidate,
                    ..AdmissionContext::default()
                }),
                author_id: None,
                actor: ai_memory_core::ActorContext::anonymous(),
                evidence: Vec::new(),
            }])
            .await
            .unwrap();
        assert_eq!(ids.len(), 1);

        let on_disk = std::fs::read_to_string(wiki.abs_path(
            ws,
            proj,
            &PagePath::new("batch/admitted.md").unwrap(),
        ))
        .unwrap();
        assert!(on_disk.contains("[REDACTED:api_key]"), "{on_disk}");
        assert!(!on_disk.contains("sk-1234567890abcdef"), "{on_disk}");

        let hits = store
            .reader
            .search_pages("REDACTED".into(), 5, None)
            .await
            .unwrap();
        assert_eq!(hits.len(), 1);
    }

    /// The preflight runs the blocking chain with no body and rejects when a
    /// `reject`-policy webhook refuses — so a caller can fail fast before
    /// spending an LLM call — while writing nothing to disk.
    #[tokio::test]
    async fn preflight_admission_rejects_without_writing() {
        use crate::admission::{AdmissionChain, AdmissionOp, FailurePolicy, WebhookConfig};
        use axum::http::StatusCode;
        use axum::routing::post;
        use axum::{Json, Router};
        use tokio::net::TcpListener;

        // A scope-guard-style webhook that refuses the write outright.
        let app = Router::new().route(
            "/gate",
            post(|Json(_payload): Json<serde_json::Value>| async move {
                (StatusCode::FORBIDDEN, "denied for this scope")
            }),
        );
        let listener = TcpListener::bind("127.0.0.1:0").await.unwrap();
        let addr = listener.local_addr().unwrap();
        tokio::spawn(async move {
            axum::serve(listener, app).await.unwrap();
        });

        let tmp = TempDir::new().unwrap();
        let store = Store::open(tmp.path()).unwrap();
        let ws = store
            .writer
            .get_or_create_workspace("default")
            .await
            .unwrap();
        let proj = store
            .writer
            .get_or_create_project(ws, "scratch", None)
            .await
            .unwrap();
        let chain = AdmissionChain::new(vec![WebhookConfig {
            name: "gate".into(),
            url: format!("http://{addr}/gate"),
            timeout_ms: 1_000,
            failure_policy: FailurePolicy::Reject,
            events: vec![AdmissionOp::Consolidate],
            blocking: true,
        }])
        .unwrap();
        let wiki = Wiki::new(tmp.path(), store.writer.clone())
            .unwrap()
            .with_admission_chain(chain)
            .with_store_reader(store.reader.clone());

        let path = PagePath::new("sessions/abc.md").unwrap();
        let err = wiki
            .preflight_admission(
                ws,
                proj,
                &path,
                AdmissionOp::Consolidate,
                ai_memory_core::ActorContext::anonymous(),
            )
            .await
            .expect_err("reject-policy webhook must fail the preflight");
        assert!(
            format!("{err}").contains("denied for this scope"),
            "the webhook rejection reason should surface: {err}",
        );
        // The preflight never persists anything.
        assert!(!wiki.abs_path(ws, proj, &path).exists());
    }

    /// With no admission chain attached there is nothing to gate, so the
    /// preflight is a no-op that always succeeds.
    #[tokio::test]
    async fn preflight_admission_is_noop_without_chain() {
        let tmp = TempDir::new().unwrap();
        let store = Store::open(tmp.path()).unwrap();
        let ws = store
            .writer
            .get_or_create_workspace("default")
            .await
            .unwrap();
        let proj = store
            .writer
            .get_or_create_project(ws, "scratch", None)
            .await
            .unwrap();
        let wiki = Wiki::new(tmp.path(), store.writer.clone()).unwrap();
        wiki.preflight_admission(
            ws,
            proj,
            &PagePath::new("sessions/abc.md").unwrap(),
            AdmissionOp::Consolidate,
            ai_memory_core::ActorContext::anonymous(),
        )
        .await
        .expect("no chain → preflight is a no-op");
    }

    /// Two projects writing the same relative path must produce two distinct
    /// files under their respective UUID-namespaced directories.
    #[tokio::test]
    async fn two_projects_same_path_no_collision() {
        let tmp = TempDir::new().unwrap();
        let store = Store::open(tmp.path()).unwrap();
        let ws = store
            .writer
            .get_or_create_workspace("default")
            .await
            .unwrap();
        let proj_a = store
            .writer
            .get_or_create_project(ws, "alpha", None)
            .await
            .unwrap();
        let proj_b = store
            .writer
            .get_or_create_project(ws, "beta", None)
            .await
            .unwrap();
        let wiki = Wiki::new(tmp.path(), store.writer.clone()).unwrap();

        wiki.write_page(WritePageRequest {
            workspace_id: ws,
            project_id: proj_a,
            path: PagePath::new("decisions/foo.md").unwrap(),
            frontmatter: serde_json::json!({"title": "Alpha decision"}),
            body: "Alpha body".into(),
            tier: Tier::Semantic,
            pinned: false,
            title: None,
            admission_ctx: None,
            author_id: None,
            actor: ai_memory_core::ActorContext::anonymous(),
            evidence: Vec::new(),
        })
        .await
        .unwrap();

        wiki.write_page(WritePageRequest {
            workspace_id: ws,
            project_id: proj_b,
            path: PagePath::new("decisions/foo.md").unwrap(),
            frontmatter: serde_json::json!({"title": "Beta decision"}),
            body: "Beta body".into(),
            tier: Tier::Semantic,
            pinned: false,
            title: None,
            admission_ctx: None,
            author_id: None,
            actor: ai_memory_core::ActorContext::anonymous(),
            evidence: Vec::new(),
        })
        .await
        .unwrap();

        let page = PagePath::new("decisions/foo.md").unwrap();
        let path_a = wiki.abs_path(ws, proj_a, &page);
        let path_b = wiki.abs_path(ws, proj_b, &page);

        assert!(path_a.is_file(), "alpha file must exist");
        assert!(path_b.is_file(), "beta file must exist");
        assert_ne!(path_a, path_b, "distinct paths on disk");

        let content_a = std::fs::read_to_string(&path_a).unwrap();
        let content_b = std::fs::read_to_string(&path_b).unwrap();
        assert!(content_a.contains("Alpha body"), "alpha content intact");
        assert!(content_b.contains("Beta body"), "beta content intact");
    }

    #[tokio::test]
    async fn rewriting_same_body_is_idempotent() {
        let tmp = TempDir::new().unwrap();
        let store = Store::open(tmp.path()).unwrap();
        let ws = store
            .writer
            .get_or_create_workspace("default")
            .await
            .unwrap();
        let proj = store
            .writer
            .get_or_create_project(ws, "scratch", None)
            .await
            .unwrap();
        let wiki = Wiki::new(tmp.path(), store.writer.clone()).unwrap();

        let r = |body: &str| req(ws, proj, "a.md", body, serde_json::json!({ "title": "A" }));

        let a = wiki.write_page(r("body one")).await.unwrap();
        let b = wiki.write_page(r("body one")).await.unwrap();
        assert_eq!(a, b);
        let c = wiki.write_page(r("body two")).await.unwrap();
        assert_ne!(b, c);
    }

    /// End-to-end gate for the workspace/project name resolution:
    /// when a wiki is built with both a store reader and an admission
    /// chain, `write_page` populates `AdmissionContext.workspace` and
    /// `AdmissionContext.project` from the resolved store rows before
    /// invoking the chain. Without [`Wiki::with_store_reader`] the
    /// fields stay empty (backward compat with external test setups).
    #[tokio::test]
    async fn write_page_resolves_workspace_and_project_names_for_chain() {
        use crate::admission::{
            AdmissionChain, AdmissionContext, AdmissionOp, FailurePolicy, WebhookConfig,
        };
        use axum::http::StatusCode;
        use axum::response::IntoResponse;
        use axum::routing::post;
        use axum::{Json, Router};
        use std::sync::Mutex;
        use tokio::net::TcpListener;

        let tmp = TempDir::new().unwrap();
        let store = Store::open(tmp.path()).unwrap();
        let ws = store
            .writer
            .get_or_create_workspace("staging")
            .await
            .unwrap();
        let proj = store
            .writer
            .get_or_create_project(ws, "ai-memory-ops", None)
            .await
            .unwrap();

        // Throwaway HTTP server that records the payload it receives.
        let recorder: Arc<Mutex<Option<serde_json::Value>>> = Arc::new(Mutex::new(None));
        let recorder_clone = recorder.clone();
        let app = Router::new().route(
            "/sync",
            post(move |Json(payload): Json<serde_json::Value>| {
                let recorder = recorder_clone.clone();
                async move {
                    *recorder.lock().unwrap() = Some(payload);
                    StatusCode::NO_CONTENT.into_response()
                }
            }),
        );
        let listener = TcpListener::bind("127.0.0.1:0").await.unwrap();
        let addr = listener.local_addr().unwrap();
        tokio::spawn(async move {
            axum::serve(listener, app).await.unwrap();
        });

        let chain = AdmissionChain::new(vec![WebhookConfig {
            name: "recorder".into(),
            url: format!("http://{addr}/sync"),
            timeout_ms: 1_000,
            failure_policy: FailurePolicy::Ignore,
            events: vec![AdmissionOp::WritePage],
            blocking: true,
        }])
        .unwrap();

        let wiki = Wiki::new(tmp.path(), store.writer.clone())
            .unwrap()
            .with_admission_chain(chain)
            .with_store_reader(store.reader.clone());

        wiki.write_page(WritePageRequest {
            workspace_id: ws,
            project_id: proj,
            path: PagePath::new("notes/x.md").unwrap(),
            frontmatter: serde_json::json!({"title": "X"}),
            body: "hi".into(),
            tier: Tier::Semantic,
            pinned: false,
            title: None,
            admission_ctx: Some(AdmissionContext {
                op: AdmissionOp::WritePage,
                ..AdmissionContext::default()
            }),
            author_id: None,
            actor: ai_memory_core::ActorContext::anonymous(),
            evidence: Vec::new(),
        })
        .await
        .unwrap();

        let payload = recorder
            .lock()
            .unwrap()
            .clone()
            .expect("webhook should have recorded the payload");
        assert_eq!(payload["ctx"]["workspace"], serde_json::json!("staging"));
        assert_eq!(
            payload["ctx"]["project"],
            serde_json::json!("ai-memory-ops")
        );
    }

    // ── P1.6: write attribution ─────────────────────────────────────

    /// Anonymous actor must NOT add a `last_modified_by` block — this
    /// is the backward-compat gate for every existing single-user
    /// install.
    #[test]
    fn stamp_last_modified_by_skips_anonymous_actor() {
        let fm = serde_json::json!({"title": "X", "kind": "fact"});
        let stamped =
            stamp_last_modified_by(fm.clone(), &ai_memory_core::ActorContext::anonymous());
        assert_eq!(
            stamped, fm,
            "anonymous actor must leave frontmatter untouched"
        );
    }

    /// Identified actor adds the full block (username + name + email
    /// when present). Existing keys in frontmatter are preserved.
    #[test]
    fn stamp_last_modified_by_adds_full_block() {
        let actor = ai_memory_core::ActorContext {
            user: Some("alice".into()),
            name: Some("Alice Smith".into()),
            email: Some("alice@home".into()),
            ..ai_memory_core::ActorContext::default()
        };
        let stamped =
            stamp_last_modified_by(serde_json::json!({"title": "X", "kind": "fact"}), &actor);
        let lmb = &stamped["last_modified_by"];
        assert_eq!(lmb["username"], "alice");
        assert_eq!(lmb["name"], "Alice Smith");
        assert_eq!(lmb["email"], "alice@home");
        assert_eq!(stamped["title"], "X");
        assert_eq!(stamped["kind"], "fact");
    }

    /// Username-only (no name/email) writes a minimal block.
    #[test]
    fn stamp_last_modified_by_minimal_username_only() {
        let actor = ai_memory_core::ActorContext {
            user: Some("boss".into()),
            ..ai_memory_core::ActorContext::default()
        };
        let stamped = stamp_last_modified_by(serde_json::json!({}), &actor);
        let lmb = &stamped["last_modified_by"];
        assert_eq!(lmb["username"], "boss");
        assert!(lmb.get("name").is_none(), "name omitted when not set");
        assert!(lmb.get("email").is_none(), "email omitted when not set");
    }

    /// Repeated writes by different actors replace the block.
    #[test]
    fn stamp_last_modified_by_replaces_previous_block() {
        let first = ai_memory_core::ActorContext {
            user: Some("alice".into()),
            ..ai_memory_core::ActorContext::default()
        };
        let after_alice = stamp_last_modified_by(serde_json::json!({}), &first);
        assert_eq!(after_alice["last_modified_by"]["username"], "alice");

        let second = ai_memory_core::ActorContext {
            user: Some("bob".into()),
            ..ai_memory_core::ActorContext::default()
        };
        let after_bob = stamp_last_modified_by(after_alice, &second);
        assert_eq!(
            after_bob["last_modified_by"]["username"], "bob",
            "second write replaces, doesn't accumulate"
        );
    }

    /// Null frontmatter is turned into a fresh object on a
    /// non-anonymous write rather than rejected.
    #[test]
    fn stamp_last_modified_by_handles_null_input() {
        let actor = ai_memory_core::ActorContext {
            user: Some("alice".into()),
            ..ai_memory_core::ActorContext::default()
        };
        let stamped = stamp_last_modified_by(serde_json::Value::Null, &actor);
        assert_eq!(stamped["last_modified_by"]["username"], "alice");
    }

    /// End-to-end: a write with a non-anonymous actor lands a
    /// `last_modified_by` block on disk AND `pages.author_id` carries
    /// the UserId.
    #[tokio::test]
    async fn write_page_with_actor_stamps_frontmatter_and_author_id() {
        use ai_memory_core::{NewUser, UserId};
        let tmp = TempDir::new().unwrap();
        let store = Store::open(tmp.path()).unwrap();
        let wiki = Wiki::new(tmp.path(), store.writer.clone()).unwrap();

        let ws = store
            .writer
            .get_or_create_workspace("default")
            .await
            .unwrap();
        let proj = store
            .writer
            .get_or_create_project(ws, "scratch", None)
            .await
            .unwrap();

        // Pre-load an actual users row so author_id can FK-resolve.
        let mut new_user = NewUser {
            username: "alice".into(),
            name: Some("Alice Smith".into()),
            email: Some("[email protected]".into()),
        };
        new_user.validate().unwrap();
        let user_id: UserId = store
            .writer
            .create_human_user(new_user, ai_memory_core::UserRole::User, None, false)
            .await
            .unwrap();

        wiki.write_page(WritePageRequest {
            workspace_id: ws,
            project_id: proj,
            path: PagePath::new("notes/note.md").unwrap(),
            frontmatter: serde_json::json!({"title": "Note"}),
            body: "body".into(),
            tier: Tier::Semantic,
            pinned: false,
            title: None,
            admission_ctx: None,
            author_id: Some(user_id),
            actor: ai_memory_core::ActorContext {
                user: Some("alice".into()),
                name: Some("Alice Smith".into()),
                email: Some("[email protected]".into()),
                ..ai_memory_core::ActorContext::default()
            },
            evidence: Vec::new(),
        })
        .await
        .unwrap();

        let md = wiki
            .read_page(ws, proj, &PagePath::new("notes/note.md").unwrap())
            .unwrap();
        assert_eq!(md.frontmatter["last_modified_by"]["username"], "alice");
        assert_eq!(
            md.frontmatter["last_modified_by"]["email"],
            "[email protected]"
        );

        let meta = store
            .reader
            .page_meta_by_path("notes/note.md")
            .await
            .unwrap()
            .expect("page exists");
        let _ = meta;
    }

    /// #607 item 2: a purge commits the DB deletion but removes on-disk files
    /// only afterward (best-effort). If that removal is interrupted, the
    /// markdown directory — `_meta.md` included — survives with no `projects`
    /// row. `reindex_all` must NOT resurrect it: the tombstone written in the
    /// purge transaction makes the deletion terminal.
    #[tokio::test]
    async fn reindex_does_not_resurrect_a_purged_scope_whose_files_survived() {
        let tmp = TempDir::new().unwrap();
        let store = Store::open(tmp.path()).unwrap();
        let wiki = Wiki::new(tmp.path(), store.writer.clone())
            .unwrap()
            .with_store_reader(store.reader.clone());
        let ws = store
            .writer
            .get_or_create_workspace("default")
            .await
            .unwrap();
        let proj = store
            .writer
            .get_or_create_project(ws, "scratch", None)
            .await
            .unwrap();

        let path = PagePath::new("notes/keep.md").unwrap();
        wiki.write_page(WritePageRequest {
            workspace_id: ws,
            project_id: proj,
            path: PagePath::new("notes/keep.md").unwrap(),
            frontmatter: serde_json::json!({"title": "Keep"}),
            body: "survivor".into(),
            tier: Tier::Semantic,
            pinned: false,
            title: None,
            admission_ctx: None,
            author_id: None,
            actor: ai_memory_core::ActorContext::anonymous(),
            evidence: Vec::new(),
        })
        .await
        .unwrap();
        // Manifests reindex reads to recreate scopes from disk.
        wiki.backfill_scope_manifests().await.unwrap();

        // Purge the DB only (store side); the on-disk files intentionally
        // survive — exactly the crash-before-file-removal window.
        store
            .writer
            .purge_project(
                ws,
                proj,
                "default/scratch",
                None,
                false,
                ai_memory_store::Compaction::Skip,
                ai_memory_store::PurgeMode::Commit,
            )
            .await
            .unwrap();
        let meta_on_disk = tmp
            .path()
            .join("wiki")
            .join(ws.to_string())
            .join(proj.to_string())
            .join("_meta.md");
        assert!(
            meta_on_disk.exists(),
            "the purge left the manifest on disk (the crash window this guards)"
        );

        let summary = wiki.reindex_all().await.unwrap();

        assert_eq!(
            summary.skipped_purged, 1,
            "the purged scope must be skipped"
        );
        assert_eq!(
            summary.projects, 0,
            "the purged project must not be recreated"
        );
        assert!(
            store
                .reader
                .page_body_by_ids(ws, proj, path.as_str())
                .await
                .unwrap()
                .is_none(),
            "a purged page must not reappear in the index"
        );
    }

    async fn finish_lock_test<F: std::future::Future>(future: F) -> F::Output {
        tokio::time::timeout(std::time::Duration::from_secs(5), future)
            .await
            .expect("wiki lock operation must finish without deadlock")
    }

    // Poll the real operation until it queues behind the held page mutex.
    // Unlike a delay, this proves it reached that lock before we release it.
    async fn wait_for_page_waiter<F: std::future::Future>(
        wiki: &Wiki,
        key: &PageKey,
        mut future: std::pin::Pin<&mut F>,
    ) {
        finish_lock_test(std::future::poll_fn(|cx| {
            assert!(
                future.as_mut().poll(cx).is_pending(),
                "operation bypassed the held page lock"
            );
            let locks = wiki.page_locks.lock().unwrap();
            if locks
                .get(key)
                .is_some_and(|lock| Arc::strong_count(lock) >= 3)
            {
                std::task::Poll::Ready(())
            } else {
                std::task::Poll::Pending
            }
        }))
        .await;
    }

    #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
    async fn reindex_page_lock_waits_before_reading_and_allows_another_path() {
        let tmp = TempDir::new().unwrap();
        let (store, wiki, ws, proj) = scoped(&tmp).await;
        let path = PagePath::new("notes/held.md").unwrap();
        let other = PagePath::new("notes/other.md").unwrap();
        let original = wiki
            .write_page(req(
                ws,
                proj,
                path.as_str(),
                "original",
                serde_json::json!({}),
            ))
            .await
            .unwrap();
        wiki.write_page(req(
            ws,
            proj,
            other.as_str(),
            "control",
            serde_json::json!({}),
        ))
        .await
        .unwrap();

        let global = wiki.mutation_lock.read().await;
        let page = wiki.lock_page(ws, proj, &path).await;
        let abs = wiki.abs_path(ws, proj, &path);
        std::fs::write(&abs, "transientsnapshot\n").unwrap();
        let reindex = wiki.reindex_page(ws, proj, path.clone());
        tokio::pin!(reindex);
        wait_for_page_waiter(&wiki, &(ws, proj, path.clone()), reindex.as_mut()).await;
        assert_eq!(
            store
                .reader
                .latest_page_id_by_ids(ws, proj, path.as_str().into())
                .await
                .unwrap(),
            Some(original),
            "the transient disk snapshot must not enter SQL"
        );

        let other_abs = wiki.abs_path(ws, proj, &other);
        std::fs::write(&other_abs, "independentcontrol\n").unwrap();
        finish_lock_test(wiki.reindex_page(ws, proj, other.clone()))
            .await
            .unwrap();
        assert_eq!(
            store
                .reader
                .page_body_by_ids(ws, proj, other.as_str())
                .await
                .unwrap()
                .unwrap()
                .body,
            "independentcontrol\n"
        );
        assert_eq!(
            std::fs::read_to_string(&other_abs).unwrap(),
            "independentcontrol\n"
        );

        std::fs::write(&abs, "committedwinner\n").unwrap();
        drop(page);
        drop(global);
        let id = finish_lock_test(reindex).await.unwrap();
        assert_ne!(id, original);
        assert_eq!(
            store
                .reader
                .page_body_by_ids(ws, proj, path.as_str())
                .await
                .unwrap()
                .unwrap()
                .body,
            "committedwinner\n"
        );
        assert_eq!(std::fs::read_to_string(&abs).unwrap(), "committedwinner\n");
        assert!(
            store
                .reader
                .search_pages("transientsnapshot".into(), 10, None)
                .await
                .unwrap()
                .is_empty()
        );
    }

    #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
    async fn reindex_page_lock_serializes_write_through_the_upsert() {
        let tmp = TempDir::new().unwrap();
        let (store, wiki, ws, proj) = scoped(&tmp).await;
        let path = PagePath::new("notes/race.md").unwrap();
        wiki.write_page(req(
            ws,
            proj,
            path.as_str(),
            "original",
            serde_json::json!({}),
        ))
        .await
        .unwrap();
        std::fs::write(wiki.abs_path(ws, proj, &path), "watcher snapshot\n").unwrap();
        let barrier = Arc::new(tokio::sync::Barrier::new(2));
        let mut watcher = wiki.clone();
        watcher.reindex_read_barrier = Some(barrier.clone());
        let reindex_path = path.clone();
        let reindex =
            tokio::spawn(async move { watcher.reindex_page(ws, proj, reindex_path).await });
        finish_lock_test(barrier.wait()).await;

        let write = wiki.write_page(req(
            ws,
            proj,
            path.as_str(),
            "writer winner",
            serde_json::json!({}),
        ));
        tokio::pin!(write);
        wait_for_page_waiter(&wiki, &(ws, proj, path.clone()), write.as_mut()).await;
        assert_eq!(
            wiki.read_page(ws, proj, &path).unwrap().body,
            "watcher snapshot\n"
        );
        finish_lock_test(barrier.wait()).await;
        let watcher_id = finish_lock_test(reindex).await.unwrap().unwrap();
        let writer_id = finish_lock_test(write).await.unwrap();
        assert_ne!(writer_id, watcher_id);
        assert_eq!(
            wiki.read_page(ws, proj, &path).unwrap().body.trim(),
            "writer winner"
        );
        assert_eq!(
            store
                .reader
                .page_body_by_ids(ws, proj, path.as_str())
                .await
                .unwrap()
                .unwrap()
                .body,
            "writer winner"
        );
        store
            .reader
            .with_conn(move |conn| {
                let (body, supersedes): (String, Vec<u8>) = conn.query_row(
                    "SELECT body, supersedes FROM pages WHERE id = ?1 AND is_latest = 1",
                    [writer_id.as_bytes()],
                    |row| Ok((row.get(0)?, row.get(1)?)),
                )?;
                assert_eq!(body, "writer winner");
                assert_eq!(supersedes, watcher_id.as_bytes());
                let prior: String = conn.query_row(
                    "SELECT body FROM pages WHERE id = ?1",
                    [watcher_id.as_bytes()],
                    |row| row.get(0),
                )?;
                assert_eq!(
                    prior, "watcher snapshot\n",
                    "the earlier version stays reachable"
                );
                Ok(())
            })
            .await
            .unwrap();
    }

    #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
    async fn reindex_page_lock_and_reversed_duplicate_batches_do_not_deadlock() {
        let tmp = TempDir::new().unwrap();
        let (store, wiki, ws, proj) = scoped(&tmp).await;
        let a = PagePath::new("notes/a.md").unwrap();
        let z = PagePath::new("notes/z.md").unwrap();
        let batch = |paths: &[&PagePath], body: &str| {
            paths
                .iter()
                .map(|path| req(ws, proj, path.as_str(), body, serde_json::json!({})))
                .collect()
        };
        wiki.apply_batch(batch(&[&a, &z], "original"))
            .await
            .unwrap();
        std::fs::write(wiki.abs_path(ws, proj, &z), "watcher snapshot\n").unwrap();
        let barrier = Arc::new(tokio::sync::Barrier::new(2));
        let mut watcher = wiki.clone();
        watcher.reindex_read_barrier = Some(barrier.clone());
        let reindex_path = z.clone();
        let reindex =
            tokio::spawn(async move { watcher.reindex_page(ws, proj, reindex_path).await });
        finish_lock_test(barrier.wait()).await;

        let reverse = wiki.apply_batch(batch(&[&z, &a, &a], "first batch"));
        tokio::pin!(reverse);
        wait_for_page_waiter(&wiki, &(ws, proj, z.clone()), reverse.as_mut()).await;
        let forward = wiki.apply_batch(batch(&[&a, &z], "second batch winner"));
        tokio::pin!(forward);
        wait_for_page_waiter(&wiki, &(ws, proj, a.clone()), forward.as_mut()).await;
        finish_lock_test(barrier.wait()).await;
        let watcher_id = finish_lock_test(reindex).await.unwrap().unwrap();
        let first = finish_lock_test(reverse).await.unwrap();
        let second = finish_lock_test(forward).await.unwrap();
        assert_eq!(
            first[1], first[2],
            "duplicate paths share one lock and no-op version"
        );
        for (path, id) in [(&a, second[0]), (&z, second[1])] {
            assert_eq!(
                wiki.read_page(ws, proj, path).unwrap().body.trim(),
                "second batch winner"
            );
            assert_eq!(
                store
                    .reader
                    .latest_page_id_by_ids(ws, proj, path.as_str().into())
                    .await
                    .unwrap(),
                Some(id)
            );
            assert_eq!(
                store
                    .reader
                    .page_body_by_ids(ws, proj, path.as_str())
                    .await
                    .unwrap()
                    .unwrap()
                    .body,
                "second batch winner"
            );
        }
        store
            .reader
            .with_conn(move |conn| {
                let ancestor: Vec<u8> = conn.query_row(
                    "SELECT supersedes FROM pages WHERE id = ?1",
                    [second[1].as_bytes()],
                    |row| row.get(0),
                )?;
                assert_eq!(ancestor, first[0].as_bytes());
                let ancestor: Vec<u8> = conn.query_row(
                    "SELECT supersedes FROM pages WHERE id = ?1",
                    [first[0].as_bytes()],
                    |row| row.get(0),
                )?;
                assert_eq!(ancestor, watcher_id.as_bytes());
                Ok(())
            })
            .await
            .unwrap();
    }

    #[tokio::test]
    async fn reindex_page_lock_releases_both_guards_before_embedding() {
        struct LockCheckingEmbedder {
            wiki: Wiki,
            key: PageKey,
            calls: std::sync::atomic::AtomicUsize,
            inner: ai_memory_llm::SyntheticEmbedder,
        }
        #[async_trait::async_trait]
        impl Embedder for LockCheckingEmbedder {
            fn provider(&self) -> &'static str {
                self.inner.provider()
            }
            fn model(&self) -> &str {
                self.inner.model()
            }
            fn dim(&self) -> u32 {
                self.inner.dim()
            }
            async fn embed(&self, text: &str) -> ai_memory_llm::LlmResult<Vec<f32>> {
                let global = self
                    .wiki
                    .mutation_lock
                    .try_write()
                    .expect("embedding must run outside the global lock");
                let page =
                    finish_lock_test(self.wiki.lock_page(self.key.0, self.key.1, &self.key.2))
                        .await;
                drop(page);
                drop(global);
                self.calls.fetch_add(1, std::sync::atomic::Ordering::SeqCst);
                self.inner.embed(text).await
            }
        }
        let tmp = TempDir::new().unwrap();
        let (store, wiki, ws, proj) = scoped(&tmp).await;
        let path = PagePath::new("notes/embed.md").unwrap();
        std::fs::create_dir_all(wiki.abs_path(ws, proj, &path).parent().unwrap()).unwrap();
        std::fs::write(
            wiki.abs_path(ws, proj, &path),
            "---\nabstract: short summary\n---\nembedded body\n",
        )
        .unwrap();
        let embedder = Arc::new(LockCheckingEmbedder {
            wiki: wiki.clone(),
            key: (ws, proj, path.clone()),
            calls: std::sync::atomic::AtomicUsize::new(0),
            inner: ai_memory_llm::SyntheticEmbedder::new(32),
        });
        let wiki = wiki.with_embedder(embedder.clone());
        let id = finish_lock_test(wiki.reindex_page(ws, proj, path))
            .await
            .unwrap();
        assert_eq!(embedder.calls.load(std::sync::atomic::Ordering::SeqCst), 2);
        assert!(
            store
                .reader
                .embedded_page_ids(ws, proj, "synthetic".into(), "bag-of-words-v1".into(), 32)
                .await
                .unwrap()
                .contains(&id)
        );
    }

    /// #607 item 3: two concurrent writes to the SAME page path must not
    /// interleave their file-rename and DB-upsert. Per-path serialization
    /// guarantees the winning writer's body lands in both the on-disk file and
    /// the DB `is_latest` row — they never disagree about who won.
    #[tokio::test(flavor = "multi_thread", worker_threads = 4)]
    async fn concurrent_same_path_writes_keep_file_and_db_consistent() {
        let tmp = TempDir::new().unwrap();
        let store = Store::open(tmp.path()).unwrap();
        let wiki = Wiki::new(tmp.path(), store.writer.clone()).unwrap();
        let ws = store
            .writer
            .get_or_create_workspace("default")
            .await
            .unwrap();
        let proj = store
            .writer
            .get_or_create_project(ws, "scratch", None)
            .await
            .unwrap();

        let path = PagePath::new("notes/hot.md").unwrap();
        let mk = |tag: char| WritePageRequest {
            workspace_id: ws,
            project_id: proj,
            path: PagePath::new("notes/hot.md").unwrap(),
            frontmatter: serde_json::json!({"title": "Hot"}),
            body: format!("body-{tag}"),
            tier: Tier::Semantic,
            pinned: false,
            title: None,
            admission_ctx: None,
            author_id: None,
            actor: ai_memory_core::ActorContext::anonymous(),
            evidence: Vec::new(),
        };

        // Many rounds so any interleave window is likely to be exercised.
        for _ in 0..25 {
            let (wa, wb) = (wiki.clone(), wiki.clone());
            let (ra, rb) = (mk('a'), mk('b'));
            let ha = tokio::spawn(async move { wa.write_page(ra).await });
            let hb = tokio::spawn(async move { wb.write_page(rb).await });
            ha.await.unwrap().unwrap();
            hb.await.unwrap().unwrap();

            let on_disk = wiki.read_page(ws, proj, &path).unwrap().body;
            let in_db = store
                .reader
                .page_body_by_ids(ws, proj, path.as_str())
                .await
                .unwrap()
                .expect("a latest row exists")
                .body;
            // Compare who won, not exact bytes (emit/parse normalizes newlines):
            // the file and the DB latest row must reflect the same writer.
            assert_eq!(
                on_disk.contains("body-a"),
                in_db.contains("body-a"),
                "file ({on_disk:?}) and DB latest ({in_db:?}) disagree on the winning writer"
            );
        }
    }

    /// Backward-compat: anonymous writes do not add attribution frontmatter.
    #[tokio::test]
    async fn write_page_with_anonymous_actor_omits_attribution_frontmatter() {
        let tmp = TempDir::new().unwrap();
        let store = Store::open(tmp.path()).unwrap();
        let wiki = Wiki::new(tmp.path(), store.writer.clone()).unwrap();
        let ws = store
            .writer
            .get_or_create_workspace("default")
            .await
            .unwrap();
        let proj = store
            .writer
            .get_or_create_project(ws, "scratch", None)
            .await
            .unwrap();

        wiki.write_page(WritePageRequest {
            workspace_id: ws,
            project_id: proj,
            path: PagePath::new("notes/anon.md").unwrap(),
            frontmatter: serde_json::json!({"title": "Anon"}),
            body: "body".into(),
            tier: Tier::Semantic,
            pinned: false,
            title: None,
            admission_ctx: None,
            author_id: None,
            actor: ai_memory_core::ActorContext::anonymous(),
            evidence: Vec::new(),
        })
        .await
        .unwrap();

        let md = wiki
            .read_page(ws, proj, &PagePath::new("notes/anon.md").unwrap())
            .unwrap();
        assert!(
            md.frontmatter.get("last_modified_by").is_none(),
            "anonymous writes must NOT add last_modified_by — backward compat"
        );
        assert_eq!(md.frontmatter["title"], "Anon");
    }

    fn copy_tree(src: &Path, dst: &Path) {
        std::fs::create_dir_all(dst).unwrap();
        for entry in std::fs::read_dir(src).unwrap() {
            let entry = entry.unwrap();
            let to = dst.join(entry.file_name());
            if entry.file_type().unwrap().is_dir() {
                copy_tree(&entry.path(), &to);
            } else {
                std::fs::copy(entry.path(), &to).unwrap();
            }
        }
    }

    /// End-to-end "DB is rebuildable from files": `backfill_scope_manifests`
    /// repairs a tree whose manifests are missing (one written by a release
    /// before scopes described themselves from their first page), then
    /// `reindex_all` on a FRESH store (no DB carried over) recreates the
    /// named scopes + all pages from the wiki tree alone — including a page
    /// that lives at the reserved name `log.md` (kept because it has
    /// frontmatter).
    #[tokio::test]
    async fn backfill_then_reindex_rebuilds_from_wiki_alone() {
        // Source store: a named scope with two pages (one at `log.md`).
        let src = TempDir::new().unwrap();
        let s1 = Store::open(src.path()).unwrap();
        let ws = s1.writer.get_or_create_workspace("acme").await.unwrap();
        let proj = s1
            .writer
            .get_or_create_project(ws, "webapp", Some("/repo/webapp".into()))
            .await
            .unwrap();
        let w1 = Wiki::new(src.path(), s1.writer.clone())
            .unwrap()
            .with_store_reader(s1.reader.clone());
        w1.apply_batch(vec![
            req(
                ws,
                proj,
                "notes/a.md",
                "alpha uniquetoken",
                serde_json::json!({"entities": ["NATS JetStream"]}),
            ),
            req(
                ws,
                proj,
                "log.md",
                "a page that lives at the reserved log name",
                serde_json::json!({ "title": "Log Page" }),
            ),
        ])
        .await
        .unwrap();

        // Simulate a tree written by an engine that had no manifests at all
        // (pre-#643 releases), so the backfill is exercised as the repair
        // path it now is — the writes above already made this scope
        // self-describing on their own.
        let ws_dir = src.path().join("wiki").join(ws.to_string());
        std::fs::remove_file(ws_dir.join("_meta.md")).unwrap();
        std::fs::remove_file(ws_dir.join(proj.to_string()).join("_meta.md")).unwrap();

        // Make the wiki self-describing again.
        let written = w1.backfill_scope_manifests().await.unwrap();
        assert!(written >= 2, "ws + proj manifests written, got {written}");
        assert!(ws_dir.join("_meta.md").is_file());
        assert!(ws_dir.join(proj.to_string()).join("_meta.md").is_file());
        drop(s1);

        // Fresh store; copy ONLY the wiki tree (no db/); rebuild from it.
        let dst = TempDir::new().unwrap();
        let s2 = Store::open(dst.path()).unwrap();
        copy_tree(&src.path().join("wiki"), &dst.path().join("wiki"));
        let w2 = Wiki::new(dst.path(), s2.writer.clone()).unwrap();
        let summary = w2.reindex_all().await.unwrap();

        assert_eq!(summary.projects, 1);
        assert_eq!(summary.pages, 2, "both pages incl. log.md reconstructed");
        assert_eq!(
            s2.reader.workspace_name_by_id(ws).await.unwrap().as_deref(),
            Some("acme"),
            "workspace name recovered from _meta.md"
        );
        let hits = s2
            .reader
            .search_pages("uniquetoken".into(), 5, None)
            .await
            .unwrap();
        assert_eq!(
            hits.len(),
            1,
            "reindexed page is searchable in the fresh store"
        );
        let entity_hits = s2
            .reader
            .hybrid_search(
                ws,
                proj,
                "jetstream".into(),
                None,
                String::new(),
                String::new(),
                0,
                5,
                None,
                false,
            )
            .await
            .unwrap();
        assert_eq!(
            entity_hits.len(),
            1,
            "reindex must rebuild the entity stream from canonical frontmatter"
        );
        assert_eq!(entity_hits[0].path.as_str(), "notes/a.md");
        drop(s2);
    }

    #[tokio::test]
    async fn promoted_identity_round_trips_through_manifest_and_clean_reindex() {
        let src = TempDir::new().unwrap();
        let source = Store::open(src.path()).unwrap();
        let workspace = source
            .writer
            .get_or_create_workspace("default")
            .await
            .unwrap();
        let identity = ai_memory_core::repository_identity::RepositoryIdentity {
            identity: "github.com/acme/platform/api".into(),
            source: ai_memory_core::repository_identity::IdentitySource::GitRemote,
        };
        let (project, _) = source
            .writer
            .resolve_project_by_identity(
                workspace,
                identity.clone(),
                ai_memory_core::repository_identity::IdentityStyle::HostPath,
                "api",
                Some("/src/api".into()),
                None,
                None,
            )
            .await
            .unwrap();
        let wiki = Wiki::new(src.path(), source.writer.clone())
            .unwrap()
            .with_store_reader(source.reader.clone());
        wiki.write_page(req(
            workspace,
            project,
            "notes/history.md",
            "history survives reindex",
            serde_json::json!({}),
        ))
        .await
        .unwrap();
        let promoted =
            ai_memory_store::create_explicit_scope(&source.writer, "default", "acme-platform-api")
                .await
                .unwrap();
        assert_eq!(promoted.scope.project_id, project);
        assert_eq!(promoted.promoted_from.as_deref(), Some("api"));
        assert!(
            wiki.refresh_renamed_scope(workspace, project)
                .await
                .unwrap()
                .is_some()
        );
        let manifest_path = src
            .path()
            .join("wiki")
            .join(workspace.to_string())
            .join(project.to_string())
            .join("_meta.md");
        let manifest = std::fs::read_to_string(&manifest_path).unwrap();
        assert!(
            manifest.contains("project: acme-platform-api"),
            "{manifest}"
        );
        assert!(
            manifest.contains("identity: github.com/acme/platform/api"),
            "{manifest}"
        );
        assert!(
            manifest.contains("identity_source: git_remote"),
            "{manifest}"
        );
        assert!(
            manifest.contains("canonical_name: acme-platform-api"),
            "{manifest}"
        );
        assert!(manifest.contains("legacy_name: api"), "{manifest}");
        let source_history = wiki.recent_checkpoints(10).unwrap();
        assert!(
            source_history
                .iter()
                .any(|checkpoint| checkpoint.summary.contains("rename-project"))
        );
        drop(source);

        let dst = TempDir::new().unwrap();
        copy_tree(&src.path().join("wiki"), &dst.path().join("wiki"));
        let rebuilt = Store::open(dst.path()).unwrap();
        let rebuilt_wiki = Wiki::new(dst.path(), rebuilt.writer.clone()).unwrap();
        let summary = rebuilt_wiki.reindex_all().await.unwrap();
        assert_eq!(summary.projects, 1);
        assert_eq!(summary.pages, 1);
        let restored_history = rebuilt_wiki.recent_checkpoints(10).unwrap();
        assert_eq!(
            restored_history
                .iter()
                .map(|checkpoint| &checkpoint.oid)
                .collect::<Vec<_>>(),
            source_history
                .iter()
                .map(|checkpoint| &checkpoint.oid)
                .collect::<Vec<_>>()
        );
        assert_eq!(
            rebuilt
                .reader
                .project_name_by_id(workspace, project)
                .await
                .unwrap()
                .as_deref(),
            Some("acme-platform-api")
        );
        let rebuilt_scope = rebuilt
            .reader
            .scope_row_by_ids(workspace, project)
            .await
            .unwrap()
            .unwrap();
        assert_eq!(
            rebuilt_scope.identity.as_deref(),
            Some("github.com/acme/platform/api")
        );
        assert_eq!(rebuilt_scope.identity_source.as_deref(), Some("git_remote"));
        assert_eq!(
            rebuilt_scope.canonical_name.as_deref(),
            Some("acme-platform-api")
        );
        assert_eq!(rebuilt_scope.legacy_name.as_deref(), Some("api"));
        assert!(
            rebuilt
                .reader
                .page_body_by_ids(workspace, project, "notes/history.md")
                .await
                .unwrap()
                .unwrap()
                .body
                .contains("history survives reindex")
        );
        for key in ["acme-platform-api", "api"] {
            assert_eq!(
                ai_memory_store::lookup_existing_scope(&rebuilt.reader, "default", key)
                    .await
                    .unwrap()
                    .project_id,
                project
            );
        }
        let (captured, resolution) = rebuilt
            .writer
            .resolve_project_by_identity(
                workspace,
                identity,
                ai_memory_core::repository_identity::IdentityStyle::Path,
                "another-checkout",
                Some("/other/api".into()),
                None,
                None,
            )
            .await
            .unwrap();
        assert_eq!(captured, project);
        assert_eq!(resolution, ai_memory_store::IdentityResolution::Matched);
        let count: i64 = rebuilt
            .reader
            .with_conn(|conn| {
                Ok(conn.query_row("SELECT COUNT(*) FROM projects", [], |row| row.get(0))?)
            })
            .await
            .unwrap();
        assert_eq!(count, 1, "capture must not create a second project UUID");
    }

    #[tokio::test]
    async fn reindex_rejects_project_coordinate_fields_that_do_not_match_identity() {
        let tmp = TempDir::new().unwrap();
        let store = Store::open(tmp.path()).unwrap();
        let wiki = Wiki::new(tmp.path(), store.writer.clone()).unwrap();
        let workspace = WorkspaceId::new();
        let project = ProjectId::new();
        let workspace_dir = tmp.path().join("wiki").join(workspace.to_string());
        let project_dir = workspace_dir.join(project.to_string());
        std::fs::create_dir_all(&project_dir).unwrap();
        std::fs::write(
            workspace_dir.join("_meta.md"),
            "---\nworkspace: default\ntype: Scope Manifest\n---\n",
        )
        .unwrap();
        std::fs::write(
            project_dir.join("_meta.md"),
            "---\nproject: acme-api\nidentity: github.com/acme/api\nidentity_source: git_remote\ncanonical_name: forged-api\nlegacy_name: api\ntype: Scope Manifest\n---\n",
        )
        .unwrap();

        let error = wiki.reindex_all().await.unwrap_err();
        assert!(
            error
                .to_string()
                .contains("coordinate keys do not match its identity"),
            "{error}"
        );
        assert!(
            store
                .reader
                .scope_row_by_ids(workspace, project)
                .await
                .unwrap()
                .is_none()
        );
    }

    #[tokio::test]
    async fn identity_manifest_without_derived_keys_reindexes_and_derives_them() {
        let src = TempDir::new().unwrap();
        let source = Store::open(src.path()).unwrap();
        let wiki = Wiki::new(src.path(), source.writer.clone())
            .unwrap()
            .with_store_reader(source.reader.clone());
        let workspace = source
            .writer
            .get_or_create_workspace("default")
            .await
            .unwrap();
        let (project, _) = source
            .writer
            .resolve_project_by_identity(
                workspace,
                ai_memory_core::repository_identity::RepositoryIdentity {
                    identity: "github.com/acme/api".into(),
                    source: ai_memory_core::repository_identity::IdentitySource::GitRemote,
                },
                ai_memory_core::repository_identity::IdentityStyle::HostPath,
                "api",
                None,
                None,
                None,
            )
            .await
            .unwrap();
        wiki.write_page(req(
            workspace,
            project,
            "notes/a.md",
            "identity history",
            serde_json::json!({}),
        ))
        .await
        .unwrap();
        let manifest_path = src
            .path()
            .join("wiki")
            .join(workspace.to_string())
            .join(project.to_string())
            .join("_meta.md");
        std::fs::write(
            &manifest_path,
            "---\nproject: api\nidentity: github.com/acme/api\nidentity_source: git_remote\ntype: Scope Manifest\n---\n",
        ).unwrap();
        drop(source);

        let dst = TempDir::new().unwrap();
        copy_tree(&src.path().join("wiki"), &dst.path().join("wiki"));
        let rebuilt = Store::open(dst.path()).unwrap();
        Wiki::new(dst.path(), rebuilt.writer.clone())
            .unwrap()
            .reindex_all()
            .await
            .unwrap();
        let scope = rebuilt
            .reader
            .scope_row_by_ids(workspace, project)
            .await
            .unwrap()
            .unwrap();
        assert_eq!(scope.canonical_name.as_deref(), Some("acme-api"));
        assert_eq!(scope.legacy_name.as_deref(), Some("api"));
    }

    #[tokio::test]
    async fn old_project_manifest_without_identity_still_reindexes() {
        let src = TempDir::new().unwrap();
        let source = Store::open(src.path()).unwrap();
        let wiki = Wiki::new(src.path(), source.writer.clone())
            .unwrap()
            .with_store_reader(source.reader.clone());
        let workspace = source
            .writer
            .get_or_create_workspace("legacy")
            .await
            .unwrap();
        let project = source
            .writer
            .get_or_create_project(workspace, "old-format", Some("/legacy".into()))
            .await
            .unwrap();
        wiki.write_page(req(
            workspace,
            project,
            "notes/legacy.md",
            "legacy manifest history",
            serde_json::json!({}),
        ))
        .await
        .unwrap();
        let manifest_path = src
            .path()
            .join("wiki")
            .join(workspace.to_string())
            .join(project.to_string())
            .join("_meta.md");
        std::fs::write(
            &manifest_path,
            "---\nproject: old-format\nrepo_path: /legacy\ntype: Scope Manifest\n---\n",
        )
        .unwrap();
        drop(source);

        let dst = TempDir::new().unwrap();
        copy_tree(&src.path().join("wiki"), &dst.path().join("wiki"));
        let rebuilt = Store::open(dst.path()).unwrap();
        Wiki::new(dst.path(), rebuilt.writer.clone())
            .unwrap()
            .reindex_all()
            .await
            .unwrap();
        let row = rebuilt
            .reader
            .scope_row_by_ids(workspace, project)
            .await
            .unwrap()
            .unwrap();
        assert_eq!(row.project_name, "old-format");
        assert_eq!(row.repo_path.as_deref(), Some("/legacy"));
        assert!(row.identity.is_none());
        assert!(row.identity_source.is_none());
        assert!(row.canonical_name.is_none());
        assert!(row.legacy_name.is_none());
    }

    #[tokio::test]
    async fn backfill_writes_manifest_for_empty_workspace() {
        let tmp = TempDir::new().unwrap();
        let store = Store::open(tmp.path()).unwrap();
        let ws = store
            .writer
            .get_or_create_workspace("empty-ws")
            .await
            .unwrap();
        let wiki = Wiki::new(tmp.path(), store.writer.clone())
            .unwrap()
            .with_store_reader(store.reader.clone());

        let written = wiki.backfill_scope_manifests().await.unwrap();

        assert_eq!(written, 1);
        let meta = std::fs::read_to_string(
            tmp.path()
                .join("wiki")
                .join(ws.to_string())
                .join("_meta.md"),
        )
        .unwrap();
        assert!(meta.contains("workspace: empty-ws"));
    }

    /// #643: a scope that first materializes *while the server is up* is
    /// self-describing from its first page, without waiting for the next
    /// startup backfill. The manifests must be byte-identical to the ones
    /// the backfill would have written, or every restart would rewrite them
    /// and churn the wiki's git history.
    #[tokio::test]
    async fn first_write_into_a_new_scope_writes_its_manifests() {
        let tmp = TempDir::new().unwrap();
        let store = Store::open(tmp.path()).unwrap();
        let wiki = Wiki::new(tmp.path(), store.writer.clone())
            .unwrap()
            .with_store_reader(store.reader.clone());

        // The scope appears after startup — no backfill has run for it.
        let ws = store.writer.get_or_create_workspace("acme").await.unwrap();
        let proj = store
            .writer
            .get_or_create_project(ws, "webapp", Some("/repo/webapp".into()))
            .await
            .unwrap();
        wiki.write_page(req(ws, proj, "notes/a.md", "alpha", serde_json::json!({})))
            .await
            .unwrap();

        let ws_dir = tmp.path().join("wiki").join(ws.to_string());
        let ws_meta = std::fs::read_to_string(ws_dir.join("_meta.md")).unwrap();
        assert!(ws_meta.contains("workspace: acme"), "{ws_meta}");
        let proj_meta =
            std::fs::read_to_string(ws_dir.join(proj.to_string()).join("_meta.md")).unwrap();
        assert!(proj_meta.contains("project: webapp"), "{proj_meta}");
        assert!(
            proj_meta.contains("repo_path: /repo/webapp"),
            "repo_path is carried, as the backfill carries it: {proj_meta}"
        );
        assert!(proj_meta.contains("type: Scope Manifest"), "{proj_meta}");

        assert_eq!(
            wiki.backfill_scope_manifests().await.unwrap(),
            0,
            "a later backfill finds nothing to write; the two emitters agree byte for byte"
        );
    }

    /// #643 end-to-end: stop the server inside the window the issue
    /// describes — a project created after startup, so no backfill has ever
    /// seen it — and `reindex` still rebuilds it from the wiki tree alone.
    /// Before the manifest was written with the first page, this aborted with
    /// a bare `No such file or directory (os error 2)`.
    #[tokio::test]
    async fn scope_created_after_startup_reindexes_without_a_restart() {
        let src = TempDir::new().unwrap();
        let s1 = Store::open(src.path()).unwrap();
        let w1 = Wiki::new(src.path(), s1.writer.clone())
            .unwrap()
            .with_store_reader(s1.reader.clone());
        // Startup backfill: the server has seen nothing yet, so it writes
        // nothing. The scope below is created afterwards, mid-run.
        assert_eq!(w1.backfill_scope_manifests().await.unwrap(), 0);

        let ws = s1.writer.get_or_create_workspace("acme").await.unwrap();
        let proj = s1
            .writer
            .get_or_create_project(ws, "webapp", None)
            .await
            .unwrap();
        w1.write_page(req(
            ws,
            proj,
            "notes/a.md",
            "alpha uniquetoken",
            serde_json::json!({}),
        ))
        .await
        .unwrap();
        drop(s1);

        // Fresh store, wiki tree only — the recovery the operator runs.
        let dst = TempDir::new().unwrap();
        let s2 = Store::open(dst.path()).unwrap();
        copy_tree(&src.path().join("wiki"), &dst.path().join("wiki"));
        let w2 = Wiki::new(dst.path(), s2.writer.clone()).unwrap();
        let summary = w2.reindex_all().await.unwrap();

        assert_eq!(summary.projects, 1);
        assert_eq!(summary.pages, 1);
        assert_eq!(
            s2.reader.workspace_name_by_id(ws).await.unwrap().as_deref(),
            Some("acme"),
            "workspace name recovered from the manifest written mid-run"
        );
        assert_eq!(
            s2.reader
                .project_name_by_id(ws, proj)
                .await
                .unwrap()
                .as_deref(),
            Some("webapp"),
        );
    }

    /// The watcher's reconcile pre-check runs outside the mutation guard, so
    /// it deliberately ensures store rows ONLY. Writing a manifest there
    /// could drop a file into a directory a concurrent project move is
    /// renaming away, and buys nothing: a directory it can see already got
    /// its manifest with its first page, or from the backfill.
    #[tokio::test]
    async fn reconcile_scope_check_does_not_write_manifests() {
        let tmp = TempDir::new().unwrap();
        let store = Store::open(tmp.path()).unwrap();
        let wiki = Wiki::new(tmp.path(), store.writer.clone())
            .unwrap()
            .with_store_reader(store.reader.clone());
        let ws = store.writer.get_or_create_workspace("acme").await.unwrap();
        let proj = store
            .writer
            .get_or_create_project(ws, "webapp", None)
            .await
            .unwrap();

        wiki.ensure_project_scope_rows(ws, proj).await.unwrap();

        let ws_dir = tmp.path().join("wiki").join(ws.to_string());
        assert!(!ws_dir.join("_meta.md").exists());
        assert!(!ws_dir.join(proj.to_string()).join("_meta.md").exists());
    }

    /// Post-audit regression: manifests are OKF-typed at the writer
    /// choke point, and a typeless manifest (the tug-of-war era, or a
    /// hand edit) is HEALED by the next backfill instead of reverting
    /// the migration's typing.
    #[tokio::test]
    async fn backfill_types_manifests_and_heals_typeless_ones() {
        let tmp = TempDir::new().unwrap();
        let store = Store::open(tmp.path()).unwrap();
        let ws = store.writer.get_or_create_workspace("w").await.unwrap();
        let wiki = Wiki::new(tmp.path(), store.writer.clone())
            .unwrap()
            .with_store_reader(store.reader.clone());

        wiki.backfill_scope_manifests().await.unwrap();
        let meta_path = tmp
            .path()
            .join("wiki")
            .join(ws.to_string())
            .join("_meta.md");
        let meta = std::fs::read_to_string(&meta_path).unwrap();
        assert!(meta.contains("type: Scope Manifest"), "{meta}");

        // Second backfill: byte-stable, no churn.
        assert_eq!(wiki.backfill_scope_manifests().await.unwrap(), 0);

        // A typeless manifest (pre-fix state) is healed, not preserved.
        std::fs::write(&meta_path, "---\nworkspace: w\n---\n").unwrap();
        assert_eq!(wiki.backfill_scope_manifests().await.unwrap(), 1);
        let healed = std::fs::read_to_string(&meta_path).unwrap();
        assert!(healed.contains("type: Scope Manifest"), "{healed}");
    }

    #[tokio::test]
    async fn reindex_names_a_missing_workspace_manifest() {
        let tmp = TempDir::new().unwrap();
        let store = Store::open(tmp.path()).unwrap();
        let wiki = Wiki::new(tmp.path(), store.writer.clone()).unwrap();
        let ws = WorkspaceId::new();
        let proj = ProjectId::new();
        let ws_dir = tmp.path().join("wiki").join(ws.to_string());
        let missing = ws_dir.join("_meta.md");
        std::fs::create_dir_all(ws_dir.join(proj.to_string())).unwrap();

        let err = wiki.reindex_all().await.unwrap_err();

        assert_eq!(
            err.to_string(),
            format!("scope manifest {} is missing", missing.display())
        );
    }

    #[tokio::test]
    async fn reindex_names_a_missing_project_manifest() {
        let tmp = TempDir::new().unwrap();
        let store = Store::open(tmp.path()).unwrap();
        let wiki = Wiki::new(tmp.path(), store.writer.clone()).unwrap();
        let ws = WorkspaceId::new();
        let proj = ProjectId::new();
        let ws_dir = tmp.path().join("wiki").join(ws.to_string());
        let proj_dir = ws_dir.join(proj.to_string());
        let missing = proj_dir.join("_meta.md");
        std::fs::create_dir_all(&proj_dir).unwrap();
        std::fs::write(
            ws_dir.join("_meta.md"),
            "---\nworkspace: acme\ntype: Scope Manifest\n---\n",
        )
        .unwrap();

        let err = wiki.reindex_all().await.unwrap_err();

        assert_eq!(
            err.to_string(),
            format!("scope manifest {} is missing", missing.display())
        );
    }

    #[cfg(any(unix, windows))]
    #[tokio::test]
    async fn reindex_rejects_symlinked_scope_manifest() {
        let tmp = TempDir::new().unwrap();
        let store = Store::open(tmp.path()).unwrap();
        let wiki = Wiki::new(tmp.path(), store.writer.clone()).unwrap();
        let ws = WorkspaceId::new();
        let proj = ProjectId::new();
        let ws_dir = tmp.path().join("wiki").join(ws.to_string());
        let proj_dir = ws_dir.join(proj.to_string());
        std::fs::create_dir_all(&proj_dir).unwrap();
        std::fs::write(ws_dir.join("_meta.md"), "---\nworkspace: acme\n---\n").unwrap();

        let outside = tmp.path().join("outside-meta.md");
        std::fs::write(&outside, "---\nproject: webapp\n---\n").unwrap();
        let link = proj_dir.join("_meta.md");
        if !create_test_symlink_file(&outside, &link) {
            return;
        }

        let err = wiki.reindex_all().await.unwrap_err();
        assert!(
            matches!(err, WikiError::Confinement { .. }),
            "reindex must reject symlinked manifests, got {err:#}"
        );
    }

    /// Frontmatter `entities:` round-trips through the write path and is
    /// normalised on the way into the index. A non-array value is a
    /// structural error; bad *items* are dropped, because entities are a
    /// ranking signal and one long hand-typed entry must not cost the page.
    #[test]
    fn parse_entities_normalises_and_rejects_non_arrays() {
        let path = PagePath::new("concepts/x.md").unwrap();

        assert!(
            parse_entities(&path, &serde_json::json!({}))
                .unwrap()
                .is_empty(),
            "absent key means no entities",
        );
        assert_eq!(
            parse_entities(
                &path,
                &serde_json::json!({"entities": ["SQLite", "  sqlite ", "Writer\nActor", 42]}),
            )
            .unwrap(),
            vec!["sqlite".to_string(), "writer actor".to_string()],
            "lowercased, whitespace-collapsed, de-duplicated, non-strings dropped",
        );
        assert!(
            parse_entities(
                &path,
                &serde_json::json!({"entities": ["ok", "x".repeat(200)]}),
            )
            .unwrap()
                == vec!["ok".to_string()],
            "over-long items are dropped, not fatal",
        );
        let err = parse_entities(&path, &serde_json::json!({"entities": "sqlite"}))
            .expect_err("a string instead of a list is a structural error");
        assert!(err.to_string().contains("non-array entities"), "{err}");
    }

    /// Entities are derived from `tags` too, so the index (and `as_of`)
    /// populate on real stores whose pages predate LLM entity extraction.
    #[test]
    fn parse_entities_derives_from_tags() {
        let path = PagePath::new("concepts/x.md").unwrap();

        // Tags alone populate entities — the common case on a mature store.
        assert_eq!(
            parse_entities(&path, &serde_json::json!({"tags": ["Storage", "SQLite"]})).unwrap(),
            vec!["storage".to_string(), "sqlite".to_string()],
            "tags become entities, normalised",
        );

        // Explicit entities come first (they win the cap), tags fill in,
        // and a tag duplicating an entity is de-duplicated.
        assert_eq!(
            parse_entities(
                &path,
                &serde_json::json!({"entities": ["FTS5"], "tags": ["fts5", "search"]}),
            )
            .unwrap(),
            vec!["fts5".to_string(), "search".to_string()],
            "explicit first, tags merged, duplicates dropped",
        );

        // A malformed tags list is lenient — it must never fail a write —
        // while a malformed entities list still errors.
        assert_eq!(
            parse_entities(
                &path,
                &serde_json::json!({"entities": ["ok"], "tags": "not-a-list"}),
            )
            .unwrap(),
            vec!["ok".to_string()],
            "non-array tags contribute nothing rather than erroring",
        );
    }

    /// Two projects in one workspace, one ended session in the first with a
    /// consolidated `sessions/<id>.md` page written through the wiki.
    async fn session_with_page(
        tmp: &TempDir,
    ) -> (
        Store,
        Wiki,
        WorkspaceId,
        ProjectId,
        ProjectId,
        SessionId,
        PagePath,
    ) {
        let (store, wiki, ws, src) = scoped(tmp).await;
        let dst = store
            .writer
            .get_or_create_project(ws, "target", None)
            .await
            .unwrap();
        let sid = SessionId::new();
        store
            .writer
            .begin_session(ai_memory_core::NewSession {
                occurred_at: None,
                id: sid,
                workspace_id: ws,
                project_id: src,
                agent_kind: ai_memory_core::AgentKind::ClaudeCode,
                cwd: Some("/repo/src".into()),
                actor_user: None,
            })
            .await
            .unwrap();
        store.writer.end_session(sid, None).await.unwrap();
        let path = PagePath::new(format!("sessions/{sid}.md")).unwrap();
        wiki.write_page(req(
            ws,
            src,
            path.as_str(),
            "consolidated session body",
            serde_json::json!({ "title": "Session" }),
        ))
        .await
        .unwrap();
        (store, wiki, ws, src, dst, sid, path)
    }

    #[tokio::test]
    async fn reindex_queued_after_purge_rechecks_session_tombstone() {
        let tmp = TempDir::new().unwrap();
        let (store, wiki, ws, proj, _, sid, path) = session_with_page(&tmp).await;
        let page_id = wiki.reindex_page(ws, proj, path.clone()).await.unwrap();
        store.writer.end_session(sid, Some(page_id)).await.unwrap();
        // The watcher's per-directory snapshot predates the purge.
        let snapshot = wiki.purged_sessions(ws, proj).await.unwrap();
        assert!(!snapshot.contains(&sid));
        let abs = wiki.abs_path(ws, proj, &path);
        let raw = std::fs::read(&abs).unwrap();
        let guard = wiki.mutation_lock.read().await;
        let purge = wiki.purge_session(ws, proj, sid, None, ai_memory_store::Compaction::Skip);
        tokio::pin!(purge);
        tokio::select! { biased;
            _ = &mut purge => panic!("purge should wait for the shared guard"),
            _ = std::future::ready(()) => {}
        }
        // A page already admitted by the stale snapshot queues behind the purge.
        let reindex = wiki.reindex_page(ws, proj, path.clone());
        tokio::pin!(reindex);
        tokio::select! { biased;
            _ = &mut reindex => panic!("reindex should wait behind queued purge"),
            _ = std::future::ready(()) => {}
        }
        // Force cleanup failure portably, as the owned-session purge test
        // does. Restore the readable leftover before the queued reindex runs.
        std::fs::remove_file(&abs).unwrap();
        std::fs::create_dir(&abs).unwrap();
        drop(guard);
        let outcome = purge.await.unwrap();
        assert_eq!(outcome.files_failed, vec![path.clone()]);
        std::fs::remove_dir(&abs).unwrap();
        std::fs::write(&abs, raw).unwrap();
        assert!(abs.is_file());
        assert!(
            store
                .reader
                .find_session_scope(sid)
                .await
                .unwrap()
                .is_none()
        );
        assert!(
            store
                .reader
                .search_pages("consolidated".into(), 10, None)
                .await
                .unwrap()
                .is_empty()
        );
        assert!(wiki.purged_sessions(ws, proj).await.unwrap().contains(&sid));
        let reindexed = reindex.await;
        let hits = store
            .reader
            .search_pages("consolidated".into(), 10, None)
            .await
            .unwrap();
        assert!(
            matches!(
                reindexed,
                Err(WikiError::Store(
                    ai_memory_store::StoreError::SessionPurged(_)
                ))
            ),
            "{reindexed:?}"
        );
        assert!(
            hits.is_empty(),
            "a reindex queued after purge resurrected the tombstoned session page"
        );
    }

    #[tokio::test]
    async fn purge_session_waits_for_in_flight_reindex_before_deleting_rows() {
        let tmp = TempDir::new().unwrap();
        let (store, wiki, ws, proj, _, sid, path) = session_with_page(&tmp).await;
        let page_id = wiki.reindex_page(ws, proj, path.clone()).await.unwrap();
        store.writer.end_session(sid, Some(page_id)).await.unwrap();

        // Model a watcher that has acquired the shared guard but has not
        // indexed its file yet. Poll the purge once, then fence the writer
        // queue: any SQL it submitted must finish before this command replies.
        let reader_guard = wiki.mutation_lock.read().await;
        let purge = wiki.purge_session(ws, proj, sid, None, ai_memory_store::Compaction::Skip);
        tokio::pin!(purge);
        tokio::select! {
            biased;
            result = &mut purge => panic!("purge bypassed an active reader: {result:?}"),
            () = std::future::ready(()) => {}
        }
        store
            .writer
            .get_or_create_workspace("queue-fence")
            .await
            .unwrap();
        assert!(
            store
                .reader
                .find_session_scope(sid)
                .await
                .unwrap()
                .is_some(),
            "purge must wait for the wiki guard before deleting SQL rows"
        );
        // Finish the already-admitted reindex without recursively locking.
        wiki.reindex_page_locked(ws, proj, path.clone())
            .await
            .unwrap();
        drop(reader_guard);
        let outcome = purge.await.unwrap();
        assert_eq!(outcome.files_deleted, vec![path.clone()]);
        assert!(outcome.files_failed.is_empty());
        assert!(
            store
                .reader
                .find_session_scope(sid)
                .await
                .unwrap()
                .is_none()
        );
        assert!(!wiki.abs_path(ws, proj, &path).exists());
        assert!(wiki.reindex_page(ws, proj, path).await.is_err());
        assert!(
            store
                .reader
                .search_pages("consolidated".into(), 10, None)
                .await
                .unwrap()
                .is_empty()
        );
    }

    /// The writer's half of the same claim. `purge_session` holds the
    /// exclusive guard across SQL and cleanup — proved by
    /// `purge_session_waits_for_in_flight_reindex_before_deleting_rows` — and
    /// `write_page` takes the shared one, so a write cannot install its file
    /// while a purge owns the guard and would otherwise delete it during
    /// cleanup. Removing the shared guard from `write_page` makes this fail.
    #[tokio::test]
    async fn page_write_cannot_land_while_the_purge_guard_is_held() {
        let tmp = TempDir::new().unwrap();
        let (store, wiki, ws, proj, _, _sid, _path) = session_with_page(&tmp).await;
        let target = PagePath::new("decisions/keep.md").unwrap();
        let abs = wiki.abs_path(ws, proj, &target);

        let purge_guard = wiki.mutation_lock.write().await;
        let write = wiki.write_page(req(
            ws,
            proj,
            target.as_str(),
            "kept body",
            serde_json::json!({ "title": "Keep" }),
        ));
        tokio::pin!(write);
        // A single poll would only prove the write did not finish in one
        // step, which is true even without the guard: `write_page` parks on
        // the writer queue before it touches disk. Give it real time instead.
        assert!(
            tokio::time::timeout(std::time::Duration::from_millis(250), &mut write)
                .await
                .is_err(),
            "the page write must not complete while a purge owns the guard"
        );
        assert!(
            !abs.exists(),
            "no page file may be installed while a purge owns the guard"
        );

        drop(purge_guard);
        write.await.unwrap();
        assert!(abs.exists(), "the write completes once the purge releases");
        assert!(
            !store
                .reader
                .search_pages("kept".into(), 10, None)
                .await
                .unwrap()
                .is_empty(),
            "disk and index agree after the guard is released"
        );
    }

    async fn owned_session_with_page(
        tmp: &TempDir,
    ) -> (
        Store,
        Wiki,
        WorkspaceId,
        ProjectId,
        UserId,
        SessionId,
        PagePath,
    ) {
        let (store, wiki, ws, proj) = scoped(tmp).await;
        let user = store
            .writer
            .create_human_user(
                ai_memory_core::NewUser {
                    username: "purge-owner".into(),
                    name: None,
                    email: None,
                },
                ai_memory_core::UserRole::User,
                None,
                false,
            )
            .await
            .unwrap();
        let sid = SessionId::new();
        store
            .writer
            .begin_session(ai_memory_core::NewSession {
                occurred_at: None,
                id: sid,
                workspace_id: ws,
                project_id: proj,
                agent_kind: ai_memory_core::AgentKind::Codex,
                cwd: None,
                actor_user: Some("user:purge-owner".into()),
            })
            .await
            .unwrap();
        let path = PagePath::new(format!("sessions/{sid}.md")).unwrap();
        let page = wiki
            .write_page(req(
                ws,
                proj,
                path.as_str(),
                "owned session body",
                serde_json::json!({"title":"Owned session"}),
            ))
            .await
            .unwrap();
        store.writer.end_session(sid, Some(page)).await.unwrap();
        (store, wiki, ws, proj, user, sid, path)
    }

    #[tokio::test]
    async fn owned_session_purge_authorization_failure_preserves_page_and_index() {
        use ai_memory_core::IdentityKey;
        let tmp = TempDir::new().unwrap();
        let (store, wiki, ws, proj, user, sid, path) = owned_session_with_page(&tmp).await;
        let abs = wiki.abs_path(ws, proj, &path);
        let before = std::fs::read(&abs).unwrap();
        assert!(matches!(
            wiki.purge_owned_session(
                ws,
                proj,
                sid,
                IdentityKey::User("foreign".into()),
                Some(user)
            )
            .await,
            Err(WikiError::Store(ai_memory_store::StoreError::NotFound(_)))
        ));
        store
            .writer
            .set_access_mode(proj, ai_memory_store::AccessMode::Restricted)
            .await
            .unwrap();
        assert!(matches!(
            wiki.purge_owned_session(
                ws,
                proj,
                sid,
                IdentityKey::User("purge-owner".into()),
                Some(user)
            )
            .await,
            Err(WikiError::Store(ai_memory_store::StoreError::Forbidden(_)))
        ));
        assert_eq!(std::fs::read(&abs).unwrap(), before);
        assert!(
            store
                .reader
                .find_session_scope(sid)
                .await
                .unwrap()
                .is_some()
        );
        assert!(
            !store
                .reader
                .search_pages("owned".into(), 10, None)
                .await
                .unwrap()
                .is_empty()
        );
        assert!(wiki.purged_sessions(ws, proj).await.unwrap().is_empty());
        // Removing the restriction provides a legitimate control for the same file.
        store
            .writer
            .set_access_mode(proj, ai_memory_store::AccessMode::Open)
            .await
            .unwrap();
        let outcome = wiki
            .purge_owned_session(
                ws,
                proj,
                sid,
                IdentityKey::User("purge-owner".into()),
                Some(user),
            )
            .await
            .unwrap();
        assert_eq!(outcome.files_deleted, vec![path]);
        assert!(!abs.exists());
    }

    #[tokio::test]
    async fn owned_session_purge_cleanup_failure_is_reported_and_tombstoned() {
        let tmp = TempDir::new().unwrap();
        let (store, wiki, ws, proj, user, sid, path) = owned_session_with_page(&tmp).await;
        let abs = wiki.abs_path(ws, proj, &path);
        let before = std::fs::read(&abs).unwrap();
        // A directory in place of a file forces cleanup failure on every platform,
        // including privileged test runners that ignore read-only permissions.
        std::fs::remove_file(&abs).unwrap();
        std::fs::create_dir(&abs).unwrap();
        let outcome = wiki
            .purge_owned_session(
                ws,
                proj,
                sid,
                ai_memory_core::IdentityKey::User("purge-owner".into()),
                Some(user),
            )
            .await
            .unwrap();
        assert_eq!(outcome.files_failed, vec![path.clone()]);
        assert!(outcome.files_deleted.is_empty());
        assert!(
            store
                .reader
                .find_session_scope(sid)
                .await
                .unwrap()
                .is_none()
        );
        assert!(wiki.purged_sessions(ws, proj).await.unwrap().contains(&sid));
        // Simulate the leftover file returning during recovery. Reindex must
        // honor the tombstone instead of resurrecting the deleted summary.
        std::fs::remove_dir(&abs).unwrap();
        std::fs::write(&abs, before).unwrap();
        let summary = wiki.reindex_all().await.unwrap();
        assert_eq!(summary.skipped_purged_sessions, 1);
        assert!(
            store
                .reader
                .search_pages("owned".into(), 10, None)
                .await
                .unwrap()
                .is_empty()
        );
    }

    #[tokio::test]
    async fn purge_session_store_failure_preserves_page_file() {
        let tmp = TempDir::new().unwrap();
        let (store, wiki, ws, proj, other, sid, path) = session_with_page(&tmp).await;
        let abs = wiki.abs_path(ws, proj, &path);
        let before = std::fs::read(&abs).unwrap();
        let result = wiki
            .purge_session(ws, other, sid, None, ai_memory_store::Compaction::Skip)
            .await;
        assert!(matches!(
            result,
            Err(WikiError::Store(ai_memory_store::StoreError::NotFound(_)))
        ));
        assert_eq!(std::fs::read(&abs).unwrap(), before);
        assert!(
            store
                .reader
                .find_session_scope(sid)
                .await
                .unwrap()
                .is_some()
        );
    }

    fn leftover_tempfiles(dir: &Path) -> Vec<String> {
        std::fs::read_dir(dir)
            .map(|rd| {
                rd.filter_map(Result::ok)
                    .map(|e| e.file_name().to_string_lossy().into_owned())
                    .filter(|n| n.starts_with(".ai-memory-tmp."))
                    .collect()
            })
            .unwrap_or_default()
    }

    #[tokio::test]
    async fn move_session_page_moves_file_and_rows() {
        let tmp = TempDir::new().unwrap();
        let (store, wiki, ws, src, dst, sid, path) = session_with_page(&tmp).await;

        let outcome = wiki
            .move_session_page(sid, (ws, src), (ws, dst), PagesMode::Move, None, None)
            .await
            .unwrap();
        assert_eq!(outcome.file, SessionPageFile::Moved);
        assert!(outcome.summary.session_moved);
        assert_eq!(outcome.summary.page_versions_moved, 1);

        assert!(
            !wiki.abs_path(ws, src, &path).exists(),
            "source file must be gone"
        );
        let moved = std::fs::read_to_string(wiki.abs_path(ws, dst, &path)).unwrap();
        assert!(moved.contains("consolidated session body"));
        assert_eq!(
            store.reader.session_project_ids(sid).await.unwrap(),
            Some((ws, dst))
        );
        assert!(
            store
                .reader
                .page_body_by_ids(ws, dst, path.as_str())
                .await
                .unwrap()
                .is_some(),
            "latest page row must now sit in the destination"
        );
        assert!(
            store
                .reader
                .page_body_by_ids(ws, src, path.as_str())
                .await
                .unwrap()
                .is_none()
        );
        // The moved file is byte-identical to what the store indexed, so the
        // watcher's follow-up reindex in the destination is a no-op.
        wiki.reindex_page(ws, dst, path.clone()).await.unwrap();
        assert_eq!(
            store
                .reader
                .page_body_by_ids(ws, dst, path.as_str())
                .await
                .unwrap()
                .unwrap()
                .body,
            "consolidated session body"
        );
    }

    #[tokio::test]
    async fn move_session_page_regenerate_removes_source_file() {
        let tmp = TempDir::new().unwrap();
        let (store, wiki, ws, src, dst, sid, path) = session_with_page(&tmp).await;

        let outcome = wiki
            .move_session_page(sid, (ws, src), (ws, dst), PagesMode::Regenerate, None, None)
            .await
            .unwrap();
        assert_eq!(outcome.file, SessionPageFile::Removed);
        assert_eq!(outcome.summary.pages_regenerated, 1);

        let src_abs = wiki.abs_path(ws, src, &path);
        assert!(!src_abs.exists(), "retired page file must not linger");
        assert!(!wiki.abs_path(ws, dst, &path).exists());
        assert!(
            leftover_tempfiles(src_abs.parent().unwrap()).is_empty(),
            "parked copy must be deleted after the store commit"
        );
        assert!(
            store
                .reader
                .page_body_by_ids(ws, src, path.as_str())
                .await
                .unwrap()
                .is_none(),
            "no latest version left in the source"
        );
        assert_eq!(
            store.reader.session_project_ids(sid).await.unwrap(),
            Some((ws, dst))
        );
    }

    #[tokio::test]
    async fn move_session_page_puts_file_back_when_store_refuses() {
        let tmp = TempDir::new().unwrap();
        let (store, wiki, ws, src, dst, sid, path) = session_with_page(&tmp).await;
        // A latest page row at the same path in the destination, without a
        // file, so the disk step succeeds and only the SQL step refuses.
        store
            .writer
            .upsert_page(NewPage {
                workspace_id: ws,
                project_id: dst,
                path: path.clone(),
                title: "taken".into(),
                body: "already here".into(),
                tier: Tier::Semantic,
                frontmatter_json: serde_json::json!({}),
                pinned: false,
                links: vec![],
                author_id: None,
                expires_at: None,
                entities: vec![],
                evidence: Vec::new(),
            })
            .await
            .unwrap();

        let err = wiki
            .move_session_page(sid, (ws, src), (ws, dst), PagesMode::Move, None, None)
            .await
            .unwrap_err();
        assert!(
            matches!(
                err,
                WikiError::Store(ai_memory_store::StoreError::PagePathTaken { .. })
            ),
            "unexpected error: {err}"
        );
        assert!(
            wiki.abs_path(ws, src, &path).exists(),
            "source file must be back after the store refused"
        );
        assert!(!wiki.abs_path(ws, dst, &path).exists());
        assert_eq!(
            store.reader.session_project_ids(sid).await.unwrap(),
            Some((ws, src))
        );
    }

    #[tokio::test]
    async fn move_session_page_refuses_existing_destination_file() {
        let tmp = TempDir::new().unwrap();
        let (store, wiki, ws, src, dst, sid, path) = session_with_page(&tmp).await;
        wiki.write_page(req(
            ws,
            dst,
            path.as_str(),
            "destination already has this page",
            serde_json::json!({}),
        ))
        .await
        .unwrap();

        let err = wiki
            .move_session_page(sid, (ws, src), (ws, dst), PagesMode::Move, None, None)
            .await
            .unwrap_err();
        assert!(
            matches!(err, WikiError::DestinationPageExists(_)),
            "unexpected error: {err}"
        );
        assert!(wiki.abs_path(ws, src, &path).exists());
        assert_eq!(
            store.reader.session_project_ids(sid).await.unwrap(),
            Some((ws, src)),
            "nothing may move when the destination file exists"
        );
    }

    #[tokio::test]
    async fn move_session_page_without_file_reports_absent() {
        let tmp = TempDir::new().unwrap();
        let (store, wiki, ws, src, dst, sid, path) = session_with_page(&tmp).await;
        std::fs::remove_file(wiki.abs_path(ws, src, &path)).unwrap();

        let outcome = wiki
            .move_session_page(sid, (ws, src), (ws, dst), PagesMode::Move, None, None)
            .await
            .unwrap();
        assert_eq!(outcome.file, SessionPageFile::Absent);
        // The rows still move even though the file was already gone.
        assert_eq!(outcome.summary.page_versions_moved, 1);
        assert_eq!(
            store.reader.session_project_ids(sid).await.unwrap(),
            Some((ws, dst))
        );
    }

    #[tokio::test]
    async fn write_page_and_apply_batch_refuse_git_reserved_and_non_portable_paths() {
        let tmp = TempDir::new().unwrap();
        let (_store, wiki, ws, proj) = scoped(&tmp).await;

        for bad in [
            "CON.md",
            "notes/aux.md",
            ".git",
            ".git/config",
            "notes/.git",
            "notes/.git/sub.md",
            "notes/.GIT/sub.md",
            "notes/git~1",
            "notes/git~1/foo.md",
            "notes/GIT~2/bar.md",
        ] {
            let bad_path = PagePath::new(bad).unwrap();
            let write_err = wiki
                .write_page(req(
                    ws,
                    proj,
                    bad_path.as_str(),
                    "content",
                    serde_json::json!({}),
                ))
                .await
                .unwrap_err();
            assert!(
                matches!(
                    write_err,
                    WikiError::Memory(ai_memory_core::MemoryError::InvalidPagePath(_))
                ),
                "write_page should refuse {bad:?}, got: {write_err}"
            );

            let batch_err = wiki
                .apply_batch(vec![req(
                    ws,
                    proj,
                    bad_path.as_str(),
                    "content",
                    serde_json::json!({}),
                )])
                .await
                .unwrap_err();
            assert!(
                matches!(
                    batch_err,
                    WikiError::Memory(ai_memory_core::MemoryError::InvalidPagePath(_))
                ),
                "apply_batch should refuse {bad:?}, got: {batch_err}"
            );

            assert!(
                !wiki.abs_path(ws, proj, &bad_path).exists(),
                "file for {bad:?} must not be written to disk"
            );
        }
    }
}