elly_core/

parse.rs

//! Parsing: Muon tree → Elly AST.
//!
//! A program is a single chain (`<expr>`). A chain's items are split on the
//! first `&`-prefixed item into an application spine and a trailing
//! abstraction, per `docs/elly-spec.md` and `docs/done/2026-07-06_elly-crate.md`.
//! Comments are dropped.
//!
//! **Patterns** (see `docs/done/2026-07-26_elly-patterns-native.md`) are
//! *faithful AST*: a `&`-header or a `let` binding's left-hand side parses into
//! a [`Pattern`] node that the evaluator matches directly. Parsing does not compile patterns
//! into eliminators — it only rephrases the Muon syntax into Elly's own
//! structures. Every abstraction is an `Expr::Abs(Rc<Lambda>)`, a run of
//! `&p0 &p1 …` collected into one multi-parameter [`Lambda`]; applying it matches
//! the arguments against the head (refuting via `NoMatch` on a miss). Source
//! application spines and spread calls flatten into one `Expr::App(Box<[Expr]>)`.

use alloc::boxed::Box;
use alloc::rc::Rc;
use alloc::string::String;
use alloc::vec::Vec;

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

use crate::ast::{Captures, Clause, Expr, HomeLeaf, Lambda, MapKey, Pattern, ProtoRef, Text};
use crate::eval::{Builtin, ModuleData};

/// Copy a source string slice into an owned text leaf. The AST no longer borrows
/// the Muon source (see `docs/todo/elly-impl-expr-repr-v1.md`), so every name /
/// symbol / bound name captured at parse time is copied here (inline for short
/// spellings, else a shared `Rc`). Takes `&str` so a `&&str` binding from a
/// slice pattern deref-coerces at the call site.
fn text(s: &str) -> Text {
    Text::from(s)
}

// 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 `parse_let`).
    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 the resolution pass (`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 the resolution pass (`resolve.rs`) after 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
    /// [`Expr::Builtin`](crate::Expr) at parse.
    UnboundName(Text),
    /// A module (`parse_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`](crate::Expr::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`](crate::Expr::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`](crate::Expr::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`](crate::Expr::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`](crate::Expr::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`](crate::Expr::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/todo/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 `parse_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,
}

/// What a module's source writes to name an import — a path, a package-qualified
/// name. Its grammar belongs to the host resolver, not to Elly.
pub type ImportSpec = Text;

/// What a resolver answers a spec with: one name per module, however many specs
/// reach it. Module instances are deduplicated by this name, so a resolver that
/// returns the spec unchanged would hand back two instances of one module for
/// `"./foo"` and `"foo"` (see [`crate::load_module`]).
pub type ModuleName = Text;

/// One `import` declaration: the name the importing module reaches the instance
/// by, and the spec its host resolver is handed.
///
/// The two written forms differ in whether the module also **re-exports** the
/// instance. `import "spec" as Foo` is a private frame slot; `Foo = import "spec"`
/// is the same slot plus an ordinary item `Foo` that forwards it. Both arrive here
/// as one `ImportDecl` — the re-exporting form has additionally pushed its
/// forwarding item into [`ModuleSyntax::items`] (see
/// `docs/done/2026-08-11_elly-modules-import.md`).
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ImportDecl {
    /// The name the importing module's bodies read the instance by.
    pub name: Text,
    /// What the host resolver is handed.
    pub spec: ImportSpec,
}

/// A module source's top-level declarations: its imports and its `const`
/// declarations, in source order, and its items. The imports are the module's
/// first frame slots — the const stage resolves, compiles and instantiates each
/// one, then instantiates this module against the results (see
/// [`crate::load_module`]). The iotas take no slot at all: an iota's identity is
/// its instance plus its position, derived on reference (see
/// `docs/done/2026-08-13_elly-modules-iotas.md`).
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ModuleSyntax {
    /// The `import` declarations, in source order, which is frame-slot order.
    pub imports: Vec<ImportDecl>,
    /// The names declared by `const`, in source order — the module's **iotas**.
    /// Sorted before they reach [`ModuleData`](crate::ModuleData), where the
    /// order is the address space a member reference counts against.
    pub iotas: Vec<Text>,
    /// The `name = body` items, in source order, bodies unresolved.
    pub items: Vec<(Text, Expr)>,
    /// The `local name = body` declarations, in source order, bodies unresolved
    /// — the module's **private** bindings. They are members like the items, and
    /// differ only in not being searched by name from outside (see
    /// `docs/done/2026-08-13_elly-modules-local.md`).
    pub locals: Vec<(Text, Expr)>,
    /// What the module declared as `__main`, if anything — the **reserved
    /// moditem** a runner evaluates and applies to the root capability.
    ///
    /// It is a slot rather than an entry in [`items`](Self::items), and that is
    /// what makes it unnameable: the member index space it stays out of is the
    /// only thing a body's reference or an outside `M.name` access can address.
    /// See `docs/done/2026-08-14_elly-run.md`.
    pub main: Option<Expr>,
}

/// Parse a whole parsed program (one top-level chain) to an expression.
pub fn parse_program<'a>(seq: &Seq<'a>) -> Result<Expr, ParseError> {
    // Chain joining runs first, so a program written as `&x` ⏎ `body` (or any
    // other continuation) is one expression, not `MultipleExpressions`.
    match chain_slices(seq).as_slice() {
        [] => Err(ParseError::EmptyProgram),
        [items] => parse_items(items),
        _ => Err(ParseError::MultipleExpressions),
    }
}

/// Parse a **module** source's top-level sequence into its declarations: one
/// `name = body` item or one `import` per non-comment chain, in source order.
/// Unlike [`parse_program`] a module is a *multi-chain* sequence, and a body is
/// not resolved here — [`crate::compile_module`] runs
/// [`crate::resolve::resolve_module_bodies`] afterwards so a body may refer to any
/// sibling regardless of order. An item's left-hand side is a single bare name in
/// v0 (no destructuring at module top level); duplicate names and non-name LHSs
/// are rejected. See `docs/done/2026-08-07_elly-modules-v0.md`.
///
/// An `import` chain has no top-level `=` in its private form, so it is recognized
/// before the `=` split rather than reported as a `MalformedBinding`. Its two
/// forms are described on [`ImportDecl`]; `Foo = import "spec"` also pushes the
/// item `Foo` that forwards the slot, since it is written as an item and should
/// read as one from outside.
///
/// A `const` declaration is read the same way and follows the same privacy
/// convention: `const false` and `const (false, true)` are private, `false =
/// const` declares the iota *and* the item that exports it.
///
/// A `local` declaration is the ordinary binding under the same convention:
/// `local x = <expr>` and the group `local (x = <expr> …)` bind a member the
/// module's own bodies reach and nothing outside can, where the bare
/// `x = <expr>` beside them is the export form.
pub fn parse_module<'a>(seq: &Seq<'a>) -> Result<ModuleSyntax, ParseError> {
    let mut items: Vec<(Text, Expr)> = Vec::new();
    let mut imports: Vec<ImportDecl> = Vec::new();
    let mut iotas: Vec<Text> = Vec::new();
    let mut locals: Vec<(Text, Expr)> = Vec::new();
    let mut main: Option<Expr> = None;
    // The declarations that are also items, kept apart by kind, so the collision
    // check below knows which shared names were written as one declaration and
    // are therefore fine. A name shared by two *declarations* never is.
    let mut reexported_imports: Vec<Text> = Vec::new();
    let mut reexported_iotas: Vec<Text> = Vec::new();
    for ci in chain_slices(seq) {
        // `chain_slices` drops comment-only chains and applies chain joining, so
        // `ci` is a non-empty, already-joined declaration chain.
        // Split on the first top-level `=`, exactly as `parse_binding` does; a
        // second top-level `=` is malformed (a nested `=` lives inside `(…)`/…).
        let split = ci.iter().position(|it| matches!(it, Item::Punct("=")));
        // `import "spec" as Foo` — a private slot, and the one module top-level
        // chain with no `=` of its own. A chain that *has* one is a binding
        // whatever it starts with, so `import = 3` still reports the keyword.
        if split.is_none() && head_keyword(ci[0]) == Some("import") {
            let (name, spec) = parse_private_import(&ci)?;
            push_import(&mut imports, name, spec)?;
            continue;
        }
        // `const false` / `const (false, true)` — a private declaration, and like
        // a private import the whole chain is the declaration.
        if split.is_none() && head_keyword(ci[0]) == Some("const") {
            for name in parse_const_decl(&ci)? {
                push_iota(&mut iotas, name)?;
            }
            continue;
        }
        // `local (x = 1, y = 2)` — the group form, whose bindings' `=`s all sit
        // inside the tuple, so the chain has none of its own. The single form
        // `local x = 1` does, and is read below with the other bindings.
        if split.is_none() && head_keyword(ci[0]) == Some("local") {
            for (name, body) in parse_local_group(&ci)? {
                push_local(&mut locals, name, body)?;
            }
            continue;
        }
        let eq = split.ok_or(ParseError::MalformedBinding)?;
        if ci[eq + 1..].iter().any(|it| matches!(it, Item::Punct("="))) {
            return Err(ParseError::MalformedBinding);
        }
        let (head, tail) = (&ci[..eq], &ci[eq + 1..]);
        if head.is_empty() || tail.is_empty() {
            return Err(ParseError::MalformedBinding);
        }
        // `const x = <expr>`, the private const-time expression form the grammar
        // reserves and nothing implements. A bare `const = 3` is not this — it
        // falls through to `plain_name`, which reports the keyword.
        if head.len() > 1 && head_keyword(head[0]) == Some("const") {
            return Err(ParseError::MalformedConst);
        }
        // `local x = <expr>` — the single private binding. A bare `local = 3` is
        // not this: it falls through to `plain_name`, which reports the keyword.
        if head.len() > 1 && head_keyword(head[0]) == Some("local") {
            let name = plain_name(&head[1..], ParseError::MalformedLocal)?;
            push_local(&mut locals, name, parse_items(tail)?)?;
            continue;
        }
        // `__main = <expr>` — a **reserved moditem**, recognized here because
        // `plain_name` would otherwise stop at the `__` and report the name as
        // reserved. It is not an item: it goes to its own slot, outside the
        // member index space, so nothing can name it (see `ModuleSyntax::main`).
        if let [Item::Sym(s)] = head {
            if let Some(reserved) = reserved_moditem(s) {
                if main.is_some() {
                    return Err(ParseError::DuplicateReserved(text(reserved)));
                }
                main = Some(parse_items(tail)?);
                continue;
            }
            if s.starts_with("__") {
                return Err(ParseError::UnknownReserved(text(s)));
            }
        }
        let name = plain_name(head, ParseError::BadModuleItemName)?;
        if items.iter().any(|(n, _)| n.as_str() == name.as_str()) {
            return Err(ParseError::DuplicateModuleItem);
        }
        // `Foo = import "spec"` — the same slot, re-exported. The item's body is
        // the name itself: resolution looks imports up before items, so it reads
        // the slot rather than looping back through this forwarding item.
        if head_keyword(tail[0]) == Some("import") {
            let spec = parse_import_spec(tail)?;
            push_import(&mut imports, name.clone(), spec)?;
            reexported_imports.push(name.clone());
            items.push((name.clone(), Expr::Name(name)));
            continue;
        }
        // `false = const` — the iota plus the item exporting it. There is nothing
        // to the right of the keyword until const-time expressions exist, and the
        // item's body is the name itself: a sibling reference finds the iota,
        // since members are searched iotas-first (see `resolve_module_bodies`).
        if head_keyword(tail[0]) == Some("const") {
            if tail.len() != 1 {
                return Err(ParseError::MalformedConst);
            }
            push_iota(&mut iotas, name.clone())?;
            reexported_iotas.push(name.clone());
            items.push((name.clone(), Expr::Name(name)));
            continue;
        }
        let body = parse_items(tail)?;
        items.push((name, body));
    }
    // A private declaration may not share a name with an item — inside the module
    // the name would have to mean both. A re-exported one shares by construction.
    // Two *declarations* may never share one, re-exported or not: neither form
    // writes an import and an iota at once.
    for imp in &imports {
        if iotas.iter().any(|n| n.as_str() == imp.name.as_str()) {
            return Err(ParseError::DuplicateModuleItem);
        }
        if reexported_imports
            .iter()
            .any(|n| n.as_str() == imp.name.as_str())
        {
            continue;
        }
        if items.iter().any(|(n, _)| n.as_str() == imp.name.as_str()) {
            return Err(ParseError::DuplicateModuleItem);
        }
    }
    for iota in &iotas {
        if reexported_iotas.iter().any(|n| n.as_str() == iota.as_str()) {
            continue;
        }
        if items.iter().any(|(n, _)| n.as_str() == iota.as_str()) {
            return Err(ParseError::DuplicateModuleItem);
        }
    }
    // A local shares with nothing: it is a declaration, and there is no form
    // writing a local and something else at once.
    for (name, _) in &locals {
        let taken = items.iter().any(|(n, _)| n.as_str() == name.as_str())
            || iotas.iter().any(|n| n.as_str() == name.as_str())
            || imports.iter().any(|i| i.name.as_str() == name.as_str());
        if taken {
            return Err(ParseError::DuplicateModuleItem);
        }
    }
    Ok(ModuleSyntax {
        imports,
        iotas,
        items,
        locals,
        main,
    })
}

/// 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 [`ModuleSyntax`]
/// 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<ImportDecl>,
    name: Text,
    spec: ImportSpec,
) -> Result<(), ParseError> {
    if imports.iter().any(|i| i.name.as_str() == name.as_str()) {
        return Err(ParseError::DuplicateModuleItem);
    }
    imports.push(ImportDecl { name, spec });
    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>]) -> Result<(Text, ImportSpec), ParseError> {
    // Drop the keyword head. When it is a glued run head (§D) the spec sits inside
    // the run (`import"spec"`), but `as <Name>` is space-separated and so stays in
    // the chain after the run — so the run's members and the chain tail concatenate
    // into one `"spec" as Name` stream, the same one the spaced form is.
    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)?;
            Ok((name, decode_str(spec)?))
        }
        _ => Err(ParseError::MalformedImport),
    }
}

/// Record one iota, rejecting a name a previous `const` already declared.
fn push_iota(iotas: &mut Vec<Text>, name: Text) -> Result<(), ParseError> {
    if iotas.iter().any(|n| n.as_str() == name.as_str()) {
        return Err(ParseError::DuplicateModuleItem);
    }
    iotas.push(name);
    Ok(())
}

/// 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>]) -> Result<Vec<Text>, ParseError> {
    // 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(seq), ..] => {
            let mut names = Vec::new();
            for c in chain_slices(seq) {
                names.push(plain_name(&c, ParseError::MalformedConst)?);
            }
            Ok(names)
        }
        rest if !rest.is_empty() => Ok(alloc::vec![plain_name(rest, ParseError::MalformedConst)?]),
        _ => Err(ParseError::MalformedConst),
    }
}

/// Record one local, rejecting a name a previous `local` already took.
fn push_local(locals: &mut Vec<(Text, Expr)>, name: Text, body: Expr) -> Result<(), ParseError> {
    if locals.iter().any(|(n, _)| n.as_str() == name.as_str()) {
        return Err(ParseError::DuplicateModuleItem);
    }
    locals.push((name, body));
    Ok(())
}

/// Parse the group form `local (<name> = <expr> …)` to its bindings.
///
/// The group is an ordinary `<parens>` wrapping a `<seq>`, so its bindings may be
/// newline- or comma-separated and it may carry comments, exactly as a `let`
/// group may — and an **empty group declares nothing**, the degenerate reading
/// `const ()` and `let ()` take. Anything else after the keyword is a malformed
/// declaration: the single form `local x = <expr>` has a top-level `=` and never
/// reaches here.
fn parse_local_group<'a>(ci: &[&Item<'a>]) -> Result<Vec<(Text, Expr)>, ParseError> {
    // The `local` keyword may be a bare sym or a glued run head (§D); the group is
    // the item after it (the run's second member in the run case).
    // The group is the item after the keyword: the run's second member in the run
    // case, the next chain item otherwise.
    let seq = match ci[0] {
        Item::Run(members) => {
            let Some(Item::Parens(seq)) = members.get(1) else {
                return Err(ParseError::MalformedLocal);
            };
            seq
        }
        _ => {
            let Some(Item::Parens(seq)) = ci.get(1) else {
                return Err(ParseError::MalformedLocal);
            };
            seq
        }
    };
    let mut bindings = Vec::new();
    for c in chain_slices(seq) {
        let eq = c
            .iter()
            .position(|it| matches!(it, Item::Punct("=")))
            .ok_or(ParseError::MalformedLocal)?;
        let (head, tail) = (&c[..eq], &c[eq + 1..]);
        if head.is_empty() || tail.is_empty() {
            return Err(ParseError::MalformedLocal);
        }
        if tail.iter().any(|it| matches!(it, Item::Punct("="))) {
            return Err(ParseError::MalformedLocal);
        }
        bindings.push((
            plain_name(head, ParseError::MalformedLocal)?,
            parse_items(tail)?,
        ));
    }
    Ok(bindings)
}

/// Parse the `import "<spec>"` right-hand side of a re-exporting import to its
/// spec. There is no `as` here: the item's own left-hand side named it. The
/// keyword may be spaced from the spec (two chain items) or glued to it (§D — one
/// run whose second member is the spec), the two spellings meaning the same.
fn parse_import_spec<'a>(tail: &[&Item<'a>]) -> Result<ImportSpec, ParseError> {
    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),
        },
        _ => return Err(ParseError::MalformedImport),
    };
    decode_str(spec)
}

/// The single plain name a binding position may hold: exactly one `<sym>` that is
/// not a keyword, a `__` name, a discard, or a number. A reserved token gets its
/// own error; every other shape (a destructuring pattern, a literal, several
/// items) gets the caller's `bad`, which names the position —
/// [`ParseError::BadPattern`] for an at-pattern's LHS,
/// [`ParseError::BadModuleItemName`] for a module item's.
fn plain_name<'a>(items: &[&Item<'a>], bad: ParseError) -> Result<Text, ParseError> {
    match items {
        [Item::Sym(s)] if is_keyword(s) => Err(ParseError::ReservedKeyword),
        [Item::Sym(s)] if s.starts_with("__") => Err(ParseError::ReservedName),
        [Item::Sym(s)] if reads_as_number(s) || *s == "_" => Err(bad),
        [Item::Sym(s)] => Ok(text(s)),
        _ => Err(bad),
    }
}

/// Would this non-empty `<sym>` read as a number rather than a reference? Either
/// it is a valid integer literal — including a signed one, since `-`/`+` are
/// symchars, so `-1` is one `<sym>` — or it is digit-leading and therefore a
/// *malformed* number. A reference is neither (see the atom path above), so a
/// binding may not take such a name: it could never be read back.
fn reads_as_number(s: &str) -> bool {
    parse_int(s).is_some() || s.as_bytes()[0].is_ascii_digit()
}

/// Parse a comment-free slice of items (a chain, or a suffix of one).
fn parse_items<'a>(items: &[&Item<'a>]) -> Result<Expr, ParseError> {
    if items.is_empty() {
        return Err(ParseError::EmptyChain);
    }
    // `|>` is the **loosest** operator: split on the last one so the chain is
    // a left-associative pipe chain over **segments**, each parsed by
    // `parse_segment`. A `&`/`let`/`recur` binder form can therefore never
    // capture a pipe — `&x x |> f` is `f (&x x)`, and a pipe-bodied lambda is
    // written `&x (x |> f)` — and a pipe's right operand is a whole segment,
    // which may itself end in a trailing binder form (`x |> &y body`).
    match items.iter().rposition(|it| matches!(it, Item::Punct("|>"))) {
        None => parse_segment(items),
        Some(k) => {
            let (left, right) = (&items[..k], &items[k + 1..]);
            if left.is_empty() || right.is_empty() {
                return Err(ParseError::MalformedPipe);
            }
            let l = parse_items(left)?;
            let r = parse_segment(right)?;
            // Thread the left operand in as `r`'s final argument, extending its
            // spine so `x |> f a b` stays one flattened call `f a b x`.
            Ok(append_arg(r, l))
        }
    }
}

/// Parse one pipe segment — a `|>`-free item slice: an application spine whose
/// trailing argument may be a `&`/`let`/`recur` binder form. A split point is a
/// `&`-binder or the `let`/`recur` keyword (or a `let`/`recur` **run head**, §D):
/// it has the lowest precedence within the segment and captures the rest of the
/// segment as its body, so the spine before the first one is a left-folded
/// application whose trailing argument is the abstraction / let / recur that
/// follows. With no split point this is exactly `parse_app_spine`.
fn parse_segment<'a>(items: &[&Item<'a>]) -> Result<Expr, ParseError> {
    match items.iter().position(|it| is_split_point(it)) {
        // No split point: a plain application spine (with `()` spread).
        None => parse_app_spine(items),
        // Leading split point: a `let (…) body`, a `recur (…) body`, or
        // `&<header> <rest>` abstracting a pattern over the rest.
        Some(0) => {
            match head_keyword(items[0]) {
                // A `let`/`recur` written glued to its group reads the group from
                // inside the run (§D): `let(x = 1) e` == `let (x = 1) e`.
                Some("let") | Some("recur") => parse_let_or_recur(items[0], items),
                // `case <subject>? { arms }`
                Some("case") => parse_case(items),
                _ => {
                    // A `&` binder (never `&`-headed-run, which is a run, not a
                    // `Prefixed`).
                    if items.len() == 1 {
                        return Err(ParseError::AbsWithoutBody);
                    }
                    let inner = match items[0] {
                        Item::Prefixed { sigil: '&', item } => item.as_ref(),
                        _ => return Err(ParseError::UnexpectedBinder),
                    };
                    // A `&<pat> when (…) …` binder carries a guard on its pattern,
                    // the same guard a `case` arm takes (see `peel_when`); the body
                    // is what remains after the guards. Guards attach only to a
                    // single (non-group) pattern header — a `&(a, b)` curried group
                    // with a `when` is not supported and falls through to
                    // `build_binder`, where the `when` lands in the body and errors.
                    if matches!(items.get(1), Some(it) if is_when_kw(it))
                        && !matches!(inner, Item::Parens(_))
                    {
                        if is_bare_literal_header(inner) {
                            return Err(ParseError::BareLiteralHeader);
                        }
                        let base = parse_pattern(&[inner])?;
                        let (pat, rest) = peel_when(base, &items[1..])?;
                        if rest.is_empty() {
                            return Err(ParseError::AbsWithoutBody);
                        }
                        let body = parse_segment(rest)?;
                        return Ok(abs(pat, body));
                    }
                    let body = parse_segment(&items[1..])?;
                    build_binder(inner, body)
                }
            }
        }
        // Split point in the middle: the abstraction / let is the trailing
        // argument of the application spine that precedes it.
        Some(k) => {
            let f = parse_segment(&items[..k])?;
            let arg = parse_segment(&items[k..])?;
            Ok(append_arg(f, arg))
        }
    }
}

/// Parse a leading `let`/`recur` form, reading the binder group from the item's
/// **second member** when the keyword is a glued run (§D) or from the next chain
/// item when it is a bare sym. `let(x = 1) e` and `let (x = 1) e` are the same.
/// The group must be a `(…)` tuple; a keyword with no group, or a glued run with
/// more than the keyword and one group member (`let(a)(b)`), is `…MissingBinders`.
fn parse_let_or_recur<'a>(head: &Item<'a>, items: &[&Item<'a>]) -> Result<Expr, ParseError> {
    // A keyword is `let` or `recur` (the only heads that reach here).
    let is_recur = head_keyword(head) == Some("recur");
    let missing = || {
        if is_recur {
            ParseError::RecurMissingBinders
        } else {
            ParseError::LetMissingBinders
        }
    };
    let (group_item, body_items): (&Item<'_>, &[&Item<'_>]) = match head {
        // Glued run: the group is the run's lone second member (a longer run is
        // malformed); the body is the chain after the run.
        Item::Run(members) if members.len() == 2 => (&members[1], &items[1..]),
        Item::Run(_) => return Err(missing()),
        // Bare keyword: the group is the next chain item, the body what follows it.
        _ => (*items.get(1).ok_or_else(missing)?, &items[2..]),
    };
    let group = match group_item {
        Item::Parens(seq) => seq,
        _ => return Err(missing()),
    };
    if is_recur {
        parse_recur_inner(group, body_items)
    } else {
        parse_let_inner(group, body_items)
    }
}

/// The body of a `let`: fold the group's **sequential** bindings
/// (`let (a = va, b = vb) e` desugars to the nested `(&a ((&b e) vb)) va`)
/// right-to-left over `body_items`, leaving the leftmost binding outermost.
/// Reached through [`parse_let_or_recur`], which reads the group from the chain
/// (a bare `let (…)` keyword) or from inside a glued run (`let(…)`).
///
/// An **empty group binds nothing**, so `let () e` is `e` — the fold over zero
/// bindings, and the unit of the form. It is not an error: a group is a list, and
/// a generated or commented-out one may legitimately come out empty.
fn parse_let_inner<'a>(group: &Seq<'a>, body_items: &[&Item<'a>]) -> Result<Expr, ParseError> {
    if body_items.is_empty() {
        return Err(ParseError::LetMissingBody);
    }
    // `let (a = va, b = vb) e` **is** the block `{ a = va, b = vb, e }`: the group's
    // (joined, comment-free) binding chains followed by the body as the final
    // clause. `build_block` produces the shared `Expr::Block`, collapsing an empty
    // group (`let () e` is `e`) and a lone body the same way a `{…}` block does.
    let mut clauses = chain_slices(group);
    // A `let` group holds **bindings only** — a chain without a top-level `=` is a
    // malformed binding (unlike a block, whose non-final clauses may be bare
    // expressions). Enforce it here so `let (x) x` stays `MalformedBinding`.
    for ci in &clauses {
        if !clause_is_binding(ci) {
            return Err(ParseError::MalformedBinding);
        }
    }
    clauses.push(body_items.to_vec());
    build_block(clauses)
}

/// Parse a `recur (b0, b1, …) body`. Shaped like [`parse_let`] — `items[0]` is the
/// keyword, `items[1]` the binder-group tuple, `items[2..]` the body — and unlike
/// it in what the group means: the bindings are **simultaneous**, so they cannot
/// desugar to nested abstractions and instead become a module item table that the
/// bodies reach through a terminal.
///
/// The left-hand sides are plain names, not patterns. The group *is* an item table,
/// so it follows [`parse_module`]'s rule (which is also what rejects a duplicate)
/// rather than `let`'s, which does allow a destructuring pattern. That divergence
/// falls out of the mechanism rather than being a choice.
///
/// The table is sorted here, at parse: the sort order *is* the index space a
/// sibling [`Expr::ModItem`] counts against, and the resolver assigns those indices
/// against the frozen [`ModuleData`].
///
/// As with `let`, an empty group is `body` — with the terminal dropped too, since a
/// group with no items has nothing to reach through it.
fn parse_recur_inner<'a>(group: &Seq<'a>, body_items: &[&Item<'a>]) -> Result<Expr, ParseError> {
    if body_items.is_empty() {
        return Err(ParseError::RecurMissingBody);
    }
    let syntax = parse_module(group)?;
    if !syntax.imports.is_empty() {
        // A group is an item table, not a module source: it has no frame of its
        // own for the const stage to fill, and it is built while a program runs.
        return Err(ParseError::MisplacedImport);
    }
    if !syntax.iotas.is_empty() {
        // Nor an instance of its own to mint iotas against.
        return Err(ParseError::MisplacedConst);
    }
    if !syntax.locals.is_empty() {
        // And every binding of a group is private already — it is reachable from
        // the group's own bodies and its body, and from nowhere else — so the
        // keyword would mark nothing.
        return Err(ParseError::MisplacedLocal);
    }
    if syntax.main.is_some() {
        // A reserved moditem is read by a tool that was pointed at a *source* —
        // a runner, a test runner — and a group is not one, so the slot would
        // never be looked at.
        return Err(ParseError::MisplacedReserved);
    }
    let mut bindings = syntax.items;
    let body = parse_segment(body_items)?;
    if bindings.is_empty() {
        return Ok(body);
    }
    bindings.sort_by(|(a, _), (b, _)| a.as_str().cmp(b.as_str()));
    // No frame, no imports, and no name: a group's bindings are written where
    // they are used, so there is no source of its own for a host to name. The
    // body goes in the module's own body slot — the same one a source fills with
    // `__main`, differing only in who evaluates it and when.
    Ok(Expr::Recur(Rc::new(ModuleData::from_bindings(
        bindings,
        Vec::new(),
        Box::new([]),
        Box::new([]),
        Box::new([]),
        Some(body),
        None,
    ))))
}

/// Parse one binding chain `<pattern> "=" <expr>` to its pattern and value. The
/// separator is the **first** top-level `=` (`<punct>`); a pattern may carry its
/// own `=` only inside `(…)`/`[…]`/`{…}` (a nested item, never top-level), so a
/// second top-level `=` is malformed. Both the head (pattern) and tail (value)
/// must be non-empty.
fn parse_binding<'a>(items: &[&Item<'a>]) -> Result<(Pattern, Expr), ParseError> {
    let mut eq = None;
    for (i, it) in items.iter().enumerate() {
        if matches!(it, Item::Punct("=")) {
            if eq.is_some() {
                return Err(ParseError::MalformedBinding); // a second top-level `=`
            }
            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);
    }
    // A top-level `|` in the LHS must be parenthesized (an `&`-header can't reach
    // this, since `&` prefixes one item), so the or-`|` and the binding `=` do
    // not compete: `let (((x=.a) | (x=.b)) = v) e`.
    if head.iter().any(|it| matches!(it, Item::Punct("|"))) {
        return Err(ParseError::LetOrUnparenthesized);
    }
    // A bare matching literal as the whole LHS needs parens: `let ((42) = v)`,
    // `let ((.foo) = v)`, `let (("s") = v)` (see `BareLiteralHeader`).
    if let [it] = head {
        if is_bare_literal_header(it) {
            return Err(ParseError::BareLiteralHeader);
        }
    }
    let pat = parse_pattern(head)?;
    let value = parse_items(tail)?;
    Ok((pat, value))
}

/// Parse a single item as an atomic expression (`<aexpr>`).
fn parse_aexpr<'a>(item: &Item<'a>) -> Result<Expr, ParseError> {
    match item {
        Item::Sym(s) => Ok(parse_sym(s)?),
        // A `.`-prefixed item is a symbol (`.foo`, `.0`); see parse_dot_symbol.
        Item::Prefixed { sigil: '.', item } => parse_dot_symbol(item),
        // A `[…]` list is a runtime list value (any arity, no 1-element
        // collapse); a `(…)` group is grouping / spread folded into one expr.
        // After the reshuffle (phase 3), bare `[…]` is rejected: write `#[…]`.
        Item::Brackets(_) => Err(ParseError::BareListLiteral),
        Item::Parens(seq) => parse_group(seq),
        // A `<str>` literal, decoded at parse into an owned `Expr::Str`.
        Item::Str(s) => Ok(Expr::Str(decode_str(s)?)),
        // A `{…}` brace group is a **block expression** (step 6), never a map:
        // the map literal is `#{…}` exclusively. `parse_block` reads the empty
        // `{}` as unit and refuses a stale `:`-clause with the `#{…}` nudge.
        Item::Braces(seq) => parse_block(seq),
        // A bare `.` (composition combinator) is deferred; any other stray punct
        // (`:`, `=`) has no atomic reading outside a map entry / `let` binding.
        Item::Punct(".") => Err(ParseError::CombinatorDeferred),
        Item::Punct(_) => Err(ParseError::PunctAtAtom),
        // Filtered before we get here.
        Item::Comm(_) => Err(ParseError::EmptyChain),
        // `#[…]` / `#{…}` are the explicit spellings of the list / map literals,
        // reading exactly as the bare `[…]` / `{…}` forms (reshuffle phase 1);
        // any other `#`-prefixed shape — including a bare `#Self`, which is a
        // form, not a value (see `parse_app_spine`) — is a reserved literal
        // notation (§2).
        Item::Prefixed { sigil: '#', item } => match item.as_ref() {
            Item::Brackets(seq) => parse_list(seq),
            Item::Braces(seq) => parse_map(seq),
            _ => Err(ParseError::ReservedLiteralForm),
        },
        // A `&`-binder is never fed to parse_aexpr by the split logic above.
        Item::Prefixed { .. } => Err(ParseError::UnexpectedBinder),
        // A **run** of glued atoms is one chain item; lower it to the single
        // expression its members would form (see `parse_run`).
        Item::Run(members) => parse_run(members),
    }
}

/// Lower a **run** — two or more atoms written with no whitespace — to the single
/// expression its members would form as one chain. The members are all atoms (a
/// `<punct>` or `<comm>` ends a run, never joins one), so they are exactly a
/// `<chain>`: parse them with the chain parser.
///
/// Two members that glue are either a **path** (a reference head followed by
/// `.`-segments) or an application (`f(x)`, `Main .A.S`). Both are the same
/// lowering — the members as a left-folded chain — so one `parse_items` call
/// serves both. A `&`-headed run is a binder slip and is refused outright (§C),
/// and a float-like run (`3.14`) is a rejected literal (§G).
fn parse_run<'a>(members: &[Item<'a>]) -> Result<Expr, ParseError> {
    check_run_head(members)?;
    parse_items(
        members
            .iter()
            .map(|it| it as &Item<'_>)
            .collect::<Vec<_>>()
            .as_slice(),
    )
}

/// Reject the two run shapes that have no reading in **any** position, so the
/// argument lowering ([`parse_run`]) and the spine-head flatten ([`parse_app_spine`])
/// refuse them alike:
///
/// - §C — a `&`-headed run is a binder glued to a following atom (`&x.0` is one
///   prefixed atom with a tail, and the tail has no binder reading);
/// - §G — an `<int>` immediately followed by a `.<digits>` segment is the float
///   shape (`3.14`), refused rather than read as the projection `3 .14` applied,
///   until a float literal exists.
///
/// A run always has ≥ 2 members (Muon never wraps a lone atom), so indexing the
/// head is sound.
fn check_run_head(members: &[Item<'_>]) -> Result<(), ParseError> {
    if matches!(&members[0], Item::Prefixed { sigil: '&', .. }) {
        return Err(ParseError::BinderRunGlued);
    }
    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);
        }
    }
    Ok(())
}

/// Is this a `.`-prefixed **number** segment (the second half of a float run)?
/// `3.14` is `Run[3, .14]`; a `.name` segment (`.foo`) is a path member, not a
/// float tail.
fn is_dot_number(item: &Item<'_>) -> bool {
    match item {
        Item::Sym(s) => parse_int(s).is_some(),
        _ => false,
    }
}

/// Decode a Muon `<str>`'s raw inner text (the bytes between the quotes, escapes
/// unresolved) into an owned UTF-8 [`Text`]. Muon has already validated the escape
/// *grammar* (only `\" \n \t \r \\ \/ \b \f` and four-hex-digit `\uXXXX`, no raw
/// newline), so this resolves the escapes and — the higher-layer job Muon defers —
/// **combines `\uXXXX` surrogate pairs** into one scalar. The one failure is an
/// **unpaired surrogate** (a high not followed by a low, or a lone low), which
/// UTF-8 cannot represent: [`ParseError::LoneSurrogate`].
fn decode_str(raw: &str) -> Result<Text, ParseError> {
    let b = raw.as_bytes();
    let mut out = String::with_capacity(raw.len());
    let mut i = 0;
    let mut chunk = 0; // start of the current verbatim (unescaped) run
    while i < b.len() {
        if b[i] != b'\\' {
            i += 1; // a non-escape byte (incl. any UTF-8 continuation) copies as-is
            continue;
        }
        out.push_str(&raw[chunk..i]); // flush the verbatim run before this escape
        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) {
                    // A high surrogate must be completed by a `\uXXXX` low surrogate.
                    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),
                    };
                    if !(0xDC00..=0xDFFF).contains(&lo) {
                        return Err(ParseError::LoneSurrogate);
                    }
                    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); // a lone low surrogate
                } 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 exactly four ASCII hex-digit bytes (Muon-validated) as a `u32`.
fn hex4(b: &[u8]) -> u32 {
    b.iter()
        .fold(0, |v, &c| v * 16 + (c as char).to_digit(16).unwrap())
}

/// Parse a `.`-prefixed item into a symbol. The inner item must be a single
/// name or number segment (`.foo`, `.0`); a `.` glued to anything else — the
/// record sugar `.(…)`, a nested sigil, a string — is deferred / ill-formed.
fn parse_dot_symbol<'a>(item: &Item<'a>) -> Result<Expr, ParseError> {
    match item {
        // Stored *without* the leading dot; the dot is implied by Expr::Symbol
        // and re-added when displayed / dumped.
        Item::Sym(s) => Ok(Expr::Symbol(text(s))),
        _ => Err(ParseError::BadSymbol),
    }
}

/// Classify a `<sym>`: an integer literal, a name, or an error. Symbols are no
/// longer `<sym>`s (a `.` is a Muon sigil now) — they arrive as `<prefixed>`
/// items and are handled by parse_dot_symbol.
fn parse_sym(s: &str) -> Result<Expr, ParseError> {
    // `Self` — the home module. It is a keyword (un-bindable, and the `Self <pat>`
    // pattern form needs a reserved head), but a *reference* to it is the module
    // leaf, so the short-circuit sits before the keyword guard. `as Self` reaches
    // here through `parse_proto_ref`, so the nominal check is the same leaf.
    if s == "Self" {
        return Ok(Expr::Home {
            leaf: HomeLeaf::Module,
            depth: 0,
        });
    }
    if is_keyword(s) {
        // A keyword is syntax, never a reference. `let` at a chain head is
        // handled before we get here; anywhere else it (and `with`) is an error.
        return Err(ParseError::ReservedKeyword);
    }
    if s == "_" {
        // `_` is the discard pattern (valid only as a binder), never a reference.
        Err(ParseError::DiscardReference)
    } else if let Some(n) = parse_int(s) {
        Ok(Expr::Int(n))
    } else if s.as_bytes()[0].is_ascii_digit() {
        // Digit-leading but not a valid int, and a name can't start with a digit.
        Err(ParseError::MalformedNumber)
    } else if s.starts_with("__") {
        // A `__` name is un-bindable, so resolve a known builtin here (a direct
        // dispatch node) rather than leaving it to a failing env walk plus a name
        // match on every call. The namespace is the language's, and closed, so an
        // unknown one is rejected here too — a misspelled `__mian` is a compile
        // error naming the namespace, not a name that happens to bind to nothing.
        // A reserved moditem (`__main`) is not a name at all and lands here as
        // well: it is a slot, and nothing reads it by reference. The former
        // home-module leaves are retired spellings like any other misspelling
        // (`Self` / `#Self` / `x.Self` are the readings now, see
        // `docs/done/2026-09-11_elly-v1-self.md`), so they land here too.
        match Builtin::from_name(s) {
            Some(op) => Ok(Expr::Builtin(op)),
            None => Err(ParseError::UnknownReserved(text(s))),
        }
    } else {
        Ok(Expr::Name(text(s)))
    }
}

/// Parse an integer literal per the *integers* grammar: optional `-`/`+` sign,
/// then decimal / `0x` hex / `0b` binary digits, with `_` separating digit
/// groups (never leading, trailing, or doubled). `None` if `s` is not a literal.
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)
        };
    // Strip `_` separators while rejecting leading/trailing/doubled ones.
    let mut cleaned = String::new();
    let mut after_sep = true; // start "after a separator" → forbids a leading `_`
    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; // trailing `_`, or no digits at all (e.g. `0x`, `+`)
    }
    let mag = BigInt::parse_bytes(cleaned.as_bytes(), radix)?;
    Some(if neg { -mag } else { mag })
}

/// Parse an application spine (a chain slice with no `&`/`let` split point and no
/// top-level `|>`), folding left. A `(…)` item does not contribute one argument —
/// it **spreads** (see `expand_arg`): `f (a, b)` folds to `((f a) b)`.
fn parse_app_spine<'a>(items: &[&Item<'a>]) -> Result<Expr, ParseError> {
    let mut args: Vec<Expr> = Vec::new();
    for (i, it) in items.iter().enumerate() {
        // The **head** run flattens into the spine (§B): `f(x) y` keeps the one
        // flat `App` node `f x y` it is today, not `((f x) y)`. A run anywhere but
        // the head never does — that is where the run is one grouped argument (§A).
        if i == 0 {
            match *it {
                Item::Run(members) => {
                    // The run still has no reading if it is `&`-headed or float-like
                    // (§C / §G) — flattening the head must not smuggle it past the
                    // guard the argument lowering applies.
                    check_run_head(members)?;
                    // `#Self(x)` — construction glued to its payload: the run's
                    // head member is the `#`-prefixed keyword (`Run[#Self, (x)]`),
                    // so it contributes the constructor leaf and the members
                    // after it the payload. Reads as the spaced `#Self x` below.
                    if is_self_head(members) {
                        args.push(Expr::Home {
                            leaf: HomeLeaf::New,
                            depth: 0,
                        });
                        for m in members[1..].iter() {
                            expand_arg(m, &mut args)?;
                        }
                    } else {
                        for m in members.iter() {
                            expand_arg(m, &mut args)?;
                        }
                    }
                }
                // `#Self x` — construction heading the spine: the constructor leaf
                // becomes the callee and the payload(s) follow as ordinary spine
                // items. A `#Self` anywhere else is `ReservedLiteralForm` (via
                // `parse_aexpr`), and a bare one — the loop's single item, refused
                // below — is too: construction is a form, not a value, so it may
                // only be applied, never bound or handed out. A module that means
                // to give construction away writes the eta-expansion
                // `mint = &n #Self(n)`.
                Item::Prefixed { sigil: '#', item }
                    if matches!(item.as_ref(), Item::Sym("Self")) =>
                {
                    args.push(Expr::Home {
                        leaf: HomeLeaf::New,
                        depth: 0,
                    });
                }
                _ => expand_arg(it, &mut args)?,
            }
        } else {
            expand_arg(it, &mut args)?;
        }
    }
    // `#Self` with nothing after it — the constructor leaf alone, which the
    // grammar above never leaves standing as a value.
    if matches!(
        args.as_slice(),
        [Expr::Home {
            leaf: HomeLeaf::New,
            ..
        }]
    ) {
        return Err(ParseError::ReservedLiteralForm);
    }
    // `items` is non-empty and every item yields at least one arg (a `()` group
    // yields the unit), so `args` is non-empty. A single arg is not an
    // application; two or more flatten into one spine (callee then arguments).
    Ok(fold_spine(args))
}

/// Fold a non-empty argument list into an expression: the lone element itself if
/// there is one, else a flattened `App` spine (element 0 the callee).
fn fold_spine(args: Vec<Expr>) -> Expr {
    if args.len() == 1 {
        args.into_iter().next().unwrap()
    } else {
        app(args)
    }
}

/// Is this run the glued `#Self(…)` construction — i.e. headed by the
/// `#`-prefixed `Self` keyword as its first member? (`#Self(5)` fuses into
/// `Run[#Self, (5)]`; the spaced `#Self 5` is two chain items and never a run.)
fn is_self_head(members: &[Item<'_>]) -> bool {
    matches!(
        members.first(),
        Some(Item::Prefixed { sigil: '#', item })
            if matches!(item.as_ref(), Item::Sym("Self"))
    )
}

/// Expand one chain item into argument expressions. A `(…)` group spreads its
/// chains (see `expand_group_args`); any other item is a single atom.
fn expand_arg<'a>(item: &'a Item<'a>, out: &mut Vec<Expr>) -> Result<(), ParseError> {
    match item {
        Item::Parens(seq) => expand_group_args(seq, out),
        // `.Self` — the payload read, a postfix over everything applied so far:
        // `f x .Self` is `(f x).Self`, the same left-associative step a `.N`
        // projection is (so a member reached by dot can no longer be named
        // `Self`). Bare — nothing accumulated before it — it stays the symbol
        // literal `.Self`: `parse_dot_symbol` never consults the keywords.
        Item::Prefixed { sigil: '.', item }
            if matches!(item.as_ref(), Item::Sym("Self")) && !out.is_empty() =>
        {
            let acc = fold_spine(core::mem::take(out));
            out.push(Expr::App(Box::new([
                Expr::Home {
                    leaf: HomeLeaf::Value,
                    depth: 0,
                },
                acc,
            ])));
            Ok(())
        }
        _ => {
            out.push(parse_aexpr(item)?);
            Ok(())
        }
    }
}

/// Expand a `(…)` group's chains as arguments, on the rule **one chain → one
/// argument** (grouping is the one-chain case). An *empty* group is the nullary
/// marker: it feeds one unit value `()` (an empty call still calls). Comment-only
/// chains are skipped and do not count toward emptiness.
fn expand_group_args<'a>(seq: &Seq<'a>, out: &mut Vec<Expr>) -> Result<(), ParseError> {
    let mut any = false;
    for items in chain_slices(seq) {
        out.push(parse_items(&items)?);
        any = true;
    }
    if !any {
        out.push(Expr::Unit); // nullary marker → the unit value ()
    }
    Ok(())
}

/// Parse a `(…)` group appearing as a standalone atom: expand it (grouping /
/// spread / nullary) and fold the pieces into one expression.
fn parse_group<'a>(seq: &Seq<'a>) -> Result<Expr, ParseError> {
    let mut args: Vec<Expr> = Vec::new();
    expand_group_args(seq, &mut args)?;
    // `expand_group_args` always yields ≥1 arg (an empty group feeds unit `()`).
    Ok(fold_spine(args))
}

/// Parse 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 parse_list<'a>(seq: &Seq<'a>) -> Result<Expr, ParseError> {
    let mut elems: Vec<Expr> = Vec::new();
    for items in chain_slices(seq) {
        elems.push(parse_items(&items)?);
    }
    Ok(Expr::List(elems))
}

/// Parse a `{…}` brace group as a **block expression** (syntax v1 step 6): a
/// sequence of clauses whose value is the last clause's. A block lowers onto the
/// same nested-abstraction chain a `let` group produces — `{ a = va, e }` is
/// `let (a = va) e`, i.e. `(&a e) va` — so it adds no evaluator node, and a
/// block *is* a scope because each binding becomes a lambda parameter that the
/// following clauses (and nothing outside) can see.
///
/// - 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) or a bare expression (evaluated for its effect, its
///   value discarded — lowered to a `_ =` binding, today's `_ = io.print(…)`).
/// - The **final** clause is the block's value and must be an expression; a
///   trailing binding is [`BlockTrailingBinding`](ParseError::BlockTrailingBinding).
///
/// A `:`-clause (a stale bare-map entry) has no reading in a block and is refused
/// with the `#{…}` nudge, as it is in every brace position. Clauses are the
/// `<seq>`'s joined non-comment chains, so a block may be laid out multi-line
/// with blank lines, comments, and the chain-continuation joins.
fn parse_block<'a>(seq: &Seq<'a>) -> Result<Expr, ParseError> {
    // A `:`-clause is the one shape a block shares with the old bare map; keep
    // the pointed error rather than letting it fall through as a bad expression.
    if braces_contain_colon(seq) {
        return Err(ParseError::BareMapLiteral);
    }
    build_block(chain_slices(seq))
}

/// Build an [`Expr::Block`] from a block's (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). Each clause becomes a
/// [`Clause::Bind`] (a chain with a top-level `=`) or a [`Clause::Do`] (a bare
/// expression). The degenerate blocks collapse rather than build a node: an empty
/// clause list is the unit value `()`, and a single expression clause is that
/// expression (`{ e }` is `e`). A trailing binding is rejected — a block's value
/// is its last clause's, and a binding leaves none (and its name would not
/// escape) — so the final clause is always a `Do`.
fn build_block<'a>(clauses: Vec<Vec<&Item<'a>>>) -> Result<Expr, ParseError> {
    let Some((last, leading)) = clauses.split_last() else {
        return Ok(Expr::Unit); // `{}` / `let () e` with no body chain — unit
    };
    if clause_is_binding(last) {
        return Err(ParseError::BlockTrailingBinding);
    }
    if leading.is_empty() {
        return parse_items(last); // `{ e }` is `e`
    }
    let mut built: Vec<Clause> = Vec::with_capacity(leading.len() + 1);
    for ci in leading {
        if clause_is_binding(ci) {
            let (pat, value) = parse_binding(ci)?;
            built.push(Clause::Bind(pat, value));
        } else {
            built.push(Clause::Do(parse_items(ci)?));
        }
    }
    built.push(Clause::Do(parse_items(last)?));
    Ok(Expr::Block(built.into_boxed_slice()))
}

/// 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 [`parse_binding`] then splits at the first `=`).
fn clause_is_binding(items: &[&Item<'_>]) -> bool {
    items.iter().any(|it| matches!(it, Item::Punct("=")))
}

/// Parse a `{…}` block into a map literal: each non-comment chain of the `<seq>`
/// is one entry (see `parse_entry`); comment-only chains are skipped (so a map may
/// be laid out multi-line with blank lines and comments). Entry order is source
/// order — evaluation re-sorts by the value order.
fn parse_map<'a>(seq: &Seq<'a>) -> Result<Expr, ParseError> {
    let mut entries: Vec<(Expr, Expr)> = Vec::new();
    for items in chain_slices(seq) {
        entries.push(parse_entry(&items)?);
    }
    Ok(Expr::Map(entries))
}

/// Parse one map entry `<key> ":" <value>`. The `:` is a single `<punct>` item at
/// position 1; the key is the single head item (`parse_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: }` == `{ .foo: () }`).
fn parse_entry<'a>(items: &[&Item<'a>]) -> Result<(Expr, Expr), ParseError> {
    if items.len() < 2 || !matches!(items[1], Item::Punct(":")) {
        return Err(ParseError::MalformedMapKey);
    }
    let key = parse_key(items[0])?;
    let value_items = &items[2..];
    let value = if value_items.is_empty() {
        Expr::Unit // empty rest → the unit value ()
    } else {
        parse_items(value_items)?
    };
    Ok((key, value))
}

/// Parse a map-entry key item. A bare *non-digit* atom key is the **symbol** of
/// the same spelling — `one` == `.one` — mirroring `.foo` exactly; a key is just
/// a token. 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`, `(0)` the integer `0`; an *empty* `()` is the unit key.
/// The remaining forms are a `.`-prefixed symbol (`.one`) and a `#[…]` / `#{…}`
/// literal key (`#[]` the empty-list key). A bare `[…]` / `{…}` key routes to the
/// same place only to be refused with its `#`-spelling nudge (`BareListLiteral` /
/// `BareMapLiteral`); anything else is a `MalformedMapKey`.
fn parse_key<'a>(item: &Item<'a>) -> Result<Expr, ParseError> {
    match item {
        // A bare non-digit `<sym>` key is the symbol of that spelling, read
        // exactly as `.<sym>` would be. A digit-leading key is rejected — write
        // `.5` (the symbol) or `(5)` (the computed integer key) to disambiguate.
        Item::Sym(s) if s.as_bytes()[0].is_ascii_digit() => Err(ParseError::MalformedMapKey),
        Item::Sym(s) => Ok(Expr::Symbol(text(s))),
        // A bare `{…}` in key position is a block expression at the atom layer,
        // which has no reading as a key — refuse it with the `#{…}` nudge rather
        // than silently keying on a block value (write `#{…}` for a map key).
        Item::Braces(_) => Err(ParseError::BareMapLiteral),
        // `.sym` symbol key, `(…)` computed key (empty `()` the unit key), `"…"`
        // string key, and the explicit `#[…]` / `#{…}` literal keys — each reads
        // exactly as the same item would at atom position. A bare `[…]` routes
        // here too, only to be refused with its `#[…]`-spelling nudge.
        Item::Prefixed { sigil: '.', .. }
        | Item::Prefixed { sigil: '#', .. }
        | Item::Brackets(_)
        | Item::Parens(_)
        | Item::Str(_) => parse_aexpr(item),
        // 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) => parse_path(members).map_err(|_| ParseError::MalformedMapKey),
        _ => Err(ParseError::MalformedMapKey),
    }
}

// ===========================================================================
// patterns
// ===========================================================================

/// `&<pattern> body` — the one binding form every abstraction (and `let`, and a
/// `__match` clause) is built from. Greedily **collects** into one multi-parameter
/// [`Lambda`]: when `body` is *directly* another abstraction (a run of `&p0 &p1 …`,
/// or a curried binder group), `pat` is prepended to its head so the whole run
/// shares one code node with a known arity. Collection stops at the first
/// non-abstraction body (a `&` nested inside an application does not extend the
/// arity) and at 255 parameters — a head that would exceed the `applied: u8`
/// counter starts a fresh nested `Lambda` instead of overflowing.
fn abs(pat: Pattern, body: Expr) -> Expr {
    match body {
        Expr::Abs(lam) if lam.head.len() < 255 => {
            // Prepend `pat` to the (freshly built, so uniquely owned) inner head.
            let lam = Rc::try_unwrap(lam).unwrap_or_else(|rc| (*rc).clone());
            let mut head = Vec::with_capacity(lam.head.len() + 1);
            head.push(pat);
            head.extend(Vec::from(lam.head));
            Expr::Abs(Rc::new(Lambda {
                head: head.into_boxed_slice(),
                body: lam.body,
                // Free variables are a resolution artifact: the parser leaves the
                // capture plan unresolved and `resolve.rs` fills it in.
                captures: Captures::Unresolved,
            }))
        }
        _ => Expr::Abs(Rc::new(Lambda {
            head: Box::new([pat]),
            body,
            captures: Captures::Unresolved,
        })),
    }
}

/// Build an application node from a flat call spine `[callee, arg0, …]` (≥ 2
/// elements). A single-element `items` is *not* an application — the caller
/// returns that element directly.
fn app(items: Vec<Expr>) -> Expr {
    debug_assert!(
        items.len() >= 2,
        "an application has a callee and ≥1 argument"
    );
    Expr::App(items.into_boxed_slice())
}

/// Apply `f` to one more `arg`, extending `f`'s call spine when it already is one
/// so `g x &y …` and `x |> f a` stay single flattened `App` nodes (a partial
/// applied to a trailing abstraction / pipe operand). Currying makes this
/// equivalent to a fresh binary application, and it re-renders identically.
fn append_arg(f: Expr, arg: Expr) -> Expr {
    match f {
        Expr::App(items) => {
            let mut v = Vec::from(items);
            v.push(arg);
            Expr::App(v.into_boxed_slice())
        }
        _ => Expr::App(Box::new([f, arg])),
    }
}

/// 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,
    }
}

/// Build the abstraction(s) an `&`-header `&<inner>` introduces over `body`. A
/// `(…)` inner is a **binder group** whose commas curry (`&(a, b)` → two params);
/// any other inner is a single-parameter pattern.
fn build_binder<'a>(inner: &Item<'a>, body: Expr) -> Result<Expr, ParseError> {
    match inner {
        Item::Parens(seq) => build_group(seq, body),
        // A bare matching literal (number `&42`, symbol `&.foo`, string `&"s"`) as
        // the whole header must be parenthesized: `&(42)`, `&(.foo)`, `&("s")` (see
        // `BareLiteralHeader`). Nested literals reach `parse_atom_item` unaffected.
        it if is_bare_literal_header(it) => Err(ParseError::BareLiteralHeader),
        other => {
            let pat = parse_pattern(&[other])?;
            Ok(abs(pat, body))
        }
    }
}

/// Build a curried binder group `&(p0, p1, …)`: each non-comment chain is one
/// parameter pattern, curried left-to-right (leftmost outermost). An empty group
/// `&()` is the nullary marker — one param, the unit pattern that matches `()`.
fn build_group<'a>(seq: &Seq<'a>, body: Expr) -> Result<Expr, ParseError> {
    let params = chain_slices(seq);
    if params.is_empty() {
        // `&()` → the unit pattern: assert the argument is unit `()`.
        return Ok(abs(Pattern::Unit, body));
    }
    let mut acc = body;
    for chain in params.iter().rev() {
        let pat = parse_pattern(chain)?;
        acc = abs(pat, acc);
    }
    Ok(acc)
}

/// Parse `case <subject>? { arms }`. The subject is exactly one item (atom, group, run)
/// or empty. Subjectless `case { ... }` is lowered to `&__arg (case __arg { ... })`
/// as an [`Expr::Abs`] using the reserved name `__arg`.
fn parse_case<'a>(items: &[&Item<'a>]) -> Result<Expr, ParseError> {
    // Gather the pieces after the `case` keyword: a glued run head contributes
    // its tail members, then the following chain items, forming `[subject?, {…}]`.
    let mut rest: Vec<&Item<'a>> = Vec::new();
    if let Item::Run(members) = items[0] {
        for m in &members[1..] {
            rest.push(m);
        }
    }
    rest.extend_from_slice(&items[1..]);
    // The arm block is the trailing `{…}`; what precedes it is the subject.
    let (last, subject_items) = rest.split_last().ok_or(ParseError::CaseMissingArms)?;
    let arms_seq = match last {
        Item::Braces(seq) => seq,
        _ => return Err(ParseError::CaseMissingArms),
    };
    let cases = parse_arms(arms_seq)?;
    match subject_items {
        // Subjectless: lower to `&__arg (case __arg { … })`.
        [] => {
            let subject = Rc::new(Expr::Name(text("__arg")));
            Ok(abs(
                Pattern::Bind(text("__arg")),
                Expr::Case { subject, cases },
            ))
        }
        // `case <subject> { … }` — the subject is exactly one item, an atom.
        [subj] => Ok(Expr::Case {
            subject: Rc::new(parse_aexpr(subj)?),
            cases,
        }),
        _ => Err(ParseError::CaseSubjectExtra),
    }
}

/// Parse `case` arms from a block. One arm per non-comment chain.
/// Empty blocks raise [`CaseMissingArms`].
fn parse_arms<'a>(seq: &Seq<'a>) -> Result<Box<[(Pattern, Expr)]>, ParseError> {
    let chains = chain_slices(seq);
    if chains.is_empty() {
        return Err(ParseError::CaseMissingArms);
    }
    let mut arms = Vec::with_capacity(chains.len());
    for chain in &chains {
        arms.push(parse_arm(chain)?);
    }
    Ok(arms.into_boxed_slice())
}

/// Parse an arm: `& <pattern> (when (<cond>))* <body>`.
/// Header must start with `&`. Guards are folded using [`peel_when`].
fn parse_arm<'a>(items: &[&Item<'a>]) -> Result<(Pattern, Expr), ParseError> {
    let inner = match items.first() {
        Some(Item::Prefixed { sigil: '&', item }) => item.as_ref(),
        _ => return Err(ParseError::ArmNotBinder),
    };
    // A bare matching literal needs parens, as everywhere a header does.
    if is_bare_literal_header(inner) {
        return Err(ParseError::BareLiteralHeader);
    }
    let base = parse_pattern(&[inner])?;
    let (pat, rest) = peel_when(base, &items[1..])?;
    if rest.is_empty() {
        return Err(ParseError::ArmMissingBody);
    }
    let body = parse_items(rest)?;
    Ok((pat, body))
}

/// Fold `when (<cond>)` guards onto `base`. Guards are nested as [`Pattern::When`]
/// and tried in order. Conditions must be `(…)` groups.
fn peel_when<'a, 'b>(
    mut base: Pattern,
    mut items: &'b [&'b Item<'a>],
) -> Result<(Pattern, &'b [&'b Item<'a>]), ParseError> {
    while !items.is_empty() && is_when_kw(items[0]) {
        let (group, next): (&Seq<'a>, &[&Item<'a>]) = match items[0] {
            // Glued run `when(…)`: the group is the run's lone second member.
            Item::Run(members) if members.len() == 2 => match &members[1] {
                Item::Parens(seq) => (seq, &items[1..]),
                _ => return Err(ParseError::WhenMissingCond),
            },
            Item::Run(_) => return Err(ParseError::WhenMissingCond),
            // Bare `when`: the group is the next chain item.
            _ => match items.get(1) {
                Some(Item::Parens(seq)) => (seq, &items[2..]),
                _ => return Err(ParseError::WhenMissingCond),
            },
        };
        let cond = parse_when_cond(group)?;
        base = Pattern::When {
            inner: Box::new(base),
            when: cond,
        };
        items = next;
    }
    Ok((base, items))
}

/// Is `item` the `when` guard keyword — bare, or a glued run head (§D)?
fn is_when_kw(item: &Item) -> bool {
    head_keyword(item) == Some("when")
}

/// Parse a `when` condition. Plain guards `(<chain>)` use `None`; pattern guards
/// `(<pattern> = <chain>)` use `Some(pattern)`.
fn parse_when_cond<'a>(seq: &Seq<'a>) -> Result<(Option<Box<Pattern>>, Expr), ParseError> {
    let chain = single_chain(seq).ok_or(ParseError::WhenMissingCond)?;
    if chain.is_empty() {
        return Err(ParseError::WhenMissingCond);
    }
    if chain.iter().any(|it| matches!(it, Item::Punct("="))) {
        let (pat, expr) = parse_binding(&chain)?;
        Ok((Some(Box::new(pat)), expr))
    } else {
        Ok((None, parse_items(&chain)?))
    }
}

/// The non-comment chains of a `<seq>`, each as its non-comment items, with the
/// [chain-joining pass](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)
}

/// Whether a `<braces>` seq contains any chain whose second non-comment item is
/// `:` — the shape a block shares with the old bare-map spelling. Such a group is
/// rejected with the `#{…}` nudge ([`parse_block`]); a brace group with no
/// `:`-clause is a block (step 6).
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
}

/// The chain-joining pass (`docs/todo/elly-syntax-v1.md` step 2, review §1): over
/// a `<seq>`'s non-comment chains, fold a chain into the one before it whenever
/// the pair reads as one continued expression that is *ill-formed as two separate
/// chains today* — so no existing program changes meaning. A chain joins onto its
/// predecessor when
///
/// - the predecessor ends with a trailing continuation — a `&`-binder header
///   (`AbsWithoutBody`), the punct `=` (`MalformedBinding`), the punct `|>`, or a
///   `when (…)` guard with no body — or
/// - the chain itself opens with a leading continuation — the punct `|>`, or one
///   of the continuation keywords `elif` / `else` / `catch`.
///
/// Joins cascade: a folded chain is re-examined, so `x =` ⏎ `&y` ⏎ `body` collapses
/// to the single chain `x = &y body`. A leading continuation at the very start of a
/// seq has no predecessor and is left alone (it fails downstream as it does today).
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` is non-empty because `join` implies a predecessor.
            out.last_mut().unwrap().extend(chain);
        } else {
            out.push(chain);
        }
    }
    out
}

/// Whether a chain ends with a trailing continuation (see [`join_chains`]).
fn trailing_join(chain: &[&Item]) -> bool {
    match chain.last() {
        Some(Item::Prefixed { sigil: '&', .. }) => true,
        Some(Item::Punct("=")) | Some(Item::Punct("|>")) => true,
        // A `when (…)` guard with no body: the arm's body is on the next line.
        _ => {
            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 (see [`join_chains`]).
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,
    }
}

/// The single non-comment chain of a `<seq>` (its non-comment items), or `None`
/// if the seq holds zero or more than one chain (e.g. a comma-separated group).
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)
}

/// Parse a pattern from a chain of items. Splits on the first top-level `|`
/// (or-pattern), then `=` (equality / at-pattern), else defers to the `as`/atom
/// levels.
fn parse_pattern<'a>(items: &[&Item<'a>]) -> Result<Pattern, ParseError> {
    if items.is_empty() {
        return Err(ParseError::BadPattern);
    }
    // `|` has the lowest precedence — split first so `=` and `as` bind tighter
    // inside each arm. Left-associative on multiple `|`.
    if let Some(idx) = items.iter().position(|it| matches!(it, Item::Punct("|"))) {
        let left = parse_pattern(&items[..idx])?;
        let right = parse_pattern(&items[idx + 1..])?;
        // Both arms must bind the same names in the same order (see
        // `ParseError::OrBindersMismatch`); that agreement is checked by the
        // resolver, which has the binders' de Bruijn order naturally.
        return Ok(Pattern::Or(Box::new(left), Box::new(right)));
    }
    // Prefix ordering comparators `< <ref>` / `> <ref>` (the rest is an atom
    // comparand, like `= <ref>`); they only appear at the head of a pattern.
    match items[0] {
        Item::Punct("<") => return Ok(Pattern::Less(parse_comparand(&items[1..])?)),
        Item::Punct(">") => return Ok(Pattern::Greater(parse_comparand(&items[1..])?)),
        _ => {}
    }
    if let Some(idx) = items.iter().position(|it| matches!(it, Item::Punct("="))) {
        if idx == 0 {
            // `= <ref>` — equality against an atom (name or literal).
            return Ok(Pattern::Equal(parse_comparand(&items[1..])?));
        }
        // `name = pat` — at-pattern (the rest is a *pattern*).
        let name = at_name(&items[..idx])?;
        let inner = parse_pattern(&items[idx + 1..])?;
        return Ok(Pattern::At(name, Box::new(inner)));
    }
    parse_as(items)
}

/// Parse the right-hand side of an `=` / `<` / `>` comparand: exactly one
/// **atom** — a name (`= x`), an integer (`= 5`), or a symbol (`= .foo`). A
/// pattern is a *closed grammar*, so a comparand never recurses into the general
/// expression parser (`parse_items`); a compound `= f x` / `< (f x)` is rejected
/// (`ComparandNotAtom`). The atom keeps the ordinary expression default at match
/// time — a name is a lookup — which is the only non-literal a match evaluates.
fn parse_comparand<'a>(items: &[&Item<'a>]) -> Result<Expr, ParseError> {
    match items {
        [it] => match it {
            Item::Sym(s) => parse_sym(s),
            Item::Prefixed { sigil: '.', item } => parse_dot_symbol(item),
            Item::Str(s) => Ok(Expr::Str(decode_str(s)?)),
            // A **path** (`Bool.false`) is one atom denoting a value by reference
            // — a lookup, not a computation, so it is a legitimate comparand (§E).
            Item::Run(members) => parse_path(members),
            _ => Err(ParseError::ComparandNotAtom),
        },
        _ => Err(ParseError::ComparandNotAtom),
    }
}

/// The bound name of an at-pattern's left-hand side: exactly one plain name (not
/// a keyword, a `__` name, a discard, or a number).
fn at_name<'a>(items: &[&Item<'a>]) -> Result<Text, ParseError> {
    plain_name(items, ParseError::BadPattern)
}

/// The narrowing level: the `Self <pat>` unwrapping qualifier, the prefix
/// `(as <Proto>) <pat>`, the postfix `<pat> as <Proto>`, or a bare atom.
fn parse_as<'a>(items: &[&Item<'a>]) -> Result<Pattern, ParseError> {
    // `Self <pat>` — narrow to an object of the home module and match its
    // payload. It qualifies whatever follows, so the rest is a whole pattern and
    // `Self x as Int` reads as `Self (x as Int)`. It is a `<pat>`, not a
    // top-level `<pattern>`, so a binder has to parenthesize it: `&(Self inner) …`
    // is valid, `&Self inner …` is not (`&` prefixes one item, so the latter
    // never reaches here with an inner at all).
    if let Item::Sym("Self") = items[0] {
        if items.len() < 2 {
            // Nothing to unwrap *into*. `Self _` is how to say "an object of
            // mine, payload ignored" — spelled out, since a bare `Self` in a
            // binder is much more likely a slip.
            return Err(ParseError::BadPattern);
        }
        let inner = parse_pattern(&items[1..])?;
        return Ok(Pattern::Unwrap {
            depth: 0,
            inner: Box::new(inner),
        });
    }
    // Prefix: `(as <Proto>) <pat>` — items[0] is a `(as …)` group.
    if let Item::Parens(seq) = items[0] {
        if let Some(chain) = single_chain(seq) {
            if !chain.is_empty() && matches!(chain[0], Item::Sym("as")) {
                let proto = parse_proto_ref(&chain[1..])?;
                let inner = parse_pattern(&items[1..])?;
                return Ok(Pattern::Type(proto, Box::new(inner)));
            }
        }
    }
    // Postfix: `<atom> as <Proto>`.
    if let Some(idx) = items.iter().position(|it| matches!(it, Item::Sym("as"))) {
        let proto = parse_proto_ref(&items[idx + 1..])?;
        let inner = parse_atom(&items[..idx])?;
        return Ok(Pattern::Type(proto, Box::new(inner)));
    }
    parse_atom(items)
}

/// Parse the prototype of an `as <Proto>` pattern: exactly one **name**. A
/// prototype is a value like any other now — `Int` is the module `__Int` under its
/// shadowable alias, not a keyword — so this is the same closed-grammar atom an
/// `=` comparand is, minus the literals: a module is named, never written out.
///
/// It stays a [`ProtoRef::Ref`] here even when the name is the `__`-spelling of a
/// builtin module. The alias spelling only becomes one at *resolve* (it is the
/// resolver's bottom tier), so folding both to the compiled [`ProtoRef::Kind`]
/// form belongs there, in one place.
fn parse_proto_ref(items: &[&Item<'_>]) -> Result<ProtoRef, ParseError> {
    let e = match items {
        [Item::Sym(s)] => parse_sym(s)?,
        // A **path** names a qualified prototype (`as Mod.Proto`), lowered by the
        // shared `parse_path` (§E).
        [Item::Run(members)] => parse_path(members)?,
        _ => return Err(ParseError::UnknownType),
    };
    match e {
        // A name (`Bool`, `Int`), a `__` builtin (`__Int`), `Self`, or a path
        // that lowers to a reference / application of references.
        e @ (Expr::Name(_) | Expr::Builtin(_) | Expr::Home { .. } | Expr::App(_)) => {
            Ok(ProtoRef::Ref(e))
        }
        // A literal: `as 5` names no module.
        _ => Err(ParseError::UnknownType),
    }
}

/// Parse a **path**: a run whose head is an **identifier** and whose every
/// following atom is a `.`-prefixed name-or-number segment (`Bool.false`,
/// `a.b.c`, `pair.0`, `__Int.add`). It lowers to a left fold of the head applied
/// to symbol literals — the same node member access and projection share — so it
/// is the reference the closed positions (a comparand, a map key, an `as <Proto>`)
/// accept by name.
///
/// The head admits a plain name, a `__` builtin, or a home leaf — references only.
/// A number head is excluded, which is what keeps `3.14` out (it is the rejected
/// float run, §G); a string or group head is a run but not a reference, so not a
/// path; a `(…)` call member anywhere is computation, not reference, and
/// disqualifies. A path is a run (≥ 2 members); the bare-name degenerate case is
/// the ordinary atom arm at the call site.
fn parse_path<'a>(members: &[Item<'a>]) -> Result<Expr, ParseError> {
    if members.len() < 2 {
        return Err(ParseError::ComparandNotAtom);
    }
    // The head is a reference: a plain name, a `__` builtin, or a home leaf.
    let head = match &members[0] {
        Item::Sym(s) => parse_sym(s)?,
        _ => return Err(ParseError::ComparandNotAtom),
    };
    // Every following member is a `.`-segment (a symbol or a number projection).
    for m in &members[1..] {
        if !matches!(m, Item::Prefixed { sigil: '.', .. }) {
            return Err(ParseError::ComparandNotAtom);
        }
    }
    // Left fold: the head applied to each `.`-segment's symbol in turn.
    let mut acc = head;
    for m in &members[1..] {
        if let Item::Prefixed { sigil: '.', item } = m {
            acc = Expr::App(Box::new([acc, parse_dot_symbol(item)?]));
        }
    }
    Ok(acc)
}

/// Parse an atomic pattern: a single item (or a `(…)` grouping of one pattern).
fn parse_atom<'a>(items: &[&Item<'a>]) -> Result<Pattern, ParseError> {
    match items {
        [it] => parse_atom_item(it),
        _ => Err(ParseError::BadPattern),
    }
}

/// Parse a single atomic-pattern item.
fn parse_atom_item<'a>(item: &Item<'a>) -> Result<Pattern, ParseError> {
    match item {
        Item::Sym("_") => Ok(Pattern::Discard),
        Item::Sym(s) if is_keyword(s) => Err(ParseError::ReservedKeyword),
        Item::Sym(s) if s.starts_with("__") => Err(ParseError::ReservedName),
        // A numeric literal is an equality pattern (`= n` sugar, mirroring the
        // `.sym → Equal(Symbol)` sugar below); a digit-leading non-integer is a
        // malformed number, and everything else is a binder name.
        Item::Sym(s) => match parse_int(s) {
            Some(n) => Ok(Pattern::Equal(Expr::Int(n))),
            None if s.as_bytes()[0].is_ascii_digit() => Err(ParseError::MalformedNumber),
            None => Ok(Pattern::Bind(text(s))),
        },
        // `.sym` literal → `= .sym`.
        Item::Prefixed { sigil: '.', item } => Ok(Pattern::Equal(parse_dot_symbol(item)?)),
        // A `<str>` literal is an equality pattern — the textual twin of `.sym`.
        Item::Str(s) => Ok(Pattern::Equal(Expr::Str(decode_str(s)?))),
        // Bare `[…]` / `{…}` in pattern position are always rejected (reshuffle):
        // write `#[…]` / `#{…}`. No `{…}` block exists in a pattern and the empty
        // `{}` is no longer the empty-map pattern, so every bare brace is refused —
        // exactly as every bare bracket is.
        Item::Brackets(_) => Err(ParseError::BareListLiteral),
        // `(…)` grouping — a single subpattern; commas (multiple chains) are an
        // error (they only curry after `&`).
        Item::Parens(seq) => match single_chain(seq) {
            Some(chain) if !chain.is_empty() => parse_pattern(&chain),
            _ => Err(ParseError::BadPattern),
        },
        Item::Braces(_) => Err(ParseError::BareMapLiteral),
        // `#[…]` / `#{…}` — the explicit spellings of the list / map patterns,
        // reading exactly as the bare forms (reshuffle phase 1); any other
        // `#`-prefixed shape is a reserved literal notation (§2).
        Item::Prefixed { sigil: '#', item } => match item.as_ref() {
            Item::Brackets(seq) => parse_list_pattern(seq),
            Item::Braces(seq) => parse_map_pattern(seq),
            _ => Err(ParseError::ReservedLiteralForm),
        },
        _ => Err(ParseError::BadPattern),
    }
}

/// Parse a `{ k0: p0, … }` map pattern: each entry is `<key> ":" <value-pattern>`,
/// with an optional trailing `...`/`...rest`; `Rest::None` (no rest) is a
/// **closed** key set. The **key is itself a pattern**, but must denote a concrete
/// value to probe. A **lookup** key names a concrete value: `.sym` (the literal),
/// bare `sym` (the literal), or the equality pattern `(= <expr>)` / `= <expr>` for
/// a computed key. A grouped **binder** pattern in key position is instead a
/// **capture** — `(k)` / `(_)` peels the smallest remaining entry, binding its key
/// (see `match_pattern` in `eval.rs`); this is why the computed key is `(= k)`,
/// not `(k)`. The entry splits on its first top-level `:`.
fn parse_map_pattern<'a>(seq: &Seq<'a>) -> Result<Pattern, ParseError> {
    let chains = chain_slices(seq);
    let n = chains.len();
    let mut entries: Vec<(MapKey, Pattern)> = Vec::new();
    let mut rest: Option<Box<Pattern>> = None;
    for (i, chain) in chains.iter().enumerate() {
        if let Some(r) = as_rest(chain) {
            if i != n - 1 {
                return Err(ParseError::BadPattern); // rest must be trailing
            }
            rest = Some(r);
        } else {
            let colon = chain
                .iter()
                .position(|it| matches!(it, Item::Punct(":")))
                .ok_or(ParseError::MalformedMapKey)?;
            let val_items = &chain[colon + 1..];
            if colon == 0 || val_items.is_empty() {
                return Err(ParseError::MalformedMapKey); // empty key or value
            }
            // A bare single `<sym>` key is the literal symbol (like a map literal);
            // otherwise the key is a pattern — an equality form is a concrete-key
            // lookup, any other (binder) pattern is a key capture.
            let key_items = &chain[..colon];
            let bare_sym = match key_items {
                [Item::Sym(s)] => Some(*s),
                _ => None,
            };
            let key = if let Some(s) = bare_sym {
                // A bare non-digit sym key is the literal symbol (`five` → `.five`);
                // a digit-leading key is rejected — write `.5` (the symbol) or
                // `(5)` / `(= 5)` (the integer key) to disambiguate.
                if s.as_bytes()[0].is_ascii_digit() {
                    return Err(ParseError::MalformedMapKey);
                }
                MapKey::Lookup(Expr::Symbol(text(s)))
            } else if let [Item::Run(members)] = key_items {
                // A **path** key (`{ Mod.k: p }`) denotes a concrete value by
                // reference — a lookup, like the `.sym` / bare-sym forms (§E).
                MapKey::Lookup(parse_path(members)?)
            } else {
                match parse_pattern(key_items)? {
                    Pattern::Equal(expr) => MapKey::Lookup(expr),
                    kpat => MapKey::Capture(Box::new(kpat)),
                }
            };
            let valpat = parse_pattern(val_items)?;
            entries.push((key, valpat));
        }
    }
    Ok(Pattern::Map { entries, rest })
}

/// Parse a `[…]` list pattern: fixed-arity element patterns with an optional
/// trailing `...`/`...rest`.
fn parse_list_pattern<'a>(seq: &Seq<'a>) -> Result<Pattern, ParseError> {
    let chains = chain_slices(seq);
    let n = chains.len();
    let mut elems: Vec<Pattern> = Vec::new();
    let mut rest: Option<Box<Pattern>> = None;
    for (i, chain) in chains.iter().enumerate() {
        if let Some(r) = as_rest(chain) {
            if i != n - 1 {
                return Err(ParseError::BadPattern); // rest must be trailing
            }
            rest = Some(r);
        } else {
            elems.push(parse_pattern(chain)?);
        }
    }
    Ok(Pattern::List { elems, rest })
}

/// Recognize a trailing-rest element chain: `...rest` (a name) or `...` (anon).
/// Both lex as nested `.` sigils (three deep), so no new Muon token is needed.
fn as_rest<'a>(chain: &[&Item<'a>]) -> Option<Box<Pattern>> {
    if chain.len() != 1 {
        return None;
    }
    // `it = .( .( … ) )`: two `.` sigils, then either `.name` (→ a `Bind` over the
    // remainder) or a bare `.` punct (→ a `Discard` over it).
    if let Item::Prefixed {
        sigil: '.',
        item: a,
    } = chain[0]
    {
        if let Item::Prefixed {
            sigil: '.',
            item: b,
        } = a.as_ref()
        {
            match b.as_ref() {
                Item::Prefixed {
                    sigil: '.',
                    item: c,
                } => {
                    if let Item::Sym(name) = c.as_ref() {
                        return Some(Box::new(Pattern::Bind(text(name))));
                    }
                }
                Item::Punct(".") => return Some(Box::new(Pattern::Discard)),
                _ => {}
            }
        }
    }
    None
}

/// Does this chain hold only comments (so it contributes no expression)?
fn is_comment_only(chain: &Chain) -> bool {
    chain.0.iter().all(|it| matches!(it, Item::Comm(_)))
}

/// Is `s` an Elly keyword (reserved syntax, neither a reference nor bindable)?
/// `as` leads the type-narrowing pattern qualifier (recognized structurally
/// before this check); `Self` is the home module — a *reference* to it is the
/// module leaf (see `parse_sym`), and the reservation is what keeps no binder
/// from taking the name and what lets `Self <pat>` head the unwrap pattern;
/// `with`/`when`/`match`/`case`/`of` are parked for future forms (a parallel
/// binding, a guard, and the surface `case`/`match` sugar over the `__match`
/// builtin).
fn is_keyword(s: &str) -> bool {
    matches!(
        s,
        "Self"
            | "let"
            | "recur"
            | "import"
            | "const"
            | "local"
            | "with"
            | "as"
            | "when"
            | "match"
            | "case"
            | "of"
            | "if"
            | "elif"
            | "else"
            | "catch"
    )
}

/// Can `name` be bound and then referenced from Elly source as a plain name? It
/// must be a Muon `<sym>` and pass the same tests `plain_name` applies to a
/// binding's left-hand side: not a keyword, not a `__` reserved name, not the
/// discard `_`, and not something that `reads_as_number` accepts.
///
/// This is the rule for names a *host* binds from outside a program — the PyO3
/// `elly.Env` prelude — where there is no left-hand side to parse but source must
/// still be able to read the binding back. Keep it in step with `plain_name`;
/// `crates/elly-core/tests/module.rs` pins the two together.
pub fn is_bindable_name(name: &str) -> bool {
    muon::is_sym(name)
        && !is_keyword(name)
        && !name.starts_with("__")
        && name != "_"
        && !reads_as_number(name)
}

/// Is this item a chain split point — a `&`-binder, or a `let` / `recur` keyword
/// (bare or as a glued **run head**, §D)? A keyword run is a split point because
/// it is the keyword form reading its group from inside the run; `head_keyword`
/// covers the bare-sym case too, so no separate bare check is needed.
fn is_split_point(item: &Item) -> bool {
    is_binder(item)
        || matches!(
            head_keyword(item),
            Some("let") | Some("recur") | Some("case")
        )
}

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

/// The **keyword head** of an item, if it is one: a bare keyword sym, or the head
/// sym of a **keyword-headed run** (§D). A keyword written glued to its group —
/// `let(x = 1) e`, `import"spec"`, `const(a, b)` — fuses into one run whose head
/// is the keyword, and the group comes from the run's second member rather than
/// the next chain item. Reading the head is what makes `let(x=1) e` equal
/// `let (x=1) e`.
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,
    }
}