volaro 0.0.2 → 0.1.0-alpha.3

package/compiler/validator/vlcheck/parser.py

@@ -0,0 +1,1638 @@
+"""A tolerant recursive-descent parser with a Pratt expression sub-parser.
+
+Design choices for a Stage 1 validator:
+  - Never abort. On an unexpected token, record E-PARSE and resynchronize on the
+    next NEWLINE / DEDENT so the rest of the file still gets checked.
+  - Parse types, `fn` signatures, and the skeleton of views / services precisely,
+    because that is where the checks live.
+  - Parse the many free-form configuration lines (api settings, auth providers,
+    theme, service errors/before/after) permissively as `Directive` nodes.
+  - Binding powers follow spec section 5.2 ordering (range binds tighter than
+    comparison, looser than additive). See PROJECT.md section 5.3 for the spec's
+    internal disagreement here.
+"""
+
+from __future__ import annotations
+
+import re
+
+from . import ast_nodes as A
+from .diagnostics import Diagnostic, Severity
+from .lexer import Token
+
+_METHODS = ("get", "post", "put", "patch", "delete")
+_ASSIGN_OPS = ("=", "+=", "-=", "*=", "/=")
+_IDENT_RE = re.compile(r"(?<![.\w])([A-Za-z_][A-Za-z0-9_]*)")
+
+# binop -> (left_bp, right_bp); equal bp marks non-associative
+_BINOPS = {
+    "|>": (1, 2),
+    "??": (4, 3),          # right associative
+    "or": (5, 6),
+    "and": (7, 8),
+    "==": (9, 9), "!=": (9, 9),
+    "<": (11, 11), "<=": (11, 11), ">": (11, 11), ">=": (11, 11),
+    "..": (12, 12), "..=": (12, 12),
+    "+": (13, 14), "-": (13, 14),
+    "*": (15, 16), "/": (15, 16), "%": (15, 16),
+}
+_PREFIX_BP = 17
+_CMP = {"<", "<=", ">", ">=", "==", "!="}
+
+
+class Parser:
+    def __init__(self, tokens: list[Token], src: str, filename: str = "<input>") -> None:
+        self.toks = tokens
+        self.src = src
+        self.filename = filename
+        self.pos = 0
+        self.diags: list[Diagnostic] = []
+        # Mirrors the lexer's own `bracket_depth` at the token-stream level
+        # (same characters, so always in lockstep) — used by `_end_line` to
+        # tolerate a statement ending at a closing bracket / comma instead of
+        # a real NEWLINE, the shape a block-bodied closure's last statement
+        # takes when it is itself a call argument (see
+        # `_parse_bracketed_closure_body`, B2 in the callback-props decision).
+        self.bracket_depth = 0
+        # One-shot: set by `_parse_bracketed_closure_body` when it ends a
+        # block-bodied closure's block by finding a sibling call argument at
+        # a shallower column, having already consumed (inside that last
+        # statement's own `_end_line()`) the real NEWLINE token that would
+        # otherwise have told the enclosing call-argument loop a separator
+        # occurred. Read via `_take_closure_ate_sep`, which resets it.
+        self._closure_ate_sep = False
+
+    def _take_closure_ate_sep(self) -> bool:
+        v = self._closure_ate_sep
+        self._closure_ate_sep = False
+        return v
+
+    # -- cursor ----------------------------------------------------------
+    def peek(self, k: int = 0) -> Token:
+        j = self.pos + k
+        return self.toks[j] if j < len(self.toks) else self.toks[-1]
+
+    @property
+    def cur(self) -> Token:
+        return self.peek()
+
+    def at(self, kind: str) -> bool:
+        return self.cur.kind == kind
+
+    def at_kw(self, *words: str) -> bool:
+        return self.cur.kind == "KW" and (not words or self.cur.value in words)
+
+    def at_soft(self, *words: str) -> bool:
+        return self.cur.kind == "NAME" and self.cur.value in words
+
+    def at_op(self, *ops: str) -> bool:
+        return self.cur.kind == "OP" and self.cur.value in ops
+
+    def advance(self) -> Token:
+        t = self.cur
+        if t.kind == "OP" and t.value in "([{":
+            self.bracket_depth += 1
+        elif t.kind == "OP" and t.value in ")]}":
+            self.bracket_depth = max(0, self.bracket_depth - 1)
+        if self.pos < len(self.toks) - 1:
+            self.pos += 1
+        return t
+
+    def expect_op(self, op: str, ctx: str = "") -> Token | None:
+        if self.at_op(op):
+            return self.advance()
+        self.error(f"expected {op!r}{(' ' + ctx) if ctx else ''}, found {self._desc(self.cur)}",
+                   self.cur)
+        return None
+
+    def error(self, msg: str, tok: Token, code: str = "E-PARSE", fix: str | None = None) -> None:
+        self.diags.append(Diagnostic(code, Severity.ERROR, msg, tok.start, max(tok.end, tok.start + 1),
+                                     fix, self.filename))
+
+    def _desc(self, t: Token) -> str:
+        if t.kind == "EOF":
+            return "end of file"
+        if t.kind == "NEWLINE":
+            return "end of line"
+        if t.kind in ("INDENT", "DEDENT"):
+            return t.kind.lower()
+        return f"{t.value!r}" if t.value else t.kind
+
+    def skip_newlines(self) -> None:
+        while self.at("NEWLINE"):
+            self.advance()
+
+    def _at_line_end(self) -> bool:
+        return self.cur.kind in ("NEWLINE", "DEDENT", "EOF")
+
+    def _end_line(self) -> None:
+        if self.at("NEWLINE"):
+            self.advance()
+        elif self.cur.kind in ("DEDENT", "EOF"):
+            return
+        elif self.bracket_depth > 0 and self.at_op(")", "]", "}", ","):
+            # The statement ended because the enclosing bracket closes (or the
+            # next comma-separated item starts) right here, not because of a
+            # real newline — exactly the shape of the last statement in a
+            # block-bodied closure passed as a call argument (see
+            # `_parse_bracketed_closure_body`): the lexer suppresses
+            # INDENT/DEDENT inside any open bracket, so there is no DEDENT to
+            # end it with either; `parse_stmt` still calls `_end_line`
+            # unconditionally, so this has to be tolerated here.
+            return
+        else:
+            self.error(f"expected end of line, found {self._desc(self.cur)}", self.cur)
+            self._recover_to_line()
+
+    def _recover_to_line(self) -> None:
+        while self.cur.kind not in ("EOF",):
+            if self.at("NEWLINE"):
+                self.advance()
+                return
+            if self.at("DEDENT"):
+                return
+            self.advance()
+
+    # -- blocks ----------------------------------------------------------
+    def parse_block(self, parse_item) -> list:
+        items: list = []
+        self.skip_newlines()
+        if not self.at("INDENT"):
+            if self.bracket_depth > 0:
+                # `_parse_bracketed_closure_body` (a flat statement sequence,
+                # tracked by source column) is the only block form available
+                # inside an open bracket -- the lexer never emits INDENT/
+                # DEDENT there, so a *nested* block (this `if`/`match`/`for`/
+                # `while`/`try`/`par`/`spawn` trying to open one) has nothing
+                # to parse. Name the real cause instead of the generic
+                # message, which otherwise reads as unrelated to the actual
+                # `fn(...)` closure a few tokens up.
+                self.error(
+                    "a nested block (if / match / for / while / try / par / "
+                    "spawn) is not supported inside a closure written "
+                    "directly as a call argument -- only a flat sequence of "
+                    "statements is. Bind the closure with `let` above the "
+                    "call instead, then pass it by name.",
+                    self.cur, code="E-CLOSURE-NESTED-BLOCK")
+            else:
+                self.error("expected an indented block", self.cur)
+            return items
+        self.advance()  # INDENT
+        while not self.at("DEDENT") and not self.at("EOF"):
+            self.skip_newlines()
+            if self.at("DEDENT") or self.at("EOF"):
+                break
+            before = self.pos
+            node = parse_item()
+            if node is not None:
+                if isinstance(node, list):
+                    items.extend(node)
+                else:
+                    items.append(node)
+            self.skip_newlines()
+            if self.pos == before:
+                self._recover_to_line()
+        if self.at("DEDENT"):
+            self.advance()
+        return items
+
+    # -- module / items ----------------------------------------------------
+    def parse_module(self) -> A.Module:
+        mod = A.Module(start=0)
+        self.skip_newlines()
+        while not self.at("EOF"):
+            before = self.pos
+            item = self.parse_item()
+            if item is not None:
+                mod.items.append(item)
+            self.skip_newlines()
+            if self.pos == before:
+                self.advance()
+        mod.end = self.cur.end
+        return mod
+
+    def parse_item(self):
+        t = self.cur
+        if self.at_kw("use"):
+            return self.parse_use()
+        if self.at_kw("type"):
+            return self.parse_type_decl()
+        if self.at_kw("fn"):
+            return self.parse_fn_decl()
+        if self.at_soft("view"):
+            return self.parse_view_decl()
+        if self.at_soft("api"):
+            return self.parse_api_decl()
+        if self.at_soft("service"):
+            return self.parse_service_decl()
+        if self.at_kw("auth"):
+            return self.parse_auth_decl()
+        if self.at_soft("model"):
+            return self.parse_model_decl()
+        if self.at_soft("theme"):
+            return self.parse_theme_decl()
+        if self.at_soft("recipe"):
+            return self.parse_recipe_decl()
+        if self.at_soft("page"):
+            return self.parse_page_decl()
+        if self.at_kw("let") or self.at_soft("state") or self.at_soft("derive"):
+            self.error(
+                f"'{t.value}' binds a value and a module holds declarations only",
+                t, fix="move it inside a view or fn; for a shared value use a "
+                "zero-parameter fn, and for config use volaro.toml / env")
+            self._recover_to_line()
+            return None
+        self.error(f"unexpected {self._desc(t)} at top level", t)
+        self._recover_to_line()
+        return None
+
+    def parse_use(self) -> A.Use:
+        start = self.advance().start
+        parts: list[str] = []
+        # A module filename may coincide with a language keyword (`auth.vl` is
+        # the project's own shared authentication declaration). Once `use` has
+        # started, keyword tokens are path text too; punctuation/newline still
+        # delimit the path unambiguously.
+        while (self.cur.kind in ("NAME", "TYPENAME", "PRIM", "KW")
+               or self.at_op(".", "..", "/")):
+            parts.append(self.advance().value)
+        names: list[str] = []
+        if self.at_op("{"):
+            self.advance()
+            while not self.at_op("}") and not self.at("EOF"):
+                if self.cur.kind in ("NAME", "TYPENAME"):
+                    names.append(self.advance().value)
+                if self.at_op(","):
+                    self.advance()
+                else:
+                    break
+            self.expect_op("}")
+        end = self.cur.end
+        self._end_line()
+        return A.Use(start=start, end=end, path="".join(parts), names=names)
+
+    # -- type / model ----------------------------------------------------
+    def parse_type_decl(self) -> A.TypeDecl:
+        start = self.advance().start
+        name = self.advance().value if self.at("TYPENAME") else "?"
+        node = A.TypeDecl(start=start, name=name)
+        if self.at_op("="):
+            self.advance()
+            if self.at("NEWLINE"):
+                node.kind = "union"
+                node.variants = self.parse_block(self.parse_variant_block)
+                return node
+            tref = self.parse_type_ref()
+            if self.at_op("|"):
+                node.kind = "union"
+                node.variants.append(A.Variant(start=tref.start, name=tref.name))
+                while self.at_op("|"):
+                    self.advance()
+                    node.variants.append(self.parse_variant_inline())
+                self._end_line()
+            else:
+                node.kind = "alias"
+                node.alias_of = tref
+                if self.at_soft("distinct"):
+                    self.advance()
+                    node.distinct = True
+                self._end_line()
+            return node
+        node.kind = "record"
+        node.fields = self.parse_block(self.parse_field)
+        node.end = self.cur.end
+        return node
+
+    def parse_variant_block(self):
+        if self.cur.kind not in ("NAME", "TYPENAME"):
+            self.error("expected a variant name", self.cur)
+            self._recover_to_line()
+            return None
+        v = A.Variant(start=self.cur.start, name=self.advance().value)
+        if self.at_op("("):
+            self.advance()
+            v.params = self._param_list_until(")")
+            self.expect_op(")")
+        self._end_line()
+        return v
+
+    def parse_variant_inline(self) -> A.Variant:
+        v = A.Variant(start=self.cur.start,
+                      name=self.advance().value if self.cur.kind in ("NAME", "TYPENAME") else "?")
+        if self.at_op("("):
+            self.advance()
+            v.params = self._param_list_until(")")
+            self.expect_op(")")
+        return v
+
+    def parse_field(self):
+        # field / param names may be keywords (e.g. `role`, `type`) per spec section 4.3
+        if self.cur.kind not in ("NAME", "KW"):
+            self.error("expected a field name", self.cur)
+            self._recover_to_line()
+            return None
+        f = A.Field(start=self.cur.start, name=self.advance().value)
+        if not self._at_line_end() and not self.at_op("="):
+            f.type = self.parse_type_ref()
+        if self.at_op("="):
+            self.advance()
+            f.default = self.parse_expr()
+        self._end_line()
+        return f
+
+    def parse_model_decl(self) -> A.ModelDecl:
+        start = self.advance().start
+        name = self.advance().value if self.at("TYPENAME") else "?"
+        node = A.ModelDecl(start=start, name=name)
+
+        def item():
+            if self.at_soft("index"):
+                self.advance()
+                cols: list[str] = []
+                if self.at_op("("):
+                    self.advance()
+                    while not self.at_op(")") and not self.at("EOF"):
+                        if self.at("NAME"):
+                            cols.append(self.advance().value)
+                        if self.at_soft("desc"):
+                            self.advance()
+                        if self.at_op(","):
+                            self.advance()
+                        else:
+                            break
+                    self.expect_op(")")
+                self._end_line()
+                node.indexes.append(cols)
+                return None
+            if self.cur.kind not in ("NAME", "KW"):
+                self.error("expected a model field", self.cur)
+                self._recover_to_line()
+                return None
+            f = A.Field(start=self.cur.start, name=self.advance().value)
+            if not self._at_line_end() and not self.at_op("="):
+                f.type = self.parse_type_ref()
+            while not self._at_line_end():
+                if self.at_op("="):
+                    self.advance()
+                    f.default = self.parse_expr()
+                    continue
+                if self.at("NAME"):
+                    a = self.advance().value
+                    if self.at_op(":"):
+                        self.advance()
+                        val: list[str] = []
+                        while self.cur.kind in ("NAME", "TYPENAME") or self.at_op("."):
+                            val.append(self.advance().value)
+                        f.attrs.append(f"{a}:{''.join(val)}")
+                    else:
+                        f.attrs.append(a)
+                    continue
+                self.error(f"unexpected {self._desc(self.cur)} in model field", self.cur)
+                self._recover_to_line()
+                break
+            self._end_line()
+            node.fields.append(f)
+            return None
+
+        self.parse_block(item)
+        node.end = self.cur.end
+        return node
+
+    # -- type refs -----------------------------------------------------
+    def parse_type_ref(self) -> A.TypeRef:
+        start = self.cur.start
+        if self.at_kw("fn"):
+            self.advance()
+            self.expect_op("(")
+            fps = []
+            while not self.at_op(")") and not self.at("EOF") and not self.at("NEWLINE"):
+                fps.append(self.parse_type_ref())
+                if self.at_op(","):
+                    self.advance()
+                else:
+                    break
+            self.expect_op(")")
+            ret = self.parse_type_ref()
+            return A.TypeRef(start=start, end=self.cur.end, is_fn=True, fn_params=fps, fn_ret=ret)
+
+        if self.cur.kind in ("PRIM", "TYPENAME", "NAME"):
+            tr = A.TypeRef(start=start, name=self.advance().value)
+            if self.at_op("<"):
+                self.advance()
+                while not self.at_op(">") and not self.at("EOF") and not self.at("NEWLINE"):
+                    tr.args.append(self.parse_type_ref())
+                    if self.at_op(","):
+                        self.advance()
+                    else:
+                        break
+                self.expect_op(">")
+        elif self.at("NIL"):
+            self.advance()
+            tr = A.TypeRef(start=start, name="nil")
+        else:
+            self.error(f"expected a type, found {self._desc(self.cur)}", self.cur)
+            return A.TypeRef(start=start, end=self.cur.end, name="?")
+
+        while True:
+            if self.at_op("??"):        # lexer glues '?' '?' into one token
+                self.advance()
+                tr.optional = True
+                tr.opt_nested = True
+                continue
+            if self.at_op("?"):
+                self.advance()
+                if tr.optional:
+                    tr.opt_nested = True
+                tr.optional = True
+                if self.at_op("?"):
+                    tr.opt_nested = True
+                    self.advance()
+                continue
+            if self.at_op("!"):
+                self.advance()
+                tr.fallible = True
+                if self.cur.kind in ("TYPENAME", "PRIM"):
+                    tr.err_type = self.parse_type_ref()
+                continue
+            break
+        tr.end = self.cur.end
+        return tr
+
+    # -- params ------------------------------------------------------------
+    def _param_list_until(self, closer: str) -> list:
+        params = []
+        self.skip_newlines()          # a param list may span lines inside ( )
+        while not self.at_op(closer) and not self.at("EOF"):
+            if not self.at("NAME"):
+                self.error(f"expected a parameter name, found {self._desc(self.cur)}", self.cur)
+                break
+            p = A.Param(start=self.cur.start, name=self.advance().value)
+            if not self.at_op(",", closer, "="):
+                p.type = self.parse_type_ref()
+            if self.at_op("="):
+                self.advance()
+                p.default = self.parse_expr()
+            params.append(p)
+            self.skip_newlines()
+            if self.at_op(","):
+                self.advance()
+                self.skip_newlines()
+            else:
+                break
+        return params
+
+    # -- functions -----------------------------------------------------
+    def parse_fn_decl(self) -> A.FnDecl:
+        start = self.advance().start
+        name = self.advance().value if self.at("NAME") else "?"
+        fn = A.FnDecl(start=start, name=name)
+        self.expect_op("(")
+        fn.params = self._param_list_until(")")
+        self.expect_op(")")
+        if not self._at_line_end():
+            fn.ret = self.parse_type_ref()
+        fn.body = self.parse_block(self.parse_stmt)
+        fn.end = self.cur.end
+        return fn
+
+    # -- views -------------------------------------------------------
+    def parse_view_decl(self) -> A.ViewDecl:
+        start = self.advance().start
+        name = self.advance().value if self.at("TYPENAME") else "?"
+        v = A.ViewDecl(start=start, name=name)
+        self.expect_op("(")
+        v.params = self._param_list_until(")")
+        self.expect_op(")")
+        v.body = self.parse_block(self.parse_view_stmt)
+        v.end = self.cur.end
+        return v
+
+    def parse_view_stmt(self):
+        t = self.cur
+        # `state` / `load` are contextual: keywords only as the head of a view
+        # statement (`state x = ...`), plain identifiers otherwise (`state = x`,
+        # `load(id)`).
+        if self.at_soft("state") and self.peek(1).kind == "NAME":
+            self.advance()
+            n = self.advance().value if self.at("NAME") else "?"
+            typ = None
+            if not self.at_op("="):
+                typ = self.parse_type_ref()
+            self.expect_op("=")
+            init = self.parse_expr()
+            self._end_line()
+            return A.StateDecl(start=t.start, name=n, type=typ, init=init)
+        if self.at_kw("derive"):
+            self.advance()
+            n = self.advance().value if self.at("NAME") else "?"
+            self.expect_op("=")
+            e = self.parse_expr()
+            self._end_line()
+            return A.DeriveDecl(start=t.start, name=n, expr=e)
+        if self.at_soft("load") and self.peek(1).kind == "NAME":
+            return self.parse_load()
+        if self.at_kw("on"):
+            return self.parse_on_block()
+        if self.at_soft("list") and self._is_list_block():
+            return self.parse_list_block()
+        if self.at_kw("if"):
+            return self.parse_if(self.parse_view_stmt)
+        if self.at_kw("match"):
+            return self.parse_match_stmt(self.parse_view_stmt)
+        if self.cur.kind in ("NAME", "TYPENAME") and not self.at_kw():
+            if self.at("NAME") and self.peek(1).kind == "OP" and self.peek(1).value in _ASSIGN_OPS:
+                return self.parse_stmt()
+            return self.parse_element()
+        return self.parse_stmt()
+
+    def _is_list_block(self) -> bool:
+        j = self.pos + 1
+        depth = 0
+        while j < len(self.toks):
+            tk = self.toks[j]
+            if tk.kind in ("NEWLINE", "EOF", "INDENT", "DEDENT"):
+                return False
+            if tk.kind == "OP" and tk.value in "([{":
+                depth += 1
+            elif tk.kind == "OP" and tk.value in ")]}":
+                depth -= 1
+            elif depth == 0 and tk.kind == "KW" and tk.value == "as":
+                return True
+            j += 1
+        return False
+
+    def parse_list_block(self) -> A.ListBlock:
+        start = self.advance().start   # 'list'
+        src = self.parse_expr()
+        if self.at_kw("as"):
+            self.advance()
+        else:
+            self.error("expected 'as' in list block", self.cur)
+        var = self.advance().value if self.at("NAME") else "?"
+        node = A.ListBlock(start=start, src=src, var=var)
+        if self.at_soft("key"):
+            self.advance()
+            if self.at_op(":"):
+                self.advance()
+                node.key = self.parse_expr()
+                node.has_key = True
+            else:
+                self.error("expected ':' after 'key'", self.cur)
+        node.end = self.cur.end
+        self.skip_newlines()
+        if self.at("INDENT"):
+            node.body = self.parse_block(self.parse_view_stmt)
+        else:
+            self._end_line()
+        return node
+
+    def parse_load(self) -> A.LoadDecl:
+        start = self.advance().start
+        n = self.advance().value if self.at("NAME") else "?"
+        self.expect_op("=")
+        e = self.parse_expr()
+        node = A.LoadDecl(start=start, name=n, expr=e)
+        node.end = self.cur.end
+        self.skip_newlines()
+        if self.at("INDENT"):
+            self.advance()
+            while not self.at("DEDENT") and not self.at("EOF"):
+                self.skip_newlines()
+                if self.at("DEDENT"):
+                    break
+                if self.at_soft("pending"):
+                    self.advance()
+                    node.pending = self.parse_block(self.parse_view_stmt)
+                elif self.at_soft("error"):
+                    self.advance()
+                    if self.at("NAME"):
+                        node.error_name = self.advance().value
+                    node.error_body = self.parse_block(self.parse_view_stmt)
+                else:
+                    self.error("expected 'pending' or 'error' in load block", self.cur)
+                    self._recover_to_line()
+                self.skip_newlines()
+            if self.at("DEDENT"):
+                self.advance()
+        else:
+            self._end_line()
+        return node
+
+    def parse_on_block(self) -> A.OnBlock:
+        start = self.advance().start   # 'on'
+        ev = self.advance().value if self.cur.kind in ("NAME", "KW") else "?"
+        args: list[str] = []
+        while self.at("NAME"):
+            args.append(self.advance().value)
+            if self.at_op(","):
+                self.advance()
+            else:
+                break
+        node = A.OnBlock(start=start, event=ev, args=args)
+        if self.at_op(":"):                     # inline form: `on tap: <stmt>`
+            self.advance()
+            node.body = self._inline_handler_body()
+            self._end_line()
+        else:
+            node.body = self.parse_block(self.parse_stmt)
+        node.end = self.cur.end
+        return node
+
+    def _inline_handler_body(self) -> list:
+        """One statement after `on <event>:` — an expression or an assignment
+        (`on tap: open = false`)."""
+        start = self.cur.start
+        expr = self.parse_expr()
+        if self.at_op(*_ASSIGN_OPS):
+            op = self.advance().value
+            return [A.Assign(start=start, target=expr, op=op, value=self.parse_expr())]
+        return [A.ExprStmt(start=start, expr=expr)]
+
+    def parse_element(self) -> A.Element:
+        start = self.cur.start
+        name = self.advance().value
+        el = A.Element(start=start, name=name)
+
+        def is_attr() -> bool:
+            # `name:` where name is an identifier or a keyword like `type` / `on`
+            return (self.cur.kind in ("NAME", "KW")
+                    and not self.at_kw("on", "if", "match")
+                    and self.peek(1).kind == "OP" and self.peek(1).value == ":")
+
+        if self.at_op("("):
+            self.advance()
+            self.skip_newlines()          # attrs may open onto their own lines
+            while not self.at_op(")") and not self.at("EOF"):
+                if is_attr():
+                    an = self.advance().value
+                    self.advance()
+                    el.attrs.append((an, self.parse_expr()))
+                else:
+                    el.args.append(self.parse_expr())
+                # spec 3.7: a bare newline also separates items inside an open
+                # bracket, matching `_parse_postfix`'s own call-argument loop
+                # -- needed for a component with more than one callback prop
+                # (DESIGN-01), each written as its own multi-line closure, with
+                # no comma between them. `_take_closure_ate_sep` reads (and
+                # resets) the one-shot flag `_parse_bracketed_closure_body`
+                # sets when a closure attr's own last statement already
+                # consumed the newline that would otherwise separate it here.
+                had_nl = self.at("NEWLINE") or self._take_closure_ate_sep()
+                self.skip_newlines()
+                if self.at_op(","):
+                    self.advance()
+                    self.skip_newlines()
+                elif not had_nl and not self.at_op(")"):
+                    break
+            self.expect_op(")")
+
+        while not self._at_line_end():
+            if is_attr():
+                an = self.advance().value
+                self.advance()
+                el.attrs.append((an, self.parse_expr()))
+                continue
+            if self.at_kw("on"):
+                self.advance()
+                ev = self.advance().value if self.cur.kind in ("NAME", "KW") else "?"
+                on_args: list[str] = []
+                while self.at("NAME"):
+                    on_args.append(self.advance().value)
+                    if self.at_op(","):
+                        self.advance()
+                    else:
+                        break
+                if self.at_op(":"):                 # `... on tap: <stmt>`
+                    self.advance()
+                    el.body.append(A.OnBlock(start=start, event=ev, args=on_args,
+                                             body=self._inline_handler_body()))
+                    continue
+                # `... on tap` then an indented block — terminates the element line
+                ob = A.OnBlock(start=start, event=ev, args=on_args)
+                if self.at("NEWLINE"):
+                    self.advance()
+                ob.body = self.parse_block(self.parse_stmt) if self.at("INDENT") else []
+                el.body.append(ob)
+                el.end = self.cur.end
+                return el
+            if self.at_kw("if", "match"):
+                break
+            before = self.pos
+            el.args.append(self.parse_expr())
+            if self.pos == before:
+                self.advance()
+                break
+
+        el.end = self.cur.end
+        if self.at("NEWLINE"):
+            self.advance()
+        if self.at("INDENT"):
+            el.body = list(el.body) + self.parse_block(self.parse_view_stmt)
+        return el
+
+    # -- api / service / auth / theme ----------------------------------------
+    def parse_api_decl(self) -> A.ApiDecl:
+        start = self.advance().start
+        name = self.advance().value if self.cur.kind in ("NAME", "KW") else "?"
+        node = A.ApiDecl(start=start, name=name)
+        if self.at_soft("from"):
+            self.advance()
+            node.from_expr = self.parse_expr()
+
+        def item():
+            if self.at("NAME") and self.cur.value in _METHODS:
+                return self.parse_endpoint()
+            return self.parse_directive()
+
+        for r in self.parse_block(item):
+            if isinstance(r, A.Endpoint):
+                node.endpoints.append(r)
+            elif r is not None:
+                node.settings.append(r)
+        node.end = self.cur.end
+        return node
+
+    def parse_endpoint(self) -> A.Endpoint:
+        start = self.cur.start
+        method = self.advance().value
+        name = self.advance().value if self.at("NAME") else "?"
+        ep = A.Endpoint(start=start, method=method, name=name)
+        self.expect_op("(")
+        ep.params = self._param_list_until(")")
+        self.expect_op(")")
+        if not self._at_line_end():
+            ep.ret = self.parse_type_ref()
+        self.skip_newlines()
+        if self.at("INDENT"):
+            ep.settings = self.parse_block(self.parse_directive)
+        else:
+            self._end_line()
+        ep.end = self.cur.end
+        return ep
+
+    def parse_service_decl(self) -> A.ServiceDecl:
+        start = self.advance().start
+        name = self.advance().value if self.cur.kind in ("NAME", "KW") else "?"
+        node = A.ServiceDecl(start=start, name=name)
+        if self.at_soft("public"):
+            self.advance()
+            node.is_public = True
+
+        def item():
+            if self.at("NAME") and self.cur.value in _METHODS:
+                return self.parse_route()
+            return self.parse_directive()
+
+        for r in self.parse_block(item):
+            if isinstance(r, A.Route):
+                node.routes.append(r)
+            elif r is not None:
+                node.settings.append(r)
+        node.end = self.cur.end
+        return node
+
+    def parse_route(self) -> A.Route:
+        start = self.cur.start
+        method = self.advance().value
+        parts: list[str] = []
+        while self.at_op("/"):
+            parts.append(self.advance().value)          # '/'
+            if self.at_op(":"):
+                parts.append(self.advance().value)      # ':'
+            if self.at("NAME"):
+                parts.append(self.advance().value)      # segment name
+        rt = A.Route(start=start, method=method, path="".join(parts))
+        if self.at_op("("):
+            self.advance()
+            rt.params = self._param_list_until(")")
+            self.expect_op(")")
+        if not self._at_line_end() and not self.at_kw("as"):
+            rt.ret = self.parse_type_ref()
+        if self.at_kw("as"):
+            self.advance()
+            if self.cur.kind in ("NAME", "TYPENAME"):
+                rt.alias = self.advance().value
+        # end the header line, then look for an optional indented body. A bodyless
+        # route (`get /posts/:id Post!`) is valid and may be followed by a sibling.
+        if self.at("NEWLINE"):
+            self.advance()
+        elif not self.at("INDENT") and self.cur.kind not in ("DEDENT", "EOF"):
+            self.error(f"expected end of line, found {self._desc(self.cur)}", self.cur)
+            self._recover_to_line()
+        self.skip_newlines()
+        if self.at("INDENT"):
+            self.advance()
+            body = []
+            while not self.at("DEDENT") and not self.at("EOF"):
+                self.skip_newlines()
+                if self.at("DEDENT"):
+                    break
+                if self.at_kw("auth"):
+                    rt.guard = self.parse_guard()
+                else:
+                    before = self.pos
+                    body.append(self.parse_stmt())
+                    if self.pos == before:
+                        self._recover_to_line()
+                self.skip_newlines()
+            if self.at("DEDENT"):
+                self.advance()
+            rt.body = body
+        rt.end = self.cur.end
+        return rt
+
+    def parse_guard(self) -> A.Guard:
+        start = self.advance().start   # 'auth'
+        g = A.Guard(start=start)
+        # The natural spelling for the open §20.8 gap is otherwise especially
+        # unhelpful: `auth role:admin or owner:...` falls through into an
+        # ordinary end-of-line parse error. Recognise the attempted composition
+        # before parsing either side and turn it into a repair instruction.
+        line = []
+        i = self.pos
+        while i < len(self.toks) and self.toks[i].kind not in ("NEWLINE", "DEDENT", "EOF"):
+            line.append(self.toks[i])
+            i += 1
+        joiner = next((t for t in line if t.kind == "KW" and t.value in ("or", "and")), None)
+        if joiner is not None and any(t.value in ("role", "owner") for t in line):
+            self.error(
+                "authorization guards do not compose in Volaro v0.2 (§20.8)",
+                joiner,
+                code="E-AUTH-COMPOSE",
+                fix=("use `auth required`, perform the combined check in the handler, "
+                     "and mark it `# LANGUAGE GAP (§20.8)`; do not present the "
+                     "workaround as idiomatic Volaro"),
+            )
+            g.kind = "compose"
+            self._recover_to_line()
+            g.end = self.cur.end
+            return g
+        if self.at("NAME") and self.cur.value in ("required", "optional", "none"):
+            g.kind = self.advance().value
+        elif self.at_soft("role"):
+            self.advance()
+            g.kind = "role"
+            if self.at_op(":"):
+                self.advance()
+                g.detail = self._role_list()
+        elif self.at_soft("owner"):
+            self.advance()
+            g.kind = "owner"
+            if self.at_op(":"):
+                self.advance()
+                g.detail = self.parse_expr()
+        else:
+            g.kind = self.advance().value if self.cur.kind in ("NAME", "KW") else "?"
+        g.end = self.cur.end
+        self._end_line()
+        return g
+
+    def _role_list(self) -> list:
+        roles: list[str] = []
+        if self.at_op("["):
+            self.advance()
+            while not self.at_op("]") and not self.at("EOF"):
+                if self.cur.kind in ("NAME", "KW"):
+                    roles.append(self.advance().value)
+                if self.at_op(","):
+                    self.advance()
+                else:
+                    break
+            self.expect_op("]")
+        elif self.cur.kind in ("NAME", "KW"):
+            roles.append(self.advance().value)
+        return roles
+
+    def parse_auth_decl(self) -> A.AuthDecl:
+        start = self.advance().start
+        node = A.AuthDecl(start=start)
+        node.settings = self.parse_block(self.parse_directive)
+        node.end = self.cur.end
+        return node
+
+    def parse_theme_decl(self) -> A.Directive:
+        start = self.advance().start
+        node = A.Directive(start=start, head="theme")
+        node.body = self.parse_block(self.parse_directive)
+        node.end = self.cur.end
+        return node
+
+    def parse_recipe_decl(self) -> A.RecipeDecl:
+        start = self.advance().start
+        primitive = (self.advance().value
+                     if self.cur.kind in ("NAME", "KW") else "?")
+        node = A.RecipeDecl(start=start, primitive=primitive)
+        node.body = self.parse_block(self.parse_directive)
+        node.end = self.cur.end
+        return node
+
+    def parse_page_decl(self) -> A.PageDecl:
+        start = self.advance().start          # 'page'
+        node = A.PageDecl(start=start)
+        # inline `name:<expr>` attributes on the same line, element-style
+        while not self._at_line_end():
+            if (self.cur.kind in ("NAME", "KW") and self.peek(1).kind == "OP"
+                    and self.peek(1).value == ":"):
+                an = self.advance().value
+                self.advance()               # ':'
+                node.attrs.append((an, self.parse_expr()))
+                continue
+            self.error("`page` takes `name:<expr>` settings (e.g. `page "
+                       "title:\"…\"`)", self.cur)
+            self._recover_to_line()
+            break
+        node.end = self.cur.end
+        if self.at("NEWLINE"):
+            self.advance()
+        return node
+
+    def parse_directive(self):
+        if self.cur.kind in ("DEDENT", "EOF"):
+            return None
+        start = self.cur.start
+        head = self.cur.value if self.cur.kind in ("NAME", "KW", "TYPENAME") else self._desc(self.cur)
+        toks: list[str] = []
+        while not self.at("NEWLINE") and self.cur.kind not in ("DEDENT", "EOF"):
+            toks.append(self.cur.value)
+            self.advance()
+        node = A.Directive(start=start, end=self.cur.end, head=head, tokens=toks)
+        self.skip_newlines()
+        if self.at("INDENT"):
+            node.body = self.parse_block(self.parse_directive)
+        return node
+
+    # -- statements ----------------------------------------------------
+    def parse_stmt(self):
+        t = self.cur
+        if self.at_kw("let"):
+            return self.parse_let()
+        if self.at_kw("if"):
+            return self.parse_if(self.parse_stmt)
+        if self.at_kw("match"):
+            return self.parse_match_stmt(self.parse_stmt)
+        if self.at_kw("for"):
+            return self.parse_for()
+        if self.at_kw("while"):
+            return self.parse_while()
+        if self.at_kw("par"):
+            return self.parse_par()
+        if self.at_kw("spawn"):
+            return self.parse_spawn()
+        if self.at_kw("try"):
+            return self.parse_try()
+        if self.at_kw("return"):
+            self.advance()
+            val = None if self._at_line_end() else self.parse_expr()
+            self._end_line()
+            return A.Return(start=t.start, value=val)
+        if self.at_kw("break"):
+            self.advance()
+            self._end_line()
+            return A.Break(start=t.start)
+        if self.at_kw("skip"):
+            self.advance()
+            self._end_line()
+            return A.Skip(start=t.start)
+
+        expr = self.parse_expr()
+        if self.at_op(*_ASSIGN_OPS):
+            op = self.advance().value
+            val = self.parse_expr()
+            if not self._closure_block_body(val):
+                self._end_line()
+            return A.Assign(start=t.start, target=expr, op=op, value=val)
+        if not self._closure_block_body(expr):
+            self._end_line()
+        return A.ExprStmt(start=t.start, expr=expr)
+
+    @staticmethod
+    def _closure_block_body(node) -> bool:
+        """True when `node` is a closure whose body is a statement block that
+        has already been fully parsed through its own terminator (a DEDENT
+        via `parse_block`, or the bracket-tracked end of
+        `_parse_bracketed_closure_body`) — so the caller must NOT also call
+        `_end_line()` for it: there is no pending NEWLINE/DEDENT left to
+        consume, only the next statement (B3 in the callback-props
+        decision — `let x = fn(...)\\n  <block>` followed by a sibling
+        statement broke here before this check existed)."""
+        return isinstance(node, A.Closure) and isinstance(node.body, list)
+
+    def parse_let(self) -> A.Let:
+        start = self.advance().start
+        mut = False
+        if self.at_kw("mut"):
+            self.advance()
+            mut = True
+        name = self.advance().value if self.at("NAME") else "?"
+        node = A.Let(start=start, name=name, mut=mut)
+        if not self.at_op("="):
+            node.type = self.parse_type_ref()
+        self.expect_op("=")
+        # `let x = try EXPR \n catch pat block(stmt)` (spec section 6.2,
+        # expression position) -- `try` is not an ordinary expression prefix
+        # (parse_expr doesn't know it), so it's special-cased here the same
+        # way parse_stmt special-cases the statement form. Reuses parse_try
+        # verbatim: the AST shape (A.Try: expr + catches) is identical either
+        # way: emit.py tells them apart by where the A.Try node ends up.
+        if self.at_kw("try"):
+            node.init = self.parse_try()
+            node.end = self.cur.end
+            return node
+        node.init = self.parse_expr()
+        if (node.type is None and isinstance(node.init, (A.ListLit, A.RecordLit))
+                and getattr(node.init, "empty", False)):
+            node.empty_literal_no_type = True
+        if self._closure_block_body(node.init):
+            node.end = node.init.end
+            return node
+        self._end_line()
+        node.end = self.cur.end
+        return node
+
+    def parse_if(self, sub) -> A.If:
+        start = self.advance().start
+        cond = self.parse_expr()
+        node = A.If(start=start, cond=cond)
+        node.then = self.parse_block(sub)
+        while (self.at_kw("else") and self.peek(1).kind == "KW" and self.peek(1).value == "if"):
+            self.advance()
+            self.advance()
+            c = self.parse_expr()
+            node.elifs.append((c, self.parse_block(sub)))
+        if self.at_kw("else"):
+            self.advance()
+            node.has_else = True
+            node.orelse = self.parse_block(sub)
+        node.end = self.cur.end
+        return node
+
+    def parse_match_stmt(self, sub) -> A.Match:
+        start = self.advance().start
+        node = A.Match(start=start, subject=self.parse_expr())
+        self.skip_newlines()
+        if not self.at("INDENT"):
+            self.error("expected indented match arms", self.cur)
+            return node
+        self.advance()
+        while not self.at("DEDENT") and not self.at("EOF"):
+            self.skip_newlines()
+            if self.at("DEDENT"):
+                break
+            arm = self._match_arm(sub)
+            if arm is not None:
+                node.arms.append(arm)
+            self.skip_newlines()
+        if self.at("DEDENT"):
+            self.advance()
+        node.end = self.cur.end
+        return node
+
+    def _match_arm(self, sub):
+        before = self.pos
+        pat = self.parse_pattern()
+        guard = None
+        if self.at_kw("if"):
+            self.advance()
+            guard = self.parse_expr()
+        if self.at_op("->"):
+            self.advance()
+        else:
+            self.error(f"expected '->' in match arm, found {self._desc(self.cur)}", self.cur)
+        if self.at("NEWLINE"):
+            body = self.parse_block(sub)
+        else:
+            body = [A.ExprStmt(expr=self.parse_expr())]
+            self._end_line()
+        if self.pos == before:
+            self.advance()
+        return (pat, guard, body)
+
+    def parse_for(self) -> A.For:
+        start = self.advance().start
+        node = A.For(start=start)
+        if self.at("NAME"):
+            node.vars.append(self.advance().value)
+        if self.at_op(","):
+            self.advance()
+            if self.at("NAME"):
+                node.vars.append(self.advance().value)
+        if self.at_kw("in"):
+            self.advance()
+        else:
+            self.error("expected 'in' in for loop", self.cur)
+        node.iter = self.parse_expr()
+        node.body = self.parse_block(self.parse_stmt)
+        node.end = self.cur.end
+        return node
+
+    def parse_while(self) -> A.While:
+        start = self.advance().start
+        node = A.While(start=start, cond=self.parse_expr())
+        node.body = self.parse_block(self.parse_stmt)
+        node.end = self.cur.end
+        return node
+
+    def parse_par(self) -> A.Par:
+        start = self.advance().start
+        node = A.Par(start=start)
+        node.lets = self.parse_block(self.parse_stmt)
+        node.end = self.cur.end
+        return node
+
+    def parse_spawn(self) -> A.Spawn:
+        start = self.advance().start
+        node = A.Spawn(start=start)
+        node.body = self.parse_block(self.parse_stmt)
+        node.end = self.cur.end
+        return node
+
+    def parse_try(self) -> A.Try:
+        start = self.advance().start          # 'try'
+        if self._at_line_end():
+            # `try` with nothing else on its line -- e.g. `try` followed by
+            # an indented block of statements, treating it as a general
+            # block the way `try { ... }` works in other languages. Volaro's
+            # `try` wraps exactly one fallible EXPRESSION on its own line;
+            # it is not a block construct. Name the actual mistake instead
+            # of letting the indented block that follows cascade into
+            # unrelated "expected end of line" / "unexpected dedent" noise.
+            self.error(
+                "`try` needs its fallible expression on the SAME line -- "
+                "`try EXPR`, with `catch` starting its own dedented line "
+                "after it. `try` is not a block and cannot wrap multiple "
+                "statements the way `try { ... }` does in other languages",
+                self.cur, fix="try some_call(...)\ncatch e\n  fallback_value")
+            self._skip_block_for_recovery()
+            node = A.Try(start=start,
+                        expr=A.Literal(start=start, end=self.cur.end, kind="nil", raw="nil"))
+            node.end = self.cur.end
+            return node
+        node = A.Try(start=start, expr=self.parse_expr())
+        if self.at_kw("catch"):
+            # `catch` right after the expression, on the SAME line -- e.g.
+            # `let r = try f() catch e fallback`. `catch` must start its own
+            # line, dedented to align with `try` (or the `let` it's part
+            # of). Named directly instead of the generic "expected end of
+            # line" this would otherwise produce.
+            self.error(
+                "`catch` must start its own line, dedented to align with "
+                "`try` -- `try EXPR catch ...` all on one line is not valid",
+                self.cur, fix="try f()\ncatch e\n  fallback_value")
+            self._recover_to_line()
+        else:
+            self._end_line()
+        self.skip_newlines()
+        while self.at_kw("catch"):
+            self.advance()
+            pat = self.parse_pattern()
+            body = self.parse_block(self.parse_stmt)
+            node.catches.append((pat, body))
+            self.skip_newlines()
+        node.end = self.cur.end
+        return node
+
+    def _skip_block_for_recovery(self) -> None:
+        """Best-effort error recovery: consume an entire INDENT...DEDENT
+        block without building AST for it, so one malformed `try` (used as
+        a block) doesn't cascade into a wall of unrelated follow-on parse
+        errors on every statement inside it."""
+        self.skip_newlines()
+        if not self.at("INDENT"):
+            return
+        depth = 0
+        while self.cur.kind != "EOF":
+            if self.at("INDENT"):
+                depth += 1
+            elif self.at("DEDENT"):
+                depth -= 1
+                if depth == 0:
+                    self.advance()
+                    return
+            self.advance()
+
+    def parse_pattern(self) -> A.Pattern:
+        start = self.cur.start
+        binds: list[str] = []
+        head = ""
+
+        def ctor_args():
+            self.advance()  # (
+            while not self.at_op(")") and not self.at("EOF"):
+                if self.at("NAME"):
+                    binds.append(self.advance().value)
+                else:
+                    self.advance()
+                if self.at_op(","):
+                    self.advance()
+                else:
+                    break
+            self.expect_op(")")
+
+        if self.at("NAME") and self.cur.value == "_":
+            self.advance()
+            head = "_"
+        elif self.at_op("_"):
+            self.advance()
+            head = "_"
+        elif self.at("NAME"):
+            nm = self.advance().value
+            head = nm
+            if self.at_op("("):
+                ctor_args()
+            else:
+                binds.append(nm)
+        elif self.at("TYPENAME"):
+            head = self.cur.value
+            self.advance()
+            if self.at_op("("):
+                ctor_args()
+            elif self.at_op("{"):
+                self.advance()
+                while not self.at_op("}") and not self.at("EOF"):
+                    if self.at("NAME"):
+                        fn = self.advance().value
+                        if self.at_op(":"):
+                            self.advance()
+                            if self.at("NAME"):
+                                binds.append(self.advance().value)
+                            else:
+                                self.parse_expr()
+                        else:
+                            binds.append(fn)
+                    if self.at_op(","):
+                        self.advance()
+                    else:
+                        break
+                self.expect_op("}")
+        elif self.cur.kind in ("INT", "FLOAT", "STRING", "BOOL", "NIL", "DURATION"):
+            self.advance()
+            if self.at_op("..", "..="):
+                self.advance()
+                if self.cur.kind in ("INT", "FLOAT", "STRING", "DURATION"):
+                    self.advance()
+        elif self.at_op("["):
+            self.advance()
+            while not self.at_op("]") and not self.at("EOF"):
+                if self.at("NAME"):
+                    binds.append(self.advance().value)
+                else:
+                    self.advance()
+                if self.at_op(","):
+                    self.advance()
+                else:
+                    break
+            self.expect_op("]")
+        else:
+            self.advance()
+
+        return A.Pattern(start=start, end=self.cur.end, binds=binds, head=head)
+
+    # -- expressions (Pratt) ---------------------------------------------
+    def parse_expr(self, min_bp: int = 0):
+        left = self._parse_prefix()
+        while True:
+            op = self._peek_binop()
+            if op is None:
+                break
+            text, lbp, rbp = op
+            if lbp < min_bp:
+                break
+            self.advance()
+            if text in ("..", "..="):
+                right = self.parse_expr(rbp)
+                left = A.Range(start=getattr(left, "start", 0), end=getattr(right, "end", 0),
+                               lo=left, hi=right, inclusive=(text == "..="))
+                continue
+            right = self.parse_expr(rbp)
+            node = A.Binary(start=getattr(left, "start", 0), end=getattr(right, "end", 0),
+                            op=text, left=left, right=right)
+            if text in _CMP:
+                nxt = self._peek_binop()
+                inner = right.op if isinstance(right, A.Binary) else None
+                if (nxt and nxt[0] in _CMP) or (inner in _CMP):
+                    self.diags.append(Diagnostic(
+                        "E-CHAIN-CMP", Severity.ERROR,
+                        "comparison operators do not chain",
+                        node.start, node.end,
+                        "split into two comparisons joined by 'and'", self.filename))
+            left = node
+        return left
+
+    def _peek_binop(self):
+        t = self.cur
+        if t.kind == "OP" and t.value in _BINOPS:
+            lbp, rbp = _BINOPS[t.value]
+            return (t.value, lbp, rbp)
+        if t.kind == "KW" and t.value in ("and", "or"):
+            lbp, rbp = _BINOPS[t.value]
+            return (t.value, lbp, rbp)
+        return None
+
+    def _parse_prefix(self):
+        t = self.cur
+        if self.at_kw("not"):
+            self.advance()
+            operand = self.parse_expr(_PREFIX_BP)
+            return A.Unary(start=t.start, end=getattr(operand, "end", t.end), op="not", operand=operand)
+        if self.at_op("-"):
+            self.advance()
+            operand = self.parse_expr(_PREFIX_BP)
+            return A.Unary(start=t.start, end=getattr(operand, "end", t.end), op="-", operand=operand)
+        return self._parse_postfix(self._parse_primary())
+
+    def _parse_postfix(self, node):
+        while True:
+            if self.at_op("."):
+                self.advance()
+                nm = self.advance().value if self.cur.kind in ("NAME", "TYPENAME", "KW") else "?"
+                node = A.Member(start=getattr(node, "start", 0), end=self.cur.end, obj=node, name=nm)
+            elif self.at_op("("):
+                # In `if (condition) (then_expr) else other`, the closing
+                # condition parenthesis is a boundary, not a callable value.
+                if self.pos in getattr(self, "_if_condition_ends", ()):
+                    break
+                self.advance()
+                args, named = [], []
+                self.skip_newlines()          # arguments may span lines inside ( )
+                while not self.at_op(")") and not self.at("EOF"):
+                    if self.at("NAME") and self.peek(1).kind == "OP" and self.peek(1).value == ":":
+                        an = self.advance().value
+                        self.advance()
+                        named.append((an, self.parse_expr()))
+                    else:
+                        args.append(self.parse_expr())
+                    had_nl = self.at("NEWLINE") or self._take_closure_ate_sep()
+                    self.skip_newlines()
+                    if self.at_op(","):
+                        self.advance()
+                        self.skip_newlines()
+                    elif not had_nl and not self.at_op(")"):
+                        break                 # spec 3.7: a bare newline also separates args
+                self.expect_op(")")
+                node = A.Call(start=getattr(node, "start", 0), end=self.cur.end,
+                              callee=node, args=args, named=named)
+            elif self.at_op("["):
+                self.advance()
+                idx = self.parse_expr()
+                self.expect_op("]")
+                node = A.Index(start=getattr(node, "start", 0), end=self.cur.end, obj=node, index=idx)
+            elif self.at_op("?"):
+                self.advance()
+                node = A.TryOp(start=getattr(node, "start", 0), end=self.cur.end, operand=node)
+            else:
+                break
+        return node
+
+    def _parse_primary(self):
+        t = self.cur
+        if t.kind == "INT":
+            self.advance()
+            return A.Literal(start=t.start, end=t.end, kind="int", raw=t.value)
+        if t.kind == "FLOAT":
+            self.advance()
+            return A.Literal(start=t.start, end=t.end, kind="float", raw=t.value)
+        if t.kind == "DURATION":
+            self.advance()
+            return A.Literal(start=t.start, end=t.end, kind="duration", raw=t.value)
+        if t.kind == "BOOL":
+            self.advance()
+            return A.Literal(start=t.start, end=t.end, kind="bool", raw=t.value)
+        if t.kind == "NIL":
+            self.advance()
+            return A.Literal(start=t.start, end=t.end, kind="nil", raw="nil")
+        if t.kind == "STRING":
+            self.advance()
+            lit = A.Literal(start=t.start, end=t.end, kind="str", raw=t.value)
+            lit.interp_names = self._interp_names(t)
+            return lit
+        if self.at_kw("if"):
+            return self._parse_if_expr()
+        if self.at_kw("match"):
+            return self.parse_match_expr()
+        if self.at_kw("fn"):
+            return self._parse_closure()
+        if self.at_op("("):
+            self.advance()
+            e = self.parse_expr()
+            self.expect_op(")")
+            return e
+        if self.at_op("["):
+            return self._parse_list_lit()
+        if self.at_op("{"):
+            return self._parse_record_lit(None)
+        if t.kind == "TYPENAME":
+            self.advance()
+            if self.at_op("{"):
+                return self._parse_record_lit(t.value)
+            return A.Name(start=t.start, end=t.end, id=t.value)
+        # `err` and `auth` are reserved but read as values here; `api` / `session`
+        # are contextual and already arrive as NAME tokens.
+        if t.kind in ("NAME", "PRIM") or self.at_kw("err", "auth"):
+            self.advance()
+            return A.Name(start=t.start, end=t.end, id=t.value)
+        self.error(f"expected an expression, found {self._desc(t)}", t)
+        self.advance()
+        return A.Name(start=t.start, end=t.end, id="?")
+
+    def _parse_if_expr(self) -> A.IfExpr:
+        start = self.advance().start
+        boundary = None
+        if self.at_op("("):
+            depth = 0
+            for i in range(self.pos, len(self.toks)):
+                t = self.toks[i]
+                if t.kind == "OP" and t.value == "(":
+                    depth += 1
+                elif t.kind == "OP" and t.value == ")":
+                    depth -= 1
+                    if depth == 0:
+                        boundary = i + 1
+                        break
+        previous = getattr(self, "_if_condition_ends", set())
+        self._if_condition_ends = previous | ({boundary} if boundary is not None else set())
+        try:
+            cond = self.parse_expr()
+        finally:
+            self._if_condition_ends = previous
+        node = A.IfExpr(start=start, cond=cond, then=self.parse_expr())
+        if self.at_kw("else"):
+            self.advance()
+            node.orelse = self.parse_expr()
+            node.has_else = True
+        else:
+            self.diags.append(Diagnostic(
+                "E-IF-EXPR-ELSE", Severity.ERROR,
+                "an `if` expression is `if <cond> <then> else <else>` -- `else` "
+                "is required, each branch is one expression, and it is binary "
+                "(nest for 3+, no `else if` / `match`). If this looks complete, "
+                "a `(` right after a value was read as a call -- wrap the "
+                "condition: `if (cond) a else b`.",
+                start, self.cur.end,
+                "if (cond) a else b   # binary; nest for more cases",
+                self.filename))
+        node.end = self.cur.end
+        return node
+
+    def parse_match_expr(self) -> A.MatchExpr:
+        start = self.advance().start
+        node = A.MatchExpr(start=start, subject=self.parse_expr())
+        self.skip_newlines()
+        if self.at("INDENT"):
+            self.advance()
+            while not self.at("DEDENT") and not self.at("EOF"):
+                self.skip_newlines()
+                if self.at("DEDENT"):
+                    break
+                arm = self._match_arm(self.parse_stmt)
+                if arm is not None:
+                    node.arms.append(arm)
+                self.skip_newlines()
+            if self.at("DEDENT"):
+                self.advance()
+        node.end = self.cur.end
+        return node
+
+    def _parse_closure(self) -> A.Closure:
+        start = self.advance().start   # 'fn'
+        self.expect_op("(")
+        params = self._param_list_until(")")
+        self.expect_op(")")
+        node = A.Closure(start=start, params=params)
+        if self.cur.kind in ("TYPENAME", "PRIM") and self.peek(1).kind == "NEWLINE":
+            node.ret = self.parse_type_ref()
+        if self.at("NEWLINE"):
+            self.skip_newlines()
+            if self.at("INDENT"):
+                node.body = self.parse_block(self.parse_stmt)
+            elif self.bracket_depth > 0:
+                # A block-bodied closure written as a call argument (e.g. a
+                # callback prop's closure at its most natural call site,
+                # `Child(onPick: fn(item)\n  selected = item.id)`): the lexer
+                # suppresses INDENT/DEDENT inside any open bracket (spec 3.7
+                # keeps NEWLINE as the item separator there), so there is no
+                # INDENT token to find the block by. Track it by source
+                # column instead, entirely inside the parser.
+                node.body = self._parse_bracketed_closure_body()
+            node.end = self.cur.end
+            return node
+        node.body = self.parse_expr()
+        node.end = getattr(node.body, "end", self.cur.end)
+        return node
+
+    def _col(self, tok: Token) -> int:
+        """0-based column of `tok` on its own source line."""
+        return tok.start - (self.src.rfind("\n", 0, tok.start) + 1)
+
+    def _parse_bracketed_closure_body(self) -> list:
+        """The statement-block form of `_parse_closure`, for when it is
+        reached inside an open bracket (see the call site). `parse_block`
+        can't be reused here — it waits for a DEDENT token, which the lexer
+        never produces while any bracket is open — so this parses statements
+        directly and decides where the block ends by comparing each
+        statement's column to the first one's, stopping at a shallower
+        column or at whatever closes/continues the enclosing bracket
+        (`)` / `]` / `}` / `,`) — the same tokens `_end_line`'s matching
+        tolerance (above) lets each statement end on."""
+        self.skip_newlines()
+        if self.cur.kind in ("DEDENT", "EOF") or self.at_op(")", "]", "}", ","):
+            return []
+        body_col = self._col(self.cur)
+        stmts: list = []
+        while True:
+            before = self.pos
+            stmts.append(self.parse_stmt())
+            if self.pos == before:
+                self.advance()
+                break
+            self.skip_newlines()
+            if self.cur.kind in ("DEDENT", "EOF") or self.at_op(")", "]", "}", ","):
+                break
+            if self._col(self.cur) != body_col:
+                # A sibling at a shallower column follows (e.g. the next
+                # named call argument) -- the block ends here. Getting here
+                # required a real NEWLINE, already consumed inside the last
+                # statement's own `_end_line()`; tell the call-argument loop
+                # that resumes once `_parse_closure` returns, since it can no
+                # longer see that token to know a separator occurred.
+                self._closure_ate_sep = True
+                break
+        return stmts
+
+    def _parse_list_lit(self) -> A.ListLit:
+        start = self.advance().start   # [
+        node = A.ListLit(start=start)
+        self.skip_newlines()           # spec 3.7: a literal may open onto its own lines
+        while not self.at_op("]") and not self.at("EOF"):
+            before = self.pos
+            node.items.append(self.parse_expr())
+            # This loop has no separator-required break (unlike a call's
+            # argument list), so it needs no `_closure_ate_sep` reading --
+            # but drain it regardless, so a block-bodied closure item here
+            # can never leave a stale flag for some later, unrelated call's
+            # argument loop to misread.
+            self._closure_ate_sep = False
+            if self.at_op(","):
+                comma = self.advance()
+                self.skip_newlines()   # `,` then a newline before the next item / `]`
+                if self.at_op("]"):
+                    self.diags.append(Diagnostic(
+                        "E-TRAILING-COMMA", Severity.ERROR,
+                        "trailing commas are not allowed",
+                        comma.start, comma.end, "remove the trailing comma", self.filename))
+            else:
+                self.skip_newlines()   # spec 3.7: a newline separates items in block position
+            if self.pos == before:
+                self.advance()
+        self.expect_op("]")
+        node.empty = not node.items
+        node.end = self.cur.end
+        return node
+
+    def _parse_record_lit(self, type_name) -> A.RecordLit:
+        start = self.cur.start
+        self.expect_op("{")
+        node = A.RecordLit(start=start, type_name=type_name)
+        self.skip_newlines()           # spec 3.7: a literal may open onto its own lines
+        while not self.at_op("}") and not self.at("EOF"):
+            before = self.pos
+            if self.at("NAME") and self.peek(1).kind == "OP" and self.peek(1).value == ":":
+                fn = self.advance().value
+                self.advance()
+                node.fields.append((fn, self.parse_expr()))
+            else:
+                key = self.parse_expr()
+                if self.at_op(":"):
+                    self.advance()
+                    node.fields.append((None, self.parse_expr()))
+                else:
+                    node.fields.append((None, key))
+            self._closure_ate_sep = False   # see the matching drain in _parse_list_lit
+            if self.at_op(","):
+                comma = self.advance()
+                self.skip_newlines()   # `,` then a newline before the next field / `}`
+                if self.at_op("}"):
+                    self.diags.append(Diagnostic(
+                        "E-TRAILING-COMMA", Severity.ERROR,
+                        "trailing commas are not allowed",
+                        comma.start, comma.end, "remove the trailing comma", self.filename))
+            else:
+                self.skip_newlines()   # spec 3.7: a newline separates fields in block position
+            if self.pos == before:
+                self.advance()
+        self.expect_op("}")
+        node.empty = not node.fields
+        node.end = self.cur.end
+        return node
+
+    def _interp_names(self, tok: Token) -> list:
+        out: list[str] = []
+        for (s, e) in getattr(tok, "interps", []):
+            frag = self.src[s:e]
+            for m in _IDENT_RE.finditer(frag):
+                out.append(m.group(1))
+        return out
+
+
+def parse(tokens: list[Token], src: str, filename: str = "<input>"):
+    p = Parser(tokens, src, filename)
+    return p.parse_module(), p.diags