radiance · Radiance self-hosting compiler

.ai/ compiler/ lib/ examples/ std/ arch/ collections/ lang/ alloc/ ast/ gen/ il/ module/ parser/ resolver/ scanner/ alloc.rad 4.2 KiB ast.rad 22.6 KiB gen.rad 489 B il.rad 18.0 KiB lower.rad 261.8 KiB module.rad 13.4 KiB package.rad 1.2 KiB parser.rad 79.7 KiB resolver.rad 246.8 KiB scanner.rad 18.1 KiB sexpr.rad 6.3 KiB strings.rad 2.2 KiB sys/ arch.rad 65 B collections.rad 36 B fmt.rad 3.8 KiB intrinsics.rad 399 B io.rad 1.2 KiB lang.rad 222 B mem.rad 2.1 KiB sys.rad 167 B testing.rad 2.3 KiB tests.rad 11.6 KiB vec.rad 3.1 KiB std.rad 231 B scripts/ seed/ test/ vim/ .gitignore 353 B .gitsigners 112 B LICENSE 1.1 KiB Makefile 3.0 KiB README 2.5 KiB std.lib 1.0 KiB std.lib.test 252 B
lib/std/lang/resolver.rad 246.8 KiB raw
//! Radiance semantic analyzer and type resolver.
//!
//! This module performs scope construction, symbol binding, and identifier
//! resolution on top of the AST produced by the parser.

pub mod printer;

/// Unit tests for the resolver.
@test mod tests;

// TODO: Move to raw vectors to reduce list duplication?
// TODO: When a function declaration fails to typecheck, it should still "exist".
// TODO: `ensureNominalResolved` should just run when you call `typeFor`.
// TODO: Have different types for positional vs. named field records.

use std::mem;
use std::io;
use std::lang::alloc;
use std::lang::ast;
use std::lang::parser;
use std::lang::module;

/// Maximum number of diagnostics recorded.
pub const MAX_ERRORS: u32 = 64;

/// Synthetic function name used when wrapping a bare expression for analysis.
pub const ANALYZE_EXPR_FN_NAME: *[u8] = "__expr__";
/// Synthetic function name used when wrapping a block for analysis.
pub const ANALYZE_BLOCK_FN_NAME: *[u8] = "__block__";

/// Maximum number of symbols stored within a module scope.
pub const MAX_MODULE_SYMBOLS: u32 = 512;
/// Maximum number of symbols stored within a local scope.
pub const MAX_LOCAL_SYMBOLS: u32 = 32;
/// Maximum function parameters.
pub const MAX_FN_PARAMS: u32 = 8;
/// Maximum function thrown types.
pub const MAX_FN_THROWS: u32 = 8;
/// Maximum number of variants in a union.
/// Nb. This should not be raised above `255`,
/// as tags are stored using 8-bits only.
pub const MAX_UNION_VARIANTS: u32 = 128;
/// Maximum nesting of loops.
pub const MAX_LOOP_DEPTH: u32 = 16;
/// Maximum trait instances.
pub const MAX_INSTANCES: u32 = 128;
/// Maximum standalone methods (across all types).
pub const MAX_METHODS: u32 = 256;

/// Trait definition stored in the resolver.
pub record TraitType {
    /// Trait name.
    name: *[u8],
    /// Method signatures, including from supertraits.
    methods: *mut [TraitMethod],
    /// Supertraits that must also be implemented.
    supertraits: *mut [*TraitType],
}

/// A single method signature within a trait.
pub record TraitMethod {
    /// Method name.
    name: *[u8],
    /// Function type for the method, excluding the receiver.
    fnType: *FnType,
    /// Whether the receiver is mutable.
    mutable: bool,
    /// V-table slot index.
    index: u32,
}

/// An entry in the trait instance registry.
pub record InstanceEntry {
    /// Trait type descriptor.
    traitType: *TraitType,
    /// Concrete type that implements the trait.
    concreteType: Type,
    /// Name of the concrete type.
    concreteTypeName: *[u8],
    /// Module where this instance was declared.
    moduleId: u16,
    /// Method symbols for each trait method, in declaration order.
    methods: *mut [*mut Symbol],
}

/// An entry in the method registry.
pub record MethodEntry {
    /// Concrete type that owns the method.
    concreteType: Type,
    /// Name of the concrete type.
    concreteTypeName: *[u8],
    /// Method name.
    name: *[u8],
    /// Function type excluding the receiver.
    fnType: *FnType,
    /// Whether the receiver is mutable.
    mutable: bool,
    /// Symbol for the method.
    symbol: *mut Symbol,
}

/// Identifier for the synthetic `len` field.
pub const LEN_FIELD: *[u8] = "len";
/// Identifier for the synthetic `ptr` field.
pub const PTR_FIELD: *[u8] = "ptr";
/// Identifier for the synthetic `cap` field.
pub const CAP_FIELD: *[u8] = "cap";

/// Maximum `u16` value.
const U16_MAX: u16 = 0xFFFF;
/// Maximum `u8` value.
const U8_MAX: u16 = 0xFF;

/// Minimum `i8` value.
const I8_MIN: i32 = -128;
/// Maximum `i8` value.
const I8_MAX: i32 = 127;
/// Minimum `i16` value.
const I16_MIN: i32 = -32768;
/// Maximum `i16` value.
const I16_MAX: i32 = 32767;

/// Minimum `i32` value.
const I32_MIN: i32 = -2147483648;
/// Maximum `i32` value.
const I32_MAX: i32 = 2147483647;
/// Minimum `i64` value: -(2^63).
const I64_MIN: i64 = -9223372036854775808;
/// Maximum `i64` value: 2^63 - 1.
const I64_MAX: i64 = 9223372036854775807;

/// Size of a pointer in bytes.
pub const PTR_SIZE: u32 = 8;

/// Information about a record or tuple field.
pub record RecordField {
    /// Field name, `nil` for positional fields.
    name: ?*[u8],
    /// Field type.
    fieldType: Type,
    /// Byte offset from the start of the record.
    offset: i32,
}

/// Information about a union variant.
record UnionVariant {
    name: *[u8],
    valueType: Type,
    symbol: *mut Symbol,
}

/// Array type payload.
pub record ArrayType {
    item: *Type,
    length: u32,
}

/// Record nominal type.
pub record RecordType {
    fields: *[RecordField],
    labeled: bool,
    /// Cached layout.
    layout: Layout,
}

/// Union nominal type.
pub record UnionType {
    variants: *[UnionVariant],
    /// Cached layout.
    layout: Layout,
    /// Cached payload offset within the union aggregate.
    valOffset: u32,
    /// If all variants have void payloads.
    isAllVoid: bool,
}

/// Metadata for user-defined types.
pub union NominalType {
    /// Placeholder for a type that hasn't been fully resolved yet.
    /// Stores the declaration node for lazy resolution.
    Placeholder(*ast::Node),
    Record(RecordType),
    Union(UnionType),
}

/// Coercion plan, when coercion from one type to another.
pub union Coercion {
    /// No coercion, eg. `T -> T`.
    Identity,
    /// Eg. `u8 -> i32`. Stores both source and target types for lowering.
    NumericCast { from: Type, to: Type },
    /// Eg. `T -> ?T`. Stores the inner value type.
    OptionalLift(Type),
    /// Wrap return value in success variant of result type.
    ResultWrap,
    /// Coerce a concrete pointer to a trait object.
    TraitObject {
        /// Trait type information.
        traitInfo: *TraitType,
        /// Instance entry for v-table lookup.
        inst: *InstanceEntry,
    },
}

/// Result of resolving a module path.
record ResolvedModule {
    /// Module entry in the graph.
    entry: *module::ModuleEntry,
    /// Scope containing the module's declarations.
    scope: *mut Scope,
}

/// Type layout.
pub record Layout {
    /// Size in bytes.
    size: u32,
    /// Alignment in bytes.
    alignment: u32,
}

/// Computed union layout parameters.
record UnionLayoutInfo {
    layout: Layout,
    valOffset: u32,
    isAllVoid: bool,
}

/// Pre-computed metadata for slice range expressions.
/// Used by the lowerer.
pub record SliceRangeInfo {
    /// Element type of the resulting slice.
    itemType: *Type,
    /// Whether the resulting slice is mutable.
    mutable: bool,
    /// Static capacity if container is an array.
    capacity: ?u32,
}

/// Pre-computed metadata for `for` loop iteration.
/// Used by the lowerer to avoid re-analyzing the iterable type.
pub union ForLoopInfo {
    /// Iterating over a range expression (e.g., `for i in 0..n`).
    Range {
        valType: *Type,
        range: ast::Range,
        bindingName: ?*[u8],
        indexName: ?*[u8]
    },
    /// Iterating over an array or slice. For arrays, the length field is set.
    Collection {
        elemType: *Type,
        length: ?u32,
        bindingName: ?*[u8],
        indexName: ?*[u8]
    },
}

/// Resolved function signature details.
pub record FnType {
    paramTypes: *[*Type],
    returnType: *Type,
    throwList: *[*Type],
    localCount: u32,
    /// Whether the function is declared `unsafe`.
    isUnsafe: bool,
}

/// Describes a type computed during semantic analysis.
pub union Type {
    /// A type that couldn't be decided.
    Unknown,
    /// Types only used during inference.
    Nil, Undefined, Int,
    /// Primitive types.
    Void, Opaque, Never, Bool,
    /// Integer types.
    U8, U16, U32, U64, I8, I16, I32, I64,
    /// Range types, eg. `start..end`.
    Range {
        start: ?*Type,
        end: ?*Type,
    },
    /// Eg. `*T`.
    Pointer {
        target: *Type,
        mutable: bool,
    },
    /// Eg. `*[i32]`.
    Slice {
        item: *Type,
        mutable: bool,
    },
    /// Eg. `[i32; 32]`.
    Array(ArrayType),
    /// Eg. `?T`.
    Optional(*Type),
    /// Eg. `fn id(i32) -> i32`.
    Fn(*FnType),
    /// Named, ie. user-defined types, includes union variants.
    Nominal(*NominalType),
    /// Trait object. An erased type with v-table.
    TraitObject {
        /// Trait definition.
        traitInfo: *TraitType,
        /// Whether the pointer is mutable.
        mutable: bool,
    },
}

/// Structured diagnostic payload for type mismatches.
pub record TypeMismatch {
    expected: Type,
    actual: Type,
}

/// Structured diagnostic payload for invalid `as` casts.
pub record InvalidAsCast {
    from: Type,
    to: Type,
}

/// Diagnostic payload for argument count mismatches.
pub record CountMismatch {
    expected: u32,
    actual: u32,
}

/// Detailed payload attached to a symbol, specialized per symbol kind.
pub union SymbolData {
    /// Payload describing mutable bindings like variables or functions.
    Value {
        /// Whether the binding permits mutation.
        mutable: bool,
        /// Custom alignment requirement, or 0 for default.
        alignment: u32,
        /// Resolved type associated with the value.
        type: Type,
        /// Whether the variable's address is taken anywhere (via `&` or `&mut`).
        /// Used by the lowerer to allocate a stack slot eagerly.
        addressTaken: bool,
    },
    /// Payload describing constants.
    Constant {
        /// Resolved type associated with the value.
        type: Type,
        /// Constant value, if any.
        value: ?ConstValue,
    },
    /// Payload describing union variants and the union type they instantiate.
    Variant {
        /// Variant payload type.
        type: Type,
        /// Union declaration.
        decl: *ast::Node,
        /// Variant ordinal in declaration order.
        ordinal: u32,
        /// Variant index within the union.
        index: u32,
    },
    /// Module reference.
    Module {
        /// Module entry in the graph.
        entry: *module::ModuleEntry,
        /// Module scope.
        scope: *mut Scope,
    },
    /// Payload describing type symbols with their resolved type.
    Type(*mut NominalType),
    /// Trait symbol.
    Trait(*mut TraitType),
}

/// Resolved symbol allocated during semantic analysis.
pub record Symbol {
    /// Symbol name in source code.
    name: *[u8],
    /// Data associated with the symbol.
    data: SymbolData,
    /// Bitset of attributes applied to the declaration.
    attrs: u32,
    /// AST node that introduced the symbol.
    node: *ast::Node,
    /// Module ID this symbol belongs to. Only for module-level symbols.
    moduleId: ?u16,
}

/// Integer constant payload.
pub record ConstInt {
    /// Absolute magnitude of the value.
    magnitude: u64,
    /// Bit width of the integer.
    bits: u8,
    /// Whether the integer is signed.
    signed: bool,
    /// Whether the value is negative (only valid when `signed` is true).
    negative: bool,
}

/// Constant value recorded for literal nodes.
pub union ConstValue {
    Bool(bool),
    Char(u8),
    String(*[u8]),
    Int(ConstInt),
}

/// Integer range metadata for primitive integer types.
union IntegerRange {
    Signed {
        bits: u8,
        min: i64,
        max: i64,
        lim: u64,
    },
    Unsigned {
        bits: u8,
        max: u64,
    },
}

/// Diagnostic emitted by the analyzer.
pub record Error {
    /// Error category.
    kind: ErrorKind,
    /// Node associated with the error, if known.
    node: ?*ast::Node,
    /// Module ID where this error occurred.
    moduleId: u16,
}

/// High-level classification for semantic diagnostics.
pub union ErrorKind {
    /// Identifier declared more than once in the same scope.
    DuplicateBinding(*[u8]),
    /// Identifier referenced before it was declared.
    UnresolvedSymbol(*[u8]),
    /// Attempted to assign to an immutable binding.
    ImmutableBinding,
    /// Expected a compile-time constant expression.
    ConstExprRequired,
    /// Symbol arena exhausted while binding identifiers.
    SymbolOverflow,
    /// Expression has the wrong type.
    TypeMismatch(TypeMismatch),
    /// Numeric literal does not fit within the required range.
    NumericLiteralOverflow,
    /// Record literal omitted a required field.
    RecordFieldMissing(*[u8]),
    /// Record literal referenced a field that does not exist.
    RecordFieldUnknown(*[u8]),
    /// Brace syntax used on unlabeled record.
    RecordFieldStyleMismatch,
    /// Record literal supplied the wrong number of fields.
    RecordFieldCountMismatch(CountMismatch),
    /// Record literal fields not in declaration order.
    RecordFieldOutOfOrder { field: *[u8], prev: *[u8] },
    /// Function call supplied the wrong number of arguments.
    FnArgCountMismatch(CountMismatch),
    /// Function throws list has the wrong number of types.
    FnThrowCountMismatch(CountMismatch),
    /// Expected an identifier node.
    ExpectedIdentifier,
    /// Expected any optional type.
    ExpectedOptional,
    /// Expected a numeric type.
    ExpectedNumeric,
    /// Expected a pointer type.
    ExpectedPointer,
    /// Expected a record type.
    ExpectedRecord,
    /// Expected an array or slice value.
    ExpectedIndexable,
    /// Expected an iterable (array, slice, or range) for a `for` loop.
    ExpectedIterable,
    /// Invalid `as` cast between the provided types.
    InvalidAsCast(InvalidAsCast),
    /// Invalid alignment value specified.
    InvalidAlignmentValue(u32),
    /// Invalid module path.
    InvalidModulePath,
    /// Invalid identifier.
    InvalidIdentifier(*ast::Node),
    /// Invalid scope access.
    InvalidScopeAccess,
    /// Referenced an unknown array field.
    ArrayFieldUnknown(*[u8]),
    /// Referenced an unknown slice field.
    SliceFieldUnknown(*[u8]),
    /// Array slicing without taking an address.
    SliceRequiresAddress,
    /// Slice bounds exceed array length.
    SliceRangeOutOfBounds,
    /// Unexpected `return` statement.
    UnexpectedReturn,
    /// Unexpected module name.
    UnexpectedModuleName,
    /// Unexpected node.
    UnexpectedNode(*ast::Node),
    /// Function with non-void return type falls through without returning.
    FnMissingReturn,
    /// Function is missing a body.
    FnMissingBody,
    /// Function body is not expected.
    FnUnexpectedBody,
    /// Intrinsic function must be declared extern.
    IntrinsicRequiresExtern,
    /// Encountered loop control outside of a loop construct.
    InvalidLoopControl,
    /// `try` used when the enclosing function does not declare throws.
    TryRequiresThrows,
    /// `try` used to propagate an error not declared by the enclosing function.
    TryIncompatibleError,
    /// `throw` used when the enclosing function does not declare throws.
    ThrowRequiresThrows,
    /// `throw` used with an error type not declared by the enclosing function.
    ThrowIncompatibleError,
    /// `try` applied to an expression that cannot throw.
    TryNonThrowing,
    /// Inferred catch binding used with multi-error callee.
    TryCatchMultiError,
    /// Duplicate error type in typed catch clauses.
    TryCatchDuplicateType,
    /// Typed catch clauses do not cover all error types.
    TryCatchNonExhaustive,
    /// Called a fallible function without using `try`.
    MissingTry,
    /// Cannot use opaque type in this context.
    OpaqueTypeNotAllowed,
    /// Cannot dereference pointer to opaque type.
    OpaqueTypeDeref,
    /// Cannot perform pointer arithmetic on opaque pointer.
    OpaquePointerArithmetic,
    /// Cannot infer type from context.
    CannotInferType,
    /// Cannot assign a void value to a variable.
    CannotAssignVoid,
    /// `default` attribute used on a non-function declaration.
    DefaultAttrOnlyOnFn,
    /// Union variant requires a payload but none was provided.
    UnionVariantPayloadMissing(*[u8]),
    /// Union variant does not expect a payload but one was provided.
    UnionVariantPayloadUnexpected(*[u8]),
    /// `match` on a union omits a variant without a `default` case.
    UnionMatchNonExhaustive(*[u8]),
    /// `match` on an optional is missing a value case.
    OptionalMatchMissingValue,
    /// `match` on an optional is missing a nil case.
    OptionalMatchMissingNil,
    /// `match` on a bool is missing a case (true or false).
    BoolMatchMissing(bool),
    /// `match` on a non-union type is missing a catch-all.
    MatchNonExhaustive,
    /// `match` has more than one catch-all prongs.
    DuplicateCatchAll,
    /// `match` has a duplicate case pattern.
    DuplicateMatchPattern,
    /// `match` has an unreachable `else`: all cases are already handled.
    UnreachableElse,
    /// Builtin called with wrong number of arguments.
    BuiltinArgCountMismatch(CountMismatch),
    /// Instance method receiver mutability does not match the trait declaration.
    ReceiverMutabilityMismatch,
    /// Duplicate instance declaration for the same (trait, type) pair.
    DuplicateInstance,
    /// Instance declaration is missing a required trait method.
    MissingTraitMethod(*[u8]),
    /// Trait name used as a value expression.
    UnexpectedTraitName,
    /// Trait method receiver does not point to the declaring trait.
    TraitReceiverMismatch,
    /// Function declaration has too many parameters.
    FnParamOverflow(CountMismatch),
    /// Function declaration has too many throws.
    FnThrowOverflow(CountMismatch),
    /// Trait declaration has too many methods.
    TraitMethodOverflow(CountMismatch),
    /// Instance declaration is missing a required supertrait instance.
    MissingSupertraitInstance(*[u8]),
    /// Unsafe operation outside of an `unsafe` block or function.
    UnsafeRequired,
    /// Call to an unsafe function outside of an `unsafe` context.
    UnsafeCallRequired,
    /// Internal error.
    Internal,
}

/// Diagnostics returned by the analyzer.
pub record Diagnostics {
    errors: *mut [Error],
}

/// Call context.
union CallCtx {
    /// Normal function call.
    Normal,
    /// Fallible function call, ie. `try f()`.
    Try,
}

/// Result of resolving a record literal's type name.
record ResolvedRecordLitType {
    /// The record nominal type to use for field checking.
    recordType: *NominalType,
    /// The result type of the literal (record type or union type for variants).
    resultType: Type,
}

/// Result of checking for a `super` path prefix.
record SuperAccessResult {
    scope: *mut Scope,
    child: *ast::Node,
}

/// Node-specific resolver metadata.
pub union NodeExtra {
    /// No extra data for this node.
    None,
    /// Resolved field index for record literal fields.
    RecordField { index: u32 },
    /// Slice range metadata for subscript expressions with ranges.
    SliceRange(SliceRangeInfo),
    /// Cached union variant metadata for patterns/constructors.
    UnionVariant { ordinal: u32, tag: u32 },
    /// Match prong metadata.
    MatchProng { catchAll: bool },
    /// Match expression metadata.
    Match { isConst: bool },
    /// For-loop iteration metadata.
    ForLoop(ForLoopInfo),
    /// Trait method call metadata.
    TraitMethodCall {
        /// Trait definition.
        traitInfo: *TraitType,
        /// Method index in the v-table.
        methodIndex: u32,
    },
    /// Standalone method call metadata.
    MethodCall { method: *MethodEntry },
    /// Slice `.append(val, allocator)` method call.
    SliceAppend { elemType: *Type },
    /// Slice `.delete(index)` method call.
    SliceDelete { elemType: *Type },
}

/// Combined resolver metadata for a single AST node.
pub record NodeData {
    /// Resolved type for this node.
    ty: Type,
    /// Coercion plan applied to this node.
    coercion: Coercion,
    /// Symbol associated with this node.
    sym: ?*mut Symbol,
    /// Constant value for literal nodes.
    constValue: ?ConstValue,
    /// Lexical scope owned by this node.
    scope: ?*mut Scope,
    /// Node-specific extra data.
    extra: NodeExtra,
}

/// Table storing all resolver metadata indexed by node ID.
record NodeDataTable {
    entries: *mut [NodeData],
}

/// Lexical scope.
pub record Scope {
    /// Owning AST node, or `nil` for the root scope.
    owner: ?*ast::Node,
    /// Parent/enclosing scope.
    parent: ?*mut Scope,
    /// Module ID if this is a module scope.
    moduleId: ?u16,
    /// Symbols introduced inside the scope, allocated from the arena.
    symbols: *mut [*mut Symbol],
    /// Number of live symbols.
    symbolsLen: u32,
}

/// An object used by the enter and exit functions for module scopes.
record ModuleScope {
    /// Module root node.
    root: *ast::Node,
    /// Module entry in graph.
    entry: *module::ModuleEntry,
    /// The newly entered scope.
    newScope: *mut Scope,
    /// The previous scope.
    prevScope: *mut Scope,
    /// The previous module.
    prevMod: u16,
}

/// Loop context for tracking control flow within loops.
record LoopCtx {
    /// Whether a reachable break was encountered in this loop.
    /// This is used to determine whether a loop diverges.
    hasBreak: bool,
}

/// Configuration for semantic analysis.
pub record Config {
    /// Whether we're building in test mode.
    buildTest: bool,
}

/// How pattern bindings are created during match.
pub union MatchBy {
    /// Match by value.
    Value,
    /// Match by immutable reference.
    Ref,
    /// Match by mutable reference.
    MutRef,
}

/// State of a match statement being resolved.
// TODO: This is only used because of the maximum function param limitation.
record MatchState {
    /// Is the match catch-all?
    catchAll: bool,
    /// Is the match constant?
    isConst: bool
}

/// Result of unwrapping a type for pattern matching.
pub record MatchSubject {
    /// The effective type to match against.
    effectiveTy: Type,
    /// How bindings should be created.
    by: MatchBy,
}

/// Unwrap a pointer type for pattern matching.
pub fn unwrapMatchSubject(ty: Type) -> MatchSubject {
    if let case Type::Pointer { target, mutable } = ty {
        let by = MatchBy::MutRef if mutable else MatchBy::Ref;
        return MatchSubject { effectiveTy: *target, by };
    }
    return MatchSubject { effectiveTy: ty, by: MatchBy::Value };
}

/// Global resolver state.
pub record Resolver {
    /// Current scope.
    scope: *mut Scope,
    /// Package scope containing package roots and top-level symbols.
    pkgScope: *mut Scope,
    /// Stack of loop contexts for nested loops.
    loopStack: [LoopCtx; MAX_LOOP_DEPTH],
    /// Current loop depth, indexes into loop stack.
    loopDepth: u32,
    /// Signature of the function currently being analyzed.
    currentFn: ?*FnType,
    /// Unsafe context depth. Non-zero inside `unsafe fn` or `unsafe { }` blocks.
    unsafeDepth: u32,
    /// Current module being analyzed.
    currentMod: u16,
    /// Configuration for semantic analysis.
    config: Config,
    /// Unified arena for symbols, scopes, and nominal type.
    arena: alloc::Arena,
    /// Combined semantic metadata table indexed by node ID.
    nodeData: NodeDataTable,
    /// Linked list of interned types.
    types: ?*TypeNode,
    /// Diagnostics recorded so far.
    errors: *mut [Error],
    /// Module graph for the current package.
    moduleGraph: *module::ModuleGraph,
    /// Cache of module scopes indexed by module ID.
    moduleScopes: [?*mut Scope; module::MAX_MODULES],
    /// Trait instance registry.
    instances: [InstanceEntry; MAX_INSTANCES],
    /// Number of registered instances.
    instancesLen: u32,
    /// Standalone method registry.
    methods: [MethodEntry; MAX_METHODS],
    /// Number of registered standalone methods.
    methodsLen: u32,
}

/// Internal error sentinel thrown when analysis cannot proceed.
pub union ResolveError {
    Failure,
}

/// Node in the type interning linked list.
record TypeNode {
    ty: Type,
    next: ?*TypeNode,
}

/// Allocate and intern a type in the arena, returning a pointer for deduplication.
pub fn allocType(self: *mut Resolver, ty: Type) -> *Type {
    // Search existing types for a match.
    let mut cursor = self.types;
    while let node = cursor {
        if node.ty == ty {
            return &node.ty;
        }
        cursor = node.next;
    }
    // Allocate a new type node from the arena.
    let node = try! alloc::alloc(
        &mut self.arena, @sizeOf(TypeNode), @alignOf(TypeNode)
    ) as *mut TypeNode;

    *node = TypeNode { ty, next: self.types };
    self.types = node;

    return &node.ty;
}

/// Allocate a nominal type descriptor and return a pointer to it.
fn allocNominalType(self: *mut Resolver, info: NominalType) -> *mut NominalType {
    // Nb. We don't attempt to de-duplicate nominal type entries,
    // since they don't carry node information and we create
    // placeholder entries when binding symbols.
    let entry = try! alloc::alloc(
        &mut self.arena, @sizeOf(NominalType), @alignOf(NominalType)
    ) as *mut NominalType;

    *entry = info;

    return entry;
}

/// Allocate a function type descriptor and return a pointer to it.
fn allocFnType(self: *mut Resolver, info: FnType) -> *FnType {
    let entry = try! alloc::alloc(
        &mut self.arena, @sizeOf(FnType), @alignOf(FnType)
    ) as *mut FnType;

    *entry = info;

    return entry;
}

/// Returns an error, if any, associated with the given node.
fn errorForNode(self: *Resolver, node: *ast::Node) -> ?*Error {
    for i in 0..self.errors.len {
        let err = &self.errors[i];
        if err.node == node {
            return err;
        }
    }
    return nil;
}

/// Storage buffers used by the analyzer.
pub record ResolverStorage {
    /// Unified arena for symbols, scopes, and nominal type.
    arena: alloc::Arena,
    /// Node semantic metadata indexed by node ID.
    nodeData: *mut [NodeData],
    /// Package scope.
    pkgScope: *mut Scope,
    /// Error storage.
    errors: *mut [Error],
}

/// Input for resolving a single package.
pub record Pkg {
    /// Root module entry.
    rootEntry: *module::ModuleEntry,
    /// Root AST node.
    rootAst: *ast::Node,
}

/// Construct a resolver with module context and backing storage.
pub fn resolver(
    storage: ResolverStorage,
    config: Config
) -> Resolver {
    let mut arena = storage.arena;
    let symbols = try! alloc::allocSlice(
        &mut arena, @sizeOf(*mut Symbol), @alignOf(*mut Symbol), MAX_MODULE_SYMBOLS
    ) as *mut [*mut Symbol];

    // Initialize the root scope.
    // TODO: Set this up when declaring `PKG_SCOPE`, not here.
    *storage.pkgScope = Scope {
        owner: nil,
        parent: nil,
        moduleId: nil,
        symbols,
        symbolsLen: 0,
    };

    // Clear all node semantic metadata to sentinel values.
    // TODO: Use array repeat literal?
    for i in 0..storage.nodeData.len {
        storage.nodeData[i] = NodeData {
            ty: Type::Unknown,
            coercion: Coercion::Identity,
            sym: nil,
            constValue: nil,
            scope: nil,
            extra: NodeExtra::None,
        };
    }

    let mut moduleScopes: [?*mut Scope; module::MAX_MODULES] = undefined;
    // TODO: Simplify.
    for i in 0..moduleScopes.len {
        moduleScopes[i] = nil;
    }
    return Resolver {
        scope: storage.pkgScope,
        pkgScope: storage.pkgScope,
        loopStack: undefined,
        loopDepth: 0,
        currentFn: nil,
        unsafeDepth: 0,
        currentMod: 0,
        config,
        arena,
        nodeData: NodeDataTable { entries: storage.nodeData },
        types: nil,
        errors: @sliceOf(storage.errors.ptr, 0, storage.errors.len),
        // TODO: Shouldn't be undefined.
        moduleGraph: undefined,
        moduleScopes,
        instances: undefined,
        instancesLen: 0,
        methods: undefined,
        methodsLen: 0,
    };
}

/// Return `true` if there are no errors in the diagnostics.
pub fn success(diag: *Diagnostics) -> bool {
    return diag.errors.len == 0;
}

/// Retrieve an error diagnostic by index, if present.
pub fn errorAt(errs: *[Error], index: u32) -> ?*Error {
    if index >= errs.len {
        return nil;
    }
    return &errs[index];
}

/// Record an error diagnostic and return an error sentinel suitable for throwing.
fn emitError(self: *mut Resolver, node: ?*ast::Node, kind: ErrorKind) -> ResolveError {
    // If our error list is full, just return an error without recording it.
    if self.errors.len >= self.errors.cap {
        return ResolveError::Failure;
    }
    // Don't record more than one error per node.
    if let n = node; errorForNode(self, n) != nil {
        return ResolveError::Failure;
    }
    let idx = self.errors.len;
    self.errors = @sliceOf(self.errors.ptr, idx + 1, self.errors.cap);
    self.errors[idx] = Error { kind, node, moduleId: self.currentMod };

    return ResolveError::Failure;
}

/// Like [`emitError`], but for type mismatches specifically.
fn emitTypeMismatch(self: *mut Resolver, node: ?*ast::Node, mismatch: TypeMismatch) -> ResolveError {
    return emitError(self, node, ErrorKind::TypeMismatch(mismatch));
}

/// Allocate a scope object with the given symbol capacity.
fn allocScope(self: *mut Resolver, owner: *ast::Node, capacity: u32) -> *mut Scope {
    // Check for an existing scope for this node, and don't allocate a new
    // one in that case.
    if let scope = scopeFor(self, owner) {
        return scope;
    }
    assert owner.id < self.nodeData.entries.len, "allocScope: node ID out of bounds";
    let p = try! alloc::alloc(&mut self.arena, @sizeOf(Scope), @alignOf(Scope));
    let entry = p as *mut Scope;

    // Allocate symbols from the arena.
    let symbols = try! alloc::allocSlice(
        &mut self.arena, @sizeOf(*mut Symbol), @alignOf(*mut Symbol), capacity
    ) as *mut [*mut Symbol];

    *entry = Scope { owner, parent: nil, moduleId: nil, symbols, symbolsLen: 0 };
    self.nodeData.entries[owner.id].scope = entry;

    return entry;
}

/// Enter a new local scope that is the child of the current scope.
/// This creates a parent/child relationship that means that lookups in the
/// child scope can recurse upwards.
pub fn enterScope(self: *mut Resolver, owner: *ast::Node) -> *Scope {
    let scope = allocScope(self, owner, MAX_LOCAL_SYMBOLS);
    scope.parent = self.scope;
    self.scope = scope;
    return scope;
}

/// Enter a module scope. Returns an object that can be used to exit the scope.
pub fn enterModuleScope(self: *mut Resolver, owner: *ast::Node, module: *module::ModuleEntry) -> ModuleScope {
    let prevScope = self.scope;
    let prevMod = self.currentMod;
    let scope = allocScope(self, owner, MAX_MODULE_SYMBOLS);

    self.scope = scope;
    self.scope.moduleId = module.id;
    self.currentMod = module.id;
    // TODO: Allow any unsigned integer to index an array.
    self.moduleScopes[module.id as u32] = scope;

    return ModuleScope { root: owner, entry: module, newScope: scope, prevScope, prevMod };
}

/// Enter a sub-module. Changes the current scope into that of the sub-module.
fn enterSubModule(self: *mut Resolver, name: *[u8], node: *ast::Node) -> ModuleScope throws (ResolveError) {
    let modEntry = module::findChild(self.moduleGraph, name, self.currentMod)
        else throw emitError(self, node, ErrorKind::UnresolvedSymbol(name));
    let modRoot = modEntry.ast
        else panic "enterSubModule: analyzing module that wasn't parsed";

    return enterModuleScope(self, modRoot, modEntry);
}

/// Exit a module scope, given the object returned by `enterModuleScope`.
pub fn exitModuleScope(self: *mut Resolver, entry: ModuleScope) {
    self.scope = entry.prevScope;
    self.currentMod = entry.prevMod;
}

/// Exit the most recent scope.
pub fn exitScope(self: *mut Resolver) {
    let parent = self.scope.parent else {
        // TODO: This should be a panic, but one of the tests hits this
        // clause, which might be a bug in the generator.
        return;
    };
    self.scope = parent;
}

/// Visit the body of a loop while tracking nesting depth.
fn visitLoop(self: *mut Resolver, body: *ast::Node) -> Type
    throws (ResolveError)
{
    assert self.loopDepth < MAX_LOOP_DEPTH, "visitLoop: loop nesting depth exceeded";
    self.loopStack[self.loopDepth] = LoopCtx { hasBreak: false };
    self.loopDepth += 1;

    let ty = try infer(self, body) catch {
        assert self.loopDepth != 0, "visitLoop: loop depth underflow";
        self.loopDepth -= 1;
        throw ResolveError::Failure;
    };
    // Pop and check if break was encountered.
    self.loopDepth -= 1;

    if self.loopStack[self.loopDepth].hasBreak {
        return Type::Void;
    }
    return Type::Never;
}

/// Require that loop control statements appear inside a loop.
fn ensureInsideLoop(self: *mut Resolver, node: *ast::Node) throws (ResolveError) {
    if self.loopDepth == 0 {
        throw emitError(self, node, ErrorKind::InvalidLoopControl);
    }
}

/// Bind a loop pattern to the provided type.
fn bindForLoopPattern(self: *mut Resolver, pattern: *ast::Node, ty: Type, mutable: bool)
    throws (ResolveError)
{
    match pattern.value {
        case ast::NodeValue::Placeholder, ast::NodeValue::Ident(_) => {
            let _ = try bindValueIdent(self, pattern, pattern, ty, mutable, 0, 0);
        }
        else => {
            let actualTy = try checkAssignable(self, pattern, ty);
            setNodeType(self, pattern, actualTy);
        }
    }
}

/// Set the expected return type for a new function body.
fn enterFn(self: *mut Resolver, node: *ast::Node, ty: *FnType) {
    assert self.currentFn == nil, "enterFn: already in a function";
    self.currentFn = ty;
    enterScope(self, node);
}

/// Clear the expected return type when leaving a function body.
fn exitFn(self: *mut Resolver) {
    if self.currentFn == nil {
        // TODO: This should be a panic, but one of the tests hits this
        // clause, which might be a bug in the generator.
        return;
    }
    self.currentFn = nil;
    exitScope(self);
}

/// Extract the identifier text from a node.
fn nodeName(self: *mut Resolver, node: *ast::Node) -> *[u8]
    throws (ResolveError)
{
    let case ast::NodeValue::Ident(name) = node.value
        else throw emitError(self, node, ErrorKind::ExpectedIdentifier);
    return name;
}

/// Associate a resolved symbol with an AST node.
fn setNodeSymbol(self: *mut Resolver, node: *ast::Node, symbol: *mut Symbol) {
    if let existingSym = self.nodeData.entries[node.id].sym {
        panic "setNodeSymbol: a symbol is already associated with this node";
    }
    self.nodeData.entries[node.id].sym = symbol;
}

/// Associate a resolved type with an AST node and return it.
fn setNodeType(self: *mut Resolver, node: *ast::Node, ty: Type) -> Type {
    if ty == Type::Unknown {
        // In this case, we simply don't associate a type.
        return ty;
    }
    self.nodeData.entries[node.id].ty = ty;

    return ty;
}

/// Unify the types of two branches for control flow. Returns `never` only if
/// both branches diverge, otherwise returns `void`. If the else branch is
/// absent, we assume it doesn't diverge.
fn unifyBranches(left: Type, right: ?Type) -> Type {
    if left == Type::Never {
        if let ty = right; ty == Type::Never {
            return Type::Never;
        }
    }
    return Type::Void;
}

/// Associate a coercion plan with an AST node.
fn setNodeCoercion(self: *mut Resolver, node: *ast::Node, coercion: Coercion) -> Coercion {
    if coercion == Coercion::Identity {
        return coercion;
    }
    self.nodeData.entries[node.id].coercion = coercion;

    return coercion;
}

/// Associate a constant value with an AST node.
fn setNodeConstValue(self: *mut Resolver, node: *ast::Node, value: ConstValue) {
    self.nodeData.entries[node.id].constValue = value;
}

/// Associate a record field index with a record literal field node.
fn setRecordFieldIndex(self: *mut Resolver, node: *ast::Node, index: u32) {
    self.nodeData.entries[node.id].extra = NodeExtra::RecordField { index };
}

/// Associate slice range metadata with a subscript expression.
fn setSliceRangeInfo(self: *mut Resolver, node: *ast::Node, info: SliceRangeInfo) {
    self.nodeData.entries[node.id].extra = NodeExtra::SliceRange(info);
}

/// Associate union variant metadata with a pattern or constructor node.
fn setVariantInfo(self: *mut Resolver, node: *ast::Node, ordinal: u32, tag: u32) {
    self.nodeData.entries[node.id].extra = NodeExtra::UnionVariant { ordinal, tag };
}

/// Associate trait method call metadata with a call node.
fn setTraitMethodCall(self: *mut Resolver, node: *ast::Node, traitInfo: *TraitType, methodIndex: u32) {
    self.nodeData.entries[node.id].extra = NodeExtra::TraitMethodCall { traitInfo, methodIndex };
}

/// Associate for-loop metadata with a for-loop node.
fn setForLoopInfo(self: *mut Resolver, node: *ast::Node, info: ForLoopInfo) {
    self.nodeData.entries[node.id].extra = NodeExtra::ForLoop(info);
}

/// Retrieve the constant value associated with a node, if any.
pub fn constValueEntry(self: *Resolver, node: *ast::Node) -> ?ConstValue {
    return self.nodeData.entries[node.id].constValue;
}

/// Get the resolved record field index for a record literal field node.
pub fn recordFieldIndexFor(self: *Resolver, node: *ast::Node) -> ?u32 {
    if let case NodeExtra::RecordField { index } = self.nodeData.entries[node.id].extra {
        return index;
    }
    return nil;
}

/// Get the slice range metadata for a subscript expression with a range index.
pub fn sliceRangeInfoFor(self: *Resolver, node: *ast::Node) -> ?SliceRangeInfo {
    if let case NodeExtra::SliceRange(info) = self.nodeData.entries[node.id].extra {
        return info;
    }
    return nil;
}

/// Get the for-loop metadata for a for-loop node.
pub fn forLoopInfoFor(self: *Resolver, node: *ast::Node) -> ?ForLoopInfo {
    if let case NodeExtra::ForLoop(info) = self.nodeData.entries[node.id].extra {
        return info;
    }
    return nil;
}

/// Associate match prong metadata with a match prong node.
fn setProngCatchAll(self: *mut Resolver, node: *ast::Node, catchAll: bool) {
    self.nodeData.entries[node.id].extra = NodeExtra::MatchProng { catchAll };
}

/// Check if a prong is catch-all.
pub fn isProngCatchAll(self: *Resolver, node: *ast::Node) -> bool {
    if let case NodeExtra::MatchProng { catchAll } = self.nodeData.entries[node.id].extra {
        return catchAll;
    }
    return false;
}

/// Set match metadata.
fn setMatchConst(self: *mut Resolver, node: *ast::Node, isConst: bool) {
    self.nodeData.entries[node.id].extra = NodeExtra::Match { isConst };
}

/// Check if a match has all constant patterns.
pub fn isMatchConst(self: *Resolver, node: *ast::Node) -> bool {
    if let case NodeExtra::Match { isConst } = self.nodeData.entries[node.id].extra {
        return isConst;
    }
    return false;
}

/// Get the resolver metadata for a node.
pub fn nodeData(self: *Resolver, node: *ast::Node) -> *NodeData {
    return &self.nodeData.entries[node.id];
}

/// Get the type for a node, or `nil` if unknown.
pub fn typeFor(self: *Resolver, node: *ast::Node) -> ?Type {
    let ty = self.nodeData.entries[node.id].ty;
    if ty == Type::Unknown {
        return nil;
    }
    return ty;
}

/// Get the scope associated with a node.
pub fn scopeFor(self: *Resolver, node: *ast::Node) -> ?*mut Scope {
    return self.nodeData.entries[node.id].scope;
}

/// Get the symbol bound to a node.
pub fn symbolFor(self: *Resolver, node: *ast::Node) -> ?*mut Symbol {
    return self.nodeData.entries[node.id].sym;
}

/// Get the coercion plan associated with a node, if any.
pub fn coercionFor(self: *Resolver, node: *ast::Node) -> ?Coercion {
    let c = self.nodeData.entries[node.id].coercion;
    if c == Coercion::Identity {
        return nil;
    }
    return c;
}

/// Get the module ID for a symbol by walking up its scope chain.
pub fn moduleIdForSymbol(self: *Resolver, sym: *Symbol) -> ?u16 {
    // For module-level symbols, return the cached module ID.
    if let id = sym.moduleId {
        return id;
    }
    // For module symbols, return the module ID directly.
    if let case SymbolData::Module { entry, .. } = sym.data {
        return entry.id;
    }
    // If this node has its own scope (functions, types, etc.), walk up from there.
    if let scope = self.nodeData.entries[sym.node.id].scope {
        return findModuleForScope(scope);
    }
    return nil;
}

/// Get the binding node for a variant pattern.
/// Returns the argument node if this is a variant constructor with a non-placeholder binding.
pub fn variantPatternBinding(self: *Resolver, pattern: *ast::Node) -> ?*ast::Node {
    let case ast::NodeValue::Call(call) = pattern.value
        else return nil;
    let sym = symbolFor(self, call.callee)
        else return nil;
    let case SymbolData::Variant { .. } = sym.data
        else return nil;

    if call.args.len == 0 {
        return nil;
    }
    let arg = call.args[0];

    if let case ast::NodeValue::Placeholder = arg.value {
        return nil;
    }
    return arg;
}

/// Allocate a new symbol, and return a reference to it.
fn allocSymbol(self: *mut Resolver, data: SymbolData, name: *[u8], node: *ast::Node, attrs: u32) -> *mut Symbol {
    let sym = try! alloc::alloc(&mut self.arena, @sizeOf(Symbol), @alignOf(Symbol)) as *mut Symbol;
    *sym = Symbol { name, data, attrs, node, moduleId: nil };

    return sym;
}

/// Check that a type is boolean, otherwise throw an error.
fn checkBoolean(self: *mut Resolver, node: *ast::Node) -> Type throws (ResolveError) {
    return try checkEqual(self, node, Type::Bool);
}

/// Check that a type is numeric, otherwise throw an error.
fn checkNumeric(self: *mut Resolver, node: *ast::Node) -> Type throws (ResolveError) {
    let ty = try infer(self, node);
    if not isNumericType(ty) {
        throw emitError(self, node, ErrorKind::ExpectedNumeric);
    }
    return ty;
}

/// Check if a type is a numeric type.
fn isNumericType(ty: Type) -> bool {
    match ty {
        case Type::U8, Type::U16, Type::U32, Type::U64,
             Type::I8, Type::I16, Type::I32, Type::I64,
             Type::Int => return true,
        else => return false,
    }
}

/// Check if a type is an unsigned integer type.
pub fn isUnsignedIntegerType(ty: Type) -> bool {
    match ty {
        case Type::U8, Type::U16, Type::U32, Type::U64 => return true,
        else => return false,
    }
}

/// Return the maximum of two u32 values.
fn max(a: u32, b: u32) -> u32 {
    if a > b {
        return a;
    }
    return b;
}

/// Get the layout of a type.
pub fn getTypeLayout(ty: Type) -> Layout {
    match ty {
        case Type::Void, Type::Never => return Layout { size: 0, alignment: 0 },
        case Type::Bool, Type::U8, Type::I8 => return Layout { size: 1, alignment: 1 },
        case Type::U16, Type::I16 => return Layout { size: 2, alignment: 2 },
        case Type::U32, Type::I32 => return Layout { size: 4, alignment: 4 },
        case Type::Int => return Layout { size: 8, alignment: 8 },
        case Type::U64, Type::I64 => return Layout { size: 8, alignment: 8 },
        case Type::Pointer { .. },
             Type::Fn(_) => return Layout { size: PTR_SIZE, alignment: PTR_SIZE },
        case Type::Slice { .. },
             Type::TraitObject { .. } => return Layout { size: PTR_SIZE * 2, alignment: PTR_SIZE },
        case Type::Array(arr) => return getArrayLayout(arr),
        case Type::Optional(inner) => return getOptionalLayout(*inner),
        case Type::Nominal(info) => return getNominalLayout(*info),
        else => {
            panic "getTypeLayout: the given type cannot be layed out";
        }
    }
}

/// Get the layout of a type or value.
pub fn getLayout(self: *Resolver, node: *ast::Node, ty: Type) -> Layout {
    let mut layout = getTypeLayout(ty);
    // Check for symbol-specific alignment override.
    if let sym = symbolFor(self, node) {
        if let case SymbolData::Value { alignment, .. } = sym.data {
            if alignment > 0 {
                layout.alignment = alignment;
            }
        }
    }
    return layout;
}

/// Get the layout of an array type.
pub fn getArrayLayout(arr: ArrayType) -> Layout {
    let itemLayout = getTypeLayout(*arr.item);
    return Layout {
        size: itemLayout.size * arr.length,
        alignment: itemLayout.alignment,
    };
}

/// Get the layout of an optional type.
pub fn getOptionalLayout(inner: Type) -> Layout {
    // Nullable types use null pointer optimization -- no tag byte needed.
    if isNullableType(inner) {
        return getTypeLayout(inner);
    }
    let innerLayout = getTypeLayout(inner);
    let tagSize: u32 = 1;
    let valOffset = mem::alignUp(tagSize, innerLayout.alignment);
    let alignment = max(innerLayout.alignment, 1);

    return Layout {
        size: mem::alignUp(valOffset + innerLayout.size, alignment),
        alignment,
    };
}

/// Get the payload offset within an optional aggregate.
pub fn getOptionalValOffset(inner: Type) -> u32 {
    let innerLayout = getTypeLayout(inner);
    return mem::alignUp(1, innerLayout.alignment);
}

/// Check if a type is optional.
pub fn isOptionalType(ty: Type) -> bool {
    match ty {
        case Type::Optional(_) => return true,
        else => return false,
    }
}

/// Check if a type uses null pointer optimization.
/// This applies to optional pointers `?*T` and optional slices `?*[T]`,
/// where `nil` is represented as a null data pointer with no tag byte.
pub fn isOptionalPointer(ty: Type) -> bool {
    if let case Type::Optional(inner) = ty {
        return isNullableType(*inner);
    }
    return false;
}

/// Check if a type uses the optional aggregate representation.
pub fn isOptionalAggregate(ty: Type) -> bool {
    if let case Type::Optional(inner) = ty {
        return not isNullableType(*inner);
    }
    return false;
}

/// Check if a type can use null to represent `nil`.
/// Pointers and slices have a data pointer that is never null when valid.
pub fn isNullableType(ty: Type) -> bool {
    match ty {
        case Type::Pointer { .. }, Type::Slice { .. } => return true,
        else => return false,
    }
}

/// Get the layout of a nominal type.
pub fn getNominalLayout(info: NominalType) -> Layout {
    match info {
        case NominalType::Placeholder(_) => {
            panic "getNominalLayout: placeholder type";
        }
        case NominalType::Record(recordType) => {
            return recordType.layout;
        }
        case NominalType::Union(unionType) => {
            return unionType.layout;
        }
    }
}

/// Get the layout of a result aggregate with a tag and the larger payload.
pub fn getResultLayout(payload: Type, throwList: *[*Type]) -> Layout {
    let payloadLayout = getTypeLayout(payload);
    let mut maxSize = payloadLayout.size;
    let mut maxAlign = payloadLayout.alignment;

    for errType in throwList {
        let errLayout = getTypeLayout(*errType);
        maxSize = max(maxSize, errLayout.size);
        maxAlign = max(maxAlign, errLayout.alignment);
    }
    return Layout {
        size: PTR_SIZE + maxSize,
        alignment: max(PTR_SIZE, maxAlign),
    };
}

/// Compute the layout for a union given its resolved variants.
fn computeUnionLayout(variants: *[UnionVariant]) -> UnionLayoutInfo {
    let tagSize: u32 = 1;
    let mut maxVarSize: u32 = 0;
    let mut maxVarAlign: u32 = 1;
    let mut isAllVoid: bool = true;

    for variant in variants {
        if variant.valueType != Type::Void {
            isAllVoid = false;
            let payloadLayout = getTypeLayout(variant.valueType);
            maxVarSize = max(maxVarSize, payloadLayout.size);
            maxVarAlign = max(maxVarAlign, payloadLayout.alignment);
        }
    }
    let unionAlignment: u32 = max(1, maxVarAlign);
    let unionValOffset: u32 = mem::alignUp(tagSize, maxVarAlign);
    let unionLayout = Layout {
        size: mem::alignUp(unionValOffset + maxVarSize, unionAlignment),
        alignment: unionAlignment,
    };
    return UnionLayoutInfo { layout: unionLayout, valOffset: unionValOffset, isAllVoid };
}

/// Compute the discriminant tag for a variant, advancing the iota counter.
/// If the variant has an explicit `= N` value, uses that; otherwise uses iota.
fn variantTag(variantDecl: ast::UnionDeclVariant, iota: *mut u32) -> u32 {
    let mut tag: u32 = *iota;
    if let valueNode = variantDecl.value {
        let case ast::NodeValue::Number(lit) = valueNode.value
            else panic "variantTag: expected number literal";
        tag = lit.magnitude as u32;
    }
    *iota = tag + 1;
    return tag;
}

/// Check if a type is a union without payloads.
pub fn isVoidUnion(ty: Type) -> bool {
    let case Type::Nominal(NominalType::Union(unionType)) = ty
        else return false;
    return unionType.isAllVoid;
}

/// Check if a type should be treated as an address-like value.
fn isAddressType(ty: Type) -> bool {
    match ty {
        case Type::Pointer { .. }, Type::Slice { .. }, Type::Fn(_) => return true,
        else => return false,
    }
}

/// Return the representable range for an integer type.
fn integerRange(ty: Type) -> ?IntegerRange {
    match ty {
        case Type::I8 => return IntegerRange::Signed {
            bits: 8,
            min: I8_MIN as i64,
            max: I8_MAX as i64,
            lim: (I8_MAX as u64) + 1,
        },
        case Type::I16 => return IntegerRange::Signed {
            bits: 16,
            min: I16_MIN as i64,
            max: I16_MAX as i64,
            lim: (I16_MAX as u64) + 1,
        },
        case Type::I32 => return IntegerRange::Signed {
            bits: 32,
            min: I32_MIN as i64,
            max: I32_MAX as i64,
            lim: (I32_MAX as u64) + 1,
        },
        case Type::I64, Type::Int => return IntegerRange::Signed {
            bits: 64,
            min: I64_MIN,
            max: I64_MAX,
            lim: (I64_MAX as u64) + 1,
        },
        case Type::U8 => return IntegerRange::Unsigned { bits: 8, max: U8_MAX as u64 },
        case Type::U16 => return IntegerRange::Unsigned { bits: 16, max: U16_MAX as u64 },
        case Type::U32 => return IntegerRange::Unsigned { bits: 32, max: parser::U32_MAX as u64 },
        case Type::U64 => return IntegerRange::Unsigned { bits: 64, max: parser::U64_MAX },
        else => return nil,
    }
}

/// Validate that an integer constant fits within the target type's range.
fn validateConstIntRange(value: ConstValue, target: Type) -> bool {
    let range = integerRange(target)
        else panic "validateConstIntRange: expected integer type";
    let case ConstValue::Int(int) = value
        else panic "validateConstIntRange: expected integer constant";

    match range {
        case IntegerRange::Signed { lim, .. } => {
            if int.negative {
                if int.magnitude > lim {
                    return false;
                }
                return true;
            }
            if int.magnitude > lim - 1 {
                return false;
            }
            return true;
        }
        case IntegerRange::Unsigned { max, .. } => {
            if int.negative or int.magnitude > max {
                return false;
            }
            return true;
        }
    }
}

/// Ensure all nested nominal types in a type are resolved.
fn ensureTypeResolved(self: *mut Resolver, ty: Type, site: *ast::Node) throws (ResolveError) {
    match ty {
        case Type::Nominal(info) => try ensureNominalResolved(self, info, site),
        case Type::Array(arr) => try ensureTypeResolved(self, *arr.item, site),
        case Type::Slice { item, .. } => try ensureTypeResolved(self, *item, site),
        case Type::Pointer { .. } => {}, // Pointers have fixed layout, don't recurse.
        case Type::Optional(inner) => try ensureTypeResolved(self, *inner, site),
        else => {},
    }
}

/// Ensure a nominal type has its body resolved.
fn ensureNominalResolved(self: *mut Resolver, tyInfo: *NominalType, site: *ast::Node)
    throws (ResolveError)
{
    if let case NominalType::Placeholder(declNode) = *tyInfo {
        // When resolving on-demand (e.g. from a child module), switch to the
        // declaring module's scope so field type lookups find the right symbols.
        let prevScope = self.scope;
        let prevMod = self.currentMod;

        if let sym = symbolFor(self, declNode) {
            if let mid = sym.moduleId {
                if (mid as u32) < self.moduleScopes.len {
                    if let ms = self.moduleScopes[mid as u32] {
                        self.scope = ms;
                        self.currentMod = mid;
                    }
                }
            }
        }

        match declNode.value {
            case ast::NodeValue::RecordDecl(decl) => {
                try resolveRecordBody(self, declNode, decl);
            }
            case ast::NodeValue::UnionDecl(decl) => {
                try resolveUnionBody(self, declNode, decl);
            }
            else => {},
        }
        self.scope = prevScope;
        self.currentMod = prevMod;
    }
}

/// Check if all elements in a node list are assignable to the target type.
fn isListAssignable(self: *mut Resolver, targetType: Type, items: *mut [*ast::Node]) -> bool {
    for itemNode in items {
        let elemTy = typeFor(self, itemNode)
            else return false;
        if let _ = isAssignable(self, targetType, elemTy, itemNode) {
            // Do nothing.
        } else {
            return false;
        }
    }
    return true;
}

/// Check if the `from` type is assignable to the `to` type, and return a
/// coercion plan if so.
fn isAssignable(self: *mut Resolver, to: Type, from: Type, rval: *ast::Node) -> ?Coercion {
    if to == Type::Unknown or from == Type::Unknown {
        return nil;
    }
    if from == Type::Undefined {
        // TODO: Don't let `undefined` be used in place of functions and other
        // non-data types.
        return Coercion::Identity;
    }
    // The "never" type can always be assigned, since the code path is never
    // executed.
    if from == Type::Never {
        return Coercion::Identity;
    }
    if to == from {
        return Coercion::Identity;
    }
    match to {
        case Type::Array(lhs) => {
            let case Type::Array(rhs) = from
                else return nil;

            if lhs.length != rhs.length {
                return nil;
            }
            // For array literals, check each element individually for
            // assignability.
            match rval.value {
                case ast::NodeValue::ArrayLit(items) => {
                    if rhs.length == 0 and lhs.length == 0 {
                        return Coercion::Identity;
                    }
                    // TODO: This won't work, because we should be setting coercions
                    // for every list item, but we don't. It's best to not have an
                    // `isAssignable` function and just have one that records coercions.
                    if isListAssignable(self, *lhs.item, items) {
                        return Coercion::Identity;
                    }
                    return nil;
                }
                case ast::NodeValue::ArrayRepeatLit(repeat) => {
                    return isAssignable(self, *lhs.item, *rhs.item, repeat.item);
                }
                else => {
                    // For non-literal arrays, require exact element type match.
                    if lhs.item == rhs.item {
                        return Coercion::Identity;
                    }
                    return nil;
                }
            }
        }
        case Type::Pointer { target: lhsTarget, mutable: lhsMutable } => {
            let case Type::Pointer { target: rhsTarget, mutable: rhsMutable } = from
                else return nil;

            // Allow coercion from `*T` to `*opaque`, and `*mut T` to `*mut opaque`.
            if *lhsTarget == Type::Opaque {
                if lhsMutable and not rhsMutable {
                    return nil;
                }
                return Coercion::Identity;
            }
            if lhsMutable and not rhsMutable {
                return nil;
            }
            return isAssignable(self, *lhsTarget, *rhsTarget, rval);
        }
        case Type::Optional(inner) => {
            if from == Type::Nil {
                return Coercion::OptionalLift(to);
            }
            if let _ = isAssignable(self, *inner, from, rval) {
                return Coercion::OptionalLift(to);
            }
            if let case Type::Optional(fromInner) = from {
                return isAssignable(self, *inner, *fromInner, rval);
            }
            return nil;
        }
        case Type::TraitObject { traitInfo, mutable: lhsMutable } => {
            // Coerce `*T` or `*mut T` where `T` implements the trait.
            if let case Type::Pointer { target, mutable: rhsMutable } = from {
                if lhsMutable and not rhsMutable {
                    return nil;
                }
                // Look up instance registry.
                if let inst = findInstance(self, traitInfo, *target) {
                    return Coercion::TraitObject { traitInfo, inst };
                }
            }
            // Identity: same trait object.
            if let case Type::TraitObject { traitInfo: rhsTrait, mutable: rhsMutable } = from {
                if traitInfo != rhsTrait {
                    return nil;
                }
                if lhsMutable and not rhsMutable {
                    return nil;
                }
                return Coercion::Identity;
            }
            return nil;
        }
        case Type::Slice { item: lhsItem, mutable: lhsMutable } => {
            match from {
                case Type::Slice { item: rhsItem, mutable: rhsMutable } => {
                    if lhsMutable and not rhsMutable {
                        return nil;
                    }
                    // Allow coercion from `*[T]` to `*[opaque]`, and `*mut [T]` to `*mut [opaque]`.
                    if *lhsItem == Type::Opaque {
                        return Coercion::Identity;
                    }
                    return isAssignable(self, *lhsItem, *rhsItem, rval);
                }
                else => return nil,
            }
        }
        case Type::Fn(toInfo) => {
            // Allow function type structural matching.
            if let case Type::Fn(fromInfo) = from {
                if fnTypeEqual(toInfo, fromInfo) {
                    return Coercion::Identity;
                }
            }
            return nil;
        }
        else => {
            if isNumericType(to) and isNumericType(from) {
                // Perform range validation at compile time if possible.
                // For unsuffixed integer expressions (`Type::Int`), only
                // validate literals directly written by the programmer.
                // Folded results (e.g. `0 - 65`) may not fit the target
                // type but are valid wrapping arithmetic at runtime.
                if let value = constValueEntry(self, rval) {
                    if from != Type::Int or isNumberLiteral(rval) {
                        if validateConstIntRange(value, to) {
                            return Coercion::Identity;
                        }
                        return nil;
                    }
                    // Folded constant expression (e.g. `1 + 2`): if the
                    // result fits the target, use identity. Otherwise allow
                    // wrapping via numeric cast.
                    if validateConstIntRange(value, to) {
                        return Coercion::Identity;
                    }
                }
                // Allow unsuffixed integer expressions to be inferred from context.
                if from == Type::Int {
                    return Coercion::NumericCast { from, to };
                }
                // Non-constant numeric values require an explicit cast.
                return nil;
            }
        }
    }
    return nil;
}

/// Check if two function type descriptors are structurally equivalent.
fn fnTypeEqual(a: *FnType, b: *FnType) -> bool {
    if a.paramTypes.len != b.paramTypes.len {
        return false;
    }
    if a.throwList.len != b.throwList.len {
        return false;
    }
    if not typesEqual(*a.returnType, *b.returnType) {
        return false;
    }
    for i in 0..a.paramTypes.len {
        if not typesEqual(*a.paramTypes[i], *b.paramTypes[i]) {
            return false;
        }
    }
    for i in 0..a.throwList.len {
        if not typesEqual(*a.throwList[i], *b.throwList[i]) {
            return false;
        }
    }
    return true;
}

/// Check if two types are structurally equal.
pub fn typesEqual(a: Type, b: Type) -> bool {
    if a == b {
        return true;
    }
    match a {
        case Type::Pointer { target: aTarget, mutable: aMutable } => {
            let case Type::Pointer { target: bTarget, mutable: bMutable } = b else return false;
            return aMutable == bMutable and typesEqual(*aTarget, *bTarget);
        }
        case Type::Slice { item: aItem, mutable: aMutable } => {
            let case Type::Slice { item: bItem, mutable: bMutable } = b else return false;
            return aMutable == bMutable and typesEqual(*aItem, *bItem);
        }
        case Type::Array(aa) => {
            let case Type::Array(ab) = b else return false;
            return aa.length == ab.length and typesEqual(*aa.item, *ab.item);
        }
        case Type::Optional(oa) => {
            let case Type::Optional(ob) = b else return false;
            return typesEqual(*oa, *ob);
        }
        case Type::Fn(fa) => {
            let case Type::Fn(fb) = b else return false;
            return fnTypeEqual(fa, fb);
        }
        else => return false,
    }
}

/// Get the record info from a record type.
pub fn getRecord(ty: Type) -> ?RecordType {
    let case Type::Nominal(NominalType::Record(recInfo)) = ty else return nil;
    return recInfo;
}

/// Auto-dereference a type: if it's a pointer, return the target type.
pub fn autoDeref(ty: Type) -> Type {
    if let case Type::Pointer { target, .. } = ty {
        return *target;
    }
    return ty;
}

/// Get field info for a record-like type (records, slices) by field index.
pub fn getRecordField(ty: Type, index: u32) -> ?RecordField {
    match ty {
        case Type::Nominal(NominalType::Record(recInfo)) => {
            if index >= recInfo.fields.len {
                return nil;
            }
            return recInfo.fields[index];
        }
        case Type::Slice { item, mutable } => {
            match index {
                case 0 => return RecordField {
                    name: PTR_FIELD,
                    fieldType: Type::Pointer { target: item, mutable },
                    offset: 0,
                },
                case 1 => return RecordField {
                    name: LEN_FIELD,
                    fieldType: Type::U32,
                    offset: PTR_SIZE as i32,
                },
                case 2 => return RecordField {
                    name: CAP_FIELD,
                    fieldType: Type::U32,
                    offset: PTR_SIZE as i32 + 4,
                },
                else => return nil,
            }
        }
        else => return nil,
    }
}

/// Check if the two types can be compared for equality.
fn isComparable(left: Type, right: Type) -> bool {
    if left == Type::Unknown or right == Type::Unknown {
        return false;
    }
    if left == right {
        return true;
    }
    // Comparisons with optionals.
    if let case Type::Optional(l) = left {
        if let case Type::Optional(r) = right {
            return isComparable(*l, *r);
        } else if right == Type::Nil {
            return true;
        }
        return isComparable(*l, right);
    } else if let case Type::Optional(_) = right {
        return isComparable(right, left); // Flip order.
    }
    // Pointer comparisons ignore mutability.
    if let case Type::Pointer { target: lTarget, .. } = left {
        if let case Type::Pointer { target: rTarget, .. } = right {
            return typesEqual(*lTarget, *rTarget);
        }
    }
    // Numeric types.
    if isNumericType(left) and isNumericType(right) {
        return true;
    }
    return false;
}

/// Check if the `from` type is assignable to the `to` type, and return a
/// coercion plan if so, or throw an error if not.
fn expectAssignable(self: *mut Resolver, to: Type, from: Type, site: *ast::Node) -> Coercion throws (ResolveError) {
    // Ensure any nested nominal types are resolved before checking assignability.
    try ensureTypeResolved(self, to, site);
    if let coercion = isAssignable(self, to, from, site) {
        return setNodeCoercion(self, site, coercion);
    }
    throw emitTypeMismatch(self, site, TypeMismatch {
        expected: to,
        actual: from,
    });
}

/// Check that a type is optional, otherwise throw an error.
fn checkOptional(self: *mut Resolver, node: *ast::Node) -> *Type
    throws (ResolveError)
{
    if let case Type::Optional(inner) = try infer(self, node) {
        return inner;
    }
    throw emitError(self, node, ErrorKind::ExpectedOptional);
}

/// Check that a node's type is equal to the expected type.
fn checkEqual(self: *mut Resolver, node: *ast::Node, expected: Type) -> Type
    throws (ResolveError)
{
    let actualTy = try visit(self, node, expected);
    if actualTy != expected {
        throw emitTypeMismatch(self, node, TypeMismatch { expected, actual: actualTy });
    }
    return actualTy;
}

/// Bind an identifier in the given scope.
fn bindIdent(
    self: *mut Resolver,
    name: *[u8],
    owner: *ast::Node,
    data: SymbolData,
    attrs: u32,
    scope: *mut Scope
) -> *mut Symbol throws (ResolveError) {
    let sym = allocSymbol(self, data, name, owner, attrs);
    try addSymbolToScope(self, sym, scope, owner);
    setNodeSymbol(self, owner, sym);

    return sym;
}

/// Add a symbol to the given scope.
fn addSymbolToScope(self: *mut Resolver, sym: *mut Symbol, scope: *mut Scope, site: *ast::Node) throws (ResolveError) {
    for i in 0..scope.symbolsLen {
        if scope.symbols[i].name == sym.name {
            throw emitError(self, site, ErrorKind::DuplicateBinding(sym.name));
        }
    }
    if scope.symbolsLen >= scope.symbols.len {
        throw emitError(self, site, ErrorKind::SymbolOverflow);
    }
    // Propagate module ID to the symbol for fast lookup.
    if let modId = scope.moduleId {
        sym.moduleId = modId;
    }
    scope.symbols[scope.symbolsLen] = sym;
    scope.symbolsLen += 1;
}

/// Bind a value identifier in the current scope.
/// Returns `nil` if the identifier is a placeholder (`_`).
fn bindValueIdent(
    self: *mut Resolver,
    ident: *ast::Node,
    owner: *ast::Node,
    type: Type,
    mutable: bool,
    alignment: u32,
    attrs: u32
) -> ?*mut Symbol throws (ResolveError) {
    if let case ast::NodeValue::Placeholder = ident.value {
        setNodeType(self, owner, type);
        return nil;
    }
    let name = try nodeName(self, ident);
    let data = SymbolData::Value { mutable, alignment, type, addressTaken: false };
    let sym = try bindIdent(self, name, owner, data, attrs, self.scope);
    setNodeType(self, owner, type);
    setNodeType(self, ident, type);

    // Track number of local bindings for lowering stage.
    if let mut fnType = self.currentFn {
        fnType.localCount += 1;
    }
    return sym;
}

/// Bind a constant identifier in the current scope.
fn bindConstIdent(
    self: *mut Resolver,
    ident: *ast::Node,
    owner: *ast::Node,
    type: Type,
    val: ?ConstValue,
    attrs: u32
) -> *mut Symbol throws (ResolveError) {
    let name = try nodeName(self, ident);
    let data = SymbolData::Constant { type, value: val };
    let sym = try bindIdent(self, name, owner, data, attrs, self.scope);
    setNodeType(self, owner, type);
    setNodeType(self, ident, type);

    return sym;
}

/// Bind a module identifier in the given scope.
/// This is used when declaring modules with `mod` or
/// importing modules with `use`.
fn bindModuleIdent(
    self: *mut Resolver,
    entry: *module::ModuleEntry,
    scope: *mut Scope,
    owner: *ast::Node,
    attrs: u32,
    bindingScope: *mut Scope
) -> *mut Symbol throws (ResolveError) {
    let data = SymbolData::Module { entry, scope };
    let name = entry.name;

    return try bindIdent(self, name, owner, data, attrs, bindingScope);
}

/// Bind a type identifier in the current scope.
fn bindTypeIdent(
    self: *mut Resolver,
    ident: *ast::Node,
    owner: *ast::Node,
    type: *mut NominalType,
    attrs: u32
) -> *mut Symbol throws (ResolveError) {
    let name = try nodeName(self, ident);
    let data = SymbolData::Type(type);
    return try bindIdent(self, name, owner, data, attrs, self.scope);
}

/// Predicate that matches any symbol.
fn isAnySymbol(_sym: *mut Symbol) -> bool {
    return true;
}

/// Predicate that matches value or constant symbols.
fn isValueSymbol(sym: *mut Symbol) -> bool {
    if let case SymbolData::Value { .. } = sym.data {
        return true;
    }
    if let case SymbolData::Constant { .. } = sym.data {
        return true;
    }
    return false;
}

/// Predicate that matches type symbols.
fn isTypeSymbol(sym: *mut Symbol) -> bool {
    if let case SymbolData::Type(_) = sym.data {
        return true;
    }
    return false;
}

/// Find a symbol by name in a specific scope, filtered by a predicate.
fn findInScope(scope: *Scope, name: *[u8], predicate: fn(*mut Symbol) -> bool) -> ?*mut Symbol {
    for i in 0..scope.symbolsLen {
        let sym = scope.symbols[i];
        if sym.name == name and predicate(sym) {
            return sym;
        }
    }
    return nil;
}

/// Find a symbol by name, traversing scopes upwards, filtered by a predicate.
fn findInScopeRecursive(scope: *Scope, name: *[u8], predicate: fn(*mut Symbol) -> bool) -> ?*mut Symbol {
    let mut curr = scope;
    loop {
        if let sym = findInScope(curr, name, predicate) {
            return sym;
        }
        if let parent = curr.parent {
            curr = parent;
        } else {
            break;
        }
    }
    return nil;
}

/// Find a symbol by name in a specific scope (matches any symbol kind).
pub fn findSymbolInScope(scope: *Scope, name: *[u8]) -> ?*mut Symbol {
    return findInScope(scope, name, isAnySymbol);
}

/// Look up a value symbol by name, searching from the given scope outward.
fn findValueSymbol(scope: *Scope, name: *[u8]) -> ?*mut Symbol {
    return findInScopeRecursive(scope, name, isValueSymbol);
}

/// Look up a type symbol by name, searching from the given scope outward.
fn findTypeSymbol(scope: *Scope, name: *[u8]) -> ?*mut Symbol {
    return findInScopeRecursive(scope, name, isTypeSymbol);
}

/// Like `findValueSymbol`, but finds symbols of any kinds.
fn findAnySymbol(scope: *Scope, name: *[u8]) -> ?*mut Symbol {
    return findInScopeRecursive(scope, name, isAnySymbol);
}

/// Flatten an identifier or scope access chain into an array of name segments.
/// Examples: `fnord` -> `&["fnord"]`, `a::b::c` -> `&["a", "b", "c"]`.
/// Returns a slice of the segments that were written.
fn flattenPath(
    self: *mut Resolver,
    node: *ast::Node,
    buf: *mut [*[u8]]
) -> *[*[u8]] throws (ResolveError) {
    let mut out: *[*[u8]] = &[];

    match node.value {
        case ast::NodeValue::Ident(name) if name.len > 0 => {
            assert buf.len >= 1, "flattenPath: invalid output buffer size";
            buf[0] = name;
            out = &buf[..1];
        }
        case ast::NodeValue::ScopeAccess(access) => {
            // Recursively flatten parent path.
            let parent = try flattenPath(self, access.parent, buf);
            assert parent.len < buf.len, "flattenPath: invalid output buffer size";
            let child = try nodeName(self, access.child);
            buf[parent.len] = child;
            out = &buf[..parent.len + 1];
        }
        case ast::NodeValue::Super => {
            // `super` is handled by scope adjustment in `checkSuperAccess`.
            // Return empty prefix so the path continues from the next segment.
            out = &buf[..0];
            return out;
        }
        else => {
            // Fallthrough to error.
        }
    }
    if out.len < 1 {
        throw emitError(self, node, ErrorKind::InvalidIdentifier(node));
    }
    return out;
}

/// Find the module ID for a given scope by walking up the scope chain until
/// we hit the module's scope.
fn findModuleForScope(scope: *Scope) -> ?u16 {
    let mut s = scope;
    loop {
        if let id = s.moduleId {
            return id;
        }
        if let parent = s.parent {
            s = parent;
        } else {
            return nil;
        }
    }
}

/// Get the parent module scope for the current module.
/// Returns the scope of the parent module, or `nil` if this is a root module.
fn getParentModuleScope(self: *mut Resolver, node: *ast::Node) -> ?*mut Scope throws (ResolveError) {
    let currentMod = module::get(self.moduleGraph, self.currentMod)
        else throw emitError(self, node, ErrorKind::Internal);
    let parentId = currentMod.parent
        else return nil; // No parent module.

    return self.moduleScopes[parentId as u32];
}

/// Check if a node has `super` at its root (e.g. `super::x` or `super::Union::Variant`).
/// Returns the parent scope and the original node so `flattenPath` can strip `super`.
fn checkSuperAccess(
    self: *mut Resolver,
    node: *ast::Node
) -> ?SuperAccessResult throws (ResolveError) {
    // TODO: Maybe we should deal with `super` after the path is flattened.
    if let case ast::NodeValue::ScopeAccess(access) = node.value {
        // Direct super access: `super::x`.
        if let case ast::NodeValue::Super = access.parent.value {
            let parentScope = try getParentModuleScope(self, node)
                else throw emitError(self, node, ErrorKind::InvalidModulePath);
            return SuperAccessResult { scope: parentScope, child: node };
        }
        // Nested super access: `super::x::y`, check if parent path contains `super`.
        if let _ = try checkSuperAccess(self, access.parent) {
            let parentScope = try getParentModuleScope(self, node)
                else throw emitError(self, node, ErrorKind::InvalidModulePath);
            return SuperAccessResult { scope: parentScope, child: node };
        }
    }
    return nil;
}

/// Check if a symbol is accessible from the given scope.
/// A symbol is accessible if:
/// * It has the `pub` attribute, OR
/// * It's being accessed from within the module where it was defined.
fn isSymbolVisible(sym: *Symbol, symScope: *Scope, fromScope: *Scope) -> bool {
    // Public symbols are visible from anywhere.
    if ast::hasAttribute(sym.attrs, ast::Attribute::Pub) {
        return true;
    }
    // In test mode, @test symbols are visible from anywhere
    // so the test runner can reference them.
    if ast::hasAttribute(sym.attrs, ast::Attribute::Test) {
        return true;
    }
    // Private symbols are only visible from the same module.
    let symModuleId = findModuleForScope(symScope);
    let currentModuleId = findModuleForScope(fromScope);

    return symModuleId == currentModuleId;
}

/// Resolve an access node (eg. `lang::resolver::MAX_ERRORS`) to a symbol,
/// starting from the given scope.
fn resolveAccess(
    self: *mut Resolver,
    node: *ast::Node,
    access: ast::Access,
    scope: *Scope
) -> *mut Symbol throws (ResolveError) {
    // Handle `super` access by adjusting scope and node.
    let mut startScope = scope;
    let mut pathNode = node;
    if let superAccess = try checkSuperAccess(self, node) {
        startScope = superAccess.scope;
        pathNode = superAccess.child;
    }
    // TODO: It doesn't make sense that `flattenPath` handles identifiers and scope access,
    // while this function requires a scope access.
    let mut buffer: [*[u8]; 32] = undefined;
    let path = try flattenPath(self, pathNode, &mut buffer[..]);

    return try resolvePath(self, node, access, path, startScope);
}

/// Resolve a path (eg. ["lang", "resolver", "MAX_ERRORS"]) to a symbol,
/// starting from the given scope.
fn resolvePath(
    self: *mut Resolver,
    node: *ast::Node,
    access: ast::Access,
    path: *[*[u8]],
    scope: *Scope
) -> *mut Symbol throws (ResolveError) {
    assert path.len != 0, "resolvePath: empty path";
    // Start by finding the root of the path.
    let root = path[0];
    let sym = findInScopeRecursive(scope, root, isAnySymbol) else
        throw emitError(self, node, ErrorKind::UnresolvedSymbol(root));
    let suffix = &path[1..];

    // Check visibility for symbol.
    if not isSymbolVisible(sym, scope, self.scope) {
        throw emitError(self, node, ErrorKind::UnresolvedSymbol(root));
    }
    // End condition.
    if suffix.len == 0 {
        return sym;
    }
    // Otherwise, we need to enter the next scope with the path suffix.
    match sym.data {
        case SymbolData::Module { scope, .. } => {
            return try resolvePath(self, node, access, suffix, scope);
        }
        case SymbolData::Type(ty) => {
            // Lazily resolve union body if not yet done.
            try ensureNominalResolved(self, ty, node);

            if let case NominalType::Union(unionType) = *ty {
                // TODO: Recurse with variant so we consolidate everything.
                if suffix.len > 1 {
                    throw emitError(self, node, ErrorKind::InvalidScopeAccess);
                }
                let variantName = suffix[0];
                let variantSym = try resolveUnionVariantAccess(
                    self, node, access, unionType, variantName
                );
                // TODO: This shouldn't be here.
                setNodeType(self, node, Type::Nominal(ty));
                return variantSym;
            }
        }
        else => {} // Fallthrough.
    }
    throw emitError(self, node, ErrorKind::InvalidScopeAccess);
}

/// Resolve a module path (e.g., `foo::bar::baz`) to a module entry and scope.
/// This traverses the module hierarchy, checking visibility at each step.
fn resolveModulePath(
    self: *mut Resolver,
    module: *ast::Node
) -> ResolvedModule throws (ResolveError) {
    let mut startScope = self.scope;
    let mut pathNode = module;

    // Handle `super` access.
    if let superAccess = try checkSuperAccess(self, module) {
        startScope = superAccess.scope;
        pathNode = superAccess.child;
    }
    let mut pathBuf: [*[u8]; 16] = undefined;
    let path = try flattenPath(self, pathNode, &mut pathBuf[..]);
    if path.len == 0 {
        throw emitError(self, module, ErrorKind::UnresolvedSymbol(""));
    }
    let parentName = path[0];

    // First, check if this is a sub-module of the start scope.
    if let sym = findSymbolInScope(startScope, parentName) {
        return try resolveModulePathRecursive(self, module, &path[1..], sym);
    }
    // Not a sub-module, so look in the global scope for a package root.
    let sym = findSymbolInScope(self.pkgScope, parentName)
        else throw emitError(self, module, ErrorKind::UnresolvedSymbol(parentName));

    return try resolveModulePathRecursive(self, module, &path[1..], sym);
}

/// Recursively resolve the remaining path segments by traversing child modules.
fn resolveModulePathRecursive(
    self: *mut Resolver,
    node: *ast::Node,
    path: *[*[u8]],
    sym: *Symbol
) -> ResolvedModule throws (ResolveError) {
    let case SymbolData::Module { entry, scope } = sym.data
        else throw emitError(self, node, ErrorKind::Internal);

    if path.len == 0 {
        return ResolvedModule { entry, scope };
    }
    let childName = path[0];
    let childSym = findSymbolInScope(scope, childName)
        else throw emitError(self, node, ErrorKind::UnresolvedSymbol(childName));

    if not isSymbolVisible(childSym, scope, self.scope) {
        throw emitError(self, node, ErrorKind::UnresolvedSymbol(childName));
    }
    return try resolveModulePathRecursive(
        self,
        node,
        &path[1..],
        childSym
    );
}

/// Resolve a type name, which could be an identifier or scoped path.
fn resolveTypeName(self: *mut Resolver, node: *ast::Node) -> *NominalType throws (ResolveError) {
    match node.value {
        case ast::NodeValue::Ident(name) => {
            let sym = findTypeSymbol(self.scope, name)
                else throw emitError(self, node, ErrorKind::UnresolvedSymbol(name));
            let case SymbolData::Type(ty) = sym.data
                else throw emitError(self, node, ErrorKind::Internal);

            setNodeSymbol(self, node, sym);

            return ty;
        }
        case ast::NodeValue::ScopeAccess(access) => {
            let sym = try resolveAccess(self, node, access, self.scope);
            let case SymbolData::Type(ty) = sym.data
                else throw emitError(self, node, ErrorKind::Internal);

            setNodeSymbol(self, node, sym);

            return ty;
        }
        else => panic "resolveTypeName: unsupported node value",
    }
}

/// Visit a top-level declaration in the declaration phase.
/// This binds all names and analyzes signatures, types, and initializers.
/// Function bodies are deferred to the definition phase.
///
/// Nb. User-defined types are already handled by this point.
fn visitDecl(self: *mut Resolver, node: *ast::Node) throws (ResolveError) {
    match node.value {
        case ast::NodeValue::FnDecl(_),
             ast::NodeValue::ConstDecl(_),
             ast::NodeValue::Mod(_),
             ast::NodeValue::Use(_) => {
            // Handled in previous passes.
        }
        case ast::NodeValue::StaticDecl(_) => {
            try infer(self, node);
        }
        case ast::NodeValue::InstanceDecl { traitName, targetType, methods } => {
            try resolveInstanceDecl(self, node, traitName, targetType, methods);
        }
        case ast::NodeValue::MethodDecl { name, receiverName, receiverType, sig, attrs, .. } => {
            try resolveMethodDecl(self, node, name, receiverName, receiverType, sig, attrs);
        }
        else => {
            // Ignore non-declaration nodes.
        }
    }
}

/// Visit a top-level definition, recursing into sub-modules.
fn visitDef(self: *mut Resolver, node: *ast::Node) throws (ResolveError) {
    match node.value {
        case ast::NodeValue::FnDecl(decl) => {
            try resolveFnDeclBody(self, node, decl) catch {
                return;
            };
        }
        case ast::NodeValue::Mod(decl) => {
            if not shouldAnalyzeModule(self, decl.attrs) {
                return;
            }
            let modName = try nodeName(self, decl.name);
            let submod = try enterSubModule(self, modName, node);
            let case ast::NodeValue::Block(block) = submod.root.value
                else panic "visitDef: expected block for module root";
            try resolveModuleDefs(self, &block);
            exitModuleScope(self, submod);
        }
        case ast::NodeValue::RecordDecl(_),
             ast::NodeValue::UnionDecl(_),
             ast::NodeValue::Use(_),
             ast::NodeValue::TraitDecl { .. } => {
            // Skip: already analyzed in declaration phase.
        }
        case ast::NodeValue::InstanceDecl { methods, .. } => {
            try resolveInstanceMethodBodies(self, methods);
        }
        case ast::NodeValue::MethodDecl { receiverName, sig, body, .. } => {
            try resolveMethodBody(self, node, receiverName, sig, body);
        }
        else => {
            // FIXME: This allows module-level statements that should
            // normally only be valid inside function bodies. We currently
            // need this because of how tests are written, but it should
            // be eventually removed.
            try infer(self, node) catch {
                return;
            };
        }
    }
}

/// Try to infer a node's type.
fn infer(self: *mut Resolver, node: *ast::Node) -> Type throws (ResolveError) {
    return try visit(self, node, Type::Unknown);
}

/// Resolve a type signature node.
fn resolveValueType(self: *mut Resolver, node: *ast::Node) -> Type throws (ResolveError) {
    let ty = try visit(self, node, Type::Unknown);
    // Opaque value types are not allowed.
    if ty == Type::Opaque {
        throw emitError(self, node, ErrorKind::OpaqueTypeNotAllowed);
    }
    return ty;
}

/// Analyze a node's type and check that it can be assigned to the expected type.
fn checkAssignable(self: *mut Resolver, node: *ast::Node, expected: Type) -> Type throws (ResolveError) {
    let actual = try visit(self, node, expected);
    let _ = try expectAssignable(self, expected, actual, node);
    return actual;
}

/// Analyze a node and propagate the resolved type.
/// The `hint` parameter provides type context for inference and validation.
/// When `nil`, the type must be inferred from the expression itself.
fn visit(self: *mut Resolver, node: *ast::Node, hint: Type) -> Type
    throws (ResolveError)
{
    if let ty = typeFor(self, node) {
        return ty;
    }
    match node.value {
        case ast::NodeValue::Ident(name) => {
            let sym = findAnySymbol(self.scope, name)
                else throw emitError(self, node, ErrorKind::UnresolvedSymbol(name));
            setNodeSymbol(self, node, sym);
            match sym.data {
                case SymbolData::Value { type, .. } =>
                    return setNodeType(self, node, type),
                case SymbolData::Constant { type, value } => {
                    if let val = value {
                        setNodeConstValue(self, node, val);
                    }
                    return setNodeType(self, node, type);
                },
                case SymbolData::Type(t) =>
                    return setNodeType(self, node, Type::Nominal(t)),
                case SymbolData::Variant { .. } =>
                    return Type::Void,
                case SymbolData::Module { .. } =>
                    throw emitError(self, node, ErrorKind::UnexpectedModuleName),
                case SymbolData::Trait(_) =>
                    throw emitError(self, node, ErrorKind::UnexpectedTraitName),
            }
        },
        case ast::NodeValue::Call(call) => return try resolveCall(self, node, call, CallCtx::Normal),
        case ast::NodeValue::FieldAccess(access) => return try resolveFieldAccess(self, node, access),
        case ast::NodeValue::BinOp(binop) => return try resolveBinOp(self, node, binop),
        case ast::NodeValue::Block(block) => return try resolveBlock(self, node, block),
        case ast::NodeValue::UnsafeBlock(inner) => {
            self.unsafeDepth += 1;
            let ty = try visit(self, inner, hint) catch e {
                self.unsafeDepth -= 1;
                throw e;
            };
            self.unsafeDepth -= 1;
            return setNodeType(self, node, ty);
        }
        case ast::NodeValue::Let(decl) => return try resolveLet(self, node, decl),
        case ast::NodeValue::ConstDecl(decl) => return try resolveConstOrStatic(
            self, node, decl.ident, decl.type, decl.value, decl.attrs, true
        ),
        case ast::NodeValue::StaticDecl(decl) => return try resolveConstOrStatic(
            self, node, decl.ident, decl.type, decl.value, decl.attrs, false
        ),
        case ast::NodeValue::FnParam(param) => return try resolveFnParam(self, node, param),
        case ast::NodeValue::If(cond) => return try resolveIf(self, node, cond),
        case ast::NodeValue::CondExpr(cond) => return try resolveCondExpr(self, node, cond),
        case ast::NodeValue::IfLet(cond) => return try resolveIfLet(self, node, cond),
        case ast::NodeValue::While(loopNode) => return try resolveWhile(self, node, loopNode),
        case ast::NodeValue::WhileLet(loopNode) => return try resolveWhileLet(self, node, loopNode),
        case ast::NodeValue::For(loopNode) => return try resolveFor(self, node, loopNode),
        case ast::NodeValue::Loop { body } => {
            let loopType = try visitLoop(self, body);
            return setNodeType(self, node, loopType);
        },
        case ast::NodeValue::Break => {
            try ensureInsideLoop(self, node);
            // Mark that the current loop has a reachable break.
            self.loopStack[self.loopDepth - 1].hasBreak = true;

            return setNodeType(self, node, Type::Never);
        },
        case ast::NodeValue::Continue => {
            try ensureInsideLoop(self, node);
            return setNodeType(self, node, Type::Never);
        },
        case ast::NodeValue::Match(sw) => return try resolveMatch(self, node, sw),
        case ast::NodeValue::MatchProng(_) => panic "visit: `MatchProng` not handled here",
        case ast::NodeValue::LetElse(letElse) => return try resolveLetElse(self, node, letElse),
        case ast::NodeValue::BuiltinCall { kind, args } => return try resolveBuiltinCall(self, node, kind, args),
        case ast::NodeValue::Assign(assign) => return try resolveAssign(self, node, assign),
        case ast::NodeValue::RecordLit(lit) => return try resolveRecordLit(self, node, lit, hint),
        case ast::NodeValue::ArrayLit(items) => return try resolveArrayLit(self, node, items, hint),
        case ast::NodeValue::ArrayRepeatLit(lit) => return try resolveArrayRepeat(self, node, lit, hint),
        case ast::NodeValue::Subscript { container, index } => return try resolveSubscript(self, node, container, index),
        case ast::NodeValue::ScopeAccess(access) => return try resolveScopeAccess(self, node, access),
        case ast::NodeValue::AddressOf(addr) => return try resolveAddressOf(self, node, addr, hint),
        case ast::NodeValue::Deref(target) => return try resolveDeref(self, node, target, hint),
        case ast::NodeValue::As(expr) => return try resolveAs(self, node, expr),
        case ast::NodeValue::Range(range) => return try resolveRange(self, node, range),
        case ast::NodeValue::Try(expr) => return try resolveTry(self, node, expr, hint),
        case ast::NodeValue::Return { value } => return try resolveReturn(self, node, value),
        case ast::NodeValue::Throw { expr } => return try resolveThrow(self, node, expr),
        case ast::NodeValue::Panic { message } => {
            try visitOptional(self, message, Type::Slice { // TODO: Have easy access to string type.
                item: allocType(self, Type::U8),
                mutable: false
            });
            return setNodeType(self, node, Type::Never);
        },
        case ast::NodeValue::Assert { condition, message } => {
            try visit(self, condition, Type::Bool);
            try visitOptional(self, message, Type::Slice { // TODO: Have easy access to string type.
                item: allocType(self, Type::U8),
                mutable: false
            });
            return setNodeType(self, node, Type::Void);
        },
        case ast::NodeValue::UnOp(unop) => return try resolveUnOp(self, node, unop),
        case ast::NodeValue::ExprStmt(expr) => {
            // Pass `Void` as expected type to indicate value is discarded.
            let exprTy = try visit(self, expr, Type::Void);
            return setNodeType(self, node, unifyBranches(exprTy, Type::Void));
        },
        case ast::NodeValue::TypeSig(sig) => return try inferTypeSig(self, node, sig),
        case ast::NodeValue::Super => {
            // `super` by itself is invalid, must be used in scope access.
            throw emitError(self, node, ErrorKind::InvalidModulePath);
        },
        case ast::NodeValue::Nil => {
            // Use the hint type if it's an optional, otherwise fall back to `Nil`.
            if let case Type::Optional(_) = hint {
                return setNodeType(self, node, hint);
            }
            return setNodeType(self, node, Type::Nil);
        },
        case ast::NodeValue::Undef => {
            return setNodeType(self, node, Type::Undefined);
        },
        case ast::NodeValue::Bool(value) => {
            setNodeConstValue(self, node, ConstValue::Bool(value));
            return setNodeType(self, node, Type::Bool);
        }
        case ast::NodeValue::Char(value) => {
            setNodeConstValue(self, node, ConstValue::Char(value));
            return setNodeType(self, node, Type::U8);
        }
        case ast::NodeValue::String(text) => {
            setNodeConstValue(self, node, ConstValue::String(text));
            let byteTy = allocType(self, Type::U8);
            let sliceTy = allocType(self, Type::Slice {
                item: byteTy,
                mutable: false,
            });
            return setNodeType(self, node, *sliceTy);
        },
        case ast::NodeValue::Number(lit) => {
            setNodeConstValue(self, node, ConstValue::Int(ConstInt {
                magnitude: lit.magnitude,
                bits: 64,
                signed: lit.signed,
                negative: lit.negative,
            }));
            return setNodeType(self, node, Type::Int);
        },
        case ast::NodeValue::Placeholder => {
            return setNodeType(self, node, hint);
        },
        else => {
            throw emitError(self, node, ErrorKind::UnexpectedNode(node));
        }
    }
}

/// Visit an optional node when present.
fn visitOptional(self: *mut Resolver, node: ?*ast::Node, hint: Type) -> ?Type
    throws (ResolveError)
{
    if let n = node {
        return try visit(self, n, hint);
    }
    return nil;
}

/// Visit every node contained in a list, returning the last resolved type.
fn visitList(self: *mut Resolver, list: *mut [*ast::Node]) -> Type
    throws (ResolveError)
{
    let mut diverges = false;
    for item in list {
        if try infer(self, item) == Type::Never {
            diverges = true;
        }
    }
    if diverges {
        return Type::Never;
    }
    return Type::Void;
}

/// Collect attribute flags applied to a declaration.
fn resolveAttributes(self: *mut Resolver, attrs: ?ast::Attributes) -> u32 {
    let list = attrs else return 0;
    let attrNodes = list.list;
    let mut mask: u32 = 0;

    for node in attrNodes {
        let case ast::NodeValue::Attribute(attr) = node.value
            else panic "resolveAttributes: invalid attribute node";
        mask |= (attr as u32);
    }
    return mask;
}

/// Ensure the `default` attribute is only applied to functions.
fn ensureDefaultAttrNotAllowed(self: *mut Resolver, node: *ast::Node, attrs: u32)
    throws (ResolveError)
{
    let defaultBit = ast::Attribute::Default as u32;
    if (attrs & defaultBit) != 0 {
        throw emitError(self, node, ErrorKind::DefaultAttrOnlyOnFn);
    }
}

/// Analyze a block node, allocating a nested lexical scope.
fn resolveBlock(self: *mut Resolver, node: *ast::Node, block: ast::Block) -> Type
    throws (ResolveError)
{
    enterScope(self, node);
    let blockTy = try visitList(self, block.statements) catch {
        // One of the statements in the block failed analysis. We simply proceed
        // without checking the rest of the block statements. Return `Never` to
        // avoid spurious `FnMissingReturn` errors.
        exitScope(self);
        return setNodeType(self, node, Type::Never);
    };
    exitScope(self);

    return setNodeType(self, node, blockTy);
}

/// Analyze a `let` declaration and bind its identifier.
fn resolveLet(self: *mut Resolver, node: *ast::Node, decl: ast::Let) -> Type
    throws (ResolveError)
{
    let mut alignment: u32 = 0; // Zero is default.
    let mut bindingTy = Type::Unknown;

    // Check type.
    if let declTy = try visitOptional(self, decl.type, Type::Unknown) {
        let _coercion = try checkAssignable(self, decl.value, declTy);
        bindingTy = declTy;
    } else {
        bindingTy = try infer(self, decl.value);

        if not isTypeInferrable(bindingTy) {
            throw emitError(self, decl.value, ErrorKind::CannotInferType);
        }
    }
    // Variables cannot have void type.
    if bindingTy == Type::Void {
        throw emitError(self, decl.value, ErrorKind::CannotAssignVoid);
    }
    // Variables cannot have opaque type directly.
    if bindingTy == Type::Opaque {
        throw emitError(self, node, ErrorKind::OpaqueTypeNotAllowed);
    }
    // Check alignment.
    if let a = decl.alignment {
        let case ast::NodeValue::Align { value } = a.value
            else panic "resolveLet: expected Align node";
        alignment = try checkSizeInt(self, value);
    }
    assert bindingTy != Type::Unknown;

    // Alignment must be zero or a power of two.
    if alignment != 0 and (alignment & (alignment - 1)) != 0 {
        throw emitError(self, decl.value, ErrorKind::InvalidAlignmentValue(alignment));
    }
    let _ = try bindValueIdent(self, decl.ident, node, bindingTy, decl.mutable, alignment, 0);
    setNodeType(self, decl.value, bindingTy);

    return Type::Void;
}

/// Check whether a node is a number literal.
fn isNumberLiteral(node: *ast::Node) -> bool {
    if let case ast::NodeValue::Number(_) = node.value {
        return true;
    }
    return false;
}

/// Determine whether a node represents a compile-time constant expression.
pub fn isConstExpr(self: *Resolver, node: *ast::Node) -> bool {
    match node.value {
        case ast::NodeValue::Bool(_),
             ast::NodeValue::Char(_),
             ast::NodeValue::Number(_),
             ast::NodeValue::String(_),
             ast::NodeValue::Undef,
             ast::NodeValue::Nil => {
            return true;
        },
        case ast::NodeValue::ArrayLit(items) => {
            for item in items {
                if not isConstExpr(self, item) {
                    return false;
                }
            }
            return true;
        },
        case ast::NodeValue::ArrayRepeatLit(repeat) => {
            return isConstExpr(self, repeat.item);
        },
        case ast::NodeValue::AddressOf(addr) => {
            let ty = typeFor(self, node) else {
                return false;
            };
            if let case Type::Slice { .. } = ty {
                return isConstExpr(self, addr.target);
            }
            return false;
        },
        case ast::NodeValue::RecordLit(lit) => {
            // Record literals are constant if all field values are constant.
            for field in lit.fields {
                if let case ast::NodeValue::RecordLitField(fieldLit) = field.value {
                    if not isConstExpr(self, fieldLit.value) {
                        return false;
                    }
                }
            }
            return true;
        },
        case ast::NodeValue::Ident(_),
             ast::NodeValue::ScopeAccess(_) => {
            // Identifiers and scope accesses referencing constants, union
            // variants, or function values are constant expressions.
            if let sym = symbolFor(self, node) {
                match sym.data {
                    case SymbolData::Variant { .. },
                         SymbolData::Constant { .. } => return true,
                    case SymbolData::Value { type, .. } => {
                        if let case Type::Fn(_) = type {
                            return true;
                        }
                    }
                    else => {}
                }
            }
            return false;
        },
        case ast::NodeValue::Call(call) => {
            // Constructor calls (union variants, unlabeled records) are constant
            // if all payload args are themselves constant.
            if let sym = symbolFor(self, call.callee) {
                match sym.data {
                    case SymbolData::Variant { .. } => {}
                    case SymbolData::Type(NominalType::Record(recInfo)) => {
                        if recInfo.labeled {
                            return false;
                        }
                    },
                    else => return false,
                }
                for arg in call.args {
                    if not isConstExpr(self, arg) {
                        return false;
                    }
                }
                return true;
            }
            return false;
        },
        case ast::NodeValue::BinOp(binop) => {
            // Binary expressions are constant if both operands are constant.
            return isConstExpr(self, binop.left) and isConstExpr(self, binop.right);
        },
        case ast::NodeValue::UnOp(unop) => {
            // Unary expressions are constant if the operand is constant.
            return isConstExpr(self, unop.value);
        },
        case ast::NodeValue::As(expr) => {
            // Cast expressions are constant if the source value is constant.
            return isConstExpr(self, expr.value);
        },
        else => {
            return false;
        }
    }
}

/// Construct an integer constant descriptor.
fn constInt(magnitude: u64, bits: u8, signed: bool, negative: bool) -> ConstValue {
    return ConstValue::Int(ConstInt { magnitude, bits, signed, negative });
}

/// Return the constant `u32` value for a slice bound when known.
fn constSliceIndex(self: *mut Resolver, node: *ast::Node) -> ?u32 {
    let value = constValueEntry(self, node)
        else return nil;
    let case ConstValue::Int(int) = value
        else return nil;
    if int.negative {
        return nil;
    }
    return int.magnitude as u32;
}

/// Validates and extracts a non-negative integer constant from a compile-time expression.
///
/// This function ensures that a node represents a valid, non-negative integer constant
/// that fits within a machine word. It is used for contexts requiring compile-time
/// non-negative integers, such as array sizes and alignment specifications.
///
/// Returns the unsigned magnitude of the constant as `u32`.
fn checkSizeInt(self: *mut Resolver, node: *ast::Node) -> u32
    throws (ResolveError)
{
    // First traverse the node expect a numeric type.
    let _ = try checkNumeric(self, node);

    // Look up the compile-time constant value associated with this node.
    let value = constValueEntry(self, node)
        else throw emitError(self, node, ErrorKind::ConstExprRequired);

    let case ConstValue::Int(int) = value
        else panic "checkSizeInt: expected integer constant";

    // Validate it fits within u32 range.
    if not validateConstIntRange(value, Type::U32) {
        throw emitError(self, node, ErrorKind::NumericLiteralOverflow);
    }
    assert not int.negative;
    setNodeType(self, node, Type::U32);

    return int.magnitude as u32;
}

/// Check that constructor arguments match record fields.
///
/// Verifies argument count matches field count, and that each argument is
/// assignable to its corresponding field type.
fn checkRecordConstructorArgs(self: *mut Resolver, node: *ast::Node, args: *mut [*ast::Node], recInfo: RecordType)
    throws (ResolveError)
{
    try checkRecordArity(self, args, recInfo, node);
    for arg, i in args {
        let fieldType = recInfo.fields[i].fieldType;
        try checkAssignable(self, arg, fieldType);
    }
}

/// Check that the argument count of a constructor pattern or call matches the record field count.
fn checkRecordArity(self: *mut Resolver, args: *mut [*ast::Node], recInfo: RecordType, pattern: *ast::Node) throws (ResolveError) {
    if args.len != recInfo.fields.len {
        throw emitError(self, pattern, ErrorKind::RecordFieldCountMismatch(CountMismatch {
            expected: recInfo.fields.len as u32,
            actual: args.len,
        }));
    }
}

/// Helper for analyzing `const` and `static` declarations.
fn resolveConstOrStatic(
    self: *mut Resolver,
    node: *ast::Node,
    ident: *ast::Node,
    typeNode: *ast::Node,
    valueNode: *ast::Node,
    attrList: ?ast::Attributes,
    isConst: bool
) -> Type throws (ResolveError) {
    let attrs = resolveAttributes(self, attrList);
    let bindingTy = try infer(self, typeNode);
    let valueTy = try checkAssignable(self, valueNode, bindingTy);

    if isConst {
        let constVal = constValueEntry(self, valueNode);
        if constVal == nil and not isConstExpr(self, valueNode) {
            throw emitError(self, valueNode, ErrorKind::ConstExprRequired);
        }
        try bindConstIdent(self, ident, node, bindingTy, constVal, attrs);
    } else {
        if not isConstExpr(self, valueNode) {
            throw emitError(self, valueNode, ErrorKind::ConstExprRequired);
        }
        try bindValueIdent(self, ident, node, bindingTy, true, 0, attrs);
    }
    setNodeType(self, valueNode, bindingTy);

    return Type::Void;
}

/// Analyze a function declaration signature and bind the function name.
fn resolveFnDecl(self: *mut Resolver, node: *ast::Node, decl: ast::FnDecl) -> Type
    throws (ResolveError)
{
    let attrMask = resolveAttributes(self, decl.attrs);
    let mut retTy = Type::Void;
    if let retNode = decl.sig.returnType {
        retTy = try infer(self, retNode);
    }
    let a = alloc::arenaAllocator(&mut self.arena);
    let mut paramTypes: *mut [*Type] = &mut [];
    let mut throwList: *mut [*Type] = &mut [];
    let mut fnType = FnType {
        paramTypes: &[],
        returnType: allocType(self, retTy),
        throwList: &[],
        localCount: 0,
        isUnsafe: ast::hasAttribute(attrMask, ast::Attribute::Unsafe),
    };
    // Enter the function scope to process parameters.
    enterFn(self, node, &fnType);

    if decl.sig.params.len > MAX_FN_PARAMS {
        exitFn(self);
        throw emitError(self, node, ErrorKind::FnParamOverflow(CountMismatch {
            expected: MAX_FN_PARAMS,
            actual: decl.sig.params.len,
        }));
    }
    for paramNode in decl.sig.params {
        let paramTy = try infer(self, paramNode) catch e {
            exitFn(self);
            throw e;
        };
        paramTypes.append(allocType(self, paramTy), a);
    }

    if decl.sig.throwList.len > MAX_FN_THROWS {
        exitFn(self);
        throw emitError(self, node, ErrorKind::FnThrowOverflow(CountMismatch {
            expected: MAX_FN_THROWS,
            actual: decl.sig.throwList.len,
        }));
    }
    for throwNode in decl.sig.throwList {
        let throwTy = try infer(self, throwNode) catch e {
            exitFn(self);
            throw e;
        };
        throwList.append(allocType(self, throwTy), a);
    }
    exitFn(self);
    fnType.paramTypes = &paramTypes[..];
    fnType.throwList = &throwList[..];

    // Bind the function name.
    let ty = Type::Fn(allocFnType(self, fnType));
    let sym = try bindValueIdent(self, decl.name, node, ty, false, 0, attrMask)
        else throw emitError(self, node, ErrorKind::ExpectedIdentifier);

    return ty;
}

/// Analyze a function body.
fn resolveFnDeclBody(self: *mut Resolver, node: *ast::Node, decl: ast::FnDecl) throws (ResolveError) {
    let sym = symbolFor(self, node) else {
        // The function declaration failed to type check, therefore
        // no symbol was associated with it.
        return;
    };
    let case SymbolData::Value { type: Type::Fn(fnType), .. } = sym.data else {
        panic "resolveFnDeclBody: unexpected symbol data for function";
    };
    let retTy = *fnType.returnType;
    let isExtern = ast::hasAttribute(sym.attrs, ast::Attribute::Extern);
    let isIntrinsic = ast::hasAttribute(sym.attrs, ast::Attribute::Intrinsic);

    if isIntrinsic and not isExtern {
        throw emitError(self, node, ErrorKind::IntrinsicRequiresExtern);
    }
    if let body = decl.body {
        if isExtern {
            throw emitError(self, node, ErrorKind::FnUnexpectedBody);
        }
        enterFn(self, node, fnType); // Enter function scope for body analysis.
        if fnType.isUnsafe {
            self.unsafeDepth += 1;
        }
        let bodyTy = try checkAssignable(self, body, Type::Void) catch e {
            if fnType.isUnsafe {
                self.unsafeDepth -= 1;
            }
            exitFn(self);
            throw e;
        };
        if retTy != Type::Void and bodyTy != Type::Never {
            if fnType.isUnsafe {
                self.unsafeDepth -= 1;
            }
            exitFn(self);
            throw emitError(self, body, ErrorKind::FnMissingReturn);
        }
        if fnType.isUnsafe {
            self.unsafeDepth -= 1;
        }
        exitFn(self);
    } else if not isExtern {
        throw emitError(self, node, ErrorKind::FnMissingBody);
    }
}

/// Analyze a function parameter and bind its identifier.
fn resolveFnParam(self: *mut Resolver, node: *ast::Node, param: ast::FnParam) -> Type
    throws (ResolveError)
{
    let ty = try resolveValueType(self, param.type);
    let _ = try bindValueIdent(self, param.name, node, ty, false, 0, 0);

    return ty;
}

/// Resolve record fields from a node list.
fn resolveRecordFields(self: *mut Resolver, node: *ast::Node, fields: *mut [*ast::Node], labeled: bool) -> RecordType
    throws (ResolveError)
{
    let a = alloc::arenaAllocator(&mut self.arena);
    let mut result: *mut [RecordField] = &mut [];
    let mut currentOffset: u32 = 0;
    let mut maxAlignment: u32 = 1;

    if fields.len > parser::MAX_RECORD_FIELDS {
        throw emitError(self, node, ErrorKind::Internal);
    }
    // TODO: Add cycle detection to catch invalid recursive types like `record A { a: A }`.
    for field in fields {
        let case ast::NodeValue::RecordField {
            field: fieldNode,
            type: typeNode,
            value: valueNode
        } = field.value else panic "resolveRecordFields: invalid record field";
        let fieldTy = try resolveValueType(self, typeNode);

        if let v = valueNode {
            let _valTy = try checkAssignable(self, v, fieldTy);
        }
        // Get field name for labeled records.
        let mut fieldName: ?*[u8] = nil;
        if labeled {
            let n = fieldNode
                else panic "resolveRecordFields: labeled record field missing name";
            fieldName = try nodeName(self, n);
        }
        let fieldType = typeFor(self, typeNode)
            else throw emitError(self, typeNode, ErrorKind::CannotInferType);

        // Ensure field type is fully resolved before computing layout.
        try ensureTypeResolved(self, fieldType, typeNode);

        // Compute field offset by aligning to field's alignment.
        let fieldLayout = getTypeLayout(fieldType);
        currentOffset = mem::alignUp(currentOffset, fieldLayout.alignment);

        result.append(RecordField { name: fieldName, fieldType, offset: currentOffset as i32 }, a);

        // Advance offset past this field.
        currentOffset += fieldLayout.size;

        // Track max alignment for record layout.
        maxAlignment = max(maxAlignment, fieldLayout.alignment);
    }
    // Compute cached layout.
    let recordLayout = Layout {
        size: mem::alignUp(currentOffset, maxAlignment),
        alignment: maxAlignment
    };
    return RecordType { fields: &result[..], labeled, layout: recordLayout };
}

/// Resolve record field types for a named record declaration.
fn resolveRecordBody(self: *mut Resolver, node: *ast::Node, decl: ast::RecordDecl)
    throws (ResolveError)
{
    // Get the type symbol that was bound to this declaration node.
    // If there's no symbol, it's because an earlier phase failed.
    let sym = symbolFor(self, node)
        else return;
    let case SymbolData::Type(nominalTy) = sym.data
        else panic "resolveRecordBody: unexpected type symbol data";

    // Skip if already resolved.
    if let case NominalType::Record(_) = *nominalTy {
        return;
    }
    try visitList(self, decl.derives);
    let recordType = try resolveRecordFields(self, node, decl.fields, decl.labeled);

    *nominalTy = NominalType::Record(recordType);
}

/// Bind a type name.
fn bindTypeName(self: *mut Resolver, node: *ast::Node, name: *ast::Node, attrs: ?ast::Attributes) -> *mut Symbol
    throws (ResolveError)
{
    let attrMask = resolveAttributes(self, attrs);
    try ensureDefaultAttrNotAllowed(self, node, attrMask);

    // Create a placeholder nominal type that will be replaced in
    // the next phase.
    let nominalTy = allocNominalType(self, NominalType::Placeholder(node));

    return try bindTypeIdent(self, name, node, nominalTy, attrMask);
}

/// Allocate a trait type descriptor and return a pointer to it.
fn allocTraitType(self: *mut Resolver, name: *[u8]) -> *mut TraitType {
    let p = try! alloc::alloc(&mut self.arena, @sizeOf(TraitType), @alignOf(TraitType));
    let entry = p as *mut TraitType;
    *entry = TraitType { name, methods: &mut [], supertraits: &mut [] };

    return entry;
}

/// Bind a trait name in the current scope.
fn bindTraitName(self: *mut Resolver, node: *ast::Node, name: *ast::Node, attrs: ?ast::Attributes) -> *mut Symbol
    throws (ResolveError)
{
    let attrMask = resolveAttributes(self, attrs);
    try ensureDefaultAttrNotAllowed(self, node, attrMask);

    let traitName = try nodeName(self, name);
    let traitType = allocTraitType(self, traitName);
    let data = SymbolData::Trait(traitType);
    let sym = try bindIdent(self, traitName, node, data, attrMask, self.scope);

    setNodeType(self, node, Type::Void);
    setNodeType(self, name, Type::Void);

    return sym;
}

/// Find a trait method by name.
pub fn findTraitMethod(traitType: *TraitType, name: *[u8]) -> ?*TraitMethod {
    for i in 0..traitType.methods.len {
        if traitType.methods[i].name == name {
            return &traitType.methods[i];
        }
    }
    return nil;
}

/// Resolve a trait declaration body: supertrait methods, then own methods.
fn resolveTraitBody(self: *mut Resolver, node: *ast::Node, supertraits: *mut [*ast::Node], methods: *mut [*ast::Node])
    throws (ResolveError)
{
    let sym = symbolFor(self, node)
        else return;
    let case SymbolData::Trait(traitType) = sym.data
        else return;

    // Resolve supertrait bounds and copy their methods into this trait.
    for superNode in supertraits {
        let superSym = try resolveNamePath(self, superNode);
        let case SymbolData::Trait(superTrait) = superSym.data
            else throw emitError(self, superNode, ErrorKind::Internal);
        setNodeSymbol(self, superNode, superSym);

        let a = alloc::arenaAllocator(&mut self.arena);
        if traitType.methods.len + superTrait.methods.len > ast::MAX_TRAIT_METHODS {
            throw emitError(self, node, ErrorKind::TraitMethodOverflow(CountMismatch {
                expected: ast::MAX_TRAIT_METHODS,
                actual: traitType.methods.len as u32 + superTrait.methods.len as u32,
            }));
        }
        // Copy inherited methods into this trait's method table.
        for inherited in superTrait.methods {
            if let _ = findTraitMethod(traitType, inherited.name) {
                throw emitError(self, superNode, ErrorKind::DuplicateBinding(inherited.name));
            }
            traitType.methods.append(TraitMethod {
                name: inherited.name,
                fnType: inherited.fnType,
                mutable: inherited.mutable,
                index: traitType.methods.len as u32,
            }, a);
        }
        traitType.supertraits.append(superTrait, a);
    }

    if traitType.methods.len + methods.len > ast::MAX_TRAIT_METHODS {
        throw emitError(self, node, ErrorKind::TraitMethodOverflow(CountMismatch {
            expected: ast::MAX_TRAIT_METHODS,
            actual: traitType.methods.len as u32 + methods.len as u32,
        }));
    }

    for methodNode in methods {
        let case ast::NodeValue::TraitMethodSig { name, receiver, sig } = methodNode.value
            else continue;
        let methodName = try nodeName(self, name);

        // Reject duplicate method names.
        if let _ = findTraitMethod(traitType, methodName) {
            throw emitError(self, name, ErrorKind::DuplicateBinding(methodName));
        }

        // Determine receiver mutability from the receiver type node
        // and validate that the receiver points to the declaring trait.
        let case ast::NodeValue::TypeSig(typeSig) = receiver.value
            else throw emitError(self, receiver, ErrorKind::TraitReceiverMismatch);
        let case ast::TypeSig::Pointer { mutable, valueType } = typeSig
            else throw emitError(self, receiver, ErrorKind::TraitReceiverMismatch);
        let case ast::NodeValue::TypeSig(innerSig) = valueType.value
            else throw emitError(self, receiver, ErrorKind::TraitReceiverMismatch);
        let case ast::TypeSig::Nominal(nameNode) = innerSig
            else throw emitError(self, receiver, ErrorKind::TraitReceiverMismatch);
        let receiverTargetName = try nodeName(self, nameNode);

        if receiverTargetName != traitType.name {
            throw emitError(self, receiver, ErrorKind::TraitReceiverMismatch);
        }
        // Resolve parameter types and return type.
        let a = alloc::arenaAllocator(&mut self.arena);
        let mut paramTypes: *mut [*Type] = &mut [];
        let mut throwList: *mut [*Type] = &mut [];
        let mut retType = allocType(self, Type::Void);

        if sig.params.len > MAX_FN_PARAMS {
            throw emitError(self, methodNode, ErrorKind::FnParamOverflow(CountMismatch {
                expected: MAX_FN_PARAMS,
                actual: sig.params.len,
            }));
        }
        for paramNode in sig.params {
            let paramTy = try infer(self, paramNode);
            paramTypes.append(allocType(self, paramTy), a);
        }
        if let ret = sig.returnType {
            retType = allocType(self, try infer(self, ret));
        }
        // Resolve throws list.
        if sig.throwList.len > MAX_FN_THROWS {
            throw emitError(self, methodNode, ErrorKind::FnThrowOverflow(CountMismatch {
                expected: MAX_FN_THROWS,
                actual: sig.throwList.len,
            }));
        }
        for throwNode in sig.throwList {
            let throwTy = try infer(self, throwNode);
            throwList.append(allocType(self, throwTy), a);
        }
        let fnType = FnType {
            paramTypes: &paramTypes[..],
            returnType: retType,
            throwList: &throwList[..],
            localCount: 0,
            isUnsafe: false,
        };
        traitType.methods.append(TraitMethod {
            name: methodName,
            fnType: allocFnType(self, fnType),
            mutable,
            index: traitType.methods.len as u32,
        }, a);

        setNodeType(self, methodNode, Type::Void);
    }
}

/// Resolve a name path node to a symbol.
/// Used for trait and type references in instance declarations and trait objects.
fn resolveNamePath(self: *mut Resolver, node: *ast::Node) -> *mut Symbol
    throws (ResolveError)
{
    match node.value {
        case ast::NodeValue::Ident(name) => {
            let sym = findAnySymbol(self.scope, name)
                else throw emitError(self, node, ErrorKind::UnresolvedSymbol(name));
            return sym;
        }
        case ast::NodeValue::ScopeAccess(access) => {
            return try resolveAccess(self, node, access, self.scope);
        }
        else => {
            throw emitError(self, node, ErrorKind::ExpectedIdentifier);
        }
    }
}

/// Resolve an instance declaration.
/// Validates that the trait exists, the target type exists, and all methods
/// match the trait's signatures.
fn resolveInstanceDecl(
    self: *mut Resolver,
    node: *ast::Node,
    traitName: *ast::Node,
    targetType: *ast::Node,
    methods: *mut [*ast::Node]
) throws (ResolveError) {
    // Look up the trait.
    let traitSym = try resolveNamePath(self, traitName);
    let case SymbolData::Trait(traitInfo) = traitSym.data
        else throw emitError(self, traitName, ErrorKind::Internal);

    setNodeSymbol(self, traitName, traitSym);

    // Look up the target type.
    let typeSym = try resolveNamePath(self, targetType);
    let case SymbolData::Type(nominalTy) = typeSym.data
        else throw emitError(self, targetType, ErrorKind::Internal);
    setNodeSymbol(self, targetType, typeSym);
    // Ensure the concrete type body is resolved.
    try ensureNominalResolved(self, nominalTy, targetType);

    // Reject duplicate instance for the same (trait, type) pair.
    let concreteType = Type::Nominal(nominalTy);
    if let _ = findInstance(self, traitInfo, concreteType) {
        throw emitError(self, node, ErrorKind::DuplicateInstance);
    }

    // Build the instance entry.
    if self.instancesLen >= MAX_INSTANCES {
        throw emitError(self, node, ErrorKind::Internal);
    }
    let methodSlice = try! alloc::allocSlice(
        &mut self.arena, @sizeOf(*mut Symbol), @alignOf(*mut Symbol), traitInfo.methods.len as u32
    ) as *mut [*mut Symbol];
    let mut entry = InstanceEntry {
        traitType: traitInfo,
        concreteType,
        concreteTypeName: typeSym.name,
        moduleId: self.currentMod,
        methods: methodSlice,
    };
    // Track which trait methods are covered by the instance.
    let mut covered: [bool; ast::MAX_TRAIT_METHODS] = [false; ast::MAX_TRAIT_METHODS];

    // Match each instance method to a trait method.
    for methodNode in methods {
        let case ast::NodeValue::MethodDecl {
            name, receiverName, receiverType, sig, body, ..
        } = methodNode.value else continue;

        let methodName = try nodeName(self, name);

        // Find the matching trait method.
        let tm = findTraitMethod(traitInfo, methodName)
            else throw emitError(self, name, ErrorKind::UnresolvedSymbol(methodName));

        // Determine receiver mutability and validate receiver type.
        // The receiver must be `*Type` or `*mut Type`.
        let case ast::NodeValue::TypeSig(typeSig) = receiverType.value
            else throw emitError(self, receiverType, ErrorKind::TraitReceiverMismatch);
        let case ast::TypeSig::Pointer { mutable: receiverMut, valueType } = typeSig
            else throw emitError(self, receiverType, ErrorKind::TraitReceiverMismatch);

        // Validate that the receiver type annotation matches the
        // concrete type from the instance declaration.
        let annotatedTy = try infer(self, valueType);
        if not typesEqual(annotatedTy, concreteType) {
            throw emitTypeMismatch(self, receiverType, TypeMismatch {
                expected: concreteType,
                actual: annotatedTy,
            });
        }

        // Check receiver mutability matches in both directions.
        if tm.mutable and not receiverMut {
            throw emitError(self, receiverType, ErrorKind::ImmutableBinding);
        }
        if receiverMut and not tm.mutable {
            throw emitError(self, receiverType, ErrorKind::ReceiverMutabilityMismatch);
        }

        // Build the function type for the instance method.
        // The receiver becomes the first parameter.
        let receiverPtrType = Type::Pointer {
            target: allocType(self, concreteType),
            mutable: receiverMut,
        };

        // Validate that the instance method's signature matches the
        // trait method's signature exactly (params, return type, throws).
        if sig.params.len != tm.fnType.paramTypes.len {
            throw emitError(self, methodNode, ErrorKind::FnArgCountMismatch(CountMismatch {
                expected: tm.fnType.paramTypes.len as u32,
                actual: sig.params.len,
            }));
        }
        for paramNode, j in sig.params {
            let case ast::NodeValue::FnParam(param) = paramNode.value
                else throw emitError(self, paramNode, ErrorKind::ExpectedIdentifier);
            let instanceParamTy = try resolveValueType(self, param.type);
            if not typesEqual(instanceParamTy, *tm.fnType.paramTypes[j]) {
                throw emitTypeMismatch(self, paramNode, TypeMismatch {
                    expected: *tm.fnType.paramTypes[j],
                    actual: instanceParamTy,
                });
            }
        }
        let mut instanceRetTy = Type::Void;
        if let retNode = sig.returnType {
            instanceRetTy = try resolveValueType(self, retNode);
        }
        if not typesEqual(instanceRetTy, *tm.fnType.returnType) {
            throw emitTypeMismatch(self, methodNode, TypeMismatch {
                expected: *tm.fnType.returnType,
                actual: instanceRetTy,
            });
        }
        if sig.throwList.len != tm.fnType.throwList.len {
            throw emitError(self, methodNode, ErrorKind::FnThrowCountMismatch(CountMismatch {
                expected: tm.fnType.throwList.len as u32,
                actual: sig.throwList.len,
            }));
        }
        for throwNode, j in sig.throwList {
            let instanceThrowTy = try resolveValueType(self, throwNode);
            if not typesEqual(instanceThrowTy, *tm.fnType.throwList[j]) {
                throw emitTypeMismatch(self, throwNode, TypeMismatch {
                    expected: *tm.fnType.throwList[j],
                    actual: instanceThrowTy,
                });
            }
        }

        // Build final function type: receiver plus trait's canonical types.
        let a = alloc::arenaAllocator(&mut self.arena);
        // TODO: Improve this pattern, maybe via something like `(&[]).append(..)`?
        let mut paramTypes: *mut [*Type] = &mut [];
        paramTypes.append(allocType(self, receiverPtrType), a);

        for ty in tm.fnType.paramTypes {
            paramTypes.append(ty, a);
        }
        let fnType = FnType {
            paramTypes: &paramTypes[..],
            returnType: tm.fnType.returnType,
            throwList: tm.fnType.throwList,
            localCount: 0,
            isUnsafe: false,
        };

        // Create a symbol for the instance method without binding it into the
        // module scope. Instance methods are dispatched via v-table, so they
        // must not pollute the enclosing scope.
        let fnTy = Type::Fn(allocFnType(self, fnType));
        let mName = try nodeName(self, name);
        let sym = allocSymbol(self, SymbolData::Value {
            mutable: false, alignment: 0, type: fnTy, addressTaken: false,
        }, mName, methodNode, 0);

        setNodeSymbol(self, methodNode, sym);
        setNodeType(self, methodNode, fnTy);
        setNodeType(self, name, fnTy);

        // Store in instance entry at the matching v-table slot.
        entry.methods[tm.index] = sym;
        covered[tm.index] = true;
    }

    // Fill inherited method slots from supertrait instances.
    for superTrait in traitInfo.supertraits {
        let superInst = findInstance(self, superTrait, concreteType)
            else throw emitError(self, node, ErrorKind::MissingSupertraitInstance(superTrait.name));
        for superMethod, mi in superTrait.methods {
            let merged = findTraitMethod(traitInfo, superMethod.name)
                else panic "resolveInstanceDecl: inherited method not found";
            if not covered[merged.index] {
                entry.methods[merged.index] = superInst.methods[mi];
                covered[merged.index] = true;
            }
        }
    }

    // Check that all trait methods are implemented.
    for method, i in traitInfo.methods {
        if not covered[i] {
            throw emitError(self, node, ErrorKind::MissingTraitMethod(method.name));
        }
    }
    self.instances[self.instancesLen] = entry;
    self.instancesLen += 1;

    setNodeType(self, node, Type::Void);
}

/// Resolve instance method bodies.
fn resolveInstanceMethodBodies(self: *mut Resolver, methods: *mut [*ast::Node])
    throws (ResolveError)
{
    for methodNode in methods {
        let case ast::NodeValue::MethodDecl {
            name, receiverName, receiverType, sig, body, ..
        } = methodNode.value else continue;

        // Symbol may be absent if [`resolveInstanceDecl`] reported an error
        // for this method (eg. unknown method name). Skip gracefully.
        let sym = symbolFor(self, methodNode)
            else continue;

        try resolveMethodBody(self, methodNode, receiverName, sig, body);
    }
}

/// Resolve a method body shared by instance methods and standalone methods.
/// Binds the receiver and parameters, then type-checks the body.
fn resolveMethodBody(
    self: *mut Resolver,
    node: *ast::Node,
    receiverName: *ast::Node,
    sig: ast::FnSig,
    body: *ast::Node,
) throws (ResolveError) {
    let sym = symbolFor(self, node)
        else throw emitError(self, node, ErrorKind::Internal);
    let case SymbolData::Value { type: Type::Fn(fnType), .. } = sym.data
        else panic "resolveMethodBody: expected value symbol";

    // Enter function scope.
    enterFn(self, node, fnType);
    if fnType.isUnsafe {
        self.unsafeDepth += 1;
    }

    // Bind the receiver parameter.
    let receiverTy = *fnType.paramTypes[0];
    try bindValueIdent(self, receiverName, receiverName, receiverTy, false, 0, 0) catch e {
        if fnType.isUnsafe { self.unsafeDepth -= 1; }
        exitFn(self);
        throw e;
    };
    // Bind the remaining parameters from the signature.
    for paramNode in sig.params {
        let paramTy = try infer(self, paramNode) catch e {
            if fnType.isUnsafe { self.unsafeDepth -= 1; }
            exitFn(self);
            throw e;
        };
    }

    // Resolve the body.
    let retTy = *fnType.returnType;
    let bodyTy = try checkAssignable(self, body, Type::Void) catch e {
        if fnType.isUnsafe { self.unsafeDepth -= 1; }
        exitFn(self);
        throw e;
    };
    if retTy != Type::Void and bodyTy != Type::Never {
        if fnType.isUnsafe { self.unsafeDepth -= 1; }
        exitFn(self);
        throw emitError(self, body, ErrorKind::FnMissingReturn);
    }
    if fnType.isUnsafe { self.unsafeDepth -= 1; }
    exitFn(self);
}

/// Resolve a standalone method declaration (signature only).
/// Validates the receiver type and registers the method in the method table.
/// Extract the type name from a resolved receiver type node (`*T` or `*mut T`).
fn receiverTypeName(self: *mut Resolver, receiverType: *ast::Node) -> *[u8] throws (ResolveError) {
    let case ast::NodeValue::TypeSig(ast::TypeSig::Pointer { valueType, .. }) = receiverType.value
        else throw emitError(self, receiverType, ErrorKind::TraitReceiverMismatch);
    let case ast::NodeValue::TypeSig(ast::TypeSig::Nominal(nameNode)) = valueType.value
        else throw emitError(self, receiverType, ErrorKind::Internal);
    let sym = symbolFor(self, nameNode)
        else throw emitError(self, receiverType, ErrorKind::Internal);

    return sym.name;
}

fn resolveMethodDecl(
    self: *mut Resolver,
    node: *ast::Node,
    name: *ast::Node,
    receiverName: *ast::Node,
    receiverType: *ast::Node,
    sig: ast::FnSig,
    attrs: ?ast::Attributes,
) throws (ResolveError) {
    // Resolve the receiver type: must be `*Type` or `*mut Type` pointing to a
    // nominal type.
    let fullReceiverTy = try infer(self, receiverType);
    let case Type::Pointer { target, mutable: receiverMut } = fullReceiverTy
        else throw emitError(self, receiverType, ErrorKind::TraitReceiverMismatch);
    let concreteType = *target;
    let case Type::Nominal(nominalTy) = concreteType
        else throw emitError(self, receiverType, ErrorKind::ExpectedRecord);
    try ensureNominalResolved(self, nominalTy, receiverType);

    // Get the type name from the inner type node's symbol.
    let typeName = try receiverTypeName(self, receiverType);
    let methodName = try nodeName(self, name);

    // Reject duplicate method for the same (type, name).
    if let _ = findMethod(self, concreteType, methodName) {
        throw emitError(self, name, ErrorKind::DuplicateBinding(methodName));
    }

    // Resolve parameter types.
    let a = alloc::arenaAllocator(&mut self.arena);
    let mut paramTypes: *mut [*Type] = &mut [];

    // Receiver is the first parameter.
    let receiverPtrType = Type::Pointer {
        target: allocType(self, concreteType),
        mutable: receiverMut,
    };
    paramTypes.append(allocType(self, receiverPtrType), a);

    for paramNode in sig.params {
        let case ast::NodeValue::FnParam(param) = paramNode.value
            else throw emitError(self, paramNode, ErrorKind::ExpectedIdentifier);
        let paramTy = try resolveValueType(self, param.type);
        paramTypes.append(allocType(self, paramTy), a);
    }

    // Resolve return type.
    let mut returnType = Type::Void;
    if let retNode = sig.returnType {
        returnType = try resolveValueType(self, retNode);
    }

    // Resolve throw list.
    let mut throwTypes: *mut [*Type] = &mut [];
    for throwNode in sig.throwList {
        let throwTy = try resolveValueType(self, throwNode);
        throwTypes.append(allocType(self, throwTy), a);
    }

    let retTypePtr = allocType(self, returnType);
    let throwList = &throwTypes[..];

    let isUnsafe = ast::hasAttribute(resolveAttributes(self, attrs), ast::Attribute::Unsafe);

    // Full function type (receiver + params) for lowering.
    let fullFnType = FnType {
        paramTypes: &paramTypes[..], returnType: retTypePtr, throwList, localCount: 0,
        isUnsafe,
    };
    let fnTy = Type::Fn(allocFnType(self, fullFnType));

    // Function type excluding receiver, for call arg checking.
    let checkFnType = FnType {
        paramTypes: &paramTypes[1..], returnType: retTypePtr, throwList, localCount: 0,
        isUnsafe,
    };

    // Compute attribute mask.
    let mut attrMask: u32 = 0;
    if let a = attrs {
        for attrNode in a.list {
            if let case ast::NodeValue::Attribute(attr) = attrNode.value {
                attrMask = attrMask | (attr as u32);
            }
        }
    }

    // Create a symbol for the method without binding it into the module scope.
    let sym = allocSymbol(self, SymbolData::Value {
        mutable: false, alignment: 0, type: fnTy, addressTaken: false,
    }, methodName, node, attrMask);

    setNodeSymbol(self, node, sym);
    setNodeType(self, node, fnTy);
    setNodeType(self, name, fnTy);

    // Register in the method table.
    if self.methodsLen >= MAX_METHODS {
        throw emitError(self, node, ErrorKind::Internal);
    }
    self.methods[self.methodsLen] = MethodEntry {
        concreteType,
        concreteTypeName: typeName,
        name: methodName,
        fnType: allocFnType(self, checkFnType),
        mutable: receiverMut,
        symbol: sym,
    };
    self.methodsLen += 1;
}

/// Look up an instance entry by trait and concrete type.
fn findInstance(self: *Resolver, traitInfo: *TraitType, concreteType: Type) -> ?*InstanceEntry {
    for i in 0..self.instancesLen {
        let entry = &self.instances[i];
        if entry.traitType == traitInfo and typesEqual(entry.concreteType, concreteType) {
            return entry;
        }
    }
    return nil;
}

/// Look up a standalone method by concrete type and name.
pub fn findMethod(self: *Resolver, concreteType: Type, name: *[u8]) -> ?*MethodEntry {
    for i in 0..self.methodsLen {
        let entry = &self.methods[i];
        if typesEqual(entry.concreteType, concreteType) and entry.name == name {
            return entry;
        }
    }
    return nil;
}

/// Look up a standalone method entry by its symbol.
pub fn findMethodBySymbol(self: *Resolver, sym: *mut Symbol) -> ?*MethodEntry {
    for i in 0..self.methodsLen {
        let entry = &self.methods[i];
        if entry.symbol == sym {
            return entry;
        }
    }
    return nil;
}

/// Resolve union variant types after all type names are bound (Phase 2 of type resolution).
fn resolveUnionBody(self: *mut Resolver, node: *ast::Node, decl: ast::UnionDecl)
    throws (ResolveError)
{
    // Get the type symbol that was bound to this declaration node.
    // If there's no symbol, it's because an earlier phase failed.
    let sym = symbolFor(self, node)
        else return;
    let case SymbolData::Type(nominalTy) = sym.data
        else panic "resolveUnionBody: unexpected symbol data";

    // Check if already resolved, in which case there's no need to
    // do it again.
    if let case NominalType::Union(_) = *nominalTy {
        return;
    }
    let a = alloc::arenaAllocator(&mut self.arena);
    let mut variants: *mut [UnionVariant] = &mut [];

    // Create a temporary nominal type to replace the placeholder.This prevents infinite recursion
    // when a variant references this union type (e.g. record payloads with `*[Self]`).
    // TODO: It would be best to have a resolving state eg. `Visiting` for this situation.
    *nominalTy = NominalType::Union(UnionType {
        variants: &[],
        layout: Layout { size: 0, alignment: 0 },
        valOffset: 0,
        isAllVoid: true
    });

    try visitList(self, decl.derives);

    assert decl.variants.len <= MAX_UNION_VARIANTS, "resolveUnionBody: maximum union variants exceeded";
    let mut iota: u32 = 0;
    for variantNode, i in decl.variants {
        let case ast::NodeValue::UnionDeclVariant(variantDecl) = variantNode.value
            else panic "resolveUnionBody: invalid union variant";
        let variantName = try nodeName(self, variantDecl.name);
        // Resolve the variant's payload type if present.
        let mut variantType = Type::Void;
        if let ty = try visitOptional(self, variantDecl.type, Type::Unknown) {
            variantType = ty;
        }
        // Process the variant's explicit discriminant value if present.
        try visitOptional(self, variantDecl.value, variantType);
        let tag = variantTag(variantDecl, &mut iota);
        // Create a symbol for this variant.
        let data = SymbolData::Variant { type: variantType, decl: node, ordinal: i, index: tag };
        let variantSym = allocSymbol(self, data, variantName, variantNode, 0);

        variants.append(UnionVariant {
            name: variantName,
            valueType: variantType,
            symbol: variantSym,
        }, a);
    }
    let info = computeUnionLayout(&variants[..]);

    // Update the nominal type with the resolved variants.
    *nominalTy = NominalType::Union(UnionType {
        variants: &variants[..],
        layout: info.layout,
        valOffset: info.valOffset,
        isAllVoid: info.isAllVoid,
    });
}

/// Check if a module should be analyzed based on its attributes and build configuration.
fn shouldAnalyzeModule(self: *Resolver, attrs: ?ast::Attributes) -> bool {
    if let attributes = attrs {
        // Skip test modules unless we're building in test mode.
        if ast::attributesContains(&attributes, ast::Attribute::Test) and not self.config.buildTest {
            return false;
        }
    }
    return true;
}

/// Analyze a module during the graph analysis phase.
fn resolveModGraph(self: *mut Resolver, node: *ast::Node, decl: ast::Mod)
    throws (ResolveError)
{
    if not shouldAnalyzeModule(self, decl.attrs) {
        return;
    }
    let modName = try nodeName(self, decl.name);
    let attrMask = resolveAttributes(self, decl.attrs);
    try ensureDefaultAttrNotAllowed(self, node, attrMask);
    let submod = try enterSubModule(self, modName, node);

    // Bind the module symbol in the outer scope, ie. where the `mod` statement is.
    try bindModuleIdent(self, submod.entry, submod.newScope, submod.root, attrMask, submod.prevScope);
    let case ast::NodeValue::Block(block) = submod.root.value
        else panic "resolveModGraph: expected block for module root";
    try resolveModuleGraph(self, &block);

    exitModuleScope(self, submod);
}

/// Analyze a module in the declaration phase.
fn resolveModDecl(self: *mut Resolver, node: *ast::Node, decl: ast::Mod)
    throws (ResolveError)
{
    if not shouldAnalyzeModule(self, decl.attrs) {
        return;
    }
    // Find module under the current module.
    let modName = try nodeName(self, decl.name);
    let submod = try enterSubModule(self, modName, node);
    let case ast::NodeValue::Block(block) = submod.root.value
        else panic "resolveModDecl: expected block for module root";
    try resolveModuleDecls(self, &block);

    exitModuleScope(self, submod);
}

/// Analyze a `use` statement and create a symbol for the imported module.
fn resolveUse(self: *mut Resolver, node: *ast::Node, decl: ast::Use) -> Type
    throws (ResolveError)
{
    let resolved = try resolveModulePath(self, decl.path);
    let attrMask = resolveAttributes(self, decl.attrs);

    if decl.wildcard {
        // Import all public symbols from the target module.
        for i in 0..resolved.scope.symbolsLen {
            let sym = resolved.scope.symbols[i];
            if ast::hasAttribute(sym.attrs, ast::Attribute::Pub) {
                try addSymbolToScope(self, sym, self.scope, node);
            }
        }
    } else {
        // Regular module import.
        try bindModuleIdent(self, resolved.entry, resolved.scope, node, attrMask, self.scope);
    }
    return Type::Void;
}

/// Analyze a standard `if` statement.
fn resolveIf(self: *mut Resolver, node: *ast::Node, cond: ast::If) -> Type
    throws (ResolveError)
{
    try checkBoolean(self, cond.condition);
    let thenTy = try visit(self, cond.thenBranch, Type::Void);
    let elseTy = try visitOptional(self, cond.elseBranch, Type::Void);

    return setNodeType(self, node, unifyBranches(thenTy, elseTy));
}

/// Analyze a conditional expression.
fn resolveCondExpr(self: *mut Resolver, node: *ast::Node, cond: ast::CondExpr) -> Type
    throws (ResolveError)
{
    try checkBoolean(self, cond.condition);
    let thenTy = try infer(self, cond.thenExpr);
    let _ = try checkAssignable(self, cond.elseExpr, thenTy);

    return setNodeType(self, node, thenTy);
}

/// Analyze a pattern match structure (used by if-let, while-let).
fn resolvePatternMatch(self: *mut Resolver, node: *ast::Node, pat: *ast::PatternMatch)
    throws (ResolveError)
{
    match pat.kind {
        case ast::PatternKind::Case => {
            // Analyze pattern against scrutinee type.
            let scrutineeTy = try infer(self, pat.scrutinee);
            let subject = unwrapMatchSubject(scrutineeTy);
            try resolveCasePattern(self, pat.pattern, subject.effectiveTy, IdentMode::Compare, subject.by);
        }
        case ast::PatternKind::Binding => {
            // Scrutinee must be optional, bind the payload.
            let scrutineeTy = try checkOptional(self, pat.scrutinee);
            let payloadTy = *scrutineeTy;

            try bindValueIdent(self, pat.pattern, node, payloadTy, pat.mutable, 0, 0);
            setNodeType(self, pat.pattern, payloadTy);
        }
    }
    if let guard = pat.guard {
        try checkBoolean(self, guard);
    }
}

/// Analyze an `if let` or `if let case` pattern binding.
fn resolveIfLet(self: *mut Resolver, node: *ast::Node, cond: ast::IfLet) -> Type
    throws (ResolveError)
{
    enterScope(self, node);
    try resolvePatternMatch(self, node, &cond.pattern);

    let thenTy = try visit(self, cond.thenBranch, Type::Void);
    exitScope(self);

    let elseTy = try visitOptional(self, cond.elseBranch, Type::Void);

    return setNodeType(self, node, unifyBranches(thenTy, elseTy));
}

/// Controls how bare identifiers are handled in case patterns.
union IdentMode {
    /// Identifier is a value to compare against.
    Compare,
    /// Identifier introduces a new binding.
    Bind,
}

/// Check whether a pattern node is a destructuring pattern that looks
/// through structure (union variant, record literal, scope access).
/// Identifiers, placeholders, and plain literals are not destructuring.
pub fn isDestructuringPattern(pattern: *ast::Node) -> bool {
    match pattern.value {
        case ast::NodeValue::Call(_),
             ast::NodeValue::RecordLit(_),
             ast::NodeValue::ScopeAccess(_) => return true,
        else => return false,
    }
}

/// Analyze a case pattern for match, if-case, let-case, or while-case.
///
/// At the top level, bare identifiers are compared against existing values.
/// Inside destructuring patterns (arrays, records), identifiers become bindings.
fn resolveCasePattern(
    self: *mut Resolver,
    pattern: *ast::Node,
    scrutineeTy: Type,
    mode: IdentMode,
    matchBy: MatchBy
) throws (ResolveError) {
    // TODO: Collapse these nested matches.
    match scrutineeTy {
        case Type::Pointer { target, .. } => {
            // Auto-deref: when the scrutinee is a pointer and the pattern
            // is a destructuring pattern, resolve against the pointed-to type.
            if isDestructuringPattern(pattern) {
                try resolveCasePattern(self, pattern, *target, mode, matchBy);
                return;
            }
        }
        case Type::Nominal(info) => {
            try ensureNominalResolved(self, info, pattern);

            match *info {
                case NominalType::Union(unionType) => {
                    try resolveUnionPattern(self, pattern, scrutineeTy, unionType, matchBy);
                    return;
                }
                case NominalType::Record(recInfo) => {
                    match pattern.value {
                        case ast::NodeValue::Call(_), ast::NodeValue::RecordLit(_) => {
                            try bindRecordPatternFields(self, pattern, recInfo, matchBy);
                            return;
                        } else => {}
                    }
                } else => {}
            }
        }
        case Type::Array(arrayInfo) => {
            if let case ast::NodeValue::ArrayLit(items) = pattern.value {
                if items.len as u32 != arrayInfo.length {
                    throw emitError(self, pattern, ErrorKind::RecordFieldCountMismatch(
                        CountMismatch { expected: arrayInfo.length, actual: items.len as u32 }
                    ));
                }
                let elemTy = *arrayInfo.item;
                for item in items {
                    try resolveCasePattern(self, item, elemTy, IdentMode::Bind, matchBy);
                }
                setNodeType(self, pattern, scrutineeTy);
                return;
            }
        } else => {}
    }
    // Handle non-binding patterns (literals, placeholders) and bindings.
    match pattern.value {
        case ast::NodeValue::Placeholder => {
            // Placeholder matches without introducing bindings.
        }
        case ast::NodeValue::Ident(_) => {
            match mode {
                case IdentMode::Bind => try bindPatternVar(self, pattern, scrutineeTy, matchBy),
                case IdentMode::Compare => try checkAssignable(self, pattern, scrutineeTy),
            }
        }
        else => {
            // Literals and other expressions: check type compatibility.
            try checkAssignable(self, pattern, scrutineeTy);
        }
    }
}

/// Analyze a traditional `while` loop.
fn resolveWhile(self: *mut Resolver, node: *ast::Node, loopNode: ast::While) -> Type
    throws (ResolveError)
{
    try checkBoolean(self, loopNode.condition);
    try visitLoop(self, loopNode.body);
    try visitOptional(self, loopNode.elseBranch, Type::Void);

    return setNodeType(self, node, Type::Void);
}

/// Analyze a `while let` loop with pattern binding.
fn resolveWhileLet(self: *mut Resolver, node: *ast::Node, loopNode: ast::WhileLet) -> Type
    throws (ResolveError)
{
    enterScope(self, node);
    try resolvePatternMatch(self, node, &loopNode.pattern);

    try visitLoop(self, loopNode.body);
    exitScope(self);

    try visitOptional(self, loopNode.elseBranch, Type::Void);

    return setNodeType(self, node, Type::Void);
}

/// Analyze a `for` loop, binding iteration variables.
fn resolveFor(self: *mut Resolver, node: *ast::Node, forStmt: ast::For) -> Type
    throws (ResolveError)
{
    let iterableTy = try infer(self, forStmt.iterable);

    // Extract binding names for the lowerer.
    let mut bindingName: ?*[u8] = nil;
    if let case ast::NodeValue::Ident(name) = forStmt.binding.value {
        bindingName = name;
    }
    let mut indexName: ?*[u8] = nil;
    if let idx = forStmt.index {
        if let case ast::NodeValue::Ident(name) = idx.value {
            indexName = name;
        }
    }
    // Extract item type and store pre-computed loop metadata for the lowerer.
    let mut itemTy: Type = undefined;
    match iterableTy {
        case Type::Range { start, .. } => {
            // Iterable ranges must have a start, and since we enforce type
            // equality for start and end, that is always the item type.
            let valType = start else {
                throw emitError(self, forStmt.iterable, ErrorKind::ExpectedIterable);
            };
            let case ast::NodeValue::Range(range) = forStmt.iterable.value else {
                throw emitError(self, forStmt.iterable, ErrorKind::ExpectedIterable);
            };
            itemTy = *valType;

            setForLoopInfo(self, node, ForLoopInfo::Range {
                valType, range, bindingName, indexName
            });
        }
        case Type::Array(arrayInfo) => {
            itemTy = *arrayInfo.item;
            setForLoopInfo(self, node, ForLoopInfo::Collection {
                elemType: arrayInfo.item,
                length: arrayInfo.length,
                bindingName,
                indexName,
            });
        }
        case Type::Slice { item, .. } => {
            itemTy = *item;
            setForLoopInfo(self, node, ForLoopInfo::Collection {
                elemType: item, length: nil, bindingName, indexName
            });
        }
        else => throw emitError(self, forStmt.iterable, ErrorKind::ExpectedIterable),
    }
    enterScope(self, node);
    try bindForLoopPattern(self, forStmt.binding, itemTy, false);

    if let pat = forStmt.index {
        try bindForLoopPattern(self, pat, Type::U32, false);
    }
    // The lowerer always creates at least one internal variable for iteration,
    // even when the binding is a placeholder or no explicit index is given.
    if let mut fnType = self.currentFn {
        fnType.localCount += 1;
    }
    try visitLoop(self, forStmt.body);
    exitScope(self);

    try visitOptional(self, forStmt.elseBranch, Type::Void);

    return setNodeType(self, node, Type::Void);
}

/// Get the node within a pattern that carries the `UnionVariant` extra.
/// For `ScopeAccess` it is the pattern itself, for `RecordLit` it is the
/// type name, and for `Call` it is the callee.
pub fn patternVariantKeyNode(pattern: *ast::Node) -> ?*ast::Node {
    match pattern.value {
        case ast::NodeValue::ScopeAccess(_) => return pattern,
        case ast::NodeValue::RecordLit(lit) => return lit.typeName,
        case ast::NodeValue::Call(call) => return call.callee,
        else => return nil,
    }
}

/// Get the i-th sub-pattern element from a compound pattern.
/// For `RecordLit` this is the i-th field's value; for `Call` it is the
/// i-th argument.
fn patternSubElement(pattern: *ast::Node, idx: u32) -> ?*ast::Node {
    match pattern.value {
        case ast::NodeValue::RecordLit(lit) => {
            if idx < lit.fields.len as u32 {
                if let case ast::NodeValue::RecordLitField(field) = lit.fields[idx].value {
                    return field.value;
                }
            }
        }
        case ast::NodeValue::Call(call) => {
            if idx < call.args.len as u32 {
                return call.args[idx];
            }
        }
        else => {}
    }
    return nil;
}

/// Get the number of sub-pattern elements in a compound pattern.
fn patternSubCount(pattern: *ast::Node) -> u32 {
    match pattern.value {
        case ast::NodeValue::RecordLit(lit) => return lit.fields.len as u32,
        case ast::NodeValue::Call(call) => return call.args.len as u32,
        else => return 0,
    }
}

/// Check whether a pattern contains nested sub-patterns that further
/// refine the match beyond the outer variant (e.g. nested union variant
/// tests or literal comparisons). Used to allow the same outer variant
/// to appear in multiple match arms.
fn hasNestedRefiningPattern(self: *Resolver, pattern: *ast::Node) -> bool {
    for i in 0..patternSubCount(pattern) {
        if let sub = patternSubElement(pattern, i) {
            if isRefiningPattern(self, sub) {
                return true;
            }
        }
    }
    return false;
}

/// Check whether a single pattern node is a refining pattern that tests
/// a value rather than just binding it. Union variants, literals, and
/// scope accesses are refining; identifiers, placeholders, and plain
/// record destructurings are not.
fn isRefiningPattern(self: *Resolver, pattern: *ast::Node) -> bool {
    match pattern.value {
        case ast::NodeValue::Ident(_), ast::NodeValue::Placeholder =>
            return false,
        case ast::NodeValue::RecordLit(_), ast::NodeValue::Call(_) => {
            if let keyNode = patternVariantKeyNode(pattern) {
                if let case NodeExtra::UnionVariant { .. } = self.nodeData.entries[keyNode.id].extra {
                    return true;
                }
            }
            // Plain record destructuring / non-variant call is not directly
            // refining; recurse to check sub-patterns.
            return hasNestedRefiningPattern(self, pattern);
        }
        case ast::NodeValue::ArrayLit(items) => {
            for item in items {
                if isRefiningPattern(self, item) {
                    return true;
                }
            }
            return false;
        }
        case ast::NodeValue::ScopeAccess(_) =>
            return true,
        else =>
            return true,
    }
}

/// Check whether any pattern in a case prong matches unconditionally.
/// A plain `_` or an all-binding array pattern (e.g. `[x, y]`) qualifies.
/// Note: top-level identifiers in `case` are comparisons, not bindings,
/// so they do not count as wildcards.
fn hasWildcardPattern(patterns: *mut [*ast::Node]) -> bool {
    for pattern in patterns {
        match pattern.value {
            case ast::NodeValue::Placeholder => return true,
            case ast::NodeValue::ArrayLit(items) => {
                if isIrrefutableArrayPattern(items) {
                    return true;
                }
            }
            else => {}
        }
    }
    return false;
}

/// Check whether all elements of an array pattern are irrefutable.
/// Inside array patterns, identifiers are bindings, not comparisons.
fn isIrrefutableArrayPattern(items: *mut [*ast::Node]) -> bool {
    for item in items {
        match item.value {
            case ast::NodeValue::Ident(_), ast::NodeValue::Placeholder => {}
            case ast::NodeValue::ArrayLit(inner) => {
                if not isIrrefutableArrayPattern(inner) {
                    return false;
                }
            }
            else => return false,
        }
    }
    return true;
}

/// Analyze a match prong, checking for duplicate catch-alls. Returns the
/// unified match type.
fn resolveMatchProng(
    self: *mut Resolver,
    prongNode: *ast::Node,
    prong: ast::MatchProng,
    subjectTy: Type,
    state: *mut MatchState,
    matchType: Type,
    matchBy: MatchBy
) -> Type throws (ResolveError) {
    // Whether this prong is catch-all.
    let mut isCatchAll = false;

    if prong.guard != nil {
        state.isConst = false;
    } else {
        match prong.arm {
            case ast::ProngArm::Binding(_),
                 ast::ProngArm::Else => isCatchAll = true,
            case ast::ProngArm::Case(patterns) => isCatchAll = hasWildcardPattern(patterns),
        }
    }
    if isCatchAll {
        if state.catchAll {
            throw emitError(self, prongNode, ErrorKind::DuplicateCatchAll);
        }
        state.catchAll = true;
    }
    setProngCatchAll(self, prongNode, isCatchAll);

    return try visitMatchProng(self, prongNode, prong, subjectTy, matchType, matchBy);
}

/// Analyze a `match` expression. Dispatches to specialized functions based on
/// the subject type.
fn resolveMatch(self: *mut Resolver, node: *ast::Node, sw: ast::Match) -> Type
    throws (ResolveError)
{
    let subjectTy = try infer(self, sw.subject);
    let subject = unwrapMatchSubject(subjectTy);

    if let case Type::Optional(inner) = subject.effectiveTy {
        try resolveMatchOptional(self, node, sw, inner);
    } else if let case Type::Nominal(NominalType::Union(u)) = subject.effectiveTy {
        try resolveMatchUnion(self, node, sw, subject.effectiveTy, u, subject.by);
    } else {
        try resolveMatchGeneric(self, node, sw, subject.effectiveTy);
    }

    // Mark last non-guarded prong as exhaustive.
    let lastProng = sw.prongs[sw.prongs.len - 1];
    let case ast::NodeValue::MatchProng(p) = lastProng.value
        else panic "resolveMatch: expected match prong";
    if p.guard == nil {
        setProngCatchAll(self, lastProng, true);
    }
    let ty = typeFor(self, node) else {
        return Type::Void;
    };
    return ty;
}

/// Analyze a `match` expression on an optional subject.
fn resolveMatchOptional(self: *mut Resolver, node: *ast::Node, sw: ast::Match, innerTy: *Type) -> Type
    throws (ResolveError)
{
    let subjectTy = Type::Optional(innerTy);
    let prongs = sw.prongs;
    let mut hasValue = false;
    let mut hasNil = false;
    let mut catchAll = false;
    let mut matchType = Type::Never;

    for prongNode in prongs {
        let case ast::NodeValue::MatchProng(prong) = prongNode.value
            else panic "resolveMatchOptional: expected match prong";

        // For optionals, a binding prong only covers the value case, not `nil`.
        // Only `else` without a guard is a true catch-all.
        if prong.arm == ast::ProngArm::Else and prong.guard == nil {
            if catchAll {
                throw emitError(self, prongNode, ErrorKind::DuplicateCatchAll);
            }
            catchAll = true;
        }

        let mut isCatchAll = false;
        if prong.guard == nil {
            match prong.arm {
                case ast::ProngArm::Else => isCatchAll = true,
                case ast::ProngArm::Case(patterns) => isCatchAll = hasWildcardPattern(patterns),
                case ast::ProngArm::Binding(_) => {
                    // For optionals, a binding does *not* always match.
                }
            }
        }
        setProngCatchAll(self, prongNode, isCatchAll);
        matchType = try visitMatchProng(self, prongNode, prong, subjectTy, matchType, MatchBy::Value);

        // Track coverage. Guarded prongs don't count as covering a case.
        if prong.guard == nil {
            if let case ast::ProngArm::Binding(_) = prong.arm {
                if hasValue {
                    throw emitError(self, prongNode, ErrorKind::DuplicateMatchPattern);
                }
                hasValue = true;
            } else if let case ast::ProngArm::Case(patterns) = prong.arm {
                for pat in patterns {
                    if let case ast::NodeValue::Nil = pat.value {
                        if hasNil {
                            throw emitError(self, pat, ErrorKind::DuplicateMatchPattern);
                        }
                        hasNil = true;
                    }
                }
            }
        }
    }

    // Check exhaustiveness.
    if not catchAll {
        if not hasValue {
            throw emitError(self, node, ErrorKind::OptionalMatchMissingValue);
        }
        if not hasNil {
            throw emitError(self, node, ErrorKind::OptionalMatchMissingNil);
        }
    } else if hasValue and hasNil {
        throw emitError(self, node, ErrorKind::UnreachableElse);
    }
    return setNodeType(self, node, matchType);
}

/// Analyze a `match` expression on a union subject.
fn resolveMatchUnion(
    self: *mut Resolver,
    node: *ast::Node,
    sw: ast::Match,
    subjectTy: Type,
    info: UnionType,
    matchBy: MatchBy
) -> Type throws (ResolveError) {
    let prongs = sw.prongs;
    let mut covered: [bool; MAX_UNION_VARIANTS] = [false; MAX_UNION_VARIANTS];
    let mut coveredCount: u32 = 0;
    let mut state = MatchState { catchAll: false, isConst: false };
    let mut matchType = Type::Never;

    for prongNode in prongs {
        let case ast::NodeValue::MatchProng(prong) = prongNode.value
            else panic "resolveMatchUnion: expected match prong";

        matchType = try resolveMatchProng(self, prongNode, prong, subjectTy, &mut state, matchType, matchBy);

        // Guarded prongs don't count as covering. Patterns with nested
        // refining sub-patterns (e.g. matching different inner union variants)
        // don't count as duplicates or as fully covering.
        if prong.guard == nil {
            if let case ast::ProngArm::Case(patterns) = prong.arm {
                for pattern in patterns {
                    if let case NodeExtra::UnionVariant { ordinal: ix, .. } = self.nodeData.entries[pattern.id].extra {
                        if not hasNestedRefiningPattern(self, pattern) {
                            if covered[ix] {
                                throw emitError(self, pattern, ErrorKind::DuplicateMatchPattern);
                            }
                            covered[ix] = true;
                            coveredCount += 1;
                        }
                    }
                }
            }
        }
    }
    // Check that all variants are covered.
    if not state.catchAll {
        for variant, i in info.variants {
            if not covered[i] {
                throw emitError(
                    self, node, ErrorKind::UnionMatchNonExhaustive(variant.name)
                );
            }
        }
    } else if coveredCount == info.variants.len as u32 {
        throw emitError(self, node, ErrorKind::UnreachableElse);
    }
    return setNodeType(self, node, matchType);
}

/// Analyze a `match` expression on a generic subject type. Requires exhaustiveness:
/// booleans must cover both `true` and `false`, other types require a catch-all.
fn resolveMatchGeneric(self: *mut Resolver, node: *ast::Node, sw: ast::Match, subjectTy: Type) -> Type
    throws (ResolveError)
{
    let prongs = sw.prongs;
    let mut state = MatchState { catchAll: false, isConst: true };
    let mut matchType = Type::Never;
    let mut hasTrue = false;
    let mut hasFalse = false;
    let mut hasConstCase = false;

    for prongNode in prongs {
        let case ast::NodeValue::MatchProng(prong) = prongNode.value
            else panic "resolveMatchGeneric: expected match prong";

        matchType = try resolveMatchProng(
            self, prongNode, prong, subjectTy, &mut state, matchType, MatchBy::Value
        );
        // Track boolean coverage. Guarded prongs don't count as covering.
        if let case ast::ProngArm::Case(patterns) = prong.arm {
            for p in patterns {
                if prong.guard == nil {
                    if let case ast::NodeValue::Bool(val) = p.value {
                        if (val and hasTrue) or (not val and hasFalse) {
                            throw emitError(self, p, ErrorKind::DuplicateMatchPattern);
                        }
                        if val {
                            hasTrue = true;
                        } else {
                            hasFalse = true;
                        }
                    }
                }
                // Scalar constant patterns allow the match to be lowered
                // to a switch instruction.
                if let c = constValueEntry(self, p) {
                    match c {
                        case ConstValue::Bool(_), ConstValue::Char(_), ConstValue::Int(_) =>
                            hasConstCase = true,
                        else =>
                            state.isConst = false,
                    }
                }
            }
        }
    }

    // Check exhaustiveness.
    if not state.catchAll {
        if let case Type::Bool = subjectTy {
            if not hasTrue {
                throw emitError(self, node, ErrorKind::BoolMatchMissing(true));
            }
            if not hasFalse {
                throw emitError(self, node, ErrorKind::BoolMatchMissing(false));
            }
        } else {
            throw emitError(self, node, ErrorKind::MatchNonExhaustive);
        }
    } else if let case Type::Bool = subjectTy {
        if hasTrue and hasFalse {
            throw emitError(self, node, ErrorKind::UnreachableElse);
        }
    }
    setMatchConst(self, node, state.isConst and hasConstCase);

    return setNodeType(self, node, matchType);
}

/// Analyze a single `match` prong branch. Returns the unified match type.
fn visitMatchProng(
    self: *mut Resolver,
    node: *ast::Node,
    prongNode: ast::MatchProng,
    subjectTy: Type,
    matchType: Type,
    matchBy: MatchBy
) -> Type throws (ResolveError) {
    enterScope(self, node);
    let prongTy = try resolveMatchProngBody(self, prongNode, subjectTy, matchBy) catch e {
        exitScope(self);
        throw e;
    };
    exitScope(self);
    setNodeType(self, node, prongTy);

    return unifyBranches(matchType, prongTy);
}

/// Analyze the contents of a `match` prong while inside the prong scope.
fn resolveMatchProngBody(
    self: *mut Resolver,
    prong: ast::MatchProng,
    subjectTy: Type,
    matchBy: MatchBy
) -> Type throws (ResolveError) {
    match prong.arm {
        case ast::ProngArm::Binding(pat) => {
            // For optionals, bind the unwrapped inner type.
            let mut bindTy = subjectTy;
            if let case Type::Optional(inner) = subjectTy {
                bindTy = *inner;
            }
            try bindPatternVar(self, pat, bindTy, matchBy);
        }
        case ast::ProngArm::Case(patterns) => {
            for pattern in patterns {
                try resolveCasePattern(self, pattern, subjectTy, IdentMode::Compare, matchBy);
            }
        }
        case ast::ProngArm::Else => {}
    }
    if let g = prong.guard {
        try checkBoolean(self, g);
    }
    return try visit(self, prong.body, Type::Void);
}

/// Ensure a scope access pattern references a compatible union variant.
fn resolveUnionScopePattern(
    self: *mut Resolver,
    pattern: *ast::Node,
    access: ast::Access,
    subjectTy: Type,
    unionType: UnionType
) throws (ResolveError) {
    let patternTy = try visit(self, pattern, subjectTy);
    if not isComparable(patternTy, subjectTy) {
        throw emitTypeMismatch(self, pattern, TypeMismatch {
            expected: subjectTy,
            actual: patternTy,
        });
    }
    let case NodeExtra::UnionVariant { ordinal: index, .. } = self.nodeData.entries[pattern.id].extra else {
        throw emitError(self, pattern, ErrorKind::Internal);
    };
    let variant = &unionType.variants[index];
    // If this variant has a payload, throw an error, since the user hasn't
    // provided one.
    if variant.valueType != Type::Void {
        throw emitError(self, pattern, ErrorKind::UnionVariantPayloadMissing(variant.name));
    }
}

/// Validate and bind a union constructor call used as a `match` pattern.
fn resolveUnionCallPattern(
    self: *mut Resolver,
    pattern: *ast::Node,
    call: ast::Call,
    subjectTy: Type,
    unionType: UnionType,
    matchBy: MatchBy
) throws (ResolveError) {
    let calleeTy = try checkEqual(self, call.callee, subjectTy);
    let case NodeExtra::UnionVariant { ordinal: index, tag } = self.nodeData.entries[call.callee.id].extra else {
        throw emitError(self, call.callee, ErrorKind::Internal);
    };
    let variant = &unionType.variants[index];
    // Copy variant index to the pattern node for the lowerer.
    setVariantInfo(self, pattern, index, tag);

    if variant.valueType != Type::Void {
        try bindUnionPatternPayload(self, pattern, call, variant.name, variant.valueType, matchBy);
    } else {
        throw emitError(self, pattern, ErrorKind::UnionVariantPayloadUnexpected(variant.name));
    }
}

/// Bind the payload introduced by a union constructor pattern.
fn bindUnionPatternPayload(
    self: *mut Resolver,
    pattern: *ast::Node,
    call: ast::Call,
    variantName: *[u8],
    payloadTy: Type,
    matchBy: MatchBy
) throws (ResolveError) {
    if call.args.len == 0 {
        throw emitError(
            self, pattern, ErrorKind::UnionVariantPayloadMissing(variantName)
        );
    }
    // All variant payloads are records.
    let recInfo = getRecord(payloadTy)
        else panic "bindUnionPatternPayload: payload is not a record";

    try bindRecordPatternFields(self, pattern, recInfo, matchBy);
}

/// Bind a pattern variable. For ref matches, wraps the type in a pointer.
fn bindPatternVar(self: *mut Resolver, binding: *ast::Node, ty: Type, matchBy: MatchBy)
    throws (ResolveError)
{
    let mut bindTy = ty;
    match matchBy {
        case MatchBy::Value => {}
        case MatchBy::Ref => bindTy = Type::Pointer { target: allocType(self, ty), mutable: false },
        case MatchBy::MutRef => bindTy = Type::Pointer { target: allocType(self, ty), mutable: true },
    }
    match binding.value {
        case ast::NodeValue::Placeholder => {
            // Nothing to do.
        }
        case ast::NodeValue::Ident(_) => {
            try bindValueIdent(self, binding, binding, bindTy, false, 0, 0);
        }
        else => {
            // Nested pattern: recursively resolve (record destructuring,
            // union variant, scope access, call, literals, etc).
            try resolveCasePattern(self, binding, ty, IdentMode::Bind, matchBy);
        }
    }
}

/// Bind record pattern fields to variables in the current scope.
fn bindRecordPatternFields(
    self: *mut Resolver,
    pattern: *ast::Node,
    recInfo: RecordType,
    matchBy: MatchBy
) throws (ResolveError) {
    match pattern.value {
        case ast::NodeValue::Call(call) => {
            // Unlabeled patterns: `S(x, y)`.
            try checkRecordArity(self, call.args, recInfo, pattern);

            for binding, i in call.args {
                let fieldType = recInfo.fields[i].fieldType;
                try bindPatternVar(self, binding, fieldType, matchBy);
            }
        }
        case ast::NodeValue::RecordLit(lit) => {
            // Labeled patterns: `T { x, y }` or `T { x: binding }`.
            if not lit.ignoreRest {
                try checkRecordArity(self, lit.fields, recInfo, pattern);
            }
            for fieldNode in lit.fields {
                let case ast::NodeValue::RecordLitField(field) = fieldNode.value
                    else panic "expected RecordLitField";

                // Brace patterns require labeled fields.
                let label = field.label else panic "expected labeled field";
                let fieldName = try nodeName(self, label);
                let fieldIndex = findRecordField(&recInfo, fieldName)
                    else throw emitError(self, fieldNode, ErrorKind::RecordFieldUnknown(fieldName));
                let fieldType = recInfo.fields[fieldIndex].fieldType;
                // Store field index for the lowerer.
                setRecordFieldIndex(self, fieldNode, fieldIndex);
                try bindPatternVar(self, field.value, fieldType, matchBy);
            }
        }
        else => throw emitError(self, pattern, ErrorKind::Internal)
    }
}

/// Validate and bind a record literal pattern for matching labeled union variants.
fn resolveUnionRecordPattern(
    self: *mut Resolver,
    pattern: *ast::Node,
    lit: ast::RecordLit,
    subjectTy: Type,
    unionType: UnionType,
    matchBy: MatchBy
) throws (ResolveError) {
    let typeName = lit.typeName else {
        throw emitError(self, pattern, ErrorKind::Internal);
    };
    // Verify the type matches the subject.
    let patternTy = try visit(self, typeName, subjectTy);
    if not isComparable(patternTy, subjectTy) {
        throw emitTypeMismatch(self, pattern, TypeMismatch {
            expected: subjectTy,
            actual: patternTy,
        });
    }
    let case NodeExtra::UnionVariant { ordinal: index, tag } = self.nodeData.entries[typeName.id].extra else {
        throw emitError(self, typeName, ErrorKind::Internal);
    };
    let variant = &unionType.variants[index];

    // Copy variant index to the pattern node for the lowerer.
    setVariantInfo(self, pattern, index, tag);

    if variant.valueType == Type::Void {
        throw emitError(self, pattern, ErrorKind::UnionVariantPayloadUnexpected(variant.name));
    }
    let recInfo = getRecord(variant.valueType)
        else panic "resolveUnionRecordPattern: payload is not a record";

    try bindRecordPatternFields(self, pattern, recInfo, matchBy);
}

/// Analyze a pattern appearing in a union case.
fn resolveUnionPattern(
    self: *mut Resolver,
    pattern: *ast::Node,
    subjectTy: Type,
    unionType: UnionType,
    matchBy: MatchBy
) throws (ResolveError) {
    match pattern.value {
        case ast::NodeValue::ScopeAccess(access) =>
            try resolveUnionScopePattern(self, pattern, access, subjectTy, unionType),
        case ast::NodeValue::Call(call) =>
            try resolveUnionCallPattern(self, pattern, call, subjectTy, unionType, matchBy),
        case ast::NodeValue::RecordLit(lit) =>
            try resolveUnionRecordPattern(self, pattern, lit, subjectTy, unionType, matchBy),
        else => {
            let patternTy = try visit(self, pattern, subjectTy);
            throw emitTypeMismatch(self, pattern, TypeMismatch {
                expected: subjectTy,
                actual: patternTy,
            });
        }
    }
}

/// Analyze a `let-else` guard.
fn resolveLetElse(self: *mut Resolver, node: *ast::Node, letElse: ast::LetElse) -> Type
    throws (ResolveError)
{
    let pat = &letElse.pattern;
    let exprTy = try infer(self, pat.scrutinee);

    match pat.kind {
        case ast::PatternKind::Binding => {
            // Simple binding requires an optional expression.
            let case Type::Optional(inner) = exprTy else {
                throw emitError(self, pat.scrutinee, ErrorKind::ExpectedOptional);
            };
            let payloadTy = *inner;
            let _ = try bindValueIdent(self, pat.pattern, node, payloadTy, pat.mutable, 0, 0);
            // The `else` branch must be assignable to the payload type.
            try checkAssignable(self, letElse.elseBranch, payloadTy);

            return setNodeType(self, node, Type::Void);
        }
        case ast::PatternKind::Case => {
            // Analyze pattern against expression type.
            try resolveCasePattern(self, pat.pattern, exprTy, IdentMode::Compare, MatchBy::Value);
        }
    }
    if let guardExpr = pat.guard {
        try checkBoolean(self, guardExpr);
    }
    // The `else` branch must be assignable to the expression type.
    try checkAssignable(self, letElse.elseBranch, exprTy);

    return setNodeType(self, node, Type::Void);
}

/// Analyze builtin function calls like `@sizeOf(T)` and `@alignOf(T)`.
fn resolveBuiltinCall(
    self: *mut Resolver,
    node: *ast::Node,
    kind: ast::Builtin,
    args: *mut [*ast::Node]
) -> Type throws (ResolveError) {
    // Handle `@sliceOf(ptr, len)` and `@sliceOf(ptr, len, cap)`.
    if kind == ast::Builtin::SliceOf {
        if args.len != 2 and args.len != 3 {
            throw emitError(self, node, ErrorKind::BuiltinArgCountMismatch(CountMismatch {
                expected: 2,
                actual: args.len as u32,
            }));
        }
        let ptrType = try visit(self, args[0], Type::Unknown);
        let case Type::Pointer { target, mutable } = ptrType else {
            throw emitError(self, node, ErrorKind::ExpectedPointer);
        };
        let _ = try checkAssignable(self, args[1], Type::U32);
        if args.len == 3 {
            let _ = try checkAssignable(self, args[2], Type::U32);
        }
        return setNodeType(self, node, Type::Slice { item: target, mutable });
    }
    if args.len != 1 {
        throw emitError(self, node, ErrorKind::BuiltinArgCountMismatch(CountMismatch {
            expected: 1,
            actual: args.len as u32,
        }));
    }

    let ty = try resolveValueType(self, args[0]);
    // Ensure the type body is resolved before computing layout.
    // TODO: Somehow, ensuring the type is resolved should just happen all
    // the time, lazily.
    try ensureTypeResolved(self, ty, args[0]);
    // TODO: This should be stored in `symbol` instead of having to recompute it.
    // That way there's a canonical place to look for code gen.
    let layout = getTypeLayout(ty);

    // Evaluate the built-in.
    let mut value: u32 = undefined;
    match kind {
        case ast::Builtin::SizeOf => {
            value = layout.size;
        },
        case ast::Builtin::AlignOf => {
            value = layout.alignment;
        },
        case ast::Builtin::SliceOf => {
            panic "unreachable: @sliceOf handled above";
        }
    }
    // Record as constant value for constant folding.
    setNodeConstValue(self, node, ConstValue::Int(ConstInt {
        magnitude: value as u64,
        bits: 32,
        signed: false,
        negative: false,
    }));
    return setNodeType(self, node, Type::U32);
}

/// Validate call arguments against a function type: check argument count,
/// type-check each argument, and verify that throwing functions use `try`.
fn checkCallArgs(self: *mut Resolver, node: *ast::Node, call: ast::Call, info: *FnType, ctx: CallCtx)
    throws (ResolveError)
{
    if ctx == CallCtx::Normal and info.throwList.len > 0 {
        throw emitError(self, node, ErrorKind::MissingTry);
    }
    if call.args.len != info.paramTypes.len as u32 {
        throw emitError(self, node, ErrorKind::FnArgCountMismatch(CountMismatch {
            expected: info.paramTypes.len as u32,
            actual: call.args.len,
        }));
    }
    for argNode, i in call.args {
        let expectedTy = *info.paramTypes[i];

        try checkAssignable(self, argNode, expectedTy);
    }
}

/// Analyze a function call expression.
fn resolveCall(self: *mut Resolver, node: *ast::Node, call: ast::Call, ctx: CallCtx) -> Type
    throws (ResolveError)
{
    // Intercept method calls on slices before inferring the callee.
    if let case ast::NodeValue::FieldAccess(access) = call.callee.value {
        let parentTy = try infer(self, access.parent);
        let subjectTy = autoDeref(parentTy);

        if let case Type::Slice { item, mutable } = subjectTy {
            let methodName = try nodeName(self, access.child);
            if methodName == "append" {
                return try resolveSliceAppend(self, node, access.parent, parentTy, call.args, item, mutable);
            }
            if methodName == "delete" {
                return try resolveSliceDelete(self, node, access.parent, call.args, item, mutable);
            }
        }
    }
    let calleeTy = try infer(self, call.callee);

    // Check if callee is a union variant and dispatch to constructor handler.
    // TODO: Move this out. We should decide on this earlier, based on the callee.
    if let calleeSym = symbolFor(self, call.callee) {
        if let case SymbolData::Variant { decl, .. } = calleeSym.data {
            // TODO: Don't pass the callee type, pass the union type by getting it from
            // the symbol.
            let declSym = symbolFor(self, decl) else panic;
            let case SymbolData::Type(ty) = declSym.data else panic;

            return try resolveUnionConstructorCall(self, node, call, ty);
        }
        // Check if callee is an unlabeled record type for constructor call syntax.
        if let case SymbolData::Type(ty) = calleeSym.data {
            // Ensure the record body is resolved before checking if labeled.
            try ensureNominalResolved(self, ty, call.callee);
            if let case NominalType::Record(recInfo) = *ty {
                if not recInfo.labeled {
                    return try resolveRecordConstructorCall(self, node, call, ty);
                }
            }
        }
    }

    // Check if we have a trait method call, ie. callee is a trait object.
    if let case ast::NodeValue::FieldAccess(access) = call.callee.value {
        let mut parentTy = Type::Unknown;
        if let t = typeFor(self, access.parent) {
            parentTy = t;
        }
        let subjectTy = autoDeref(parentTy);

        if let case Type::TraitObject { traitInfo, mutable: objMutable } = subjectTy {
            let methodName = try nodeName(self, access.child);
            let method = findTraitMethod(traitInfo, methodName)
                else throw emitError(self, access.child, ErrorKind::RecordFieldUnknown(methodName));

            // Reject mutable-receiver methods called on immutable trait objects.
            if method.mutable and not objMutable {
                throw emitError(self, access.parent, ErrorKind::ImmutableBinding);
            }
            try checkCallArgs(self, node, call, method.fnType, ctx);
            setTraitMethodCall(self, node, traitInfo, method.index);

            return setNodeType(self, node, *method.fnType.returnType);
        }

        // Check for a standalone method call on a concrete type.
        if let case Type::Nominal(_) = subjectTy {
            let methodName = try nodeName(self, access.child);
            if let method = findMethod(self, subjectTy, methodName) {
                // Reject mutable-receiver methods on immutable bindings.
                // If the parent is already a mutable pointer, the receiver is fine.
                // Otherwise, check that the parent can yield a mutable borrow.
                if method.mutable {
                    let mut isMutPtr = false;
                    if let case Type::Pointer { mutable, .. } = parentTy {
                        isMutPtr = mutable;
                    }
                    if not isMutPtr and not (try canBorrowMutFrom(self, access.parent)) {
                        throw emitError(self, access.parent, ErrorKind::ImmutableBinding);
                    }
                }
                // Check arguments (excluding receiver).
                try checkCallArgs(self, node, call, method.fnType, ctx);
                self.nodeData.entries[node.id].extra = NodeExtra::MethodCall { method };

                return setNodeType(self, node, *method.fnType.returnType);
            }
        }
    }
    let case Type::Fn(info) = calleeTy else {
        throw emitError(self, call.callee, ErrorKind::TypeMismatch(TypeMismatch {
            expected: Type::Unknown,
            actual: calleeTy,
        }));
    };
    try checkCallArgs(self, node, call, info, ctx);
    // Associate function type to callee.
    setNodeType(self, call.callee, calleeTy);

    // Associate return type to call.
    return setNodeType(self, node, *info.returnType);
}

/// Resolve `slice.append(val, allocator)`.
fn resolveSliceAppend(
    self: *mut Resolver,
    node: *ast::Node,
    parent: *ast::Node,
    parentType: Type,
    args: *mut [*ast::Node],
    elemType: *Type,
    mutable: bool
) -> Type throws (ResolveError) {
    if not mutable {
        throw emitError(self, parent, ErrorKind::ImmutableBinding);
    }
    if args.len != 2 {
        throw emitError(self, node, ErrorKind::FnArgCountMismatch(CountMismatch {
            expected: 2,
            actual: args.len as u32,
        }));
    }
    // First argument must be assignable to the element type.
    try checkAssignable(self, args[0], *elemType);
    // Second argument: the allocator. We accept any type -- the lowerer
    // reads `.func` and `.ctx` at fixed offsets.
    try visit(self, args[1], Type::Unknown);
    self.nodeData.entries[node.id].extra = NodeExtra::SliceAppend { elemType };

    // Return the parent's type so the caller can rebind:
    return setNodeType(self, node, parentType);
}

/// Resolve `slice.delete(index)`.
fn resolveSliceDelete(
    self: *mut Resolver,
    node: *ast::Node,
    parent: *ast::Node,
    args: *mut [*ast::Node],
    elemType: *Type,
    mutable: bool
) -> Type throws (ResolveError) {
    if not mutable {
        throw emitError(self, parent, ErrorKind::ImmutableBinding);
    }
    if args.len != 1 {
        throw emitError(self, node, ErrorKind::FnArgCountMismatch(CountMismatch {
            expected: 1,
            actual: args.len as u32,
        }));
    }
    try checkAssignable(self, args[0], Type::U32);
    self.nodeData.entries[node.id].extra = NodeExtra::SliceDelete { elemType };

    return setNodeType(self, node, Type::Void);
}

/// Analyze an assignment expression.
fn resolveAssign(self: *mut Resolver, node: *ast::Node, assign: ast::Assign) -> Type
    throws (ResolveError)
{
    // Slice assignment: `slice[range] = value`.
    if let case ast::NodeValue::Subscript { container, index } = assign.left.value {
        if let case ast::NodeValue::Range(range) = index.value {
            try infer(self, index);
            let containerTy = try infer(self, container);
            if not try canBorrowMutFrom(self, container) {
                throw emitError(self, container, ErrorKind::ImmutableBinding);
            }
            let subjectTy = autoDeref(containerTy);
            try checkSliceRangeIndices(self, range);

            let mut item: *Type = undefined;
            let mut capacity: ?u32 = nil;

            match subjectTy {
                case Type::Array(a) => {
                    try validateArraySliceBounds(self, range, a.length, node);
                    item = a.item;
                    capacity = a.length;
                }
                case Type::Slice { item: i, mutable } => {
                    if not mutable { throw emitError(self, container, ErrorKind::ImmutableBinding); }
                    item = i;
                }
                else => throw emitError(self, container, ErrorKind::ExpectedIndexable),
            }
            // RHS is either a fill value or a source slice.
            let rhsTy = try infer(self, assign.right);
            if let case Type::Slice { item: srcItem, .. } = rhsTy {
                if *srcItem != *item {
                    throw emitTypeMismatch(self, assign.right, TypeMismatch { expected: *item, actual: *srcItem });
                }
            } else {
                try checkAssignable(self, assign.right, *item);
            }
            setSliceRangeInfo(self, node, SliceRangeInfo { itemType: item, mutable: true, capacity });
            setNodeType(self, assign.left, *item);

            return setNodeType(self, node, Type::Void);
        }
    }
    let leftTy = try infer(self, assign.left);

    // Check if the left-hand side can be assigned to by checking if it's a mutable location.
    if not try canBorrowMutFrom(self, assign.left) {
        throw emitError(self, assign.left, ErrorKind::ImmutableBinding);
    }
    try checkAssignable(self, assign.right, leftTy);

    return setNodeType(self, node, leftTy);
}

/// Ensure slice range bounds are valid `u32` values.
fn checkSliceRangeIndices(self: *mut Resolver, range: ast::Range) throws (ResolveError) {
    if let start = range.start {
        try checkIndex(self, start);
    }
    if let end = range.end {
        try checkIndex(self, end);
    }
}

/// Emit an error when a slice range with compile-tyime values exceeds the array length.
fn validateArraySliceBounds(self: *mut Resolver, range: ast::Range, length: u32, site: *ast::Node) throws (ResolveError) {
    let mut startVal: ?u32 = nil;
    let mut endVal: ?u32 = length;

    if let startNode = range.start {
        if let val = constSliceIndex(self, startNode) {
            startVal = val;
        }
    }
    if let endNode = range.end {
        if let val = constSliceIndex(self, endNode) {
            endVal = val;
        }
    }
    if let val = startVal; val >= length {
        throw emitError(self, site, ErrorKind::SliceRangeOutOfBounds);
    }
    if let val = endVal; val > length {
        throw emitError(self, site, ErrorKind::SliceRangeOutOfBounds);
    }
    if let start = startVal {
        if let end = endVal; start > end {
            throw emitError(self, site, ErrorKind::SliceRangeOutOfBounds);
        }
    }
}

/// Check that an index expression has an unsigned integer type.
/// Accepts `u8`, `u16`, `u32` and unsuffixed integer literals.
/// Smaller types are widened to `u32` via a numeric cast coercion.
fn checkIndex(self: *mut Resolver, indexNode: *ast::Node) throws (ResolveError) {
    let indexTy = try visit(self, indexNode, Type::U32);
    if indexTy == Type::Int or indexTy == Type::U32 {
        let _ = try expectAssignable(self, Type::U32, indexTy, indexNode);
        return;
    }
    match indexTy {
        case Type::U8, Type::U16 => {
            setNodeCoercion(self, indexNode, Coercion::NumericCast {
                from: indexTy, to: Type::U32,
            });
        }
        else => {
            throw emitTypeMismatch(self, indexNode, TypeMismatch {
                expected: Type::U32,
                actual: indexTy,
            });
        }
    }
}

/// Analyze an array or slice subscript expression.
fn resolveSubscript(self: *mut Resolver, node: *ast::Node, container: *ast::Node, indexNode: *ast::Node) -> Type
    throws (ResolveError)
{
    // Range subscripts always require `&` to form a slice.
    if let case ast::NodeValue::Range(range) = indexNode.value {
        let _ = try infer(self, indexNode);
        let _ = try infer(self, container);
        try checkSliceRangeIndices(self, range);
        throw emitError(self, node, ErrorKind::SliceRequiresAddress);
    }
    let containerTy = try infer(self, container);
    try checkIndex(self, indexNode);
    let subjectTy = autoDeref(containerTy);

    match subjectTy {
        case Type::Array(arrayInfo) => {
            return setNodeType(self, node, *arrayInfo.item);
        }
        case Type::Slice { item, .. } => {
            return setNodeType(self, node, *item);
        }
        else => {
            throw emitError(self, container, ErrorKind::ExpectedIndexable);
        }
    }
}

/// Find a record field by name.
fn findRecordField(s: *RecordType, fieldName: *[u8]) -> ?u32 {
    for field, i in s.fields {
        if let name = field.name {
            if name == fieldName {
                return i;
            }
        }
    }
    return nil;
}

/// Analyze a union constructor call with payload.
fn resolveUnionConstructorCall(self: *mut Resolver, node: *ast::Node, call: ast::Call, unionNominal: *NominalType) -> Type
    throws (ResolveError)
{
    // Get the union nominal type.
    let case NominalType::Union(unionType) = *unionNominal
        else panic "resolveUnionConstructorCall: not a union type";

    // Callee was already visited; get the variant index it set.
    let case NodeExtra::UnionVariant { ordinal: index, tag } = self.nodeData.entries[call.callee.id].extra else {
        throw emitError(self, call.callee, ErrorKind::Internal);
    };
    let variant = &unionType.variants[index];

    // Associate variant index with `call` node for the lowerer.
    setVariantInfo(self, node, index, tag);

    // Check if this variant expects a payload.
    let payloadType = variant.valueType;
    if payloadType != Type::Void {
        let recInfo = getRecord(payloadType)
            else panic "resolveUnionVariantConstructor: payload is not a record";
        try checkRecordConstructorArgs(self, node, call.args, recInfo);
    } else {
        if call.args.len > 0 {
            throw emitError(self, node, ErrorKind::UnionVariantPayloadUnexpected(variant.name));
        }
    }
    return setNodeType(self, node, Type::Nominal(unionNominal));
}

/// Analyze an unlabeled record constructor call.
///
/// Handles the syntax `R(a, b)` for unlabeled records, checking that the
/// number of arguments matches the record's field count and that each argument
/// is assignable to its corresponding field type.
fn resolveRecordConstructorCall(self: *mut Resolver, node: *ast::Node, call: ast::Call, recordType: *NominalType) -> Type
    throws (ResolveError)
{
    let case NominalType::Record(recInfo) = *recordType
        else panic "resolveRecordConstructorCall: not a record type";

    try checkRecordConstructorArgs(self, node, call.args, recInfo);
    return setNodeType(self, node, Type::Nominal(recordType));
}

/// Resolve the type name of a record literal, handling both record types and
/// union variant payloads like `Union::Variant { ... }`.
fn resolveRecordLitType(
    self: *mut Resolver, node: *ast::Node, typeIdent: *ast::Node
) -> ResolvedRecordLitType
    throws (ResolveError)
{
    // Check if this is a scope access that might be a union variant.
    if let case ast::NodeValue::ScopeAccess(access) = typeIdent.value {
        let sym = try resolveAccess(self, typeIdent, access, self.scope);

        // Check if resolved symbol is a union variant.
        if let case SymbolData::Variant { type, decl, ordinal, index } = sym.data {
            // Get the union type from the variant's declaration.
            let declSym = symbolFor(self, decl)
                else throw emitError(self, node, ErrorKind::Internal);
            let case SymbolData::Type(unionNominalType) = declSym.data
                else throw emitError(self, node, ErrorKind::Internal);

            // Get the variant's payload type.
            let case Type::Nominal(payloadInfo) = type
                else throw emitError(self, node, ErrorKind::ExpectedRecord);

            // Store the variant index for the lowerer.
            setVariantInfo(self, node, ordinal, index);

            return ResolvedRecordLitType {
                recordType: payloadInfo,
                resultType: Type::Nominal(unionNominalType),
            };
        }
        // Not a variant, must be a type.
        let case SymbolData::Type(ty) = sym.data
            else throw emitError(self, node, ErrorKind::ExpectedRecord);
        return ResolvedRecordLitType {
            recordType: ty,
            resultType: Type::Nominal(ty),
        };
    }
    // Simple identifier, resolve as type name.
    let tyInfo = try resolveTypeName(self, typeIdent);
    return ResolvedRecordLitType {
        recordType: tyInfo,
        resultType: Type::Nominal(tyInfo),
    };
}

/// Analyze a record literal expression.
fn resolveRecordLit(self: *mut Resolver, node: *ast::Node, lit: ast::RecordLit, hint: Type) -> Type
    throws (ResolveError)
{
    // If no type name, infer an anonymous tuple type.
    let typeIdent = lit.typeName else {
        return try resolveAnonRecordLit(self, node, lit, hint);
    };
    // Resolve the type name, handling both record types and union variants.
    let resolved = try resolveRecordLitType(self, node, typeIdent);
    let tyInfo = resolved.recordType;
    let resultType = resolved.resultType;

    // Lazily resolve record body if not yet done.
    try ensureNominalResolved(self, tyInfo, typeIdent);
    let case NominalType::Record(recordType) = *tyInfo
        else throw emitError(self, node, ErrorKind::ExpectedRecord);

    // Unlabeled records must use constructor call syntax `R(...)`, not brace syntax.
    if not recordType.labeled {
        throw emitError(self, node, ErrorKind::RecordFieldStyleMismatch);
    }
    // Check field count. With `{ .. }` syntax, fewer fields are allowed.
    if lit.fields.len > recordType.fields.len {
        throw emitError(self, node, ErrorKind::RecordFieldCountMismatch(CountMismatch {
            expected: recordType.fields.len as u32,
            actual: lit.fields.len,
        }));
    }
    if not lit.ignoreRest and lit.fields.len < recordType.fields.len {
        let missingName = recordType.fields[lit.fields.len].name else panic;
        throw emitError(self, node, ErrorKind::RecordFieldMissing(missingName));
    }

    // Fields must be in declaration order.
    for fieldNode, idx in lit.fields {
        let case ast::NodeValue::RecordLitField(fieldArg) = fieldNode.value
            else panic "resolveRecordLit: expected field node value";
        let label = fieldArg.label
            else panic "resolveRecordLit: expected labeled field";
        let fieldName = try nodeName(self, label);
        let expected = recordType.fields[idx];
        let expectedName = expected.name else panic;

        if fieldName != expectedName {
            throw emitError(self, fieldNode, ErrorKind::RecordFieldOutOfOrder {
                field: fieldName,
                prev: expectedName,
            });
        }
        setRecordFieldIndex(self, fieldNode, idx);
        try checkAssignable(self, fieldArg.value, expected.fieldType);
        setNodeType(self, fieldNode, expected.fieldType);
    }
    return setNodeType(self, node, resultType);
}

/// Analyze an anonymous record literal, checking fields against the hint type.
fn resolveAnonRecordLit(self: *mut Resolver, node: *ast::Node, lit: ast::RecordLit, hint: Type) -> Type
    throws (ResolveError)
{
    // Unwrap optional hint to get the inner record type.
    let mut innerHint = hint;
    if let case Type::Optional(inner) = hint {
        innerHint = *inner;
    }
    let mut hintInfo: ?RecordType = nil;
    if let case Type::Nominal(info) = innerHint {
        try ensureNominalResolved(self, info, node);
        if let case NominalType::Record(s) = *info {
            hintInfo = s;
        }
    }
    let targetInfo = hintInfo else {
        throw emitError(self, node, ErrorKind::CannotInferType);
    };

    // Check field count.
    if lit.fields.len != targetInfo.fields.len {
        if lit.fields.len < targetInfo.fields.len {
            let missingName = targetInfo.fields[lit.fields.len].name else panic;
            throw emitError(self, node, ErrorKind::RecordFieldMissing(missingName));
        } else {
            throw emitError(self, node, ErrorKind::RecordFieldCountMismatch(CountMismatch {
                expected: targetInfo.fields.len as u32,
                actual: lit.fields.len,
            }));
        }
    }

    // Fields must be in declaration order.
    for fieldNode, idx in lit.fields {
        let case ast::NodeValue::RecordLitField(fieldArg) = fieldNode.value
            else panic "resolveAnonRecordLit: expected field node value";
        let label = fieldArg.label
            else panic "resolveAnonRecordLit: expected labeled field";
        let fieldName = try nodeName(self, label);
        let expected = targetInfo.fields[idx];
        let expectedName = expected.name else panic;

        if fieldName != expectedName {
            throw emitError(self, fieldNode, ErrorKind::RecordFieldOutOfOrder {
                field: fieldName,
                prev: expectedName,
            });
        }
        setRecordFieldIndex(self, fieldNode, idx);
        let fieldType = try visit(self, fieldArg.value, expected.fieldType);

        try expectAssignable(self, expected.fieldType, fieldType, fieldArg.value);
        setNodeType(self, fieldNode, fieldType);
    }
    return setNodeType(self, node, innerHint);
}

/// Analyze an array literal expression.
fn resolveArrayLit(self: *mut Resolver, node: *ast::Node, items: *mut [*ast::Node], hint: Type) -> Type
    throws (ResolveError)
{
    let length = items.len;
    let mut expectedTy: Type = Type::Unknown;

    if let case Type::Array(ary) = hint {
        expectedTy = *ary.item;
    } else if let case Type::Optional(inner) = hint {
        if let case Type::Array(ary) = *inner {
            expectedTy = *ary.item;
        }
    };
    for itemNode in items {
        let itemTy = try visit(self, itemNode, expectedTy);
        assert itemTy != Type::Unknown;

        // Set the expected type to the first type we encounter.
        if expectedTy == Type::Unknown {
            expectedTy = itemTy;
        } else {
            try expectAssignable(self, expectedTy, itemTy, itemNode);
        }
    }
    if expectedTy == Type::Unknown {
        throw emitError(self, node, ErrorKind::CannotInferType);
    };
    let arrayTy = Type::Array(ArrayType { item: allocType(self, expectedTy), length });
    return setNodeType(self, node, arrayTy);
}

/// Analyze an array repeat literal expression.
fn resolveArrayRepeat(self: *mut Resolver, node: *ast::Node, lit: ast::ArrayRepeatLit, hint: Type) -> Type
    throws (ResolveError)
{
    let mut itemHint = hint;
    if let case Type::Array(ary) = hint {
        itemHint = *ary.item;
    } else if let case Type::Optional(inner) = hint {
        if let case Type::Array(ary) = *inner {
            itemHint = *ary.item;
        }
    }
    let valueTy = try visit(self, lit.item, itemHint);
    let count = try checkSizeInt(self, lit.count);
    let arrayTy = Type::Array(ArrayType {
        item: allocType(self, valueTy),
        length: count,
    });
    return setNodeType(self, node, arrayTy);
}

/// Resolve union variant access.
fn resolveUnionVariantAccess(
    self: *mut Resolver,
    node: *ast::Node,
    access: ast::Access,
    unionType: UnionType,
    variantName: *[u8]
) -> *mut Symbol throws (ResolveError) {
    // Look up the variant in the union's nominal type.
    for i in 0..unionType.variants.len {
        let variant = &unionType.variants[i];
        if variant.name == variantName {
            let case SymbolData::Variant { ordinal, index, .. } = variant.symbol.data
                else panic "resolveUnionVariantAccess: expected variant symbol";

            // Associate the variant symbol with the child node.
            setNodeSymbol(self, access.child, variant.symbol);
            setNodeSymbol(self, node, variant.symbol);

            // Store the variant index for the lowerer.
            setVariantInfo(self, node, ordinal, index);

            return variant.symbol;
        }
    }
    throw emitError(self, access.child, ErrorKind::UnresolvedSymbol(variantName));
}

/// Analyze a scope access expression.
fn resolveScopeAccess(self: *mut Resolver, node: *ast::Node, access: ast::Access) -> Type
    throws (ResolveError)
{
    let sym = try resolveAccess(self, node, access, self.scope);
    let mut ty: Type = undefined;

    match sym.data {
        case SymbolData::Value { type, .. } => {
            setNodeSymbol(self, node, sym);
            ty = type;
        }
        case SymbolData::Constant { type, value } => {
            // Propagate the constant value.
            if let val = value {
                setNodeConstValue(self, node, val);
            }
            setNodeSymbol(self, node, sym);
            ty = type;
        }
        case SymbolData::Type(t) => {
            setNodeSymbol(self, node, sym);
            ty = Type::Nominal(t);
        }
        case SymbolData::Variant { index, .. } => {
            let ty = typeFor(self, node)
                else throw emitError(self, node, ErrorKind::Internal);
            // For unions without payload, store the variant index as a constant.
            if isVoidUnion(ty) {
                setNodeConstValue(self, node, ConstValue::Int(ConstInt {
                    magnitude: index as u64,
                    bits: 32,
                    signed: false,
                    negative: false,
                }));
            }
            return setNodeType(self, node, ty);
        }
        case SymbolData::Module { .. } => {
            throw emitError(self, node, ErrorKind::UnexpectedModuleName);
        }
        case SymbolData::Trait(_) => { // Trait names are not values.
            throw emitError(self, node, ErrorKind::UnexpectedTraitName);
        }
    }
    return setNodeType(self, node, ty);
}

/// Analyze a field access expression.
fn resolveFieldAccess(self: *mut Resolver, node: *ast::Node, access: ast::Access) -> Type
    throws (ResolveError)
{
    let parentTy = try infer(self, access.parent);
    let subjectTy = autoDeref(parentTy);

    match subjectTy {
        case Type::Nominal(NominalType::Record(recordType)) => {
            let fieldNode = access.child;
            let fieldName = try nodeName(self, fieldNode);
            if let fieldIndex = findRecordField(&recordType, fieldName) {
                let fieldTy = recordType.fields[fieldIndex].fieldType;
                setRecordFieldIndex(self, fieldNode, fieldIndex);
                return setNodeType(self, node, fieldTy);
            }
            // Not a field: check for a standalone method.
            if let method = findMethod(self, subjectTy, fieldName) {
                return setNodeType(self, node, Type::Fn(method.fnType));
            }
            throw emitError(self, node, ErrorKind::RecordFieldUnknown(fieldName));
        }
        case Type::Array(arrayInfo) => {
            let fieldNode = access.child;
            let fieldName = try nodeName(self, fieldNode);

            if mem::eq(fieldName, LEN_FIELD) {
                let lengthConst = constInt(arrayInfo.length as u64, 32, false, false);
                setNodeConstValue(self, node, lengthConst);

                return setNodeType(self, node, Type::U32);
            }
            throw emitError(self, node, ErrorKind::ArrayFieldUnknown(fieldName));
        }
        case Type::Slice { item, mutable } => {
            let fieldNode = access.child;
            let fieldName = try nodeName(self, fieldNode);

            if mem::eq(fieldName, PTR_FIELD) {
                setRecordFieldIndex(self, fieldNode, 0);
                let ptrTy = Type::Pointer {
                    target: item,
                    mutable,
                };
                return setNodeType(self, node, ptrTy);
            }
            if mem::eq(fieldName, LEN_FIELD) {
                setRecordFieldIndex(self, fieldNode, 1);
                return setNodeType(self, node, Type::U32);
            }
            if mem::eq(fieldName, CAP_FIELD) {
                setRecordFieldIndex(self, fieldNode, 2);
                return setNodeType(self, node, Type::U32);
            }
            throw emitError(self, node, ErrorKind::SliceFieldUnknown(fieldName));
        }
        case Type::TraitObject { traitInfo, .. } => {
            let fieldName = try nodeName(self, access.child);
            let method = findTraitMethod(traitInfo, fieldName)
                else throw emitError(self, node, ErrorKind::RecordFieldUnknown(fieldName));

            return setNodeType(self, node, Type::Fn(method.fnType));
        }
        else => {
            // Check for standalone methods on any nominal type (e.g. unions).
            if let case Type::Nominal(_) = subjectTy {
                let fieldName = try nodeName(self, access.child);
                if let method = findMethod(self, subjectTy, fieldName) {
                    return setNodeType(self, node, Type::Fn(method.fnType));
                }
            }
            throw emitError(self, access.parent, ErrorKind::ExpectedRecord);
        }
    }
}

/// Determine whether an expression can yield a mutable location for borrowing.
fn canBorrowMutFrom(self: *mut Resolver, node: *ast::Node) -> bool
    throws (ResolveError)
{
    match node.value {
        case ast::NodeValue::Ident(name) => {
            let sym = findValueSymbol(self.scope, name)
                else return false;
            let case SymbolData::Value { mutable, .. } = sym.data
                else return false;
            // Check if the binding itself is mutable, or if it's a mutable pointer.
            if mutable {
                return true;
            }
            // Check if the type is a mutable pointer or slice.
            let ty = typeFor(self, node) else return false;
            if let case Type::Pointer { mutable, .. } = ty {
                return mutable;
            }
            if let case Type::Slice { mutable, .. } = ty {
                return mutable;
            }
            return false;
        }
        case ast::NodeValue::FieldAccess(access) => {
            let _ = try infer(self, access.parent);
            return try canBorrowMutFrom(self, access.parent);
        }
        case ast::NodeValue::Subscript { container, .. } => {
            let containerTy = try infer(self, container);
            // Subscript auto-derefs pointers, so check the actual indexed type.
            let subjectTy = autoDeref(containerTy);

            if let case Type::Slice { mutable, .. } = subjectTy {
                return mutable;
            }
            if let case Type::Array(_) = subjectTy {
                return try canBorrowMutFrom(self, container);
            }
            return false;
        }
        case ast::NodeValue::ArrayLit(_),
             ast::NodeValue::ArrayRepeatLit(_) =>
        {
            return true;
        }
        case ast::NodeValue::Deref(inner) => {
            let innerTy = try infer(self, inner);

            if let case Type::Pointer { mutable, .. } = innerTy {
                return mutable;
            }
            if let case Type::Slice { mutable, .. } = innerTy {
                return mutable;
            }
            // Record deref: mutability depends on the inner binding.
            if let case Type::Nominal(NominalType::Record(recInfo)) = innerTy {
                if not recInfo.labeled and recInfo.fields.len == 1 {
                    return try canBorrowMutFrom(self, inner);
                }
            }
            return false;
        }
        else => {
            return false;
        }
    }
}

/// Analyze an address-of expression.
fn resolveAddressOf(self: *mut Resolver, node: *ast::Node, addr: ast::AddressOf, hint: Type) -> Type
    throws (ResolveError)
{
    if addr.mutable {
        if not try canBorrowMutFrom(self, addr.target) {
            throw emitError(self, addr.target, ErrorKind::ImmutableBinding);
        }
    }
    if let case ast::NodeValue::Subscript { container, index } = addr.target.value {
        if let case ast::NodeValue::Range(range) = index.value {
            let containerTy = try infer(self, container);
            let subjectTy = autoDeref(containerTy);

            try checkSliceRangeIndices(self, range);

            let mut item: *Type = undefined;
            let mut capacity: ?u32 = nil;

            match subjectTy {
                case Type::Array(arrayInfo) => {
                    try validateArraySliceBounds(self, range, arrayInfo.length, node);
                    item = arrayInfo.item;
                    capacity = arrayInfo.length;
                }
                case Type::Slice { item: sliceItem, mutable } => {
                    if addr.mutable and not mutable {
                        throw emitError(self, addr.target, ErrorKind::ImmutableBinding);
                    }
                    item = sliceItem;
                }
                else => {
                    throw emitError(self, container, ErrorKind::ExpectedIndexable);
                }
            }
            let sliceTy = Type::Slice { item, mutable: addr.mutable };
            let alloc = allocType(self, sliceTy);
            setSliceRangeInfo(self, node, SliceRangeInfo {
                itemType: item,
                mutable: addr.mutable,
                capacity,
            });
            setNodeType(self, addr.target, *alloc);
            return setNodeType(self, node, *alloc);
        }
    }
    // Derive a hint for the target type from the slice hint.
    let mut targetHint: Type = Type::Unknown;
    if let case Type::Slice { item, .. } = hint {
        targetHint = Type::Array(ArrayType { item, length: 0 });
    }
    let targetTy = try visit(self, addr.target, targetHint);

    // Mark local variable symbols as address-taken so the lowerer
    // allocates a stack slot eagerly.
    if let case ast::NodeValue::Ident(name) = addr.target.value {
        if let sym = findValueSymbol(self.scope, name) {
            match &mut sym.data {
                case SymbolData::Value { addressTaken, .. } => {
                    *addressTaken = true;
                }
                else => {}
            }
        }
    }

    if let case Type::Array(arrayInfo) = targetTy {
        match addr.target.value {
            case ast::NodeValue::ArrayLit(_),
                 ast::NodeValue::ArrayRepeatLit(_) =>
            {
                let sliceTy = Type::Slice {
                    item: arrayInfo.item,
                    mutable: addr.mutable,
                };
                return setNodeType(self, node, *allocType(self, sliceTy));
            }
            else => {}
        }
    }
    let pointerTy = Type::Pointer {
        target: allocType(self, targetTy),
        mutable: addr.mutable,
    };
    return setNodeType(self, node, pointerTy);
}

/// Analyze a dereference expression.
fn resolveDeref(self: *mut Resolver, node: *ast::Node, targetNode: *ast::Node, hint: Type) -> Type
    throws (ResolveError)
{
    let operandTy = try visit(self, targetNode, hint);
    if let case Type::Pointer { target, .. } = operandTy {
        // Disallow dereferencing opaque pointers.
        if *target == Type::Opaque {
            throw emitError(self, targetNode, ErrorKind::OpaqueTypeDeref);
        }
        return setNodeType(self, node, *target);
    }
    // Auto-deref for single-field unlabeled records.
    if let case Type::Nominal(NominalType::Record(recInfo)) = operandTy {
        if not recInfo.labeled and recInfo.fields.len == 1 {
            let fieldTy = recInfo.fields[0].fieldType;
            setRecordFieldIndex(self, node, 0);
            return setNodeType(self, node, fieldTy);
        }
    }
    throw emitError(self, targetNode, ErrorKind::ExpectedPointer);
}

/// Check if a type is a pointer to opaque.
fn isOpaquePointer(ty: Type) -> bool {
    if let case Type::Pointer { target, .. } = ty {
        return *target == Type::Opaque;
    }
    return false;
}

/// Check if a type is an opaque slice.
fn isOpaqueSlice(ty: Type) -> bool {
    if let case Type::Slice { item, .. } = ty {
        return *item == Type::Opaque;
    }
    return false;
}

/// Check if an `as` cast between two types is valid.
fn isValidCast(source: Type, target: Type) -> bool {
    // Allow identity casts.
    if source == target {
        return true;
    }
    // Allow numeric to numeric.
    if isNumericType(source) and isNumericType(target) {
        return true;
    }
    // Allow `void` union to numeric.
    // TODO: Check that variant index fits in target type.
    if isVoidUnion(source) and isNumericType(target) {
        return true;
    }
    // Allow address to numeric.
    if let case Type::Slice { .. } = source {
        // Disallow slice to numeric; slices are fat pointers.
    } else if isAddressType(source) and isNumericType(target) {
        return true;
    }
    // Allow numeric to pointer (requires unsafe context; checked in resolveAs).
    if isNumericType(source) {
        if let case Type::Pointer { .. } = target {
            return true;
        }
    }
    // Allow pointer casts if one side is `*opaque` or target types are castable.
    if let case Type::Pointer { target: sourceTarget, .. } = source {
        if let case Type::Pointer { target: targetTarget, .. } = target {
            if isOpaquePointer(source) or isOpaquePointer(target) {
                return true;
            }
            return isValidCast(*sourceTarget, *targetTarget);
        }
    }
    // Allow slice casts if one side is `*[opaque]`, target is `*[u8]`,
    // or element types are castable.
    if let case Type::Slice { item: sourceItem, .. } = source {
        if let case Type::Slice { item: targetItem, .. } = target {
            if isOpaqueSlice(source) or isOpaqueSlice(target) {
                return true;
            }
            if *targetItem == Type::U8 {
                return true;
            }
            return isValidCast(*sourceItem, *targetItem);
        }
    }
    return false;
}

/// Analyze an `as` cast expression.
fn resolveAs(self: *mut Resolver, node: *ast::Node, expr: ast::As) -> Type
    throws (ResolveError)
{
    let targetTy = try infer(self, expr.type);
    let sourceTy = try visit(self, expr.value, targetTy);

    assert sourceTy != Type::Unknown;
    assert targetTy != Type::Unknown;

    if isValidCast(sourceTy, targetTy) {
        // Integer-to-pointer cast requires unsafe context.
        if isNumericType(sourceTy) {
            if let case Type::Pointer { .. } = targetTy {
                if self.unsafeDepth == 0 {
                    throw emitError(self, node, ErrorKind::UnsafeRequired);
                }
            }
        }
        // TODO: Opaque pointer casts (*opaque as *T) should require unsafe
        // context, since they assert the pointer is valid for the target type.
        // Currently exempted because the allocator returns *opaque and every
        // allocation site does `alloc() as *mut T`. This will be resolved
        // when generics allow the allocator to return *mut T directly.
        // Propagate constant value through the cast, adjusting integer
        // metadata to match the target type.
        if let value = constValueEntry(self, expr.value) {
            if let case ConstValue::Int(i) = value {
                if let range = integerRange(targetTy) {
                    match range {
                        case IntegerRange::Signed { bits, .. } =>
                            setNodeConstValue(self, node, constInt(i.magnitude, bits, true, i.negative)),
                        case IntegerRange::Unsigned { bits, .. } =>
                            setNodeConstValue(self, node, constInt(i.magnitude, bits, false, false)),
                    }
                }
            }
        }
        return setNodeType(self, node, targetTy);
    }
    throw emitError(self, node, ErrorKind::InvalidAsCast(InvalidAsCast {
        from: sourceTy,
        to: targetTy,
    }));
}

/// Analyze a range expression.
fn resolveRange(self: *mut Resolver, node: *ast::Node, range: ast::Range) -> Type
    throws (ResolveError)
{
    let mut start: ?*Type = nil;
    let mut end: ?*Type = nil;

    if let s = range.start {
        let startTy = try checkNumeric(self, s);

        if let e = range.end {
            let endTy = try checkNumeric(self, e);
            let mut resolvedTy = startTy;

            // Infer unsuffixed integer literals from the opposite bound.
            if startTy == Type::Int and endTy != Type::Int {
                let _ = try checkAssignable(self, s, endTy);
                resolvedTy = endTy;
            } else if endTy == Type::Int and startTy != Type::Int {
                let _ = try checkAssignable(self, e, startTy);
                resolvedTy = startTy;
            } else {
                let _ = try checkAssignable(self, e, startTy);
            }
            start = allocType(self, resolvedTy);
            end = allocType(self, resolvedTy);
        } else {
            start = allocType(self, startTy);
        }
    } else if let e = range.end {
        end = allocType(self, try checkNumeric(self, e));
    }
    return setNodeType(self, node, Type::Range { start, end });
}

/// Analyze a `try` expression and its handlers.
/// The `expected` type is used to determine if the value is discarded (`Void`)
/// or if the catch expression needs type checking.
fn resolveTry(self: *mut Resolver, node: *ast::Node, tryExpr: ast::Try, hint: Type) -> Type
    throws (ResolveError)
{
    let call = tryExpr.expr;
    let case ast::NodeValue::Call(callExpr) = call.value
        else throw emitError(self, call, ErrorKind::TryNonThrowing);
    let resultTy = try resolveCall(self, call, callExpr, CallCtx::Try);

    // TODO: It's annoying that we need to re-fetch the function type after
    // analyzing the call.
    let calleeTy = typeFor(self, callExpr.callee)
        else return setNodeType(self, node, resultTy);
    let case Type::Fn(calleeInfo) = calleeTy
        else throw emitError(self, callExpr.callee, ErrorKind::TryNonThrowing);

    if calleeInfo.throwList.len == 0 {
        throw emitError(self, callExpr.callee, ErrorKind::TryNonThrowing);
    }
    // If we're not catching the error, nor panicking on error, nor returning
    // optional, then the current function must be able to propagate it.
    let mut tryResultTy = resultTy;
    if tryExpr.returnsOptional {
        // `try?` converts errors to `nil` and wraps the result in an optional.
        if let case Type::Optional(_) = resultTy {
            // Already optional, no wrapping needed.
        } else {
            tryResultTy = Type::Optional(allocType(self, resultTy));
        }
    } else if tryExpr.catches.len > 0 {
        // `try ... catch` -- one or more catch clauses.
        tryResultTy = try resolveTryCatches(self, node, tryExpr.catches, calleeInfo, resultTy, hint);
    } else if not tryExpr.shouldPanic {
        let fnInfo = self.currentFn
            else throw emitError(self, node, ErrorKind::TryRequiresThrows);
        if fnInfo.throwList.len == 0 {
            throw emitError(self, node, ErrorKind::TryRequiresThrows);
        }
        // Check that *all* thrown errors of the callee can be propagated by
        // the caller.
        for throwTy in calleeInfo.throwList {
            let mut found = false;

            for callerThrowTy in fnInfo.throwList {
                if callerThrowTy == throwTy {
                    found = true;
                    break;
                }
            }
            if not found {
                throw emitError(self, node, ErrorKind::TryIncompatibleError);
            }
        }
    }
    return setNodeType(self, node, tryResultTy);
}

/// Check that a `catch` body is assignable to the expected result type, but only
/// in expression context (`hint` is neither `Unknown` nor `Void`).
fn checkCatchBody(self: *mut Resolver, body: *ast::Node, resultTy: Type, hint: Type)
    throws (ResolveError)
{
    if hint != Type::Unknown and hint != Type::Void {
        try checkAssignable(self, body, resultTy);
    }
}

/// Resolve catch clauses for a `try ... catch` expression.
///
/// For a single untyped catch (with or without binding), resolves the catch
/// body and returns the result type. Multi-error callees with inferred bindings
/// are rejected; you must use typed catches.
fn resolveTryCatches(
    self: *mut Resolver,
    node: *ast::Node,
    catches: *mut [*ast::Node],
    calleeInfo: *FnType,
    resultTy: Type,
    hint: Type
) -> Type throws (ResolveError) {
    let firstNode = catches[0];
    let case ast::NodeValue::CatchClause(first) = firstNode.value else
        throw emitError(self, node, ErrorKind::UnexpectedNode(firstNode));

    // Typed catches: dispatch to dedicated handler.
    if first.typeNode != nil {
        return try resolveTypedCatches(self, node, catches, calleeInfo, resultTy, hint);
    }
    // Single untyped catch clause.
    if let binding = first.binding {
        if calleeInfo.throwList.len > 1 {
            throw emitError(self, binding, ErrorKind::TryCatchMultiError);
        }
        enterScope(self, node);

        let errTy = *calleeInfo.throwList[0];
        try bindValueIdent(self, binding, binding, errTy, false, 0, 0);
    }
    try visit(self, first.body, resultTy);

    if let _ = first.binding {
        exitScope(self);
    }
    try checkCatchBody(self, first.body, resultTy, hint);

    return resultTy;
}

/// Resolve typed catch clauses (`catch e as T {..} catch e as S {..}`).
///
/// Validates that each type annotation is in the callee's throw list, that
/// there are no duplicate catch types, and that the clauses are exhaustive.
fn resolveTypedCatches(
    self: *mut Resolver,
    node: *ast::Node,
    catches: *mut [*ast::Node],
    calleeInfo: *FnType,
    resultTy: Type,
    hint: Type
) -> Type throws (ResolveError) {
    // Track which of the callee's throw types have been covered.
    let mut covered: [bool; MAX_FN_THROWS] = [false; MAX_FN_THROWS];
    let mut hasCatchAll = false;

    for clauseNode in catches {
        let case ast::NodeValue::CatchClause(clause) = clauseNode.value else
            throw emitError(self, node, ErrorKind::UnexpectedNode(clauseNode));

        if let typeNode = clause.typeNode {
            // Typed catch clause: validate against callee's throw list.
            let errTy = try infer(self, typeNode);
            let mut foundIdx: ?u32 = nil;

            for throwType, j in calleeInfo.throwList {
                if errTy == *throwType {
                    foundIdx = j;
                    break;
                }
            }
            let idx = foundIdx else {
                throw emitError(self, typeNode, ErrorKind::TryIncompatibleError);
            };
            if covered[idx] {
                throw emitError(self, typeNode, ErrorKind::TryCatchDuplicateType);
            }
            covered[idx] = true;

            // Bind the error variable if present.
            if let binding = clause.binding {
                enterScope(self, clauseNode);
                try bindValueIdent(self, binding, binding, errTy, false, 0, 0);
            }
        } else {
            // Catch-all clause with no type annotation or binding.
            hasCatchAll = true;
        }
        // Resolve the catch body and check assignability.
        try visit(self, clause.body, resultTy);
        // Only typed clauses can have bindings.
        if let _ = clause.binding {
            exitScope(self);
        }
        try checkCatchBody(self, clause.body, resultTy, hint);
    }

    // Check exhaustiveness: all callee error types must be covered.
    if not hasCatchAll {
        for i in 0..calleeInfo.throwList.len {
            if not covered[i] {
                throw emitError(self, node, ErrorKind::TryCatchNonExhaustive);
            }
        }
    }
    return resultTy;
}

/// Analyze a `throw` statement.
fn resolveThrow(self: *mut Resolver, node: *ast::Node, expr: *ast::Node) -> Type
    throws (ResolveError)
{
    let fnInfo = self.currentFn
        else throw emitError(self, node, ErrorKind::ThrowRequiresThrows);
    if fnInfo.throwList.len == 0 {
        throw emitError(self, node, ErrorKind::ThrowRequiresThrows);
    }
    let throwTy = try infer(self, expr);
    for errTy in fnInfo.throwList {
        if let coerce = isAssignable(self, *errTy, throwTy, expr) {
            setNodeCoercion(self, expr, coerce);
            return setNodeType(self, node, Type::Never);
        }
    }
    throw emitError(self, expr, ErrorKind::ThrowIncompatibleError);
}

/// Analyze a `return` statement.
fn resolveReturn(self: *mut Resolver, node: *ast::Node, retVal: ?*ast::Node) -> Type
    throws (ResolveError)
{
    let f = self.currentFn
        else throw emitError(self, node, ErrorKind::UnexpectedReturn);
    let expected = *f.returnType;

    if let val = retVal {
        let _actualTy = try checkAssignable(self, val, expected);
    } else if expected != Type::Void {
        throw emitTypeMismatch(self, node, TypeMismatch { expected, actual: Type::Void });
    }
    // In throwing functions, return values are wrapped in the success variant.
    if f.throwList.len > 0 {
        setNodeCoercion(self, node, Coercion::ResultWrap);
    }
    return setNodeType(self, node, Type::Never);
}

/// Convert a [`ConstInt`] to its signed two's-complement representation.
fn constIntToSigned(c: ConstInt) -> i64 {
    if c.negative {
        return -(c.magnitude as i64);
    }
    return c.magnitude as i64;
}

/// Build a [`ConstInt`] from a signed result, preserving bit width and signedness.
fn constIntFromSigned(value: i64, bits: u8, signed: bool) -> ConstInt {
    if value < 0 {
        // Compute magnitude without signed overflow.
        let uval = value as u64;
        return ConstInt {
            magnitude: 0 - uval,
            bits,
            signed,
            negative: true,
        };
    }
    return ConstInt {
        magnitude: value as u64,
        bits,
        signed,
        negative: false,
    };
}

/// Try to fold a binary operation on two integer constants.
/// Returns the resulting constant value if successful.
fn foldIntBinOp(op: ast::BinaryOp, left: ConstInt, right: ConstInt) -> ?ConstValue {
    // Use the wider bit width and propagate signedness.
    let mut bits = left.bits;
    if right.bits > bits {
        bits = right.bits;
    }
    let signed = left.signed or right.signed;
    let l = constIntToSigned(left);
    let r = constIntToSigned(right);

    match op {
        // Shifts operate on unsigned magnitudes directly.
        case ast::BinaryOp::Shl => {
            return ConstValue::Int(ConstInt {
                magnitude: left.magnitude << right.magnitude, bits, signed, negative: left.negative,
            });
        },
        case ast::BinaryOp::Shr => {
            return ConstValue::Int(ConstInt {
                magnitude: left.magnitude >> right.magnitude, bits, signed, negative: left.negative,
            });
        },
        case ast::BinaryOp::Eq  => return ConstValue::Bool(l == r),
        case ast::BinaryOp::Ne  => return ConstValue::Bool(l != r),
        case ast::BinaryOp::Lt  => return ConstValue::Bool(l < r),
        case ast::BinaryOp::Gt  => return ConstValue::Bool(l > r),
        case ast::BinaryOp::Lte => return ConstValue::Bool(l <= r),
        case ast::BinaryOp::Gte => return ConstValue::Bool(l >= r),
        case ast::BinaryOp::Add => return ConstValue::Int(constIntFromSigned(l + r, bits, signed)),
        case ast::BinaryOp::Sub => return ConstValue::Int(constIntFromSigned(l - r, bits, signed)),
        case ast::BinaryOp::Mul => return ConstValue::Int(constIntFromSigned(l * r, bits, signed)),
        case ast::BinaryOp::Div => {
            if r == 0 {
                return nil;
            }
            return ConstValue::Int(constIntFromSigned(l / r, bits, signed));
        },
        case ast::BinaryOp::Mod => {
            if r == 0 {
                return nil;
            }
            return ConstValue::Int(constIntFromSigned(l % r, bits, signed));
        },
        case ast::BinaryOp::BitAnd => return ConstValue::Int(constIntFromSigned(l & r, bits, signed)),
        case ast::BinaryOp::BitOr  => return ConstValue::Int(constIntFromSigned(l | r, bits, signed)),
        case ast::BinaryOp::BitXor => return ConstValue::Int(constIntFromSigned(l ^ r, bits, signed)),
        else => return nil,
    }
}

/// Try to constant-fold a binary operation on two resolved operands.
/// Only folds when the result type is concrete.
fn tryFoldBinOp(self: *mut Resolver, node: *ast::Node, binop: ast::BinOp, resultTy: Type) {
    let leftVal = constValueEntry(self, binop.left)
        else return;
    let rightVal = constValueEntry(self, binop.right)
        else return;

    // Fold integer binary ops.
    if let case ConstValue::Int(leftInt) = leftVal {
        if let case ConstValue::Int(rightInt) = rightVal {
            if let result = foldIntBinOp(binop.op, leftInt, rightInt) {
                setNodeConstValue(self, node, result);
            }
            return;
        }
    }

    // Fold boolean binary ops.
    if let case ConstValue::Bool(l) = leftVal {
        if let case ConstValue::Bool(r) = rightVal {
            match binop.op {
                case ast::BinaryOp::And => setNodeConstValue(self, node, ConstValue::Bool(l and r)),
                case ast::BinaryOp::Or => setNodeConstValue(self, node, ConstValue::Bool(l or r)),
                case ast::BinaryOp::Eq => setNodeConstValue(self, node, ConstValue::Bool(l == r)),
                case ast::BinaryOp::Ne,
                     ast::BinaryOp::Xor => setNodeConstValue(self, node, ConstValue::Bool(l != r)),
                else => {}
            }
        }
    }
}

/// Analyze a binary expression.
fn resolveBinOp(self: *mut Resolver, node: *ast::Node, binop: ast::BinOp) -> Type
    throws (ResolveError)
{
    let mut resultTy = Type::Unknown;

    match binop.op {
        case ast::BinaryOp::And,
             ast::BinaryOp::Or,
             ast::BinaryOp::Xor =>
        {
            try checkBoolean(self, binop.left);
            try checkBoolean(self, binop.right);

            resultTy = Type::Bool;
        },
        case ast::BinaryOp::Eq,
             ast::BinaryOp::Ne =>
        {
            let leftTy = try infer(self, binop.left);
            let rightTy = try visit(self, binop.right, leftTy);

            if not isComparable(leftTy, rightTy) {
                throw emitTypeMismatch(self, binop.right, TypeMismatch {
                    expected: leftTy,
                    actual: rightTy,
                });
            }
            // When comparing `T == ?T`, record a coercion on the
            // non-optional side so the lowerer lifts it before comparing.
            // We use the already-optional type from the other side rather than
            // constructing a new optional, so that e.g. `?u8 == 42` coerces
            // `42` to `?u8` (not `?i32`). We also record OptionalLift directly
            // rather than using expectAssignable, because comparisons should
            // allow e.g. `?*mut T == *T` where mutability differs.
            if let case Type::Optional(_) = leftTy {
                if not isOptionalType(rightTy) {
                    setNodeCoercion(self, binop.right, Coercion::OptionalLift(leftTy));
                }
            } else if let case Type::Optional(_) = rightTy {
                setNodeCoercion(self, binop.left, Coercion::OptionalLift(rightTy));
            }
            resultTy = Type::Bool;
        },
        else => {
            // Check for pointer arithmetic before numeric check.
            if binop.op == ast::BinaryOp::Add or binop.op == ast::BinaryOp::Sub {
                let leftTy = try infer(self, binop.left);
                let rightTy = try visit(self, binop.right, leftTy);

                // Disallow pointer arithmetic on opaque pointers.
                if let case Type::Pointer { target: leftTarget, .. } = leftTy; *leftTarget == Type::Opaque {
                    throw emitError(self, node, ErrorKind::OpaquePointerArithmetic);
                }
                if let case Type::Pointer { target: rightTarget, .. } = rightTy; *rightTarget == Type::Opaque {
                    throw emitError(self, node, ErrorKind::OpaquePointerArithmetic);
                }
                // Allow pointer plus integer or integer plus pointer.
                if let case Type::Pointer { .. } = leftTy; isNumericType(rightTy) {
                    return setNodeType(self, node, leftTy);
                }
                if binop.op == ast::BinaryOp::Add {
                    if let case Type::Pointer { .. } = rightTy; isNumericType(leftTy) {
                        return setNodeType(self, node, rightTy);
                    }
                }
            }
            let leftTy = try checkNumeric(self, binop.left);
            let rightTy = try checkNumeric(self, binop.right);

            // Ordering comparisons return `bool`, not the operand type.
            match binop.op {
                case ast::BinaryOp::Lt, ast::BinaryOp::Gt,
                     ast::BinaryOp::Lte, ast::BinaryOp::Gte => {
                    resultTy = Type::Bool;
                } else => {
                    if leftTy == rightTy {
                        resultTy = leftTy;
                    } else if leftTy == Type::Int {
                        resultTy = rightTy;
                    } else if rightTy == Type::Int {
                        resultTy = leftTy;
                    } else {
                        throw emitTypeMismatch(self, binop.right, TypeMismatch {
                            expected: leftTy,
                            actual: rightTy,
                        });
                    }
                }
            }

        }
    };
    // Try constant folding after both operands are resolved.
    tryFoldBinOp(self, node, binop, resultTy);

    return setNodeType(self, node, resultTy);
}

/// Analyze a unary expression.
fn resolveUnOp(self: *mut Resolver, node: *ast::Node, unop: ast::UnOp) -> Type
    throws (ResolveError)
{
    let mut resultTy = Type::Unknown;

    match unop.op {
        case ast::UnaryOp::Not => {
            resultTy = try checkBoolean(self, unop.value);
            if let value = constValueEntry(self, unop.value) {
                if let case ConstValue::Bool(val) = value {
                    setNodeConstValue(self, node, ConstValue::Bool(not val));
                }
            }
        },
        case ast::UnaryOp::Neg => {
            // TODO: Check that we're allowed to use `-` here? Should negation
            // only be valid for signed integers?
            resultTy = try checkNumeric(self, unop.value);
            if let value = constValueEntry(self, unop.value) {
                // Get the constant expression for the value, flip the sign,
                // and store that new expression on the unary op node.
                if let case ConstValue::Int(intVal) = value {
                    setNodeConstValue(
                        self,
                        node,
                        constInt(intVal.magnitude, intVal.bits, true, not intVal.negative)
                    );
                }
            }
        },
        case ast::UnaryOp::BitNot => {
            resultTy = try checkNumeric(self, unop.value);
            if let value = constValueEntry(self, unop.value) {
                if let case ConstValue::Int(intVal) = value {
                    let signed = constIntToSigned(intVal);
                    let inverted = constIntFromSigned(-(signed + 1), intVal.bits, intVal.signed);
                    setNodeConstValue(self, node, ConstValue::Int(inverted));
                }
            }
        },
    };
    return setNodeType(self, node, resultTy);
}

/// Resolve a type signature node and set its type.
fn inferTypeSig(self: *mut Resolver, node: *ast::Node, sig: ast::TypeSig) -> Type
    throws (ResolveError)
{
    let resolved = try resolveTypeSig(self, node, sig);

    return setNodeType(self, node, resolved);
}

/// Convert a type signature node into a type value.
fn resolveTypeSig(self: *mut Resolver, node: *ast::Node, sig: ast::TypeSig) -> Type
    throws (ResolveError)
{
    match sig {
        case ast::TypeSig::Void => {
            return Type::Void;
        }
        case ast::TypeSig::Opaque => {
            return Type::Opaque;
        }
        case ast::TypeSig::Bool => {
            return Type::Bool;
        }
        case ast::TypeSig::Integer { width, sign } => {
            let u = sign == ast::Signedness::Unsigned;
            match width {
                case 1 => return Type::U8 if u else Type::I8,
                case 2 => return Type::U16 if u else Type::I16,
                case 4 => return Type::U32 if u else Type::I32,
                case 8 => return Type::U64 if u else Type::I64,
                else => {
                    panic "resolveTypeSig: invalid integer width";
                }
            }
        }
        case ast::TypeSig::Array { itemType, length } => {
            let item = try infer(self, itemType);
            let length = try checkSizeInt(self, length);

            return Type::Array(ArrayType { item: allocType(self, item), length });
        }
        case ast::TypeSig::Slice { itemType, mutable } => {
            let item = try infer(self, itemType);
            return Type::Slice {
                item: allocType(self, item),
                mutable,
            };
        }
        case ast::TypeSig::Pointer { valueType, mutable } => {
            let target = try infer(self, valueType);
            return Type::Pointer {
                target: allocType(self, target),
                mutable,
            };
        }
        case ast::TypeSig::Optional { valueType } => {
            let payload = try infer(self, valueType);
            return Type::Optional(allocType(self, payload));
        }
        case ast::TypeSig::Nominal(name) => {
            let ty = try resolveTypeName(self, name);
            return Type::Nominal(ty);
        }
        case ast::TypeSig::Record { fields, labeled } => {
            let recordType = try resolveRecordFields(self, node, fields, labeled);
            let nominalTy = allocNominalType(self, NominalType::Record(recordType));
            return Type::Nominal(nominalTy);
        }
        case ast::TypeSig::Fn(t) => {
            let a = alloc::arenaAllocator(&mut self.arena);
            let mut paramTypes: *mut [*Type] = &mut [];
            let mut throwList: *mut [*Type] = &mut [];

            if t.params.len > MAX_FN_PARAMS {
                throw emitError(self, node, ErrorKind::FnParamOverflow(CountMismatch {
                    expected: MAX_FN_PARAMS,
                    actual: t.params.len,
                }));
            }
            if t.throwList.len > MAX_FN_THROWS {
                throw emitError(self, node, ErrorKind::FnThrowOverflow(CountMismatch {
                    expected: MAX_FN_THROWS,
                    actual: t.throwList.len,
                }));
            }

            for paramNode in t.params {
                let paramTy = try infer(self, paramNode);
                paramTypes.append(allocType(self, paramTy), a);
            }
            for tyNode in t.throwList {
                let throwTy = try infer(self, tyNode);
                throwList.append(allocType(self, throwTy), a);
            }
            let mut retType = allocType(self, Type::Void);
            if let ret = t.returnType {
                retType = allocType(self, try infer(self, ret));
            }
            let fnType = FnType {
                paramTypes: &paramTypes[..],
                returnType: retType,
                throwList: &throwList[..],
                localCount: 0,
                isUnsafe: false,
            };
            return Type::Fn(allocFnType(self, fnType));
        }
        case ast::TypeSig::TraitObject { traitName, mutable } => {
            let sym = try resolveNamePath(self, traitName);
            let case SymbolData::Trait(traitInfo) = sym.data
                else throw emitError(self, traitName, ErrorKind::Internal);
            setNodeSymbol(self, traitName, sym);

            return Type::TraitObject { traitInfo, mutable };
        }
    }
}

/// Check if a type can be used for inferrence.
fn isTypeInferrable(type: Type) -> bool {
    match type {
        case Type::Unknown, Type::Nil, Type::Undefined, Type::Int => return false,
        case Type::Array(ary) => return isTypeInferrable(*ary.item),
        case Type::Optional(opt) => return isTypeInferrable(*opt),
        case Type::Pointer { target, .. } => return isTypeInferrable(*target),
        else => return true,
    }
}

/// Analyze a standalone expression by wrapping it in a synthetic function.
pub fn resolveExpr(
    self: *mut Resolver, expr: *ast::Node, arena: *mut ast::NodeArena
) -> Diagnostics throws (ResolveError) {
    let a = alloc::arenaAllocator(&mut arena.arena);
    let exprStmt = ast::synthNode(arena, ast::NodeValue::ExprStmt(expr));
    let bodyStmts = ast::nodeSlice(arena, 1).append(exprStmt, a);
    let module = ast::synthFnModule(arena, ANALYZE_EXPR_FN_NAME, bodyStmts);

    let case ast::NodeValue::Block(block) = module.modBody.value
        else panic "resolveExpr: expected block for module body";
    enterScope(self, module.modBody);
    try resolveModuleDecls(self, &block) catch {
        return Diagnostics { errors: self.errors };
    };
    try resolveModuleDefs(self, &block) catch {
        return Diagnostics { errors: self.errors };
    };
    exitScope(self);

    return Diagnostics { errors: self.errors };
}

/// Analyze a parsed module root, ie. a block of top-level statements.
pub fn resolveModuleRoot(self: *mut Resolver, root: *ast::Node) -> Diagnostics throws (ResolveError) {
    let case ast::NodeValue::Block(block) = root.value
        else panic "resolveModuleRoot: expected block for module root";

    enterScope(self, root);
    try resolveModuleDecls(self, &block) catch {
        return Diagnostics { errors: self.errors };
    };
    try resolveModuleDefs(self, &block) catch {
        return Diagnostics { errors: self.errors };
    };
    exitScope(self);
    setNodeType(self, root, Type::Void);

    return Diagnostics { errors: self.errors };
}

/// Analyze the module graph. This pass processes `mod` statements, creating symbols
/// and scopes for them, and also binds type names in each module so that cross-module
/// type references work regardless of declaration order.
fn resolveModuleGraph(self: *mut Resolver, block: *ast::Block) throws (ResolveError) {
    try bindTypeNames(self, block);

    for node in block.statements {
        if let case ast::NodeValue::Mod(decl) = node.value {
            try resolveModGraph(self, node, decl);
        }
    }
}

/// Bind all type names in a module.
/// Skips declarations that have already been bound.
fn bindTypeNames(self: *mut Resolver, block: *ast::Block) throws (ResolveError) {
    for node in block.statements {
        match node.value {
            case ast::NodeValue::RecordDecl(decl) => {
                if symbolFor(self, node) == nil {
                    try bindTypeName(self, node, decl.name, decl.attrs) catch {};
                }
            }
            case ast::NodeValue::UnionDecl(decl) => {
                if symbolFor(self, node) == nil {
                    try bindTypeName(self, node, decl.name, decl.attrs) catch {};
                }
            }
            case ast::NodeValue::TraitDecl { name, attrs, .. } => {
                if symbolFor(self, node) == nil {
                    try bindTraitName(self, node, name, attrs) catch {};
                }
            }
            else => {}
        }
    }
}

/// Resolve all type bodies in a module.
fn resolveTypeBodies(self: *mut Resolver, block: *ast::Block) throws (ResolveError) {
    for node in block.statements {
        match node.value {
            case ast::NodeValue::RecordDecl(decl) => {
                try resolveRecordBody(self, node, decl) catch {
                    // Continue resolving other types even if one fails.
                };
            }
            case ast::NodeValue::UnionDecl(decl) => {
                try resolveUnionBody(self, node, decl) catch {
                    // Continue resolving other types even if one fails.
                };
            }
            case ast::NodeValue::TraitDecl { supertraits, methods, .. } => {
                try resolveTraitBody(self, node, supertraits, methods) catch {
                    // Continue resolving other types even if one fails.
                };
            }
            else => {
                // Ignore other declarations.
            }
        }
    }
}

/// Analyze module declarations. This pass processes all top-level statements. When it hits
/// a `mod` statement, it recurses inside the module, analyzing its statements. Module import
/// statements (`use`) are processed here, and make use of the module graph established in the
/// previous pass.
///
/// This function uses a two-phase approach:
/// Phase 1: Bind all type names to allow forward references and mutual recursion.
/// Phase 2: Resolve type bodies, ie. field types, variant types, etc.
fn resolveModuleDecls(res: *mut Resolver, block: *ast::Block) throws (ResolveError) {
    // Phase 1: Bind all type names as placeholders.
    try bindTypeNames(res, block);
    // Phase 2: Process non-wildcard imports so module names are available
    // for submodule resolution and type lookups.
    for node in block.statements {
        if let case ast::NodeValue::Use(decl) = node.value {
            if not decl.wildcard {
                try resolveUse(res, node, decl);
            }
        }
    }
    // Phase 3: Bind function signatures so that function references are
    // available in constant and static initializers.
    for node in block.statements {
        if let case ast::NodeValue::FnDecl(decl) = node.value {
            try resolveFnDecl(res, node, decl);
        }
    }
    // Phase 4: Process constants before submodules, so that child modules
    // can reference parent constants via `super::`.
    for node in block.statements {
        if let case ast::NodeValue::ConstDecl(_) = node.value {
            try infer(res, node);
        }
    }
    // Phase 5: Process submodule declarations -- recurses into child modules.
    // Child modules may trigger on-demand type resolution via
    // [`ensureNominalResolved`] which switches to the declaring module's
    // scope.
    for node in block.statements {
        if let case ast::NodeValue::Mod(decl) = node.value {
            try resolveModDecl(res, node, decl);
        }
    }
    // Phase 5b: Process wildcard imports after submodules are resolved,
    // so that transitive re-exports (pub use foo::*) are visible.
    for node in block.statements {
        if let case ast::NodeValue::Use(decl) = node.value {
            if decl.wildcard {
                try resolveUse(res, node, decl);
            }
        }
    }
    // Phase 6: Resolve type bodies (record fields, union variants).
    try resolveTypeBodies(res, block);
    // Phase 7: Process all other declarations (statics, etc.).
    for stmt in block.statements {
        try visitDecl(res, stmt);
    }
}

/// Analyze module definitions. This pass analyzes function bodies, recursing into sub-modules.
fn resolveModuleDefs(self: *mut Resolver, block: *ast::Block) throws (ResolveError) {
    for stmt in block.statements {
        try visitDef(self, stmt);
    }
}

/// Resolve all packages.
pub fn resolve(self: *mut Resolver, graph: *module::ModuleGraph, packages: *[Pkg]) -> Diagnostics throws (ResolveError) {
    self.moduleGraph = graph;

    // 1. Bind all package roots to enable cross-package references.
    for i in 0..packages.len {
        let pkg = &packages[i];
        // Enter a new scope for the module.
        let enter = enterModuleScope(self, pkg.rootAst, pkg.rootEntry);
        // Bind the package root module name in the global package scope.
        try bindModuleIdent(self, pkg.rootEntry, enter.newScope, pkg.rootAst, 0, self.pkgScope);

        exitModuleScope(self, enter);
    }
    // 2. Resolve each package's contents.
    for i in 0..packages.len {
        let pkg = &packages[i];
        let diags = try resolvePackage(self, pkg.rootEntry, pkg.rootAst);
        if not success(&diags) {
            return diags;
        }
    }
    return Diagnostics { errors: self.errors };
}

/// Resolve a package.
fn resolvePackage(self: *mut Resolver, rootEntry: *module::ModuleEntry, node: *ast::Node) -> Diagnostics throws (ResolveError) {
    let rootId = rootEntry.id;
    let scope = self.moduleScopes[rootId as u32]
        else panic "resolvePackage: module scope not found";

    // Set up the module scope for this package.
    self.scope = scope;
    self.currentMod = rootId;

    let case ast::NodeValue::Block(block) = node.value
        else panic "resolvePackage: expected block for module root";

    // Module graph analysis phase: bind all module name symbols and scopes.
    try resolveModuleGraph(self, &block) catch {
        assert self.errors.len > 0, "resolvePackage: failure should have diagnostics";
        return Diagnostics { errors: self.errors };
    };

    // Declaration phase: bind all names and analyze top-level declarations.
    try resolveModuleDecls(self, &block) catch {
        assert self.errors.len > 0, "resolvePackage: failure should have diagnostics";
    };
    if self.errors.len > 0 {
        return Diagnostics { errors: self.errors };
    }

    // Definition phase: analyze function bodies and sub-module definitions.
    try resolveModuleDefs(self, &block) catch {
        assert self.errors.len > 0, "resolvePackage: failure should have diagnostics";
    };
    setNodeType(self, node, Type::Void);

    return Diagnostics { errors: self.errors };
}