compiler 0.0.2-preview.1

The Zena self-hosted compiler

Readme Files Dependencies Versions

compiler#

The Zena compiler, written in Zena. It parses, type-checks, and compiles Zena source code to WebAssembly (Wasm GC) and WebAssembly Text (WAT).

Usage#

Parsing a Single File#

Use compiler/parser to parse Zena source text into an AST (Module):

import { parse } from 'compiler/parser';

let ast = parse('export let answer = 42;', 'example.zena');

Loading and Checking a Program#

Use compiler (createCompiler and checkCompilation) with a CompilerHost to resolve imports across a module graph and type-check a program:

import {
  createCompiler, checkCompilation, buildStdlibConfig
} from 'compiler';
import { FsCompilerHost } from 'compiler/fs-host';

let stdlibRoot = '/stdlib';
let host = new FsCompilerHost(stdlibRoot);
let packages = buildStdlibConfig(stdlibRoot, 'host');
let compiler = createCompiler(host, {
  stdlibRoot,
  packages,
});

let result = await compiler.compile({
  entry: '/workspace/main.zena',
  target: 'host',
});
let checked = checkCompilation(result);

Compiling a File to WebAssembly#

Use compiler/compile-file to compile an entry file on disk to a .wasm or .wat output file:

import { compileFile } from 'compiler/compile-file';

let ok = await compileFile({
  entry: 'src/main.zena',
  outPath: 'out/main.wasm',
  stdlibRoot: '/stdlib',
});

Libraries#

  • compiler / compiler/compiler — compiler entry point (Compiler, createCompiler, checkCompilation, ProgramCheckResult)
  • compiler/compile-file — end-to-end file compilation (compileFile, CompileFileOptions)
  • compiler/tokenizer — lexer and token definitions (tokenize, Token, TokenType)
  • compiler/parser — recursive-descent parser (parse, Parser)
  • compiler/ast — AST node definitions (Node, Module, Statement, Expression, TypeAnnotation)
  • compiler/visitor — AST traversal helpers (walk, Visitor)
  • compiler/scope — lexical scope and symbol resolution (ScopeBuilder, ScopeResult, Symbol)
  • compiler/checker — static type checker (checkModule, CheckResult)
  • compiler/semantic-model — semantic queries over a checked module (SemanticModel)
  • compiler/types — compiler type representations (Type, ClassType, FunctionType, typeToString)
  • compiler/diagnostics — compiler diagnostics and source spans (Diagnostic, DiagnosticCode, DiagnosticSeverity, SourceSpan)
  • compiler/package-manifest — zena-package.json manifest and workspace loader (loadWorkspace, loadPackageMap)
  • compiler/module-resolver — package and relative module specifier resolution (ModuleResolver, PackageConfig)
  • compiler/library-loader — module graph loader (LibraryLoader, CompilerHost, SourceFile)
  • compiler/codegen/binary-generator — WebAssembly GC binary emitter (BinaryGenerator)
  • compiler/codegen/wat-generator — WebAssembly Text (WAT) emitter (WatGenerator)

License#

MIT

193.5 KiB Raw
import { StringTable, growable } from 'zena:core';
import { Token, TokenType, Tokenizer } from './tokenizer.zena';
import { Diagnostic, DiagnosticCode, DiagnosticSeverity, SourceSpan, SyntaxError } from './diagnostics.zena';
import { walkEnter } from './visitor.zena';
import { registerSource } from './line-index.zena';
import { 
  SourceLocation,
  Comment,
  Node,
  IdGenerator,
  NodeId,
  makeNodeIdGenerator,
  NodeId,
  Module,
  Statement,
  Expression,
  Pattern,
  TypeAnnotation,
  Identifier,
  IdentifierPattern,
  BindingPattern,
  NumberLiteral,
  StringLiteral,
  BooleanLiteral,
  NullLiteral,
  BinaryExpression,
  UnaryExpression,
  AssignmentExpression,
  VariableDeclaration,
  UsingStatement,
  ShieldedStatement,
  FunctionDeclaration,
  ExpressionStatement,
  BlockStatement,
  ReturnStatement,
  YieldStatement,
  AwaitExpression,
  BreakStatement,
  ContinueStatement,
  IfStatement,
  WhileStatement,
  ForStatement,
  ForInStatement,
  LetPatternCondition,
  NamedTypeAnnotation,
  UnionTypeAnnotation,
  NullableTypeAnnotation,
  FunctionTypeAnnotation,
  LiteralTypeAnnotation,
  RecordTypeAnnotation,
  TupleTypeAnnotation,
  InlineTypeAnnotation,
  ThisTypeAnnotation,
  PropertySignature,
  TypeParameter,
  Parameter,
  FunctionExpression,
  CallExpression,
  MemberExpression,
  IndexExpression,
  ThisExpression,
  ArrayLiteral,
  PropertyAssignment,
  SpreadElement,
  RecordLiteral,
  MapEntry,
  MapLiteral,
  TupleLiteral,
  RecordPattern,
  BindingProperty,
  TuplePattern,
  ArrayPattern,
  RestPattern,
  AsPattern,
  ClassPattern,
  LogicalPattern,
  AssignmentPattern, AbsencePattern,
  LiteralPattern,
  MatchExpression,
  MatchCase,
  IfExpression,
  CaseClassParam,
  ClassDeclaration,
  FieldDefinition,
  MethodDefinition,
  AccessorDeclaration,
  SetterInfo,
  SuperExpression,
  FieldInitializer,
  SuperInitializer,
  InterfaceDeclaration,
  MixinDeclaration,
  MethodSignature,
  AccessorSignature,
  TemplateElement,
  TemplateLiteral,
  TaggedTemplateExpression,
  AsExpression,
  IsExpression,
  RangeExpression,
  PipelineExpression,
  PipePlaceholder,
  NewExpression,
  ThrowExpression,
  TryExpression,
  CatchClause,
  EnumDeclaration,
  EnumMember,
  SealedVariant,
  TypeAliasDeclaration,
  ImportDeclaration,
  ImportSpecifier,
  ExportAllDeclaration,
  ExportFromDeclaration,
  Decorator,
  decoratorStringArg,
  ContractClause,
  ContractKind,
  ContractMode,
  contractKeyword,
  DeclareFunction,
  SymbolDeclaration,
  SymbolPropertyName
} from './ast.zena';

/**
 * How much of the source an AST accounts for. Callers branch on this
 * rather than inferring it from the diagnostic list or from whether the
 * parse threw.
 *
 * Codegen requires `Complete`. Completions, document symbols and hover
 * work on `Recovered`: every node in that AST came from the source, and
 * the stand-ins are the ones the diagnostics point at.
 *
 * Add a third case when the parser first returns from an error it cannot
 * recover from instead of throwing. Callers already branch, so only the
 * parser and this enum change then.
 */
export enum ParseCompleteness {
  /** Nothing was missing. */
  Complete,
  /** Source was missing where the user is still typing, and the AST
   *  holds stand-ins for it. */
  Recovered
}

/**
 * The AST from a recovering parse, what it is fit for, and the errors
 * recovered from along the way.
 */
export type ParseResult = {
  ast: Module,
  completeness: ParseCompleteness,
  diagnostics: GrowableArray<Diagnostic>
};

/**
 * Whether a statement is one of the twelve declarations a module body
 * may hold. A module body runs nothing of its own, so anything else
 * there would never execute. Holding a body to declarations is also
 * what keeps importing a library free of side effects, which is what
 * lets a build drop an unused one. See language-reference.md §8.
 *
 * The checker's `checkTopLevelStatement` matches the same twelve, so a
 * new declaration node belongs in both.
 */
function isModuleDeclaration(stmt: Statement): boolean {
  return match (stmt) {
    case VariableDeclaration {}: true
    case FunctionDeclaration {}: true
    case ClassDeclaration {}: true
    case InterfaceDeclaration {}: true
    case EnumDeclaration {}: true
    case MixinDeclaration {}: true
    case TypeAliasDeclaration {}: true
    case SymbolDeclaration {}: true
    case DeclareFunction {}: true
    case ImportDeclaration {}: true
    case ExportAllDeclaration {}: true
    case ExportFromDeclaration {}: true
    case _: false
  };
}

export final class Parser {
  var #tokens: GrowableArray<Token>;
  var #comments: GrowableArray<Comment>;
  var #current: i32;
  var #extraGreaters: i32;
  var #destructParamCounter: i32;
  var #combinedTypeAnnotation: RecordTypeAnnotation | null;
  #errors: GrowableArray<Diagnostic>;
  var #completeness: ParseCompleteness;
  var #lastErrorOffset: i32;
  #recover: boolean;
  /**
   * Whether a module body may hold statements as well as declarations.
   * Off for the language; on for callers that are handed one statement
   * written at module level and have no use for the rule — the parser
   * tests and the formatter. See `parseAllowingStatements`.
   */
  #allowTopLevelStatements: boolean;
  #source: String;
  #path: String;

  new(source: String, path: String, recover: boolean = false,
      table: StringTable | null = null,
      allowTopLevelStatements: boolean = false)
    : #source = source, #path = path, #recover = recover, #allowTopLevelStatements = allowTopLevelStatements, #tokens = new Array<Token>(0), #comments = new Array<Comment>(0), #current = 0, #extraGreaters = 0, #destructParamCounter = 0, #combinedTypeAnnotation = null, #errors = new Array<Diagnostic>(0), #completeness = ParseCompleteness.Complete, #lastErrorOffset = -1
  {
    let tokenizer = new Tokenizer(source, table);
    this.#tokens = tokenizer.tokenize();
    this.#comments = tokenizer.getComments();
  }

  /**
   * The errors the last `parse()` recovered from, in source order. Only
   * ever populated when the parser was told to recover — otherwise the
   * first one is thrown as it happens, and there is no second.
   */
  recoveredErrors: GrowableArray<Diagnostic> {
    get {
      return this.#errors;
    }
  }

  /** What the AST from the last `parse()` is fit to be used for. */
  completeness: ParseCompleteness {
    get {
      return this.#completeness;
    }
  }

  parse(): Module {
    let body = new Array<Statement>(16);

    // Parse imports at the top of the file
    while (this.#check(TokenType.Import) || this.#check(TokenType.From)) {
      if (this.#check(TokenType.From) && this.#peek2().kind != TokenType.String) {
        break;
      }
      if (this.#recover) {
        let posBefore = this.#current;
        try {
          body.push(this.#parseImportDeclaration());
        } catch (e) {
          this.#recordSyntaxError(e);
          this.#synchronizeTopLevel(posBefore);
        }
        if (this.#current == posBefore && !this.#isAtEnd()) {
          this.#advance();
        }
      } else {
        body.push(this.#parseImportDeclaration());
      }
    }

    while (!this.#isAtEnd()) {
      let startToken = this.#peek();
      if (this.#recover) {
        let posBefore = this.#current;
        try {
          let stmt = this.#parseStatement(true);
          if (!this.#allowTopLevelStatements && !isModuleDeclaration(stmt)) {
            this.#recoverableError(
                "A module body may only contain declarations. Move this statement into a function.",
                DiagnosticCode.StatementOutsideFunction, startToken);
          }
          body.push(stmt);
        } catch (e) {
          this.#recordSyntaxError(e);
          this.#synchronizeTopLevel(posBefore);
        }
        if (this.#current == posBefore && !this.#isAtEnd()) {
          this.#advance();
        }
      } else {
        let stmt = this.#parseStatement(true);
        if (!this.#allowTopLevelStatements && !isModuleDeclaration(stmt)) {
          this.#recoverableError(
              "A module body may only contain declarations. Move this statement into a function.",
              DiagnosticCode.StatementOutsideFunction, startToken);
        }
        body.push(stmt);
      }
    }

    return new Module(body, this.#path, this.#source, this.#comments, null);
  }
  
  // ==========================================================================
  // Import Parsing
  // ==========================================================================
  
  #parseImportDeclaration(): ImportDeclaration {
    let startToken = this.#peek();
    if (this.#match(TokenType.Import)) {
      let imports = if (this.#check(TokenType.Star)) {
        let starToken = this.#advance();
        this.#consume(TokenType.As, "Expected 'as' after '*'.");
        let local = this.#parseIdentifier();
        let imported = new Identifier("*", this.#makeLocation(starToken));
        let arr = growable<ImportSpecifier>([
          new ImportSpecifier(imported, local, this.#makeLocation(starToken)),
        ]);
        arr
      } else {
        this.#parseImportSpecifiers()
      };
      // `import {Map}` with the `from` clause not typed yet.
      if (!this.#consumeOrRecover(TokenType.From, "Expected 'from'")) {
        return new ImportDeclaration(this.#missingModuleSpecifier(), imports, this.#makeLocation(startToken));
      }
      let moduleSpecifier = this.#parseModuleSpecifier();
      this.#consumeOrRecover(TokenType.Semi, "Expected ';'");
      return new ImportDeclaration(moduleSpecifier, imports, this.#makeLocation(startToken));
    }

    if (this.#match(TokenType.From)) {
      let moduleSpecifier = this.#parseStringLiteralNode();
      // `from 'zena:map'` with the import clause not typed yet.
      if (!this.#consumeOrRecover(TokenType.Import, "Expected 'import'")) {
        return new ImportDeclaration(moduleSpecifier, new Array<ImportSpecifier>(0), this.#makeLocation(startToken));
      }
      let imports = if (this.#check(TokenType.Star)) {
        let starToken = this.#advance();
        this.#consume(TokenType.As, "Expected 'as' after '*'.");
        let local = this.#parseIdentifier();
        let imported = new Identifier("*", this.#makeLocation(starToken));
        let arr = growable<ImportSpecifier>([
          new ImportSpecifier(imported, local, this.#makeLocation(starToken)),
        ]);
        arr
      } else {
        this.#parseImportSpecifiers()
      };
      this.#consumeOrRecover(TokenType.Semi, "Expected ';'");
      return new ImportDeclaration(moduleSpecifier, imports, this.#makeLocation(startToken));
    }

    throw this.#error('Expected import declaration.');
  }

  #parseImportSpecifiers(): GrowableArray<ImportSpecifier> {
    let imports = new Array<ImportSpecifier>(4);
    // `import` with the specifier list not typed yet.
    if (!this.#consumeOrRecover(TokenType.LBrace, "Expected '{'")) {
      return imports;
    }
    if (!this.#check(TokenType.RBrace) && !this.#atSpecifierListEnd()) {
      let startToken = this.#peek();
      let imported = this.#parseIdentifier();
      let local = if (this.#match(TokenType.As)) {
        this.#parseIdentifier()
      } else {
        imported
      };
      imports.push(new ImportSpecifier(imported, local, this.#makeLocation(startToken)));
      while (this.#match(TokenType.Comma) && !this.#check(TokenType.RBrace) && !this.#atSpecifierListEnd()) {
        let startToken2 = this.#peek();
        let imported2 = this.#parseIdentifier();
        let local2 = if (this.#match(TokenType.As)) {
          this.#parseIdentifier()
        } else {
          imported2
        };
        imports.push(new ImportSpecifier(imported2, local2, this.#makeLocation(startToken2)));
      }
    }
    // `import {Map` with the list still open at the end of a line.
    this.#consumeOrRecover(TokenType.RBrace, "Expected '}'");
    return imports;
  }

  /**
   * Parse the module specifier of an import, recovering from one that
   * has not been typed yet. This is where the user's cursor sits when
   * they ask what modules exist, so it has to yield a node either way.
   */
  #parseModuleSpecifier(): StringLiteral {
    if (!this.#check(TokenType.String) && this.#atLineBreak()) {
      this.#recoverableError("Expected string literal");
      return this.#missingModuleSpecifier();
    }
    return this.#parseStringLiteralNode();
  }

  /**
   * A stand-in for a module specifier that has not been typed yet,
   * located where it would go. The empty value is what marks it missing:
   * no real specifier is empty, so import wiring skips it instead of
   * trying to resolve it.
   */
  #missingModuleSpecifier(): StringLiteral {
    let token = this.#peek();
    return new StringLiteral("", new SourceLocation(
      token.start, token.start, this.#path));
  }

  /**
   * True when the last token consumed ended its line — the next token is
   * on a later line, or there is none. Import recovery keys off this: a
   * declaration still being typed runs out at a line break, while one
   * that is malformed within a single line is still an error.
   */
  #atLineBreak(): boolean {
    if (this.#isAtEnd()) {
      return true;
    }
    if (this.#current == 0) {
      return false;
    }
    return this.#peek().line > this.#previous().line;
  }

  /**
   * True when a specifier list has run out mid-typing. A line break alone
   * is not enough — import lists are routinely written across several
   * lines — so the next token must also be unable to name an import.
   */
  #atSpecifierListEnd(): boolean {
    return this.#atLineBreak() && !this.#isIdentifier();
  }

  #parseStringLiteralNode(): StringLiteral {
    let token = this.#consume(TokenType.String, "Expected string literal");
    return new StringLiteral(token.value, this.#makeLocation(token));
  }
  
  // ==========================================================================
  // Token Navigation
  // ==========================================================================
  
  #peek(): Token {
    return this.#tokens[this.#current];
  }
  
  #peek2(): Token {
    return this.#tokens[this.#current + 1];
  }

  #peek3(): Token {
    return this.#tokens[this.#current + 2];
  }
  
  #previous(): Token {
    return this.#tokens[this.#current - 1];
  }
  
  #isAtEnd(): boolean {
    return this.#peek().kind == TokenType.EOF;
  }
  
  #check(type: TokenType): boolean {
    // If we previously split a `>>` or `>>>` token in a generic context (like
    // `Array<Array<i32>>`), we pretend the current token is `>` until all
    // 'extra' greaters are consumed. This prevents `#match` from prematurely
    // checking the next underlying stream token.
    if (this.#extraGreaters > 0) {
      return type == TokenType.Greater;
    }
    if (this.#isAtEnd()) {
      return false;
    }
    return this.#peek().kind == type;
  }
  
  #advance(): Token {
    if (!this.#isAtEnd()) {
      this.#current = this.#current + 1;
    }
    return this.#previous();
  }
  
  #match(type: TokenType): boolean {
    if (this.#check(type)) {
      this.#advance();
      return true;
    }
    return false;
  }
  
  #consume(type: TokenType, message: String): Token {
    if (this.#check(type)) {
      return this.#advance();
    }
    throw this.#error(message);
  }
  
  /**
   * The error to throw where the grammar ran out, formatted for a
   * terminal: the same `file:line:column - Error: ` header a type error
   * carries, then the offending line and an underline of the token.
   *
   * `at` names the token to point at, for an error the parser only sees
   * once it is past the token it is about. The default is where the
   * parser stopped, which is what every error raised as it happens
   * wants.
   */
  #error(message: String, at: Token | null = null): SyntaxError {
    let token = at ?? this.#peek();
    let {line} = token;
    let col = token.column;
    let header = `${this.#path}:${i32ToString(line)}:${i32ToString(col)} - Error: `;

    // Extract the source line for context
    let src = this.#source;
    var lineStart = token.start;
    while (lineStart > 0 && src.sliceBytes(lineStart - 1, lineStart) != "\n") {
      lineStart -= 1;
    }
    var lineEnd = token.start;
    while (lineEnd < src.length && src.sliceBytes(lineEnd, lineEnd + 1) != "\n") {
      lineEnd += 1;
    }
    let sourceLine = src.sliceBytes(lineStart, lineEnd);

    // Underline the whole token, not just the byte it starts at. A zero
    // width token — end of input — still gets one caret to point with.
    var underline = "";
    var ci = 1;
    while (ci < col) {
      underline = underline + " ";
      ci += 1;
    }
    var width = token.end - token.start;
    if (width < 1) {
      width = 1;
    }
    var drawn = 0;
    while (drawn < width) {
      underline = underline + "^";
      drawn += 1;
    }

    let text = `${message} (got '${token.value}')`;
    let diagnostic = new Diagnostic(
      DiagnosticCode.UnexpectedToken,
      text,
      DiagnosticSeverity.Error,
      new SourceSpan(this.#path, token.start, width, line, col)
    );
    return new SyntaxError(
      `${header}${text}\n${sourceLine}\n${underline}`,
      diagnostic);
  }

  /**
   * Consume `type`, treating its absence at the end of a line as
   * recoverable rather than fatal. Returns whether the token was there,
   * so the caller can supply whatever the grammar needed it for.
   *
   * Calling this, rather than `#consume`, is the whole of what makes a
   * point in the grammar recoverable — nothing about the error itself
   * says so. "Expected ';'" is recoverable inside an import being typed
   * and fatal after a `let`, so the position decides, not the message.
   */
  #consumeOrRecover(type: TokenType, message: String): boolean {
    if (this.#check(type)) {
      this.#advance();
      return true;
    }
    if (this.#atLineBreak()) {
      this.#recoverableError(message);
      return false;
    }
    throw this.#error(message);
  }

  /**
   * Report an error at a point the parser knows how to recover from.
   *
   * A parser not constructed to recover throws, as `#consume` would
   * have. One that was collects the error as a diagnostic and continues,
   * leaving the caller an AST and the full list of what is wrong with
   * it. The source is invalid either way; only the reporting differs.
   */
  #recoverableError(
      message: String,
      code: DiagnosticCode = DiagnosticCode.ExpectedToken,
      at: Token | null = null): void {
    if (!this.#recover) {
      throw this.#error(message, at);
    }
    this.#completeness = ParseCompleteness.Recovered;
    let token = at ?? this.#peek();
    this.#lastErrorOffset = token.start;
    this.#errors.push(new Diagnostic(
      code,
      message,
      DiagnosticSeverity.Error,
      new SourceSpan(
        this.#path,
        token.start,
        token.end - token.start,
        token.line,
        token.column
      )
    ));
  }

  #recordSyntaxError(e: Error): void {
    if (!(e is SyntaxError)) {
      throw e;
    }
    this.#completeness = ParseCompleteness.Recovered;
    let loc = e.diagnostic.location;
    if (loc != null) {
      if (loc.start == this.#lastErrorOffset) {
        return;
      }
      this.#lastErrorOffset = loc.start;
    }
    this.#errors.push(e.diagnostic);
  }

  #isTopLevelStart(): boolean {
    if (this.#isAtEnd()) {
      return false;
    }
    return match (this.#peek().kind) {
      case TokenType.Import: true
      case TokenType.Export: true
      case TokenType.Let: true
      case TokenType.Var: true
      case TokenType.Function: true
      case TokenType.Gen: true
      case TokenType.Async: true
      case TokenType.Class: true
      case TokenType.Final: true
      case TokenType.Abstract: true
      case TokenType.Sealed: true
      case TokenType.Extension: true
      case TokenType.Interface: true
      case TokenType.Mixin: true
      case TokenType.Decorator: true
      case TokenType.Enum: true
      case TokenType.Type: true
      case TokenType.Distinct: true
      case TokenType.Symbol: true
      case TokenType.Declare: true
      case TokenType.At: true
      case _: false
    };
  }

  #isStatementStart(): boolean {
    if (this.#isTopLevelStart()) {
      return true;
    }
    if (this.#isAtEnd()) {
      return false;
    }
    return match (this.#peek().kind) {
      case TokenType.Return: true
      case TokenType.While: true
      case TokenType.For: true
      case TokenType.Break: true
      case TokenType.Continue: true
      case TokenType.If: true
      case TokenType.Match: true
      case TokenType.Try: true
      case TokenType.Using: true
      case TokenType.Yield: true
      case _: false
    };
  }

  #synchronizeTopLevel(posBefore: i32): void {
    this.#extraGreaters = 0;
    if (this.#current == posBefore && !this.#isAtEnd()) {
      let tok = this.#advance();
      if (tok.kind == TokenType.Semi) {
        return;
      }
    } else if (this.#current > posBefore) {
      let prev = this.#previous().kind;
      if (prev == TokenType.Semi || prev == TokenType.RBrace) {
        return;
      }
      if (this.#check(TokenType.Semi)) {
        this.#advance();
        return;
      }
      if ((this.#atLineBreak() && !this.#check(TokenType.RBrace)) || this.#isTopLevelStart()) {
        return;
      }
    }

    var braceDepth = 0;
    while (!this.#isAtEnd()) {
      if (braceDepth == 0) {
        if (this.#check(TokenType.Semi)) {
          this.#advance();
          return;
        }
        if ((this.#atLineBreak() && !this.#check(TokenType.RBrace)) || this.#isTopLevelStart()) {
          return;
        }
      }
      let tok = this.#advance();
      if (tok.kind == TokenType.LBrace) {
        braceDepth += 1;
      } else if (tok.kind == TokenType.RBrace) {
        if (braceDepth > 0) {
          braceDepth -= 1;
          if (braceDepth == 0) {
            return;
          }
        }
      }
    }
  }

  #synchronizeStatement(posBefore: i32): void {
    this.#extraGreaters = 0;
    if (this.#current == posBefore && !this.#isAtEnd() && !this.#check(TokenType.RBrace)) {
      let tok = this.#advance();
      if (tok.kind == TokenType.Semi) {
        return;
      }
    } else if (this.#current > posBefore) {
      let prev = this.#previous().kind;
      if (prev == TokenType.Semi || prev == TokenType.RBrace) {
        return;
      }
      if (this.#check(TokenType.Semi)) {
        this.#advance();
        return;
      }
      if (this.#check(TokenType.RBrace) || this.#atLineBreak() || this.#isStatementStart()) {
        return;
      }
    }

    var braceDepth = 0;
    while (!this.#isAtEnd()) {
      if (braceDepth == 0) {
        if (this.#check(TokenType.Semi)) {
          this.#advance();
          return;
        }
        if (this.#check(TokenType.RBrace) || this.#atLineBreak() || this.#isStatementStart()) {
          return;
        }
      }
      let tok = this.#advance();
      if (tok.kind == TokenType.LBrace) {
        braceDepth += 1;
      } else if (tok.kind == TokenType.RBrace) {
        if (braceDepth > 0) {
          braceDepth -= 1;
          if (braceDepth == 0) {
            return;
          }
        }
      }
    }
  }

  #synchronizeClassMember(posBefore: i32): void {
    this.#synchronizeStatement(posBefore);
  }

  #parseNumberLiteral(token: Token, startToken: Token): NumberLiteral {
    let err = validateNumberLiteral(token.value);
    if (err != null) {
      this.#recoverableError(err, DiagnosticCode.UnexpectedToken, token);
      return new NumberLiteral("0", this.#makeLocation(startToken));
    }
    return new NumberLiteral(token.value, this.#makeLocation(startToken));
  }


  /**
   * A node from `startToken` to the last token consumed. While some `>` of
   * a split `>>` or `>>>` are still pending (`#consumeGreater`), the node
   * ends at the `>` it consumed, that many characters before the token
   * does: in `Map<String, Array<i32>>`, `Array<i32>` ends at the first `>`.
   */
  #makeLocation(startToken: Token): SourceLocation {
    let endToken = this.#previous();
    return new SourceLocation(startToken.start, endToken.end - this.#extraGreaters, this.#path);
  }
  
  // ==========================================================================
  // Statement Parsing
  // ==========================================================================
  
  /**
   * `topLevel` is true only for statements directly in a module body.
   * `function` declarations are top-level-only, which is what makes their
   * "never a closure" guarantee structural: at module scope the only names
   * in scope are globals and imports.
   */
  #parseStatement(topLevel: boolean = false): Statement {
    let startToken = this.#peek();
    
    // Decorated statement: @decorator ... declare function ...
    if (this.#check(TokenType.At)) {
      let decorators = new Array<Decorator>(2);
      while (this.#check(TokenType.At)) {
        decorators.push(this.#parseDecorator());
      }
      let decExported = this.#match(TokenType.Export);
      if (this.#match(TokenType.Declare)) {
        if (this.#check(TokenType.Type)) {
          // A declared type operator: bodyless, because no body could
          // be honest about a type the type system cannot express
          // (@intrinsic('type.…') declare type Awaited<T>;).
          return this.#parseTypeAliasDeclaration(decExported, false, false, startToken, decorators, true);
        }
        return this.#parseDeclareFunction(decorators, decExported, startToken);
      }
      throw this.#error("Expected 'declare' after decorator");
    }
    
    // Export prefix
    var exported = false;
    if (this.#match(TokenType.Export)) {
      // export * from '...';
      if (this.#match(TokenType.Star)) {
        this.#consume(TokenType.From, "Expected 'from' after '*'");
        let moduleSpecifier = this.#parseStringLiteralNode();
        this.#consume(TokenType.Semi, "Expected ';' after export declaration");
        return new ExportAllDeclaration(moduleSpecifier, this.#makeLocation(startToken));
      }
      // export { x, y } from '...';
      if (this.#check(TokenType.LBrace)) {
        let specifiers = this.#parseImportSpecifiers();
        this.#consume(TokenType.From, "Expected 'from' after export specifiers");
        let moduleSpecifier = this.#parseStringLiteralNode();
        this.#consume(TokenType.Semi, "Expected ';' after export-from declaration");
        return new ExportFromDeclaration(specifiers, moduleSpecifier, this.#makeLocation(startToken));
      }
      exported = true;
    }
    
    // Reject late imports
    if (this.#check(TokenType.Import)) {
      throw this.#error('Imports must appear at the top of the file.');
    }
    if (this.#check(TokenType.From) && this.#peek2().kind == TokenType.String) {
      throw this.#error('Imports must appear at the top of the file.');
    }
    
    // Declare function (without decorators)
    if (this.#check(TokenType.Declare) && this.#peek2().kind == TokenType.Function) {
      this.#advance(); // consume 'declare'
      return this.#parseDeclareFunction(new Array<Decorator>(0), exported, startToken);
    }
    // Declare type without decorators parses; the checker rejects it
    // (a declared type operator requires its @intrinsic decorator).
    if (this.#check(TokenType.Declare) && this.#peek2().kind == TokenType.Type) {
      this.#advance(); // consume 'declare'
      return this.#parseTypeAliasDeclaration(exported, false, false, startToken, null, true);
    }
    
    // Function declarations: `function f() {}`, `gen function f() {}`,
    // `async function f() {}`. `gen`/`async` alone still start an arrow
    // function expression, so the lookahead for `function` is what
    // distinguishes them.
    if (this.#check(TokenType.Function) ||
        ((this.#check(TokenType.Gen) || this.#check(TokenType.Async)) &&
         this.#peek2().kind == TokenType.Function) ||
        // `async gen function`
        (this.#check(TokenType.Async) && this.#peek2().kind == TokenType.Gen &&
         this.#peek3().kind == TokenType.Function)) {
      return this.#parseFunctionDeclaration(exported, topLevel, startToken);
    }

    // `using` bindings, bound or not
    if (this.#match(TokenType.Using)) {
      return this.#parseUsingStatement(startToken);
    }

    // `shielded { ... }` — a contextual keyword, like `cancel`
    // (docs/design/cancellation.md §Shields).
    if (this.#check(TokenType.Identifier) &&
        this.#peek().value == 'shielded' &&
        this.#peek2().kind == TokenType.LBrace) {
      this.#advance();
      this.#consume(TokenType.LBrace, "Expected '{' after 'shielded'");
      let body = this.#parseBlockAsExpression(this.#previous());
      return new ShieldedStatement(body, this.#makeLocation(startToken));
    }

    // Variable declarations
    if (this.#match(TokenType.Let)) {
      return this.#parseVariableDeclaration('let', exported, startToken);
    }
    if (this.#match(TokenType.Var)) {
      return this.#parseVariableDeclaration('var', exported, startToken);
    }
    
    // Sealed class declarations
    if (this.#check(TokenType.Sealed)) {
      return this.#parseSealedClassEntry(exported, startToken);
    }
    
    // `resource` is a contextual modifier, not a reserved word: it only means
    // "resource class" when a class declaration actually follows, so `let
    // resource = ...` keeps working. See docs/design/ownership.md.
    if (this.#isResourceClassAhead()) {
      this.#advance();   // consume `resource`
      return this.#parseClassDeclarationEntry(exported, startToken, true);
    }

    // Class declarations
    if (this.#check(TokenType.Class) || this.#check(TokenType.Final) || this.#check(TokenType.Abstract) || this.#check(TokenType.Extension)) {
      return this.#parseClassDeclarationEntry(exported, startToken, false);
    }
    
    // Interface declarations
    if (this.#match(TokenType.Interface)) {
      return this.#parseInterfaceDeclaration(exported, startToken);
    }
    
    // Mixin declarations
    if (this.#match(TokenType.Mixin)) {
      return this.#parseMixinDeclaration(exported, startToken, false);
    }

    // Decorator declarations: a mixin applied one field at a time.
    if (this.#match(TokenType.Decorator)) {
      return this.#parseMixinDeclaration(exported, startToken, true);
    }
    
    // Enum declarations
    if (this.#match(TokenType.Enum)) {
      return this.#parseEnumDeclaration(exported, startToken);
    }
    
    // Type alias declarations: type X = Y; distinct type X = Y;
    // or opaque type X = Y;
    if (this.#check(TokenType.Type)) {
      return this.#parseTypeAliasDeclaration(exported, false, false, startToken);
    }
    if (this.#check(TokenType.Distinct)) {
      this.#advance(); // consume 'distinct'
      return this.#parseTypeAliasDeclaration(exported, true, false, startToken);
    }
    // `opaque` is only a modifier directly before `type`; anywhere else it is
    // an ordinary identifier (see #isIdentifier).
    if (this.#check(TokenType.Opaque) && this.#peek2().kind == TokenType.Type) {
      this.#advance(); // consume 'opaque'
      // An opaque type is a distinct type with a cast restriction, so both
      // flags are set — downstream passes only special-case the restriction.
      return this.#parseTypeAliasDeclaration(exported, true, true, startToken);
    }
    
    // Symbol declarations
    if (this.#check(TokenType.Symbol) && this.#peek2().kind == TokenType.Identifier) {
      this.#advance(); // consume 'symbol'
      return this.#parseSymbolDeclaration(exported, startToken);
    }
    
    // Control flow
    if (this.#match(TokenType.Return)) {
      return this.#parseReturnStatement(startToken, false);
    }
    if (this.#isTailReturnAhead()) {
      this.#advance();   // consume `tail`
      this.#advance();   // consume `return`
      return this.#parseReturnStatement(startToken, true);
    }
    if (this.#match(TokenType.Yield)) {
      let argument = this.#parseExpression();
      this.#consume(TokenType.Semi, "Expected ';' after yield value");
      return new YieldStatement(argument, this.#makeLocation(startToken));
    }
    if (this.#match(TokenType.Break)) {
      this.#consume(TokenType.Semi, "Expected ';' after break");
      return new BreakStatement(this.#makeLocation(startToken));
    }
    if (this.#match(TokenType.Continue)) {
      this.#consume(TokenType.Semi, "Expected ';' after continue");
      return new ContinueStatement(this.#makeLocation(startToken));
    }
    if (this.#match(TokenType.If)) {
      return this.#parseIfStatement(startToken);
    }
    if (this.#match(TokenType.While)) {
      return this.#parseWhileStatement(startToken);
    }
    if (this.#match(TokenType.For)) {
      return this.#parseForStatement(startToken);
    }
    
    // Block statement
    if (this.#match(TokenType.LBrace)) {
      return this.#parseBlockStatement(startToken);
    }
    
    // Expression statement
    return this.#parseExpressionStatement();
  }
  
  /**
   * `using file = open(path);` or the unbound `using acquire(lock);`.
   *
   * `using` declares the binding itself — no `let`. It cannot declare a
   * mutable one, so there is no mutability left for `let`/`var` to choose
   * between: the release targets the value bound here, and a rebound name
   * would release a stale value and leak the new one. Every language with
   * this construct reaches the same place (C#'s using variable is
   * read-only, Java's try-with-resources resource is implicitly final,
   * JavaScript's `using` binding cannot be assigned to).
   *
   * `using` is a keyword, so the unbound form needs no placeholder binding —
   * `using _ = foo()` is a workaround for a syntax gap other languages have
   * and this one does not. Telling the two forms apart is one token of
   * lookahead: a name followed by `=` or `:` binds, anything else is the
   * expression form. See docs/design/ownership.md §`using`.
   */
  #parseUsingStatement(startToken: Token): UsingStatement {
    var pattern: Pattern | null = null;
    var typeAnnotation: TypeAnnotation | null = null;

    if (this.#check(TokenType.Var)) {
      throw this.#error(`A 'using' binding is released when it leaves scope, so it cannot be reassigned: write 'using ${this.#peek2().value} = ...'.`);
    }
    if (this.#check(TokenType.Let)) {
      throw this.#error(`'using' already declares the binding; write 'using ${this.#peek2().value} = ...' rather than 'using let'.`);
    }

    if (this.#check(TokenType.Identifier) &&
        (this.#peek2().kind == TokenType.Equals ||
         this.#peek2().kind == TokenType.Colon)) {
      pattern = this.#parsePattern(true);
      if (this.#match(TokenType.Colon)) {
        typeAnnotation = this.#parseTypeAnnotation();
      }
      this.#consume(TokenType.Equals, "Expected '=' after the name of a 'using' binding");
    }

    let init = this.#parseExpression();

    if (this.#check(TokenType.Semi)) {
      this.#advance();
    } else if (this.#recover) {
      if (this.#atLineBreak() || this.#check(TokenType.RBrace) || this.#isAtEnd()) {
        this.#recordSyntaxError(this.#error("Expected ';' after using statement"));
      } else {
        this.#consume(TokenType.Semi, "Expected ';' after using statement");
      }
    } else if (!this.#check(TokenType.RBrace) && !this.#isAtEnd()) {
      this.#consume(TokenType.Semi, "Expected ';' after using statement");
    }

    return new UsingStatement(pattern, typeAnnotation, init, this.#makeLocation(startToken));
  }

  #parseVariableDeclaration(kind: String, exported: boolean, startToken: Token): VariableDeclaration {
    // Parse pattern (for now just identifier)
    let pattern = this.#parsePattern(true);
    
    // Optional type annotation
    let typeAnnotation: TypeAnnotation | null = if (this.#match(TokenType.Colon)) {
      this.#parseTypeAnnotation()
    } else {
      null
    };
    
    // Initializer (optional for typed `var` declarations, which default to null)
    let init = if (kind == 'var' && pattern is IdentifierPattern && typeAnnotation != null && !this.#check(TokenType.Equals)) {
      new NullLiteral(null)
    } else {
      this.#consume(TokenType.Equals, "Expected '=' after variable name");
      if (this.#check(TokenType.RBrace) || this.#isAtEnd()) {
        if (this.#recover) {
          this.#recordSyntaxError(this.#error("Unexpected token in expression"));
        }
        let st = this.#peek();
        new Identifier("", this.#makeLocation(st))
      } else {
        this.#parseExpression()
      }
    };
    
    if (this.#check(TokenType.Semi)) {
      this.#advance();
    } else if (this.#recover) {
      if (this.#atLineBreak() || this.#check(TokenType.RBrace) || this.#isAtEnd()) {
        this.#recordSyntaxError(this.#error("Expected ';' after variable declaration"));
      } else {
        this.#consume(TokenType.Semi, "Expected ';' after variable declaration");
      }
    } else if (!this.#check(TokenType.RBrace) && !this.#isAtEnd()) {
      this.#consume(TokenType.Semi, "Expected ';' after variable declaration");
    }
    
    return new VariableDeclaration(kind, pattern, typeAnnotation, init, exported, this.#makeLocation(startToken));
  }

  /**
   * `function name<T>(params): Ret { ... }`, optionally prefixed by `gen`
   * or `async`. The body must be a block: a `function` reads as a
   * declaration, and an expression body would just be a longer spelling of
   * `let name = (params) => expr`.
   */
  #parseFunctionDeclaration(exported: boolean, topLevel: boolean, startToken: Token): FunctionDeclaration {
    var isGenerator = false;
    var isAsync = false;
    if (this.#match(TokenType.Gen)) {
      isGenerator = true;
    } else if (this.#match(TokenType.Async)) {
      isAsync = true;
      // `async gen function`: may await AND yield (async-iteration.md).
      if (this.#match(TokenType.Gen)) {
        isGenerator = true;
      }
    }
    this.#consume(TokenType.Function, "Expected 'function'");

    if (!topLevel) {
      throw this.#error("'function' declarations may only appear at the top level of a module. Use an arrow function, e.g. `let f = () => ...`, inside a body.");
    }

    let nameToken = this.#peek();
    let nameIdent = this.#parseIdentifier();
    let name = new IdentifierPattern(nameIdent.name, this.#makeLocation(nameToken));

    // Type parameters: function f<T>(...)
    var typeParameters: GrowableArray<TypeParameter> | null = null;
    if (this.#check(TokenType.Less)) {
      this.#advance();
      typeParameters = this.#parseTypeParameterList();
    }

    this.#consume(TokenType.LParen, "Expected '(' after function name");
    let params = this.#parseParameters();
    this.#consume(TokenType.RParen, "Expected ')' after parameters");

    let returnType: TypeAnnotation | null = if (this.#match(TokenType.Colon)) {
      this.#parseTypeAnnotation()
    } else {
      null
    };

    let contracts = this.#parseFunctionContracts();

    let braceToken = this.#consume(TokenType.LBrace, "Expected '{' before function body");
    let body = this.#parseBlockStatement(braceToken);

    let func = new FunctionExpression(
      typeParameters, params, returnType, body, isGenerator, isAsync, contracts,
      this.#makeLocation(startToken));
    return new FunctionDeclaration(name, func, exported, this.#makeLocation(startToken));
  }

  /** Whether the token `offset` past the current one is the name `word`. */
  #isNameAt(offset: i32, word: String): boolean {
    let token = this.#tokens[this.#current + offset];
    return token.kind == TokenType.Identifier && token.value == word;
  }

  /**
   * The offset of a clause's keyword, for a clause that starts `offset`
   * past the current token: one further when the clause is marked
   * `debug`. The caller checks that a clause keyword is there.
   */
  #clauseKeywordAt(offset: i32): i32 {
    return if (this.#clauseModifierAt(offset) != ContractMode.Checked) offset + 1 else offset;
  }

  /**
   * The modifier written `offset` past the current token: `debug`, a
   * name, or `static`, a keyword; `Checked` when there is none.
   */
  #clauseModifierAt(offset: i32): ContractMode {
    if (this.#isNameAt(offset, 'debug')) { return ContractMode.Debug; }
    if (this.#tokens[this.#current + offset].kind == TokenType.Static) {
      return ContractMode.Static;
    }
    return ContractMode.Checked;
  }

  /**
   * Whether a `requires` or `ensures` clause, marked `debug` or not,
   * starts `offset` past the current token. The words are contextual: a
   * signature is never followed by a name, so after one they can only
   * start a clause, and nothing named `requires`, `ensures` or `debug`
   * is disturbed. See docs/design/contracts.md.
   */
  #isFunctionContractAt(offset: i32): boolean {
    let keyword = this.#clauseKeywordAt(offset);
    return this.#isNameAt(keyword, 'requires') || this.#isNameAt(keyword, 'ensures');
  }

  /**
   * The `requires` and `ensures` clauses that follow a signature, or null
   * when there are none.
   */
  #parseFunctionContracts(): GrowableArray<ContractClause> | null {
    if (!this.#isFunctionContractAt(0)) { return null; }
    let clauses = new Array<ContractClause>(2);
    while (this.#isFunctionContractAt(0)) {
      let kind = if (this.#isNameAt(this.#clauseKeywordAt(0), 'requires')) {
        ContractKind.Requires
      } else {
        ContractKind.Ensures
      };
      clauses.push(this.#parseContractClause(kind));
    }
    return clauses;
  }

  /**
   * Where an `invariant (...)` clause, marked `debug` or not, ends, when
   * one starts `offset` past the current token: the offset just past
   * its `)`. Otherwise -1.
   */
  #invariantClauseEnd(offset: i32): i32 {
    let keyword = this.#clauseKeywordAt(offset);
    if (!this.#isNameAt(keyword, 'invariant')) { return -1; }
    var i = keyword + 1;
    if (this.#tokens[this.#current + i].kind != TokenType.LParen) { return -1; }
    var depth = 0;
    while (true) {
      let token = this.#tokens[this.#current + i];
      if (token.kind == TokenType.EOF) { return -1; }
      if (token.kind == TokenType.LParen) {
        depth += 1;
      } else if (token.kind == TokenType.RParen) {
        depth -= 1;
      }
      i += 1;
      if (depth == 0) { break; }
    }
    return i;
  }

  /**
   * Whether an `invariant` clause starts at the current token. A loop's
   * body can be any statement, so `while (c) invariant(x);` is a loop
   * that calls a function. The word is a clause keyword only when its
   * parenthesized condition is followed by `{` or by another clause,
   * which a call statement never is.
   */
  #isLoopInvariantAhead(): boolean {
    let end = this.#invariantClauseEnd(0);
    if (end < 0) { return false; }
    return this.#tokens[this.#current + end].kind == TokenType.LBrace ||
        this.#invariantClauseEnd(end) >= 0;
  }

  /**
   * The `invariant` clauses that follow a loop's header, or null when
   * there are none.
   */
  #parseLoopInvariants(): GrowableArray<ContractClause> | null {
    if (!this.#isLoopInvariantAhead()) { return null; }
    let clauses = new Array<ContractClause>(2);
    while (this.#isLoopInvariantAhead()) {
      clauses.push(this.#parseContractClause(ContractKind.Invariant));
    }
    return clauses;
  }

  /**
   * A loop's body. A loop with `invariant` clauses takes a block, which
   * is what lets `invariant` stay an ordinary name everywhere else.
   */
  #parseLoopBody(invariants: GrowableArray<ContractClause> | null): Statement {
    if (invariants != null && !this.#check(TokenType.LBrace)) {
      throw this.#error("Expected '{': a loop with 'invariant' clauses needs a block body");
    }
    return this.#parseStatement();
  }

  /**
   * One clause, `keyword (condition)` with or without a modifier in
   * front, with the current token at its first word.
   */
  #parseContractClause(kind: ContractKind): ContractClause {
    let startToken = this.#peek();
    let mode = this.#clauseModifierAt(0);
    if (mode != ContractMode.Checked) {
      this.#advance();
    }
    this.#advance();
    let keyword = contractKeyword(kind);
    this.#consume(TokenType.LParen,
        `Expected '(' after '${keyword}': the condition is written in parentheses, as in '${keyword} (x > 0)'`);
    let condition = this.#parseExpression();
    this.#consume(TokenType.RParen, `Expected ')' after the '${keyword}' condition`);
    let loc = this.#makeLocation(startToken);
    let text = this.#source.sliceBytes(loc.start, loc.end);
    return new ContractClause(kind, condition, mode, text, loc);
  }

  #parseReturnStatement(startToken: Token, isTail: boolean): ReturnStatement {
    let argument: Expression | null = if (!this.#check(TokenType.Semi)) {
      this.#parseExpression()
    } else {
      null
    };

    this.#consume(TokenType.Semi, "Expected ';' after return statement");

    if (isTail && argument == null) {
      throw this.#error("'tail return' needs a call to return: write 'tail return f(x);'.");
    }

    return new ReturnStatement(argument, isTail, this.#makeLocation(startToken));
  }
  
  #parseIfStatement(startToken: Token): IfStatement {
    this.#consume(TokenType.LParen, "Expected '(' after 'if'");
    let test = this.#parseCondition();
    this.#consume(TokenType.RParen, "Expected ')' after condition");
    
    let consequent = this.#parseStatement();
    
    let alternate: Statement | null = if (this.#match(TokenType.Else)) {
      this.#parseStatement()
    } else {
      null
    };
    
    return new IfStatement(test, consequent, alternate, this.#makeLocation(startToken));
  }
  
  #parseWhileStatement(startToken: Token): WhileStatement {
    this.#consume(TokenType.LParen, "Expected '(' after 'while'");
    let test = this.#parseCondition();
    this.#consume(TokenType.RParen, "Expected ')' after condition");

    let invariants = this.#parseLoopInvariants();
    let body = this.#parseLoopBody(invariants);

    return new WhileStatement(test, body, invariants, this.#makeLocation(startToken));
  }
  
  #parseCondition(): Node {
    if (this.#match(TokenType.Let)) {
      return this.#parseLetPatternCondition();
    }
    return this.#parseExpression();
  }
  
  #parseLetPatternCondition(): LetPatternCondition {
    let startToken = this.#previous();
    // The `let` is explicit, so the whole pattern is under it — elements bind,
    // exactly as in `case let (true, x)`. (Declaration-context parsing handles
    // literal elements like the `true` here as LiteralPattern.)
    let pattern = if (this.#check(TokenType.LParen)) {
      let parenToken = this.#advance();
      let p = this.#parseParenTuplePattern(parenToken, true, false);
      p
    } else {
      let p = this.#parsePattern(true);
      p
    };
    this.#consume(TokenType.Equals, "Expected '=' after pattern in let condition");
    let init = this.#parseExpression();
    return new LetPatternCondition(pattern, init, this.#makeLocation(startToken));
  }
  
  #parseForStatement(startToken: Token): Statement {
    // `for await (x in it)` consumes its elements asynchronously
    // (async-iteration.md). The flag only applies to the for-in form.
    let isAwait = this.#match(TokenType.Await);
    this.#consume(TokenType.LParen, "Expected '(' after 'for'");
    
    if (this.#match(TokenType.Let)) {
      // Could be for-in or C-style with let declaration
      let pattern = this.#parsePattern(true);
      
      if (this.#match(TokenType.In)) {
        // for-in loop
        let iterable = this.#parseExpression();
        this.#consume(TokenType.RParen, "Expected ')' after for-in iterable");
        let invariants = this.#parseLoopInvariants();
        let body = this.#parseLoopBody(invariants);
        return new ForInStatement(pattern, iterable, body, isAwait, invariants, this.#makeLocation(startToken));
      }
      
      // C-style for with let declaration
      this.#consume(TokenType.Equals, "Expected '=' or 'in' after pattern in for statement");
      let initExpr = this.#parseExpression();
      let init = new VariableDeclaration('let', pattern, null, initExpr, false, this.#makeLocation(startToken));
      return this.#parseCStyleFor(startToken, init, isAwait);
    }
    
    if (this.#match(TokenType.Var)) {
      // C-style for with var declaration
      let varStart = this.#previous();
      let pattern = this.#parsePattern(true);
      
      let typeAnnotation: TypeAnnotation | null = if (this.#match(TokenType.Colon)) {
        this.#parseTypeAnnotation()
      } else {
        null
      };
      
      let initExpr: Expression = if (pattern is IdentifierPattern && typeAnnotation != null && !this.#check(TokenType.Equals)) {
        new NullLiteral(null)
      } else {
        this.#consume(TokenType.Equals, "Expected '=' after variable name");
        this.#parseExpression()
      };
      let init = new VariableDeclaration('var', pattern, typeAnnotation, initExpr, false, this.#makeLocation(varStart));
      return this.#parseCStyleFor(startToken, init, isAwait);
    }
    
    // Parse init as expression, or empty
    let init: Node | null = if (!this.#check(TokenType.Semi)) {
      this.#parseExpression()
    } else {
      null
    };
    
    return this.#parseCStyleFor(startToken, init, isAwait);
  }
  
  #parseCStyleFor(startToken: Token, init: Node | null, isAwait: boolean): ForStatement {
    if (isAwait) {
      throw this.#error("'for await' requires an 'in' clause: 'for await (let x in it)'");
    }
    this.#consume(TokenType.Semi, "Expected ';' after for initializer");
    
    let test: Expression | null = if (!this.#check(TokenType.Semi)) {
      this.#parseExpression()
    } else {
      null
    };
    this.#consume(TokenType.Semi, "Expected ';' after for condition");
    
    let update: Expression | null = if (!this.#check(TokenType.RParen)) {
      this.#parseExpression()
    } else {
      null
    };
    this.#consume(TokenType.RParen, "Expected ')' after for clauses");

    let invariants = this.#parseLoopInvariants();
    let body = this.#parseLoopBody(invariants);

    return new ForStatement(init, test, update, body, invariants, this.#makeLocation(startToken));
  }
  
  /**
   * `tail return f(x);` — see docs/design/tail-calls.md. `tail` is
   * contextual: a name followed by `return` is not otherwise a
   * statement, so nothing named `tail` is disturbed.
   */
  #isTailReturnAhead(): boolean {
    return this.#check(TokenType.Identifier) && this.#peek().value == 'tail' &&
        this.#peek2().kind == TokenType.Return;
  }

  #parseBlockStatement(startToken: Token): BlockStatement {
    let body = new Array<Statement>(8);
    
    while (!this.#check(TokenType.RBrace) && !this.#isAtEnd()) {
      if (this.#recover) {
        let posBefore = this.#current;
        try {
          body.push(this.#parseStatement());
        } catch (e) {
          this.#recordSyntaxError(e);
          this.#synchronizeStatement(posBefore);
        }
        if (this.#current == posBefore && !this.#check(TokenType.RBrace) && !this.#isAtEnd()) {
          this.#advance();
        }
      } else {
        body.push(this.#parseStatement());
      }
    }
    
    if (this.#recover && !this.#check(TokenType.RBrace)) {
      this.#recordSyntaxError(this.#error("Expected '}' after block"));
    } else {
      this.#consume(TokenType.RBrace, "Expected '}' after block");
    }
    
    return new BlockStatement(body, this.#makeLocation(startToken));
  }
  
  #parseBlockAsExpression(startToken: Token): BlockStatement {
    let body = new Array<Statement>(8);
    
    while (!this.#check(TokenType.RBrace) && !this.#isAtEnd()) {
      let posBefore = this.#current;
      try {
        // Check for keywords that definitely start statements
        if (this.#check(TokenType.Let) || this.#check(TokenType.Var) || this.#check(TokenType.Return) || this.#check(TokenType.Yield) || this.#check(TokenType.While) || this.#check(TokenType.For) || this.#check(TokenType.Break) || this.#check(TokenType.Continue) || this.#check(TokenType.Class) || this.#check(TokenType.Using) || this.#isTailReturnAhead()) {
          body.push(this.#parseStatement());
        } else if (this.#check(TokenType.Semi)) {
          // If we're at a semicolon, skip it (e.g. empty statement or trailing ; after block-ended stmt)
          this.#advance();
        } else {
          // Try to parse as expression
          let exprStart = this.#current;
          let expr = this.#parseExpression();
          if (this.#recover && this.#current == exprStart &&
              !this.#check(TokenType.Semi) && !this.#check(TokenType.RBrace) && !this.#isAtEnd()) {
            this.#advance();
          }

          // If next token is '}', this is the trailing expression (no semicolon needed)
          if (this.#check(TokenType.RBrace)) {
            body.push(new ExpressionStatement(expr, expr.loc));
            break;
          }

          body.push(new ExpressionStatement(expr, expr.loc));
          if (!this.#isBlockEndedExpression(expr)) {
            if (this.#check(TokenType.Semi)) {
              this.#advance();
            } else if (!this.#check(TokenType.RBrace)) {
              if (this.#recover) {
                if (this.#atLineBreak() || this.#isAtEnd()) {
                  this.#recordSyntaxError(this.#error("Expected ';' after expression"));
                } else {
                  this.#consume(TokenType.Semi, "Expected ';' after expression");
                }
              } else {
                this.#error("Expected ';' after expression");
              }
            }
          } else if (this.#check(TokenType.Semi)) {
            this.#advance();
          }
        }
      } catch (e) {
        if (!this.#recover) {
          throw e;
        }
        this.#recordSyntaxError(e);
        this.#synchronizeStatement(posBefore);
      }
      if (this.#recover && this.#current == posBefore && !this.#check(TokenType.RBrace) && !this.#isAtEnd()) {
        this.#advance();
      }
    }
    
    if (this.#recover && !this.#check(TokenType.RBrace)) {
      this.#recordSyntaxError(this.#error("Expected '}' after block"));
    } else {
      this.#consume(TokenType.RBrace, "Expected '}' after block");
    }
    
    return new BlockStatement(body, this.#makeLocation(startToken));
  }
  
  // ==========================================================================
  // Match Expression
  // ==========================================================================
  
  #parseMatchExpression(startToken: Token): MatchExpression {
    this.#consume(TokenType.LParen, "Expected '(' after 'match'");
    let discriminant = this.#parseExpression();
    this.#consume(TokenType.RParen, "Expected ')' after match discriminant");
    this.#consume(TokenType.LBrace, "Expected '{' before match cases");
    
    let cases = new Array<MatchCase>(4);
    while (!this.#check(TokenType.RBrace) && !this.#isAtEnd()) {
      cases.push(this.#parseMatchCase());
    }
    this.#consume(TokenType.RBrace, "Expected '}' after match cases");
    
    return new MatchExpression(discriminant, cases, this.#makeLocation(startToken));
  }
  
  #parseMatchCase(): MatchCase {
    this.#consume(TokenType.Case, "Expected 'case'");
    let startToken = this.#previous();
    let pattern = this.#parseMatchPattern();
    
    let guard: Expression | null = if (this.#match(TokenType.If)) {
      this.#parseExpression()
    } else {
      null
    };
    
    this.#consume(TokenType.Colon, "Expected ':' after case pattern");
    
    return if (this.#match(TokenType.LBrace)) {
      let body: Node = this.#parseBlockAsExpression(this.#previous());
      new MatchCase(pattern, guard, body, this.#makeLocation(startToken))
    } else {
      let body: Node = this.#parseExpression();
      new MatchCase(pattern, guard, body, this.#makeLocation(startToken))
    };
  }
  
  #parseMatchPattern(): Node {
    return this.#parseLogicalOrPattern();
  }
  
  #parseLogicalOrPattern(): Node {
    var left = this.#parseLogicalAndPattern();
    while (this.#match(TokenType.Pipe)) {
      let right = this.#parseLogicalAndPattern();
      left = new LogicalPattern('||', left, right, null);
    }
    return left;
  }
  
  #parseLogicalAndPattern(): Node {
    var left = this.#parseAsPattern();
    while (this.#match(TokenType.Ampersand)) {
      let right = this.#parseAsPattern();
      left = new LogicalPattern('&&', left, right, null);
    }
    return left;
  }
  
  #parseAsPattern(): Node {
    let pattern = this.#parsePrimaryPattern();
    if (this.#match(TokenType.As)) {
      let name = this.#parseIdentifier();
      return new AsPattern(pattern, name, null);
    }
    return pattern;
  }
  
  #parsePrimaryPattern(): Node {
    let startToken = this.#peek();
    
    // Binding pattern: let x or var y
    if (this.#match(TokenType.Let) || this.#match(TokenType.Var)) {
      let kind = if (this.#previous().kind == TokenType.Let) 'let' else 'var';
      let inner = this.#parsePattern(true);
      return new BindingPattern(kind, inner, this.#makeLocation(startToken));
    }
    
    // Number literal pattern
    if (this.#match(TokenType.Number)) {
      let token = this.#previous();
      return this.#parseNumberLiteral(token, startToken);
    }
    
    // String literal pattern
    if (this.#match(TokenType.String)) {
      let token = this.#previous();
      return new StringLiteral(token.value, this.#makeLocation(startToken));
    }
    
    // Boolean literal patterns
    if (this.#match(TokenType.True)) {
      return new BooleanLiteral(true, this.#makeLocation(startToken));
    }
    if (this.#match(TokenType.False)) {
      return new BooleanLiteral(false, this.#makeLocation(startToken));
    }
    
    // Null literal pattern
    if (this.#match(TokenType.Null)) {
      return new NullLiteral(this.#makeLocation(startToken));
    }
    
    // Record pattern: { a, b }
    if (this.#match(TokenType.LBrace)) {
      return this.#parseRecordPattern(startToken, false, true);
    }
    
    // Tuple pattern: (a, b)
    if (this.#match(TokenType.LParen)) {
      return this.#parseMatchTuplePattern(startToken);
    }

    // Array pattern: [a, b]
    if (this.#match(TokenType.LBracket)) {
      return this.#parseMatchArrayPattern(startToken);
    }
    
    // Identifier, wildcard, class pattern, or member expression pattern
    if (this.#isIdentifier()) {
      let ident = this.#parseIdentifier();
      // `Box<f64>` names an instantiation; a field list may follow.
      let typeArguments: GrowableArray<TypeAnnotation> | null =
          if (this.#check(TokenType.Less)) this.#parseTypeArguments() else null;

      // Class pattern: ClassName { ... }
      if (this.#check(TokenType.LBrace)) {
        this.#advance();
        let properties = new Array<BindingProperty>(4);
        while (!this.#check(TokenType.RBrace) && !this.#isAtEnd()) {
          let propStart = this.#peek();
          // Parsed here so the checker can reject it with a pointed
          // message (class fields have no presence).
          if (this.#match(TokenType.Bang)) {
            let absentName = this.#parseIdentifier();
            properties.push(new BindingProperty(absentName,
                new AbsencePattern(this.#makeLocation(propStart)),
                this.#makeLocation(propStart)));
            if (!this.#check(TokenType.RBrace)) {
              this.#consume(TokenType.Comma, "Expected ',' after property");
            }
            continue;
          }
          let name = this.#parseIdentifier();
          var value: Node = new IdentifierPattern(name.name, name.loc);
          if (this.#match(TokenType.Colon)) {
            value = this.#parseMatchPattern();
          } else if (this.#match(TokenType.As)) {
            let newName = this.#parseIdentifier();
            value = new IdentifierPattern(newName.name, newName.loc);
          }
          properties.push(new BindingProperty(name, value, this.#makeLocation(propStart)));
          if (!this.#check(TokenType.RBrace)) {
            this.#consume(TokenType.Comma, "Expected ',' after property");
          }
        }
        this.#consume(TokenType.RBrace, "Expected '}' after class pattern");
        return new ClassPattern(ident, typeArguments, properties, this.#makeLocation(startToken));
      }
      if (typeArguments != null) {
        return new ClassPattern(ident, typeArguments, new Array<BindingProperty>(),
            this.#makeLocation(startToken));
      }

      // Member expression pattern: Enum.Member or A.B.C
      if (this.#check(TokenType.Dot)) {
        var obj: Expression = ident;
        while (this.#match(TokenType.Dot)) {
          let prop = this.#parseIdentifier();
          obj = new MemberExpression(obj, prop, false, false, null, this.#makeLocation(startToken));
        }
        return obj;
      }
      
      // Plain identifier or wildcard
      return ident;
    }
    
    throw this.#error("Unexpected token in pattern");
  }
  
  #parseMatchTuplePattern(startToken: Token): Node {
    let elements = new Array<Node | null>(4);
    var hasRest = false;

    if (!this.#check(TokenType.RParen)) {
      while (true) {
        // Rest: (first, ...rest) binds the elements the others do not.
        if (this.#match(TokenType.DotDotDot)) {
          let restToken = this.#previous();
          if (hasRest) {
            throw this.#error("A tuple pattern may only contain one rest element");
          }
          hasRest = true;
          let restName = this.#parseIdentifier();
          let restPat = new IdentifierPattern(restName.name, restName.loc);
          elements.push(new RestPattern(restPat, this.#makeLocation(restToken)));
        } else {
          elements.push(this.#parseMatchPattern());
        }
        if (!this.#match(TokenType.Comma) || this.#check(TokenType.RParen)) {
          break;
        }
      }
    }
    
    this.#consume(TokenType.RParen, "Expected ')' after tuple pattern");
    if (elements.length == 1 && !(elements[0] is RestPattern)) {
      return elements[0] as Node;
    }
    return new TuplePattern(elements, this.#makeLocation(startToken));
  }

  #parseMatchArrayPattern(startToken: Token): Node {
    let elements = new Array<Node | null>(4);
    var hasRest = false;

    while (!this.#check(TokenType.RBracket) && !this.#isAtEnd()) {
      if (this.#match(TokenType.Comma)) {
        if (hasRest) {
          throw this.#error("Rest element cannot be followed by another element");
        }
        elements.push(null);
        continue;
      }

      if (this.#match(TokenType.DotDotDot)) {
        let restToken = this.#previous();
        if (hasRest) {
          throw this.#error("An array pattern may only contain one rest element");
        }
        hasRest = true;
        let restPat = this.#parseMatchPattern();
        elements.push(new RestPattern(restPat, this.#makeLocation(restToken)));
        if (this.#match(TokenType.Comma)) {
          if (!this.#check(TokenType.RBracket)) {
            throw this.#error("Rest element must be the last element in an array pattern");
          }
        }
        break;
      }

      elements.push(this.#parseMatchPattern());

      if (!this.#check(TokenType.RBracket)) {
        this.#consume(TokenType.Comma, "Expected ',' in array pattern");
      }
    }

    this.#consume(TokenType.RBracket, "Expected ']' after array pattern");
    return new ArrayPattern(elements, this.#makeLocation(startToken));
  }
  
  // ==========================================================================
  // If Expression
  // ==========================================================================
  
  #parseIfExpression(startToken: Token): IfExpression {
    this.#consume(TokenType.LParen, "Expected '(' after 'if'");
    let test = this.#parseCondition();
    this.#consume(TokenType.RParen, "Expected ')' after if condition");
    
    let consequent = if (this.#match(TokenType.LBrace)) {
      let b: Node = this.#parseBlockAsExpression(this.#previous());
      b
    } else {
      let e: Node = this.#parseExpression();
      e
    };
    
    let alternate: Node | null = if (this.#match(TokenType.Else)) {
      if (this.#match(TokenType.LBrace)) {
        let b: Node = this.#parseBlockAsExpression(this.#previous());
        b
      } else if (this.#check(TokenType.If)) {
        this.#advance();
        let e: Node = this.#parseIfExpression(this.#previous());
        e
      } else {
        let e: Node = this.#parseExpression();
        e
      }
    } else {
      null
    };
    
    return new IfExpression(test, consequent, alternate, this.#makeLocation(startToken));
  }
  
  #parseTryExpression(startToken: Token): TryExpression {
    this.#consume(TokenType.LBrace, "Expected '{' after 'try'");
    let body = this.#parseBlockAsExpression(this.#previous());
    
    var handler: CatchClause | null = null;
    var cancelBlock: BlockStatement | null = null;
    var finalizer: BlockStatement | null = null;

    // `cancel { ... }` — a contextual keyword, legal only between the
    // try block and any catch (docs/design/cancellation.md).
    if (this.#check(TokenType.Identifier) && this.#peek().value == 'cancel' &&
        this.#peek2().kind == TokenType.LBrace) {
      this.#advance();
      this.#consume(TokenType.LBrace, "Expected '{' after 'cancel'");
      cancelBlock = this.#parseBlockAsExpression(this.#previous());
    }

    if (this.#match(TokenType.Catch)) {
      let catchToken = this.#previous();
      var param: Identifier | null = null;
      
      if (this.#match(TokenType.LParen)) {
        param = this.#parseIdentifier();
        this.#consume(TokenType.RParen, "Expected ')' after catch parameter");
      }
      
      this.#consume(TokenType.LBrace, "Expected '{' after catch");
      let catchBody = this.#parseBlockAsExpression(this.#previous());
      
      handler = new CatchClause(param, catchBody, this.#makeLocation(catchToken));
    }
    
    if (this.#match(TokenType.Finally)) {
      this.#consume(TokenType.LBrace, "Expected '{' after 'finally'");
      finalizer = this.#parseBlockAsExpression(this.#previous());
    }
    
    if (handler == null && cancelBlock == null && finalizer == null) {
      throw this.#error(
          "Expected 'cancel', 'catch' or 'finally' after try block");
    }

    return new TryExpression(body, handler, cancelBlock, finalizer,
        this.#makeLocation(startToken));
  }
  
  #parseExpressionStatement(): ExpressionStatement {
    let startToken = this.#peek();
    let exprStart = this.#current;
    let expr = this.#parseExpression();
    if (this.#recover && this.#current == exprStart &&
        !this.#check(TokenType.Semi) && !this.#check(TokenType.RBrace) && !this.#isAtEnd()) {
      this.#advance();
    }
    if (this.#isBlockEndedExpression(expr)) {
      if (this.#check(TokenType.Semi)) {
        this.#advance();
      }
    } else if (this.#check(TokenType.Semi)) {
      this.#advance();
    } else if (this.#recover) {
      if (this.#atLineBreak() || this.#check(TokenType.RBrace) || this.#check(TokenType.EOF)) {
        this.#recordSyntaxError(this.#error("Expected ';' after expression"));
      } else {
        this.#consume(TokenType.Semi, "Expected ';' after expression");
      }
    } else if (!this.#check(TokenType.RBrace) && !this.#check(TokenType.EOF)) {
      this.#consume(TokenType.Semi, "Expected ';' after expression");
    }
    return new ExpressionStatement(expr, this.#makeLocation(startToken));
  }
  
  #isBlockEndedExpression(expr: Expression): boolean {
    if (expr is MatchExpression) { return true; }
    if (expr is TryExpression) { return true; }
    if (expr is IfExpression) {
      if (expr.alternate == null) {
        return expr.consequent is BlockStatement;
      }
      if (expr.alternate is BlockStatement) { return true; }
      if (expr.alternate is IfExpression) {
        return this.#isBlockEndedExpression(expr.alternate as Expression);
      }
      return false;
    }
    return false;
  }
  
  // ==========================================================================
  // Pattern Parsing
  // ==========================================================================
  
  #parsePattern(isUnderLet: boolean = false): Pattern {
    let startToken = this.#peek();
    
    // Binding pattern: let x or var y
    if (!isUnderLet && (this.#match(TokenType.Let) || this.#match(TokenType.Var))) {
      let kind = if (this.#previous().kind == TokenType.Let) 'let' else 'var';
      let inner = this.#parsePattern(true);
      return new BindingPattern(kind, inner, this.#makeLocation(startToken));
    }

    // Literal patterns: parsed as LiteralPattern nodes so the checker can
    // report them as refutable in variable declarations.
    if (this.#match(TokenType.Number)) {
      let token = this.#previous();
      return new LiteralPattern(this.#parseNumberLiteral(token, startToken), this.#makeLocation(startToken));
    }
    if (this.#match(TokenType.String)) {
      let token = this.#previous();
      return new LiteralPattern(new StringLiteral(token.value, this.#makeLocation(startToken)), this.#makeLocation(startToken));
    }
    if (this.#match(TokenType.True)) {
      return new LiteralPattern(new BooleanLiteral(true, this.#makeLocation(startToken)), this.#makeLocation(startToken));
    }
    if (this.#match(TokenType.False)) {
      return new LiteralPattern(new BooleanLiteral(false, this.#makeLocation(startToken)), this.#makeLocation(startToken));
    }
    if (this.#match(TokenType.Null)) {
      return new LiteralPattern(new NullLiteral(this.#makeLocation(startToken)), this.#makeLocation(startToken));
    }
    
    // Record pattern: { a, b }
    if (this.#match(TokenType.LBrace)) {
      return this.#parseRecordPattern(startToken, isUnderLet, false);
    }
    
    // Array pattern: [a, b]
    if (this.#match(TokenType.LBracket)) {
      return this.#parseArrayPattern(startToken, isUnderLet);
    }
    
    // Tuple pattern with parens: (a, b)
    if (this.#match(TokenType.LParen)) {
      return this.#parseParenTuplePattern(startToken, isUnderLet, false);
    }
    
    // Identifier or class pattern: Identifier or ClassName { fields }
    if (this.#isIdentifier()) {
      let ident = this.#parseIdentifier();
      // `Box<f64>` names an instantiation, so it is a class pattern even
      // without a field list; a bare name here is a binding.
      let typeArguments: GrowableArray<TypeAnnotation> | null =
          if (this.#check(TokenType.Less)) this.#parseTypeArguments() else null;

      // Class pattern: ClassName { ... }
      if (this.#check(TokenType.LBrace)) {
        this.#advance();
        let properties = new Array<BindingProperty>(4);
        while (!this.#check(TokenType.RBrace) && !this.#isAtEnd()) {
          let propStart = this.#peek();
          // Parsed here so the checker can reject it with a pointed
          // message (class fields have no presence).
          if (this.#match(TokenType.Bang)) {
            let absentName = this.#parseIdentifier();
            properties.push(new BindingProperty(absentName,
                new AbsencePattern(this.#makeLocation(propStart)),
                this.#makeLocation(propStart)));
            if (!this.#check(TokenType.RBrace)) {
              this.#consume(TokenType.Comma, "Expected ',' after property");
            }
            continue;
          }
          let name = this.#parseIdentifier();
          var value: Node = new IdentifierPattern(name.name, name.loc);
          if (this.#match(TokenType.Colon)) {
            let subPattern = this.#parsePattern();
            if (let IdentifierPattern {name as targetName} = subPattern) {
              if (targetName != '_') {
                throw this.#error(`Use 'as' to rename a destructured field: '${name.name} as ${targetName}'`);
              }
            }
            value = subPattern;
          } else if (this.#match(TokenType.As)) {
            let newName = this.#parseIdentifier();
            value = new IdentifierPattern(newName.name, newName.loc);
          }
          properties.push(new BindingProperty(name, value, this.#makeLocation(propStart)));
          if (!this.#check(TokenType.RBrace)) {
            this.#consume(TokenType.Comma, "Expected ',' after property");
          }
        }
        this.#consume(TokenType.RBrace, "Expected '}' after class pattern");
        return new ClassPattern(ident, typeArguments, properties, this.#makeLocation(startToken));
      }
      if (typeArguments != null) {
        return new ClassPattern(ident, typeArguments, new Array<BindingProperty>(),
            this.#makeLocation(startToken));
      }

      return new IdentifierPattern(ident.name, ident.loc);
    }

    throw this.#error("Expected pattern");
  }
  
  #parseIdentifierPattern(): IdentifierPattern {
    let startToken = this.#peek();
    if (this.#isIdentifier()) {
      let token = this.#advance();
      return new IdentifierPattern(token.value, this.#makeLocation(startToken));
    }
    throw this.#error("Expected identifier");
  }
  
  #parseRecordPattern(startToken: Token, isUnderLet: boolean, matchContext: boolean): RecordPattern {
    let properties = new Array<BindingProperty>(4);
    var rest: Node | null = null;

    while (!this.#check(TokenType.RBrace) && !this.#isAtEnd()) {
      let propStart = this.#peek();
      // Rest: { x, ...rest } binds the fields the pattern does not name.
      if (this.#match(TokenType.DotDotDot)) {
        let restName = this.#parseIdentifier();
        rest = new IdentifierPattern(restName.name, restName.loc);
        this.#match(TokenType.Comma);
        if (!this.#check(TokenType.RBrace)) {
          throw this.#error("A rest element must be the last element in a record pattern");
        }
        continue;
      }
      // Absence pattern: { !x } asserts the optional field is absent.
      if (this.#match(TokenType.Bang)) {
        let absentName = this.#parseIdentifier();
        properties.push(new BindingProperty(absentName,
            new AbsencePattern(this.#makeLocation(propStart)),
            this.#makeLocation(propStart)));
        if (!this.#check(TokenType.RBrace)) {
          this.#consume(TokenType.Comma, "Expected ',' after property");
        }
        continue;
      }
      let name = this.#parseIdentifier();
      
      // Shorthand: { x } binds x; { x as y } renames; { x: pattern } matches a sub-pattern.
      var value: Node = new IdentifierPattern(name.name, name.loc);
      if (this.#match(TokenType.Colon)) {
        value = if (matchContext) {
          let m = this.#parseMatchPattern();
          m
        } else {
          let p: Node = this.#parsePattern(isUnderLet);
          if (let IdentifierPattern {name as targetName} = p) {
            if (targetName != '_') {
              throw this.#error(`Use 'as' to rename a destructured field: '${name.name} as ${targetName}'`);
            }
          }
          p
        };
      } else if (this.#match(TokenType.As)) {
        // Rename: { x as y }
        let newName = this.#parseIdentifier();
        value = new IdentifierPattern(newName.name, newName.loc);
      }
      
      // Default value: { x = 1 }
      if (this.#match(TokenType.Equals)) {
        let defaultValue = this.#parseExpression();
        value = new AssignmentPattern(value, defaultValue, this.#makeLocation(propStart));
      }
      
      properties.push(new BindingProperty(name, value, this.#makeLocation(propStart)));
      
      if (!this.#check(TokenType.RBrace)) {
        this.#consume(TokenType.Comma, "Expected ',' after property");
      }
    }
    
    this.#consume(TokenType.RBrace, "Expected '}' after record pattern");
    return new RecordPattern(properties, rest, this.#makeLocation(startToken));
  }
  
  // Parse combined record parameter pattern: {name: Type, name as alias: Type = default, ...}
  // In parameter context, : after field name introduces a TypeAnnotation (not a Pattern).
  // Sets this.#combinedTypeAnnotation if any field has a type annotation.
  #parseRecordParamPattern(startToken: Token): RecordPattern {
    let bindingProps = new Array<BindingProperty>(4);
    let typeSigs = new Array<PropertySignature>(4);
    var hasTypeAnnotations = false;
    var rest: Node | null = null;

    while (!this.#check(TokenType.RBrace) && !this.#isAtEnd()) {
      let propStart = this.#peek();
      // Rest: { x, ...rest } binds the fields the pattern does not name.
      if (this.#match(TokenType.DotDotDot)) {
        let restName = this.#parseIdentifier();
        rest = new IdentifierPattern(restName.name, restName.loc);
        this.#match(TokenType.Comma);
        if (!this.#check(TokenType.RBrace)) {
          throw this.#error("A rest element must be the last element in a record pattern");
        }
        continue;
      }
      let name = this.#parseIdentifier();
      
      var value: Node = new IdentifierPattern(name.name, name.loc);
      var propType: TypeAnnotation | null = null;
      
      if (this.#match(TokenType.As)) {
        let newName = this.#parseIdentifier();
        value = new IdentifierPattern(newName.name, newName.loc);
      }
      
      if (this.#match(TokenType.Colon)) {
        propType = this.#parseTypeAnnotation();
        hasTypeAnnotations = true;
      }
      
      if (this.#match(TokenType.Equals)) {
        let defaultExpr = this.#parseExpression();
        value = new AssignmentPattern(value, defaultExpr, this.#makeLocation(propStart));
      }
      
      bindingProps.push(new BindingProperty(name, value, this.#makeLocation(propStart)));
      
      if (propType != null) {
        typeSigs.push(new PropertySignature(name, propType, false, this.#makeLocation(propStart)));
      }
      
      if (!this.#check(TokenType.RBrace)) {
        this.#consume(TokenType.Comma, "Expected ',' after property");
      }
    }
    
    this.#consume(TokenType.RBrace, "Expected '}' after record parameter pattern");

    // Types written on the fields make the parameter's type exactly those
    // fields, which would leave nothing for the rest.
    if (hasTypeAnnotations && rest != null) {
      throw this.#error("A destructured parameter with '...rest' takes its type after the pattern, not on its fields");
    }

    if (hasTypeAnnotations) {
      this.#combinedTypeAnnotation = new RecordTypeAnnotation(typeSigs, null, false, this.#makeLocation(startToken));
    } else {
      this.#combinedTypeAnnotation = null;
    }
    
    return new RecordPattern(bindingProps, rest, this.#makeLocation(startToken));
  }
  
  #parseArrayPattern(startToken: Token, isUnderLet: boolean): ArrayPattern {
    let elements = new Array<Node | null>(4);
    var hasRest = false;
    
    while (!this.#check(TokenType.RBracket) && !this.#isAtEnd()) {
      // Support holes: [a, , c]
      if (this.#match(TokenType.Comma)) {
        if (hasRest) {
          throw this.#error("Rest element cannot be followed by another element");
        }
        elements.push(null);
        continue;
      }

      if (this.#match(TokenType.DotDotDot)) {
        let restToken = this.#previous();
        if (hasRest) {
          throw this.#error("An array pattern may only contain one rest element");
        }
        hasRest = true;
        let restPat = this.#parsePattern(isUnderLet);
        elements.push(new RestPattern(restPat, this.#makeLocation(restToken)));
        if (this.#match(TokenType.Comma)) {
          if (!this.#check(TokenType.RBracket)) {
            throw this.#error("Rest element must be the last element in an array pattern");
          }
        }
        break;
      }

      elements.push(this.#parsePattern(isUnderLet));

      if (!this.#check(TokenType.RBracket)) {
        this.#consume(TokenType.Comma, "Expected ',' in array pattern");
      }
    }
    
    this.#consume(TokenType.RBracket, "Expected ']' after array pattern");
    return new ArrayPattern(elements, this.#makeLocation(startToken));
  }
  
  #parseParenTuplePattern(startToken: Token, isUnderLet: boolean, matchContext: boolean): Pattern {
    let elements = new Array<Node | null>(4);
    var hasRest = false;

    while (!this.#check(TokenType.RParen) && !this.#isAtEnd()) {
      // Support holes: (a, , c)
      if (this.#match(TokenType.Comma)) {
        elements.push(null);
        continue;
      }

      // Rest: (first, ...middle, last) binds the elements between.
      if (this.#match(TokenType.DotDotDot)) {
        let restToken = this.#previous();
        if (hasRest) {
          throw this.#error("A tuple pattern may only contain one rest element");
        }
        hasRest = true;
        let restName = this.#parseIdentifier();
        let restPat = new IdentifierPattern(restName.name, restName.loc);
        elements.push(new RestPattern(restPat, this.#makeLocation(restToken)));
        if (!this.#check(TokenType.RParen)) {
          this.#consume(TokenType.Comma, "Expected ',' in tuple pattern");
        }
        continue;
      }

      let elem = if (matchContext) { this.#parseMatchPattern() } else {
        let p: Node = this.#parsePattern(isUnderLet);
        p
      };

      // In declaration context, detect OR patterns: (A {} | B {}) becomes LogicalPattern
      if (!matchContext && this.#check(TokenType.Pipe)) {
        var orLeft = elem;
        while (this.#match(TokenType.Pipe)) {
          let orRight: Node = this.#parsePattern(isUnderLet);
          orLeft = new LogicalPattern('||', orLeft, orRight, this.#makeLocation(startToken));
        }
        this.#consume(TokenType.RParen, "Expected ')' after pattern");
        return orLeft as Pattern;
      }

      elements.push(elem);

      if (!this.#check(TokenType.RParen)) {
        if (!matchContext && this.#check(TokenType.Pipe)) {
          throw this.#error("Refutable pattern: OR pattern is not allowed in a 'let' or 'var' declaration");
        }
        this.#consume(TokenType.Comma, "Expected ',' in tuple pattern");
      }
    }
    
    this.#consume(TokenType.RParen, "Expected ')' after tuple pattern");
    if (elements.length == 1 && !(elements[0] is RestPattern)) {
      return elements[0] as Pattern;
    }
    return new TuplePattern(elements, this.#makeLocation(startToken));
  }
  
  // ==========================================================================
  // Expression Parsing (Precedence Climbing)
  // ==========================================================================
  
  #parseExpression(): Expression {
    return this.#parseAssignment();
  }
  
  #parseAssignment(): Expression {
    let startToken = this.#peek();
    let expr = this.#parsePipeline();
    
    if (this.#match(TokenType.Equals)) {
      let value = this.#parseAssignment();
      return new AssignmentExpression(expr, value, null, this.#makeLocation(startToken));
    }
    
    let compoundOp = this.#matchCompoundAssignment();
    if (compoundOp != null) {
      let value = this.#parseAssignment();
      return new AssignmentExpression(expr, value, compoundOp, this.#makeLocation(startToken));
    }
    
    return expr;
  }
  
  #matchCompoundAssignment(): String | null {
    if (this.#match(TokenType.PlusEquals)) { return '+'; }
    if (this.#match(TokenType.MinusEquals)) { return '-'; }
    if (this.#match(TokenType.StarStarEquals)) { return '**'; }
    if (this.#match(TokenType.StarEquals)) { return '*'; }
    if (this.#match(TokenType.SlashEquals)) { return '/'; }
    if (this.#match(TokenType.PercentEquals)) { return '%'; }
    if (this.#match(TokenType.QuestionQuestionEquals)) { return '??'; }
    return null;
  }
  
  #parsePipeline(): Expression {
    var expr = this.#parseLogicalOr();
    
    while (this.#match(TokenType.PipeGreater)) {
      let startToken = this.#previous();
      let right = this.#parseLogicalOr();
      expr = new PipelineExpression(expr, right, this.#makeLocation(startToken));
    }
    
    return expr;
  }
  
  #parseLogicalOr(): Expression {
    var expr = this.#parseLogicalAnd();
    
    while (this.#check(TokenType.PipePipe) || this.#check(TokenType.QuestionQuestion)) {
      let op = this.#advance();
      let right = this.#parseLogicalAnd();
      let opStr = op.value;
      expr = new BinaryExpression(opStr, expr, right, this.#makeLocation(op));
    }
    
    return expr;
  }
  
  #parseLogicalAnd(): Expression {
    var expr = this.#parseBitwiseOr();
    
    while (this.#match(TokenType.AmpersandAmpersand)) {
      let startToken = this.#previous();
      let right = this.#parseBitwiseOr();
      expr = new BinaryExpression('&&', expr, right, this.#makeLocation(startToken));
    }
    
    return expr;
  }
  
  #parseBitwiseOr(): Expression {
    var expr = this.#parseBitwiseXor();
    
    while (this.#match(TokenType.Pipe)) {
      let startToken = this.#previous();
      let right = this.#parseBitwiseXor();
      expr = new BinaryExpression('|', expr, right, this.#makeLocation(startToken));
    }
    
    return expr;
  }
  
  #parseBitwiseXor(): Expression {
    var expr = this.#parseBitwiseAnd();
    
    while (this.#match(TokenType.Caret)) {
      let startToken = this.#previous();
      let right = this.#parseBitwiseAnd();
      expr = new BinaryExpression('^', expr, right, this.#makeLocation(startToken));
    }
    
    return expr;
  }
  
  #parseBitwiseAnd(): Expression {
    var expr = this.#parseEquality();
    
    while (this.#match(TokenType.Ampersand)) {
      let startToken = this.#previous();
      let right = this.#parseEquality();
      expr = new BinaryExpression('&', expr, right, this.#makeLocation(startToken));
    }
    
    return expr;
  }
  
  #parseEquality(): Expression {
    var expr = this.#parseComparison();
    
    while (this.#check(TokenType.EqualsEquals) || this.#check(TokenType.BangEquals) ||
           this.#check(TokenType.EqualsEqualsEquals) || this.#check(TokenType.BangEqualsEquals)) {
      let op = this.#advance();
      let right = this.#parseComparison();
      let opStr = op.value;
      expr = new BinaryExpression(opStr, expr, right, this.#makeLocation(op));
    }
    
    return expr;
  }
  
  #parseComparison(): Expression {
    var expr = this.#parseShift();
    
    while (this.#check(TokenType.Less) || this.#check(TokenType.LessEquals) ||
           this.#check(TokenType.Greater) || this.#check(TokenType.GreaterEquals)) {
      let op = this.#advance();
      let right = this.#parseShift();
      let opStr = op.value;
      expr = new BinaryExpression(opStr, expr, right, this.#makeLocation(op));
    }
    
    return expr;
  }
  
  #parseShift(): Expression {
    var expr = this.#parseRange();
    
    while (this.#check(TokenType.LessLess) || this.#check(TokenType.GreaterGreater) ||
           this.#check(TokenType.GreaterGreaterGreater)) {
      let op = this.#advance();
      let right = this.#parseRange();
      let opStr = op.value;
      expr = new BinaryExpression(opStr, expr, right, this.#makeLocation(op));
    }
    
    return expr;
  }
  
  #parseRange(): Expression {
    let startToken = this.#peek();
    
    // Handle prefix range: ..end or ..
    if (this.#match(TokenType.DotDot)) {
      if (this.#check(TokenType.Comma) || this.#check(TokenType.Semi) ||
          this.#check(TokenType.RParen) || this.#check(TokenType.RBracket) ||
          this.#check(TokenType.RBrace)) {
        // .. with no end -> FullRange
        return new RangeExpression(null, null, this.#makeLocation(startToken));
      } else {
        // ..end -> ToRange
        let end = this.#parseAs();
        return new RangeExpression(null, end, this.#makeLocation(startToken));
      }
    }
    
    let left = this.#parseAs();
    
    // Handle postfix range: start.. or bounded range: start..end
    if (this.#match(TokenType.DotDot)) {
      if (this.#check(TokenType.Comma) || this.#check(TokenType.Semi) ||
          this.#check(TokenType.RParen) || this.#check(TokenType.RBracket) ||
          this.#check(TokenType.RBrace)) {
        // start.. with no end -> FromRange
        return new RangeExpression(left, null, this.#makeLocation(startToken));
      } else {
        // start..end -> BoundedRange
        let end = this.#parseAs();
        return new RangeExpression(left, end, this.#makeLocation(startToken));
      }
    }
    
    return left;
  }
  
  #parseAs(): Expression {
    var expr = this.#parseTerm();
    
    while (this.#check(TokenType.As) || this.#check(TokenType.Is)) {
      let op = this.#advance();
      let typeAnnotation = this.#parseTypeAnnotation();
      if (op.kind == TokenType.As) {
        expr = new AsExpression(expr, typeAnnotation, this.#makeLocation(op));
      } else {
        expr = new IsExpression(expr, typeAnnotation, this.#makeLocation(op));
      }
    }
    
    return expr;
  }
  
  #parseTerm(): Expression {
    var expr = this.#parseFactor();
    
    while (this.#check(TokenType.Plus) || this.#check(TokenType.Minus)) {
      let op = this.#advance();
      let right = if (this.#check(TokenType.Semi) || this.#check(TokenType.RParen) || this.#check(TokenType.Comma) || this.#check(TokenType.RBrace) || this.#isAtEnd()) {
        if (this.#recover) {
          this.#recordSyntaxError(this.#error("Unexpected token in expression"));
        }
        let st = this.#peek();
        new Identifier("", this.#makeLocation(st))
      } else {
        this.#parseFactor()
      };
      let opStr = op.value;
      expr = new BinaryExpression(opStr, expr, right, this.#makeLocation(op));
    }
    
    return expr;
  }
  
  #parseFactor(): Expression {
    var expr = this.#parseExponentiation();
    
    while (this.#check(TokenType.Star) || this.#check(TokenType.Slash) || this.#check(TokenType.Percent)) {
      let op = this.#advance();
      let right = if (this.#check(TokenType.Semi) || this.#check(TokenType.RParen) || this.#check(TokenType.Comma) || this.#check(TokenType.RBrace) || this.#isAtEnd()) {
        if (this.#recover) {
          this.#recordSyntaxError(this.#error("Unexpected token in expression"));
        }
        let st = this.#peek();
        new Identifier("", this.#makeLocation(st))
      } else {
        this.#parseExponentiation()
      };
      let opStr = op.value;
      expr = new BinaryExpression(opStr, expr, right, this.#makeLocation(op));
    }
    
    return expr;
  }
  
  #parseExponentiation(): Expression {
    var expr = this.#parseUnary();
    
    if (this.#match(TokenType.StarStar)) {
      let op = this.#previous();
      let right = if (this.#check(TokenType.Semi) || this.#check(TokenType.RParen) || this.#check(TokenType.Comma) || this.#check(TokenType.RBrace) || this.#isAtEnd()) {
        if (this.#recover) {
          this.#recordSyntaxError(this.#error("Unexpected token in expression"));
        }
        let st = this.#peek();
        new Identifier("", this.#makeLocation(st))
      } else {
        this.#parseExponentiation()
      };
      let opStr = op.value;
      expr = new BinaryExpression(opStr, expr, right, this.#makeLocation(op));
    }
    
    return expr;
  }
  
  #parseUnary(): Expression {
    if (this.#check(TokenType.Bang) || this.#check(TokenType.Minus)) {
      let op = this.#advance();
      let argument = this.#parseUnary();
      let opStr = op.value;
      return new UnaryExpression(opStr, argument, true, this.#makeLocation(op));
    }

    // await expr — unary precedence, chains (await await f).
    if (this.#match(TokenType.Await)) {
      let startToken = this.#previous();
      let argument = this.#parseUnary();
      return new AwaitExpression(argument, this.#makeLocation(startToken));
    }

    if (this.#check(TokenType.Throw)) {
      let next = this.#peek2().kind;
      if (next != TokenType.RParen
        && next != TokenType.RBrace
        && next != TokenType.RBracket
        && next != TokenType.Comma
        && next != TokenType.Semi
        && next != TokenType.EOF
        && next != TokenType.Dot) {
        let startToken = this.#advance();
        let argument = this.#parseExpression();
        return new ThrowExpression(argument, this.#makeLocation(startToken));
      }
    }
    
    return this.#parseCall();
  }
  
  #parseCall(): Expression {
    let callStart = this.#peek();
    var expr = this.#parsePrimary();
    
    while (true) {
      if (this.#match(TokenType.LParen)) {
        expr = this.#finishCall(expr, null, false, callStart);
      } else if (this.#check(TokenType.Less) && this.#isGenericCall()) {
        let typeArguments = this.#parseTypeArguments();
        this.#consume(TokenType.LParen, "Expected '(' after type arguments");
        expr = this.#finishCall(expr, typeArguments, false, callStart);
      } else if (this.#match(TokenType.Dot)) {
        if (this.#match(TokenType.LBracket)) {
          var symbolPath: Expression = this.#parseIdentifier();
          while (this.#match(TokenType.Dot)) {
            let prop = this.#parseIdentifier();
            symbolPath = new MemberExpression(symbolPath, prop, false, false, null, this.#makeLocation(callStart));
          }
          this.#consume(TokenType.RBracket, "Expected ']' after symbol member name");
          let property = if (symbolPath is Identifier) {
            symbolPath
          } else {
            (symbolPath as MemberExpression).property
          };
          expr = new MemberExpression(expr, property, false, true, symbolPath, this.#makeLocation(callStart));
        } else if (this.#match(TokenType.Hash)) {
          // Private field access: obj.#field
          let hashToken = this.#previous();
          let fieldId = this.#parseIdentifier();
          let name = new Identifier("#" + fieldId.name, this.#makeLocation(hashToken));
          expr = new MemberExpression(expr, name, false, false, null, this.#makeLocation(callStart));
        } else {
          let name = if (this.#isIdentifier()) {
            this.#parseIdentifier()
          } else {
            if (this.#recover) {
              this.#recordSyntaxError(this.#error("Expected identifier"));
            }
            let startToken = this.#peek();
            new Identifier("", this.#makeLocation(startToken))
          };
          expr = new MemberExpression(expr, name, false, false, null, this.#makeLocation(callStart));
        }
      } else if (this.#match(TokenType.LBracket)) {
        let index = this.#parseExpression();
        this.#consume(TokenType.RBracket, "Expected ']' after index");
        expr = new IndexExpression(expr, index, false, this.#makeLocation(callStart));
      } else if (this.#match(TokenType.QuestionDot)) {
        // Optional chaining
        if (this.#match(TokenType.LBracket)) {
          var symbolPath: Expression = this.#parseIdentifier();
          while (this.#match(TokenType.Dot)) {
            let prop = this.#parseIdentifier();
            symbolPath = new MemberExpression(symbolPath, prop, false, false, null, this.#makeLocation(callStart));
          }
          this.#consume(TokenType.RBracket, "Expected ']' after symbol member name");
          let property = if (symbolPath is Identifier) {
            symbolPath
          } else {
            (symbolPath as MemberExpression).property
          };
          expr = new MemberExpression(expr, property, true, true, symbolPath, this.#makeLocation(callStart));
        } else if (this.#match(TokenType.Hash)) {
          // Private field access with optional chaining: obj?.#field
          let hashToken = this.#previous();
          let fieldId = this.#parseIdentifier();
          let name = new Identifier("#" + fieldId.name, this.#makeLocation(hashToken));
          expr = new MemberExpression(expr, name, true, false, null, this.#makeLocation(callStart));
        } else {
          let name = this.#parseIdentifier();
          expr = new MemberExpression(expr, name, true, false, null, this.#makeLocation(callStart));
        }
      } else if (this.#match(TokenType.QuestionLBracket)) {
        let index = this.#parseExpression();
        this.#consume(TokenType.RBracket, "Expected ']' after index");
        expr = new IndexExpression(expr, index, true, this.#makeLocation(callStart));
      } else if (this.#match(TokenType.QuestionLParen)) {
        expr = this.#finishCall(expr, null, true, callStart);
      } else if (this.#check(TokenType.NoSubstitutionTemplate) || this.#check(TokenType.TemplateHead)) {
        let tagStartToken = this.#peek();
        let quasi = this.#parsePrimary();
        expr = new TaggedTemplateExpression(expr, quasi as TemplateLiteral, this.#makeLocation(tagStartToken));
      } else {
        break;
      }
    }
    
    return expr;
  }
  
  #finishCall(callee: Expression, typeArguments: GrowableArray<TypeAnnotation> | null, optional: boolean, startToken: Token): CallExpression {
    let args = new Array<Expression>(4);
    
    if (!this.#check(TokenType.RParen)) {
      if (this.#check(TokenType.Semi) || this.#check(TokenType.RBrace) || this.#isAtEnd()) {
        if (this.#recover) {
          this.#recordSyntaxError(this.#error("Unexpected token in expression"));
        }
        let st = this.#peek();
        args.push(new Identifier("", this.#makeLocation(st)));
      } else {
        args.push(this.#parseExpression());
        while (this.#match(TokenType.Comma)) {
          if (this.#check(TokenType.RParen)) {
            break;
          }
          if (this.#check(TokenType.Semi) || this.#check(TokenType.RBrace) || this.#isAtEnd()) {
            if (this.#recover) {
              this.#recordSyntaxError(this.#error("Unexpected token in expression"));
            }
            let st = this.#peek();
            args.push(new Identifier("", this.#makeLocation(st)));
            break;
          }
          args.push(this.#parseExpression());
        }
      }
    }
    
    if (this.#check(TokenType.RParen)) {
      this.#advance();
    } else if (this.#recover && (this.#check(TokenType.Semi) || this.#check(TokenType.RBrace) || this.#isAtEnd())) {
      this.#recordSyntaxError(this.#error("Expected ')' after arguments"));
    } else if (!this.#check(TokenType.Semi) && !this.#check(TokenType.RBrace) && !this.#isAtEnd()) {
      this.#consume(TokenType.RParen, "Expected ')' after arguments");
    }
    
    return new CallExpression(callee, args, typeArguments, optional, this.#makeLocation(startToken));
  }
  
  #parsePrimary(): Expression {
    let startToken = this.#peek();
    
    // Boolean literals
    if (this.#match(TokenType.True)) {
      return new BooleanLiteral(true, this.#makeLocation(startToken));
    }
    if (this.#match(TokenType.False)) {
      return new BooleanLiteral(false, this.#makeLocation(startToken));
    }
    
    // Null literal
    if (this.#match(TokenType.Null)) {
      return new NullLiteral(this.#makeLocation(startToken));
    }
    
    // Number literal
    if (this.#match(TokenType.Number)) {
      let token = this.#previous();
      return this.#parseNumberLiteral(token, startToken);
    }
    
    // String literal
    if (this.#match(TokenType.String)) {
      let token = this.#previous();
      return new StringLiteral(token.value, this.#makeLocation(startToken));
    }
    
    // Template literal (no substitution)
    if (this.#match(TokenType.NoSubstitutionTemplate)) {
      let token = this.#previous();
      let quasis = new Array<TemplateElement>(1);
      var raw = token.rawValue;
      if (raw == null) {
        raw = token.value;
      }
      quasis.push(new TemplateElement(token.value, raw, true, this.#makeLocation(token)));
      let expressions = new Array<Expression>(0);
      return new TemplateLiteral(quasis, expressions, this.#makeLocation(startToken));
    }
    
    // Template literal (with substitutions)
    if (this.#match(TokenType.TemplateHead)) {
      return this.#parseTemplateLiteral(startToken);
    }
    
    // This expression
    if (this.#match(TokenType.This)) {
      return new ThisExpression(this.#makeLocation(startToken));
    }
    
    // Super expression
    if (this.#match(TokenType.Super)) {
      return new SuperExpression(this.#makeLocation(startToken));
    }
    
    // Match expression: match (expr) { case ...: ... }
    if (this.#check(TokenType.Match) && this.#peek2().kind == TokenType.LParen) {
      this.#advance();
      return this.#parseMatchExpression(startToken);
    }
    
    // If expression: if (cond) expr else expr
    if (this.#match(TokenType.If)) {
      return this.#parseIfExpression(startToken);
    }
    
    // Try expression: try { ... } catch (e) { ... } finally { ... }
    if (this.#match(TokenType.Try)) {
      return this.#parseTryExpression(startToken);
    }
    
    // Generator function expression: gen (params): Iterator<T> => { ... }
    // (or generic: gen <T>(params): Iterator<T> => { ... })
    if (this.#match(TokenType.Gen)) {
      let genTypeParams: GrowableArray<TypeParameter> | null = if (this.#match(TokenType.Less)) {
        this.#parseTypeParameterList()
      } else {
        null
      };
      this.#consume(TokenType.LParen, "Expected '(' after 'gen'");
      return this.#parseArrowFunction(startToken, genTypeParams, true, false);
    }

    // Async function expression: async (params): Future<T> => { ... }
    if (this.#match(TokenType.Async)) {
      // `async gen (params): Iterator<T> => { ... }`.
      let asyncIsGen = this.#match(TokenType.Gen);
      let asyncTypeParams: GrowableArray<TypeParameter> | null = if (this.#match(TokenType.Less)) {
        this.#parseTypeParameterList()
      } else {
        null
      };
      this.#consume(TokenType.LParen, "Expected '(' after 'async'");
      return this.#parseArrowFunction(startToken, asyncTypeParams, asyncIsGen, true);
    }

    // Generic arrow function: <T>(x: T) => x
    if (this.#check(TokenType.Less) && this.#isGenericArrowFunction()) {
      this.#advance(); // consume '<'
      let typeParams = this.#parseTypeParameterList();
      this.#consume(TokenType.LParen, "Expected '(' after type parameters");
      return this.#parseArrowFunction(startToken, typeParams, false, false);
    }

    // Parenthesized expression, tuple, or arrow function
    if (this.#match(TokenType.LParen)) {
      // Check for arrow function: (params) =>
      if (this.#isArrowFunction()) {
        return this.#parseArrowFunction(startToken, null, false, false);
      }
      
      // Parse first expression; `...t` makes this a tuple, even alone.
      let firstSpread = this.#match(TokenType.DotDotDot);
      let first = this.#parseExpression();

      // If comma follows, it's a tuple literal
      if (firstSpread || this.#match(TokenType.Comma)) {
        let elements = growable<Expression>([first]);
        var spreadIndices: GrowableArray<i32> | null = null;
        if (firstSpread) {
          spreadIndices = growable<i32>([0]);
          this.#match(TokenType.Comma);
        }
        while (!this.#check(TokenType.RParen) && !this.#isAtEnd()) {
          if (this.#match(TokenType.DotDotDot)) {
            spreadIndices ??= new Array<i32>();
            spreadIndices.push(elements.length);
          }
          elements.push(this.#parseExpression());
          if (!this.#match(TokenType.Comma)) {
            break;
          }
        }
        this.#consume(TokenType.RParen, "Expected ')' after tuple");
        return new TupleLiteral(elements, spreadIndices, this.#makeLocation(startToken));
      }
      
      // Single expression: grouping
      this.#consume(TokenType.RParen, "Expected ')' after expression");
      return first;
    }
    
    // Array literal
    if (this.#match(TokenType.LBracket)) {
      return this.#parseArrayLiteral(startToken);
    }
    
    // Record or map literal
    if (this.#match(TokenType.LBrace)) {
      return this.#parseRecordOrMapLiteral(startToken);
    }
    
    // Pipeline placeholder ($)
    if (this.#isIdentifier() && this.#peek().value == '$') {
      let token = this.#advance();
      return new PipePlaceholder(this.#makeLocation(token));
    }
    
    // New expression
    if (this.#match(TokenType.New)) {
      let callee = this.#parseIdentifier();
      var typeArguments: GrowableArray<TypeAnnotation> | null = null;
      if (this.#match(TokenType.Less)) {
        let args = growable<TypeAnnotation>([this.#parseTypeAnnotation()]);
        while (this.#match(TokenType.Comma) && !this.#checkGreater()) {
          args.push(this.#parseTypeAnnotation());
        }
        this.#consumeGreater("Expected '>' after type arguments");
        typeArguments = args;
      }
      var constructorName: Node | null = null;
      if (this.#match(TokenType.Dot)) {
        if (this.#match(TokenType.Hash)) {
          let hashToken = this.#previous();
          let id = this.#parseIdentifier();
          constructorName = new Identifier("#" + id.name, this.#makeLocation(hashToken));
        } else if (this.#match(TokenType.LBracket)) {
          let colStart = this.#previous();
          var symbolExpr: Expression = this.#parseIdentifier();
          while (this.#match(TokenType.Dot)) {
            let prop = this.#parseIdentifier();
            symbolExpr = new MemberExpression(symbolExpr, prop, false, false, null, this.#makeLocation(colStart));
          }
          this.#consume(TokenType.RBracket, "Expected ']' after symbol name");
          constructorName = new SymbolPropertyName(symbolExpr, this.#makeLocation(colStart));
        } else {
          constructorName = this.#parseIdentifier();
        }
      }
      this.#consume(TokenType.LParen, "Expected '(' after class name");
      let args = new Array<Expression>(4);
      if (!this.#check(TokenType.RParen)) {
        args.push(this.#parseExpression());
        while (this.#match(TokenType.Comma) && !this.#check(TokenType.RParen)) {
          args.push(this.#parseExpression());
        }
      }
      this.#consume(TokenType.RParen, "Expected ')' after arguments");
      return new NewExpression(callee, typeArguments, args, constructorName, this.#makeLocation(startToken));
    }
    
    // Identifier (including contextual keywords)
    if (this.#isIdentifier()) {
      return this.#parseIdentifier();
    }
    
    if (this.#recover && (
      this.#check(TokenType.Semi) ||
      this.#check(TokenType.RParen) ||
      this.#check(TokenType.RBracket) ||
      this.#check(TokenType.RBrace) ||
      this.#check(TokenType.Comma) ||
      this.#isAtEnd() ||
      (this.#atLineBreak() && this.#isStatementStart())
    )) {
      this.#recordSyntaxError(this.#error("Unexpected token in expression"));
      return new Identifier("", this.#makeLocation(startToken));
    }

    throw this.#error("Unexpected token in expression");
  }
  
  #parseTemplateLiteral(startToken: Token): TemplateLiteral {
    let headToken = this.#previous();
    let quasis = new Array<TemplateElement>(4);
    let expressions = new Array<Expression>(4);
    
    // Add the head quasi
    var headRaw = headToken.rawValue;
    if (headRaw == null) {
      headRaw = headToken.value;
    }
    quasis.push(new TemplateElement(headToken.value, headRaw, false, this.#makeLocation(headToken)));
    
    // Parse expression
    expressions.push(this.#parseExpression());
    
    // Parse middle parts and tail
    while (this.#match(TokenType.TemplateMiddle)) {
      let midToken = this.#previous();
      var midRaw = midToken.rawValue;
      if (midRaw == null) {
        midRaw = midToken.value;
      }
      quasis.push(new TemplateElement(midToken.value, midRaw, false, this.#makeLocation(midToken)));
      expressions.push(this.#parseExpression());
    }
    
    // Expect tail
    this.#consume(TokenType.TemplateTail, "Expected template tail after expression");
    let tailToken = this.#previous();
    var tailRaw = tailToken.rawValue;
    if (tailRaw == null) {
      tailRaw = tailToken.value;
    }
    quasis.push(new TemplateElement(tailToken.value, tailRaw, true, this.#makeLocation(tailToken)));
    
    return new TemplateLiteral(quasis, expressions, this.#makeLocation(startToken));
  }
  
  #isArrowFunction(): boolean {
    // Look ahead to determine if this is an arrow function
    // The opening '(' has already been consumed by match(), so current
    // points at the first token inside the parentheses.
    // depth starts at 1 to account for the consumed '('.
    
    var depth = 1;
    var i = 0;
    
    // Find matching )
    while (depth > 0) {
      let token = this.#tokens[this.#current + i];
      if (token.kind == TokenType.EOF) {
        return false;
      }
      if (token.kind == TokenType.LParen) {
        depth = depth + 1;
      } else if (token.kind == TokenType.RParen) {
        depth = depth - 1;
      }
      i += 1;
    }
    
    // Check if next token after ) is => or : (return type annotation)
    let nextToken = this.#tokens[this.#current + i];
    if (nextToken.kind == TokenType.Arrow) {
      return true;
    }
    // (...) requires (c) => — a parenthesized expression is never
    // followed by a name, so this can only be an arrow's contract.
    if (this.#isFunctionContractAt(i) &&
        this.#tokens[this.#current + this.#clauseKeywordAt(i) + 1].kind == TokenType.LParen) {
      return true;
    }
    if (nextToken.kind == TokenType.Colon) {
      // Could be return type annotation: (...): Type =>
      // Skip past the type to find =>
      i += 1;
      while (true) {
        let t = this.#tokens[this.#current + i];
        if (t.kind == TokenType.EOF) { return false; }
        if (t.kind == TokenType.Arrow) { return true; }
        if (t.kind == TokenType.Semi) { return false; }
        // Handle nested < > for generic types
        if (t.kind == TokenType.Less) {
          var depth2 = 1;
          i += 1;
          while (depth2 > 0) {
            let t2 = this.#tokens[this.#current + i];
            if (t2.kind == TokenType.EOF) { return false; }
            if (t2.kind == TokenType.Less) { depth2 = depth2 + 1; }
            else if (t2.kind == TokenType.Greater) { depth2 = depth2 - 1; }
            else if (t2.kind == TokenType.GreaterGreater) { depth2 = depth2 - 2; }
            else if (t2.kind == TokenType.GreaterGreaterGreater) { depth2 = depth2 - 3; }
            i += 1;
          }
        // Handle nested { } for record types
        } else if (t.kind == TokenType.LBrace) {
          var depth2 = 1;
          i += 1;
          while (depth2 > 0) {
            let t2 = this.#tokens[this.#current + i];
            if (t2.kind == TokenType.EOF) { return false; }
            if (t2.kind == TokenType.LBrace) { depth2 = depth2 + 1; }
            else if (t2.kind == TokenType.RBrace) { depth2 = depth2 - 1; }
            i += 1;
          }
        } else {
          i += 1;
        }
      }
    }
    return false;
  }
  
  #isGenericArrowFunction(): boolean {
    // Check if <...> is followed by (
    var depth = 1;
    var i = 1; // skip the <
    
    while (depth > 0) {
      let token = this.#tokens[this.#current + i];
      if (token.kind == TokenType.EOF) { return false; }
      if (token.kind == TokenType.Semi || 
          token.kind == TokenType.LBrace || token.kind == TokenType.Plus || 
          token.kind == TokenType.Minus || token.kind == TokenType.Star || 
          token.kind == TokenType.Slash || token.kind == TokenType.Let || 
          token.kind == TokenType.Var || token.kind == TokenType.If || 
          token.kind == TokenType.While || token.kind == TokenType.For ||
          token.kind == TokenType.Return || token.kind == TokenType.AmpersandAmpersand || 
          token.kind == TokenType.PipePipe) {
        return false;
      }
      if (token.kind == TokenType.Less) { depth = depth + 1; }
      else if (token.kind == TokenType.Greater) { depth = depth - 1; }
      else if (token.kind == TokenType.GreaterGreater) { depth = depth - 2; }
      else if (token.kind == TokenType.GreaterGreaterGreater) { depth = depth - 3; }
      i += 1;
    }
    
    // After > should be (
    let nextToken = this.#tokens[this.#current + i];
    return depth == 0 && nextToken.kind == TokenType.LParen;
  }
  
  #isGenericCall(): boolean {
    let end = this.#genericArgumentsEnd();
    return end >= 0 && this.#tokens[this.#current + end].kind == TokenType.LParen;
  }

  /**
   * Offset from the current `<` of the token just past the balanced
   * `>`, or -1 if the angle brackets are not a type-argument list.
   */
  #genericArgumentsEnd(): i32 {
    var depth = 1;
    var i = 1; // skip the <

    while (depth > 0) {
      let token = this.#tokens[this.#current + i];
      if (token.kind == TokenType.EOF) { return -1; }
      // A `{` may open a record type argument (`f<{x: i32}>(...)`); the
      // statement tokens below still end the scan at a block's contents.
      if (token.kind == TokenType.Semi || token.kind == TokenType.Equals ||
          token.kind == TokenType.Plus ||
          token.kind == TokenType.Minus || token.kind == TokenType.Star ||
          token.kind == TokenType.Slash || token.kind == TokenType.Let ||
          token.kind == TokenType.Var || token.kind == TokenType.If ||
          token.kind == TokenType.While || token.kind == TokenType.For ||
          token.kind == TokenType.Return || token.kind == TokenType.AmpersandAmpersand ||
          token.kind == TokenType.PipePipe) {
        return -1;
      }
      if (token.kind == TokenType.Less) {
        depth = depth + 1;
      } else if (token.kind == TokenType.Greater) {
        depth = depth - 1;
      } else if (token.kind == TokenType.GreaterGreater) {
        depth = depth - 2;
      } else if (token.kind == TokenType.GreaterGreaterGreater) {
        depth = depth - 3;
      } else if (token.kind == TokenType.GreaterEquals) {
        return -1;
      }
      i += 1;
    }

    return if (depth == 0) i else -1;
  }

  #parseTypeArguments(): GrowableArray<TypeAnnotation> {
    this.#consume(TokenType.Less, "Expected '<' before type arguments");
    let args = growable<TypeAnnotation>([this.#parseTypeAnnotation()]);
    while (this.#match(TokenType.Comma) && !this.#checkGreater()) {
      args.push(this.#parseTypeAnnotation());
    }
    this.#consumeGreater("Expected '>' after type arguments");
    return args;
  }
  
  #parseTypeParameterList(): GrowableArray<TypeParameter> {
    let params = new Array<TypeParameter>(4);
    
    let startToken = this.#peek();
    // `scoped` is contextual: a modifier only when another identifier
    // follows, so a parameter NAMED scoped (`<scoped>`, `<scoped extends
    // X>`) still parses.
    var isScoped = false;
    if (this.#check(TokenType.Identifier) && this.#peek().value == 'scoped' &&
        this.#peek2().kind == TokenType.Identifier) {
      this.#advance();
      isScoped = true;
    }
    let name = this.#advance().value;

    let constraint: TypeAnnotation | null = if (this.#match(TokenType.Extends)) {
      this.#parseTypeAnnotation()
    } else {
      null
    };

    let defaultType: TypeAnnotation | null = if (this.#match(TokenType.Equals)) {
      this.#parseTypeAnnotation()
    } else {
      null
    };

    params.push(new TypeParameter(name, constraint, defaultType, isScoped, this.#makeLocation(startToken)));
    
    while (this.#match(TokenType.Comma) && !this.#checkGreater()) {
      let tpStart = this.#peek();
      var tpScoped = false;
      if (this.#check(TokenType.Identifier) && this.#peek().value == 'scoped' &&
          this.#peek2().kind == TokenType.Identifier) {
        this.#advance();
        tpScoped = true;
      }
      let tpName = this.#advance().value;

      let tpConstraint: TypeAnnotation | null = if (this.#match(TokenType.Extends)) {
        this.#parseTypeAnnotation()
      } else {
        null
      };

      let tpDefault: TypeAnnotation | null = if (this.#match(TokenType.Equals)) {
        this.#parseTypeAnnotation()
      } else {
        null
      };

      params.push(new TypeParameter(tpName, tpConstraint, tpDefault, tpScoped, this.#makeLocation(tpStart)));
    }
    
    this.#consumeGreater("Expected '>' after type parameters");
    return params;
  }
  
  #parseArrowFunction(startToken: Token, typeParameters: GrowableArray<TypeParameter> | null, isGenerator: boolean, isAsync: boolean): FunctionExpression {
    // We're after the '('
    let params = this.#parseParameters();

    this.#consume(TokenType.RParen, "Expected ')' after parameters");

    // Optional return type
    let returnType: TypeAnnotation | null = if (this.#match(TokenType.Colon)) {
      this.#parseTypeAnnotation()
    } else {
      null
    };

    let contracts = this.#parseFunctionContracts();

    this.#consume(TokenType.Arrow, "Expected '=>' after parameters");

    // Body: expression or block
    if (this.#check(TokenType.LBrace)) {
      let blockStart = this.#advance();
      let body = this.#parseBlockStatement(blockStart);
      return new FunctionExpression(typeParameters, params, returnType, body, isGenerator, isAsync, contracts, this.#makeLocation(startToken));
    } else {
      if (isGenerator) {
        throw this.#error("Generator functions require a block body");
      }
      // Async expression bodies are fine: await is an expression, and
      // an awaitless async body still runs eagerly to completion.
      let body = this.#parseExpression();
      return new FunctionExpression(typeParameters, params, returnType, body, false, isAsync, contracts, this.#makeLocation(startToken));
    }
  }
  
  #parseParameters(): GrowableArray<Parameter> {
    let params = new Array<Parameter>(4);
    
    if (!this.#check(TokenType.RParen)) {
      params.push(this.#parseParameter());
      while (this.#match(TokenType.Comma) && !this.#check(TokenType.RParen)) {
        params.push(this.#parseParameter());
      }
    }
    
    return params;
  }
  
  #parseParameter(): Parameter {
    let startToken = this.#peek();
    
    // Destructured record parameter: {x: i32, y: i32} or {x, y}: Type or {x, y}
    if (this.#check(TokenType.LBrace)) {
      let braceToken = this.#advance(); // consume '{'
      let pattern = this.#parseRecordParamPattern(braceToken);
      let combinedType = this.#combinedTypeAnnotation;
      this.#combinedTypeAnnotation = null;
      
      // Type annotation: explicit :Type after }, or combined from field types
      let typeAnnotation: TypeAnnotation | null = if (this.#match(TokenType.Colon)) {
        this.#parseTypeAnnotation()
      } else if (combinedType != null) {
        combinedType
      } else {
        null
      };
      
      // Default value
      var optional = false;
      var defaultValue: Expression | null = null;
      if (this.#match(TokenType.Equals)) {
        defaultValue = this.#parseExpression();
        optional = true;
      }
      
      let syntheticName = new Identifier(`$$destruct_${this.#destructParamCounter}`, this.#makeLocation(startToken));
      this.#destructParamCounter = this.#destructParamCounter + 1;
      return new Parameter(syntheticName, pattern, typeAnnotation, optional, defaultValue, false, this.#makeLocation(startToken));
    }
    
    // Destructured tuple parameter: (a, b): Type or (a, b)
    if (this.#check(TokenType.LParen)) {
      let parenToken = this.#advance(); // consume '('
      let pattern = this.#parseParenTuplePattern(parenToken, false, false);
      
      // Type annotation (optional - contextual typing)
      let typeAnnotation2: TypeAnnotation | null = if (this.#match(TokenType.Colon)) {
        this.#parseTypeAnnotation()
      } else {
        null
      };
      
      // Default value
      var optional2 = false;
      var defaultValue2: Expression | null = null;
      if (this.#match(TokenType.Equals)) {
        defaultValue2 = this.#parseExpression();
        optional2 = true;
      }
      
      let syntheticName = new Identifier(`$$destruct_${this.#destructParamCounter}`, this.#makeLocation(startToken));
      this.#destructParamCounter = this.#destructParamCounter + 1;
      return new Parameter(syntheticName, pattern, typeAnnotation2, optional2, defaultValue2, false, this.#makeLocation(startToken));
    }

    // Destructured array parameter: [a, b]: Type or [a, b]
    if (this.#check(TokenType.LBracket)) {
      let bracketToken = this.#advance(); // consume '['
      let pattern = this.#parseArrayPattern(bracketToken, false);
      
      // Type annotation (optional - contextual typing)
      let typeAnnotation3: TypeAnnotation | null = if (this.#match(TokenType.Colon)) {
        this.#parseTypeAnnotation()
      } else {
        null
      };
      
      // Default value
      var optional3 = false;
      var defaultValue3: Expression | null = null;
      if (this.#match(TokenType.Equals)) {
        defaultValue3 = this.#parseExpression();
        optional3 = true;
      }
      
      let syntheticName = new Identifier(`$$destruct_${this.#destructParamCounter}`, this.#makeLocation(startToken));
      this.#destructParamCounter = this.#destructParamCounter + 1;
      return new Parameter(syntheticName, pattern, typeAnnotation3, optional3, defaultValue3, false, this.#makeLocation(startToken));
    }
    
    // Check for this.field constructor parameter
    var isThisParam = false;
    if (this.#check(TokenType.This) && this.#peek2().kind == TokenType.Dot) {
      this.#advance(); // consume 'this'
      this.#advance(); // consume '.'
      isThisParam = true;
    }
    
    let name = this.#parseIdentifier();
    
    // Parameters cannot be marked optional with `?`; use a default value instead.
    if (this.#match(TokenType.Question)) {
      throw this.#error("Parameters cannot be optional. Use a default value: 'name: Type = default'.");
    }
    var optional3 = false;
    
    // Type annotation (optional for this.field params)
    let typeAnnotation2: TypeAnnotation | null = if (this.#match(TokenType.Colon)) {
      this.#parseTypeAnnotation()
    } else {
      null
    };
    
    // Default value
    var defaultValue3: Expression | null = null;
    if (this.#match(TokenType.Equals)) {
      defaultValue3 = this.#parseExpression();
      optional3 = true;
    }
    
    return new Parameter(name, null, typeAnnotation2, optional3, defaultValue3, isThisParam, this.#makeLocation(startToken));
  }
  
  #parseArrayLiteral(startToken: Token): ArrayLiteral {
    let elements = new Array<Expression>(8);
    
    while (!this.#check(TokenType.RBracket) && !this.#isAtEnd()) {
      elements.push(this.#parseExpression());
      if (!this.#check(TokenType.RBracket)) {
        this.#consume(TokenType.Comma, "Expected ',' after array element");
      }
    }
    
    this.#consume(TokenType.RBracket, "Expected ']' after array");
    
    return new ArrayLiteral(elements, this.#makeLocation(startToken));
  }
  
  #parseRecordOrMapLiteral(startToken: Token): Expression {
    // Empty: {} → empty record
    if (this.#check(TokenType.RBrace)) {
      this.#advance();
      return new RecordLiteral(
        new Array<Node>(0),
        this.#makeLocation(startToken)
      );
    }
    
    // Spread element: definitely a record
    if (this.#check(TokenType.DotDotDot)) {
      let properties = new Array<Node>(4);
      return this.#parseRecordProperties(startToken, properties);
    }
    
    // Parse the first expression to determine record vs map
    let firstToken = this.#peek();
    let firstExpr = this.#parseExpression();
    
    // If followed by =>, it's a map literal
    if (this.#match(TokenType.Arrow)) {
      let firstValue = this.#parseExpression();
      let entries = growable<MapEntry>([
        new MapEntry(firstExpr, firstValue, this.#makeLocation(startToken)),
      ]);
      
      while (this.#match(TokenType.Comma)) {
        if (this.#check(TokenType.RBrace)) {
          break; // trailing comma
        }
        let entryStart = this.#peek();
        let key = this.#parseExpression();
        this.#consume(TokenType.Arrow, "Expected '=>' in map entry");
        let value = this.#parseExpression();
        entries.push(new MapEntry(key, value, this.#makeLocation(entryStart)));
      }
      
      this.#consume(TokenType.RBrace, "Expected '}' after map literal");
      return new MapLiteral(entries, this.#makeLocation(startToken));
    }
    
    // Otherwise it's a record — first expression must be an identifier
    if (!(firstExpr is Identifier)) {
      throw this.#error(
        "A record field is named by an identifier; a map entry is written 'key => value'.",
        firstToken
      );
    }
    let name = firstExpr as Identifier;
    let value: Expression = if (this.#match(TokenType.Colon)) {
      this.#parseExpression()
    } else {
      name
    };
    
    let properties = growable<Node>([
      new PropertyAssignment(name, value, this.#makeLocation(startToken)),
    ]);
    return this.#parseRecordProperties(startToken, properties);
  }
  
  #parseRecordProperties(startToken: Token, properties: GrowableArray<Node>): RecordLiteral {
    while (this.#match(TokenType.Comma) || this.#check(TokenType.DotDotDot)) {
      if (this.#check(TokenType.RBrace)) {
        break; // trailing comma
      }
      if (this.#match(TokenType.DotDotDot)) {
        let spreadStart = this.#previous();
        let argument = this.#parseExpression();
        properties.push(new SpreadElement(argument, this.#makeLocation(spreadStart)));
      } else {
        let propStart = this.#peek();
        let propName = this.#parseIdentifier();
        let propValue: Expression = if (this.#match(TokenType.Colon)) {
          this.#parseExpression()
        } else {
          propName
        };
        properties.push(new PropertyAssignment(propName, propValue, this.#makeLocation(propStart)));
      }
    }
    
    this.#consume(TokenType.RBrace, "Expected '}' after record");
    return new RecordLiteral(properties, this.#makeLocation(startToken));
  }
  
  // ==========================================================================
  // Type Annotation Parsing
  // ==========================================================================
  
  #parseTypeAnnotation(): TypeAnnotation {
    let startToken = this.#peek();
    let type = this.#parsePostfixType();

    // Check for union type: T | U
    if (this.#check(TokenType.Pipe)) {
      let types = growable<TypeAnnotation>([type]);

      while (this.#match(TokenType.Pipe)) {
        types.push(this.#parsePostfixType());
      }

      return new UnionTypeAnnotation(types, this.#makeLocation(startToken));
    }

    return type;
  }

  // Nullable shorthand: T? is T | null. Binds tighter than `|`, so
  // `A | B?` is `A | (B | null)`; parenthesize for the other reading.
  #parsePostfixType(): TypeAnnotation {
    let startToken = this.#peek();
    var annotation = this.#parsePrimaryType();
    while (this.#match(TokenType.Question)) {
      annotation = new NullableTypeAnnotation(annotation, this.#makeLocation(startToken));
    }
    return annotation;
  }

  // `?` after a name means "may be absent" and fields are never absent —
  // only record properties and parameters can be optional.
  #rejectOptionalField(): void {
    if (this.#check(TokenType.Question)) {
      throw this.#error("Fields cannot be optional. For a field that may be null, use a nullable type: 'name: Type?'.");
    }
  }

  #parsePrimaryType(): TypeAnnotation {
    let startToken = this.#peek();
    
    // this type
    if (this.#check(TokenType.This)) {
      this.#advance();
      return new ThisTypeAnnotation(this.#makeLocation(startToken));
    }
    
    // Boolean literal types: true / false
    if (this.#check(TokenType.True)) {
      this.#advance();
      return new LiteralTypeAnnotation(new BooleanLiteral(true, this.#makeLocation(startToken)), this.#makeLocation(startToken));
    }
    if (this.#check(TokenType.False)) {
      this.#advance();
      return new LiteralTypeAnnotation(new BooleanLiteral(false, this.#makeLocation(startToken)), this.#makeLocation(startToken));
    }
    
    // Null type
    if (this.#check(TokenType.Null)) {
      this.#advance();
      return new NamedTypeAnnotation('null', null, false, this.#makeLocation(startToken));
    }
    
    // Number literal type
    if (this.#check(TokenType.Number)) {
      let token = this.#advance();
      return new LiteralTypeAnnotation(this.#parseNumberLiteral(token, startToken), this.#makeLocation(startToken));
    }
    
    // String literal type
    if (this.#check(TokenType.String)) {
      let token = this.#advance();
      return new LiteralTypeAnnotation(new StringLiteral(token.value, this.#makeLocation(startToken)), this.#makeLocation(startToken));
    }
    
    // `inline T`: the operand is a whole union, so `inline A | B` is
    // `inline (A | B)`, and so is `A | inline B | C` from `B` on.
    // `inline? T` unboxes a type parameter's argument when it can be.
    if (this.#match(TokenType.Inline)) {
      let ifPossible = this.#match(TokenType.Question);
      let operand = this.#parseTypeAnnotation();
      return new InlineTypeAnnotation(operand, ifPossible, this.#makeLocation(startToken));
    }
    
    // Parenthesized: function type or tuple type
    if (this.#check(TokenType.LParen)) {
      return this.#parseFunctionOrTupleType(startToken);
    }
    
    // Record type: { x: i32, y: i32 }
    if (this.#check(TokenType.LBrace)) {
      return this.#parseRecordType(startToken);
    }
    
    // Named type or primitive
    if (this.#isIdentifier()) {
      let name = this.#advance().value;

      // Check for type arguments: Type<T>
      var typeArgs: GrowableArray<TypeAnnotation> | null = null;
      var elementsMutable = false;
      if (this.#match(TokenType.Less)) {
        // `array<var T>` — the element slot's mutability, part of the
        // grammar of the builtin array type constructor. The checker
        // rejects the modifier on any name that does not resolve to it.
        if (this.#check(TokenType.Var)) {
          this.#advance();
          elementsMutable = true;
        }
        let args = growable<TypeAnnotation>([this.#parseTypeAnnotation()]);
        while (this.#match(TokenType.Comma) && !this.#checkGreater()) {
          args.push(this.#parseTypeAnnotation());
        }
        this.#consumeGreater("Expected '>' after type arguments");
        typeArgs = args;
      }

      return new NamedTypeAnnotation(name, typeArgs, elementsMutable, this.#makeLocation(startToken));
    }
    
    if (this.#recover && (
      this.#check(TokenType.Equals) ||
      this.#check(TokenType.Semi) ||
      this.#check(TokenType.RParen) ||
      this.#check(TokenType.RBrace) ||
      this.#check(TokenType.Comma) ||
      this.#isAtEnd() ||
      this.#atLineBreak()
    )) {
      this.#recordSyntaxError(this.#error("Expected type annotation"));
      return new NamedTypeAnnotation("", null, false, this.#makeLocation(startToken));
    }

    throw this.#error("Expected type annotation");
  }
  
  #parseFunctionOrTupleType(startToken: Token): TypeAnnotation {
    this.#advance(); // consume '('
    
    // Empty parens: () => ReturnType (function type with no params)
    if (this.#check(TokenType.RParen)) {
      this.#advance(); // consume ')'
      // Must be followed by '=>' for function type
      this.#consume(TokenType.Arrow, "Expected '=>' after '()'");
      let returnType = this.#parseTypeAnnotation();
      return new FunctionTypeAnnotation(
        new Array<String>(0),
        new Array<TypeAnnotation>(0),
        returnType,
        this.#makeLocation(startToken));
    }
    
    // Try to determine if this is a function type or tuple type
    // Function type has named params: (name: Type, ...) => ReturnType
    // Tuple type has just types: (Type1, Type2)
    // Heuristic: if we see Identifier followed by ':', it's a function type
    if (this.#isIdentifier() && this.#peek2().kind == TokenType.Colon) {
      // Function type
      let paramNames = new Array<String>(4);
      let params = new Array<TypeAnnotation>(4);
      
      // Parse first param
      let paramName = this.#advance().value;
      this.#consume(TokenType.Colon, "Expected ':' after parameter name");
      let paramType = this.#parseTypeAnnotation();
      paramNames.push(paramName);
      params.push(paramType);
      
      // Parse remaining params
      while (this.#match(TokenType.Comma) && !this.#check(TokenType.RParen)) {
        let nextName = this.#advance().value;
        this.#consume(TokenType.Colon, "Expected ':' after parameter name");
        let nextType = this.#parseTypeAnnotation();
        paramNames.push(nextName);
        params.push(nextType);
      }
      
      this.#consume(TokenType.RParen, "Expected ')' after function type parameters");
      this.#consume(TokenType.Arrow, "Expected '=>' after function type parameters");
      let returnType = this.#parseTypeAnnotation();
      
      return new FunctionTypeAnnotation(paramNames, params, returnType, this.#makeLocation(startToken));
    }
    
    // Tuple type: (Type1, Type2), with `...T` spreads among the elements
    // Or parenthesized type: (Type)
    let elementTypes = new Array<TypeAnnotation>(4);
    var spreadIndices: GrowableArray<i32> | null = null;
    while (true) {
      if (this.#match(TokenType.DotDotDot)) {
        spreadIndices ??= new Array<i32>();
        spreadIndices.push(elementTypes.length);
      }
      elementTypes.push(this.#parseTypeAnnotation());
      if (!this.#match(TokenType.Comma) || this.#check(TokenType.RParen)) {
        break;
      }
    }
    this.#consume(TokenType.RParen, "Expected ')' after tuple type elements");

    // Single element is just a parenthesized type, not a tuple — unless
    // it is a spread: `(...R)` is the tuple R stands for.
    if (elementTypes.length == 1 && spreadIndices == null) {
      return elementTypes[0];
    }

    return new TupleTypeAnnotation(elementTypes, spreadIndices, this.#makeLocation(startToken));
  }
  
  #parseRecordType(startToken: Token): TypeAnnotation {
    this.#advance(); // consume '{'
    let properties = new Array<PropertySignature>(4);
    var spreads: GrowableArray<TypeAnnotation> | null = null;
    var isExistential = false;

    while (!this.#check(TokenType.RBrace) && !this.#isAtEnd()) {
      // Spread: ...T
      if (this.#match(TokenType.DotDotDot)) {
        // A bare trailing `...`: an existential record type.
        if (this.#check(TokenType.RBrace) ||
            (this.#check(TokenType.Comma) && this.#peek2().kind == TokenType.RBrace)) {
          this.#match(TokenType.Comma);
          isExistential = true;
          continue;
        }
        let spreadType = this.#parseTypeAnnotation();
        spreads ??= new Array<TypeAnnotation>();
        spreads.push(spreadType);
        if (!this.#check(TokenType.RBrace)) {
          this.#consume(TokenType.Comma, "Expected ',' between record type properties");
        }
        continue;
      }
      let propStartToken = this.#peek();
      let propName = this.#parseIdentifier();
      
      // Check for optional: name?:
      let optional = this.#match(TokenType.Question);
      
      this.#consume(TokenType.Colon, "Expected ':' after property name in record type");
      let propType = this.#parseTypeAnnotation();
      
      properties.push(new PropertySignature(propName, propType, optional, this.#makeLocation(propStartToken)));
      
      if (!this.#check(TokenType.RBrace)) {
        this.#consume(TokenType.Comma, "Expected ',' between record type properties");
      }
    }
    
    this.#consume(TokenType.RBrace, "Expected '}' after record type");
    return new RecordTypeAnnotation(properties, spreads, isExistential, this.#makeLocation(startToken));
  }
  
  /**
   * Consume a '>' token in type context. Handles '>>' and '>>>' by consuming
   * one '>' and leaving the rest for subsequent parsing via #extraGreaters.
   */
  #consumeGreater(message: String): Token {
    // Check if we have a pending '>' from a previous '>>' split
    if (this.#extraGreaters > 0) {
      this.#extraGreaters = this.#extraGreaters - 1;
      return this.#previous();
    }
    
    if (this.#check(TokenType.Greater)) {
      return this.#advance();
    }
    
    if (this.#check(TokenType.GreaterGreater)) {
      // '>>' in type context: consume as one '>' and mark one pending
      this.#extraGreaters = this.#extraGreaters + 1;
      return this.#advance();
    }
    
    if (this.#check(TokenType.GreaterGreaterGreater)) {
      // '>>>' in type context: consume as one '>' and mark two pending
      this.#extraGreaters = this.#extraGreaters + 2;
      return this.#advance();
    }
    
    throw this.#error(message);
  }
  
  #checkGreater(): boolean {
    return this.#check(TokenType.Greater) || this.#check(TokenType.GreaterGreater) || this.#check(TokenType.GreaterGreaterGreater);
  }
  
  // ==========================================================================
  // Helper Methods
  // ==========================================================================
  
  // Check if `[` after let/var starts a symbol property name.
  // `var [sym]: Type` → Var(+0), LBracket(+1) → symbol field
  // `var: Type`       → Var(+0), Colon(+1)    → field named 'var'
  #isSymbolFieldAfterKeyword(): boolean {
    return this.#tokens[this.#current + 1].kind == TokenType.LBracket;
  }
  
  #isIdentifier(): boolean {
    return this.#isIdentifierKind(this.#peek().kind);
  }

  /** Identifier, or one of the contextual keywords usable as a name. */
  #isIdentifierKind(t: TokenType): boolean {
    return t == TokenType.Identifier
      || t == TokenType.From
      || t == TokenType.Type
      || t == TokenType.As
      || t == TokenType.Is
      || t == TokenType.On
      || t == TokenType.Abstract
      || t == TokenType.Declare
      || t == TokenType.Mixin
      || t == TokenType.Decorator
      || t == TokenType.Operator
      || t == TokenType.Static
      || t == TokenType.Extension
      || t == TokenType.Distinct
      || t == TokenType.Opaque
      || t == TokenType.Final
      || t == TokenType.Extends
      || t == TokenType.Implements
      || t == TokenType.With
      || t == TokenType.Case
      || t == TokenType.Match
      || t == TokenType.Throw
      || t == TokenType.Sealed;
  }

  #parseIdentifier(): Identifier {
    let startToken = this.#peek();
    if (this.#isIdentifier()) {
      let token = this.#advance();
      return new Identifier(token.value, this.#makeLocation(startToken));
    }
    throw this.#error("Expected identifier");
  }
  
  // ==========================================================================
  // Class Declarations
  // ==========================================================================
  
  /**
   * True when the current token is the contextual modifier `resource` and a
   * class declaration follows it. Keeps `resource` usable as an identifier.
   */
  #isResourceClassAhead(): boolean {
    if (!this.#check(TokenType.Identifier) || this.#peek().value != 'resource') {
      return false;
    }
    let next = this.#peek2().kind;
    return next == TokenType.Class || next == TokenType.Final ||
        next == TokenType.Abstract;
  }

  #parseClassDeclarationEntry(exported: boolean, startToken: Token, isResource: boolean): ClassDeclaration {
    var isFinal = false;
    var isAbstract = false;
    var isExtension = false;

    if (this.#match(TokenType.Final)) {
      isFinal = true;
      // final extension class
      if (this.#check(TokenType.Extension)) {
        isExtension = true;
        this.#advance();
      }
    } else if (this.#match(TokenType.Abstract)) {
      isAbstract = true;
    } else if (this.#match(TokenType.Extension)) {
      isExtension = true;
    }

    this.#consume(TokenType.Class, "Expected 'class'");
    if (isResource && isExtension) {
      // An extension class re-presents an existing representation (a
      // primitive, an array); a resource class is defined by having no
      // unwrapped form. The two cannot both hold.
      throw this.#error("'resource' cannot be combined with 'extension'");
    }
    return this.#parseClassDeclaration(exported, isFinal, isAbstract, isExtension, false, startToken, isResource);
  }
  
  #parseSealedClassEntry(exported: boolean, startToken: Token): ClassDeclaration {
    this.#consume(TokenType.Sealed, "Expected 'sealed'");
    // sealed abstract class ...
    let isAbstract = this.#match(TokenType.Abstract);
    this.#consume(TokenType.Class, "Expected 'class' after 'sealed'");
    return this.#parseClassDeclaration(exported, false, isAbstract, false, true, startToken, false);
  }
  
  #parseClassDeclaration(exported: boolean, isFinal: boolean, isAbstract: boolean, isExtension: boolean, isSealed: boolean, startToken: Token, isResource: boolean): ClassDeclaration {
    let name = this.#parseIdentifier();
    
    // Type parameters: class Foo<T, U>
    let typeParameters: GrowableArray<TypeParameter> | null = if (this.#match(TokenType.Less)) {
      this.#parseTypeParameterList()
    } else {
      null
    };
    
    // Extension class: on TargetType. An extension class that extends
    // another extension class may leave the clause out and take the
    // superclass's underlying type; writing it is still allowed, and
    // the checker requires the two to agree.
    var onType: TypeAnnotation | null = null;
    if (isExtension && !this.#check(TokenType.Extends)) {
      this.#consume(TokenType.On, "Expected 'on' after extension class name");
      onType = this.#parseTypeAnnotation();
    }
    
    // Case class parameters: class Point(x: f64, y: f64)
    var caseParams: GrowableArray<CaseClassParam> | null = null;
    if (!isExtension && this.#match(TokenType.LParen)) {
      let cps = new Array<CaseClassParam>(4);
      if (!this.#check(TokenType.RParen)) {
        cps.push(this.#parseCaseClassParam());
        while (this.#match(TokenType.Comma) && !this.#check(TokenType.RParen)) {
          cps.push(this.#parseCaseClassParam());
        }
      }
      this.#consume(TokenType.RParen, "Expected ')' after case class parameters");
      caseParams = cps;
    }
    
    // Extends clause
    var superClass: TypeAnnotation | null = null;
    if (this.#match(TokenType.Extends)) {
      if (this.#check(TokenType.With) || this.#check(TokenType.Implements) || this.#check(TokenType.LBrace) || this.#isAtEnd()) {
        if (this.#recover) {
          this.#recordSyntaxError(this.#error("Expected type annotation"));
        }
        let st = this.#peek();
        superClass = new NamedTypeAnnotation("", null, false, this.#makeLocation(st));
      } else {
        superClass = this.#parseTypeAnnotation();
      }
    }
    
    // With clause (mixins)
    var mixins: GrowableArray<TypeAnnotation> | null = null;
    if (this.#match(TokenType.With)) {
      let ms = new Array<TypeAnnotation>(4);
      if (this.#check(TokenType.Implements) || this.#check(TokenType.LBrace) || this.#isAtEnd()) {
        if (this.#recover) {
          this.#recordSyntaxError(this.#error("Expected type annotation"));
        }
        let st = this.#peek();
        ms.push(new NamedTypeAnnotation("", null, false, this.#makeLocation(st)));
      } else {
        ms.push(this.#parseTypeAnnotation());
        while (this.#match(TokenType.Comma)) {
          if (this.#check(TokenType.Implements) || this.#check(TokenType.LBrace) || this.#isAtEnd()) {
            if (this.#recover) {
              this.#recordSyntaxError(this.#error("Expected type annotation"));
            }
            let st = this.#peek();
            ms.push(new NamedTypeAnnotation("", null, false, this.#makeLocation(st)));
          } else {
            ms.push(this.#parseTypeAnnotation());
          }
        }
      }
      mixins = ms;
    }
    
    // Implements clause
    var implementsList: GrowableArray<TypeAnnotation> | null = null;
    if (this.#match(TokenType.Implements)) {
      let impls = new Array<TypeAnnotation>(4);
      if (this.#check(TokenType.LBrace) || this.#isAtEnd()) {
        if (this.#recover) {
          this.#recordSyntaxError(this.#error("Expected type annotation"));
        }
        let st = this.#peek();
        impls.push(new NamedTypeAnnotation("", null, false, this.#makeLocation(st)));
      } else {
        impls.push(this.#parseTypeAnnotation());
        while (this.#match(TokenType.Comma)) {
          if (this.#check(TokenType.LBrace) || this.#isAtEnd()) {
            if (this.#recover) {
              this.#recordSyntaxError(this.#error("Expected type annotation"));
            }
            let st = this.#peek();
            impls.push(new NamedTypeAnnotation("", null, false, this.#makeLocation(st)));
          } else {
            impls.push(this.#parseTypeAnnotation());
          }
        }
      }
      implementsList = impls;
    }
    
    // Body is optional for case classes
    let body = new Array<Node>(8);
    let sealedVariants = new Array<SealedVariant>(4);
    if (this.#match(TokenType.LBrace)) {
      while (!this.#check(TokenType.RBrace) && !this.#isAtEnd()) {
        if (this.#recover) {
          let posBefore = this.#current;
          try {
            if (isSealed && this.#check(TokenType.Case)) {
              this.#parseSealedVariants(sealedVariants);
            } else {
              body.push(this.#parseClassMember());
            }
          } catch (e) {
            this.#recordSyntaxError(e);
            this.#synchronizeClassMember(posBefore);
          }
          if (this.#current == posBefore && !this.#check(TokenType.RBrace) && !this.#isAtEnd()) {
            this.#advance();
          }
        } else {
          if (isSealed && this.#check(TokenType.Case)) {
            this.#parseSealedVariants(sealedVariants);
          } else {
            body.push(this.#parseClassMember());
          }
        }
      }
      if (this.#recover && !this.#check(TokenType.RBrace)) {
        this.#recordSyntaxError(this.#error("Expected '}' after class body"));
      } else {
        this.#consume(TokenType.RBrace, "Expected '}' after class body");
      }
    } else if (caseParams == null) {
      this.#consume(TokenType.LBrace, "Expected '{' before class body");
    }
    
    // A resource class with no explicit superclass extends `Resource`, the
    // root that holds the lifecycle flag. Synthesized here rather than in
    // the checker so that everything downstream — scope resolution, member
    // inheritance, vtable layout, the struct's field list — sees an ordinary
    // extends clause and needs no special case. `Resource` is its own root
    // and must not extend itself.
    var effectiveSuper = superClass;
    if (isResource && effectiveSuper == null && name.name != "Resource") {
      effectiveSuper = new NamedTypeAnnotation(
        "Resource", null, false, this.#makeLocation(startToken));
    }

    return new ClassDeclaration(
      name, typeParameters, caseParams, effectiveSuper, mixins, implementsList,
      body, exported, isFinal, isAbstract, isExtension, isSealed,
      if (sealedVariants.length > 0) { sealedVariants } else { null },
      onType, isResource, this.#makeLocation(startToken)
    );
  }
  
  #parseCaseClassParam(): CaseClassParam {
    let paramStart = this.#peek();
    let mutability: String | null = if (this.#match(TokenType.Var)) {
      'var'
    } else if (this.#match(TokenType.Let)) {
      'let'
    } else {
      null
    };
    let paramName = this.#parseIdentifier();
    if (this.#match(TokenType.Question)) {
      throw this.#error("Parameters cannot be optional. Use a default value: 'name: Type = default'.");
    }
    this.#consume(TokenType.Colon, "Expected ':' after case class parameter name");
    let typeAnnotation = this.#parseTypeAnnotation();
    let defaultValue: Expression | null = if (this.#match(TokenType.Equals)) {
      this.#parseExpression()
    } else {
      null
    };
    return new CaseClassParam(paramName, typeAnnotation, mutability, defaultValue, this.#makeLocation(paramStart));
  }
  
  #parseSealedVariants(variants: GrowableArray<SealedVariant>): void {
    this.#consume(TokenType.Case, "Expected 'case' for sealed variant");
    // Parse comma-separated variants: case A, B, C(x: i32)
    variants.push(this.#parseSealedVariant());
    while (this.#match(TokenType.Comma)) {
      variants.push(this.#parseSealedVariant());
    }
  }
  
  #parseSealedVariant(): SealedVariant {
    let variantStart = this.#peek();
    let variantName = this.#parseIdentifier();
    var params: GrowableArray<CaseClassParam> | null = null;
    if (this.#match(TokenType.LParen)) {
      let ps = new Array<CaseClassParam>(4);
      if (!this.#check(TokenType.RParen)) {
        ps.push(this.#parseCaseClassParam());
        while (this.#match(TokenType.Comma) && !this.#check(TokenType.RParen)) {
          ps.push(this.#parseCaseClassParam());
        }
      }
      this.#consume(TokenType.RParen, "Expected ')' after sealed variant parameters");
      params = ps;
    }
    return new SealedVariant(variantName, params, this.#makeLocation(variantStart));
  }
  
  #parseClassMember(): Node {
    let startToken = this.#peek();
    
    // Parse decorators
    let decorators = new Array<Decorator>(2);
    while (this.#check(TokenType.At)) {
      decorators.push(this.#parseDecorator());
    }
    
    // Check for member-level modifiers
    var isFinal = false;
    var isAbstract = false;
    var isDeclare = false;
    var isStatic = false;

    // `shared` is contextual: a modifier when a member follows it, and a
    // member name when `:`, `(`, `=`, `;` or `<` does.
    var isShared = false;
    if (this.#check(TokenType.Identifier) && this.#peek().value == "shared") {
      let next = this.#peek2().kind;
      if (next != TokenType.Colon && next != TokenType.LParen &&
          next != TokenType.Equals && next != TokenType.Semi &&
          next != TokenType.Less) {
        isShared = true;
        this.#advance();
      }
    }

    if (this.#check(TokenType.Final) && this.#peek2().kind != TokenType.Colon) {
      isFinal = true;
      this.#advance();
    } else if (this.#check(TokenType.Abstract) && this.#peek2().kind != TokenType.Colon) {
      isAbstract = true;
      this.#advance();
    } else if (this.#check(TokenType.Declare) && this.#peek2().kind != TokenType.Colon && this.#peek2().kind != TokenType.LParen && this.#peek2().kind != TokenType.Less) {
      isDeclare = true;
      this.#advance();
    }
    
    // Static can combine with declare/abstract/final, so check separately
    if (this.#check(TokenType.Static) && this.#peek2().kind != TokenType.Colon && this.#peek2().kind != TokenType.Symbol) {
      isStatic = true;
      this.#advance();
    }

    // Generator/async method modifiers: gen name(...) / async name(...)
    var isGen = false;
    if (this.#match(TokenType.Gen)) {
      isGen = true;
      if (isDeclare) {
        throw this.#error("'declare' methods cannot be generators");
      }
      if (this.#check(TokenType.New)) {
        throw this.#error("Constructors cannot be generators");
      }
      if (this.#check(TokenType.Operator)) {
        throw this.#error("Operator methods cannot be generators");
      }
    }
    var isAsyncM = false;
    if (this.#match(TokenType.Async)) {
      isAsyncM = true;
      // `async gen name(): Iterator<T>`: may await and yield.
      if (this.#match(TokenType.Gen)) {
        isGen = true;
      }
      if (isDeclare) {
        throw this.#error("'declare' methods cannot be async");
      }
      if (this.#check(TokenType.New)) {
        throw this.#error('Constructors cannot be async');
      }
      if (this.#check(TokenType.Operator)) {
        throw this.#error('Operator methods cannot be async');
      }
    }

    // Check for field mutability prefix
    // Disambiguate: `let name: Type` vs field named `let` (when followed by `:`)
    // Exception: `let :sym: Type` or `var :sym: Type` is a symbol field with mutability
    // Pattern: Keyword, Colon, Ident, (Colon|Dot) → symbol field after keyword
    var mutability: String | null = null;
    var setterName: Node | null = null;
    if (this.#check(TokenType.Let) && (this.#peek2().kind != TokenType.Colon || this.#isSymbolFieldAfterKeyword()) && this.#peek2().kind != TokenType.LParen) {
      this.#advance();
      mutability = 'let';
    } else if (this.#check(TokenType.Var) && (this.#peek2().kind != TokenType.Colon || this.#isSymbolFieldAfterKeyword())) {
      this.#advance();
      mutability = 'var';
      if (this.#match(TokenType.LParen)) {
        // Parse setterName: var(#x) or var(set: #x)
        if (this.#check(TokenType.Identifier) && this.#peek().value == "set" && this.#peek2().kind == TokenType.Colon) {
          this.#advance(); // consume 'set'
          this.#advance(); // consume ':'
        }
        if (this.#match(TokenType.Hash)) {
          let hashToken = this.#previous();
          let id = this.#parseIdentifier();
          setterName = new Identifier("#" + id.name, this.#makeLocation(hashToken));
        } else if (this.#match(TokenType.LBracket)) {
          let colStart = this.#previous();
          var symbolExpr: Expression = this.#parseIdentifier();
          while (this.#match(TokenType.Dot)) {
            let prop = this.#parseIdentifier();
            symbolExpr = new MemberExpression(symbolExpr, prop, false, false, null, this.#makeLocation(colStart));
          }
          this.#consume(TokenType.RBracket, "Expected ']' after setter symbol name");
          setterName = new SymbolPropertyName(symbolExpr, this.#makeLocation(colStart));
        } else {
          setterName = this.#parseIdentifier();
        }
        this.#consume(TokenType.RParen, "Expected ')' after setter name in var(...)");
      }
    }
    
    // Constructor: new(...) or new fromBar(...) or new #fromByteArray(...) or new [fromByteArray](...)
    if (this.#check(TokenType.New)) {
      this.#advance();
      if (isFinal) {
        throw this.#error("Constructors cannot be final");
      }
      if (isAbstract) {
        throw this.#error("Constructors cannot be abstract");
      }
      if (isDeclare) {
        throw this.#error("Constructors cannot be declared 'declare'");
      }
      let ctorName: Node = if (this.#check(TokenType.LParen)) {
        new Identifier('<constructor>', this.#makeLocation(startToken))
      } else if (this.#match(TokenType.Hash)) {
        let hashToken = this.#previous();
        let id = this.#parseIdentifier();
        new Identifier('#' + id.name, this.#makeLocation(hashToken))
      } else if (this.#match(TokenType.LBracket)) {
        let symStart = this.#previous();
        var symbolExpr: Expression = this.#parseIdentifier();
        while (this.#match(TokenType.Dot)) {
          let prop = this.#parseIdentifier();
          symbolExpr = new MemberExpression(symbolExpr, prop, false, false, null, this.#makeLocation(symStart));
        }
        this.#consume(TokenType.RBracket, "Expected ']' after symbol name");
        new SymbolPropertyName(symbolExpr, this.#makeLocation(symStart))
      } else if (this.#isIdentifier()) {
        this.#parseIdentifier()
      } else {
        throw this.#error("Expected '(' or constructor name after 'new'");
      };
      return this.#parseMethodBody(ctorName, null, isFinal, isAbstract, isDeclare, isStatic, isGen, isAsyncM, decorators, startToken, true, false, isShared);
    }
    
    // Operator method: operator ==(other), operator [](index), operator +(other)
    if (this.#check(TokenType.Operator)) {
      this.#advance(); // consume 'operator'
      let opStart = this.#previous();
      
      // Index operator: operator [](param) or operator []=(param, value)
      if (this.#match(TokenType.LBracket)) {
        this.#consume(TokenType.RBracket, "Expected ']' after '[' in operator declaration");
        let opName = if (this.#match(TokenType.Equals)) "[]=" else "[]";
        let identifier = new Identifier(opName, this.#makeLocation(opStart));
        return this.#parseMethodBody(identifier, null, isFinal, isAbstract, isDeclare, isStatic, isGen, isAsyncM, decorators, startToken, false, false, isShared);
      }
      
      // Other operators (==, +, -, etc.)
      let opToken = this.#advance();
      var opName = opToken.value;
      if (opName == "=" && this.#check(TokenType.Equals)) {
        this.#advance();
        opName = "==";
      }
      let identifier = new Identifier(opName, this.#makeLocation(opStart));
      return this.#parseMethodBody(identifier, null, isFinal, isAbstract, isDeclare, isStatic, isGen, isAsyncM, decorators, startToken, false, false, isShared);
    }
    
    // Private field/method: #name
    if (this.#match(TokenType.Hash)) {
      let hashToken = this.#previous();
      let id = this.#parseIdentifier();
      let hashName = new Identifier("#" + id.name, this.#makeLocation(hashToken));
      
      // Private method: #name(params) { ... }
      if (this.#check(TokenType.LParen)) {
        return this.#parseMethodBody(hashName, null, isFinal, isAbstract, isDeclare, isStatic, isGen, isAsyncM, decorators, startToken, false, false, isShared);
      }
      // Generic private method: #name<T>(params) { ... }
      if (this.#check(TokenType.Less) && this.#isGenericMethodStart()) {
        this.#advance(); // consume '<'
        let typeParams = this.#parseTypeParameterList();
        return this.#parseMethodBody(hashName, typeParams, isFinal, isAbstract, isDeclare, isStatic, isGen, isAsyncM, decorators, startToken, false, false, isShared);
      }
      if (isGen || isAsyncM) {
        throw this.#error("Expected '(' after generator/async method name");
      }

      // Private field: #name: Type; or #name = value;
      // -OR- private accessor: #name: Type { get { } set(v) { } }
      this.#rejectOptionalField();
      let typeAnnotation: TypeAnnotation | null = if (this.#match(TokenType.Colon)) {
        this.#parseTypeAnnotation()
      } else {
        null
      };
      if (typeAnnotation != null && this.#check(TokenType.LBrace)) {
        return this.#parseAccessorBlock(hashName, typeAnnotation, isFinal, isStatic, decorators, startToken);
      }
      let value: Expression | null = if (this.#match(TokenType.Equals)) {
        this.#parseExpression()
      } else {
        null
      };
      if (typeAnnotation == null && value == null) {
        throw this.#error("Private field must have a type annotation or initializer");
      }
      this.#consume(TokenType.Semi, "Expected ';' after field declaration");
      return new FieldDefinition(hashName, typeAnnotation, value, isFinal, false, isStatic, false, mutability, decorators, null, isShared, this.#makeLocation(startToken));
    }
    
    // Static symbol declaration: static symbol name;
    if (this.#check(TokenType.Static) && this.#peek2().kind == TokenType.Symbol) {
      this.#advance(); // consume 'static'
      this.#advance(); // consume 'symbol'
      let symName = this.#parseIdentifier();
      this.#consume(TokenType.Semi, "Expected ';' after symbol declaration");
      return new FieldDefinition(symName, new NamedTypeAnnotation('symbol', null, false, symName.loc), null, true, false, true, false, null, decorators, null, false, this.#makeLocation(startToken));
    }
    
    // Symbol-keyed member: [symbolName]
    if (this.#match(TokenType.LBracket)) {
      let symStart = this.#previous();
      var symbolExpr: Expression = this.#parseIdentifier();
      while (this.#match(TokenType.Dot)) {
        let prop = this.#parseIdentifier();
        symbolExpr = new MemberExpression(symbolExpr, prop, false, false, null, this.#makeLocation(symStart));
      }
      this.#consume(TokenType.RBracket, "Expected ']' after symbol name");
      let symPropName = new SymbolPropertyName(symbolExpr, this.#makeLocation(symStart));
      
      // Symbol-keyed method: [name](params) { ... }
      if (this.#check(TokenType.LParen)) {
        return this.#parseMethodBody(symPropName, null, isFinal, isAbstract, isDeclare, isStatic, isGen, isAsyncM, decorators, startToken, false, false, isShared);
      }
      if (isGen || isAsyncM) {
        throw this.#error("Expected '(' after generator/async method name");
      }

      // Symbol-keyed field: [name]: Type; or :name: Type;
      this.#consume(TokenType.Colon, "Expected ':' after symbol field name");
      let symTypeAnnotation = this.#parseTypeAnnotation();
      
      // Check for accessor block
      if (this.#check(TokenType.LBrace)) {
        return this.#parseAccessorBlock(symPropName, symTypeAnnotation, isFinal, isStatic, decorators, startToken);
      }
      
      let symFieldValue: Expression | null = if (this.#match(TokenType.Equals)) {
        this.#parseExpression()
      } else {
        null
      };
      this.#consume(TokenType.Semi, "Expected ';' after field declaration");
      return new FieldDefinition(symPropName, symTypeAnnotation, symFieldValue, isFinal, false, isStatic, false, mutability, decorators, null, isShared, this.#makeLocation(startToken));
    }
    
    let name = this.#parseIdentifier();
    
    // Generic method: name<T>(params) { ... }
    if (this.#check(TokenType.Less) && this.#isGenericMethodStart()) {
      this.#advance(); // consume '<'
      let typeParams = this.#parseTypeParameterList();
      return this.#parseMethodBody(name, typeParams, isFinal, isAbstract, isDeclare, isStatic, isGen, isAsyncM, decorators, startToken, false, false, isShared);
    }
    
    // Method: name(params) { ... }
    if (this.#check(TokenType.LParen)) {
      return this.#parseMethodBody(name, null, isFinal, isAbstract, isDeclare, isStatic, isGen, isAsyncM, decorators, startToken, false, false, isShared);
    }
    if (isGen || isAsyncM) {
      throw this.#error("Expected '(' after generator/async method name");
    }

    // Abstract field: abstract name: Type;
    if (isAbstract) {
      this.#rejectOptionalField();
      this.#consume(TokenType.Colon, "Expected ':' after abstract field name.");
      let typeAnnotation = this.#parseTypeAnnotation();
      this.#consume(TokenType.Semi, "Expected ';' after abstract field declaration.");
      return new FieldDefinition(name, typeAnnotation, null, false, true, false, false, mutability, decorators, null, isShared, this.#makeLocation(startToken));
    }

    // Declare field: declare name: Type;
    if (isDeclare) {
      this.#rejectOptionalField();
      this.#consume(TokenType.Colon, "Expected ':' after declared field name.");
      let typeAnnotation = this.#parseTypeAnnotation();
      this.#consume(TokenType.Semi, "Expected ';' after declared field.");
      return new FieldDefinition(name, typeAnnotation, null, false, false, false, true, mutability, decorators, null, isShared, this.#makeLocation(startToken));
    }

    // Field: name: Type; or name: Type = value; or name = value;
    // -OR- Accessor: name: Type { get { } set(v) { } }
    this.#rejectOptionalField();
    let typeAnnotation: TypeAnnotation | null = if (this.#match(TokenType.Colon)) {
      this.#parseTypeAnnotation()
    } else {
      null
    };
    
    // Check for accessor block
    if (typeAnnotation != null && this.#check(TokenType.LBrace)) {
      return this.#parseAccessorBlock(name, typeAnnotation, isFinal, isStatic, decorators, startToken);
    }
    
    let fieldValue: Expression | null = if (this.#match(TokenType.Equals)) {
      this.#parseExpression()
    } else {
      null
    };
    
    if (typeAnnotation == null && fieldValue == null) {
      throw this.#error("Expected ':' for type annotation or '=' for initializer after field name");
    }
    
    this.#consume(TokenType.Semi, "Expected ';' after field declaration");
    return new FieldDefinition(name, typeAnnotation, fieldValue, isFinal, false, isStatic, false, mutability, decorators, setterName, isShared, this.#makeLocation(startToken));
  }
  
  // Check if < starts a generic method (vs a comparison expression)
  #isGenericMethodStart(): boolean {
    // Save position and try to parse type parameter list
    let saved = this.#current;
    var depth = 1;
    this.#advance(); // skip past '<' (already consumed by caller check)
    while (depth > 0 && !this.#isAtEnd()) {
      // A nested generic's closers lex as shift tokens
      // (`Array<String>>` ends in one GreaterGreater), so each one
      // closes several depths at once.
      if (this.#check(TokenType.Less)) {
        depth = depth + 1;
      } else if (this.#check(TokenType.Greater)) {
        depth = depth - 1;
      } else if (this.#check(TokenType.GreaterGreater)) {
        depth = depth - 2;
      } else if (this.#check(TokenType.GreaterGreaterGreater)) {
        depth = depth - 3;
      }
      if (depth > 0) {
        this.#advance();
      }
    }
    // After matching '>', check if next token is '('
    var result = false;
    if (depth <= 0) {
      this.#advance(); // skip the closing '>' (or the shift token that ends it)
      result = this.#check(TokenType.LParen);
    }
    this.#current = saved;
    return result;
  }
  
  #parseAccessorBlock(name: Node, typeAnnotation: TypeAnnotation, isFinal: boolean, isStatic: boolean, decorators: GrowableArray<Decorator>, startToken: Token): AccessorDeclaration {
    this.#consume(TokenType.LBrace, "Expected '{' for accessor block");
    
    var getter: BlockStatement | null = null;
    var setter: Node | null = null;
    
    while (!this.#check(TokenType.RBrace) && !this.#isAtEnd()) {
      let keyword = this.#peek();
      if (keyword.value == "get") {
        if (getter != null) {
          throw this.#error("Duplicate getter");
        }
        this.#advance();
        let blockStart = this.#peek();
        this.#consume(TokenType.LBrace, "Expected '{' after get");
        getter = this.#parseBlockStatement(blockStart);
      } else if (keyword.value == "set") {
        if (setter != null) {
          throw this.#error("Duplicate setter");
        }
        this.#advance();
        this.#consume(TokenType.LParen, "Expected '(' after set");
        let param = this.#parseIdentifier();
        this.#consume(TokenType.RParen, "Expected ')' after setter parameter");
        let blockStart = this.#peek();
        this.#consume(TokenType.LBrace, "Expected '{' after setter parameter");
        let body = this.#parseBlockStatement(blockStart);
        setter = new SetterInfo(param, body, this.#makeLocation(keyword));
      } else {
        throw this.#error("Expected 'get' or 'set' in accessor block");
      }
    }
    
    if (getter == null && setter == null) {
      throw this.#error("Accessor must have at least a getter or a setter");
    }
    
    this.#consume(TokenType.RBrace, "Expected '}' after accessor block");
    return new AccessorDeclaration(name, typeAnnotation, getter, setter, isFinal, isStatic, decorators, this.#makeLocation(startToken));
  }
  
  #parseMethodBody(name: Node, typeParameters: GrowableArray<TypeParameter> | null, isFinal: boolean, isAbstract: boolean, isDeclare: boolean, isStatic: boolean, isGenerator: boolean, isAsync: boolean, decorators: GrowableArray<Decorator>, startToken: Token, isConstructor: boolean, inInterface: boolean = false, isShared: boolean = false): MethodDefinition {
    this.#consume(TokenType.LParen, "Expected '(' after method name");

    // An explicitly declared receiver: `dispose(this: Own<this>)`. It leads
    // the parameter list but is not a parameter — the receiver is implicit in
    // every method — so it is parsed here rather than in `#parseParameters`,
    // which also keeps `this: T` out of arrow functions and top-level
    // `function` declarations, where there is no receiver to declare.
    var receiver: TypeAnnotation | null = null;
    if (this.#check(TokenType.This) && this.#peek2().kind == TokenType.Colon) {
      this.#advance(); // consume 'this'
      this.#advance(); // consume ':'
      receiver = this.#parseTypeAnnotation();
      if (!this.#check(TokenType.RParen)) {
        this.#consume(TokenType.Comma, "Expected ',' after receiver");
      }
    }

    let params = this.#parseParameters();
    this.#consume(TokenType.RParen, "Expected ')' after parameters");
    
    // Synthesize FieldInitializer entries for this.field params
    let thisInits = new Array<Node>(4);
    for (let p in params) {
      if (p.isThisParam) {
        thisInits.push(new FieldInitializer(
          new Identifier(p.name.name, p.name.loc),
          new Identifier(p.name.name, p.name.loc),
          p.loc
        ));
      }
    }
    
    // A class constructor has no return type, so its clauses follow the
    // parameters, ahead of the initializer list they guard.
    let constructorContracts = if (isConstructor && !inInterface) {
      this.#parseFunctionContracts()
    } else {
      null
    };

    var returnType: TypeAnnotation | null = null;
    if (this.#match(TokenType.Colon)) {
      // Check for initializer list (: field = value, ...) vs return type
      // If this is a constructor, the colon starts an initializer list.
      // An INTERFACE constructor has no fields, so its colon is a return
      // type — except when what follows is shaped like an initializer
      // entry (`name =`, `#name =`, `super`), which is kept so the
      // checker can say why an interface constructor cannot have one.
      let looksLikeInitializer = this.#check(TokenType.Super) ||
          this.#check(TokenType.Hash) ||
          (this.#isIdentifier() && this.#peek2().kind == TokenType.Equals);
      if (isConstructor && (!inInterface || looksLikeInitializer)) {
        // Parse initializer list
        let initList = new Array<Node>(4);
        var superInit: Node | null = null;
        
        // First entry
        if (this.#check(TokenType.Super)) {
          superInit = this.#parseSuperInitializer();
        } else {
          initList.push(this.#parseFieldInitializer());
        }
        
        while (this.#match(TokenType.Comma)) {
          if (this.#check(TokenType.Super)) {
            superInit = this.#parseSuperInitializer();
          } else {
            initList.push(this.#parseFieldInitializer());
          }
        }
        
        // Prepend this.field initializers before explicit ones
        let combined = new Array<Node>(thisInits.length + initList.length);
        var j = 0;
        while (j < thisInits.length) {
          combined.push(thisInits[j]);
          j = j + 1;
        }
        j = 0;
        while (j < initList.length) {
          combined.push(initList[j]);
          j = j + 1;
        }
        
        // Body: either { } or ;
        var body: Node | null = null;
        if (this.#check(TokenType.LBrace)) {
          let blockStart = this.#advance();
          body = this.#parseBlockStatement(blockStart);
        } else if (this.#match(TokenType.Semi)) {
          body = new BlockStatement(new Array<Statement>(0), this.#makeLocation(startToken));
        }
        
        let initListResult: GrowableArray<Node> | null = if (combined.length > 0) {
          combined
        } else {
          null
        };
        
        return new MethodDefinition(name, typeParameters, receiver, params, null, body, initListResult, superInit, isFinal, isAbstract, isStatic, isDeclare, isGenerator, isAsync, decorators, true, isShared, constructorContracts, this.#makeLocation(startToken));
      } else {
        returnType = this.#parseTypeAnnotation();
      }
    }

    let contracts = if (isConstructor) constructorContracts else this.#parseFunctionContracts();

    // Method body
    var body: Node | null = null;
    if (this.#check(TokenType.LBrace)) {
      let blockStart = this.#advance();
      body = this.#parseBlockStatement(blockStart);
    } else if (this.#match(TokenType.Semi)) {
      // Abstract/declare method or semicolon body — treated as empty block
      if (!isAbstract && !isDeclare) {
        body = new BlockStatement(new Array<Statement>(0), this.#makeLocation(startToken));
      }
    }
    
    // If we have this.field params but no explicit initializer list
    let thisInitResult: GrowableArray<Node> | null = if (thisInits.length > 0) {
      thisInits
    } else {
      null
    };
    
    return new MethodDefinition(name, typeParameters, receiver, params, returnType, body, thisInitResult, null, isFinal, isAbstract, isStatic, isDeclare, isGenerator, isAsync, decorators, isConstructor, isShared, contracts, this.#makeLocation(startToken));
  }
  
  #parseFieldInitializer(): FieldInitializer {
    let initStart = this.#peek();
    // Handle #private field names
    let fieldName = if (this.#check(TokenType.Hash)) {
      this.#advance();
      let privName = this.#parseIdentifier();
      new Identifier("#" + privName.name, this.#makeLocation(initStart))
    } else {
      this.#parseIdentifier()
    };
    this.#consume(TokenType.Equals, "Expected '=' in initializer");
    let value = this.#parseExpression();
    return new FieldInitializer(fieldName, value, this.#makeLocation(initStart));
  }
  
  #parseSuperInitializer(): SuperInitializer {
    let superStart = this.#peek();
    this.#consume(TokenType.Super, "Expected 'super'");
    var constructorName: Node | null = null;
    if (this.#match(TokenType.Dot)) {
      if (this.#match(TokenType.Hash)) {
        let hashToken = this.#previous();
        let id = this.#parseIdentifier();
        constructorName = new Identifier("#" + id.name, this.#makeLocation(hashToken));
      } else if (this.#match(TokenType.LBracket)) {
        let colStart = this.#previous();
        var symbolExpr: Expression = this.#parseIdentifier();
        while (this.#match(TokenType.Dot)) {
          let prop = this.#parseIdentifier();
          symbolExpr = new MemberExpression(symbolExpr, prop, false, false, null, this.#makeLocation(colStart));
        }
        this.#consume(TokenType.RBracket, "Expected ']' after symbol name");
        constructorName = new SymbolPropertyName(symbolExpr, this.#makeLocation(colStart));
      } else {
        constructorName = this.#parseIdentifier();
      }
    }
    this.#consume(TokenType.LParen, "Expected '(' after super");
    let args = new Array<Expression>(4);
    if (!this.#check(TokenType.RParen)) {
      args.push(this.#parseExpression());
      while (this.#match(TokenType.Comma) && !this.#check(TokenType.RParen)) {
        args.push(this.#parseExpression());
      }
    }
    this.#consume(TokenType.RParen, "Expected ')' after super arguments");
    return new SuperInitializer(args, constructorName, this.#makeLocation(superStart));
  }
  
  // ==========================================================================
  // Decorators
  // ==========================================================================
  
  /**
   * `@name`, `@a.b.c`, or either followed by an argument list. The
   * arguments are ordinary expressions; what a builtin accepts is checked
   * where it is read.
   */
  #parseDecorator(): Decorator {
    let startToken = this.#peek();
    this.#consume(TokenType.At, "Expected '@'");
    let path = growable<Identifier>([this.#parseIdentifier()]);
    var name = path[0].name;
    while (this.#match(TokenType.Dot)) {
      let segment = this.#parseIdentifier();
      path.push(segment);
      name = `${name}.${segment.name}`;
    }
    let args = new Array<Expression>(2);
    if (this.#match(TokenType.LParen)) {
      if (!this.#check(TokenType.RParen)) {
        args.push(this.#parseExpression());
        while (this.#match(TokenType.Comma) && !this.#check(TokenType.RParen)) {
          args.push(this.#parseExpression());
        }
      }
      this.#consume(TokenType.RParen, "Expected ')' after decorator arguments");
    }
    return new Decorator(name, path, args, this.#makeLocation(startToken));
  }
  
  // ==========================================================================
  // Declare Function
  // ==========================================================================
  
  #parseDeclareFunction(decorators: GrowableArray<Decorator>, exported: boolean, startToken: Token): DeclareFunction {
    this.#consume(TokenType.Function, "Expected 'function' after 'declare'");
    let name = this.#parseIdentifier();
    
    // Optional type parameters
    var typeParameters: GrowableArray<TypeParameter> | null = null;
    if (this.#check(TokenType.Less)) {
      this.#advance();
      typeParameters = this.#parseTypeParameterList();
    }
    
    this.#consume(TokenType.LParen, "Expected '(' after function name");
    let params = this.#parseParameters();
    this.#consume(TokenType.RParen, "Expected ')' after parameters");
    
    this.#consume(TokenType.Colon, "Expected ':' for return type");
    let returnType = this.#parseTypeAnnotation();
    
    this.#consume(TokenType.Semi, "Expected ';' after function declaration");
    
    // Extract @external module/name from decorators
    var externalModule: String | null = null;
    var externalName: String | null = null;
    for (let d in decorators) {
      if (d.name == "external") {
        // A third argument is the import's canonical options
        // ("async"), read in codegen — see
        // docs/design/component-emission.md.
        if (d.args.length != 2 && d.args.length != 3) {
          throw this.#error("@external expects 2 or 3 arguments");
        }
        let moduleArg = decoratorStringArg(d, 0);
        let nameArg = decoratorStringArg(d, 1);
        if (moduleArg == null || nameArg == null) {
          throw this.#error("@external arguments must be string literals");
        }
        externalModule = moduleArg;
        externalName = nameArg;
      }
    }
    
    return new DeclareFunction(name, typeParameters, params, returnType, externalModule, externalName, exported, decorators, this.#makeLocation(startToken));
  }
  
  // ==========================================================================
  // Interface Declarations
  // ==========================================================================
  
  #parseInterfaceDeclaration(exported: boolean, startToken: Token): InterfaceDeclaration {
    let name = this.#parseIdentifier();
    
    // Type parameters: interface Foo<T>
    let typeParameters: GrowableArray<TypeParameter> | null = if (this.#match(TokenType.Less)) {
      this.#parseTypeParameterList()
    } else {
      null
    };
    
    // Extends clause: interface Foo extends Bar, Baz
    var extendsList: GrowableArray<TypeAnnotation> | null = null;
    if (this.#match(TokenType.Extends)) {
      let exts = growable<TypeAnnotation>([this.#parseTypeAnnotation()]);
      while (this.#match(TokenType.Comma)) {
        exts.push(this.#parseTypeAnnotation());
      }
      extendsList = exts;
    }
    
    this.#consume(TokenType.LBrace, "Expected '{' before interface body");
    
    let body = new Array<Node>(8);
    while (!this.#check(TokenType.RBrace) && !this.#isAtEnd()) {
      if (this.#recover) {
        let posBefore = this.#current;
        try {
          body.push(this.#parseInterfaceMember());
        } catch (e) {
          this.#recordSyntaxError(e);
          this.#synchronizeClassMember(posBefore);
        }
        if (this.#current == posBefore && !this.#check(TokenType.RBrace) && !this.#isAtEnd()) {
          this.#advance();
        }
      } else {
        body.push(this.#parseInterfaceMember());
      }
    }
    
    if (this.#recover && !this.#check(TokenType.RBrace)) {
      this.#recordSyntaxError(this.#error("Expected '}' after interface body"));
    } else {
      this.#consume(TokenType.RBrace, "Expected '}' after interface body");
    }
    
    return new InterfaceDeclaration(name, typeParameters, extendsList, body, exported, this.#makeLocation(startToken));
  }
  
  #parseInterfaceMember(): Node {
    let startToken = this.#peek();
    
    // Static symbol declaration: static symbol name;
    if (this.#check(TokenType.Static) && this.#peek2().kind == TokenType.Symbol) {
      this.#advance(); // consume 'static'
      this.#advance(); // consume 'symbol'
      let symName = this.#parseIdentifier();
      this.#consume(TokenType.Semi, "Expected ';' after symbol declaration");
      return new SymbolDeclaration(symName, false, this.#makeLocation(startToken));
    }

    // Constructor: new(...) or new name(...). An interface constructor is
    // a factory: its body returns an instance of some class that
    // implements the interface. It parses like a class constructor
    // (the same MethodDefinition node, `isConstructor` set); the checker
    // rejects the parts that make no sense without a class — an
    // initializer list, a `super` call, `this.` parameters, a body-less
    // declaration.
    if (this.#check(TokenType.New)) {
      this.#advance();
      let ctorName: Node = if (this.#check(TokenType.LParen) || this.#check(TokenType.Less)) {
        new Identifier('<constructor>', this.#makeLocation(startToken))
      } else if (this.#isIdentifier()) {
        this.#parseIdentifier()
      } else {
        throw this.#error("Expected '(' or a constructor name after 'new' in an interface");
      };
      // `new<K extends Hashable, V>(...)`: the constructor restates the
      // interface's type parameters with the bounds its body needs. The
      // checker requires the names to be the interface's, in order.
      let ctorTypeParams: GrowableArray<TypeParameter> | null = if (this.#match(TokenType.Less)) {
        this.#parseTypeParameterList()
      } else {
        null
      };
      return this.#parseMethodBody(ctorName, ctorTypeParams, false, false, false, false, false, false, new Array<Decorator>(0), startToken, true, true);
    }

    // Check for `var` modifier on interface fields
    var mutableField = false;
    if (this.#check(TokenType.Var)) {
      mutableField = true;
      this.#advance();
    }
    
    // Operator signature: operator [](index: i32): T;  or  operator []=(index: i32, value: T): void;
    if (this.#check(TokenType.Operator)) {
      this.#advance();
      var opName = "";
      if (this.#match(TokenType.LBracket)) {
        this.#consume(TokenType.RBracket, "Expected ']' after operator '['");
        if (this.#match(TokenType.Equals)) {
          opName = "[]=";
        } else {
          opName = "[]";
        }
      } else {
        let opToken = this.#advance();
        opName = opToken.value;
        if (opName == "=" && this.#check(TokenType.Equals)) {
          this.#advance();
          opName = "==";
        }
      }
      let operatorName = new Identifier(opName, this.#makeLocation(startToken));
      this.#consume(TokenType.LParen, "Expected '(' after operator name");
      let params = this.#parseParameters();
      this.#consume(TokenType.RParen, "Expected ')' after parameters");
      let returnType: TypeAnnotation | null = if (this.#match(TokenType.Colon)) {
        this.#parseTypeAnnotation()
      } else {
        null
      };
      let contracts = this.#parseFunctionContracts();
      this.#consume(TokenType.Semi, "Expected ';' after operator signature");
      return new MethodSignature(operatorName, null, params, returnType, contracts, this.#makeLocation(startToken));
    }
    
    // Symbol-keyed method: [symbolName](params): ReturnType;
    if (this.#match(TokenType.LBracket)) {
      let symStart = this.#previous();
      var symbolExpr: Expression = this.#parseIdentifier();
      while (this.#match(TokenType.Dot)) {
        let prop = this.#parseIdentifier();
        symbolExpr = new MemberExpression(symbolExpr, prop, false, false, null, this.#makeLocation(symStart));
      }
      this.#consume(TokenType.RBracket, "Expected ']' after symbol name");
      let symPropName = new SymbolPropertyName(symbolExpr, this.#makeLocation(symStart));
      this.#consume(TokenType.LParen, "Expected '(' after symbol method name");
      let symParams = this.#parseParameters();
      this.#consume(TokenType.RParen, "Expected ')' after parameters");
      let symReturnType: TypeAnnotation | null = if (this.#match(TokenType.Colon)) {
        this.#parseTypeAnnotation()
      } else {
        null
      };
      let symContracts = this.#parseFunctionContracts();
      this.#consume(TokenType.Semi, "Expected ';' after method signature");
      return new MethodSignature(symPropName, null, symParams, symReturnType, symContracts, this.#makeLocation(startToken));
    }
    
    let name = this.#parseIdentifier();
    
    // Type parameters for methods
    let typeParameters: GrowableArray<TypeParameter> | null = if (this.#match(TokenType.Less)) {
      this.#parseTypeParameterList()
    } else {
      null
    };
    
    // Method: name(params): ReturnType;
    if (this.#match(TokenType.LParen)) {
      if (mutableField) {
        throw this.#error("'var' modifier is not allowed on methods.");
      }
      let params = this.#parseParameters();
      this.#consume(TokenType.RParen, "Expected ')' after parameters");
      
      let returnType: TypeAnnotation | null = if (this.#match(TokenType.Colon)) {
        this.#parseTypeAnnotation()
      } else {
        null
      };
      
      let contracts = this.#parseFunctionContracts();

      this.#consume(TokenType.Semi, "Expected ';' after method signature");

      return new MethodSignature(name, typeParameters, params, returnType, contracts, this.#makeLocation(startToken));
    }
    
    if (typeParameters != null) {
      throw this.#error("Fields cannot have type parameters.");
    }
    
    // Field: name: Type;  or  Accessor: name: Type { get; set; }
    this.#rejectOptionalField();
    this.#consume(TokenType.Colon, "Expected ':' after field name");
    let typeAnnotation = this.#parseTypeAnnotation();
    
    // Check for accessor signature: { get; set; }
    if (this.#match(TokenType.LBrace)) {
      if (mutableField) {
        throw this.#error("'var' modifier is not allowed on accessor signatures.");
      }
      var hasGetter = false;
      var hasSetter = false;
      
      while (!this.#match(TokenType.RBrace)) {
        let id = this.#parseIdentifier();
        if (id.name == "get") {
          hasGetter = true;
        } else if (id.name == "set") {
          hasSetter = true;
        } else {
          throw this.#error(`Expected 'get' or 'set' in accessor signature, got '${id.name}'`);
        }
        this.#consume(TokenType.Semi, "Expected ';' after accessor specifier");
      }
      
      return new AccessorSignature(name, typeAnnotation, hasGetter, hasSetter, this.#makeLocation(startToken));
    }
    
    this.#consume(TokenType.Semi, "Expected ';' after field declaration");
    
    return new FieldDefinition(name, typeAnnotation, null, false, false, false, false, if (mutableField) { "var" } else { null }, new Array<Decorator>(0), null, false, this.#makeLocation(startToken));
  }
  
  // ==========================================================================
  // Mixin Declarations
  // ==========================================================================
  
  /**
   * `mixin Name<T> on Base with A, B { ... }`, or with `isDecorator`,
   * `decorator Name<T>(var subject: T) { ... }`. A decorator declares the
   * field it stands in for instead of an `on` or `with` clause.
   */
  #parseMixinDeclaration(exported: boolean, startToken: Token, isDecorator: boolean): MixinDeclaration {
    let name = this.#parseIdentifier();
    let what = if (isDecorator) "decorator" else "mixin";

    // Type parameters: mixin Foo<T>
    let typeParameters: GrowableArray<TypeParameter> | null = if (this.#match(TokenType.Less)) {
      this.#parseTypeParameterList()
    } else {
      null
    };

    // Subject: decorator Foo(var value: T)
    var decoratorSubject: FieldDefinition | null = null;
    if (isDecorator) {
      this.#consume(TokenType.LParen, "Expected '(' after decorator name");
      let subjectStart = this.#peek();
      let mutability: String | null = if (this.#match(TokenType.Var)) {
        "var"
      } else if (this.#match(TokenType.Let)) {
        "let"
      } else {
        null
      };
      let subjectName = this.#parseIdentifier();
      this.#consume(TokenType.Colon, "Expected ':' after the decorated field's name");
      let subjectType = this.#parseTypeAnnotation();
      this.#consume(TokenType.RParen, "Expected ')' after the decorated field");
      decoratorSubject = new FieldDefinition(subjectName, subjectType, null, false, false, false, false, mutability, new Array<Decorator>(0), null, false, this.#makeLocation(subjectStart));
    }

    // On clause: mixin Foo on Bar, decorator Foo(var value: T) on Bar.
    // A decorator takes no `with`: a mixin's members are public, and a
    // decorator adds nothing public but the member it decorates
    // (docs/design/decorators.md §"Shared state across applications").
    let on: TypeAnnotation | null = if (this.#match(TokenType.On)) {
      this.#parseTypeAnnotation()
    } else {
      null
    };

    // With clause: mixin Foo with A, B
    var mixins: GrowableArray<TypeAnnotation> | null = null;
    if (!isDecorator && this.#match(TokenType.With)) {
      let ms = growable<TypeAnnotation>([this.#parseTypeAnnotation()]);
      while (this.#match(TokenType.Comma)) {
        ms.push(this.#parseTypeAnnotation());
      }
      mixins = ms;
    }

    this.#consume(TokenType.LBrace, `Expected '{' before ${what} body`);

    let body = new Array<Node>(8);
    while (!this.#check(TokenType.RBrace) && !this.#isAtEnd()) {
      if (this.#recover) {
        let posBefore = this.#current;
        try {
          body.push(this.#parseClassMember());
        } catch (e) {
          this.#recordSyntaxError(e);
          this.#synchronizeClassMember(posBefore);
        }
        if (this.#current == posBefore && !this.#check(TokenType.RBrace) && !this.#isAtEnd()) {
          this.#advance();
        }
      } else {
        body.push(this.#parseClassMember());
      }
    }

    if (this.#recover && !this.#check(TokenType.RBrace)) {
      this.#recordSyntaxError(this.#error(`Expected '}' after ${what} body`));
    } else {
      this.#consume(TokenType.RBrace, `Expected '}' after ${what} body`);
    }

    return new MixinDeclaration(name, typeParameters, on, mixins, body, exported, decoratorSubject, this.#makeLocation(startToken));
  }
  
  #parseEnumDeclaration(exported: boolean, startToken: Token): EnumDeclaration {
    let name = this.#parseIdentifier();
    this.#consume(TokenType.LBrace, "Expected '{' after enum name");
    
    let members = new Array<EnumMember>(8);
    while (!this.#check(TokenType.RBrace) && !this.#isAtEnd()) {
      let memberStartToken = this.#peek();
      let memberName = this.#parseIdentifier();
      let initializer: Expression | null = if (this.#match(TokenType.Equals)) {
        this.#parseExpression()
      } else {
        null
      };
      members.push(new EnumMember(memberName, initializer, this.#makeLocation(memberStartToken)));
      if (!this.#check(TokenType.RBrace)) {
        this.#consume(TokenType.Comma, "Expected ',' after enum member");
      }
    }
    
    this.#consume(TokenType.RBrace, "Expected '}' after enum body");
    
    return new EnumDeclaration(name, members, exported, this.#makeLocation(startToken));
  }
  
  #parseSymbolDeclaration(exported: boolean, startToken: Token): SymbolDeclaration {
    let name = this.#parseIdentifier();
    this.#consume(TokenType.Semi, "Expected ';' after symbol declaration");
    return new SymbolDeclaration(name, exported, this.#makeLocation(startToken));
  }
  
  #parseTypeAliasDeclaration(exported: boolean, isDistinct: boolean, isOpaque: boolean, startToken: Token, decorators: GrowableArray<Decorator> | null = null, isDeclare: boolean = false): TypeAliasDeclaration {
    this.#consume(TokenType.Type, "Expected 'type' keyword");
    let name = this.#parseIdentifier();
    
    // Optional type parameters
    let typeParameters: GrowableArray<TypeParameter> | null = if (this.#match(TokenType.Less)) {
      this.#parseTypeParameterList()
    } else {
      null
    };
    
    var typeAnnotation: TypeAnnotation | null = null;
    if (!isDeclare) {
      this.#consume(TokenType.Equals, "Expected '=' after type alias name");
      typeAnnotation = this.#parseTypeAnnotation();
    }
    this.#consume(TokenType.Semi, "Expected ';' after type alias declaration");
    
    return new TypeAliasDeclaration(name, typeParameters, typeAnnotation, exported, isDistinct, isOpaque, decorators ?? new Array<Decorator>(0), this.#makeLocation(startToken));
  }
}

// ============================================================================
// Convenience function
// ============================================================================

export function assignNodeIds(node: Node, idGen: IdGenerator<NodeId>): void {
  walkEnter(node, (n) => {
    n.id = idGen.next();
  });
}

/**
 * Parse a source string into a Module AST.
 *
 * @param nodeIdGenerator An optional shared node ID generator.
 *
 * You would want to share a `nodeIdGenerator` across multiple parsing passes
 * when compiling a whole program in a single run if you need globally unique
 * AST Node IDs (e.g. for whole-program optimizations, global macro expansions,
 * or unified graph-based compilers). If no generator is passed, each file's
 * nodes are numbered starting from 1 locally.
 */
export function parse(source: String, path: String, nodeIdGenerator: IdGenerator<NodeId> = makeNodeIdGenerator(), table: StringTable | null = null): Module {
  registerSource(path, source);
  let parser = new Parser(source, path, false, table);
  let mod = parser.parse();
  assignNodeIds(mod, nodeIdGenerator);
  mod.lastNodeId = (nodeIdGenerator.peek() - 1) as NodeId;
  return mod;
}

/**
 * Parse with the module-body rule off, so a statement written at module
 * level is accepted as the AST it parses to.
 *
 * Two callers want this. The parser tests hand the parser one statement
 * or one expression at a time and compare the node it produces, so
 * every `@target: statement` and `@target: expression` case is a
 * statement at module level by construction. And the formatter prints
 * whatever it is given: the rule is about where a statement may run,
 * which is not a question a formatter has to answer to lay the
 * statement out.
 *
 * Nothing that goes on to check or compile the result should use this —
 * `parse` is the language.
 */
export function parseAllowingStatements(source: String, path: String, nodeIdGenerator: IdGenerator<NodeId> = makeNodeIdGenerator(), table: StringTable | null = null): Module {
  registerSource(path, source);
  let parser = new Parser(source, path, false, table, true);
  let mod = parser.parse();
  assignNodeIds(mod, nodeIdGenerator);
  mod.lastNodeId = (nodeIdGenerator.peek() - 1) as NodeId;
  return mod;
}

/**
 * Parse, recovering from the errors that recovery covers instead of
 * throwing them, and report those as diagnostics alongside the AST.
 *
 * This is for tools that have to say something useful about source that
 * is still being typed — completions, symbols, hover. Errors the parser
 * cannot recover from are still thrown, so a caller must handle both.
 */
export function parseRecovering(source: String, path: String, nodeIdGenerator: IdGenerator<NodeId> = makeNodeIdGenerator(), table: StringTable | null = null): ParseResult {
  registerSource(path, source);
  let parser = new Parser(source, path, true, table);
  let mod = parser.parse();
  assignNodeIds(mod, nodeIdGenerator);
  mod.lastNodeId = (nodeIdGenerator.peek() - 1) as NodeId;
  return {
    ast: mod,
    completeness: parser.completeness,
    diagnostics: parser.recoveredErrors
  };
}

function isValidRadixDigit(c: i32, base: i32) {
  if (base == 2) {
    return c == 48 || c == 49;
  }
  if (base == 8) {
    return c >= 48 && c <= 55;
  }
  if (base == 16) {
    return (c >= 48 && c <= 57) || (c >= 97 && c <= 102) || (c >= 65 && c <= 70);
  }
  return c >= 48 && c <= 57;
}

function validateNumberLiteral(raw: String): String | null {
  var base = 10;
  var start = 0;
  if (raw.length >= 2 && raw.getByteAt(0) == 48) {
    let c1 = raw.getByteAt(1);
    if (c1 == 120 || c1 == 88) {
      base = 16;
      start = 2;
    } else if (c1 == 98 || c1 == 66) {
      base = 2;
      start = 2;
    } else if (c1 == 111 || c1 == 79) {
      base = 8;
      start = 2;
    }
  }

  var end = raw.length;
  if (end > start && raw.getByteAt(end - 1) == 110) {
    if (raw.contains('.')) {
      return `BigInt suffix 'n' is not allowed on floating-point literal '${raw}'.`;
    }
    end -= 1;
    if (end > start && raw.getByteAt(end - 1) == 95) {
      if (end - 1 <= start || raw.getByteAt(end - 2) == 95) {
        return `Unexpected numeric separator '_' in '${raw}': '_' is only allowed between digits.`;
      }
      end -= 1;
    }
  }

  if (start >= end) {
    return `Unexpected end of numeric literal '${raw}': expected digits after prefix.`;
  }

  var prevWasDigit = false;
  var sawDot = false;
  var sawDigitAfterDot = false;
  for (var i = start; i < end; i += 1) {
    let c = raw.getByteAt(i);
    if (c == 95) {
      if (!prevWasDigit || i + 1 >= end) {
        return `Unexpected numeric separator '_' in '${raw}': '_' is only allowed between digits.`;
      }
      prevWasDigit = false;
      continue;
    }
    if (c == 46 && base == 10 && !sawDot) {
      if (!prevWasDigit) {
        return `Unexpected numeric separator '_' before '.' in '${raw}'.`;
      }
      sawDot = true;
      prevWasDigit = false;
      continue;
    }
    if (!isValidRadixDigit(c, base)) {
      return `Unexpected character in numeric literal '${raw}'.`;
    }
    prevWasDigit = true;
    if (sawDot) {
      sawDigitAfterDot = true;
    }
  }

  if (sawDot && !sawDigitAfterDot) {
    return `Unexpected end of floating-point literal '${raw}'.`;
  }
  return null;
}
VersionPublishedDependenciesApproved by
0.0.2-preview.1 2026-11-19