elly_core/

parse.rs

//! Parsing: Muon tree → Elly chunk, resolving names as it goes.
//!
//! A program is a single chain (`<expr>`). Chains are split on the first `&`-prefixed
//! item into an application spine and a trailing abstraction. Comments are dropped.
//!
//! The parser emits straight into a [`Builder`](crate::code::Builder): each
//! method pushes the nodes below its own and returns that node unpushed (see
//! [`code`](crate::code)). It resolves every name as it reaches it, against
//! a [`Scope`] that mirrors the environment the evaluator will build, so no
//! tree is built and no pass runs after the parse. A module is read in two
//! walks over its chains: the declarations first, which give every member its
//! index, then the bodies (see `docs/done/2026-10-11_elly-ctx-chunks.md`).
//!
//! Patterns are emitted as [`Pat`]s matched directly by the evaluator.
//! `&p0 &p1 …` runs collect into one multi-parameter lambda, and application
//! spines and spread calls flatten into one `App` node.

use alloc::vec::Vec;

use muon::{Chain, Group, Item, Seq};
use num_bigint::BigInt;

use crate::builtins::Builtin;
use crate::code::{len32, Builder, ChunkId, HomeLeaf, Member, Node, NodeId, Pat, PatId, Run, Text};
use crate::module::{ImportSpec, ModuleName};
use crate::resolve::{Barrier, Ref, Scope};
use crate::source::{report, ChunkSpan, DocSource, Pos};
use crate::sym::Sym;
use crate::Ctx;

/// Copy a source string slice into an owned text leaf.
fn text(s: &str) -> Text {
    Text::from(s)
}

// TODO: use thiserror?
/// A failure at the syntax or parse stage.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum Error {
    /// The syntax layer (Muon) rejected the input.
    Syntax(muon::ParseError),
    /// The input is a valid Muon tree but not a valid Elly program (this
    /// subset), with the span of the source the error is about.
    Parse(ParseError, muon::Span),
}

impl Error {
    /// The span of the source the error is about; a syntax error is at an
    /// offset, so its span is empty.
    pub fn span(&self) -> muon::Span {
        match self {
            Error::Syntax(e) => muon::Span {
                offset: e.offset as Pos,
                length: 0,
            },
            Error::Parse(_, span) => *span,
        }
    }

    /// Reports the error in the document `name`, whose text is `text`, as
    /// `name:line:column: message` and the line, the span underlined (see
    /// [`source::report`](crate::source::report)).
    pub fn report(&self, name: &str, text: &str) -> alloc::string::String {
        let message = match self {
            Error::Syntax(e) => alloc::format!("syntax error: {:?}", e.kind),
            Error::Parse(e, _) => alloc::format!("parse error: {e:?}"),
        };
        report(name, text, self.span(), &message)
    }
}

// TODO: use thiserror?
/// A parse failure: the input is a valid Muon tree but not a well-formed Elly
/// program in this subset.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum ParseError {
    /// The top-level sequence held no chain (nothing to evaluate).
    EmptyProgram,
    /// The top-level sequence held more than one chain; top-level sequencing
    /// is deferred (a program is a single expression).
    MultipleExpressions,
    /// A chain reduced to nothing (e.g. only comments).
    EmptyChain,
    /// A `&` binder with no body — `&x` alone is ill-formed (yet).
    AbsWithoutBody,
    /// A `&` prefix on something that is not a well-formed binder header (see
    /// `BadPattern` for the pattern content itself).
    BadBinder,
    /// A binder appeared where an atomic expression was expected. Not reachable
    /// via the split logic, kept so parsing never panics.
    UnexpectedBinder,
    /// A `.` sigil on something that is not a single name/number segment (e.g.
    /// `.(…)`, `.&x`). `.foo` / `.0` are symbols; the record sugar `.(…)` and
    /// other prefixed items are deferred / ill-formed.
    BadSymbol,
    /// A bare `.` used as an atom (`f . g`, a lone `.`). At the Muon layer this
    /// is a `<punct>`; Elly reserves it for a future `.` / `|>` application
    /// combinator, which is deferred.
    CombinatorDeferred,
    /// `_` used as a reference. `_` is the discard pattern (a binder that binds
    /// nothing), never a name that can be read back.
    DiscardReference,
    /// A `&`-binder tried to introduce a name starting with `__`. Such names are
    /// reserved for builtins / special forms and may be referenced but not bound.
    ReservedName,
    /// A `<sym>` that begins like a number but is not a valid integer literal
    /// (`1a`, `0xZZ`, `1__2`, `0x`). Since a `<name>` may not start with a digit,
    /// a digit-leading sym must be a well-formed `<int>` or it is an error.
    MalformedNumber,
    /// A stray `:` / `=` (or other) `<punct>` item at atom position. Muon parses
    /// this punctuation, but outside a `let` binding (`=`) or a map entry (`:`)
    /// it has no atomic reading. (A `#{…}` map literal and a `#[…]` list value are
    /// their own atoms; the bare `{…}` / `[…]` forms are rejected, not deferred.)
    PunctAtAtom,
    /// A map entry (`<braces>` chain) whose key is missing or malformed: no `:`
    /// after the key, or a key item that is not a bare atom, a `.`-symbol, a `(…)`
    /// computed key, or a `#[…]` / `#{…}` literal key (`{ : 1 }`, `{ foo }`).
    MalformedMapKey,
    /// A `let` not followed by a binder group — `let 1 e`. An *empty* group is not
    /// an error: `let () e` binds nothing and is `e` (see `Parser::let_block`).
    LetMissingBinders,
    /// A `let (…)` with nothing after the binder group; the body is required.
    LetMissingBody,
    /// A `recur` not followed by a binder group — `recur 1 e`. As with `let`, an
    /// empty group is not an error: `recur () e` is `e`.
    RecurMissingBinders,
    /// A `recur (…)` with nothing after the binder group; the body is required.
    RecurMissingBody,
    /// A `recur` binding whose name is already in scope. The group's bindings are
    /// simultaneous, so inside it the name would mean the group's own binding and
    /// never the outer one — the opposite of what the identical `let` line means.
    /// Detected by resolution (`resolve.rs`); carries the offending name.
    RecurShadowsOuter(Text),
    /// A binding inside a `let (…)` group is not `<pattern> "=" <expr>`: missing
    /// or repeated top-level `=`, an empty pattern, or an empty value.
    MalformedBinding,
    /// A keyword (`let`, `with`) used as a reference or a binder. Keywords are
    /// syntax, not names: they may be neither read nor bound.
    ReservedKeyword,
    /// A malformed pattern: an empty pattern, a comma-grouped `(a, b)` used as a
    /// single pattern, a misplaced `...rest`, or any item with no pattern reading.
    BadPattern,
    /// A comparand after `=` / `<` / `>` that is not a single **atom** (a name or
    /// a literal). A pattern is a closed grammar — `= f x`, `< (f x)`, `= [a]`
    /// have no reading; write `= x`, `= 5`, or `.foo`.
    ComparandNotAtom,
    /// A bare **matching literal** used as an entire `&`-header or `let` binding
    /// LHS: a number (`&42`), a symbol (`&.foo`), or a string (`&"foo"`).
    /// Parenthesize it — `&(42)`, `&(.foo)`, `&("foo")`, `let ((42) = v)` — so the
    /// "match this literal" intent is explicit (a bare literal reads as a value, or
    /// as an intended binder). A literal *nested* in `[…]` / `{…}` / `(…)` / an
    /// or-pattern needs no parens.
    BareLiteralHeader,
    /// A `<str>` literal with an **unpaired UTF-16 surrogate** escape (`"\uD83D"`,
    /// a high or low `\uXXXX` not completing a pair). Muon accepts it lexically,
    /// but UTF-8 cannot represent it, so Elly's decode rejects it at parse.
    LoneSurrogate,
    /// A bare top-level `|` in a `let` binding's LHS: `let ((x=.a) | (x=.b) = v)`.
    /// Wrap the or-pattern — `let (((x=.a) | (x=.b)) = v) e` — so it does not
    /// visually compete with the binding's own `=`.
    LetOrUnparenthesized,
    /// An `as <Type>` whose `<Type>` is not one of the closed kinds
    /// `Int Sym List Map Fun`.
    UnknownType,
    /// An or-pattern `(p | q)` whose arms bind different sets of names.
    OrBindersMismatch,
    /// A `|>` pipe combinator with a missing operand — `|> f`, `x |>`, or
    /// `x |> |> f`. Both sides of `|>` must be non-empty.
    MalformedPipe,
    /// A name reference that resolves to no enclosing `&`-binding — a free
    /// variable. Detected by resolution (`resolve.rs`) while parsing, so it is
    /// a *static* error: the program is rejected before it runs, rather
    /// than raising `.unbound_name` at eval. Carries the offending name (spans
    /// are still a TODO). `__`-names never reach here — they are resolved to
    /// [`Node::Builtin`] at parse.
    UnboundName(Text),
    /// A module binding whose left-hand side is not a single bare
    /// name: a destructuring pattern, a literal, a discard, or a digit-leading
    /// token. Module top-level keys are plain names in v0. A `__…` or keyword LHS
    /// reports [`ParseError::ReservedName`] / [`ParseError::ReservedKeyword`] instead.
    BadModuleItemName,
    /// A module defines the same item name twice, or an `import`'s local name is
    /// also an item name. A name means one thing inside a module, so both are
    /// rejected here. The `Foo = import "spec"` form is the one place a name is
    /// both an import and an item: it is a single declaration, and it makes them
    /// the same thing.
    DuplicateModuleItem,
    /// An `import` that is neither `import "<spec>" as <Name>` nor
    /// `<Name> = import "<spec>"`: a missing `as`, a spec that is not a string
    /// literal, or trailing items. The spec is a literal in a fixed position —
    /// which is what makes a module's imports a static, auditable list — so there
    /// is nothing to compute here.
    MalformedImport,
    /// An `import` somewhere other than a module's top level — today, inside a
    /// `recur` group. An import is a frame slot the const
    /// stage fills before the module exists, so it can only be written in a
    /// module's own source. Written anywhere else, `import` is an ordinary keyword
    /// and reports [`ParseError::ReservedKeyword`].
    MisplacedImport,
    /// A `const` declaration that is neither `const <name>`, `const (<name> …)`
    /// nor `<name> = const`: a declaration that is not a bare name, a group whose
    /// chains are not bare names, or a **payload** — `const x = 1`, `x = const 1`.
    /// The payload forms are reserved for const-time expressions and rejected
    /// until those exist (see `docs/done/2026-08-13_elly-modules-iotas.md`).
    MalformedConst,
    /// A `const` somewhere other than a module's top level — today, inside a
    /// `recur` group. A group is built while a program runs
    /// and has no instance of its own to mint against, so an iota can only be
    /// declared in a module's source. Written anywhere else, `const` is an
    /// ordinary keyword and reports [`ParseError::ReservedKeyword`].
    MisplacedConst,
    /// A binder — a pattern binder, a `let` binding, a `recur` binding — taking a
    /// name the enclosing module declares as an **import**. A declaration's name
    /// means one thing over the whole module, so it may not be shadowed from
    /// inside (see `docs/done/2026-08-13_elly-modules-iotas.md`). Carries the name.
    ShadowsImport(Text),
    /// A binder taking a name the enclosing module declares as a `const`
    /// [iota](ParseError::ShadowsImport). Carries the name.
    ShadowsIota(Text),
    /// A `local` declaration that is neither `local <name> = <expr>` nor the
    /// group `local (<name> = <expr> …)`: a left-hand side that is not a bare
    /// name, a group chain that is not a binding, or a missing body. The
    /// head-with-arguments form `local f x = <expr>` lands here too — it is a
    /// template moditem, left open (see `docs/done/2026-08-13_elly-modules-local.md`).
    MalformedLocal,
    /// A `local` somewhere other than a module's top level — today, inside a
    /// `recur` group, where every binding is private
    /// already, so the keyword would say nothing. Written anywhere else, `local`
    /// is an ordinary keyword and reports [`ParseError::ReservedKeyword`].
    MisplacedLocal,
    /// A binder taking a name the enclosing module declares as a
    /// [`local`](ParseError::ShadowsImport). Carries the name.
    ShadowsLocal(Text),
    /// A binder taking a name the enclosing module — or an enclosing
    /// `recur` group — declares as an **item**. Carries the
    /// name. This is the direction opposite to
    /// [`RecurShadowsOuter`](ParseError::RecurShadowsOuter), which stops a group
    /// binding from shadowing a name already in scope; together they make a
    /// declared name unshadowable from either side.
    ShadowsItem(Text),
    /// A `__` name the language does not define, in either position it can be
    /// written: a module top-level left-hand side (`__mian = …`) or a reference
    /// in an expression (`__mian`). The `__` namespace belongs to the language —
    /// a source may write the builtins and the **reserved moditems** it defines
    /// and nothing else — so a misspelling fails here, naming the namespace,
    /// rather than becoming an item nobody reads or a name nothing binds.
    /// Carries the name as written.
    UnknownReserved(Text),
    /// A module declaring the same reserved moditem twice (two `__main`s). A
    /// reserved moditem is a single slot, not a table, so there is no second one
    /// to hold. Carries the name.
    DuplicateReserved(Text),
    /// A reserved moditem somewhere other than a module's top level — today,
    /// inside a `recur` group. A group is an item table,
    /// not a module source, and nothing would ever read the slot. Written
    /// anywhere else, `__main` is an ordinary `__` name and reports
    /// [`UnknownReserved`](ParseError::UnknownReserved).
    MisplacedReserved,
    /// A [home-module leaf](crate::HomeLeaf) — `Self`, `#Self(…)`, `x.Self`, or
    /// the `Self <pat>` pattern — outside a module body. Each reads the module
    /// its body is written in, and there is none: the term is not a module's, or
    /// it is a `recur` group in a program that is not a
    /// module. One test covers both, since a group is not a module either.
    /// Carries the name — `Self`, the one word every form is spelled with.
    OutsideModule(Text),
    /// An `as <Proto>` pattern whose reference is a `__` name that is not a
    /// **prototype**: a builtin that is no module at all (`as __eq`), or `__Err`,
    /// which is a namespace of operations that no value answers `__proto` with —
    /// so the check could never hold. Rejected here rather than compiled into a
    /// pattern that always refutes. Carries the name.
    NotAPrototype(Text),
    /// A [`&`](muon::Item::Prefixed)-headed **run** (`&x.0`, `&(a, b).0`) — a
    /// binder glued to a following atom with no whitespace. A binder is one
    /// prefixed atom, so the glued tail has no reading; write it spaced
    /// (`&x .0`) to apply, or restructure. See `docs/done/2026-09-09_elly-parse-runs.md` §C.
    BinderRunGlued,
    /// An `<int>`-then-`.<digits>` run — the float-like run `3.14` (Muon groups
    /// the two atoms, see `docs/done/2026-09-08_muon-runs.md`). Float literals do
    /// not exist yet; this holds the notation open for them (a real float is a
    /// later `Num` extension) while giving a clear error now instead of the
    /// runtime `.not_applicable` a spaced `3 .14` projection raises.
    FloatLiteralUnsupported,
    /// A [`#`](muon::Item::Prefixed)-prefixed form other than the three that
    /// read: `#[…]` (a list), `#{…}` (a map), and `#Self(…)` / `#Self …`
    /// (construction). The `#` sigil marks a **literal notation**, and the
    /// remaining shapes — `#<sym>`, `#<str>`, `#(…)`, `#.name` — are reserved
    /// for future literal kinds with no reading yet. A bare `#Self` lands here
    /// as well: construction is a form, not a value, so it may only head a
    /// spine (see `Parser::app_spine`). See `docs/todo/elly-syntax-v1.md` §2.
    ReservedLiteralForm,
    /// A bare `[…]` where a list literal or list pattern is written. After the
    /// reshuffle (phase 3), the list literal uses the `#`-prefixed spelling
    /// exclusively: write `#[…]`. See `docs/todo/elly-syntax-v1.md` § 3–5.
    BareListLiteral,
    /// A bare `{…}` carrying a `:`-clause where a map literal or map pattern is
    /// written. After the reshuffle, the map literal uses the `#`-prefixed
    /// spelling exclusively: write `#{…}`. A `:`-clause has no reading in a block
    /// (nothing legal in a block starts `<key> :`), so a brace group with one is
    /// this error in every position; a brace group *without* a `:`-clause is a
    /// block (step 6), and the empty `{}` is the unit value.
    /// See `docs/todo/elly-syntax-v1.md` § 3–5.
    BareMapLiteral,
    /// A block `{…}` whose final clause is a binding (`{ …, x = v }`). A block's
    /// value is its last clause's value and its bindings do not escape, so a
    /// trailing binding would bind a name nothing can read and leave no value to
    /// return — as a `let` with no body does. End the block with an expression.
    /// See `docs/todo/elly-syntax-v1.md` § 5 (review) and step 6.
    BlockTrailingBinding,
    /// A `case` with no `{…}` arm block — `case x` or `case` alone, or a trailing
    /// item that is not a brace group. The block is where the clauses live, so a
    /// `case` without one has nothing to match against and no reading.
    CaseMissingArms,
    /// A `case` subject that is more than one item — `case f x { … }`. The subject
    /// is exactly one item so the arm block's `{…}` is unambiguous; group a
    /// compound subject (`case (f x) { … }`) or pipe it in (`f x |> case { … }`).
    CaseSubjectExtra,
    /// A `case` arm whose chain is not headed by `&` — a clause that is not a
    /// binder. Every arm is `& <pattern> … <body>`; a bare expression is not one.
    ArmNotBinder,
    /// A `case` arm with a pattern (and any guards) but no body after them —
    /// `& x` or `& x when (c)` alone. An arm's body is required.
    ArmMissingBody,
    /// A `when` guard with no `(…)` condition group — `when` at the end of a
    /// header, or `when` followed by something other than a parenthesized group.
    WhenMissingCond,
}

/// A parse error unwinding, with the span of the source it is about, or
/// `NONE` until a caller that knows what it was parsing gives one: an error
/// is placed at the innermost item, chain or declaration that places it.
#[derive(Debug)]
struct Failure(ParseError, ChunkSpan);

/// A parser result.
type Parsed<T> = Result<T, Failure>;

impl From<ParseError> for Failure {
    fn from(error: ParseError) -> Self {
        Failure(error, ChunkSpan::NONE)
    }
}

impl Failure {
    /// The failure, placed at `span()` if it has no span yet.
    fn or_at(self, span: impl FnOnce() -> ChunkSpan) -> Self {
        match self.1.get() {
            Some(_) => self,
            None => Failure(self.0, span()),
        }
    }

    /// The error a compile entry point reports, its span in the document
    /// `src`. An error nothing placed is at the document's start.
    fn into_error(self, src: Source<'_>) -> Error {
        let span = self.1.in_doc(src.base).unwrap_or_default();
        Error::Parse(self.0, span)
    }
}

// ===========================================================================
// entry points
// ===========================================================================

/// How an expression source resolves its free names.
pub(crate) enum Root<'p> {
    /// A free name is [`ParseError::UnboundName`].
    Closed,
    /// A free name is bound into the root frame, as if given: an open term.
    Open,
    /// The root frame holds `prelude`, and any other free name is unbound.
    Prelude(&'p [Text]),
}

impl Ctx {
    /// Parse expression source `src` into a new chunk named `__eval_N`: a top
    /// module with only a body.
    pub(crate) fn compile_expr(&self, src: &str, root: Root<'_>) -> Result<ChunkId, Error> {
        let seq = muon::parse(src).map_err(Error::Syntax)?;
        let (names, auto_bind) = match root {
            Root::Closed => (Vec::new(), false),
            Root::Open => (Vec::new(), true),
            Root::Prelude(prelude) => (prelude.iter().map(|n| self.intern(n)).collect(), false),
        };
        let scope = Scope::new(self, names, 0, auto_bind, Vec::new());
        let mut b = Builder::new();
        let src = Source {
            text: src,
            base: b.add_doc(None, src),
        };
        let mut p = Parser::new(self, scope, b, src);
        let top = p.b.enter_module();
        let (body, span) = p.program(&seq).map_err(|f| f.into_error(src))?;
        let body = p.b.push(body, span);
        let mark = p.b.member_scratch.len();
        p.b.leave_module(top, None, mark, 0, 0, &[], Vec::new(), body);
        Ok(self.add_built(p.b, None, "__eval_"))
    }

    /// Compile module source `src` against a frame of ordered names into a
    /// new chunk named `name`, or `__module_N` if it has none.
    ///
    /// References to frame names resolve to de Bruijn locals. Lookup order:
    /// enclosing binders $\to$ imports $\to$ module members (iotas $\to$ items
    /// $\to$ locals) $\to$ frame $\to$ builtin aliases. Module imports occupy
    /// the leading frame slots.
    /// `doc` is where the source came from, `None` for an anonymous source.
    pub(crate) fn compile_source(
        &self,
        src: &str,
        frame: &[Text],
        name: Option<ModuleName>,
        doc: Option<DocSource>,
    ) -> Result<ChunkId, Error> {
        let seq = muon::parse(src).map_err(Error::Syntax)?;
        let b = self.emit_module(&seq, src, doc, frame, name.clone())?;
        Ok(self.add_built(b, name, "__module_"))
    }

    fn emit_module(
        &self,
        seq: &Seq<'_>,
        src: &str,
        doc: Option<DocSource>,
        frame: &[Text],
        name: Option<ModuleName>,
    ) -> Result<Builder, Error> {
        let mut b = Builder::new();
        let source = Source {
            text: src,
            base: b.add_doc(doc, src),
        };
        let chains = chain_slices(seq);
        let decls = declarations(&chains, self, source).map_err(|f| f.into_error(source))?;
        let items = sorted(&decls.items);
        let locals = sorted(&decls.locals);
        let iotas = sorted(&decls.iotas);
        // The imports are the leading frame slots, searched before the
        // members; the host's frame names follow them.
        let mut slots: Vec<Sym> = decls.imports.iter().map(|(n, _)| *n).collect();
        slots.extend(frame.iter().map(|n| self.intern(n)));
        let members = Barrier::Module {
            items: items.clone(),
            locals: locals.clone(),
            iotas: iotas.clone(),
        };
        let scope = Scope::new(
            self,
            slots.clone(),
            decls.imports.len(),
            false,
            alloc::vec![members],
        );
        let mut p = Parser::new(self, scope, b, source);
        let top = p.b.enter_module();
        let (mark, body) = p
            .members(&decls, &items, &locals, &iotas)
            .map_err(|f| f.into_error(source))?;
        let specs = decls.imports.into_iter().map(|(_, spec)| spec).collect();
        let (n_items, n_locals) = (len32(items.len()), len32(locals.len()));
        p.b.leave_module(top, name, mark, n_items, n_locals, &slots, specs, body);
        Ok(p.b)
    }
}

/// The text a chunk's document was parsed from, and its first position in
/// the chunk: what turns the Muon tree's items into chunk spans.
#[derive(Clone, Copy)]
struct Source<'s> {
    text: &'s str,
    base: Pos,
}

impl Source<'_> {
    /// The span of `item`, which was parsed from this source.
    fn item(self, item: &Item<'_>) -> ChunkSpan {
        let span = item.span(self.text);
        ChunkSpan::new(self.base + span.offset, span.length)
    }

    /// The span from the first of `items` to the last, which were parsed from
    /// this source in order.
    fn items(self, items: &[&Item<'_>]) -> ChunkSpan {
        match items {
            [] => ChunkSpan::NONE,
            [item] => self.item(item),
            [first, .., last] => self.item(first).join(self.item(last)),
        }
    }

    /// The span of a bracket group, its brackets included.
    fn group(self, group: &Group<'_>) -> ChunkSpan {
        ChunkSpan::new(self.base + group.span.offset, group.span.length)
    }
}

/// `names`, sorted by `Sym`: the order of a member index space.
fn sorted(names: &[Sym]) -> Vec<Sym> {
    let mut names = names.to_vec();
    names.sort();
    names
}

// ===========================================================================
// module declarations
// ===========================================================================

/// One body a module source declares, read in the declaration walk and
/// emitted in the second.
enum Decl<'b, 'a> {
    /// `name = <body>`.
    Item(Sym, Vec<&'b Item<'a>>),
    /// `Name = import "…"` or `name = const`: an item that forwards the
    /// import or the iota of the same name.
    Forward(Sym),
    /// `local name = <body>`.
    Local(Sym, Vec<&'b Item<'a>>),
    /// `__main = <body>`, the reserved moditem.
    Main(Vec<&'b Item<'a>>),
}

/// A module source's left-hand sides, read before any body.
struct Decls<'b, 'a> {
    /// What each body is, in source order, with its declaration's span.
    bodies: Vec<(Decl<'b, 'a>, ChunkSpan)>,
    /// The span of every member's declaration, sorted by name (see
    /// [`span`](Self::span)).
    spans: Vec<(Sym, ChunkSpan)>,
    /// The item names, in source order.
    items: Vec<Sym>,
    /// The `local` names, in source order.
    locals: Vec<Sym>,
    /// The names declared by `const`, in source order — the module's iotas.
    iotas: Vec<Sym>,
    /// The `import` declarations, in source order, which is frame-slot order.
    imports: Vec<(Sym, ImportSpec)>,
    has_main: bool,
}

impl Decls<'_, '_> {
    /// The span of member `name`'s declaration: `name = body`, or the name of
    /// an iota a group declares. An item and an iota of one name are one
    /// declaration, `name = const`.
    fn span(&self, name: Sym) -> ChunkSpan {
        match self.spans.binary_search_by(|(n, _)| n.cmp(&name)) {
            Ok(i) => self.spans[i].1,
            Err(_) => ChunkSpan::NONE,
        }
    }
}

/// Read a module source's (or a `recur` group's) declarations: the items,
/// locals, iotas, imports and `__main`, with their bodies unparsed, rejecting
/// a name declared twice.
///
/// Items are single bare names in v0. An import is both a frame slot and, in
/// its re-exporting form `Foo = import "spec"`, an item.
fn declarations<'b, 'a>(
    chains: &[Vec<&'b Item<'a>>],
    ctx: &Ctx,
    src: Source<'_>,
) -> Parsed<Decls<'b, 'a>> {
    let mut d = Decls {
        bodies: Vec::new(),
        spans: Vec::new(),
        items: Vec::new(),
        locals: Vec::new(),
        iotas: Vec::new(),
        imports: Vec::new(),
        has_main: false,
    };
    let mut re = Reexports::default();
    for ci in chains {
        declaration(ci, ctx, src, &mut d, &mut re).map_err(|f| f.or_at(|| src.items(ci)))?;
    }
    // A name declared twice in two kinds is placed at its later declaration
    // that has a span: a private import records none.
    let dup = |name: &Sym| {
        let span = d.spans.iter().rev().find(|(n, _)| n == name);
        Err(Failure(
            ParseError::DuplicateModuleItem,
            span.map_or(ChunkSpan::NONE, |(_, span)| *span),
        ))
    };
    for (name, _) in &d.imports {
        if d.iotas.contains(name) || !re.imports.contains(name) && d.items.contains(name) {
            return dup(name);
        }
    }
    for iota in &d.iotas {
        if !re.iotas.contains(iota) && d.items.contains(iota) {
            return dup(iota);
        }
    }
    for name in &d.locals {
        let taken = d.items.contains(name)
            || d.iotas.contains(name)
            || d.imports.iter().any(|(n, _)| n == name);
        if taken {
            return dup(name);
        }
    }
    // Stable, so that of an item and an iota of one name the first stays.
    d.spans.sort_by_key(|(name, _)| *name);
    Ok(d)
}

/// The imports and iotas a module's items re-export, by name.
#[derive(Default)]
struct Reexports {
    imports: Vec<Sym>,
    iotas: Vec<Sym>,
}

/// Read one declaration, the chain `ci`, into `d`.
fn declaration<'b, 'a>(
    ci: &[&'b Item<'a>],
    ctx: &Ctx,
    src: Source<'_>,
    d: &mut Decls<'b, 'a>,
    re: &mut Reexports,
) -> Parsed<()> {
    let span = src.items(ci);
    let split = ci.iter().position(|it| matches!(it, Item::Punct("=")));
    if split.is_none() && head_keyword(ci[0]) == Some("import") {
        let (name, spec) = parse_private_import(ci, ctx, src)?;
        push_import(&mut d.imports, name, spec)?;
        return Ok(());
    }
    if split.is_none() && head_keyword(ci[0]) == Some("const") {
        for (name, span) in parse_const_decl(ci, ctx, src)? {
            push_name(&mut d.iotas, name)?;
            d.spans.push((name, span));
        }
        return Ok(());
    }
    if split.is_none() && head_keyword(ci[0]) == Some("local") {
        for (name, body, span) in parse_local_group(ci, ctx, src)? {
            push_name(&mut d.locals, name)?;
            d.spans.push((name, span));
            d.bodies.push((Decl::Local(name, body), span));
        }
        return Ok(());
    }
    let eq = split.ok_or(ParseError::MalformedBinding)?;
    if ci[eq + 1..].iter().any(|it| matches!(it, Item::Punct("="))) {
        return Err(ParseError::MalformedBinding.into());
    }
    let (head, tail) = (&ci[..eq], &ci[eq + 1..]);
    if head.is_empty() || tail.is_empty() {
        return Err(ParseError::MalformedBinding.into());
    }
    if head.len() > 1 && head_keyword(head[0]) == Some("const") {
        return Err(ParseError::MalformedConst.into());
    }
    if head.len() > 1 && head_keyword(head[0]) == Some("local") {
        let name = plain_name(&head[1..], ParseError::MalformedLocal, ctx, src)?;
        push_name(&mut d.locals, name)?;
        d.spans.push((name, span));
        d.bodies.push((Decl::Local(name, tail.to_vec()), span));
        return Ok(());
    }
    if let [Item::Sym(s)] = head {
        if let Some(reserved) = reserved_moditem(s) {
            if d.has_main {
                let error = ParseError::DuplicateReserved(text(reserved));
                return Err(Failure(error, src.items(head)));
            }
            d.has_main = true;
            d.bodies.push((Decl::Main(tail.to_vec()), span));
            return Ok(());
        }
        if s.starts_with("__") {
            let error = ParseError::UnknownReserved(text(s));
            return Err(Failure(error, src.items(head)));
        }
    }
    let name = plain_name(head, ParseError::BadModuleItemName, ctx, src)?;
    if d.items.contains(&name) {
        return Err(ParseError::DuplicateModuleItem.into());
    }
    if head_keyword(tail[0]) == Some("import") {
        let spec = parse_import_spec(tail)?;
        push_import(&mut d.imports, name, spec)?;
        re.imports.push(name);
        d.items.push(name);
        d.spans.push((name, span));
        d.bodies.push((Decl::Forward(name), span));
        return Ok(());
    }
    if head_keyword(tail[0]) == Some("const") {
        if tail.len() != 1 {
            return Err(ParseError::MalformedConst.into());
        }
        push_name(&mut d.iotas, name)?;
        re.iotas.push(name);
        d.items.push(name);
        d.spans.push((name, span));
        d.bodies.push((Decl::Forward(name), span));
        return Ok(());
    }
    d.items.push(name);
    d.spans.push((name, span));
    d.bodies.push((Decl::Item(name, tail.to_vec()), span));
    Ok(())
}

/// The reserved moditems the language defines, as the names a module top-level
/// left-hand side may spell in the `__` namespace. One so far; `__test` and
/// `__doc` are anticipated, and each will be another slot on a module with a
/// clause here (see `docs/done/2026-08-14_elly-run.md`).
///
/// Answers with the `'static` spelling so the caller reports the *defined* name
/// rather than echoing the source, and `None` for a name that is not one — which
/// the caller turns into [`ParseError::UnknownReserved`] rather than an item.
fn reserved_moditem(name: &str) -> Option<&'static str> {
    match name {
        "__main" => Some("__main"),
        _ => None,
    }
}

/// Record one import, rejecting a name a previous import already took.
fn push_import(imports: &mut Vec<(Sym, ImportSpec)>, name: Sym, spec: ImportSpec) -> Parsed<()> {
    if imports.iter().any(|(n, _)| *n == name) {
        return Err(ParseError::DuplicateModuleItem.into());
    }
    imports.push((name, spec));
    Ok(())
}

/// Record one iota or local, rejecting a name a previous one already took.
fn push_name(names: &mut Vec<Sym>, name: Sym) -> Parsed<()> {
    if names.contains(&name) {
        return Err(ParseError::DuplicateModuleItem.into());
    }
    names.push(name);
    Ok(())
}

/// Parse `import "<spec>" as <Name>` — the private form, whose whole chain is the
/// declaration — to its name and spec. The keyword may be a bare sym or a glued
/// run head (§D); in the run case only the spec glues into the run (`import"spec"`)
/// while `as <Name>` stays in the chain after it, so the two are concatenated back
/// into the one item stream the spaced form already is.
fn parse_private_import<'a>(
    ci: &[&Item<'a>],
    ctx: &Ctx,
    src: Source<'_>,
) -> Parsed<(Sym, ImportSpec)> {
    let rest: Vec<&Item<'a>> = match ci[0] {
        Item::Run(members) => members[1..]
            .iter()
            .map(|it| it as &Item<'a>)
            .chain(ci[1..].iter().copied())
            .collect(),
        _ => ci[1..].to_vec(),
    };
    match rest.as_slice() {
        [Item::Str(spec), Item::Sym("as"), rest @ ..] if !rest.is_empty() => {
            let name = plain_name(rest, ParseError::BadModuleItemName, ctx, src)?;
            Ok((name, decode_str(spec)?))
        }
        _ => Err(ParseError::MalformedImport.into()),
    }
}

/// Parse a private `const` declaration — `const <name>`, or the group form
/// `const (<name> …)` — to the names it declares.
///
/// The group is an ordinary `<parens>` wrapping a `<seq>`, so its names may be
/// newline- or comma-separated and it may carry comments, exactly as a `let`
/// group may. An **empty group declares nothing**, the same degenerate reading
/// `let ()` and `recur ()` take.
fn parse_const_decl<'a>(
    ci: &[&Item<'a>],
    ctx: &Ctx,
    src: Source<'_>,
) -> Parsed<Vec<(Sym, ChunkSpan)>> {
    // The keyword may be a bare sym or a glued run head (§D); the declared names
    // are read from what follows it (the run's members in the run case).
    let rest: Vec<&Item<'a>> = match ci[0] {
        Item::Run(members) => members[1..].iter().map(|it| it as &Item<'a>).collect(),
        _ => ci[1..].to_vec(),
    };
    match rest.as_slice() {
        [Item::Parens(Group { seq, .. }), ..] => {
            let mut names = Vec::new();
            for c in chain_slices(seq) {
                let name = plain_name(&c, ParseError::MalformedConst, ctx, src)?;
                names.push((name, src.items(&c)));
            }
            Ok(names)
        }
        rest if !rest.is_empty() => {
            let name = plain_name(rest, ParseError::MalformedConst, ctx, src)?;
            Ok(alloc::vec![(name, src.items(rest))])
        }
        _ => Err(ParseError::MalformedConst.into()),
    }
}

/// Parse group form `local (<name> = <expr> …)` to its names and unparsed bodies.
///
/// The group is an ordinary `<parens>` wrapping a `<seq>`. An empty group
/// declares nothing. The single form `local x = <expr>` is handled separately.
#[allow(clippy::type_complexity)]
fn parse_local_group<'b, 'a>(
    ci: &[&'b Item<'a>],
    ctx: &Ctx,
    src: Source<'_>,
) -> Parsed<Vec<(Sym, Vec<&'b Item<'a>>, ChunkSpan)>> {
    let group = match ci[0] {
        Item::Run(members) => members.get(1),
        _ => ci.get(1).copied(),
    };
    let Some(Item::Parens(Group { seq, .. })) = group else {
        return Err(ParseError::MalformedLocal.into());
    };
    let mut bindings = Vec::new();
    for c in chain_slices(seq) {
        let malformed = || Failure(ParseError::MalformedLocal, src.items(&c));
        let eq = c
            .iter()
            .position(|it| matches!(it, Item::Punct("=")))
            .ok_or_else(malformed)?;
        let (head, tail) = (&c[..eq], &c[eq + 1..]);
        if head.is_empty() || tail.is_empty() {
            return Err(malformed());
        }
        if tail.iter().any(|it| matches!(it, Item::Punct("="))) {
            return Err(malformed());
        }
        bindings.push((
            plain_name(head, ParseError::MalformedLocal, ctx, src)?,
            tail.to_vec(),
            src.items(&c),
        ));
    }
    Ok(bindings)
}

/// Parse the `import "<spec>"` RHS of a re-exporting import to its spec.
/// Handles both spaced and glued spellings.
fn parse_import_spec(tail: &[&Item<'_>]) -> Parsed<ImportSpec> {
    let spec = match tail {
        [_import, Item::Str(spec)] => spec,
        [Item::Run(members)] => match members.as_slice() {
            [_import, Item::Str(spec)] => spec,
            _ => return Err(ParseError::MalformedImport.into()),
        },
        _ => return Err(ParseError::MalformedImport.into()),
    };
    decode_str(spec)
}

/// Parse a single plain name for a binding position.
/// Must be exactly one `<sym>` that is not a keyword, `__` name, discard, or number.
fn plain_name(items: &[&Item<'_>], bad: ParseError, ctx: &Ctx, src: Source<'_>) -> Parsed<Sym> {
    plain_name_at(items, bad, ctx).map_err(|f| f.or_at(|| src.items(items)))
}

/// [`plain_name`], unplaced.
fn plain_name_at(items: &[&Item<'_>], bad: ParseError, ctx: &Ctx) -> Parsed<Sym> {
    match items {
        [Item::Sym(s)] if is_keyword(s) => Err(ParseError::ReservedKeyword.into()),
        [Item::Sym(s)] if s.starts_with("__") => Err(ParseError::ReservedName.into()),
        [Item::Sym(s)] if reads_as_number(s) || *s == "_" => Err(bad.into()),
        [Item::Sym(s)] => Ok(ctx.intern(s)),
        _ => Err(bad.into()),
    }
}

/// Check if a `<sym>` reads as a number (valid integer or digit-leading).
fn reads_as_number(s: &str) -> bool {
    parse_int(s).is_some() || s.as_bytes()[0].is_ascii_digit()
}

// ===========================================================================
// the parser
// ===========================================================================

/// Where an expression lands, which decides what an `&` there becomes.
///
/// A slot passes through the forms that are their inner expression — a
/// one-chain `( … )`, `{ e }`, `let () e`, `recur () e`, a pipe's right-hand
/// side — and every other form parses its parts in slots of their own.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
enum Slot {
    /// Anywhere else: an `&` captures a fresh frame.
    Value,
    /// Applied where it is made — a callee, a builtin's thunk argument: an
    /// `&` shares the enclosing environment ([`Plan::Chain`](crate::code::Plan)).
    Applied,
    /// A list argument a builtin applies elementwise: its elements are
    /// [`Applied`](Slot::Applied).
    AppliedElems,
    /// Directly the body of a lambda whose head is still open: an `&` extends
    /// the head, so `&a &b body` is one lambda of two parameters.
    Body,
}

/// A node and its span.
type Spanned = (Node, ChunkSpan);

/// A parsed expression, its descendants pushed.
enum Built {
    /// Its own node, unpushed, and its span.
    Node(Node, ChunkSpan),
    /// An application spine still open on the scratch stack, so a trailing
    /// argument or a pipe operand can extend it.
    Spine(Spine),
}

/// An application spine on the builder's scratch stack: the callee at
/// `mark`, then the arguments so far.
struct Spine {
    mark: usize,
    /// The callee, if it is a builtin: it decides its arguments' slots.
    callee: Option<Builtin>,
    /// The span of the application so far.
    span: ChunkSpan,
}

/// A lambda whose head is being parsed: its parameters are
/// `pat_scratch[pats..]`.
struct Head {
    pats: usize,
    /// For a [`Chain`](crate::code::Plan::Chain) lambda, the enclosing
    /// activation's mark to unbind its parameters to; `None` for one that
    /// opened an activation of its own.
    chain: Option<usize>,
}

/// A name or literal as written, before it is resolved.
enum SymRef {
    Home,
    Int(BigInt),
    Builtin(Builtin),
    Name(Sym),
}

/// The most parameters one lambda takes: a closure counts its applied
/// arguments in a `u8`.
const MAX_HEAD: usize = u8::MAX as usize;

/// Emits one chunk from the Muon tree, resolving as it goes.
struct Parser<'c, 's> {
    ctx: &'c Ctx,
    b: Builder,
    scope: Scope<'c>,
    /// The lambdas whose heads are open, innermost last.
    heads: Vec<Head>,
    /// The source being parsed, which gives the spans.
    src: Source<'s>,
}

impl<'c, 's> Parser<'c, 's> {
    /// A parser emitting into `b`, which has recorded `src` as a document.
    fn new(ctx: &'c Ctx, scope: Scope<'c>, b: Builder, src: Source<'s>) -> Self {
        Parser {
            ctx,
            b,
            scope,
            heads: Vec::new(),
            src,
        }
    }

    /// A program: a single top-level chain.
    fn program(&mut self, seq: &Seq<'_>) -> Parsed<Spanned> {
        match chain_slices(seq).as_slice() {
            [] => Err(ParseError::EmptyProgram.into()),
            [items] => {
                let built = self.expr(items, Slot::Value)?;
                Ok(self.close(built))
            }
            [_, second, ..] => Err(Failure(
                ParseError::MultipleExpressions,
                self.src.items(second),
            )),
        }
    }

    /// Emits the bodies `decls` declares into the member slots of the module
    /// being emitted, whose sorted names are `items`, `locals` and `iotas`.
    /// Returns the members' scratch mark and the `__main` body, or `NONE`.
    ///
    /// The bodies are emitted in source order, so errors come in source
    /// order, and their members land in sorted order.
    fn members(
        &mut self,
        decls: &Decls<'_, '_>,
        items: &[Sym],
        locals: &[Sym],
        iotas: &[Sym],
    ) -> Parsed<(usize, NodeId)> {
        let mark = self.b.member_scratch.len();
        for &name in items.iter().chain(locals).chain(iotas) {
            let member = Member {
                name,
                node: NodeId::NONE,
            };
            self.b.member_scratch.push((member, decls.span(name)));
        }
        let slot = |name: Sym, names: &[Sym]| {
            names
                .binary_search(&name)
                .expect("a declared name has a slot")
        };
        let mut main = NodeId::NONE;
        for (decl, span) in &decls.bodies {
            let (index, node) = match decl {
                Decl::Item(name, body) => (slot(*name, items), self.body(body)?),
                Decl::Forward(name) => {
                    let node = self.name_ref(*name).map_err(|f| f.or_at(|| *span))?;
                    (slot(*name, items), self.b.push(node, *span))
                }
                Decl::Local(name, body) => (items.len() + slot(*name, locals), self.body(body)?),
                Decl::Main(body) => {
                    main = self.body(body)?;
                    continue;
                }
            };
            self.b.member_scratch[mark + index].0.node = node;
        }
        Ok((mark, main))
    }

    /// A member's body, pushed.
    fn body(&mut self, items: &[&Item<'_>]) -> Parsed<NodeId> {
        let built = self.expr(items, Slot::Value)?;
        Ok(self.child(built))
    }

    // -----------------------------------------------------------------------
    // spines
    // -----------------------------------------------------------------------

    /// The node of `built` and its span, closing an open spine.
    fn close(&mut self, built: Built) -> Spanned {
        match built {
            Built::Node(node, span) => (node, span),
            Built::Spine(spine) => self.close_spine(spine),
        }
    }

    /// `built`, pushed.
    fn child(&mut self, built: Built) -> NodeId {
        let (node, span) = self.close(built);
        self.b.push(node, span)
    }

    /// An application of the spine's run, or its one element.
    fn close_spine(&mut self, spine: Spine) -> Spanned {
        let len = self.b.scratch.len() - spine.mark;
        if len == 1 {
            return self.b.scratch.pop().expect("a spine has a callee");
        }
        let app = Node::App {
            len: len32(len),
            args: self.b.push_run(Run::App, spine.mark),
        };
        (app, spine.span)
    }

    /// A spine with `callee` and no arguments yet.
    fn start(&mut self, callee: Spanned) -> Spine {
        let mark = self.b.scratch.len();
        self.b.scratch.push(callee);
        Spine {
            mark,
            callee: builtin_of(callee.0),
            span: callee.1,
        }
    }

    /// A spine that `built` heads, to apply to one more argument: an open
    /// spine extends, and so does a closed application, whose run is copied
    /// (`(f x) &y b` is `f` applied to `x` and the lambda).
    fn open(&mut self, built: Built) -> Spine {
        match built {
            Built::Spine(spine) => spine,
            Built::Node(Node::App { len, args }, span) => {
                let mark = self.b.scratch.len();
                for i in 0..len {
                    let node = self.b.node(args.nth(i));
                    self.b.scratch.push(node);
                }
                Spine {
                    mark,
                    callee: builtin_of(self.b.scratch[mark].0),
                    span,
                }
            }
            Built::Node(node, span) => self.start((node, span)),
        }
    }

    /// The slot of `spine`'s next argument.
    fn arg_slot(&self, spine: &Spine) -> Slot {
        let i = self.b.scratch.len() - spine.mark - 1;
        match spine.callee {
            Some(op) if op.applies_arg(i) => Slot::Applied,
            Some(op) if op.applies_elements_of(i) => Slot::AppliedElems,
            _ => Slot::Value,
        }
    }

    /// The slot of the next element of a spine being built: the callee of a
    /// spine of several elements is applied where it is made.
    fn next_slot(&self, spine: &Option<Spine>) -> Slot {
        match spine {
            None => Slot::Applied,
            Some(spine) => self.arg_slot(spine),
        }
    }

    /// Applies `spine` to one more argument. A builtin module applied to the
    /// symbol of one of its members folds to the member's own leaf
    /// (`__Int .add` is `__Int.add`), so a written member costs no lookup.
    fn extend(&mut self, spine: &mut Spine, arg: Spanned) {
        spine.span = spine.span.join(arg.1);
        if self.b.scratch.len() - spine.mark == 1 {
            if let (Some(ns), Node::Symbol(m)) = (spine.callee, arg.0) {
                if let Some(op) = ns.member(m) {
                    self.b.scratch[spine.mark] = (Node::Builtin(op), spine.span);
                    spine.callee = Some(op);
                    return;
                }
            }
        }
        self.b.scratch.push(arg);
    }

    /// Adds `arg` to the spine being built, starting it if it is the first.
    fn push_arg(&mut self, spine: &mut Option<Spine>, arg: Spanned) {
        match spine {
            None => *spine = Some(self.start(arg)),
            Some(spine) => self.extend(spine, arg),
        }
    }

    // -----------------------------------------------------------------------
    // expressions
    // -----------------------------------------------------------------------

    /// A comment-free slice of items. An error in it that nothing below
    /// placed is placed at the slice, as is each of the methods below that
    /// parse an item or a chain.
    fn expr(&mut self, items: &[&Item<'_>], slot: Slot) -> Parsed<Built> {
        let src = self.src;
        self.pipeline(items, slot)
            .map_err(|f| f.or_at(|| src.items(items)))
    }

    /// [`expr`](Self::expr), unplaced.
    fn pipeline(&mut self, items: &[&Item<'_>], slot: Slot) -> Parsed<Built> {
        if items.is_empty() {
            return Err(ParseError::EmptyChain.into());
        }
        // `|>` is the loosest operator: split on the last one to form a
        // left-associative pipe chain over segments. The right side is parsed
        // first, so the left knows the slot it lands in.
        match items.iter().rposition(|it| matches!(it, Item::Punct("|>"))) {
            None => self.segment(items, slot),
            Some(k) => {
                let (left, right) = (&items[..k], &items[k + 1..]);
                if left.is_empty() || right.is_empty() {
                    let pipe = self.src.item(items[k]);
                    return Err(Failure(ParseError::MalformedPipe, pipe));
                }
                let r = self.segment(right, Slot::Applied)?;
                let mut spine = self.open(r);
                let slot = self.arg_slot(&spine);
                let l = self.expr(left, slot)?;
                let l = self.close(l);
                self.extend(&mut spine, l);
                Ok(Built::Spine(spine))
            }
        }
    }

    /// One pipe segment (a `|>`-free slice).
    ///
    /// This is an application spine whose trailing argument may be a `&`/`let`/`recur`
    /// binder form. Split points have lowest precedence within the segment.
    fn segment(&mut self, items: &[&Item<'_>], slot: Slot) -> Parsed<Built> {
        match items.iter().position(|it| is_split_point(it)) {
            None => self.app_spine(items, slot),
            Some(0) => match head_keyword(items[0]) {
                Some("let") | Some("recur") => self.let_or_recur(items[0], items, slot),
                Some("case") => self.case(items, slot),
                _ => self.binder(items, slot),
            },
            Some(k) => {
                let f = self.segment(&items[..k], Slot::Applied)?;
                let mut spine = self.open(f);
                let slot = self.arg_slot(&spine);
                let arg = self.segment(&items[k..], slot)?;
                let arg = self.close(arg);
                self.extend(&mut spine, arg);
                Ok(Built::Spine(spine))
            }
        }
    }

    /// An application spine, folding left. `(…)` items are spread into
    /// multiple arguments. A spine of one element is that element, in the
    /// slot the spine is in.
    fn app_spine(&mut self, items: &[&Item<'_>], slot: Slot) -> Parsed<Built> {
        if let [item] = items {
            match item {
                Item::Parens(group) => return self.group(group, slot),
                Item::Run(_) => {}
                _ => return self.aexpr(item, slot),
            }
        }
        let mut spine: Option<Spine> = None;
        for (i, it) in items.iter().enumerate() {
            match *it {
                Item::Run(members) if i == 0 => {
                    let src = self.src;
                    check_run_head(members).map_err(|f| f.or_at(|| src.item(it)))?;
                    let members = if is_self_head(members) {
                        let new = self.home(HomeLeaf::New)?;
                        let span = self.src.item(&members[0]);
                        self.push_arg(&mut spine, (new, span));
                        &members[1..]
                    } else {
                        &members[..]
                    };
                    for m in members {
                        self.expand_arg(m, &mut spine)?;
                    }
                }
                Item::Prefixed { sigil: '#', item }
                    if i == 0 && matches!(item.as_ref(), Item::Sym("Self")) =>
                {
                    let new = self.home(HomeLeaf::New)?;
                    let span = self.src.item(it);
                    self.push_arg(&mut spine, (new, span));
                }
                _ => self.expand_arg(it, &mut spine)?,
            }
        }
        let spine = spine.expect("a spine has at least one item");
        let len = self.b.scratch.len() - spine.mark;
        if len == 1 {
            if let Node::Home {
                leaf: HomeLeaf::New,
                ..
            } = self.b.scratch[spine.mark].0
            {
                let span = self.b.scratch[spine.mark].1;
                return Err(Failure(ParseError::ReservedLiteralForm, span));
            }
            let (node, span) = self.close_spine(spine);
            return Ok(Built::Node(node, span));
        }
        Ok(Built::Spine(spine))
    }

    /// Expand one chain item into arguments of the spine being built. `(…)`
    /// groups spread; `.Self` reads the payload of everything before it;
    /// other items are single atoms.
    fn expand_arg(&mut self, item: &Item<'_>, spine: &mut Option<Spine>) -> Parsed<()> {
        match item {
            Item::Parens(group) => {
                let chains = chain_slices(&group.seq);
                if chains.is_empty() {
                    let span = self.src.group(group);
                    self.push_arg(spine, (Node::Unit, span));
                }
                for chain in &chains {
                    let slot = self.next_slot(spine);
                    let arg = self.expr(chain, slot)?;
                    let arg = self.close(arg);
                    self.push_arg(spine, arg);
                }
                // The application covers the group's brackets too.
                if let Some(spine) = spine {
                    spine.span = spine.span.join(self.src.group(group));
                }
                Ok(())
            }
            Item::Prefixed { sigil: '.', item }
                if matches!(item.as_ref(), Item::Sym("Self")) && spine.is_some() =>
            {
                let acc = self.close_spine(spine.take().expect("checked"));
                let value = self.home(HomeLeaf::Value)?;
                let value_span = self.src.item(item);
                let span = acc.1.join(value_span);
                let mark = self.b.scratch.len();
                self.b.scratch.push((value, value_span));
                self.b.scratch.push(acc);
                let read = Node::App {
                    len: 2,
                    args: self.b.push_run(Run::App, mark),
                };
                *spine = Some(self.start((read, span)));
                Ok(())
            }
            _ => {
                let slot = self.next_slot(spine);
                let arg = self.aexpr(item, slot)?;
                let arg = self.close(arg);
                self.push_arg(spine, arg);
                Ok(())
            }
        }
    }

    /// A `(…)` group as an atom: `()` is unit, `(e)` is `e`, and `(a, b, …)`
    /// a spread spine.
    fn group(&mut self, group: &Group<'_>, slot: Slot) -> Parsed<Built> {
        let chains = chain_slices(&group.seq);
        match chains.as_slice() {
            [] => Ok(Built::Node(Node::Unit, self.src.group(group))),
            [chain] => self.expr(chain, slot),
            chains => {
                let mut spine = None;
                for chain in chains {
                    let slot = self.next_slot(&spine);
                    let arg = self.expr(chain, slot)?;
                    let arg = self.close(arg);
                    self.push_arg(&mut spine, arg);
                }
                let mut spine = spine.expect("a group of several chains");
                spine.span = self.src.group(group);
                Ok(Built::Spine(spine))
            }
        }
    }

    /// A single item as an atomic expression.
    fn aexpr(&mut self, item: &Item<'_>, slot: Slot) -> Parsed<Built> {
        let src = self.src;
        self.atom_expr(item, slot)
            .map_err(|f| f.or_at(|| src.item(item)))
    }

    /// [`aexpr`](Self::aexpr), unplaced.
    fn atom_expr(&mut self, item: &Item<'_>, slot: Slot) -> Parsed<Built> {
        let node = match item {
            Item::Sym(s) => self.sym(s)?,
            Item::Prefixed { sigil: '.', item } => self.dot_symbol(item)?,
            Item::Brackets(_) => return Err(ParseError::BareListLiteral.into()),
            Item::Parens(group) => return self.group(group, slot),
            Item::Str(s) => self.b.str(decode_str(s)?),
            Item::Braces(group) => return self.block(group, slot),
            Item::Punct(".") => return Err(ParseError::CombinatorDeferred.into()),
            Item::Punct(_) => return Err(ParseError::PunctAtAtom.into()),
            Item::Comm(_) => return Err(ParseError::EmptyChain.into()),
            Item::Prefixed { sigil: '#', item } => match item.as_ref() {
                Item::Brackets(Group { seq, .. }) => self.list(seq, slot)?,
                Item::Braces(Group { seq, .. }) => self.map(seq)?,
                _ => return Err(ParseError::ReservedLiteralForm.into()),
            },
            Item::Prefixed { .. } => return Err(ParseError::UnexpectedBinder.into()),
            Item::Run(members) => {
                check_run_head(members)?;
                let items: Vec<&Item<'_>> = members.iter().collect();
                return self.expr(&items, slot);
            }
        };
        Ok(Built::Node(node, self.src.item(item)))
    }

    /// A `<sym>`: an integer literal or a resolved name.
    fn sym(&mut self, s: &str) -> Parsed<Node> {
        let r = classify(s, self.ctx)?;
        self.resolve_sym(r)
    }

    fn resolve_sym(&mut self, r: SymRef) -> Parsed<Node> {
        match r {
            SymRef::Home => self.home(HomeLeaf::Module),
            SymRef::Int(n) => Ok(self.b.int(n)),
            SymRef::Builtin(op) => Ok(Node::Builtin(op)),
            SymRef::Name(name) => self.name_ref(name),
        }
    }

    /// A reference to `name`, resolved.
    fn name_ref(&mut self, name: Sym) -> Parsed<Node> {
        Ok(match self.scope.reference(name)? {
            Ref::Local(index) => Node::Local { name, index },
            Ref::Item { index, depth } => Node::ModItem { index, depth, name },
            Ref::Builtin(op) => Node::Builtin(op),
        })
    }

    /// A home-module leaf, resolved to the nearest module.
    fn home(&mut self, leaf: HomeLeaf) -> Parsed<Node> {
        let depth = self
            .scope
            .home_depth()
            .ok_or_else(|| ParseError::OutsideModule(text(leaf.name())))?;
        Ok(Node::Home { leaf, depth })
    }

    /// A `.`-prefixed item as a symbol.
    fn dot_symbol(&mut self, item: &Item<'_>) -> Parsed<Node> {
        match item {
            Item::Sym(s) => Ok(Node::Symbol(self.ctx.intern(s))),
            _ => Err(ParseError::BadSymbol.into()),
        }
    }

    /// A `#[…]` list into a runtime list literal of *any* arity: `#[]` (the
    /// empty list, not unit), `#[e]` (a genuine 1-list, not collapsed),
    /// `#[e0, e1, …]`. Each non-comment chain is one element expression.
    fn list(&mut self, seq: &Seq<'_>, slot: Slot) -> Parsed<Node> {
        let elem_slot = match slot {
            Slot::AppliedElems => Slot::Applied,
            _ => Slot::Value,
        };
        let chains = chain_slices(seq);
        let mark = self.b.scratch.len();
        for chain in &chains {
            let elem = self.expr(chain, elem_slot)?;
            let elem = self.close(elem);
            self.b.scratch.push(elem);
        }
        Ok(Node::List {
            len: len32(chains.len()),
            elems: self.b.push_run(Run::List, mark),
        })
    }

    /// A `#{…}` map literal: each non-comment chain of the `<seq>` is one
    /// entry (see [`entry`](Self::entry)). Entry order is source order —
    /// evaluation re-sorts by the value order. The run holds the keys, then
    /// the values.
    fn map(&mut self, seq: &Seq<'_>) -> Parsed<Node> {
        let chains = chain_slices(seq);
        let n = chains.len();
        let mark = self.b.scratch.len();
        self.b
            .scratch
            .resize(mark + 2 * n, (Node::Unit, ChunkSpan::NONE));
        for (i, chain) in chains.iter().enumerate() {
            let src = self.src;
            let (key, value) = self
                .entry(chain)
                .map_err(|f| f.or_at(|| src.items(chain)))?;
            self.b.scratch[mark + i] = key;
            self.b.scratch[mark + n + i] = value;
        }
        Ok(Node::Map {
            len: len32(n),
            entries: self.b.push_run(Run::Map, mark),
        })
    }

    /// One map entry `<key> ":" <value>`. The `:` is a single `<punct>` item at
    /// position 1; the key is the single head item ([`map_key`](Self::map_key))
    /// and the value is the rest of the chain parsed as an `<expr>`. An *empty*
    /// value tail is sugar for the unit value `()` (so `#{ .foo: }` is
    /// `#{ .foo: () }`).
    fn entry(&mut self, items: &[&Item<'_>]) -> Parsed<(Spanned, Spanned)> {
        if items.len() < 2 || !matches!(items[1], Item::Punct(":")) {
            return Err(ParseError::MalformedMapKey.into());
        }
        let src = self.src;
        let key = self
            .map_key(items[0])
            .map_err(|f| f.or_at(|| src.item(items[0])))?;
        let value_items = &items[2..];
        let value = if value_items.is_empty() {
            // The unit an empty value stands for is written as the `:`.
            (Node::Unit, self.src.item(items[1]))
        } else {
            let value = self.expr(value_items, Slot::Value)?;
            self.close(value)
        };
        Ok((key, value))
    }

    /// A map-entry key item. A bare *non-digit* atom key is the **symbol** of
    /// the same spelling — `one` == `.one`. A **digit-leading** bare key (`0`,
    /// `5`) is rejected to avoid the number/symbol confusion: write `.0` for
    /// the symbol or `(0)` for the integer. Wrap a key as a `(…)` **computed**
    /// key to evaluate it: `(one)` is the *value* of variable `one`; an *empty*
    /// `()` is the unit key. The remaining forms are a `.`-prefixed symbol, a
    /// string, a path (`Mod.k`), and a `#[…]` / `#{…}` literal key. A bare
    /// `[…]` / `{…}` key is refused with its `#`-spelling nudge.
    fn map_key(&mut self, item: &Item<'_>) -> Parsed<Spanned> {
        match item {
            Item::Sym(s) if s.as_bytes()[0].is_ascii_digit() => {
                Err(ParseError::MalformedMapKey.into())
            }
            Item::Sym(s) => Ok((Node::Symbol(self.ctx.intern(s)), self.src.item(item))),
            // A bare `{…}` in key position is a block expression at the atom
            // layer, which has no reading as a key.
            Item::Braces(_) => Err(ParseError::BareMapLiteral.into()),
            Item::Prefixed { sigil: '.', .. }
            | Item::Prefixed { sigil: '#', .. }
            | Item::Brackets(_)
            | Item::Parens(_)
            | Item::Str(_) => {
                let key = self.aexpr(item, Slot::Value)?;
                Ok(self.close(key))
            }
            // A **path** key (`#{ Mod.k: v }`) denotes a concrete value by
            // reference, so it is a lookup key alongside the `.sym` /
            // bare-sym forms (§E).
            Item::Run(members) => {
                let head =
                    check_path(members, self.ctx).map_err(|_| ParseError::MalformedMapKey)?;
                self.path(head, members)
            }
            _ => Err(ParseError::MalformedMapKey.into()),
        }
    }

    /// A `{…}` brace group as a **block expression** (syntax v1 step 6): a
    /// sequence of clauses whose value is the last clause's (see
    /// [`build_block`](Self::build_block)). A `:`-clause (a stale bare-map
    /// entry) has no reading in a block and is refused with the `#{…}` nudge.
    fn block(&mut self, group: &Group<'_>, slot: Slot) -> Parsed<Built> {
        if braces_contain_colon(&group.seq) {
            return Err(ParseError::BareMapLiteral.into());
        }
        let span = self.src.group(group);
        self.build_block(chain_slices(&group.seq), slot, span)
    }

    /// A block from its (already joined, comment-free) clause chains — shared
    /// by the `{…}` block and by `let (…) e` (its group's binding chains plus
    /// its body as the final clause).
    ///
    /// - The empty block `{}` is the unit value `()`, and `{ e }` is `e` — the
    ///   degenerate-case identities.
    /// - Each **non-final** clause is a binding (`<pat> = <expr>`, a top-level
    ///   `=`, bound over the rest; its value resolves before its pattern binds)
    ///   or a bare expression, evaluated for its effect.
    /// - The **final** clause is the block's value and must be an expression; a
    ///   trailing binding is [`BlockTrailingBinding`](ParseError::BlockTrailingBinding).
    ///
    /// A block is a scope: its bindings are unbound when it ends. Its span is
    /// `span`, the whole form.
    fn build_block(
        &mut self,
        clauses: Vec<Vec<&Item<'_>>>,
        slot: Slot,
        span: ChunkSpan,
    ) -> Parsed<Built> {
        let Some((last, leading)) = clauses.split_last() else {
            return Ok(Built::Node(Node::Unit, span));
        };
        if clause_is_binding(last) {
            let span = self.src.items(last);
            return Err(Failure(ParseError::BlockTrailingBinding, span));
        }
        if leading.is_empty() {
            return self.expr(last, slot);
        }
        let (mark, pat_mark) = (self.b.scratch.len(), self.b.pat_scratch.len());
        let locals = self.scope.mark();
        for ci in leading {
            let (pat, value) = if clause_is_binding(ci) {
                let src = self.src;
                let (head, tail) = split_binding(ci).map_err(|f| f.or_at(|| src.items(ci)))?;
                let value = self.expr(tail, Slot::Value)?;
                let value = self.close(value);
                ((self.pattern(head)?, self.src.items(head)), value)
            } else {
                let value = self.expr(ci, Slot::Value)?;
                ((Pat::None, ChunkSpan::NONE), self.close(value))
            };
            self.b.pat_scratch.push(pat);
            self.b.scratch.push(value);
        }
        let value = self.expr(last, Slot::Value)?;
        let value = self.close(value);
        self.b.pat_scratch.push((Pat::None, ChunkSpan::NONE));
        self.b.scratch.push(value);
        self.scope.truncate(locals);
        let block = Node::Block {
            len: len32(clauses.len()),
            binds: self.b.push_pat_run(Run::Block, pat_mark),
            exprs: self.b.push_run(Run::Block, mark),
        };
        Ok(Built::Node(block, span))
    }

    /// A leading `let`/`recur` form, reading the binder group from a glued
    /// run or a bare symbol.
    fn let_or_recur(&mut self, head: &Item<'_>, items: &[&Item<'_>], slot: Slot) -> Parsed<Built> {
        let is_recur = head_keyword(head) == Some("recur");
        // Placed at the keyword and what follows it.
        let at = self.src.items(&items[..items.len().min(2)]);
        let missing = || {
            let error = if is_recur {
                ParseError::RecurMissingBinders
            } else {
                ParseError::LetMissingBinders
            };
            Failure(error, at)
        };
        let (group_item, body_items): (&Item<'_>, &[&Item<'_>]) = match head {
            Item::Run(members) if members.len() == 2 => (&members[1], &items[1..]),
            Item::Run(_) => return Err(missing()),
            _ => (*items.get(1).ok_or_else(missing)?, &items[2..]),
        };
        let group = match group_item {
            Item::Parens(Group { seq, .. }) => seq,
            _ => return Err(missing()),
        };
        let span = self.src.items(items);
        if is_recur {
            self.recur(group, body_items, slot, span)
        } else {
            self.let_block(group, body_items, slot, span)
        }
    }

    /// `let (b0, b1, …) body`: a block of the group's bindings and the body.
    /// An empty group binds nothing (`let () e` is `e`).
    fn let_block(
        &mut self,
        group: &Seq<'_>,
        body_items: &[&Item<'_>],
        slot: Slot,
        span: ChunkSpan,
    ) -> Parsed<Built> {
        if body_items.is_empty() {
            return Err(ParseError::LetMissingBody.into());
        }
        let mut clauses = chain_slices(group);
        for ci in &clauses {
            if !clause_is_binding(ci) {
                return Err(Failure(ParseError::MalformedBinding, self.src.items(ci)));
            }
        }
        clauses.push(body_items.to_vec());
        self.build_block(clauses, slot, span)
    }

    /// `recur (b0, b1, …) body`: simultaneous bindings, a nested module whose
    /// items they are and whose body is `body`. Its names are read before any
    /// of its bodies, as a module's are, and sorted to give each its index.
    /// An empty group is `body`.
    fn recur(
        &mut self,
        group: &Seq<'_>,
        body_items: &[&Item<'_>],
        slot: Slot,
        span: ChunkSpan,
    ) -> Parsed<Built> {
        if body_items.is_empty() {
            return Err(ParseError::RecurMissingBody.into());
        }
        let chains = chain_slices(group);
        let decls = declarations(&chains, self.ctx, self.src)?;
        if !decls.imports.is_empty() {
            return Err(ParseError::MisplacedImport.into());
        }
        if let Some(&iota) = decls.iotas.first() {
            return Err(Failure(ParseError::MisplacedConst, decls.span(iota)));
        }
        if let Some(&local) = decls.locals.first() {
            return Err(Failure(ParseError::MisplacedLocal, decls.span(local)));
        }
        if let Some((_, span)) = decls
            .bodies
            .iter()
            .find(|(d, _)| matches!(d, Decl::Main(_)))
        {
            return Err(Failure(ParseError::MisplacedReserved, *span));
        }
        if decls.items.is_empty() {
            return self.segment(body_items, slot);
        }
        let items = sorted(&decls.items);
        self.scope.push_group(items.clone()).map_err(|e| {
            let at = match &e {
                ParseError::RecurShadowsOuter(name) => decls.span(self.ctx.intern(name)),
                _ => span,
            };
            Failure(e, at)
        })?;
        let id = self.b.enter_module();
        let (mark, _) = self.members(&decls, &items, &[], &[])?;
        let body = self.segment(body_items, Slot::Value)?;
        let body = self.child(body);
        self.scope.pop_group();
        let n = len32(items.len());
        self.b
            .leave_module(id, None, mark, n, 0, &[], Vec::new(), body);
        Ok(Built::Node(Node::Recur(id), span))
    }

    /// `case <subject>? { arms }`. The subject resolves first and is placed
    /// after the arm bodies. A subjectless case is `&__arg (case __arg { … })`.
    fn case(&mut self, items: &[&Item<'_>], slot: Slot) -> Parsed<Built> {
        let span = self.src.items(items);
        let missing = || Failure(ParseError::CaseMissingArms, span);
        let mut rest: Vec<&Item<'_>> = Vec::new();
        if let Item::Run(members) = items[0] {
            rest.extend(members[1..].iter());
        }
        rest.extend_from_slice(&items[1..]);
        let (last, subject_items) = rest.split_last().ok_or_else(missing)?;
        let arms = match last {
            Item::Braces(Group { seq, .. }) => chain_slices(seq),
            _ => return Err(missing()),
        };
        if arms.is_empty() {
            return Err(missing());
        }
        match subject_items {
            [] => {
                let arg = self.ctx.intern("__arg");
                // The parameter and the subject it binds are the case's own.
                let depth = self.begin_abs(slot);
                self.param(span, |p| {
                    p.scope.bind(arg)?;
                    Ok(Pat::Bind(arg))
                })?;
                let subject = self.name_ref(arg)?;
                let body = self.case_node((subject, span), &arms)?;
                self.end_abs(depth, Built::Node(body, span), span)
            }
            [subject] => {
                let subject = self.aexpr(subject, Slot::Value)?;
                let subject = self.close(subject);
                Ok(Built::Node(self.case_node(subject, &arms)?, span))
            }
            _ => Err(Failure(
                ParseError::CaseSubjectExtra,
                self.src.items(subject_items),
            )),
        }
    }

    /// The arms of a case over `subject`, each `& <pattern> (when (<cond>))* <body>`.
    fn case_node(&mut self, subject: Spanned, arms: &[Vec<&Item<'_>>]) -> Parsed<Node> {
        let (mark, pat_mark) = (self.b.scratch.len(), self.b.pat_scratch.len());
        for items in arms {
            let inner = match items.first() {
                Some(Item::Prefixed { sigil: '&', item }) => item.as_ref(),
                _ => return Err(Failure(ParseError::ArmNotBinder, self.src.items(items))),
            };
            if is_bare_literal_header(inner) {
                let span = self.src.item(inner);
                return Err(Failure(ParseError::BareLiteralHeader, span));
            }
            let locals = self.scope.mark();
            let base = (self.pattern(&[inner])?, self.src.item(inner));
            let (pat, rest) = self.guarded(base, &items[1..])?;
            if rest.is_empty() {
                return Err(Failure(ParseError::ArmMissingBody, self.src.items(items)));
            }
            let body = self.expr(rest, Slot::Value)?;
            let body = self.close(body);
            self.scope.truncate(locals);
            self.b.pat_scratch.push(pat);
            self.b.scratch.push(body);
        }
        self.b.scratch.push(subject);
        Ok(Node::Case {
            len: len32(arms.len()),
            conds: self.b.push_pat_run(Run::Case, pat_mark),
            exprs: self.b.push_run(Run::Case, mark),
        })
    }

    // -----------------------------------------------------------------------
    // abstractions
    // -----------------------------------------------------------------------

    /// `&<pattern> body` — the one binding form every abstraction is built
    /// from. A run of `&p0 &p1 …`, or a curried binder group `&(a, b)`,
    /// collects into one lambda: the body is parsed in [`Slot::Body`], where
    /// an `&` extends the open head. A head that would exceed
    /// [`MAX_HEAD`] parameters starts a fresh nested lambda instead.
    fn binder(&mut self, items: &[&Item<'_>], slot: Slot) -> Parsed<Built> {
        if items.len() == 1 {
            return Err(ParseError::AbsWithoutBody.into());
        }
        let inner = match items[0] {
            Item::Prefixed { sigil: '&', item } => item.as_ref(),
            _ => return Err(ParseError::UnexpectedBinder.into()),
        };
        let span = self.src.items(items);
        let depth = self.begin_abs(slot);
        let rest = if matches!(items.get(1), Some(it) if is_when_kw(it))
            && !matches!(inner, Item::Parens(_))
        {
            if is_bare_literal_header(inner) {
                let span = self.src.item(inner);
                return Err(Failure(ParseError::BareLiteralHeader, span));
            }
            let mut rest: &[&Item<'_>] = &[];
            let base_span = self.src.item(inner);
            self.param_spanned(|p| {
                let base = (p.pattern(&[inner])?, base_span);
                let (pat, after) = p.guarded(base, &items[1..])?;
                rest = after;
                Ok(pat)
            })?;
            if rest.is_empty() {
                return Err(ParseError::AbsWithoutBody.into());
            }
            rest
        } else {
            match inner {
                // A `(…)` inner is a binder group whose commas curry
                // (`&(a, b)` is two parameters); `&()` is the nullary marker,
                // one parameter that matches unit.
                Item::Parens(group) => {
                    let params = chain_slices(&group.seq);
                    if params.is_empty() {
                        self.param(self.src.group(group), |_| Ok(Pat::Unit))?;
                    }
                    for chain in &params {
                        self.param(self.src.items(chain), |p| p.pattern(chain))?;
                    }
                }
                // A bare matching literal (number `&42`, symbol `&.foo`,
                // string `&"s"`) as the whole header must be parenthesized:
                // `&(42)`, `&(.foo)`, `&("s")` (see `BareLiteralHeader`).
                it if is_bare_literal_header(it) => {
                    let span = self.src.item(it);
                    return Err(Failure(ParseError::BareLiteralHeader, span));
                }
                other => self.param(self.src.item(other), |p| p.pattern(&[other]))?,
            }
            &items[1..]
        };
        let body = self.segment(rest, Slot::Body)?;
        self.end_abs(depth, body, span)
    }

    /// Starts an abstraction in `slot`: opens a lambda, or in
    /// [`Slot::Body`] extends the open one. Returns the depth of the open
    /// heads to close back to in [`end_abs`](Self::end_abs).
    fn begin_abs(&mut self, slot: Slot) -> usize {
        let depth = self.heads.len();
        if slot != Slot::Body {
            self.open_head(slot == Slot::Applied);
        }
        depth
    }

    /// Opens a lambda: a [`Chain`](crate::code::Plan::Chain) one binds in
    /// the enclosing activation, any other opens an activation of its own.
    fn open_head(&mut self, chain: bool) {
        let pats = self.b.pat_scratch.len();
        let chain = if chain {
            Some(self.scope.mark())
        } else {
            self.scope.push_level();
            None
        };
        self.heads.push(Head { pats, chain });
    }

    /// Adds the parameter `parse` emits, and binds, to the innermost open
    /// head, opening a nested lambda first if the head is full. The
    /// parameter's span is `span`.
    fn param(
        &mut self,
        span: ChunkSpan,
        parse: impl FnOnce(&mut Self) -> Parsed<Pat>,
    ) -> Parsed<()> {
        self.param_spanned(|p| Ok((parse(p)?, span)))
    }

    /// [`param`](Self::param) for a parameter whose span `parse` gives.
    fn param_spanned(
        &mut self,
        parse: impl FnOnce(&mut Self) -> Parsed<(Pat, ChunkSpan)>,
    ) -> Parsed<()> {
        let head = self.heads.last().expect("a parameter has a head");
        if self.b.pat_scratch.len() - head.pats == MAX_HEAD {
            self.open_head(false);
        }
        let pat = parse(self)?;
        self.b.pat_scratch.push(pat);
        Ok(())
    }

    /// Closes the heads opened since `depth` around `body`, innermost first;
    /// each lambda's span is `span`, the whole abstraction. An abstraction
    /// that only extended an open head returns its body.
    fn end_abs(&mut self, depth: usize, body: Built, span: ChunkSpan) -> Parsed<Built> {
        let mut body = self.close(body);
        while self.heads.len() > depth {
            let head = self.heads.pop().expect("an open head");
            let plan = match head.chain {
                Some(mark) => {
                    self.scope.truncate(mark);
                    None
                }
                None => Some(self.scope.pop_level()),
            };
            body = (self.b.lambda(head.pats, body, plan.as_deref(), span), span);
        }
        Ok(Built::Node(body.0, body.1))
    }

    /// Folds `when (<cond>)` guards onto `base`, returning the guarded pattern
    /// and the items after the guards. Each condition resolves after the
    /// pattern it guards binds, and a pattern guard's pattern after its
    /// condition.
    fn guarded<'i, 'a>(
        &mut self,
        mut pat: (Pat, ChunkSpan),
        mut items: &'i [&'i Item<'a>],
    ) -> Parsed<((Pat, ChunkSpan), &'i [&'i Item<'a>])> {
        while !items.is_empty() && is_when_kw(items[0]) {
            // Placed at the `when` and what follows it.
            let missing = Failure(
                ParseError::WhenMissingCond,
                self.src.items(&items[..items.len().min(2)]),
            );
            let (group, next): (&Seq<'a>, &[&Item<'a>]) = match items[0] {
                Item::Run(members) if members.len() == 2 => match &members[1] {
                    Item::Parens(Group { seq, .. }) => (seq, &items[1..]),
                    _ => return Err(missing),
                },
                Item::Run(_) => return Err(missing),
                _ => match items.get(1) {
                    Some(Item::Parens(Group { seq, .. })) => (seq, &items[2..]),
                    _ => return Err(missing),
                },
            };
            let Some(chain) = single_chain(group).filter(|chain| !chain.is_empty()) else {
                return Err(missing);
            };
            let inner = self.b.push_pat(pat.0, pat.1);
            let (gpat, cond) = if clause_is_binding(&chain) {
                let src = self.src;
                let (head, tail) =
                    split_binding(&chain).map_err(|f| f.or_at(|| src.items(&chain)))?;
                let cond = self.expr(tail, Slot::Value)?;
                let cond = self.child(cond);
                let gpat = self.pattern(head)?;
                (self.b.push_pat(gpat, self.src.items(head)), cond)
            } else {
                let cond = self.expr(&chain, Slot::Value)?;
                (PatId::NONE, self.child(cond))
            };
            let guard = self.src.items(&items[..items.len() - next.len()]);
            pat = (Pat::When { inner, gpat, cond }, pat.1.join(guard));
            items = next;
        }
        Ok((pat, items))
    }

    // -----------------------------------------------------------------------
    // patterns
    // -----------------------------------------------------------------------

    /// A pattern from a chain of items, binding its names. Splits on `|`
    /// (or-pattern), then `=` (equality / at-pattern), otherwise defers to
    /// `as` / atom levels.
    fn pattern(&mut self, items: &[&Item<'_>]) -> Parsed<Pat> {
        let src = self.src;
        self.or_pattern(items)
            .map_err(|f| f.or_at(|| src.items(items)))
    }

    /// [`pattern`](Self::pattern), unplaced.
    fn or_pattern(&mut self, items: &[&Item<'_>]) -> Parsed<Pat> {
        if items.is_empty() {
            return Err(ParseError::BadPattern.into());
        }
        if let Some(idx) = items.iter().position(|it| matches!(it, Item::Punct("|"))) {
            let mark = self.scope.mark();
            let left = self.pattern(&items[..idx])?;
            let left_names: Vec<Sym> = self.scope.bound_since(mark).to_vec();
            self.scope.truncate(mark);
            let right = self.pattern(&items[idx + 1..])?;
            if self.scope.bound_since(mark) != left_names.as_slice() {
                return Err(ParseError::OrBindersMismatch.into());
            }
            let left = self.b.push_pat(left, self.src.items(&items[..idx]));
            let right = self.b.push_pat(right, self.src.items(&items[idx + 1..]));
            return Ok(Pat::Or(left, right));
        }
        match items[0] {
            Item::Punct("<") => return Ok(Pat::Less(self.comparand(&items[1..])?)),
            Item::Punct(">") => return Ok(Pat::Greater(self.comparand(&items[1..])?)),
            _ => {}
        }
        if let Some(idx) = items.iter().position(|it| matches!(it, Item::Punct("="))) {
            if idx == 0 {
                return Ok(Pat::Equal(self.comparand(&items[1..])?));
            }
            let name = plain_name(&items[..idx], ParseError::BadPattern, self.ctx, self.src)?;
            self.scope.bind(name)?;
            let inner = self.pattern(&items[idx + 1..])?;
            let span = self.src.items(&items[idx + 1..]);
            return Ok(Pat::At(name, self.b.push_pat(inner, span)));
        }
        self.narrowed(items)
    }

    /// The RHS of an `=` / `<` / `>` comparand: exactly one atom, pushed.
    /// A pattern is a closed grammar; comparands never recurse into `expr`.
    fn comparand(&mut self, items: &[&Item<'_>]) -> Parsed<NodeId> {
        let node = match items {
            [it] => match it {
                Item::Sym(s) => self.sym(s)?,
                Item::Prefixed { sigil: '.', item } => self.dot_symbol(item)?,
                Item::Str(s) => self.b.str(decode_str(s)?),
                Item::Run(members) => {
                    let head = check_path(members, self.ctx)?;
                    self.path(head, members)?.0
                }
                _ => return Err(Failure(ParseError::ComparandNotAtom, self.src.items(items))),
            },
            _ => return Err(Failure(ParseError::ComparandNotAtom, self.src.items(items))),
        };
        Ok(self.b.push(node, self.src.items(items)))
    }

    /// The narrowing level: `Self <pat>`, `(as <Proto>) <pat>`, `<pat> as <Proto>`, or a bare atom.
    /// A prototype resolves before the pattern it narrows binds.
    fn narrowed(&mut self, items: &[&Item<'_>]) -> Parsed<Pat> {
        if let Item::Sym("Self") = items[0] {
            if items.len() < 2 {
                return Err(ParseError::BadPattern.into());
            }
            let depth = self
                .scope
                .home_depth()
                .ok_or_else(|| ParseError::OutsideModule(text("Self")))?;
            let inner = self.pattern(&items[1..])?;
            return Ok(Pat::Unwrap {
                depth,
                inner: self.b.push_pat(inner, self.src.items(&items[1..])),
            });
        }
        if let Item::Parens(Group { seq, .. }) = items[0] {
            if let Some(chain) = single_chain(seq) {
                if !chain.is_empty() && matches!(chain[0], Item::Sym("as")) {
                    let proto = self.proto(&chain[1..])?;
                    let inner = self.pattern(&items[1..])?;
                    return Ok(self.typed(proto, (inner, self.src.items(&items[1..]))));
                }
            }
        }
        if let Some(idx) = items.iter().position(|it| matches!(it, Item::Sym("as"))) {
            let proto = self.proto(&items[idx + 1..])?;
            let inner = self.atom(&items[..idx])?;
            return Ok(self.typed(proto, (inner, self.src.items(&items[..idx]))));
        }
        self.atom(items)
    }

    /// The prototype of `as <Proto>`: exactly one name or path, a module
    /// reference. A reference to a builtin prototype folds to its kind.
    fn proto(&mut self, items: &[&Item<'_>]) -> Parsed<Proto> {
        let src = self.src;
        self.proto_ref(items)
            .map_err(|f| f.or_at(|| src.items(items)))
    }

    /// [`proto`](Self::proto), unplaced.
    fn proto_ref(&mut self, items: &[&Item<'_>]) -> Parsed<Proto> {
        let node = match items {
            [Item::Sym(s)] => match classify(s, self.ctx)? {
                SymRef::Int(_) => return Err(ParseError::UnknownType.into()),
                r => self.resolve_sym(r)?,
            },
            [Item::Run(members)] => {
                let head = check_path(members, self.ctx)?;
                self.path(head, members)?.0
            }
            _ => return Err(ParseError::UnknownType.into()),
        };
        match node {
            Node::Builtin(op) => match op.proto_kind() {
                Some(kind) => Ok(Proto::Kind(kind)),
                None => Err(ParseError::NotAPrototype(text(op.name())).into()),
            },
            node => Ok(Proto::Ref(self.b.push(node, self.src.items(items)))),
        }
    }

    /// `inner as proto`.
    fn typed(&mut self, proto: Proto, inner: (Pat, ChunkSpan)) -> Pat {
        let inner = self.b.push_pat(inner.0, inner.1);
        match proto {
            Proto::Kind(kind) => Pat::TypeKind(kind, inner),
            Proto::Ref(node) => Pat::TypeRef(node, inner),
        }
    }

    /// A path: a run of a name followed by `.`-prefixed segments, checked by
    /// [`check_path`] to have head `head`. Folds left into the head applied
    /// to symbol literals, each a binary application, and a builtin module's
    /// member to its leaf.
    fn path(&mut self, head: SymRef, members: &[Item<'_>]) -> Parsed<Spanned> {
        let mut acc = (self.resolve_sym(head)?, self.src.item(&members[0]));
        for m in &members[1..] {
            let Item::Prefixed { sigil: '.', item } = m else {
                unreachable!("checked by check_path")
            };
            let symbol = self.dot_symbol(item)?;
            let Node::Symbol(name) = symbol else {
                unreachable!("a dotted segment is a symbol")
            };
            let span = self.src.item(m);
            if let Some(op) = builtin_of(acc.0).and_then(|ns| ns.member(name)) {
                acc = (Node::Builtin(op), acc.1.join(span));
                continue;
            }
            let mark = self.b.scratch.len();
            let joined = acc.1.join(span);
            self.b.scratch.push(acc);
            self.b.scratch.push((symbol, span));
            let app = Node::App {
                len: 2,
                args: self.b.push_run(Run::App, mark),
            };
            acc = (app, joined);
        }
        Ok(acc)
    }

    /// An atomic pattern: a single item or a `(…)` grouping of one pattern.
    fn atom(&mut self, items: &[&Item<'_>]) -> Parsed<Pat> {
        match items {
            [it] => self.atom_item(it),
            _ => Err(ParseError::BadPattern.into()),
        }
    }

    /// A single atomic-pattern item.
    fn atom_item(&mut self, item: &Item<'_>) -> Parsed<Pat> {
        let src = self.src;
        self.atom_pattern(item)
            .map_err(|f| f.or_at(|| src.item(item)))
    }

    /// [`atom_item`](Self::atom_item), unplaced.
    fn atom_pattern(&mut self, item: &Item<'_>) -> Parsed<Pat> {
        match item {
            Item::Sym("_") => Ok(Pat::Discard),
            Item::Sym(s) if is_keyword(s) => Err(ParseError::ReservedKeyword.into()),
            Item::Sym(s) if s.starts_with("__") => Err(ParseError::ReservedName.into()),
            Item::Sym(s) => match parse_int(s) {
                Some(n) => {
                    let node = self.b.int(n);
                    Ok(Pat::Equal(self.b.push(node, self.src.item(item))))
                }
                None if s.as_bytes()[0].is_ascii_digit() => Err(ParseError::MalformedNumber.into()),
                None => {
                    let name = self.ctx.intern(s);
                    self.scope.bind(name)?;
                    Ok(Pat::Bind(name))
                }
            },
            Item::Prefixed {
                sigil: '.',
                item: inner,
            } => {
                let node = self.dot_symbol(inner)?;
                Ok(Pat::Equal(self.b.push(node, self.src.item(item))))
            }
            Item::Str(s) => {
                let node = self.b.str(decode_str(s)?);
                Ok(Pat::Equal(self.b.push(node, self.src.item(item))))
            }
            Item::Brackets(_) => Err(ParseError::BareListLiteral.into()),
            Item::Parens(Group { seq, .. }) => match single_chain(seq) {
                Some(chain) if !chain.is_empty() => self.pattern(&chain),
                _ => Err(ParseError::BadPattern.into()),
            },
            Item::Braces(_) => Err(ParseError::BareMapLiteral.into()),
            Item::Prefixed { sigil: '#', item } => match item.as_ref() {
                Item::Brackets(Group { seq, .. }) => self.list_pattern(seq),
                Item::Braces(Group { seq, .. }) => self.map_pattern(seq),
                _ => Err(ParseError::ReservedLiteralForm.into()),
            },
            _ => Err(ParseError::BadPattern.into()),
        }
    }

    /// A trailing rest (`...name` or `...`) written at `span`, binding its name.
    fn rest(&mut self, rest: Option<&str>, span: ChunkSpan) -> Parsed<PatId> {
        let pat = match rest {
            Some(name) => {
                let name = self.ctx.intern(name);
                self.scope.bind(name)?;
                Pat::Bind(name)
            }
            None => Pat::Discard,
        };
        Ok(self.b.push_pat(pat, span))
    }

    /// A `#[…]` list pattern with an optional trailing rest, which binds
    /// before the elements.
    fn list_pattern(&mut self, seq: &Seq<'_>) -> Parsed<Pat> {
        let chains = chain_slices(seq);
        let (elems, rest) = split_rest(&chains)?;
        let rest = match rest {
            Some(rest) => self.rest(rest, self.rest_span(&chains))?,
            None => PatId::NONE,
        };
        let mark = self.b.pat_scratch.len();
        for chain in elems {
            let pat = self.pattern(chain)?;
            self.b.pat_scratch.push((pat, self.src.items(chain)));
        }
        Ok(Pat::List {
            len: len32(elems.len()),
            elems: self.b.push_pat_run(Run::PatList, mark),
            rest,
        })
    }

    /// A `#{ k0: p0, … }` map pattern. A key is a lookup — a bare symbol, a
    /// path, or a pattern that is an equality — or else a pattern that
    /// captures the key. The lookup keys resolve first, then their values
    /// bind, then each captured key and its value, then the rest: the order
    /// the matcher binds in.
    fn map_pattern(&mut self, seq: &Seq<'_>) -> Parsed<Pat> {
        let chains = chain_slices(seq);
        let (entries, rest) = split_rest(&chains)?;
        let mut keys = Vec::with_capacity(entries.len());
        for chain in entries {
            let malformed = || Failure(ParseError::MalformedMapKey, self.src.items(chain));
            let colon = chain
                .iter()
                .position(|it| matches!(it, Item::Punct(":")))
                .ok_or_else(malformed)?;
            if colon == 0 || colon + 1 == chain.len() {
                return Err(malformed());
            }
            let key = match &chain[..colon] {
                [Item::Sym(s)] if s.as_bytes()[0].is_ascii_digit() => return Err(malformed()),
                [Item::Sym(_)] | [Item::Run(_)] => true,
                key => is_lookup(key),
            };
            keys.push((colon, key));
        }
        let n = entries.len();
        let mark = self.b.pat_scratch.len();
        self.b
            .pat_scratch
            .resize(mark + 2 * n, (Pat::None, ChunkSpan::NONE));
        for (i, (chain, &(colon, lookup))) in entries.iter().zip(&keys).enumerate() {
            if lookup {
                let node = match &chain[..colon] {
                    [Item::Sym(s)] => Node::Symbol(self.ctx.intern(s)),
                    [Item::Run(members)] => {
                        let head = check_path(members, self.ctx)?;
                        self.path(head, members)?.0
                    }
                    key => self.lookup_expr(key)?,
                };
                let span = self.src.items(&chain[..colon]);
                self.b.pat_scratch[mark + i] = (Pat::Lookup(self.b.push(node, span)), span);
            }
        }
        for (i, (chain, &(colon, lookup))) in entries.iter().zip(&keys).enumerate() {
            if lookup {
                let value = self.pattern(&chain[colon + 1..])?;
                let span = self.src.items(&chain[colon + 1..]);
                self.b.pat_scratch[mark + n + i] = (value, span);
            }
        }
        for (i, (chain, &(colon, lookup))) in entries.iter().zip(&keys).enumerate() {
            if !lookup {
                let key = self.pattern(&chain[..colon])?;
                self.b.pat_scratch[mark + i] = (key, self.src.items(&chain[..colon]));
                let value = self.pattern(&chain[colon + 1..])?;
                let span = self.src.items(&chain[colon + 1..]);
                self.b.pat_scratch[mark + n + i] = (value, span);
            }
        }
        let rest = match rest {
            Some(rest) => self.rest(rest, self.rest_span(&chains))?,
            None => PatId::NONE,
        };
        Ok(Pat::Map {
            len: len32(n),
            entries: self.b.push_pat_run(Run::PatMap, mark),
            rest,
        })
    }

    /// The span of a list or map pattern's rest, its last chain.
    fn rest_span(&self, chains: &[Vec<&Item<'_>>]) -> ChunkSpan {
        chains
            .last()
            .map_or(ChunkSpan::NONE, |chain| self.src.items(chain))
    }

    /// The expression of a lookup key, one [`is_lookup`] accepts.
    fn lookup_expr(&mut self, items: &[&Item<'_>]) -> Parsed<Node> {
        if let Some(Item::Punct("=")) = items.first() {
            let node = self.comparand(&items[1..])?;
            return Ok(self.b.node(node).0);
        }
        match items {
            [Item::Parens(Group { seq, .. })] => {
                let chain = single_chain(seq).expect("checked by is_lookup");
                self.lookup_expr(&chain)
            }
            [Item::Sym(s)] => Ok(self.b.int(parse_int(s).expect("checked by is_lookup"))),
            [Item::Prefixed { sigil: '.', item }] => self.dot_symbol(item),
            [Item::Str(s)] => Ok(self.b.str(decode_str(s)?)),
            _ => unreachable!("checked by is_lookup"),
        }
    }
}

/// A prototype in `as <Proto>`.
enum Proto {
    /// A builtin prototype, compiled to a discriminant test.
    Kind(crate::builtins::TyKind),
    /// Any other, evaluated at match time and required to be a module.
    Ref(NodeId),
}

/// The builtin `node` is, if it is one.
fn builtin_of(node: Node) -> Option<Builtin> {
    match node {
        Node::Builtin(op) => Some(op),
        _ => None,
    }
}

/// Classify a `<sym>` as a home leaf, an integer literal, a builtin or a
/// name, rejecting what reads as none of them.
fn classify(s: &str, ctx: &Ctx) -> Parsed<SymRef> {
    if s == "Self" {
        return Ok(SymRef::Home);
    }
    if is_keyword(s) {
        return Err(ParseError::ReservedKeyword.into());
    }
    if s == "_" {
        Err(ParseError::DiscardReference.into())
    } else if let Some(n) = parse_int(s) {
        Ok(SymRef::Int(n))
    } else if s.as_bytes()[0].is_ascii_digit() {
        Err(ParseError::MalformedNumber.into())
    } else if s.starts_with("__") {
        match Builtin::from_name(s) {
            Some(op) => Ok(SymRef::Builtin(op)),
            None => Err(ParseError::UnknownReserved(text(s)).into()),
        }
    } else {
        Ok(SymRef::Name(ctx.intern(s)))
    }
}

/// Check a path — a run starting with an identifier followed by
/// `.`-prefixed segments — and classify its head.
fn check_path(members: &[Item<'_>], ctx: &Ctx) -> Parsed<SymRef> {
    if members.len() < 2 {
        return Err(ParseError::ComparandNotAtom.into());
    }
    let head = match &members[0] {
        Item::Sym(s) => classify(s, ctx)?,
        _ => return Err(ParseError::ComparandNotAtom.into()),
    };
    for m in &members[1..] {
        if !matches!(m, Item::Prefixed { sigil: '.', .. }) {
            return Err(ParseError::ComparandNotAtom.into());
        }
    }
    for m in &members[1..] {
        if let Item::Prefixed { item, .. } = m {
            if !matches!(item.as_ref(), Item::Sym(_)) {
                return Err(ParseError::BadSymbol.into());
            }
        }
    }
    Ok(head)
}

/// Whether a map pattern's key chain is an equality pattern, and so a lookup
/// key: the shape [`Parser::pattern`] reads as [`Pat::Equal`].
fn is_lookup(items: &[&Item<'_>]) -> bool {
    if items.is_empty() || items.iter().any(|it| matches!(it, Item::Punct("|"))) {
        return false;
    }
    if matches!(items[0], Item::Punct("<") | Item::Punct(">")) {
        return false;
    }
    if let Some(idx) = items.iter().position(|it| matches!(it, Item::Punct("="))) {
        return idx == 0;
    }
    if matches!(items[0], Item::Sym("Self")) || items.iter().any(|it| matches!(it, Item::Sym("as")))
    {
        return false;
    }
    match items {
        [Item::Sym(s)] => !is_keyword(s) && !s.starts_with("__") && parse_int(s).is_some(),
        [Item::Prefixed { sigil: '.', .. }] | [Item::Str(_)] => true,
        [Item::Parens(Group { seq, .. })] => match single_chain(seq) {
            Some(chain) => is_lookup(&chain) && !starts_with_as(&chain),
            None => false,
        },
        _ => false,
    }
}

/// Whether a chain is the `as <Proto>` of a `(as <Proto>) <pat>` pattern.
fn starts_with_as(chain: &[&Item<'_>]) -> bool {
    matches!(chain.first(), Some(Item::Sym("as")))
}

/// Split a list or map pattern's chains into its entries and its trailing
/// rest, if any: `Some(Some(name))` for `...name`, `Some(None)` for `...`.
/// A rest anywhere but last is [`ParseError::BadPattern`].
#[allow(clippy::type_complexity)]
fn split_rest<'c, 'b, 'a>(
    chains: &'c [Vec<&'b Item<'a>>],
) -> Parsed<(&'c [Vec<&'b Item<'a>>], Option<Option<&'a str>>)> {
    let n = chains.len();
    for (i, chain) in chains.iter().enumerate() {
        if as_rest(chain).is_some() && i != n - 1 {
            return Err(ParseError::BadPattern.into());
        }
    }
    match chains.split_last() {
        Some((last, entries)) => match as_rest(last) {
            Some(rest) => Ok((entries, Some(rest))),
            None => Ok((chains, None)),
        },
        None => Ok((chains, None)),
    }
}

/// Recognize a trailing-rest element chain (`...rest` or `...`).
fn as_rest<'a>(chain: &[&Item<'a>]) -> Option<Option<&'a str>> {
    let [Item::Prefixed {
        sigil: '.',
        item: a,
    }] = chain
    else {
        return None;
    };
    let Item::Prefixed {
        sigil: '.',
        item: b,
    } = a.as_ref()
    else {
        return None;
    };
    match b.as_ref() {
        Item::Prefixed {
            sigil: '.',
            item: c,
        } => match c.as_ref() {
            Item::Sym(name) => Some(Some(name)),
            _ => None,
        },
        Item::Punct(".") => Some(None),
        _ => None,
    }
}

/// Split a binding chain `<pattern> "=" <expr>` on its one top-level `=`.
/// Head and tail must be non-empty.
#[allow(clippy::type_complexity)]
fn split_binding<'i, 'a>(
    items: &'i [&'i Item<'a>],
) -> Parsed<(&'i [&'i Item<'a>], &'i [&'i Item<'a>])> {
    let mut eq = None;
    for (i, it) in items.iter().enumerate() {
        if matches!(it, Item::Punct("=")) {
            if eq.is_some() {
                return Err(ParseError::MalformedBinding.into());
            }
            eq = Some(i);
        }
    }
    let eq = eq.ok_or(ParseError::MalformedBinding)?;
    let (head, tail) = (&items[..eq], &items[eq + 1..]);
    if head.is_empty() || tail.is_empty() {
        return Err(ParseError::MalformedBinding.into());
    }
    if head.iter().any(|it| matches!(it, Item::Punct("|"))) {
        return Err(ParseError::LetOrUnparenthesized.into());
    }
    if let [it] = head {
        if is_bare_literal_header(it) {
            return Err(ParseError::BareLiteralHeader.into());
        }
    }
    Ok((head, tail))
}

/// Reject `&`-headed runs and float-like runs (`3.14`).
fn check_run_head(members: &[Item<'_>]) -> Parsed<()> {
    if matches!(&members[0], Item::Prefixed { sigil: '&', .. }) {
        return Err(ParseError::BinderRunGlued.into());
    }
    if let (
        Item::Sym(head),
        Some(Item::Prefixed {
            sigil: '.',
            item: seg,
        }),
    ) = (&members[0], members.get(1))
    {
        if parse_int(head).is_some() && is_dot_number(seg) {
            return Err(ParseError::FloatLiteralUnsupported.into());
        }
    }
    Ok(())
}

/// Check if a `.`-prefixed segment is a number (float tail).
fn is_dot_number(item: &Item<'_>) -> bool {
    match item {
        Item::Sym(s) => parse_int(s).is_some(),
        _ => false,
    }
}

/// Check if a run is the glued `#Self(…)` construction.
fn is_self_head(members: &[Item<'_>]) -> bool {
    matches!(
        members.first(),
        Some(Item::Prefixed { sigil: '#', item })
            if matches!(item.as_ref(), Item::Sym("Self"))
    )
}

/// Decode a Muon `<str>` literal into owned UTF-8 `Text`, combining surrogate pairs.
/// Unpaired surrogates cause [`ParseError::LoneSurrogate`].
fn decode_str(raw: &str) -> Parsed<Text> {
    let b = raw.as_bytes();
    let mut out = alloc::string::String::with_capacity(raw.len());
    let mut i = 0;
    let mut chunk = 0;
    while i < b.len() {
        if b[i] != b'\\' {
            i += 1;
            continue;
        }
        out.push_str(&raw[chunk..i]);
        match b[i + 1] {
            b'"' => out.push('"'),
            b'\\' => out.push('\\'),
            b'/' => out.push('/'),
            b'n' => out.push('\n'),
            b't' => out.push('\t'),
            b'r' => out.push('\r'),
            b'b' => out.push('\u{8}'),
            b'f' => out.push('\u{c}'),
            b'u' => {
                let hi = hex4(&b[i + 2..i + 6]);
                i += 6;
                if (0xD800..=0xDBFF).contains(&hi) {
                    let lo = match (b.get(i), b.get(i + 1)) {
                        (Some(b'\\'), Some(b'u')) => hex4(&b[i + 2..i + 6]),
                        _ => return Err(ParseError::LoneSurrogate.into()),
                    };
                    if !(0xDC00..=0xDFFF).contains(&lo) {
                        return Err(ParseError::LoneSurrogate.into());
                    }
                    let c = 0x1_0000 + ((hi - 0xD800) << 10) + (lo - 0xDC00);
                    out.push(char::from_u32(c).expect("combined surrogate pair"));
                    i += 6;
                } else if (0xDC00..=0xDFFF).contains(&hi) {
                    return Err(ParseError::LoneSurrogate.into());
                } else {
                    out.push(char::from_u32(hi).expect("non-surrogate BMP scalar"));
                }
                chunk = i;
                continue;
            }
            _ => unreachable!("Muon validated the <str> escape grammar"),
        }
        i += 2;
        chunk = i;
    }
    out.push_str(&raw[chunk..]);
    Ok(Text::from(out.as_str()))
}

/// Read four ASCII hex digits as a `u32`.
fn hex4(b: &[u8]) -> u32 {
    b.iter()
        .fold(0, |v, &c| v * 16 + (c as char).to_digit(16).unwrap())
}

/// Parse an integer literal (decimal, hex, or binary) with `_` separators.
pub(crate) fn parse_int(s: &str) -> Option<BigInt> {
    let (neg, body) = match s.as_bytes().first()? {
        b'-' => (true, &s[1..]),
        b'+' => (false, &s[1..]),
        _ => (false, s),
    };
    let (radix, digits) =
        if let Some(h) = body.strip_prefix("0x").or_else(|| body.strip_prefix("0X")) {
            (16u32, h)
        } else if let Some(b) = body.strip_prefix("0b").or_else(|| body.strip_prefix("0B")) {
            (2, b)
        } else {
            (10, body)
        };
    let mut cleaned = alloc::string::String::new();
    let mut after_sep = true;
    for &c in digits.as_bytes() {
        if c == b'_' {
            if after_sep {
                return None;
            }
            after_sep = true;
        } else {
            cleaned.push(c as char);
            after_sep = false;
        }
    }
    if after_sep || cleaned.is_empty() {
        return None;
    }
    let mag = BigInt::parse_bytes(cleaned.as_bytes(), radix)?;
    Some(if neg { -mag } else { mag })
}

/// Whether a block clause is a **binding** — it carries a top-level `=` punct.
/// A nested `=` lives inside a `(…)`/`[…]`/`{…}` item, never as a top-level
/// `Item::Punct`, so this is exactly the `<binding>` vs `<chain>` split the
/// `let` group makes (and [`split_binding`] then splits at the first `=`).
fn clause_is_binding(items: &[&Item<'_>]) -> bool {
    items.iter().any(|it| matches!(it, Item::Punct("=")))
}

/// Whether `item` is a bare **matching literal** — a number, a `.`-symbol, or a
/// string — used where a whole `&`-header or `let` LHS is expected. These are
/// equality patterns, not binders, so a bare one reads as a stray value or an
/// intended binding; Elly requires the wrap (`&(42)`, `&(.foo)`, `&("s")`; see
/// `BareLiteralHeader`). Nested in `[…]`/`{…}`/`(…)`/an or-pattern they are fine.
fn is_bare_literal_header(item: &Item<'_>) -> bool {
    match item {
        Item::Sym(s) => parse_int(s).is_some(),
        Item::Prefixed { sigil: '.', .. } => true,
        Item::Str(_) => true,
        _ => false,
    }
}

/// Check if an item is the `when` guard keyword.
fn is_when_kw(item: &Item) -> bool {
    head_keyword(item) == Some("when")
}

/// Returns non-comment chains of a `<seq>` with [chain-joining](join_chains) applied.
fn chain_slices<'a, 'b>(seq: &'b Seq<'a>) -> Vec<Vec<&'b Item<'a>>> {
    let chains = seq
        .0
        .iter()
        .filter(|c| !is_comment_only(c))
        .map(|c| {
            c.0.iter()
                .filter(|it| !matches!(it, Item::Comm(_)))
                .collect()
        })
        .collect();
    join_chains(chains)
}

/// Returns true if a `<braces>` seq contains a chain whose second non-comment item is `:`.
/// Used by [`Parser::block`] to reject bare-map spellings.
fn braces_contain_colon(seq: &Seq<'_>) -> bool {
    for chain in seq.0.iter().filter(|c| !is_comment_only(c)) {
        let items: Vec<&Item<'_>> = chain
            .0
            .iter()
            .filter(|it| !matches!(it, Item::Comm(_)))
            .collect();
        if items.len() >= 2 && matches!(items[1], Item::Punct(":")) {
            return true;
        }
    }
    false
}

/// Joins adjacent chains if they form a single continued expression.
/// A chain joins if the predecessor ends with a continuation (e.g., `&`, `=`, `|>`, `when`)
/// or if the current chain starts with one (e.g., `|>`, `elif`, `else`, `catch`).
fn join_chains<'a, 'b>(chains: Vec<Vec<&'b Item<'a>>>) -> Vec<Vec<&'b Item<'a>>> {
    let mut out: Vec<Vec<&'b Item<'a>>> = Vec::with_capacity(chains.len());
    for chain in chains {
        let join = matches!(out.last(), Some(prev) if trailing_join(prev) || leading_join(&chain));
        if join {
            out.last_mut().unwrap().extend(chain);
        } else {
            out.push(chain);
        }
    }
    out
}

/// Whether a chain ends with a trailing continuation.
fn trailing_join(chain: &[&Item]) -> bool {
    match chain.last() {
        Some(Item::Prefixed { sigil: '&', .. }) => true,
        Some(Item::Punct("=")) | Some(Item::Punct("|>")) => true,
        _ => {
            let n = chain.len();
            n >= 2
                && matches!(chain[n - 2], Item::Sym("when"))
                && matches!(chain[n - 1], Item::Parens(_))
        }
    }
}

/// Whether a chain opens with a leading continuation.
fn leading_join(chain: &[&Item]) -> bool {
    match chain.first() {
        Some(Item::Punct("|>")) => true,
        Some(first) => matches!(head_keyword(first), Some("elif" | "else" | "catch")),
        None => false,
    }
}

/// Returns the single non-comment chain of a `<seq>`, if it contains exactly one.
fn single_chain<'a, 'b>(seq: &'b Seq<'a>) -> Option<Vec<&'b Item<'a>>> {
    let mut chains = chain_slices(seq).into_iter();
    let first = chains.next()?;
    if chains.next().is_some() {
        return None;
    }
    Some(first)
}

/// Whether a chain holds only comments.
fn is_comment_only(chain: &Chain) -> bool {
    chain.0.iter().all(|it| matches!(it, Item::Comm(_)))
}

/// Whether `s` is an Elly keyword.
fn is_keyword(s: &str) -> bool {
    matches!(
        s,
        "Self"
            | "let"
            | "recur"
            | "import"
            | "const"
            | "local"
            | "with"
            | "as"
            | "when"
            | "match"
            | "case"
            | "of"
            | "if"
            | "elif"
            | "else"
            | "catch"
    )
}

/// Whether `name` can be bound and referenced from source as a plain name.
pub fn is_bindable_name(name: &str) -> bool {
    muon::is_sym(name)
        && !is_keyword(name)
        && !name.starts_with("__")
        && name != "_"
        && !reads_as_number(name)
}

/// Whether this item is a chain split point (e.g., `&`-binder or `let`/`recur`/`case`).
fn is_split_point(item: &Item) -> bool {
    is_binder(item)
        || matches!(
            head_keyword(item),
            Some("let") | Some("recur") | Some("case")
        )
}

/// Whether this item is a `&`-prefixed binder.
fn is_binder(item: &Item) -> bool {
    matches!(item, Item::Prefixed { sigil: '&', .. })
}

/// The keyword head of an item, if any (bare keyword or head of a keyword-headed run).
fn head_keyword<'a>(item: &Item<'a>) -> Option<&'a str> {
    match item {
        Item::Sym(s) if is_keyword(s) => Some(s),
        Item::Run(members) => match members.first() {
            Some(Item::Sym(s)) if is_keyword(s) => Some(s),
            _ => None,
        },
        _ => None,
    }
}