bynk_syntax/

parser.rs

//! Hand-written recursive-descent parser for Bynk v0.
//!
//! Token grammar in spec §4. The expression parser uses one function per
//! precedence level (§4.4). Errors carry spans and short fix-oriented
//! messages; the parser does not currently attempt synchronisation, which
//! means at most one parse error is reported per compilation.

use crate::ast::*;
use crate::error::CompileError;
use crate::lexer::{Token, TokenKind, comment_body, doc_block_content, has_blank_line_between};
use crate::span::Span;
mod declarations;
mod expressions;
mod statements;
mod types;

/// Side-channel store for line-comment trivia (v1.1 LSP spec §3.5).
///
/// Built once up-front by [`split_trivia`] from the raw lexer token stream.
/// Comments are removed from the token stream the parser walks; their text
/// is filed into `leading` (comments on lines preceding a content token)
/// and `trailing` (a single comment on the same line as a content token).
/// The parser consumes entries through [`TriviaTable::take_leading`] and
/// [`TriviaTable::take_trailing`] as it recognises declarations.
#[derive(Debug, Default)]
struct TriviaTable {
    /// `leading[i]` holds the comment-body texts that appear immediately
    /// before content token `i` (zero or more `--` lines, in source order,
    /// not separated from the token by another content token).
    leading: Vec<Vec<String>>,
    /// `trailing[i]` holds an optional comment on the same source line as
    /// content token `i`. Only one trailing comment is recorded per token
    /// because a single `--` consumes the rest of the line.
    trailing: Vec<Option<String>>,
    /// Any pending leading comments at end-of-file (no content token
    /// followed). Used to preserve file-trailing comments.
    epilogue: Vec<String>,
}

impl TriviaTable {
    fn take_leading(&mut self, index: usize) -> Vec<String> {
        match self.leading.get_mut(index) {
            Some(v) => std::mem::take(v),
            None => Vec::new(),
        }
    }

    fn take_trailing(&mut self, index: usize) -> Option<String> {
        self.trailing.get_mut(index).and_then(|s| s.take())
    }

    fn take_epilogue(&mut self) -> Vec<String> {
        std::mem::take(&mut self.epilogue)
    }

    /// True when every entry has been drained via `take_leading`/
    /// `take_trailing`/`take_epilogue` — i.e. no comment was silently
    /// dropped. Each harvest is already a `mem::take`, so anything still
    /// present here is exactly the set of comments that never reached an
    /// AST `Trivia` field.
    ///
    /// Deliberately **not** wired into a `debug_assert!` in the general parse
    /// path: expressions carry no per-node trivia (§ "Comment trivia" in the
    /// 2026-07-27 pipeline review), so an ordinary, valid program with a
    /// comment inside a `match`/list/record/binop — a common, accepted
    /// pattern `bynk-fmt`'s own comment-loss guard already handles
    /// gracefully — would leave `leading`/`trailing` non-empty and trip it on
    /// every compile, not just on formatting. Instead surfaced through
    /// [`parse_units_with_drain_check`] (finding #66), whose one caller
    /// (`bynk-fmt`) *does* care about exactly this signal.
    /// [`Self::epilogue_is_empty`] is the narrower, safe-to-assert check.
    fn is_fully_drained(&self) -> bool {
        self.leading.iter().all(Vec::is_empty)
            && self.trailing.iter().all(Option::is_none)
            && self.epilogue.is_empty()
    }

    /// True when no file-trailing comment was left stranded. Unlike
    /// [`Self::is_fully_drained`], this is safe to assert unconditionally: a
    /// clean file's epilogue is empty by construction (nothing pending at
    /// EOF), and the one shape that legitimately populates it — a top-level
    /// trailing comment — is drained by every parse path that calls
    /// `take_epilogue`. A brace-form declaration that forgets to is exactly
    /// the bug this catches.
    fn epilogue_is_empty(&self) -> bool {
        self.epilogue.is_empty()
    }
}

/// Remove `Comment` trivia tokens from `tokens` and bin them into a
/// [`TriviaTable`] keyed against the surviving content tokens. A comment
/// on the same source line as the preceding content token is recorded as
/// that token's *trailing* trivia; everything else is *leading* for the
/// next content token.
fn split_trivia(tokens: &[Token], source: &str) -> (Vec<Token>, TriviaTable) {
    let mut filtered: Vec<Token> = Vec::with_capacity(tokens.len());
    let mut table = TriviaTable::default();
    let mut pending_leading: Vec<String> = Vec::new();
    let mut last_content_end: Option<usize> = None;
    for tok in tokens {
        if tok.kind == TokenKind::Comment {
            let body = comment_body(source, tok.span).to_string();
            // If nothing has been buffered as leading for the next token and
            // there is no newline between the previous content token and
            // this comment, it trails that token.
            if pending_leading.is_empty()
                && let Some(prev_end) = last_content_end
                && !source[prev_end..tok.span.start].contains('\n')
            {
                let last_idx = filtered.len() - 1;
                // Only attach if no trailing already recorded (shouldn't
                // happen because `--` consumes through end-of-line).
                if table.trailing[last_idx].is_none() {
                    table.trailing[last_idx] = Some(body);
                    continue;
                }
            }
            pending_leading.push(body);
            continue;
        }
        filtered.push(*tok);
        table.leading.push(std::mem::take(&mut pending_leading));
        table.trailing.push(None);
        last_content_end = Some(tok.span.end);
    }
    table.epilogue = pending_leading;
    (filtered, table)
}

/// Parse a token slice into a [`Commons`] AST.
///
/// Accepts either form of v0.3 commons file:
/// - Brace form: `commons name { items... }` (v0–v0.2 compatible).
/// - Fragment form: `commons name uses... items...` to EOF (v0.3).
pub fn parse(tokens: &[Token], source: &str) -> Result<Commons, Vec<CompileError>> {
    parse_with_warnings(tokens, source).map(|(c, _warnings)| c)
}

/// [`parse`] with the non-fatal diagnostics threaded out alongside the AST
/// (ADR 0117) — see [`parse_units_with_warnings`].
pub fn parse_with_warnings(
    tokens: &[Token],
    source: &str,
) -> Result<(Commons, Vec<CompileError>), Vec<CompileError>> {
    let (unit, warnings) = parse_unit_with_warnings(tokens, source)?;
    match unit {
        SourceUnit::Commons(c) => Ok((c, warnings)),
        SourceUnit::Context(ctx) => Err(vec![
            CompileError::new(
                "bynk.parse.unexpected_context",
                ctx.span,
                "expected a `commons` declaration but found a `context` declaration",
            )
            .with_note(
                "contexts must be compiled as part of a project — pass the source directory, e.g. `bynkc compile --target bundle --output out src`",
            ),
        ]),
        SourceUnit::Suite(t) => Err(vec![
            CompileError::new(
                "bynk.parse.unexpected_suite",
                t.span,
                "expected a `commons` declaration but found a `suite` declaration",
            )
            .with_note(
                "tests must be compiled as part of a project — pass the source directory, e.g. `bynkc compile --target bundle --output out src`",
            ),
        ]),
        SourceUnit::Adapter(a) => Err(vec![
            CompileError::new(
                "bynk.parse.unexpected_adapter",
                a.span,
                "expected a `commons` declaration but found an `adapter` declaration",
            )
            .with_note(
                "adapters must be compiled as part of a project — pass the source directory, e.g. `bynkc compile --target bundle --output out src`",
            ),
        ]),
    }
}

/// Parse a token slice into a [`SourceUnit`] with error recovery, returning a
/// best-effort partial AST plus the full list of parse errors and warnings.
///
/// Used by the LSP: item-level recovery skips past a malformed declaration to
/// the next top-level item, so multiple errors are reported per compilation
/// rather than just the first. Compared to [`parse_unit`], this never bails;
/// if no SourceUnit could be parsed at all (e.g. the file is empty or the
/// header itself fails) the returned `Option` is `None`.
///
/// Keeps only the *first* unit — v0.113 allows more than one top-level unit
/// per file (an atomic `commons` + `suite`, DECISION S), and every existing
/// caller here is keyed on the primary declaration. [`parse_units_with_recovery`]
/// is the same recovery parse without that narrowing, for the one caller
/// (finding #29/#30) that needs every unit a file declares.
pub fn parse_unit_with_recovery(
    tokens: &[Token],
    source: &str,
) -> (Option<SourceUnit>, Vec<CompileError>) {
    let (units, errors) = parse_units_with_recovery(tokens, source);
    (units.into_iter().next(), errors)
}

/// [`parse_unit_with_recovery`], keeping **every** top-level unit instead of
/// discarding all but the first (finding #29/#30). Used by the IDE's own parse
/// entry point, which needs to see a trailing `suite` in an atomic
/// `commons`+`suite` file, not just the primary declaration.
pub fn parse_units_with_recovery(
    tokens: &[Token],
    source: &str,
) -> (Vec<SourceUnit>, Vec<CompileError>) {
    let (filtered, trivia) = split_trivia(tokens, source);
    let mut warnings = Vec::new();
    let mut p = Parser::new(&filtered, source, trivia, &mut warnings);
    p.recover_mode = true;
    let mut units = Vec::new();
    loop {
        match p.parse_unit() {
            Ok(u) => units.push(u),
            Err(e) => {
                p.recovered_errors.push(e);
                break;
            }
        }
        // A genuinely malformed trailing declaration is still surfaced via
        // recovery — checked *after* each successful parse, matching
        // `parse_unit`'s own "at least once" attempt on the first unit (an
        // empty file must still produce its usual unexpected-EOF diagnostic,
        // not silently yield an empty `units` with no error at all).
        if p.peek().is_none() {
            break;
        }
    }
    let mut all_errors = p.recovered_errors;
    all_errors.append(&mut warnings);
    (units, all_errors)
}

/// Parse a token slice into a [`SourceUnit`] — either a commons or a context.
///
/// Each `.bynk` file is exactly one declaration of one kind.
pub fn parse_unit(tokens: &[Token], source: &str) -> Result<SourceUnit, Vec<CompileError>> {
    parse_unit_with_warnings(tokens, source).map(|(unit, _warnings)| unit)
}

/// [`parse_unit`] with the non-fatal diagnostics threaded out alongside the
/// AST (ADR 0117) — see [`parse_units_with_warnings`].
pub fn parse_unit_with_warnings(
    tokens: &[Token],
    source: &str,
) -> Result<(SourceUnit, Vec<CompileError>), Vec<CompileError>> {
    parse_unit_with_warnings_from(tokens, source, &mut 0)
}

/// [`parse_unit_with_warnings`], continuing [`ExprId`] allocation from
/// `next_id` instead of starting at 0, and writing the id one past the last
/// one this parse handed out back into it. T3.4 (R2.4): every top-level parse
/// entry point in this file constructs its own `Parser` and therefore its own
/// zero-based id space; a caller that will check two files' output together
/// in one pass (a multi-file commons — `bynk-emit`'s `collect_unit_methods`
/// merges a type's methods from sibling files into the file that declares the
/// type, before one `check_record` call) must thread one counter across every
/// file it parses, or two independently-numbered files collide on the same
/// id in the same `expr_types` map. Every *other* caller (a single buffer, an
/// LSP hover/completion query, a fixture test) never merges its output with
/// another file's before checking, so starting at 0 every time is correct —
/// [`parse_unit_with_warnings`] above is that default, unchanged.
pub fn parse_unit_with_warnings_from(
    tokens: &[Token],
    source: &str,
    next_id: &mut u32,
) -> Result<(SourceUnit, Vec<CompileError>), Vec<CompileError>> {
    let (filtered, trivia) = split_trivia(tokens, source);
    let mut warnings = Vec::new();
    let mut p = Parser::new(&filtered, source, trivia, &mut warnings);
    p.next_expr_id = *next_id;
    let result = match p.parse_unit() {
        Ok(u) => {
            if let Some(extra) = p.peek() {
                Err(vec![
                    CompileError::new(
                        "bynk.parse.extra_tokens",
                        extra.span,
                        "unexpected token after top-level declaration",
                    )
                    .with_note(
                        "a `.bynk` file contains exactly one `commons` or `context` declaration",
                    ),
                ])
            } else {
                Ok(u)
            }
        }
        Err(e) => Err(vec![e]),
    };
    *next_id = p.next_expr_id;
    // ADR 0117: warnings (e.g. orphan doc blocks) ride alongside a successful
    // parse — severity governs gating at the caller, not here.
    match result {
        Ok(u) => {
            // See `parse_units_with_warnings`: a file-trailing comment must
            // have been drained by `take_epilogue`.
            debug_assert!(
                p.trivia.epilogue_is_empty(),
                "a file-trailing comment was left undrained after a successful parse"
            );
            Ok((u, warnings))
        }
        Err(mut errs) => {
            errs.append(&mut warnings);
            Err(errs)
        }
    }
}

/// Parse a token slice into **all** the top-level [`SourceUnit`]s in one file
/// (v0.113, testing track slice 1b). A `.bynk` file may hold more than one
/// top-level declaration — an *atomic* file with `commons`/`context` **and** a
/// `suite` together (DECISION S) — so the compiler parses a `Vec`, not a single
/// unit. Test-ness is a property of each declaration, not of the file.
///
/// Bails on the first malformed declaration (like [`parse_unit`], not the
/// recovering LSP path). An empty file is an error.
pub fn parse_units(tokens: &[Token], source: &str) -> Result<Vec<SourceUnit>, Vec<CompileError>> {
    parse_units_with_warnings(tokens, source).map(|(units, _warnings)| units)
}

/// [`parse_units`] with the non-fatal diagnostics threaded out alongside the
/// AST (ADR 0117): a successful parse returns `Ok((units, warnings))` instead
/// of hard-failing on a warning-severity diagnostic (an orphan doc block used
/// to abort file discovery and throw the good AST away). A failed parse still
/// returns every diagnostic — errors then warnings — in the `Err`.
pub fn parse_units_with_warnings(
    tokens: &[Token],
    source: &str,
) -> Result<(Vec<SourceUnit>, Vec<CompileError>), Vec<CompileError>> {
    parse_units_with_drain_check(tokens, source)
        .map(|(units, warnings, _drained)| (units, warnings))
}

/// [`parse_units_with_warnings`], continuing [`ExprId`] allocation from
/// `next_id` rather than starting at 0 — see [`parse_unit_with_warnings_from`]
/// for why this exists. The one production caller is `bynk-emit`'s per-file
/// parse loop (`phase_parse`), which owns one counter across every file in a
/// single project parse so two files whose methods later get merged into one
/// `check_record` call (a multi-file commons) never collide.
pub fn parse_units_with_warnings_from(
    tokens: &[Token],
    source: &str,
    next_id: &mut u32,
) -> Result<(Vec<SourceUnit>, Vec<CompileError>), Vec<CompileError>> {
    parse_units_with_drain_check_from(tokens, source, next_id)
        .map(|(units, warnings, _drained)| (units, warnings))
}

/// [`parse_units_with_warnings`] plus whether every comment's trivia was
/// drained into the AST (`TriviaTable::is_fully_drained`). Finding #66:
/// `bynk-fmt`'s comment-preservation guard re-tokenized its own rendered
/// output just to diff comment bodies against the input — wasted work in the
/// overwhelming common case where nothing was left behind. That guard uses
/// this drain signal, computed from the same parse it already needs for
/// rendering, as a fast-path: `true` means every comment landed in the AST,
/// so re-checking the output can be skipped outright. No other caller needs
/// the signal, so it rides its own entry point rather than widening
/// [`parse_units_with_warnings`].
pub fn parse_units_with_drain_check(
    tokens: &[Token],
    source: &str,
) -> Result<(Vec<SourceUnit>, Vec<CompileError>, bool), Vec<CompileError>> {
    parse_units_with_drain_check_from(tokens, source, &mut 0)
}

/// [`parse_units_with_drain_check`], continuing [`ExprId`] allocation from
/// `next_id` — see [`parse_unit_with_warnings_from`].
pub fn parse_units_with_drain_check_from(
    tokens: &[Token],
    source: &str,
    next_id: &mut u32,
) -> Result<(Vec<SourceUnit>, Vec<CompileError>, bool), Vec<CompileError>> {
    let (filtered, trivia) = split_trivia(tokens, source);
    let mut warnings = Vec::new();
    let mut p = Parser::new(&filtered, source, trivia, &mut warnings);
    p.next_expr_id = *next_id;
    let mut units = Vec::new();
    let mut errors: Vec<CompileError> = Vec::new();
    while p.peek().is_some() {
        match p.parse_unit() {
            Ok(u) => units.push(u),
            Err(e) => {
                errors.push(e);
                break;
            }
        }
    }
    *next_id = p.next_expr_id;
    let eof = p.eof_span();
    let fully_drained = p.trivia.is_fully_drained();
    // `p` (and thus its `&mut warnings` borrow) is no longer used past here, so
    // the local `warnings` are readable again.
    if !errors.is_empty() {
        errors.append(&mut warnings);
        return Err(errors);
    }
    if units.is_empty() {
        return Err(vec![CompileError::new(
            "bynk.parse.unexpected_eof",
            eof,
            "expected `commons`, `context`, or `suite` to start the file, found end of file",
        )]);
    }
    // A file-trailing comment must have been drained by `take_epilogue` — the
    // one brace-form declarations forgot to call (a live comment-loss bug,
    // not the fundamentally-unfixed expression-interior case: expressions
    // carry no trivia at all, so asserting full drainage here would fire on
    // any ordinary program with a comment inside a `match`/list/record, which
    // `bynk-fmt`'s own comment-loss guard already handles gracefully rather
    // than as a hard failure).
    debug_assert!(
        p.trivia.epilogue_is_empty(),
        "a file-trailing comment was left undrained after a successful parse"
    );
    Ok((units, warnings, fully_drained))
}

/// A signed numeric literal in refinement-bound position (v0.21): `InRange`
/// bounds are either both `Int` or both `Float`.
enum SignedNumLit {
    Int(IntBound),
    Float(FloatBound),
}

struct Parser<'a> {
    tokens: &'a [Token],
    source: &'a str,
    pos: usize,
    /// Accumulated non-fatal diagnostics. v0.3 uses this for orphan-doc
    /// warnings, which are emitted as errors with a distinguishable category.
    warnings: &'a mut Vec<CompileError>,
    /// When true, the item-level loops catch errors from individual item
    /// parses, push them into `recovered_errors`, and skip forward to the
    /// next top-level item boundary instead of bailing. Used by the LSP via
    /// [`parse_unit_with_recovery`]; disabled in the normal `parse` path so
    /// existing single-error behaviour is preserved.
    recover_mode: bool,
    /// Errors collected during recovery-mode parsing. Only populated when
    /// `recover_mode` is true.
    recovered_errors: Vec<CompileError>,
    /// Line-comment trivia separated from the token stream. See
    /// [`TriviaTable`].
    trivia: TriviaTable,
    /// Live recursion depth of the three self-recursive parse entry points
    /// (`parse_expr`, `parse_type_ref`, `parse_pattern`). Incremented on entry
    /// and decremented on exit by [`Parser::enter_recursion`] so it tracks the
    /// current stack depth; when it exceeds [`crate::MAX_NESTING_DEPTH`] the
    /// parser reports a bounded-depth diagnostic instead of overflowing its
    /// stack (#713).
    depth: usize,
    /// When true, a bare `ident {` on the *spine* of the current expression is
    /// an identifier followed by an unrelated block, never a record
    /// construction — so an `if`/`match` condition that ends in a bare
    /// identifier does not swallow the branch/arm block as `Ident { field }`
    /// (#636). Set only around the condition parse (see [`parse_cond_expr`]);
    /// `parse_expr` clears it, so the restriction is lifted inside any
    /// delimited sub-expression (parentheses, call arguments, list, record
    /// field). Mirrors Rust's `NO_STRUCT_LITERAL` restriction.
    no_record_literal: bool,
    /// Running count of unclosed `{` seen so far — maintained solely by
    /// [`Self::bump`] (the one primitive that advances `self.pos`), so it
    /// always reflects the true nesting depth no matter which parse function
    /// is on the call stack. Finding #27/#30: `recover_to_top_item` reads it
    /// against [`Self::item_loop_baseline`] to tell "the enclosing item
    /// loop's own closing brace" apart from a still-unclosed nested
    /// construct's — without it, a sync scan that started partway through
    /// such a construct (an error deep inside a function body) stopped at the
    /// first `}` it saw, however deeply nested, and the enclosing item loop
    /// mistook that for its own body's end.
    brace_depth: usize,
    /// Stack of `brace_depth` snapshots, one per active item-loop body
    /// (commons/context/adapter/suite) — pushed right after that body's own
    /// `{` is consumed (or at loop entry, for a brace-free fragment form),
    /// popped at the loop's normal exit. `recover_to_top_item` treats its top
    /// entry as the depth an `}` must return to before it counts as the
    /// enclosing body's own closing brace rather than a nested construct's.
    item_loop_baseline: Vec<usize>,
    /// T3.4 (R2.4): next [`ExprId`] to hand out — monotonic, incremented by
    /// [`Self::alloc_expr_id`], the sole allocation point every `Expr`
    /// construction site in this parser calls.
    next_expr_id: u32,
}

impl<'a> Parser<'a> {
    fn new(
        tokens: &'a [Token],
        source: &'a str,
        trivia: TriviaTable,
        warnings: &'a mut Vec<CompileError>,
    ) -> Self {
        Self {
            tokens,
            source,
            pos: 0,
            warnings,
            recover_mode: false,
            recovered_errors: Vec::new(),
            trivia,
            depth: 0,
            no_record_literal: false,
            brace_depth: 0,
            item_loop_baseline: Vec::new(),
            next_expr_id: 0,
        }
    }

    /// T3.4 (R2.4): allocate the next [`ExprId`]. The sole allocation point —
    /// every `Expr { id: self.alloc_expr_id(), .. }` construction in this
    /// parser calls it exactly once, so two nodes never share an id and every
    /// id a caller holds was actually handed out here.
    fn alloc_expr_id(&mut self) -> ExprId {
        let id = ExprId(self.next_expr_id);
        self.next_expr_id += 1;
        id
    }

    /// Enter a self-recursive parse step, bumping the live recursion depth and
    /// failing with a bounded-depth diagnostic if it would exceed
    /// [`crate::MAX_NESTING_DEPTH`]. The caller pairs a successful entry with a
    /// matching `self.depth -= 1` on the way out (see `parse_expr` /
    /// `parse_type_ref`); on the error path the depth is restored here so a
    /// recovering caller is not left mis-counted. `what` names the construct
    /// for the message (e.g. "this expression", "this type"). See #713.
    fn enter_recursion(&mut self, what: &str) -> Result<(), CompileError> {
        self.depth += 1;
        if self.depth > crate::MAX_NESTING_DEPTH {
            self.depth -= 1;
            let span = self
                .peek()
                .map(|t| t.span)
                .unwrap_or_else(|| self.eof_span());
            return Err(self.nesting_too_deep(span, what));
        }
        Ok(())
    }

    /// The bounded-depth diagnostic shared by [`enter_recursion`] and
    /// [`enter_chain_fold`].
    fn nesting_too_deep(&self, span: Span, what: &str) -> CompileError {
        CompileError::new(
            "bynk.parse.nesting_too_deep",
            span,
            format!(
                "{what} nests more than {} levels deep",
                crate::MAX_NESTING_DEPTH
            ),
        )
        .with_note(
            "deeply nested source is rejected to keep the parser from overflowing its \
             stack and aborting; flatten or split the construct",
        )
    }

    /// The bounded-depth diagnostic for the *iteratively*-built spines —
    /// associative operator chains ([`enter_chain_fold`]) and postfix receiver
    /// chains ([`deepen_spine`]). Same code as [`nesting_too_deep`] (one budget,
    /// one diagnostic) but phrased for a flat chain, which is long rather than
    /// *nested*, and points at the idiomatic fix.
    fn expression_too_long(&self, span: Span) -> CompileError {
        CompileError::new(
            "bynk.parse.nesting_too_deep",
            span,
            format!(
                "this expression is more than {} levels deep",
                crate::MAX_NESTING_DEPTH
            ),
        )
        .with_note(
            "a long operator or member chain is rejected to keep the compiler from overflowing \
             its stack; split it across `let` bindings, or reduce a sequence with \
             `.sum()`/`.fold(...)`",
        )
    }

    /// Count one more operand folded onto an associative operator chain against
    /// the same recursion budget as [`enter_recursion`] (#714).
    ///
    /// Associative chains (`+`, `*`, `&&`, `||`) are built *iteratively* in the
    /// precedence ladder, so — unlike parentheses, calls, or `implies` — they
    /// never re-enter `parse_expr` and thus slip past the `enter_recursion`
    /// guard. Yet each fold deepens the left-nested `Expr` tree by one level,
    /// and a long flat chain (`1 + 1 + … + 1`) overflows every *recursive*
    /// consumer of that tree downstream — the checker's `type_of`, the
    /// formatter, the emitter, and the AST's own recursive `Drop` — exactly as
    /// deeply nested source overflows the parser. Counting each fold on the
    /// shared `depth` budget bounds the whole expression's height, and because
    /// it is the *same* budget it composes with the ambient nesting depth, so a
    /// chain buried inside deeply nested source cannot exceed the bound either.
    ///
    /// The caller accumulates `folds` and subtracts them from `depth` before it
    /// returns, so the live count unwinds as a recursive descent would; on the
    /// overflow path the whole chain's contribution is restored here so a
    /// recovering caller is not left mis-counted.
    fn enter_chain_fold(&mut self, folds: &mut usize, span: Span) -> Result<(), CompileError> {
        self.depth += 1;
        *folds += 1;
        if self.depth > crate::MAX_NESTING_DEPTH {
            self.depth -= *folds;
            *folds = 0;
            return Err(self.expression_too_long(span));
        }
        Ok(())
    }

    /// Count one more level of an iteratively-built postfix receiver spine
    /// (`a.b.c…`, `f()?.g()…`) against the shared budget (#714). Like
    /// [`enter_chain_fold`], postfix loops rather than recurses, so a long spine
    /// escapes [`enter_recursion`] yet grows an arbitrarily deep receiver tree
    /// that the downstream walks recurse through. `parse_postfix` restores
    /// `depth` wholesale on the way out (its many error paths make a
    /// save/restore wrapper cleaner than per-fold unwinding), so this only bumps
    /// and checks.
    fn deepen_spine(&mut self, span: Span) -> Result<(), CompileError> {
        self.depth += 1;
        if self.depth > crate::MAX_NESTING_DEPTH {
            return Err(self.expression_too_long(span));
        }
        Ok(())
    }

    /// Comments immediately preceding the current peek position. Consumed
    /// (the table entry is cleared) so the same comments are not attached
    /// to two nodes.
    fn take_leading_trivia(&mut self) -> Vec<String> {
        self.trivia.take_leading(self.pos)
    }

    /// Trailing comment, if any, on the same source line as the most
    /// recently consumed content token. Call AFTER finishing a declaration
    /// or statement, while `self.pos` points one past its last token.
    fn take_trailing_trivia(&mut self) -> Option<String> {
        if self.pos == 0 {
            return None;
        }
        self.trivia.take_trailing(self.pos - 1)
    }

    /// Handle a per-item parse error. In recovery mode, record the error and
    /// advance to the next sync point so the item loop can continue; otherwise
    /// propagate as a hard failure.
    fn handle_item_err(&mut self, e: CompileError) -> Result<(), CompileError> {
        if self.recover_mode {
            self.recovered_errors.push(e);
            let before = self.pos;
            self.recover_to_top_item();
            // The sync target may be the very token that produced the error —
            // a context-only keyword (`capability`, `service`, …) at item
            // position in a commons errors *without consuming it*, and it is
            // itself a sync point. Recovery must always make progress, or the
            // item loop re-reports the same error until memory runs out
            // (found by the `parse` fuzz target on a seed input).
            if self.pos == before {
                self.bump();
            }
            Ok(())
        } else {
            Err(e)
        }
    }

    /// Skip forward to the next top-level item boundary: either an
    /// [`is_item_start`] keyword at the enclosing item loop's own nesting
    /// depth, a closing brace that returns to that depth, or end-of-input.
    /// Used only in recovery mode.
    ///
    /// Finding #27/#30: brace-depth-gated against
    /// [`Self::item_loop_baseline`], so a `}` deep inside a still-unclosed
    /// nested construct (an error partway through a function body, itself
    /// inside a `match` arm) is skipped over rather than mistaken for the
    /// enclosing body's own closing brace — the old flat scan stopped at
    /// literally the first `}` it saw, however deep, handing the item loop a
    /// brace that did not belong to it and making it return with zero items.
    fn recover_to_top_item(&mut self) {
        let baseline = self.item_loop_baseline.last().copied().unwrap_or(0);
        while let Some(t) = self.peek() {
            match t.kind {
                TokenKind::RBrace if self.brace_depth == baseline => return,
                _ if self.brace_depth == baseline && is_item_start(t.kind) => return,
                _ => {
                    self.bump();
                }
            }
        }
    }

    /// Mark the start of a top-level item loop (`declarations.rs`'s
    /// `parse_commons_brace`/`_fragment`, `parse_context_brace`/`_fragment`,
    /// `parse_test_brace`/`_fragment`, `parse_adapter_body`) — called right
    /// after that body's own `{` is consumed (brace form) or at the loop's
    /// own entry (fragment form, which has no enclosing brace of its own).
    /// Paired with [`Self::exit_item_loop`] at the loop's normal exit.
    fn enter_item_loop(&mut self) {
        self.item_loop_baseline.push(self.brace_depth);
    }

    /// Pair of [`Self::enter_item_loop`].
    fn exit_item_loop(&mut self) {
        self.item_loop_baseline.pop();
    }

    fn peek(&self) -> Option<Token> {
        self.tokens.get(self.pos).copied()
    }

    fn peek_kind(&self) -> Option<TokenKind> {
        self.peek().map(|t| t.kind)
    }

    /// The token `n` positions ahead of the cursor (`nth(0)` == `peek()`).
    fn nth(&self, n: usize) -> Option<Token> {
        self.tokens.get(self.pos + n).copied()
    }

    fn nth_kind(&self, n: usize) -> Option<TokenKind> {
        self.nth(n).map(|t| t.kind)
    }

    /// The source text of the token `n` positions ahead, or `""` if none.
    fn nth_text(&self, n: usize) -> &'a str {
        self.nth(n).map(|t| self.slice(t.span)).unwrap_or("")
    }

    /// The span of the most recently consumed token (`self.pos - 1`). Falls back
    /// to the current token's span when nothing has been consumed yet.
    fn prev_span(&self) -> Span {
        self.tokens
            .get(self.pos.wrapping_sub(1))
            .or_else(|| self.peek_ref())
            .map(|t| t.span)
            .unwrap_or_default()
    }

    fn peek_ref(&self) -> Option<&Token> {
        self.tokens.get(self.pos)
    }

    fn bump(&mut self) -> Option<Token> {
        let t = self.peek();
        if let Some(t) = t {
            match t.kind {
                TokenKind::LBrace => self.brace_depth += 1,
                TokenKind::RBrace => self.brace_depth = self.brace_depth.saturating_sub(1),
                _ => {}
            }
            self.pos += 1;
        }
        t
    }

    fn eat(&mut self, kind: TokenKind) -> Option<Token> {
        if self.peek_kind() == Some(kind) {
            self.bump()
        } else {
            None
        }
    }

    fn slice(&self, span: Span) -> &'a str {
        &self.source[span.range()]
    }

    /// True when the next token sits on a later line than `prev`. Used to
    /// keep a `[` that opens a new line out of the postfix type-application
    /// form: `f` followed by `[1, 2]` on the next line is an identifier and
    /// a list literal, not `f[…]` (v0.20b).
    fn next_token_on_new_line(&self, prev: Span) -> bool {
        match self.peek() {
            Some(t) if prev.end <= t.span.start => {
                self.source[prev.end..t.span.start].contains('\n')
            }
            _ => false,
        }
    }

    /// Span pointing at the end of input — used for "unexpected EOF" reports.
    /// The start backs up to the **start of the final char**, not `len - 1`, so
    /// the span never splits a multibyte codepoint (an unterminated construct
    /// whose last line ends in non-ASCII — e.g. a `--` comment ending in `→`).
    fn eof_span(&self) -> Span {
        let end = self.source.len();
        let start = (0..end)
            .rev()
            .find(|&i| self.source.is_char_boundary(i))
            .unwrap_or(0);
        Span::new(start, end)
    }

    fn expect(&mut self, kind: TokenKind, ctx: &str) -> Result<Token, CompileError> {
        match self.peek() {
            Some(t) if t.kind == kind => {
                self.bump();
                Ok(t)
            }
            Some(t) => Err(CompileError::new(
                "bynk.parse.expected_token",
                t.span,
                format!(
                    "expected {} {ctx}, found {}",
                    kind.describe(),
                    t.kind.describe()
                ),
            )),
            None => Err(CompileError::new(
                "bynk.parse.unexpected_eof",
                self.eof_span(),
                format!("expected {} {ctx}, found end of file", kind.describe()),
            )),
        }
    }

    fn expect_ident(&mut self, ctx: &str) -> Result<Ident, CompileError> {
        match self.peek() {
            Some(t) if t.kind == TokenKind::Ident => {
                self.bump();
                Ok(Ident {
                    name: self.slice(t.span).to_string(),
                    span: t.span,
                })
            }
            // v0.5 contextual keyword `on` doubles as an identifier in
            // expression / field-access positions so users can name fields and
            // parameters using it. It retains its keyword meaning only at
            // handler-decl-level (`on call(...)`).
            //
            // v0.7 / v0.112: `suite` and `case` are contextual too — they
            // introduce the suite declaration and its cases, but are perfectly
            // valid commons/context/field names otherwise.
            //
            // The tier is single-sourced in `keywords::RESERVED_CONTEXTUAL`:
            // this arm defers to it rather than hardcoding the token kinds, so
            // extending that list is enough to admit a new contextual keyword
            // here. Each of these words lexes only to its own token, so matching
            // the source text is equivalent to matching the kind.
            Some(t) if crate::keywords::is_reserved_contextual(self.slice(t.span)) => {
                self.bump();
                Ok(Ident {
                    name: self.slice(t.span).to_string(),
                    span: t.span,
                })
            }
            Some(t) if is_reserved_keyword(t.kind) => Err(CompileError::new(
                "bynk.parse.reserved_keyword",
                t.span,
                format!(
                    "expected identifier {ctx}, but `{}` is a reserved keyword",
                    self.slice(t.span)
                ),
            )
            .with_note("rename the identifier to something that is not a keyword")),
            Some(t) => Err(CompileError::new(
                "bynk.parse.expected_token",
                t.span,
                format!("expected identifier {ctx}, found {}", t.kind.describe()),
            )),
            None => Err(CompileError::new(
                "bynk.parse.unexpected_eof",
                self.eof_span(),
                format!("expected identifier {ctx}, found end of file"),
            )),
        }
    }

    // -- top level --

    /// Consume an optional doc block at the current position, returning the
    /// (content, end-of-doc span) pair. Returns None if the next token is not
    /// a doc block.
    fn take_doc_block(&mut self) -> Option<(String, Span)> {
        if self.peek_kind() == Some(TokenKind::DocBlock) {
            let t = self.bump().unwrap();
            let body = doc_block_content(self.source, t.span);
            return Some((body, t.span));
        }
        None
    }

    /// Collect all line-comment trivia leading the next declaration plus
    /// the optional doc block. Comments may appear both *before* and
    /// *between* the doc and the declaration; the spec canonicalises both
    /// groups above the doc, so we concatenate them.
    fn collect_item_lead(&mut self) -> (Vec<String>, Option<(String, Span)>) {
        let mut leading = self.take_leading_trivia();
        let doc = self.take_doc_block();
        if doc.is_some() {
            leading.extend(self.take_leading_trivia());
        }
        (leading, doc)
    }

    /// Attach a parsed doc block to a following declaration unless a blank
    /// line separates them, in which case the doc is orphaned (warning).
    fn finalize_doc(&mut self, doc: Option<(String, Span)>, next_span: Span) -> Option<String> {
        let (content, doc_span) = doc?;
        // A blank line between the doc and the next decl orphans the doc.
        if has_blank_line_between(self.source, doc_span.end, next_span.start) {
            self.warnings.push(
                CompileError::new(
                    "bynk.parse.orphan_doc_block",
                    doc_span,
                    "documentation block is separated from the following declaration by a blank line; it will not be attached",
                )
                .with_note(
                    "remove the blank line to attach the doc to the next declaration, \
                     or remove the doc block if it is not meant to document anything",
                ),
            );
            return None;
        }
        Some(content)
    }
}

/// Parse the body of a lexed double-quoted string literal (the lexeme,
/// including surrounding quotes), applying the v0 escape rules.
fn parse_string_literal(lexeme: &str, span: Span) -> Result<String, CompileError> {
    let bytes = lexeme.as_bytes();
    debug_assert!(bytes.first() == Some(&b'"') && bytes.last() == Some(&b'"'));
    let inner = &lexeme[1..lexeme.len() - 1];
    let mut out = String::with_capacity(inner.len());
    let mut chars = inner.chars();
    while let Some(c) = chars.next() {
        if c == '\\' {
            match chars.next() {
                Some('n') => out.push('\n'),
                Some('t') => out.push('\t'),
                Some('"') => out.push('"'),
                Some('\\') => out.push('\\'),
                other => {
                    return Err(CompileError::new(
                        "bynk.lex.bad_escape",
                        span,
                        format!(
                            "invalid escape sequence `\\{}` in string literal",
                            other.map(|c| c.to_string()).unwrap_or_default()
                        ),
                    )
                    .with_note("supported escapes: \\n \\t \\\" \\\\"));
                }
            }
        } else {
            out.push(c);
        }
    }
    Ok(out)
}

fn is_reserved_keyword(kind: TokenKind) -> bool {
    use TokenKind::*;
    matches!(
        kind,
        Commons
            | Type
            | Fn
            | Where
            | True
            | False
            | Int
            | String
            | Bool
            | Let
            | If
            | Else
            | Ok
            | Err
            | Result
            | ValidationError
            | Enum
            | Match
            | Option
            | Record
            | Self_
            | Some
            | None
            | Is
            | Opaque
            | Uses
            | Context
            | Consumes
            | Exports
            | Transparent
            | Agent
            | As
            | Capability
            | Effect
            | Do
            | Given
            | On
            | Http
            | Provides
            | Stub
            | Service
            | Actor
            | By
            | Expect
            | Suite
            | Case
            | Float
            | Duration
            | Instant
            | Bytes
            | JsonError
            | Property
            | Adapter
            | Binding
            | Cron
            | Queue
            | From
            | Protocol
            | Invariant
            | Implies
            | Requires
            | Ensures
            | Transition
    )
}

/// True when `kind` starts a top-level unit (`commons`/`context`/`adapter`/
/// `suite`) or an item within one of their bodies — every keyword any of
/// `parse_commons_brace`/`_fragment`, `parse_context_brace`/`_fragment`,
/// `parse_test_brace`/`_fragment`, or `parse_adapter_body` dispatches on
/// (`declarations.rs`). The single set [`Parser::recover_to_top_item`]'s sync
/// scan checks against — finding #27/#30: that scan had drifted from what the
/// item loops actually recognise (`Property`, `Actor`, `Event`, `Binding`,
/// and the `adapter` unit keyword itself were all missing), so an error
/// recovery sync could walk past a real item/unit boundary instead of
/// stopping there.
fn is_item_start(kind: TokenKind) -> bool {
    use TokenKind::*;
    matches!(
        kind,
        // Top-level unit keywords.
        Commons | Context | Adapter | Suite
        // Body items shared across commons/context/adapter.
        | Type | Fn | Messages | Event | Uses
        // Context/adapter-only body items.
        | Consumes | Exports | Capability | Provides | Service | Agent | Actor
        // Adapter-only.
        | Binding
        // Suite/test-only body items.
        | Stub | Case | Property
    )
}

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

    fn parse_str(src: &str) -> Result<Commons, Vec<CompileError>> {
        let toks = tokenize(src).map_err(|e| vec![e])?;
        parse(&toks, src)
    }

    fn parse_recover_str(src: &str) -> (Option<SourceUnit>, Vec<CompileError>) {
        let toks = match tokenize(src) {
            Ok(t) => t,
            Err(e) => return (None, vec![e]),
        };
        parse_unit_with_recovery(&toks, src)
    }

    /// Finding #29/#30: `parse_units_with_recovery` keeps every top-level unit
    /// an atomic `commons`+`suite` file declares (v0.113, DECISION S), where
    /// `parse_unit_with_recovery` keeps only the first — the defect the IDE's
    /// old single-unit parse entry point had (it silently discarded the
    /// trailing `suite`).
    #[test]
    fn parse_units_with_recovery_keeps_every_top_level_unit() {
        let src =
            "commons m {\n  fn f() -> Int { 1 }\n}\n\nsuite m\n\ncase \"c\" {\n  expect true\n}\n";
        let toks = tokenize(src).unwrap();
        let (units, errors) = parse_units_with_recovery(&toks, src);
        assert!(errors.is_empty(), "{errors:?}");
        assert_eq!(units.len(), 2, "expected both units, got {units:?}");
        assert!(matches!(units[0], SourceUnit::Commons(_)));
        assert!(matches!(units[1], SourceUnit::Suite(_)));

        // The singular wrapper still narrows to just the first, unchanged.
        let (unit, errors) = parse_unit_with_recovery(&toks, src);
        assert!(errors.is_empty(), "{errors:?}");
        assert!(matches!(unit, Some(SourceUnit::Commons(_))));
    }

    /// `parse_unit_with_recovery` always attempts at least one parse, even on
    /// empty input — `parse_units_with_recovery`'s loop must preserve that
    /// (its `while`-style peek check alone would skip the body entirely and
    /// silently return no error), since 16+ existing callers rely on an empty
    /// file still producing its usual diagnostic rather than a silent `None`
    /// with no error at all.
    #[test]
    fn empty_input_still_reports_an_error_through_the_plural_entry_point() {
        let toks = tokenize("").unwrap();
        let (units, errors) = parse_units_with_recovery(&toks, "");
        assert!(units.is_empty());
        assert!(
            !errors.is_empty(),
            "an empty file must still produce a diagnostic, not silently no units and no error"
        );

        let (unit, unit_errors) = parse_unit_with_recovery(&toks, "");
        assert!(unit.is_none());
        assert_eq!(
            errors.len(),
            unit_errors.len(),
            "the singular wrapper must see the same error(s) as the plural entry point"
        );
    }

    /// Finding #66: `parse_units_with_drain_check`'s `fully_drained` flag is
    /// `bynk-fmt`'s signal for whether its comment-loss guard can skip a
    /// re-tokenize-and-diff of its own output. It must be `true` for an
    /// ordinary file (every comment sits before a declaration/statement or
    /// trails one) and `false` the moment a comment sits inside an expression
    /// subtree, where `TriviaTable` has no field to attach it to.
    #[test]
    fn drain_check_reports_expression_interior_comments_as_undrained() {
        let ordinary = "commons x {\n-- note\ntype T = Int where Positive\n}\n";
        let toks = tokenize(ordinary).unwrap();
        let (_, _, drained) = parse_units_with_drain_check(&toks, ordinary).unwrap();
        assert!(
            drained,
            "a declaration-leading comment must be fully drained"
        );

        let lossy = "commons x {\n  fn f() -> Int {\n    1 + -- note\n    2\n  }\n}\n";
        let toks = tokenize(lossy).unwrap();
        let (_, _, drained) = parse_units_with_drain_check(&toks, lossy).unwrap();
        assert!(
            !drained,
            "a comment inside a binop expression must be reported as undrained"
        );
    }

    #[test]
    fn eof_span_never_splits_a_multibyte_codepoint() {
        // An unterminated construct whose final line ends in a non-ASCII char
        // (here a `--` comment ending in `→`) once produced an `unexpected_eof`
        // span of `len - 1 .. len`, landing on the arrow's last continuation
        // byte. Every reported span must sit on char boundaries.
        for src in [
            "commons x {\n  -- ends with an arrow →",
            "agent A {\n  key k: String\n  -- note 🦀",
            "commons y {\n  type T = é",
        ] {
            let (_unit, errors) = parse_recover_str(src);
            for e in &errors {
                assert!(
                    src.is_char_boundary(e.span.start) && src.is_char_boundary(e.span.end),
                    "span {:?} splits a codepoint in {src:?}",
                    e.span,
                );
            }
        }
    }

    #[test]
    fn reserved_contextual_keywords_readable_in_expression_position() {
        // Events track, slice 0 (#939): `expect_ident`'s `RESERVED_CONTEXTUAL`
        // exemption (`keywords::RESERVED_CONTEXTUAL`: case/event/messages/on/
        // suite) covers *declaring* a binding with one of these names — a
        // parameter, a `let` — but the primary-expression parser previously
        // only admitted plain `TokenKind::Ident` when *reading one back*.
        // Latent since messages/on/case/suite shipped (no fixture happened to
        // name a binding after one of them and read it back inside the body);
        // surfaced concretely when `event` joined the tier and collided with
        // `examples/event-log`'s pre-existing `add(event: Event)` handler.
        for kw in ["case", "event", "messages", "on", "suite"] {
            let src = format!("commons x\n\nfn f({kw}: Int) -> Int {{\n  {kw}\n}}\n");
            let result = parse_str(&src);
            assert!(
                result.is_ok(),
                "a parameter named `{kw}` must be readable in expression position: {:?}",
                result.err()
            );
        }
    }

    #[test]
    fn recovery_skips_garbage_between_decls() {
        // Two `type` declarations separated by garbage. Recovery should
        // accept both and report one error for the garbage between them.
        let src = "commons x {\n\
                   type A = Int where NonNegative\n\
                   ??? !!!\n\
                   type B = String where NonEmpty\n\
                   }";
        let (unit, errors) = parse_recover_str(src);
        let unit = unit.expect("recovery should produce a partial AST");
        let SourceUnit::Commons(c) = unit else {
            panic!("expected commons")
        };
        // Both type decls should have been collected despite the garbage.
        let names: Vec<_> = c
            .items
            .iter()
            .map(|i| match i {
                CommonsItem::Type(t) => t.name.name.clone(),
                _ => panic!("expected only types"),
            })
            .collect();
        assert!(
            names.contains(&"A".to_string()) && names.contains(&"B".to_string()),
            "expected both A and B; got {names:?}",
        );
        assert!(!errors.is_empty(), "expected at least one parse error");
    }

    #[test]
    fn recovery_handles_bad_first_decl_then_good_second() {
        // First decl is malformed (missing `=`); second is well-formed.
        let src = "commons x {\n\
                   type A Int where NonNegative\n\
                   type B = String where NonEmpty\n\
                   }";
        let (unit, errors) = parse_recover_str(src);
        let unit = unit.expect("recovery should produce a partial AST");
        let SourceUnit::Commons(c) = unit else {
            panic!("expected commons")
        };
        let names: Vec<_> = c
            .items
            .iter()
            .filter_map(|i| match i {
                CommonsItem::Type(t) => Some(t.name.name.clone()),
                _ => None,
            })
            .collect();
        assert!(
            names.contains(&"B".to_string()),
            "B should be parsed after A's failure; got {names:?}"
        );
        assert!(!errors.is_empty(), "expected at least one parse error");
    }

    /// Finding #27/#30: an error two levels deep inside `f`'s body (a
    /// `match` arm's own block) used to make `recover_to_top_item`'s flat,
    /// depth-blind scan stop at the *first* `}` it saw — the arm block's own,
    /// not `f`'s. Two more `}` (the match's, then `f`'s) then got consumed one
    /// at a time across repeated recovery re-entries, and the outer item loop
    /// eventually mistook the commons's *own* closing `}` for having arrived
    /// early, returning zero items and a spurious second
    /// `bynk.parse.expected_unit_header` error. With brace-depth tracking, `g`
    /// is recovered as the sole item and only `f`'s own error is reported.
    #[test]
    fn recovery_skips_a_nested_blocks_own_closing_brace() {
        let src = "commons m {\n  \
                   fn f() -> Int {\n    \
                   match 1 {\n      \
                   is 1 -> { let z = }\n      \
                   is _ -> 2\n    \
                   }\n  \
                   }\n  \
                   fn g() -> Int { 2 }\n\
                   }\n";
        let (unit, errors) = parse_recover_str(src);
        let unit = unit.expect("recovery should produce a partial AST");
        let SourceUnit::Commons(c) = unit else {
            panic!("expected commons")
        };
        let names: Vec<_> = c
            .items
            .iter()
            .filter_map(|i| match i {
                CommonsItem::Fn(f) => match &f.name {
                    FnName::Free(id) => Some(id.name.clone()),
                    _ => None,
                },
                _ => None,
            })
            .collect();
        assert_eq!(
            names,
            vec!["g".to_string()],
            "g must still be recovered as an item; got {names:?}"
        );
        assert!(
            !errors
                .iter()
                .any(|e| e.category == "bynk.parse.expected_unit_header"),
            "the outer body's own closing brace must not be mistaken for \
             end-of-file: {errors:?}"
        );
    }

    #[test]
    fn doc_block_attaches_to_type() {
        let c =
            parse_str("commons x {\n---\nA descriptive doc.\n---\ntype T = Int where Positive\n}")
                .unwrap();
        let CommonsItem::Type(t) = &c.items[0] else {
            panic!()
        };
        assert!(t.documentation.is_some());
        assert!(
            t.documentation
                .as_ref()
                .unwrap()
                .contains("A descriptive doc.")
        );
    }

    #[test]
    fn interpolated_string_parses_into_parts() {
        // v0.43: `"Hi, \(name)!"` splits into chunk / hole / chunk.
        let c = parse_str("commons x\n\nfn f(name: String) -> String {\n  \"Hi, \\(name)!\"\n}\n")
            .unwrap();
        let CommonsItem::Fn(f) = &c.items[0] else {
            panic!("expected fn")
        };
        let ExprKind::InterpStr(parts) = &f.body.tail.kind else {
            panic!("expected InterpStr, got {:?}", f.body.tail.kind)
        };
        assert_eq!(parts.len(), 3);
        assert!(matches!(&parts[0], InterpPart::Chunk(s) if s == "Hi, "));
        assert!(
            matches!(&parts[1], InterpPart::Hole(h) if matches!(&h.kind, ExprKind::Ident(id) if id.name == "name"))
        );
        assert!(matches!(&parts[2], InterpPart::Chunk(s) if s == "!"));
    }

    #[test]
    fn interpolated_hole_parses_a_full_expression() {
        // A hole holds an arbitrary expression, not just an identifier.
        let c =
            parse_str("commons x\n\nfn f(a: Int, b: Int) -> String {\n  \"sum = \\(a + b)\"\n}\n")
                .unwrap();
        let CommonsItem::Fn(f) = &c.items[0] else {
            panic!("expected fn")
        };
        let ExprKind::InterpStr(parts) = &f.body.tail.kind else {
            panic!("expected InterpStr")
        };
        assert!(matches!(&parts[1], InterpPart::Hole(h) if matches!(&h.kind, ExprKind::BinOp(..))));
    }

    #[test]
    fn empty_interpolation_hole_is_rejected() {
        let errs = parse_str("commons x\n\nfn f() -> String {\n  \"\\()\"\n}\n").unwrap_err();
        assert!(
            errs.iter()
                .any(|e| e.category == "bynk.parse.empty_interpolation"),
            "expected empty_interpolation; got {errs:?}"
        );
    }

    #[test]
    fn interpolation_hole_lex_error_span_is_rebased() {
        // #716: a lex error inside a `\(…)` hole once carried a span relative to
        // the hole substring — never rebased by `hole.start` — so it pointed at
        // the file's opening bytes and could split a multibyte char, tripping
        // the char-boundary invariant. The error must land on the offending
        // bytes within the hole and stay on char boundaries.
        let cases = [
            // `$` is not a valid token; the error should point at it, not byte 0.
            "commons x\n\nfn f() -> String {\n  \"a \\($)\"\n}\n",
            // Integer overflow — the reported span must cover the literal itself.
            "commons x\n\nfn f() -> String {\n  \"n = \\(99999999999999999999)\"\n}\n",
            // A multibyte char before the hole means an un-rebased span could
            // land inside the `é`; the rebased span must not.
            "commons x\n\nfn f() -> String {\n  \"é \\($)\"\n}\n",
        ];
        for src in cases {
            let errs = parse_str(src).unwrap_err();
            assert!(!errs.is_empty(), "expected a lex error for {src:?}");
            for e in &errs {
                assert!(
                    src.is_char_boundary(e.span.start) && src.is_char_boundary(e.span.end),
                    "span {:?} splits a codepoint in {src:?}",
                    e.span,
                );
                // The error must point inside the interpolation hole, not at the
                // header text that precedes it.
                let hole_start = src.find("\\(").expect("case has a hole") + 2;
                assert!(
                    e.span.start >= hole_start,
                    "span {:?} precedes the hole (starts at {hole_start}) in {src:?}",
                    e.span,
                );
            }
        }
    }

    #[test]
    fn fragment_form_parses() {
        let c = parse_str("commons x.y\n\ntype T = Int where NonNegative\n").unwrap();
        assert_eq!(c.form, CommonsForm::Fragment);
        assert_eq!(c.items.len(), 1);
    }

    #[test]
    fn uses_parses() {
        let c = parse_str("commons x\n\nuses other.lib\n").unwrap();
        assert_eq!(c.uses.len(), 1);
        assert_eq!(c.uses[0].target.joined(), "other.lib");
    }

    fn parse_unit_str(src: &str) -> Result<SourceUnit, Vec<CompileError>> {
        let toks = tokenize(src).map_err(|e| vec![e])?;
        parse_unit(&toks, src)
    }

    #[test]
    fn minimal_context_parses() {
        let u = parse_unit_str("context commerce.orders {}").unwrap();
        let SourceUnit::Context(c) = u else {
            panic!("expected context");
        };
        assert_eq!(c.name.joined(), "commerce.orders");
        assert!(c.items.is_empty());
    }

    #[test]
    fn context_consumes_and_exports_parse() {
        let src = "context commerce.orders {\n  uses commerce.money\n  consumes commerce.payment\n  exports opaque { OrderId }\n  exports transparent { OrderError }\n  type OrderId = String where Matches(\"ORD-[0-9]+\")\n  type OrderError = enum { CartEmpty, BadInput }\n}";
        let u = parse_unit_str(src).unwrap();
        let SourceUnit::Context(c) = u else { panic!() };
        assert_eq!(c.uses.len(), 1);
        assert_eq!(c.consumes.len(), 1);
        assert_eq!(c.exports.len(), 2);
        assert_eq!(c.exports[0].kind, ExportKind::Type(Visibility::Opaque));
        assert_eq!(c.exports[1].kind, ExportKind::Type(Visibility::Transparent));
    }

    #[test]
    fn context_fragment_form_parses() {
        let src = "context x.y\n\nuses other.lib\nconsumes other.ctx\nexports opaque { T }\n\ntype T = Int where NonNegative\n";
        let u = parse_unit_str(src).unwrap();
        let SourceUnit::Context(c) = u else { panic!() };
        assert_eq!(c.form, CommonsForm::Fragment);
        assert_eq!(c.uses.len(), 1);
        assert_eq!(c.consumes.len(), 1);
        assert_eq!(c.exports.len(), 1);
    }

    #[test]
    fn opaque_type_parses() {
        let c = parse_str("commons x { type T = opaque Int where NonNegative }").unwrap();
        let CommonsItem::Type(t) = &c.items[0] else {
            panic!()
        };
        assert!(matches!(t.body, TypeBody::Opaque { .. }));
    }

    #[test]
    fn empty_commons() {
        let c = parse_str("commons fitness.units {}").unwrap();
        assert_eq!(c.name.joined(), "fitness.units");
        assert!(c.items.is_empty());
    }

    #[test]
    fn one_type_decl() {
        let c = parse_str("commons x { type Metres = Int where NonNegative }").unwrap();
        assert_eq!(c.items.len(), 1);
        let CommonsItem::Type(t) = &c.items[0] else {
            panic!()
        };
        assert_eq!(t.name.name, "Metres");
        match &t.body {
            TypeBody::Refined {
                base, refinement, ..
            } => {
                assert_eq!(*base, BaseType::Int);
                assert!(refinement.is_some());
            }
            _ => panic!("expected refined body"),
        }
    }

    #[test]
    fn function_decl() {
        let c = parse_str("commons x { fn add(a: Int, b: Int) -> Int { a + b } }").unwrap();
        let CommonsItem::Fn(f) = &c.items[0] else {
            panic!()
        };
        assert_eq!(f.name.ident().name, "add");
        assert_eq!(f.params.len(), 2);
    }

    #[test]
    fn chained_comparison_is_error() {
        let errs = parse_str("commons x { fn f(a: Int, b: Int, c: Int) -> Bool { a < b < c } }")
            .unwrap_err();
        assert_eq!(errs[0].category, "bynk.parse.non_associative");
    }

    #[test]
    fn chained_equality_is_error() {
        let errs = parse_str("commons x { fn f(a: Int, b: Int, c: Int) -> Bool { a == b == c } }")
            .unwrap_err();
        assert_eq!(errs[0].category, "bynk.parse.non_associative");
    }

    /// Run `f` on a thread with a generous stack. The depth-guard tests build
    /// source that, *without* the guard, overflows — so if the guard ever
    /// regressed we want a clean assertion failure, not a `SIGABRT` that takes
    /// the whole test binary down. A large stack also absorbs the fat frames a
    /// debug build spends per recursion level (production release frames are
    /// ~9 KB/level, so `MAX_NESTING_DEPTH = 64` sits well inside a 1 MB stack;
    /// a debug frame is several times larger and would overflow libtest's
    /// default 2 MB test thread near the limit even though the guard fires).
    fn on_big_stack<T: Send + 'static>(f: impl FnOnce() -> T + Send + 'static) -> T {
        std::thread::Builder::new()
            .stack_size(64 * 1024 * 1024)
            .spawn(f)
            .unwrap()
            .join()
            .unwrap()
    }

    #[test]
    fn deeply_nested_parens_are_bounded_not_overflowed() {
        // Without a depth guard the parenthesised-expression recursion
        // (`parse_primary` -> `parse_expr` -> …) overflows the stack and aborts
        // the process (#713). Well past the limit it must instead report a
        // bounded-depth diagnostic. The nesting is left open so the guard, not
        // a later `)`, is what stops the descent.
        let errs = on_big_stack(|| {
            let depth = crate::MAX_NESTING_DEPTH + 8;
            let src = format!(
                "commons x {{ fn f() -> Int {{ {}0{} }} }}",
                "(".repeat(depth),
                ")".repeat(depth),
            );
            parse_str(&src).unwrap_err()
        });
        assert_eq!(errs[0].category, "bynk.parse.nesting_too_deep");
    }

    #[test]
    fn deeply_nested_types_are_bounded_not_overflowed() {
        // The type parser self-recurses through generic type arguments
        // (`parse_type_ref` -> `parse_type_atom` -> `parse_type_ref`); the same
        // guard bounds it (#713). A right-nested `Result[Int, …]` in parameter
        // position drives that recursion.
        let errs = on_big_stack(|| {
            let depth = crate::MAX_NESTING_DEPTH + 8;
            let src = format!(
                "commons x {{ fn f(x: {}Int{}) -> Int {{ 0 }} }}",
                "Result[Int, ".repeat(depth),
                "]".repeat(depth),
            );
            parse_str(&src).unwrap_err()
        });
        assert_eq!(errs[0].category, "bynk.parse.nesting_too_deep");
    }

    #[test]
    fn deeply_nested_patterns_are_bounded_not_overflowed() {
        // Variant patterns are a third self-recursive descent (`parse_pattern`
        // -> `parse_pattern_binding` -> `parse_pattern`) that routes through
        // neither `parse_expr` nor `parse_type_ref`; without its own guard a
        // nested `Ok(Ok(…))` match arm reproduces the #713 crash.
        let errs = on_big_stack(|| {
            let depth = crate::MAX_NESTING_DEPTH + 8;
            let src = format!(
                "commons x {{ fn f(n: Int) -> Int {{ match n {{ {}n{} => 0 }} }} }}",
                "Ok(".repeat(depth),
                ")".repeat(depth),
            );
            parse_str(&src).unwrap_err()
        });
        assert_eq!(errs[0].category, "bynk.parse.nesting_too_deep");
    }

    #[test]
    fn nesting_below_the_limit_still_parses() {
        // The guard must not reject ordinary well-nested source: a paren-nested
        // expression comfortably under the limit still parses cleanly.
        let ok = on_big_stack(|| {
            let depth = crate::MAX_NESTING_DEPTH - 8;
            let src = format!(
                "commons x {{ fn f() -> Int {{ {}0{} }} }}",
                "(".repeat(depth),
                ")".repeat(depth),
            );
            parse_str(&src).is_ok()
        });
        assert!(ok, "well-nested source under the limit should parse");
    }

    #[test]
    fn let_statement_parses() {
        let c = parse_str("commons x { fn f(n: Int) -> Int { let y = n + 1\n y } }").unwrap();
        let CommonsItem::Fn(f) = &c.items[0] else {
            panic!()
        };
        assert_eq!(f.body.statements.len(), 1);
        match &f.body.statements[0] {
            Statement::Let(l) => {
                assert_eq!(l.name.name, "y");
                assert!(l.type_annot.is_none());
            }
            _ => panic!("expected a pure `let` statement"),
        }
    }

    #[test]
    fn let_with_annotation() {
        let c = parse_str("commons x { fn f(n: Int) -> Int { let y: Int = n\n y } }").unwrap();
        let CommonsItem::Fn(f) = &c.items[0] else {
            panic!()
        };
        match &f.body.statements[0] {
            Statement::Let(l) => assert!(l.type_annot.is_some()),
            _ => panic!("expected a pure `let` statement"),
        }
    }

    #[test]
    fn if_else_parses_as_expression() {
        let c = parse_str("commons x { fn f(b: Bool) -> Int { if b { 1 } else { 0 } } }").unwrap();
        let CommonsItem::Fn(f) = &c.items[0] else {
            panic!()
        };
        assert!(matches!(f.body.tail.kind, ExprKind::If { .. }));
    }

    #[test]
    fn else_if_chain_parses() {
        let c = parse_str(
            "commons x { fn f(n: Int) -> Int { if n < 0 { -1 } else if n == 0 { 0 } else { 1 } } }",
        )
        .unwrap();
        let CommonsItem::Fn(f) = &c.items[0] else {
            panic!()
        };
        let ExprKind::If { else_block, .. } = &f.body.tail.kind else {
            panic!()
        };
        // The else-branch is a block whose tail is another `If`.
        assert!(else_block.statements.is_empty());
        assert!(matches!(else_block.tail.kind, ExprKind::If { .. }));
    }

    #[test]
    fn ok_and_err_parse_as_expressions() {
        let c = parse_str("commons x { fn f(n: Int) -> Result[Int, String] { Ok(n) } }").unwrap();
        let CommonsItem::Fn(f) = &c.items[0] else {
            panic!()
        };
        assert!(matches!(f.body.tail.kind, ExprKind::Ok(_)));

        let c =
            parse_str("commons x { fn f(n: Int) -> Result[Int, String] { Err(\"x\") } }").unwrap();
        let CommonsItem::Fn(f) = &c.items[0] else {
            panic!()
        };
        assert!(matches!(f.body.tail.kind, ExprKind::Err(_)));
    }

    #[test]
    fn question_postfix_parses() {
        let c = parse_str(
            "commons x { type T = Int where Positive\n fn f(n: Int) -> Result[T, ValidationError] { let x = T.of(n)?\n Ok(x) } }",
        )
        .unwrap();
        let CommonsItem::Fn(f) = &c.items[1] else {
            panic!()
        };
        let Statement::Let(l) = &f.body.statements[0] else {
            panic!("expected a pure `let` statement");
        };
        assert!(matches!(l.value.kind, ExprKind::Question(_)));
    }

    #[test]
    fn constructor_call_parses() {
        let c = parse_str(
            "commons x { type T = Int where Positive\n fn f(n: Int) -> Result[T, ValidationError] { T.of(n) } }",
        )
        .unwrap();
        let CommonsItem::Fn(f) = &c.items[1] else {
            panic!()
        };
        // v0.2: T.of(n) parses as a MethodCall with receiver Ident("T"); the
        // checker reinterprets it as a static call by noticing T is a type.
        let ExprKind::MethodCall {
            receiver, method, ..
        } = &f.body.tail.kind
        else {
            panic!("expected MethodCall, got {:?}", f.body.tail.kind)
        };
        let ExprKind::Ident(id) = &receiver.kind else {
            panic!("expected receiver Ident");
        };
        assert_eq!(id.name, "T");
        assert_eq!(method.name, "of");
    }

    #[test]
    fn result_type_ref_parses() {
        let c = parse_str("commons x { fn f(n: Int) -> Result[Int, String] { Ok(n) } }").unwrap();
        let CommonsItem::Fn(f) = &c.items[0] else {
            panic!()
        };
        assert!(matches!(f.return_type, TypeRef::Result(_, _, _)));
    }

    #[test]
    fn result_missing_arg_count_errors() {
        let errs = parse_str("commons x { fn f(n: Int) -> Result[Int] { Ok(n) } }").unwrap_err();
        assert_eq!(errs[0].category, "bynk.parse.generic_arg_count");
    }

    #[test]
    fn field_access_parses_in_v0_2() {
        // v0.2: field access is supported (the type checker validates the
        // field exists on the receiver's type). Parser-level acceptance:
        let c =
            parse_str("commons x { type R = { foo: Int }\n fn f(r: R) -> Int { r.foo } }").unwrap();
        let CommonsItem::Fn(f) = &c.items[1] else {
            panic!()
        };
        assert!(matches!(f.body.tail.kind, ExprKind::FieldAccess { .. }));
    }

    // -- v1.1 trivia attachment --

    #[test]
    fn leading_line_comment_attaches_to_next_decl() {
        let src = "commons x {\n-- explain the type\ntype T = Int where NonNegative\n}";
        let c = parse_str(src).unwrap();
        let CommonsItem::Type(t) = &c.items[0] else {
            panic!()
        };
        assert_eq!(t.trivia.leading, vec![" explain the type".to_string()]);
        assert!(t.trivia.trailing.is_none());
    }

    #[test]
    fn trailing_line_comment_attaches_to_prev_decl() {
        let src = "commons x {\ntype T = Int where NonNegative  -- trailing note\n}";
        let c = parse_str(src).unwrap();
        let CommonsItem::Type(t) = &c.items[0] else {
            panic!()
        };
        assert!(t.trivia.leading.is_empty());
        assert_eq!(t.trivia.trailing.as_deref(), Some(" trailing note"));
    }

    #[test]
    fn grouped_leading_comments_attach_together() {
        let src = "commons x {\n-- one\n-- two\n-- three\ntype T = Int where Positive\n}";
        let c = parse_str(src).unwrap();
        let CommonsItem::Type(t) = &c.items[0] else {
            panic!()
        };
        assert_eq!(
            t.trivia.leading,
            vec![" one".to_string(), " two".to_string(), " three".to_string()],
        );
    }

    #[test]
    fn comment_with_doc_block_keeps_both() {
        // Both `-- intro` and the doc block should attach to the type decl.
        let src = "commons x {\n-- intro\n---\ndocs\n---\ntype T = Int where Positive\n}";
        let c = parse_str(src).unwrap();
        let CommonsItem::Type(t) = &c.items[0] else {
            panic!()
        };
        assert_eq!(t.trivia.leading, vec![" intro".to_string()]);
        assert_eq!(t.documentation.as_deref(), Some("docs"));
    }

    #[test]
    fn messages_keyword_does_not_collide_with_a_commons_name_segment() {
        // `messages` is RESERVED_CONTEXTUAL (like `case`/`on`/`suite`), not a
        // hard keyword: `commons app.messages { ... }` — the design's own
        // natural naming choice for a bundle commons — must still parse.
        // (Caught during slice-1 implementation: a first pass made `messages`
        // a plain hard keyword and this exact name broke.)
        let src = "commons app.messages {\ntype T = Int where Positive\n}";
        let c = parse_str(src).unwrap();
        assert_eq!(c.name.joined(), "app.messages");
    }

    #[test]
    fn messages_decl_parses_tag_annotation_and_entries() {
        // message-bundles slice 1 (#859): the construct + doc/trivia wiring.
        let src = "commons app.messages {\n\
                   -- intro\n\
                   ---\n\
                   docs\n\
                   ---\n\
                   messages \"en\" @reference {\n\
                   \"greeting\" => \"Hello, {name}!\"\n\
                   \"farewell\" => \"Bye\"\n\
                   } -- trailing\n\
                   }";
        let c = parse_str(src).unwrap();
        let CommonsItem::Messages(m) = &c.items[0] else {
            panic!("expected a messages item, got {:?}", c.items[0]);
        };
        assert_eq!(m.tag, "en");
        assert_eq!(m.annotations.len(), 1);
        assert_eq!(m.annotations[0].name.name, "reference");
        assert!(m.annotations[0].args.is_empty());
        assert_eq!(m.entries.len(), 2);
        assert_eq!(m.entries[0].code, "greeting");
        assert_eq!(m.entries[0].template, "Hello, {name}!");
        assert_eq!(m.entries[1].code, "farewell");
        assert_eq!(m.entries[1].template, "Bye");
        assert_eq!(m.trivia.leading, vec![" intro".to_string()]);
        assert_eq!(m.documentation.as_deref(), Some("docs"));
        assert_eq!(m.trivia.trailing.as_deref(), Some(" trailing"));
    }

    #[test]
    fn messages_decl_parses_with_no_annotation_and_no_entries() {
        // The parser stays permissive on annotation cardinality (zero-or-more)
        // — "exactly one `@reference`" is a checker concern (validate.rs), not
        // a parse error.
        let src = "commons app.messages {\nmessages \"en\" {\n}\n}";
        let c = parse_str(src).unwrap();
        let CommonsItem::Messages(m) = &c.items[0] else {
            panic!("expected a messages item, got {:?}", c.items[0]);
        };
        assert_eq!(m.tag, "en");
        assert!(m.annotations.is_empty());
        assert!(m.entries.is_empty());
    }

    #[test]
    fn messages_decl_parses_syntactically_inside_a_context_too() {
        // Commons-only legality is a checker concern (bynk.messages.outside_commons
        // in bynk-emit's project validation), not a parser rejection — mirrors
        // how `service`/`agent` already parse syntactically inside `adapter`
        // bodies for the same reason.
        let src = "context app.svc {\nmessages \"en\" @reference {\n\"a\" => \"b\"\n}\n}";
        let toks = tokenize(src).unwrap();
        let (unit, errors) = parse_unit_with_recovery(&toks, src);
        assert!(errors.is_empty(), "unexpected parse errors: {errors:?}");
        let Some(SourceUnit::Context(ctx)) = unit else {
            panic!("expected a context")
        };
        let CommonsItem::Messages(m) = &ctx.items[0] else {
            panic!("expected a messages item, got {:?}", ctx.items[0]);
        };
        assert_eq!(m.tag, "en");
    }

    #[test]
    fn comment_before_let_statement_attaches() {
        let src = "commons x {\nfn f(n: Int) -> Int {\n-- pick a value\nlet y = n + 1\ny\n}\n}";
        let c = parse_str(src).unwrap();
        let CommonsItem::Fn(f) = &c.items[0] else {
            panic!()
        };
        let Statement::Let(l) = &f.body.statements[0] else {
            panic!()
        };
        assert_eq!(l.trivia.leading, vec![" pick a value".to_string()]);
    }

    #[test]
    fn comment_before_tail_attaches_to_block_tail() {
        let src = "commons x {\nfn f(n: Int) -> Int {\nlet y = n + 1\n-- result\ny\n}\n}";
        let c = parse_str(src).unwrap();
        let CommonsItem::Fn(f) = &c.items[0] else {
            panic!()
        };
        assert_eq!(f.body.tail_leading_comments, vec![" result".to_string()],);
    }

    /// #637 Gap A: the contextual keywords `on` / `suite` / `case` are lexer
    /// tokens but `expect_ident` admits them as identifiers outside their one
    /// keyword position, so they are valid record-field and parameter names.
    /// The keyword reference now renders them as a distinct "contextual" tier
    /// rather than claiming (falsely) that they cannot be used as identifiers.
    #[test]
    fn contextual_keywords_are_valid_identifiers() {
        // Record field names.
        let c = parse_str("commons demo {\n  type R = { on: Int, suite: String, case: Bool }\n}")
            .expect("`on`/`suite`/`case` are valid field names");
        let CommonsItem::Type(_) = &c.items[0] else {
            panic!("expected a type decl")
        };

        // Function parameter names (the other `expect_ident` position).
        parse_str("commons demo {\n  fn f(on: Int, case: Int) -> Int { 0 }\n}")
            .expect("`on`/`case` are valid parameter names");

        // `suite` too, as a field name.
        parse_str("commons demo {\n  type R = { suite: Int }\n}")
            .expect("`suite` is a valid field name");
    }

    /// Drift guard: every alphabetic keyword the lexer declares must be
    /// classified by `is_reserved_keyword`, or be one of the *contextual*
    /// keywords `expect_ident` deliberately admits as identifiers
    /// (`on`/`suite`/`case`). Everything else in this codebase that can
    /// drift has a guard; this predicate had silently fallen 17 keywords
    /// behind, degrading the reserved-keyword diagnostic to the generic
    /// expected-token one.
    #[test]
    fn is_reserved_keyword_covers_every_lexer_keyword() {
        let lexer_src = include_str!("lexer.rs");
        let mut words = Vec::new();
        for line in lexer_src.lines() {
            let t = line.trim();
            if let Some(rest) = t.strip_prefix("#[token(\"")
                && let Some(word) = rest.split('"').next()
                && word.chars().next().is_some_and(|c| c.is_ascii_alphabetic())
                && word.chars().all(|c| c.is_ascii_alphanumeric() || c == '_')
            {
                words.push(word.to_string());
            }
        }
        assert!(
            words.len() > 30,
            "keyword extraction looks broken: only {} words",
            words.len()
        );
        // Contextual keywords double as identifiers (see `expect_ident`); the
        // tier is single-sourced in `keywords::RESERVED_CONTEXTUAL`.
        use crate::keywords::RESERVED_CONTEXTUAL;
        let mut unclassified = Vec::new();
        for word in &words {
            let tokens = crate::lexer::tokenize(word).expect("keyword lexes");
            let kind = tokens.first().expect("keyword yields a token").kind;
            if !is_reserved_keyword(kind) && !RESERVED_CONTEXTUAL.contains(&word.as_str()) {
                unclassified.push(word.clone());
            }
        }
        assert!(
            unclassified.is_empty(),
            "keywords missing from is_reserved_keyword (add them, or document \
             them as contextual): {unclassified:?}"
        );
    }

    /// Finding #27/#30: pins `is_item_start` to exactly the keyword set
    /// `declarations.rs`'s six item loops (`parse_commons_brace`/`_fragment`,
    /// `parse_context_brace`/`_fragment`, `parse_test_brace`/`_fragment`) plus
    /// `parse_adapter_body` dispatch on, as of this writing — the drift this
    /// finding fixed (`Property`, `Actor`, `Event`, `Binding`, and the
    /// `adapter` unit keyword itself were all missing from
    /// `recover_to_top_item`'s old hand-written sync list, even though every
    /// one of them is a real item/unit start). Adding a new item keyword to
    /// any of those loops should mean deliberately updating this list too,
    /// not silently leaving recovery unable to resync at it.
    #[test]
    fn is_item_start_matches_the_pinned_keyword_set() {
        use TokenKind::*;
        let expected_true = [
            Commons, Context, Adapter, Suite, Type, Fn, Messages, Event, Uses, Consumes, Exports,
            Capability, Provides, Service, Agent, Actor, Binding, Stub, Case, Property,
        ];
        for kind in expected_true {
            assert!(is_item_start(kind), "{kind:?} must be an item start");
        }
        let expected_false = [
            Ident, Plus, Minus, Colon, Dot, Eq, LBrace, RBrace, LParen, RParen, If, Else, Let,
            Where, True, False, Match, Is, On, Given,
        ];
        for kind in expected_false {
            assert!(!is_item_start(kind), "{kind:?} must not be an item start");
        }
    }

    /// Fuzz-found (#516): a context-only keyword at item position in a
    /// commons errors without consuming the token, and the recovery sync
    /// stops at exactly that keyword — without a progress guard the item
    /// loop re-reported the same error until memory ran out.
    #[test]
    fn recovery_makes_progress_on_context_only_keyword_in_commons() {
        let src = "commons demo\n\ncapability Logger {\n  fn log(m: String) -> Effect[()]\n}\n";
        let tokens = crate::lexer::tokenize(src).unwrap();
        let (unit, errors) = parse_unit_with_recovery(&tokens, src);
        assert!(unit.is_some(), "the commons header still parses");
        assert!(
            errors
                .iter()
                .any(|e| e.category == "bynk.capability.outside_context"),
            "the misplaced capability is reported: {errors:?}"
        );
        // Termination is the real assertion (this used to OOM); a bounded,
        // non-repeating error list is the observable proxy.
        assert!(errors.len() < 10, "recovery repeated itself: {errors:?}");
    }

    #[test]
    fn trailing_file_comment_becomes_unit_trailing() {
        // A comment after the last item but before EOF (fragment form)
        // becomes the commons body's trailing comments so the formatter
        // can preserve it.
        let src = "commons x\n\ntype T = Int where Positive\n-- afterword\n";
        let c = parse_str(src).unwrap();
        assert_eq!(c.trailing_comments, vec![" afterword".to_string()]);
    }

    #[test]
    fn trailing_file_comment_after_a_brace_form_commons_is_not_dropped() {
        // Regression: the brace form's item loop exits on `RBrace`, never
        // reaching the fragment form's end-of-input case that drains the
        // trivia table's epilogue — so a comment after the closing `}` was
        // silently discarded (and, per `epilogue_is_empty`'s debug_assert,
        // would panic a debug build instead of round-tripping through
        // `bynk-fmt`).
        let src = "commons x {\n  type T = Int where Positive\n}\n-- afterword\n";
        let c = parse_str(src).unwrap();
        assert_eq!(c.trailing_comments, vec![" afterword".to_string()]);
    }

    #[test]
    fn trailing_file_comment_after_a_brace_form_context_is_not_dropped() {
        // Same regression as the commons case, for `parse_context_brace`.
        let src = "context x {\n  type T = Int where Positive\n}\n-- afterword\n";
        let SourceUnit::Context(c) = parse_unit_str(src).unwrap() else {
            panic!("expected context");
        };
        assert_eq!(c.trailing_comments, vec![" afterword".to_string()]);
    }

    #[test]
    fn trailing_file_comment_after_a_brace_form_suite_is_not_dropped() {
        // Same regression as the commons case, for `parse_test_brace`.
        let src = "suite x {\n  case \"c\" {\n    expect 1 == 1\n  }\n}\n-- afterword\n";
        let SourceUnit::Suite(s) = parse_unit_str(src).unwrap() else {
            panic!("expected suite");
        };
        assert_eq!(s.trailing_comments, vec![" afterword".to_string()]);
    }

    /// Finding #30: unlike the three regressions just above,
    /// `parse_adapter_body`'s brace-closing path never called
    /// `take_epilogue` at all (not a regression from a shared pattern — it
    /// simply never had the call), so a comment after a brace-form adapter's
    /// closing `}` was silently dropped. The fragment form (no braces) was
    /// already correct.
    #[test]
    fn trailing_file_comment_after_a_brace_form_adapter_is_not_dropped() {
        let src = "adapter x {\n  binding \"./x.ts\"\n}\n-- afterword\n";
        let SourceUnit::Adapter(a) = parse_unit_str(src).unwrap() else {
            panic!("expected adapter");
        };
        assert_eq!(a.trailing_comments, vec![" afterword".to_string()]);
    }

    // -- Six-fold unification (review Part 3): the fragment-only ordering
    // restrictions declarations.rs's brace/fragment pairs preserve, now that
    // they share one function each behind `brace: bool`. None of these had
    // any prior test coverage at all. --

    /// Fragment-form commons: `uses` must precede every `type`/`fn`.
    #[test]
    fn commons_fragment_rejects_uses_after_a_decl() {
        let src = "commons x\n\ntype T = Int where Positive\nuses bynk.list\n";
        let errs = parse_str(src).unwrap_err();
        assert!(
            errs.iter()
                .any(|e| e.category == "bynk.parse.uses_after_decls"),
            "{errs:?}"
        );
    }

    /// The same ordering is NOT enforced in brace form — `uses` may appear
    /// anywhere in the body.
    #[test]
    fn commons_brace_allows_uses_after_a_decl() {
        let src = "commons x {\n  type T = Int where Positive\n  uses bynk.list\n}\n";
        parse_str(src).expect("brace form must not enforce fragment's uses-ordering rule");
    }

    /// Fragment-form context: `consumes` must precede every `type`/`fn`/etc.
    #[test]
    fn context_fragment_rejects_consumes_after_a_decl() {
        let src = "context x\n\ntype T = Int where Positive\nconsumes bynk\n";
        let errs = parse_unit_str(src).unwrap_err();
        assert!(
            errs.iter()
                .any(|e| e.category == "bynk.parse.consumes_after_decls"),
            "{errs:?}"
        );
    }

    /// Fragment-form context: `exports` must precede every `type`/`fn`/etc.
    #[test]
    fn context_fragment_rejects_exports_after_a_decl() {
        let src = "context x\n\ntype T = Int where Positive\nexports opaque { T }\n";
        let errs = parse_unit_str(src).unwrap_err();
        assert!(
            errs.iter()
                .any(|e| e.category == "bynk.parse.exports_after_decls"),
            "{errs:?}"
        );
    }

    /// Brace-form context enforces none of the three orderings.
    #[test]
    fn context_brace_allows_consumes_and_exports_after_a_decl() {
        let src = "context x {\n  type T = Int where Positive\n  consumes bynk\n  exports opaque { T }\n}\n";
        parse_unit_str(src)
            .expect("brace form must not enforce fragment's consumes/exports-ordering rules");
    }

    /// Fragment-form suite/test: `uses` must precede every `stub`/`case`/`property`.
    #[test]
    fn test_fragment_rejects_uses_after_a_decl() {
        let src = "suite m\n\ncase \"c\" {\n  expect true\n}\nuses bynk.list\n";
        let errs = parse_unit_str(src).unwrap_err();
        assert!(
            errs.iter()
                .any(|e| e.category == "bynk.parse.uses_after_decls"),
            "{errs:?}"
        );
    }

    /// Brace-form suite/test allows `uses` anywhere.
    #[test]
    fn test_brace_allows_uses_after_a_decl() {
        let src = "suite m {\n  case \"c\" {\n    expect true\n  }\n  uses bynk.list\n}\n";
        parse_unit_str(src).expect("brace form must not enforce fragment's uses-ordering rule");
    }

    // ---- #636: `if`/`match` condition vs record construction ----

    /// Parse `body` as the tail expression of a fn and return its kind.
    fn body_tail(body: &str) -> ExprKind {
        let src = format!("commons x\n\nfn f() -> Int {{\n  {body}\n}}\n");
        let c = parse_str(&src).unwrap_or_else(|e| panic!("parse failed for {body:?}: {e:?}"));
        let CommonsItem::Fn(f) = &c.items[0] else {
            panic!("expected fn, got {:?}", c.items[0]);
        };
        f.body.tail.kind.clone()
    }

    fn body_err(body: &str) -> Vec<CompileError> {
        let src = format!("commons x\n\nfn f() -> Int {{\n  {body}\n}}\n");
        parse_str(&src).expect_err(&format!("expected a parse error for {body:?}"))
    }

    #[test]
    fn if_condition_ending_in_ident_does_not_swallow_a_single_ident_branch() {
        // #636: `ready { result }` shares its shape with a shorthand-field
        // record construction. In condition position the branch must win.
        for src in [
            "if ready { result } else { fallback }",
            "if ready { fallback } else { result }",
            "if !ready { result } else { fallback }",
            "if a == b { result } else { fallback }",
            "if a && b { result } else { fallback }",
        ] {
            let ExprKind::If {
                then_block,
                else_block,
                ..
            } = body_tail(src)
            else {
                panic!("expected If for {src:?}, got {:?}", body_tail(src));
            };
            // Both branches carry a bare-identifier tail — proof the `{ … }`
            // was read as a block, not consumed as a record by the condition.
            assert!(
                matches!(&then_block.tail.kind, ExprKind::Ident(_)),
                "then-branch tail not an ident for {src:?}: {:?}",
                then_block.tail.kind,
            );
            assert!(
                matches!(&else_block.tail.kind, ExprKind::Ident(_)),
                "else-branch tail not an ident for {src:?}: {:?}",
                else_block.tail.kind,
            );
        }
    }

    #[test]
    fn else_less_if_with_single_ident_branch_parses() {
        // The no-`else` reproduction: previously errored `found `}``.
        let ExprKind::If { then_block, .. } = body_tail("if ready { result }") else {
            panic!("expected If");
        };
        assert!(matches!(&then_block.tail.kind, ExprKind::Ident(_)));
    }

    #[test]
    fn record_construction_still_parses_in_value_position() {
        // The restriction is confined to condition spines — an ordinary value
        // position still constructs records, including the shorthand tail form.
        assert!(matches!(
            body_tail("Point { x }"),
            ExprKind::RecordConstruction { .. }
        ));
        assert!(matches!(
            body_tail("Point { x: 1, y: 2 }"),
            ExprKind::RecordConstruction { .. }
        ));
        assert!(matches!(
            body_tail("Empty {}"),
            ExprKind::RecordConstruction { .. }
        ));
    }

    #[test]
    fn parenthesised_record_is_allowed_in_condition_head() {
        // A delimiter lifts the restriction: `(ready { result })` constructs a
        // record even in condition position (mirrors Rust's paren escape).
        let ExprKind::If { cond, .. } =
            body_tail("if (ready { result }) { branch } else { other }")
        else {
            panic!("expected If");
        };
        let ExprKind::Paren(inner) = &cond.kind else {
            panic!("expected a parenthesised condition, got {:?}", cond.kind);
        };
        assert!(
            matches!(&inner.kind, ExprKind::RecordConstruction { .. }),
            "parenthesised record in condition head should still construct: {:?}",
            inner.kind,
        );
    }

    #[test]
    fn record_in_call_arg_within_condition_still_constructs() {
        // The restriction is lifted through a call-argument delimiter, so a
        // record literal passed to a predicate in the condition still parses.
        let ExprKind::If { cond, .. } = body_tail("if check(Point { x: 1 }) { a } else { b }")
        else {
            panic!("expected If");
        };
        let ExprKind::Call { args, .. } = &cond.kind else {
            panic!("expected Call in condition, got {:?}", cond.kind);
        };
        assert!(matches!(&args[0].kind, ExprKind::RecordConstruction { .. }));
    }

    #[test]
    fn safe_condition_shapes_are_unaffected() {
        // Cases the issue lists as already-safe must stay safe.
        assert!(matches!(
            body_tail("if ready == true { result } else { fallback }"),
            ExprKind::If { .. }
        ));
        assert!(matches!(
            body_tail("if (ready) { result } else { fallback }"),
            ExprKind::If { .. }
        ));
        assert!(matches!(
            body_tail("if ready { \"a\" } else { \"b\" }"),
            ExprKind::If { .. }
        ));
    }

    #[test]
    fn empty_match_reports_its_own_diagnostic() {
        // #636: `match result {}` once parsed `result {}` as an empty record,
        // masking `bynk.parse.empty_match`. The intended diagnostic is now
        // reachable.
        let errs = body_err("match result {}");
        assert!(
            errs.iter().any(|e| e.category == "bynk.parse.empty_match"),
            "expected empty_match; got {errs:?}",
        );
    }

    #[test]
    fn match_discriminant_ending_in_ident_parses() {
        // A `match` over a bare-identifier discriminant reaches its arm list.
        assert!(matches!(
            body_tail("match ready { x => x }"),
            ExprKind::Match { .. }
        ));
    }

    /// #981: an identifier statement immediately followed, on its own line, by
    /// a standalone `()` must stay two separate constructs — not merge into a
    /// zero-arg call. `status := Paid` / `()` is an Assign statement whose
    /// value is the bare identifier `Paid`, then a unit tail; it must never
    /// parse as a single `status := Paid()` (a call). The call-parens rule
    /// mirrors the v0.20b same-line `[` rule already applied to type
    /// arguments: a postfix opener that begins a new line does not continue
    /// the previous token.
    #[test]
    fn identifier_statement_followed_by_unit_tail_does_not_merge_into_a_call() {
        let src = "commons c\n\nfn f() -> Int {\n  status := Paid\n  ()\n}\n";
        let c = parse_str(src).unwrap_or_else(|e| panic!("parse failed: {e:?}"));
        let CommonsItem::Fn(f) = &c.items[0] else {
            panic!("expected fn, got {:?}", c.items[0]);
        };
        assert_eq!(
            f.body.statements.len(),
            1,
            "expected exactly one Assign statement, got {:?}",
            f.body.statements
        );
        let Statement::Assign(a) = &f.body.statements[0] else {
            panic!(
                "expected an Assign statement, got {:?}",
                f.body.statements[0]
            );
        };
        assert!(
            matches!(a.value.kind, ExprKind::Ident(_)),
            "assign value must stay the bare identifier `Paid`, got {:?}",
            a.value.kind
        );
        assert!(
            matches!(f.body.tail.kind, ExprKind::UnitLit),
            "the `()` must remain the block's own tail, got {:?}",
            f.body.tail.kind
        );
    }

    /// #981: the same same-line rule extends to a method call's parens — a
    /// `.method` immediately followed, on its own line, by a standalone `()`
    /// must not merge into `.method()`.
    #[test]
    fn method_reference_followed_by_unit_tail_does_not_merge_into_a_call() {
        let src = "commons c\n\nfn f() -> Int {\n  let y = x.field\n  ()\n}\n";
        let c = parse_str(src).unwrap_or_else(|e| panic!("parse failed: {e:?}"));
        let CommonsItem::Fn(f) = &c.items[0] else {
            panic!("expected fn, got {:?}", c.items[0]);
        };
        let Statement::Let(l) = &f.body.statements[0] else {
            panic!("expected a Let statement, got {:?}", f.body.statements[0]);
        };
        assert!(
            matches!(l.value.kind, ExprKind::FieldAccess { .. }),
            "let value must stay a field access, got {:?}",
            l.value.kind
        );
        assert!(
            matches!(f.body.tail.kind, ExprKind::UnitLit),
            "the `()` must remain the block's own tail, got {:?}",
            f.body.tail.kind
        );
    }

    #[test]
    fn unparenthesised_record_in_condition_head_now_errors() {
        // #636 narrowing (matches Rust): a record literal in condition *head*
        // position must be parenthesised. Unparenthesised, `Point` reads as the
        // discriminant and `{ x: 1 }` as the arm list, whose first "arm" `x: 1`
        // is not an arm — so the parse fails. Pinned so the divergence from the
        // (still-accepting) tree-sitter grammar is deliberate, not a bug.
        assert!(
            !body_err("match Point { x: 1 } { p => p }").is_empty(),
            "unparenthesised record discriminant should not parse",
        );
        // Parenthesised, the record is the discriminant and the match parses.
        let ExprKind::Match { discriminant, .. } = body_tail("match (Point { x: 1 }) { p => p }")
        else {
            panic!("expected Match for the parenthesised form");
        };
        let ExprKind::Paren(inner) = &discriminant.kind else {
            panic!(
                "expected a parenthesised discriminant, got {:?}",
                discriminant.kind
            );
        };
        assert!(matches!(&inner.kind, ExprKind::RecordConstruction { .. }));
    }
}