memstead_base/entity/

id.rs

//! Entity ID parsing, generation, and path mapping.

use super::EntityId;
use unicode_normalization::UnicodeNormalization;

/// Cap on the full `mem--slug` entity id (Unicode scalar length).
/// 200 leaves headroom for `mem--`-style prefixes and the `.md`
/// suffix against the 255-byte `NAME_MAX` ceiling on common
/// filesystems. The read-path validator on the MCP surface and the
/// write-path slug derivation share this constant so an entity that
/// the write side accepts is always readable on the same wire.
/// F2 + F4.
pub const ENTITY_ID_MAX_LEN: usize = 200;

/// Error cases for title→slug derivation. `title_to_slug` itself is
/// total — any title produces a slug (residual cases like
/// all-emoji collapse to a deterministic short-hash id) — so it never
/// returns these variants directly. The strict mutation-entry gate
/// [`validate_and_derive_slug`] returns them for control characters
/// and for input that would have fallen back to the hash slug;
/// [`enforce_id_length`] returns [`Self::IdTooLong`] when the
/// derived `mem--slug` exceeds the read-path length cap.
///
/// Loader and parse paths continue to call [`title_to_slug`] so
/// pre-gate entities created with the old permissive pipeline remain
/// readable.
#[derive(Debug, thiserror::Error)]
pub enum SlugError {
    /// The derived `mem--slug` id exceeds [`ENTITY_ID_MAX_LEN`]. The
    /// read-path validator rejects ids past this length, so without
    /// this guard a title that the write path accepts produces an
    /// entity that is silently unreachable on read.
    ///
    /// The bound is on the **composed id** (`<mem>--<slug>`), which is
    /// also the on-disk filename — so the budget is mem-name-dependent
    /// and the same title can be valid in a short-named mem and rejected
    /// in a longer-named one. `input` echoes that composed id (not the
    /// title) so it agrees with `length`: the payload measures one
    /// quantity, the id, end to end. `max` is [`ENTITY_ID_MAX_LEN`] so the
    /// agent can shorten by the exact delta. F2 + F4.
    #[error(
        "entity id \"{input}\" is {length} characters (max {max}); the id is `<mem>--<slug>`, so the title budget shrinks as the mem name grows — shorten the title"
    )]
    IdTooLong {
        /// The composed `<mem>--<slug>` id whose length exceeded the
        /// cap. Echoed as the `input` wire field so `input` and `length`
        /// describe the same measured quantity.
        input: String,
        length: usize,
        max: usize,
    },
    /// Strict mutation-entry rejection: the title is empty,
    /// whitespace-only, or composed exclusively of pipeline-separator
    /// characters (hyphens) so the slug pipeline would have collapsed
    /// it to a hash-fallback id. Recovery: supply a non-empty title
    /// with at least one alphanumeric character. F4.
    #[error("title is empty or contains no slug-meaningful characters")]
    TitleEmpty { input: String },
    /// Strict mutation-entry rejection: the title contains control
    /// characters (newline, tab, other C0/C1 controls). These are
    /// Unicode whitespace, so the slug pipeline silently folds them to
    /// hyphens and accepts the title — but they survive verbatim into the
    /// stored `# H1` heading, which then splits across lines so every
    /// read truncates the title at the first control char (search and
    /// `memstead_entity` see only the prefix). Refused up front with the same
    /// named-offenders + `proposed_slug` recovery shape the invalid-char
    /// guard uses. `control_chars` lists each distinct offender in source
    /// order; `proposed_slug` is the slug the pipeline would produce, for
    /// a mechanical retry with a single-line title. F8.
    #[error(
        "title {input:?} contains control character(s) {control_chars:?} that would split the stored heading — \
         retry with a single-line title (proposed slug: \"{proposed_slug}\")"
    )]
    TitleHasControlChars {
        input: String,
        control_chars: Vec<char>,
        proposed_slug: String,
    },
}

impl SlugError {
    /// Stable discriminator for the structured-details `reason` field
    /// on the `INVALID_TITLE` wire envelope. Each surface (MCP, CLI)
    /// reads this when building the response payload.
    pub fn reason(&self) -> &'static str {
        match self {
            SlugError::IdTooLong { .. } => "id_too_long",
            SlugError::TitleEmpty { .. } => "empty",
            SlugError::TitleHasControlChars { .. } => "control_chars",
        }
    }
}

/// The separator between mem and entity path in IDs.
/// Build an EntityId from mem and title.
pub fn build_id(mem: &str, title: &str) -> Result<EntityId, SlugError> {
    let slug = title_to_slug(title)?;
    let id = EntityId::new(mem, &slug);
    enforce_id_length(id.as_ref())?;
    Ok(id)
}

/// Reject ids whose Unicode scalar length exceeds
/// [`ENTITY_ID_MAX_LEN`]. Shared by [`build_id`] and the engine's
/// `create_entity` / `rename_entity` paths so the write side never
/// produces an id the read side would refuse. The cap is on the
/// composed `<mem>--<slug>` id (which is also the filename), so the
/// error echoes the id itself — the `reason`, the echoed `input`, and
/// the reported `length` all describe the id, not the title. F2 + F4.
pub fn enforce_id_length(id: &str) -> Result<(), SlugError> {
    if id.chars().count() > ENTITY_ID_MAX_LEN {
        return Err(SlugError::IdTooLong {
            input: id.to_string(),
            length: id.chars().count(),
            max: ENTITY_ID_MAX_LEN,
        });
    }
    Ok(())
}

/// Convert a title string to a kebab-case slug.
///
/// Pipeline (F1, option B+A):
///
/// 1. **NFC-normalize** so combining sequences fold into precomposed
///    forms (`Café` written NFD becomes `Café` written NFC). One
///    canonical surface form keeps slug equality byte-stable across
///    NFD-storing filesystems (older HFS+) and NFC-default ones
///    (APFS, ext4, NTFS).
/// 2. **Lowercase** via Unicode default case-folding — correct for
///    Latin / Cyrillic / Greek / Armenian; no-op for case-less
///    scripts (CJK, Arabic, Hebrew, Devanagari, Thai, etc.).
/// 3. **Whitespace → hyphen**.
/// 4. **Filter to `is_alphanumeric() || '-'`** — Unicode alphanumeric,
///    not ASCII. Keeps every Latin and non-Latin letter or digit;
///    drops combining marks, punctuation, symbols, emoji, and the
///    reserved `--` / `:` separators by construction.
/// 5. **Collapse hyphen runs, trim**.
///
/// Always returns `Ok(...)`. When the filter leaves the slug empty
/// (all-emoji titles, all-punctuation, all-symbol titles), the slug
/// degrades to a deterministic short hash of the title
/// (`entity-<8-hex>`) rather than failing. Titles that are already
/// slug-form — case-less scripts (`知識グラフ`) and lowercase
/// single-token Latin (`wohnung`) — produce slug == title, so
/// Obsidian-style `[[<title>]]` authoring round-trips without lookup
/// for exactly those titles; any other title (a capital, a space:
/// `Knowledge Graph`) derives a different slug, and the strict
/// wiki-link decoder below refuses the natural form as a link target
/// — such entities are linked by slug (`[[knowledge-graph]]`).
pub fn title_to_slug(title: &str) -> Result<String, SlugError> {
    let normalized: String = title.nfc().collect();
    let slug: String = normalized
        .chars()
        .flat_map(|c| c.to_lowercase())
        .map(|c| if c.is_whitespace() { '-' } else { c })
        .filter(|c| c.is_alphanumeric() || *c == '-')
        .collect::<String>()
        .split('-')
        .filter(|s| !s.is_empty())
        .collect::<Vec<_>>()
        .join("-");
    if slug.is_empty() {
        return Ok(format!("entity-{}", short_hash(title)));
    }
    Ok(slug)
}

/// The accepted title grammar, stated as a rule. THE single sentence
/// every surface that documents titles carries: the CLI's
/// create/rename help embeds it at build time, the MCP
/// `memstead_create` / `memstead_rename` descriptions contain it
/// verbatim (a tool-surface test asserts the containment), and the
/// handbook quotes it naming this constant as its source. A
/// conformance test in this module asserts
/// [`validate_and_derive_slug`]'s behaviour matches the sentence's
/// claim — so neither the prose nor the validator can drift alone.
pub const TITLE_GRAMMAR_RULE: &str = "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";

/// A strict-gate derivation result: the slug plus the distinct title
/// characters (source order, post NFC + case-fold) the pipeline
/// dropped on the way. `dropped_chars` non-empty means the title and
/// its id diverge beyond case/whitespace — the mutation surfaces it
/// as the typed `TITLE_CHARS_DROPPED_FROM_SLUG` warning so the
/// divergence stays visible without being fatal.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct SlugDerivation {
    pub slug: String,
    pub dropped_chars: Vec<char>,
}

/// Strict slug derivation for mutation entry (`memstead_create`,
/// `memstead_rename`). Runs the same pipeline as [`title_to_slug`] —
/// byte-identical slugs for every title — but refuses the residual
/// cases the permissive variant tolerates:
///
/// 1. **Control characters.** They would survive verbatim into the
///    stored `# H1` and split it across lines. Returns
///    [`SlugError::TitleHasControlChars`].
/// 2. **Empty / collapses-to-empty.** Empty input, whitespace-only,
///    hyphen-only, or all-dropped input — anything that would force
///    the loader-path hash fallback. Returns [`SlugError::TitleEmpty`].
///
/// Any other character is admitted: the title is display text, stored
/// verbatim, and characters outside the slug alphabet are dropped from
/// the derived slug and reported in
/// [`SlugDerivation::dropped_chars`] ([`TITLE_GRAMMAR_RULE`]).
///
/// Loader paths continue to call [`title_to_slug`] so pre-gate
/// entities created with the old permissive pipeline remain
/// readable — only mutation entry runs this strict gate.
pub fn validate_and_derive_slug(title: &str) -> Result<SlugDerivation, SlugError> {
    let normalized: String = title.nfc().collect();
    let case_folded: String = normalized.chars().flat_map(|c| c.to_lowercase()).collect();

    // Control characters (newline, tab, other C0/C1) are Unicode
    // whitespace, so the slug pipeline below would fold them to hyphens
    // and accept the title — but they survive into the stored `# H1`,
    // splitting it across lines and truncating every read of the title.
    // Refuse them before the slug derivation.
    let mut control_chars: Vec<char> = Vec::new();
    for c in case_folded.chars() {
        if c.is_control() && !control_chars.contains(&c) {
            control_chars.push(c);
        }
    }
    if !control_chars.is_empty() {
        let proposed = title_to_slug(title).unwrap_or_default();
        return Err(SlugError::TitleHasControlChars {
            input: title.to_string(),
            control_chars,
            proposed_slug: proposed,
        });
    }

    // Characters outside the slug alphabet are dropped from the id —
    // recorded, not refused: the title is display text, the slug is
    // the sanitised identifier, and the divergence rides back to the
    // caller as a typed warning.
    let mut dropped_chars: Vec<char> = Vec::new();
    for c in case_folded.chars() {
        if c.is_whitespace() || c == '-' || c.is_alphanumeric() {
            continue;
        }
        if !dropped_chars.contains(&c) {
            dropped_chars.push(c);
        }
    }

    let slug: String = case_folded
        .chars()
        .filter(|c| c.is_whitespace() || *c == '-' || c.is_alphanumeric())
        .map(|c| if c.is_whitespace() { '-' } else { c })
        .collect::<String>()
        .split('-')
        .filter(|s| !s.is_empty())
        .collect::<Vec<_>>()
        .join("-");

    if slug.is_empty() {
        return Err(SlugError::TitleEmpty {
            input: title.to_string(),
        });
    }

    Ok(SlugDerivation {
        slug,
        dropped_chars,
    })
}

/// Deterministic 8-char hex digest used as the fallback slug when
/// the title contains no Unicode alphanumeric characters (the
/// residual case of [`title_to_slug`]'s pipeline). 32 bits is
/// plenty for collision-resistance inside a single mem; the
/// fallback only fires for titles that contain no
/// agent-meaningful characters anyway, so the opaque form is
/// acceptable. F1 (option A backstop).
fn short_hash(input: &str) -> String {
    use sha2::{Digest, Sha256};
    let digest = Sha256::digest(input.as_bytes());
    format!(
        "{:02x}{:02x}{:02x}{:02x}",
        digest[0], digest[1], digest[2], digest[3]
    )
}

/// Convert a relative file path to a mem-prefixed entity ID.
///
/// `file_path_to_id("architecture/result.md", "specs")` → `specs--architecture/result`
pub fn file_path_to_id(path: &str, mem: &str) -> EntityId {
    let stripped = path.strip_suffix(".md").unwrap_or(path);
    EntityId::new(mem, stripped)
}

/// Strict wiki-link grammar refusal. Returned by [`wiki_link_to_id`]
/// when the input between `[[...]]` (after alias / `.md` strip) does
/// not resolve to a slug-form `EntityId`. Two variants matching the
/// two grammars a wiki-link target carries:
///
/// - [`Self::InvalidMemName`] — Tier-2 prefix `[[mem:slug]]`'s
///   mem name fails [`validate_mem_name_grammar`]. Recovery is
///   manual: mem names are fixed identifiers in the workspace, not
///   free-form text the agent can slugify.
/// - [`Self::InvalidTarget`] — the slug-form path fails
///   [`validate_id_path_grammar`]. Carries the
///   [`title_to_slug`]-derived suggestion (omitted when the input
///   has no meaningful slug equivalent — empty, all-punctuation,
///   all-emoji).
#[derive(Debug, thiserror::Error, Clone)]
pub enum WikiLinkError {
    #[error("mem prefix '{raw}' is not a valid mem name: {reason}")]
    InvalidMemName { raw: String, reason: String },
    #[error("wiki-link target '{raw}' is not slug-form: {reason}")]
    InvalidTarget {
        raw: String,
        suggested: Option<String>,
        reason: String,
    },
}

/// Compute the [`title_to_slug`]-derived suggestion for a malformed
/// wiki-link target. Returns `None` when the slug pipeline produces
/// either an empty result or the deterministic hash fallback
/// (`entity-<8hex>`) — both signal that the input has no canonical
/// form the agent can mechanically lift into a retry.
fn wiki_link_suggestion(raw: &str) -> Option<String> {
    let derived = title_to_slug(raw).ok()?;
    if derived.is_empty() || derived.starts_with("entity-") {
        return None;
    }
    validate_id_path_grammar(&derived)
        .is_ok()
        .then_some(derived)
}

/// Convert a wiki-link target to a mem-prefixed entity ID, refusing
/// non-slug-form inputs.
///
/// Recognises three grammars:
/// - **Tier 0** `[[<mem>--<slug>]]` — cross-mem dash-form,
///   symmetric with every engine-emitted ID: body wiki-links accept
///   the canonical `<mem>--<slug>` form the engine writes elsewhere
///   so an agent can author the same grammar in both directions.
///   `<mem>` must match the single-segment mem-name grammar
///   (`[a-z0-9-]+`, no `/`); hierarchical mem names stay on the
///   Tier-2 colon-form. Cross-mem routing is policy-gated downstream in
///   the alias-synthesis pass (same code path that already gates
///   body-link → REFERENCES emission).
/// - **Tier 1** `[[slug]]` or `[[a/b/c]]` — same-mem, resolves to
///   `<current_mem>--<slug>`.
/// - **Tier 2** `[[leaf:slug]]` — cross-mem, same mem-repo, resolves
///   to `<leaf>--<slug>`. Hierarchical paths are first-class: the
///   prefix accepts the full `team/sub-mem` form, so
///   `[[team/sub-mem:auth-service]]` resolves to
///   `team/sub-mem--auth-service`. Tier-1 with a
///   hierarchical-mem dash-prefix (`[[team/sub-mem--auth-service]]`)
///   remains unsupported — that combination is genuinely ambiguous
///   between a cross-mem reference into a hierarchical mem and a
///   same-mem entity at a hierarchical slug. Operators authoring
///   such references must use the colon Tier-2 form.
///
/// Strips `[[` / `]]`, Obsidian alias (`|display`), `../` prefixes, `.md`
/// suffix, and a redundant leading `<current_mem>--` (so an agent that
/// writes the canonical fully-qualified id `[[mem--slug]]` produces the
/// same `EntityId` as the bare-slug form `[[slug]]` instead of doubly-
/// prefixing into `mem--mem--slug`).
///
/// Strictness: any input whose Tier-2 prefix fails
/// [`validate_mem_name_grammar`] or whose resolved slug fails
/// [`validate_id_path_grammar`] refuses with [`WikiLinkError`]. There is
/// no permissive form that constructs an `EntityId` from any character
/// sequence between the brackets — callers
/// (`extract_inline_links`, the relate path's body scanners)
/// propagate the refusal so an agent's `[[Knowledge Graph]]` body
/// link can no longer land a malformed auto-stub. Read-side scanners
/// that must tolerate pre-strict on-disk drift use
/// [`wiki_link_to_id_lenient`].
///
/// Hierarchical-dash ambiguity: the Tier-1 fallback refuses inputs whose post-
/// self-prefix-strip slug contains BOTH `/` and `--`
/// (`[[team/sub-mem--target]]`). The combination is grammatically
/// ambiguous between a cross-mem reference into a hierarchical mem
/// and a same-mem entity at a hierarchical slug; the refusal carries
/// the canonical colon form (`team/sub-mem:target`) as `suggested`.
pub fn wiki_link_to_id(link: &str, current_mem: &str) -> Result<EntityId, WikiLinkError> {
    let stripped = strip_wiki_link_decorations(link);

    if !stripped.contains("::")
        && let Some(colon_idx) = stripped.find(':')
    {
        let (prefix, rest) = stripped.split_at(colon_idx);
        let slug_part = &rest[1..];
        if !prefix.is_empty() && !slug_part.is_empty() {
            if let Err(reason) = validate_mem_name_grammar(prefix) {
                return Err(WikiLinkError::InvalidMemName {
                    raw: prefix.to_string(),
                    reason,
                });
            }
            if let Err(reason) = validate_id_path_grammar(slug_part) {
                let suggested = wiki_link_suggestion(slug_part).map(|s| format!("{prefix}:{s}"));
                return Err(WikiLinkError::InvalidTarget {
                    raw: stripped.to_string(),
                    suggested,
                    reason,
                });
            }
            return Ok(EntityId::new(prefix, slug_part));
        }
    }

    // Tier 0 — cross-mem dash form `<mem>--<slug>`. Symmetric
    // with every engine-emitted ID. Recognises only
    // single-segment mem names (no `/` in the prefix); the
    // hierarchical-mem dash form is grammatically ambiguous (see
    // the dash/slash refusal further down) and stays on the colon
    // Tier-2 form. Routes to the named mem even when it differs
    // from `current_mem` — the cross-mem policy gate fires in
    // the alias-synthesis pass, not here.
    if let Some(dash_idx) = stripped.find("--") {
        let prefix = &stripped[..dash_idx];
        let suffix = &stripped[dash_idx + 2..];
        if !prefix.is_empty()
            && !suffix.is_empty()
            && !prefix.contains('/')
            && validate_mem_name_grammar(prefix).is_ok()
            && validate_id_path_grammar(suffix).is_ok()
        {
            return Ok(EntityId::new(prefix, suffix));
        }
    }

    let slug = if !current_mem.is_empty() {
        let self_prefix = format!("{current_mem}--");
        stripped
            .strip_prefix(self_prefix.as_str())
            .unwrap_or(&stripped)
    } else {
        &stripped
    };
    // A slug carrying BOTH `/` and `--` is grammatically ambiguous —
    // it could be a cross-mem reference into a hierarchical mem
    // (`team/sub-mem--target` → mem `team/sub-mem`, slug `target`)
    // or a same-mem entity at a hierarchical slug that happens to
    // contain `--`. The docstring above pins the canonical disambiguation
    // (colon-form for cross-mem) but the dash form silently collapsed
    // to the same-mem interpretation pre-fix, landing phantom stubs
    // for any agent writing `[[team/sub-mem--target]]` in body text.
    // Refuse and surface the colon-form as the recovery hint.
    if let Some(dash_idx) = slug.find("--")
        && slug[..dash_idx].contains('/')
    {
        let prefix = &slug[..dash_idx];
        let suffix = &slug[dash_idx + 2..];
        let cross_mem_form = format!("{prefix}:{suffix}");
        let same_mem_form = if current_mem.is_empty() {
            format!("<current-mem>:{slug}")
        } else {
            format!("{current_mem}:{slug}")
        };
        return Err(WikiLinkError::InvalidTarget {
            raw: stripped.to_string(),
            suggested: Some(cross_mem_form),
            reason: format!(
                "wiki-link target contains both '/' and '--', which is ambiguous \
                 between a cross-mem reference into a hierarchical mem and a \
                 same-mem entity at a hierarchical slug; use the colon form \
                 '[[{prefix}:{suffix}]]' for a cross-mem reference, or \
                 '[[{same_mem_form}]]' for a same-mem entity whose slug \
                 contains '--'"
            ),
        });
    }
    if let Err(reason) = validate_id_path_grammar(slug) {
        return Err(WikiLinkError::InvalidTarget {
            raw: stripped.to_string(),
            suggested: wiki_link_suggestion(slug),
            reason,
        });
    }
    Ok(EntityId::new(current_mem, slug))
}

/// Permissive wiki-link decoder for read-side scanners that must
/// tolerate pre-strict-gate on-disk drift (e.g. dangling-link
/// reporters, body-link scanners on stored entities, archive readers
/// for non-canonical sources). Returns an `EntityId` even for
/// non-slug-form input — non-conformant chars flow through
/// unchanged. Mutation paths MUST
/// NOT use this helper; they use [`wiki_link_to_id`] and propagate
/// the typed refusal.
pub fn wiki_link_to_id_lenient(link: &str, current_mem: &str) -> EntityId {
    let stripped = strip_wiki_link_decorations(link);

    if !stripped.contains("::")
        && let Some(colon_idx) = stripped.find(':')
    {
        let (prefix, rest) = stripped.split_at(colon_idx);
        let slug_part = &rest[1..];
        if !prefix.is_empty() && !slug_part.is_empty() {
            return EntityId::new(prefix, slug_part);
        }
    }

    // Tier 0 — cross-mem dash form. Read-side mirror of the strict
    // decoder's recognition so dangling-link reports and graph
    // inspectors interpret on-disk `[[other--target]]` the same way
    // the mutation gate writes it. Pre-strict drift on older entities
    // keeps the bare-slug fallback below for
    // shapes the tier-0 doesn't admit (empty prefix, hierarchical
    // prefix, malformed slug).
    if let Some(dash_idx) = stripped.find("--") {
        let prefix = &stripped[..dash_idx];
        let suffix = &stripped[dash_idx + 2..];
        if !prefix.is_empty()
            && !suffix.is_empty()
            && !prefix.contains('/')
            && validate_mem_name_grammar(prefix).is_ok()
            && validate_id_path_grammar(suffix).is_ok()
        {
            return EntityId::new(prefix, suffix);
        }
    }

    let slug = if !current_mem.is_empty() {
        let self_prefix = format!("{current_mem}--");
        stripped
            .strip_prefix(self_prefix.as_str())
            .unwrap_or(&stripped)
    } else {
        &stripped
    };
    EntityId::new(current_mem, slug)
}

/// Strip `[[`/`]]`, the Obsidian alias suffix `|display`, the section
/// anchor `#section` (plus any trailing `#sub` etc — stripped from the
/// first `#` onward), leading `../` segments, and the trailing `.md`
/// suffix from a raw wiki-link token. Shared by the strict and
/// lenient decoders so the pre-grammar-gate textual normalisation is
/// byte-equivalent on both paths.
///
/// `#anchor` strip: Obsidian-style section anchors are display-only at
/// the graph layer; the engine has no semantic use for them. Strip
/// from the first `#` onward so multi-anchor forms like
/// `target#a#b` collapse to `target` in one pass. Ordered after the
/// `|alias` strip so `target#section|display` correctly drops both
/// (the alias strip drops `|display` first, leaving `target#section`;
/// the anchor strip then drops `#section`).
fn strip_wiki_link_decorations(link: &str) -> String {
    let cleaned = link.trim_start_matches("[[").trim_end_matches("]]").trim();
    let target = match cleaned.find('|') {
        Some(i) => &cleaned[..i],
        None => cleaned,
    };
    let target_no_anchor = match target.find('#') {
        Some(i) => &target[..i],
        None => target,
    };
    let target_no_dotdot = target_no_anchor.trim_start_matches("../");
    target_no_dotdot
        .strip_suffix(".md")
        .unwrap_or(target_no_dotdot)
        .to_string()
}

/// Compute the file path for an entity given its ID and base directory.
/// The path is relative to the mem directory.
///
/// `specs--architecture/result-entity` → `architecture/result-entity.md`
pub fn id_to_file_path(id: &EntityId) -> String {
    format!("{}.md", id.path())
}

/// Validate that an `EntityId`'s path matches the wiki-link grammar
/// (`^[\p{Ll}\p{Lo}\p{Lm}\p{N}-]+(/[\p{Ll}\p{Lo}\p{Lm}\p{N}-]+)*$`).
/// Same regex the strict ingress validator applies to inline
/// `[[...]]` targets — keeping the two gates aligned ensures the
/// relate-target path doesn't admit ids that would fail an in-body
/// wiki-link parse.
///
/// Accepted character classes match what [`title_to_slug`] produces:
/// Unicode lowercase letters (`\p{Ll}`), case-less letters
/// (`\p{Lo}` — CJK, Arabic, Hebrew, Devanagari, Thai, …), modifier
/// letters (`\p{Lm}` — e.g. Japanese prolonged-sound mark `ー`),
/// any Unicode numeric (`\p{N}`), and hyphen. Mem names stay
/// ASCII — see [`validate_mem_name_grammar`]. F1 (option B+A).
///
/// Returns the original path on success, an error message on failure.
/// Callers wrap the failure into a typed envelope (e.g.
/// `INVALID_ENTITY_ID`).
pub fn validate_id_path_grammar(path: &str) -> Result<&str, String> {
    use std::sync::OnceLock;
    static RE: OnceLock<regex::Regex> = OnceLock::new();
    let re = RE.get_or_init(|| {
        regex::Regex::new(
            r"^[\p{Ll}\p{Lo}\p{Lm}\p{Mn}\p{Mc}\p{N}-]+(/[\p{Ll}\p{Lo}\p{Lm}\p{Mn}\p{Mc}\p{N}-]+)*$",
        )
        .unwrap()
    });
    if re.is_match(path) {
        Ok(path)
    } else {
        Err(format!(
            "id path '{path}' does not match the wiki-link grammar — \
             entity slugs must be lowercase Unicode letters / digits / \
             hyphens, with path segments separated by '/'"
        ))
    }
}

/// Validate a mem name (left side of `--`). Hierarchical paths are
/// first-class: mem names accept `<segment>(/<segment>)*` where each
/// segment matches the single-segment rule (`[a-z0-9-]+`). Leading slashes,
/// trailing slashes, double slashes, and any character outside the
/// allowed segment alphabet are explicit refusals.
///
/// Flat (single-segment) names work unchanged — the
/// regex's `(/<segment>)*` tail matches zero or more times. The
/// storage representation uses the full path for the
/// `__MEMSTEAD` config blob (`__MEMSTEAD:mems/<path>/config.json`), the
/// branch ref (`refs/heads/<path>`), and the in-memory router key.
pub fn validate_mem_name_grammar(mem: &str) -> Result<&str, String> {
    use std::sync::OnceLock;
    static RE: OnceLock<regex::Regex> = OnceLock::new();
    let re = RE.get_or_init(|| regex::Regex::new(r"^[a-z0-9-]+(/[a-z0-9-]+)*$").unwrap());
    if re.is_match(mem) {
        Ok(mem)
    } else {
        Err(format!(
            "mem name '{mem}' must match ^[a-z0-9-]+(/[a-z0-9-]+)*$ \
             (lowercase ASCII / digits / hyphens, optionally segmented \
             by '/' for hierarchical layouts; no leading, trailing, or \
             double slashes)"
        ))
    }
}

/// Validate relationship type. Input is case-insensitive and canonicalised
/// to uppercase; only ASCII letters and underscores are permitted.
pub fn validate_rel_type(rel_type: &str) -> Result<String, String> {
    let cleaned = rel_type.to_uppercase();
    if cleaned.chars().all(|c| c.is_ascii_uppercase() || c == '_') && !cleaned.is_empty() {
        Ok(cleaned)
    } else {
        Err(format!(
            "Invalid relationship type: \"{rel_type}\". Only ASCII letters and underscores allowed (input is canonicalised to uppercase)."
        ))
    }
}

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

    /// Mem-name grammar accepts hierarchical paths and refuses
    /// malformations. Flat (single-segment) names continue to work —
    /// the regex's `(/<segment>)*` tail matches zero or more times.
    #[test]
    fn validate_mem_name_grammar_accepts_hierarchical_paths() {
        // Flat layouts (regression).
        assert!(validate_mem_name_grammar("specs").is_ok());
        assert!(validate_mem_name_grammar("my-mem").is_ok());
        assert!(validate_mem_name_grammar("v1").is_ok());
        // Hierarchical layouts.
        assert!(validate_mem_name_grammar("team/sub-mem").is_ok());
        assert!(validate_mem_name_grammar("a/b/c/d").is_ok());
        assert!(validate_mem_name_grammar("planning/2026-q1").is_ok());
    }

    /// Grammar refusals are explicit. Each malformation
    /// case (`/team`, `team/`, `team//sub`,
    /// uppercase / underscore / dot) returns an `Err`.
    #[test]
    fn validate_mem_name_grammar_refuses_malformations() {
        // Leading slash.
        assert!(validate_mem_name_grammar("/team/sub").is_err());
        // Trailing slash.
        assert!(validate_mem_name_grammar("team/sub/").is_err());
        // Double slash.
        assert!(validate_mem_name_grammar("team//sub").is_err());
        // Empty.
        assert!(validate_mem_name_grammar("").is_err());
        // Uppercase.
        assert!(validate_mem_name_grammar("Team/Sub").is_err());
        // Underscore (not in allowed alphabet).
        assert!(validate_mem_name_grammar("team_sub").is_err());
        assert!(validate_mem_name_grammar("team/sub_mem").is_err());
        // Dot.
        assert!(validate_mem_name_grammar("team.sub").is_err());
        // Space.
        assert!(validate_mem_name_grammar("team sub").is_err());
    }

    #[test]
    fn title_to_slug_basic() {
        assert_eq!(title_to_slug("My Entity").unwrap(), "my-entity");
        assert_eq!(title_to_slug("My  Entity  Name").unwrap(), "my-entity-name");
    }

    /// F1 (B+A) behaviour change: precomposed Latin diacritics are
    /// preserved in the slug rather than transliterated to ASCII.
    /// `Große Änderung` was `grosse-aenderung` pre-F1; it is now
    /// `große-änderung`. Same applies to `naïve`, `Café résumé`,
    /// `Łódź`, etc. — slug matches title in every script the
    /// Unicode `is_alphanumeric` predicate accepts.
    #[test]
    fn title_to_slug_german() {
        assert_eq!(title_to_slug("Große Änderung").unwrap(), "große-änderung");
        assert_eq!(title_to_slug("Björn").unwrap(), "björn");
    }

    #[test]
    fn title_to_slug_diacritics() {
        assert_eq!(title_to_slug("Café résumé").unwrap(), "café-résumé");
        assert_eq!(title_to_slug("naïve").unwrap(), "naïve");
    }

    #[test]
    fn title_to_slug_special_chars() {
        assert_eq!(title_to_slug("Hello, World!").unwrap(), "hello-world");
        assert_eq!(
            title_to_slug("--leading--trailing--").unwrap(),
            "leading-trailing"
        );
    }

    #[test]
    fn title_to_slug_polish() {
        assert_eq!(title_to_slug("Łódź").unwrap(), "łódź");
    }

    /// F1 (B+A): CJK titles round-trip cleanly. No transliteration,
    /// no hash — the slug equals the title.
    #[test]
    fn title_to_slug_cjk() {
        assert_eq!(
            title_to_slug("日本語のタイトル").unwrap(),
            "日本語のタイトル"
        );
        // Spaces still collapse to hyphens.
        assert_eq!(title_to_slug("中文 標題").unwrap(), "中文-標題");
        // Mixed CJK + Latin + digits.
        assert_eq!(title_to_slug("Project 日本 v2").unwrap(), "project-日本-v2");
    }

    /// F1 (B+A): cased non-Latin scripts (Cyrillic, Greek, Armenian)
    /// case-fold to lowercase the same way Latin does.
    #[test]
    fn title_to_slug_cyrillic() {
        assert_eq!(title_to_slug("Москва").unwrap(), "москва");
        assert_eq!(title_to_slug("Москва-проект").unwrap(), "москва-проект");
        assert_eq!(title_to_slug("ПРОЕКТ ПЛАН").unwrap(), "проект-план");
    }

    /// F1 (B+A): Right-to-left scripts. Hebrew and Arabic letters
    /// are `\p{Lo}` (case-less); they pass through unchanged.
    /// Hebrew niqqud and Arabic harakat are `\p{Mn}` (nonspacing
    /// marks) carrying the Unicode `Other_Alphabetic` property, so
    /// Rust's `is_alphanumeric` treats them as alphabetic and the
    /// slug filter keeps them — wiki-link round-trip is exact for
    /// titles that include vowelization. (The wiki-link regex
    /// accepts the wider `\p{Mn}`/`\p{Mc}` class for the same
    /// reason; see `slug_path_regex` in `validator/strict.rs`.)
    #[test]
    fn title_to_slug_rtl() {
        // Hebrew with niqqud — niqqud is preserved; spaces become hyphens.
        assert_eq!(title_to_slug("תַּפְקִיד עברי").unwrap(), "תַּפְקִיד-עברי");
        // Arabic with harakat — harakat preserved (same Other_Alphabetic property).
        assert_eq!(title_to_slug("مَرْحَبًا").unwrap(), "مَرْحَبًا");
        // Plain Hebrew without vowelization (the more common case)
        // round-trips letter-for-letter.
        assert_eq!(title_to_slug("שלום עולם").unwrap(), "שלום-עולם");
    }

    /// F1 (option A backstop): titles whose pipeline yields an
    /// empty slug fall through to a deterministic short-hash id
    /// rather than failing. Covers all-emoji, all-symbol,
    /// all-punctuation, and empty/whitespace inputs.
    #[test]
    fn title_to_slug_residual_falls_back_to_hash() {
        // All emoji.
        let emoji = title_to_slug("🚀✨").unwrap();
        assert!(emoji.starts_with("entity-"), "got {emoji}");
        assert_eq!(emoji.len(), "entity-".len() + 8);
        // Same input always produces same hash (deterministic).
        assert_eq!(emoji, title_to_slug("🚀✨").unwrap());
        // Different inputs produce different hashes.
        assert_ne!(emoji, title_to_slug("🌟").unwrap());

        // Empty / whitespace / punctuation-only all hit the same path.
        assert!(title_to_slug("").unwrap().starts_with("entity-"));
        assert!(title_to_slug("   ").unwrap().starts_with("entity-"));
        assert!(title_to_slug("\t\n").unwrap().starts_with("entity-"));
        assert!(title_to_slug("---").unwrap().starts_with("entity-"));
        assert!(title_to_slug("!!!").unwrap().starts_with("entity-"));
        assert!(title_to_slug("!?.,;").unwrap().starts_with("entity-"));
    }

    /// NFC normalization is load-bearing for cross-platform safety:
    /// a `Café` written NFD (`Cafe` + combining-acute U+0301) and
    /// one written NFC (single codepoint U+00E9) must produce the
    /// same slug. Pre-F1 the pipeline NFD-decomposed and stripped
    /// combining marks, yielding `cafe` for both — that path is
    /// gone, so the NFC normalization step is what holds the
    /// invariant now.
    #[test]
    fn title_to_slug_nfc_normalization() {
        let nfc = "Café"; // single-codepoint é
        let nfd = "Cafe\u{0301}"; // e + combining acute
        assert_ne!(nfc, nfd, "NFC and NFD forms must differ at the byte level");
        assert_eq!(
            title_to_slug(nfc).unwrap(),
            title_to_slug(nfd).unwrap(),
            "NFC and NFD inputs must produce the same slug",
        );
    }

    /// F4: the strict mutation-entry gate rejects empty titles with
    /// `TitleEmpty` so the wire envelope can carry `reason: "empty"`
    /// rather than silently producing a hash-fallback slug.
    #[test]
    fn validate_and_derive_slug_rejects_empty() {
        // `"\t\n"` is no longer here: it contains control characters, so
        // the more specific control-char guard fires first (see
        // `validate_and_derive_slug_rejects_control_chars`). These cases
        // hold no control chars and collapse to an empty slug.
        for empty in ["", "   ", "---", " - - - ", "-"] {
            let err = validate_and_derive_slug(empty).unwrap_err();
            let SlugError::TitleEmpty { input } = err else {
                panic!("expected TitleEmpty for {empty:?}, got {err:?}");
            };
            assert_eq!(input, empty);
        }
    }

    /// F10 + F19: any character the permissive pipeline would drop
    /// (emoji, punctuation, math/currency symbols, path separators)
    /// is admitted — the title is display text — with the dropped
    /// characters reported and the slug derived exactly as the
    /// permissive pipeline would (the old refusal's `proposed_slug`
    /// is now simply the slug).
    #[test]
    fn validate_and_derive_slug_admits_and_reports_dropped_chars() {
        let cases: &[(&str, &[char], &str)] = &[
            ("Hello, World!", &[',', '!'], "hello-world"),
            ("Café — résumé", &['—'], "café-résumé"),
            ("🚀 launch", &['🚀'], "launch"),
            ("price € 100", &['€'], "price-100"),
            ("../escape", &['.', '/'], "escape"),
            ("path/to/entity", &['/'], "pathtoentity"),
            ("a\\b", &['\\'], "ab"),
            ("Wohnung 2.OG rechts", &['.'], "wohnung-2og-rechts"),
            (
                "Anlage 4a – Leistungsbeschreibung",
                &['–'],
                "anlage-4a-leistungsbeschreibung",
            ),
            (
                "Bösenberg Grundstücks GmbH & Co. KG",
                &['&', '.'],
                "bösenberg-grundstücks-gmbh-co-kg",
            ),
        ];
        for (title, expected_dropped, expected_slug) in cases {
            let got = validate_and_derive_slug(title)
                .unwrap_or_else(|e| panic!("expected ok for {title:?}, got {e:?}"));
            assert_eq!(got.slug, *expected_slug, "title={title:?}");
            assert_eq!(got.dropped_chars, *expected_dropped, "title={title:?}");
            // Byte-identical to the permissive pipeline, always.
            assert_eq!(got.slug, title_to_slug(title).unwrap(), "title={title:?}");
        }
    }

    /// F8: control characters (newline, tab,
    /// carriage return, other C0 controls) are refused with
    /// `TitleHasControlChars` rather than silently folded to hyphens —
    /// they would otherwise split the stored `# H1` and truncate every
    /// read of the title. The proposed slug is the single-line form.
    #[test]
    fn validate_and_derive_slug_rejects_control_chars() {
        let cases: &[(&str, &[char], &str)] = &[
            (
                "Tab\tand\nnewline title",
                &['\t', '\n'],
                "tab-and-newline-title",
            ),
            ("line\rreturn", &['\r'], "line-return"),
            ("null\u{0}byte", &['\u{0}'], "nullbyte"),
        ];
        for (title, expected_control, expected_proposed) in cases {
            let err = validate_and_derive_slug(title).unwrap_err();
            let SlugError::TitleHasControlChars {
                input,
                control_chars,
                proposed_slug,
            } = err
            else {
                panic!("expected TitleHasControlChars for {title:?}, got {err:?}");
            };
            assert_eq!(input, *title);
            assert_eq!(control_chars, *expected_control, "title={title:?}");
            assert_eq!(proposed_slug, *expected_proposed, "title={title:?}");
        }
    }

    /// A plain space is whitespace but NOT a control character, so it
    /// must keep folding to a hyphen (the control-char guard does not
    /// narrow ordinary whitespace handling).
    #[test]
    fn validate_and_derive_slug_space_is_not_control() {
        assert_eq!(validate_and_derive_slug("a b c").unwrap().slug, "a-b-c");
    }

    /// Success path — titles whose every character survives the
    /// pipeline round-trip cleanly produce the same slug as
    /// `title_to_slug` would.
    #[test]
    fn validate_and_derive_slug_success() {
        let cases: &[(&str, &str)] = &[
            ("My Entity", "my-entity"),
            ("Große Änderung", "große-änderung"),
            ("日本語のタイトル", "日本語のタイトル"),
            ("--leading--trailing--", "leading-trailing"),
            ("Project 日本 v2", "project-日本-v2"),
        ];
        for (title, expected) in cases {
            let got = validate_and_derive_slug(title)
                .unwrap_or_else(|e| panic!("expected ok for {title:?}, got {e:?}"));
            assert_eq!(&got.slug, expected, "title={title:?}");
            // A title the old grammar admitted drops nothing.
            assert!(got.dropped_chars.is_empty(), "title={title:?}");
            // Must agree with the permissive pipeline for accepted titles.
            assert_eq!(got.slug, title_to_slug(title).unwrap(), "title={title:?}");
        }
    }

    /// The strict gate runs the same NFC normalization as the
    /// permissive pipeline, so NFC and NFD spellings of the same
    /// title produce the same slug (or both reject).
    #[test]
    fn validate_and_derive_slug_nfc_normalization() {
        let nfc = "Café";
        let nfd = "Cafe\u{0301}";
        assert_eq!(
            validate_and_derive_slug(nfc).unwrap().slug,
            validate_and_derive_slug(nfd).unwrap().slug,
        );
    }

    /// SlugError::reason() returns the stable discriminator each
    /// surface uses on the `details.reason` field.
    #[test]
    fn slug_error_reason_discriminator() {
        let e = SlugError::TitleEmpty {
            input: "".to_string(),
        };
        assert_eq!(e.reason(), "empty");
        let e = SlugError::IdTooLong {
            input: "specs--x".to_string(),
            length: 201,
            max: 200,
        };
        assert_eq!(e.reason(), "id_too_long");
        let e = SlugError::TitleHasControlChars {
            input: "a\nb".to_string(),
            control_chars: vec!['\n'],
            proposed_slug: "a-b".to_string(),
        };
        assert_eq!(e.reason(), "control_chars");
    }

    /// F2 + F4: a title that derives a slug whose full
    /// `mem--slug` id sits at the 200-char ceiling is accepted;
    /// one byte over is rejected with a recovery-friendly error.
    /// `build_id` is the canonical write-side entry, so both
    /// behaviours land here.
    #[test]
    fn build_id_enforces_length_cap() {
        let mem = "specs";
        // mem.len()=5, "--"=2 → 7-char prefix. Slug of 193 chars
        // produces a 200-char id; 194 chars trips the cap.
        let just_fits = "a".repeat(ENTITY_ID_MAX_LEN - mem.len() - 2);
        let ok = build_id(mem, &just_fits).expect("at-cap id must pass");
        assert_eq!(ok.as_ref().chars().count(), ENTITY_ID_MAX_LEN);

        let one_over = "a".repeat(ENTITY_ID_MAX_LEN - mem.len() - 2 + 1);
        let err = build_id(mem, &one_over).unwrap_err();
        let SlugError::IdTooLong { input, length, max } = err else {
            panic!("expected IdTooLong, got {err:?}");
        };
        // `input` echoes the composed id, not the title, so it agrees
        // with `length`.
        assert_eq!(input, format!("{mem}--{one_over}"));
        assert_eq!(input.chars().count(), length);
        assert_eq!(length, ENTITY_ID_MAX_LEN + 1);
        assert_eq!(max, ENTITY_ID_MAX_LEN);
    }

    #[test]
    fn build_id_basic() {
        assert_eq!(
            build_id("specs", "My Entity").unwrap().0,
            "specs--my-entity"
        );
    }

    /// F1 (B+A): non-Latin titles round-trip through `build_id`.
    #[test]
    fn build_id_non_latin() {
        assert_eq!(
            build_id("specs", "日本語のタイトル").unwrap().0,
            "specs--日本語のタイトル",
        );
        assert_eq!(
            build_id("specs", "Москва-проект").unwrap().0,
            "specs--москва-проект",
        );
    }

    #[test]
    fn file_path_to_id_basic() {
        assert_eq!(
            file_path_to_id("architecture/result-entity.md", "specs").0,
            "specs--architecture/result-entity"
        );
        assert_eq!(
            file_path_to_id("result-entity.md", "specs").0,
            "specs--result-entity"
        );
    }

    #[test]
    fn wiki_link_to_id_basic() {
        assert_eq!(
            wiki_link_to_id("result-entity", "specs").unwrap().0,
            "specs--result-entity"
        );
        assert_eq!(
            wiki_link_to_id("parent/child/entity", "specs").unwrap().0,
            "specs--parent/child/entity"
        );
    }

    #[test]
    fn wiki_link_to_id_strips_alias() {
        assert_eq!(
            wiki_link_to_id("target|Display Name", "specs").unwrap().0,
            "specs--target"
        );
    }

    #[test]
    fn wiki_link_to_id_strips_prefix_and_suffix() {
        assert_eq!(
            wiki_link_to_id("../parent/entity.md", "specs").unwrap().0,
            "specs--parent/entity"
        );
    }

    /// Agents writing the canonical fully-qualified id `[[mem--slug]]`
    /// must not be doubly-prefixed into `mem--mem--slug`.
    #[test]
    fn wiki_link_to_id_strips_redundant_self_prefix() {
        assert_eq!(
            wiki_link_to_id("specs--result-entity", "specs").unwrap().0,
            "specs--result-entity"
        );
        assert_eq!(
            wiki_link_to_id("test-mem-mini--engine", "test-mem-mini")
                .unwrap()
                .0,
            "test-mem-mini--engine"
        );
        assert_eq!(
            wiki_link_to_id("specs--target.md|Display", "specs")
                .unwrap()
                .0,
            "specs--target"
        );
        assert_eq!(
            wiki_link_to_id("specs--parent/child", "specs").unwrap().0,
            "specs--parent/child"
        );
        // Self-prefix stripping is one-shot, not iterative — a second
        // embedded `<current_mem>--` is preserved so cross-mem-style
        // drift stays visible.
        assert_eq!(
            wiki_link_to_id("specs--specs--slug", "specs").unwrap().0,
            "specs--specs--slug"
        );
    }

    /// Cross-mem dash form `[[<mem>--<slug>]]` routes to the named
    /// mem rather than silently re-prepending the source mem into a
    /// phantom `specs--other--entity` stub.
    /// The cross-mem policy gate (alias-synthesis pass) refuses the
    /// auto-stub when the workspace policy denies the direction —
    /// that gate is exercised in engine-layer tests.
    #[test]
    fn wiki_link_to_id_tier_zero_cross_mem_dash_form() {
        assert_eq!(
            wiki_link_to_id("other--entity", "specs").unwrap().0,
            "other--entity"
        );
        assert_eq!(
            wiki_link_to_id("nonexistent-mem--target", "specs")
                .unwrap()
                .0,
            "nonexistent-mem--target"
        );
    }

    /// Tier-0 dash form collapses cleanly when the named mem is the
    /// source mem — equivalent to the self-prefix-strip fast path
    /// for bare-slug authoring.
    #[test]
    fn wiki_link_to_id_tier_zero_self_mem_dash_form() {
        assert_eq!(
            wiki_link_to_id("specs--target", "specs").unwrap().0,
            "specs--target"
        );
    }

    /// Tier-0 only admits single-segment mem names — the
    /// hierarchical dash form stays on the colon Tier-2 recovery
    /// path. The pre-existing slash-dash ambiguity refusal is what
    /// fires here (cross-mem into a hierarchical mem is
    /// grammatically ambiguous with a same-mem hierarchical slug).
    #[test]
    fn wiki_link_to_id_tier_zero_refuses_hierarchical_prefix() {
        let err = wiki_link_to_id("team/sub-mem--target", "specs").unwrap_err();
        match err {
            WikiLinkError::InvalidTarget { suggested, .. } => {
                assert_eq!(suggested.as_deref(), Some("team/sub-mem:target"));
            }
            other => panic!("expected InvalidTarget, got {other:?}"),
        }
    }

    /// Section anchors strip as a display decoration alongside `|alias`,
    /// `../`, and `.md`. Single anchor, multi-anchor, and the
    /// combined anchor+alias form all collapse to the underlying
    /// slug-form id.
    #[test]
    fn wiki_link_to_id_strips_section_anchor() {
        assert_eq!(
            wiki_link_to_id("login-service#identity", "specs")
                .unwrap()
                .0,
            "specs--login-service"
        );
        assert_eq!(
            wiki_link_to_id("specs--login-service#identity", "specs")
                .unwrap()
                .0,
            "specs--login-service"
        );
        // Multi-anchor — strip from first `#`.
        assert_eq!(
            wiki_link_to_id("specs--target#a#b", "specs").unwrap().0,
            "specs--target"
        );
        // Combined anchor + alias.
        assert_eq!(
            wiki_link_to_id("specs--target#section|Display", "specs")
                .unwrap()
                .0,
            "specs--target"
        );
    }

    /// Cross-mem routing and anchor stripping compose: a cross-mem
    /// anchored form resolves under tier-0 and strips the anchor.
    #[test]
    fn wiki_link_to_id_cross_mem_anchored_composes() {
        assert_eq!(
            wiki_link_to_id("other--target#section", "specs").unwrap().0,
            "other--target"
        );
    }

    /// Empty `current_mem` opts out of self-prefix stripping so a
    /// literal leading `--` (which would never legitimately occur, but
    /// could collide with `format!("{mem}--", mem="")`) stays intact.
    #[test]
    fn wiki_link_to_id_empty_mem_does_not_strip() {
        assert_eq!(wiki_link_to_id("--weird", "").unwrap().0, "----weird");
    }

    #[test]
    fn wiki_link_to_id_tier_two_cross_mem() {
        assert_eq!(
            wiki_link_to_id("engine:health", "plugin").unwrap().0,
            "engine--health"
        );
        assert_eq!(
            wiki_link_to_id("engine:architecture/result", "plugin")
                .unwrap()
                .0,
            "engine--architecture/result"
        );
    }

    #[test]
    fn wiki_link_to_id_tier_two_self_prefix_collapses() {
        assert_eq!(
            wiki_link_to_id("specs:foo", "specs").unwrap().0,
            "specs--foo"
        );
        assert_eq!(
            wiki_link_to_id("specs:foo", "specs").unwrap(),
            wiki_link_to_id("foo", "specs").unwrap()
        );
    }

    #[test]
    fn wiki_link_to_id_tier_two_combines_with_alias_and_md() {
        assert_eq!(
            wiki_link_to_id("engine:health.md|See health", "plugin")
                .unwrap()
                .0,
            "engine--health"
        );
    }

    #[test]
    fn wiki_link_to_id_tier_two_accepts_hierarchical_prefix() {
        assert_eq!(
            wiki_link_to_id("external/engine:health", "plugin")
                .unwrap()
                .0,
            "external/engine--health"
        );
    }

    #[test]
    fn wiki_link_to_id_tier_one_strips_hierarchical_self_prefix() {
        assert_eq!(
            wiki_link_to_id("team/sub-mem--auth-service", "team/sub-mem")
                .unwrap()
                .0,
            "team/sub-mem--auth-service"
        );
    }

    #[test]
    fn wiki_link_to_id_tier_one_bare_slug_from_hierarchical_mem() {
        assert_eq!(
            wiki_link_to_id("auth-service", "team/sub-mem").unwrap().0,
            "team/sub-mem--auth-service"
        );
    }

    /// `::` is reserved syntax — strict refusal. The slug-grammar gate
    /// refuses the `:` character outright.
    #[test]
    fn wiki_link_to_id_double_colon_refuses() {
        let err = wiki_link_to_id("engine::health", "plugin").unwrap_err();
        assert!(
            matches!(err, WikiLinkError::InvalidTarget { .. }),
            "got {err:?}"
        );
    }

    /// Empty halves around the colon refuse under strict mode — the
    /// `:` character isn't in the slug-grammar character class, so
    /// the Tier-1 fallback fails.
    #[test]
    fn wiki_link_to_id_empty_tier_two_halves_refuse() {
        assert!(matches!(
            wiki_link_to_id(":foo", "specs").unwrap_err(),
            WikiLinkError::InvalidTarget { .. }
        ));
        assert!(matches!(
            wiki_link_to_id("engine:", "specs").unwrap_err(),
            WikiLinkError::InvalidTarget { .. }
        ));
    }

    /// Natural-form (uppercase + whitespace) refuses with
    /// `InvalidTarget` and a `title_to_slug`-derived suggestion the
    /// agent lifts directly into a retry.
    #[test]
    fn wiki_link_to_id_natural_form_refuses_with_suggestion() {
        let err = wiki_link_to_id("Knowledge Graph", "specs").unwrap_err();
        let WikiLinkError::InvalidTarget { raw, suggested, .. } = err else {
            panic!("expected InvalidTarget, got {err:?}");
        };
        assert_eq!(raw, "Knowledge Graph");
        assert_eq!(suggested.as_deref(), Some("knowledge-graph"));
    }

    /// Tier-2 with natural-form slug suggests `mem:slug`
    /// preserving the prefix. The agent rewrites only the slug part.
    #[test]
    fn wiki_link_to_id_tier_two_natural_slug_refuses_with_prefixed_suggestion() {
        let err = wiki_link_to_id("engine:Health Check", "plugin").unwrap_err();
        let WikiLinkError::InvalidTarget { raw, suggested, .. } = err else {
            panic!("expected InvalidTarget, got {err:?}");
        };
        assert_eq!(raw, "engine:Health Check");
        assert_eq!(suggested.as_deref(), Some("engine:health-check"));
    }

    /// Tier-1 dash form
    /// with `/` in the would-be mem prefix is grammatically
    /// ambiguous (cross-mem into a hierarchical mem vs same-mem
    /// hierarchical slug). Refusal carries the colon-form as
    /// `suggested` so the agent's recovery is a one-character edit.
    #[test]
    fn wiki_link_to_id_hierarchical_dash_form_refuses_with_colon_suggestion() {
        let err = wiki_link_to_id("team/sub-mem--auth-service", "test").unwrap_err();
        let WikiLinkError::InvalidTarget {
            raw,
            suggested,
            reason,
        } = err
        else {
            panic!("expected InvalidTarget, got {err:?}");
        };
        assert_eq!(raw, "team/sub-mem--auth-service");
        assert_eq!(suggested.as_deref(), Some("team/sub-mem:auth-service"));
        // Reason names both disambiguations.
        assert!(
            reason.contains("team/sub-mem:auth-service"),
            "reason must surface the cross-mem colon form: {reason}"
        );
        assert!(
            reason.contains("test:team/sub-mem--auth-service"),
            "reason must surface the same-mem hierarchical form: {reason}"
        );
    }

    /// For self-prefixed dash form, tier-0 splits on the FIRST `--`, so
    /// `[[test--team/sub--target]]` resolves as mem `test`, slug
    /// `team/sub--target` — a same-mem entity with a hierarchical
    /// slug containing `--`. The ambiguity gate in the slug position
    /// does not apply because the mem/slug boundary is
    /// pinned by tier-0's grammar.
    #[test]
    fn wiki_link_to_id_self_prefixed_dash_form_resolves_via_tier_zero() {
        let id = wiki_link_to_id("test--team/sub--target", "test").unwrap();
        assert_eq!(id.mem(), "test");
        assert_eq!(id.path(), "team/sub--target");
    }

    /// A bare hierarchical slug (no `--`) continues to
    /// resolve to a same-mem entity. The refusal is keyed on the
    /// simultaneous presence of `/` AND `--`, not on `/` alone.
    #[test]
    fn wiki_link_to_id_bare_hierarchical_slug_still_resolves() {
        let id = wiki_link_to_id("team/sub-mem", "test").unwrap();
        assert_eq!(id.mem(), "test");
        assert_eq!(id.path(), "team/sub-mem");
    }

    /// Colon-form for cross-mem hierarchical reference
    /// continues to resolve correctly (the canonical disambiguation).
    #[test]
    fn wiki_link_to_id_hierarchical_colon_form_resolves_cross_mem() {
        let id = wiki_link_to_id("team/sub-mem:auth-service", "test").unwrap();
        assert_eq!(id.mem(), "team/sub-mem");
        assert_eq!(id.path(), "auth-service");
    }

    /// Flat `[[<other-mem>--<slug>]]` routes to the named mem under
    /// tier-0 rather than silently re-prefixing with the source mem into
    /// a phantom `test--other--target` stub. The cross-mem policy
    /// gate enforces routing legality in the alias-synthesis pass —
    /// that gate is exercised in engine-layer tests.
    #[test]
    fn wiki_link_to_id_flat_foreign_dash_form_routes_via_tier_zero() {
        let id = wiki_link_to_id("other--target", "test").unwrap();
        assert_eq!(id.mem(), "other");
        assert_eq!(id.path(), "target");
    }

    /// Tier-2 with non-ASCII mem prefix refuses with
    /// `InvalidMemName`. Mem names are ASCII-only operator
    /// identifiers; the agent cannot auto-slugify them.
    #[test]
    fn wiki_link_to_id_tier_two_bad_mem_refuses_with_distinct_error() {
        let err = wiki_link_to_id("Other Mem:foo", "plugin").unwrap_err();
        let WikiLinkError::InvalidMemName { raw, .. } = err else {
            panic!("expected InvalidMemName, got {err:?}");
        };
        assert_eq!(raw, "Other Mem");
    }

    /// Pathological inputs (empty, all punctuation) refuse
    /// with `suggested: None`.
    #[test]
    fn wiki_link_to_id_pathological_input_no_suggestion() {
        let err = wiki_link_to_id("!!!", "specs").unwrap_err();
        let WikiLinkError::InvalidTarget { suggested, .. } = err else {
            panic!("expected InvalidTarget, got {err:?}");
        };
        assert!(suggested.is_none(), "got {suggested:?}");
    }

    /// Slug-form across every script family the slug
    /// pipeline accepts round-trips through the strict gate.
    #[test]
    fn wiki_link_to_id_accepts_slug_form_across_scripts() {
        let cases: &[(&str, &str)] = &[
            ("knowledge-graph", "v--knowledge-graph"),
            ("الرسم-البياني-للمعرفة", "v--الرسم-البياني-للمعرفة"),
            ("ज्ञान-ग्राफ", "v--ज्ञान-ग्राफ"),
            ("知识图谱", "v--知识图谱"),
            ("知識グラフ", "v--知識グラフ"),
            ("กราฟความรู้", "v--กราฟความรู้"),
            ("ידע-גרף", "v--ידע-גרף"),
        ];
        for (input, expected) in cases {
            let id = wiki_link_to_id(input, "v")
                .unwrap_or_else(|e| panic!("expected ok for {input:?}, got {e:?}"));
            assert_eq!(&id.0, expected, "input={input:?}");
        }
    }

    /// The lenient decoder preserves pre-strict behaviour
    /// for read-side scanners that must tolerate on-disk drift.
    /// Round-trip equivalence on the inputs the strict gate accepts.
    #[test]
    fn wiki_link_to_id_lenient_matches_strict_on_valid_input() {
        let inputs = &["knowledge-graph", "engine:health", "parent/child"];
        for input in inputs {
            let strict = wiki_link_to_id(input, "specs").unwrap();
            let lenient = wiki_link_to_id_lenient(input, "specs");
            assert_eq!(strict, lenient, "input={input:?}");
        }
    }

    /// The lenient decoder accepts what the strict gate
    /// refuses, surfacing the literal drift for read-side reporting.
    #[test]
    fn wiki_link_to_id_lenient_admits_drift() {
        assert_eq!(
            wiki_link_to_id_lenient("Knowledge Graph", "specs").0,
            "specs--Knowledge Graph"
        );
        assert_eq!(
            wiki_link_to_id_lenient("engine::health", "plugin").0,
            "plugin--engine::health"
        );
    }

    #[test]
    fn entity_id_parts() {
        let id = EntityId::new("specs", "parent/child");
        assert_eq!(id.mem(), "specs");
        assert_eq!(id.path(), "parent/child");
        assert_eq!(id.name(), "child");
    }

    #[test]
    fn entity_id_no_mem() {
        let id = EntityId("result-entity".to_string());
        assert_eq!(id.mem(), "");
        assert_eq!(id.path(), "result-entity");
        assert_eq!(id.name(), "result-entity");
    }

    #[test]
    fn id_to_file_path_basic() {
        let id = EntityId::new("specs", "architecture/result-entity");
        assert_eq!(id_to_file_path(&id), "architecture/result-entity.md");
    }

    #[test]
    fn validate_rel_type_valid() {
        assert_eq!(validate_rel_type("PART_OF").unwrap(), "PART_OF");
        assert_eq!(validate_rel_type("uses").unwrap(), "USES");
    }

    #[test]
    fn validate_rel_type_invalid() {
        assert!(validate_rel_type("has spaces").is_err());
        assert!(validate_rel_type("").is_err());
    }

    /// TITLE_GRAMMAR_RULE conformance: the documented sentence and the
    /// validator agree — any single-line text is admitted, characters
    /// outside the slug alphabet are dropped from the slug and
    /// reported, and control characters are the rejection. If this
    /// test fails, either the validator's behaviour or the constant
    /// changed alone; change them together.
    #[test]
    fn title_grammar_rule_matches_validator_behaviour() {
        // Admitted with nothing dropped: Unicode alphanumerics,
        // whitespace, hyphen.
        for ok in [
            "Plain Title",
            "hyphen-ated",
            "Große Änderung", // non-ASCII alphanumerics
            "日本語 タイトル",
            "nbsp\u{a0}space", // non-control whitespace folds to hyphen
        ] {
            let got = validate_and_derive_slug(ok)
                .unwrap_or_else(|e| panic!("rule says {ok:?} is accepted, got {e:?}"));
            assert!(got.dropped_chars.is_empty(), "{ok:?} drops nothing");
        }
        // Admitted per the rule, with characters outside the slug
        // alphabet dropped from the slug and reported — the plenum
        // collision list plus representative symbol/punctuation cases.
        for (title, dropped) in [
            ("v1.0", '.'),
            ("a (draft)", '('),
            ("a (draft", '('),
            ("either/or", '/'),
            ("re: title", ':'),
            ("a \u{2014} b", '\u{2014}'), // em dash
            ("hello!", '!'),
        ] {
            let got = validate_and_derive_slug(title)
                .unwrap_or_else(|e| panic!("rule says {title:?} is admitted, got {e:?}"));
            assert!(
                got.dropped_chars.contains(&dropped),
                "{title:?}: the divergence report names {dropped:?}, got {:?}",
                got.dropped_chars
            );
            assert!(
                !got.slug.is_empty(),
                "{title:?}: a slug still derives from the surviving characters"
            );
        }
        // Control-class whitespace (tab, newline) is the rejection,
        // per the rule's parenthetical.
        for title in ["tabs\tinside", "line\nbreak"] {
            assert!(
                matches!(
                    validate_and_derive_slug(title),
                    Err(SlugError::TitleHasControlChars { .. })
                ),
                "rule says {title:?} is rejected as a control character"
            );
        }
    }
}