memstead_base/entity/

parser.rs

//! Markdown → Entity parser. Handles YAML frontmatter, sections, wiki-links.
//!
//! Key design decisions:
//! - Hand-rolled YAML frontmatter parser (NOT serde_yaml) to match JS type coercion
//! - Code blocks are masked before section/link detection to prevent false matches
//! - The parser is schema-aware: it uses the schema to determine catch-all sections

use std::collections::{HashMap, HashSet};
use std::path::Path;
use std::sync::OnceLock;

use indexmap::IndexMap;
use regex::Regex;
use sha2::{Digest, Sha256};

use memstead_schema::TypeDefinition;

use super::id::{WikiLinkError, file_path_to_id, wiki_link_to_id, wiki_link_to_id_lenient};
use super::{Entity, EntityId, HeadingSpan, MetadataValue, ParseResult, Relationship};

/// Parse a markdown string into an Entity.
pub fn parse_markdown(
    content: &str,
    relative_path: &str,
    schema: &TypeDefinition,
    mem: &str,
) -> Result<ParseResult, ParseError> {
    let id = file_path_to_id(relative_path, mem);

    // Compute content hash from raw markdown
    let content_hash = compute_hash(content);

    // Extract YAML frontmatter FIRST — frontmatter is not markdown, and
    // handing it to a CommonMark parser invents block structure that is
    // not there (a value line that reads as a fence opener would open a
    // code block running past the closing `---` and mask the whole
    // body). Only the body is markdown, so only the body is masked.
    let (metadata, body) = split_frontmatter(content)?;
    let masked_body = mask_code_blocks(&body);

    // Extract title (first # heading)
    let title = extract_title(&body, &masked_body).unwrap_or_else(|| id.name().to_string());

    // Split body into ## sections (match against masked, slice from original).
    // Duplicate `## Heading` lines whose slug matches a schema-declared key
    // become `DuplicateSectionHeading` warnings below; first-wins is the
    // resolution policy.
    let (sections_map, duplicate_headings, raw_section_headings) =
        split_sections(&body, &masked_body);

    // Parse typed relationships from the Relationships section.
    // The entity-id collector lets the parser surface
    // `AMBIGUOUS_DESCRIPTION_DELIMITER` warnings against a concrete
    // source so boot / reload / attach sites can report them in
    // `LoadCollector::warnings`.
    let rel_heading_key = "relationships";
    let entity_id_for_rel_warnings = file_path_to_id(relative_path, mem);
    let (relationships, rel_parse_warnings) = parse_relationships_with_warnings(
        sections_map
            .get(rel_heading_key)
            .map(|(_, content)| content.as_str())
            .unwrap_or(""),
        mem,
        Some(&entity_id_for_rel_warnings),
    );

    // Build catch-all section content
    let catch_all_content = build_catch_all(&sections_map, schema);

    // Extract schema-defined section values.
    // IndexMap + this loop order is what guarantees sections iterate in the
    // schema's declared order downstream. Do not change to a HashMap.
    // No re-trim here: `split_sections` already normalised each value
    // (leading blank lines dropped, first visible line's bytes kept,
    // trailing trimmed), and `build_catch_all` joins such values. A
    // second full trim silently promoted a whitespace-prefixed first
    // line (`\u{b}` + backticks) to column 0, where the CommonMark
    // referee suddenly saw a fence opener that the stored form did not
    // have — the section structure then shifted between rounds (fuzz
    // finding, long tier, corpus member `crash-fd71330e…`).
    let mut result_sections = IndexMap::new();
    for s in &schema.sections {
        if s.catch_all {
            // The catch-all key stays present when its own heading was in
            // the document or any non-schema section fed it — an absent
            // catch-all with no absorbed content stays absent, like every
            // other section below.
            if sections_map.contains_key(s.key.as_str()) || !catch_all_content.trim().is_empty() {
                result_sections.insert(s.key.clone(), catch_all_content.clone());
            }
        } else if let Some((_, content)) = sections_map.get(s.key.as_str()) {
            result_sections.insert(s.key.clone(), content.clone());
        }
        // A declared section whose heading the document does not carry is
        // ABSENT, not present-with-empty. Materialising every declared key
        // here (the pre-fix `unwrap_or_default`) made "no heading" and
        // "empty heading" the same entity, so the generator re-emitted a
        // scaffold heading for every declared-but-unwritten section and
        // `sections_unset` could not close one — the removed key came back
        // on the next round-trip.
    }

    // Parse metadata values with type coercion
    let mut parsed_metadata = parse_metadata(&metadata);

    // Determine type from metadata or default, and ensure it's in metadata.
    // The entity's `type:` frontmatter key takes precedence over the mem's
    // default type — parse-time resolution means each file is authoritative
    // about its own type.
    let type_name = parsed_metadata
        .get("type")
        .and_then(|v| v.as_str())
        .unwrap_or(schema.name.as_str())
        .to_string();
    parsed_metadata.insert("type".to_string(), MetadataValue::String(type_name.clone()));

    // Extract inline wiki-links from text fields (excluding relationships section)
    let inline_link_text: String = schema
        .text_fields
        .iter()
        .filter_map(|f| result_sections.get(f.as_str()))
        .cloned()
        .collect::<Vec<_>>()
        .join("\n");
    // Read-time scan: tolerate pre-strict on-disk drift so loaders
    // and dangling-link reporters keep working against legacy
    // entities. The mutation pipeline re-extracts strictly via
    // `extract_inline_links` and refuses on grammar violations.
    let inline_links = extract_inline_links_lenient(&inline_link_text, mem);

    // Filter out targets already covered by explicit relationships
    let explicit_targets: HashSet<_> = relationships.iter().map(|r| &r.target).collect();
    let inline_links: Vec<EntityId> = inline_links
        .into_iter()
        .filter(|link| !explicit_targets.contains(link))
        .collect();

    // Extract H3–H6 spans per section for search-time heading-path attribution.
    // Side-struct only: regenerated every parse, never persisted.
    let heading_spans = extract_heading_spans(&result_sections);

    // Build warnings for duplicate-heading occurrences whose slug matches a
    // schema-declared key. Catch-all keys (`s.catch_all`) absorb arbitrary
    // headings by design, so duplicates there are not surfaced.
    let declared_keys: HashSet<&str> = schema
        .sections
        .iter()
        .filter(|s| !s.catch_all)
        .map(|s| s.key.as_str())
        .collect();
    let entity_id_for_warnings = file_path_to_id(relative_path, mem);
    let mut parse_warnings: Vec<crate::ops::WarningHint> = duplicate_headings
        .into_iter()
        .filter(|d| declared_keys.contains(d.key.as_str()))
        .map(|d| crate::ops::WarningHint::DuplicateSectionHeading {
            entity_id: entity_id_for_warnings.clone(),
            section_key: d.key,
            heading: d.heading,
            occurrences: d.occurrences,
        })
        .collect();
    parse_warnings.extend(rel_parse_warnings);

    let entity = Entity {
        id,
        title,
        entity_type: type_name,
        mem: mem.to_string(),
        file_path: relative_path.to_string(),
        metadata: parsed_metadata,
        sections: result_sections,
        relationships,
        content_hash,
        stub: false,
        stub_kind: None,
        heading_spans,
        raw_section_headings,
    };

    Ok(ParseResult {
        entity,
        inline_links,
        parse_warnings,
    })
}

/// Parse an entity from a file on disk.
pub fn parse_file(
    path: &Path,
    mem_dir: &Path,
    schema: &TypeDefinition,
    mem: &str,
) -> Result<ParseResult, ParseError> {
    let content = std::fs::read_to_string(path)?;
    let relative_path = path.strip_prefix(mem_dir).unwrap_or(path).to_string_lossy();
    parse_markdown(&content, &relative_path, schema, mem)
}

// ---------------------------------------------------------------------------
// Frontmatter
// ---------------------------------------------------------------------------

// ---------------------------------------------------------------------------
// The frontmatter delimiter contract — one implementation
// ---------------------------------------------------------------------------

/// What a document's leading `---` block turned out to be.
///
/// The three historical readers differed only in what they did with these
/// three cases, never in how they found them: the tolerant path degraded on
/// both failures, the peek borrowed and degraded, the strict path refused with
/// a different typed error for each. That difference belongs to the wrappers;
/// the arithmetic below belongs here, once.
#[derive(Debug, PartialEq, Eq)]
pub(crate) enum Frontmatter<'a> {
    /// A closed block. Both slices borrow the input.
    Present { meta: &'a str, body: &'a str },
    /// The document does not open with `---` on its first line.
    NoOpeningDelimiter,
    /// It opens but never closes with `\n---`.
    Unclosed,
}

/// Split a document at its frontmatter delimiters.
///
/// Returns the byte-order-mark-stripped input alongside the verdict, because
/// every caller that degrades to "the whole document is body" must degrade to
/// the *stripped* document: a marked local file once parsed as all body and
/// lost its entire frontmatter precisely because two paths disagreed about
/// where the document began. **The mark is stripped here and nowhere else.**
///
/// Both returned slices are suffixes of the returned `stripped` slice, which
/// is itself a suffix of `content`. Two callers recover the frontmatter prefix
/// by subtracting the body's length, so a core that copied or normalised
/// anything would break them silently.
pub(crate) fn split_frontmatter_core(content: &str) -> (&str, Frontmatter<'_>) {
    let content = content.strip_prefix('\u{feff}').unwrap_or(content);

    let after_open = if content.starts_with("---\r\n") {
        5
    } else if content.starts_with("---\n") {
        4
    } else {
        return (content, Frontmatter::NoOpeningDelimiter);
    };

    let rest = &content[after_open..];
    let Some(close_pos) = rest.find("\n---") else {
        return (content, Frontmatter::Unclosed);
    };
    let meta = &rest[..close_pos];

    let body_rest = &rest[close_pos + "\n---".len()..];
    let body = body_rest
        .strip_prefix("\r\n")
        .or_else(|| body_rest.strip_prefix('\n'))
        .unwrap_or(body_rest);

    (content, Frontmatter::Present { meta, body })
}

/// Extract the `type:` value from frontmatter without running the full parser.
///
/// Used by the loader to resolve each file's type independently — the mem
/// config's default type is only a fallback for files that don't declare one.
/// Returns None if there's no frontmatter, no `type:` line, or it's empty.
pub fn peek_type_from_frontmatter(content: &str) -> Option<String> {
    let (_, split) = split_frontmatter_core(content);
    let Frontmatter::Present {
        meta: frontmatter, ..
    } = split
    else {
        return None;
    };

    for line in frontmatter.lines() {
        let trimmed = line.trim();
        if trimmed.is_empty() || trimmed.starts_with('#') {
            continue;
        }
        let Some(colon_idx) = trimmed.find(':') else {
            continue;
        };
        let key = trimmed[..colon_idx].trim();
        if key != "type" {
            continue;
        }
        let mut value = trimmed[colon_idx + 1..].trim();
        if let Some(hash_idx) = value.find('#') {
            value = value[..hash_idx].trim();
        }
        let value = value.trim_matches(|c| c == '"' || c == '\'');
        if value.is_empty() {
            return None;
        }
        return Some(value.to_string());
    }
    None
}

/// Peek the entity title (first `# ` heading in the body) and type
/// (`type:` frontmatter field) from raw markdown without running the
/// full schema-aware parser. Used by surfaces that read a markdown blob
/// outside the in-memory store — e.g. `memstead_diff` walking git trees
/// between two arbitrary refs, where the store snapshot (current HEAD)
/// is not a valid source for a non-HEAD ref. Returns `None` for `title`
/// when the body carries no `# ` heading and `None` for `entity_type`
/// when the frontmatter lacks a non-empty `type:`.
pub fn peek_title_and_type(content: &str) -> (Option<String>, Option<String>) {
    let entity_type = peek_type_from_frontmatter(content);
    let body = body_after_frontmatter(content);
    let title = extract_title(body, &mask_code_blocks(body));
    (title, entity_type)
}

/// Return the body slice after a leading `---` frontmatter block, or
/// the whole input when no frontmatter is present. Mirrors the offset
/// arithmetic in [`split_frontmatter`] but borrows rather than
/// allocating — a scan needs to read, not own.
///
/// **Call this before handing a whole entity file to any markdown
/// reader in this module.** Frontmatter is not markdown: a CommonMark
/// parser reads block structure into it that is not there, and a YAML
/// value that looks like a fence opener (legal at 1–3 spaces) opens a
/// code block that runs past the `---` terminator to end of file,
/// masking the entire body. Every reader here — [`mask_code_blocks`],
/// [`extract_inline_links`], [`extract_inline_links_lenient`],
/// [`split_sections`] — expects a body, and the callers inside the
/// engine that hold one already pass section bodies. A caller holding
/// a raw file or git blob does not, and must trim it here first.
pub fn body_after_frontmatter(content: &str) -> &str {
    match split_frontmatter_core(content) {
        (_, Frontmatter::Present { body, .. }) => body,
        (stripped, _) => stripped,
    }
}

/// Split content into frontmatter metadata string and body.
/// Returns (metadata_string, body). Both boundaries are found in the
/// raw content — the caller masks the body afterwards.
pub(crate) fn split_frontmatter(content: &str) -> Result<(String, String), ParseError> {
    // The every-local-read path: it never refuses. A document with no opening
    // delimiter, or an unclosed block, is entirely body — a hand-edited file
    // without frontmatter must still load.
    match split_frontmatter_core(content) {
        (_, Frontmatter::Present { meta, body }) => Ok((meta.to_string(), body.to_string())),
        (stripped, _) => Ok((String::new(), stripped.to_string())),
    }
}

/// Parse metadata key-value pairs with JS-compatible type coercion.
///
/// Handles: strings, integers, floats, booleans.
/// Strips inline comments (`value # comment`) and quotes (`"value"`).
fn parse_metadata(text: &str) -> IndexMap<String, MetadataValue> {
    let mut meta = IndexMap::new();
    if text.is_empty() {
        return meta;
    }

    for line in text.lines() {
        let trimmed = line.trim();
        // Skip empty lines, comments, heading markers, delimiters
        if trimmed.is_empty() || trimmed.starts_with('#') || trimmed.starts_with("---") {
            continue;
        }

        let Some(colon_idx) = trimmed.find(':') else {
            continue;
        };

        let key = trimmed[..colon_idx].trim().to_string();
        let raw_value = trimmed[colon_idx + 1..].trim();

        // Strip inline comments (# not inside the value)
        let value = strip_inline_comment(raw_value).trim().to_string();

        if value.is_empty() {
            meta.insert(key, MetadataValue::String(String::new()));
            continue;
        }

        // Type coercion (matching JS parser behavior exactly)
        if value == "true" {
            meta.insert(key, MetadataValue::Bool(true));
        } else if value == "false" {
            meta.insert(key, MetadataValue::Bool(false));
        } else if is_float_literal(&value) {
            if let Ok(f) = value.parse::<f64>() {
                meta.insert(key, MetadataValue::Float(f));
            } else {
                meta.insert(key, MetadataValue::String(strip_quotes(&value)));
            }
        } else if is_integer_literal(&value) {
            if let Ok(n) = value.parse::<i64>() {
                meta.insert(key, MetadataValue::Integer(n));
            } else {
                meta.insert(key, MetadataValue::String(strip_quotes(&value)));
            }
        } else {
            meta.insert(key, MetadataValue::String(strip_quotes(&value)));
        }
    }

    meta
}

/// Check if a string matches the JS float regex: /^-?\d+\.\d+$/
fn is_float_literal(s: &str) -> bool {
    let s = s.strip_prefix('-').unwrap_or(s);
    if let Some((before, after)) = s.split_once('.') {
        !before.is_empty()
            && before.chars().all(|c| c.is_ascii_digit())
            && !after.is_empty()
            && after.chars().all(|c| c.is_ascii_digit())
    } else {
        false
    }
}

/// Check if a string matches the JS integer regex: /^-?\d+$/
fn is_integer_literal(s: &str) -> bool {
    let s = s.strip_prefix('-').unwrap_or(s);
    !s.is_empty() && s.chars().all(|c| c.is_ascii_digit())
}

/// Would `parse_metadata` coerce this raw value away from
/// `MetadataValue::String`? Exposed so the generator can decide whether
/// to YAML-quote a string value that would otherwise round-trip as
/// Integer / Float / Bool. Kept co-located with the coercion rules so
/// the two cannot drift.
pub(crate) fn would_coerce_from_string(s: &str) -> bool {
    s == "true" || s == "false" || is_integer_literal(s) || is_float_literal(s)
}

/// Strip inline comments: `value # comment` → `value`.
fn strip_inline_comment(s: &str) -> &str {
    // Find ` #` pattern (space followed by #)
    // But be careful not to strip inside quoted strings
    if let Some(idx) = s.find(" #") {
        s[..idx].trim_end()
    } else {
        s
    }
}

/// Strip surrounding quotes: `"value"` or `'value'` → `value`.
/// A lone quote character is not a quoted value — `len >= 2` keeps the
/// slice in bounds (a 1-char `"` satisfies both starts_with and ends_with).
fn strip_quotes(s: &str) -> String {
    if s.len() >= 2
        && ((s.starts_with('"') && s.ends_with('"')) || (s.starts_with('\'') && s.ends_with('\'')))
    {
        s[1..s.len() - 1].to_string()
    } else {
        s.to_string()
    }
}

// ---------------------------------------------------------------------------
// Code block masking
// ---------------------------------------------------------------------------

/// Mask every CommonMark code block by replacing its bytes with spaces
/// (preserves line count and byte offsets). Handles unclosed blocks
/// safely — they mask to end of text.
///
/// The definition lives in [`crate::markdown`] — one referee for every
/// content reader in the engine. Re-exported here because this module's
/// callers are the historical ones.
pub use crate::markdown::{mask_code_blocks, mask_code_blocks_and_spans};

// ---------------------------------------------------------------------------
// Merge-conflict detection
// ---------------------------------------------------------------------------

/// True when `text` — a whole entity file — carries a complete git
/// merge-conflict block: an ordered `<<<<<<< …` / `=======` /
/// `>>>>>>> …` triple at line starts.
///
/// The frontmatter is scanned **raw** and the body over
/// [`mask_code_blocks`] output. Both halves of that split are
/// load-bearing:
///
/// - Masking the body is why a code example documenting conflict
///   markers never trips the check. It is a legibility trade-off, not
///   a soundness one: a real conflict whose markers all fall inside
///   one code block goes undetected (the file then loads/degrades
///   exactly as it did before this check existed) — git writes markers
///   without regard for fences, so that shape is rare, while marker
///   examples in documentation entities are not.
/// - Frontmatter is **not** masked, because frontmatter is not
///   markdown. Handing it to a CommonMark parser invents block
///   structure that is not there: a YAML value that reads as a fence
///   opener (legal at 1–3 spaces) opens a code block that runs past
///   the `---` terminator to end of file and blanks the entire body,
///   markers and all — a conflicted file would then load with both
///   sides fused into one entity, which is precisely the outcome
///   `entity::loader`'s caller exists to prevent. Git also writes
///   conflict markers into frontmatter, so scanning it is not merely
///   safe, it is required.
pub fn has_merge_conflict_markers(text: &str) -> bool {
    // One view, not two scans: a conflict can straddle the `---`
    // terminator (git writes markers wherever the hunks fall), so the
    // raw frontmatter and the masked body are rejoined and scanned as
    // a single text. Masking preserves byte length, so the join is the
    // original file with only body code blocks blanked.
    let body = body_after_frontmatter(text);
    let frontmatter = &text[..text.len() - body.len()];
    let view = format!("{frontmatter}{}", mask_code_blocks(body));

    let mut seen_start = false;
    let mut seen_separator = false;
    for line in view.lines() {
        if line.starts_with("<<<<<<< ") {
            seen_start = true;
            seen_separator = false;
        } else if seen_start && line.trim_end() == "=======" {
            seen_separator = true;
        } else if seen_separator && line.starts_with(">>>>>>> ") {
            return true;
        }
    }
    false
}

// ---------------------------------------------------------------------------
// Section splitting
// ---------------------------------------------------------------------------

/// Tracks one schema-declared section key seen more than once on parse.
/// `key` is the slugified storage key (e.g. `realization`); `heading` is
/// the original literal text from the first occurrence (e.g. `Realization`).
/// Sections keyed by derived key; each value is the heading line
/// VERBATIM from the original body plus the section's content.
pub(crate) type SplitSections = IndexMap<String, (String, String)>;

/// `occurrences` counts every header line for that key — first plus
/// duplicates.
pub(crate) struct DuplicateSection {
    pub key: String,
    pub heading: String,
    pub occurrences: usize,
}

/// Split body into named sections. Returns `Map<lowercase_key,
/// (heading_line, content)>` — the heading line VERBATIM from the
/// original body, because the catch-all re-emits it and a heading
/// rebuilt from the derived key changes what the CommonMark referee
/// sees (a CR inside a heading is a line ending of its own, so its
/// tail can be a live fence opener; the derived key lost the CRs, the
/// re-parse un-masked the section's content, and a promoted empty
/// heading then vanished — fuzz finding, corpus member
/// `crash-9fd95247…`) — plus a list of duplicate-heading occurrences.
/// Duplicate headings keep the first occurrence's body; subsequent
/// occurrences are dropped from the storage value entirely (no
/// embedded `## Heading` separator). The caller decides whether each
/// duplicate becomes a `WarningHint` (schema-declared keys only —
/// catch-all repetition stays silent). The third element is every
/// literal heading text in document order (duplicates included) — the
/// raw material for the health check that distinguishes "section
/// absent" from "content under a non-deriving heading".
pub(crate) fn split_sections(
    body: &str,
    masked_body: &str,
) -> (SplitSections, Vec<DuplicateSection>, Vec<String>) {
    // IndexMap, not HashMap: the catch-all builder re-emits non-schema
    // sections in this map's iteration order, so the order must be the
    // document's — hash-random order made canonical bytes unstable
    // across parses whenever more than one non-schema section coexisted
    // (reachable on the tolerant local-read path, which refuses nothing).
    let mut sections = IndexMap::new();
    let mut duplicates: HashMap<String, DuplicateSection> = HashMap::new();
    let mut raw_headings = Vec::new();
    static SECTION_RE: OnceLock<Regex> = OnceLock::new();
    let section_re = SECTION_RE.get_or_init(|| Regex::new(r"(?m)^## (.+)$").unwrap());

    let matches: Vec<_> = section_re.find_iter(masked_body).collect();

    for (i, m) in matches.iter().enumerate() {
        // Extract heading name from original body (not masked)
        let heading_line = &body[m.start()..m.end()];
        let name = heading_line
            .strip_prefix("## ")
            .unwrap_or(heading_line)
            .trim();

        let content_start = m.end();
        let content_end = if i + 1 < matches.len() {
            matches[i + 1].start()
        } else {
            body.len()
        };
        // Leading trim drops blank lines wholesale but keeps the first
        // visible line's indentation: a full trim promoted an indented
        // heading-lookalike (` ## Specifies`) to column 0 inside stored
        // content, where the catch-all re-emit made the NEXT parse read
        // it as a real section heading — structure from content, and a
        // broken parse-generate fixpoint (fuzz finding, long tier,
        // 2026-08-24, corpus member `crash-de0c69e0…`). Trailing trim
        // stays full: it can never move a line to column 0. The
        // runtime validator's embedded-heading guard keeps its own full
        // trim, so the mutation path refuses exactly what it refused.
        let raw = &body[content_start..content_end];
        let visible_start = raw
            .split_inclusive('\n')
            .take_while(|line| line.trim().is_empty())
            .map(str::len)
            .sum::<usize>();
        let content = raw[visible_start..].trim_end().to_string();
        // Schema section keys are underscore-separated (e.g. `current_state`).
        // A heading like `## Current State` must derive to the same form so
        // schema-declared sections land in `result_sections` under the right
        // key instead of falling through to catch-all — which would break
        // canonical byte-stability for any multi-word section. The derivation
        // is shared with the schema loader's round-trip check — never inline
        // a second copy here.
        let key = memstead_schema::derive_section_key(name);
        raw_headings.push(name.to_string());

        match sections.entry(key.clone()) {
            indexmap::map::Entry::Vacant(slot) => {
                slot.insert((heading_line.to_string(), content));
                duplicates.insert(
                    key.clone(),
                    DuplicateSection {
                        key: key.clone(),
                        heading: name.to_string(),
                        occurrences: 1,
                    },
                );
            }
            indexmap::map::Entry::Occupied(_) => {
                // First-wins: drop this duplicate's body entirely. Bump the
                // occurrence count for the warning emitted by the caller.
                if let Some(d) = duplicates.get_mut(&key) {
                    d.occurrences += 1;
                }
            }
        }
    }

    let dup_list: Vec<DuplicateSection> = duplicates
        .into_values()
        .filter(|d| d.occurrences > 1)
        .collect();

    (sections, dup_list, raw_headings)
}

/// Extract the title from the first `# ` heading.
///
/// Scans the masked body so a `# ` line inside a code block can never
/// become the entity title, and reads the text back from the original —
/// masking preserves byte offsets and line count, so the two line
/// sequences correspond one-to-one.
fn extract_title(body: &str, masked_body: &str) -> Option<String> {
    for (line, masked) in body.lines().zip(masked_body.lines()) {
        if masked.starts_with("# ") {
            return Some(line[2..].trim().to_string());
        }
    }
    None
}

// ---------------------------------------------------------------------------
// Heading spans (H3–H6)
// ---------------------------------------------------------------------------

/// Extract H3–H6 heading spans from each section's content. Byte offsets are
/// into the (trimmed) section string stored in `result_sections`. Code blocks
/// are masked before scanning so `### foo` inside any code block is ignored.
///
/// End offsets use a level-aware closing rule: a span closes at the next
/// heading with the same or lower level (H3 closes on next H3 or H2 — but
/// H2 doesn't appear here since sections are already split), otherwise at
/// the end of the section. Level skips (H2 → H4 without H3) are tolerated:
/// the H4 span is recorded flat, and query-time path resolution uses offset
/// containment to reconstruct ancestry.
fn extract_heading_spans(sections: &IndexMap<String, String>) -> HashMap<String, Vec<HeadingSpan>> {
    // Compiled once per process; shape-constrained so it can't fail at runtime.
    static RE: OnceLock<Regex> = OnceLock::new();
    let re = RE.get_or_init(|| Regex::new(r"(?m)^(#{3,6})[ \t]+(.+)$").unwrap());
    let mut out: HashMap<String, Vec<HeadingSpan>> = HashMap::new();

    for (key, content) in sections {
        if content.is_empty() {
            continue;
        }
        let masked = mask_code_blocks(content);

        // Collect (start_offset, level, title) in document order.
        let raw: Vec<(usize, u8, String)> = re
            .captures_iter(&masked)
            .map(|cap| {
                let whole = cap.get(0).unwrap();
                let level = cap[1].len() as u8; // 3..=6
                // Read the title from the original (unmasked) content so the
                // captured text survives code-block masking's space-padding.
                let line_end = content[whole.start()..]
                    .find('\n')
                    .map(|i| whole.start() + i)
                    .unwrap_or(content.len());
                let hashes_end = whole.start() + level as usize;
                let title = content[hashes_end..line_end].trim().to_string();
                (whole.start(), level, title)
            })
            .collect();

        if raw.is_empty() {
            continue;
        }

        let mut spans: Vec<HeadingSpan> = Vec::with_capacity(raw.len());
        for (i, &(start, level, ref title)) in raw.iter().enumerate() {
            // Scan forward for the next heading with level <= this one.
            let end = raw[i + 1..]
                .iter()
                .find(|(_, l, _)| *l <= level)
                .map(|(s, _, _)| *s)
                .unwrap_or(content.len());
            spans.push(HeadingSpan {
                level,
                title: title.clone(),
                start_offset: start,
                end_offset: end,
            });
        }
        out.insert(key.clone(), spans);
    }

    out
}

// ---------------------------------------------------------------------------
// Catch-all section
// ---------------------------------------------------------------------------

/// Build catch-all section content from its own section + non-schema sections.
fn build_catch_all(sections: &SplitSections, schema: &TypeDefinition) -> String {
    let catch_all = match schema.catch_all_section() {
        Some(s) => s,
        None => return String::new(),
    };

    let known_sections: HashSet<&str> = schema
        .sections
        .iter()
        .map(|s| s.key.as_str())
        .chain(std::iter::once("relationships"))
        .collect();

    let mut parts = Vec::new();

    // First, add the explicit catch-all section content
    if let Some((_, content)) = sections.get(catch_all.key.as_str())
        && !content.is_empty()
    {
        parts.push(content.clone());
    }

    // Then add all non-schema sections, each re-emitted under its
    // ORIGINAL heading line, byte-verbatim — never a heading rebuilt
    // from the derived key: the rebuilt form changed what the referee
    // sees (a CR inside a heading is a CommonMark line ending of its
    // own, so its tail can be a live fence opener the derived key
    // lost), and the re-parse then promoted masked content to
    // structure (fuzz finding, corpus member `crash-9fd95247…`).
    // Document order — `sections` is an IndexMap for exactly this
    // loop: with more than one non-schema section (reachable on the
    // tolerant local-read path, which refuses nothing) a hash-random
    // order made the reconstructed catch-all differ from parse to parse.
    for (key, (heading_line, content)) in sections {
        if !known_sections.contains(key.as_str()) && !content.is_empty() {
            parts.push(format!("{heading_line}\n{content}"));
        }
    }

    // Incremental context close: every close decision is judged over
    // the RUNNING string after each append — never over a piece in
    // isolation. Isolation misjudges in both directions (lazy
    // continuation and CR line endings make the same bytes a fence in
    // one context and prose in another): an isolation close injected a
    // spurious closer that the generator's part-level close then paired
    // into an empty fence block, growing the document every round
    // (corpus candidate `crash-619fe90c`), while skipping the close
    // entirely let a piece's dangling fence swallow the next piece's
    // heading (corpus member `crash-07c152bb`). Closing in context
    // after each piece keeps both: a dangling fence closes before the
    // next piece, and no closer is ever added for a construct the
    // document context does not read as a fence. The oracle verifies
    // its closer against the mask, so the appended line is a real
    // closer wherever it lands. The context is not only fences: an
    // HTML block of the kinds no blank line ends (`<!X`, `<!--`, `<?`,
    // `<![CDATA[`, a `<script>`-family tag) hides every fence the
    // referee would otherwise read, so a piece that ends inside one
    // changes what the NEXT piece's fences mean — a `## ` line that a
    // fence masked in situ surfaces as a heading after the merge, and
    // as an empty non-schema section it is dropped a round later
    // (fuzz finding, long tier, 0.17.0 release readiness run, corpus
    // member `crash-1233c134…`). The same oracle closes both.
    let mut joined = String::new();
    for piece in parts {
        if joined.is_empty() {
            joined = piece;
        } else {
            joined.push_str("\n\n");
            joined.push_str(&piece);
        }
        if let Some(closer) = crate::markdown::closing_context_if_unterminated(&joined) {
            joined.push('\n');
            joined.push_str(&closer);
        }
    }
    joined
}

// ---------------------------------------------------------------------------
// Relationships
// ---------------------------------------------------------------------------

/// Parse typed relationships from the Relationships section.
///
/// Recognises two row shapes:
/// - simple: `- **TYPE**: [[target]]` → `description: None`
/// - em-dash: `- **TYPE**: [[target]] — text` → `description: Some(text)`
///
/// Returns the relations plus parse-time warnings flagging
/// AMBIGUOUS-delimiter rows (`-- text`, `- text`, en-dash, minus). On
/// AMBIGUOUS rows the description is dropped — the renderer will
/// normalise the row to the simple form on next write.
///
/// Rows inside a code block are not relationships. The scan runs over
/// the masked section body and reads every captured span from the
/// original, so a fenced or indented example of the row syntax — the
/// obvious thing to write in an entity documenting that syntax — no
/// longer becomes a live edge and an auto-stub. Without the mask this
/// path synthesised edges from links the strict validator cannot see
/// (`validator::strict::check_wiki_links` masks), which is exactly the
/// asymmetry the one-definition rule exists to prevent.
pub(crate) fn parse_relationships_with_warnings(
    text: &str,
    mem: &str,
    entity_id: Option<&EntityId>,
) -> (Vec<Relationship>, Vec<crate::ops::WarningHint>) {
    // Anchor on the canonical row prefix `- **TYPE**: [[<target>]]` and
    // capture everything that follows on the same line so the trailing
    // segment can be classified (simple, em-dash, or AMBIGUOUS).
    //
    // The target must not cross a line: a ROW is a line. A capture
    // spanning a newline only ever came from degenerate drift, and it
    // cannot round-trip — the generated multi-line token re-enters the
    // mask with different structure (a following `-` + tab line reads
    // as list-item indented code and swallows the closing `]]`), so
    // the row silently vanished one round later (fuzz finding, corpus
    // member `crash-93f0a4bd…`). Ids containing newlines can never
    // exist as entity files, so such pseudo-rows are consistently not
    // relationships in ANY round.
    static RE: OnceLock<Regex> = OnceLock::new();
    let re = RE.get_or_init(|| {
        Regex::new(r"(?m)^\s*-\s*\*\*(\w+)\*\*:\s*\[\[([^\]\n]+)\]\](?P<tail>[^\n]*)").unwrap()
    });
    let mut relationships = Vec::new();
    let mut warnings = Vec::new();
    // Blocks AND inline spans — the same mask every link scanner uses.
    // A legitimate row's target can never sit inside a code span, so
    // masking spans costs nothing and closes the seam: with a
    // blocks-only mask a row inside a multi-line inline span stayed
    // invisible to the validator and to every extractor while still
    // building an edge and a stub. Masking preserves byte offsets, so a
    // match found in the masked copy indexes the original exactly.
    let masked = mask_code_blocks_and_spans(text);
    for cap in re.captures_iter(&masked) {
        let rel_type = text[cap.get(1).unwrap().range()].to_uppercase();
        // Read-time parsing of the ## Relationships table tolerates
        // pre-strict on-disk drift so legacy rows whose target fails
        // the wiki-link grammar continue to round-trip. The mutation
        // pipeline (`memstead_relate`, declare_relations) gates strictly
        // via `validate_relation_target_grammar`.
        let target = wiki_link_to_id_lenient(&text[cap.get(2).unwrap().range()], mem);
        // A raw target that decodes to an EMPTY path (`[[specs--]]`
        // after the self-prefix strip, `[[../]]` after decoration
        // stripping) is not a relationship: the generator would render
        // it as `[[]]`, which the row pattern cannot re-capture, so the
        // row silently vanished one round later (fuzz finding, corpus
        // member `crash-0c7207a1…`). Skipping it here mirrors how rows
        // that never match the pattern behave; both strict gates refuse
        // such targets outright.
        if target.path().is_empty() {
            continue;
        }
        let tail = cap.name("tail").map(|m| &text[m.range()]).unwrap_or("");
        let description = match classify_description_tail(tail) {
            DescriptionTail::None => None,
            DescriptionTail::EmDash(text) => Some(text),
            DescriptionTail::Ambiguous(literal) => {
                if let Some(id) = entity_id {
                    warnings.push(crate::ops::WarningHint::AmbiguousDescriptionDelimiter {
                        from: id.clone(),
                        rel_type: rel_type.clone(),
                        target: target.clone(),
                        trailing: literal,
                    });
                }
                None
            }
        };
        relationships.push(Relationship {
            rel_type,
            target,
            description,
        });
    }
    (relationships, warnings)
}

/// Classification of the per-line tail that follows `]]` on a
/// `## Relationships` row.
enum DescriptionTail {
    /// Tail is empty or whitespace-only.
    None,
    /// Tail begins with the canonical em-dash delimiter; carries the
    /// captured description text (trimmed of trailing whitespace).
    EmDash(String),
    /// Tail starts with a non-canonical dash-like delimiter (`-`,
    /// `--`, U+2013 en-dash, U+2212 minus). Carries the literal
    /// trailing content so the warning surfaces what was dropped.
    Ambiguous(String),
}

/// Inspect the post-`]]` tail of a `## Relationships` row and decide
/// what shape it takes. The em-dash delimiter is the exact three-byte
/// UTF-8 sequence of U+2014 framed by single ASCII spaces; everything
/// else falls into [`DescriptionTail::None`] or
/// [`DescriptionTail::Ambiguous`].
fn classify_description_tail(tail: &str) -> DescriptionTail {
    let trimmed_end = tail.trim_end();
    if trimmed_end.is_empty() {
        return DescriptionTail::None;
    }
    // Canonical: literal space + U+2014 + literal space + content.
    if let Some(rest) = trimmed_end.strip_prefix(" \u{2014} ") {
        if rest.is_empty() {
            return DescriptionTail::None;
        }
        return DescriptionTail::EmDash(rest.to_string());
    }
    // U+2014 directly after `]]` (no leading space) is also ambiguous
    // — the canonical form requires the framing space. Likewise an
    // em-dash with no trailing content (` — `) collapses to None.
    if let Some(rest) = trimmed_end.strip_prefix(" \u{2014}") {
        // ` —` (no trailing space, but content followed) lands here.
        return DescriptionTail::Ambiguous(format!(" \u{2014}{rest}"));
    }
    // Dash-likes: ASCII `--`, ASCII `-`, en-dash U+2013, minus U+2212.
    let starters = [" --", " -", " \u{2013}", " \u{2212}"];
    if starters
        .iter()
        .any(|prefix| trimmed_end.starts_with(prefix))
    {
        return DescriptionTail::Ambiguous(trimmed_end.to_string());
    }
    // Anything else after `]]` (e.g. inline comment, stray text) —
    // classify as ambiguous so the operator sees that content was
    // dropped rather than silently swallowed.
    DescriptionTail::Ambiguous(trimmed_end.to_string())
}

// ---------------------------------------------------------------------------
// Wiki-links
// ---------------------------------------------------------------------------

/// The `[[target]]` / `[[target|label]]` wiki-link pattern, compiled once.
///
/// The inner group is `*`, not `+`, so an empty target `[[]]` is *seen*
/// by every path — the strict validator refuses it with a typed
/// `InvalidWikiLink`, and this module's strict extractor routes it to
/// the same refusal. A pattern that cannot see `[[]]` is how one path
/// came to silently ignore what another path refused.
fn wiki_link_re() -> &'static Regex {
    static RE: OnceLock<Regex> = OnceLock::new();
    RE.get_or_init(|| Regex::new(r"\[\[([^\]]*)\]\]").unwrap())
}

/// Extract unique mem-prefixed entity IDs from inline wiki-links,
/// strictly validating each target against the slug-form grammar.
/// Strips code blocks and inline code spans before scanning, by the
/// one CommonMark definition ([`crate::markdown`]).
///
/// Returns the deduped valid ids on success, or every refusal in the
/// scan window on failure (errors are collected, not fail-fast — the
/// agent sees every malformed link in a single round-trip).
///
/// Mutation-pipeline callers (`synthesise_alias_relations`, etc.) use
/// this strict variant and map [`WikiLinkError`] to the typed engine
/// envelope with section context. Read-side scanners that must
/// tolerate pre-strict on-disk drift use [`extract_inline_links_lenient`].
pub(crate) fn extract_inline_links(
    text: &str,
    mem: &str,
) -> Result<Vec<EntityId>, Vec<WikiLinkError>> {
    let stripped = mask_code_blocks_and_spans(text);

    let link_re = wiki_link_re();
    let mut seen = HashSet::new();
    let mut links = Vec::new();
    let mut errors = Vec::new();

    for cap in link_re.captures_iter(&stripped) {
        match wiki_link_to_id(&cap[1], mem) {
            Ok(id) => {
                if errors.is_empty() && seen.insert(id.0.clone()) {
                    links.push(id);
                }
            }
            Err(e) => errors.push(e),
        }
    }

    if errors.is_empty() {
        Ok(links)
    } else {
        Err(errors)
    }
}

/// Permissive sibling of [`extract_inline_links`] for read-side
/// scanners. Decodes every `[[...]]` token via [`wiki_link_to_id_lenient`]
/// so on-disk drift (legacy entities, archive-imports from pre-strict
/// engines, partial-mutation rollbacks) keeps flowing through dangling-
/// link reporters and graph inspectors. Mutation paths MUST NOT use this
/// helper — see [`extract_inline_links`] for the strict variant.
pub fn extract_inline_links_lenient(text: &str, mem: &str) -> Vec<EntityId> {
    let stripped = mask_code_blocks_and_spans(text);

    let link_re = wiki_link_re();
    let mut seen = HashSet::new();
    let mut links = Vec::new();

    for cap in link_re.captures_iter(&stripped) {
        // An empty target decodes to no id. The read side tolerates
        // drift by ignoring what it cannot decode; the strict side
        // refuses it (`extract_inline_links`). Both *see* it — that is
        // the part that must not diverge.
        if cap[1].is_empty() {
            continue;
        }
        let id = wiki_link_to_id_lenient(&cap[1], mem);
        if seen.insert(id.0.clone()) {
            links.push(id);
        }
    }

    links
}

// ---------------------------------------------------------------------------
// Content hash
// ---------------------------------------------------------------------------

/// Compute SHA-256 hash of content, truncated to 16 hex characters.
pub fn compute_hash(content: &str) -> String {
    let mut hasher = Sha256::new();
    hasher.update(content.as_bytes());
    let result = hasher.finalize();
    crate::hex_lower(&result)[..16].to_string()
}

// ---------------------------------------------------------------------------
// Errors
// ---------------------------------------------------------------------------

#[derive(Debug, thiserror::Error)]
pub enum ParseError {
    #[error("missing frontmatter")]
    MissingFrontmatter,
    #[error("invalid frontmatter: {0}")]
    InvalidFrontmatter(String),
    #[error("missing title")]
    MissingTitle,
    #[error("io error: {0}")]
    Io(#[from] std::io::Error),
}

#[cfg(test)]
mod tests {
    use super::*;
    use memstead_schema::{builtin_names, type_by_name};
    use std::sync::Arc;

    fn spec_schema() -> Arc<TypeDefinition> {
        type_by_name(builtin_names::SPEC).unwrap()
    }

    fn memo_schema() -> Arc<TypeDefinition> {
        type_by_name(builtin_names::MEMO).unwrap()
    }

    #[test]
    fn parse_metadata_types() {
        let meta = parse_metadata("key: value\nnum: 42\nfloat: 0.85\nbool: true\nfalsy: false");
        assert_eq!(meta["key"], MetadataValue::String("value".to_string()));
        assert_eq!(meta["num"], MetadataValue::Integer(42));
        assert_eq!(meta["float"], MetadataValue::Float(0.85));
        assert_eq!(meta["bool"], MetadataValue::Bool(true));
        assert_eq!(meta["falsy"], MetadataValue::Bool(false));
    }

    #[test]
    fn parse_metadata_strips_comments() {
        let meta = parse_metadata("key: value # this is a comment");
        assert_eq!(meta["key"], MetadataValue::String("value".to_string()));
    }

    #[test]
    fn parse_metadata_strips_quotes() {
        let meta = parse_metadata("key: \"quoted value\"\nkey2: 'single'");
        assert_eq!(
            meta["key"],
            MetadataValue::String("quoted value".to_string())
        );
        assert_eq!(meta["key2"], MetadataValue::String("single".to_string()));
    }

    #[test]
    fn parse_metadata_survives_malformed_values() {
        // A lone quote character satisfies both starts_with and ends_with —
        // the old unguarded slice `s[1..s.len()-1]` panicked on it.
        let meta = parse_metadata(
            "key: \"\nkey2: '\nkey3: \"\"\nkey4: ''\nkey5: \"unterminated\nkey6: mixed'\"",
        );
        assert_eq!(meta["key"], MetadataValue::String("\"".to_string()));
        assert_eq!(meta["key2"], MetadataValue::String("'".to_string()));
        assert_eq!(meta["key3"], MetadataValue::String(String::new()));
        assert_eq!(meta["key4"], MetadataValue::String(String::new()));
        assert_eq!(
            meta["key5"],
            MetadataValue::String("\"unterminated".to_string())
        );
        assert_eq!(meta["key6"], MetadataValue::String("mixed'\"".to_string()));

        // More frontmatter shapes that must parse to a value, never panic:
        // colon-only lines, multi-byte values, keyless colons, huge digits.
        let meta =
            parse_metadata(":\n: value\nkey7: ✓\"\nkey8: 99999999999999999999999999\nkey9: -");
        assert_eq!(meta["key7"], MetadataValue::String("✓\"".to_string()));
        assert_eq!(
            meta["key8"],
            MetadataValue::String("99999999999999999999999999".to_string())
        );
        assert_eq!(meta["key9"], MetadataValue::String("-".to_string()));
    }

    #[test]
    fn parse_metadata_skips_comments_and_empty() {
        let meta = parse_metadata("# comment\n\nkey: val\n---");
        assert_eq!(meta.len(), 1);
        assert_eq!(meta["key"], MetadataValue::String("val".to_string()));
    }

    #[test]
    fn peek_type_finds_value() {
        let content = "---\ntype: memo\ntitle: Test\n---\n# Body\n";
        assert_eq!(
            peek_type_from_frontmatter(content),
            Some("memo".to_string())
        );
    }

    #[test]
    fn peek_type_returns_none_when_missing() {
        let content = "---\ntitle: Test\n---\n# Body\n";
        assert_eq!(peek_type_from_frontmatter(content), None);
    }

    #[test]
    fn peek_type_returns_none_without_frontmatter() {
        let content = "# Just a heading\n\nBody with type: concept inside text.\n";
        assert_eq!(peek_type_from_frontmatter(content), None);
    }

    #[test]
    fn peek_type_handles_windows_line_endings() {
        let content = "---\r\ntype: principle\r\n---\r\n# Body\r\n";
        assert_eq!(
            peek_type_from_frontmatter(content),
            Some("principle".to_string())
        );
    }

    #[test]
    fn peek_type_strips_quotes_and_comments() {
        let quoted = "---\ntype: \"concept\"\n---\n";
        assert_eq!(
            peek_type_from_frontmatter(quoted),
            Some("concept".to_string())
        );
        let commented = "---\ntype: memo # kind of\n---\n";
        assert_eq!(
            peek_type_from_frontmatter(commented),
            Some("memo".to_string())
        );
    }

    #[test]
    fn peek_type_empty_value_returns_none() {
        let content = "---\ntype:\n---\n";
        assert_eq!(peek_type_from_frontmatter(content), None);
    }

    #[test]
    fn peek_type_ignores_legacy_schema_key() {
        // After the hard break, a bare `schema:` in frontmatter is not
        // recognized as the type key — it's just arbitrary metadata.
        let content = concat!("---\n", "schema", ": memo\n---\n");
        assert_eq!(peek_type_from_frontmatter(content), None);
    }

    #[test]
    fn mask_code_blocks_basic() {
        let input = "before\n```\ncode [[link]]\n```\nafter";
        let masked = mask_code_blocks(input);
        assert!(!masked.contains("[[link]]"));
        assert!(masked.contains("before"));
        assert!(masked.contains("after"));
    }

    #[test]
    fn mask_code_blocks_preserves_line_count() {
        let input = "line1\n```\ncode\nmore code\n```\nline6";
        let masked = mask_code_blocks(input);
        assert_eq!(input.lines().count(), masked.lines().count());
    }

    #[test]
    fn mask_code_blocks_unclosed() {
        let input = "before\n```\ncode\nmore code";
        let masked = mask_code_blocks(input);
        assert!(masked.contains("before"));
        assert!(!masked.contains("code"));
    }

    #[test]
    fn parse_relationships_basic() {
        let text = "- **USES**: [[target-entity]]\n- **PART_OF**: [[parent]]";
        let rels = parse_relationships_with_warnings(text, "specs", None).0;
        assert_eq!(rels.len(), 2);
        assert_eq!(rels[0].rel_type, "USES");
        assert_eq!(rels[0].target.0, "specs--target-entity");
        assert_eq!(rels[1].rel_type, "PART_OF");
        assert_eq!(rels[1].target.0, "specs--parent");
        // Simple form parses without a description.
        assert!(rels[0].description.is_none());
        assert!(rels[1].description.is_none());
    }

    #[test]
    fn parse_relationships_canonical_em_dash_captures_description() {
        let text = "- **OTHER**: [[a]] \u{2014} replaced by checkout-flow";
        let (rels, warnings) = parse_relationships_with_warnings(text, "specs", None);
        assert_eq!(rels.len(), 1);
        assert_eq!(
            rels[0].description.as_deref(),
            Some("replaced by checkout-flow")
        );
        assert!(warnings.is_empty(), "canonical em-dash does not warn");
    }

    #[test]
    fn parse_relationships_em_dash_inside_description_body() {
        let text = "- **OTHER**: [[a]] \u{2014} note with — inside body";
        let (rels, warnings) = parse_relationships_with_warnings(text, "specs", None);
        assert_eq!(rels.len(), 1);
        assert_eq!(
            rels[0].description.as_deref(),
            Some("note with — inside body"),
            "the parser captures up to end-of-line; em-dashes inside the body survive"
        );
        assert!(warnings.is_empty());
    }

    #[test]
    fn parse_relationships_ambiguous_double_hyphen_warns_and_drops_content() {
        let text = "- **USES**: [[a]] -- legacy delimiter";
        let entity_id = EntityId::new("specs", "src");
        let (rels, warnings) = parse_relationships_with_warnings(text, "specs", Some(&entity_id));
        assert_eq!(rels.len(), 1);
        assert!(rels[0].description.is_none(), "trailing content is dropped");
        assert_eq!(warnings.len(), 1);
        assert!(matches!(
            warnings[0],
            crate::ops::WarningHint::AmbiguousDescriptionDelimiter { .. }
        ));
    }

    #[test]
    fn parse_relationships_ambiguous_single_hyphen_warns_and_drops_content() {
        let text = "- **USES**: [[a]] - single hyphen";
        let entity_id = EntityId::new("specs", "src");
        let (rels, warnings) = parse_relationships_with_warnings(text, "specs", Some(&entity_id));
        assert_eq!(rels.len(), 1);
        assert!(rels[0].description.is_none());
        assert_eq!(warnings.len(), 1);
        assert_eq!(warnings[0].code(), "AMBIGUOUS_DESCRIPTION_DELIMITER");
    }

    #[test]
    fn parse_relationships_hyphenated_slug_target_parses_unambiguously() {
        let text = "- **USES**: [[some-slug-with-hyphens]] \u{2014} ok";
        let (rels, warnings) = parse_relationships_with_warnings(text, "specs", None);
        assert_eq!(rels.len(), 1);
        assert_eq!(rels[0].target.path(), "some-slug-with-hyphens");
        assert_eq!(rels[0].description.as_deref(), Some("ok"));
        assert!(warnings.is_empty());
    }

    #[test]
    fn parse_full_entity() {
        let md = "\
---
type: spec
created_date: 2026-01-15
last_modified: 2026-04-12
level: M0
tags: backend, api
---
# Test Entity

## Identity

This is a test entity.

## Purpose

Testing the parser.

## Relationships

- **USES**: [[other-entity]]

## Specifies

Some specification content with [[inline-link]].
";
        let result = parse_markdown(md, "test-entity.md", &spec_schema(), "specs").unwrap();
        let entity = &result.entity;
        assert_eq!(entity.id.0, "specs--test-entity");
        assert_eq!(entity.title, "Test Entity");
        assert_eq!(entity.mem, "specs");
        assert_eq!(
            entity.metadata["type"],
            MetadataValue::String("spec".to_string())
        );
        assert_eq!(
            entity.metadata["level"],
            MetadataValue::String("M0".to_string())
        );
        assert_eq!(
            entity.metadata["tags"],
            MetadataValue::String("backend, api".to_string())
        );
        assert_eq!(entity.sections["identity"], "This is a test entity.");
        assert_eq!(entity.sections["purpose"], "Testing the parser.");
        assert_eq!(entity.relationships.len(), 1);
        assert_eq!(entity.relationships[0].rel_type, "USES");
        assert_eq!(entity.relationships[0].target.0, "specs--other-entity");
        assert_eq!(result.inline_links.len(), 1);
        assert_eq!(result.inline_links[0].0, "specs--inline-link");
    }

    #[test]
    fn parse_full_entity_memo_schema() {
        let md = "\
---
type: memo
created_date: 2026-01-15
last_modified: 2026-04-12
status: active
tags: decision, architecture
---
# Use Sled For Storage

## Claim

Sled is the right embedded store for this workload.

## Context

We evaluated sled, rocksdb, and sqlite for the in-process graph cache.

## Substance

Sled wins on pure-Rust dependency footprint.
";
        let result = parse_markdown(md, "use-sled.md", &memo_schema(), "memos").unwrap();
        let entity = &result.entity;
        assert_eq!(entity.id.0, "memos--use-sled");
        assert_eq!(entity.title, "Use Sled For Storage");
        assert_eq!(entity.mem, "memos");
        assert_eq!(
            entity.metadata["type"],
            MetadataValue::String("memo".to_string())
        );
        assert_eq!(
            entity.metadata["status"],
            MetadataValue::String("active".to_string())
        );
        assert_eq!(
            entity.sections["claim"],
            "Sled is the right embedded store for this workload."
        );
        assert_eq!(
            entity.sections["context"],
            "We evaluated sled, rocksdb, and sqlite for the in-process graph cache."
        );
        assert_eq!(
            entity.sections["substance"],
            "Sled wins on pure-Rust dependency footprint."
        );
        assert!(!entity.sections.contains_key("identity"));
        assert!(!entity.sections.contains_key("purpose"));
    }

    #[test]
    fn parse_entity_without_frontmatter() {
        let md = "# No Frontmatter\n\n## Identity\n\nJust a title and section.";
        let result = parse_markdown(md, "no-fm.md", &spec_schema(), "specs").unwrap();
        assert_eq!(result.entity.title, "No Frontmatter");
        // Only the auto-injected type field should be present
        assert_eq!(result.entity.metadata.len(), 1);
        assert_eq!(
            result.entity.metadata.get("type"),
            Some(&MetadataValue::String("spec".to_string()))
        );
    }

    #[test]
    fn parse_entity_code_blocks_not_detected() {
        let md = "\
---
type: spec
---
# Code Test

## Identity

Test entity.

## Specifies

```
## Not A Section
- **USES**: [[not-a-link]]
```

Real content after code block.
";
        let result = parse_markdown(md, "code-test.md", &spec_schema(), "specs").unwrap();
        // The ## inside code block should NOT be parsed as a section
        assert!(!result.entity.sections.contains_key("not a section"));
        // The wiki-link inside code block should NOT be extracted
        assert!(result.inline_links.is_empty());
    }

    // Fixture pinned by the adversarial harness (seed 0x5eedf001, case 224):
    // a BOM'd file parsed tolerantly as all-body, losing its entire
    // frontmatter, while the strict validator and the archive path stripped
    // the mark and saw it. That divergence is why the mark is now stripped in
    // `split_frontmatter_core` and nowhere else: one implementation cannot
    // disagree with itself about where a document begins.
    #[test]
    fn bom_prefixed_frontmatter_is_recognized() {
        let md = "\u{feff}---\ntype: spec\n---\n# Bom Entity\n\n## Identity\n\nBody.\n";
        assert_eq!(peek_type_from_frontmatter(md), Some("spec".to_string()));
        assert_eq!(
            body_after_frontmatter(md),
            "# Bom Entity\n\n## Identity\n\nBody.\n"
        );
        let (meta, body) = split_frontmatter(md).unwrap();
        assert_eq!(meta, "type: spec");
        assert_eq!(body, "# Bom Entity\n\n## Identity\n\nBody.\n");
        let result = parse_markdown(md, "bom.md", &spec_schema(), "specs").unwrap();
        assert_eq!(
            result.entity.metadata["type"],
            MetadataValue::String("spec".to_string())
        );
        assert_eq!(result.entity.sections["identity"], "Body.");
    }

    // Fixture pinned by the adversarial harness (seed 0x5eedf001, case 46):
    // a section whose content ends inside an open code fence absorbed every
    // section the generator wrote after it on the next parse — content
    // shifted between sections and the document GREW on every
    // parse→generate round. The generator now terminates the open fence;
    // the first round normalises, then parse→generate is a fixpoint.
    #[test]
    fn open_fence_in_section_content_does_not_swallow_following_sections() {
        let md = "\
---
type: spec
---
# Code Test

## Identity

Base.

## Specifies

```
truncated code with no closer";
        let schema = spec_schema();
        let e1 = parse_markdown(md, "open-fence.md", &schema, "specs").unwrap();
        let m1 = crate::entity::generator::generate_markdown(&e1.entity, &schema);
        let e2 = parse_markdown(&m1, "open-fence.md", &schema, "specs").unwrap();
        assert_eq!(
            e2.entity.sections["identity"], "Base.",
            "sections before the open fence survive"
        );
        assert!(
            !e2.entity.sections["specifies"].contains("## Constraints"),
            "the generated sections after the fence are not absorbed into it"
        );
        let m2 = crate::entity::generator::generate_markdown(&e2.entity, &schema);
        assert_eq!(
            m1, m2,
            "parse→generate is a fixpoint after one normalising round"
        );
    }

    // Fixture pinned by the adversarial harness (seed 0x5eedf001, case 26):
    // a document carrying MULTIPLE non-schema sections — reachable on the
    // tolerant local-read path, which refuses nothing — reconstructed its
    // catch-all in HashMap iteration order, so canonical bytes differed
    // from parse to parse of the same input. The catch-all must re-emit
    // non-schema sections in document order, and parse→generate must be
    // idempotent for such input.
    #[test]
    fn catch_all_reconstruction_is_document_ordered_and_idempotent() {
        let md = "\
---
type: spec
---
# Multi Unknown

## Identity

Base.

## Claim

First unknown.

## Context

Second unknown.

## Substance

Third unknown.
";
        let schema = spec_schema();
        let e1 = parse_markdown(md, "multi-unknown.md", &schema, "specs").unwrap();
        assert_eq!(
            e1.entity.sections["specifies"],
            "## Claim\nFirst unknown.\n\n## Context\nSecond unknown.\n\n## Substance\nThird unknown.",
            "non-schema sections land in the catch-all in document order"
        );
        let m1 = crate::entity::generator::generate_markdown(&e1.entity, &schema);
        let e2 = parse_markdown(&m1, "multi-unknown.md", &schema, "specs").unwrap();
        let m2 = crate::entity::generator::generate_markdown(&e2.entity, &schema);
        assert_eq!(
            m1, m2,
            "parse→generate is idempotent over multi-unknown-section input"
        );
    }

    // Fixture pinned by the coverage-guided long tier (local run,
    // 2026-08-24; corpus member `crash-fd71330e…`): parse_markdown
    // re-trimmed every section value after split_sections had already
    // normalised it, silently promoting a whitespace-prefixed first
    // line (vertical tab + backticks) to column 0 — where the
    // CommonMark referee saw a fence opener the stored form did not
    // have, so the section structure shifted between rounds. The
    // splitter's trim is the only content trim.
    #[test]
    fn first_line_whitespace_prefix_survives_storage_and_round_trips() {
        let schema = spec_schema();
        let md = "---\ntype: spec\n---\n# T\n\n## Identity\n\u{b}```\nx\n\n## Purpose\np\n";
        let e1 = parse_markdown(md, "vt.md", &schema, "specs").unwrap();
        assert_eq!(
            e1.entity.sections["identity"], "\u{b}```\nx",
            "the first visible line keeps its whitespace prefix byte-exactly"
        );
        let m1 = crate::entity::generator::generate_markdown(&e1.entity, &schema);
        let e2 = parse_markdown(&m1, "vt.md", &schema, "specs").unwrap();
        let m2 = crate::entity::generator::generate_markdown(&e2.entity, &schema);
        assert_eq!(m1, m2, "parse→generate is a fixpoint");
    }

    // Fixture pinned by the coverage-guided long tier (0.17.0 release
    // readiness run, 2026-09-02; corpus member `crash-1233c134…`): a
    // non-schema section whose content ends inside an HTML block of a
    // kind no blank line ends (`<!X`, type 4) was merged in front of a
    // later piece. In situ a `>` line in the catch-all's own content had
    // closed the block, so the later piece's tilde fence opened and
    // masked a `## ` line into content; merged, the block stayed open,
    // the fence became prose, the masked line surfaced as an empty
    // non-schema heading, and the next round dropped it. The merge's
    // incremental context close now terminates HTML blocks like fences.
    #[test]
    fn merged_open_html_block_is_closed_so_later_fences_keep_masking() {
        let schema = spec_schema();
        let md = "\
---
type: spec
---
# T

## Claim
<!X

## Specifies
done >

## Later
~~~
## Hidden
";
        let e1 = parse_markdown(md, "html.md", &schema, "specs").unwrap();
        assert_eq!(
            e1.entity.sections["specifies"],
            "done >\n\n## Claim\n<!X\n>\n\n## Later\n~~~\n## Hidden\n~~~",
            "the open HTML block closes before the next piece, the dangling fence after it"
        );
        let m1 = crate::entity::generator::generate_markdown(&e1.entity, &schema);
        let e2 = parse_markdown(&m1, "html.md", &schema, "specs").unwrap();
        let m2 = crate::entity::generator::generate_markdown(&e2.entity, &schema);
        assert_eq!(m1, m2, "parse→generate is a fixpoint");
    }

    // Fixture pinned by the coverage-guided long tier (first dispatch,
    // 2026-08-24; corpus member `crash-de0c69e0…`): the splitter's full
    // content trim promoted an INDENTED heading-lookalike on the first
    // content line (` ## Specifies`) to column 0 inside stored content;
    // the catch-all re-emit then made the next parse read it as a real
    // duplicate section heading, whose first-wins rule dropped the
    // content — structure from content, and a broken fixpoint. Leading
    // blank lines still drop; the first visible line keeps its
    // indentation.
    #[test]
    fn indented_heading_lookalike_stays_content_and_round_trips() {
        let md = "\
---
type: spec
---
# Promoted Heading

## Identity

Base.

## Unknown Extra

 ## Specifies

Some content that must survive.
";
        let schema = spec_schema();
        let e1 = parse_markdown(md, "indent.md", &schema, "specs").unwrap();
        assert!(
            e1.entity.sections["specifies"].contains(" ## Specifies"),
            "the indented lookalike keeps its indentation inside the catch-all"
        );
        assert!(
            e1.entity.sections["specifies"].contains("Some content that must survive."),
            "content after the lookalike is preserved"
        );
        let m1 = crate::entity::generator::generate_markdown(&e1.entity, &schema);
        let e2 = parse_markdown(&m1, "indent.md", &schema, "specs").unwrap();
        let m2 = crate::entity::generator::generate_markdown(&e2.entity, &schema);
        assert_eq!(
            m1, m2,
            "parse→generate is a fixpoint after one normalising round"
        );
        assert!(
            e2.entity.sections["specifies"].contains("Some content that must survive."),
            "no content is lost across rounds"
        );
    }

    #[test]
    fn compute_hash_deterministic() {
        let hash1 = compute_hash("test content");
        let hash2 = compute_hash("test content");
        assert_eq!(hash1, hash2);
        assert_eq!(hash1.len(), 16);
    }

    #[test]
    fn compute_hash_differs() {
        let hash1 = compute_hash("content a");
        let hash2 = compute_hash("content b");
        assert_ne!(hash1, hash2);
    }

    #[test]
    fn is_float_literal_matches() {
        assert!(is_float_literal("0.85"));
        assert!(is_float_literal("-1.5"));
        assert!(is_float_literal("100.0"));
        assert!(!is_float_literal(".5"));
        assert!(!is_float_literal("1."));
        assert!(!is_float_literal("42"));
        assert!(!is_float_literal("hello"));
    }

    #[test]
    fn is_integer_literal_matches() {
        assert!(is_integer_literal("42"));
        assert!(is_integer_literal("-1"));
        assert!(is_integer_literal("0"));
        assert!(!is_integer_literal("0.5"));
        assert!(!is_integer_literal("hello"));
        assert!(!is_integer_literal(""));
    }

    // Regression lock for metadata-key order. The parser reads frontmatter
    // line-by-line into an IndexMap, so metadata iteration yields the file's
    // declared key order. Render sites iterate entity.metadata directly (see
    // `render::render_entity_markdown`), so any regression to HashMap
    // reintroduces hash-seed-dependent frontmatter ordering in MCP output.
    #[test]
    fn parse_preserves_frontmatter_key_order() {
        let md = "\
---
type: principle
universality: domain-wide
authority: proposed
tags: a, b, c
created_date: 2026-01-15
last_modified: 2026-04-12
---
# Key Order
";
        let result = parse_markdown(
            md,
            "key-order.md",
            &type_by_name(builtin_names::PRINCIPLE).unwrap(),
            "knowledge",
        )
        .unwrap();
        let keys: Vec<&str> = result.entity.metadata.keys().map(|s| s.as_str()).collect();
        assert_eq!(
            keys,
            vec![
                "type",
                "universality",
                "authority",
                "tags",
                "created_date",
                "last_modified",
            ],
            "metadata iteration must preserve frontmatter declaration order"
        );
    }

    // Regression lock for section-order round-trip stability. Today this
    // passes by construction: the parser inserts keys in schema-declared
    // order, the generator writes them in schema-declared order, and
    // `IndexMap` preserves that order across re-parses. HashMap iteration
    // order was the hole — an IndexMap-based entity.sections closes it.
    // Keep the test; if a future refactor reintroduces a HashMap anywhere on
    // the parse/write path, this catches it.
    #[test]
    fn parse_write_roundtrip_preserves_section_order() {
        let md = "\
---
type: spec
created_date: 2026-01-15
last_modified: 2026-04-12
level: M0
---
# Order Roundtrip

## Identity

Identity content.

## Purpose

Purpose content.

## Specifies

Specifies content.
";
        let schema = spec_schema();
        let first = parse_markdown(md, "order-roundtrip.md", &schema, "specs").unwrap();
        let regenerated = crate::entity::generator::generate_markdown(&first.entity, &schema);
        let second = parse_markdown(&regenerated, "order-roundtrip.md", &schema, "specs").unwrap();

        let first_keys: Vec<&String> = first.entity.sections.keys().collect();
        let second_keys: Vec<&String> = second.entity.sections.keys().collect();
        assert_eq!(
            first_keys, second_keys,
            "section iteration order must survive parse -> generate -> parse"
        );
    }

    // ------------------------------------------------------------------
    // Heading-spans extraction (H3–H6)
    //
    // These lock the parser contract: one extra pass per section that
    // records H3+ headings as a side-struct. Flat storage; level skips
    // are tolerated; code blocks are ignored. See
    // `extract_heading_spans`.
    // ------------------------------------------------------------------

    #[test]
    fn parser_extracts_single_h3() {
        let md = "\
---
type: spec
---
# Entity

## Identity

Body.

## Specifies

### Response Shapes

Content under response shapes.
";
        let result = parse_markdown(md, "h3-single.md", &spec_schema(), "specs").unwrap();
        let spans = result
            .entity
            .heading_spans
            .get("specifies")
            .expect("specifies section should have spans");
        assert_eq!(spans.len(), 1);
        assert_eq!(spans[0].level, 3);
        assert_eq!(spans[0].title, "Response Shapes");
        // The section is trimmed, so the H3 sits at offset 0.
        assert_eq!(spans[0].start_offset, 0);
        let section = result.entity.sections.get("specifies").unwrap();
        assert_eq!(spans[0].end_offset, section.len());
        // Non-specifies sections either get no entry or the content has no H3+ headings.
        assert!(
            result
                .entity
                .heading_spans
                .get("identity")
                .is_none_or(Vec::is_empty)
        );
    }

    #[test]
    fn parser_extracts_nested_h3_h4() {
        let md = "\
---
type: spec
---
# Entity

## Identity

Body.

## Specifies

### Outer

Outer body.

#### Inner

Inner body.
";
        let result = parse_markdown(md, "h3-h4.md", &spec_schema(), "specs").unwrap();
        let spans = result.entity.heading_spans.get("specifies").unwrap();
        assert_eq!(spans.len(), 2, "both H3 and H4 must be recorded");
        assert_eq!(spans[0].level, 3);
        assert_eq!(spans[0].title, "Outer");
        assert_eq!(spans[1].level, 4);
        assert_eq!(spans[1].title, "Inner");
        assert!(
            spans[0].start_offset < spans[1].start_offset,
            "spans must be in document order"
        );
        // H3 contains H4: H3.end_offset must cover H4.start_offset.
        assert!(
            spans[0].end_offset > spans[1].start_offset,
            "outer H3 must contain inner H4 by offset"
        );
    }

    #[test]
    fn parser_ignores_headings_in_code_blocks() {
        let md = "\
---
type: spec
---
# Entity

## Identity

Body.

## Specifies

Prefix.

```
### Not a heading
Still code.
```

Suffix.
";
        let result = parse_markdown(md, "h3-code.md", &spec_schema(), "specs").unwrap();
        let spans = result
            .entity
            .heading_spans
            .get("specifies")
            .cloned()
            .unwrap_or_default();
        assert!(
            spans.is_empty(),
            "a '### ' inside a fenced block must not register as a heading span: {spans:?}"
        );
    }

    #[test]
    fn parser_handles_level_skip() {
        let md = "\
---
type: spec
---
# Entity

## Identity

Body.

## Specifies

#### Skipped To H4

Content under a sudden H4 — no virtual H3 is inserted.
";
        let result = parse_markdown(md, "h2-h4.md", &spec_schema(), "specs").unwrap();
        let spans = result.entity.heading_spans.get("specifies").unwrap();
        assert_eq!(spans.len(), 1);
        assert_eq!(spans[0].level, 4);
        assert_eq!(spans[0].title, "Skipped To H4");
    }

    #[test]
    fn parser_handles_duplicate_siblings() {
        let md = "\
---
type: spec
---
# Entity

## Identity

Body.

## Specifies

### Same Title

First occurrence body.

### Same Title

Second occurrence body.
";
        let result = parse_markdown(md, "h3-dup.md", &spec_schema(), "specs").unwrap();
        let spans = result.entity.heading_spans.get("specifies").unwrap();
        assert_eq!(spans.len(), 2, "duplicate siblings must produce two spans");
        assert_eq!(spans[0].title, spans[1].title);
        assert_ne!(
            spans[0].start_offset, spans[1].start_offset,
            "spans with identical titles must be distinguishable by offset"
        );
        // Siblings at the same level: neither contains the other.
        assert!(
            spans[0].end_offset <= spans[1].start_offset,
            "first sibling must close before the second starts"
        );
    }

    // Duplicate `## Heading` lines for a schema-declared key collapse to the
    // first occurrence's body and emit a `DuplicateSectionHeading` warning.
    // Catch-all keys absorb arbitrary headings by design and do not warn.

    #[test]
    fn duplicate_declared_heading_two_populated_keeps_first_warns() {
        let md = "---\ntype: spec\n---\n# Title\n\n## Identity\n\nfirst body\n\n## Identity\n\nsecond body\n";
        let result = parse_markdown(md, "x.md", &spec_schema(), "v").unwrap();
        assert_eq!(
            result.entity.sections.get("identity").map(String::as_str),
            Some("first body"),
            "first body must win"
        );
        assert!(
            !result
                .entity
                .sections
                .get("identity")
                .unwrap()
                .contains("## Identity"),
            "storage value must not embed a duplicate heading"
        );
        assert_eq!(result.parse_warnings.len(), 1);
        match &result.parse_warnings[0] {
            crate::ops::WarningHint::DuplicateSectionHeading {
                section_key,
                heading,
                occurrences,
                ..
            } => {
                assert_eq!(section_key, "identity");
                assert_eq!(heading, "Identity");
                assert_eq!(*occurrences, 2);
            }
            other => panic!("expected DuplicateSectionHeading, got {other:?}"),
        }
    }

    #[test]
    fn duplicate_declared_heading_blank_then_populated_keeps_blank() {
        // First-wins is mechanical: a blank first occurrence wins over a
        // populated second one. The warning surfaces so the operator
        // notices content was discarded.
        let md =
            "---\ntype: spec\n---\n# Title\n\n## Identity\n\n## Identity\n\nleftover content\n";
        let result = parse_markdown(md, "x.md", &spec_schema(), "v").unwrap();
        assert_eq!(
            result.entity.sections.get("identity").map(String::as_str),
            Some(""),
            "first (blank) occurrence wins; second body is dropped"
        );
        assert_eq!(result.parse_warnings.len(), 1);
    }

    #[test]
    fn duplicate_declared_heading_three_occurrences() {
        let md = "---\ntype: spec\n---\n# Title\n\n## Constraints\n\nA\n\n## Constraints\n\n## Constraints\n\nC\n";
        let result = parse_markdown(md, "x.md", &spec_schema(), "v").unwrap();
        assert_eq!(
            result
                .entity
                .sections
                .get("constraints")
                .map(String::as_str),
            Some("A"),
        );
        assert_eq!(result.parse_warnings.len(), 1);
        match &result.parse_warnings[0] {
            crate::ops::WarningHint::DuplicateSectionHeading { occurrences, .. } => {
                assert_eq!(*occurrences, 3);
            }
            _ => unreachable!(),
        }
    }

    #[test]
    fn no_warning_when_each_declared_section_appears_once() {
        let md = "---\ntype: spec\n---\n# Title\n\n## Identity\n\nID\n\n## Purpose\n\nP\n\n## Constraints\n\nC\n";
        let result = parse_markdown(md, "x.md", &spec_schema(), "v").unwrap();
        assert!(result.parse_warnings.is_empty());
    }

    #[test]
    fn no_warning_when_catch_all_section_repeats() {
        // `specifies` is the spec schema's catch-all section. Repetition
        // there is silent — duplicates only warn for non-catch-all keys.
        let md =
            "---\ntype: spec\n---\n# Title\n\n## Specifies\n\nfirst\n\n## Specifies\n\nsecond\n";
        let result = parse_markdown(md, "x.md", &spec_schema(), "v").unwrap();
        assert!(
            result.parse_warnings.is_empty(),
            "catch-all repetition must not warn"
        );
    }

    // Three `## Realization` headings on a spec entity. The default-schema
    // `spec` does not declare `realization`, so it flows to the catch-all
    // `specifies` bucket and emits no warning, but the storage must still
    // not concatenate duplicate heading bytes — that was the bug being
    // fixed. Workspaces that declare `realization` (e.g. `software@0.1.0`)
    // additionally surface a `DuplicateSectionHeading` warning.
    #[test]
    fn duplicate_realization_does_not_concatenate_headers_in_storage() {
        let md = "---\ntype: spec\n---\n# Title\n\n## Identity\n\nID\n\n## Realization\n\n- a.mjs\n- b.mjs\n\n## Realization\n\n## Realization\n\n- c.mjs\n\n## Constraints\n\nC\n";
        let result = parse_markdown(md, "x.md", &spec_schema(), "v").unwrap();
        let catch_all = result.entity.sections.get("specifies").unwrap();
        let header_count = catch_all.matches("## Realization").count();
        assert!(
            header_count <= 1,
            "catch-all bucket must not contain multiple `## Realization` headers — got {header_count}: {catch_all:?}"
        );
    }

    // After a parse → render round-trip, an entity that was loaded from a
    // markdown file with three `## Identity` headings emits exactly one
    // `## Identity` heading on re-render. This is the self-heal contract:
    // the next read-modify-write of a duplicate-heading entity collapses
    // the markdown to one heading per declared section.
    #[test]
    fn parse_render_round_trip_collapses_duplicate_headings() {
        let md = "---\ntype: spec\n---\n# Title\n\n## Identity\n\nA\n\n## Identity\n\n## Identity\n\nC\n\n## Purpose\n\nP\n";
        let result = parse_markdown(md, "x.md", &spec_schema(), "v").unwrap();
        let rendered = crate::render::render_entity_markdown(&result.entity, None);
        let identity_count = rendered.matches("## Identity").count();
        assert_eq!(
            identity_count, 1,
            "rendered output must carry exactly one `## Identity`, got {identity_count}: {rendered}"
        );
        // First-wins: the rendered Identity body is `A`, not `C`.
        assert!(rendered.contains("\n## Identity\n\nA\n"));
        assert!(!rendered.contains("C\n"), "second body must not survive");
    }
}

/// End-to-end pins for the six verified code-block misparse classes,
/// on the real entity paths: section splitting, title extraction,
/// heading spans, and wiki-link extraction. The unit-level pins for
/// the mask itself live in [`crate::markdown`]; these assert the
/// classes are actually fixed where they did damage.
#[cfg(test)]
mod commonmark_referee {
    use super::*;
    use memstead_schema::{builtin_names, type_by_name};
    use std::sync::Arc;

    fn spec_schema() -> Arc<TypeDefinition> {
        type_by_name(builtin_names::SPEC).unwrap()
    }

    /// Wrap a `## Specifies` body in a minimal, valid spec entity.
    fn entity_with_specifies(body: &str) -> ParseResult {
        let md = format!(
            "---\ntype: spec\n---\n\n# Referee Test\n\n## Identity\n\nx\n\n## Specifies\n\n{body}\n"
        );
        parse_markdown(&md, "referee-test.md", &spec_schema(), "specs").unwrap()
    }

    fn headings(result: &ParseResult) -> Vec<&str> {
        result
            .entity
            .raw_section_headings
            .iter()
            .map(String::as_str)
            .collect()
    }

    fn link_targets(result: &ParseResult) -> Vec<String> {
        result.inline_links.iter().map(|id| id.0.clone()).collect()
    }

    /// The complement first: without it, every assertion below could
    /// pass because the paths do nothing at all.
    #[test]
    fn complement_prose_headings_and_links_still_work() {
        let r = entity_with_specifies("See [[real-target]] here.");
        assert_eq!(headings(&r), vec!["Identity", "Specifies"]);
        assert_eq!(link_targets(&r), vec!["specs--real-target".to_string()]);
        assert_eq!(r.entity.title, "Referee Test");
    }

    #[test]
    fn class_1_indented_code_block() {
        let r = entity_with_specifies("Example:\n\n    ## Not A Section\n    [[not-a-link]]\n");
        assert_eq!(headings(&r), vec!["Identity", "Specifies"]);
        assert!(link_targets(&r).is_empty(), "{:?}", link_targets(&r));
    }

    #[test]
    fn class_2_fence_indented_one_to_three_spaces() {
        let r = entity_with_specifies(
            "- item\n\n   ```\n   ## Not A Section\n   [[not-a-link]]\n   ```\n",
        );
        assert_eq!(headings(&r), vec!["Identity", "Specifies"]);
        assert!(link_targets(&r).is_empty(), "{:?}", link_targets(&r));
    }

    #[test]
    fn class_3_tilde_fence() {
        let r = entity_with_specifies("~~~\n## Not A Section\n[[not-a-link]]\n~~~\n");
        assert_eq!(headings(&r), vec!["Identity", "Specifies"]);
        assert!(link_targets(&r).is_empty(), "{:?}", link_targets(&r));
    }

    #[test]
    fn class_4_info_string_on_the_closing_line() {
        let r = entity_with_specifies(
            "```\ncode\n``` still-code\n## Not A Section\n[[not-a-link]]\n```\n",
        );
        assert_eq!(headings(&r), vec!["Identity", "Specifies"]);
        assert!(link_targets(&r).is_empty(), "{:?}", link_targets(&r));
    }

    #[test]
    fn class_5_fence_inside_a_blockquote() {
        let r = entity_with_specifies("> ```\n> ## Not A Section\n> [[not-a-link]]\n> ```\n");
        assert_eq!(headings(&r), vec!["Identity", "Specifies"]);
        assert!(link_targets(&r).is_empty(), "{:?}", link_targets(&r));
    }

    #[test]
    fn class_6_opening_fence_length_is_honoured_on_close() {
        let r = entity_with_specifies("````\n```\n## Not A Section\n[[not-a-link]]\n```\n````\n");
        assert_eq!(headings(&r), vec!["Identity", "Specifies"]);
        assert!(link_targets(&r).is_empty(), "{:?}", link_targets(&r));
    }

    /// The title extractor was the one scanner with no masking at all.
    #[test]
    fn a_heading_inside_a_code_block_never_becomes_the_title() {
        let md =
            "---\ntype: spec\n---\n\n```\n# Fake Title\n```\n\n# Real Title\n\n## Identity\n\nx\n";
        let r = parse_markdown(md, "title-test.md", &spec_schema(), "specs").unwrap();
        assert_eq!(r.entity.title, "Real Title");
    }

    /// …and when the code block is the whole body, the filename
    /// fallback applies rather than a title mined out of code.
    #[test]
    fn a_code_block_only_body_falls_back_to_the_filename() {
        let md = "---\ntype: spec\n---\n\n    # Fake Title\n\n## Identity\n\nx\n";
        let r = parse_markdown(md, "fallback-test.md", &spec_schema(), "specs").unwrap();
        assert_eq!(r.entity.title, "fallback-test");
    }

    #[test]
    fn heading_spans_ignore_code_block_content() {
        let r = entity_with_specifies("### Real Sub\n\n~~~\n### Fake Sub\n~~~\n");
        let spans = r.entity.heading_spans.get("specifies").expect("spans");
        let titles: Vec<&str> = spans.iter().map(|s| s.title.as_str()).collect();
        assert_eq!(titles, vec!["Real Sub"]);
    }

    /// One definition of "not visible to a link scanner": a link the
    /// strict validator cannot see is a link no path turns into an
    /// edge. Multi-backtick spans are the case a delimiter-count regex
    /// slices through.
    #[test]
    fn inline_code_spans_hide_links_on_the_extraction_path() {
        let r = entity_with_specifies("`[[hidden-one]]` and ``[[hidden-two]]`` but [[visible]].");
        assert_eq!(link_targets(&r), vec!["specs--visible".to_string()]);
    }

    /// The empty-target asymmetry: the strict extractor now *sees*
    /// `[[]]` and routes it to the same refusal the validator emits,
    /// instead of a pattern that could not match it at all.
    #[test]
    fn empty_wiki_link_target_is_refused_by_the_strict_extractor() {
        let errors = extract_inline_links("an empty [[]] link", "specs")
            .expect_err("empty target must refuse");
        assert_eq!(errors.len(), 1, "{errors:?}");
    }

    /// The read side tolerates drift by ignoring what it cannot
    /// decode — but it sees the same token the strict side refuses.
    #[test]
    fn empty_wiki_link_target_yields_no_id_on_the_lenient_path() {
        assert!(extract_inline_links_lenient("an empty [[]] link", "specs").is_empty());
    }

    /// A conflicted file must be refused however its frontmatter is
    /// shaped. Masking the whole file let a YAML value that reads as a
    /// fence opener blank the body — markers included — so the file
    /// loaded as a normal entity with BOTH merge sides fused into one
    /// body, which is the exact outcome the guard exists to prevent.
    #[test]
    fn merge_conflict_markers_are_seen_through_fence_shaped_frontmatter() {
        let body = "\n# T\n\n## Identity\n\n<<<<<<< HEAD\nours\n=======\ntheirs\n>>>>>>> branch\n";
        for fm in [
            "---\ntype: spec\n---",
            "---\ntype: spec\nnotes: |\n  ```rust\n  fn x() {}\n---",
            "---\ntype: spec\nnotes: |\n   ~~~\n---",
            "---\ntype: spec\nnotes: |\n    indented block\n---",
        ] {
            assert!(
                has_merge_conflict_markers(&format!("{fm}{body}")),
                "conflict markers must be seen through frontmatter: {fm:?}"
            );
        }
    }

    /// …and markers in the frontmatter itself count: git writes them
    /// wherever the hunks fall, including above the `---`.
    #[test]
    fn merge_conflict_markers_in_frontmatter_are_seen() {
        let content =
            "---\n<<<<<<< HEAD\ntype: spec\n=======\ntype: memo\n>>>>>>> branch\n---\n\n# T\n";
        assert!(has_merge_conflict_markers(content));
    }

    /// Complement: a fenced code example documenting conflict markers
    /// in a section body still does not trip the guard.
    #[test]
    fn a_fenced_conflict_marker_example_still_does_not_trip_the_guard() {
        let content = "---\ntype: spec\n---\n\n# T\n\n## Identity\n\n```\n<<<<<<< HEAD\nours\n=======\ntheirs\n>>>>>>> branch\n```\n";
        assert!(!has_merge_conflict_markers(content));
    }

    /// A relationship row inside a code block is an example of the
    /// syntax, not a relationship. It used to become a live edge and an
    /// auto-stub while the strict validator — which masks — could not
    /// see the link at all: one path synthesising an edge from what
    /// another path refuses to see.
    #[test]
    fn a_relationship_row_inside_a_code_block_is_not_a_relationship() {
        for body in [
            "```\n- **REFERENCES**: [[ghost]]\n```",
            "~~~\n- **REFERENCES**: [[ghost]]\n~~~",
            "    - **REFERENCES**: [[ghost]]",
            "> ```\n> - **REFERENCES**: [[ghost]]\n> ```",
            "````\n```\n- **REFERENCES**: [[ghost]]\n```\n````",
        ] {
            let (rels, _) = parse_relationships_with_warnings(body, "specs", None);
            assert!(
                rels.is_empty(),
                "code-block row must not become an edge: {body:?} -> {rels:?}"
            );
        }
    }

    /// …and a row hidden inside an INLINE CODE SPAN is not one either.
    /// A blocks-only mask left this row invisible to the strict
    /// validator and to every link extractor — both of which mask
    /// spans — while still building an edge and a stub from it. A
    /// multi-line span is the shape that bites: a lazy paragraph
    /// continuation keeps the backticks open across the row.
    #[test]
    fn a_relationship_row_inside_an_inline_code_span_is_not_a_relationship() {
        for body in [
            // The row is indented, so it does not interrupt the
            // paragraph as a list — it is a lazy continuation and the
            // backtick pair holds the span open across all three lines.
            // (At column 0 a `-` DOES start a list, the span never
            // forms, and the row is a real relationship — correctly.)
            "Example `open\n    - **REFERENCES**: [[ghost]]\nclose`",
            "A `- **REFERENCES**: [[ghost]]` sample.",
            "A ``- **REFERENCES**: [[ghost]]`` sample.",
        ] {
            let (rels, _) = parse_relationships_with_warnings(body, "specs", None);
            assert!(
                rels.is_empty(),
                "code-span row must not become an edge: {body:?} -> {rels:?}"
            );
        }
    }

    /// Complement: a real row still parses, keeps its type, target and
    /// em-dash description, and still warns on an ambiguous delimiter —
    /// every captured span is read from the original, not the mask.
    #[test]
    fn real_relationship_rows_are_unchanged_by_the_mask() {
        let body = "- **REFERENCES**: [[alpha]]\n- **uses**: [[beta]] — because it must\n\n```\n- **REFERENCES**: [[ghost]]\n```\n";
        let (rels, _) = parse_relationships_with_warnings(body, "specs", None);
        assert_eq!(rels.len(), 2, "{rels:?}");
        assert_eq!(rels[0].rel_type, "REFERENCES");
        assert_eq!(rels[0].target.0, "specs--alpha");
        assert_eq!(rels[0].description, None);
        assert_eq!(
            rels[1].rel_type, "USES",
            "case is normalised from the original"
        );
        assert_eq!(rels[1].target.0, "specs--beta");
        assert_eq!(rels[1].description.as_deref(), Some("because it must"));
    }

    #[test]
    fn ambiguous_delimiter_warning_still_fires_on_a_real_row() {
        let id = file_path_to_id("x.md", "specs");
        let (_, warnings) = parse_relationships_with_warnings(
            "- **REFERENCES**: [[alpha]] -- not an em dash\n",
            "specs",
            Some(&id),
        );
        assert_eq!(warnings.len(), 1, "{warnings:?}");
    }

    /// Frontmatter is not markdown. Masking the whole file would hand
    /// a CommonMark parser YAML it can read as block structure: a
    /// value line that looks like a fence opener (legal at 1–3 spaces
    /// since the indented-fence class was fixed) would open a code
    /// block that runs past the closing `---` and mask the entire
    /// body — no title, no sections, no links. The split happens
    /// first; only the body is masked.
    #[test]
    fn frontmatter_never_opens_a_code_block_over_the_body() {
        for fm in [
            "notes: |\n  ```rust",
            "notes: |\n   ~~~",
            "notes: |\n  ```\n  still open",
            "notes: |\n    indented block\n",
        ] {
            let md = format!(
                "---\ntype: spec\n{fm}\n---\n\n# Real Title\n\n## Identity\n\nSee [[a-link]].\n"
            );
            let r = parse_markdown(&md, "fm-test.md", &spec_schema(), "specs").unwrap();
            assert_eq!(
                r.entity.title, "Real Title",
                "frontmatter ate the title: {fm:?}"
            );
            assert_eq!(
                headings(&r),
                vec!["Identity"],
                "frontmatter ate the sections: {fm:?}"
            );
            assert_eq!(
                link_targets(&r),
                vec!["specs--a-link".to_string()],
                "frontmatter ate the links: {fm:?}"
            );
        }
    }
}