dms/

lib.rs

//! DMS parser — full spec v0.14.

// Re-exported so downstream code can build meta tables without its own
// `indexmap` dependency.
pub use indexmap::IndexMap;

// Tier-1 decoder/encoder skeleton. Public types match the contract
// in `dms/TIER1.md` §"Document types" and §"AST shape"; the lexer
// and parser additions are not yet implemented. Tier-0 callers can
// ignore this module — `decode_document` / `encode` are unchanged.
pub mod tier1;
pub mod tier1_stream;

// `fast_hash` feature swaps the std siphash for `foldhash::fast::FixedState`
// in the `IndexMap` that backs `Value::Table` and the front-matter meta
// table. Mirrors toml-rs's `fast_hash` switch — keeps DMS-side
// apples-to-apples with TOML when both have the flag enabled.
#[cfg(feature = "fast_hash")]
type DmsHasher = foldhash::fast::FixedState;
#[cfg(not(feature = "fast_hash"))]
type DmsHasher = std::collections::hash_map::RandomState;

/// `IndexMap` specialization used for body tables and front matter.
/// Hasher is swappable via the `fast_hash` cargo feature.
pub type DmsMap<V> = IndexMap<String, V, DmsHasher>;

/// `HashMap` specialization used by **unordered** body tables, opt-in via
/// `decode_document_unordered` / `decode_lite_document_unordered` (or the
/// `--ignore-order` CLI flag). Iteration order is **arbitrary** — see
/// SPEC §"Unordered tables". Reuses `DmsHasher` so the hasher is the
/// same as the ordered side; the only difference is the lack of the
/// `IndexMap`'s entry-order `Vec<usize>` bookkeeping.
pub type DmsHashMap<V> = std::collections::HashMap<String, V, DmsHasher>;

#[derive(Debug, Clone, PartialEq)]
pub enum Value {
    Bool(bool),
    Integer(i64),
    Float(f64),
    String(String),
    OffsetDateTime(String),
    LocalDateTime(String),
    LocalDate(String),
    LocalTime(String),
    /// Ordered table (insertion-order preserving). Built by the default
    /// parser entry points.
    Table(DmsMap<Value>),
    /// Unordered table (arbitrary iteration order). Built only by the
    /// `*_unordered` decoder entry points. `encode` (full mode) refuses
    /// to round-trip a Document containing this variant; `encode_lite`
    /// accepts it but emits keys in arbitrary order. See SPEC
    /// §"Unordered tables".
    UnorderedTable(DmsHashMap<Value>),
    List(Vec<Value>),
}

#[derive(Debug, Clone)]
pub struct DecodeError {
    pub line: usize,
    pub column: usize,
    pub message: String,
}

impl std::fmt::Display for DecodeError {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        write!(f, "{}:{}: {}", self.line, self.column, self.message)
    }
}

impl std::error::Error for DecodeError {}

/// Deprecated alias for [`DecodeError`]. Removed in v0.4.
///
/// SPEC v0.14 renamed `parse`/`to_dms` -> `decode`/`encode`; this type
/// alias keeps `dms::ParseError` working for one release so downstream
/// code keeps compiling (with a warning).
#[deprecated(since = "0.3.0", note = "renamed to `DecodeError`")]
pub type ParseError = DecodeError;

/// Errors raised by the encode (emitter) path. Currently the only
/// failure mode is full-mode emit refusing a `Document` that contains
/// an unordered table — see SPEC §"Unordered tables". Lite-mode emit
/// (`encode_lite`) cannot fail and accepts unordered Documents.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum EncodeError {
    /// Full-mode `encode` was called with a Document whose body
    /// contains a `Value::UnorderedTable` (built only by the
    /// `*_unordered` decoder entry points). Round-trip emit needs a
    /// stable iteration order; an unordered Document cannot satisfy
    /// that. Use `encode_lite` instead, which accepts unordered
    /// Documents but emits keys in arbitrary order.
    UnorderedInFullMode,
}

impl std::fmt::Display for EncodeError {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            EncodeError::UnorderedInFullMode => write!(
                f,
                "encode (full-mode round-trip) refuses Document with \
                 Value::UnorderedTable; unordered tables have arbitrary \
                 iteration order — use encode_lite instead. \
                 See SPEC §\"Unordered tables\"."
            ),
        }
    }
}

impl std::error::Error for EncodeError {}

/// A parsed DMS document — body value plus optional front matter table.
#[derive(Debug, Clone, PartialEq)]
pub struct Document {
    /// Front matter table (user metadata only; reserved `_dms_*` keys are
    /// consumed by the parser and do NOT appear here). `None` if the
    /// source had no `+++` block.
    pub meta: Option<DmsMap<Value>>,
    /// The body — the rest of the document, parsed per the spec.
    pub body: Value,
    /// Comments captured during parsing, in source order, each tagged with
    /// its attachment (path + position). Empty when the source had no
    /// comments.
    ///
    /// Path-prefix convention: body-attached comments use bare paths
    /// (rooted at the body value); front-matter-attached comments use a
    /// path that begins with the special segment
    /// `BreadcrumbSegment::Key("__fm__")` and continues with the path
    /// inside the front-matter table. (We chose a single flat list with
    /// a sentinel prefix — rather than a separate `meta_comments` field —
    /// for simpler downstream iteration: a re-emitter that walks the
    /// list once handles both contexts uniformly.)
    pub comments: Vec<AttachedComment>,
    /// Sparse `(path, OriginalLiteral)` entries — only nodes whose
    /// surface form differs from the default (decimal-no-underscores
    /// for ints, basic-quoted for strings) get an entry. Consulted by
    /// `encode` to re-emit values in their decoded form. The
    /// conformance JSON encoder ignores this field. Same `__fm__`
    /// path-prefix convention as `comments`.
    pub original_forms: Vec<(Vec<BreadcrumbSegment>, OriginalLiteral)>,
}

/// Whether a comment was a `#`/`//` line comment or a `### ###` / `/* */`
/// block comment.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum CommentKind {
    Line,
    Block,
}

/// How a comment attaches to its target node.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum CommentPosition {
    /// Comment(s) on lines preceding a sibling node (no blank line gap).
    Leading,
    /// `/* ... */` block comment(s) appearing between a key's `:` and
    /// its value, or between a `+` and a list item's content. `Inner`
    /// is `/* ... */`-only (line comments consume to EOL; `### ###`
    /// block comments require the opener on its own line). See SPEC
    /// §Attachment rules.
    Inner,
    /// Comment(s) on the same line as a value, after the value.
    /// Multiple stack in source order; a `#`/`//` line comment, if
    /// present, must come last.
    Trailing,
    /// Comment that did not attach to a sibling — separated by a blank
    /// line, or left over at block close. Attaches to the enclosing
    /// container.
    Floating,
}

/// One captured comment.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct Comment {
    /// Raw text of the comment, **including delimiters**:
    /// `# foo` / `// foo` / `/* foo */` / `### LABEL\n...\nLABEL`.
    pub content: String,
    pub kind: CommentKind,
}

/// One step in a comment-attachment breadcrumb path.
///
/// `Ord` is derived so the emitter can sort path slices for binary
/// search lookup (see `SortedIndex` in §encode emitter). The order
/// itself is not normative — it only needs to be stable and total so
/// that two passes of `encode` produce byte-identical output. The
/// derived order is `Key < Index` (variant order), then lexicographic
/// on the inner value.
#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]
pub enum BreadcrumbSegment {
    Key(String),
    Index(usize),
}

/// A comment plus its attachment metadata.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct AttachedComment {
    pub comment: Comment,
    pub position: CommentPosition,
    /// Path to the node the comment is attached to. Empty `[]` means
    /// "the document root" (or the front-matter table root, given the
    /// `__fm__` prefix convention).
    pub path: Vec<BreadcrumbSegment>,
}

/// Per-node literal-form record, captured during decoding so that
/// `encode` can re-emit the value in the same source form (integer
/// base, string flavor, heredoc modifiers). Keyed off the node's path
/// in `Document::original_forms`. Spec §encode.
#[derive(Debug, Clone, PartialEq)]
pub enum OriginalLiteral {
    /// An integer literal, stored as its exact source lexeme:
    /// `"0x1F40"`, `"0o755"`, `"0b1010_0110"`, `"1_000_000"`,
    /// `"+42"`, `"-7"`, etc. Re-emitted verbatim.
    Integer { lit: String },
    /// A string value, stored with its original surface form (basic /
    /// literal / heredoc-basic / heredoc-literal, plus heredoc label
    /// and modifier list).
    String { form: StringForm },
}

#[derive(Debug, Clone, PartialEq)]
pub enum StringForm {
    /// `"..."`
    Basic,
    /// `'...'`
    Literal,
    /// `"""[LABEL]...LABEL` or `'''[LABEL]...LABEL` (or unlabeled
    /// `"""..."""` / `'''...'''`).
    Heredoc {
        flavor: HeredocFlavor,
        /// `None` means unlabeled (terminator is `"""` / `'''`).
        label: Option<String>,
        /// Modifier calls in source order: `_trim(...)`,
        /// `_fold_paragraphs()`, etc. Re-emitted on the opener line.
        modifiers: Vec<HeredocModifierCall>,
    },
}

#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum HeredocFlavor {
    BasicTriple,
    LiteralTriple,
}

#[derive(Debug, Clone, PartialEq)]
pub struct HeredocModifierCall {
    pub name: String,
    /// Pre-evaluated args (Strings, Integers, etc.). Re-rendered
    /// using the same default-form emit rules as ordinary values
    /// (integers as decimal, strings as basic-quoted).
    pub args: Vec<Value>,
}

/// Parse mode — full preserves comments and original literal forms;
/// lite skips that bookkeeping. See SPEC §Parsing modes — full and
/// lite. Same grammar, same errors; only the round-trip metadata
/// differs.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum ParseMode {
    Full,
    Lite,
}

/// Capability advertisement — this port ships lite-mode decode +
/// lite-mode `encode`. See SPEC §Parsing modes — full and lite. Lite
/// mode is optional to ship; callers can probe this constant before
/// opting in via `decode_lite_document` / `encode_lite`.
pub const SUPPORTS_LITE_MODE: bool = true;

/// Capability advertisement — this port ships unordered-table decode
/// mode. See SPEC §Unordered tables. Unordered mode is optional to
/// ship; callers probe this before opting in via
/// `decode_document_unordered` / `decode_lite_document_unordered`.
pub const SUPPORTS_IGNORE_ORDER: bool = true;

/// Decode a DMS source string and return only the body. Front matter,
/// if present, is decoded and validated (illegal declarations error),
/// then discarded. SPEC v0.14 canonical name (replaces `parse`).
pub fn decode(src: &str) -> Result<Value, DecodeError> {
    decode_document(src).map(|d| d.body)
}

/// Lite-mode body-only decode. Equivalent to
/// `decode_lite_document(src)?.body`, but returns only the body. Use
/// when you don't need front matter either.
pub fn decode_lite(src: &str) -> Result<Value, DecodeError> {
    decode_document_with_mode(src, ParseMode::Lite).map(|d| d.body)
}

/// Lite-mode `Document` decode. Body + front matter, no comment AST,
/// no `original_forms`. The returned `Document` is **not** suitable
/// for `encode` round-trip — see SPEC §Parsing modes — full and lite.
pub fn decode_lite_document(src: &str) -> Result<Document, DecodeError> {
    decode_document_with_mode(src, ParseMode::Lite)
}

/// Decode a full DMS document, returning body + front-matter metadata
/// + attached comments.
pub fn decode_document(src: &str) -> Result<Document, DecodeError> {
    decode_document_with_options(src, ParseMode::Full, false)
}

/// Full-mode decode with the **unordered** table backing — every
/// `Value::Table` is replaced by `Value::UnorderedTable` (a plain
/// `HashMap`, no insertion-order tracking). See SPEC §"Unordered
/// tables". Front matter remains ordered (per spec — meta is small and
/// is consumed strictly).
///
/// **Important:** the resulting `Document` cannot be round-tripped via
/// `encode` (full-mode emit). Use `encode_lite` if you need to
/// re-serialize. `encode` will panic with a clear message on an
/// unordered Document.
pub fn decode_document_unordered(src: &str) -> Result<Document, DecodeError> {
    decode_document_with_options(src, ParseMode::Full, true)
}

/// Lite-mode decode with the **unordered** table backing. The
/// `(unordered, lite)` combo is the fastest read-only path: hash-only
/// table backing + no comment/original-form bookkeeping. See SPEC
/// §"Unordered tables".
pub fn decode_lite_document_unordered(src: &str) -> Result<Document, DecodeError> {
    decode_document_with_options(src, ParseMode::Lite, true)
}

/// Decode with explicit mode selection.
pub fn decode_document_with_mode(src: &str, mode: ParseMode) -> Result<Document, DecodeError> {
    decode_document_with_options(src, mode, false)
}

/// Decode with explicit mode and ordering selection. When
/// `ignore_order=true`, body tables are built as `Value::UnorderedTable`
/// (HashMap-backed); when false, as `Value::Table` (IndexMap-backed,
/// insertion-order preserved). See SPEC §"Unordered tables".
pub fn decode_document_with_options(
    src: &str,
    mode: ParseMode,
    ignore_order: bool,
) -> Result<Document, DecodeError> {
    // SPEC §"UTF-8 only, NFC-normalized": DMS source is plain UTF-8 with
    // no byte-order mark. A leading U+FEFF is not silently consumed —
    // reject it explicitly so encoding mistakes surface loudly. (BOMs
    // *inside* string/heredoc bodies are fine; this only fires at offset 0.)
    if src.starts_with('\u{FEFF}') {
        return Err(DecodeError {
            line: 1,
            column: 1,
            message: "BOM (U+FEFF) at file start is not allowed; DMS source is plain UTF-8"
                .to_string(),
        });
    }
    // U+0000 is not allowed anywhere in DMS source (see SPEC §Strings).
    // Reject up front so deeper code can assume NUL-free bytes.
    if let Some(off) = src.find('\0') {
        let prefix = &src[..off];
        let line = 1 + prefix.bytes().filter(|&b| b == b'\n').count();
        let last_nl = prefix.rfind('\n').map(|i| i + 1).unwrap_or(0);
        let col = off - last_nl + 1;
        return Err(DecodeError {
            line,
            column: col,
            message: "U+0000 (NUL) is not allowed in DMS source".to_string(),
        });
    }
    // SPEC §Unicode normalization: NFC the source before tokenization so
    // bare keys in decomposed form get accepted, and so equivalent
    // spellings collide on the duplicate-key check. Idempotent for
    // already-NFC input.
    let normalized = nfc_normalize(src);
    let mut p = Parser::new_with_mode(&normalized, mode);
    p.ignore_order = ignore_order;
    let meta = p.parse_front_matter()?;
    let body = p.parse_body()?;
    Ok(Document {
        meta,
        body,
        comments: p.comments,
        original_forms: p.original_forms,
    })
}

/// Tier-1-aware decode entry point used by `tier1::decode_t1`.
///
/// Identical to `decode_document_with_options(src, Full, false)` except
/// that `_dms_tier: 1` in front matter is accepted rather than rejected.
/// Returns the decoded `Document` together with the observed tier value
/// (`0` when no `_dms_tier` key was present or when `_dms_tier: 0`;
/// `1` when `_dms_tier: 1` was seen). See TIER1.md §"Front matter
/// additions" for the contract.
pub(crate) fn decode_document_accepting_tier1(
    src: &str,
) -> Result<
    (
        Document,
        u32,
        Vec<(Vec<BreadcrumbSegment>, tier1::DecorationPosition, tier1::DecoratorCall)>,
        Vec<Vec<BreadcrumbSegment>>,
    ),
    DecodeError,
> {
    if src.starts_with('\u{FEFF}') {
        return Err(DecodeError {
            line: 1,
            column: 1,
            message: "BOM (U+FEFF) at file start is not allowed; DMS source is plain UTF-8"
                .to_string(),
        });
    }
    if let Some(off) = src.find('\0') {
        let prefix = &src[..off];
        let line = 1 + prefix.bytes().filter(|&b| b == b'\n').count();
        let last_nl = prefix.rfind('\n').map(|i| i + 1).unwrap_or(0);
        let col = off - last_nl + 1;
        return Err(DecodeError {
            line,
            column: col,
            message: "U+0000 (NUL) is not allowed in DMS source".to_string(),
        });
    }
    let normalized = nfc_normalize(src);
    let mut p = Parser::new_with_mode(&normalized, ParseMode::Full);
    p.accept_tier1 = true;
    let meta = p.parse_front_matter()?;
    let tier = p.observed_tier;
    let body = p.parse_body()?;
    let raw_decorations = p.decorations_raw;
    let decoration_only_paths = p.decoration_only_paths;
    Ok((
        Document {
            meta,
            body,
            comments: p.comments,
            original_forms: p.original_forms,
        },
        tier,
        raw_decorations,
        decoration_only_paths,
    ))
}

/// Parse a bare value string with tier-1 decoration capture active.
///
/// Used by `tier1::parse_param_group` to parse the interior of a
/// param-group bracket (`{...}` for named, `[...]` for positional)
/// while capturing any nested decorator calls on the values.
///
/// `src` must be a complete value expression (table literal, list
/// literal, etc.) with no surrounding front matter. Decorations found
/// inside are returned in the second element of the tuple; paths are
/// rooted at the parsed value's own shape (e.g. `[Key("label")]` for
/// `{label: |inner() "v"}`).
///
/// Errors if there is trailing content after the value.
pub(crate) fn parse_value_t1(
    src: &str,
) -> Result<
    (
        Value,
        Vec<(Vec<BreadcrumbSegment>, tier1::DecorationPosition, tier1::DecoratorCall)>,
    ),
    DecodeError,
> {
    let mut p = Parser::new_with_mode(src, ParseMode::Full);
    p.accept_tier1 = true;
    p.observed_tier = 1;
    let v = p.parse_body()?;
    // parse_body already checks for trailing content.
    Ok((v, p.decorations_raw))
}

/// Front-matter-only decode. Scans leading trivia, the opening `+++`,
/// the front-matter contents, and the closing `+++`, then stops — body
/// bytes are NOT tokenized. Required at SPEC tier 0; see SPEC
/// §"Front-matter-only decode" for the full contract.
///
/// Return value:
///
/// - `Ok(None)` — the document has no front matter at all (no opening
///   `+++` after leading trivia).
/// - `Ok(Some(Value::Table(map)))` — front matter was present. `map` is
///   empty when the source carried `+++\n+++\n` with no inner keys, so
///   callers can distinguish "no front matter" from "present-but-empty".
/// - `Err(DecodeError)` — every front-matter rule still applies:
///   open/close on their own lines, unterminated front matter is an
///   error, the `_`-prefix namespace is enforced (`_dms_tier` is
///   type-checked, unknown reserved keys rejected). Diagnostics inside
///   the `+++ ... +++` block are byte-identical to a full decode.
///
/// Errors that only manifest in the body (duplicate body keys,
/// unterminated body heredoc, …) are NOT surfaced — that's the entire
/// point of this entry point. Callers needing whole-document validation
/// must use [`decode_document`].
///
/// Runs in lite mode (no comment AST, no `original_forms`).
pub fn decode_front_matter(src: &str) -> Result<Option<Value>, DecodeError> {
    // Source preprocessing — same as `decode_document_with_options` so
    // diagnostics stay byte-identical between front-matter-only and
    // full decode for sources whose only error is in the FM block.
    if src.starts_with('\u{FEFF}') {
        return Err(DecodeError {
            line: 1,
            column: 1,
            message: "BOM (U+FEFF) at file start is not allowed; DMS source is plain UTF-8"
                .to_string(),
        });
    }
    if let Some(off) = src.find('\0') {
        let prefix = &src[..off];
        let line = 1 + prefix.bytes().filter(|&b| b == b'\n').count();
        let last_nl = prefix.rfind('\n').map(|i| i + 1).unwrap_or(0);
        let col = off - last_nl + 1;
        return Err(DecodeError {
            line,
            column: col,
            message: "U+0000 (NUL) is not allowed in DMS source".to_string(),
        });
    }
    let normalized = nfc_normalize(src);
    let mut p = Parser::new_with_mode(&normalized, ParseMode::Lite);
    let meta = p.parse_front_matter()?;
    // Note: we deliberately do NOT call p.parse_body() — body bytes
    // remain untokenized, per SPEC §"Front-matter-only decode".
    Ok(meta.map(Value::Table))
}

// ---------- deprecated `parse*` aliases (SPEC v0.14 rename) ----------
//
// SPEC v0.14 renamed the canonical entry points from `parse`/`to_dms`
// to `decode`/`encode`. The old names live on for one release as
// thin deprecated wrappers so existing downstream code keeps compiling
// (with a warning) — slated for removal in v0.15. See PORTING.md
// §"Migration from the `parse`/`to_dms` era".

/// Deprecated alias for [`decode`]. Removed in v0.15.
#[deprecated(since = "0.3.0", note = "use `decode` instead")]
pub fn parse(src: &str) -> Result<Value, DecodeError> {
    decode(src)
}

/// Deprecated alias for [`decode_lite`]. Removed in v0.15.
#[deprecated(since = "0.3.0", note = "use `decode_lite` instead")]
pub fn parse_lite(src: &str) -> Result<Value, DecodeError> {
    decode_lite(src)
}

/// Deprecated alias for [`decode_lite_document`]. Removed in v0.15.
#[deprecated(since = "0.3.0", note = "use `decode_lite_document` instead")]
pub fn parse_lite_document(src: &str) -> Result<Document, DecodeError> {
    decode_lite_document(src)
}

/// Deprecated alias for [`decode_document`]. Removed in v0.15.
#[deprecated(since = "0.3.0", note = "use `decode_document` instead")]
pub fn parse_document(src: &str) -> Result<Document, DecodeError> {
    decode_document(src)
}

/// Deprecated alias for [`decode_document_unordered`]. Removed in v0.15.
#[deprecated(since = "0.3.0", note = "use `decode_document_unordered` instead")]
pub fn parse_document_unordered(src: &str) -> Result<Document, DecodeError> {
    decode_document_unordered(src)
}

/// Deprecated alias for [`decode_lite_document_unordered`]. Removed in v0.15.
#[deprecated(since = "0.3.0", note = "use `decode_lite_document_unordered` instead")]
pub fn parse_lite_document_unordered(src: &str) -> Result<Document, DecodeError> {
    decode_lite_document_unordered(src)
}

/// Deprecated alias for [`decode_document_with_mode`]. Removed in v0.15.
#[deprecated(since = "0.3.0", note = "use `decode_document_with_mode` instead")]
pub fn parse_document_with_mode(src: &str, mode: ParseMode) -> Result<Document, DecodeError> {
    decode_document_with_mode(src, mode)
}

/// Deprecated alias for [`decode_document_with_options`]. Removed in v0.15.
#[deprecated(since = "0.3.0", note = "use `decode_document_with_options` instead")]
pub fn parse_document_with_options(
    src: &str,
    mode: ParseMode,
    ignore_order: bool,
) -> Result<Document, DecodeError> {
    decode_document_with_options(src, mode, ignore_order)
}

/// NFC-normalize a string. Returns the original `String` allocation when
/// the input is already NFC (the common case for ASCII-heavy sources),
/// otherwise allocates the normalized form.
fn nfc_normalize(s: &str) -> String {
    use unicode_normalization::{is_nfc_quick, IsNormalized, UnicodeNormalization};
    match is_nfc_quick(s.chars()) {
        IsNormalized::Yes => s.to_string(),
        _ => s.nfc().collect(),
    }
}

// ---------- helpers ----------

// Frozen Unicode 15.1 snapshot of `XID_Continue \ Default_Ignorable_Code_Point`.
// SPEC §"What counts as a bare key" — UAX #31 §2 default identifier syntax,
// frozen so every conforming parser rejects/accepts the *same* code points
// regardless of the host runtime's stdlib Unicode version. 773 inclusive
// ranges, sorted by start; binary searched in `is_xid_continue`.
static XID_CONTINUE_RANGES: &[(u32, u32)] = &[
    (0x00AA, 0x00AA),
    (0x00B5, 0x00B5),
    (0x00B7, 0x00B7),
    (0x00BA, 0x00BA),
    (0x00C0, 0x00D6),
    (0x00D8, 0x00F6),
    (0x00F8, 0x02C1),
    (0x02C6, 0x02D1),
    (0x02E0, 0x02E4),
    (0x02EC, 0x02EC),
    (0x02EE, 0x02EE),
    (0x0300, 0x034E),
    (0x0350, 0x0374),
    (0x0376, 0x0377),
    (0x037B, 0x037D),
    (0x037F, 0x037F),
    (0x0386, 0x038A),
    (0x038C, 0x038C),
    (0x038E, 0x03A1),
    (0x03A3, 0x03F5),
    (0x03F7, 0x0481),
    (0x0483, 0x0487),
    (0x048A, 0x052F),
    (0x0531, 0x0556),
    (0x0559, 0x0559),
    (0x0560, 0x0588),
    (0x0591, 0x05BD),
    (0x05BF, 0x05BF),
    (0x05C1, 0x05C2),
    (0x05C4, 0x05C5),
    (0x05C7, 0x05C7),
    (0x05D0, 0x05EA),
    (0x05EF, 0x05F2),
    (0x0610, 0x061A),
    (0x0620, 0x0669),
    (0x066E, 0x06D3),
    (0x06D5, 0x06DC),
    (0x06DF, 0x06E8),
    (0x06EA, 0x06FC),
    (0x06FF, 0x06FF),
    (0x0710, 0x074A),
    (0x074D, 0x07B1),
    (0x07C0, 0x07F5),
    (0x07FA, 0x07FA),
    (0x07FD, 0x07FD),
    (0x0800, 0x082D),
    (0x0840, 0x085B),
    (0x0860, 0x086A),
    (0x0870, 0x0887),
    (0x0889, 0x088E),
    (0x0898, 0x08E1),
    (0x08E3, 0x0963),
    (0x0966, 0x096F),
    (0x0971, 0x0983),
    (0x0985, 0x098C),
    (0x098F, 0x0990),
    (0x0993, 0x09A8),
    (0x09AA, 0x09B0),
    (0x09B2, 0x09B2),
    (0x09B6, 0x09B9),
    (0x09BC, 0x09C4),
    (0x09C7, 0x09C8),
    (0x09CB, 0x09CE),
    (0x09D7, 0x09D7),
    (0x09DC, 0x09DD),
    (0x09DF, 0x09E3),
    (0x09E6, 0x09F1),
    (0x09FC, 0x09FC),
    (0x09FE, 0x09FE),
    (0x0A01, 0x0A03),
    (0x0A05, 0x0A0A),
    (0x0A0F, 0x0A10),
    (0x0A13, 0x0A28),
    (0x0A2A, 0x0A30),
    (0x0A32, 0x0A33),
    (0x0A35, 0x0A36),
    (0x0A38, 0x0A39),
    (0x0A3C, 0x0A3C),
    (0x0A3E, 0x0A42),
    (0x0A47, 0x0A48),
    (0x0A4B, 0x0A4D),
    (0x0A51, 0x0A51),
    (0x0A59, 0x0A5C),
    (0x0A5E, 0x0A5E),
    (0x0A66, 0x0A75),
    (0x0A81, 0x0A83),
    (0x0A85, 0x0A8D),
    (0x0A8F, 0x0A91),
    (0x0A93, 0x0AA8),
    (0x0AAA, 0x0AB0),
    (0x0AB2, 0x0AB3),
    (0x0AB5, 0x0AB9),
    (0x0ABC, 0x0AC5),
    (0x0AC7, 0x0AC9),
    (0x0ACB, 0x0ACD),
    (0x0AD0, 0x0AD0),
    (0x0AE0, 0x0AE3),
    (0x0AE6, 0x0AEF),
    (0x0AF9, 0x0AFF),
    (0x0B01, 0x0B03),
    (0x0B05, 0x0B0C),
    (0x0B0F, 0x0B10),
    (0x0B13, 0x0B28),
    (0x0B2A, 0x0B30),
    (0x0B32, 0x0B33),
    (0x0B35, 0x0B39),
    (0x0B3C, 0x0B44),
    (0x0B47, 0x0B48),
    (0x0B4B, 0x0B4D),
    (0x0B55, 0x0B57),
    (0x0B5C, 0x0B5D),
    (0x0B5F, 0x0B63),
    (0x0B66, 0x0B6F),
    (0x0B71, 0x0B71),
    (0x0B82, 0x0B83),
    (0x0B85, 0x0B8A),
    (0x0B8E, 0x0B90),
    (0x0B92, 0x0B95),
    (0x0B99, 0x0B9A),
    (0x0B9C, 0x0B9C),
    (0x0B9E, 0x0B9F),
    (0x0BA3, 0x0BA4),
    (0x0BA8, 0x0BAA),
    (0x0BAE, 0x0BB9),
    (0x0BBE, 0x0BC2),
    (0x0BC6, 0x0BC8),
    (0x0BCA, 0x0BCD),
    (0x0BD0, 0x0BD0),
    (0x0BD7, 0x0BD7),
    (0x0BE6, 0x0BEF),
    (0x0C00, 0x0C0C),
    (0x0C0E, 0x0C10),
    (0x0C12, 0x0C28),
    (0x0C2A, 0x0C39),
    (0x0C3C, 0x0C44),
    (0x0C46, 0x0C48),
    (0x0C4A, 0x0C4D),
    (0x0C55, 0x0C56),
    (0x0C58, 0x0C5A),
    (0x0C5D, 0x0C5D),
    (0x0C60, 0x0C63),
    (0x0C66, 0x0C6F),
    (0x0C80, 0x0C83),
    (0x0C85, 0x0C8C),
    (0x0C8E, 0x0C90),
    (0x0C92, 0x0CA8),
    (0x0CAA, 0x0CB3),
    (0x0CB5, 0x0CB9),
    (0x0CBC, 0x0CC4),
    (0x0CC6, 0x0CC8),
    (0x0CCA, 0x0CCD),
    (0x0CD5, 0x0CD6),
    (0x0CDD, 0x0CDE),
    (0x0CE0, 0x0CE3),
    (0x0CE6, 0x0CEF),
    (0x0CF1, 0x0CF3),
    (0x0D00, 0x0D0C),
    (0x0D0E, 0x0D10),
    (0x0D12, 0x0D44),
    (0x0D46, 0x0D48),
    (0x0D4A, 0x0D4E),
    (0x0D54, 0x0D57),
    (0x0D5F, 0x0D63),
    (0x0D66, 0x0D6F),
    (0x0D7A, 0x0D7F),
    (0x0D81, 0x0D83),
    (0x0D85, 0x0D96),
    (0x0D9A, 0x0DB1),
    (0x0DB3, 0x0DBB),
    (0x0DBD, 0x0DBD),
    (0x0DC0, 0x0DC6),
    (0x0DCA, 0x0DCA),
    (0x0DCF, 0x0DD4),
    (0x0DD6, 0x0DD6),
    (0x0DD8, 0x0DDF),
    (0x0DE6, 0x0DEF),
    (0x0DF2, 0x0DF3),
    (0x0E01, 0x0E3A),
    (0x0E40, 0x0E4E),
    (0x0E50, 0x0E59),
    (0x0E81, 0x0E82),
    (0x0E84, 0x0E84),
    (0x0E86, 0x0E8A),
    (0x0E8C, 0x0EA3),
    (0x0EA5, 0x0EA5),
    (0x0EA7, 0x0EBD),
    (0x0EC0, 0x0EC4),
    (0x0EC6, 0x0EC6),
    (0x0EC8, 0x0ECE),
    (0x0ED0, 0x0ED9),
    (0x0EDC, 0x0EDF),
    (0x0F00, 0x0F00),
    (0x0F18, 0x0F19),
    (0x0F20, 0x0F29),
    (0x0F35, 0x0F35),
    (0x0F37, 0x0F37),
    (0x0F39, 0x0F39),
    (0x0F3E, 0x0F47),
    (0x0F49, 0x0F6C),
    (0x0F71, 0x0F84),
    (0x0F86, 0x0F97),
    (0x0F99, 0x0FBC),
    (0x0FC6, 0x0FC6),
    (0x1000, 0x1049),
    (0x1050, 0x109D),
    (0x10A0, 0x10C5),
    (0x10C7, 0x10C7),
    (0x10CD, 0x10CD),
    (0x10D0, 0x10FA),
    (0x10FC, 0x115E),
    (0x1161, 0x1248),
    (0x124A, 0x124D),
    (0x1250, 0x1256),
    (0x1258, 0x1258),
    (0x125A, 0x125D),
    (0x1260, 0x1288),
    (0x128A, 0x128D),
    (0x1290, 0x12B0),
    (0x12B2, 0x12B5),
    (0x12B8, 0x12BE),
    (0x12C0, 0x12C0),
    (0x12C2, 0x12C5),
    (0x12C8, 0x12D6),
    (0x12D8, 0x1310),
    (0x1312, 0x1315),
    (0x1318, 0x135A),
    (0x135D, 0x135F),
    (0x1369, 0x1371),
    (0x1380, 0x138F),
    (0x13A0, 0x13F5),
    (0x13F8, 0x13FD),
    (0x1401, 0x166C),
    (0x166F, 0x167F),
    (0x1681, 0x169A),
    (0x16A0, 0x16EA),
    (0x16EE, 0x16F8),
    (0x1700, 0x1715),
    (0x171F, 0x1734),
    (0x1740, 0x1753),
    (0x1760, 0x176C),
    (0x176E, 0x1770),
    (0x1772, 0x1773),
    (0x1780, 0x17B3),
    (0x17B6, 0x17D3),
    (0x17D7, 0x17D7),
    (0x17DC, 0x17DD),
    (0x17E0, 0x17E9),
    (0x1810, 0x1819),
    (0x1820, 0x1878),
    (0x1880, 0x18AA),
    (0x18B0, 0x18F5),
    (0x1900, 0x191E),
    (0x1920, 0x192B),
    (0x1930, 0x193B),
    (0x1946, 0x196D),
    (0x1970, 0x1974),
    (0x1980, 0x19AB),
    (0x19B0, 0x19C9),
    (0x19D0, 0x19DA),
    (0x1A00, 0x1A1B),
    (0x1A20, 0x1A5E),
    (0x1A60, 0x1A7C),
    (0x1A7F, 0x1A89),
    (0x1A90, 0x1A99),
    (0x1AA7, 0x1AA7),
    (0x1AB0, 0x1ABD),
    (0x1ABF, 0x1ACE),
    (0x1B00, 0x1B4C),
    (0x1B50, 0x1B59),
    (0x1B6B, 0x1B73),
    (0x1B80, 0x1BF3),
    (0x1C00, 0x1C37),
    (0x1C40, 0x1C49),
    (0x1C4D, 0x1C7D),
    (0x1C80, 0x1C88),
    (0x1C90, 0x1CBA),
    (0x1CBD, 0x1CBF),
    (0x1CD0, 0x1CD2),
    (0x1CD4, 0x1CFA),
    (0x1D00, 0x1F15),
    (0x1F18, 0x1F1D),
    (0x1F20, 0x1F45),
    (0x1F48, 0x1F4D),
    (0x1F50, 0x1F57),
    (0x1F59, 0x1F59),
    (0x1F5B, 0x1F5B),
    (0x1F5D, 0x1F5D),
    (0x1F5F, 0x1F7D),
    (0x1F80, 0x1FB4),
    (0x1FB6, 0x1FBC),
    (0x1FBE, 0x1FBE),
    (0x1FC2, 0x1FC4),
    (0x1FC6, 0x1FCC),
    (0x1FD0, 0x1FD3),
    (0x1FD6, 0x1FDB),
    (0x1FE0, 0x1FEC),
    (0x1FF2, 0x1FF4),
    (0x1FF6, 0x1FFC),
    (0x203F, 0x2040),
    (0x2054, 0x2054),
    (0x2071, 0x2071),
    (0x207F, 0x207F),
    (0x2090, 0x209C),
    (0x20D0, 0x20DC),
    (0x20E1, 0x20E1),
    (0x20E5, 0x20F0),
    (0x2102, 0x2102),
    (0x2107, 0x2107),
    (0x210A, 0x2113),
    (0x2115, 0x2115),
    (0x2118, 0x211D),
    (0x2124, 0x2124),
    (0x2126, 0x2126),
    (0x2128, 0x2128),
    (0x212A, 0x2139),
    (0x213C, 0x213F),
    (0x2145, 0x2149),
    (0x214E, 0x214E),
    (0x2160, 0x2188),
    (0x2C00, 0x2CE4),
    (0x2CEB, 0x2CF3),
    (0x2D00, 0x2D25),
    (0x2D27, 0x2D27),
    (0x2D2D, 0x2D2D),
    (0x2D30, 0x2D67),
    (0x2D6F, 0x2D6F),
    (0x2D7F, 0x2D96),
    (0x2DA0, 0x2DA6),
    (0x2DA8, 0x2DAE),
    (0x2DB0, 0x2DB6),
    (0x2DB8, 0x2DBE),
    (0x2DC0, 0x2DC6),
    (0x2DC8, 0x2DCE),
    (0x2DD0, 0x2DD6),
    (0x2DD8, 0x2DDE),
    (0x2DE0, 0x2DFF),
    (0x3005, 0x3007),
    (0x3021, 0x302F),
    (0x3031, 0x3035),
    (0x3038, 0x303C),
    (0x3041, 0x3096),
    (0x3099, 0x309A),
    (0x309D, 0x309F),
    (0x30A1, 0x30FF),
    (0x3105, 0x312F),
    (0x3131, 0x3163),
    (0x3165, 0x318E),
    (0x31A0, 0x31BF),
    (0x31F0, 0x31FF),
    (0x3400, 0x4DBF),
    (0x4E00, 0xA48C),
    (0xA4D0, 0xA4FD),
    (0xA500, 0xA60C),
    (0xA610, 0xA62B),
    (0xA640, 0xA66F),
    (0xA674, 0xA67D),
    (0xA67F, 0xA6F1),
    (0xA717, 0xA71F),
    (0xA722, 0xA788),
    (0xA78B, 0xA7CA),
    (0xA7D0, 0xA7D1),
    (0xA7D3, 0xA7D3),
    (0xA7D5, 0xA7D9),
    (0xA7F2, 0xA827),
    (0xA82C, 0xA82C),
    (0xA840, 0xA873),
    (0xA880, 0xA8C5),
    (0xA8D0, 0xA8D9),
    (0xA8E0, 0xA8F7),
    (0xA8FB, 0xA8FB),
    (0xA8FD, 0xA92D),
    (0xA930, 0xA953),
    (0xA960, 0xA97C),
    (0xA980, 0xA9C0),
    (0xA9CF, 0xA9D9),
    (0xA9E0, 0xA9FE),
    (0xAA00, 0xAA36),
    (0xAA40, 0xAA4D),
    (0xAA50, 0xAA59),
    (0xAA60, 0xAA76),
    (0xAA7A, 0xAAC2),
    (0xAADB, 0xAADD),
    (0xAAE0, 0xAAEF),
    (0xAAF2, 0xAAF6),
    (0xAB01, 0xAB06),
    (0xAB09, 0xAB0E),
    (0xAB11, 0xAB16),
    (0xAB20, 0xAB26),
    (0xAB28, 0xAB2E),
    (0xAB30, 0xAB5A),
    (0xAB5C, 0xAB69),
    (0xAB70, 0xABEA),
    (0xABEC, 0xABED),
    (0xABF0, 0xABF9),
    (0xAC00, 0xD7A3),
    (0xD7B0, 0xD7C6),
    (0xD7CB, 0xD7FB),
    (0xF900, 0xFA6D),
    (0xFA70, 0xFAD9),
    (0xFB00, 0xFB06),
    (0xFB13, 0xFB17),
    (0xFB1D, 0xFB28),
    (0xFB2A, 0xFB36),
    (0xFB38, 0xFB3C),
    (0xFB3E, 0xFB3E),
    (0xFB40, 0xFB41),
    (0xFB43, 0xFB44),
    (0xFB46, 0xFBB1),
    (0xFBD3, 0xFC5D),
    (0xFC64, 0xFD3D),
    (0xFD50, 0xFD8F),
    (0xFD92, 0xFDC7),
    (0xFDF0, 0xFDF9),
    (0xFE20, 0xFE2F),
    (0xFE33, 0xFE34),
    (0xFE4D, 0xFE4F),
    (0xFE71, 0xFE71),
    (0xFE73, 0xFE73),
    (0xFE77, 0xFE77),
    (0xFE79, 0xFE79),
    (0xFE7B, 0xFE7B),
    (0xFE7D, 0xFE7D),
    (0xFE7F, 0xFEFC),
    (0xFF10, 0xFF19),
    (0xFF21, 0xFF3A),
    (0xFF3F, 0xFF3F),
    (0xFF41, 0xFF5A),
    (0xFF65, 0xFF9F),
    (0xFFA1, 0xFFBE),
    (0xFFC2, 0xFFC7),
    (0xFFCA, 0xFFCF),
    (0xFFD2, 0xFFD7),
    (0xFFDA, 0xFFDC),
    (0x10000, 0x1000B),
    (0x1000D, 0x10026),
    (0x10028, 0x1003A),
    (0x1003C, 0x1003D),
    (0x1003F, 0x1004D),
    (0x10050, 0x1005D),
    (0x10080, 0x100FA),
    (0x10140, 0x10174),
    (0x101FD, 0x101FD),
    (0x10280, 0x1029C),
    (0x102A0, 0x102D0),
    (0x102E0, 0x102E0),
    (0x10300, 0x1031F),
    (0x1032D, 0x1034A),
    (0x10350, 0x1037A),
    (0x10380, 0x1039D),
    (0x103A0, 0x103C3),
    (0x103C8, 0x103CF),
    (0x103D1, 0x103D5),
    (0x10400, 0x1049D),
    (0x104A0, 0x104A9),
    (0x104B0, 0x104D3),
    (0x104D8, 0x104FB),
    (0x10500, 0x10527),
    (0x10530, 0x10563),
    (0x10570, 0x1057A),
    (0x1057C, 0x1058A),
    (0x1058C, 0x10592),
    (0x10594, 0x10595),
    (0x10597, 0x105A1),
    (0x105A3, 0x105B1),
    (0x105B3, 0x105B9),
    (0x105BB, 0x105BC),
    (0x10600, 0x10736),
    (0x10740, 0x10755),
    (0x10760, 0x10767),
    (0x10780, 0x10785),
    (0x10787, 0x107B0),
    (0x107B2, 0x107BA),
    (0x10800, 0x10805),
    (0x10808, 0x10808),
    (0x1080A, 0x10835),
    (0x10837, 0x10838),
    (0x1083C, 0x1083C),
    (0x1083F, 0x10855),
    (0x10860, 0x10876),
    (0x10880, 0x1089E),
    (0x108E0, 0x108F2),
    (0x108F4, 0x108F5),
    (0x10900, 0x10915),
    (0x10920, 0x10939),
    (0x10980, 0x109B7),
    (0x109BE, 0x109BF),
    (0x10A00, 0x10A03),
    (0x10A05, 0x10A06),
    (0x10A0C, 0x10A13),
    (0x10A15, 0x10A17),
    (0x10A19, 0x10A35),
    (0x10A38, 0x10A3A),
    (0x10A3F, 0x10A3F),
    (0x10A60, 0x10A7C),
    (0x10A80, 0x10A9C),
    (0x10AC0, 0x10AC7),
    (0x10AC9, 0x10AE6),
    (0x10B00, 0x10B35),
    (0x10B40, 0x10B55),
    (0x10B60, 0x10B72),
    (0x10B80, 0x10B91),
    (0x10C00, 0x10C48),
    (0x10C80, 0x10CB2),
    (0x10CC0, 0x10CF2),
    (0x10D00, 0x10D27),
    (0x10D30, 0x10D39),
    (0x10E80, 0x10EA9),
    (0x10EAB, 0x10EAC),
    (0x10EB0, 0x10EB1),
    (0x10EFD, 0x10F1C),
    (0x10F27, 0x10F27),
    (0x10F30, 0x10F50),
    (0x10F70, 0x10F85),
    (0x10FB0, 0x10FC4),
    (0x10FE0, 0x10FF6),
    (0x11000, 0x11046),
    (0x11066, 0x11075),
    (0x1107F, 0x110BA),
    (0x110C2, 0x110C2),
    (0x110D0, 0x110E8),
    (0x110F0, 0x110F9),
    (0x11100, 0x11134),
    (0x11136, 0x1113F),
    (0x11144, 0x11147),
    (0x11150, 0x11173),
    (0x11176, 0x11176),
    (0x11180, 0x111C4),
    (0x111C9, 0x111CC),
    (0x111CE, 0x111DA),
    (0x111DC, 0x111DC),
    (0x11200, 0x11211),
    (0x11213, 0x11237),
    (0x1123E, 0x11241),
    (0x11280, 0x11286),
    (0x11288, 0x11288),
    (0x1128A, 0x1128D),
    (0x1128F, 0x1129D),
    (0x1129F, 0x112A8),
    (0x112B0, 0x112EA),
    (0x112F0, 0x112F9),
    (0x11300, 0x11303),
    (0x11305, 0x1130C),
    (0x1130F, 0x11310),
    (0x11313, 0x11328),
    (0x1132A, 0x11330),
    (0x11332, 0x11333),
    (0x11335, 0x11339),
    (0x1133B, 0x11344),
    (0x11347, 0x11348),
    (0x1134B, 0x1134D),
    (0x11350, 0x11350),
    (0x11357, 0x11357),
    (0x1135D, 0x11363),
    (0x11366, 0x1136C),
    (0x11370, 0x11374),
    (0x11400, 0x1144A),
    (0x11450, 0x11459),
    (0x1145E, 0x11461),
    (0x11480, 0x114C5),
    (0x114C7, 0x114C7),
    (0x114D0, 0x114D9),
    (0x11580, 0x115B5),
    (0x115B8, 0x115C0),
    (0x115D8, 0x115DD),
    (0x11600, 0x11640),
    (0x11644, 0x11644),
    (0x11650, 0x11659),
    (0x11680, 0x116B8),
    (0x116C0, 0x116C9),
    (0x11700, 0x1171A),
    (0x1171D, 0x1172B),
    (0x11730, 0x11739),
    (0x11740, 0x11746),
    (0x11800, 0x1183A),
    (0x118A0, 0x118E9),
    (0x118FF, 0x11906),
    (0x11909, 0x11909),
    (0x1190C, 0x11913),
    (0x11915, 0x11916),
    (0x11918, 0x11935),
    (0x11937, 0x11938),
    (0x1193B, 0x11943),
    (0x11950, 0x11959),
    (0x119A0, 0x119A7),
    (0x119AA, 0x119D7),
    (0x119DA, 0x119E1),
    (0x119E3, 0x119E4),
    (0x11A00, 0x11A3E),
    (0x11A47, 0x11A47),
    (0x11A50, 0x11A99),
    (0x11A9D, 0x11A9D),
    (0x11AB0, 0x11AF8),
    (0x11C00, 0x11C08),
    (0x11C0A, 0x11C36),
    (0x11C38, 0x11C40),
    (0x11C50, 0x11C59),
    (0x11C72, 0x11C8F),
    (0x11C92, 0x11CA7),
    (0x11CA9, 0x11CB6),
    (0x11D00, 0x11D06),
    (0x11D08, 0x11D09),
    (0x11D0B, 0x11D36),
    (0x11D3A, 0x11D3A),
    (0x11D3C, 0x11D3D),
    (0x11D3F, 0x11D47),
    (0x11D50, 0x11D59),
    (0x11D60, 0x11D65),
    (0x11D67, 0x11D68),
    (0x11D6A, 0x11D8E),
    (0x11D90, 0x11D91),
    (0x11D93, 0x11D98),
    (0x11DA0, 0x11DA9),
    (0x11EE0, 0x11EF6),
    (0x11F00, 0x11F10),
    (0x11F12, 0x11F3A),
    (0x11F3E, 0x11F42),
    (0x11F50, 0x11F59),
    (0x11FB0, 0x11FB0),
    (0x12000, 0x12399),
    (0x12400, 0x1246E),
    (0x12480, 0x12543),
    (0x12F90, 0x12FF0),
    (0x13000, 0x1342F),
    (0x13440, 0x13455),
    (0x14400, 0x14646),
    (0x16800, 0x16A38),
    (0x16A40, 0x16A5E),
    (0x16A60, 0x16A69),
    (0x16A70, 0x16ABE),
    (0x16AC0, 0x16AC9),
    (0x16AD0, 0x16AED),
    (0x16AF0, 0x16AF4),
    (0x16B00, 0x16B36),
    (0x16B40, 0x16B43),
    (0x16B50, 0x16B59),
    (0x16B63, 0x16B77),
    (0x16B7D, 0x16B8F),
    (0x16E40, 0x16E7F),
    (0x16F00, 0x16F4A),
    (0x16F4F, 0x16F87),
    (0x16F8F, 0x16F9F),
    (0x16FE0, 0x16FE1),
    (0x16FE3, 0x16FE4),
    (0x16FF0, 0x16FF1),
    (0x17000, 0x187F7),
    (0x18800, 0x18CD5),
    (0x18D00, 0x18D08),
    (0x1AFF0, 0x1AFF3),
    (0x1AFF5, 0x1AFFB),
    (0x1AFFD, 0x1AFFE),
    (0x1B000, 0x1B122),
    (0x1B132, 0x1B132),
    (0x1B150, 0x1B152),
    (0x1B155, 0x1B155),
    (0x1B164, 0x1B167),
    (0x1B170, 0x1B2FB),
    (0x1BC00, 0x1BC6A),
    (0x1BC70, 0x1BC7C),
    (0x1BC80, 0x1BC88),
    (0x1BC90, 0x1BC99),
    (0x1BC9D, 0x1BC9E),
    (0x1CF00, 0x1CF2D),
    (0x1CF30, 0x1CF46),
    (0x1D165, 0x1D169),
    (0x1D16D, 0x1D172),
    (0x1D17B, 0x1D182),
    (0x1D185, 0x1D18B),
    (0x1D1AA, 0x1D1AD),
    (0x1D242, 0x1D244),
    (0x1D400, 0x1D454),
    (0x1D456, 0x1D49C),
    (0x1D49E, 0x1D49F),
    (0x1D4A2, 0x1D4A2),
    (0x1D4A5, 0x1D4A6),
    (0x1D4A9, 0x1D4AC),
    (0x1D4AE, 0x1D4B9),
    (0x1D4BB, 0x1D4BB),
    (0x1D4BD, 0x1D4C3),
    (0x1D4C5, 0x1D505),
    (0x1D507, 0x1D50A),
    (0x1D50D, 0x1D514),
    (0x1D516, 0x1D51C),
    (0x1D51E, 0x1D539),
    (0x1D53B, 0x1D53E),
    (0x1D540, 0x1D544),
    (0x1D546, 0x1D546),
    (0x1D54A, 0x1D550),
    (0x1D552, 0x1D6A5),
    (0x1D6A8, 0x1D6C0),
    (0x1D6C2, 0x1D6DA),
    (0x1D6DC, 0x1D6FA),
    (0x1D6FC, 0x1D714),
    (0x1D716, 0x1D734),
    (0x1D736, 0x1D74E),
    (0x1D750, 0x1D76E),
    (0x1D770, 0x1D788),
    (0x1D78A, 0x1D7A8),
    (0x1D7AA, 0x1D7C2),
    (0x1D7C4, 0x1D7CB),
    (0x1D7CE, 0x1D7FF),
    (0x1DA00, 0x1DA36),
    (0x1DA3B, 0x1DA6C),
    (0x1DA75, 0x1DA75),
    (0x1DA84, 0x1DA84),
    (0x1DA9B, 0x1DA9F),
    (0x1DAA1, 0x1DAAF),
    (0x1DF00, 0x1DF1E),
    (0x1DF25, 0x1DF2A),
    (0x1E000, 0x1E006),
    (0x1E008, 0x1E018),
    (0x1E01B, 0x1E021),
    (0x1E023, 0x1E024),
    (0x1E026, 0x1E02A),
    (0x1E030, 0x1E06D),
    (0x1E08F, 0x1E08F),
    (0x1E100, 0x1E12C),
    (0x1E130, 0x1E13D),
    (0x1E140, 0x1E149),
    (0x1E14E, 0x1E14E),
    (0x1E290, 0x1E2AE),
    (0x1E2C0, 0x1E2F9),
    (0x1E4D0, 0x1E4F9),
    (0x1E7E0, 0x1E7E6),
    (0x1E7E8, 0x1E7EB),
    (0x1E7ED, 0x1E7EE),
    (0x1E7F0, 0x1E7FE),
    (0x1E800, 0x1E8C4),
    (0x1E8D0, 0x1E8D6),
    (0x1E900, 0x1E94B),
    (0x1E950, 0x1E959),
    (0x1EE00, 0x1EE03),
    (0x1EE05, 0x1EE1F),
    (0x1EE21, 0x1EE22),
    (0x1EE24, 0x1EE24),
    (0x1EE27, 0x1EE27),
    (0x1EE29, 0x1EE32),
    (0x1EE34, 0x1EE37),
    (0x1EE39, 0x1EE39),
    (0x1EE3B, 0x1EE3B),
    (0x1EE42, 0x1EE42),
    (0x1EE47, 0x1EE47),
    (0x1EE49, 0x1EE49),
    (0x1EE4B, 0x1EE4B),
    (0x1EE4D, 0x1EE4F),
    (0x1EE51, 0x1EE52),
    (0x1EE54, 0x1EE54),
    (0x1EE57, 0x1EE57),
    (0x1EE59, 0x1EE59),
    (0x1EE5B, 0x1EE5B),
    (0x1EE5D, 0x1EE5D),
    (0x1EE5F, 0x1EE5F),
    (0x1EE61, 0x1EE62),
    (0x1EE64, 0x1EE64),
    (0x1EE67, 0x1EE6A),
    (0x1EE6C, 0x1EE72),
    (0x1EE74, 0x1EE77),
    (0x1EE79, 0x1EE7C),
    (0x1EE7E, 0x1EE7E),
    (0x1EE80, 0x1EE89),
    (0x1EE8B, 0x1EE9B),
    (0x1EEA1, 0x1EEA3),
    (0x1EEA5, 0x1EEA9),
    (0x1EEAB, 0x1EEBB),
    (0x1FBF0, 0x1FBF9),
    (0x20000, 0x2A6DF),
    (0x2A700, 0x2B739),
    (0x2B740, 0x2B81D),
    (0x2B820, 0x2CEA1),
    (0x2CEB0, 0x2EBE0),
    (0x2EBF0, 0x2EE5D),
    (0x2F800, 0x2FA1D),
    (0x30000, 0x3134A),
    (0x31350, 0x323AF),
];

/// Membership test for the frozen Unicode 15.1 snapshot of
/// `XID_Continue \ Default_Ignorable_Code_Point` (see SPEC §"What counts
/// as a bare key" — UAX #31 §2). ASCII is handled by callers; this returns
/// `false` for `cp < 0x80` to keep the binary search out of the hot path.
fn is_xid_continue(cp: u32) -> bool {
    if cp < 0x80 {
        return false;
    }
    XID_CONTINUE_RANGES
        .binary_search_by(|&(lo, hi)| {
            if cp < lo {
                std::cmp::Ordering::Greater
            } else if cp > hi {
                std::cmp::Ordering::Less
            } else {
                std::cmp::Ordering::Equal
            }
        })
        .is_ok()
}

pub(crate) fn is_bare_key_char(c: char) -> bool {
    if is_reserved_emoji_codepoint(c as u32) {
        return false;
    }
    c == '_'
        || c == '-'
        || c.is_ascii_alphanumeric()
        || (!c.is_ascii() && is_xid_continue(c as u32))
}

// Frozen Unicode 15.1 snapshot of `Extended_Pictographic=Yes`, sourced
// from emoji-data.txt. SPEC §Lexical → "Reserved emoji characters".
// 78 inclusive ranges, sorted by start; binary searched in
// `is_extended_pictographic`.
static EXTENDED_PICTOGRAPHIC_RANGES: &[(u32, u32)] = &[
    (0x00A9, 0x00A9), (0x00AE, 0x00AE), (0x203C, 0x203C), (0x2049, 0x2049),
    (0x2122, 0x2122), (0x2139, 0x2139), (0x2194, 0x2199), (0x21A9, 0x21AA),
    (0x231A, 0x231B), (0x2328, 0x2328), (0x2388, 0x2388), (0x23CF, 0x23CF),
    (0x23E9, 0x23F3), (0x23F8, 0x23FA), (0x24C2, 0x24C2), (0x25AA, 0x25AB),
    (0x25B6, 0x25B6), (0x25C0, 0x25C0), (0x25FB, 0x25FE), (0x2600, 0x2605),
    (0x2607, 0x2612), (0x2614, 0x2685), (0x2690, 0x2705), (0x2708, 0x2712),
    (0x2714, 0x2714), (0x2716, 0x2716), (0x271D, 0x271D), (0x2721, 0x2721),
    (0x2728, 0x2728), (0x2733, 0x2734), (0x2744, 0x2744), (0x2747, 0x2747),
    (0x274C, 0x274C), (0x274E, 0x274E), (0x2753, 0x2755), (0x2757, 0x2757),
    (0x2763, 0x2767), (0x2795, 0x2797), (0x27A1, 0x27A1), (0x27B0, 0x27B0),
    (0x27BF, 0x27BF), (0x2934, 0x2935), (0x2B05, 0x2B07), (0x2B1B, 0x2B1C),
    (0x2B50, 0x2B50), (0x2B55, 0x2B55), (0x3030, 0x3030), (0x303D, 0x303D),
    (0x3297, 0x3297), (0x3299, 0x3299), (0x1F000, 0x1F0FF), (0x1F10D, 0x1F10F),
    (0x1F12F, 0x1F12F), (0x1F16C, 0x1F171), (0x1F17E, 0x1F17F), (0x1F18E, 0x1F18E),
    (0x1F191, 0x1F19A), (0x1F1AD, 0x1F1E5), (0x1F201, 0x1F20F), (0x1F21A, 0x1F21A),
    (0x1F22F, 0x1F22F), (0x1F232, 0x1F23A), (0x1F23C, 0x1F23F), (0x1F249, 0x1F3FA),
    (0x1F400, 0x1F53D), (0x1F546, 0x1F64F), (0x1F680, 0x1F6FF), (0x1F774, 0x1F77F),
    (0x1F7D5, 0x1F7FF), (0x1F80C, 0x1F80F), (0x1F848, 0x1F84F), (0x1F85A, 0x1F85F),
    (0x1F888, 0x1F88F), (0x1F8AE, 0x1F8FF), (0x1F90C, 0x1F93A), (0x1F93C, 0x1F945),
    (0x1F947, 0x1FAFF), (0x1FC00, 0x1FFFD),
];

fn is_extended_pictographic(cp: u32) -> bool {
    if cp < 0xA9 {
        return false;
    }
    EXTENDED_PICTOGRAPHIC_RANGES
        .binary_search_by(|&(lo, hi)| {
            if cp < lo { std::cmp::Ordering::Greater }
            else if cp > hi { std::cmp::Ordering::Less }
            else { std::cmp::Ordering::Equal }
        })
        .is_ok()
}

/// True if `cp` is a member of the Reserved Emoji Set defined in SPEC.md
/// §Lexical → "Reserved emoji characters". The set is the union of:
///   - `Extended_Pictographic=Yes` (UTS #51, frozen UCD 15.1)
///   - Regional Indicators (U+1F1E6..U+1F1FF)
///   - Emoji Modifiers (U+1F3FB..U+1F3FF)
///   - Combining Enclosing Keycap (U+20E3)
///
/// All four sub-ranges are frozen at Unicode 15.1.0 and shipped with this
/// port (no host-runtime delegation).
pub(crate) fn is_reserved_emoji_codepoint(cp: u32) -> bool {
    if (0x1F1E6..=0x1F1FF).contains(&cp) { return true; }   // regional indicator
    if (0x1F3FB..=0x1F3FF).contains(&cp) { return true; }   // skin-tone modifier
    if cp == 0x20E3 { return true; }                         // keycap combiner
    is_extended_pictographic(cp)
}

#[inline]
pub(crate) fn is_regional_indicator(cp: u32) -> bool {
    (0x1F1E6..=0x1F1FF).contains(&cp)
}

#[inline]
pub(crate) fn is_emoji_modifier(cp: u32) -> bool {
    (0x1F3FB..=0x1F3FF).contains(&cp)
}

/// Read one extended grapheme cluster of *reserved-emoji* shape starting
/// at byte offset `start` in `s`. Returns `Some(end_byte)` (exclusive end)
/// if the cluster begins with a Reserved-Emoji codepoint, else `None`.
///
/// Implements a minimal subset of UAX #29 grapheme-cluster boundaries
/// sufficient for emoji clusters: GB12/GB13 (regional-indicator pair),
/// GB9/GB9a (Extend, ZWJ, SpacingMark — restricted to emoji-relevant
/// extenders), and GB11 (E_P × Extend* ZWJ × E_P).
///
/// Frozen behavior: matches the UAX #29 algorithm against frozen UCD
/// 15.1 property tables. The algorithm itself is stable across Unicode
/// versions; only the property tables it consults need pinning.
pub(crate) fn read_reserved_emoji_atom(s: &str, start: usize) -> Option<usize> {
    let bytes = s.as_bytes();
    if start >= bytes.len() {
        return None;
    }
    let mut chars = s[start..].char_indices();
    let (_, c0) = chars.next()?;
    let cp0 = c0 as u32;
    if !is_reserved_emoji_codepoint(cp0) {
        return None;
    }
    let mut end = start + c0.len_utf8();

    // Regional-indicator pair: per UAX #29 GB12/GB13, RI pairs cluster.
    if is_regional_indicator(cp0) {
        if let Some((_, c1)) = chars.next() {
            if is_regional_indicator(c1 as u32) {
                end += c1.len_utf8();
            }
        }
        return Some(end);
    }

    // GB9/GB9a/GB11 loop: extend cluster across modifiers, VS-16, keycap
    // combiner, and ZWJ-joined Extended_Pictographic continuations.
    loop {
        let rest = &s[end..];
        let mut it = rest.chars();
        let Some(c) = it.next() else { break };
        let cp = c as u32;
        if is_emoji_modifier(cp) || cp == 0xFE0F || cp == 0x20E3 {
            // GB9/GB9a — Extend or SpacingMark glued to base.
            end += c.len_utf8();
            continue;
        }
        if cp == 0x200D {
            // GB11 — ZWJ × Extended_Pictographic continues the cluster.
            let after_zwj = end + c.len_utf8();
            let after = &s[after_zwj..];
            if let Some(nc) = after.chars().next() {
                if is_extended_pictographic(nc as u32) {
                    end = after_zwj + nc.len_utf8();
                    continue;
                }
            }
            // ZWJ not followed by E_P: cluster ends before the ZWJ.
            break;
        }
        break;
    }
    Some(end)
}

fn is_label_start(c: char) -> bool {
    c == '_' || c.is_ascii_alphabetic()
}

fn is_label_cont(c: char) -> bool {
    c == '_' || c.is_ascii_alphanumeric()
}

fn looks_like_date_prefix(s: &str) -> bool {
    let b = s.as_bytes();
    b.len() >= 10
        && b[0].is_ascii_digit()
        && b[1].is_ascii_digit()
        && b[2].is_ascii_digit()
        && b[3].is_ascii_digit()
        && b[4] == b'-'
        && b[5].is_ascii_digit()
        && b[6].is_ascii_digit()
        && b[7] == b'-'
        && b[8].is_ascii_digit()
        && b[9].is_ascii_digit()
}

fn looks_like_time_prefix(s: &str) -> bool {
    let b = s.as_bytes();
    b.len() >= 8
        && b[0].is_ascii_digit()
        && b[1].is_ascii_digit()
        && b[2] == b':'
        && b[3].is_ascii_digit()
        && b[4].is_ascii_digit()
        && b[5] == b':'
        && b[6].is_ascii_digit()
        && b[7].is_ascii_digit()
}

// ---------- parser ----------

struct Parser<'a> {
    src: &'a str,
    pos: usize,
    line: usize,
    line_start: usize,

    // ---- comment-attachment state ----
    /// All comments that have been finalized and attached so far, in
    /// source order.
    comments: Vec<AttachedComment>,
    /// Comments collected from comment-only lines that have not yet been
    /// attached. They become `Leading` on the next sibling node, or
    /// `Floating` on the enclosing container if a blank line appears
    /// before any sibling does, or if the block closes first.
    pending_leading: Vec<Comment>,
    /// The breadcrumb path to the *currently-being-parsed* container.
    /// Block parsers push the relevant segment (Key or Index) before
    /// recursing into a child node and pop after, so that whichever node
    /// is "current" at the time a comment is captured/flushed has the
    /// right path to attach to.
    path: Vec<BreadcrumbSegment>,
    /// Original-literal records captured during parsing. Sparse: only
    /// non-default forms get entries (e.g. an unsigned decimal integer
    /// without underscores has no entry; `0xFF` does). Consulted by
    /// `encode` for round-trip emission.
    original_forms: Vec<(Vec<BreadcrumbSegment>, OriginalLiteral)>,
    /// When false, integer/string lexeme recording is suppressed. Used
    /// while parsing heredoc-modifier args (which are values used at
    /// parse time but otherwise discarded — they shouldn't appear in
    /// the host node's `original_forms` slot).
    record_forms: bool,
    /// Lite mode short-circuit: when true, skip all comment-AST and
    /// `original_forms` bookkeeping. The grammar still runs in full,
    /// errors are unchanged; only the round-trip metadata is dropped.
    /// SPEC §Parsing modes — full and lite.
    lite: bool,
    /// Unordered mode: when true, body tables are produced as
    /// `Value::UnorderedTable` (HashMap-backed) instead of
    /// `Value::Table` (IndexMap-backed). Iteration order is arbitrary.
    /// Front-matter parsing ignores this flag — meta stays ordered.
    /// See SPEC §"Unordered tables".
    ignore_order: bool,
    /// When true, front-matter `_dms_tier: 1` is accepted rather than
    /// rejected. Set by `decode_document_accepting_tier1`. Default: false.
    accept_tier1: bool,
    /// The tier value observed in front matter (`_dms_tier`). Zero when
    /// no `_dms_tier` key is present or when tier is 0. Set only when
    /// `accept_tier1` is true and a valid tier value is seen.
    observed_tier: u32,
    /// Tier-1 only: decorator calls captured at line-start positions
    /// before the next sibling lands. Drained by
    /// `flush_pending_as_leading_on_current` / `flush_pending_as_floating`
    /// alongside `pending_leading` comments. Source-order preserved.
    pending_leading_decorators: Vec<tier1::DecoratorCall>,
    /// Tier-1 only: flat accumulator of (path, position, call) tuples.
    /// Grouped into `DecoratorEntry` records by `tier1::decode_t1` after
    /// parsing completes. Empty in tier-0 mode.
    decorations_raw: Vec<(Vec<BreadcrumbSegment>, tier1::DecorationPosition, tier1::DecoratorCall)>,
    /// Tier-1 only: paths where the source used decoration-only form
    /// (inner decoration with no base_value). Hoist pass substitutes
    /// the family's empty_default. TIER1.md §"Decoration-only".
    decoration_only_paths: Vec<Vec<BreadcrumbSegment>>,
}

impl<'a> Parser<'a> {
    #[cfg(test)]
    fn new(src: &'a str) -> Self {
        Self::new_with_mode(src, ParseMode::Full)
    }

    fn new_with_mode(src: &'a str, mode: ParseMode) -> Self {
        let src = src.strip_prefix('\u{feff}').unwrap_or(src);
        Self {
            src,
            pos: 0,
            line: 1,
            line_start: 0,
            comments: Vec::new(),
            pending_leading: Vec::new(),
            path: Vec::new(),
            original_forms: Vec::new(),
            record_forms: true,
            lite: matches!(mode, ParseMode::Lite),
            ignore_order: false,
            accept_tier1: false,
            observed_tier: 0,
            pending_leading_decorators: Vec::new(),
            decorations_raw: Vec::new(),
            decoration_only_paths: Vec::new(),
        }
    }

    /// True iff the parser has observed `_dms_tier: 1` in front matter.
    /// Tier-1 lex/parse paths gate on this.
    fn is_t1_active(&self) -> bool {
        self.observed_tier >= 1
    }

    /// Append an `OriginalLiteral` record at the current path. Skipped
    /// when `record_forms` is false (e.g. inside heredoc modifier args),
    /// when the parser is in lite mode (no round-trip metadata kept),
    /// or when the form is the implicit default.
    fn record_form(&mut self, lit: OriginalLiteral) {
        if self.lite || !self.record_forms {
            return;
        }
        self.original_forms.push((self.path.clone(), lit));
    }

    // ----- position / chars -----

    fn col(&self) -> usize {
        // 1-based column in bytes
        self.pos - self.line_start + 1
    }

    fn err(&self, msg: impl Into<String>) -> DecodeError {
        DecodeError { line: self.line, column: self.col(), message: msg.into() }
    }

    fn err_at(&self, line: usize, line_start: usize, pos: usize, msg: impl Into<String>) -> DecodeError {
        DecodeError { line, column: pos.saturating_sub(line_start) + 1, message: msg.into() }
    }

    fn peek(&self) -> Option<char> {
        self.src[self.pos..].chars().next()
    }

    fn rest(&self) -> &str {
        &self.src[self.pos..]
    }

    fn bump(&mut self) -> Option<char> {
        let c = self.peek()?;
        self.pos += c.len_utf8();
        Some(c)
    }

    fn eof(&self) -> bool {
        self.pos >= self.src.len()
    }

    fn advance_line(&mut self) {
        self.line += 1;
        self.line_start = self.pos;
    }

    // ----- whitespace and line terminators -----

    fn skip_inline_ws(&mut self) {
        while matches!(self.peek(), Some(' ') | Some('\t')) {
            self.bump();
        }
    }

    /// Consume a line terminator (LF or CRLF). Returns true if consumed.
    /// Bare CR is NOT a line terminator and is left for the caller to error on.
    fn consume_eol(&mut self) -> bool {
        if self.peek() == Some('\n') {
            self.bump();
            self.advance_line();
            true
        } else if self.rest().starts_with("\r\n") {
            self.pos += 2;
            self.advance_line();
            true
        } else {
            false
        }
    }

    /// Skip blank lines, full-line comments (line + block) at the current
    /// position. Stops at the first content character at column 1+ that is
    /// not trivia.
    ///
    /// Captures full-line comments into `self.pending_leading` (they
    /// become `Leading` on the next sibling, or `Floating` on the
    /// enclosing container if a blank line intervenes). The blank-line
    /// rule: any blank line encountered in this loop while there are
    /// pending comments flushes them as `Floating` on the current path.
    fn skip_trivia(&mut self) -> Result<(), DecodeError> {
        loop {
            // skip indent on a line that is entirely trivia: leading ws is
            // okay only if the line is blank or comment.
            let line_start_pos = self.pos;
            self.skip_inline_ws();
            match self.peek() {
                Some('\n') | Some('\r') => {
                    if self.peek() == Some('\r') && !self.rest().starts_with("\r\n") {
                        return Err(self.err("bare CR is not a valid line terminator"));
                    }
                    // Blank line. If we have pending leading comments,
                    // they're separated from any future sibling — flush
                    // them as Floating on the enclosing container.
                    self.flush_pending_as_floating();
                    self.consume_eol();
                }
                Some('#') => {
                    if self.rest().starts_with("###") {
                        let raw = self.read_hash_block_comment()?;
                        if !self.lite {
                            self.pending_leading.push(Comment {
                                content: raw,
                                kind: CommentKind::Block,
                            });
                        }
                    } else {
                        let raw = self.read_line_comment_to_eol();
                        self.consume_eol();
                        if !self.lite {
                            self.pending_leading.push(Comment {
                                content: raw,
                                kind: CommentKind::Line,
                            });
                        }
                    }
                }
                Some('/') if self.rest().starts_with("//") => {
                    let raw = self.read_line_comment_to_eol();
                    self.consume_eol();
                    if !self.lite {
                        self.pending_leading.push(Comment {
                            content: raw,
                            kind: CommentKind::Line,
                        });
                    }
                }
                Some('/') if self.rest().starts_with("/*") => {
                    let raw = self.read_c_block_comment()?;
                    if !self.lite {
                        self.pending_leading.push(Comment {
                            content: raw,
                            kind: CommentKind::Block,
                        });
                    }
                    // after a c-style block, may be more on this line; loop
                }
                Some(c) if self.is_t1_active() && tier1::is_sigil_atom_start(c) => {
                    // Tier-1: line-start decorator call. Per TIER1.md
                    // §"Decoration sites" `leading_block = ( decoration NEWLINE )+`,
                    // each leading decoration is on its own line.
                    let (call, end) = tier1::parse_decorator_call(self.src, self.pos)?;
                    // Walk the consumed range byte-by-byte, bumping line/line_start on '\n'.
                    let mut walk = self.pos;
                    while walk < end {
                        if self.src.as_bytes()[walk] == b'\n' {
                            self.line += 1;
                            self.line_start = walk + 1;
                        }
                        walk += 1;
                    }
                    self.pos = end;
                    // Decorator call must be on its own line: skip trailing ws, then EOL/EOF.
                    self.skip_inline_ws();
                    if !(self.consume_eol() || self.eof()) {
                        return Err(self.err("trailing content after leading decorator (only EOL allowed in this build)"));
                    }
                    self.pending_leading_decorators.push(call);
                    // continue trivia loop
                }
                Some(_) => {
                    // not trivia — rewind to line start (preserve indent for caller)
                    self.pos = line_start_pos;
                    return Ok(());
                }
                None => return Ok(()),
            }
        }
    }

    /// Flush any `pending_leading` comments as `Floating` on the current
    /// path (i.e. attached to the enclosing container). Called when a
    /// blank line appears between pending comments and the next sibling,
    /// and when a block closes with leftover pending comments.
    fn flush_pending_as_floating(&mut self) {
        let had_decorators = !self.pending_leading_decorators.is_empty();
        if !self.pending_leading.is_empty() {
            let drained: Vec<Comment> = self.pending_leading.drain(..).collect();
            for c in drained {
                self.comments.push(AttachedComment {
                    comment: c,
                    position: CommentPosition::Floating,
                    path: self.path.clone(),
                });
            }
        }
        if had_decorators {
            let drained: Vec<tier1::DecoratorCall> =
                self.pending_leading_decorators.drain(..).collect();
            for call in drained {
                self.decorations_raw.push((
                    self.path.clone(),
                    tier1::DecorationPosition::Floating,
                    call,
                ));
            }
        }
    }

    /// Attach all `pending_leading` comments as `Leading` on the path
    /// formed by `self.path` + `last_segment`. Called by sibling-entry
    /// points right after pushing the new sibling's breadcrumb.
    fn flush_pending_as_leading_on_current(&mut self) {
        let had_decorators = !self.pending_leading_decorators.is_empty();
        if !self.pending_leading.is_empty() {
            let drained: Vec<Comment> = self.pending_leading.drain(..).collect();
            for c in drained {
                self.comments.push(AttachedComment {
                    comment: c,
                    position: CommentPosition::Leading,
                    path: self.path.clone(),
                });
            }
        }
        if had_decorators {
            let drained: Vec<tier1::DecoratorCall> =
                self.pending_leading_decorators.drain(..).collect();
            for call in drained {
                self.decorations_raw.push((
                    self.path.clone(),
                    tier1::DecorationPosition::Leading,
                    call,
                ));
            }
        }
    }

    fn read_line_comment_to_eol(&mut self) -> String {
        let start = self.pos;
        while let Some(c) = self.peek() {
            if c == '\n' || c == '\r' {
                break;
            }
            self.bump();
        }
        self.src[start..self.pos].to_string()
    }

    /// `/* ... */` with nesting. Caller has not yet consumed `/*`. Returns
    /// the raw comment text (including delimiters).
    fn read_c_block_comment(&mut self) -> Result<String, DecodeError> {
        let start_line = self.line;
        let start_lstart = self.line_start;
        let start_pos = self.pos;
        // consume opening /*
        self.pos += 2;
        let mut depth = 1usize;
        while depth > 0 {
            match self.peek() {
                None => {
                    return Err(self.err_at(
                        start_line,
                        start_lstart,
                        start_pos,
                        "unterminated /* block comment",
                    ));
                }
                Some('/') if self.rest().starts_with("/*") => {
                    self.pos += 2;
                    depth += 1;
                }
                Some('*') if self.rest().starts_with("*/") => {
                    self.pos += 2;
                    depth -= 1;
                }
                Some('\n') => {
                    self.bump();
                    self.advance_line();
                }
                Some('\r') if self.rest().starts_with("\r\n") => {
                    self.pos += 2;
                    self.advance_line();
                }
                Some(_) => {
                    self.bump();
                }
            }
        }
        Ok(self.src[start_pos..self.pos].to_string())
    }

    /// `### ... ###` or `###LABEL ... LABEL`. Opener and terminator each on
    /// their own line. Caller has not yet consumed `###`. Returns the
    /// raw comment text including delimiters and the terminator line
    /// (but **not** the trailing EOL of the terminator).
    fn read_hash_block_comment(&mut self) -> Result<String, DecodeError> {
        let start_line = self.line;
        let start_lstart = self.line_start;
        let start_pos = self.pos;
        // consume ###
        self.pos += 3;
        // optional label, no whitespace between ### and label
        let label_start = self.pos;
        while let Some(c) = self.peek() {
            if !(c == '_' || c.is_ascii_alphanumeric()) {
                break;
            }
            self.bump();
        }
        let label_str: String = self.src[label_start..self.pos].to_string();
        if !label_str.is_empty() {
            // must start with letter or _
            if !label_str.chars().next().unwrap().is_ascii_alphabetic()
                && !label_str.starts_with('_')
            {
                return Err(self.err_at(
                    start_line,
                    start_lstart,
                    start_pos,
                    "block comment label must start with a letter or underscore",
                ));
            }
        }
        let terminator: String = if label_str.is_empty() {
            "###".to_string()
        } else {
            label_str.clone()
        };
        // require rest of opener line to be only whitespace, then EOL
        self.skip_inline_ws();
        if !(self.consume_eol() || self.eof()) {
            return Err(self.err(
                "block comment opener must be on its own line",
            ));
        }
        // consume body lines until we find a line whose trimmed content
        // equals `terminator`
        loop {
            if self.eof() {
                return Err(self.err_at(
                    start_line,
                    start_lstart,
                    start_pos,
                    "unterminated ### block comment",
                ));
            }
            // capture this line
            let line_begin = self.pos;
            while let Some(c) = self.peek() {
                if c == '\n' || c == '\r' {
                    break;
                }
                self.bump();
            }
            let line_text = &self.src[line_begin..self.pos];
            // The terminator line is part of the captured comment text;
            // capture the comment body BEFORE consuming the EOL so the
            // returned content does not include the terminator's EOL.
            let line_end = self.pos;
            let _ = self.consume_eol();
            if line_text.trim() == terminator {
                return Ok(self.src[start_pos..line_end].to_string());
            }
        }
    }

    // ----- document entry -----

    /// Parse optional front matter block. Leaves the parser positioned at
    /// the start of the body (which may be empty). Returns the user
    /// metadata table (Some) if a block was present, else None. Reserved
    /// `_dms_*` keys are consumed and validated here, not surfaced.
    fn parse_front_matter(&mut self) -> Result<Option<DmsMap<Value>>, DecodeError> {
        // Front matter must be the first *significant* line. Skip
        // leading trivia; if the next non-trivia line is `+++`, it's
        // front matter. Otherwise rewind so the body parser sees the
        // same position it would have seen.
        let save_pos = self.pos;
        let save_line = self.line;
        let save_lstart = self.line_start;
        let save_pending = self.pending_leading.len();
        let save_comments = self.comments.len();
        self.skip_trivia()?;
        // Check for +++ on its own line
        if !self.rest().starts_with("+++") {
            self.pos = save_pos;
            self.line = save_line;
            self.line_start = save_lstart;
            // Speculative skip_trivia may have captured comments — undo
            // so the body parser re-captures them with the correct
            // path/context.
            self.pending_leading.truncate(save_pending);
            self.comments.truncate(save_comments);
            return Ok(None);
        }
        // The char after +++ must be end-of-line (optionally with inline ws).
        // Any other trailing content on the opener line is a parse error
        // (SPEC §Front matter: "each `+++` must appear on its own line,
        // with no trailing content"). We position the parser past `+++`
        // (so the diagnostic points at the offending column) and let
        // the strict EOL check below produce the error.
        let opener_line = self.line;
        let opener_lstart = self.line_start;
        let opener_pos = self.pos;
        // consume `+++`, then trailing whitespace, then EOL
        self.pos += 3;
        self.skip_inline_ws();
        if !(self.consume_eol() || self.eof()) {
            return Err(self.err(
                "front matter opener must be on its own line",
            ));
        }
        // Collect lines into a scratch string until we hit the closer `+++`
        let mut inner = String::new();
        loop {
            if self.eof() {
                return Err(self.err_at(
                    opener_line, opener_lstart, opener_pos,
                    "unterminated front matter: missing closing '+++'",
                ));
            }
            // Read one line (without EOL)
            let line_begin = self.pos;
            while let Some(c) = self.peek() {
                if c == '\n' || c == '\r' { break; }
                self.bump();
            }
            let line_text = &self.src[line_begin..self.pos];
            // Is this line the closing `+++`?
            if line_text.trim() == "+++" {
                let _ = self.consume_eol();
                break;
            }
            // Otherwise, preserve this line in `inner` (including trailing EOL)
            inner.push_str(line_text);
            if self.consume_eol() {
                inner.push('\n');
            }
        }
        // Parse `inner` as a standalone DMS table block at indent 0.
        // Inherit lite mode from the outer parser — front matter
        // shouldn't preserve comments/forms if the outer doesn't.
        let inner_mode = if self.lite { ParseMode::Lite } else { ParseMode::Full };
        let mut sub = Parser::new_with_mode(&inner, inner_mode);
        let table = sub.parse_body_as_table()?;
        // Now process reserved keys
        let mut meta = DmsMap::default();
        for (k, v) in table {
            if k.strip_prefix('_').is_some() {
                match k.as_str() {
                    "_dms_tier" => {
                        let Value::Integer(n) = v else {
                            return Err(self.err_at(
                                opener_line, opener_lstart, opener_pos,
                                "_dms_tier must be a non-negative integer",
                            ));
                        };
                        if n < 0 {
                            return Err(self.err_at(
                                opener_line, opener_lstart, opener_pos,
                                "_dms_tier must be non-negative",
                            ));
                        }
                        if n >= 1 {
                            if self.accept_tier1 {
                                // Tier-1 accepted by the tier-1 entry
                                // point. Record the observed tier and
                                // consume the key silently.
                                self.observed_tier = n as u32;
                            } else {
                                // TIER1.md §"Behavior at the boundary":
                                // tier-0 decoders surface tier-1 input
                                // with an actionable forward-compat
                                // message pointing at decode_t1.
                                return Err(self.err_at(
                                    opener_line, opener_lstart, opener_pos,
                                    format!(
                                        "_dms_tier: {n} found, but this decoder only supports tier 0. Use decode_t1."
                                    ),
                                ));
                            }
                        }
                        // _dms_tier: 0 — accept and discard.
                    }
                    "_dms_imports" => {
                        if self.accept_tier1 {
                            // Pass through to meta so tier1::extract_imports
                            // can read and validate it. TIER1.md §"Front
                            // matter additions" (line 170).
                            meta.insert(k, v);
                        } else {
                            // Tier-0 decoders reject _dms_imports with an
                            // actionable message. TIER1.md line 179-181.
                            return Err(self.err_at(
                                opener_line, opener_lstart, opener_pos,
                                "_dms_imports requires _dms_tier: 1; \
                                 tier-0 documents must not contain _dms_imports",
                            ));
                        }
                    }
                    other => {
                        return Err(self.err_at(
                            opener_line, opener_lstart, opener_pos,
                            format!("unknown reserved key: {other}"),
                        ));
                    }
                }
            } else {
                meta.insert(k, v);
            }
        }
        // Hoist comments from the sub-parser, prefixing each path with
        // `Key("__fm__")` so callers can distinguish front-matter
        // comments from body comments. Comments attached to reserved
        // (parser-consumed) `_dms_*` keys are re-attached as `Floating`
        // on the front-matter table itself — the reserved-key node
        // doesn't appear in the final tree, but the comment was about
        // the document and shouldn't silently vanish.
        for ac in sub.comments {
            let attached_to_reserved = matches!(
                ac.path.first(),
                Some(BreadcrumbSegment::Key(k0)) if k0.starts_with('_')
            );
            if attached_to_reserved {
                self.comments.push(AttachedComment {
                    comment: ac.comment,
                    position: CommentPosition::Floating,
                    path: vec![BreadcrumbSegment::Key("__fm__".to_string())],
                });
                continue;
            }
            let mut new_path = Vec::with_capacity(ac.path.len() + 1);
            new_path.push(BreadcrumbSegment::Key("__fm__".to_string()));
            new_path.extend(ac.path);
            self.comments.push(AttachedComment {
                comment: ac.comment,
                position: ac.position,
                path: new_path,
            });
        }
        // Same hoist for original_forms: `__fm__` prefix, drop entries
        // attached to reserved (consumed) `_dms_*` keys.
        for (path, lit) in sub.original_forms {
            if let Some(BreadcrumbSegment::Key(k0)) = path.first() {
                if k0.starts_with('_') {
                    continue;
                }
            }
            let mut new_path = Vec::with_capacity(path.len() + 1);
            new_path.push(BreadcrumbSegment::Key("__fm__".to_string()));
            new_path.extend(path);
            self.original_forms.push((new_path, lit));
        }
        Ok(Some(meta))
    }

    /// Parse the inner content of a front matter block as a table.
    fn parse_body_as_table(&mut self) -> Result<DmsMap<Value>, DecodeError> {
        self.skip_trivia()?;
        if self.eof() {
            // Empty FM body with comment-only content: flush any
            // pending-leading comments as floating on the (empty)
            // table root, so the outer hoist can re-attach them under
            // the `__fm__` prefix.
            self.flush_pending_as_floating();
            return Ok(DmsMap::default());
        }
        if matches!(self.peek(), Some(' ') | Some('\t')) {
            return Err(self.err("unexpected indentation inside front matter"));
        }
        // SPEC §Lexical: reject reserved decorator sigils at line-start.
        self.reject_reserved_decorator_sigil()?;
        if self.peek() == Some('+') && self.peek_after_plus_is_space_or_eol() {
            return Err(self.err("front matter block cannot have a list root"));
        }
        if !self.line_starts_kvpair() {
            return Err(self.err("front matter block must be a table"));
        }
        let t = self.parse_table_block(0)?;
        self.skip_trivia()?;
        if !self.eof() {
            return Err(self.err("trailing content inside front matter"));
        }
        // Any final pending-leading comments become floating on FM root.
        self.flush_pending_as_floating();
        Ok(t)
    }

    /// Parse a complete document body.
    fn parse_body(&mut self) -> Result<Value, DecodeError> {
        self.skip_trivia()?;
        if self.eof() {
            // Empty / comment-only body: pending comments float on root.
            self.flush_pending_as_floating();
            if self.ignore_order {
                return Ok(Value::UnorderedTable(DmsHashMap::default()));
            }
            return Ok(Value::Table(DmsMap::default()));
        }
        // dispatch on the first significant char at column 1 (no indent allowed at root)
        if matches!(self.peek(), Some(' ') | Some('\t')) {
            return Err(self.err("unexpected indentation at document root"));
        }
        // SPEC §Lexical: reject reserved decorator sigils at line-start.
        self.reject_reserved_decorator_sigil()?;
        // Decide root type
        let result = if self.peek() == Some('+') && self.peek_after_plus_is_space_or_eol() {
            // list root
            let v = self.parse_list_block(0)?;
            self.skip_trivia()?;
            if !self.eof() {
                return Err(self.err("trailing content after list root"));
            }
            Value::List(v)
        } else if self.line_starts_kvpair() {
            let v = if self.ignore_order {
                Value::UnorderedTable(self.parse_table_block_unordered(0)?)
            } else {
                Value::Table(self.parse_table_block(0)?)
            };
            self.skip_trivia()?;
            if !self.eof() {
                return Err(self.err("trailing content after table root"));
            }
            v
        } else {
            // scalar root
            let v = self.parse_inline_value_or_heredoc()?;
            self.consume_after_value(true)?;
            self.skip_trivia()?;
            if !self.eof() {
                return Err(self.err("scalar root cannot be followed by more content"));
            }
            v
        };
        // Any post-body trivia comments float on root.
        self.flush_pending_as_floating();
        Ok(result)
    }

    fn peek_after_plus_is_space_or_eol(&self) -> bool {
        let bytes = self.src.as_bytes();
        let next = bytes.get(self.pos + 1).copied();
        matches!(next, Some(b' ') | Some(b'\t') | Some(b'\n') | Some(b'\r') | None)
    }

    /// SPEC §Lexical: the characters `! @ $ % ^ & * | ~ \`` are reserved as
    /// decorator sigils at line-start position. A body line whose first
    /// non-whitespace character is one of these is a parse error in tier 0.
    /// (Underscore `_` is **not** in this set — it has its own category for
    /// core / built-in decorators like heredoc modifiers `_trim`.)
    ///
    /// Callers position the parser at the first non-whitespace byte of a
    /// body line (i.e. at `line_start + indent`) and invoke this helper
    /// before any other dispatch. Returns `Err` if the current `peek()`
    /// is one of the reserved sigils, `Ok(())` otherwise.
    fn reject_reserved_decorator_sigil(&self) -> Result<(), DecodeError> {
        match self.peek() {
            Some(c @ ('!' | '@' | '$' | '%' | '^' | '&' | '*' | '|' | '~' | '`'
                | '.' | ',' | '>' | '<' | '?' | ';' | '=')) => {
                Err(self.err(format!(
                    "'{c}' is a reserved decorator sigil at line-start; \
                     these characters (! @ $ % ^ & * | ~ ` . , > < ? ; =) cannot begin a \
                     body line in tier 0"
                )))
            }
            Some(c) if is_reserved_emoji_codepoint(c as u32) => {
                Err(self.err(format!(
                    "'{c}' (U+{cp:04X}) is in the Reserved Emoji Set and cannot \
                     begin a body line in tier 0; quote it (\"{c}\": ...) or place \
                     it inside a string value",
                    cp = c as u32,
                )))
            }
            _ => Ok(()),
        }
    }

    /// Heuristic: scan from current position to determine if the line is a
    /// kvpair (presence of `:` followed by ws/EOL after a key-shaped prefix)
    /// vs a scalar. We don't commit yet; we just classify.
    fn line_starts_kvpair(&self) -> bool {
        let mut p = self.pos;
        let bytes = self.src.as_bytes();
        // Try basic-quoted key
        if bytes.get(p).copied() == Some(b'"') {
            // skip until matching unescaped "
            p += 1;
            while p < bytes.len() {
                match bytes[p] {
                    b'\\' => p += 2,
                    b'"' => { p += 1; break; }
                    b'\n' | b'\r' => return false,
                    _ => p += 1,
                }
            }
        } else if bytes.get(p).copied() == Some(b'\'') {
            p += 1;
            while p < bytes.len() {
                match bytes[p] {
                    b'\'' => { p += 1; break; }
                    b'\n' | b'\r' => return false,
                    _ => p += 1,
                }
            }
        } else {
            // bare key chars
            let s = &self.src[p..];
            let mut chars = s.char_indices();
            let mut last_end = 0;
            let mut any = false;
            while let Some((i, c)) = chars.next() {
                if is_bare_key_char(c) {
                    last_end = i + c.len_utf8();
                    any = true;
                } else {
                    break;
                }
            }
            if !any {
                return false;
            }
            p += last_end;
        }
        // now expect ':'
        if bytes.get(p).copied() != Some(b':') {
            return false;
        }
        // followed by ws, EOL, or EOF — we consider it a kvpair
        match bytes.get(p + 1).copied() {
            Some(b' ') | Some(b'\t') | Some(b'\n') | Some(b'\r') | None => true,
            _ => false,
        }
    }

    // ----- block parsers -----

    /// Parses a table block: a sequence of kvpairs at exactly `indent`
    /// (column = indent+1). Stops at a line whose indent < indent+1 or EOF.
    fn parse_table_block(&mut self, indent: usize) -> Result<DmsMap<Value>, DecodeError> {
        let mut table: DmsMap<Value> = DmsMap::default();
        loop {
            self.skip_trivia()?;
            if self.eof() {
                break;
            }
            // measure this line's indent
            let line_indent = self.measure_line_indent();
            if line_indent < indent {
                break;
            }
            if line_indent != indent {
                return Err(self.err_at(
                    self.line,
                    self.line_start,
                    self.line_start + indent,
                    format!(
                        "inconsistent indent: expected {indent} spaces, got {line_indent}"
                    ),
                ));
            }
            // consume the indent
            self.pos = self.line_start + indent;
            // SPEC §Lexical: reject reserved decorator sigils at line-start.
            self.reject_reserved_decorator_sigil()?;
            let (key, value) = self.parse_kvpair(indent)?;
            if table.contains_key(&key) {
                return Err(self.err(format!("duplicate key: {key}")));
            }
            table.insert(key, value);
        }
        // Block closing: any leftover pending leading comments become
        // floating on the enclosing container (the table itself).
        self.flush_pending_as_floating();
        Ok(table)
    }

    /// Unordered counterpart of `parse_table_block` — same grammar, same
    /// errors; only difference is the backing store is a `HashMap`
    /// (no insertion-order tracking). Called when `self.ignore_order`
    /// is true. See SPEC §"Unordered tables".
    fn parse_table_block_unordered(
        &mut self,
        indent: usize,
    ) -> Result<DmsHashMap<Value>, DecodeError> {
        let mut table: DmsHashMap<Value> = DmsHashMap::default();
        loop {
            self.skip_trivia()?;
            if self.eof() {
                break;
            }
            let line_indent = self.measure_line_indent();
            if line_indent < indent {
                break;
            }
            if line_indent != indent {
                return Err(self.err_at(
                    self.line,
                    self.line_start,
                    self.line_start + indent,
                    format!(
                        "inconsistent indent: expected {indent} spaces, got {line_indent}"
                    ),
                ));
            }
            self.pos = self.line_start + indent;
            // SPEC §Lexical: reject reserved decorator sigils at line-start.
            self.reject_reserved_decorator_sigil()?;
            let (key, value) = self.parse_kvpair(indent)?;
            if table.contains_key(&key) {
                return Err(self.err(format!("duplicate key: {key}")));
            }
            table.insert(key, value);
        }
        self.flush_pending_as_floating();
        Ok(table)
    }

    /// Parses a list block: sibling `+ item` lines at exactly `indent`.
    fn parse_list_block(&mut self, indent: usize) -> Result<Vec<Value>, DecodeError> {
        let mut items: Vec<Value> = Vec::new();
        loop {
            self.skip_trivia()?;
            if self.eof() {
                break;
            }
            let line_indent = self.measure_line_indent();
            if line_indent < indent {
                break;
            }
            if line_indent != indent {
                return Err(self.err_at(
                    self.line,
                    self.line_start,
                    self.line_start + indent,
                    format!(
                        "inconsistent indent: expected {indent} spaces, got {line_indent}"
                    ),
                ));
            }
            self.pos = self.line_start + indent;
            // SPEC §Lexical: reject reserved decorator sigils at line-start.
            self.reject_reserved_decorator_sigil()?;
            if self.peek() != Some('+') {
                // not a list item — caller may treat as end of list
                break;
            }
            // We've committed to a new list item. Push its index, attach
            // pending leading comments to it, then parse the value.
            let idx = items.len();
            self.path.push(BreadcrumbSegment::Index(idx));
            self.flush_pending_as_leading_on_current();
            // consume '+'
            self.bump();
            // require whitespace OR end-of-line
            let item_result: Result<Value, DecodeError> = match self.peek() {
                Some(' ') | Some('\t') => {
                    self.bump();
                    self.skip_inline_ws();
                    // Capture inner /* ... */ comments before deciding
                    // empty-item vs scalar/kvpair. They attach to the
                    // current list item via path.
                    let dec_count_before = self.decorations_raw.len();
                    self.capture_inner_block_comments()?;
                    let inner_dec_captured = self.decorations_raw.len() > dec_count_before;
                    match self.peek() {
                        Some('\n') | Some('\r') | None => {
                            // Tier-1 decoration-only: `+ |decorator[EOL]` with no base
                            // value. The value is a placeholder (empty Table); the hoist
                            // pass will substitute the family's empty_default.
                            if self.is_t1_active() && inner_dec_captured {
                                self.decoration_only_paths.push(self.path.clone());
                                self.consume_eol();
                                Ok(Value::Table(DmsMap::default()))
                            } else {
                                // `+ /* ... */[EOL]` → empty item with
                                // inner comments, opens a nested block.
                                self.consume_eol();
                                self.skip_trivia()?;
                                if self.eof() {
                                    Err(self.err("expected indented block after empty '+' marker"))
                                } else {
                                    let inner_indent = self.measure_line_indent();
                                    if inner_indent <= indent {
                                        Err(self.err("expected indented block after empty '+' marker"))
                                    } else {
                                        self.parse_block_value(inner_indent)
                                    }
                                }
                            }
                        }
                        _ => self.parse_list_item_value(indent),
                    }
                }
                Some('\n') | Some('\r') | None => {
                    // empty `+` opens a nested block on next lines
                    self.consume_eol();
                    self.skip_trivia()?;
                    if self.eof() {
                        Err(self.err("expected indented block after empty '+' marker"))
                    } else {
                        let inner_indent = self.measure_line_indent();
                        if inner_indent <= indent {
                            Err(self.err("expected indented block after empty '+' marker"))
                        } else {
                            self.parse_block_value(inner_indent)
                        }
                    }
                }
                _ => Err(self.err("expected space after '+'")),
            };
            self.path.pop();
            let v = item_result?;
            items.push(v);
        }
        // Block close: leftover pending become floating on the list itself.
        self.flush_pending_as_floating();
        Ok(items)
    }

    fn measure_line_indent(&self) -> usize {
        let b = self.src.as_bytes();
        let mut i = self.line_start;
        let mut n = 0usize;
        while i < b.len() && b[i] == b' ' {
            n += 1;
            i += 1;
        }
        n
    }

    fn parse_block_value(&mut self, indent: usize) -> Result<Value, DecodeError> {
        // Decide: list or table
        // Consume the indent first
        self.pos = self.line_start + indent;
        // SPEC §Lexical: reject reserved decorator sigils at line-start.
        self.reject_reserved_decorator_sigil()?;
        if self.peek() == Some('+') && self.peek_after_plus_is_space_or_eol() {
            Ok(Value::List(self.parse_list_block(indent)?))
        } else if self.ignore_order {
            Ok(Value::UnorderedTable(self.parse_table_block_unordered(indent)?))
        } else {
            Ok(Value::Table(self.parse_table_block(indent)?))
        }
    }

    fn parse_list_item_value(&mut self, list_indent: usize) -> Result<Value, DecodeError> {
        // The value sits after `+ `. It can be:
        //   - inline scalar (number/string/...) ending at EOL
        //   - the start of a kvpair (key:value), in which case the item is
        //     a table; subsequent keys of that table sit at the column of
        //     the first key (not the `+`).
        //   - heredoc opener
        if self.line_starts_kvpair() {
            // remember key column
            let key_col = self.col() - 1; // 0-based column of first key
            if self.ignore_order {
                let (k, v) = self.parse_kvpair(key_col)?;
                let mut t: DmsHashMap<Value> = DmsHashMap::default();
                t.insert(k, v);
                loop {
                    self.skip_trivia()?;
                    if self.eof() {
                        break;
                    }
                    let li = self.measure_line_indent();
                    if li < key_col {
                        break;
                    }
                    if li != key_col {
                        return Err(self.err_at(
                            self.line,
                            self.line_start,
                            self.line_start + key_col,
                            "list-item table sibling key must align with first key",
                        ));
                    }
                    self.pos = self.line_start + key_col;
                    // SPEC §Lexical: reject reserved decorator sigils
                    // at line-start.
                    self.reject_reserved_decorator_sigil()?;
                    if self.peek() == Some('+') {
                        return Err(self.err(
                            "'+' marker at sibling-key column is ambiguous",
                        ));
                    }
                    if !self.line_starts_kvpair() {
                        break;
                    }
                    let (k, v) = self.parse_kvpair(key_col)?;
                    if t.contains_key(&k) {
                        return Err(self.err(format!("duplicate key: {k}")));
                    }
                    t.insert(k, v);
                }
                self.flush_pending_as_floating();
                return Ok(Value::UnorderedTable(t));
            }
            let (k, v) = self.parse_kvpair(key_col)?;
            // additional keys at key_col are siblings of this table
            let mut t = DmsMap::default();
            t.insert(k, v);
            // continue reading sibling keys at key_col
            loop {
                self.skip_trivia()?;
                if self.eof() {
                    break;
                }
                let li = self.measure_line_indent();
                if li < key_col {
                    break;
                }
                if li != key_col {
                    return Err(self.err_at(
                        self.line,
                        self.line_start,
                        self.line_start + key_col,
                        "list-item table sibling key must align with first key",
                    ));
                }
                self.pos = self.line_start + key_col;
                // SPEC §Lexical: reject reserved decorator sigils at line-start.
                self.reject_reserved_decorator_sigil()?;
                // ensure not a `+` at key_col (would indicate next list item misaligned)
                if self.peek() == Some('+') {
                    return Err(self.err(
                        "'+' marker at sibling-key column is ambiguous",
                    ));
                }
                if !self.line_starts_kvpair() {
                    break;
                }
                let (k, v) = self.parse_kvpair(key_col)?;
                if t.contains_key(&k) {
                    return Err(self.err(format!("duplicate key: {k}")));
                }
                t.insert(k, v);
            }
            // End of this inline-table-in-list-item: any pending leading
            // comments belong to the enclosing list item itself (Floating).
            self.flush_pending_as_floating();
            Ok(Value::Table(t))
        } else {
            // inline scalar (or heredoc); same end-of-line discipline
            let v = self.parse_inline_value_or_heredoc()?;
            self.consume_after_value(false)?;
            // For a heredoc the parse already consumed up through the
            // terminator line; consume_after_value handled the EOL after
            // any inline scalar.
            // Lists do not support a child block when the item's value is a
            // simple scalar; we don't try to attach one here.
            let _ = list_indent;
            Ok(v)
        }
    }

    // ----- kvpair parsing -----

    fn parse_kvpair(&mut self, parent_indent: usize) -> Result<(String, Value), DecodeError> {
        let key = self.parse_key()?;
        if self.peek() != Some(':') {
            return Err(self.err("expected ':' after key"));
        }
        // We've now committed: this is a kvpair with key `key`. Push the
        // breadcrumb so any pending leading comments attach to this node,
        // and so trailing comments captured by `consume_after_value` (and
        // any floating comments inside the value's child block) get the
        // right path.
        self.path.push(BreadcrumbSegment::Key(key.clone()));
        self.flush_pending_as_leading_on_current();
        let result = self.parse_kvpair_after_key(parent_indent);
        self.path.pop();
        result.map(|v| (key, v))
    }

    fn parse_kvpair_after_key(&mut self, parent_indent: usize) -> Result<Value, DecodeError> {
        // caller has consumed the key but not the ':'
        self.bump(); // consume ':'
        match self.peek() {
            Some(' ') | Some('\t') => {
                self.bump();
                self.skip_inline_ws();
                // Inner `/* ... */` comments live in this slot. Capture
                // them now; they attach to the current kvpair via path.
                let dec_count_before = self.decorations_raw.len();
                self.capture_inner_block_comments()?;
                let inner_dec_captured = self.decorations_raw.len() > dec_count_before;
                // After the `: <inner?>`, decide: inline value, or
                // (with at least one inner comment present) a child
                // block opened by EOL.
                match self.peek() {
                    Some('\n') | Some('\r') | None => {
                        // Tier-1 decoration-only: `key: |decorator[EOL]` with no base
                        // value. The value is a placeholder (empty Table); the hoist
                        // pass will substitute the family's empty_default.
                        if self.is_t1_active() && inner_dec_captured {
                            self.decoration_only_paths.push(self.path.clone());
                            self.consume_eol();
                            return Ok(Value::Table(DmsMap::default()));
                        }
                        // `key: /* ... */[EOL]` → child block. Without
                        // any inner comment this branch is reached only
                        // via the dedicated no-WS-after-colon path
                        // below; reaching it here means at least one
                        // inner comment was captured.
                        self.consume_eol();
                        self.skip_trivia()?;
                        if self.eof() {
                            return Err(self.err("expected indented child block"));
                        }
                        let child_indent = self.measure_line_indent();
                        if child_indent <= parent_indent {
                            return Err(self.err("expected indented child block"));
                        }
                        let v = self.parse_block_value(child_indent)?;
                        Ok(v)
                    }
                    _ => {
                        let v = self.parse_inline_value_or_heredoc()?;
                        self.consume_after_value(false)?;
                        Ok(v)
                    }
                }
            }
            Some('\n') | Some('\r') | None => {
                // `key:[EOL]` — child block, no inner-comment slot.
                self.consume_eol();
                self.skip_trivia()?;
                if self.eof() {
                    return Err(self.err("expected indented child block"));
                }
                let child_indent = self.measure_line_indent();
                if child_indent <= parent_indent {
                    return Err(self.err("expected indented child block"));
                }
                let v = self.parse_block_value(child_indent)?;
                Ok(v)
            }
            _ => Err(self.err("expected whitespace after ':'")),
        }
    }

    // ----- key parsing -----

    fn parse_key(&mut self) -> Result<String, DecodeError> {
        match self.peek() {
            Some('"') => self.parse_basic_string_key(),
            Some('\'') => self.parse_literal_string_key(),
            Some(_) => self.parse_bare_key(),
            None => Err(self.err("expected key")),
        }
    }

    fn parse_bare_key(&mut self) -> Result<String, DecodeError> {
        let start = self.pos;
        while let Some(c) = self.peek() {
            if is_bare_key_char(c) {
                self.bump();
            } else {
                break;
            }
        }
        if self.pos == start {
            return Err(self.err("expected key"));
        }
        Ok(self.src[start..self.pos].to_string())
    }

    fn parse_basic_string_key(&mut self) -> Result<String, DecodeError> {
        // disallow """ as key opener (heredoc-ish)
        if self.rest().starts_with("\"\"\"") {
            return Err(self.err("triple-quoted strings are not allowed as keys"));
        }
        // Suppress original-form recording: the key is not a value
        // and must not end up as an OriginalLiteral entry on the
        // parent container's path.
        let saved = self.record_forms;
        self.record_forms = false;
        let r = self.parse_basic_string_value();
        self.record_forms = saved;
        r
    }

    fn parse_literal_string_key(&mut self) -> Result<String, DecodeError> {
        if self.rest().starts_with("'''") {
            return Err(self.err("triple-quoted strings are not allowed as keys"));
        }
        let saved = self.record_forms;
        self.record_forms = false;
        let r = self.parse_literal_string_value();
        self.record_forms = saved;
        r
    }

    // ----- value parsing -----

    /// Capture mid-token `/* ... */` block comments that appear between
    /// `:` and an inline value, or between `+` and a list item's content.
    /// Each one is pushed as `Inner` on the current `self.path` (the
    /// caller is responsible for ensuring the path already points at the
    /// kvpair / list-item being parsed). Inline whitespace between
    /// comments is consumed.
    ///
    /// In tier-1 mode, delegates to `capture_t1_decoration_run` which
    /// handles both block comments and decorator calls in source order.
    fn capture_inner_block_comments(&mut self) -> Result<(), DecodeError> {
        if self.is_t1_active() {
            return self.capture_t1_decoration_run(tier1::DecorationPosition::Inner);
        }
        loop {
            match self.peek() {
                Some('/') if self.rest().starts_with("/*") => {
                    let raw = self.read_c_block_comment()?;
                    if !self.lite {
                        self.comments.push(AttachedComment {
                            comment: Comment {
                                content: raw,
                                kind: CommentKind::Block,
                            },
                            position: CommentPosition::Inner,
                            path: self.path.clone(),
                        });
                    }
                    self.skip_inline_ws();
                }
                _ => break,
            }
        }
        Ok(())
    }

    /// Tier-1 decoration-run consumer. Position is at start of run. Each
    /// recognized decoration is pushed to `decorations_raw` with the given
    /// position at `self.path`. Comments captured at the same position
    /// also use the existing `self.comments` accumulator with the matching
    /// `CommentPosition`. Returns when peek is non-whitespace,
    /// non-sigil, non-block-comment.
    ///
    /// Per TIER1.md §"Stacking and interleaving with comments", source
    /// order is preserved across decorators + block comments.
    fn capture_t1_decoration_run(
        &mut self,
        position: tier1::DecorationPosition,
    ) -> Result<(), DecodeError> {
        if !self.is_t1_active() {
            return Ok(());
        }
        let comment_position = match position {
            tier1::DecorationPosition::Inner => CommentPosition::Inner,
            tier1::DecorationPosition::Trailing => CommentPosition::Trailing,
            tier1::DecorationPosition::Leading => CommentPosition::Leading,
            tier1::DecorationPosition::Floating => CommentPosition::Floating,
        };
        loop {
            // skip inline ws between decorations
            self.skip_inline_ws();
            match self.peek() {
                Some(c) if tier1::is_sigil_atom_start(c) => {
                    let (mut call, end) = tier1::parse_decorator_call(self.src, self.pos)?;
                    // Bookkeeping: walk consumed bytes for line/line_start
                    let mut walk = self.pos;
                    while walk < end {
                        if self.src.as_bytes()[walk] == b'\n' {
                            self.line += 1;
                            self.line_start = walk + 1;
                        }
                        walk += 1;
                    }
                    self.pos = end;
                    call.position = position;
                    self.decorations_raw.push((self.path.clone(), position, call));
                }
                Some('/') if self.rest().starts_with("/*") => {
                    let raw = self.read_c_block_comment()?;
                    if !self.lite {
                        self.comments.push(AttachedComment {
                            comment: Comment {
                                content: raw,
                                kind: CommentKind::Block,
                            },
                            position: comment_position.clone(),
                            path: self.path.clone(),
                        });
                    }
                }
                _ => return Ok(()),
            }
        }
    }

    /// Variant of [`capture_t1_decoration_run`] for use inside flow forms
    /// (`[...]` and `{...}`).
    ///
    /// In flow context `,`, `]`, and `}` are structural delimiters, but those
    /// characters also appear in the tier-0 reserved decorator sigil set.
    /// This wrapper peeks first: if the next non-inline-whitespace character
    /// is one of those three, the run is considered over and we return
    /// immediately without attempting a decorator parse.
    fn capture_t1_decoration_run_flow(
        &mut self,
        position: tier1::DecorationPosition,
    ) -> Result<(), DecodeError> {
        if !self.is_t1_active() {
            return Ok(());
        }
        let comment_position = match position {
            tier1::DecorationPosition::Inner => CommentPosition::Inner,
            tier1::DecorationPosition::Trailing => CommentPosition::Trailing,
            tier1::DecorationPosition::Leading => CommentPosition::Leading,
            tier1::DecorationPosition::Floating => CommentPosition::Floating,
        };
        loop {
            // Skip inline whitespace (spaces/tabs) between decorations.
            self.skip_inline_ws();
            match self.peek() {
                // Flow delimiters always terminate the run, even though
                // `,`, `]`, and `}` are in the reserved sigil set.
                Some(',') | Some(']') | Some('}') => return Ok(()),
                Some(c) if tier1::is_sigil_atom_start(c) => {
                    let (mut call, end) = tier1::parse_decorator_call(self.src, self.pos)?;
                    // Bookkeeping: walk consumed bytes for line/line_start
                    let mut walk = self.pos;
                    while walk < end {
                        if self.src.as_bytes()[walk] == b'\n' {
                            self.line += 1;
                            self.line_start = walk + 1;
                        }
                        walk += 1;
                    }
                    self.pos = end;
                    call.position = position;
                    self.decorations_raw.push((self.path.clone(), position, call));
                }
                Some('/') if self.rest().starts_with("/*") => {
                    let raw = self.read_c_block_comment()?;
                    if !self.lite {
                        self.comments.push(AttachedComment {
                            comment: Comment {
                                content: raw,
                                kind: CommentKind::Block,
                            },
                            position: comment_position.clone(),
                            path: self.path.clone(),
                        });
                    }
                }
                _ => return Ok(()),
            }
        }
    }

    fn parse_inline_value_or_heredoc(&mut self) -> Result<Value, DecodeError> {
        // Inner /* ... */ block comments between `:` and value (or `+`
        // and item) are captured by the caller via
        // `capture_inner_block_comments` before this function runs, so
        // we don't expect a leading `/*` here.
        match self.peek() {
            Some('"') => {
                if self.rest().starts_with("\"\"\"") {
                    self.parse_heredoc_basic().map(Value::String)
                } else {
                    let r = self.parse_basic_string_value().map(Value::String);
                    // Basic is the emitter's default for strings, so
                    // we don't need to record it as an OriginalLiteral
                    // entry — `encode` falls back to Basic when no
                    // entry is found. Still walking through the parse
                    // path here for symmetry / future extension.
                    r
                }
            }
            Some('\'') => {
                if self.rest().starts_with("'''") {
                    self.parse_heredoc_literal().map(Value::String)
                } else {
                    let r = self.parse_literal_string_value().map(Value::String)?;
                    self.record_form(OriginalLiteral::String { form: StringForm::Literal });
                    Ok(r)
                }
            }
            Some('[') => Ok(Value::List(self.parse_flow_array()?)),
            Some('{') => {
                if self.ignore_order {
                    Ok(Value::UnorderedTable(self.parse_flow_table_unordered()?))
                } else {
                    Ok(Value::Table(self.parse_flow_table()?))
                }
            }
            Some('t') | Some('f') => self.parse_bool_or_keyword_value(),
            Some('i') => self.parse_inf_value(false),
            Some('n') => self.parse_nan_value(false),
            Some(c) if c == '+' || c == '-' || c.is_ascii_digit() => {
                self.parse_number_or_datetime()
            }
            Some(c) => Err(self.err(format!("unexpected character '{c}' in value"))),
            None => Err(self.err("expected value")),
        }
    }

    fn parse_bool_or_keyword_value(&mut self) -> Result<Value, DecodeError> {
        let rest = self.rest();
        if let Some(after) = rest.strip_prefix("true") {
            if Self::is_value_terminator(after.chars().next()) {
                self.pos += 4;
                return Ok(Value::Bool(true));
            }
        }
        if let Some(after) = rest.strip_prefix("false") {
            if Self::is_value_terminator(after.chars().next()) {
                self.pos += 5;
                return Ok(Value::Bool(false));
            }
        }
        Err(self.err("expected value"))
    }

    fn parse_inf_value(&mut self, signed: bool) -> Result<Value, DecodeError> {
        let after = if signed { 4 } else { 3 };
        let want: &'static str = if signed {
            // peek to see sign
            match self.peek() {
                Some('+') => "+inf",
                Some('-') => "-inf",
                _ => "inf",
            }
        } else {
            "inf"
        };
        let neg = want.starts_with('-');
        let rest_owned = self.rest().to_string();
        if let Some(rem) = rest_owned.strip_prefix(want) {
            if Self::is_value_terminator(rem.chars().next()) {
                self.pos += after;
                let v = if neg { f64::NEG_INFINITY } else { f64::INFINITY };
                return Ok(Value::Float(v));
            }
        }
        Err(self.err("expected 'inf'"))
    }

    fn parse_nan_value(&mut self, signed: bool) -> Result<Value, DecodeError> {
        let after = if signed { 4 } else { 3 };
        let want: &'static str = if signed {
            match self.peek() { Some('+') => "+nan", Some('-') => "-nan", _ => "nan" }
        } else {
            "nan"
        };
        let rest_owned = self.rest().to_string();
        if let Some(rem) = rest_owned.strip_prefix(want) {
            if Self::is_value_terminator(rem.chars().next()) {
                self.pos += after;
                return Ok(Value::Float(f64::NAN));
            }
        }
        Err(self.err("expected 'nan'"))
    }

    fn is_value_terminator(c: Option<char>) -> bool {
        match c {
            None => true,
            Some(c) => matches!(c, ' ' | '\t' | '\n' | '\r' | '#' | '/' | ',' | ']' | '}'),
        }
    }

    // ----- numbers + datetime -----

    fn parse_number_or_datetime(&mut self) -> Result<Value, DecodeError> {
        let rest = self.rest();
        let starts_with_sign = matches!(self.peek(), Some('+') | Some('-'));
        if !starts_with_sign && looks_like_date_prefix(rest) {
            return self.parse_datetime_value();
        }
        if !starts_with_sign && looks_like_time_prefix(rest) {
            return self.parse_local_time_value();
        }
        // Check inf/nan with sign
        if starts_with_sign {
            let after_sign = &rest[1..];
            if after_sign.starts_with("inf") {
                let signed_rest = &rest[..4];
                if Self::is_value_terminator(rest[4..].chars().next()) {
                    let neg = signed_rest.starts_with('-');
                    self.pos += 4;
                    return Ok(Value::Float(if neg { f64::NEG_INFINITY } else { f64::INFINITY }));
                }
            }
            // signed nan rejected per design — keep `nan` bare only
        }
        // determine if this is a float by scanning the token
        let tok = self.scan_number_token();
        let s = &self.src[self.pos..self.pos + tok.len];
        if tok.is_float {
            let f = parse_float(s).ok_or_else(|| self.err(format!("invalid float: {s}")))?;
            self.pos += tok.len;
            Ok(Value::Float(f))
        } else {
            let n = parse_integer(s).map_err(|e| self.err(e))?;
            self.pos += tok.len;
            // Record original lexeme only when it differs from the
            // canonical "decimal, no underscores, no '+' sign" form
            // used by the default emitter (i.e. `n.to_string()`).
            // Anything else — hex/oct/bin, underscore separators,
            // explicit `+` — gets recorded.
            //
            // Lite mode skips the full canonical-comparison alloc up
            // front: no `original_forms` is kept, so the lexeme is
            // never needed.
            if !self.lite && self.record_forms {
                let canonical = n.to_string();
                if s != canonical {
                    self.record_form(OriginalLiteral::Integer { lit: s.to_string() });
                }
            }
            Ok(Value::Integer(n))
        }
    }

    fn scan_number_token(&self) -> NumTok {
        let s = self.rest();
        let bytes = s.as_bytes();
        let mut i = 0usize;
        if matches!(bytes.get(0), Some(b'+') | Some(b'-')) {
            i += 1;
        }
        // detect base prefix
        let is_prefixed = bytes.get(i) == Some(&b'0')
            && matches!(bytes.get(i + 1).copied(), Some(b'x') | Some(b'o') | Some(b'b'));
        if is_prefixed {
            i += 2;
            // mantissa digits + underscores + possible '.'
            let mut saw_dot = false;
            let mut saw_p = false;
            while let Some(&b) = bytes.get(i) {
                if b == b'_' || is_base_digit(b, bytes[i - if saw_dot { 1 } else { 0 } - 1]) {
                    i += 1;
                } else if b == b'.' && !saw_dot && !saw_p {
                    saw_dot = true;
                    i += 1;
                } else if b == b'p' && !saw_p {
                    saw_p = true;
                    i += 1;
                    if matches!(bytes.get(i), Some(b'+') | Some(b'-')) {
                        i += 1;
                    }
                } else if saw_p && b.is_ascii_digit() {
                    i += 1;
                } else {
                    break;
                }
            }
            return NumTok { len: i, is_float: saw_dot || saw_p };
        }
        // decimal
        let mut saw_dot = false;
        let mut saw_e = false;
        while let Some(&b) = bytes.get(i) {
            if b.is_ascii_digit() || b == b'_' {
                i += 1;
            } else if b == b'.' && !saw_dot && !saw_e {
                saw_dot = true;
                i += 1;
            } else if (b == b'e' || b == b'E') && !saw_e {
                saw_e = true;
                i += 1;
                if matches!(bytes.get(i), Some(b'+') | Some(b'-')) {
                    i += 1;
                }
            } else {
                break;
            }
        }
        NumTok { len: i, is_float: saw_dot || saw_e }
    }

    fn parse_datetime_value(&mut self) -> Result<Value, DecodeError> {
        let rest: String = self.rest().to_string();
        let date = rest[..10].to_string();
        validate_date(&date).map_err(|e| self.err(e))?;
        let rest2 = &rest[10..];
        if !rest2.starts_with('T') && !rest2.starts_with(' ') {
            if rest2.starts_with('t') {
                return Err(self.err("date and time separator must be uppercase 'T' (lowercase 't' not permitted)"));
            }
            if !Self::is_value_terminator(rest2.chars().next()) {
                return Err(self.err("invalid character after date"));
            }
            self.pos += 10;
            return Ok(Value::LocalDate(date));
        }
        if rest2.starts_with(' ') {
            let after_ws = rest2.trim_start_matches(|c: char| c == ' ' || c == '\t');
            if matches!(after_ws.chars().next(), Some(c) if c.is_ascii_digit()) {
                return Err(self.err("date and time must be separated by 'T' (space not permitted)"));
            }
            self.pos += 10;
            return Ok(Value::LocalDate(date));
        }
        let after_t = &rest2[1..];
        if !looks_like_time_prefix(after_t) {
            return Err(self.err("expected HH:MM:SS after 'T'"));
        }
        let time_str = &after_t[..8];
        validate_time(time_str).map_err(|e| self.err(e))?;
        let mut consumed = 10 + 1 + 8;
        let after_time = &rest[consumed..];
        let mut frac_len = 0usize;
        if after_time.starts_with('.') {
            let bytes = after_time.as_bytes();
            let mut k = 1usize;
            while k < bytes.len() && bytes[k].is_ascii_digit() {
                k += 1;
            }
            let digits = k - 1;
            if digits == 0 {
                return Err(self.err("expected fractional digits after '.'"));
            }
            if digits > 9 {
                return Err(self.err("fractional seconds limited to 9 digits (nanosecond precision)"));
            }
            frac_len = k;
        }
        consumed += frac_len;
        let after_frac = &rest[consumed..];
        if after_frac.starts_with('Z') || after_frac.starts_with('z') {
            consumed += 1;
            let s = rest[..consumed].to_string();
            self.pos += consumed;
            return Ok(Value::OffsetDateTime(s));
        }
        if after_frac.starts_with('+') || after_frac.starts_with('-') {
            let bytes = after_frac.as_bytes();
            if bytes.len() < 6
                || !bytes[1].is_ascii_digit()
                || !bytes[2].is_ascii_digit()
                || bytes[3] != b':'
                || !bytes[4].is_ascii_digit()
                || !bytes[5].is_ascii_digit()
            {
                return Err(self.err("invalid offset; expected ±HH:MM"));
            }
            let oh = (bytes[1] - b'0') * 10 + (bytes[2] - b'0');
            let om = (bytes[4] - b'0') * 10 + (bytes[5] - b'0');
            if oh > 23 || om > 59 {
                return Err(self.err("offset out of range"));
            }
            consumed += 6;
            let s = rest[..consumed].to_string();
            self.pos += consumed;
            return Ok(Value::OffsetDateTime(s));
        }
        // no offset → local-datetime
        if !Self::is_value_terminator(after_frac.chars().next()) {
            return Err(self.err("invalid character after datetime"));
        }
        let s = rest[..consumed].to_string();
        self.pos += consumed;
        Ok(Value::LocalDateTime(s))
    }

    fn parse_local_time_value(&mut self) -> Result<Value, DecodeError> {
        let rest = self.rest();
        let time_str = &rest[..8];
        validate_time(time_str).map_err(|e| self.err(e))?;
        let mut consumed = 8usize;
        let after = &rest[consumed..];
        if after.starts_with('.') {
            let bytes = after.as_bytes();
            let mut k = 1usize;
            while k < bytes.len() && bytes[k].is_ascii_digit() {
                k += 1;
            }
            let digits = k - 1;
            if digits == 0 {
                return Err(self.err("expected fractional digits after '.'"));
            }
            if digits > 9 {
                return Err(self.err("fractional seconds limited to 9 digits"));
            }
            consumed += k;
        }
        let after2 = &rest[consumed..];
        if !Self::is_value_terminator(after2.chars().next()) {
            return Err(self.err("invalid character after time"));
        }
        let s = rest[..consumed].to_string();
        self.pos += consumed;
        Ok(Value::LocalTime(s))
    }

    // ----- strings -----

    fn parse_basic_string_value(&mut self) -> Result<String, DecodeError> {
        let start_line = self.line;
        let start_lstart = self.line_start;
        let start_pos = self.pos;
        self.bump(); // consume opening "
        let mut out = String::new();
        loop {
            match self.peek() {
                None => return Err(self.err_at(start_line, start_lstart, start_pos, "unterminated string")),
                Some('\n') | Some('\r') => return Err(self.err("strings cannot span lines")),
                Some('"') => {
                    self.bump();
                    // SPEC §Unicode normalization: re-NFC after escape
                    // decoding — `é` resolves to U+0065 U+0301
                    // which the source-level NFC pass never saw.
                    return Ok(nfc_normalize(&out));
                }
                Some('\\') => {
                    self.bump();
                    let esc_pos = self.pos;
                    match self.bump() {
                        Some('"') => out.push('"'),
                        Some('\\') => out.push('\\'),
                        Some('n') => out.push('\n'),
                        Some('t') => out.push('\t'),
                        Some('r') => out.push('\r'),
                        Some('b') => out.push('\u{0008}'),
                        Some('f') => out.push('\u{000c}'),
                        Some('u') => {
                            let cp = self.read_hex_codepoint(4, esc_pos)?;
                            out.push(cp);
                        }
                        Some('U') => {
                            let cp = self.read_hex_codepoint(8, esc_pos)?;
                            out.push(cp);
                        }
                        Some(c) => return Err(self.err(format!("invalid escape '\\{c}'"))),
                        None => return Err(self.err("unterminated escape")),
                    }
                }
                Some(c) => {
                    self.bump();
                    out.push(c);
                }
            }
        }
    }

    fn parse_literal_string_value(&mut self) -> Result<String, DecodeError> {
        let start_line = self.line;
        let start_lstart = self.line_start;
        let start_pos = self.pos;
        self.bump(); // consume '
        let mut out = String::new();
        loop {
            match self.peek() {
                None => return Err(self.err_at(start_line, start_lstart, start_pos, "unterminated string")),
                Some('\n') | Some('\r') => return Err(self.err("strings cannot span lines")),
                Some('\'') => {
                    self.bump();
                    return Ok(out);
                }
                Some(c) => {
                    self.bump();
                    out.push(c);
                }
            }
        }
    }

    fn read_hex_codepoint(&mut self, n: usize, _esc_pos: usize) -> Result<char, DecodeError> {
        let s = self.rest();
        if s.len() < n {
            return Err(self.err(format!("expected {n} hex digits in unicode escape")));
        }
        let hex = &s[..n];
        if !hex.bytes().all(|b| b.is_ascii_hexdigit()) {
            return Err(self.err(format!("invalid hex in unicode escape: {hex}")));
        }
        let v = u32::from_str_radix(hex, 16)
            .map_err(|_| self.err("invalid unicode escape"))?;
        // SPEC: U+0000 is forbidden anywhere in DMS source, including via
        // escape decoding. `` / `\U00000000` must not slip through.
        if v == 0 {
            return Err(self.err("\\u0000 escape forbidden"));
        }
        self.pos += n;
        char::from_u32(v).ok_or_else(|| self.err("unicode escape is not a scalar value"))
    }

    // ----- heredocs -----

    fn parse_heredoc_basic(&mut self) -> Result<String, DecodeError> {
        // consume opening """
        self.pos += 3;
        let label = self.parse_heredoc_label();
        let modifiers = self.parse_heredoc_modifiers()?;
        // rest of opener line must be only whitespace, then EOL
        self.skip_inline_ws();
        if !(self.consume_eol() || self.eof()) {
            return Err(self.err("heredoc opener must be followed by end of line"));
        }
        let label_opt = if label.is_empty() { None } else { Some(label.clone()) };
        let terminator = if label.is_empty() { "\"\"\"".to_string() } else { label };
        let body = self.collect_heredoc_body(&terminator, true)?;
        // SPEC §basic-string escapes: surrogate codepoints (U+D800..U+DFFF)
        // are not valid Unicode scalars and are a parse error in `\uXXXX` /
        // `\UXXXXXXXX` escapes. Basic-heredoc bodies process the same
        // escapes as basic strings, so apply the same rejection here.
        validate_heredoc_basic_surrogates(&body)?;
        let stripped = strip_indent_and_continuations(&body, true)?;
        let processed = apply_modifiers(stripped, &modifiers).map_err(|e| self.err(e))?;
        let calls: Vec<HeredocModifierCall> = modifiers
            .into_iter()
            .map(|m| HeredocModifierCall { name: m.name, args: m.args })
            .collect();
        self.record_form(OriginalLiteral::String {
            form: StringForm::Heredoc {
                flavor: HeredocFlavor::BasicTriple,
                label: label_opt,
                modifiers: calls,
            },
        });
        // SPEC §Unicode normalization: re-NFC after escape decoding —
        // basic-heredoc bodies process the same `\u`/`\U` escapes as
        // basic strings, so escape-decoded scalars need normalizing.
        Ok(nfc_normalize(&processed))
    }

    fn parse_heredoc_literal(&mut self) -> Result<String, DecodeError> {
        self.pos += 3;
        let label = self.parse_heredoc_label();
        let modifiers = self.parse_heredoc_modifiers()?;
        self.skip_inline_ws();
        if !(self.consume_eol() || self.eof()) {
            return Err(self.err("heredoc opener must be followed by end of line"));
        }
        let label_opt = if label.is_empty() { None } else { Some(label.clone()) };
        let terminator = if label.is_empty() { "'''".to_string() } else { label };
        let body = self.collect_heredoc_body(&terminator, false)?;
        let stripped = strip_indent_and_continuations(&body, false)?;
        let processed = apply_modifiers(stripped, &modifiers).map_err(|e| self.err(e))?;
        let calls: Vec<HeredocModifierCall> = modifiers
            .into_iter()
            .map(|m| HeredocModifierCall { name: m.name, args: m.args })
            .collect();
        self.record_form(OriginalLiteral::String {
            form: StringForm::Heredoc {
                flavor: HeredocFlavor::LiteralTriple,
                label: label_opt,
                modifiers: calls,
            },
        });
        Ok(processed)
    }

    fn parse_heredoc_label(&mut self) -> String {
        let start = self.pos;
        if let Some(c) = self.peek() {
            if !is_label_start(c) {
                return String::new();
            }
        } else {
            return String::new();
        }
        while let Some(c) = self.peek() {
            if is_label_cont(c) {
                self.bump();
            } else {
                break;
            }
        }
        self.src[start..self.pos].to_string()
    }

    fn parse_heredoc_modifiers(&mut self) -> Result<Vec<HMod>, DecodeError> {
        let mut mods = Vec::new();
        loop {
            // require whitespace before each modifier
            let ws_start = self.pos;
            self.skip_inline_ws();
            let had_ws = self.pos > ws_start;
            match self.peek() {
                Some(c) if is_label_start(c) => {
                    if !had_ws {
                        return Err(self.err("modifier must be preceded by whitespace"));
                    }
                    let m = self.parse_one_modifier()?;
                    mods.push(m);
                }
                _ => {
                    self.pos = ws_start;
                    return Ok(mods);
                }
            }
        }
    }

    fn parse_one_modifier(&mut self) -> Result<HMod, DecodeError> {
        let name_start = self.pos;
        while let Some(c) = self.peek() {
            if is_label_cont(c) {
                self.bump();
            } else {
                break;
            }
        }
        let name = self.src[name_start..self.pos].to_string();
        if self.peek() != Some('(') {
            return Err(self.err("modifiers require parentheses"));
        }
        self.bump();
        // Suppress original-form recording while parsing modifier args:
        // these values are consumed at parse time (passed into the modifier
        // call) and otherwise discarded — they must not pollute the host
        // heredoc node's `original_forms` slot. e.g. `_trim("\n", ">")`
        // should leave the heredoc's String form intact, not push entries
        // for the basic-string `","` or literal-string `">"` arguments.
        let prev_record = self.record_forms;
        self.record_forms = false;
        // parse args: comma-separated inline values
        let mut args = Vec::new();
        let result: Result<(), DecodeError> = (|| {
            loop {
                self.skip_inline_ws();
                if self.peek() == Some(')') {
                    self.bump();
                    return Ok(());
                }
                let v = self.parse_inline_value_or_heredoc()?;
                args.push(v);
                self.skip_inline_ws();
                match self.peek() {
                    Some(',') => { self.bump(); }
                    Some(')') => { self.bump(); return Ok(()); }
                    _ => return Err(self.err("expected ',' or ')' in modifier args")),
                }
            }
        })();
        self.record_forms = prev_record;
        result?;
        Ok(HMod { name, args })
    }

    fn collect_heredoc_body(&mut self, terminator: &str, _allow_continuation: bool) -> Result<HBody, DecodeError> {
        let mut lines: Vec<HLine> = Vec::new();
        let opener_line = self.line;
        let opener_lstart = self.line_start;
        let opener_pos = self.pos;
        loop {
            if self.eof() {
                return Err(self.err_at(opener_line, opener_lstart, opener_pos, "unterminated heredoc"));
            }
            let line_begin = self.pos;
            // read until eol
            while let Some(c) = self.peek() {
                if c == '\n' || c == '\r' {
                    break;
                }
                self.bump();
            }
            let line_text = &self.src[line_begin..self.pos];
            let raw = line_text.to_string();
            let this_line = self.line;
            let this_line_start = self.line_start;
            if raw.trim() == terminator {
                // Leave the terminator's trailing EOL for the caller's
                // consume_after_value() to consume; otherwise we'd skip
                // past it and the next line's content gets misread.
                let strip_depth = raw.bytes().take_while(|&b| b == b' ').count();
                return Ok(HBody { lines, strip_depth });
            }
            // not the terminator — consume this line's EOL and continue
            let _consumed_eol = self.consume_eol();
            lines.push(HLine { text: raw, line: this_line, line_start: this_line_start });
        }
    }

    // ----- flow forms -----

    fn parse_flow_array(&mut self) -> Result<Vec<Value>, DecodeError> {
        self.bump(); // consume [
        let mut items = Vec::new();
        loop {
            self.skip_flow_ws()?;
            if self.peek() == Some(']') {
                self.bump();
                return Ok(items);
            }
            // Push the current index onto the path so decoration captures and
            // OriginalLiteral records get the right breadcrumb. The path is
            // popped after inner + value + trailing have all been processed.
            let idx = items.len();
            self.path.push(BreadcrumbSegment::Index(idx));
            // Tier-1: capture any inner decoration run before the value.
            if let Err(e) = self.capture_t1_decoration_run_flow(tier1::DecorationPosition::Inner) {
                self.path.pop();
                return Err(e);
            }
            let parsed = self.parse_inline_value_or_heredoc_in_flow();
            if let Err(e) = parsed {
                self.path.pop();
                return Err(e);
            }
            let v = parsed.unwrap();
            // Tier-1: capture any trailing decoration run after the value.
            if let Err(e) = self.capture_t1_decoration_run_flow(tier1::DecorationPosition::Trailing) {
                self.path.pop();
                return Err(e);
            }
            self.path.pop();
            items.push(v);
            self.skip_flow_ws()?;
            match self.peek() {
                Some(',') => { self.bump(); }
                Some(']') => { self.bump(); return Ok(items); }
                Some(c) => return Err(self.err(format!("unexpected '{c}' in flow array; expected ',' or ']'"))),
                None => return Err(self.err("unterminated flow array")),
            }
        }
    }

    fn parse_flow_table(&mut self) -> Result<DmsMap<Value>, DecodeError> {
        self.bump(); // consume {
        let mut t: DmsMap<Value> = DmsMap::default();
        loop {
            self.skip_flow_ws()?;
            if self.peek() == Some('}') {
                self.bump();
                return Ok(t);
            }
            let key = self.parse_key()?;
            if self.peek() != Some(':') {
                return Err(self.err("expected ':' after flow-table key"));
            }
            self.bump();
            // require at least one space or newline (whitespace is insignificant in flow)
            if !matches!(self.peek(), Some(' ') | Some('\t') | Some('\n') | Some('\r')) {
                return Err(self.err("expected whitespace after ':'"));
            }
            self.skip_flow_ws()?;
            // Path push so decoration captures and OriginalLiteral records on
            // the value get attached to the key path.
            self.path.push(BreadcrumbSegment::Key(key.clone()));
            // Tier-1: capture any inner decoration run between ':' and value.
            if let Err(e) = self.capture_t1_decoration_run_flow(tier1::DecorationPosition::Inner) {
                self.path.pop();
                return Err(e);
            }
            let parsed = self.parse_inline_value_or_heredoc_in_flow();
            if let Err(e) = parsed {
                self.path.pop();
                return Err(e);
            }
            let v = parsed.unwrap();
            // Tier-1: capture any trailing decoration run after the value.
            if let Err(e) = self.capture_t1_decoration_run_flow(tier1::DecorationPosition::Trailing) {
                self.path.pop();
                return Err(e);
            }
            self.path.pop();
            if t.contains_key(&key) {
                return Err(self.err(format!("duplicate key: {key}")));
            }
            t.insert(key, v);
            self.skip_flow_ws()?;
            match self.peek() {
                Some(',') => { self.bump(); }
                Some('}') => { self.bump(); return Ok(t); }
                Some(c) => return Err(self.err(format!("unexpected '{c}' in flow table; expected ',' or '}}'"))),
                None => return Err(self.err("unterminated flow table")),
            }
        }
    }

    /// Unordered counterpart of `parse_flow_table`. Same grammar; the
    /// only difference is the backing `HashMap` (no insertion-order
    /// tracking). See SPEC §"Unordered tables".
    fn parse_flow_table_unordered(&mut self) -> Result<DmsHashMap<Value>, DecodeError> {
        self.bump(); // consume {
        let mut t: DmsHashMap<Value> = DmsHashMap::default();
        loop {
            self.skip_flow_ws()?;
            if self.peek() == Some('}') {
                self.bump();
                return Ok(t);
            }
            let key = self.parse_key()?;
            if self.peek() != Some(':') {
                return Err(self.err("expected ':' after flow-table key"));
            }
            self.bump();
            if !matches!(self.peek(), Some(' ') | Some('\t') | Some('\n') | Some('\r')) {
                return Err(self.err("expected whitespace after ':'"));
            }
            self.skip_flow_ws()?;
            // Path push so decoration captures and OriginalLiteral records on
            // the value get attached to the key path.
            self.path.push(BreadcrumbSegment::Key(key.clone()));
            // Tier-1: capture any inner decoration run between ':' and value.
            if let Err(e) = self.capture_t1_decoration_run_flow(tier1::DecorationPosition::Inner) {
                self.path.pop();
                return Err(e);
            }
            let parsed = self.parse_inline_value_or_heredoc_in_flow();
            if let Err(e) = parsed {
                self.path.pop();
                return Err(e);
            }
            let v = parsed.unwrap();
            // Tier-1: capture any trailing decoration run after the value.
            if let Err(e) = self.capture_t1_decoration_run_flow(tier1::DecorationPosition::Trailing) {
                self.path.pop();
                return Err(e);
            }
            self.path.pop();
            if t.contains_key(&key) {
                return Err(self.err(format!("duplicate key: {key}")));
            }
            t.insert(key, v);
            self.skip_flow_ws()?;
            match self.peek() {
                Some(',') => { self.bump(); }
                Some('}') => { self.bump(); return Ok(t); }
                Some(c) => return Err(self.err(format!("unexpected '{c}' in flow table; expected ',' or '}}'"))),
                None => return Err(self.err("unterminated flow table")),
            }
        }
    }

    /// Whitespace inside flow forms: spaces, tabs, newlines (LF/CRLF). NO comments.
    fn skip_flow_ws(&mut self) -> Result<(), DecodeError> {
        loop {
            match self.peek() {
                Some(' ') | Some('\t') => { self.bump(); }
                Some('\n') => { self.bump(); self.advance_line(); }
                Some('\r') if self.rest().starts_with("\r\n") => {
                    self.pos += 2; self.advance_line();
                }
                Some('#') => return Err(self.err("comments not allowed inside flow forms")),
                Some('/') if self.rest().starts_with("//") => return Err(self.err("comments not allowed inside flow forms")),
                Some('/') if self.rest().starts_with("/*") => return Err(self.err("comments not allowed inside flow forms")),
                _ => return Ok(()),
            }
        }
    }

    /// Inside a flow form, heredocs are not permitted (would need newline-significant content).
    fn parse_inline_value_or_heredoc_in_flow(&mut self) -> Result<Value, DecodeError> {
        match self.peek() {
            Some('"') if self.rest().starts_with("\"\"\"") => {
                Err(self.err("heredocs are not allowed inside flow forms"))
            }
            Some('\'') if self.rest().starts_with("'''") => {
                Err(self.err("heredocs are not allowed inside flow forms"))
            }
            _ => self.parse_inline_value_or_heredoc(),
        }
    }

    // ----- post-value -----

    fn consume_after_value(&mut self, allow_eof: bool) -> Result<(), DecodeError> {
        // Same-line comment(s) after a value attach as `Trailing` on the
        // node currently identified by `self.path`. Callers (kvpair / list
        // item entry points) push the breadcrumb segment for that node
        // before parsing the value, so `self.path` is correct here.
        //
        // Multiple trailing comments may appear on one line, separated
        // by whitespace, e.g. `port: 3 /* a */ /* b */ # last`. Block
        // comments don't terminate the line; a `#` or `//` line comment
        // (if present) consumes to EOL and must therefore come last.
        //
        // Tier-1: consume decorator calls + interleaved block comments
        // before handing off to the existing trailing-comment logic.
        self.capture_t1_decoration_run(tier1::DecorationPosition::Trailing)?;
        let mut first = true;
        loop {
            let ws_start = self.pos;
            self.skip_inline_ws();
            let had_ws = self.pos > ws_start;
            let captured = match self.peek() {
                Some('#') if !self.rest().starts_with("###") => {
                    if !had_ws {
                        return Err(self.err("expected whitespace before '#' comment"));
                    }
                    let raw = self.read_line_comment_to_eol();
                    if !self.lite {
                        self.comments.push(AttachedComment {
                            comment: Comment { content: raw, kind: CommentKind::Line },
                            position: CommentPosition::Trailing,
                            path: self.path.clone(),
                        });
                    }
                    // Line comment consumes to EOL → no more trailing.
                    break;
                }
                Some('/') if self.rest().starts_with("//") => {
                    if !had_ws {
                        return Err(self.err("expected whitespace before '//' comment"));
                    }
                    let raw = self.read_line_comment_to_eol();
                    if !self.lite {
                        self.comments.push(AttachedComment {
                            comment: Comment { content: raw, kind: CommentKind::Line },
                            position: CommentPosition::Trailing,
                            path: self.path.clone(),
                        });
                    }
                    break;
                }
                Some('/') if self.rest().starts_with("/*") => {
                    let raw = self.read_c_block_comment()?;
                    if !self.lite {
                        self.comments.push(AttachedComment {
                            comment: Comment { content: raw, kind: CommentKind::Block },
                            position: CommentPosition::Trailing,
                            path: self.path.clone(),
                        });
                    }
                    true
                }
                _ => false,
            };
            if !captured {
                // No more comments — restore position past whitespace,
                // then require EOL/EOF below. (Whitespace before EOL is
                // benign; we leave it consumed.)
                let _ = first;
                break;
            }
            first = false;
        }
        // Now expect EOL, EOF, or — for nested contexts — nothing.
        match self.peek() {
            None => {
                if allow_eof { Ok(()) } else { Ok(()) }
            }
            Some('\n') => { self.bump(); self.advance_line(); Ok(()) }
            Some('\r') if self.rest().starts_with("\r\n") => {
                self.pos += 2; self.advance_line(); Ok(())
            }
            Some(c) => Err(self.err(format!("unexpected character '{c}' after value"))),
        }
    }
}

// ---------- helper structs ----------

struct NumTok {
    len: usize,
    is_float: bool,
}

#[derive(Debug, Clone)]
struct HMod {
    name: String,
    args: Vec<Value>,
}

struct HBody {
    lines: Vec<HLine>,
    strip_depth: usize,
}

struct HLine {
    text: String,
    line: usize,
    line_start: usize,
}

// ---------- number helpers ----------

fn is_base_digit(b: u8, _prev_for_disambig: u8) -> bool {
    // Base-agnostic: any hex digit qualifies. Final base-correctness check
    // happens in parse_integer / parse_nondec_float. Note: 'p' is NOT a
    // hex digit (it's the binary exponent marker for non-decimal floats).
    b.is_ascii_hexdigit()
}

fn parse_integer(s: &str) -> Result<i64, String> {
    let (sign, rest) = if let Some(r) = s.strip_prefix('-') { (-1i128, r) }
        else if let Some(r) = s.strip_prefix('+') { (1i128, r) }
        else { (1i128, s) };
    let (radix, body) = if let Some(r) = rest.strip_prefix("0x") {
        if rest.starts_with("0X") {
            return Err("hex prefix must be lowercase '0x'".into());
        }
        (16u32, r)
    } else if let Some(r) = rest.strip_prefix("0o") {
        (8u32, r)
    } else if let Some(r) = rest.strip_prefix("0b") {
        (2u32, r)
    } else {
        (10u32, rest)
    };
    if body.is_empty() {
        return Err("empty number".into());
    }
    if body.starts_with('_') || body.ends_with('_') {
        return Err("underscore must be between digits".into());
    }
    if radix == 10 && rest.len() > 1 && rest.starts_with('0') {
        return Err("leading zeros are not allowed on decimal integers".into());
    }
    // strip underscores, ensuring they're between digits
    let mut clean = String::with_capacity(body.len());
    let mut prev_is_digit = false;
    for c in body.chars() {
        if c == '_' {
            if !prev_is_digit {
                return Err("underscore must be between digits".into());
            }
            prev_is_digit = false;
        } else {
            if !c.is_digit(radix) {
                return Err(format!("invalid digit '{c}' for base {radix}"));
            }
            clean.push(c);
            prev_is_digit = true;
        }
    }
    if !prev_is_digit {
        return Err("underscore must be between digits".into());
    }
    let n = i128::from_str_radix(&clean, radix)
        .map_err(|_| "integer out of range".to_string())?;
    let signed = sign * n;
    if signed < i64::MIN as i128 || signed > i64::MAX as i128 {
        return Err("integer out of i64 range".into());
    }
    Ok(signed as i64)
}

fn parse_float(s: &str) -> Option<f64> {
    let (sign, rest) = if let Some(r) = s.strip_prefix('-') { (-1.0f64, r) }
        else if let Some(r) = s.strip_prefix('+') { (1.0f64, r) }
        else { (1.0f64, s) };
    if rest.starts_with("0x") || rest.starts_with("0o") || rest.starts_with("0b") {
        return parse_nondec_float(rest).map(|v| sign * v);
    }
    parse_dec_float(rest).map(|v| sign * v)
}

fn parse_dec_float(s: &str) -> Option<f64> {
    // require digit on both sides of '.'
    let (m, e) = if let Some(idx) = s.find(['e', 'E']) {
        (&s[..idx], Some(&s[idx + 1..]))
    } else {
        (s, None)
    };
    if !m.contains('.') {
        return None; // decimal float requires a dot in our spec slice
    }
    let parts: Vec<&str> = m.splitn(2, '.').collect();
    if parts.len() != 2 || parts[0].is_empty() || parts[1].is_empty() {
        return None;
    }
    if !parts[0].chars().all(|c| c.is_ascii_digit() || c == '_')
        || !parts[1].chars().all(|c| c.is_ascii_digit() || c == '_')
    {
        return None;
    }
    if !valid_underscores(parts[0]) || !valid_underscores(parts[1]) {
        return None;
    }
    let int_part: String = parts[0].chars().filter(|&c| c != '_').collect();
    let frac_part: String = parts[1].chars().filter(|&c| c != '_').collect();
    let mut full = format!("{int_part}.{frac_part}");
    if let Some(es) = e {
        let es_clean = es.trim_start_matches(['+', '-']);
        if es_clean.contains('_') {
            return None;
        }
        if !es.chars().all(|c| c.is_ascii_digit() || c == '+' || c == '-') {
            return None;
        }
        if es_clean.is_empty() {
            return None;
        }
        full.push('e');
        full.push_str(es);
    }
    full.parse::<f64>().ok()
}

fn parse_nondec_float(s: &str) -> Option<f64> {
    // `0xMANT[.FRAC]pEXP`
    let (radix, rest) = if let Some(r) = s.strip_prefix("0x") { (16u32, r) }
        else if let Some(r) = s.strip_prefix("0o") { (8u32, r) }
        else if let Some(r) = s.strip_prefix("0b") { (2u32, r) }
        else { return None; };
    let p_idx = rest.find('p')?;
    let mant = &rest[..p_idx];
    let exp_str = &rest[p_idx + 1..];
    if exp_str.is_empty() {
        return None;
    }
    if exp_str.contains('_') {
        return None;
    }
    let exp_clean = exp_str.trim_start_matches(['+', '-']);
    if !exp_clean.chars().all(|c| c.is_ascii_digit()) {
        return None;
    }
    let exp: i32 = exp_str.parse().ok()?;
    // mantissa: digit on both sides of dot if dot present
    let (int_part, frac_part) = if let Some(idx) = mant.find('.') {
        (&mant[..idx], &mant[idx + 1..])
    } else {
        (mant, "")
    };
    if mant.contains('.') {
        if int_part.is_empty() || frac_part.is_empty() {
            return None;
        }
    }
    if !valid_underscores(int_part) || !valid_underscores(frac_part) {
        return None;
    }
    let int_clean: String = int_part.chars().filter(|&c| c != '_').collect();
    let frac_clean: String = frac_part.chars().filter(|&c| c != '_').collect();
    if int_clean.is_empty() && frac_clean.is_empty() {
        return None;
    }
    if !int_clean.chars().all(|c| c.is_digit(radix)) {
        return None;
    }
    if !frac_clean.chars().all(|c| c.is_digit(radix)) {
        return None;
    }
    let int_val = if int_clean.is_empty() {
        0u128
    } else {
        u128::from_str_radix(&int_clean, radix).ok()?
    };
    let mut frac_val = 0f64;
    let mut div = radix as f64;
    for c in frac_clean.chars() {
        let d = c.to_digit(radix)? as f64;
        frac_val += d / div;
        div *= radix as f64;
    }
    let mantissa = int_val as f64 + frac_val;
    Some(mantissa * (2f64).powi(exp))
}

fn valid_underscores(s: &str) -> bool {
    if s.is_empty() {
        return true;
    }
    if s.starts_with('_') || s.ends_with('_') {
        return false;
    }
    let mut prev_us = false;
    for c in s.chars() {
        if c == '_' {
            if prev_us {
                return false;
            }
            prev_us = true;
        } else {
            prev_us = false;
        }
    }
    true
}

// ---------- date/time validation ----------

fn validate_date(s: &str) -> Result<(), String> {
    if s.len() != 10 {
        return Err("invalid date length".into());
    }
    let b = s.as_bytes();
    if b[4] != b'-' || b[7] != b'-' {
        return Err("invalid date format".into());
    }
    for &i in &[0, 1, 2, 3, 5, 6, 8, 9] {
        if !b[i].is_ascii_digit() {
            return Err("date must be all digits".into());
        }
    }
    let year: u16 = (b[0] - b'0') as u16 * 1000
        + (b[1] - b'0') as u16 * 100
        + (b[2] - b'0') as u16 * 10
        + (b[3] - b'0') as u16;
    let month: u8 = (b[5] - b'0') * 10 + (b[6] - b'0');
    let day: u8 = (b[8] - b'0') * 10 + (b[9] - b'0');
    if month < 1 || month > 12 {
        return Err("month out of range".into());
    }
    if day < 1 || day > days_in_month(year, month) {
        return Err("day out of range".into());
    }
    Ok(())
}

fn validate_time(s: &str) -> Result<(), String> {
    if s.len() != 8 {
        return Err("invalid time length".into());
    }
    let b = s.as_bytes();
    if b[2] != b':' || b[5] != b':' {
        return Err("invalid time format".into());
    }
    for &i in &[0, 1, 3, 4, 6, 7] {
        if !b[i].is_ascii_digit() {
            return Err("time must be all digits".into());
        }
    }
    let hh: u8 = (b[0] - b'0') * 10 + (b[1] - b'0');
    let mm: u8 = (b[3] - b'0') * 10 + (b[4] - b'0');
    let ss: u8 = (b[6] - b'0') * 10 + (b[7] - b'0');
    if hh > 23 {
        return Err("hour out of range".into());
    }
    if mm > 59 {
        return Err("minute out of range".into());
    }
    if ss > 59 {
        return Err("second out of range (leap seconds not supported)".into());
    }
    Ok(())
}

fn days_in_month(year: u16, month: u8) -> u8 {
    match month {
        1 | 3 | 5 | 7 | 8 | 10 | 12 => 31,
        4 | 6 | 9 | 11 => 30,
        2 => if is_leap(year) { 29 } else { 28 },
        _ => 0,
    }
}

fn is_leap(y: u16) -> bool {
    (y % 4 == 0 && y % 100 != 0) || y % 400 == 0
}

// ---------- heredoc body processing ----------

/// SPEC §basic-string escapes: a `\uXXXX` / `\UXXXXXXXX` escape whose
/// decoded value falls in the surrogate range U+D800..U+DFFF is not a
/// Unicode scalar and is a parse error. The basic-string lexer
/// (`read_hex_codepoint`) already enforces this via `char::from_u32`,
/// which returns `None` for surrogates; basic-heredoc body lines are
/// collected raw here, so we validate the same rule by scanning the
/// body for surrogate escape sequences.
fn validate_heredoc_basic_surrogates(body: &HBody) -> Result<(), DecodeError> {
    for line in &body.lines {
        let bytes = line.text.as_bytes();
        let mut i = 0;
        while i < bytes.len() {
            // Only consider unescaped `\` — a `\\` is a literal
            // backslash and the following `u`/`U` is not an escape
            // introducer. Count preceding contiguous backslashes; an
            // odd count means this `\` is unescaped.
            if bytes[i] == b'\\' {
                // find the run of consecutive backslashes starting at i
                let mut j = i;
                while j < bytes.len() && bytes[j] == b'\\' {
                    j += 1;
                }
                let run = j - i;
                // pairs of `\\` consume themselves; only the last `\` of
                // an odd-length run is an escape introducer.
                if run % 2 == 1 && j < bytes.len() {
                    let intro = bytes[j];
                    let n = match intro {
                        b'u' => 4,
                        b'U' => 8,
                        _ => 0,
                    };
                    if n > 0 && j + 1 + n <= bytes.len() {
                        let hex = &line.text[j + 1..j + 1 + n];
                        if hex.bytes().all(|b| b.is_ascii_hexdigit()) {
                            if let Ok(cp) = u32::from_str_radix(hex, 16) {
                                if (0xD800..=0xDFFF).contains(&cp) {
                                    // column points at the leading `\`
                                    // of the escape (1-based, byte col).
                                    let esc_off = j - 1;
                                    return Err(DecodeError {
                                        line: line.line,
                                        column: esc_off + 1,
                                        message: format!(
                                            "surrogate codepoint U+{cp:04X} in escape"
                                        ),
                                    });
                                }
                            }
                        }
                    }
                }
                i = j;
            } else {
                i += 1;
            }
        }
    }
    Ok(())
}

fn strip_indent_and_continuations(body: &HBody, allow_continuation: bool) -> Result<String, DecodeError> {
    let mut out = String::new();
    let mut first = true;
    let mut pending_continuation = false;
    let mut last_line_pos = (1usize, 0usize); // for trailing-continuation error
    for line in &body.lines {
        let raw = &line.text;
        last_line_pos = (line.line, line.line_start);
        // blank lines (only whitespace) are exempt from strip-depth check
        let is_blank = raw.bytes().all(|b| b == b' ' || b == b'\t');
        let stripped: &str = if is_blank {
            ""
        } else {
            // count leading spaces; must be >= strip_depth
            let leading_spaces = raw.bytes().take_while(|&b| b == b' ').count();
            if leading_spaces < body.strip_depth {
                return Err(DecodeError {
                    line: line.line,
                    column: leading_spaces + 1,
                    message: format!(
                        "heredoc body line indented {} spaces, less than strip depth {}",
                        leading_spaces, body.strip_depth
                    ),
                });
            }
            &raw[body.strip_depth..]
        };
        let mut piece = stripped.to_string();
        // line continuation: a `\` that is the last non-whitespace char
        let mut splice = false;
        if allow_continuation {
            // scan for trailing \ that is not preceded by an unescaped escape
            let trimmed_end = piece.trim_end_matches(|c: char| c == ' ' || c == '\t').to_string();
            if let Some(last_idx) = trimmed_end.rfind('\\') {
                if last_idx == trimmed_end.len() - 1 {
                    // count preceding backslashes
                    let preceding = trimmed_end[..last_idx]
                        .bytes()
                        .rev()
                        .take_while(|&b| b == b'\\')
                        .count();
                    if preceding % 2 == 0 {
                        // unescaped trailing backslash -> continuation
                        // remove the trailing \ and any following ws
                        piece = trimmed_end[..last_idx].to_string();
                        splice = true;
                    }
                }
            }
        }
        if first {
            out.push_str(&piece);
            first = false;
        } else if pending_continuation {
            // splice into previous: skip leading ws of this line
            let trimmed_start = piece.trim_start_matches(|c: char| c == ' ' || c == '\t');
            // also: a blank line during continuation is consumed entirely
            if !is_blank {
                out.push_str(trimmed_start);
            }
        } else {
            out.push('\n');
            out.push_str(&piece);
        }
        pending_continuation = splice;
    }
    if pending_continuation {
        return Err(DecodeError {
            line: last_line_pos.0,
            column: 1,
            message: "trailing line continuation has nothing to splice to".into(),
        });
    }
    Ok(out)
}

fn apply_modifiers(s: String, mods: &[HMod]) -> Result<String, String> {
    let mut cur = s;
    for m in mods {
        match m.name.as_str() {
            "_fold_paragraphs" => {
                if !m.args.is_empty() {
                    return Err("fold_paragraphs() takes no arguments".into());
                }
                cur = fold_paragraphs(&cur);
            }
            "_trim" => {
                if m.args.len() < 2 || m.args.len() > 3 {
                    return Err("trim(chars, where, replacement = \"\") expects 2 or 3 arguments".into());
                }
                let chars = match &m.args[0] {
                    Value::String(s) => s.clone(),
                    _ => return Err("trim: first argument (chars) must be a string".into()),
                };
                let where_s = match &m.args[1] {
                    Value::String(s) => s.clone(),
                    _ => return Err("trim: second argument (where) must be a string".into()),
                };
                let replacement = if m.args.len() == 3 {
                    match &m.args[2] {
                        Value::String(s) => s.clone(),
                        _ => return Err("trim: third argument (replacement) must be a string".into()),
                    }
                } else {
                    String::new()
                };
                cur = apply_trim(&cur, &chars, &where_s, &replacement);
            }
            other => return Err(format!("unknown modifier: {other}")),
        }
    }
    Ok(cur)
}

fn fold_paragraphs(s: &str) -> String {
    // Split by double-newline (paragraph breaks); within each paragraph,
    // join lines with single space.
    let paragraphs: Vec<&str> = s.split("\n\n").collect();
    let folded: Vec<String> = paragraphs
        .iter()
        .map(|p| {
            let lines: Vec<&str> = p.split('\n').collect();
            lines
                .iter()
                .filter(|l| !l.is_empty())
                .copied()
                .collect::<Vec<&str>>()
                .join(" ")
        })
        .collect();
    folded.join("\n")
}

/// Swiss-army trim/replace.
///
/// `chars` = bag of characters to match (any single char in this string).
/// `where_s` = DSL flags. Recognized: `<` leading (whole string), `>`
/// trailing (whole string), `|` per-line edges, `*` every occurrence.
/// Unknown flags are silently ignored for forward compatibility.
/// `replacement` = what each run of matching chars becomes.
///
/// **Run collapse**: consecutive matching chars become one replacement,
/// not one per char.
///
/// If `*` is set, the whole-string and per-line flags become redundant
/// (every run anywhere is replaced). Otherwise, flags are applied in a
/// defined order: per-line (`|`) first, then leading (`<`), then
/// trailing (`>`).
fn apply_trim(s: &str, chars: &str, where_s: &str, replacement: &str) -> String {
    if chars.is_empty() {
        return s.to_string();
    }
    let char_set: std::collections::HashSet<char> = chars.chars().collect();
    let has_star = where_s.contains('*');
    let has_pipe = where_s.contains('|');
    let has_lt = where_s.contains('<');
    let has_gt = where_s.contains('>');
    if !(has_star || has_pipe || has_lt || has_gt) {
        return s.to_string();
    }
    if has_star {
        return replace_all_runs(s, &char_set, replacement);
    }
    let mut cur = s.to_string();
    if has_pipe {
        cur = per_line_edges(&cur, &char_set, replacement);
    }
    if has_lt {
        cur = replace_leading_run(&cur, &char_set, replacement);
    }
    if has_gt {
        cur = replace_trailing_run(&cur, &char_set, replacement);
    }
    cur
}

fn replace_all_runs(s: &str, char_set: &std::collections::HashSet<char>, replacement: &str) -> String {
    let mut out = String::with_capacity(s.len());
    let mut chars = s.chars().peekable();
    while let Some(c) = chars.next() {
        if char_set.contains(&c) {
            while let Some(&nc) = chars.peek() {
                if char_set.contains(&nc) {
                    chars.next();
                } else {
                    break;
                }
            }
            out.push_str(replacement);
        } else {
            out.push(c);
        }
    }
    out
}

fn replace_leading_run(s: &str, char_set: &std::collections::HashSet<char>, replacement: &str) -> String {
    let mut end = 0;
    for (i, c) in s.char_indices() {
        if char_set.contains(&c) {
            end = i + c.len_utf8();
        } else {
            break;
        }
    }
    if end == 0 {
        return s.to_string();
    }
    let mut out = String::with_capacity(s.len());
    out.push_str(replacement);
    out.push_str(&s[end..]);
    out
}

fn replace_trailing_run(s: &str, char_set: &std::collections::HashSet<char>, replacement: &str) -> String {
    let mut start = s.len();
    for (i, c) in s.char_indices().rev() {
        if char_set.contains(&c) {
            start = i;
        } else {
            break;
        }
    }
    if start == s.len() {
        return s.to_string();
    }
    let mut out = String::with_capacity(s.len());
    out.push_str(&s[..start]);
    out.push_str(replacement);
    out
}

fn per_line_edges(s: &str, char_set: &std::collections::HashSet<char>, replacement: &str) -> String {
    let mut out = String::with_capacity(s.len());
    let mut lines = s.split('\n').peekable();
    let mut first = true;
    while let Some(line) = lines.next() {
        if !first {
            out.push('\n');
        }
        first = false;
        let trimmed_start = replace_leading_run(line, char_set, replacement);
        let trimmed = replace_trailing_run(&trimmed_start, char_set, replacement);
        out.push_str(&trimmed);
    }
    out
}

// ---------- encode emitter ----------

/// Re-emit a decoded `Document` as DMS source. See SPEC §encode.
///
/// Contract: `decode(encode(decode(source)))` is data-equivalent to
/// `decode(source)`, has the same comments at the same attached paths,
/// and uses the same literal forms for values where preserved
/// (integer base, string form). Float formatting is `ryu`-shortest;
/// indentation is 2 spaces; lists/tables default to block form.
///
/// Round-trip stability: `encode(decode(encode(decode(source))))` is
/// byte-equal to `encode(decode(source))`.
///
/// Returns `Err(EncodeError::UnorderedInFullMode)` if the `Document`'s
/// body contains any `Value::UnorderedTable` (built only by the
/// `*_unordered` decoder entry points). Per SPEC §"Unordered tables",
/// a full-mode round-trip requires a stable iteration order; an
/// unordered Document cannot satisfy that contract. Use `encode_lite`
/// for canonical emit on unordered Documents.
pub fn encode(doc: &Document) -> Result<String, EncodeError> {
    if contains_unordered_table(&doc.body) {
        return Err(EncodeError::UnorderedInFullMode);
    }
    let mut emitter = DmsEmitter::new(doc);
    emitter.emit_document();
    Ok(emitter.out)
}

/// Recursively checks whether a `Value` tree contains any
/// `Value::UnorderedTable`. Used by `encode` to enforce the SPEC
/// contract that full-mode emit refuses unordered documents.
fn contains_unordered_table(v: &Value) -> bool {
    match v {
        Value::UnorderedTable(_) => true,
        Value::Table(t) => t.values().any(contains_unordered_table),
        Value::List(items) => items.iter().any(contains_unordered_table),
        _ => false,
    }
}

/// Lite-mode `encode` — emits the same data tree in **canonical
/// form**: comments are dropped, integers are emitted in decimal
/// regardless of source base, strings are emitted in basic-quoted
/// form regardless of source flavour. Accepts both full-mode and
/// lite-mode decoded `Document`s — the `comments` and `original_forms`
/// fields are simply ignored. See SPEC §encode.
///
/// Round-trip stability for lite-mode emit is **data-only**:
/// `decode(encode_lite(doc))` must be data-equivalent to `doc`. It is
/// **lossy by design** for comments and source forms.
pub fn encode_lite(doc: &Document) -> String {
    let mut emitter = DmsEmitter::new_lite(doc);
    emitter.emit_document();
    emitter.out
}

/// Mirror of `ParseMode` for the emitter side.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum EmitMode {
    /// Default. Re-emits comments + `original_forms` for full
    /// round-trip preservation. Requires a full-mode-decoded
    /// `Document` (or one constructed in code with those fields
    /// populated).
    Full,
    /// Canonical-form emit. Drops comments + `original_forms` even
    /// when present. Accepts any `Document`.
    Lite,
}

/// Mode-parameterised `encode`. `EmitMode::Full` matches `encode()`
/// (and can fail with [`EncodeError::UnorderedInFullMode`]);
/// `EmitMode::Lite` matches `encode_lite()` (always `Ok`). See SPEC
/// §encode.
pub fn encode_with_mode(doc: &Document, mode: EmitMode) -> Result<String, EncodeError> {
    match mode {
        EmitMode::Full => encode(doc),
        EmitMode::Lite => Ok(encode_lite(doc)),
    }
}

/// Tier-1 encode entry point — like `encode` but also emits tier-1
/// decorator calls at their recorded positions. Used by `tier1::encode_t1`.
#[allow(dead_code)]
pub(crate) fn encode_with_decorators(
    doc: &Document,
    decorators: &[tier1::DecoratorEntry],
) -> Result<String, EncodeError> {
    encode_with_decorators_and_suppressed(doc, decorators, std::collections::HashSet::new())
}

/// Like [`encode_with_decorators`] but also accepts a set of paths whose
/// body value emission is suppressed. At suppressed paths the encoder emits
/// the decorator call(s) only — no `key: value` / `+ value` token — so that
/// Inner decoration-only nodes round-trip as `key: |dec` (no redundant `{}` or
/// other `empty_default` body). Used by `tier1::encode_t1_with_registry`.
pub(crate) fn encode_with_decorators_and_suppressed(
    doc: &Document,
    decorators: &[tier1::DecoratorEntry],
    suppressed_paths: std::collections::HashSet<Vec<BreadcrumbSegment>>,
) -> Result<String, EncodeError> {
    if contains_unordered_table(&doc.body) {
        return Err(EncodeError::UnorderedInFullMode);
    }
    let comments_by_path = SortedIndex::from_comments(&doc.comments);
    let forms_by_path = SortedIndex::from_forms(&doc.original_forms);
    let decorators_by_path = SortedIndex::from_decorators(decorators);
    let mut emitter = DmsEmitter {
        out: String::new(),
        comments_by_path,
        forms_by_path,
        decorators_by_path,
        suppressed_paths,
        lite: false,
        doc,
    };
    emitter.emit_document();
    Ok(emitter.out)
}

// ---------- deprecated `to_dms*` aliases (SPEC v0.14 rename) ----------
//
// SPEC v0.14 renamed `to_dms` → `encode`. The old names live on for
// one release as deprecated thin wrappers — slated for removal in
// v0.15. See PORTING.md §"Migration from the `parse`/`to_dms` era".

/// Deprecated alias for [`encode`]. Removed in v0.4.
#[deprecated(since = "0.3.0", note = "use `encode` instead")]
pub fn to_dms(doc: &Document) -> Result<String, EncodeError> {
    encode(doc)
}

/// Deprecated alias for [`encode_lite`]. Removed in v0.4.
#[deprecated(since = "0.3.0", note = "use `encode_lite` instead")]
pub fn to_dms_lite(doc: &Document) -> String {
    encode_lite(doc)
}

/// Deprecated alias for [`encode_with_mode`]. Removed in v0.4.
#[deprecated(since = "0.3.0", note = "use `encode_with_mode` instead")]
pub fn to_dms_with_mode(doc: &Document, mode: EmitMode) -> Result<String, EncodeError> {
    encode_with_mode(doc, mode)
}

/// Sorted index of `(path, value)` pairs with `O(log n)` lookup.
///
/// Replaces the previous `HashMap<Vec<BreadcrumbSegment>, V>` design,
/// which paid a `Vec<BreadcrumbSegment>` clone (and a sip-hash) per
/// entry on insert. On a comment-heavy config (30k comments) those
/// clones + hashes dominated `encode` wall time. The sorted-Vec
/// design borrows path slices directly from `doc.comments` /
/// `doc.original_forms` — zero allocations during build, lookup is
/// `binary_search_by`.
///
/// Same shape `dms-c` uses (see `sort_indices` in `dms.c`).
struct SortedIndex<'a, V> {
    /// Sorted-ascending by path.
    entries: Vec<(&'a [BreadcrumbSegment], V)>,
}

impl<'a, V> SortedIndex<'a, V> {
    fn empty() -> Self {
        Self { entries: Vec::new() }
    }

    /// Look up by exact-path match. Equivalent to `HashMap::get`.
    fn get(&self, query: &[BreadcrumbSegment]) -> Option<&V> {
        match self.entries.binary_search_by(|(p, _)| (*p).cmp(query)) {
            Ok(i) => Some(&self.entries[i].1),
            Err(_) => None,
        }
    }
}

impl<'a> SortedIndex<'a, NodeComments<'a>> {
    /// Build from `doc.comments`. Groups by path; within a group,
    /// comments retain their original `doc.comments` order (the sort
    /// is stable on path, so equal paths preserve source order).
    fn from_comments(comments: &'a [AttachedComment]) -> Self {
        if comments.is_empty() {
            return Self::empty();
        }
        let mut idx: Vec<usize> = (0..comments.len()).collect();
        idx.sort_by(|&a, &b| comments[a].path.cmp(&comments[b].path));
        let mut entries: Vec<(&'a [BreadcrumbSegment], NodeComments<'a>)> =
            Vec::with_capacity(comments.len());
        for i in idx {
            let ac = &comments[i];
            let path: &'a [BreadcrumbSegment] = ac.path.as_slice();
            let same_as_prev = entries.last().is_some_and(|(p, _)| *p == path);
            if !same_as_prev {
                entries.push((path, NodeComments::default()));
            }
            let nc = &mut entries.last_mut().unwrap().1;
            match ac.position {
                CommentPosition::Leading => nc.leading.push(&ac.comment),
                CommentPosition::Inner => nc.inner.push(&ac.comment),
                CommentPosition::Trailing => nc.trailing.push(&ac.comment),
                CommentPosition::Floating => nc.floating.push(&ac.comment),
            }
        }
        // Capacity was over-allocated (one entry per comment, then
        // merged). Trim — these arrays live the whole emit.
        entries.shrink_to_fit();
        Self { entries }
    }
}

impl<'a> SortedIndex<'a, &'a OriginalLiteral> {
    /// Build from `doc.original_forms`. Sorts by path; first entry
    /// wins on collision (matches the HashMap impl's `or_insert`).
    fn from_forms(forms: &'a [(Vec<BreadcrumbSegment>, OriginalLiteral)]) -> Self {
        if forms.is_empty() {
            return Self::empty();
        }
        let mut idx: Vec<usize> = (0..forms.len()).collect();
        idx.sort_by(|&a, &b| forms[a].0.cmp(&forms[b].0));
        let mut entries: Vec<(&'a [BreadcrumbSegment], &'a OriginalLiteral)> =
            Vec::with_capacity(forms.len());
        for i in idx {
            let (p, lit) = &forms[i];
            let path: &'a [BreadcrumbSegment] = p.as_slice();
            // First wins on path collision — skip duplicates.
            if entries.last().is_some_and(|(prev, _)| *prev == path) {
                continue;
            }
            entries.push((path, lit));
        }
        entries.shrink_to_fit();
        Self { entries }
    }
}

impl<'a> SortedIndex<'a, NodeDecorations<'a>> {
    /// Build from a slice of `DecoratorEntry`. Groups by path;
    /// within a group, retains source order (sigil-map order, then
    /// within-sigil vec order).
    fn from_decorators(decorators: &'a [tier1::DecoratorEntry]) -> Self {
        if decorators.is_empty() {
            return Self::empty();
        }
        // Collect (path_slice, position, call_ref) triples.
        // We don't sort by position here — we bucket into per-position
        // vecs in a second pass, preserving the per-path source order
        // within each position bucket.
        let mut path_indices: Vec<usize> = (0..decorators.len()).collect();
        path_indices.sort_by(|&a, &b| decorators[a].path.cmp(&decorators[b].path));

        let mut entries: Vec<(&'a [BreadcrumbSegment], NodeDecorations<'a>)> =
            Vec::with_capacity(decorators.len());

        for i in path_indices {
            let entry = &decorators[i];
            let path: &'a [BreadcrumbSegment] = entry.path.as_slice();
            let same_as_prev = entries.last().is_some_and(|(p, _)| *p == path);
            if !same_as_prev {
                entries.push((path, NodeDecorations::default()));
            }
            let nd = &mut entries.last_mut().unwrap().1;
            // Iterate sigils in IndexMap order, then within-sigil vec order.
            for (_sigil, calls) in &entry.decorators {
                for call in calls {
                    match call.position {
                        tier1::DecorationPosition::Leading => nd.leading.push(call),
                        tier1::DecorationPosition::Inner => nd.inner.push(call),
                        tier1::DecorationPosition::Trailing => nd.trailing.push(call),
                        tier1::DecorationPosition::Floating => nd.floating.push(call),
                    }
                }
            }
        }
        entries.shrink_to_fit();
        Self { entries }
    }
}

struct DmsEmitter<'a> {
    out: String,
    /// Path → `NodeComments` (per-position comment slices into
    /// `doc.comments`). Empty in lite mode. See `SortedIndex` doc for
    /// why this isn't a HashMap.
    comments_by_path: SortedIndex<'a, NodeComments<'a>>,
    /// Path → `&OriginalLiteral`. Empty in lite mode.
    forms_by_path: SortedIndex<'a, &'a OriginalLiteral>,
    /// Path → `NodeDecorations` (per-position decorator-call slices).
    /// Empty in tier-0 emit.
    decorators_by_path: SortedIndex<'a, NodeDecorations<'a>>,
    /// Paths whose body emission is suppressed. For an Inner-position
    /// decoration-only node where the body value equals the family's
    /// `empty_default`, we emit `key: |dec` (or `+ |dec`) and skip
    /// the value token entirely. Set by `encode_t1_with_registry` when
    /// it detects such paths; empty for all tier-0 and unregistered-
    /// tier-1 emit paths.
    suppressed_paths: std::collections::HashSet<Vec<BreadcrumbSegment>>,
    /// Lite mode (canonical-form emit) — drops comments and
    /// `original_forms` even when present in `doc`. See SPEC §encode.
    lite: bool,
    doc: &'a Document,
}

#[derive(Default)]
struct NodeComments<'a> {
    leading: Vec<&'a Comment>,
    inner: Vec<&'a Comment>,
    trailing: Vec<&'a Comment>,
    floating: Vec<&'a Comment>,
}

#[derive(Default)]
struct NodeDecorations<'a> {
    leading: Vec<&'a tier1::DecoratorCall>,
    inner: Vec<&'a tier1::DecoratorCall>,
    trailing: Vec<&'a tier1::DecoratorCall>,
    floating: Vec<&'a tier1::DecoratorCall>,
}

const INDENT_STR: &str = "  ";

impl<'a> DmsEmitter<'a> {
    fn new(doc: &'a Document) -> Self {
        Self {
            out: String::new(),
            comments_by_path: SortedIndex::from_comments(&doc.comments),
            forms_by_path: SortedIndex::from_forms(&doc.original_forms),
            decorators_by_path: SortedIndex::empty(),
            suppressed_paths: std::collections::HashSet::new(),
            lite: false,
            doc,
        }
    }

    /// Lite-mode constructor — empty comment + form lookups, so the
    /// walker emits canonical form (no comments, decimal integers,
    /// basic-quoted strings) even when `doc.comments` and
    /// `doc.original_forms` are populated. See SPEC §encode.
    fn new_lite(doc: &'a Document) -> Self {
        Self {
            out: String::new(),
            comments_by_path: SortedIndex::empty(),
            forms_by_path: SortedIndex::empty(),
            decorators_by_path: SortedIndex::empty(),
            suppressed_paths: std::collections::HashSet::new(),
            lite: true,
            doc,
        }
    }

    fn emit_document(&mut self) {
        // Front matter: emit the `+++` block whenever the parsed doc
        // carried one (meta=Some(...)), even if it's empty. The SPEC
        // §encode allows omitting an empty-meta block with no comments,
        // but round-trip data equivalence is cleaner when we preserve
        // the `Some({})` ↔ `None` distinction, since the canonical JSON
        // encoder keys off `meta.is_some()`. Emitting `+++\n+++\n` for
        // an empty-meta doc with no FM comments gives byte-stable round
        // trips through parse/emit.
        // Lite mode emits no comments, so FM comments don't force
        // a `+++` block — only an explicit `meta = Some(...)` does.
        let has_fm_comments = !self.lite && self.doc.comments.iter().any(|ac| {
            matches!(ac.path.first(), Some(BreadcrumbSegment::Key(k)) if k == "__fm__")
        });
        let fm_present = self.doc.meta.is_some();
        if fm_present || has_fm_comments {
            self.out.push_str("+++\n");
            // Emit FM keys at indent 0, with paths prefixed by __fm__.
            let fm_path: Vec<BreadcrumbSegment> = vec![BreadcrumbSegment::Key("__fm__".to_string())];
            if let Some(meta) = &self.doc.meta {
                self.emit_table_block(meta, &fm_path, 0);
            } else {
                // No meta keys, only floating FM comments — emit them at
                // the FM root.
                self.emit_floating(&fm_path, 0);
            }
            self.out.push_str("+++\n\n");
        }
        // Body
        let body_path: Vec<BreadcrumbSegment> = Vec::new();
        match &self.doc.body {
            Value::Table(t) => self.emit_table_block(t, &body_path, 0),
            Value::UnorderedTable(t) => {
                // Lite-mode emit on an unordered Document: iterate the
                // HashMap directly. Full-mode emit is gated upstream by
                // `encode()`, which returns
                // `Err(EncodeError::UnorderedInFullMode)` before we get
                // here.
                self.emit_unordered_table_block(t, &body_path, 0);
            }
            Value::List(items) => self.emit_list_block(items, &body_path, 0),
            other => {
                // Scalar root: emit any leading comments, then the value
                // on its own line, then trailing.
                let leading: Vec<&Comment> = self
                    .comments_by_path
                    .get(&body_path)
                    .map(|nc| nc.leading.iter().copied().collect())
                    .unwrap_or_default();
                for c in leading {
                    self.emit_comment_line(c, 0);
                }
                self.emit_value_inline(other, &body_path);
                self.emit_trailing_for(&body_path);
                self.out.push('\n');
                let floating: Vec<&Comment> = self
                    .comments_by_path
                    .get(&body_path)
                    .map(|nc| nc.floating.iter().copied().collect())
                    .unwrap_or_default();
                for c in floating {
                    self.emit_comment_line(c, 0);
                }
            }
        }
    }

    fn emit_table_block(
        &mut self,
        t: &DmsMap<Value>,
        path: &[BreadcrumbSegment],
        indent: usize,
    ) {
        for (k, v) in t {
            let mut child_path: Vec<BreadcrumbSegment> = path.to_vec();
            child_path.push(BreadcrumbSegment::Key(k.clone()));
            // Leading comments for this child node
            if let Some(nc) = self.comments_by_path.get(&child_path) {
                let leading: Vec<&Comment> = nc.leading.iter().copied().collect();
                for c in leading {
                    self.emit_comment_line(c, indent);
                }
            }
            // Leading decorators for this child node (after comments)
            self.emit_leading_decorators_for(&child_path, indent);
            // The "key:" line. For block-form children (non-empty
            // table/list), we use `key:\n` then a deeper-indented block;
            // for inline values, `key: value`.
            //
            // Exception: if the container has a trailing comment AND its
            // contents are all flow-safe (scalars + nested flow-safe
            // containers, no heredocs, no comments inside), we emit it
            // as flow form so the trailing comment can sit on the same
            // line. Block-form would force us to emit `key:\n  # ...`,
            // which the parser rejects (`:<space>#` is not valid
            // inline-value syntax).
            let has_trailing = self
                .comments_by_path
                .get(&child_path)
                .map(|nc| !nc.trailing.is_empty())
                .unwrap_or(false)
                || self
                    .decorators_by_path
                    .get(&child_path)
                    .map(|nd| !nd.trailing.is_empty())
                    .unwrap_or(false);
            let has_inner = self.has_inner(&child_path)
                || self
                    .decorators_by_path
                    .get(&child_path)
                    .map(|nd| !nd.inner.is_empty())
                    .unwrap_or(false);
            let can_block = matches!(v,
                Value::Table(tt) if !tt.is_empty()
            ) || matches!(v,
                Value::UnorderedTable(tt) if !tt.is_empty()
            ) || matches!(v,
                Value::List(items) if !items.is_empty()
            );
            let needs_block = can_block
                && !(has_trailing && self.is_flow_safe(v, &child_path));
            self.push_indent(indent);
            self.out.push_str(&format_key(k));
            self.out.push(':');
            if self.suppressed_paths.contains(&child_path) {
                // Suppression takes priority over block-form: body emission is
                // omitted entirely. Used for inner decoration-only form (body
                // equals empty_default) AND for flow re-fold (body folded into
                // decorator params). Emit `key: |dec` with no value token.
                self.out.push(' ');
                self.emit_inner_decorators_for(&child_path);
                // trim trailing space left by emit_inner_decorators_for
                if self.out.ends_with(' ') {
                    self.out.pop();
                }
                self.out.push('\n');
            } else if needs_block {
                // `key: /* inner */ <newline>` — inner sits between
                // the colon and the EOL that opens the child block.
                if has_inner {
                    self.out.push(' ');
                    self.emit_inner_for(&child_path);
                    self.emit_inner_decorators_for(&child_path);
                    // trim trailing space
                    if self.out.ends_with(' ') {
                        self.out.pop();
                    }
                }
                self.out.push('\n');
                match v {
                    Value::Table(tt) => self.emit_table_block(tt, &child_path, indent + 1),
                    Value::UnorderedTable(tt) => {
                        self.emit_unordered_table_block(tt, &child_path, indent + 1)
                    }
                    Value::List(items) => self.emit_list_block(items, &child_path, indent + 1),
                    _ => unreachable!(),
                }
            } else {
                self.out.push(' ');
                self.emit_inner_for(&child_path);
                self.emit_inner_decorators_for(&child_path);
                self.emit_value_inline(v, &child_path);
                self.emit_trailing_for(&child_path);
                self.emit_trailing_decorators_for(&child_path);
                self.out.push('\n');
            }
        }
        // Floating comments + decorators attached to this container
        self.emit_floating(path, indent);
    }

    /// Lite-mode-only counterpart of `emit_table_block` for unordered
    /// tables (HashMap-backed). Iteration order is arbitrary. Full-mode
    /// emit is gated upstream by `encode()`, which returns an error
    /// before this is reached. SPEC §"Unordered tables".
    fn emit_unordered_table_block(
        &mut self,
        t: &DmsHashMap<Value>,
        path: &[BreadcrumbSegment],
        indent: usize,
    ) {
        for (k, v) in t {
            let mut child_path: Vec<BreadcrumbSegment> = path.to_vec();
            child_path.push(BreadcrumbSegment::Key(k.clone()));
            // (Lite mode has no comment_by_path entries; the lookup
            // calls below are no-ops, but kept for symmetry with the
            // ordered variant in case a caller constructs an
            // UnorderedTable Document with comments by hand.)
            if let Some(nc) = self.comments_by_path.get(&child_path) {
                let leading: Vec<&Comment> = nc.leading.iter().copied().collect();
                for c in leading {
                    self.emit_comment_line(c, indent);
                }
            }
            let has_trailing = self
                .comments_by_path
                .get(&child_path)
                .map(|nc| !nc.trailing.is_empty())
                .unwrap_or(false);
            let has_inner = self.has_inner(&child_path);
            let can_block = matches!(v,
                Value::Table(tt) if !tt.is_empty()
            ) || matches!(v,
                Value::UnorderedTable(tt) if !tt.is_empty()
            ) || matches!(v,
                Value::List(items) if !items.is_empty()
            );
            let needs_block = can_block
                && !(has_trailing && self.is_flow_safe(v, &child_path));
            self.push_indent(indent);
            self.out.push_str(&format_key(k));
            self.out.push(':');
            if needs_block {
                if has_inner {
                    self.out.push(' ');
                    self.emit_inner_for(&child_path);
                    if self.out.ends_with(' ') {
                        self.out.pop();
                    }
                }
                self.out.push('\n');
                match v {
                    Value::Table(tt) => self.emit_table_block(tt, &child_path, indent + 1),
                    Value::UnorderedTable(tt) => {
                        self.emit_unordered_table_block(tt, &child_path, indent + 1)
                    }
                    Value::List(items) => self.emit_list_block(items, &child_path, indent + 1),
                    _ => unreachable!(),
                }
            } else {
                self.out.push(' ');
                self.emit_inner_for(&child_path);
                self.emit_value_inline(v, &child_path);
                self.emit_trailing_for(&child_path);
                self.out.push('\n');
            }
        }
        self.emit_floating(path, indent);
    }

    fn emit_list_block(
        &mut self,
        items: &[Value],
        path: &[BreadcrumbSegment],
        indent: usize,
    ) {
        for (i, v) in items.iter().enumerate() {
            let mut child_path: Vec<BreadcrumbSegment> = path.to_vec();
            child_path.push(BreadcrumbSegment::Index(i));
            if let Some(nc) = self.comments_by_path.get(&child_path) {
                let leading: Vec<&Comment> = nc.leading.iter().copied().collect();
                for c in leading {
                    self.emit_comment_line(c, indent);
                }
            }
            // Leading decorators for this list item
            self.emit_leading_decorators_for(&child_path, indent);
            self.push_indent(indent);
            self.out.push('+');
            let has_inner = self.has_inner(&child_path)
                || self
                    .decorators_by_path
                    .get(&child_path)
                    .map(|nd| !nd.inner.is_empty())
                    .unwrap_or(false);
            if self.suppressed_paths.contains(&child_path) {
                // Suppression takes priority: body emission is omitted entirely.
                // Used for inner decoration-only form AND flow re-fold. Emit
                // `+ |dec` with no value token.
                self.out.push(' ');
                self.emit_inner_decorators_for(&child_path);
                if self.out.ends_with(' ') {
                    self.out.pop();
                }
                self.out.push('\n');
            } else {
            match v {
                Value::Table(tt) if !tt.is_empty() => {
                    // `+ /* inner */[EOL]<indent><first key>:`
                    if has_inner {
                        self.out.push(' ');
                        self.emit_inner_for(&child_path);
                        self.emit_inner_decorators_for(&child_path);
                        if self.out.ends_with(' ') {
                            self.out.pop();
                        }
                    }
                    self.emit_trailing_for(&child_path);
                    self.emit_trailing_decorators_for(&child_path);
                    self.out.push('\n');
                    self.emit_table_block(tt, &child_path, indent + 1);
                }
                Value::UnorderedTable(tt) if !tt.is_empty() => {
                    if has_inner {
                        self.out.push(' ');
                        self.emit_inner_for(&child_path);
                        self.emit_inner_decorators_for(&child_path);
                        if self.out.ends_with(' ') {
                            self.out.pop();
                        }
                    }
                    self.emit_trailing_for(&child_path);
                    self.emit_trailing_decorators_for(&child_path);
                    self.out.push('\n');
                    self.emit_unordered_table_block(tt, &child_path, indent + 1);
                }
                Value::List(inner) if !inner.is_empty() => {
                    if has_inner {
                        self.out.push(' ');
                        self.emit_inner_for(&child_path);
                        self.emit_inner_decorators_for(&child_path);
                        if self.out.ends_with(' ') {
                            self.out.pop();
                        }
                    }
                    self.emit_trailing_for(&child_path);
                    self.emit_trailing_decorators_for(&child_path);
                    self.out.push('\n');
                    self.emit_list_block(inner, &child_path, indent + 1);
                }
                _ => {
                    self.out.push(' ');
                    self.emit_inner_for(&child_path);
                    self.emit_inner_decorators_for(&child_path);
                    self.emit_value_inline(v, &child_path);
                    self.emit_trailing_for(&child_path);
                    self.emit_trailing_decorators_for(&child_path);
                    self.out.push('\n');
                }
            }
            } // end !suppressed
        }
        self.emit_floating(path, indent);
    }

    fn emit_value_inline(&mut self, v: &Value, path: &[BreadcrumbSegment]) {
        match v {
            Value::Bool(b) => self.out.push_str(if *b { "true" } else { "false" }),
            Value::Integer(n) => self.emit_integer(*n, path),
            Value::Float(f) => self.emit_float(*f),
            Value::String(s) => self.emit_string(s, path),
            Value::OffsetDateTime(s)
            | Value::LocalDateTime(s)
            | Value::LocalDate(s)
            | Value::LocalTime(s) => self.out.push_str(s),
            Value::List(items) => {
                if items.is_empty() {
                    self.out.push_str("[]");
                } else {
                    // Non-empty list emitted as flow form would clash with
                    // our block-form rule, but inline contexts only arrive
                    // here for empty lists (block-form path takes
                    // non-empty). Defensive: emit flow-form.
                    self.out.push('[');
                    for (i, item) in items.iter().enumerate() {
                        if i > 0 {
                            self.out.push_str(", ");
                        }
                        let mut sub_path: Vec<BreadcrumbSegment> = path.to_vec();
                        sub_path.push(BreadcrumbSegment::Index(i));
                        self.emit_value_inline(item, &sub_path);
                    }
                    self.out.push(']');
                }
            }
            Value::Table(t) => {
                if t.is_empty() {
                    self.out.push_str("{}");
                } else {
                    self.out.push('{');
                    let mut first = true;
                    for (k, vv) in t {
                        if !first {
                            self.out.push_str(", ");
                        }
                        first = false;
                        self.out.push_str(&format_key(k));
                        self.out.push_str(": ");
                        let mut sub_path: Vec<BreadcrumbSegment> = path.to_vec();
                        sub_path.push(BreadcrumbSegment::Key(k.clone()));
                        self.emit_value_inline(vv, &sub_path);
                    }
                    self.out.push('}');
                }
            }
            Value::UnorderedTable(t) => {
                if t.is_empty() {
                    self.out.push_str("{}");
                } else {
                    self.out.push('{');
                    let mut first = true;
                    for (k, vv) in t {
                        if !first {
                            self.out.push_str(", ");
                        }
                        first = false;
                        self.out.push_str(&format_key(k));
                        self.out.push_str(": ");
                        let mut sub_path: Vec<BreadcrumbSegment> = path.to_vec();
                        sub_path.push(BreadcrumbSegment::Key(k.clone()));
                        self.emit_value_inline(vv, &sub_path);
                    }
                    self.out.push('}');
                }
            }
        }
    }

    fn emit_integer(&mut self, n: i64, path: &[BreadcrumbSegment]) {
        if let Some(lit_ref) = self.forms_by_path.get(path).copied() {
            if let OriginalLiteral::Integer { lit } = lit_ref {
                self.out.push_str(lit.as_str());
                return;
            }
        }
        self.out.push_str(&n.to_string());
    }

    fn emit_float(&mut self, f: f64) {
        if f.is_nan() {
            self.out.push_str("nan");
        } else if f.is_infinite() {
            self.out.push_str(if f > 0.0 { "inf" } else { "-inf" });
        } else {
            let mut buf = ryu::Buffer::new();
            self.out.push_str(buf.format(f));
        }
    }

    fn emit_string(&mut self, s: &str, path: &[BreadcrumbSegment]) {
        let form_opt = self
            .forms_by_path
            .get(path)
            .and_then(|lit| match lit {
                OriginalLiteral::String { form } => Some(form.clone()),
                _ => None,
            });
        let form = form_opt.unwrap_or(StringForm::Basic);
        match form {
            StringForm::Basic => {
                self.out.push('"');
                self.out.push_str(&escape_basic(s));
                self.out.push('"');
            }
            StringForm::Literal => {
                self.out.push('\'');
                self.out.push_str(s);
                self.out.push('\'');
            }
            StringForm::Heredoc { flavor, label, modifiers } => {
                // The stored body is post-modifier. For byte-stable
                // round-trips, the emitted source must re-produce the
                // same post-modifier value under re-application. For
                // idempotent modifiers this is mostly automatic; for
                // `_fold_paragraphs()` (which joins lines within a
                // paragraph with spaces), we pre-expand each `\n` in
                // the stored value into a `\n\n` paragraph break so
                // that the re-applied modifier preserves (not merges)
                // line boundaries.
                let body_to_emit = if modifiers.iter().any(|m| m.name == "_fold_paragraphs") {
                    s.replace('\n', "\n\n")
                } else {
                    s.to_string()
                };
                self.emit_heredoc(&body_to_emit, flavor, label.as_deref(), &modifiers);
            }
        }
    }

    fn emit_heredoc(
        &mut self,
        body: &str,
        flavor: HeredocFlavor,
        label: Option<&str>,
        modifiers: &[HeredocModifierCall],
    ) {
        // The "current line" the kvpair was just written on already has
        // text up to and including ": " (or "+ "). The caller's
        // `emit_value_inline` placed us right after the space. We compute
        // the kvpair's indent from the most recent newline in `out`.
        let kv_indent_spaces = {
            let bytes = self.out.as_bytes();
            let mut last_nl = None;
            for i in (0..bytes.len()).rev() {
                if bytes[i] == b'\n' {
                    last_nl = Some(i);
                    break;
                }
            }
            let line_start = last_nl.map(|i| i + 1).unwrap_or(0);
            // count leading spaces on this line
            let mut k = line_start;
            let mut n = 0usize;
            while k < bytes.len() && bytes[k] == b' ' {
                n += 1;
                k += 1;
            }
            n
        };
        let body_indent_str = " ".repeat(kv_indent_spaces + INDENT_STR.len());
        let term_indent_str = " ".repeat(kv_indent_spaces + INDENT_STR.len());
        let opener = match flavor {
            HeredocFlavor::BasicTriple => "\"\"\"",
            HeredocFlavor::LiteralTriple => "'''",
        };
        self.out.push_str(opener);
        if let Some(lbl) = label {
            self.out.push_str(lbl);
        }
        for m in modifiers {
            self.out.push(' ');
            self.out.push_str(&m.name);
            self.out.push('(');
            for (i, a) in m.args.iter().enumerate() {
                if i > 0 {
                    self.out.push_str(", ");
                }
                self.emit_modifier_arg(a);
            }
            self.out.push(')');
        }
        self.out.push('\n');
        // Body lines, indented to body_indent_str. The body is the
        // post-strip content as stored in Value::String — to round-trip
        // through the parser, we re-indent each line to body_indent and
        // emit a final body line that is empty (so the terminator
        // appears alone on its line). The parser's strip-indent logic
        // then yields the same content.
        if body.is_empty() {
            // Emit just the terminator on its own line.
        } else {
            for line in body.split('\n') {
                if line.is_empty() {
                    // Blank source line — output just newline (no
                    // indentation prefix, matches strip-indent rule).
                    self.out.push('\n');
                } else {
                    self.out.push_str(&body_indent_str);
                    self.out.push_str(line);
                    self.out.push('\n');
                }
            }
        }
        // Terminator
        self.out.push_str(&term_indent_str);
        let terminator = match (flavor, label) {
            (HeredocFlavor::BasicTriple, None) => "\"\"\"".to_string(),
            (HeredocFlavor::LiteralTriple, None) => "'''".to_string(),
            (_, Some(lbl)) => lbl.to_string(),
        };
        self.out.push_str(&terminator);
    }

    fn emit_modifier_arg(&mut self, v: &Value) {
        match v {
            Value::Bool(b) => self.out.push_str(if *b { "true" } else { "false" }),
            Value::Integer(n) => self.out.push_str(&n.to_string()),
            Value::Float(f) => {
                if f.is_nan() {
                    self.out.push_str("nan");
                } else if f.is_infinite() {
                    self.out.push_str(if *f > 0.0 { "inf" } else { "-inf" });
                } else {
                    let mut buf = ryu::Buffer::new();
                    self.out.push_str(buf.format(*f));
                }
            }
            Value::String(s) => {
                self.out.push('"');
                self.out.push_str(&escape_basic(s));
                self.out.push('"');
            }
            Value::OffsetDateTime(s)
            | Value::LocalDateTime(s)
            | Value::LocalDate(s)
            | Value::LocalTime(s) => self.out.push_str(s),
            Value::List(_) | Value::Table(_) | Value::UnorderedTable(_) => {
                // Modifier args are scalars in practice; defensive
                // fallback emits empty container literal.
                if matches!(v, Value::List(_)) {
                    self.out.push_str("[]");
                } else {
                    self.out.push_str("{}");
                }
            }
        }
    }

    fn emit_comment_line(&mut self, c: &Comment, indent: usize) {
        // The comment's `content` field preserves its original internal
        // whitespace verbatim (block-comment body lines retain their
        // own indentation, line comments are single-line text). Only
        // the FIRST line gets re-indented to the current emit context;
        // subsequent body lines keep their stored indentation, so a
        // round-trip is byte-stable. The terminator on a `###LABEL`
        // block sits on its own line, also stored verbatim.
        let text = &c.content;
        let prefix = INDENT_STR.repeat(indent);
        if !text.contains('\n') {
            self.out.push_str(&prefix);
            self.out.push_str(text);
            self.out.push('\n');
            return;
        }
        let mut first = true;
        for line in text.split('\n') {
            if !first {
                self.out.push('\n');
            }
            if first {
                self.out.push_str(&prefix);
                first = false;
            }
            self.out.push_str(line);
        }
        self.out.push('\n');
    }

    fn emit_trailing_for(&mut self, path: &[BreadcrumbSegment]) {
        if let Some(nc) = self.comments_by_path.get(path) {
            let mut first = true;
            for t in &nc.trailing {
                if first {
                    self.out.push_str("  ");
                    first = false;
                } else {
                    self.out.push(' ');
                }
                self.out.push_str(&c_oneliner(t));
            }
        }
    }

    fn emit_inner_for(&mut self, path: &[BreadcrumbSegment]) {
        if let Some(nc) = self.comments_by_path.get(path) {
            for c in &nc.inner {
                self.out.push_str(&c_oneliner(c));
                self.out.push(' ');
            }
        }
    }

    fn has_inner(&self, path: &[BreadcrumbSegment]) -> bool {
        self.comments_by_path
            .get(path)
            .map(|nc| !nc.inner.is_empty())
            .unwrap_or(false)
    }

    fn emit_floating(&mut self, path: &[BreadcrumbSegment], indent: usize) {
        if let Some(nc) = self.comments_by_path.get(path) {
            let floating: Vec<&Comment> = nc.floating.iter().copied().collect();
            for c in floating {
                self.emit_comment_line(c, indent);
            }
        }
        // Floating decorators at same path, after comments.
        if let Some(nd) = self.decorators_by_path.get(path) {
            let floating: Vec<&tier1::DecoratorCall> = nd.floating.iter().copied().collect();
            for call in floating {
                self.push_indent(indent);
                self.emit_decorator_call(call);
                self.out.push('\n');
            }
        }
    }

    /// Emit leading decorators for a path (own lines, before the value line).
    /// Call this after comment leading emission at the same path.
    fn emit_leading_decorators_for(&mut self, path: &[BreadcrumbSegment], indent: usize) {
        if let Some(nd) = self.decorators_by_path.get(path) {
            let leading: Vec<&tier1::DecoratorCall> = nd.leading.iter().copied().collect();
            for call in leading {
                self.push_indent(indent);
                self.emit_decorator_call(call);
                self.out.push('\n');
            }
        }
    }

    /// Emit inner decorators for a path (between key: and value, same line).
    /// Call this after comment inner emission at the same path.
    fn emit_inner_decorators_for(&mut self, path: &[BreadcrumbSegment]) {
        if let Some(nd) = self.decorators_by_path.get(path) {
            let inner: Vec<&tier1::DecoratorCall> = nd.inner.iter().copied().collect();
            for call in inner {
                self.emit_decorator_call(call);
                self.out.push(' ');
            }
        }
    }

    /// Emit trailing decorators for a path (after value, same line, before EOL).
    /// Call this after comment trailing emission at the same path.
    fn emit_trailing_decorators_for(&mut self, path: &[BreadcrumbSegment]) {
        if let Some(nd) = self.decorators_by_path.get(path) {
            let trailing: Vec<&tier1::DecoratorCall> = nd.trailing.iter().copied().collect();
            for call in trailing {
                self.out.push(' ');
                self.emit_decorator_call(call);
            }
        }
    }

    /// Emit one decorator call: `<sigil><name>[(group)...]`.
    /// Bare form when params is a single empty Named group.
    /// Respects `call_style`: Nameless calls emit `<sigil>` with no name.
    fn emit_decorator_call(&mut self, call: &tier1::DecoratorCall) {
        self.out.push_str(&call.sigil);
        if call.call_style == tier1::CallStyle::Named {
            // Build name: ns.fn or just fn
            let name = match &call.ns {
                Some(ns) => format!("{}.{}", ns, call.fn_name),
                None => call.fn_name.clone(),
            };
            self.out.push_str(&name);
        }
        // Nameless form: sigil only — no name emitted.

        // Bare form: single Named(empty) → no parens at all.
        if call.params.len() == 1 {
            if let tier1::ParamGroup::Named(m) = &call.params[0] {
                if m.is_empty() {
                    // bare form — emit nothing
                    return;
                }
            }
        }

        // Otherwise emit each group as `(...)`.
        for group in &call.params {
            self.out.push('(');
            match group {
                tier1::ParamGroup::Named(m) => {
                    let mut first = true;
                    for (k, v) in m {
                        if !first {
                            self.out.push_str(", ");
                        }
                        first = false;
                        self.out.push_str(&format_key(k));
                        self.out.push_str(": ");
                        let s = fmt_value_inline(v);
                        self.out.push_str(&s);
                    }
                }
                tier1::ParamGroup::Positional(items) => {
                    let mut first = true;
                    for v in items {
                        if !first {
                            self.out.push_str(", ");
                        }
                        first = false;
                        let s = fmt_value_inline(v);
                        self.out.push_str(&s);
                    }
                }
            }
            self.out.push(')');
        }
    }

    fn push_indent(&mut self, indent: usize) {
        for _ in 0..indent {
            self.out.push_str(INDENT_STR);
        }
    }

    /// True if `v` (rooted at `path`) can be safely emitted as a flow
    /// form: no heredoc strings (heredocs require own line), no
    /// comments attached to any descendant. Used to decide flow-vs-block
    /// when a trailing comment forces flow form.
    fn is_flow_safe(&self, v: &Value, path: &[BreadcrumbSegment]) -> bool {
        // Any descendant comment ⇒ unsafe, since flow form has no
        // place to put it. Skipped in lite mode (no comments emitted
        // anyway). We check by scanning all comment paths.
        if !self.lite {
            for ac in &self.doc.comments {
                if ac.path.len() > path.len() && ac.path.starts_with(path) {
                    // descendant has a comment
                    return false;
                }
            }
        }
        match v {
            Value::String(_) => {
                // If the string's original form is a heredoc, it's not
                // flow-safe (heredocs require their own line).
                if let Some(OriginalLiteral::String { form: StringForm::Heredoc { .. } }) =
                    self.forms_by_path.get(path).copied()
                {
                    return false;
                }
                true
            }
            Value::List(items) => {
                for (i, item) in items.iter().enumerate() {
                    let mut sub: Vec<BreadcrumbSegment> = path.to_vec();
                    sub.push(BreadcrumbSegment::Index(i));
                    if !self.is_flow_safe(item, &sub) {
                        return false;
                    }
                }
                true
            }
            Value::Table(t) => {
                for (k, vv) in t {
                    let mut sub: Vec<BreadcrumbSegment> = path.to_vec();
                    sub.push(BreadcrumbSegment::Key(k.clone()));
                    if !self.is_flow_safe(vv, &sub) {
                        return false;
                    }
                }
                true
            }
            Value::UnorderedTable(t) => {
                for (k, vv) in t {
                    let mut sub: Vec<BreadcrumbSegment> = path.to_vec();
                    sub.push(BreadcrumbSegment::Key(k.clone()));
                    if !self.is_flow_safe(vv, &sub) {
                        return false;
                    }
                }
                true
            }
            _ => true,
        }
    }
}

/// Emit a comment whose content fits on one line, returning the text to
/// place after a value (no leading whitespace included). For block
/// comments that span multiple lines, the result still contains
/// newlines — only used in the `emit_trailing_for` path where the
/// parser invariant guarantees a single-line trailing comment.
fn c_oneliner(c: &Comment) -> String {
    c.content.clone()
}

/// Serialize a `Value` to inline string form for use in decorator param groups.
/// Handles scalar values and flow containers. Heredoc strings are emitted as
/// basic-quoted strings (lossy but valid for round-trip).
fn fmt_value_inline(v: &Value) -> String {
    match v {
        Value::Bool(b) => (if *b { "true" } else { "false" }).to_string(),
        Value::Integer(n) => n.to_string(),
        Value::Float(f) => {
            if f.is_nan() {
                "nan".to_string()
            } else if f.is_infinite() {
                if *f > 0.0 { "inf".to_string() } else { "-inf".to_string() }
            } else {
                let mut buf = ryu::Buffer::new();
                buf.format(*f).to_string()
            }
        }
        Value::String(s) => {
            format!("\"{}\"", escape_basic(s))
        }
        Value::OffsetDateTime(s)
        | Value::LocalDateTime(s)
        | Value::LocalDate(s)
        | Value::LocalTime(s) => s.clone(),
        Value::List(items) => {
            let mut out = String::from("[");
            for (i, item) in items.iter().enumerate() {
                if i > 0 { out.push_str(", "); }
                out.push_str(&fmt_value_inline(item));
            }
            out.push(']');
            out
        }
        Value::Table(t) => {
            let mut out = String::from("{");
            let mut first = true;
            for (k, vv) in t {
                if !first { out.push_str(", "); }
                first = false;
                out.push_str(&format_key(k));
                out.push_str(": ");
                out.push_str(&fmt_value_inline(vv));
            }
            out.push('}');
            out
        }
        Value::UnorderedTable(t) => {
            let mut out = String::from("{");
            let mut first = true;
            for (k, vv) in t {
                if !first { out.push_str(", "); }
                first = false;
                out.push_str(&format_key(k));
                out.push_str(": ");
                out.push_str(&fmt_value_inline(vv));
            }
            out.push('}');
            out
        }
    }
}

fn escape_basic(s: &str) -> String {
    let mut out = String::with_capacity(s.len());
    for c in s.chars() {
        match c {
            '\\' => out.push_str("\\\\"),
            '"' => out.push_str("\\\""),
            '\n' => out.push_str("\\n"),
            '\r' => out.push_str("\\r"),
            '\t' => out.push_str("\\t"),
            '\u{08}' => out.push_str("\\b"),
            '\u{0c}' => out.push_str("\\f"),
            c if (c as u32) < 0x20 => {
                out.push_str(&format!("\\u{:04X}", c as u32));
            }
            c => out.push(c),
        }
    }
    out
}

fn format_key(k: &str) -> String {
    // If the key is a valid bare key (and non-empty), emit bare;
    // otherwise quote it. Bare key: `[A-Za-z0-9_-]+` plus unicode
    // letters/digits per `is_bare_key_char`.
    if !k.is_empty() && k.chars().all(is_bare_key_char) {
        k.to_string()
    } else {
        // Use literal quoting if the key contains no single quotes,
        // basic otherwise.
        if !k.contains('\'') && !k.contains('\n') && !k.contains('\r') {
            format!("'{}'", k)
        } else {
            format!("\"{}\"", escape_basic(k))
        }
    }
}

// ---------- tests ----------

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

    fn parse_table(src: &str) -> DmsMap<Value> {
        match decode(src).expect("decode failed") {
            Value::Table(t) => t,
            other => panic!("expected table, got {other:?}"),
        }
    }

    #[test]
    fn empty_doc() {
        assert!(parse_table("").is_empty());
    }

    #[test]
    fn single_int() {
        let t = parse_table("n: 42\n");
        assert_eq!(t["n"], Value::Integer(42));
    }

    #[test]
    fn hex_int() {
        let t = parse_table("n: 0xFF\n");
        assert_eq!(t["n"], Value::Integer(255));
    }

    #[test]
    fn float_dec() {
        let t = parse_table("n: 3.14\n");
        if let Value::Float(f) = t["n"] {
            assert!((f - 3.14).abs() < 1e-12);
        } else {
            panic!();
        }
    }

    #[test]
    fn float_inf() {
        let t = parse_table("n: inf\n");
        assert_eq!(t["n"], Value::Float(f64::INFINITY));
    }

    #[test]
    fn flow_array() {
        let t = parse_table("xs: [1, 2, 3]\n");
        if let Value::List(v) = &t["xs"] {
            assert_eq!(v.len(), 3);
        } else {
            panic!();
        }
    }

    #[test]
    fn flow_table() {
        let t = parse_table("p: {x: 1, y: 2}\n");
        if let Value::Table(v) = &t["p"] {
            assert_eq!(v.len(), 2);
        } else {
            panic!();
        }
    }

    #[test]
    fn nested_table() {
        let t = parse_table("a:\n  b: 1\n  c: 2\n");
        if let Value::Table(v) = &t["a"] {
            assert_eq!(v.len(), 2);
        } else {
            panic!();
        }
    }

    #[test]
    fn nested_list() {
        let t = parse_table("xs:\n  + 1\n  + 2\n  + 3\n");
        if let Value::List(v) = &t["xs"] {
            assert_eq!(v.len(), 3);
        } else {
            panic!();
        }
    }

    #[test]
    fn list_of_tables() {
        let src = "servers:\n  + name: \"web1\"\n    port: 80\n  + name: \"web2\"\n    port: 81\n";
        let t = parse_table(src);
        if let Value::List(v) = &t["servers"] {
            assert_eq!(v.len(), 2);
        } else {
            panic!();
        }
    }

    #[test]
    fn heredoc_basic() {
        let src = "doc: \"\"\"EOF\n    hello\n    world\n    EOF\n";
        let t = parse_table(src);
        assert_eq!(t["doc"], Value::String("hello\nworld".into()));
    }

    #[test]
    fn date_only() {
        let t = parse_table("d: 1979-05-27\n");
        assert_eq!(t["d"], Value::LocalDate("1979-05-27".into()));
    }

    #[test]
    fn offset_dt() {
        let t = parse_table("d: 1979-05-27T07:32:00Z\n");
        assert_eq!(t["d"], Value::OffsetDateTime("1979-05-27T07:32:00Z".into()));
    }

    #[test]
    fn rejects_tier1_in_front_matter() {
        let err = decode("+++\n_dms_tier: 1\n+++\nx: 1\n").unwrap_err();
        // TIER1.md §"Behavior at the boundary" mandates an
        // actionable forward-compat message that points the
        // caller at `decode_t1`.
        assert!(
            err.message.contains("decode_t1"),
            "expected tier-1 rejection to mention decode_t1, got: {}",
            err.message
        );
    }

    #[test]
    fn accepts_explicit_tier_zero() {
        let t = match decode_document("+++\n_dms_tier: 0\n+++\nx: 1\n").unwrap().body {
            Value::Table(t) => t,
            other => panic!("expected table, got {other:?}"),
        };
        assert_eq!(t["x"], Value::Integer(1));
    }

    // ----- comment-attachment tests (tier-0 feature) -----

    fn key(s: &str) -> BreadcrumbSegment {
        BreadcrumbSegment::Key(s.to_string())
    }

    #[test]
    fn comment_leading_attaches_to_next_kvpair() {
        // # leading\nport: 8080
        let doc = decode_document("# leading\nport: 8080\n").unwrap();
        assert_eq!(doc.comments.len(), 1);
        let ac = &doc.comments[0];
        assert_eq!(ac.position, CommentPosition::Leading);
        assert_eq!(ac.path, vec![key("port")]);
        assert_eq!(ac.comment.kind, CommentKind::Line);
        assert_eq!(ac.comment.content, "# leading");
    }

    #[test]
    fn comment_blank_line_gap_is_floating_on_container() {
        // # floating\n\nport: 8080  → blank line separates → floating on root
        let doc = decode_document("# floating\n\nport: 8080\n").unwrap();
        assert_eq!(doc.comments.len(), 1);
        let ac = &doc.comments[0];
        assert_eq!(ac.position, CommentPosition::Floating);
        // root path
        assert!(ac.path.is_empty(), "expected empty path, got {:?}", ac.path);
        assert_eq!(ac.comment.content, "# floating");
    }

    #[test]
    fn comment_trailing_on_same_line() {
        // port: 8080   # default
        let doc = decode_document("port: 8080   # default\n").unwrap();
        assert_eq!(doc.comments.len(), 1);
        let ac = &doc.comments[0];
        assert_eq!(ac.position, CommentPosition::Trailing);
        assert_eq!(ac.path, vec![key("port")]);
        assert_eq!(ac.comment.content, "# default");
    }

    #[test]
    fn comment_floating_at_end_of_block() {
        // a:\n  x: 1\n  # leftover            (no sibling follows in `a`)
        let src = "a:\n  x: 1\n  # leftover\n";
        let doc = decode_document(src).unwrap();
        assert_eq!(doc.comments.len(), 1);
        let ac = &doc.comments[0];
        assert_eq!(ac.position, CommentPosition::Floating);
        assert_eq!(ac.path, vec![key("a")]);
        assert_eq!(ac.comment.content, "# leftover");
    }

    #[test]
    fn block_comment_attaches_as_leading() {
        let src = "###\nNOTE\n###\nport: 8080\n";
        let doc = decode_document(src).unwrap();
        assert_eq!(doc.comments.len(), 1);
        let ac = &doc.comments[0];
        assert_eq!(ac.position, CommentPosition::Leading);
        assert_eq!(ac.path, vec![key("port")]);
        assert_eq!(ac.comment.kind, CommentKind::Block);
        assert!(
            ac.comment.content.starts_with("###") && ac.comment.content.ends_with("###"),
            "expected delimiters preserved, got: {:?}",
            ac.comment.content
        );
    }

    #[test]
    fn front_matter_comment_recorded_with_fm_prefix() {
        // +++\n# meta-leading\nauthor: \"x\"\n+++\nbody: 1\n
        let src = "+++\n# meta-leading\nauthor: \"x\"\n+++\nbody: 1\n";
        let doc = decode_document(src).unwrap();
        assert_eq!(doc.comments.len(), 1);
        let ac = &doc.comments[0];
        assert_eq!(ac.position, CommentPosition::Leading);
        assert_eq!(ac.path, vec![key("__fm__"), key("author")]);
        assert_eq!(ac.comment.content, "# meta-leading");
    }

    #[test]
    fn document_with_no_comments_has_empty_comments_vec() {
        let doc = decode_document("a: 1\nb: 2\n").unwrap();
        assert!(doc.comments.is_empty(), "expected no comments, got {:?}", doc.comments);
    }

    // ----- encode emitter tests (round-trip contract) -----

    fn roundtrip(src: &str) -> String {
        let doc = decode_document(src).expect("parse failed");
        encode(&doc).expect("encode failed")
    }

    #[test]
    fn encode_int_base_preserved() {
        let src = "a: 0x1F40\nb: 0o755\nc: 0b1010_0110\nd: 1_000_000\ne: +42\nf: -7\n";
        let doc = decode_document(src).unwrap();
        let out = encode(&doc).unwrap();
        assert!(out.contains("a: 0x1F40"), "out:\n{out}");
        assert!(out.contains("b: 0o755"), "out:\n{out}");
        assert!(out.contains("c: 0b1010_0110"), "out:\n{out}");
        assert!(out.contains("d: 1_000_000"), "out:\n{out}");
        assert!(out.contains("e: +42"), "out:\n{out}");
        assert!(out.contains("f: -7"), "out:\n{out}");
        // round-trip preserves integer values
        let doc2 = decode_document(&out).unwrap();
        assert_eq!(doc.body, doc2.body);
    }

    #[test]
    fn encode_string_forms_preserved() {
        let src = concat!(
            "basic: \"hello\"\n",
            "lit: 'C:\\path'\n",
            "hd_b_lab: \"\"\"END\n",
            "  hello\n",
            "  END\n",
            "hd_b_unl: \"\"\"\n",
            "  one\n",
            "  \"\"\"\n",
            "hd_l_lab: '''END\n",
            "  raw\n",
            "  END\n",
            "hd_l_unl: '''\n",
            "  raw2\n",
            "  '''\n",
        );
        let doc = decode_document(src).unwrap();
        let out = encode(&doc).unwrap();
        assert!(out.contains("basic: \"hello\""), "out:\n{out}");
        assert!(out.contains("lit: 'C:\\path'"), "out:\n{out}");
        assert!(out.contains("\"\"\"END"), "out:\n{out}");
        assert!(out.contains("'''END"), "out:\n{out}");
        // Round-trip values match.
        let doc2 = decode_document(&out).unwrap();
        assert_eq!(doc.body, doc2.body);
    }

    #[test]
    fn encode_heredoc_modifiers_preserved() {
        let src = concat!(
            "msg: \"\"\"END _trim(\"\\n\", \">\")\n",
            "  >  hi\n",
            "  END\n",
        );
        let doc = decode_document(src).unwrap();
        let out = encode(&doc).unwrap();
        assert!(out.contains("_trim("), "expected _trim() in output:\n{out}");
        // Round-trip value match.
        let doc2 = decode_document(&out).unwrap();
        assert_eq!(doc.body, doc2.body);
    }

    #[test]
    fn encode_comments_at_attached_paths() {
        let src = concat!(
            "# leading on a\n",
            "a: 1   # trailing on a\n",
            "b:\n",
            "  x: 2\n",
            "  # floating in b\n",
        );
        let doc = decode_document(src).unwrap();
        let out = encode(&doc).unwrap();
        // Re-parse and check comment paths survived.
        let doc2 = decode_document(&out).unwrap();
        assert_eq!(doc2.comments.len(), 3);
        let mut have_leading = false;
        let mut have_trailing = false;
        let mut have_floating = false;
        for ac in &doc2.comments {
            match ac.position {
                CommentPosition::Leading => {
                    if ac.path == vec![key("a")] {
                        have_leading = true;
                    }
                }
                CommentPosition::Trailing => {
                    if ac.path == vec![key("a")] {
                        have_trailing = true;
                    }
                }
                CommentPosition::Floating => {
                    if ac.path == vec![key("b")] {
                        have_floating = true;
                    }
                }
                CommentPosition::Inner => { /* not produced by this fixture */ }
            }
        }
        assert!(have_leading && have_trailing && have_floating, "out:\n{out}\ncomments: {:?}", doc2.comments);
    }

    #[test]
    fn encode_front_matter_omitted_when_empty() {
        let src = "x: 1\n";
        let out = roundtrip(src);
        assert!(!out.contains("+++"), "expected no front matter in output:\n{out}");
    }

    #[test]
    fn encode_second_round_byte_stable() {
        let cases = [
            "a: 1\nb: 2\n",
            "# leading\nport: 0x1F40   # trailing\n",
            "+++\nauthor: \"x\"\n+++\nbody: 1\n",
            concat!(
                "msg: \"\"\"END\n",
                "  hello world\n",
                "  END\n",
                "ints:\n",
                "  + 0xFF\n",
                "  + 1_000\n",
            ),
            "items: [1, 2, 3]\np: {x: 1, y: 2}\n",
        ];
        for src in cases {
            let out1 = encode(&decode_document(src).unwrap()).unwrap();
            let out2 = encode(&decode_document(&out1).unwrap()).unwrap();
            assert_eq!(out1, out2, "round-trip not stable for src:\n{src}\nout1:\n{out1}\nout2:\n{out2}");
        }
    }

    // -- Modification scenarios (decode → edit → re-encode) --------------
    //
    // The SPEC §Comments §Round-trip semantics promises:
    //   "comments on still-present nodes travel with them; newly inserted
    //    nodes carry no comments; deleted nodes drop theirs."
    // These tests exercise that promise with explicit add / update / delete
    // mutations between parse and emit.

    fn count_comments_at_path(doc: &Document, path: &[BreadcrumbSegment]) -> usize {
        doc.comments.iter().filter(|c| c.path == path).count()
    }

    #[test]
    fn encode_value_update_preserves_attached_comments() {
        // Update a leaf value; leading + trailing comments on its kvpair
        // must travel with it.
        let src = "# the listening port\nport: 8080   # default for staging\nhost: \"localhost\"\n";
        let mut doc = decode_document(src).unwrap();
        if let Value::Table(ref mut t) = doc.body {
            // Replace 8080 with 5432.
            *t.get_mut("port").unwrap() = Value::Integer(5432);
        } else {
            panic!("expected table");
        }
        let emitted = encode(&doc).unwrap();
        let doc2 = decode_document(&emitted).unwrap();
        // Value updated.
        if let Value::Table(t) = &doc2.body {
            assert_eq!(t["port"], Value::Integer(5432));
        } else {
            panic!("expected table after re-parse");
        }
        // Comments still attached to `port`.
        let port = vec![BreadcrumbSegment::Key("port".to_string())];
        let leading = doc2.comments.iter().filter(|c| c.path == port && c.position == CommentPosition::Leading).count();
        let trailing = doc2.comments.iter().filter(|c| c.path == port && c.position == CommentPosition::Trailing).count();
        assert_eq!(leading, 1, "leading comment on `port` should survive update; got doc2.comments = {:?}", doc2.comments);
        assert_eq!(trailing, 1, "trailing comment on `port` should survive update; got doc2.comments = {:?}", doc2.comments);
    }

    #[test]
    fn encode_deleted_key_drops_attached_comments() {
        // Delete a kvpair; its leading + trailing comments must NOT
        // survive (the node they attached to is gone).
        let src = "# keep this\nkeep: 1   # me too\n# drop this\ndrop: 2   # bye\n";
        let mut doc = decode_document(src).unwrap();
        if let Value::Table(ref mut t) = doc.body {
            t.shift_remove("drop");
        } else {
            panic!("expected table");
        }
        let emitted = encode(&doc).unwrap();
        let doc2 = decode_document(&emitted).unwrap();
        // `drop` is gone.
        if let Value::Table(t) = &doc2.body {
            assert!(!t.contains_key("drop"), "deleted key should not reappear");
            assert!(t.contains_key("keep"), "non-deleted key should remain");
        } else {
            panic!("expected table after re-parse");
        }
        // No comments at the deleted path.
        let drop_path = vec![BreadcrumbSegment::Key("drop".to_string())];
        assert_eq!(
            count_comments_at_path(&doc2, &drop_path),
            0,
            "deleted key's comments must not survive; got: {:?}",
            doc2.comments
        );
        // `keep`'s comments still there.
        let keep_path = vec![BreadcrumbSegment::Key("keep".to_string())];
        let keep_leading = doc2.comments.iter().filter(|c| c.path == keep_path && c.position == CommentPosition::Leading).count();
        let keep_trailing = doc2.comments.iter().filter(|c| c.path == keep_path && c.position == CommentPosition::Trailing).count();
        assert_eq!(keep_leading, 1, "leading comment on `keep` must survive sibling deletion");
        assert_eq!(keep_trailing, 1, "trailing comment on `keep` must survive sibling deletion");
    }

    #[test]
    fn encode_inserted_key_carries_no_comments() {
        // Insert a new kvpair; it must come back with zero attached
        // comments.
        let src = "# leading on existing\nexisting: 1   # trailing on existing\n";
        let mut doc = decode_document(src).unwrap();
        if let Value::Table(ref mut t) = doc.body {
            t.insert("inserted".to_string(), Value::String("new".to_string()));
        } else {
            panic!("expected table");
        }
        let emitted = encode(&doc).unwrap();
        let doc2 = decode_document(&emitted).unwrap();
        // Both keys present.
        if let Value::Table(t) = &doc2.body {
            assert_eq!(t["existing"], Value::Integer(1));
            assert_eq!(t["inserted"], Value::String("new".to_string()));
        } else {
            panic!("expected table after re-parse");
        }
        // Inserted key has no comments.
        let inserted_path = vec![BreadcrumbSegment::Key("inserted".to_string())];
        assert_eq!(
            count_comments_at_path(&doc2, &inserted_path),
            0,
            "newly inserted key must not pick up comments; got: {:?}",
            doc2.comments
        );
        // Existing key's comments preserved.
        let existing_path = vec![BreadcrumbSegment::Key("existing".to_string())];
        assert_eq!(
            count_comments_at_path(&doc2, &existing_path),
            2,
            "existing key's leading + trailing comments must survive insertion of a sibling"
        );
    }

    #[test]
    fn encode_combined_mutations() {
        // Stress: do all three at once — update one value, delete one
        // key, insert a new one. Each should behave per the SPEC
        // independently.
        let src = "# A\na: 1   # a-trail\n# B\nb: 2   # b-trail\n# C\nc: 3   # c-trail\n";
        let mut doc = decode_document(src).unwrap();
        if let Value::Table(ref mut t) = doc.body {
            *t.get_mut("a").unwrap() = Value::Integer(100);  // update
            t.shift_remove("b");                              // delete
            t.insert("d".to_string(), Value::Integer(4));     // insert
        } else {
            panic!("expected table");
        }
        let emitted = encode(&doc).unwrap();
        let doc2 = decode_document(&emitted).unwrap();
        if let Value::Table(t) = &doc2.body {
            assert_eq!(t["a"], Value::Integer(100));
            assert!(!t.contains_key("b"));
            assert_eq!(t["c"], Value::Integer(3));
            assert_eq!(t["d"], Value::Integer(4));
        } else {
            panic!("expected table after re-parse");
        }
        let p = |k: &str| vec![BreadcrumbSegment::Key(k.to_string())];
        // a: leading + trailing survived update
        assert_eq!(count_comments_at_path(&doc2, &p("a")), 2, "a should keep both comments");
        // b: deleted, no comments
        assert_eq!(count_comments_at_path(&doc2, &p("b")), 0, "b should be gone with its comments");
        // c: untouched, both comments present
        assert_eq!(count_comments_at_path(&doc2, &p("c")), 2, "c should keep both comments");
        // d: inserted, no comments
        assert_eq!(count_comments_at_path(&doc2, &p("d")), 0, "d should have no comments");
    }

    // ----- encode_lite (canonical-form emit) tests -----

    #[test]
    fn encode_lite_drops_comments() {
        // Full-mode parse captures comments; lite-mode emit drops them.
        let src = "# leading\na: 1   # trailing\n# floating\n";
        let doc = decode_document(src).unwrap();
        assert!(!doc.comments.is_empty(), "fixture should capture comments");
        let lite = encode_lite(&doc);
        assert!(!lite.contains('#'), "lite emit should have no comments, got:\n{lite}");
        // Data still round-trips.
        let doc2 = decode_document(&lite).unwrap();
        assert_eq!(doc.body, doc2.body);
        assert!(doc2.comments.is_empty(), "re-parsed lite emit should have no comments");
    }

    #[test]
    fn encode_lite_canonicalises_integer_base() {
        // Full mode preserves source base; lite drops original_forms
        // and emits decimal.
        let src = "a: 0x1F40\nb: 0o755\nc: 0b1010_0110\nd: 1_000_000\n";
        let doc = decode_document(src).unwrap();
        let lite = encode_lite(&doc);
        // Decimal-only output: no 0x / 0o / 0b prefixes, no underscores.
        assert!(!lite.contains("0x"), "lite emit should not preserve hex base, got:\n{lite}");
        assert!(!lite.contains("0o"), "lite emit should not preserve oct base, got:\n{lite}");
        assert!(!lite.contains("0b"), "lite emit should not preserve bin base, got:\n{lite}");
        assert!(lite.contains("a: 8000"),       "lite emit should canonicalise 0x1F40 to 8000, got:\n{lite}");
        assert!(lite.contains("b: 493"),        "lite emit should canonicalise 0o755 to 493, got:\n{lite}");
        assert!(lite.contains("c: 166"),        "lite emit should canonicalise 0b10100110 to 166, got:\n{lite}");
        assert!(lite.contains("d: 1000000"),    "lite emit should canonicalise underscored 1_000_000 to 1000000, got:\n{lite}");
        // Data round-trips via lite emit.
        let doc2 = decode_document(&lite).unwrap();
        assert_eq!(doc.body, doc2.body);
    }

    #[test]
    fn encode_lite_canonicalises_string_form() {
        // Full mode preserves '...'; lite emits "...".
        let src = "a: 'literal'\nb: \"basic\"\n";
        let doc = decode_document(src).unwrap();
        let lite = encode_lite(&doc);
        // No literal-string single quotes.
        assert!(!lite.contains("'literal'"),
                "lite emit should canonicalise '...' to \"...\", got:\n{lite}");
        assert!(lite.contains("a: \"literal\""), "got:\n{lite}");
        assert!(lite.contains("b: \"basic\""),   "got:\n{lite}");
    }

    #[test]
    fn encode_lite_works_on_lite_parse() {
        // A Document parsed in lite mode has empty comments +
        // original_forms — encode_lite must still produce valid DMS.
        let src = "# leading\na: 0x1F40\nb: 'hello'\n";
        let doc = decode_lite_document(src).unwrap();
        assert!(doc.comments.is_empty());
        assert!(doc.original_forms.is_empty());
        let lite = encode_lite(&doc);
        let doc2 = decode_document(&lite).unwrap();
        assert_eq!(doc.body, doc2.body);
    }

    #[test]
    fn encode_with_mode_dispatches_correctly() {
        let src = "# c\na: 1\n";
        let doc = decode_document(src).unwrap();
        assert_eq!(
            encode_with_mode(&doc, EmitMode::Full).unwrap(),
            encode(&doc).unwrap()
        );
        assert_eq!(
            encode_with_mode(&doc, EmitMode::Lite).unwrap(),
            encode_lite(&doc)
        );
    }

    // ---------- unordered-table tests (SPEC §"Unordered tables") ----------

    #[test]
    fn decode_document_unordered_produces_unordered_table() {
        // Body of a kvpair-only source must come back as
        // Value::UnorderedTable when parsed via the *_unordered entry
        // point.
        let doc = decode_document_unordered("a: 1\nb: 2\n").unwrap();
        match &doc.body {
            Value::UnorderedTable(t) => {
                assert_eq!(t.len(), 2);
                assert_eq!(t["a"], Value::Integer(1));
                assert_eq!(t["b"], Value::Integer(2));
            }
            other => panic!("expected Value::UnorderedTable, got {other:?}"),
        }
    }

    #[test]
    fn decode_lite_document_unordered_produces_unordered_table() {
        // (unordered, lite) — the read-only fast path. No comments,
        // no original_forms, hash-only backing.
        let src = "# leading\na: 0xFF\nb: 'lit'\n";
        let doc = decode_lite_document_unordered(src).unwrap();
        assert!(doc.comments.is_empty(), "lite mode must drop comments");
        assert!(doc.original_forms.is_empty(), "lite mode must drop original_forms");
        match &doc.body {
            Value::UnorderedTable(t) => {
                assert_eq!(t.len(), 2);
                assert_eq!(t["a"], Value::Integer(255));
                assert_eq!(t["b"], Value::String("lit".to_string()));
            }
            other => panic!("expected Value::UnorderedTable, got {other:?}"),
        }
    }

    #[test]
    fn unordered_data_round_trip() {
        // Parse unordered → emit lite → re-parse (ordered) → must be
        // data-equivalent (key set + values match; iteration order is
        // not promised).
        let src = "a: 1\nb: 2\nc: 3\nd: 'x'\n";
        let unordered = decode_document_unordered(src).unwrap();
        let emitted = encode_lite(&unordered);
        let reparsed = decode_document(&emitted).unwrap();
        // Compare structurally: collect both into ordered maps and
        // compare key/value sets.
        let unordered_keys: std::collections::HashSet<&String> = match &unordered.body {
            Value::UnorderedTable(t) => t.keys().collect(),
            other => panic!("expected UnorderedTable, got {other:?}"),
        };
        let reparsed_map: &DmsMap<Value> = match &reparsed.body {
            Value::Table(t) => t,
            other => panic!("expected Table after re-parse, got {other:?}"),
        };
        let reparsed_keys: std::collections::HashSet<&String> =
            reparsed_map.keys().collect();
        assert_eq!(unordered_keys, reparsed_keys, "key sets must match");
        if let Value::UnorderedTable(t) = &unordered.body {
            for (k, v) in t {
                assert_eq!(reparsed_map.get(k), Some(v), "value for {k} must match");
            }
        }
    }

    #[test]
    fn encode_full_errors_on_unordered() {
        // Per SPEC §"Unordered tables": full-mode `encode` MUST refuse
        // an unordered Document (round-trip needs a stable order). As
        // of v0.3 this is a clean `Err(EncodeError::UnorderedInFullMode)`
        // rather than a panic.
        let doc = decode_document_unordered("a: 1\nb: 2\n").unwrap();
        assert_eq!(encode(&doc), Err(EncodeError::UnorderedInFullMode));
    }

    #[test]
    fn encode_full_errors_on_unordered_nested() {
        // Same error must fire when the unordered table is nested
        // inside a List or another Table — the contains check is
        // recursive.
        let mut nested: DmsHashMap<Value> = DmsHashMap::default();
        nested.insert("x".to_string(), Value::Integer(1));
        let doc = Document {
            meta: None,
            body: Value::List(vec![Value::UnorderedTable(nested)]),
            comments: Vec::new(),
            original_forms: Vec::new(),
        };
        assert_eq!(encode(&doc), Err(EncodeError::UnorderedInFullMode));
    }

    #[test]
    fn encode_lite_accepts_unordered() {
        // Lite emit accepts unordered Document and yields valid DMS.
        // No round-trip stability promised, but data equivalence is.
        let src = "a: 1\nb: 2\n";
        let doc = decode_document_unordered(src).unwrap();
        let lite = encode_lite(&doc);
        // Should not contain any internal markers; should re-parse.
        let doc2 = decode_document(&lite).unwrap();
        match &doc2.body {
            Value::Table(t) => {
                assert_eq!(t.len(), 2);
                assert_eq!(t["a"], Value::Integer(1));
                assert_eq!(t["b"], Value::Integer(2));
            }
            other => panic!("expected Table after re-parse, got {other:?}"),
        }
    }

    #[test]
    fn decode_document_ordered_unaffected() {
        // Sanity: the default parse path still produces Value::Table,
        // and is otherwise unchanged by the addition of UnorderedTable.
        let doc = decode_document("a: 1\nb: 2\n").unwrap();
        match &doc.body {
            Value::Table(t) => {
                assert_eq!(t.len(), 2);
                let keys: Vec<&String> = t.keys().collect();
                // IndexMap preserves insertion order — that's the
                // whole point of the ordered path.
                assert_eq!(keys, vec![&"a".to_string(), &"b".to_string()]);
            }
            other => panic!("expected Value::Table, got {other:?}"),
        }
        // Round-trip via full encode still works.
        let emitted = encode(&doc).expect("encode failed");
        let doc2 = decode_document(&emitted).unwrap();
        assert_eq!(doc.body, doc2.body);
    }

    #[test]
    fn unordered_nested_table_via_block() {
        // Nested block tables under unordered mode also become
        // UnorderedTable (the rule is: every body table is unordered).
        let src = "outer:\n  inner: 1\n  other: 2\n";
        let doc = decode_document_unordered(src).unwrap();
        match &doc.body {
            Value::UnorderedTable(t) => {
                match t.get("outer").unwrap() {
                    Value::UnorderedTable(inner) => {
                        assert_eq!(inner.len(), 2);
                        assert_eq!(inner["inner"], Value::Integer(1));
                        assert_eq!(inner["other"], Value::Integer(2));
                    }
                    other => panic!("expected UnorderedTable inner, got {other:?}"),
                }
            }
            other => panic!("expected UnorderedTable outer, got {other:?}"),
        }
    }

    #[test]
    fn unordered_flow_table() {
        // Inline flow tables {a: 1, b: 2} also become UnorderedTable
        // under --ignore-order.
        let src = "x: { a: 1, b: 2 }\n";
        let doc = decode_document_unordered(src).unwrap();
        match &doc.body {
            Value::UnorderedTable(outer) => match outer.get("x").unwrap() {
                Value::UnorderedTable(t) => {
                    assert_eq!(t.len(), 2);
                    assert_eq!(t["a"], Value::Integer(1));
                    assert_eq!(t["b"], Value::Integer(2));
                }
                other => panic!("expected UnorderedTable for flow, got {other:?}"),
            },
            other => panic!("expected UnorderedTable, got {other:?}"),
        }
    }
}