memstead_mcp/

filesystem_server.rs

//! filesystem-mem MCP server — parallel module to [`crate::server`].
//!
//! Boots when `memstead-mcp/src/main.rs` runs without the `mem-repo`
//! feature against a `.memstead/workspace.toml` workspace that carries
//! only folder + archive mounts (no `mem-repo/.git/`). Wraps the
//! unified [`memstead_base::Engine`] behind the same rmcp ServerHandler
//! shape the mem-repo `McpServer` uses, but ports only the subset
//! of tools that make sense in a single-mem history-free context.
//!
//! Per-mutation provenance lands in `.memstead/changes.jsonl` (the
//! filesystem-mem analogue of the commit-body trailer the
//! mem-repo server writes).

use std::path::PathBuf;
use std::sync::{Arc, Mutex, OnceLock};

use rmcp::handler::server::wrapper::Parameters;
use rmcp::model::{
    CallToolRequestParams, CallToolResult, ContentBlock, InitializeRequestParams, InitializeResult,
    ListToolsResult, PaginatedRequestParams, Tool,
};
use rmcp::service::RequestContext;
use rmcp::{ErrorData as McpError, RoleServer, ServerHandler, tool, tool_handler, tool_router};

use indexmap::IndexMap;

use memstead_base::EntityId;
use memstead_base::ops::SearchScope;
use memstead_base::render::{render_entity_markdown, render_search_markdown};
use memstead_base::vcs::{Actor, ClientId};
use memstead_base::{
    BootError, CreateEntityArgs, DeleteEntityArgs, Engine, EngineError, RelateAction,
    RelateEntityArgs, RenameEntityArgs, UpdateEntityArgs,
};
use std::path::Path;

use crate::tools::admin::{ChangesSinceParams, DiffParams, HealthParams};
use crate::tools::graph::{EntityParams, OverviewParams, SchemaParams, SearchParams};
use crate::tools::mutation::{
    CheckParams, CreateParams, DeleteParams, RelateParams, RenameParams, UpdateParams,
};

/// MCP server backed by the unified [`memstead_base::Engine`].
///
/// Constructed via [`Self::from_workspace_root`].
#[derive(Clone)]
pub struct FilesystemMcpServer {
    /// Persistent unified engine. Mutations invalidate its memo
    /// caches via the engine's own hooks; reads see fresh state on
    /// every lock without needing a re-init from disk.
    engine: Arc<Mutex<Engine>>,
    /// Workspace root captured at construction time. Used by
    /// `memstead_changes_since` (which still reads JSONL directly off
    /// disk) — the unified engine does not expose a workspace_root
    /// accessor because mounts can be heterogeneous.
    workspace_root: PathBuf,
    /// Captured `clientInfo` from the initialize handshake. Used to
    /// stamp the changelog `client` field on every mutation. Same
    /// `OnceLock` shape as `crate::server::McpServer::client`.
    client: Arc<OnceLock<ClientId>>,
}

impl FilesystemMcpServer {
    /// Construct from a workspace root. Boots the unified
    /// [`Engine`] via [`Engine::from_workspace_root`] (lean path —
    /// folder + archive backends only). The error envelope wraps
    /// every layer (layout dispatch, store load, backend
    /// instantiation, engine construction) under one [`BootError`].
    ///
    /// Production callers (main.rs, every test fixture) reach the
    /// server through this constructor directly.
    pub fn from_workspace_root(workspace_root: &Path) -> Result<Self, BootError> {
        let workspace_root = workspace_root.to_path_buf();
        let engine = Engine::from_workspace_root(&workspace_root)?;
        Ok(Self {
            engine: Arc::new(Mutex::new(engine)),
            workspace_root,
            client: Arc::new(OnceLock::new()),
        })
    }

    /// Construct directly from a pre-built [`Engine`] — e.g. a sealed
    /// read-only archive mount stood up by an embedding service. `workspace_root`
    /// is consulted only by `memstead_changes_since` (which reads JSONL off
    /// disk); surfaces that do not expose that tool may pass any path.
    pub fn from_engine(engine: Engine, workspace_root: PathBuf) -> Self {
        Self {
            engine: Arc::new(Mutex::new(engine)),
            workspace_root,
            client: Arc::new(OnceLock::new()),
        }
    }

    /// Export the server's single mem as `.mem` archive bytes. Used by
    /// embedding services (the session server) to hand a visitor a
    /// self-describing copy of the mem their agent built. The server's
    /// engine carries exactly one mem (filesystem / session mems are
    /// single-mem by design); this exports it.
    pub fn export_mem_to_bytes(&self) -> Result<Vec<u8>, memstead_base::EngineError> {
        let engine = self
            .engine
            .lock()
            .expect("filesystem MCP engine mutex poisoned");
        let mem = engine
            .mem_names()
            .into_iter()
            .next()
            .map(String::from)
            .ok_or_else(|| {
                memstead_base::EngineError::InvalidInput("no mem to export".to_string())
            })?;
        engine.export_mem_to_bytes(&mem)
    }

    /// Count of real (non-stub) entities across the server's mem. Used
    /// by embedding services (the session server) to enforce a
    /// per-session resource cap before admitting a create.
    pub fn entity_count(&self) -> usize {
        self.engine
            .lock()
            .expect("filesystem MCP engine mutex poisoned")
            .status()
            .entity_count
    }

    /// Run a read closure against the locked engine. The escape hatch for
    /// embedding services that need engine reads the tool surface does not
    /// expose — e.g. the session server's live graph projection and its
    /// change-event subscription. Keeps the engine itself private; callers
    /// get a borrow only for the duration of `f`.
    pub fn with_engine<R>(&self, f: impl FnOnce(&Engine) -> R) -> R {
        let engine = self
            .engine
            .lock()
            .expect("filesystem MCP engine mutex poisoned");
        f(&engine)
    }

    fn actor_and_client(&self) -> (Actor, Option<ClientId>) {
        match self.client.get() {
            Some(c) => (Actor::Agent, Some(c.clone())),
            None => (Actor::Agent, None),
        }
    }
}

/// Build a typed tool-error envelope. The text channel is
/// `ERROR [<CODE>]: <message>` (consumers reading only
/// `result.content[0].text` recover the code with one regex) and the
/// `structured_content` channel carries `{code, message}` so agents
/// branching on the structured shape get the typed code without parsing
/// text. Mirror of `crate::error_envelope::tool_error_with_payload`'s
/// payload-less shape — the per-flavour symmetry is what makes the
/// wire-byte contract uniform across lean and full. Pre-fix the text
/// channel emitted a JSON-stringified `{code, message}` payload; that
/// form parsed for machine consumers but missed the documented
/// prefix-form contract.
fn tool_error(code: &str, message: &str) -> CallToolResult {
    tool_error_with_details(code, message, None)
}

/// Same as [`tool_error`] but additionally embeds a structured `details`
/// payload under `structured_content.details`. Text channel format is
/// identical (`ERROR [<CODE>]: <message>`); recovery payloads (current
/// hash, declared sections, referrer list) live exclusively on the
/// structured channel.
fn tool_error_with_details(
    code: &str,
    message: &str,
    details: Option<serde_json::Value>,
) -> CallToolResult {
    let payload = match details {
        Some(d) => serde_json::json!({ "code": code, "message": message, "details": d }),
        None => serde_json::json!({ "code": code, "message": message }),
    };
    let text = format!("ERROR [{code}]: {message}");
    let mut result = CallToolResult::error(vec![ContentBlock::text(text)]);
    result.structured_content = Some(payload);
    result
}

fn md_response(markdown: String) -> CallToolResult {
    CallToolResult::success(vec![ContentBlock::text(markdown)])
}

/// Pair rendered markdown on the text channel with a structured
/// envelope on `structured_content`:
/// tools whose response has a canonical human-readable form (entity,
/// search) ship the markdown to terminal/inline consumers and the
/// typed JSON to branching agents in one call.
fn md_with_structured(markdown: String, structured: serde_json::Value) -> CallToolResult {
    let mut result = CallToolResult::success(vec![ContentBlock::text(markdown)]);
    result.structured_content = Some(structured);
    result
}

fn json_response<T: serde::Serialize>(data: &T) -> CallToolResult {
    let value = serde_json::to_value(data).unwrap_or(serde_json::Value::Null);
    let text = serde_json::to_string_pretty(&value).unwrap_or_default();
    let mut result = CallToolResult::success(vec![ContentBlock::text(text)]);
    result.structured_content = Some(value);
    result
}

/// Whether the named mem's storage is durable (persists past restart /
/// session-TTL eviction), derived from its mount's `MountStorage` kind.
/// On the ephemeral in-memory sketch this returns `false` — the per-write
/// `durable` echo on every mutation response is how an agent learns its
/// `commit_sha` denotes nothing durable. Defaults to `false` for an
/// unresolvable mem: the engine never claims a durability it can't vouch
/// for.
fn mem_is_durable(engine: &memstead_base::Engine, mem: &str) -> bool {
    engine
        .mounts()
        .iter()
        .find(|m| m.mem == mem)
        .map(|m| m.storage.is_durable())
        .unwrap_or(false)
}

/// Refuse params the filesystem-mem MCP surface does not honour rather
/// than silently dropping them (Plan 03, Part B). Each `(name, meaningful)`
/// pair flags a param this surface hardwires off; `meaningful` is true when
/// the caller passed it with an effect they expect (a non-empty map/list, or
/// `dry_run: true`). When any such param was meaningfully supplied the call
/// refuses UP FRONT — before any mutation — with `UNSUPPORTED_PARAM` naming
/// every dropped param in `details.params`, so an agent can never believe a
/// no-op succeeded (the worst case being `dry_run: true`, which would
/// otherwise commit a real write the agent thought was a preview). A
/// defaulted-empty / absent / `false` param is left alone — the caller
/// intended no effect, so the call proceeds unchanged (backward-compatible).
/// Returns `None` when nothing meaningful was dropped.
/// Resolve a per-call `role` parameter (agent-trust plan 13) on the
/// lean flavour. No session default here (the lean binary carries no
/// `--role`); absent records unspecified. Unknown values refuse typed
/// with the declarable vocabulary named — same contract as the full
/// flavour.
fn resolve_role_lean(raw: Option<&str>) -> Result<memstead_base::vcs::Role, Box<CallToolResult>> {
    match raw {
        None => Ok(memstead_base::vcs::Role::Unspecified),
        Some(s) => memstead_base::vcs::Role::from_wire(s).ok_or_else(|| {
            let msg = format!(
                "unknown role {s:?} — declarable roles: {}",
                memstead_base::vcs::Role::DECLARABLE.join(", ")
            );
            Box::new(tool_error_with_details(
                "INVALID_ROLE",
                &msg,
                Some(serde_json::json!({
                    "role": s,
                    "allowed": memstead_base::vcs::Role::DECLARABLE,
                })),
            ))
        }),
    }
}

fn reject_unsupported_params(params: &[(&str, bool)]) -> Option<CallToolResult> {
    let dropped: Vec<&str> = params
        .iter()
        .filter_map(|(name, meaningful)| meaningful.then_some(*name))
        .collect();
    if dropped.is_empty() {
        return None;
    }
    let msg = format!(
        "the filesystem-mem surface does not implement: {}. These params were \
         refused, not silently ignored — pass them only to the unified engine \
         (mem-repo MCP / CLI), or omit them.",
        dropped.join(", ")
    );
    Some(tool_error_with_details(
        "UNSUPPORTED_PARAM",
        &msg,
        Some(serde_json::json!({ "params": dropped })),
    ))
}

/// Map an [`EngineError`] to an MCP error envelope. Codes match the
/// mem-repo error-code vocabulary (`HASH_MISMATCH`, `ENTITY_NOT_FOUND`,
/// `ENTITY_ALREADY_EXISTS`, etc.) so agents that handle mem-repo
/// errors get the same shape here.
///
/// Variants that should never trip on a single-mem filesystem-mem
/// boot path (`DuplicateMem`, `UnknownMem`, `ReadOnlyMount`) still
/// fall into a generic `INTERNAL` envelope so the wire shape is total —
/// a future bug that produced one of those wouldn't crash the handler.
/// Schema-resolution failures (`SchemaNotFound`, `SchemaResolverInit`)
/// surface as their own typed codes via [`EngineError::code()`] so
/// callers see the same wire contract here as on the mem-repo server.
fn engine_op_error(err: EngineError) -> CallToolResult {
    // Pre-compute the canonical Display string. Variants that take the
    // engine's Display rendering verbatim use this — variants that build
    // their own customised message (e.g. stub-aware `HashMismatch`) keep
    // doing so in-arm.
    let display = err.to_string();
    match err {
        EngineError::UnknownType {
            name,
            schema_ref,
            declared,
            suggestion,
        } => {
            let hint = suggestion
                .as_deref()
                .map(|s| format!(". Did you mean '{s}'?"))
                .unwrap_or_default();
            tool_error(
                "UNKNOWN_ENTITY_TYPE",
                &format!(
                    "unknown entity type '{name}' in schema '{schema_ref}'. \
                     Declared types: [{}]{hint}",
                    declared.join(", ")
                ),
            )
        }
        EngineError::InvalidTitle(slug_err) => {
            use memstead_base::SlugError;
            let reason = slug_err.reason();
            let details = match &slug_err {
                SlugError::IdTooLong { input, length, max } => serde_json::json!({
                    "reason": reason,
                    "input": input,
                    "length": length,
                    "max": max,
                }),
                SlugError::TitleEmpty { input } => serde_json::json!({
                    "reason": reason,
                    "input": input,
                }),
                SlugError::TitleHasControlChars {
                    input,
                    control_chars,
                    proposed_slug,
                } => {
                    let control_chars_str: Vec<String> = control_chars
                        .iter()
                        .map(|c| c.escape_default().to_string())
                        .collect();
                    serde_json::json!({
                        "reason": reason,
                        "input": input,
                        "control_chars": control_chars_str,
                        "proposed_slug": proposed_slug,
                    })
                }
            };
            tool_error_with_details(
                "INVALID_TITLE",
                &format!("title is invalid: {slug_err}"),
                Some(details),
            )
        }
        e @ EngineError::AlreadyExists { .. } => tool_error_with_details(
            "ENTITY_ALREADY_EXISTS",
            // Display names the occupying title; ship the structured
            // payload too so the lean server matches the full wire.
            &e.to_string(),
            Some(e.details()),
        ),
        // Block-tier declared-constraint refusals — code and recovery
        // payload come from the error itself so the lean server ships
        // the same wire contract as the full server.
        e @ (EngineError::ConstraintUnsatisfied { .. }
        | EngineError::RequiredOutgoingUnsatisfied { .. }
        | EngineError::SectionFormatRefused { .. }) => {
            tool_error_with_details(e.code(), &display, Some(e.details()))
        }
        EngineError::NotFound { id } => {
            tool_error("ENTITY_NOT_FOUND", &format!("entity not found: {id}"))
        }
        EngineError::HashMismatch {
            id,
            current,
            is_stub,
        } => {
            // Stub-aware message — pre-fix code printed `current is `
            // with an empty trailing value when the entity was a stub
            // and misdirected toward hash-recovery. Surface
            // `details.is_stub` and a corrective-action message
            // ("pass expected_hash: \"\"") for stubs; the prior
            // contract holds for real entities.
            let message = if is_stub {
                format!(
                    "hash mismatch for {id} — entity is a stub (no content_hash); pass expected_hash: \"\" to operate on stubs"
                )
            } else {
                format!("hash mismatch for {id}: current is {current}")
            };
            let payload = serde_json::json!({
                "code": "HASH_MISMATCH",
                "message": message.clone(),
                "details": {
                    "id": id,
                    "current": current,
                    "is_stub": is_stub,
                },
            });
            // Same text-channel format as `tool_error_with_payload`:
            // `ERROR [<CODE>]: <message>`. Pre-Item-01 this site emitted
            // a JSON-stringified payload on the text channel.
            let text = format!("ERROR [HASH_MISMATCH]: {message}");
            let mut result = CallToolResult::error(vec![ContentBlock::text(text)]);
            result.structured_content = Some(payload);
            result
        }
        EngineError::HasIncomingRefs { id, referrers } => {
            let referrers_json: Vec<_> = referrers
                .iter()
                .map(|r| {
                    serde_json::json!({
                        "from_id": r.from_id,
                        "rel_types": r.rel_types,
                        "mem": r.mem,
                        "capability": "write",
                    })
                })
                .collect();
            let message = display;
            let payload = serde_json::json!({
                "code": "HAS_INCOMING_REFS",
                "message": message.clone(),
                "details": { "id": id, "referrers": referrers_json },
            });
            let text = format!("ERROR [HAS_INCOMING_REFS]: {message}");
            let mut result = CallToolResult::error(vec![ContentBlock::text(text)]);
            result.structured_content = Some(payload);
            result
        }
        EngineError::MemHasIncomingRefs { mem, referrers } => {
            // Single-mem filesystem boot path never produces
            // MemHasIncomingRefs in practice — mem-delete is a
            // full-only operation. The arm is here for exhaustiveness;
            // the envelope shape matches the full-side mapping so
            // wire-byte parity holds if the filesystem flavour ever
            // gains a mem-delete surface.
            let referrers_json: Vec<_> = referrers
                .iter()
                .map(|r| {
                    serde_json::json!({
                        "from_id": r.from_id,
                        "rel_types": r.rel_types,
                        "mem": r.mem,
                    })
                })
                .collect();
            let message = display;
            let payload = serde_json::json!({
                "code": "MEM_HAS_INCOMING_REFS",
                "message": message.clone(),
                "details": { "mem": mem, "referrers": referrers_json },
            });
            let text = format!("ERROR [MEM_HAS_INCOMING_REFS]: {message}");
            let mut result = CallToolResult::error(vec![ContentBlock::text(text)]);
            result.structured_content = Some(payload);
            result
        }
        EngineError::CrossMemLinkNotAllowed { from_mem, to_mem } => tool_error(
            "CROSS_MEM_LINK_NOT_ALLOWED",
            &format!(
                "cross-mem link from `{from_mem}` to `{to_mem}` is not allowed by the workspace `[cross_mem_links]` policy"
            ),
        ),
        EngineError::CrossMemTargetNotFound {
            target_id,
            target_mem,
        } => tool_error(
            "CROSS_MEM_TARGET_NOT_FOUND",
            &format!(
                "cross-mem target `{target_id}` is absent in read-only mem `{target_mem}` — auto-stub is unavailable across the read-only boundary"
            ),
        ),
        EngineError::CrossMemEdgeNotDeclared {
            source_schema,
            target_schema,
            rel_type,
            from_id,
            to_id,
        } => {
            let message = display;
            let payload = serde_json::json!({
                "code": "CROSS_MEM_EDGE_NOT_DECLARED",
                "message": message.clone(),
                "details": {
                    "source_schema": source_schema,
                    "target_schema": target_schema,
                    "rel_type": rel_type,
                    "from_id": from_id,
                    "to_id": to_id,
                },
            });
            let text = format!("ERROR [CROSS_MEM_EDGE_NOT_DECLARED]: {message}");
            let mut result = CallToolResult::error(vec![ContentBlock::text(text)]);
            result.structured_content = Some(payload);
            result
        }
        EngineError::RepairNotNeeded { id, recovery } => {
            let message = display;
            let payload = serde_json::json!({
                "code": "REPAIR_NOT_NEEDED",
                "message": message.clone(),
                "details": { "id": id, "recovery": recovery },
            });
            let text = format!("ERROR [REPAIR_NOT_NEEDED]: {message}");
            let mut result = CallToolResult::error(vec![ContentBlock::text(text)]);
            result.structured_content = Some(payload);
            result
        }
        EngineError::RenameNoOp { id, new_title } => tool_error(
            "RENAME_NO_OP",
            &format!(
                "rename would not change the id of {id} — new title {new_title:?} produces the same slug"
            ),
        ),
        EngineError::WikiLinkWithoutRelation { from_id, missing } => {
            let message = display;
            let payload = serde_json::json!({
                "code": "WIKILINK_WITHOUT_RELATION",
                "message": message.clone(),
                "details": {
                    "from_id": from_id,
                    "missing": missing,
                },
            });
            let text = format!("ERROR [WIKILINK_WITHOUT_RELATION]: {message}");
            let mut result = CallToolResult::error(vec![ContentBlock::text(text)]);
            result.structured_content = Some(payload);
            result
        }
        EngineError::RelationHasBodyLinks {
            from_id,
            to_id,
            rel_type,
            body_links,
        } => {
            let message = display;
            let payload = serde_json::json!({
                "code": "RELATION_HAS_BODY_LINKS",
                "message": message.clone(),
                "details": {
                    "from_id": from_id,
                    "to_id": to_id,
                    "rel_type": rel_type,
                    "body_links": body_links,
                },
            });
            let text = format!("ERROR [RELATION_HAS_BODY_LINKS]: {message}");
            let mut result = CallToolResult::error(vec![ContentBlock::text(text)]);
            result.structured_content = Some(payload);
            result
        }
        EngineError::RenamePartialFailure {
            committed_mems,
            failed_mem,
            failure_cause,
        } => {
            let message = format!(
                "rename partial-failure: mem `{failed_mem}` aborted with cause {failure_cause:?} after {committed_mems:?} already committed — reload and retry, or reconcile manually"
            );
            let payload = serde_json::json!({
                "code": "RENAME_PARTIAL_FAILURE",
                "message": message.clone(),
                "details": {
                    "committed_mems": committed_mems,
                    "failed_mem": failed_mem,
                    "failure_cause": failure_cause,
                },
            });
            let text = format!("ERROR [RENAME_PARTIAL_FAILURE]: {message}");
            let mut result = CallToolResult::error(vec![ContentBlock::text(text)]);
            result.structured_content = Some(payload);
            result
        }
        EngineError::RenameBlockedByCrossMemPolicy {
            ref from_mem,
            ref blocked_referrers,
        } => {
            let message = err.to_string();
            let entries: Vec<_> = blocked_referrers
                .iter()
                .map(|r| {
                    serde_json::json!({
                        "from_mem": r.from_mem,
                        "to_mem": r.to_mem,
                        "count": r.count,
                    })
                })
                .collect();
            let payload = serde_json::json!({
                "code": "RENAME_BLOCKED_BY_CROSS_MEM_POLICY",
                "message": message.clone(),
                "details": {
                    "from_mem": from_mem,
                    "blocked_referrers": entries,
                },
            });
            let text = format!("ERROR [RENAME_BLOCKED_BY_CROSS_MEM_POLICY]: {message}");
            let mut result = CallToolResult::error(vec![ContentBlock::text(text)]);
            result.structured_content = Some(payload);
            result
        }
        EngineError::StubCannotRelate { id } => {
            let message = format!(
                "source entity {id} is a stub — promote it to a real entity via memstead_create first"
            );
            let payload = serde_json::json!({
                "code": "STUB_CANNOT_RELATE",
                "message": message.clone(),
                "details": { "id": id },
            });
            let text = format!("ERROR [STUB_CANNOT_RELATE]: {message}");
            let mut result = CallToolResult::error(vec![ContentBlock::text(text)]);
            result.structured_content = Some(payload);
            result
        }
        EngineError::StubNotUpdatable { id } => {
            let message = format!(
                "entity {id} is a stub — promote it to a real entity via memstead_create first"
            );
            let payload = serde_json::json!({
                "code": "STUB_NOT_UPDATABLE",
                "message": message.clone(),
                "details": { "id": id },
            });
            let text = format!("ERROR [STUB_NOT_UPDATABLE]: {message}");
            let mut result = CallToolResult::error(vec![ContentBlock::text(text)]);
            result.structured_content = Some(payload);
            result
        }
        EngineError::StubNotRenamable { id } => {
            let message = format!(
                "entity {id} is a stub — promote it to a real entity via memstead_create before renaming"
            );
            let payload = serde_json::json!({
                "code": "STUB_NOT_RENAMABLE",
                "message": message.clone(),
                "details": { "id": id },
            });
            let text = format!("ERROR [STUB_NOT_RENAMABLE]: {message}");
            let mut result = CallToolResult::error(vec![ContentBlock::text(text)]);
            result.structured_content = Some(payload);
            result
        }
        EngineError::InvalidEntityId { id, reason } => {
            let message = format!("entity id '{id}' is malformed: {reason}");
            tool_error_with_details(
                "INVALID_ENTITY_ID",
                &message,
                Some(serde_json::json!({ "id": id, "reason": reason })),
            )
        }
        EngineError::InvalidWikiLinkTarget {
            raw,
            suggested,
            section,
            link_source,
            reason,
        } => {
            let message = format!(
                "body wiki-link target '{raw}' in section '{section}' is not slug-form: {reason}"
            );
            tool_error_with_details(
                "INVALID_WIKI_LINK_TARGET",
                &message,
                Some(serde_json::json!({
                    "raw": raw,
                    "suggested": suggested,
                    "section": section,
                    "source": link_source,
                    "reason": reason,
                })),
            )
        }
        EngineError::InvalidWikiLinkMem {
            raw,
            section,
            reason,
        } => {
            let message = format!(
                "body wiki-link mem prefix '{raw}' in section '{section}' is not a valid mem name: {reason}"
            );
            tool_error_with_details(
                "INVALID_MEM_NAME",
                &message,
                Some(serde_json::json!({
                    "raw": raw,
                    "section": section,
                    "reason": reason,
                })),
            )
        }
        EngineError::ConflictingSectionModes { section, modes } => {
            let message =
                format!("section {section:?} appears in multiple mutation modes: {modes:?}");
            tool_error_with_details(
                "CONFLICTING_SECTION_MODES",
                &message,
                Some(serde_json::json!({ "section": section, "modes": modes })),
            )
        }
        EngineError::RelationshipCycle {
            rel_type,
            from,
            to,
            existing_path,
            path_truncated,
        } => {
            let existing_path_json: Vec<String> =
                existing_path.iter().map(|id| id.to_string()).collect();
            let message = format!(
                "creating edge {rel_type} from '{from}' to '{to}' would close a cycle in the {rel_type} subgraph"
            );
            tool_error_with_details(
                "RELATIONSHIP_CYCLE",
                &message,
                Some(serde_json::json!({
                    "rel_type": rel_type,
                    "from": from.to_string(),
                    "to": to.to_string(),
                    "existing_path": existing_path_json,
                    "path_truncated": path_truncated,
                })),
            )
        }
        EngineError::SetAndUnsetConflict { keys } => {
            let message = format!("metadata keys appear in both set and unset: {keys:?}");
            tool_error_with_details(
                "SET_AND_UNSET_CONFLICT",
                &message,
                Some(serde_json::json!({ "keys": keys })),
            )
        }
        EngineError::RequiredFieldUnset {
            field,
            entity_type,
            field_description,
            enum_values,
            type_write_rules,
            on_create,
            missing,
        } => {
            // Path-aware wording — create path renders "not provided"
            // (caller never supplied the field), update path renders
            // "cannot unset" (caller asked to remove a required field).
            // The typed code stays `REQUIRED_FIELD_UNSET` on both
            // paths so code-key consumers branch unchanged.
            let message = if on_create {
                format!(
                    "required metadata field '{field}' not provided — type '{entity_type}' declares the field as required and has no default for it"
                )
            } else {
                format!("cannot unset required field '{field}' for type '{entity_type}'")
            };
            // `details.missing[]` carries every required-no-default
            // field unset on the create path.
            let missing_json: Vec<_> = missing
                .iter()
                .map(|m| {
                    serde_json::json!({
                        "field": m.key,
                        "description": m.description,
                        "enum_values": m.enum_values,
                        "write_rules": type_write_rules,
                    })
                })
                .collect();
            tool_error_with_details(
                "REQUIRED_FIELD_UNSET",
                &message,
                Some(serde_json::json!({
                    "field": field,
                    "entity_type": entity_type,
                    "field_description": field_description,
                    "enum_values": enum_values,
                    "type_write_rules": type_write_rules,
                    "missing": missing_json,
                })),
            )
        }
        EngineError::MissingRequiredSection {
            entity_type,
            missing_count,
            sections,
            type_guidance,
        } => {
            let message =
                format!("missing {missing_count} required section(s) for type '{entity_type}'");
            let sections_json: Vec<_> = sections
                .iter()
                .map(|s| {
                    serde_json::json!({
                        "entity_type": s.entity_type,
                        "key": s.key,
                        "heading": s.heading,
                        "write_rules": s.write_rules,
                    })
                })
                .collect();
            tool_error_with_details(
                "MISSING_REQUIRED_SECTION",
                &message,
                Some(serde_json::json!({
                    "entity_type": entity_type,
                    "missing_count": missing_count,
                    "sections": sections_json,
                    "type_guidance": type_guidance,
                })),
            )
        }
        EngineError::PatchSectionEmpty { section } => tool_error(
            "PATCH_SECTION_EMPTY",
            &format!("patch target section is empty: {section}"),
        ),
        EngineError::PatchOldNotFound {
            section,
            current_content,
            truncated,
        } => {
            let message = format!("patch `old` substring not found in {section}");
            tool_error_with_details(
                "PATCH_OLD_NOT_FOUND",
                &message,
                Some(serde_json::json!({
                    "section": section,
                    "current_content": current_content,
                    "truncated": truncated,
                })),
            )
        }
        // Codes follow `EngineError::code()` — the single wire-code
        // source every surface (full MCP, CLI, wasm) shares. These two
        // historically drifted (`MEM_WRITER_ERROR` / `PARSE_AFTER_WRITE`);
        // `lean_backend_and_parse_after_write_codes_follow_code_contract`
        // pins them to `code()` so a re-divergence fails the build.
        EngineError::Backend(e) => tool_error("MEM_ERROR", &e.to_string()),
        EngineError::ParseAfterWrite(e) => {
            tool_error("PARSE_ERROR", &format!("parse-after-write failed: {e}"))
        }
        EngineError::Parse(e) => tool_error("PARSE_ERROR", &e.to_string()),
        EngineError::Validation(v) => validation_envelope(v),
        // Schema-resolution, boot-path, and lifecycle variants surface
        // as their own typed codes so the wire contract matches the
        // mem-repo server. Pre-fix this set collapsed to `INTERNAL`
        // — a lean-fireable variant (multi-folder workspaces can trip
        // DuplicateMem / UnknownMem; cross_mem_links policy can
        // trip ReadOnlyMount; generic input validation produces
        // InvalidInput) shipped as INTERNAL instead of its typed code,
        // breaking the agent contract that the structured code matches
        // `EngineError::code()`.
        // Description-posture variants ship structured details so MCP
        // callers branch on `details.rel_type`/`details.from_id`/
        // `details.to_id` instead of parsing the message — bit-identical
        // wire shape with the full-server typed envelope.
        ref err @ EngineError::MissingRequiredDescription {
            ref rel_type,
            ref from_id,
            ref to_id,
        } => tool_error_with_details(
            "MISSING_REQUIRED_DESCRIPTION",
            &err.to_string(),
            Some(serde_json::json!({
                "rel_type": rel_type,
                "from_id": from_id,
                "to_id": to_id,
            })),
        ),
        ref err @ EngineError::DescriptionNotPermitted {
            ref rel_type,
            ref from_id,
            ref to_id,
        } => tool_error_with_details(
            "DESCRIPTION_NOT_PERMITTED",
            &err.to_string(),
            Some(serde_json::json!({
                "rel_type": rel_type,
                "from_id": from_id,
                "to_id": to_id,
            })),
        ),
        ref err @ EngineError::RelationManualAuthoringForbidden {
            ref rel_type,
            ref from_id,
            ref to_id,
            ref guidance,
        } => tool_error_with_details(
            "RELATION_MANUAL_AUTHORING_FORBIDDEN",
            &err.to_string(),
            Some(serde_json::json!({
                "rel_type": rel_type,
                "from_id": from_id,
                "to_id": to_id,
                "guidance": guidance,
            })),
        ),
        e @ EngineError::SchemaNotFound { .. }
        | e @ EngineError::EmbeddedSchemaInvalid { .. }
        | e @ EngineError::SchemaPackageInvalid { .. }
        | e @ EngineError::SchemaResolverInit(_)
        | e @ EngineError::DuplicateMem(_)
        | e @ EngineError::MemQuarantined { .. }
        | e @ EngineError::UnknownMem(_)
        | e @ EngineError::UnknownRef(_)
        | e @ EngineError::UnknownRemote(_)
        | e @ EngineError::LocalDivergence { .. }
        | e @ EngineError::NonFastForward { .. }
        | e @ EngineError::LocalInvalidState { .. }
        | e @ EngineError::SchemaViolationInFetch { .. }
        | e @ EngineError::PushedCommitsProtected { .. }
        | e @ EngineError::BranchResetHeadMoved { .. }
        | e @ EngineError::ReadOnlyMount(_)
        | e @ EngineError::CheckNotRecorded { .. }
        | e @ EngineError::Mem(_)
        | e @ EngineError::MemNameCollision { .. }
        | e @ EngineError::InvalidInput(_) => tool_error(e.code(), &e.to_string()),
        EngineError::RenameSimilarityOutOfRange {
            requested,
            allowed_min,
            allowed_max,
        } => tool_error_with_details(
            "INVALID_INPUT",
            &format!(
                "rename_similarity {requested} outside allowed range [{allowed_min}, {allowed_max}]"
            ),
            Some(serde_json::json!({
                "field": "rename_similarity",
                "requested": requested,
                "allowed_range": [allowed_min, allowed_max],
            })),
        ),
        EngineError::MemConfigIncomplete {
            mem,
            missing_fields,
        } => {
            let message = format!(
                "mem `{mem}` config is missing required field(s) {missing_fields:?} — \
                 set via `memstead mem set-version {mem} <version>` (e.g. 0.1.0)"
            );
            tool_error_with_details(
                "MEM_CONFIG_INCOMPLETE",
                &message,
                Some(serde_json::json!({
                    "mem": mem,
                    "missing_fields": missing_fields,
                    "set_via": format!("memstead mem set-version {mem} <version>"),
                })),
            )
        }
        EngineError::SearchUnavailable => tool_error_with_details(
            "SEARCH_UNAVAILABLE_IN_WASM",
            &display,
            Some(serde_json::json!({})),
        ),
        // Typed refusal when
        // `export_markdown` targets a mem whose active backend
        // doesn't support markdown regeneration. Filesystem-backed
        // workspaces don't reach this arm today (single folder mount),
        // but the variant must be handled to keep the match exhaustive.
        ref err @ EngineError::MarkdownExportUnsupportedBackend {
            ref mem,
            ref active_backend,
            ref supported_backends,
        } => tool_error_with_details(
            "MARKDOWN_EXPORT_UNSUPPORTED_BACKEND",
            &err.to_string(),
            Some(serde_json::json!({
                "mem": mem,
                "active_backend": active_backend,
                "supported_backends": supported_backends,
            })),
        ),
        ref err @ EngineError::EmptyUpdate { ref id } => tool_error_with_details(
            "EMPTY_UPDATE",
            &err.to_string(),
            Some(serde_json::json!({
                "id": id,
                "recognised_keys": [
                    "sections", "append_sections", "patch_sections",
                    "metadata", "metadata_unset", "declare_relations",
                ],
            })),
        ),
        // A bad `since` cursor on `memstead_changes_since`. The folder backend
        // keys `since` off timestamps rather than commit SHAs, so this
        // arm isn't reached on a filesystem-mem workspace today, but the
        // variant must be handled to keep the match exhaustive.
        ref err @ EngineError::InvalidChangesCursor { ref mem, ref since } => {
            tool_error_with_details(
                "INVALID_CURSOR",
                &err.to_string(),
                Some(serde_json::json!({ "mem": mem, "since": since })),
            )
        }
        // Review-mark diff on a markless mem — typed refusal.
        ref err @ EngineError::ReviewMarkNotSet { ref mem } => tool_error_with_details(
            "REVIEW_MARK_NOT_SET",
            &err.to_string(),
            Some(serde_json::json!({ "mem": mem })),
        ),
        // Malformed `anchors[]` element on create/update: typed
        // `INVALID_ANCHOR` with the wrapped anchor error's recovery detail.
        ref err @ EngineError::InvalidAnchor(ref anchor_err) => tool_error_with_details(
            memstead_base::anchor::INVALID_ANCHOR_CODE,
            &err.to_string(),
            Some(serde_json::Value::Object(
                anchor_err.detail().into_iter().collect(),
            )),
        ),
    }
}

/// Map a runtime [`memstead_base::runtime_validator::ValidationError`] to
/// the MCP wire envelope. Thin delegation to the shared
/// [`crate::error_envelopes::validation_envelope`] so the wire shape
/// stays bit-identical with the mem-repo `server.rs` handlers.
fn validation_envelope(err: memstead_base::runtime_validator::ValidationError) -> CallToolResult {
    crate::error_envelopes::validation_envelope(err)
}

#[tool_router(vis = "pub")]
impl FilesystemMcpServer {
    #[tool(
        name = "memstead_entity",
        description = "Read one entity as markdown (filesystem-mem flavour). Same JSON shape as the mem-repo `memstead_entity`. Frontmatter carries `_hash` (content hash) for optimistic locking on follow-up mutations. Pass `sections` to narrow the rendered body; `include_relations` appends the entity's outgoing and incoming edges; `include_context` appends its community cluster.",
        annotations(
            read_only_hint = true,
            destructive_hint = false,
            idempotent_hint = true,
            open_world_hint = false
        )
    )]
    fn memstead_entity(&self, Parameters(p): Parameters<EntityParams>) -> CallToolResult {
        let engine = crate::lock_engine!(self.engine);
        let id = EntityId::canonical(&p.id);
        let entity = match engine.get_entity(&id) {
            Some(e) => e.clone(),
            None => {
                // A quarantined mem's entities are deliberately absent
                // — the read names the quarantine, not a phantom miss.
                if engine.quarantine_reason(id.mem()).is_some() {
                    return engine_op_error(engine.unknown_mem_error(id.mem()));
                }
                return tool_error("ENTITY_NOT_FOUND", &format!("entity not found: {id}"));
            }
        };
        let sections_filter = p.sections.as_deref();
        let mut md = render_entity_markdown(&entity, sections_filter);
        // Inject `_hash` as the first frontmatter field so callers
        // can pin it to `expected_hash` on the next mutation.
        if let Some(idx) = md.find("---\n") {
            let inject_at = idx + 4;
            let line = format!("_hash: {}\n", entity.content_hash);
            md.insert_str(inject_at, &line);
        }

        // Append `## Relations` when the caller asked for it. Mirrors
        // the mem-repo entity handler — outgoing + incoming edges
        // grouped by direction, rendered as a Markdown table.
        if p.include_relations.unwrap_or(false) {
            let outgoing = engine.store().outgoing(&id).to_vec();
            let incoming = engine.store().incoming(&id).to_vec();
            md.push_str(&memstead_base::render::render_relations_markdown(
                id.as_ref(),
                &outgoing,
                &incoming,
            ));
        }

        // Append `## Community Context` when the caller asked for it
        // — the entity's cluster + neighbour list. The community
        // detection is lazy (memoised per engine) and invalidated on
        // every successful mutation, so this is cheap on a static
        // graph and pays the Louvain cost once after each write.
        if p.include_context.unwrap_or(false)
            && let Some(ctx) = engine.context(&id)
        {
            let cluster_id = ctx.community.clone().unwrap_or_else(|| "unknown".into());
            md.push_str(&memstead_base::render::render_community_context_section(
                &ctx,
                &cluster_id,
            ));
        }

        // Structured envelope
        // alongside the markdown text channel; same shape both MCP
        // flavours emit so agents branch on `structured_content`
        // uniformly regardless of which backend served the read.
        let rendered_body_tokens = memstead_base::chunking::estimate_tokens(&md);
        let full_tokens = if sections_filter.is_some() {
            let full_body = render_entity_markdown(&entity, None);
            Some(memstead_base::chunking::estimate_tokens(&full_body))
        } else {
            None
        };
        let mut structured = memstead_base::render::build_entity_envelope(
            &entity,
            rendered_body_tokens,
            full_tokens,
            sections_filter,
            None,
            engine.store().outgoing(&entity.id),
        );
        // Mutation provenance (agent-trust plan 13), opt-in — same
        // block and key the full flavour serves; default responses
        // are byte-unchanged.
        if p.include_provenance.unwrap_or(false)
            && let Some(obj) = structured.as_object_mut()
        {
            let block = match engine.entity_provenance(id.mem(), id.as_ref()) {
                Ok(prov) => serde_json::to_value(&prov).unwrap_or(serde_json::Value::Null),
                Err(e) => serde_json::json!({ "unavailable": e.to_string() }),
            };
            obj.insert("mutation_provenance".into(), block);
        }
        md_with_structured(md, structured)
    }

    #[tool(
        name = "memstead_create",
        description = "Create a new entity in the filesystem-mem workspace. Required: `title`, `entity_type`. Titles accept any single-line text (control characters such as tab/newline are rejected); the title is stored verbatim as display text, while characters outside Unicode alphanumerics, whitespace, and hyphen are dropped from the derived slug — warning TITLE_CHARS_DROPPED_FROM_SLUG names them (`INVALID_TITLE` refusals remain for control characters, empty-deriving titles, and over-long ids). Optional `sections`, `metadata`, `note`, `mem`. `mem` selects the target mount; omit it to land in the default writable mem (the first writable mount in declaration order). A create aimed at a read-only mount is refused with READ_ONLY_MOUNT. The `note` lands in `.memstead/changes.jsonl` (the filesystem-mem analogue of the mem-repo commit body). `relations` and `dry_run` are not implemented on this surface: passing a non-empty `relations` or `dry_run: true` is REFUSED up front with `UNSUPPORTED_PARAM` (`details.params` names them), never silently ignored — so a `dry_run` preview can never accidentally land a real write. Omit them, or use the unified engine (mem-repo MCP / CLI) which honours both.",
        annotations(
            read_only_hint = false,
            destructive_hint = false,
            idempotent_hint = false,
            open_world_hint = false
        )
    )]
    fn memstead_create(&self, Parameters(p): Parameters<CreateParams>) -> CallToolResult {
        // Part B: this surface hardwires `dry_run` off and ignores inline
        // `relations`. Refuse up front when either was meaningfully supplied
        // rather than committing a real write the agent thought was a preview
        // (or dropping edges it thought it wired).
        if let Some(err) = reject_unsupported_params(&[
            ("dry_run", p.dry_run == Some(true)),
            (
                "relations",
                p.relations.as_ref().is_some_and(|r| !r.is_empty()),
            ),
        ]) {
            return err;
        }
        let mut engine = crate::lock_engine!(self.engine);
        match resolve_role_lean(p.role.as_deref()) {
            Ok(r) => engine.set_role(r),
            Err(resp) => return *resp,
        }
        let (actor, client) = self.actor_and_client();
        // Resolve the target mem. An explicit, non-empty `mem` is
        // honoured verbatim — so a multi-mount engine (e.g. a read-only
        // content mem alongside a writable sketch mem) can be targeted
        // by name, and a create aimed at a read-only mount surfaces the
        // engine's READ_ONLY_MOUNT refusal rather than being silently
        // redirected to the writable mount. Omitted → the default writable
        // mem (first writable mount in declaration order), falling back to
        // the first mount so a read-only-only engine still resolves a name
        // (the create then refuses with READ_ONLY_MOUNT, never panics on an
        // empty mem). Single-mem filesystem workspaces are unaffected:
        // the sole mem is both the first and the default writable one.
        let mem = match p.mem.as_deref() {
            Some(v) if !v.is_empty() => v.to_string(),
            _ => engine
                .default_writable_mem()
                .or_else(|| engine.mem_names().into_iter().next())
                .map(String::from)
                .unwrap_or_default(),
        };
        let args = CreateEntityArgs {
            anchors: p
                .anchors
                .unwrap_or_default()
                .into_iter()
                .map(|a| a.into_engine())
                .collect(),
            mem,
            title: p.title,
            entity_type: p.entity_type,
            sections: p.sections.unwrap_or_default(),
            metadata: p.metadata.unwrap_or_default(),
            // The filesystem-mem MCP surface doesn't (yet)
            // accept inline relations on the wire — pass empty;
            // operators wire edges via memstead_relate post-create.
            relations: Vec::new(),
            // dry_run not exposed on the filesystem-mem tool
            // surface; operators preview changes by reading first
            // and inspecting on the agent side.
            dry_run: false,
        };
        match engine.create_entity(args, actor, client.as_ref(), p.note.as_deref()) {
            Ok(outcome) => {
                // WarningHint's Serialize impl produces the same
                // `{code, message, details}` envelope the manual
                // synthesis used to emit. commit_sha + title +
                // mem are now first-class on the outcome.
                let durable = mem_is_durable(&engine, &outcome.mem);
                let body = serde_json::json!({
                    "id": outcome.id.to_string(),
                    "title": outcome.title,
                    "mem": outcome.mem,
                    "file_path": outcome.file_path,
                    "_hash": outcome.content_hash,
                    "commit_sha": outcome.commit_sha,
                    "durable": durable,
                    "warnings": outcome.warnings,
                    "type_guidance": outcome.type_guidance,
                });
                json_response(&body)
            }
            Err(e) => engine_op_error(e),
        }
    }

    #[tool(
        name = "memstead_update",
        description = "Update an existing entity in the filesystem-mem workspace. `expected_hash` (from a previous memstead_entity read) is required — mismatch returns code HASH_MISMATCH with details.current carrying the live hash. This surface honours `sections` (replace) + `metadata` (set) + `metadata_unset` + `declare_relations` + `relations_unset`. The mem-repo `append_sections` / `patch_sections` / `dry_run` shapes are NOT implemented here: passing a non-empty `append_sections` / `patch_sections`, or `dry_run: true`, is REFUSED up front with `UNSUPPORTED_PARAM` (`details.params` names them), never silently ignored — an agent that patches is told its patch was dropped instead of believing it applied. Omit them, or use the unified engine (mem-repo MCP / CLI) which honours all three.",
        annotations(
            read_only_hint = false,
            destructive_hint = false,
            idempotent_hint = false,
            open_world_hint = false
        )
    )]
    fn memstead_update(&self, Parameters(p): Parameters<UpdateParams>) -> CallToolResult {
        // Part B: this surface hardwires `append_sections` / `patch_sections`
        // off and `dry_run` off. Refuse up front when any was meaningfully
        // supplied rather than dropping the edit silently (an agent that
        // patched believes it patched). `sections` (replace), `metadata`,
        // `metadata_unset`, `declare_relations`, and `relations_unset` ARE
        // honoured and pass through untouched.
        if let Some(err) = reject_unsupported_params(&[
            ("dry_run", p.dry_run == Some(true)),
            (
                "append_sections",
                p.append_sections.as_ref().is_some_and(|m| !m.is_empty()),
            ),
            (
                "patch_sections",
                p.patch_sections.as_ref().is_some_and(|m| !m.is_empty()),
            ),
        ]) {
            return err;
        }
        let mut engine = crate::lock_engine!(self.engine);
        match resolve_role_lean(p.role.as_deref()) {
            Ok(r) => engine.set_role(r),
            Err(resp) => return *resp,
        }
        let (actor, client) = self.actor_and_client();
        let args = UpdateEntityArgs {
            anchors: p
                .anchors
                .unwrap_or_default()
                .into_iter()
                .map(|a| a.into_engine())
                .collect(),
            anchors_unset: p
                .anchors_unset
                .unwrap_or_default()
                .into_iter()
                .map(|u| u.into_engine())
                .collect(),
            relations_unset: p
                .relations_unset
                .unwrap_or_default()
                .into_iter()
                .map(|r| memstead_base::ops::RelationUnsetArg {
                    rel_type: r.rel_type,
                    target: memstead_base::EntityId(r.target),
                })
                .collect(),
            id: EntityId(p.id),
            expected_hash: Some(p.expected_hash),
            sections: p.sections.unwrap_or_default(),
            // The filesystem-mem tool doesn't expose
            // append_sections / patch_sections on the wire yet;
            // pass empty.
            append_sections: IndexMap::new(),
            patch_sections: IndexMap::new(),
            metadata: p.metadata.unwrap_or_default(),
            metadata_unset: p.metadata_unset.unwrap_or_default(),
            declare_relations: p
                .declare_relations
                .unwrap_or_default()
                .into_iter()
                .map(|r| memstead_base::ops::RelateArg {
                    rel_type: r.r#type,
                    to: EntityId(r.to),
                    description: r.description,
                })
                .collect(),
            dry_run: false,
        };
        match engine.update_entity(args, actor, client.as_ref(), p.note.as_deref()) {
            Ok(outcome) => {
                let durable = mem_is_durable(&engine, outcome.id.mem());
                let body = serde_json::json!({
                    "id": outcome.id.to_string(),
                    "file_path": outcome.file_path,
                    "_hash": outcome.content_hash,
                    "durable": durable,
                    "modified_sections": outcome.modified_sections.replaced,
                    "modified_metadata_set": outcome.modified_metadata.set,
                    "modified_metadata_unset": outcome.modified_metadata.unset,
                    // Typed warnings ride out on `outcome.warnings` —
                    // the engine emits `NOTE_MISSING` here under
                    // `[mutations].require_notes`, matching create/relate.
                    "warnings": outcome.warnings,
                    // Orphan-stub GC: when this update removed a body
                    // wiki-link that was a stub target's last referrer,
                    // the engine GC'd the stub and lists it here. Always
                    // present (empty array when nothing orphaned),
                    // matching the relate-remove and delete shape so
                    // consumers don't branch on field presence.
                    "orphan_stubs_removed": outcome
                        .orphan_stubs_removed
                        .iter()
                        .map(|i| i.to_string())
                        .collect::<Vec<_>>(),
                });
                json_response(&body)
            }
            Err(e) => engine_op_error(e),
        }
    }

    #[tool(
        name = "memstead_delete",
        description = "Remove an entity from the filesystem-mem workspace. `expected_hash` is required (read first via memstead_entity); mismatch returns HASH_MISMATCH. Refuses entities with incoming references — v1 has no per-call force toggle on the MCP surface; use `memstead delete --force` on the CLI. The `note` lands in `.memstead/changes.jsonl` (the per-mutation changelog).",
        annotations(
            read_only_hint = false,
            destructive_hint = true,
            idempotent_hint = false,
            open_world_hint = false
        )
    )]
    fn memstead_delete(&self, Parameters(p): Parameters<DeleteParams>) -> CallToolResult {
        let mut engine = crate::lock_engine!(self.engine);
        match resolve_role_lean(p.role.as_deref()) {
            Ok(r) => engine.set_role(r),
            Err(resp) => return *resp,
        }
        let (actor, client) = self.actor_and_client();
        let args = DeleteEntityArgs {
            id: EntityId(p.id),
            // The MCP delete shape carries a required `expected_hash` String;
            // an empty string is the documented "stub delete" path. The
            // engine takes Option — pass `None` only for empty
            // strings to preserve the no-hash-check semantics.
            expected_hash: if p.expected_hash.is_empty() {
                None
            } else {
                Some(p.expected_hash)
            },
        };
        match engine.delete_entity(args, actor, client.as_ref(), p.note.as_deref()) {
            Ok(outcome) => {
                let durable = mem_is_durable(&engine, outcome.id.mem());
                let body = serde_json::json!({
                    "id": outcome.id.to_string(),
                    "file_path": outcome.file_path,
                    "removed_incoming": outcome.removed_incoming,
                    "durable": durable,
                    // Engine-emitted warnings (residual-stub demotion,
                    // and `NOTE_MISSING` under `require_notes`).
                    "warnings": outcome.warnings,
                });
                json_response(&body)
            }
            Err(e) => engine_op_error(e),
        }
    }

    #[tool(
        name = "memstead_relate",
        description = "Connect or disconnect two entities with a typed relationship in the same filesystem-mem. Cross-mem targets are rejected with CROSS_MEM_RELATION (filesystem-mem is single-mem by design). `remove: true` drops the matching pair if present; otherwise the call appends. No-op paths (already present add, absent remove) succeed silently and do not append a changelog line. `dry_run` is not implemented on this surface: passing `dry_run: true` is REFUSED up front with `UNSUPPORTED_PARAM` (`details.params` names it), never silently ignored — so a rehearsal can never accidentally land a real write. Omit it, or use the unified engine (mem-repo MCP / CLI) which honours it.",
        // idempotent_hint = true: relate's duplicate-add and
        // remove-nonexistent paths are typed-warning no-ops, so a retry
        // converges. Matches the mem-repo server's annotation —
        // `relate_annotation_is_idempotent_on_lean` pins parity.
        annotations(read_only_hint = false, destructive_hint = false, idempotent_hint = true, open_world_hint = false)
    )]
    fn memstead_relate(&self, Parameters(p): Parameters<RelateParams>) -> CallToolResult {
        // This surface hardwires `dry_run` off — refuse up front when
        // meaningfully supplied so a rehearsal can never accidentally
        // land a real write (same posture as create / update).
        if let Some(refusal) = reject_unsupported_params(&[("dry_run", p.dry_run == Some(true))]) {
            return refusal;
        }
        if p.relations.is_empty() {
            return tool_error(
                "INVALID_INPUT",
                "relations must carry at least one operation",
            );
        }
        let mut engine = crate::lock_engine!(self.engine);
        match resolve_role_lean(p.role.as_deref()) {
            Ok(r) => engine.set_role(r),
            Err(resp) => return *resp,
        }
        let (actor, client) = self.actor_and_client();
        // Relate is hash-stable on the section bodies but the
        // Relationships section regenerates, so `_hash` per entry is
        // read back post-commit. `expected_hash` is omitted on relate
        // across both flavours.
        let ops: Vec<(RelateEntityArgs, Option<String>)> = p
            .relations
            .iter()
            .map(|op| {
                (
                    RelateEntityArgs {
                        source: EntityId::canonical(&op.from),
                        expected_hash: None,
                        rel_type: op.r#type.clone(),
                        target: EntityId::canonical(&op.to),
                        remove: op.remove.unwrap_or(false),
                        description: op.description.clone(),
                        dry_run: false,
                    },
                    p.note.clone(),
                )
            })
            .collect();
        let anchor_mem = ops[0].0.source.mem().to_string();

        // A list of one routes through the single-op engine path —
        // byte-identical semantics to the historical single call,
        // wrapped in the same plural envelope larger lists produce.
        if p.relations.len() == 1 {
            let (args, note) = {
                let mut it = ops.into_iter();
                it.next().expect("len checked above")
            };
            return match engine.relate_entity(args, actor, client.as_ref(), note.as_deref()) {
                Ok(outcome) => {
                    let action = match outcome.action {
                        RelateAction::Added => "added",
                        RelateAction::Removed => "removed",
                        RelateAction::NoOpAlreadyPresent | RelateAction::NoOpAbsent => "noop",
                    };
                    let durable = mem_is_durable(&engine, outcome.from.mem());
                    let body = serde_json::json!({
                        "results": [{
                            "from": outcome.from.to_string(),
                            "to": outcome.to.to_string(),
                            "rel_type": outcome.rel_type,
                            "action": action,
                            "source": outcome.source,
                            "_hash": outcome.content_hash,
                        }],
                        "commit_sha": outcome.commit_sha,
                        "durable": durable,
                        "warnings": outcome.warnings,
                        "orphan_stubs_removed": outcome
                            .orphan_stubs_removed
                            .iter()
                            .map(|i| i.to_string())
                            .collect::<Vec<_>>(),
                    });
                    json_response(&body)
                }
                Err(e) => engine_op_error(e),
            };
        }

        // Snapshot which targets are absent pre-call so applied
        // auto-stubs can surface the same AUTO_STUB_CREATED warning
        // the single call emitted.
        let absent_targets: std::collections::HashSet<String> = p
            .relations
            .iter()
            .filter(|op| !op.remove.unwrap_or(false))
            .map(|op| EntityId::canonical(&op.to))
            .filter(|to| engine.store().get(to).is_none())
            .map(|to| to.to_string())
            .collect();
        let result = match engine.batch_relate(ops, actor, client.as_ref(), false) {
            Ok(r) => r,
            Err(e) => return engine_op_error(e),
        };

        if !result.applied {
            // Report-all refusal — nothing committed. A list of one
            // surfaces its entry's own typed envelope; larger lists
            // wrap under BATCH_REFUSED with per-entry envelopes.
            let entries: Vec<serde_json::Value> = result
                .results
                .iter()
                .zip(p.relations.iter())
                .enumerate()
                .map(|(i, (entry, op))| {
                    let mut e = serde_json::json!({
                        "index": i,
                        "from": op.from,
                        "to": op.to,
                        "rel_type": op.r#type,
                        "action": entry.action,
                    });
                    if let Some(err) = &entry.error {
                        e["code"] = serde_json::json!(err.code);
                        e["message"] = serde_json::json!(err.message);
                        e["details"] = err.details.clone();
                    }
                    e
                })
                .collect();
            let msg = format!(
                "batch refused — {} of {} operation(s) failed, nothing committed",
                result.failed,
                p.relations.len(),
            );
            return tool_error_with_details(
                "BATCH_REFUSED",
                &msg,
                Some(serde_json::json!({
                    "entries": entries,
                    "failed": result.failed,
                    "errors_suppressed": result.errors_suppressed,
                })),
            );
        }

        let durable = mem_is_durable(&engine, anchor_mem.as_str());
        let mut warnings: Vec<memstead_base::ops::WarningHint> = Vec::new();
        let entries: Vec<serde_json::Value> = result
            .results
            .iter()
            .zip(p.relations.iter())
            .map(|(entry, op)| {
                let from = EntityId::canonical(&op.from);
                let to = EntityId::canonical(&op.to);
                let canonical_type = op.r#type.to_uppercase();
                if entry.action == "noop" {
                    if op.remove.unwrap_or(false) {
                        warnings.push(memstead_base::ops::WarningHint::NoSuchRelationship {
                            rel_type: canonical_type.clone(),
                            from: from.clone(),
                            to: to.clone(),
                        });
                    } else {
                        warnings.push(memstead_base::ops::WarningHint::DuplicateRelationship {
                            rel_type: canonical_type.clone(),
                            from: from.clone(),
                            to: to.clone(),
                        });
                    }
                }
                if !op.remove.unwrap_or(false)
                    && absent_targets.contains(&to.to_string())
                    && engine.store().get(&to).map(|e| e.stub).unwrap_or(false)
                {
                    // Real batch only (this flavour has no relate
                    // rehearsal): the stub exists post-commit.
                    warnings.push(memstead_base::ops::WarningHint::AutoStubCreated {
                        stub_id: to.clone(),
                        pending: false,
                    });
                }
                let source_label = engine
                    .store()
                    .outgoing(&from)
                    .iter()
                    .find(|e| e.target == to && e.rel_type.eq_ignore_ascii_case(&op.r#type))
                    .map(|e| match e.source {
                        memstead_base::EdgeSource::BodyLink => "body_link",
                        memstead_base::EdgeSource::Hierarchy => "hierarchy",
                        memstead_base::EdgeSource::Explicit => "explicit",
                    })
                    .unwrap_or("explicit");
                let hash = engine
                    .store()
                    .get(&from)
                    .map(|e| e.content_hash.clone())
                    .unwrap_or_default();
                serde_json::json!({
                    "from": from.to_string(),
                    "to": to.to_string(),
                    "rel_type": canonical_type,
                    "action": entry.action,
                    "source": source_label,
                    "_hash": hash,
                })
            })
            .collect();

        let body = serde_json::json!({
            "results": entries,
            "commit_sha": result.commit_sha,
            "durable": durable,
            "warnings": warnings,
            "orphan_stubs_removed": result
                .orphan_stubs_removed
                .iter()
                .map(|i| i.to_string())
                .collect::<Vec<_>>(),
        });
        json_response(&body)
    }

    #[tool(
        name = "memstead_search",
        description = "Search entities by lexical content + structural filters. Same JSON shape as the mem-repo `memstead_search`. The first call after engine init or any mutation pays a one-time search-index build (scales with entity count); subsequent calls reuse the cache. Pass an empty `query: {}` (or omit it) for a metadata-only structural filter — the list shape folds in here. Filters: `mem`, `entity_type`, `edge_type` (first-class engine axes), `stub`, plus `filters: { <field>: <value> }` for any schema-declared `filterable: equality` field (e.g. `{\"level\": \"M0\", \"tags\": \"auth\"}`). Strict type-narrowing: an entity whose type doesn't declare a *filterable* field is excluded (warning `FILTER_TYPE_SCOPED`); a field declared but not filterable on any reachable type is ignored — the result equals the same search without it (warning `FIELD_NOT_FILTERABLE`), never emptied, in both the scoped and unscoped case; a key no schema declares is ignored (`UNKNOWN_FILTER_KEY`). Pagination via `limit` / `offset`. Section bodies are not shipped per hit — read them with `memstead_entity`. A page is bounded to `token_budget` (default 12000): an overflowing page returns the highest-ranked hits that fit with a `SEARCH_RESULTS_TRUNCATED` warning (`kept`/`budget`) while `_total` stays the full count — page on with `offset` or raise `token_budget`.",
        annotations(
            read_only_hint = true,
            destructive_hint = false,
            idempotent_hint = true,
            open_world_hint = false
        )
    )]
    fn memstead_search(&self, Parameters(p): Parameters<SearchParams>) -> CallToolResult {
        let engine = crate::lock_engine!(self.engine);
        let filters = p.filters.unwrap_or_default();
        let scope = SearchScope {
            query: p.query,
            mem: p.mem,
            entity_type: p.entity_type,
            limit: p.limit,
            offset: p.offset,
            filters,
            // Thread the
            // agent's `range_filters` through to the engine arg —
            // mirrors the full server's wiring so both servers expose the
            // typed range-filter warnings the engine already produces.
            range_filters: p.range_filters.unwrap_or_default(),
            edge_type: p.edge_type,
            related_to: p.related_to.map(EntityId),
            depth: p.depth,
            expand_via: p.expand_via,
            expand_depth: p.expand_depth,
            direction: p.direction.unwrap_or_default(),
            stub: p.stub,
            token_budget: p.token_budget,
        };
        let offset = scope.offset.unwrap_or(0);
        let result = match engine.search(&scope) {
            Ok(r) => r,
            Err(e) => return engine_op_error(e),
        };
        let md = render_search_markdown(&result, offset);
        // Structured envelope
        // on `structured_content`, rendered markdown on the text
        // channel; lean MCP mirrors full's split so cross-flavour
        // agents see the same wire contract.
        let envelope = memstead_base::render::build_search_envelope(&result, offset);
        let structured = serde_json::to_value(&envelope).unwrap_or(serde_json::Value::Null);
        md_with_structured(md, structured)
    }

    #[tool(
        name = "memstead_health",
        description = "Return the filesystem-mem workspace's health summary: orphans, stubs, missing required fields, stale entities. Same JSON shape as the mem-repo `memstead_health` (single-mem, so `writable_mems` carries one entry). `include` accepts the shared health key set — today the lean surface dispatches `dangling_links` (matching the mem-repo response shape: `{from, target_id, target_path, section}`) and validates every key against the allowed set, emitting `UNKNOWN_INCLUDE_KEY` on the response's `warnings[]` for typos. `conformance` / `integrity` are dispatched too: `conformance` lints every entity against the effective schema (the pin, or `target_schema` when given) into a `findings` array of `{id, axis, code, detail}` with write-time typed codes; `integrity` adds the consistency axis (DANGLING_LINK, ORPHAN_STUB) to the same list; `anchors` adds per-mem counts of the four standalone anchor-verification states (resolved/drifted/recheck/unresolvable). `constraints` lists standing declared-constraint violations with `severity`. Other detail keys (`orphans`, `stubs`, …) are accepted but the v1 surface returns the full report regardless — narrowing is a follow-up.",
        annotations(
            read_only_hint = true,
            destructive_hint = false,
            idempotent_hint = true,
            open_world_hint = false
        )
    )]
    fn memstead_health(&self, Parameters(p): Parameters<HealthParams>) -> CallToolResult {
        let engine = crate::lock_engine!(self.engine);
        let mut health = engine.health();
        let include = p.include.unwrap_or_default();

        // Validate include keys against the shared catalogue. Unknown
        // keys surface as a typed `UNKNOWN_INCLUDE_KEY` warning — the
        // same shape full emits and the same shape the CLI consumes.
        for key in &include {
            if !memstead_base::ops::health::HEALTH_INCLUDE_KEYS.contains(&key.as_str()) {
                health
                    .warnings
                    .push(memstead_base::WarningHint::UnknownIncludeKey {
                        key: key.clone(),
                        allowed: memstead_base::ops::health::HEALTH_INCLUDE_KEYS
                            .iter()
                            .map(|s| s.to_string())
                            .collect(),
                    });
            }
        }

        // `dangling_links` opt-in: the engine's `HealthSummary` carries
        // a `dangling_links: Option<...>` slot that handlers populate
        // (the kernel's `compute_health` leaves it `None`). Populating
        // it from the lean surface gives agents the documented
        // include-key without forcing them through the full engine.
        if include.iter().any(|s| s == "dangling_links") {
            let dangling = memstead_base::ops::health::collect_dangling_links(engine.store(), None);
            health.dangling_links = Some(dangling);
        }

        // Conformance axis (`conformance`), or both axes
        // (`integrity`) — same `findings` slot and `{ id, axis, code,
        // detail }` shape as the mem-repo flavour. The scan iterates every
        // mounted mem's schema (`engine.schemas().keys()`), so on a
        // two-mount session engine (writable sketch + read-only content) it
        // covers both mounts — the summary counts and roster come straight
        // from `engine.health()`, which is mount-aware, so nothing is
        // misreported on a multi-mount engine.
        if include
            .iter()
            .any(|s| s == "conformance" || s == "integrity")
        {
            let target: Option<memstead_schema::SchemaRef> = match p.target_schema.as_deref() {
                None => None,
                Some(raw) => match raw.parse::<memstead_schema::SchemaRef>() {
                    Ok(r) => Some(r),
                    Err(reason) => {
                        return tool_error(
                            "INVALID_INPUT",
                            &format!("invalid target_schema {raw:?}: {reason}"),
                        );
                    }
                },
            };
            let mut mem_names: Vec<String> = engine.schemas().keys().cloned().collect();
            mem_names.sort();
            let mut findings = Vec::new();
            for v in &mem_names {
                match engine.conformance_findings(v, target.as_ref()) {
                    Ok(f) => findings.extend(f),
                    Err(e) => {
                        return tool_error(e.code(), &e.to_string());
                    }
                }
                if include.iter().any(|s| s == "integrity") {
                    match engine.consistency_findings(v) {
                        Ok(f) => findings.extend(f),
                        Err(e) => {
                            return tool_error(e.code(), &e.to_string());
                        }
                    }
                }
            }
            health.findings = Some(findings);
        }

        // `include=["anchors"]` (per-mem four-state counts),
        // `include=["constraints"]` (standing declared-constraint
        // violations), and `include=["friction"]` (the refusal
        // ledger's summary — agent-trust plan 08) — from the shared
        // base helpers, patched onto the serialized report so
        // combined includes compose.
        let wants_anchors = include.iter().any(|s| s == "anchors");
        let wants_constraints = include.iter().any(|s| s == "constraints");
        let wants_friction = include.iter().any(|s| s == "friction");
        let wants_open_questions = include.iter().any(|s| s == "open_questions");
        let wants_stale_derivations = include.iter().any(|s| s == "stale_derivations");
        let wants_checks = include.iter().any(|s| s == "checks");
        if wants_anchors
            || wants_constraints
            || wants_friction
            || wants_open_questions
            || wants_stale_derivations
            || wants_checks
        {
            let mut value = match serde_json::to_value(&health) {
                Ok(v) => v,
                Err(e) => return tool_error("INTERNAL", &format!("serialize health: {e}")),
            };
            if wants_anchors {
                value["anchors"] = memstead_base::ops::health::health_anchors_axis(&engine);
            }
            if wants_constraints {
                value["constraints"] = serde_json::to_value(engine.constraint_findings(None))
                    .unwrap_or(serde_json::Value::Null);
                let defects = engine.schema_format_defects();
                if !defects.is_empty() {
                    value["schema_format_defects"] =
                        serde_json::to_value(defects).unwrap_or(serde_json::Value::Null);
                }
            }
            if wants_friction {
                value["friction"] =
                    memstead_base::friction::FrictionLedger::for_workspace(&self.workspace_root)
                        .summarize();
            }
            if wants_open_questions {
                value["open_questions"] =
                    memstead_base::ops::health::health_open_questions_axis(&engine, None);
            }
            if wants_stale_derivations {
                value["stale_derivations"] =
                    memstead_base::ops::health::health_stale_derivations_axis(&engine, None);
            }
            if wants_checks {
                value["checks"] = memstead_base::ops::health::health_checks_axis(&engine, None);
            }
            return json_response(&value);
        }

        json_response(&health)
    }

    #[tool(
        name = "memstead_schema",
        description = "Read the workspace's pinned schema as a JSON document — `ref` (canonical `name@version`), `relationship_mode`, the relationship vocabulary, `community`, `used_by[]`, top-level `origin` (`first-party` / `third-party`; a third-party schema is served structural-only with its prose-instruction fields omitted), top-level `alias_target_rel_type` (when authored — the rel-type body wiki-links `[[target]]` auto-emit), and per-type section/field detail. Accepts either `name` (bare name or canonical pin) or `mem` (the workspace's single mem). Passing both is `INVALID_INPUT`. v1 surface returns the engine's pinned schema regardless of which form is used (filesystem-mem is single-mem, single-schema). Default `verbosity` is `\"lite\"` — a cheap cold-start skeleton: entity-type names + section keys + field shapes, relationship names + endpoints, the alias pointer, prose dropped (heavy arrays ship as `types_summary`/`relationships_summary`). Pass `verbosity: \"full\"` for the complete prose payload. An unrecognized `verbosity` returns `INVALID_INPUT`. Returns `ENTITY_NOT_FOUND` when `name` explicitly mismatches the pinned schema; `UNKNOWN_MEM` when `mem` is not the workspace's mem.",
        annotations(
            read_only_hint = true,
            destructive_hint = false,
            idempotent_hint = true,
            open_world_hint = false
        )
    )]
    fn memstead_schema(&self, Parameters(p): Parameters<SchemaParams>) -> CallToolResult {
        let engine = crate::lock_engine!(self.engine);
        // filesystem-mem is single-mem by design; the new engine
        // carries one schemas[] entry. Pick it.
        let Some((mem_name, schema)) = engine.schemas().iter().next() else {
            // Genuinely-systemic: the filesystem boot path always
            // mounts exactly one mem and pins exactly one schema. An
            // empty `schemas()` map means engine construction itself
            // is inconsistent — no agent-side recovery applies, so
            // `INTERNAL` is the honest wire code (this class of
            // genuinely-systemic failure is the legitimate `INTERNAL`
            // use case).
            return tool_error(
                "INTERNAL",
                "engine has no schemas — workspace mount list is empty",
            );
        };
        let pinned_name = &schema.manifest.name;
        let pinned_version = schema.version.to_string();
        let canon = format!("{pinned_name}@{pinned_version}");

        // Validate (`name`, `mem`) input shape; either resolves to a
        // string the lookup below checks against the pinned schema.
        // The `mem` path is provided for parity with the mem-repo
        // flavour; in filesystem-mem the single mem always maps
        // to the single schema.
        let want_owned: String = match (p.name.as_deref(), p.mem.as_deref()) {
            (Some(_), Some(_)) => {
                return tool_error(
                    "INVALID_INPUT",
                    "memstead_schema accepts exactly one of `name` or `mem`, not both.",
                );
            }
            (Some(name), None) => name.trim().to_string(),
            (None, Some(mem)) => {
                if mem != mem_name.as_str() {
                    return tool_error(
                        "UNKNOWN_MEM",
                        &format!("unknown mem: {mem:?} — workspace mounts {mem_name:?}"),
                    );
                }
                String::new() // matches pinned schema by default
            }
            (None, None) => String::new(),
        };
        let want = want_owned.as_str();
        let matches = want.is_empty() || want == pinned_name.as_str() || want == canon.as_str();
        if !matches {
            return tool_error(
                "ENTITY_NOT_FOUND",
                &format!("schema not found: {want:?} — workspace pins {canon}"),
            );
        }

        // Verbosity toggle — `lite` (default) or the full body, mirroring
        // the mem-repo server's default. An unrecognized value refuses
        // with a typed INVALID_INPUT naming the bad value rather than
        // silently falling back.
        let verbosity = match p.verbosity.as_deref() {
            None => memstead_base::render::SchemaVerbosity::Lite,
            Some(v) => match memstead_base::render::SchemaVerbosity::from_wire(v) {
                Some(sv) => sv,
                None => {
                    return tool_error(
                        "INVALID_INPUT",
                        &format!("unknown verbosity: {v:?} — expected \"full\" or \"lite\""),
                    );
                }
            },
        };

        // One shared, transport-neutral builder for every schema-read
        // surface (mem-repo MCP, the HTTP `/api/schema` endpoint, and
        // this filesystem-mem flavour) — no second divergent renderer
        // to drift. `ref` carries the canonical `name@version`, and
        // `alias_target_rel_type` rides along, so the public surface now
        // advertises the body-wiki-link edge-authoring rule the full
        // schema response always carried.
        // Trust origin governs de-framing: a third-party schema is served
        // structural-only regardless of the requested `verbosity`.
        let origin = engine.schema_origin(schema);
        let payload = memstead_base::render::build_schema_payload(
            schema,
            vec![mem_name.to_string()],
            verbosity,
            origin,
        );
        json_response(&payload)
    }

    #[tool(
        name = "memstead_diff",
        description = "Return a two-ref structural diff at entity granularity. **Filesystem-mem flavour:** folder mounts carry no git refs, so this tool refuses with `INVALID_INPUT` against folder-backed mems. Use the mem-repo flavour for the real diff; the surface stays for cross-flavour clients that hit either server.",
        annotations(
            read_only_hint = true,
            destructive_hint = false,
            idempotent_hint = true,
            open_world_hint = false
        )
    )]
    fn memstead_diff(&self, Parameters(p): Parameters<DiffParams>) -> CallToolResult {
        let engine = crate::lock_engine!(self.engine);
        let config = memstead_base::ops::DiffConfig {
            rename_similarity: p
                .rename_similarity
                .unwrap_or(memstead_base::ops::RENAME_SIMILARITY_DEFAULT),
            include_content: p.include_content,
            include_ripple: p.include_ripple,
        };
        match engine.diff(&p.mem, &p.ref_a, &p.ref_b, Some(config)) {
            Ok(diff) => json_response(&diff),
            Err(e) => engine_op_error(e),
        }
    }

    #[tool(
        name = "memstead_changes_since",
        description = "Read the per-mutation changelog at `.memstead/changes.jsonl` since a given RFC 3339 timestamp. **Diverges from the mem-repo flavour** — filesystem-mem has no commit history, so `since` is a timestamp string (e.g. `\"2026-05-08T15:30:00.000Z\"`) and the response yields the JSONL entries with `ts > since` as a structured array. Pass an empty string or the UNIX epoch (`\"1970-01-01T00:00:00.000Z\"`) for a full dump. The `mem` field is accepted for shape compatibility with the mem-repo flavour but ignored — single-mem. `rename_similarity` and `include_notes` are also accepted but ignored.",
        annotations(
            read_only_hint = true,
            destructive_hint = false,
            idempotent_hint = true,
            open_world_hint = false
        )
    )]
    fn memstead_changes_since(
        &self,
        Parameters(p): Parameters<ChangesSinceParams>,
    ) -> CallToolResult {
        // The unified engine doesn't expose a workspace_root accessor
        // (mounts can be heterogeneous); use the captured field.
        let log_path = self
            .workspace_root
            .join(memstead_base::MEM_META_DIR)
            .join("changes.jsonl");
        let raw = match std::fs::read_to_string(&log_path) {
            Ok(s) => s,
            Err(e) if e.kind() == std::io::ErrorKind::NotFound => String::new(),
            Err(e) => {
                return tool_error("CHANGELOG_ERROR", &e.to_string());
            }
        };

        let since = p.since.trim();
        let mut entries: Vec<serde_json::Value> = Vec::new();
        for line in raw.lines() {
            let trimmed = line.trim();
            if trimmed.is_empty() {
                continue;
            }
            let value: serde_json::Value = match serde_json::from_str(trimmed) {
                Ok(v) => v,
                Err(_) => continue, // skip malformed lines silently
            };
            let ts_match = value
                .get("ts")
                .and_then(|v| v.as_str())
                .map(|s| s.to_string())
                .unwrap_or_default();
            if !since.is_empty() && ts_match.as_str() <= since {
                continue;
            }
            entries.push(value);
        }
        let payload = serde_json::json!({
            "since": since,
            "count": entries.len(),
            "entries": entries,
        });
        json_response(&payload)
    }

    #[tool(
        name = "memstead_rename",
        description = "Rename an entity by changing its title. The slug, id, and on-disk file path follow. Titles accept any single-line text (control characters such as tab/newline are rejected); the title is stored verbatim as display text, while characters outside Unicode alphanumerics, whitespace, and hyphen are dropped from the derived slug — warning TITLE_CHARS_DROPPED_FROM_SLUG names them (`INVALID_TITLE` refusals remain for control characters, empty-deriving titles, and over-long ids). `expected_hash` is required. Atomic referrer rewrite: every Write-Mem entity whose relationships or section bodies point at the old id has its `[[old-slug]]` tokens rewritten in one per-mem commit; ReadOnly referrers leave a residual stub at the old id holding the surviving incoming edges.",
        annotations(
            read_only_hint = false,
            destructive_hint = false,
            idempotent_hint = false,
            open_world_hint = false
        )
    )]
    fn memstead_rename(&self, Parameters(p): Parameters<RenameParams>) -> CallToolResult {
        let mut engine = crate::lock_engine!(self.engine);
        match resolve_role_lean(p.role.as_deref()) {
            Ok(r) => engine.set_role(r),
            Err(resp) => return *resp,
        }
        let (actor, client) = self.actor_and_client();
        let args = RenameEntityArgs {
            id: EntityId(p.id),
            expected_hash: Some(p.expected_hash),
            new_title: p.new_title,
        };
        match engine.rename_entity(args, actor, client.as_ref(), p.note.as_deref()) {
            Ok(outcome) => {
                let durable = mem_is_durable(&engine, outcome.new_id.mem());
                let body = serde_json::json!({
                    "old_id": outcome.old_id.to_string(),
                    "new_id": outcome.new_id.to_string(),
                    "old_file_path": outcome.old_path,
                    "new_file_path": outcome.new_path,
                    "_hash": outcome.content_hash,
                    "durable": durable,
                    // Engine-emitted warnings (slug-noop, and
                    // `NOTE_MISSING` under `require_notes`).
                    "warnings": outcome.warnings,
                });
                json_response(&body)
            }
            Err(e) => engine_op_error(e),
        }
    }

    #[tool(
        name = "memstead_check",
        description = "Record a check: \"entity E checked, verdict ok | failed, via method M\" — the engine-recorded act of verification (never a mutation: entity markdown, `_hash`, and the mem's change history are untouched). The record carries the caller-declared `role` plus actor/client identity and the entity's `_hash` at check time, appended to the workspace's append-only check ledger. Derived check state (`never_checked` | `checked_ok` | `check_failed` | `check_stale` — computed by hash comparison, never stamped) is served in `memstead_entity`'s opt-in `mutation_provenance` block and echoed here as `check_state`. Verdict vocabulary is closed (`ok` | `failed`); an unknown verdict refuses `INVALID_VERDICT`. Refuses typed on unknown entity (`ENTITY_NOT_FOUND`), read-only mems (`READ_ONLY_MOUNT`), and persistence failure (`CHECK_NOT_RECORDED`).",
        annotations(
            read_only_hint = false,
            destructive_hint = false,
            idempotent_hint = false,
            open_world_hint = false
        )
    )]
    fn memstead_check(&self, Parameters(p): Parameters<CheckParams>) -> CallToolResult {
        let Some(verdict) = memstead_base::check::Verdict::from_wire(&p.verdict) else {
            return tool_error_with_details(
                "INVALID_VERDICT",
                &format!(
                    "unknown verdict {:?} — the vocabulary is: {}",
                    p.verdict,
                    memstead_base::check::VERDICTS.join(", ")
                ),
                Some(serde_json::json!({ "allowed": memstead_base::check::VERDICTS })),
            );
        };
        let mut engine = crate::lock_engine!(self.engine);
        match resolve_role_lean(p.role.as_deref()) {
            Ok(r) => engine.set_role(r),
            Err(resp) => return *resp,
        }
        let (actor, client) = self.actor_and_client();
        let id = EntityId(p.entity);
        match engine.record_check(
            id.mem(),
            id.as_ref(),
            verdict,
            p.method.as_deref(),
            actor,
            client.as_ref(),
        ) {
            Ok(record) => {
                let (state, _) = match engine.entity_check_state(id.mem(), id.as_ref()) {
                    Ok(pair) => pair,
                    Err(e) => return engine_op_error(e),
                };
                json_response(&serde_json::json!({
                    "entity": record.entity,
                    "verdict": record.verdict,
                    "check_state": state.as_str(),
                    "role": record.role,
                    "ts": record.ts,
                    "method": record.method,
                }))
            }
            Err(e) => engine_op_error(e),
        }
    }

    #[tool(
        name = "memstead_overview",
        description = "Start here — the cold-start entry point for a Memstead engine. Returns the schema catalogue, the mem inventory, and the community clusters as Markdown. Every visible mem is listed under `## Mems`: a writable mem carries a `durable` flag and `storage` kind (an in-memory sketch reads `durable: false` / `storage: in-memory` — writes are volatile, evicted on session-TTL / restart), and a read-only mount carries `Access: read-only`, its deployment-declared trust `Origin` (`first-party` / `third-party`), and its own entity count. Per-mem counts, `_entity_count`, and the communities section always agree — one rendering authority. Schemas list as `{ref, description}` only — call `memstead_schema(name=<ref>)` for full per-type bodies. Token-budget-driven: hard-required content (mems, schema, community titles) always ships; heavy content greedy-fills the remaining budget by default-priority. Anything that didn't fit is advertised under `## Hints` with `estimated_tokens`; re-query by passing `key` into `include[]`. Allowed `include` keys: `community_members`, `community_bridges`, `mem_distribution`, `dangling_links`. `mem` scopes the roster, schema anchor, and communities to any one visible mem (a read-only mount included); a name matching no visible mem returns `UNKNOWN_MEM` whose list names every visible mem. Set `rebuild: true` to invalidate the community memo before computing — it recomputes the whole-graph Louvain partition (detection is global; there is no per-subgraph scoping). A small or disconnected subgraph may surface as no cluster: sparsely-connected / edge-less nodes collapse into a single catch-all rather than forming their own cluster. This surface carries no mem-lifecycle tools, so the `## Lifecycle Namespaces` section is omitted. Frontmatter `_overview_mode` is \"complete\", \"reduced\", or \"overbudget\"; `_mem_schema` appears only under a `mem` filter; `_workspace_root` is the serving engine's absolute workspace path (omitted for rootless in-memory engines).",
        annotations(
            read_only_hint = true,
            destructive_hint = false,
            idempotent_hint = true,
            open_world_hint = false
        )
    )]
    fn memstead_overview(&self, Parameters(p): Parameters<OverviewParams>) -> CallToolResult {
        // The lean surface renders the identical overview through the one shared
        // composer in `memstead_base::overview` (relocated there so this
        // no-`memstead-engine` build can reach it). The hand-rolled single-mem
        // renderer is gone: with one rendering authority the roster,
        // `_entity_count`, and the communities section can never disagree, and a
        // read-only mount appears with its `Access: read-only` / `Origin` lines
        // instead of being dropped. `suppress_lifecycle` is set because this
        // surface carries no mem-lifecycle tools, so naming them would be false.
        let mut engine = crate::lock_engine!(self.engine);
        let include = p.include.clone().unwrap_or_default();
        let args = memstead_base::overview::OverviewArgs {
            include: &include,
            mem: p.mem.as_deref(),
            rebuild: p.rebuild.unwrap_or(false) && p.chunk.unwrap_or(1) <= 1,
            token_budget: p
                .token_budget
                .unwrap_or(memstead_base::overview::DEFAULT_OVERVIEW_BUDGET),
            operator_mode: false,
            suppress_lifecycle: true,
        };
        match memstead_base::overview::compose_overview(
            &mut engine,
            args,
            memstead_base::overview::Surface::Mcp,
        ) {
            Ok(out) => md_response(out.markdown),
            Err(memstead_base::overview::ComposeOverviewError::InvalidIncludeKeySchemaTypes) => {
                tool_error(
                    "INVALID_INPUT",
                    "include key 'schema_types' was removed; \
                     call memstead_schema(name=...) for full schema bodies.",
                )
            }
            Err(memstead_base::overview::ComposeOverviewError::MemQuarantined(name)) => {
                engine_op_error(engine.unknown_mem_error(&name))
            }
            Err(memstead_base::overview::ComposeOverviewError::UnknownMem {
                name,
                writable_mems,
            }) => tool_error_with_details(
                "UNKNOWN_MEM",
                &format!(
                    "unknown mem: \"{name}\". Visible mems: [{}]",
                    writable_mems.join(", ")
                ),
                Some(serde_json::json!({ "name": name, "visible_mems": writable_mems })),
            ),
        }
    }
}

/// The lean (filesystem-mem) server's session-start instructions —
/// one named const so the registry-honesty tests read the SAME string
/// the handler serves. Built with `concat!` so the engine version is
/// baked in at compile time; the roster must name every tool this
/// flavour registers (bidirectionally test-enforced).
pub const FS_SERVER_INSTRUCTIONS: &str = concat!(
    "Memstead: schema-agnostic graph engine over typed, interconnected markdown entities. Each mem is a typed model of a chosen subject — its modal flavour (knowledge, planning, inquiry, spec, or any mix) follows from the schema the mem pins. Granularity: a mem is the packaged unit — a whole typed model, designed for 1,000-5,000 entities (operating costs measured in docs/sizing-curve.md; larger holdings work at proportionally higher load cost); an entity is never called a mem (a mem is not one 'memory'/fact). Cold-start: call memstead_overview first for the schema catalogue and mem inventory; read a mem's schema via memstead_schema before mutating.",
    " Engine version: ",
    env!("CARGO_PKG_VERSION"),
    " — serverInfo.version carries the same value; a version different from your last session means this surface may have changed: re-read the roster below. Tool roster (complete, 13 tools): READ — memstead_overview (workspace dashboard: schemas, mems, communities, quarantine roster), memstead_entity (one entity + _hash), memstead_search (text + metadata filter), memstead_schema (the pinned schema, lite/full), memstead_health (drift, conformance, quarantine roster, boot diagnosis), memstead_diff (two-ref structural diff), memstead_changes_since (change deltas for incremental sync). WRITE — memstead_create, memstead_update, memstead_relate, memstead_rename, memstead_delete (entity mutations, optimistic _hash locking). PROCESS — memstead_check (record a check of one entity: verdict ok|failed with method note; never a mutation — derived check state serves in memstead_entity's opt-in provenance block). CLI companion: the `memstead` CLI serves this same engine with verb families that deliberately live only there — bulk mutation (batch-create, batch-update, batch-relate: reach for these instead of looping single MCP mutation calls when writing many entities), archive export (export), distribution/registry (publish, unpublish, login, logout, domain), workspace bootstrap and repair (init, quickstart, projection migrate, schema install), and read/report verbs (status, list, context, due — the due-brief: open entities whose schema-declared due date falls inside a window, overdue first). If a task feels like N repetitive single-entity calls, check the CLI first."
);

#[tool_handler(router = FilesystemMcpServer::tool_router())]
impl ServerHandler for FilesystemMcpServer {
    /// Hand-written so `instructions` can be the named
    /// [`FS_SERVER_INSTRUCTIONS`] const (the macro only accepts string
    /// literals) and the serverInfo version is the engine's full
    /// build version (semver + git build sha for dev builds) by
    /// construction — the historical hardcoded `"0.1.0"` cannot recur,
    /// and two dev builds between releases stay distinguishable.
    fn get_info(&self) -> rmcp::model::ServerInfo {
        rmcp::model::ServerInfo::new(
            rmcp::model::ServerCapabilities::builder()
                .enable_tools()
                .build(),
        )
        .with_server_info(rmcp::model::Implementation::new(
            "memstead-mcp",
            memstead_base::build_info::full_version(),
        ))
        .with_instructions(FS_SERVER_INSTRUCTIONS.to_string())
    }

    async fn initialize(
        &self,
        request: InitializeRequestParams,
        context: RequestContext<RoleServer>,
    ) -> Result<InitializeResult, McpError> {
        let info = request.client_info.clone();
        let cid = ClientId {
            name: info.name.clone(),
            version: info.version.clone(),
        };
        let _ = self.client.set(cid);
        if context.peer.peer_info().is_none() {
            context.peer.set_peer_info(request);
        }
        Ok(self.get_info())
    }

    async fn list_tools(
        &self,
        _request: Option<PaginatedRequestParams>,
        _context: RequestContext<RoleServer>,
    ) -> Result<ListToolsResult, McpError> {
        let tools: Vec<Tool> = Self::tool_router().list_all();
        Ok(ListToolsResult {
            tools,
            meta: None,
            next_cursor: None,
        })
    }

    /// Friction-ledger seam (agent-trust plan 08), mirroring the full
    /// flavour: every dispatched typed refusal appends one
    /// content-free ledger entry, best-effort, after the response is
    /// built.
    async fn call_tool(
        &self,
        request: CallToolRequestParams,
        context: RequestContext<RoleServer>,
    ) -> Result<CallToolResult, McpError> {
        let verb = request.name.to_string();
        let tcc = rmcp::handler::server::tool::ToolCallContext::new(self, request, context);
        let result = Self::tool_router().call(tcc).await;
        if let Ok(r) = &result
            && r.is_error.unwrap_or(false)
            && let Some(code) = r
                .structured_content
                .as_ref()
                .and_then(|v| v.get("code"))
                .and_then(|c| c.as_str())
        {
            let details = r.structured_content.as_ref().and_then(|v| v.get("details"));
            memstead_base::friction::FrictionLedger::for_workspace(&self.workspace_root).record(
                "mcp",
                &verb,
                code,
                memstead_base::friction::closed_reason(code, details),
            );
        }
        result
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::tools::mutation::RelateOpInput;
    use indexmap::IndexMap;
    use memstead_base::filesystem::config::{WorkspaceConfig, write_workspace_config};
    use memstead_schema::SchemaRef;
    use rmcp::handler::server::wrapper::Parameters;
    use tempfile::TempDir;

    /// The lean MCP error map must emit the same wire code as
    /// `EngineError::code()` — the single source every surface (full MCP,
    /// CLI, wasm) follows. `Backend` and `ParseAfterWrite` historically
    /// shipped `MEM_WRITER_ERROR` / `PARSE_AFTER_WRITE` here, diverging
    /// from `code()`'s `MEM_ERROR` / `PARSE_ERROR`. Pin them so a
    /// re-divergence fails the build.
    #[test]
    fn lean_backend_and_parse_after_write_codes_follow_code_contract() {
        let cases: Vec<EngineError> = vec![
            EngineError::Backend(memstead_base::backend::BackendError::Other("disk".into())),
            EngineError::ParseAfterWrite("boom".into()),
        ];
        for err in cases {
            let expected = err.code();
            let result = engine_op_error(err);
            let code = result
                .structured_content
                .as_ref()
                .and_then(|v| v.get("code"))
                .and_then(|c| c.as_str())
                .expect("error envelope carries structured.code")
                .to_string();
            assert_eq!(
                code, expected,
                "lean error-map code drifted from EngineError::code()"
            );
        }
    }

    /// `memstead_relate` is idempotent on the lean surface, matching the
    /// mem-repo server: duplicate-add and remove-nonexistent are
    /// typed-warning no-ops, so a retry converges. The full-side
    /// annotation meta-test is `mem-repo`-gated; this lean-side test
    /// pins the parity so the two flavours cannot silently re-diverge.
    #[test]
    fn relate_annotation_is_idempotent_on_lean() {
        let tools = FilesystemMcpServer::tool_router().list_all();
        let relate = tools
            .iter()
            .find(|t| t.name == "memstead_relate")
            .expect("memstead_relate is on the lean surface");
        let ann = relate
            .annotations
            .as_ref()
            .expect("memstead_relate sets annotation hints");
        assert_eq!(
            ann.idempotent_hint,
            Some(true),
            "lean memstead_relate idempotent_hint must match the mem-repo server's `true`"
        );
    }

    fn write_workspace(tmp: &TempDir, name: &str) {
        let pin: SchemaRef = "default@1.0.0".parse().unwrap();
        let cfg = WorkspaceConfig::new(name, pin.clone());
        write_workspace_config(tmp.path(), &cfg).unwrap();
        // Two-layer file adapter markers — `Engine::from_workspace_root`
        // recognises a workspace by `.memstead/workspace.toml` plus the
        // mount list in `.memstead/state/mounts.json`.
        let memstead = tmp.path().join(".memstead");
        std::fs::write(
            memstead.join("workspace.toml"),
            "format = \"memstead-git-branch-2\"\n\n[persistence_adapter]\nname = \"file-two-layer\"\n",
        )
        .unwrap();
        let workspace = memstead_base::Workspace {
            mounts: vec![memstead_base::Mount {
                mem: name.to_string(),
                schema: Some(pin),
                storage: memstead_base::MountStorage::Folder {
                    path: tmp.path().to_path_buf(),
                },
                capability: memstead_base::MountCapability::Write,
                lifecycle: memstead_base::MountLifecycle::Eager,
                cross_linkable: true,
                migration_target: None,
            }],
            settings: memstead_base::WorkspaceSettings::default(),
        };
        use memstead_base::WorkspaceStoreAdapter;
        memstead_base::FileWorkspaceStore::new()
            .save_state(tmp.path(), &workspace)
            .unwrap();
    }

    #[test]
    fn poisoned_engine_lock_returns_typed_envelope_not_panic() {
        let tmp = TempDir::new().unwrap();
        write_workspace(&tmp, "demo");
        let server = FilesystemMcpServer::from_workspace_root(tmp.path()).unwrap();

        // Poison the engine mutex for real: a thread panics while
        // holding the guard.
        let engine = server.engine.clone();
        std::thread::spawn(move || {
            let _guard = engine.lock().unwrap();
            panic!("deliberate poison");
        })
        .join()
        .unwrap_err();

        let result = server.memstead_overview(Parameters(OverviewParams {
            rebuild: None,
            chunk: None,
            mem: None,
            include: None,
            token_budget: None,
        }));
        assert_eq!(result.is_error, Some(true));
        let code = result
            .structured_content
            .as_ref()
            .and_then(|v| v.get("code"))
            .and_then(|c| c.as_str())
            .unwrap();
        assert_eq!(code, "ENGINE_LOCK_POISONED");
    }

    #[test]
    fn create_then_entity_round_trip() {
        let tmp = TempDir::new().unwrap();
        write_workspace(&tmp, "demo");
        let server = FilesystemMcpServer::from_workspace_root(tmp.path()).unwrap();

        // memstead_create — the engine refuses on missing required
        // sections, so seed `identity` + `purpose` so the spec lands.
        let mut sections = IndexMap::new();
        sections.insert("identity".to_string(), "first identity".to_string());
        sections.insert("purpose".to_string(), "first purpose".to_string());
        let create_params = CreateParams {
            anchors: None,
            title: "First".to_string(),
            entity_type: "spec".to_string(),
            mem: None,
            sections: Some(sections),
            metadata: None,
            relations: None,
            dry_run: None,
            note: Some("first via mcp".to_string()),
            role: None,
        };
        let create_result = server.memstead_create(Parameters(create_params));
        assert!(
            !create_result.is_error.unwrap_or(false),
            "create must succeed: {:?}",
            create_result.structured_content,
        );
        let create_body = create_result
            .structured_content
            .as_ref()
            .expect("structured content");
        let id = create_body["id"].as_str().unwrap().to_string();
        assert_eq!(id, "demo--first");

        // Changelog has the note.
        let log =
            std::fs::read_to_string(tmp.path().join(".memstead").join("changes.jsonl")).unwrap();
        assert!(log.contains("\"note\":\"first via mcp\""));

        // memstead_entity
        let entity_params = EntityParams {
            id: id.clone(),
            sections: None,
            include_relations: None,
            include_context: None,
            token_budget: None,
            chunk: None,
            include_provenance: None,
        };
        let entity_result = server.memstead_entity(Parameters(entity_params));
        assert!(!entity_result.is_error.unwrap_or(false));
        let text = match entity_result.content.first() {
            Some(c) => match c.as_text() {
                Some(t) => t.text.clone(),
                None => panic!("expected text"),
            },
            None => panic!("expected at least one content"),
        };
        assert!(text.contains("# First"));
        assert!(text.contains("_hash:"));
    }

    /// Build a two-mount engine — a writable in-memory `sketch` mem
    /// (declared first) and a read-only in-memory `content` mem — so the
    /// create handler's multi-mount mem resolution is exercised at this
    /// layer. Mirrors the session server's two-tier shape.
    fn two_mount_engine() -> memstead_base::Engine {
        use memstead_base::backend::MemBackend;
        use memstead_base::storage::InMemoryBackend;
        use memstead_base::{Mount, MountCapability, MountLifecycle, MountStorage};
        let pin: SchemaRef = "default@1.0.0".parse().unwrap();
        let build = |name: &str, cap: MountCapability| -> (Mount, Box<dyn MemBackend>) {
            let backend = InMemoryBackend::new();
            let cfg = format!(r#"{{"version":"0.1.0","schema":"{pin}"}}"#).into_bytes();
            backend.write_mem_config(&cfg).unwrap();
            let mount = Mount {
                mem: name.to_string(),
                schema: Some(pin.clone()),
                storage: MountStorage::InMemory,
                capability: cap,
                lifecycle: MountLifecycle::Eager,
                cross_linkable: true,
                migration_target: None,
            };
            (mount, Box::new(backend) as Box<dyn MemBackend>)
        };
        memstead_base::Engine::from_mounts(vec![
            build("sketch", MountCapability::Write),
            build("content", MountCapability::ReadOnly),
        ])
        .unwrap()
    }

    fn spec_sections() -> Option<IndexMap<String, String>> {
        let mut s = IndexMap::new();
        s.insert("identity".to_string(), "i".to_string());
        s.insert("purpose".to_string(), "p".to_string());
        Some(s)
    }

    fn create_params(title: &str, mem: Option<&str>) -> CreateParams {
        CreateParams {
            anchors: None,
            title: title.to_string(),
            entity_type: "spec".to_string(),
            mem: mem.map(String::from),
            sections: spec_sections(),
            metadata: None,
            relations: None,
            dry_run: None,
            note: None,
            role: None,
        }
    }

    /// Multi-mount create-targeting: with a writable `sketch` and a
    /// read-only `content` mem mounted together, an omitted `mem` lands
    /// in the writable mount (not the alphabetically-first read-only one);
    /// an explicit read-only target is refused with READ_ONLY_MOUNT rather
    /// than silently redirected; an explicit writable target is honoured.
    #[test]
    fn create_resolves_target_mem_across_multiple_mounts() {
        let server =
            FilesystemMcpServer::from_engine(two_mount_engine(), std::path::PathBuf::new());

        // Omitted mem → default writable mount (`sketch`).
        let r = server.memstead_create(Parameters(create_params("Default Target", None)));
        assert!(
            !r.is_error.unwrap_or(false),
            "omitted-mem create must land in the writable mount: {:?}",
            r.structured_content
        );
        assert_eq!(
            r.structured_content.as_ref().unwrap()["id"].as_str(),
            Some("sketch--default-target"),
            "create defaults to the writable mem, not the read-only one"
        );

        // Explicit read-only mem → typed refusal, not a redirect.
        let r = server.memstead_create(Parameters(create_params("Into Content", Some("content"))));
        assert!(
            r.is_error.unwrap_or(false),
            "write to a read-only mount must refuse"
        );
        assert_eq!(
            r.structured_content.unwrap()["code"],
            "READ_ONLY_MOUNT",
            "the engine capability layer refuses the read-only target"
        );

        // Explicit writable mem → honoured.
        let r =
            server.memstead_create(Parameters(create_params("Explicit Sketch", Some("sketch"))));
        assert!(
            !r.is_error.unwrap_or(false),
            "explicit writable target must land: {:?}",
            r.structured_content
        );
        assert_eq!(
            r.structured_content.as_ref().unwrap()["id"].as_str(),
            Some("sketch--explicit-sketch")
        );
    }

    /// Plan 03, Part B: params this surface hardwires off are REFUSED with
    /// a typed `UNSUPPORTED_PARAM` naming them — never silently dropped. The
    /// `dry_run` case is the load-bearing one: silently treating it as a real
    /// write would land an entity the agent thought was a preview.
    #[test]
    fn unsupported_write_params_refuse_rather_than_silently_drop() {
        use crate::tools::mutation::RelationInput;
        let tmp = TempDir::new().unwrap();
        write_workspace(&tmp, "demo");
        let server = FilesystemMcpServer::from_workspace_root(tmp.path()).unwrap();

        let dropped = |r: &CallToolResult| -> Vec<String> {
            r.structured_content.as_ref().unwrap()["details"]["params"]
                .as_array()
                .unwrap()
                .iter()
                .map(|v| v.as_str().unwrap().to_string())
                .collect()
        };
        let is_unsupported = |r: &CallToolResult| {
            r.is_error.unwrap_or(false)
                && r.structured_content.as_ref().unwrap()["code"] == "UNSUPPORTED_PARAM"
        };

        // create + dry_run: true → refused up front; nothing lands.
        let mut p = create_params("Preview Me", None);
        p.dry_run = Some(true);
        let r = server.memstead_create(Parameters(p));
        assert!(is_unsupported(&r), "dry_run create must refuse: {r:?}");
        assert!(dropped(&r).contains(&"dry_run".to_string()));
        // The refusal precedes the engine, so the preview entity never lands.
        let entity = server.memstead_entity(Parameters(EntityParams {
            id: "demo--preview-me".into(),
            include_relations: None,
            include_context: None,
            sections: None,
            token_budget: None,
            chunk: None,
            include_provenance: None,
        }));
        assert!(
            entity.is_error.unwrap_or(false),
            "a refused dry_run must NOT have created the entity"
        );

        // create + non-empty relations → refused, naming relations.
        let mut p = create_params("With Edges", None);
        p.relations = Some(vec![RelationInput {
            to: "demo--target".into(),
            r#type: "REFERENCES".into(),
            description: None,
        }]);
        let r = server.memstead_create(Parameters(p));
        assert!(is_unsupported(&r));
        assert!(dropped(&r).contains(&"relations".to_string()));

        // update + each unsupported param → refused naming it.
        let base = || UpdateParams {
            anchors: None,
            id: "demo--anything".into(),
            expected_hash: "deadbeef".into(),
            sections: None,
            append_sections: None,
            patch_sections: None,
            metadata: None,
            metadata_unset: None,
            dry_run: None,
            declare_relations: None,
            relations_unset: None,
            anchors_unset: None,
            note: None,
            role: None,
        };
        let mut u = base();
        u.append_sections = Some(IndexMap::from([("purpose".to_string(), "x".to_string())]));
        let r = server.memstead_update(Parameters(u));
        assert!(is_unsupported(&r));
        assert!(dropped(&r).contains(&"append_sections".to_string()));

        let mut u = base();
        u.patch_sections = Some(IndexMap::from([(
            "purpose".to_string(),
            crate::tools::mutation::PatchInput {
                old: "a".into(),
                new: "b".into(),
                all: None,
            },
        )]));
        let r = server.memstead_update(Parameters(u));
        assert!(is_unsupported(&r));
        assert!(dropped(&r).contains(&"patch_sections".to_string()));

        let mut u = base();
        u.dry_run = Some(true);
        let r = server.memstead_update(Parameters(u));
        assert!(is_unsupported(&r));
        assert!(dropped(&r).contains(&"dry_run".to_string()));

        // relate + dry_run: true → refused up front (the unified
        // engine's rehearsal contract does NOT silently erode into a
        // real write here); dry_run absent / false stays served.
        let relate = |dry: Option<bool>| {
            server.memstead_relate(Parameters(crate::tools::mutation::RelateParams {
                relations: vec![crate::tools::mutation::RelateOpInput {
                    from: "demo--anything".into(),
                    to: "demo--other".into(),
                    r#type: "REFERENCES".into(),
                    remove: None,
                    description: None,
                }],
                note: None,
                role: None,
                dry_run: dry,
            }))
        };
        let r = relate(Some(true));
        assert!(is_unsupported(&r), "dry_run relate must refuse: {r:?}");
        assert!(dropped(&r).contains(&"dry_run".to_string()));
        // dry_run: false / absent is not a meaningful supply — the
        // call proceeds to the engine (and fails only on the missing
        // source entity, not on UNSUPPORTED_PARAM).
        let r = relate(Some(false));
        assert!(
            !(r.is_error.unwrap_or(false)
                && r.structured_content.as_ref().unwrap()["code"] == "UNSUPPORTED_PARAM"),
            "dry_run: false must not refuse: {r:?}"
        );
    }

    /// The `open_questions` axis on the lean flavour (agent-trust
    /// plan 11): include-gated — absent without the include, an
    /// empty per-mem worklist with it, never an error on a hole-free
    /// mem.
    #[test]
    fn open_questions_axis_is_include_gated_on_lean() {
        let tmp = TempDir::new().unwrap();
        write_workspace(&tmp, "demo");
        let server = FilesystemMcpServer::from_workspace_root(tmp.path()).unwrap();

        let plain = server.memstead_health(Parameters(HealthParams::default()));
        assert!(!plain.is_error.unwrap_or(false));
        assert!(
            plain
                .structured_content
                .as_ref()
                .unwrap()
                .get("open_questions")
                .is_none(),
            "axis must be include-gated on lean"
        );

        let served = server.memstead_health(Parameters(HealthParams {
            include: Some(vec!["open_questions".to_string()]),
            ..Default::default()
        }));
        assert!(!served.is_error.unwrap_or(false));
        let axis = &served.structured_content.as_ref().unwrap()["open_questions"];
        assert_eq!(axis["_item_cap"], 20, "{axis}");
        assert_eq!(axis["demo"]["total_open"], 0, "{axis}");
    }

    /// Refusal complement (Part B): a defaulted-empty / absent unsupported
    /// param is left alone — the surface stays backward-compatible for a
    /// caller that harmlessly passes nothing. A plain create/update with the
    /// supported params still succeeds.
    #[test]
    fn absent_unsupported_params_do_not_refuse() {
        let tmp = TempDir::new().unwrap();
        write_workspace(&tmp, "demo");
        let server = FilesystemMcpServer::from_workspace_root(tmp.path()).unwrap();

        // create with dry_run: None / relations: None → no UNSUPPORTED_PARAM.
        let r = server.memstead_create(Parameters(create_params("Plain Create", None)));
        assert!(
            !r.is_error.unwrap_or(false),
            "a default create must not be refused: {r:?}"
        );
        // dry_run: Some(false) is the caller intending no preview — also fine.
        let mut p = create_params("Explicit No Preview", None);
        p.dry_run = Some(false);
        let r = server.memstead_create(Parameters(p));
        assert!(
            !r.is_error.unwrap_or(false),
            "dry_run: false must not be refused: {r:?}"
        );
    }

    #[test]
    fn create_rejects_unknown_type_with_typed_code() {
        let tmp = TempDir::new().unwrap();
        write_workspace(&tmp, "demo");
        let server = FilesystemMcpServer::from_workspace_root(tmp.path()).unwrap();

        let result = server.memstead_create(Parameters(CreateParams {
            anchors: None,
            title: "X".into(),
            entity_type: "totally-not-a-type".into(),
            mem: None,
            sections: None,
            metadata: None,
            relations: None,
            dry_run: None,
            note: None,
            role: None,
        }));
        assert!(result.is_error.unwrap_or(false));
        let body = result.structured_content.unwrap();
        assert_eq!(body["code"], "UNKNOWN_ENTITY_TYPE");
    }

    /// Smoke-test probe A: a memo created with sections that belong
    /// to a different type (here `identity` + `purpose`, which are
    /// `spec` sections, not `memo`'s `claim` + `context`) must reject
    /// with `UNKNOWN_SECTION` before any disk write lands.
    #[test]
    fn create_rejects_unknown_section_keys() {
        let tmp = TempDir::new().unwrap();
        write_workspace(&tmp, "demo");
        let server = FilesystemMcpServer::from_workspace_root(tmp.path()).unwrap();

        let mut sections = IndexMap::new();
        sections.insert("identity".to_string(), "Some text".to_string());
        sections.insert("purpose".to_string(), "Other text".to_string());

        let result = server.memstead_create(Parameters(CreateParams {
            anchors: None,
            title: "Stray Memo".into(),
            entity_type: "memo".into(),
            mem: None,
            sections: Some(sections),
            metadata: None,
            relations: None,
            dry_run: None,
            note: None,
            role: None,
        }));
        assert!(result.is_error.unwrap_or(false));
        let body = result.structured_content.unwrap();
        assert_eq!(body["code"], "UNKNOWN_SECTION");
        // The first offender hits first; either key would be valid.
        let bad_key = body["details"]["key"].as_str().unwrap();
        assert!(
            bad_key == "identity" || bad_key == "purpose",
            "expected identity/purpose, got {bad_key}"
        );
        // No file should have been written.
        assert!(
            !tmp.path().join("stray-memo.md").exists(),
            "stray memo should not have been persisted"
        );
    }

    /// Smoke-test probe B: a memo with no sections at all should
    /// succeed (required-section gaps are Tier-2 warnings, not hard
    /// errors), but the response must carry a `MISSING_REQUIRED_SECTION`
    /// warning per missing required section so the agent can
    /// self-correct.
    #[test]
    fn create_refuses_missing_required_section_with_typed_envelope() {
        // `memstead_create` refuses on missing required sections instead
        // of emitting warnings. Pre-fix the entity landed with empty
        // placeholders for each missing required section and the
        // install-time strict validator could later refuse the
        // resulting archive — the export-then-install round-trip
        // broke. Now the refusal fires at the write boundary.
        let tmp = TempDir::new().unwrap();
        write_workspace(&tmp, "demo");
        let server = FilesystemMcpServer::from_workspace_root(tmp.path()).unwrap();

        let result = server.memstead_create(Parameters(CreateParams {
            anchors: None,
            title: "Empty Memo".into(),
            entity_type: "memo".into(),
            mem: None,
            sections: Some(IndexMap::new()),
            metadata: None,
            relations: None,
            dry_run: None,
            note: None,
            role: None,
        }));
        assert!(result.is_error.unwrap_or(false), "create must refuse");
        let body = result.structured_content.unwrap();
        assert_eq!(body["code"], "MISSING_REQUIRED_SECTION");
        assert_eq!(body["details"]["entity_type"], "memo");
        assert!(
            body["details"]["sections"]
                .as_array()
                .map_or(0, |s| s.len())
                >= 1,
            "details.sections must list at least one missing key, got: {body}"
        );
        assert!(
            body["details"]["type_guidance"].is_object(),
            "details.type_guidance must be a map, got: {body}"
        );
    }

    /// Smoke-test probe C: an out-of-enum metadata value (`level: "Z3"`
    /// against the `M0|M1|M2|M3` allowed set) must reject with
    /// `INVALID_ENUM_VALUE`.
    #[test]
    fn create_rejects_out_of_enum_metadata_value() {
        let tmp = TempDir::new().unwrap();
        write_workspace(&tmp, "demo");
        let server = FilesystemMcpServer::from_workspace_root(tmp.path()).unwrap();

        let mut metadata = IndexMap::new();
        metadata.insert("level".to_string(), "Z3".to_string());

        let result = server.memstead_create(Parameters(CreateParams {
            anchors: None,
            title: "Bad Level".into(),
            entity_type: "spec".into(),
            mem: None,
            sections: None,
            metadata: Some(metadata),
            relations: None,
            dry_run: None,
            note: None,
            role: None,
        }));
        assert!(result.is_error.unwrap_or(false));
        let body = result.structured_content.unwrap();
        assert_eq!(body["code"], "INVALID_ENUM_VALUE");
        assert_eq!(body["details"]["field"], "level");
        assert_eq!(body["details"]["value"], "Z3");
    }

    /// Unknown metadata fields surface `UNKNOWN_METADATA_FIELD`. The
    /// mem-repo path emits the same code; this guard pins the
    /// filesystem-mem contract so future refactors don't silently
    /// drop the gate.
    #[test]
    fn create_rejects_unknown_metadata_field() {
        let tmp = TempDir::new().unwrap();
        write_workspace(&tmp, "demo");
        let server = FilesystemMcpServer::from_workspace_root(tmp.path()).unwrap();

        let mut metadata = IndexMap::new();
        metadata.insert("nonsense".to_string(), "value".to_string());

        let result = server.memstead_create(Parameters(CreateParams {
            anchors: None,
            title: "Stray Field".into(),
            entity_type: "spec".into(),
            mem: None,
            sections: None,
            metadata: Some(metadata),
            relations: None,
            dry_run: None,
            note: None,
            role: None,
        }));
        assert!(result.is_error.unwrap_or(false));
        let body = result.structured_content.unwrap();
        assert_eq!(body["code"], "UNKNOWN_METADATA_FIELD");
        assert_eq!(body["details"]["key"], "nonsense");
    }

    #[test]
    fn entity_not_found_returns_typed_code() {
        let tmp = TempDir::new().unwrap();
        write_workspace(&tmp, "demo");
        let server = FilesystemMcpServer::from_workspace_root(tmp.path()).unwrap();

        let result = server.memstead_entity(Parameters(EntityParams {
            id: "demo--ghost".into(),
            sections: None,
            include_relations: None,
            include_context: None,
            token_budget: None,
            chunk: None,
            include_provenance: None,
        }));
        assert!(result.is_error.unwrap_or(false));
        let body = result.structured_content.unwrap();
        assert_eq!(body["code"], "ENTITY_NOT_FOUND");
    }

    fn seed_via_mcp(server: &FilesystemMcpServer, title: &str) -> (String, String) {
        // The
        // engine refuses on missing required sections. Seed the
        // `spec` type's required `identity` + `purpose` sections so
        // wire-shape tests using this helper continue to land valid
        // entities.
        let mut seeded_sections = IndexMap::new();
        seeded_sections.insert("identity".to_string(), "seed identity".to_string());
        seeded_sections.insert("purpose".to_string(), "seed purpose".to_string());
        let result = server.memstead_create(Parameters(CreateParams {
            anchors: None,
            title: title.into(),
            entity_type: "spec".into(),
            mem: None,
            sections: Some(seeded_sections),
            metadata: None,
            relations: None,
            dry_run: None,
            note: None,
            role: None,
        }));
        assert!(
            !result.is_error.unwrap_or(false),
            "seed_via_mcp must succeed; got error: {:?}",
            result.structured_content,
        );
        let body = result.structured_content.unwrap();
        (
            body["id"].as_str().unwrap().to_string(),
            body["_hash"].as_str().unwrap().to_string(),
        )
    }

    #[test]
    fn update_replaces_section_and_returns_new_hash() {
        let tmp = TempDir::new().unwrap();
        write_workspace(&tmp, "demo");
        let server = FilesystemMcpServer::from_workspace_root(tmp.path()).unwrap();
        let (id, hash) = seed_via_mcp(&server, "Updatable");

        let mut sections = indexmap::IndexMap::new();
        sections.insert("identity".to_string(), "Updated body.".to_string());
        let result = server.memstead_update(Parameters(UpdateParams {
            anchors: None,
            relations_unset: None,
            anchors_unset: None,
            id: id.clone(),
            expected_hash: hash.clone(),
            sections: Some(sections),
            append_sections: None,
            patch_sections: None,
            metadata: None,
            metadata_unset: None,
            dry_run: None,
            note: Some("touched body".into()),
            role: None,
            declare_relations: None,
        }));
        assert!(!result.is_error.unwrap_or(false));
        let body = result.structured_content.unwrap();
        let new_hash = body["_hash"].as_str().unwrap();
        assert_ne!(new_hash, hash);
        assert_eq!(body["modified_sections"][0], "identity");
    }

    #[test]
    fn update_rejects_stale_hash_with_typed_code() {
        let tmp = TempDir::new().unwrap();
        write_workspace(&tmp, "demo");
        let server = FilesystemMcpServer::from_workspace_root(tmp.path()).unwrap();
        let (id, _hash) = seed_via_mcp(&server, "Pinned");

        let result = server.memstead_update(Parameters(UpdateParams {
            anchors: None,
            relations_unset: None,
            anchors_unset: None,
            id,
            expected_hash: "0000000000".into(),
            sections: None,
            append_sections: None,
            patch_sections: None,
            metadata: None,
            metadata_unset: None,
            dry_run: None,
            note: None,
            role: None,
            declare_relations: None,
        }));
        assert!(result.is_error.unwrap_or(false));
        let body = result.structured_content.unwrap();
        assert_eq!(body["code"], "HASH_MISMATCH");
        assert!(body["details"]["current"].is_string());
    }

    /// `memstead_update` must reject any attempt to mutate the read-only
    /// metadata triple (`mem`, `id`, `type`) on either set or unset
    /// — the entity-id contract depends on those staying stable.
    #[test]
    fn update_rejects_read_only_metadata_set() {
        let tmp = TempDir::new().unwrap();
        write_workspace(&tmp, "demo");
        let server = FilesystemMcpServer::from_workspace_root(tmp.path()).unwrap();
        let (id, hash) = seed_via_mcp(&server, "Locked");

        for field in ["mem", "id", "type"] {
            let mut metadata = IndexMap::new();
            metadata.insert(field.to_string(), "garbage".to_string());
            let result = server.memstead_update(Parameters(UpdateParams {
                anchors: None,
                relations_unset: None,
                anchors_unset: None,
                id: id.clone(),
                expected_hash: hash.clone(),
                sections: None,
                append_sections: None,
                patch_sections: None,
                metadata: Some(metadata),
                metadata_unset: None,
                dry_run: None,
                note: None,
                role: None,
                declare_relations: None,
            }));
            assert!(
                result.is_error.unwrap_or(false),
                "set of {field} should error"
            );
            let body = result.structured_content.unwrap();
            assert_eq!(body["code"], "READ_ONLY_FIELD");
            assert_eq!(body["details"]["field"], field);
        }
    }

    /// `metadata_unset` is the asymmetric half of the reservation:
    /// unsetting a reserved key is ALLOWED (the sanctioned repair for a
    /// historically smuggled key — on a healthy entity it is a
    /// committed-nothing no-op, and `type` is engine-re-seeded so the
    /// entity never goes typeless), while the engine-stamped timestamp
    /// fields stay refused on unset.
    #[test]
    fn update_allows_reserved_metadata_unset_but_refuses_timestamp_unset() {
        let tmp = TempDir::new().unwrap();
        write_workspace(&tmp, "demo");
        let server = FilesystemMcpServer::from_workspace_root(tmp.path()).unwrap();
        let (id, hash) = seed_via_mcp(&server, "Unsettable");

        let unset_params = |keys: Vec<&str>| {
            Parameters(UpdateParams {
                anchors: None,
                relations_unset: None,
                anchors_unset: None,
                id: id.clone(),
                expected_hash: hash.clone(),
                sections: None,
                append_sections: None,
                patch_sections: None,
                metadata: None,
                metadata_unset: Some(keys.into_iter().map(String::from).collect()),
                dry_run: None,
                note: None,
                role: None,
                declare_relations: None,
            })
        };

        // Reserved triple: unset succeeds. On this healthy entity it is
        // a no-op (nothing was smuggled), surfaced as UPDATE_NOOP.
        for field in ["type", "mem", "id"] {
            let result = server.memstead_update(unset_params(vec![field]));
            assert!(
                !result.is_error.unwrap_or(false),
                "unset of reserved '{field}' must be allowed (repair route)"
            );
            let body = result.structured_content.unwrap();
            assert!(
                body["warnings"]
                    .as_array()
                    .is_some_and(|w| w.iter().any(|e| e["code"] == "UPDATE_NOOP")),
                "healthy-entity reserved unset is a no-op: {body}"
            );
        }

        // Engine-stamped timestamps: unset still refuses.
        let result = server.memstead_update(unset_params(vec!["last_modified"]));
        assert!(result.is_error.unwrap_or(false));
        let body = result.structured_content.unwrap();
        assert_eq!(body["code"], "READ_ONLY_FIELD");
        assert_eq!(body["details"]["field"], "last_modified");
    }

    /// The virtual `relationships` surface is managed by `memstead_relate`,
    /// not `memstead_update`. Writes there reject with
    /// `SECTION_NOT_UPDATABLE` so an agent does not bypass the
    /// rel-validation pipeline by treating relationships as a section.
    #[test]
    fn update_rejects_relationships_section_as_not_updatable() {
        let tmp = TempDir::new().unwrap();
        write_workspace(&tmp, "demo");
        let server = FilesystemMcpServer::from_workspace_root(tmp.path()).unwrap();
        let (id, hash) = seed_via_mcp(&server, "Sneaky");

        let mut sections = IndexMap::new();
        sections.insert("relationships".to_string(), "- KIND: target".to_string());
        let result = server.memstead_update(Parameters(UpdateParams {
            anchors: None,
            relations_unset: None,
            anchors_unset: None,
            id,
            expected_hash: hash,
            sections: Some(sections),
            append_sections: None,
            patch_sections: None,
            metadata: None,
            metadata_unset: None,
            dry_run: None,
            note: None,
            role: None,
            declare_relations: None,
        }));
        assert!(result.is_error.unwrap_or(false));
        let body = result.structured_content.unwrap();
        // The relationships sneak path is gated by validate_section_keys
        // first (the schema doesn't declare a `relationships` section),
        // so it fires UNKNOWN_SECTION. Either gate is correct — both
        // close the bypass.
        let code = body["code"].as_str().unwrap();
        assert!(
            code == "SECTION_NOT_UPDATABLE" || code == "UNKNOWN_SECTION",
            "expected SECTION_NOT_UPDATABLE or UNKNOWN_SECTION, got {code}"
        );
    }

    #[test]
    fn delete_removes_entity_and_logs_change() {
        let tmp = TempDir::new().unwrap();
        write_workspace(&tmp, "demo");
        let server = FilesystemMcpServer::from_workspace_root(tmp.path()).unwrap();
        let (id, hash) = seed_via_mcp(&server, "Doomed");

        let result = server.memstead_delete(Parameters(DeleteParams {
            id: id.clone(),
            expected_hash: hash,
            note: Some("retired".into()),
            role: None,
        }));
        assert!(!result.is_error.unwrap_or(false));
        let body = result.structured_content.unwrap();
        assert_eq!(body["id"], id);

        let log =
            std::fs::read_to_string(tmp.path().join(".memstead").join("changes.jsonl")).unwrap();
        assert!(log.contains("\"kind\":\"delete\""));
        assert!(log.contains("\"note\":\"retired\""));
    }

    #[test]
    fn relate_appends_then_no_op_on_duplicate() {
        let tmp = TempDir::new().unwrap();
        write_workspace(&tmp, "demo");
        let server = FilesystemMcpServer::from_workspace_root(tmp.path()).unwrap();
        let (from, _) = seed_via_mcp(&server, "Source");
        let (to, _) = seed_via_mcp(&server, "Target");

        let added = server.memstead_relate(Parameters(RelateParams {
            relations: vec![RelateOpInput {
                from: from.clone(),
                to: to.clone(),
                r#type: "USES".into(),
                remove: None,
                description: None,
            }],
            note: Some("first".into()),
            role: None,
            dry_run: None,
        }));
        assert!(!added.is_error.unwrap_or(false));
        assert_eq!(
            added.structured_content.unwrap()["results"][0]["action"],
            "added"
        );

        let dup = server.memstead_relate(Parameters(RelateParams {
            relations: vec![RelateOpInput {
                from: from.clone(),
                to: to.clone(),
                r#type: "USES".into(),
                remove: None,
                description: None,
            }],
            note: None,
            role: None,
            dry_run: None,
        }));
        assert!(!dup.is_error.unwrap_or(false));
        let dup_body = dup.structured_content.unwrap();
        assert_eq!(dup_body["results"][0]["action"], "noop");
        assert!(
            dup_body["warnings"]
                .as_array()
                .is_some_and(|w| w.iter().any(|x| x["code"] == "DUPLICATE_RELATIONSHIP")),
            "duplicate add must warn typed: {dup_body}"
        );
    }

    /// Strict-mode schemas (the default) reject undeclared
    /// relationship names with `INVALID_REL_TYPE`. The recovery
    /// envelope carries the canonical vocabulary on
    /// `details.allowed[]` so the agent can self-correct in one
    /// round trip without a follow-up `memstead_overview`.
    #[test]
    fn relate_rejects_undeclared_rel_type() {
        let tmp = TempDir::new().unwrap();
        write_workspace(&tmp, "demo");
        let server = FilesystemMcpServer::from_workspace_root(tmp.path()).unwrap();
        let (from, _) = seed_via_mcp(&server, "Source");
        let (to, _) = seed_via_mcp(&server, "Target");

        let result = server.memstead_relate(Parameters(RelateParams {
            relations: vec![RelateOpInput {
                from: from.clone(),
                to: to.clone(),
                r#type: "TOTALLY_MADE_UP".into(),
                remove: None,
                description: None,
            }],
            note: None,
            role: None,
            dry_run: None,
        }));
        assert!(result.is_error.unwrap_or(false));
        let body = result.structured_content.unwrap();
        assert_eq!(body["code"], "INVALID_REL_TYPE");
        assert_eq!(body["details"]["input"], "TOTALLY_MADE_UP");
        let allowed = body["details"]["allowed"]
            .as_array()
            .expect("allowed should be array");
        assert!(!allowed.is_empty(), "allowed[] must list real edges");
    }

    #[test]
    fn relate_rejects_cross_mem_target() {
        let tmp = TempDir::new().unwrap();
        write_workspace(&tmp, "demo");
        let server = FilesystemMcpServer::from_workspace_root(tmp.path()).unwrap();
        let (from, _) = seed_via_mcp(&server, "Source");

        let result = server.memstead_relate(Parameters(RelateParams {
            relations: vec![RelateOpInput {
                from: from.clone(),
                to: "other--thing".into(),
                r#type: "USES".into(),
                remove: None,
                description: None,
            }],
            note: None,
            role: None,
            dry_run: None,
        }));
        assert!(result.is_error.unwrap_or(false));
        assert_eq!(
            result.structured_content.unwrap()["code"],
            "CROSS_MEM_LINK_NOT_ALLOWED"
        );
    }

    #[test]
    fn search_with_empty_query_returns_seeded_entities() {
        let tmp = TempDir::new().unwrap();
        write_workspace(&tmp, "demo");
        let server = FilesystemMcpServer::from_workspace_root(tmp.path()).unwrap();
        for title in ["Alpha", "Beta", "Gamma"] {
            seed_via_mcp(&server, title);
        }

        let result = server.memstead_search(Parameters(SearchParams {
            query: None,
            mem: None,
            entity_type: None,
            expand_via: None,
            expand_depth: None,
            related_to: None,
            depth: None,
            edge_type: None,
            limit: None,
            offset: None,
            filters: None,
            range_filters: None,
            stub: Some(false),
            token_budget: None,
            direction: None,
        }));
        assert!(!result.is_error.unwrap_or(false));
        let md = result
            .content
            .iter()
            .filter_map(|c| c.as_text().map(|t| t.text.as_str()))
            .collect::<Vec<_>>()
            .join("\n");
        assert!(md.contains("_total: 3"), "expected _total: 3 in: {md}");
        for title in ["Alpha", "Beta", "Gamma"] {
            assert!(md.contains(title), "expected title {title} in: {md}");
        }
    }

    /// Malformed `range_filters` key (no `min_`/`max_`/`*_before`/`*_after`
    /// shape) refuses with `RANGE_FILTER_KEY_MALFORMED`. An earlier
    /// MCP `SearchParams` had no `range_filters` field at all so the
    /// engine never saw the input — silent no-op.
    #[test]
    fn search_range_filter_malformed_key_surfaces_typed_warning() {
        let tmp = TempDir::new().unwrap();
        write_workspace(&tmp, "demo");
        let server = FilesystemMcpServer::from_workspace_root(tmp.path()).unwrap();
        seed_via_mcp(&server, "Seed");

        let mut range_filters = std::collections::HashMap::new();
        range_filters.insert("malformedkey".to_string(), "10".to_string());

        let result = server.memstead_search(Parameters(SearchParams {
            query: None,
            mem: None,
            entity_type: None,
            expand_via: None,
            expand_depth: None,
            related_to: None,
            depth: None,
            edge_type: None,
            limit: None,
            offset: None,
            filters: None,
            range_filters: Some(range_filters),
            stub: Some(false),
            token_budget: None,
            direction: None,
        }));
        let sc = result
            .structured_content
            .as_ref()
            .expect("range-filter warning must ride on structured_content");
        let warnings = sc["warnings"]
            .as_array()
            .expect("warnings array on the structured envelope");
        assert!(
            warnings
                .iter()
                .any(|w| w["code"] == "RANGE_FILTER_KEY_MALFORMED"),
            "expected RANGE_FILTER_KEY_MALFORMED warning, got: {warnings:?}",
        );
    }

    /// Unknown range-filter field surfaces
    /// `UNKNOWN_RANGE_FILTER_FIELD` with the derived field name.
    #[test]
    fn search_range_filter_unknown_field_surfaces_typed_warning() {
        let tmp = TempDir::new().unwrap();
        write_workspace(&tmp, "demo");
        let server = FilesystemMcpServer::from_workspace_root(tmp.path()).unwrap();
        seed_via_mcp(&server, "Seed");

        let mut range_filters = std::collections::HashMap::new();
        range_filters.insert("min_fake_field".to_string(), "10".to_string());

        let result = server.memstead_search(Parameters(SearchParams {
            query: None,
            mem: None,
            entity_type: Some("spec".to_string()),
            expand_via: None,
            expand_depth: None,
            related_to: None,
            depth: None,
            edge_type: None,
            limit: None,
            offset: None,
            filters: None,
            range_filters: Some(range_filters),
            stub: Some(false),
            token_budget: None,
            direction: None,
        }));
        let sc = result.structured_content.as_ref().unwrap();
        let warnings = sc["warnings"].as_array().unwrap();
        assert!(
            warnings
                .iter()
                .any(|w| w["code"] == "UNKNOWN_RANGE_FILTER_FIELD"),
            "expected UNKNOWN_RANGE_FILTER_FIELD warning, got: {warnings:?}",
        );
    }

    /// Range-filter against a field that exists on the
    /// type's schema but is not declared `filterable: range` surfaces
    /// `FIELD_NOT_RANGE_FILTERABLE`. `level` exists on the default
    /// `spec` type with `filterable: equality` — perfect probe.
    #[test]
    fn search_range_filter_field_not_range_filterable_surfaces_typed_warning() {
        let tmp = TempDir::new().unwrap();
        write_workspace(&tmp, "demo");
        let server = FilesystemMcpServer::from_workspace_root(tmp.path()).unwrap();
        seed_via_mcp(&server, "Seed");

        let mut range_filters = std::collections::HashMap::new();
        range_filters.insert("min_level".to_string(), "M0".to_string());

        let result = server.memstead_search(Parameters(SearchParams {
            query: None,
            mem: None,
            entity_type: Some("spec".to_string()),
            expand_via: None,
            expand_depth: None,
            related_to: None,
            depth: None,
            edge_type: None,
            limit: None,
            offset: None,
            filters: None,
            range_filters: Some(range_filters),
            stub: Some(false),
            token_budget: None,
            direction: None,
        }));
        let sc = result.structured_content.as_ref().unwrap();
        let warnings = sc["warnings"].as_array().unwrap();
        assert!(
            warnings
                .iter()
                .any(|w| w["code"] == "FIELD_NOT_RANGE_FILTERABLE"),
            "expected FIELD_NOT_RANGE_FILTERABLE warning, got: {warnings:?}",
        );
    }

    /// Omitting `range_filters` produces no
    /// range-filter warnings (the parameter is optional).
    #[test]
    fn search_without_range_filters_produces_no_range_warnings() {
        let tmp = TempDir::new().unwrap();
        write_workspace(&tmp, "demo");
        let server = FilesystemMcpServer::from_workspace_root(tmp.path()).unwrap();
        seed_via_mcp(&server, "Seed");

        let result = server.memstead_search(Parameters(SearchParams {
            query: None,
            mem: None,
            entity_type: None,
            expand_via: None,
            expand_depth: None,
            related_to: None,
            depth: None,
            edge_type: None,
            limit: None,
            offset: None,
            filters: None,
            range_filters: None,
            stub: Some(false),
            token_budget: None,
            direction: None,
        }));
        let sc = result.structured_content.as_ref().unwrap();
        let warnings = sc["warnings"].as_array().unwrap_or(&Vec::new()).clone();
        for w in warnings {
            let code = w["code"].as_str().unwrap_or("");
            assert!(
                !code.starts_with("RANGE_FILTER_")
                    && code != "UNKNOWN_RANGE_FILTER_FIELD"
                    && code != "FIELD_NOT_RANGE_FILTERABLE",
                "no range-filter warning expected when range_filters omitted, got: {w}",
            );
        }
    }

    #[test]
    fn search_filters_by_entity_type() {
        let tmp = TempDir::new().unwrap();
        write_workspace(&tmp, "demo");
        let server = FilesystemMcpServer::from_workspace_root(tmp.path()).unwrap();
        seed_via_mcp(&server, "OnlySpec");

        // Filter to a non-existent type → empty hits.
        let result = server.memstead_search(Parameters(SearchParams {
            query: None,
            mem: None,
            entity_type: Some("totally-not-a-type".into()),
            expand_via: None,
            expand_depth: None,
            related_to: None,
            depth: None,
            edge_type: None,
            limit: None,
            offset: None,
            filters: None,
            range_filters: None,
            stub: Some(false),
            token_budget: None,
            direction: None,
        }));
        let md = result
            .content
            .iter()
            .filter_map(|c| c.as_text().map(|t| t.text.as_str()))
            .collect::<Vec<_>>()
            .join("\n");
        assert!(md.contains("_total: 0"), "expected _total: 0 in: {md}");
    }

    #[test]
    fn health_returns_workspace_summary() {
        let tmp = TempDir::new().unwrap();
        write_workspace(&tmp, "demo");
        let server = FilesystemMcpServer::from_workspace_root(tmp.path()).unwrap();
        seed_via_mcp(&server, "Healthy");

        let result = server.memstead_health(Parameters(HealthParams {
            include: None,
            limit: None,
            mem: None,
            include_config: false,
            target_schema: None,
            token_budget: None,
            chunk: None,
        }));
        assert!(!result.is_error.unwrap_or(false));
        let body = result.structured_content.unwrap();
        // The summary structure carries totals and a per-mem map.
        // We do not pin field names here (memstead-base owns the shape),
        // just assert the response is a non-empty JSON object.
        assert!(body.is_object());
        assert!(!body.as_object().unwrap().is_empty());
    }

    /// Plan 08 duplicate check (MCP leg): an identifier-shaped value
    /// living only in an entity's metadata is findable by a plain
    /// free-text `memstead_search`, and the hit reports the metadata
    /// match in its matched-terms breakdown.
    #[test]
    fn search_finds_identifier_shaped_metadata_value() {
        let tmp = TempDir::new().unwrap();
        write_workspace(&tmp, "demo");
        // Seed a file carrying the identifier in an UNDECLARED
        // metadata field (tolerated on load; now findable).
        std::fs::write(
            tmp.path().join("akte.md"),
            "---\ntype: spec\naktenzeichen: 20/54/033\n---\n# Akte\n\n\
             ## Identity\n\nDie Akte selbst.\n\n## Purpose\n\nNachweis.\n",
        )
        .unwrap();
        let server = FilesystemMcpServer::from_workspace_root(tmp.path()).unwrap();

        let result = server.memstead_search(Parameters(SearchParams {
            query: Some(memstead_base::ops::Query {
                any: vec!["20/54/033".into()],
                not: vec![],
                phrase: None,
                field: None,
            }),
            direction: None,
            mem: None,
            entity_type: None,
            expand_via: None,
            expand_depth: None,
            related_to: None,
            depth: None,
            edge_type: None,
            limit: None,
            offset: None,
            filters: None,
            range_filters: None,
            stub: None,
            token_budget: None,
        }));
        assert!(!result.is_error.unwrap_or(false), "{result:?}");
        let body = result.structured_content.unwrap();
        let hits = body["hits"].as_array().expect("hits array");
        assert_eq!(hits.len(), 1, "identifier found over MCP: {body}");
        assert_eq!(hits[0]["id"], "demo--akte");
        assert!(
            hits[0]["matched_terms"]
                .as_object()
                .into_iter()
                .flat_map(|m| m.values())
                .flat_map(|v| v.as_array().cloned().unwrap_or_default())
                .any(|tm| tm["field"] == "metadata"),
            "hit identifiable as a metadata match: {}",
            hits[0]
        );
    }

    #[test]
    fn health_via_new_engine_reflects_post_boot_mutations() {
        // Pins the migration template's "boot fresh per call" property:
        // seed entities through the legacy engine after server boot,
        // then assert memstead_health (which now routes through a fresh
        // memstead_base::Engine) reflects them. Without the per-call boot
        // the health response would be stale relative to the legacy
        // engine's mutations.
        //
        // `memstead_create` refuses on missing required sections,
        // so `seed_via_mcp` seeds `identity` + `purpose`. The
        // seeded entity no longer surfaces as missing_fields, but
        // the broader invariant — health reflects post-boot
        // mutations — still holds via the total entity count.
        let tmp = TempDir::new().unwrap();
        write_workspace(&tmp, "demo");
        let server = FilesystemMcpServer::from_workspace_root(tmp.path()).unwrap();

        seed_via_mcp(&server, "Post Boot Spec");

        // Health must reflect the post-boot mutation — the seeded
        // entity is visible via the stats projection (stub_count and
        // missing_fields can both be 0 on a fresh mem with a
        // well-formed seed). Use a query for the entity directly:
        // memstead_search by title term proves the engine re-boot sees
        // the new entity. If `health` had been boot-cached, the
        // search index would lag.
        let result = server.memstead_search(Parameters(SearchParams {
            query: Some(memstead_base::ops::Query {
                any: vec!["post-boot".into()],
                not: vec![],
                phrase: None,
                field: None,
            }),
            direction: None,
            mem: None,
            entity_type: None,
            expand_via: None,
            expand_depth: None,
            related_to: None,
            depth: None,
            edge_type: None,
            limit: None,
            offset: None,
            filters: None,
            range_filters: None,
            stub: None,
            token_budget: None,
        }));
        assert!(!result.is_error.unwrap_or(false));
        let text = result
            .content
            .first()
            .unwrap()
            .as_text()
            .unwrap()
            .text
            .clone();
        assert!(
            text.contains("demo--post-boot-spec") || text.contains("Post Boot"),
            "post-seed search must surface the seeded entity, got: {text}"
        );
    }

    #[test]
    fn schema_returns_pinned_schema_when_name_matches() {
        let tmp = TempDir::new().unwrap();
        write_workspace(&tmp, "demo");
        let server = FilesystemMcpServer::from_workspace_root(tmp.path()).unwrap();

        // Bare-name and canonical pin both work.
        for name in ["default", "default@1.0.0"] {
            let result = server.memstead_schema(Parameters(SchemaParams {
                verbosity: None,
                name: Some(name.into()),
                mem: None,
            }));
            assert!(!result.is_error.unwrap_or(false), "name={name:?}");
            let body = result.structured_content.unwrap();
            // Converged onto the shared `build_schema_payload`: the
            // canonical `ref` subsumes the former top-level `name`/`version`.
            // The omitted-verbosity default is the lite skeleton.
            assert_eq!(body["ref"], "default@1.0.0");
            assert!(body["types_summary"].is_array());
            assert!(body.get("types").is_none(), "default is lite, not full");
            assert!(body["used_by"].is_array());
            assert_eq!(body["used_by"][0], "demo");
        }

        // Explicit full verbosity still ships the rich catalogue.
        let result = server.memstead_schema(Parameters(SchemaParams {
            verbosity: Some("full".into()),
            name: Some("default".into()),
            mem: None,
        }));
        assert!(!result.is_error.unwrap_or(false));
        let body = result.structured_content.unwrap();
        assert!(body["types"].is_array());

        // `mem` shortcut resolves the same schema.
        let result = server.memstead_schema(Parameters(SchemaParams {
            verbosity: None,
            name: None,
            mem: Some("demo".into()),
        }));
        assert!(!result.is_error.unwrap_or(false));
        let body = result.structured_content.unwrap();
        assert_eq!(body["ref"], "default@1.0.0");
    }

    /// Surface parity: the public filesystem `/mcp` flavour honours the
    /// same `verbosity` toggle as the mem-repo surface (Plan 01) — it
    /// converged onto the shared `build_schema_payload`, so lite is the
    /// identical structural skeleton and an unknown value refuses typed.
    #[test]
    fn schema_honours_verbosity_toggle() {
        let tmp = TempDir::new().unwrap();
        write_workspace(&tmp, "demo");
        let server = FilesystemMcpServer::from_workspace_root(tmp.path()).unwrap();

        let lite = server.memstead_schema(Parameters(SchemaParams {
            verbosity: Some("lite".into()),
            name: None,
            mem: Some("demo".into()),
        }));
        assert!(!lite.is_error.unwrap_or(false));
        let lite_body = lite.structured_content.unwrap();
        assert!(
            lite_body["types_summary"].is_array(),
            "lite skeleton present"
        );
        assert!(lite_body.get("types").is_none(), "lite omits rich types");
        assert!(lite_body.get("description").is_none(), "lite drops prose");
        assert_eq!(lite_body["ref"], "default@1.0.0");

        let unknown = server.memstead_schema(Parameters(SchemaParams {
            verbosity: Some("brief".into()),
            name: None,
            mem: Some("demo".into()),
        }));
        assert!(
            unknown.is_error.unwrap_or(false),
            "unknown verbosity refuses"
        );
        let env = unknown.structured_content.unwrap();
        assert_eq!(env["code"], "INVALID_INPUT");
    }

    #[test]
    fn schema_rejects_both_name_and_mem() {
        let tmp = TempDir::new().unwrap();
        write_workspace(&tmp, "demo");
        let server = FilesystemMcpServer::from_workspace_root(tmp.path()).unwrap();

        let result = server.memstead_schema(Parameters(SchemaParams {
            verbosity: None,
            name: Some("default".into()),
            mem: Some("demo".into()),
        }));
        assert!(result.is_error.unwrap_or(false));
        let body = result.content[0]
            .as_text()
            .map(|t| t.text.clone())
            .unwrap_or_default();
        assert!(body.contains("INVALID_INPUT"), "got: {body}");
    }

    #[test]
    fn schema_rejects_unknown_mem() {
        let tmp = TempDir::new().unwrap();
        write_workspace(&tmp, "demo");
        let server = FilesystemMcpServer::from_workspace_root(tmp.path()).unwrap();

        let result = server.memstead_schema(Parameters(SchemaParams {
            verbosity: None,
            name: None,
            mem: Some("nope".into()),
        }));
        assert!(result.is_error.unwrap_or(false));
        let body = result.content[0]
            .as_text()
            .map(|t| t.text.clone())
            .unwrap_or_default();
        assert!(body.contains("UNKNOWN_MEM"), "got: {body}");
    }

    #[test]
    fn schema_rejects_unknown_name_with_typed_code() {
        let tmp = TempDir::new().unwrap();
        write_workspace(&tmp, "demo");
        let server = FilesystemMcpServer::from_workspace_root(tmp.path()).unwrap();

        let result = server.memstead_schema(Parameters(SchemaParams {
            verbosity: None,
            name: Some("totally-not-a-schema".into()),
            mem: None,
        }));
        assert!(result.is_error.unwrap_or(false));
        let body = result.structured_content.unwrap();
        assert_eq!(body["code"], "ENTITY_NOT_FOUND");
    }

    #[test]
    fn changes_since_returns_entries_after_timestamp() {
        let tmp = TempDir::new().unwrap();
        write_workspace(&tmp, "demo");
        let server = FilesystemMcpServer::from_workspace_root(tmp.path()).unwrap();

        // Three creates → three changelog lines.
        for title in ["A", "B", "C"] {
            seed_via_mcp(&server, title);
        }

        // Empty `since` → all three entries.
        let result = server.memstead_changes_since(Parameters(ChangesSinceParams {
            mem: "demo".into(),
            since: "".into(),
            rename_similarity: None,
            include_notes: false,
        }));
        assert!(!result.is_error.unwrap_or(false));
        let body = result.structured_content.unwrap();
        assert_eq!(body["count"], 3);
        let entries = body["entries"].as_array().unwrap();
        assert_eq!(entries.len(), 3);
        for entry in entries {
            assert_eq!(entry["kind"], "create");
        }

        // `since` set to a far-future timestamp → empty.
        let result = server.memstead_changes_since(Parameters(ChangesSinceParams {
            mem: "demo".into(),
            since: "9999-01-01T00:00:00.000Z".into(),
            rename_similarity: None,
            include_notes: false,
        }));
        let body = result.structured_content.unwrap();
        assert_eq!(body["count"], 0);
    }

    #[test]
    fn changes_since_handles_missing_changelog_file() {
        // Fresh workspace with no mutations → no changelog file
        // exists. Must return an empty result, not an error.
        let tmp = TempDir::new().unwrap();
        write_workspace(&tmp, "demo");
        let server = FilesystemMcpServer::from_workspace_root(tmp.path()).unwrap();
        let result = server.memstead_changes_since(Parameters(ChangesSinceParams {
            mem: "demo".into(),
            since: "".into(),
            rename_similarity: None,
            include_notes: false,
        }));
        assert!(!result.is_error.unwrap_or(false));
        let body = result.structured_content.unwrap();
        assert_eq!(body["count"], 0);
    }

    #[test]
    fn entity_includes_relations_when_flag_set() {
        let tmp = TempDir::new().unwrap();
        write_workspace(&tmp, "demo");
        let server = FilesystemMcpServer::from_workspace_root(tmp.path()).unwrap();
        let (from, _) = seed_via_mcp(&server, "Source");
        let (to, _) = seed_via_mcp(&server, "Target");

        // Add a relation.
        server.memstead_relate(Parameters(RelateParams {
            relations: vec![RelateOpInput {
                from: from.clone(),
                to: to.clone(),
                r#type: "USES".into(),
                remove: None,
                description: None,
            }],
            note: None,
            role: None,
            dry_run: None,
        }));

        // Read with include_relations.
        let result = server.memstead_entity(Parameters(EntityParams {
            id: from,
            sections: None,
            include_relations: Some(true),
            include_context: None,
            token_budget: None,
            chunk: None,
            include_provenance: None,
        }));
        assert!(!result.is_error.unwrap_or(false));
        let text = result
            .content
            .first()
            .unwrap()
            .as_text()
            .unwrap()
            .text
            .clone();
        assert!(text.contains("## Relations"));
    }

    #[test]
    fn entity_includes_context_when_flag_set() {
        let tmp = TempDir::new().unwrap();
        write_workspace(&tmp, "demo");
        let server = FilesystemMcpServer::from_workspace_root(tmp.path()).unwrap();
        let (id, _) = seed_via_mcp(&server, "Lonely");

        // Read with include_context. The community cache runs Louvain
        // on first call; a single-node graph has a trivial cluster.
        let result = server.memstead_entity(Parameters(EntityParams {
            id,
            sections: None,
            include_relations: None,
            include_context: Some(true),
            token_budget: None,
            chunk: None,
            include_provenance: None,
        }));
        assert!(!result.is_error.unwrap_or(false));
        let text = result
            .content
            .first()
            .unwrap()
            .as_text()
            .unwrap()
            .text
            .clone();
        assert!(text.contains("## Community Context"));
    }

    #[test]
    fn search_returns_results_for_text_query() {
        let tmp = TempDir::new().unwrap();
        write_workspace(&tmp, "demo");
        let server = FilesystemMcpServer::from_workspace_root(tmp.path()).unwrap();

        // Seed two entities — one matches the query body, one does not.
        // The
        // engine refuses on missing required sections, so seed both
        // `identity` + `purpose` for each create.
        let mut secs = indexmap::IndexMap::new();
        secs.insert(
            "identity".to_string(),
            "Discusses the architecture of the universe.".to_string(),
        );
        secs.insert("purpose".to_string(), "match purpose".to_string());
        server.memstead_create(Parameters(CreateParams {
            anchors: None,
            title: "Match".into(),
            entity_type: "spec".into(),
            mem: None,
            sections: Some(secs),
            metadata: None,
            relations: None,
            dry_run: None,
            note: None,
            role: None,
        }));
        let mut other_secs = indexmap::IndexMap::new();
        other_secs.insert("identity".to_string(), "other identity".to_string());
        other_secs.insert("purpose".to_string(), "other purpose".to_string());
        server.memstead_create(Parameters(CreateParams {
            anchors: None,
            title: "Other".into(),
            entity_type: "spec".into(),
            mem: None,
            sections: Some(other_secs),
            metadata: None,
            relations: None,
            dry_run: None,
            note: None,
            role: None,
        }));

        // Issue a search using the structured query shape.
        use memstead_base::ops::Query;
        let result = server.memstead_search(Parameters(SearchParams {
            query: Some(Query {
                any: vec!["architecture".into()],
                not: vec![],
                phrase: None,
                field: None,
            }),
            direction: None,
            mem: None,
            entity_type: None,
            expand_via: None,
            expand_depth: None,
            related_to: None,
            depth: None,
            edge_type: None,
            limit: None,
            offset: None,
            filters: None,
            range_filters: None,
            stub: Some(false),
            token_budget: None,
        }));
        assert!(!result.is_error.unwrap_or(false));
        let text = result
            .content
            .first()
            .unwrap()
            .as_text()
            .unwrap()
            .text
            .clone();
        // Markdown response — rendered by `render_search_markdown`.
        // The matching entity's title or id appears; the
        // non-matching one should not (asserts that the text
        // predicate actually filtered).
        assert!(text.contains("demo--match") || text.contains("Match"));
        assert!(!text.contains("demo--other"));
    }

    #[test]
    fn search_metadata_only_returns_seeded_entities() {
        // Empty query → falls through to metadata-only / list semantics.
        // Asserts the no-text-predicate branch returns hits without
        // tripping on the index path.
        let tmp = TempDir::new().unwrap();
        write_workspace(&tmp, "demo");
        let server = FilesystemMcpServer::from_workspace_root(tmp.path()).unwrap();
        seed_via_mcp(&server, "Alpha");
        seed_via_mcp(&server, "Beta");

        let result = server.memstead_search(Parameters(SearchParams {
            query: None,
            mem: None,
            entity_type: None,
            expand_via: None,
            expand_depth: None,
            related_to: None,
            depth: None,
            edge_type: None,
            limit: None,
            offset: None,
            filters: None,
            range_filters: None,
            stub: Some(false),
            token_budget: None,
            direction: None,
        }));
        assert!(!result.is_error.unwrap_or(false));
        let text = result
            .content
            .first()
            .unwrap()
            .as_text()
            .unwrap()
            .text
            .clone();
        // Both seeded entities appear when there is no text filter.
        assert!(text.contains("demo--alpha") || text.contains("Alpha"));
        assert!(text.contains("demo--beta") || text.contains("Beta"));
    }

    #[test]
    fn overview_returns_schema_and_mem_sections() {
        let tmp = TempDir::new().unwrap();
        write_workspace(&tmp, "demo");
        let server = FilesystemMcpServer::from_workspace_root(tmp.path()).unwrap();
        seed_via_mcp(&server, "Alpha");
        seed_via_mcp(&server, "Beta");

        let result = server.memstead_overview(Parameters(OverviewParams {
            rebuild: None,
            chunk: None,
            mem: None,
            include: None,
            token_budget: None,
        }));
        assert!(!result.is_error.unwrap_or(false));
        let text = result
            .content
            .first()
            .unwrap()
            .as_text()
            .unwrap()
            .text
            .clone();
        // Produced by the shared composer now: an `_overview_mode` frontmatter
        // line and the standard section headings, with the single mem in the
        // roster and its own entity count. `_mem_schema` is emitted only under a
        // `mem` filter (composer behaviour), so it is absent from this
        // unscoped call — asserted below. The lean surface carries no
        // mem-lifecycle tools, so the lifecycle section is suppressed.
        assert!(text.contains("_overview_mode:"));
        assert!(text.contains("## Schemas"));
        assert!(text.contains("## Mems"));
        assert!(text.contains("### demo"));
        assert!(text.contains("- **Entities:** 2"));
        assert!(text.contains("## Communities"));
        assert!(
            !text.contains("## Lifecycle Namespaces"),
            "lean surface has no mem-lifecycle tools: {text}"
        );
        assert!(
            !text.contains("_mem_schema:"),
            "_mem_schema is emitted only under a mem filter: {text}"
        );

        // Scoping to the one visible mem succeeds and now anchors `_mem_schema`.
        let scoped = server.memstead_overview(Parameters(OverviewParams {
            rebuild: None,
            chunk: None,
            mem: Some("demo".into()),
            include: None,
            token_budget: None,
        }));
        assert!(!scoped.is_error.unwrap_or(false));
        let stext = scoped
            .content
            .first()
            .unwrap()
            .as_text()
            .unwrap()
            .text
            .clone();
        assert!(
            stext.contains("_mem_schema: default@1.0.0"),
            "a mem-scoped overview anchors the schema: {stext}"
        );
    }

    #[test]
    fn overview_rejects_unknown_mem_filter() {
        let tmp = TempDir::new().unwrap();
        write_workspace(&tmp, "demo");
        let server = FilesystemMcpServer::from_workspace_root(tmp.path()).unwrap();

        let result = server.memstead_overview(Parameters(OverviewParams {
            rebuild: None,
            chunk: None,
            mem: Some("not-the-mem".into()),
            include: None,
            token_budget: None,
        }));
        assert!(result.is_error.unwrap_or(false));
        let body = result.structured_content.unwrap();
        // The shared composer returns the typed unknown-mem error, and its mem
        // list names every visible mem (here, the workspace's single mem).
        assert_eq!(body["code"], "UNKNOWN_MEM");
        assert_eq!(body["details"]["visible_mems"][0], "demo");
    }

    #[test]
    fn overview_include_community_members_renders_member_ids() {
        let tmp = TempDir::new().unwrap();
        write_workspace(&tmp, "demo");
        let server = FilesystemMcpServer::from_workspace_root(tmp.path()).unwrap();
        let (a, _) = seed_via_mcp(&server, "Alpha");
        let (b, _) = seed_via_mcp(&server, "Beta");
        // Edge so the cluster has structure to discuss.
        server.memstead_relate(Parameters(RelateParams {
            relations: vec![RelateOpInput {
                from: a.clone(),
                to: b.clone(),
                r#type: "USES".into(),
                remove: None,
                description: None,
            }],
            note: None,
            role: None,
            dry_run: None,
        }));

        let result = server.memstead_overview(Parameters(OverviewParams {
            rebuild: None,
            chunk: None,
            mem: None,
            include: Some(vec!["community_members".into()]),
            token_budget: None,
        }));
        assert!(!result.is_error.unwrap_or(false));
        let text = result
            .content
            .first()
            .unwrap()
            .as_text()
            .unwrap()
            .text
            .clone();
        // With community_members forced, the rendered cluster lists
        // each member entity id as a bullet — both Alpha and Beta
        // should appear under Communities.
        assert!(text.contains(&format!("- {a}")));
        assert!(text.contains(&format!("- {b}")));
    }

    /// `memstead_overview include=["dangling_links"]` lists every non-stub
    /// entity whose section body wiki-links resolve to a stub or
    /// missing target. Pre-fix the lean overview surface hardcoded
    /// `[]` here and the `## Dangling Links` block never rendered,
    /// even when the health surface populated the same
    /// view. The test fails against that state.
    #[test]
    fn overview_dangling_links_surfaces_stub_targets() {
        let tmp = TempDir::new().unwrap();
        write_workspace(&tmp, "demo");
        let server = FilesystemMcpServer::from_workspace_root(tmp.path()).unwrap();
        let (id, hash) = seed_via_mcp(&server, "Anchor");

        // Rewrite Identity to carry a body wiki-link to a slug with
        // no on-disk file, backed by an atomic REFERENCES declaration
        // (forward-reference auto-stub). The stub is the dangling
        // signal — the dangling-links surface flags wiki-links whose
        // target resolves to a stub entity.
        let mut sections = indexmap::IndexMap::new();
        sections.insert(
            "identity".to_string(),
            "Refers to [[gone]] in prose.".to_string(),
        );
        let upd = server.memstead_update(Parameters(UpdateParams {
            anchors: None,
            relations_unset: None,
            anchors_unset: None,
            id: id.clone(),
            expected_hash: hash,
            sections: Some(sections),
            append_sections: None,
            patch_sections: None,
            metadata: None,
            metadata_unset: None,
            dry_run: None,
            note: Some("seed dangling link".into()),
            role: None,
            // Body wiki-link `[[gone]]` is auto-emitted as REFERENCES
            // via the alias-synthesis pass — explicit author refused
            // under the schema's `manual_authoring: forbidden` posture.
            declare_relations: None,
        }));
        assert!(!upd.is_error.unwrap_or(false), "{upd:?}");

        let result = server.memstead_overview(Parameters(OverviewParams {
            rebuild: None,
            chunk: None,
            mem: None,
            include: Some(vec!["dangling_links".into()]),
            token_budget: None,
        }));
        assert!(!result.is_error.unwrap_or(false));
        let text = result
            .content
            .first()
            .unwrap()
            .as_text()
            .unwrap()
            .text
            .clone();
        assert!(
            text.contains("## Dangling Links"),
            "overview must render the Dangling Links section when an opt-in caller finds one: {text}"
        );
        assert!(
            text.contains(&id),
            "Dangling Links must name the linking entity ({id}): {text}"
        );
        assert!(
            text.contains("demo--gone"),
            "Dangling Links must name the dangling target: {text}"
        );
    }

    #[test]
    fn overview_unknown_include_key_emits_warning() {
        let tmp = TempDir::new().unwrap();
        write_workspace(&tmp, "demo");
        let server = FilesystemMcpServer::from_workspace_root(tmp.path()).unwrap();
        seed_via_mcp(&server, "Alpha");

        let result = server.memstead_overview(Parameters(OverviewParams {
            rebuild: None,
            chunk: None,
            mem: None,
            include: Some(vec!["totally-bogus".into()]),
            token_budget: None,
        }));
        assert!(!result.is_error.unwrap_or(false));
        let text = result
            .content
            .first()
            .unwrap()
            .as_text()
            .unwrap()
            .text
            .clone();
        assert!(text.contains("## Warnings"));
        assert!(text.contains("UNKNOWN_INCLUDE_KEY"));
    }

    #[test]
    fn overview_rejects_legacy_schema_types_include() {
        let tmp = TempDir::new().unwrap();
        write_workspace(&tmp, "demo");
        let server = FilesystemMcpServer::from_workspace_root(tmp.path()).unwrap();

        let result = server.memstead_overview(Parameters(OverviewParams {
            rebuild: None,
            chunk: None,
            mem: None,
            include: Some(vec!["schema_types".into()]),
            token_budget: None,
        }));
        assert!(result.is_error.unwrap_or(false));
        let body = result.structured_content.unwrap();
        assert_eq!(body["code"], "INVALID_INPUT");
    }

    #[test]
    fn rename_changes_id_and_persists_through_disk() {
        let tmp = TempDir::new().unwrap();
        write_workspace(&tmp, "demo");
        let server = FilesystemMcpServer::from_workspace_root(tmp.path()).unwrap();
        let (id, hash) = seed_via_mcp(&server, "Old Title");

        let result = server.memstead_rename(Parameters(RenameParams {
            id,
            new_title: "New Title".into(),
            expected_hash: hash,
            note: Some("renamed".into()),
            role: None,
        }));
        assert!(!result.is_error.unwrap_or(false));
        let body = result.structured_content.unwrap();
        assert_eq!(body["new_id"], "demo--new-title");
        assert_eq!(body["new_file_path"], "new-title.md");
        assert!(tmp.path().join("new-title.md").is_file());
        assert!(!tmp.path().join("old-title.md").exists());
    }
}