radiance · Radiance self-hosting compiler

compiler/ lib/ examples/ std/ arch/ char/ collections/ lang/ alloc/ ast/ gen/ il/ module/ parser/ resolver/ scanner/ alloc.rad 4.3 KiB ast.rad 23.9 KiB gen.rad 507 B il.rad 15.3 KiB lower.rad 287.8 KiB module.rad 13.5 KiB package.rad 1.2 KiB parser.rad 82.9 KiB resolver.rad 407.8 KiB scanner.rad 18.3 KiB sexpr.rad 6.3 KiB strings.rad 2.2 KiB types.rad 280 B sys/ arch.rad 68 B char.rad 855 B collections.rad 39 B fmt.rad 8.1 KiB intrinsics.rad 467 B io.rad 1.3 KiB lang.rad 276 B mem.rad 2.2 KiB sys.rad 173 B testing.rad 2.4 KiB tests.rad 12.9 KiB vec.rad 1.7 KiB std.rad 281 B scripts/ seed/ sublime/ test/ vim/ .gitignore 336 B .gitsigners 112 B LICENSE 1.1 KiB Makefile 3.7 KiB README 4.8 KiB STYLE 2.5 KiB std.lib 1.2 KiB std.lib.test 347 B
lib/std/lang/resolver.rad 407.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.

export 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::types;
use std::lang::ast;
use std::lang::parser;
use std::lang::module;

/// Maximum number of diagnostics recorded.
export constant MAX_ERRORS: u32 = 64;

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

/// Maximum number of symbols stored within a module scope.
export constant MAX_MODULE_SYMBOLS: u32 = 768;
/// Maximum number of symbols stored within a local scope.
export constant MAX_LOCAL_SYMBOLS: u32 = 32;
/// Maximum function parameters.
export constant MAX_FN_PARAMS: u32 = 8;
/// Maximum function thrown types.
export constant 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.
export constant MAX_UNION_VARIANTS: u32 = 128;
/// Maximum nesting of loops.
export constant MAX_LOOP_DEPTH: u32 = 16;
/// Maximum trait instances.
export constant MAX_INSTANCES: u32 = 128;
/// Maximum standalone methods (across all types).
export constant MAX_METHODS: u32 = 256;
/// Maximum generic parameters on one declaration.
export constant MAX_GENERIC_PARAMS: u32 = 8;
/// Maximum explicit specialization roots in one package.
export constant MAX_GENERIC_ROOTS: u32 = 256;
/// Maximum canonical data and function specializations in one package.
export constant MAX_GENERIC_SPECIALIZATIONS: u32 = 512;
/// Maximum expanding generic function dependency depth.
export constant MAX_GENERIC_SPECIALIZATION_DEPTH: u16 = 32;

/// Resolution state for a trait signature table.
export union TraitState {
    Queued,
    Resolving,
    Complete,
}

/// Trait definition stored in the resolver.
export record TraitType {
    /// Trait name.
    name: *[u8],
    /// Module-local identity used by semantic tables.
    moduleId: u16,
    nodeId: u32,
    /// Method signatures, including from supertraits.
    methods: *mut [TraitMethod],
    /// Supertraits that must also be implemented.
    supertraits: *mut [*TraitType],
    /// Rigid `Self` type used by static signatures.
    selfType: *GenericParamType,
    /// Whether signature resolution has started or completed.
    state: TraitState,
    /// Whether every vtable-exposed method is object-safe.
    objectSafe: bool,
}

/// A single method signature within a trait.
export record TraitMethod {
    /// Method name.
    name: *[u8],
    /// Function type for the method, excluding the receiver.
    fnType: *FnType,
    /// Whether the receiver is mutable.
    mutable: bool,
    /// Pointer-like class used by the receiver.
    receiverClass: types::PointerClass,
    /// Trait that originally declared this method.
    owner: *TraitType,
    /// V-table slot index.
    index: u32,
}

/// An entry in the trait instance registry.
export record InstanceEntry {
    /// Trait type descriptor.
    traitType: *TraitType,
    /// Concrete type that implements the trait.
    concreteType: Type,
    /// 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.
export record MethodEntry {
    /// Concrete type that owns the method.
    concreteType: Type,
    /// Method name.
    name: *[u8],
    /// Function type excluding the receiver.
    fnType: *FnType,
    /// Whether the receiver is mutable.
    mutable: bool,
    /// Pointer-like class used by the receiver.
    receiverClass: types::PointerClass,
    /// Symbol for the method.
    symbol: *mut Symbol,
}

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

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

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

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

/// Size of a pointer in bytes.
export constant PTR_SIZE: u32 = 8;

/// Information about a record or tuple field.
export 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.
export record ArrayType {
    item: *Type,
    length: u32,
}

/// Anonymous record whose field layout depends on rigid parameters.
export record GenericRecordType {
    fields: *[RecordField],
    labeled: bool,
}

/// Record nominal type.
export record RecordType {
    fields: *[RecordField],
    labeled: bool,
    /// Cached layout.
    layout: Layout,
    /// Whether the declaration explicitly carries the `Linear` marker.
    declaredLinear: bool,
}

/// Union nominal type.
export 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,
    /// Whether the declaration explicitly carries the `Linear` marker.
    declaredLinear: bool,
}

/// Metadata for user-defined types.
export 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.
export 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.
export 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.
export 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.
export 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]
    },
}

/// A rigid type parameter belonging to one generic declaration.
export record GenericParamType {
    /// Declaration that owns the parameter.
    owner: *ast::Node,
    /// Parameter declaration node.
    node: *ast::Node,
    /// Parameter name.
    name: *[u8],
    /// Position in the declaration's ordered parameter list.
    index: u32,
    /// Resolved trait bounds.
    bounds: *[*TraitType],
    /// Shared usage flag, mutable through symbol references.
    used: *mut bool,
    /// Declared integer type for a constant parameter, or `nil` for a type parameter.
    constType: ?*Type,
}

/// Resolved function signature details.
export record FnType {
    paramTypes: *[*Type],
    returnType: *Type,
    throwList: *[*Type],
    /// Whether calling this function requires an unsafe context.
    isUnsafe: bool,
    localCount: u32,
}

/// Resolved, declaration-scoped generic metadata.
export record GenericTemplate {
    /// Declaration that owns this template.
    decl: *ast::Node,
    /// Ordered rigid type parameters.
    params: *[*GenericParamType],
    /// Symbolic function signature, for function templates.
    signature: ?*FnType,
    /// Symbolic field or variant types, in declaration order.
    members: *[*Type],
    /// Whether the declaration explicitly carries the `Linear` marker.
    declaredLinear: bool,
    moduleId: ?u16,
    /// Whether a generic function body has already been checked.
    bodyResolved: bool,
    /// Number of body-analysis entries, retained to enforce check-once behavior.
    bodyChecks: u8,
}

/// Canonical concrete specialization of a generic record or union.
export record GenericDataSpecialization {
    /// Template symbol whose declaration is specialized.
    template: *mut Symbol,
    /// Ordered, interned concrete type arguments.
    args: *[*Type],
    /// Ordinary nominal type produced for this application.
    nominal: *mut NominalType,
    /// Whether an explicit `instantiate` declaration requested this type.
    rooted: *mut bool,
    /// First concrete application site, used for root diagnostics.
    site: *ast::Node,
}

/// Worklist state for a concrete generic function body.
export union GenericFnState {
    Queued,
    Lowering,
    Complete,
}

/// Canonical concrete specialization of a generic free function.
export record GenericFnSpecialization {
    /// Template symbol whose body is lowered.
    template: *mut Symbol,
    /// Ordered, interned concrete type arguments.
    args: *[*Type],
    /// Substituted concrete function signature.
    fnType: *FnType,
    /// First explicit instantiation site.
    site: *ast::Node,
    /// Dependency-closure state.
    state: GenericFnState,
    /// Distance from an explicit root, used to bound expanding recursion.
    depth: u16,
}

/// Linked cache entry for generic function specializations.
export record GenericFnSpecializationNode {
    specialization: GenericFnSpecialization,
    next: ?*mut GenericFnSpecializationNode,
}

/// A generic call retained in a checked symbolic function body.
export record GenericFnDependency {
    caller: ?*mut Symbol,
    callee: *mut Symbol,
    args: *[*Type],
    site: *ast::Node,
    next: ?*GenericFnDependency,
}

/// Concrete call selected for one symbolic edge in one caller specialization.
export record GenericFnDependencyResolution {
    dependency: *GenericFnDependency,
    caller: *GenericFnSpecialization,
    callee: *GenericFnSpecialization,
    next: ?*GenericFnDependencyResolution,
}

/// Linked cache entry for generic data specializations.
record GenericDataSpecializationNode {
    specialization: GenericDataSpecialization,
    next: ?*GenericDataSpecializationNode,
}

/// Sparse generic metadata entry, allocated only for template symbols.
record GenericTemplateNode {
    symbol: *mut Symbol,
    template: GenericTemplate,
    next: ?*mut GenericTemplateNode,
}

/// Ordered replacement types for rigid parameters.
export record Substitution {
    params: *[*GenericParamType],
    args: *[*Type],
}

/// Symbolic application of a generic data template inside another template.
export record GenericDataApplyType {
    template: *mut Symbol,
    args: *[*Type],
    site: *ast::Node,
}

/// Pointer-like address payload.
export record PointerType {
    /// Ownership and safety class.
    class: types::PointerClass,
    /// Pointer target type.
    target: *Type,
    /// Whether the pointer is mutable.
    mutable: bool,
}

/// Pointer-like slice payload.
export record SliceType {
    /// Ownership and safety class.
    class: types::PointerClass,
    /// Slice element type.
    item: *Type,
    /// Whether the slice is mutable.
    mutable: bool,
}

/// Erased pointer-like type payload.
export record TraitObjectType {
    /// Ownership and safety class.
    class: types::PointerClass,
    /// Trait definition.
    traitInfo: *TraitType,
    /// Whether the pointer is mutable.
    mutable: bool,
}

/// Describes a type computed during semantic analysis.
export 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,
    },
    /// Pointer-like address.
    Pointer(PointerType),
    /// Pointer-like slice.
    Slice(SliceType),
    /// Eg. `[i32; 32]`.
    Array(ArrayType),
    /// Array type whose length depends on a rigid constant parameter.
    GenericArray {
        item: *Type,
        length: *ast::Node,
    },
    /// Rigid integer constant parameter within a generic declaration.
    ConstParameter(*GenericParamType),
    /// Canonical typed integer generic argument.
    ConstArgument {
        type: *Type,
        value: ConstInt,
    },
    /// Symbolic integer expression awaiting constant-parameter substitution.
    GenericConstExpr {
        type: *Type,
        expr: *ast::Node,
    },
    /// Eg. `?T`.
    Optional(*Type),
    /// Eg. `fn id(i32) -> i32`.
    Fn(*FnType),
    /// Named, ie. user-defined types, includes union variants.
    Nominal(*NominalType),
    /// Rigid type parameter within a generic declaration.
    Parameter(*GenericParamType),
    /// Anonymous record awaiting substitution before layout.
    GenericRecord(*GenericRecordType),
    /// Generic data application awaiting substitution of its arguments.
    GenericDataApply(*GenericDataApplyType),
    /// An erased pointer-like type with a v-table.
    TraitObject(TraitObjectType),
}

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

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

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

/// Detailed payload attached to a symbol, specialized per symbol kind.
export 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),
    /// Rigid generic type parameter.
    TypeParameter(*GenericParamType),
    /// Rigid generic integer constant parameter.
    ConstParameter(*GenericParamType),
    /// Trait symbol.
    Trait(*mut TraitType),
}

/// Resolved symbol allocated during semantic analysis.
export 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.
export 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.
export 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.
export 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.
export 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 not have a body.
    IntrinsicUnexpectedBody,
    /// 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]),
    /// Subtrait instance attempts to override an inherited method.
    InheritedTraitMethod(*[u8]),
    /// Trait name used as a value expression.
    UnexpectedTraitName,
    /// Trait method receiver does not point to the declaring trait.
    TraitReceiverMismatch,
    /// A trait mentioning `Self` outside its receiver cannot form an object.
    TraitNotObjectSafe,
    /// Supertrait declarations form a cycle.
    TraitInheritanceCycle,
    /// An instance target is not a supported concrete type.
    InvalidInstanceTarget,
    /// Trait declaration and instance disagree about unsafe call requirements.
    TraitMethodSafetyMismatch,
    /// 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]),
    /// Linear binding was consumed more than once.
    LinearUseAfterConsume(*[u8]),
    /// Linear binding remains available at an exit.
    LinearNotConsumed(*[u8]),
    /// A case-pattern `let-else` fallback must terminate control flow.
    LinearLetElseMustTerminate,
    /// Branches disagree about a linear binding's state.
    LinearBranchMismatch(*[u8]),
    /// A linear field cannot be moved independently.
    LinearPartialMove,
    /// A linear value cannot be discarded.
    LinearDiscard,
    /// Assignment would overwrite a live linear value.
    LinearOverwrite,
    /// `undefined` cannot initialize a linear type.
    LinearUndefined,
    /// A reference appears in a storable or escaping position.
    InvalidRefPosition,
    /// A reference cannot be bound to a local.
    RefBinding,
    /// Call arguments contain overlapping incompatible loans.
    BorrowConflict(*[u8]),
    /// Unsafe pointer operation outside an `unsafe` declaration.
    UnsafeOperation,
    /// Safe code cannot call an `unsafe` function.
    UnsafeCall,
    /// A syntax node is not valid in a generic context.
    GenericUnsupported,
    /// A generic bound did not name a trait.
    GenericBoundNotTrait,
    /// A constant parameter type is not a concrete integer type.
    GenericConstUnsupported,
    /// An attribute cannot be applied to a generic function.
    GenericFnAttribute,
    /// Generic function declarations must be at module scope.
    GenericFnNested,
    /// A type parameter does not affect its function.
    GenericFnUnusedParameter(*[u8]),
    /// More than one bound exposes the selected method name.
    GenericBoundAmbiguous(*[u8]),
    /// A rigid parameter was used where a concrete layout is required.
    GenericLayoutRequired,
    /// A concrete generic specialization has infinitely recursive layout.
    GenericRecursiveLayout,
    /// A function specialization targeted a non-function declaration.
    GenericFunctionExpected,
    /// A concrete type argument does not satisfy a declared trait bound.
    GenericBoundUnsatisfied(*[u8]),
    /// A generic function application has no explicit instantiation root.
    GenericFunctionInstantiationRequired,
    /// A generic call graph expands beyond the specialization bound.
    GenericSpecializationChain,
    /// Generic argument inference did not determine every parameter.
    GenericInferenceIncomplete,
    /// Generic argument inference found incompatible evidence.
    GenericInferenceConflict,
    /// A generic declaration was named without required arguments.
    GenericArgumentsRequired,
    /// A concrete application is not covered by an explicit instantiation root.
    GenericInstantiationRequired,
    /// Internal error.
    Internal,
    /// A generic application supplied the wrong number of arguments.
    GenericArgumentCount(CountMismatch),
    /// A data specialization targeted a non-data generic declaration.
    GenericDataExpected,
    /// A data specialization argument still contains a rigid parameter.
    GenericConcreteArgumentsRequired,
    /// A declaration exceeds the generic parameter limit.
    GenericParameterLimit,
    /// A package exceeds the explicit generic root limit.
    GenericRootLimit,
    /// A package exceeds the canonical specialization limit.
    GenericSpecializationLimit,
}

/// Diagnostics returned by the analyzer.
export 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.
export 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,
    },
    /// Static method call through a bounded generic parameter.
    GenericBoundMethodCall {
        param: *GenericParamType,
        traitInfo: *TraitType,
        methodIndex: u32,
        /// Whether the receiver is the first explicit call argument.
        explicitReceiver: bool,
    },
    /// Standalone method call metadata.
    MethodCall { method: *MethodEntry },
    /// Slice `.append(val, allocator)` method call.
    SliceAppend { elemType: *Type },
    /// Slice `.delete(index)` method call.
    SliceDelete { elemType: *Type },
    /// Concrete specialization selected by an explicit generic function value.
    GenericFnCall(*GenericFnSpecialization),
    /// Symbolic generic call resolved under the caller's specialization.
    GenericFnDependency(*GenericFnDependency),
}

/// Combined resolver metadata for a single AST node.
export 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.
export 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.
export record Config {
    /// Whether we're building in test mode.
    buildTest: bool,
}

/// How pattern bindings are created during match.
export 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.
export record MatchSubject {
    /// The effective type to match against.
    effectiveTy: Type,
    /// How bindings should be created.
    by: MatchBy,
}

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

/// Global resolver state.
export 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,
    /// Rigid `Self` type while resolving a trait signature.
    currentTraitSelf: ?*GenericParamType,
    /// Current module being analyzed.
    currentMod: u16,
    /// Nesting depth of unsafe modules and function bodies.
    unsafeDepth: u32,
    /// Whether this compilation contains explicitly linear declarations.
    linearEnabled: bool,
    /// 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,
    /// Sparse metadata for generic declarations.
    genericTemplates: ?*mut GenericTemplateNode,
    /// Canonical generic function specializations.
    genericFnSpecializations: ?*mut GenericFnSpecializationNode,
    /// Symbolic and deferred generic call edges.
    genericFnDependencies: ?*GenericFnDependency,
    /// Concrete resolutions of symbolic generic call edges.
    genericFnDependencyResolutions: ?*GenericFnDependencyResolution,
    /// Package-wide canonical generic data specializations.
    genericDataSpecializations: ?*GenericDataSpecializationNode,
    /// Number of explicit generic roots requested by the package.
    genericRoots: u32,
    /// Number of canonical data and function specializations.
    genericSpecializationCount: u32,
}

/// Internal error sentinel thrown when analysis cannot proceed.
export 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.
export 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;
        }
        set 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;

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

    return &node.ty;
}

/// Return whether a type contains a rigid generic parameter.
export fn containsGenericParameter(ty: Type) -> bool {
    match ty {
        case Type::Pointer(pointer) =>
            return containsGenericParameter(*pointer.target),
        case Type::Slice(slice) =>
            return containsGenericParameter(*slice.item),
        case Type::Parameter(_), Type::ConstParameter(_),
             Type::GenericConstExpr { .. } => return true,
        case Type::Array(array) => return containsGenericParameter(*array.item),
        case Type::GenericArray { .. } => return true,
        case Type::Optional(inner) => return containsGenericParameter(*inner),
        // Symbolic anonymous records require materialization even when their
        // own fields happen not to mention a rigid parameter.
        case Type::GenericRecord(_) => return true,
        case Type::GenericDataApply(_) => return true,
        case Type::Fn(info) => {
            for param in info.paramTypes {
                if containsGenericParameter(*param) {
                    return true;
                }
            }
            if containsGenericParameter(*info.returnType) {
                return true;
            }
            for thrown in info.throwList {
                if containsGenericParameter(*thrown) {
                    return true;
                }
            }
            return false;
        }
        case Type::Range { start, end } => {
            if let ty = start {
                if containsGenericParameter(*ty) {
                    return true;
                }
            }
            if let ty = end {
                if containsGenericParameter(*ty) {
                    return true;
                }
            }
            return false;
        }
        else => return false,
    }
}

/// Return whether a by-value type reaches an in-progress nominal placeholder.
fn hasUnresolvedNominalLayout(ty: Type) -> bool {
    match ty {
        case Type::Pointer(_), Type::Slice(_) => return false,
        case Type::Array(array) => return hasUnresolvedNominalLayout(*array.item),
        case Type::Optional(inner) => return hasUnresolvedNominalLayout(*inner),
        case Type::Nominal(info) => {
            if let case NominalType::Placeholder(_) = *info {
                return true;
            }
            return false;
        }
        case Type::GenericRecord(rec) => {
            for field in rec.fields {
                if hasUnresolvedNominalLayout(field.fieldType) {
                    return true;
                }
            }
            return false;
        }
        else => return false,
    }
}

/// Materialize concrete generic data applications within a type while
/// preserving rigid parameters and constant-dependent constructors.
fn materializeConcreteGenericData(
    self: *mut Resolver,
    ty: Type,
    site: *ast::Node,
) -> Type throws (ResolveError) {
    match ty {
        case Type::Pointer(pointer) => {
            let inner = try materializeConcreteGenericData(self, *pointer.target, site);
            return Type::Pointer(PointerType {
                class: pointer.class,
                target: allocType(self, inner),
                mutable: pointer.mutable,
            });
        }
        case Type::Slice(slice) => {
            let inner = try materializeConcreteGenericData(self, *slice.item, site);
            return Type::Slice(SliceType {
                class: slice.class,
                item: allocType(self, inner),
                mutable: slice.mutable,
            });
        }
        case Type::Array(array) => {
            let item = try materializeConcreteGenericData(self, *array.item, site);
            return Type::Array(ArrayType {
                item: allocType(self, item),
                length: array.length,
            });
        }
        case Type::GenericArray { item, length } => {
            let inner = try materializeConcreteGenericData(self, *item, site);
            return Type::GenericArray { item: allocType(self, inner), length };
        }
        case Type::Optional(inner) => {
            let value = try materializeConcreteGenericData(self, *inner, site);
            return Type::Optional(allocType(self, value));
        }
        case Type::GenericDataApply(app) => {
            let a = alloc::arenaAllocator(&mut self.arena);
            let mut args: *mut [*Type] = &mut [];
            let mut concrete = true;
            for arg in app.args {
                let value = try materializeConcreteGenericData(self, *arg, site);
                set concrete = concrete and not containsGenericParameter(value);
                args.append(allocType(self, value), a);
            }
            if concrete {
                let nominal = try specializeGenericData(
                    self, app.site, app.template, &args[..], false
                );
                return Type::Nominal(nominal);
            }
            let application = try! alloc::alloc(
                &mut self.arena,
                @sizeOf(GenericDataApplyType),
                @alignOf(GenericDataApplyType),
            ) as *mut GenericDataApplyType;
            set *application = GenericDataApplyType {
                template: app.template,
                args: &args[..],
                site: app.site,
            };
            return Type::GenericDataApply(application);
        }
        case Type::Fn(info) => {
            let a = alloc::arenaAllocator(&mut self.arena);
            let mut params: *mut [*Type] = &mut [];
            let mut throwTypes: *mut [*Type] = &mut [];
            for param in info.paramTypes {
                let value = try materializeConcreteGenericData(self, *param, site);
                params.append(allocType(self, value), a);
            }
            for thrown in info.throwList {
                let value = try materializeConcreteGenericData(self, *thrown, site);
                throwTypes.append(allocType(self, value), a);
            }
            let result = try materializeConcreteGenericData(
                self, *info.returnType, site
            );
            return Type::Fn(allocFnType(self, FnType {
                paramTypes: &params[..],
                returnType: allocType(self, result),
                throwList: &throwTypes[..],
                isUnsafe: info.isUnsafe,
                localCount: info.localCount,
            }));
        }
        case Type::GenericRecord(rec) => {
            let a = alloc::arenaAllocator(&mut self.arena);
            let mut fields: *mut [RecordField] = &mut [];
            let mut symbolic = false;
            for field in rec.fields {
                let fieldType = try materializeConcreteGenericData(
                    self, field.fieldType, site
                );
                set symbolic = symbolic or containsGenericParameter(fieldType);
                fields.append(RecordField {
                    name: field.name,
                    fieldType,
                    offset: field.offset,
                }, a);
            }
            let updatedRec = try! alloc::alloc(
                &mut self.arena,
                @sizeOf(GenericRecordType),
                @alignOf(GenericRecordType),
            ) as *mut GenericRecordType;
            set *updatedRec = GenericRecordType {
                fields: &fields[..],
                labeled: rec.labeled,
            };
            let updated = Type::GenericRecord(updatedRec);
            if symbolic {
                return updated;
            }
            let empty = Substitution { params: &[], args: &[] };
            return try substituteType(self, updated, &empty, site);
        }
        else => return ty,
    }
}

/// Look up the concrete replacement for a rigid parameter.
export fn substitutionArg(sub: *Substitution, param: *GenericParamType) -> Type {
    assert sub.params.len == sub.args.len, "substitution length mismatch";
    for candidate, i in sub.params {
        if candidate == param {
            return *sub.args[i];
        }
    }
    if param.constType <> nil {
        return Type::ConstParameter(param);
    }
    return Type::Parameter(param);
}

/// Recursively replace rigid parameters in a resolved type.
export fn substituteType(
    self: *mut Resolver,
    ty: Type,
    sub: *Substitution,
    site: *ast::Node,
) -> Type throws (ResolveError) {
    if not containsGenericParameter(ty) {
        return ty;
    }
    match ty {
        case Type::Parameter(param) => return substitutionArg(sub, param),
        case Type::ConstParameter(param) => return substitutionArg(sub, param),
        case Type::GenericConstExpr { type, expr } => {
            let value = constValueWithSubstitution(self, expr, sub)
                else throw emitError(self, expr, ErrorKind::ConstExprRequired);
            let case ConstValue::Int(int) = value
                else throw emitError(self, expr, ErrorKind::ConstExprRequired);
            if not validateConstIntRange(value, *type) {
                throw emitError(self, expr, ErrorKind::NumericLiteralOverflow);
            }
            let case ConstValue::Int(canonical) = castConstInt(int, *type)
                else throw emitError(self, expr, ErrorKind::Internal);
            return Type::ConstArgument { type, value: canonical };
        }
        case Type::Pointer(pointer) => {
            let inner = try substituteType(self, *pointer.target, sub, site);
            return Type::Pointer(PointerType {
                class: pointer.class,
                target: allocType(self, inner),
                mutable: pointer.mutable,
            });
        }
        case Type::Slice(slice) => {
            let inner = try substituteType(self, *slice.item, sub, site);
            return Type::Slice(SliceType {
                class: slice.class,
                item: allocType(self, inner),
                mutable: slice.mutable,
            });
        }
        case Type::Array(array) => {
            let item = try substituteType(self, *array.item, sub, site);
            return Type::Array(ArrayType {
                item: allocType(self, item),
                length: array.length,
            });
        }
        case Type::GenericArray { item, length } => {
            let concreteItem = try substituteType(self, *item, sub, site);
            let value = constValueWithSubstitution(self, length, sub)
                else throw emitError(self, length, ErrorKind::ConstExprRequired);
            if not validateConstIntRange(value, Type::U32) {
                throw emitError(self, length, ErrorKind::NumericLiteralOverflow);
            }
            let case ConstValue::Int(int) = value
                else throw emitError(self, length, ErrorKind::ConstExprRequired);
            return Type::Array(ArrayType {
                item: allocType(self, concreteItem),
                length: int.magnitude as u32,
            });
        }
        case Type::Optional(inner) => {
            let value = try substituteType(self, *inner, sub, site);
            return Type::Optional(allocType(self, value));
        }
        case Type::GenericDataApply(app) => {
            let a = alloc::arenaAllocator(&mut self.arena);
            let mut args: *mut [*Type] = &mut [];
            let mut symbolic = false;
            for arg in app.args {
                let replacement = try substituteType(self, *arg, sub, site);
                set symbolic = symbolic or containsGenericParameter(replacement);
                args.append(allocType(self, replacement), a);
            }
            if symbolic {
                let application = try! alloc::alloc(
                    &mut self.arena,
                    @sizeOf(GenericDataApplyType),
                    @alignOf(GenericDataApplyType),
                ) as *mut GenericDataApplyType;
                set *application = GenericDataApplyType {
                    template: app.template,
                    args: &args[..],
                    site: app.site,
                };
                return Type::GenericDataApply(application);
            }
            let nominal = try specializeGenericData(
                self, app.site, app.template, &args[..], false
            );
            return Type::Nominal(nominal);
        }
        case Type::GenericRecord(rec) => {
            let a = alloc::arenaAllocator(&mut self.arena);
            let mut fields: *mut [RecordField] = &mut [];
            let mut offset: u32 = 0;
            let mut alignment: u32 = 1;
            for field in rec.fields {
                let fieldType = try substituteType(self, field.fieldType, sub, site);
                if hasUnresolvedNominalLayout(fieldType) {
                    throw emitError(self, site, ErrorKind::GenericRecursiveLayout);
                }
                try ensureStorableType(self, site, fieldType);
                try ensureTypeResolved(self, fieldType, site);
                let fieldLayout = getTypeLayout(fieldType);
                set offset = mem::alignUp(offset, fieldLayout.alignment);
                fields.append(RecordField {
                    name: field.name,
                    fieldType,
                    offset: offset as i32,
                }, a);
                set offset += fieldLayout.size;
                set alignment = max(alignment, fieldLayout.alignment);
            }
            let layout = Layout {
                size: mem::alignUp(offset, alignment),
                alignment,
            };
            return Type::Nominal(allocNominalType(self, NominalType::Record(RecordType {
                fields: &fields[..],
                labeled: rec.labeled,
                layout,
                declaredLinear: false,
            })));
        }
        case Type::Fn(info) => {
            let a = alloc::arenaAllocator(&mut self.arena);
            let mut params: *mut [*Type] = &mut [];
            let mut throwTypes: *mut [*Type] = &mut [];
            for param in info.paramTypes {
                let concrete = try substituteType(self, *param, sub, site);
                params.append(allocType(self, concrete), a);
            }
            for thrown in info.throwList {
                let concrete = try substituteType(self, *thrown, sub, site);
                throwTypes.append(allocType(self, concrete), a);
            }
            let result = try substituteType(self, *info.returnType, sub, site);
            return Type::Fn(allocFnType(self, FnType {
                paramTypes: &params[..],
                returnType: allocType(self, result),
                throwList: &throwTypes[..],
                isUnsafe: info.isUnsafe,
                localCount: info.localCount,
            }));
        }
        case Type::Range { start, end } => {
            let mut newStart: ?*Type = nil;
            let mut newEnd: ?*Type = nil;
            if let value = start {
                let concrete = try substituteType(self, *value, sub, site);
                set newStart = allocType(self, concrete);
            }
            if let value = end {
                let concrete = try substituteType(self, *value, sub, site);
                set newEnd = allocType(self, concrete);
            }
            return Type::Range { start: newStart, end: newEnd };
        }
        else => return 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;

    set *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;

    set *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.
export 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.
export record Pkg {
    /// Root module entry.
    rootEntry: *module::ModuleEntry,
    /// Root AST node.
    rootAst: *ast::Node,
}

/// Construct a resolver with module context and backing storage.
export 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.
    set *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 {
        set 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 {
        set moduleScopes[i] = nil;
    }
    return Resolver {
        scope: storage.pkgScope,
        pkgScope: storage.pkgScope,
        loopStack: undefined,
        loopDepth: 0,
        currentFn: nil,
        currentTraitSelf: nil,
        currentMod: 0,
        unsafeDepth: 0,
        linearEnabled: false,
        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,
        genericTemplates: nil,
        genericFnSpecializations: nil,
        genericFnDependencies: nil,
        genericFnDependencyResolutions: nil,
        genericDataSpecializations: nil,
        genericRoots: 0,
        genericSpecializationCount: 0,
    };
}

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

/// Retrieve an error diagnostic by index, if present.
export 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;
    set self.errors = @sliceOf(self.errors.ptr, idx + 1, self.errors.cap);
    set 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];

    set *entry = Scope { owner, parent: nil, moduleId: nil, symbols, symbolsLen: 0 };
    set 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.
export fn enterScope(self: *mut Resolver, owner: *ast::Node) -> *Scope {
    let scope = allocScope(self, owner, MAX_LOCAL_SYMBOLS);
    set scope.parent = self.scope;
    set self.scope = scope;
    return scope;
}

/// Enter a module scope. Returns an object that can be used to exit the scope.
export 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);

    set self.scope = scope;
    set self.scope.moduleId = module.id;
    set self.currentMod = module.id;
    // TODO: Allow any unsigned integer to index an array.
    set 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`.
export fn exitModuleScope(self: *mut Resolver, entry: ModuleScope) {
    set self.scope = entry.prevScope;
    set self.currentMod = entry.prevMod;
}

/// Exit the most recent scope.
export 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;
    };
    set 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";
    set self.loopStack[self.loopDepth] = LoopCtx { hasBreak: false };
    set self.loopDepth += 1;

    let ty = try infer(self, body) catch {
        assert self.loopDepth <> 0, "visitLoop: loop depth underflow";
        set self.loopDepth -= 1;
        throw ResolveError::Failure;
    };
    // Pop and check if break was encountered.
    set 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";
    set 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;
    }
    set 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";
    }
    set 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;
    }
    set 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;
    }
    set 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) {
    set 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) {
    set 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) {
    set 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) {
    set 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) {
    set self.nodeData.entries[node.id].extra = NodeExtra::TraitMethodCall { traitInfo, methodIndex };
}

/// Associate static generic-bound dispatch metadata with a call node.
fn setGenericBoundMethodCall(
    self: *mut Resolver,
    node: *ast::Node,
    param: *GenericParamType,
    traitInfo: *TraitType,
    methodIndex: u32,
    explicitReceiver: bool,
) {
    set self.nodeData.entries[node.id].extra = NodeExtra::GenericBoundMethodCall {
        param, traitInfo, methodIndex, explicitReceiver,
    };
}

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

/// Retrieve the constant value associated with a node, if any.
export 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.
export 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.
export 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.
export 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) {
    set self.nodeData.entries[node.id].extra = NodeExtra::MatchProng { catchAll };
}

/// Check if a prong is catch-all.
export 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) {
    set self.nodeData.entries[node.id].extra = NodeExtra::Match { isConst };
}

/// Check if a match has all constant patterns.
export 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.
export fn nodeData(self: *Resolver, node: *ast::Node) -> *NodeData {
    return &self.nodeData.entries[node.id];
}

/// Get the type for a node, or `nil` if unknown.
export 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.
export fn scopeFor(self: *Resolver, node: *ast::Node) -> ?*mut Scope {
    return self.nodeData.entries[node.id].scope;
}

/// Get the symbol bound to a node.
export 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.
export 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.
export 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.
export 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;
    set *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.
export 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.
export fn getTypeLayout(ty: Type) -> Layout {
    match ty {
        case Type::Pointer(_) => return Layout { size: PTR_SIZE, alignment: PTR_SIZE },
        case Type::Slice(_), Type::TraitObject(_) =>
            return Layout { size: PTR_SIZE * 2, alignment: PTR_SIZE },
        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::Fn(_) => return Layout { size: PTR_SIZE, 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.
export 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 {
                set layout.alignment = alignment;
            }
        }
    }
    return layout;
}

/// Get the layout of an array type.
export 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.
export 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.
export fn getOptionalValOffset(inner: Type) -> u32 {
    let innerLayout = getTypeLayout(inner);
    return mem::alignUp(1, innerLayout.alignment);
}

/// Check if a type is optional.
export 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.
export 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.
export 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.
export fn isNullableType(ty: Type) -> bool {
    match ty {
        case Type::Pointer(_), Type::Slice(_) => return true,
        else => return false,
    }
}

/// Get the layout of a nominal type.
export 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.
export 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);
        set maxSize = max(maxSize, errLayout.size);
        set 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 {
            set isAllVoid = false;
            let payloadLayout = getTypeLayout(variant.valueType);
            set maxVarSize = max(maxVarSize, payloadLayout.size);
            set 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.
fn variantTag(
    self: *mut Resolver,
    variantDecl: ast::UnionDeclVariant,
    iota: *mut u32,
    sub: ?*Substitution,
) -> u32 throws (ResolveError) {
    let mut tag: u32 = *iota;
    if let valueNode = variantDecl.value {
        let mut value: ?ConstValue = nil;
        if let substitution = sub {
            set value = constValueWithSubstitution(self, valueNode, substitution);
        } else {
            set value = constValueEntry(self, valueNode);
        }
        let resolved = value
            else throw emitError(self, valueNode, ErrorKind::ConstExprRequired);
        if not validateConstIntRange(resolved, Type::U32) {
            throw emitError(self, valueNode, ErrorKind::NumericLiteralOverflow);
        }
        let case ConstValue::Int(int) = resolved
            else throw emitError(self, valueNode, ErrorKind::ConstExprRequired);
        set tag = int.magnitude as u32;
    }
    set *iota = tag + 1;
    return tag;
}

/// Check if a type is a union without payloads.
export 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::Slice(slice) => try ensureTypeResolved(self, *slice.item, site),
        case Type::Pointer(_) => {}, // Pointers have fixed layout, don't recurse.
        case Type::Array(arr) => try ensureTypeResolved(self, *arr.item, site),
        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] {
                        set self.scope = ms;
                        set 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 => {},
        }
        set self.scope = prevScope;
        set 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;
}

/// Preserve legacy address-of coercions until a package opts into linearity.
fn pointerClassesAssignable(
    self: *Resolver,
    to: types::PointerClass,
    from: types::PointerClass,
) -> bool {
    return to == from or (
        not self.linearEnabled
        and to == types::PointerClass::Owned
        and from == types::PointerClass::Ref
    );
}

/// 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 typesEqual(to, from) {
        return Coercion::Identity;
    }
    if let case Type::Pointer(lhs) = to {
        let case Type::Pointer(rhs) = from else return nil;
        if not pointerClassesAssignable(self, lhs.class, rhs.class) {
            return nil;
        }
        // Allow coercion from `*T` to `*opaque`, and mutable counterparts.
        if *lhs.target == Type::Opaque {
            if lhs.mutable and not rhs.mutable {
                return nil;
            }
            return Coercion::Identity;
        }
        if lhs.mutable and not rhs.mutable {
            return nil;
        }
        return isAssignable(self, *lhs.target, *rhs.target, rval);
    }
    if let case Type::TraitObject(lhs) = to {
        if let case Type::Pointer(rhs) = from {
            if not pointerClassesAssignable(self, lhs.class, rhs.class)
                or (lhs.mutable and not rhs.mutable)
            {
                return nil;
            }
            if let inst = findInstance(self, lhs.traitInfo, *rhs.target) {
                return Coercion::TraitObject { traitInfo: lhs.traitInfo, inst };
            }
        }
        if let case Type::TraitObject(rhs) = from {
            if not pointerClassesAssignable(self, lhs.class, rhs.class)
                or lhs.traitInfo <> rhs.traitInfo
            {
                return nil;
            }
            if lhs.mutable and not rhs.mutable {
                return nil;
            }
            return Coercion::Identity;
        }
        return nil;
    }
    if let case Type::Slice(lhs) = to {
        let case Type::Slice(rhs) = from else return nil;
        if not pointerClassesAssignable(self, lhs.class, rhs.class)
            or (lhs.mutable and not rhs.mutable)
        {
            return nil;
        }
        // Allow coercion from `*[T]` to `*[opaque]`, and mutable counterparts.
        if *lhs.item == Type::Opaque {
            return Coercion::Identity;
        }
        return isAssignable(self, *lhs.item, *rhs.item, rval);
    }
    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 => {
                    if typesEqual(*lhs.item, *rhs.item) {
                        return Coercion::Identity;
                    }
                    return nil;
                }
            }
        }

        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::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 isIntegerLiteralExpr(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.isUnsafe <> b.isUnsafe {
        return false;
    }
    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.
export fn typesEqual(a: Type, b: Type) -> bool {
    if a == b {
        return true;
    }
    if let case Type::Pointer(av) = a {
        let case Type::Pointer(bv) = b else return false;
        return av.class == bv.class and av.mutable == bv.mutable
            and typesEqual(*av.target, *bv.target);
    }
    if let case Type::Slice(av) = a {
        let case Type::Slice(bv) = b else return false;
        return av.class == bv.class and av.mutable == bv.mutable
            and typesEqual(*av.item, *bv.item);
    }
    if let case Type::TraitObject(av) = a {
        let case Type::TraitObject(bv) = b else return false;
        return av.class == bv.class and av.mutable == bv.mutable
            and av.traitInfo == bv.traitInfo;
    }
    match a {
        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);
        }
        case Type::GenericDataApply(aa) => {
            let case Type::GenericDataApply(ab) = b else return false;
            if aa.template <> ab.template or aa.args.len <> ab.args.len {
                return false;
            }
            for i in 0..aa.args.len {
                if not typesEqual(*aa.args[i], *ab.args[i]) {
                    return false;
                }
            }
            return true;
        }
        else => return false,
    }
}

/// Return whether `ty` is a direct reference.
export fn isRefType(ty: Type) -> bool {
    match ty {
        case Type::Pointer(PointerType { class: types::PointerClass::Ref, .. }),
             Type::Slice(SliceType { class: types::PointerClass::Ref, .. }),
             Type::TraitObject(TraitObjectType { class: types::PointerClass::Ref, .. }) => return true,
        else => return false,
    }
}

/// Return whether a type contains a reference.
fn containsRef(ty: Type) -> bool {
    if isRefType(ty) {
        return true;
    }
    if let case Type::Pointer(pointer) = ty {
        return containsRef(*pointer.target);
    }
    if let case Type::Slice(slice) = ty {
        return containsRef(*slice.item);
    }
    match ty {
        case Type::Array(array) => return containsRef(*array.item),
        case Type::Optional(inner) => return containsRef(*inner),
        case Type::GenericRecord(rec) => {
            for field in rec.fields {
                if containsRef(field.fieldType) {
                    return true;
                }
            }
            return false;
        }
        // Nominal declarations validate their own fields and variants.
        // Treating them as leaves also terminates recursive pointer types.
        case Type::Nominal(_) => return false,
        else => return false,
    }
}

/// Return whether a type is exact-linear.
export fn isLinear(ty: Type) -> bool {
    match ty {
        case Type::Pointer(PointerType { class: types::PointerClass::Owned, .. }),
             Type::Slice(SliceType { class: types::PointerClass::Owned, .. }),
             Type::TraitObject(TraitObjectType { class: types::PointerClass::Owned, .. }) => return true,
        case Type::Pointer(PointerType { class: types::PointerClass::Ref, .. }),
             Type::Pointer(PointerType { class: types::PointerClass::Unsafe, .. }),
             Type::Slice(SliceType { class: types::PointerClass::Ref, .. }),
             Type::Slice(SliceType { class: types::PointerClass::Unsafe, .. }),
             Type::TraitObject(TraitObjectType { class: types::PointerClass::Ref, .. }),
             Type::TraitObject(TraitObjectType { class: types::PointerClass::Unsafe, .. }) => return false,

        case Type::Array(array) => return isLinear(*array.item),
        case Type::Optional(inner) => return isLinear(*inner),
        case Type::Nominal(NominalType::Record(recInfo)) => {
            if recInfo.declaredLinear {
                return true;
            }
            for field in recInfo.fields {
                if isLinear(field.fieldType) {
                    return true;
                }
            }
            return false;
        }
        case Type::Nominal(NominalType::Union(unionType)) => {
            if unionType.declaredLinear {
                return true;
            }
            for variant in unionType.variants {
                if isLinear(variant.valueType) {
                    return true;
                }
            }
            return false;
        }
        else => return false,
    }
}

/// Return whether `ty` is a direct unsafe pointer-like value.
fn isUnsafePointerType(ty: Type) -> bool {
    match ty {
        case Type::Pointer(PointerType { class: types::PointerClass::Unsafe, .. }),
             Type::Slice(SliceType { class: types::PointerClass::Unsafe, .. }),
             Type::TraitObject(TraitObjectType { class: types::PointerClass::Unsafe, .. }) => return true,
        else => return false,
    }
}

/// Get the record info from a record type.
export 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.
export fn autoDeref(ty: Type) -> Type {
    if let case Type::Pointer(view) = ty {
        return *view.target;
    }
    return ty;
}

/// Get field info for a record-like type (records, slices) by field index.
export fn getRecordField(ty: Type, index: u32) -> ?RecordField {
    if let case Type::Slice(slice) = ty {
        match index {
            case 0 => return RecordField {
                name: PTR_FIELD,
                fieldType: Type::Pointer(PointerType {
                    class: slice.class,
                    target: slice.item,
                    mutable: slice.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,
        }
    }
    if let case Type::Nominal(NominalType::Record(recInfo)) = ty;
        index < recInfo.fields.len
    {
        return recInfo.fields[index];
    }
    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(l) = left {
        if let case Type::Pointer(r) = right {
            return typesEqual(*l.target, *r.target);
        }
    }
    // 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);
    }
    // Preserve the defining module when importing an existing symbol into
    // another module's scope.
    if sym.moduleId == nil {
        if let modId = scope.moduleId {
            set sym.moduleId = modId;
        }
    }
    set scope.symbols[scope.symbolsLen] = sym;
    set 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 {
        set 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 {
    match sym.data {
        case SymbolData::Type(_), SymbolData::TypeParameter(_) => return true,
        else => 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 {
            set curr = parent;
        } else {
            break;
        }
    }
    return nil;
}

/// Find a symbol by name in a specific scope (matches any symbol kind).
export 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";
            set buf[0] = name;
            set 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);
            set buf[parent.len] = child;
            set 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.
            set 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 {
            set 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 `export` 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::Export) {
        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) {
    // A specialized union application introduces the variant namespace.
    if let case ast::NodeValue::GenericApply(app) = access.parent.value {
        let nominal = try resolveGenericDataApply(self, access.parent, app, false);
        let case NominalType::Union(unionType) = *nominal
            else throw emitError(self, node, ErrorKind::InvalidScopeAccess);
        let variantName = try nodeName(self, access.child);
        let variant = try resolveUnionVariantAccess(
            self, node, access, unionType, variantName
        );
        setNodeType(self, node, Type::Nominal(nominal));
        return variant;
    }
    let mut startScope = scope;
    let mut pathNode = node;
    if let superAccess = try checkSuperAccess(self, node) {
        set startScope = superAccess.scope;
        set 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) {
        set startScope = superAccess.scope;
        set 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
    );
}

/// Return whether a declaration requires generic arguments.
fn isGenericDeclaration(node: *ast::Node) -> bool {
    match node.value {
        case ast::NodeValue::RecordDecl(decl) => return decl.params.len > 0,
        case ast::NodeValue::UnionDecl(decl) => return decl.params.len > 0,
        case ast::NodeValue::FnDecl(decl) => return decl.params.len > 0,
        else => return false,
    }
}

/// Stack node used to stop cycles while walking ordinary nominal containers.
record GenericRootVisit {
    /// Nominal type visited at this stack entry.
    nominal: *NominalType,
    /// Previous stack entry.
    parent: ?*GenericRootVisit,
}

/// Return whether a nominal type is present in the visit stack.
fn genericRootVisited(visit: ?*GenericRootVisit, nominal: *NominalType) -> bool {
    let mut cursor = visit;
    while let entry = cursor {
        if entry.nominal == nominal {
            return true;
        }
        set cursor = entry.parent;
    }
    return false;
}

/// Mark generic specializations reached through one concrete type.
fn markGenericDataTypeRootedInner(
    self: *mut Resolver,
    ty: Type,
    visited: ?*GenericRootVisit,
) -> bool {
    match ty {
        case Type::Pointer(pointer) =>
            return markGenericDataTypeRootedInner(self, *pointer.target, visited),
        case Type::Slice(slice) =>
            return markGenericDataTypeRootedInner(self, *slice.item, visited),
        case Type::Array(array) =>
            return markGenericDataTypeRootedInner(self, *array.item, visited),
        case Type::Optional(inner) =>
            return markGenericDataTypeRootedInner(self, *inner, visited),
        case Type::Fn(info) => {
            let mut changed = markGenericDataTypeRootedInner(
                self, *info.returnType, visited
            );
            for param in info.paramTypes {
                set changed = markGenericDataTypeRootedInner(
                    self, *param, visited
                ) or changed;
            }
            for thrown in info.throwList {
                set changed = markGenericDataTypeRootedInner(
                    self, *thrown, visited
                ) or changed;
            }
            return changed;
        }
        case Type::Nominal(nominal) => {
            let mut cursor = self.genericDataSpecializations;
            while let node = cursor {
                let specialization = &node.specialization;
                if specialization.nominal == nominal {
                    if not *specialization.rooted {
                        set *specialization.rooted = true;
                        return true;
                    }
                    return false;
                }
                set cursor = node.next;
            }
            if genericRootVisited(visited, nominal) {
                return false;
            }
            let visit = GenericRootVisit { nominal, parent: visited };
            let mut changed = false;
            match *nominal {
                case NominalType::Record(recordType) => {
                    for field in recordType.fields {
                        set changed = markGenericDataTypeRootedInner(
                            self, field.fieldType, &visit
                        ) or changed;
                    }
                }
                case NominalType::Union(unionType) => {
                    for variant in unionType.variants {
                        set changed = markGenericDataTypeRootedInner(
                            self, variant.valueType, &visit
                        ) or changed;
                    }
                }
                case NominalType::Placeholder(_) => {}
            }
            return changed;
        }
        else => return false,
    }
}

/// Mark generic data specializations reachable from a concrete type.
fn markGenericDataTypeRooted(self: *mut Resolver, ty: Type) -> bool {
    return markGenericDataTypeRootedInner(self, ty, nil);
}

/// Propagate explicit roots through arguments and specialized data members.
fn validateGenericDataRoots(self: *mut Resolver) throws (ResolveError) {
    loop {
        let mut changed = false;
        let mut cursor = self.genericDataSpecializations;
        while let node = cursor {
            let specialization = &node.specialization;
            if *specialization.rooted {
                for arg in specialization.args {
                    set changed = markGenericDataTypeRooted(self, *arg) or changed;
                }
                match *specialization.nominal {
                    case NominalType::Record(recordType) => {
                        for field in recordType.fields {
                            set changed = markGenericDataTypeRooted(
                                self, field.fieldType
                            ) or changed;
                        }
                    }
                    case NominalType::Union(unionType) => {
                        for variant in unionType.variants {
                            set changed = markGenericDataTypeRooted(
                                self, variant.valueType
                            ) or changed;
                        }
                    }
                    case NominalType::Placeholder(_) => {}
                }
            }
            set cursor = node.next;
        }
        if not changed {
            break;
        }
    }
    let mut cursor = self.genericDataSpecializations;
    while let node = cursor {
        let specialization = &node.specialization;
        if not *specialization.rooted {
            throw emitError(
                self, specialization.site, ErrorKind::GenericInstantiationRequired
            );
        }
        set cursor = node.next;
    }
}

/// Look up a cached specialization by template and ordered arguments.
export fn findGenericDataSpecialization(
    self: *Resolver,
    template: *Symbol,
    args: *[*Type],
) -> ?*GenericDataSpecialization {
    let mut cursor = self.genericDataSpecializations;
    while let node = cursor {
        let entry = &node.specialization;
        if entry.template == template and entry.args.len == args.len {
            let mut equal = true;
            for arg, i in args {
                if not typesEqual(*entry.args[i], *arg) {
                    set equal = false;
                    break;
                }
            }
            if equal {
                return entry;
            }
        }
        set cursor = node.next;
    }
    return nil;
}

/// Look up a generic data specialization by its concrete nominal identity.
export fn genericDataSpecializationForNominal(
    self: *Resolver,
    nominal: *NominalType,
) -> ?*GenericDataSpecialization {
    let mut cursor = self.genericDataSpecializations;
    while let node = cursor {
        if node.specialization.nominal == nominal {
            return &node.specialization;
        }
        set cursor = node.next;
    }
    return nil;
}

/// Find the declaration symbol that owns an ordinary nominal type.
export fn symbolForNominal(
    self: *Resolver,
    nominal: *NominalType,
) -> ?*Symbol {
    for data in self.nodeData.entries {
        if let sym = data.sym {
            if let case SymbolData::Type(candidate) = sym.data; candidate == nominal {
                return sym;
            }
        }
    }
    return nil;
}

/// Resolve generic metadata lazily so applications are source-order independent.
fn ensureGenericDataTemplate(self: *mut Resolver, sym: *mut Symbol)
    throws (ResolveError)
{
    if genericTemplateFor(self, sym) <> nil {
        return;
    }
    let prevScope = self.scope;
    let prevMod = self.currentMod;
    if let mid = moduleIdForSymbol(self, sym) {
        if let moduleScope = self.moduleScopes[mid as u32] {
            set self.scope = moduleScope;
            set self.currentMod = mid;
        }
    }
    match sym.node.value {
        case ast::NodeValue::RecordDecl(decl) => {
            try resolveGenericDataTemplate(
                self, sym.node, decl.params, decl.fields, decl.derives, true
            ) catch e {
                set self.scope = prevScope;
                set self.currentMod = prevMod;
                throw e;
            };
        }
        case ast::NodeValue::UnionDecl(decl) => {
            try resolveGenericDataTemplate(
                self, sym.node, decl.params, decl.variants, decl.derives, false
            ) catch e {
                set self.scope = prevScope;
                set self.currentMod = prevMod;
                throw e;
            };
        }
        else => {
            set self.scope = prevScope;
            set self.currentMod = prevMod;
            throw emitError(self, sym.node, ErrorKind::GenericDataExpected);
        }
    }
    set self.scope = prevScope;
    set self.currentMod = prevMod;
}

/// Look up a possible inferred generic call target without emitting diagnostics.
fn findGenericCandidateSymbol(
    self: *Resolver,
    node: *ast::Node,
) -> ?*mut Symbol {
    if let sym = symbolFor(self, node) {
        return sym;
    }
    match node.value {
        case ast::NodeValue::Ident(name) =>
            return findAnySymbol(self.scope, name),
        case ast::NodeValue::ScopeAccess(access) => {
            let case ast::NodeValue::Ident(childName) = access.child.value
                else return nil;
            if let case ast::NodeValue::Super = access.parent.value {
                let current = module::get(self.moduleGraph, self.currentMod) else return nil;
                let parentId = current.parent else return nil;
                let parentScope = self.moduleScopes[parentId as u32] else return nil;
                return findSymbolInScope(parentScope, childName);
            }
            let sym = findGenericCandidateSymbol(self, access.parent) else return nil;
            let case SymbolData::Module { scope, .. } = sym.data else return nil;
            return findSymbolInScope(scope, childName);
        }
        else => return nil,
    }
}

/// Resolve a generic application's declaration symbol without requiring arguments.
fn resolveGenericTarget(
    self: *mut Resolver,
    node: *ast::Node,
) -> *mut Symbol throws (ResolveError) {
    if let existing = symbolFor(self, node) {
        return existing;
    }
    let mut sym: *mut Symbol = undefined;
    match node.value {
        case ast::NodeValue::Ident(name) => {
            let found = findAnySymbol(self.scope, name) else {
                throw emitError(self, node, ErrorKind::UnresolvedSymbol(name));
            };
            set sym = found;
        }
        case ast::NodeValue::ScopeAccess(access) => {
            set sym = try resolveAccess(self, node, access, self.scope);
        }
        else => throw emitError(self, node, ErrorKind::GenericUnsupported),
    }
    if not isGenericDeclaration(sym.node) {
        throw emitError(self, node, ErrorKind::GenericUnsupported);
    }
    setNodeSymbol(self, node, sym);
    return sym;
}

/// Resolve a generic record or union target.
fn resolveGenericDataTarget(
    self: *mut Resolver,
    node: *ast::Node,
) -> *mut Symbol throws (ResolveError) {
    let sym = try resolveGenericTarget(self, node);
    let case SymbolData::Type(_) = sym.data
        else throw emitError(self, node, ErrorKind::GenericDataExpected);
    match sym.node.value {
        case ast::NodeValue::RecordDecl(_), ast::NodeValue::UnionDecl(_) => {}
        else => throw emitError(self, node, ErrorKind::GenericDataExpected),
    }
    return sym;
}

/// Build a concrete record specialization from substituted member types.
fn specializeGenericRecord(
    self: *mut Resolver,
    template: *GenericTemplate,
    decl: ast::RecordDecl,
    sub: *Substitution,
) -> RecordType throws (ResolveError) {
    let a = alloc::arenaAllocator(&mut self.arena);
    let mut fields: *mut [RecordField] = &mut [];
    let mut offset: u32 = 0;
    let mut alignment: u32 = 1;
    for member, i in decl.fields {
        let case ast::NodeValue::RecordField { field, type, .. } = member.value
            else throw emitError(self, member, ErrorKind::Internal);
        let concrete = try substituteType(self, *template.members[i], sub, type);
        if hasUnresolvedNominalLayout(concrete) {
            throw emitError(self, type, ErrorKind::GenericRecursiveLayout);
        }
        try ensureStorableType(self, type, concrete);
        try ensureTypeResolved(self, concrete, type);
        let layout = getTypeLayout(concrete);
        set offset = mem::alignUp(offset, layout.alignment);
        let mut name: ?*[u8] = nil;
        if decl.labeled {
            let nameNode = field else throw emitError(self, member, ErrorKind::Internal);
            set name = try nodeName(self, nameNode);
        }
        fields.append(RecordField {
            name,
            fieldType: concrete,
            offset: offset as i32,
        }, a);
        set offset += layout.size;
        set alignment = max(alignment, layout.alignment);
    }
    return RecordType {
        fields: &fields[..],
        labeled: decl.labeled,
        layout: Layout {
            size: mem::alignUp(offset, alignment),
            alignment,
        },
        declaredLinear: template.declaredLinear,
    };
}

/// Build a concrete union specialization from substituted variant types.
fn specializeGenericUnion(
    self: *mut Resolver,
    templateSym: *mut Symbol,
    template: *GenericTemplate,
    decl: ast::UnionDecl,
    sub: *Substitution,
) -> UnionType throws (ResolveError) {
    let a = alloc::arenaAllocator(&mut self.arena);
    let mut variants: *mut [UnionVariant] = &mut [];
    let mut iota: u32 = 0;
    for variantNode, i in decl.variants {
        let case ast::NodeValue::UnionDeclVariant(variantDecl) = variantNode.value
            else throw emitError(self, variantNode, ErrorKind::Internal);
        let valueType = try substituteType(
            self, *template.members[i], sub, variantNode
        );
        if hasUnresolvedNominalLayout(valueType) {
            throw emitError(self, variantNode, ErrorKind::GenericRecursiveLayout);
        }
        if let typeNode = variantDecl.type {
            try ensureStorableType(self, typeNode, valueType);
            try ensureTypeResolved(self, valueType, typeNode);
        }
        let name = try nodeName(self, variantDecl.name);
        let tag = try variantTag(self, variantDecl, &mut iota, sub);
        let symbol = allocSymbol(
            self,
            SymbolData::Variant {
                type: valueType,
                decl: template.decl,
                ordinal: i,
                index: tag,
            },
            name,
            variantNode,
            0,
        );
        set symbol.moduleId = templateSym.moduleId;
        variants.append(UnionVariant { name, valueType, symbol }, a);
    }
    let info = computeUnionLayout(&variants[..]);
    return UnionType {
        variants: &variants[..],
        layout: info.layout,
        valOffset: info.valOffset,
        isAllVoid: info.isAllVoid,
        declaredLinear: template.declaredLinear,
    };
}

/// Return one canonical concrete specialization for a generic data application.
fn specializeGenericData(
    self: *mut Resolver,
    site: *ast::Node,
    templateSym: *mut Symbol,
    args: *[*Type],
    rooted: bool,
) -> *mut NominalType throws (ResolveError) {
    if let existing = findGenericDataSpecialization(self, templateSym, args) {
        if rooted {
            set *existing.rooted = true;
        }
        return existing.nominal;
    }
    if self.genericSpecializationCount >= MAX_GENERIC_SPECIALIZATIONS {
        throw emitError(self, site, ErrorKind::GenericSpecializationLimit);
    }
    set self.genericSpecializationCount += 1;
    let template = genericTemplateFor(self, templateSym)
        else throw emitError(self, site, ErrorKind::Internal);
    let a = alloc::arenaAllocator(&mut self.arena);
    let mut storedArgs: *mut [*Type] = &mut [];
    let rootedFlag = try! alloc::alloc(
        &mut self.arena, @sizeOf(bool), @alignOf(bool)
    ) as *mut bool;
    set *rootedFlag = rooted;
    for arg in args {
        storedArgs.append(arg, a);
    }
    let nominal = allocNominalType(self, NominalType::Placeholder(template.decl));
    let cacheNode = try! alloc::alloc(
        &mut self.arena,
        @sizeOf(GenericDataSpecializationNode),
        @alignOf(GenericDataSpecializationNode),
    ) as *mut GenericDataSpecializationNode;
    set *cacheNode = GenericDataSpecializationNode {
        specialization: GenericDataSpecialization {
            template: templateSym,
            args: &storedArgs[..],
            nominal,
            rooted: rootedFlag,
            site,
        },
        next: self.genericDataSpecializations,
    };
    set self.genericDataSpecializations = cacheNode;
    let sub = Substitution { params: template.params, args: &storedArgs[..] };
    match template.decl.value {
        case ast::NodeValue::RecordDecl(decl) => {
            let recordType = try specializeGenericRecord(self, template, decl, &sub);
            set *nominal = NominalType::Record(recordType);
        }
        case ast::NodeValue::UnionDecl(decl) => {
            let unionType = try specializeGenericUnion(
                self, templateSym, template, decl, &sub
            );
            set *nominal = NominalType::Union(unionType);
        }
        else => throw emitError(self, site, ErrorKind::GenericDataExpected),
    }
    return nominal;
}

/// Resolve one generic argument according to its declaration kind.
fn resolveGenericArgument(
    self: *mut Resolver,
    argNode: *ast::Node,
    param: *GenericParamType,
) -> Type throws (ResolveError) {
    if let constType = param.constType {
        let mut expr = argNode;
        if let case ast::NodeValue::TypeSig(ast::TypeSig::Nominal(name)) = argNode.value {
            set expr = name;
        }
        let actual = try visit(self, expr, *constType);
        if let value = constValueEntry(self, expr) {
            let case ConstValue::Int(int) = value
                else throw emitError(self, expr, ErrorKind::ConstExprRequired);
            if not validateConstIntRange(value, *constType) {
                throw emitError(self, expr, ErrorKind::NumericLiteralOverflow);
            }
            let _ = try expectAssignable(self, *constType, actual, expr);
            let case ConstValue::Int(canonical) = castConstInt(int, *constType)
                else throw emitError(self, expr, ErrorKind::Internal);
            return Type::ConstArgument { type: constType, value: canonical };
        }
        let _ = try expectAssignable(self, *constType, actual, expr);
        if isConstExpr(self, expr) and containsGenericConstExpr(self, expr) {
            return Type::GenericConstExpr { type: constType, expr };
        }
        throw emitError(self, expr, ErrorKind::ConstExprRequired);
    }
    if let case ast::NodeValue::TypeSig(_) = argNode.value {
        let arg = try resolveGenericValueType(self, argNode);
        return try materializeConcreteGenericData(self, arg, argNode);
    }
    throw emitError(self, argNode, ErrorKind::GenericUnsupported);
}

/// Resolve and canonicalize one generic data type application.
fn resolveGenericDataApply(
    self: *mut Resolver,
    node: *ast::Node,
    app: ast::GenericApply,
    rooted: bool,
) -> *mut NominalType throws (ResolveError) {
    let templateSym = try resolveGenericDataTarget(self, app.target);
    try ensureGenericDataTemplate(self, templateSym);
    let template = genericTemplateFor(self, templateSym)
        else throw emitError(self, node, ErrorKind::Internal);
    if app.args.len <> template.params.len {
        throw emitError(self, node, ErrorKind::GenericArgumentCount(CountMismatch {
            expected: template.params.len,
            actual: app.args.len,
        }));
    }
    let a = alloc::arenaAllocator(&mut self.arena);
    let mut args: *mut [*Type] = &mut [];
    for argNode, i in app.args {
        let argType = try resolveGenericArgument(self, argNode, template.params[i]);
        if containsGenericParameter(argType) {
            throw emitError(self, argNode, ErrorKind::GenericConcreteArgumentsRequired);
        }
        args.append(allocType(self, argType), a);
    }
    let nominal = try specializeGenericData(
        self, node, templateSym, &args[..], rooted
    );

    setNodeSymbol(self, node, templateSym);
    setNodeType(self, node, Type::Nominal(nominal));
    return nominal;
}

/// Return the function specialization list for lowering.
export fn genericFnSpecializations(
    self: *Resolver,
) -> ?*GenericFnSpecializationNode {
    return self.genericFnSpecializations;
}

/// Look up a canonical function specialization.
export fn findGenericFnSpecialization(
    self: *Resolver,
    template: *Symbol,
    args: *[*Type],
) -> ?*GenericFnSpecialization {
    let mut cursor = self.genericFnSpecializations;
    while let node = cursor {
        let entry = &node.specialization;
        if entry.template == template and entry.args.len == args.len {
            let mut equal = true;
            for arg, i in args {
                if not typesEqual(*entry.args[i], *arg) {
                    set equal = false;
                    break;
                }
            }
            if equal {
                return entry;
            }
        }
        set cursor = node.next;
    }
    return nil;
}

/// Create or retrieve one concrete generic function specialization.
fn internGenericFnSpecialization(
    self: *mut Resolver,
    templateSym: *mut Symbol,
    args: *[*Type],
    site: *ast::Node,
    depth: u16,
) -> *GenericFnSpecialization throws (ResolveError) {
    if let existing = findGenericFnSpecialization(self, templateSym, args) {
        return existing;
    }
    if self.genericSpecializationCount >= MAX_GENERIC_SPECIALIZATIONS {
        throw emitError(self, site, ErrorKind::GenericSpecializationLimit);
    }
    set self.genericSpecializationCount += 1;
    let template = genericTemplateFor(self, templateSym)
        else throw emitError(self, site, ErrorKind::Internal);
    let signature = template.signature
        else throw emitError(self, site, ErrorKind::GenericFunctionExpected);
    let a = alloc::arenaAllocator(&mut self.arena);
    let mut storedArgs: *mut [*Type] = &mut [];
    for arg in args {
        storedArgs.append(allocType(self, *arg), a);
    }
    let sub = Substitution { params: template.params, args: &storedArgs[..] };
    let concrete = try substituteType(self, Type::Fn(signature), &sub, site);
    let case Type::Fn(fnType) = concrete
        else throw emitError(self, site, ErrorKind::Internal);
    let _ = markGenericDataTypeRooted(self, concrete);
    let cacheNode = try! alloc::alloc(
        &mut self.arena,
        @sizeOf(GenericFnSpecializationNode),
        @alignOf(GenericFnSpecializationNode),
    ) as *mut GenericFnSpecializationNode;
    set *cacheNode = GenericFnSpecializationNode {
        specialization: GenericFnSpecialization {
            template: templateSym,
            args: &storedArgs[..],
            fnType,
            site,
            state: GenericFnState::Queued,
            depth,
        },
        next: self.genericFnSpecializations,
    };
    set self.genericFnSpecializations = cacheNode;
    return &cacheNode.specialization;
}

/// Retain a generic call edge for package-wide specialization closure.
fn recordGenericFnDependency(
    self: *mut Resolver,
    node: *ast::Node,
    caller: ?*mut Symbol,
    callee: *mut Symbol,
    args: *[*Type],
    fnType: *FnType,
) {
    let a = alloc::arenaAllocator(&mut self.arena);
    let mut storedArgs: *mut [*Type] = &mut [];
    for arg in args {
        storedArgs.append(allocType(self, *arg), a);
    }
    let dependency = try! alloc::alloc(
        &mut self.arena,
        @sizeOf(GenericFnDependency),
        @alignOf(GenericFnDependency),
    ) as *mut GenericFnDependency;
    set *dependency = GenericFnDependency {
        caller,
        callee,
        args: &storedArgs[..],
        site: node,
        next: self.genericFnDependencies,
    };
    set self.genericFnDependencies = dependency;
    setNodeSymbol(self, node, callee);
    setNodeType(self, node, Type::Fn(fnType));
    set self.nodeData.entries[node.id].extra =
        NodeExtra::GenericFnDependency(dependency);
}

/// Resolve a generic function application as a root, concrete call, or symbolic edge.
fn resolveGenericFnApply(
    self: *mut Resolver,
    node: *ast::Node,
    app: ast::GenericApply,
    rooted: bool,
) -> *FnType throws (ResolveError) {
    let templateSym = try resolveGenericTarget(self, app.target);
    let case SymbolData::Value { type: Type::Fn(_), .. } = templateSym.data
        else throw emitError(self, app.target, ErrorKind::GenericFunctionExpected);
    let template = genericTemplateFor(self, templateSym)
        else throw emitError(self, node, ErrorKind::Internal);
    let signature = template.signature
        else throw emitError(self, app.target, ErrorKind::GenericFunctionExpected);
    if app.args.len <> template.params.len {
        throw emitError(self, node, ErrorKind::GenericArgumentCount(CountMismatch {
            expected: template.params.len,
            actual: app.args.len,
        }));
    }
    let a = alloc::arenaAllocator(&mut self.arena);
    let mut args: *mut [*Type] = &mut [];
    let caller = currentGenericTemplateSymbol(self);
    for argNode, i in app.args {
        let argType = try resolveGenericArgument(self, argNode, template.params[i]);
        let symbolic = containsGenericParameter(argType);
        if symbolic and caller == nil {
            throw emitError(
                self, argNode, ErrorKind::GenericConcreteArgumentsRequired
            );
        }
        if not symbolic {
            for bound in template.params[i].bounds {
                if findInstance(self, bound, argType) == nil {
                    throw emitError(
                        self, argNode, ErrorKind::GenericBoundUnsatisfied(bound.name)
                    );
                }
            }
        }
        args.append(allocType(self, argType), a);
    }
    let sub = Substitution { params: template.params, args: &args[..] };
    let applied = try substituteType(self, Type::Fn(signature), &sub, node);
    let case Type::Fn(appliedFn) = applied
        else throw emitError(self, node, ErrorKind::Internal);
    if rooted {
        if caller <> nil {
            throw emitError(self, node, ErrorKind::GenericConcreteArgumentsRequired);
        }
        let specialization = try internGenericFnSpecialization(
            self, templateSym, &args[..], node, 0
        );
        setNodeSymbol(self, node, templateSym);
        setNodeType(self, node, Type::Fn(specialization.fnType));
        set self.nodeData.entries[node.id].extra =
            NodeExtra::GenericFnCall(specialization);
        return specialization.fnType;
    }
    if caller == nil {
        if let existing = findGenericFnSpecialization(self, templateSym, &args[..]) {
            setNodeSymbol(self, node, templateSym);
            setNodeType(self, node, Type::Fn(existing.fnType));
            set self.nodeData.entries[node.id].extra =
                NodeExtra::GenericFnCall(existing);
            return existing.fnType;
        }
    }
    recordGenericFnDependency(
        self, node, caller, templateSym, &args[..], appliedFn
    );
    return appliedFn;
}

/// Expand explicit roots through symbolic generic calls to a fixed point.
fn closeGenericFnSpecializations(self: *mut Resolver) throws (ResolveError) {
    loop {
        let mut queued: ?*mut GenericFnSpecialization = nil;
        let mut cursor = self.genericFnSpecializations;
        while let node = cursor {
            if let case GenericFnState::Queued = node.specialization.state {
                set queued = &mut node.specialization;
                break;
            }
            set cursor = node.next;
        }
        let specialization = queued else break;
        set specialization.state = GenericFnState::Lowering;
        let callerTemplate = genericTemplateFor(self, specialization.template)
            else throw emitError(self, specialization.site, ErrorKind::Internal);
        let callerSub = Substitution {
            params: callerTemplate.params,
            args: specialization.args,
        };
        let mut edge = self.genericFnDependencies;
        while let dependency = edge {
            if dependency.caller == specialization.template {
                let a = alloc::arenaAllocator(&mut self.arena);
                let mut concreteArgs: *mut [*Type] = &mut [];
                for arg in dependency.args {
                    let concrete = try substituteType(
                        self, *arg, &callerSub, dependency.site
                    );
                    if containsGenericParameter(concrete) {
                        throw emitError(
                            self,
                            dependency.site,
                            ErrorKind::GenericConcreteArgumentsRequired,
                        );
                    }
                    concreteArgs.append(allocType(self, concrete), a);
                }
                let calleeTemplate = genericTemplateFor(self, dependency.callee)
                    else throw emitError(
                        self, dependency.site, ErrorKind::Internal
                    );
                for arg, i in concreteArgs {
                    for bound in calleeTemplate.params[i].bounds {
                        if findInstance(self, bound, *arg) == nil {
                            throw emitError(
                                self,
                                dependency.site,
                                ErrorKind::GenericBoundUnsatisfied(bound.name),
                            );
                        }
                    }
                }
                let mut callee = findGenericFnSpecialization(
                    self, dependency.callee, &concreteArgs[..]
                );
                if callee == nil {
                    if specialization.depth >= MAX_GENERIC_SPECIALIZATION_DEPTH {
                        throw emitError(
                            self,
                            dependency.site,
                            ErrorKind::GenericSpecializationChain,
                        );
                    }
                    set callee = try internGenericFnSpecialization(
                        self,
                        dependency.callee,
                        &concreteArgs[..],
                        dependency.site,
                        specialization.depth + 1,
                    );
                }
                let concreteCallee = callee
                    else throw emitError(
                        self, dependency.site, ErrorKind::Internal
                    );
                let resolution = try! alloc::alloc(
                    &mut self.arena,
                    @sizeOf(GenericFnDependencyResolution),
                    @alignOf(GenericFnDependencyResolution),
                ) as *mut GenericFnDependencyResolution;
                set *resolution = GenericFnDependencyResolution {
                    dependency,
                    caller: specialization,
                    callee: concreteCallee,
                    next: self.genericFnDependencyResolutions,
                };
                set self.genericFnDependencyResolutions = resolution;
            }
            set edge = dependency.next;
        }
        set specialization.state = GenericFnState::Complete;
    }

    // Non-generic calls may only select entries made reachable by the closure.
    let mut edge = self.genericFnDependencies;
    while let dependency = edge {
        if dependency.caller == nil {
            let specialization = findGenericFnSpecialization(
                self, dependency.callee, dependency.args
            ) else {
                throw emitError(
                    self,
                    dependency.site,
                    ErrorKind::GenericFunctionInstantiationRequired,
                );
            };
            set self.nodeData.entries[dependency.site.id].extra =
                NodeExtra::GenericFnCall(specialization);
            set self.nodeData.entries[dependency.site.id].ty =
                Type::Fn(specialization.fnType);
        }
        set edge = dependency.next;
    }
}

/// Select the concrete callee for a symbolic edge while lowering a specialization.
export fn genericFnSpecializationForDependency(
    self: *Resolver,
    dependency: *GenericFnDependency,
    caller: *GenericFnSpecialization,
) -> ?*GenericFnSpecialization {
    let mut resolution = self.genericFnDependencyResolutions;
    while let entry = resolution {
        if entry.dependency == dependency and entry.caller == caller {
            return entry.callee;
        }
        set resolution = entry.next;
    }
    return nil;
}

/// 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);
            if isGenericDeclaration(sym.node) {
                throw emitError(self, node, ErrorKind::GenericArgumentsRequired);
            }

            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);
            if isGenericDeclaration(sym.node) {
                throw emitError(self, node, ErrorKind::GenericArgumentsRequired);
            }

            setNodeSymbol(self, node, sym);

            return ty;
        }
        case ast::NodeValue::GenericApply(app) =>
            return try resolveGenericDataApply(self, node, app, false),
        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, body, attrs } => {
            try resolveMethodDecl(self, node, name, receiverName, receiverType, sig, attrs);
        }
        case ast::NodeValue::Instantiate(applications) => {
            for application in applications {
                let case ast::NodeValue::GenericApply(app) = application.value
                    else throw emitError(self, application, ErrorKind::GenericUnsupported);
                if self.genericRoots >= MAX_GENERIC_ROOTS {
                    throw emitError(self, application, ErrorKind::GenericRootLimit);
                }
                set self.genericRoots += 1;
                let target = try resolveGenericTarget(self, app.target);
                match target.data {
                    case SymbolData::Type(_) => {
                        let _ = try resolveGenericDataApply(self, application, app, true);
                    }
                    case SymbolData::Value { type: Type::Fn(_), .. } => {
                        let _ = try resolveGenericFnApply(self, application, app, true);
                    }
                    else => {
                        throw emitError(self, app.target, ErrorKind::GenericUnsupported);
                    }
                }
            }
            setNodeType(self, node, Type::Void);
        }
        else => {
            // Ignore non-declaration nodes.
        }
    }
}

/// Require the current declaration to be unsafe.
fn requireUnsafe(self: *mut Resolver, node: *ast::Node) throws (ResolveError) {
    if self.unsafeDepth == 0 {
        throw emitError(self, node, ErrorKind::UnsafeOperation);
    }
}

/// Reject calls from safe code through unsafe function types.
fn checkUnsafeCall(self: *mut Resolver, node: *ast::Node, info: *FnType)
    throws (ResolveError)
{
    if info.isUnsafe and self.unsafeDepth == 0 {
        throw emitError(self, node, ErrorKind::UnsafeCall);
    }
}

/// 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";
            let mut isUnsafe = false;
            if let attrs = decl.attrs {
                set isUnsafe = ast::attributesContains(&attrs, ast::Attribute::Unsafe);
            }
            if isUnsafe {
                set self.unsafeDepth += 1;
            }
            try resolveModuleDefs(self, &block) catch e {
                if isUnsafe { set self.unsafeDepth -= 1; }
                exitModuleScope(self, submod);
                throw e;
            };
            if isUnsafe {
                set self.unsafeDepth -= 1;
            }
            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);
}

/// Reject nested references while allowing a direct parameter reference.
fn validateValueTypeReferences(self: *mut Resolver, node: *ast::Node, ty: Type)
    throws (ResolveError)
{
    if isRefType(ty) {
        if let case Type::Pointer(pointer) = ty {
            if containsRef(*pointer.target) {
                throw emitError(self, node, ErrorKind::InvalidRefPosition);
            }
        } else if let case Type::Slice(slice) = ty {
            if containsRef(*slice.item) {
                throw emitError(self, node, ErrorKind::InvalidRefPosition);
            }
        }
    } else if containsRef(ty) {
        throw emitError(self, node, ErrorKind::InvalidRefPosition);
    }
}

/// Require a type that may be stored or escape a call.
fn ensureStorableType(self: *mut Resolver, node: *ast::Node, ty: Type)
    throws (ResolveError)
{
    if containsRef(ty) {
        throw emitError(self, node, ErrorKind::InvalidRefPosition);
    }
}

/// 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);
    }
    try validateValueTypeReferences(self, node, ty);
    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, .. } => {
                    if isGenericDeclaration(sym.node) {
                        throw emitError(self, node, ErrorKind::GenericArgumentsRequired);
                    }
                    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) => {
                    if isGenericDeclaration(sym.node) {
                        throw emitError(self, node, ErrorKind::GenericArgumentsRequired);
                    }
                    return setNodeType(self, node, Type::Nominal(t));
                }
                case SymbolData::TypeParameter(param) => {
                    set *param.used = true;
                    return setNodeType(self, node, Type::Parameter(param));
                }
                case SymbolData::ConstParameter(param) => {
                    set *param.used = true;
                    let ty = param.constType else {
                        throw emitError(self, node, ErrorKind::Internal);
                    };
                    return setNodeType(self, node, *ty);
                }
                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, hint),
        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::FnDecl(decl) => {
            if decl.params.len > 0 {
                throw emitError(self, node, ErrorKind::GenericFnNested);
            }
            throw emitError(self, node, ErrorKind::UnexpectedNode(node));
        }
        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.
            set 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::GenericApply(app) => {
            let fnType = try resolveGenericFnApply(self, node, app, false);
            return setNodeType(self, node, Type::Fn(fnType));
        }
        case ast::NodeValue::Instantiate(_) =>
            throw emitError(self, node, ErrorKind::GenericUnsupported),
        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 } => {
            // TODO: Have easy access to string type.
            try visitOptional(self, message, Type::Slice(SliceType {
                class: types::PointerClass::Owned,
                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);
            // TODO: Have easy access to string type.
            try visitOptional(self, message, Type::Slice(SliceType {
                class: types::PointerClass::Owned,
                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(SliceType {
                class: types::PointerClass::Owned,
                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: false,
                negative: false,
            }));
            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 {
            set 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";
        set 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);
        set bindingTy = declTy;
    } else {
        set bindingTy = try infer(self, decl.value);

        if not isTypeInferrable(bindingTy) {
            throw emitError(self, decl.value, ErrorKind::CannotInferType);
        }
    }
    // Variables cannot have void type.
    if containsRef(bindingTy) {
        throw emitError(self, node, ErrorKind::RefBinding);
    }
    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";
        set 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 an integer literal, optionally under unary negation.
fn isIntegerLiteralExpr(node: *ast::Node) -> bool {
    match node.value {
        case ast::NodeValue::Number(_) => return true,
        case ast::NodeValue::UnOp(unop) => {
            if unop.op == ast::UnaryOp::Neg {
                return isIntegerLiteralExpr(unop.value);
            }
            return false;
        },
        else => return false,
    }
}

/// Determine whether a node represents a compile-time constant expression.
export 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 { .. },
                         SymbolData::ConstParameter(_) => 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 });
}

/// Apply an integer cast to a constant value, including target-width
/// truncation and signed interpretation.
fn castConstInt(value: ConstInt, target: Type) -> ConstValue {
    let raw = constIntToBits(value);
    let range = integerRange(target)
        else panic "castConstInt: expected integer type";

    match range {
        case IntegerRange::Unsigned { bits, .. } =>
            return ConstValue::Int(constIntFromBits(raw, bits, false)),
        case IntegerRange::Signed { bits, .. } =>
            return ConstValue::Int(constIntFromBits(raw, bits, true)),
    }
}

/// Return whether a constant expression depends on a rigid constant parameter.
fn containsGenericConstExpr(self: *Resolver, node: *ast::Node) -> bool {
    match node.value {
        case ast::NodeValue::Ident(_), ast::NodeValue::ScopeAccess(_) => {
            let sym = symbolFor(self, node) else return false;
            if let case SymbolData::ConstParameter(_) = sym.data {
                return true;
            }
            return false;
        }
        case ast::NodeValue::BinOp(binop) =>
            return containsGenericConstExpr(self, binop.left) or
                   containsGenericConstExpr(self, binop.right),
        case ast::NodeValue::UnOp(unop) =>
            return containsGenericConstExpr(self, unop.value),
        case ast::NodeValue::As(expr) =>
            return containsGenericConstExpr(self, expr.value),
        else => return false,
    }
}

/// Evaluate an integer constant expression after replacing rigid parameters.
fn constValueWithSubstitution(
    self: *mut Resolver,
    node: *ast::Node,
    sub: *Substitution,
) -> ?ConstValue {
    if let value = constValueEntry(self, node) {
        return value;
    }
    match node.value {
        case ast::NodeValue::Ident(_), ast::NodeValue::ScopeAccess(_) => {
            let sym = symbolFor(self, node) else return nil;
            let case SymbolData::ConstParameter(param) = sym.data else return nil;
            let arg = substitutionArg(sub, param);
            let case Type::ConstArgument { value, .. } = arg else return nil;
            return ConstValue::Int(value);
        }
        case ast::NodeValue::BinOp(binop) => {
            let left = constValueWithSubstitution(self, binop.left, sub)
                else return nil;
            let right = constValueWithSubstitution(self, binop.right, sub)
                else return nil;
            let case ConstValue::Int(leftInt) = left else return nil;
            let case ConstValue::Int(rightInt) = right else return nil;
            return foldIntBinOp(binop.op, leftInt, rightInt);
        }
        case ast::NodeValue::UnOp(unop) => {
            let value = constValueWithSubstitution(self, unop.value, sub)
                else return nil;
            match unop.op {
                case ast::UnaryOp::Not => {
                    let case ConstValue::Bool(v) = value else return nil;
                    return ConstValue::Bool(not v);
                }
                case ast::UnaryOp::Neg => {
                    let case ConstValue::Int(v) = value else return nil;
                    return constInt(v.magnitude, v.bits, true, not v.negative);
                }
                case ast::UnaryOp::BitNot => {
                    let case ConstValue::Int(v) = value else return nil;
                    return ConstValue::Int(
                        constIntFromSigned(
                            -(constIntToSigned(v) + 1), v.bits, v.signed
                        )
                    );
                }
            }
        }
        case ast::NodeValue::As(expr) => {
            let value = constValueWithSubstitution(self, expr.value, sub)
                else return nil;
            let case ConstValue::Int(v) = value else return nil;
            let target = typeFor(self, node) else return nil;
            if integerRange(target) == nil {
                return nil;
            }
            return castConstInt(v, target);
        }
        else => return nil,
    }
}

/// 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 `constant` 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);
    try ensureStorableType(self, typeNode, bindingTy);
    let valueTy = try checkAssignable(self, valueNode, bindingTy);

    if isConst {
        let mut constVal = constValueEntry(self, valueNode);
        if constVal == nil and not isConstExpr(self, valueNode) {
            throw emitError(self, valueNode, ErrorKind::ConstExprRequired);
        }
        if let val = constVal {
            if let case ConstValue::Int(int) = val; isNumericType(bindingTy) {
                set constVal = castConstInt(int, bindingTy);
            }
        }
        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;
}

/// Bind one declaration's rigid generic parameters in its child scope.
fn resolveGenericParams(
    self: *mut Resolver,
    owner: *ast::Node,
    nodes: *mut [*ast::Node],
) -> *[*GenericParamType] throws (ResolveError) {
    if nodes.len > MAX_GENERIC_PARAMS {
        throw emitError(self, owner, ErrorKind::GenericParameterLimit);
    }
    let a = alloc::arenaAllocator(&mut self.arena);
    let mut result: *mut [*GenericParamType] = &mut [];
    for paramNode, index in nodes {
        let case ast::NodeValue::GenericParam(param) = paramNode.value
            else throw emitError(self, paramNode, ErrorKind::Internal);
        let mut paramName: *[u8] = undefined;
        let mut nameNode: *ast::Node = undefined;
        let mut traitBounds: *mut [*TraitType] = &mut [];
        let mut constType: ?*Type = nil;
        match param {
            case ast::GenericParam::Const { name, type } => {
                set nameNode = name;
                set paramName = try nodeName(self, name);
                let ty = try resolveValueType(self, type);
                if integerRange(ty) == nil or ty == Type::Int {
                    throw emitError(self, type, ErrorKind::GenericConstUnsupported);
                }
                set constType = allocType(self, ty);
            }
            case ast::GenericParam::Type { name, bounds } => {
                set nameNode = name;
                set paramName = try nodeName(self, name);
                for bound in bounds {
                    let boundSym = try resolveNamePath(self, bound);
                    let case SymbolData::Trait(traitInfo) = boundSym.data else {
                        throw emitError(self, bound, ErrorKind::GenericBoundNotTrait);
                    };
                    setNodeSymbol(self, bound, boundSym);
                    traitBounds.append(traitInfo, a);
                }
            }
        }
        let used = try! alloc::alloc(
            &mut self.arena, @sizeOf(bool), @alignOf(bool)
        ) as *mut bool;
        set *used = false;
        let p = try! alloc::alloc(
            &mut self.arena,
            @sizeOf(GenericParamType),
            @alignOf(GenericParamType),
        ) as *mut GenericParamType;
        set *p = GenericParamType {
            owner,
            node: paramNode,
            name: paramName,
            index,
            bounds: &traitBounds[..],
            used,
            constType,
        };
        let data = SymbolData::ConstParameter(p) if constType <> nil
            else SymbolData::TypeParameter(p);
        let sym = try bindIdent(
            self, paramName, paramNode, data, 0, self.scope
        );
        setNodeSymbol(self, nameNode, sym);
        if let ty = constType {
            setNodeType(self, nameNode, *ty);
            setNodeType(self, paramNode, *ty);
        } else {
            setNodeType(self, nameNode, Type::Parameter(p));
            setNodeType(self, paramNode, Type::Parameter(p));
        }
        result.append(p, a);
    }
    return &result[..];
}

/// Retrieve sparse metadata for a generic declaration symbol.
export fn genericTemplateFor(self: *Resolver, symbol: *Symbol) -> ?*GenericTemplate {
    let mut cursor = self.genericTemplates;
    while let entry = cursor {
        if entry.symbol == symbol {
            return &entry.template;
        }
        set cursor = entry.next;
    }
    return nil;
}

/// Retrieve mutable metadata while checking a generic function body.
fn genericTemplateForMut(
    self: *mut Resolver,
    symbol: *Symbol,
) -> ?*mut GenericTemplate {
    let mut cursor = self.genericTemplates;
    while let entry = cursor {
        if entry.symbol == symbol {
            return &mut entry.template;
        }
        set cursor = entry.next;
    }
    return nil;
}

/// Return the generic template whose symbolic body is currently being checked.
fn currentGenericTemplateSymbol(self: *Resolver) -> ?*mut Symbol {
    let current = self.currentFn else return nil;
    let mut cursor = self.genericTemplates;
    while let entry = cursor {
        if let signature = entry.template.signature; signature == current {
            return entry.symbol;
        }
        set cursor = entry.next;
    }
    return nil;
}

/// Attach generic metadata without increasing every symbol's allocation.
fn registerGenericTemplate(
    self: *mut Resolver,
    symbol: *mut Symbol,
    template: GenericTemplate,
) -> *mut GenericTemplate {
    let entry = try! alloc::alloc(
        &mut self.arena,
        @sizeOf(GenericTemplateNode),
        @alignOf(GenericTemplateNode),
    ) as *mut GenericTemplateNode;
    set *entry = GenericTemplateNode {
        symbol,
        template,
        next: self.genericTemplates,
    };
    set self.genericTemplates = entry;
    return &mut entry.template;
}

/// Resolve a function signature type without laying out generic aggregates.
fn resolveFnSignatureType(self: *mut Resolver, node: *ast::Node, generic: bool) -> Type
    throws (ResolveError)
{
    if generic {
        return try resolveGenericValueType(self, node);
    }
    return try infer(self, node);
}

/// Resolve and bind a function parameter using its signature mode.
fn resolveFnSignatureParam(self: *mut Resolver, node: *ast::Node, generic: bool) -> Type
    throws (ResolveError)
{
    if not generic {
        return try infer(self, node);
    }
    let case ast::NodeValue::FnParam(param) = node.value
        else throw emitError(self, node, ErrorKind::Internal);
    let ty = try resolveGenericValueType(self, param.type);
    let _ = try bindValueIdent(self, param.name, node, ty, false, 0, 0);
    return setNodeType(self, node, ty);
}

/// 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);
    if decl.params.len > 0 {
        if self.currentFn <> nil {
            throw emitError(self, node, ErrorKind::GenericFnNested);
        }
        if ast::hasAttribute(attrMask, ast::Attribute::Extern)
            or ast::hasAttribute(attrMask, ast::Attribute::Default)
            or ast::hasAttribute(attrMask, ast::Attribute::Intrinsic)
        {
            throw emitError(self, node, ErrorKind::GenericFnAttribute);
        }
    }
    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, Type::Void),
        throwList: &[],
        isUnsafe: ast::hasAttribute(attrMask, ast::Attribute::Unsafe),
        localCount: 0,
    };
    enterFn(self, node, &fnType);
    let genericParams = try resolveGenericParams(self, node, decl.params) catch e {
        exitFn(self);
        throw e;
    };
    if let retNode = decl.sig.returnType {
        let retTy = try resolveFnSignatureType(
            self, retNode, genericParams.len > 0
        ) catch e {
            exitFn(self);
            throw e;
        };
        try ensureStorableType(self, retNode, retTy) catch e {
            exitFn(self);
            throw e;
        };
        set fnType.returnType = allocType(self, retTy);
    }
    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 resolveFnSignatureParam(
            self, paramNode, genericParams.len > 0
        ) 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 resolveFnSignatureType(
            self, throwNode, genericParams.len > 0
        ) catch e {
            exitFn(self);
            throw e;
        };
        try ensureStorableType(self, throwNode, throwTy) catch e {
            exitFn(self);
            throw e;
        };
        throwList.append(allocType(self, throwTy), a);
    }
    exitFn(self);
    set fnType.paramTypes = &paramTypes[..];
    set fnType.throwList = &throwList[..];

    let fnInfo = allocFnType(self, fnType);
    let ty = Type::Fn(fnInfo);
    let sym = try bindValueIdent(self, decl.name, node, ty, false, 0, attrMask)
        else throw emitError(self, node, ErrorKind::ExpectedIdentifier);
    if genericParams.len > 0 {
        registerGenericTemplate(self, sym, GenericTemplate {
            decl: node,
            params: genericParams,
            signature: fnInfo,
            members: &[],
            declaredLinear: false,
            moduleId: sym.moduleId,
            bodyResolved: false,
            bodyChecks: 0,
        });
    }
    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 generic = genericTemplateForMut(self, sym);
    if let template = generic {
        if template.bodyResolved {
            return;
        }
        set template.bodyResolved = true;
        set template.bodyChecks += 1;
    }
    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);
    let isUnsafe = fnType.isUnsafe;

    if let body = decl.body {
        if isIntrinsic {
            throw emitError(self, node, ErrorKind::IntrinsicUnexpectedBody);
        }
        if isExtern {
            throw emitError(self, node, ErrorKind::FnUnexpectedBody);
        }
        if isUnsafe {
            set self.unsafeDepth += 1;
        }
        enterFn(self, node, fnType); // Enter function scope for body analysis.

        let bodyTy = try checkAssignable(self, body, Type::Void) catch e {
            exitFn(self);
            if isUnsafe { set self.unsafeDepth -= 1; }
            throw e;
        };
        if retTy <> Type::Void and bodyTy <> Type::Never {
            exitFn(self);
            if isUnsafe { set self.unsafeDepth -= 1; }
            throw emitError(self, body, ErrorKind::FnMissingReturn);
        }
        exitFn(self);
        if isUnsafe {
            set self.unsafeDepth -= 1;
        }
        if self.linearEnabled {
            try checkLinearFn(self, nil, decl.sig.params, body);
        }
        if let template = generic {
            for param in template.params {
                if not *param.used {
                    throw emitError(
                        self,
                        param.node,
                        ErrorKind::GenericFnUnusedParameter(param.name),
                    );
                }
            }
        }
    } 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 the compiler-known `Linear` marker from a derive list.
fn resolveLinearDerive(self: *mut Resolver, derives: *mut [*ast::Node]) -> bool
    throws (ResolveError)
{
    let mut linear = false;
    for derive in derives {
        let name = try nodeName(self, derive);
        if mem::eq(name, "Linear") {
            if linear {
                throw emitError(self, derive, ErrorKind::DuplicateBinding(name));
            }
            set linear = true;
            set self.linearEnabled = true;
        } else {
            // Other derives retain their existing trait-name validation.
            try infer(self, derive);
        }
    }
    return linear;
}

/// Resolve a type used in generic data without requiring aggregate layout.
fn resolveGenericValueType(self: *mut Resolver, node: *ast::Node) -> Type
    throws (ResolveError)
{
    let case ast::NodeValue::TypeSig(sig) = node.value
        else return try resolveValueType(self, node);
    let mut ty: Type = undefined;
    match sig {
        case ast::TypeSig::Array { itemType, length } => {
            let item = try resolveGenericValueType(self, itemType);
            let _ = try checkNumeric(self, length);
            if let value = constValueEntry(self, length) {
                if not validateConstIntRange(value, Type::U32) {
                    throw emitError(self, length, ErrorKind::NumericLiteralOverflow);
                }
                let case ConstValue::Int(int) = value
                    else throw emitError(self, length, ErrorKind::ConstExprRequired);
                set ty = Type::Array(ArrayType {
                    item: allocType(self, item),
                    length: int.magnitude as u32,
                });
            } else if isConstExpr(self, length) and
                      containsGenericConstExpr(self, length)
            {
                set ty = Type::GenericArray {
                    item: allocType(self, item),
                    length,
                };
            } else {
                throw emitError(self, length, ErrorKind::ConstExprRequired);
            }
        }
        case ast::TypeSig::Slice { class, itemType, mutable } => {
            let item = try resolveGenericValueType(self, itemType);
            set ty = Type::Slice(SliceType {
                class,
                item: allocType(self, item),
                mutable,
            });
        }
        case ast::TypeSig::Pointer { class, valueType, mutable } => {
            let target = try resolveGenericValueType(self, valueType);
            set ty = Type::Pointer(PointerType {
                class,
                target: allocType(self, target),
                mutable,
            });
        }
        case ast::TypeSig::Optional { valueType } => {
            let payload = try resolveGenericValueType(self, valueType);
            set ty = Type::Optional(allocType(self, payload));
        }
        case ast::TypeSig::Nominal(typeName) => {
            let case ast::NodeValue::GenericApply(app) = typeName.value
                else return try resolveValueType(self, node);
            let templateSym = try resolveGenericDataTarget(self, app.target);
            try ensureGenericDataTemplate(self, templateSym);
            let template = genericTemplateFor(self, templateSym)
                else throw emitError(self, typeName, ErrorKind::Internal);
            if app.args.len <> template.params.len {
                throw emitError(self, typeName, ErrorKind::GenericArgumentCount(
                    CountMismatch {
                        expected: template.params.len,
                        actual: app.args.len,
                    }
                ));
            }
            let a = alloc::arenaAllocator(&mut self.arena);
            let mut args: *mut [*Type] = &mut [];
            for argNode, i in app.args {
                let arg = try resolveGenericArgument(
                    self, argNode, template.params[i]
                );
                args.append(allocType(self, arg), a);
            }
            let symbolic = try! alloc::alloc(
                &mut self.arena,
                @sizeOf(GenericDataApplyType),
                @alignOf(GenericDataApplyType),
            ) as *mut GenericDataApplyType;
            set *symbolic = GenericDataApplyType {
                template: templateSym,
                args: &args[..],
                site: typeName,
            };
            set ty = Type::GenericDataApply(symbolic);
        }
        case ast::TypeSig::Record { fields, labeled } => {
            let a = alloc::arenaAllocator(&mut self.arena);
            let mut result: *mut [RecordField] = &mut [];
            for field in fields {
                let case ast::NodeValue::RecordField {
                    field: fieldNameNode,
                    type: typeNode,
                    value,
                } = field.value else panic "resolveGenericValueType: invalid record field";
                let fieldType = try resolveGenericValueType(self, typeNode);
                try ensureStorableType(self, typeNode, fieldType);
                if let initializer = value {
                    let _ = try checkAssignable(self, initializer, fieldType);
                }
                let mut fieldName: ?*[u8] = nil;
                if let name = fieldNameNode {
                    set fieldName = try nodeName(self, name);
                }
                result.append(RecordField {
                    name: fieldName,
                    fieldType,
                    offset: -1,
                }, a);
            }
            let rec = try! alloc::alloc(
                &mut self.arena,
                @sizeOf(GenericRecordType),
                @alignOf(GenericRecordType),
            ) as *mut GenericRecordType;
            set *rec = GenericRecordType {
                fields: &result[..],
                labeled,
            };
            set ty = Type::GenericRecord(rec);
        }
        case ast::TypeSig::Fn(fnSig) => {
            if fnSig.params.len > MAX_FN_PARAMS {
                throw emitError(self, node, ErrorKind::FnParamOverflow(CountMismatch {
                    expected: MAX_FN_PARAMS,
                    actual: fnSig.params.len,
                }));
            }
            if fnSig.throwList.len > MAX_FN_THROWS {
                throw emitError(self, node, ErrorKind::FnThrowOverflow(CountMismatch {
                    expected: MAX_FN_THROWS,
                    actual: fnSig.throwList.len,
                }));
            }
            let a = alloc::arenaAllocator(&mut self.arena);
            let mut params: *mut [*Type] = &mut [];
            let mut throwTypes: *mut [*Type] = &mut [];
            for param in fnSig.params {
                let paramType = try resolveGenericValueType(self, param);
                params.append(allocType(self, paramType), a);
            }
            for throwNode in fnSig.throwList {
                let throwType = try resolveGenericValueType(self, throwNode);
                try ensureStorableType(self, throwNode, throwType);
                throwTypes.append(allocType(self, throwType), a);
            }
            let mut returnType = allocType(self, Type::Void);
            if let returnNode = fnSig.returnType {
                let resolved = try resolveGenericValueType(self, returnNode);
                try ensureStorableType(self, returnNode, resolved);
                set returnType = allocType(self, resolved);
            }
            set ty = Type::Fn(allocFnType(self, FnType {
                paramTypes: &params[..],
                returnType,
                throwList: &throwTypes[..],
                isUnsafe: false,
                localCount: 0,
            }));
        }
        else => return try resolveValueType(self, node),
    }
    return setNodeType(self, node, ty);
}

/// Resolve symbolic field or variant types for a generic data template.
fn resolveGenericDataTemplate(
    self: *mut Resolver,
    node: *ast::Node,
    params: *mut [*ast::Node],
    members: *mut [*ast::Node],
    derives: *mut [*ast::Node],
    isRecord: bool,
) throws (ResolveError) {
    let sym = symbolFor(self, node) else return;
    if genericTemplateFor(self, sym) <> nil {
        return;
    }
    enterScope(self, node);
    let genericParams = try resolveGenericParams(self, node, params) catch e {
        exitScope(self);
        throw e;
    };
    let declaredLinear = try resolveLinearDerive(self, derives) catch e {
        exitScope(self);
        throw e;
    };
    // Publish the rigid parameters before resolving members so recursive and
    // mutually recursive applications can observe the in-progress template.
    let metadata = registerGenericTemplate(self, sym, GenericTemplate {
        decl: node,
        params: genericParams,
        signature: nil,
        members: &[],
        declaredLinear,
        moduleId: sym.moduleId,
        bodyResolved: true,
        bodyChecks: 0,
    });
    let a = alloc::arenaAllocator(&mut self.arena);
    let mut memberTypes: *mut [*Type] = &mut [];
    for member in members {
        let mut memberTy = Type::Void;
        let mut defaultValue: ?*ast::Node = nil;
        if isRecord {
            let case ast::NodeValue::RecordField { type, value, .. } = member.value
                else panic "resolveGenericDataTemplate: invalid record field";
            set memberTy = try resolveGenericValueType(self, type) catch e {
                exitScope(self);
                throw e;
            };
            set defaultValue = value;
            try ensureStorableType(self, type, memberTy) catch e {
                exitScope(self);
                throw e;
            };
        } else {
            let case ast::NodeValue::UnionDeclVariant(variant) = member.value
                else panic "resolveGenericDataTemplate: invalid union variant";
            if let type = variant.type {
                set memberTy = try resolveGenericValueType(self, type) catch e {
                    exitScope(self);
                    throw e;
                };
                try ensureStorableType(self, type, memberTy) catch e {
                    exitScope(self);
                    throw e;
                };
            }
            set defaultValue = variant.value;
        }
        if let value = defaultValue {
            if isRecord {
                let _ = try checkAssignable(self, value, memberTy) catch e {
                    exitScope(self);
                    throw e;
                };
            } else {
                let _ = try checkNumeric(self, value) catch e {
                    exitScope(self);
                    throw e;
                };
                if constValueEntry(self, value) == nil and
                   (not isConstExpr(self, value) or
                    not containsGenericConstExpr(self, value))
                {
                    exitScope(self);
                    throw emitError(self, value, ErrorKind::ConstExprRequired);
                }
            }
        }
        memberTypes.append(allocType(self, memberTy), a);
    }
    exitScope(self);
    set *metadata = GenericTemplate {
        decl: node,
        params: genericParams,
        signature: nil,
        members: &memberTypes[..],
        declaredLinear,
        moduleId: sym.moduleId,
        bodyResolved: true,
        bodyChecks: 0,
    };
}

/// 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);
        try ensureStorableType(self, typeNode, fieldTy);

        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";
            set 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);
        set currentOffset = mem::alignUp(currentOffset, fieldLayout.alignment);

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

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

        // Track max alignment for record layout.
        set 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,
        declaredLinear: false,
    };
}

/// 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;
    }
    let declaredLinear = try resolveLinearDerive(self, decl.derives);
    let mut recordType = try resolveRecordFields(self, node, decl.fields, decl.labeled);
    set recordType.declaredLinear = declaredLinear;

    set *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],
    node: *ast::Node,
) -> *mut TraitType {
    let p = try! alloc::alloc(&mut self.arena, @sizeOf(TraitType), @alignOf(TraitType));
    let entry = p as *mut TraitType;
    let used = try! alloc::alloc(
        &mut self.arena, @sizeOf(bool), @alignOf(bool)
    ) as *mut bool;
    set *used = false;
    let selfType = try! alloc::alloc(
        &mut self.arena, @sizeOf(GenericParamType), @alignOf(GenericParamType)
    ) as *mut GenericParamType;
    set *selfType = GenericParamType {
        owner: node,
        node,
        name: "Self",
        index: 0,
        bounds: &[],
        used,
        constType: nil,
    };
    set *entry = TraitType {
        name,
        moduleId: self.currentMod,
        nodeId: node.id,
        methods: &mut [],
        supertraits: &mut [],
        selfType,
        state: TraitState::Queued,
        objectSafe: true,
    };
    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, node);
    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.
export 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 one trait signature type with the declaring trait's rigid `Self`.
fn resolveTraitSignatureType(
    self: *mut Resolver,
    traitType: *TraitType,
    node: *ast::Node,
) -> Type throws (ResolveError) {
    let previous = self.currentTraitSelf;
    set self.currentTraitSelf = traitType.selfType;
    let resolved = try resolveValueType(self, node) catch {
        set self.currentTraitSelf = previous;
        throw ResolveError::Failure;
    };
    set self.currentTraitSelf = previous;
    return resolved;
}

/// 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;
    match traitType.state {
        case TraitState::Complete, TraitState::Resolving => return,
        case TraitState::Queued => set traitType.state = TraitState::Resolving,
    }

    // 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);
        // Resolve queued supertraits before consuming their method tables.
        match superTrait.state {
            case TraitState::Queued => {
                let case ast::NodeValue::TraitDecl {
                    supertraits: inheritedTraits, methods: inheritedMethods, ..
                } = superSym.node.value
                    else throw emitError(self, superNode, ErrorKind::Internal);
                try resolveTraitBody(
                    self, superSym.node, inheritedTraits, inheritedMethods
                );
            }
            case TraitState::Resolving => {
                throw emitError(self, superNode, ErrorKind::TraitInheritanceCycle);
            }
            case TraitState::Complete => {}
        }

        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,
                receiverClass: inherited.receiverClass,
                owner: inherited.owner,
                index: traitType.methods.len as u32,
            }, a);
        }
        traitType.supertraits.append(superTrait, a);
        if not superTrait.objectSafe {
            set traitType.objectSafe = false;
        }
    }

    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, attrs } = methodNode.value
            else continue;
        let methodName = try nodeName(self, name);
        let attrMask = resolveAttributes(self, attrs);

        // Reject duplicate method names.
        if let _ = findTraitMethod(traitType, methodName) {
            throw emitError(self, name, ErrorKind::DuplicateBinding(methodName));
        }
        // Determine the receiver class and mutability, and validate that it
        // 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 {
            class: receiverClass, valueType: receiverValueType, mutable,
        } = typeSig
            else throw emitError(self, receiver, ErrorKind::TraitReceiverMismatch);
        let case ast::NodeValue::TypeSig(innerSig) = receiverValueType.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 case ast::NodeValue::FnParam(param) = paramNode.value
                else throw emitError(self, paramNode, ErrorKind::ExpectedIdentifier);
            let paramTy = try resolveTraitSignatureType(self, traitType, param.type);
            paramTypes.append(allocType(self, paramTy), a);
        }
        if let ret = sig.returnType {
            set retType = allocType(
                self, try resolveTraitSignatureType(self, traitType, 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 resolveTraitSignatureType(self, traitType, throwNode);
            throwList.append(allocType(self, throwTy), a);
        }
        let fnType = FnType {
            paramTypes: &paramTypes[..],
            returnType: retType,
            throwList: &throwList[..],
            isUnsafe: ast::hasAttribute(attrMask, ast::Attribute::Unsafe),
            localCount: 0,
        };
        if containsGenericParameter(Type::Fn(&fnType)) {
            set traitType.objectSafe = false;
        }
        traitType.methods.append(TraitMethod {
            name: methodName,
            fnType: allocFnType(self, fnType),
            mutable,
            receiverClass,
            owner: traitType,
            index: traitType.methods.len as u32,
        }, a);

        setNodeType(self, methodNode, Type::Void);
    }
    set traitType.state = TraitState::Complete;
}

/// 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);

    // Resolve a concrete target type, including built-in scalar types.
    let concreteType = try resolveValueType(self, targetType);
    if containsGenericParameter(concreteType) {
        throw emitError(self, targetType, ErrorKind::InvalidInstanceTarget);
    }
    if let case Type::Nominal(nominalTy) = concreteType {
        try ensureNominalResolved(self, nominalTy, targetType);
    }
    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,
        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, attrs,
        } = methodNode.value else continue;

        let methodName = try nodeName(self, name);
        let attrMask = resolveAttributes(self, attrs);

        // Find the matching trait method.
        let tm = findTraitMethod(traitInfo, methodName)
            else throw emitError(self, name, ErrorKind::UnresolvedSymbol(methodName));
        if tm.owner <> traitInfo {
            throw emitError(self, name, ErrorKind::InheritedTraitMethod(methodName));
        }
        let selfArg = allocType(self, concreteType);
        let selfParams: [*GenericParamType; 1] = [tm.owner.selfType];
        let selfArgs: [*Type; 1] = [selfArg];
        let selfSub = Substitution {
            params: &selfParams[..],
            args: &selfArgs[..],
        };
        let concreteMethodType = try substituteType(
            self, Type::Fn(tm.fnType), &selfSub, methodNode
        );
        let case Type::Fn(expectedFn) = concreteMethodType
            else throw emitError(self, methodNode, ErrorKind::Internal);
        let instanceUnsafe = ast::hasAttribute(attrMask, ast::Attribute::Unsafe);
        if instanceUnsafe <> tm.fnType.isUnsafe {
            throw emitError(self, methodNode, ErrorKind::TraitMethodSafetyMismatch);
        }

        // 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 {
            class: receiverClass, valueType, mutable: receiverMut,
        } = typeSig
            else throw emitError(self, receiverType, ErrorKind::TraitReceiverMismatch);
        if receiverClass <> tm.receiverClass {
            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(PointerType {
            class: receiverClass,
            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 <> expectedFn.paramTypes.len {
            throw emitError(self, methodNode, ErrorKind::FnArgCountMismatch(CountMismatch {
                expected: expectedFn.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, *expectedFn.paramTypes[j]) {
                throw emitTypeMismatch(self, paramNode, TypeMismatch {
                    expected: *expectedFn.paramTypes[j],
                    actual: instanceParamTy,
                });
            }
        }
        let mut instanceRetTy = Type::Void;
        if let retNode = sig.returnType {
            set instanceRetTy = try resolveValueType(self, retNode);
        }
        if not typesEqual(instanceRetTy, *expectedFn.returnType) {
            throw emitTypeMismatch(self, methodNode, TypeMismatch {
                expected: *expectedFn.returnType,
                actual: instanceRetTy,
            });
        }
        if sig.throwList.len <> expectedFn.throwList.len {
            throw emitError(self, methodNode, ErrorKind::FnThrowCountMismatch(CountMismatch {
                expected: expectedFn.throwList.len as u32,
                actual: sig.throwList.len,
            }));
        }
        for throwNode, j in sig.throwList {
            let instanceThrowTy = try resolveValueType(self, throwNode);
            if not typesEqual(instanceThrowTy, *expectedFn.throwList[j]) {
                throw emitTypeMismatch(self, throwNode, TypeMismatch {
                    expected: *expectedFn.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 expectedFn.paramTypes {
            paramTypes.append(ty, a);
        }
        let fnType = FnType {
            paramTypes: &paramTypes[..],
            returnType: expectedFn.returnType,
            throwList: expectedFn.throwList,
            isUnsafe: expectedFn.isUnsafe,
            localCount: 0,
        };

        // 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, attrMask);

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

        // Store in instance entry at the matching v-table slot.
        set entry.methods[tm.index] = sym;
        set 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] {
                set entry.methods[merged.index] = superInst.methods[mi];
                set 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));
        }
    }
    set self.instances[self.instancesLen] = entry;
    set 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";
    let isUnsafe = fnType.isUnsafe;
    if isUnsafe {
        set self.unsafeDepth += 1;
    }

    // Enter function scope.
    enterFn(self, node, fnType);

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

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

/// Resolve a standalone method declaration (signature only).
/// Validates the receiver type and registers the method in the method table.

/// Resolve and register a standalone method declaration.
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(receiver) = fullReceiverTy
        else throw emitError(self, receiverType, ErrorKind::TraitReceiverMismatch);
    let concreteType = *receiver.target;
    let case Type::Nominal(nominalTy) = concreteType
        else throw emitError(self, receiverType, ErrorKind::ExpectedRecord);
    try ensureNominalResolved(self, nominalTy, receiverType);

    let methodName = try nodeName(self, name);
    let attrMask = resolveAttributes(self, attrs);

    // 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(PointerType {
        class: receiver.class,
        target: allocType(self, concreteType),
        mutable: receiver.mutable,
    });
    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 {
        set 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(attrMask, ast::Attribute::Unsafe);
    // Full function type (receiver + params) for lowering.
    let fullFnType = FnType {
        paramTypes: &paramTypes[..],
        returnType: retTypePtr,
        throwList,
        isUnsafe,
        localCount: 0,
    };
    let fnTy = Type::Fn(allocFnType(self, fullFnType));

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

    // 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);
    }
    set self.methods[self.methodsLen] = MethodEntry {
        concreteType,
        name: methodName,
        fnType: allocFnType(self, checkFnType),
        mutable: receiver.mutable,
        receiverClass: receiver.class,
        symbol: sym,
    };
    set self.methodsLen += 1;
}

/// Look up an instance entry by trait and concrete type.
export 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.
export 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.
export 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.
    let declaredLinear = try resolveLinearDerive(self, decl.derives);
    set *nominalTy = NominalType::Union(UnionType {
        variants: &[],
        layout: Layout { size: 0, alignment: 0 },
        valOffset: 0,
        isAllVoid: true,
        declaredLinear,
    });

    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 typeNode = variantDecl.type {
            set variantType = try infer(self, typeNode);
            try ensureStorableType(self, typeNode, variantType);
        }
        // Process the variant's explicit discriminant value if present.
        if let value = variantDecl.value {
            let _ = try checkSizeInt(self, value);
        }
        let tag = try variantTag(self, variantDecl, &mut iota, nil);
        // 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.
    set *nominalTy = NominalType::Union(UnionType {
        variants: &variants[..],
        layout: info.layout,
        valOffset: info.valOffset,
        isAllVoid: info.isAllVoid,
        declaredLinear,
    });
}

/// 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::Export) {
                if let existing = findSymbolInScope(self.scope, sym.name) {
                    if existing == sym {
                        continue;
                    }
                }
                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 elseTy = try infer(self, cond.elseExpr);

    // Either branch may supply the concrete type for an otherwise context-
    // dependent expression, such as an unsuffixed integer or `nil`.
    if let coercion = isAssignable(self, thenTy, elseTy, cond.elseExpr) {
        setNodeCoercion(self, cond.elseExpr, coercion);
        return setNodeType(self, node, thenTy);
    }
    if let coercion = isAssignable(self, elseTy, thenTy, cond.thenExpr) {
        setNodeCoercion(self, cond.thenExpr, coercion);
        return setNodeType(self, node, elseTy);
    }
    try expectAssignable(self, thenTy, elseTy, cond.elseExpr);

    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.
export 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) {
    if let case Type::Pointer(pointer) = scrutineeTy; isDestructuringPattern(pattern) {
        try resolveCasePattern(self, pattern, *pointer.target, mode, matchBy);
        return;
    }
    // TODO: Collapse these nested matches.
    match scrutineeTy {
        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 {
        set bindingName = name;
    }
    let mut indexName: ?*[u8] = nil;
    if let idx = forStmt.index {
        if let case ast::NodeValue::Ident(name) = idx.value {
            set indexName = name;
        }
    }
    // Extract item type and store pre-computed loop metadata for the lowerer.
    let mut itemTy: Type = undefined;
    match iterableTy {
        case Type::Slice(slice) => {
            set itemTy = *slice.item;
            setForLoopInfo(self, node, ForLoopInfo::Collection {
                elemType: slice.item, length: nil, bindingName, indexName
            });
        }
        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);
            };
            set itemTy = *valType;

            setForLoopInfo(self, node, ForLoopInfo::Range {
                valType, range, bindingName, indexName
            });
        }
        case Type::Array(arrayInfo) => {
            set itemTy = *arrayInfo.item;
            setForLoopInfo(self, node, ForLoopInfo::Collection {
                elemType: arrayInfo.item,
                length: arrayInfo.length,
                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 {
        set 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.
export 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 {
        set state.isConst = false;
    } else {
        match prong.arm {
            case ast::ProngArm::Binding(_),
                 ast::ProngArm::Else => set isCatchAll = true,
            case ast::ProngArm::Case(patterns) => set isCatchAll = hasWildcardPattern(patterns),
        }
    }
    if isCatchAll {
        if state.catchAll {
            throw emitError(self, prongNode, ErrorKind::DuplicateCatchAll);
        }
        set 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, subject.by);
    } 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,
    matchBy: MatchBy
) -> 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";

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

        // 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);
                }
                set 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);
                        }
                        set 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";

        set 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);
                            }
                            set covered[ix] = true;
                            set 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";

        set 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 {
                            set hasTrue = true;
                        } else {
                            set 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(_) =>
                            set hasConstCase = true,
                        else =>
                            set 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 {
                set 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 => set bindTy = Type::Pointer(PointerType {
            class: types::PointerClass::Ref,
            target: allocType(self, ty),
            mutable: false,
        }),
        case MatchBy::MutRef => set bindTy = Type::Pointer(PointerType {
            class: types::PointerClass::Ref,
            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,
            });
        }
    }
}

/// Return whether a case pattern introduces value bindings.
fn casePatternIntroducesBindings(pattern: *ast::Node, nested: bool) -> bool {
    match pattern.value {
        case ast::NodeValue::Ident(_) => return nested,
        case ast::NodeValue::Call(call) => {
            for arg in call.args {
                if casePatternIntroducesBindings(arg, true) {
                    return true;
                }
            }
        }
        case ast::NodeValue::RecordLit(lit) => {
            for fieldNode in lit.fields {
                let case ast::NodeValue::RecordLitField(field) = fieldNode.value
                    else continue;
                if casePatternIntroducesBindings(field.value, true) {
                    return true;
                }
            }
        }
        case ast::NodeValue::ArrayLit(items) => {
            for item in items {
                if casePatternIntroducesBindings(item, true) {
                    return true;
                }
            }
        }
        else => {}
    }
    return false;
}

/// 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 supplies the binding when the optional is nil.
            try checkAssignable(self, letElse.elseBranch, payloadTy);
            return setNodeType(self, node, Type::Void);
        }
        case ast::PatternKind::Case => {
            // Resolve the failure path before introducing success-only bindings.
            let elseTy = try checkAssignable(self, letElse.elseBranch, exprTy);
            try resolveCasePattern(
                self,
                pat.pattern,
                exprTy,
                IdentMode::Compare,
                MatchBy::Value,
            );
            if let guardExpr = pat.guard {
                try checkBoolean(self, guardExpr);
            }
            if elseTy <> Type::Never and
               casePatternIntroducesBindings(pat.pattern, false)
            {
                throw emitError(
                    self,
                    letElse.elseBranch,
                    ErrorKind::LinearLetElseMustTerminate,
                );
            }
        }
    }
    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(ptr) = 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(SliceType {
            class: ptr.class,
            item: ptr.target,
            mutable: ptr.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]);
    if containsGenericParameter(ty) {
        throw emitError(self, args[0], ErrorKind::GenericLayoutRequired);
    }
    // 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 => {
            set value = layout.size;
        },
        case ast::Builtin::AlignOf => {
            set 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);
    }
}

/// Unify one symbolic parameter type with exact call-site evidence.
fn inferGenericArgument(
    self: *mut Resolver,
    pattern: Type,
    actual: Type,
    params: *[*GenericParamType],
    inferred: *mut [?*Type],
) -> bool {
    if let case Type::Parameter(param) = pattern {
        let mut evidence = actual;
        match actual {
            case Type::Unknown, Type::Nil, Type::Undefined => return true,
            case Type::Int => set evidence = Type::I64,
            else => {},
        }
        for candidate, i in params {
            if candidate == param {
                if let prior = inferred[i] {
                    return typesEqual(*prior, evidence);
                }
                set inferred[i] = allocType(self, evidence);
                return true;
            }
        }
        return typesEqual(pattern, evidence);
    }
    if typesEqual(pattern, actual) {
        return true;
    }
    if not containsGenericParameter(pattern) {
        return true;
    }
    match pattern {
        case Type::Pointer(pointer) => {
            let case Type::Pointer(actualPointer) = actual else return false;
            return pointer.class == actualPointer.class
                and pointer.mutable == actualPointer.mutable
                and inferGenericArgument(
                    self,
                    *pointer.target,
                    *actualPointer.target,
                    params,
                    inferred,
                );
        }
        case Type::Slice(slice) => {
            let case Type::Slice(actualSlice) = actual else return false;
            return slice.class == actualSlice.class
                and slice.mutable == actualSlice.mutable
                and inferGenericArgument(
                    self,
                    *slice.item,
                    *actualSlice.item,
                    params,
                    inferred,
                );
        }
        case Type::Optional(inner) => {
            let case Type::Optional(actualInner) = actual else return false;
            return inferGenericArgument(
                self, *inner, *actualInner, params, inferred
            );
        }
        case Type::Array(array) => {
            let case Type::Array(actualArray) = actual else return false;
            return array.length == actualArray.length and inferGenericArgument(
                self, *array.item, *actualArray.item, params, inferred
            );
        }
        case Type::GenericDataApply(application) => {
            let case Type::Nominal(nominal) = actual else return false;
            let concrete = genericDataSpecializationForNominal(self, nominal)
                else return false;
            if concrete.template <> application.template
                or concrete.args.len <> application.args.len
            {
                return false;
            }
            for arg, i in application.args {
                if not inferGenericArgument(
                    self, *arg, *concrete.args[i], params, inferred
                ) {
                    return false;
                }
            }
            return true;
        }
        else => return false,
    }
}

/// Infer and resolve a direct call to a generic function template.
fn resolveInferredGenericCall(
    self: *mut Resolver,
    callee: *ast::Node,
    call: ast::Call,
    expected: Type,
) -> ?*FnType throws (ResolveError) {
    let templateSym = findGenericCandidateSymbol(self, callee) else return nil;
    let template = genericTemplateFor(self, templateSym) else return nil;
    let signature = template.signature else return nil;
    if call.args.len <> signature.paramTypes.len {
        return nil;
    }
    let mut inferred: [?*Type; MAX_FN_PARAMS] = undefined;
    for i in 0..inferred.len {
        set inferred[i] = nil;
    }
    for argNode, i in call.args {
        let actual = try infer(self, argNode);
        if not inferGenericArgument(
            self,
            *signature.paramTypes[i],
            actual,
            template.params,
            &mut inferred[..],
        ) {
            throw emitError(self, argNode, ErrorKind::GenericInferenceConflict);
        }
    }
    if expected <> Type::Unknown and expected <> Type::Void and not inferGenericArgument(
        self,
        *signature.returnType,
        expected,
        template.params,
        &mut inferred[..],
    ) {
        throw emitError(self, callee, ErrorKind::GenericInferenceConflict);
    }
    let a = alloc::arenaAllocator(&mut self.arena);
    let mut args: *mut [*Type] = &mut [];
    for _, i in template.params {
        let arg = inferred[i] else {
            throw emitError(
                self, callee, ErrorKind::GenericInferenceIncomplete
            );
        };
        args.append(arg, a);
    }
    for arg, i in args {
        if not containsGenericParameter(*arg) {
            for bound in template.params[i].bounds {
                if findInstance(self, bound, *arg) == nil {
                    throw emitError(
                        self,
                        callee,
                        ErrorKind::GenericBoundUnsatisfied(bound.name),
                    );
                }
            }
        }
    }
    let sub = Substitution { params: template.params, args: &args[..] };
    let applied = try substituteType(self, Type::Fn(signature), &sub, callee);
    let case Type::Fn(appliedFn) = applied
        else throw emitError(self, callee, ErrorKind::Internal);
    let caller = currentGenericTemplateSymbol(self);
    if caller == nil {
        if let existing = findGenericFnSpecialization(
            self, templateSym, &args[..]
        ) {
            setNodeSymbol(self, callee, templateSym);
            setNodeType(self, callee, Type::Fn(existing.fnType));
            set self.nodeData.entries[callee.id].extra =
                NodeExtra::GenericFnCall(existing);
            return existing.fnType;
        }
    }
    recordGenericFnDependency(
        self, callee, caller, templateSym, &args[..], appliedFn
    );
    return appliedFn;
}

/// Resolve `Trait::method(receiver, ...)` for a rigid bounded parameter.
fn resolveQualifiedGenericBoundCall(
    self: *mut Resolver,
    node: *ast::Node,
    call: ast::Call,
    ctx: CallCtx,
) -> ?Type throws (ResolveError) {
    let case ast::NodeValue::ScopeAccess(access) = call.callee.value
        else return nil;
    if currentGenericTemplateSymbol(self) == nil or call.args.len == 0 {
        return nil;
    }
    let traitSym = try resolveNamePath(self, access.parent);
    let case SymbolData::Trait(traitInfo) = traitSym.data else return nil;
    let receiverTy = try infer(self, call.args[0]);
    let case Type::Pointer(receiver) = receiverTy else return nil;
    let case Type::Parameter(param) = *receiver.target else return nil;
    let mut hasBound = false;
    for bound in param.bounds {
        if bound == traitInfo {
            set hasBound = true;
            break;
        }
    }
    if not hasBound {
        return nil;
    }
    if isUnsafePointerType(receiverTy) {
        try requireUnsafe(self, call.args[0]);
    }
    let methodName = try nodeName(self, access.child);
    let method = findTraitMethod(traitInfo, methodName)
        else throw emitError(
            self, access.child, ErrorKind::RecordFieldUnknown(methodName)
        );
    if method.mutable and not receiver.mutable {
        throw emitError(self, call.args[0], ErrorKind::ImmutableBinding);
    }
    let selfParam: [*GenericParamType; 1] = [method.owner.selfType];
    let selfArg: [*Type; 1] = [allocType(self, Type::Parameter(param))];
    let sub = Substitution {
        params: &selfParam[..],
        args: &selfArg[..],
    };
    let substituted = try substituteType(
        self, Type::Fn(method.fnType), &sub, node
    );
    let case Type::Fn(methodFn) = substituted
        else throw emitError(self, node, ErrorKind::Internal);
    let a = alloc::arenaAllocator(&mut self.arena);
    let mut params: *mut [*Type] = &mut [];
    params.append(allocType(self, receiverTy), a);
    for methodParam in methodFn.paramTypes {
        params.append(methodParam, a);
    }
    let fullFn = allocFnType(self, FnType {
        paramTypes: &params[..],
        returnType: methodFn.returnType,
        throwList: methodFn.throwList,
        isUnsafe: methodFn.isUnsafe,
        localCount: 0,
    });
    try checkUnsafeCall(self, call.callee, fullFn);
    try checkCallArgs(self, node, call, fullFn, ctx);
    setNodeSymbol(self, access.parent, traitSym);
    setNodeType(self, call.callee, Type::Fn(fullFn));
    setGenericBoundMethodCall(
        self, node, param, traitInfo, method.index, true
    );
    return setNodeType(self, node, *methodFn.returnType);
}

/// Analyze a function call expression.
fn resolveCall(
    self: *mut Resolver,
    node: *ast::Node,
    call: ast::Call,
    ctx: CallCtx,
    expected: Type,
) -> 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);
        if isUnsafePointerType(parentTy) {
            try requireUnsafe(self, access.parent);
        }

        let subjectTy = autoDeref(parentTy);

        if let case Type::Slice(slice) = subjectTy {
            let methodName = try nodeName(self, access.child);
            if methodName == "append" {
                return try resolveSliceAppend(
                    self, node, access.parent, parentTy, call.args, slice.item, slice.mutable
                );
            }
            if methodName == "delete" {
                return try resolveSliceDelete(
                    self, node, access.parent, call.args, slice.item, slice.mutable
                );
            }
        }
    }
    if let bounded = try resolveQualifiedGenericBoundCall(
        self, node, call, ctx
    ) {
        return bounded;
    }
    if let inferred = try resolveInferredGenericCall(
        self, call.callee, call, expected
    ) {
        try checkUnsafeCall(self, call.callee, inferred);
        try checkCallArgs(self, node, call, inferred, ctx);
        return setNodeType(self, node, *inferred.returnType);
    }
    let calleeTy = try infer(self, call.callee);
    if let case Type::Fn(info) = calleeTy {
        try checkUnsafeCall(self, call.callee, info);
    }

    // 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 { .. } = calleeSym.data {
            let case Type::Nominal(unionType) = calleeTy
                else throw emitError(self, call.callee, ErrorKind::Internal);
            return try resolveUnionConstructorCall(self, node, call, unionType);
        }
        // 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) {
            set parentTy = t;
        }
        let subjectTy = autoDeref(parentTy);

        if let case Type::Parameter(param) = subjectTy; param.bounds.len > 0 {
            let methodName = try nodeName(self, access.child);
            let selected = try findGenericBoundMethod(
                self, access.child, param, methodName
            );
            let case Type::Fn(info) = calleeTy
                else throw emitError(self, call.callee, ErrorKind::Internal);
            if selected.method.mutable {
                let mut isMutPtr = false;
                if let case Type::Pointer(pointer) = parentTy {
                    set isMutPtr = pointer.mutable;
                }
                if not isMutPtr and not (try canBorrowMutFrom(self, access.parent)) {
                    throw emitError(self, access.parent, ErrorKind::ImmutableBinding);
                }
            }
            try checkUnsafeCall(self, call.callee, info);
            try checkCallArgs(self, node, call, info, ctx);
            setGenericBoundMethodCall(
                self,
                node,
                param,
                selected.traitInfo,
                selected.method.index,
                false,
            );
            return setNodeType(self, node, *info.returnType);
        }

        if let case Type::TraitObject(traitObject) = subjectTy {
            let methodName = try nodeName(self, access.child);
            let method = findTraitMethod(traitObject.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 traitObject.mutable {
                throw emitError(self, access.parent, ErrorKind::ImmutableBinding);
            }
            try checkCallArgs(self, node, call, method.fnType, ctx);
            setTraitMethodCall(self, node, traitObject.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(pointer) = parentTy {
                        set isMutPtr = pointer.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);
                set 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);
    set 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);
    set 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;

            if let case Type::Slice(slice) = subjectTy {
                if not slice.mutable {
                    throw emitError(self, container, ErrorKind::ImmutableBinding);
                }
                set item = slice.item;
            } else {
                match subjectTy {
                    case Type::Array(a) => {
                        try validateArraySliceBounds(self, range, a.length, node);
                        set item = a.item;
                        set capacity = a.length;
                    }
                    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(source) = rhsTy {
                if *source.item <> *item {
                    throw emitTypeMismatch(
                        self,
                        assign.right,
                        TypeMismatch { expected: *item, actual: *source.item },
                    );
                }
            } 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) {
            set startVal = val;
        }
    }
    if let endNode = range.end {
        if let val = constSliceIndex(self, endNode) {
            set 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);
    if isUnsafePointerType(containerTy) {
        try requireUnsafe(self, container);
    }
    try checkIndex(self, indexNode);
    let subjectTy = autoDeref(containerTy);
    if let case Type::Slice(slice) = subjectTy {
        return setNodeType(self, node, *slice.item);
    }

    match subjectTy {
        case Type::Array(arrayInfo) => {
            return setNodeType(self, node, *arrayInfo.item);
        }
        case Type::GenericArray { 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, ordinal, index, .. } = sym.data {
            let resolved = typeFor(self, typeIdent)
                else throw emitError(self, node, ErrorKind::Internal);
            let case Type::Nominal(unionNominalType) = resolved
                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 {
        set 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 {
            set 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 {
        set expectedTy = *ary.item;
    } else if let case Type::Optional(inner) = hint {
        if let case Type::Array(ary) = *inner {
            set 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 {
            set 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 {
        set itemHint = *ary.item;
    } else if let case Type::GenericArray { item, .. } = hint {
        set itemHint = *item;
    } else if let case Type::Optional(inner) = hint {
        if let case Type::Array(ary) = *inner {
            set itemHint = *ary.item;
        }
    }
    let valueTy = try visit(self, lit.item, itemHint);
    let _ = try checkNumeric(self, lit.count);
    let mut arrayTy: Type = undefined;
    if let value = constValueEntry(self, lit.count) {
        if not validateConstIntRange(value, Type::U32) {
            throw emitError(self, lit.count, ErrorKind::NumericLiteralOverflow);
        }
        let case ConstValue::Int(int) = value
            else throw emitError(self, lit.count, ErrorKind::ConstExprRequired);
        set arrayTy = Type::Array(ArrayType {
            item: allocType(self, valueTy),
            length: int.magnitude as u32,
        });
    } else if isConstExpr(self, lit.count) and
              containsGenericConstExpr(self, lit.count)
    {
        set arrayTy = Type::GenericArray {
            item: allocType(self, valueTy),
            length: lit.count,
        };
    } else {
        throw emitError(self, lit.count, ErrorKind::ConstExprRequired);
    }
    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, .. } => {
            if isGenericDeclaration(sym.node) {
                throw emitError(self, node, ErrorKind::GenericArgumentsRequired);
            }
            setNodeSymbol(self, node, sym);
            set ty = type;
        }
        case SymbolData::Constant { type, value } => {
            // Propagate the constant value.
            if let val = value {
                setNodeConstValue(self, node, val);
            }
            setNodeSymbol(self, node, sym);
            set ty = type;
        }
        case SymbolData::Type(t) => {
            if isGenericDeclaration(sym.node) {
                throw emitError(self, node, ErrorKind::GenericArgumentsRequired);
            }
            setNodeSymbol(self, node, sym);
            set ty = Type::Nominal(t);
        }
        case SymbolData::TypeParameter(param) => {
            set *param.used = true;
            setNodeSymbol(self, node, sym);
            set ty = Type::Parameter(param);
        }
        case SymbolData::ConstParameter(param) => {
            set *param.used = true;
            setNodeSymbol(self, node, sym);
            let constType = param.constType
                else throw emitError(self, node, ErrorKind::Internal);
            set ty = *constType;
        }
        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);
}

/// A uniquely selected method exposed by a generic parameter bound.
record GenericBoundMethod {
    traitInfo: *TraitType,
    method: *TraitMethod,
}

/// Find one bound method, rejecting ambiguous unqualified selections.
fn findGenericBoundMethod(
    self: *mut Resolver,
    node: *ast::Node,
    param: *GenericParamType,
    name: *[u8],
) -> GenericBoundMethod throws (ResolveError) {
    let mut found: ?GenericBoundMethod = nil;
    for bound in param.bounds {
        if let method = findTraitMethod(bound, name) {
            if found <> nil {
                throw emitError(self, node, ErrorKind::GenericBoundAmbiguous(name));
            }
            set found = GenericBoundMethod { traitInfo: bound, method };
        }
    }
    let result = found else throw emitError(
        self, node, ErrorKind::RecordFieldUnknown(name)
    );
    return result;
}

/// 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);
    if isUnsafePointerType(parentTy) {
        try requireUnsafe(self, access.parent);
    }
    let subjectTy = autoDeref(parentTy);
    if let case Type::Slice(slice) = subjectTy {
        let fieldNode = access.child;
        let fieldName = try nodeName(self, fieldNode);
        if mem::eq(fieldName, PTR_FIELD) {
            setRecordFieldIndex(self, fieldNode, 0);
            return setNodeType(
                self,
                node,
                Type::Pointer(PointerType {
                    class: slice.class,
                    target: slice.item,
                    mutable: slice.mutable,
                }),
            );
        }
        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));
    }
    if let case Type::TraitObject(traitObject) = subjectTy {
        let fieldName = try nodeName(self, access.child);
        let method = findTraitMethod(traitObject.traitInfo, fieldName)
            else throw emitError(self, node, ErrorKind::RecordFieldUnknown(fieldName));
        return setNodeType(self, node, Type::Fn(method.fnType));
    }

    match subjectTy {
        case Type::Parameter(param) if param.bounds.len > 0 => {
            let fieldName = try nodeName(self, access.child);
            let selected = try findGenericBoundMethod(
                self, access.child, param, fieldName
            );
            let selfParam: [*GenericParamType; 1] = [selected.method.owner.selfType];
            let selfArg: [*Type; 1] = [allocType(self, Type::Parameter(param))];
            let sub = Substitution {
                params: &selfParam[..],
                args: &selfArg[..],
            };
            let methodType = try substituteType(
                self, Type::Fn(selected.method.fnType), &sub, node
            );
            return setNodeType(self, node, methodType);
        }
        case Type::GenericDataApply(application) => {
            let template = genericTemplateFor(self, application.template)
                else throw emitError(self, node, ErrorKind::Internal);
            let case ast::NodeValue::RecordDecl(decl) = application.template.node.value
                else throw emitError(self, access.parent, ErrorKind::ExpectedRecord);
            let fieldName = try nodeName(self, access.child);
            for fieldNode, index in decl.fields {
                let case ast::NodeValue::RecordField { field: maybeField, .. } =
                    fieldNode.value
                    else throw emitError(self, node, ErrorKind::Internal);
                let fieldNodeName = maybeField
                    else throw emitError(self, fieldNode, ErrorKind::Internal);
                let candidate = try nodeName(self, fieldNodeName);
                if mem::eq(candidate, fieldName) {
                    let sub = Substitution {
                        params: template.params,
                        args: application.args,
                    };
                    let fieldType = try substituteType(
                        self, *template.members[index], &sub, node
                    );
                    setRecordFieldIndex(self, access.child, index);
                    return setNodeType(self, node, fieldType);
                }
            }
            throw emitError(self, node, ErrorKind::RecordFieldUnknown(fieldName));
        }
        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::GenericArray { .. } => {
            let fieldName = try nodeName(self, access.child);
            if mem::eq(fieldName, LEN_FIELD) {
                return setNodeType(self, node, Type::U32);
            }
            throw emitError(self, node, ErrorKind::ArrayFieldUnknown(fieldName));
        }
        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(pointer) = ty {
                return pointer.mutable;
            }
            if let case Type::Slice(slice) = ty {
                return slice.mutable;
            }
            return false;
        }
        case ast::NodeValue::FieldAccess(access) => {
            let _ = try infer(self, access.parent);
            return try canBorrowMutFrom(self, access.parent);
        }
        case ast::NodeValue::ScopeAccess(_) => {
            // Module-qualified access to a top-level symbol. A `static`
            // binds as a mutable value; a `constant` does not.
            let _ = try infer(self, node);
            let sym = nodeData(self, node).sym
                else return false;

            if let case SymbolData::Value { mutable, .. } = sym.data {
                return mutable;
            }
            return false;
        }
        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(slice) = subjectTy {
                return slice.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::Call(_) => {
            // A call returning `*mut T` (or `&mut [T]`) yields a
            // mutable place. Non-pointer returns cannot be mutably borrowed.
            let ty = try infer(self, node);
            if let case Type::Pointer(pointer) = ty {
                return pointer.mutable;
            }
            if let case Type::Slice(slice) = ty {
                return slice.mutable;
            }
            return false;
        }
        case ast::NodeValue::Deref(inner) => {
            let innerTy = try infer(self, inner);

            if let case Type::Pointer(pointer) = innerTy {
                return pointer.mutable;
            }
            if let case Type::Slice(slice) = innerTy {
                return slice.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)
{
    // Linear source treats every address expression as a call-scoped reference.
    // Legacy packages keep their historical owning-address inference.
    let class = types::PointerClass::Ref
        if self.linearEnabled or isRefType(hint)
        else types::PointerClass::Owned;
    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;

            if let case Type::Slice(slice) = subjectTy {
                if addr.mutable and not slice.mutable {
                    throw emitError(self, addr.target, ErrorKind::ImmutableBinding);
                }
                set item = slice.item;
            } else {
                match subjectTy {
                    case Type::Array(arrayInfo) => {
                        try validateArraySliceBounds(self, range, arrayInfo.length, node);
                        set item = arrayInfo.item;
                        set capacity = arrayInfo.length;
                    }
                    else => {
                        throw emitError(self, container, ErrorKind::ExpectedIndexable);
                    }
                }
            }
            let sliceTy = Type::Slice(SliceType {
                class,
                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(slice) = hint {
        set targetHint = Type::Array(ArrayType { item: slice.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, .. } => {
                    set *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(SliceType {
                    class,
                    item: arrayInfo.item,
                    mutable: addr.mutable,
                });
                return setNodeType(self, node, *allocType(self, sliceTy));
            }
            else => {}
        }
    }
    let pointerTy = Type::Pointer(PointerType {
        class,
        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(pointer) = operandTy {
        if pointer.class == types::PointerClass::Unsafe {
            try requireUnsafe(self, targetNode);
        }
        // Disallow dereferencing opaque pointers.
        if *pointer.target == Type::Opaque {
            throw emitError(self, targetNode, ErrorKind::OpaqueTypeDeref);
        }
        return setNodeType(self, node, *pointer.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(pointer) = ty {
        return *pointer.target == Type::Opaque;
    }
    return false;
}

/// Check if a type is an opaque slice.
fn isOpaqueSlice(ty: Type) -> bool {
    if let case Type::Slice(slice) = ty {
        return *slice.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 pointer casts if one side is `*opaque` or target types are castable.
    if let case Type::Pointer(sourcePointer) = source {
        if let case Type::Pointer(targetPointer) = target {
            if sourcePointer.class <> targetPointer.class {
                return false;
            }
            if targetPointer.mutable and not sourcePointer.mutable {
                return false;
            }
            if isOpaquePointer(source) or isOpaquePointer(target) {
                return true;
            }
            return isValidCast(*sourcePointer.target, *targetPointer.target);
        }
    }
    // Allow slice casts if one side is `*[opaque]`, target is `*[u8]`,
    // or element types are castable.
    if let case Type::Slice(sourceSlice) = source {
        if let case Type::Slice(targetSlice) = target {
            if sourceSlice.class <> targetSlice.class {
                return false;
            }
            if targetSlice.mutable and not sourceSlice.mutable {
                return false;
            }
            if isOpaqueSlice(source) or isOpaqueSlice(target) {
                return true;
            }
            if *targetSlice.item == Type::U8 {
                return true;
            }
            return isValidCast(*sourceSlice.item, *targetSlice.item);
        }
    }
    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);
    if isUnsafePointerType(sourceTy) or isUnsafePointerType(targetTy) {
        try requireUnsafe(self, node);
    }

    assert sourceTy <> Type::Unknown;
    assert targetTy <> Type::Unknown;

    let mut valid = isValidCast(sourceTy, targetTy);
    if let case Type::Pointer(sourcePointer) = sourceTy {
        if let case Type::Pointer(targetPointer) = targetTy {
            if sourcePointer.class == types::PointerClass::Ref and
               targetPointer.class == types::PointerClass::Unsafe and
               (not targetPointer.mutable or sourcePointer.mutable) and
               isValidCast(*sourcePointer.target, *targetPointer.target)
            {
                set valid = true;
            }
        }
    }
    if let case Type::Slice(sourceSlice) = sourceTy {
        if let case Type::Slice(targetSlice) = targetTy {
            if sourceSlice.class == types::PointerClass::Ref and
               targetSlice.class == types::PointerClass::Unsafe and
               (not targetSlice.mutable or sourceSlice.mutable) and
               isValidCast(*sourceSlice.item, *targetSlice.item)
            {
                set valid = true;
            }
        }
    }
    if valid {
        // Propagate the constant value after applying the cast's target-width
        // truncation and signed interpretation.
        if let value = constValueEntry(self, expr.value) {
            if let case ConstValue::Int(i) = value {
                setNodeConstValue(self, node, castConstInt(i, targetTy));
            }
        }
        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);
                set resolvedTy = endTy;
            } else if endTy == Type::Int and startTy <> Type::Int {
                let _ = try checkAssignable(self, e, startTy);
                set resolvedTy = startTy;
            } else {
                let _ = try checkAssignable(self, e, startTy);
            }
            set start = allocType(self, resolvedTy);
            set end = allocType(self, resolvedTy);
        } else {
            set start = allocType(self, startTy);
        }
    } else if let e = range.end {
        set 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, hint
    );

    // 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 {
            set tryResultTy = Type::Optional(allocType(self, resultTy));
        }
    } else if tryExpr.catches.len > 0 {
        // `try ... catch` -- one or more catch clauses.
        set 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 {
                    set 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 {
                    set foundIdx = j;
                    break;
                }
            }
            let idx = foundIdx else {
                throw emitError(self, typeNode, ErrorKind::TryIncompatibleError);
            };
            if covered[idx] {
                throw emitError(self, typeNode, ErrorKind::TryCatchDuplicateType);
            }
            set 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.
            set 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 two's-complement bit pattern.
fn constIntToBits(c: ConstInt) -> u64 {
    return (0 - c.magnitude) if c.negative else c.magnitude;
}

/// Convert a [`ConstInt`] to its signed two's-complement representation.
fn constIntToSigned(c: ConstInt) -> i64 {
    return constIntToBits(c) 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,
    };
}

/// Build a [`ConstInt`] from a two's-complement bit pattern.
fn constIntFromBits(raw: u64, bits: u8, signed: bool) -> ConstInt {
    let mask = parser::U64_MAX if bits == 64 else parser::U64_MAX >> (64 - bits) as u64;
    let truncated = raw & mask;

    if signed {
        let signBit = (mask >> 1) + 1;
        if (truncated & signBit) <> 0 {
            return ConstInt {
                magnitude: (0 - truncated) & mask,
                bits,
                signed,
                negative: true,
            };
        }
    }
    return ConstInt { magnitude: truncated, 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 {
        set bits = right.bits;
    }
    let signed = left.signed or right.signed;
    let l = constIntToSigned(left);
    let r = constIntToSigned(right);

    match op {
        // Shift counts are masked to the left operand's width, matching
        // the runtime word instructions.
        case ast::BinaryOp::Shl => {
            let raw = constIntToBits(left);
            let shamt = constIntToBits(right) % left.bits as u64;
            return ConstValue::Int(constIntFromBits(raw << shamt, left.bits, left.signed));
        },
        case ast::BinaryOp::Shr => {
            let shamt = constIntToBits(right) % left.bits as u64;
            if left.signed {
                let shifted = constIntToSigned(left) >> shamt as i64;
                return ConstValue::Int(
                    constIntFromBits(shifted as u64, left.bits, true)
                );
            }
            return ConstValue::Int(
                constIntFromBits(left.magnitude >> shamt, left.bits, false)
            );
        },
        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 if signed else left.magnitude < right.magnitude),
        case ast::BinaryOp::Gt =>
            return ConstValue::Bool(l > r if signed else left.magnitude > right.magnitude),
        case ast::BinaryOp::Lte =>
            return ConstValue::Bool(l <= r if signed else left.magnitude <= right.magnitude),
        case ast::BinaryOp::Gte =>
            return ConstValue::Bool(l >= r if signed else left.magnitude >= right.magnitude),
        case ast::BinaryOp::Add => {
            if not signed {
                return ConstValue::Int(
                    constIntFromBits(left.magnitude + right.magnitude, bits, false)
                );
            }
            return ConstValue::Int(constIntFromSigned(l + r, bits, true));
        },
        case ast::BinaryOp::Sub => {
            if not signed {
                return ConstValue::Int(
                    constIntFromBits(left.magnitude - right.magnitude, bits, false)
                );
            }
            return ConstValue::Int(constIntFromSigned(l - r, bits, true));
        },
        case ast::BinaryOp::Mul => {
            if not signed {
                return ConstValue::Int(
                    constIntFromBits(left.magnitude * right.magnitude, bits, false)
                );
            }
            return ConstValue::Int(constIntFromSigned(l * r, bits, true));
        },
        case ast::BinaryOp::Div => {
            if signed {
                if r == 0 {
                    return nil;
                }
                if l == parser::I64_MIN and r == -1 {
                    return ConstValue::Int(
                        constIntFromBits(parser::I64_MIN as u64, bits, true)
                    );
                }
                return ConstValue::Int(constIntFromSigned(l / r, bits, true));
            }
            if right.magnitude == 0 {
                return nil;
            }
            return constInt(left.magnitude / right.magnitude, bits, false, false);
        },
        case ast::BinaryOp::Mod => {
            if signed {
                if r == 0 {
                    return nil;
                }
                if l == parser::I64_MIN and r == -1 {
                    return ConstValue::Int(
                        constIntFromBits(0, bits, true)
                    );
                }
                return ConstValue::Int(constIntFromSigned(l % r, bits, true));
            }
            if right.magnitude == 0 {
                return nil;
            }
            return constInt(left.magnitude % right.magnitude, bits, false, false);
        },
        case ast::BinaryOp::BitAnd => return ConstValue::Int(
            constIntFromBits(constIntToBits(left) & constIntToBits(right), bits, signed)
        ),
        case ast::BinaryOp::BitOr => return ConstValue::Int(
            constIntFromBits(constIntToBits(left) | constIntToBits(right), bits, signed)
        ),
        case ast::BinaryOp::BitXor => return ConstValue::Int(
            constIntFromBits(constIntToBits(left) ^ constIntToBits(right), 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);

            set 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 isUnsafePointerType(leftTy) or isUnsafePointerType(rightTy) {
                try requireUnsafe(self, node);
            }

            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));
            }
            set 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);

                // Allow arithmetic on owning pointers and unsafe pointers, but
                // never on references.
                if let case Type::Pointer(leftPointer) = leftTy {
                    if *leftPointer.target == Type::Opaque {
                        throw emitError(self, node, ErrorKind::OpaquePointerArithmetic);
                    }
                    if leftPointer.class <> types::PointerClass::Ref
                        and isNumericType(rightTy)
                    {
                        if leftPointer.class == types::PointerClass::Unsafe {
                            try requireUnsafe(self, node);
                        }
                        return setNodeType(self, node, leftTy);
                    }
                }
                if let case Type::Pointer(rightPointer) = rightTy {
                    if *rightPointer.target == Type::Opaque {
                        throw emitError(self, node, ErrorKind::OpaquePointerArithmetic);
                    }
                    if binop.op == ast::BinaryOp::Add
                        and rightPointer.class <> types::PointerClass::Ref
                        and isNumericType(leftTy)
                    {
                        if rightPointer.class == types::PointerClass::Unsafe {
                            try requireUnsafe(self, node);
                        }
                        return setNodeType(self, node, rightTy);
                    }
                }
            }
            let leftTy = try checkNumeric(self, binop.left);
            let rightTy = try checkNumeric(self, binop.right);

            let mut operandTy = leftTy;
            if leftTy <> rightTy {
                if leftTy == Type::Int {
                    set operandTy = rightTy;
                } else if rightTy <> Type::Int {
                    throw emitTypeMismatch(self, binop.right, TypeMismatch {
                        expected: leftTy,
                        actual: rightTy,
                    });
                }
            }

            // Ordering comparisons return `bool`, not the operand type.
            match binop.op {
                case ast::BinaryOp::Lt, ast::BinaryOp::Gt,
                     ast::BinaryOp::Lte, ast::BinaryOp::Gte =>
                    set resultTy = Type::Bool,
                else =>
                    set resultTy = operandTy,
            }

        }
    };
    // 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 => {
            set 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?
            set 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 => {
            set 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 { class, itemType, mutable } => {
            let item = try infer(self, itemType);
            return Type::Slice(SliceType {
                class,
                item: allocType(self, item),
                mutable,
            });
        }
        case ast::TypeSig::Pointer { class, valueType, mutable } => {
            let target = try infer(self, valueType);
            return Type::Pointer(PointerType {
                class,
                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) => {
            if let case ast::NodeValue::Ident(paramName) = name.value {
                if mem::eq(paramName, "Self") {
                    let selfType = self.currentTraitSelf else {
                        throw emitError(
                            self, name, ErrorKind::UnresolvedSymbol(paramName)
                        );
                    };
                    set *selfType.used = true;
                    return Type::Parameter(selfType);
                }
                let sym = findTypeSymbol(self.scope, paramName) else {
                    throw emitError(self, name, ErrorKind::UnresolvedSymbol(paramName));
                };
                match sym.data {
                    case SymbolData::Type(ty) => {
                        if isGenericDeclaration(sym.node) {
                            throw emitError(self, name, ErrorKind::GenericArgumentsRequired);
                        }
                        setNodeSymbol(self, name, sym);
                        return Type::Nominal(ty);
                    }
                    case SymbolData::TypeParameter(param) => {
                        set *param.used = true;
                        setNodeSymbol(self, name, sym);
                        return Type::Parameter(param);
                    }
                    else => throw emitError(self, name, ErrorKind::Internal),
                }
            }
            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 resolveValueType(self, paramNode);
                paramTypes.append(allocType(self, paramTy), a);
            }
            for tyNode in t.throwList {
                let throwTy = try resolveValueType(self, tyNode);
                try ensureStorableType(self, tyNode, throwTy);
                throwList.append(allocType(self, throwTy), a);
            }
            let mut retType = allocType(self, Type::Void);
            if let ret = t.returnType {
                let resolvedRet = try resolveValueType(self, ret);
                try ensureStorableType(self, ret, resolvedRet);
                set retType = allocType(self, resolvedRet);
            }
            let fnType = FnType {
                paramTypes: &paramTypes[..],
                returnType: retType,
                throwList: &throwList[..],
                isUnsafe: false,
                localCount: 0,
            };
            return Type::Fn(allocFnType(self, fnType));
        }
        // Resolve an opaque trait object signature.
        case ast::TypeSig::TraitObject { class, traitName, mutable } => {
            let sym = try resolveNamePath(self, traitName);
            let case SymbolData::Trait(traitInfo) = sym.data
                else throw emitError(self, traitName, ErrorKind::Internal);
            if traitInfo.state == TraitState::Queued {
                let case ast::NodeValue::TraitDecl { supertraits, methods, .. } = sym.node.value
                    else throw emitError(self, traitName, ErrorKind::Internal);
                try resolveTraitBody(self, sym.node, supertraits, methods);
            }
            if not traitInfo.objectSafe {
                throw emitError(self, traitName, ErrorKind::TraitNotObjectSafe);
            }
            setNodeSymbol(self, traitName, sym);
            return Type::TraitObject(TraitObjectType { class, traitInfo, mutable });
        }
    }
}

/// Check if a type can be used for inferrence.
fn isTypeInferrable(type: Type) -> bool {
    if let case Type::Pointer(pointer) = type {
        return isTypeInferrable(*pointer.target);
    }
    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),
        else => return true,
    }
}

/// Analyze a standalone expression by wrapping it in a synthetic function.
export 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.
export 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);

    try closeGenericFnSpecializations(self) catch {
        return Diagnostics { errors: self.errors };
    };
    try validateGenericDataRoots(self) catch {
        return Diagnostics { errors: self.errors };
    };
    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) => {
                if decl.params.len > 0 {
                    try resolveGenericDataTemplate(
                        self, node, decl.params, decl.fields, decl.derives, true,
                    ) catch {};
                } else {
                    try resolveRecordBody(self, node, decl) catch {
                        // Continue resolving other types even if one fails.
                    };
                }
            }
            case ast::NodeValue::UnionDecl(decl) => {
                if decl.params.len > 0 {
                    try resolveGenericDataTemplate(
                        self, node, decl.params, decl.variants, decl.derives, false,
                    ) catch {};
                } else {
                    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 imports so names available from the module graph can
    // be used in function signatures.
    for node in block.statements {
        if let case ast::NodeValue::Use(decl) = node.value {
            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 (export 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);
    }
}

/// Maximum number of linear bindings active in one function.
constant MAX_LINEAR_BINDINGS: u32 = 32;
/// Maximum nesting depth tracked for loops.
constant MAX_LINEAR_LOOP_DEPTH: u32 = 16;

/// How an expression uses a linear result.
union LinearUse {
    Consume,
    Observe,
    Borrow,
    Discard,
    Place,
}

/// Per-control-flow-path ownership state.
record LinearEnv {
    symbols: [?*mut Symbol; MAX_LINEAR_BINDINGS],
    available: u64,
    len: u32,
    terminated: bool,
}

/// Function-local exact-use checker state.
record LinearChecker {
    resolver: *mut Resolver,
    loopMarks: [u32; MAX_LINEAR_LOOP_DEPTH],
    loopAvailable: [u64; MAX_LINEAR_LOOP_DEPTH],
    loopExitAvailable: [u64; MAX_LINEAR_LOOP_DEPTH],
    loopHasNaturalExit: [bool; MAX_LINEAR_LOOP_DEPTH],
    loopBreakSeen: [bool; MAX_LINEAR_LOOP_DEPTH],
    loopDepth: u32,
}

/// Find a tracked binding by symbol identity.
fn findLinearBinding(env: *LinearEnv, sym: *mut Symbol) -> ?u32 {
    for i in 0..env.len {
        if let bound = env.symbols[i]; bound == sym {
            return i;
        }
    }
    return nil;
}

/// Return whether a tracked binding is still available.
fn linearBindingAvailable(env: *LinearEnv, index: u32) -> bool {
    return (env.available & ((1 as u64) << (index as u64))) <> 0;
}

/// Add a local binding when its resolved type is linear.
fn addLinearBinding(checker: *mut LinearChecker, env: *mut LinearEnv, node: *ast::Node)
    throws (ResolveError)
{
    let sym = symbolFor(checker.resolver, node) else return;
    let case SymbolData::Value { type: ty, .. } = sym.data else return;
    if not isLinear(ty) {
        return;
    }
    if env.len >= MAX_LINEAR_BINDINGS {
        throw emitError(checker.resolver, node, ErrorKind::Internal);
    }
    set env.symbols[env.len] = sym;
    set env.available |= (1 as u64) << (env.len as u64);
    set env.len += 1;
}

/// Require all bindings introduced after `start` to have been consumed.
fn finishLinearScope(
    checker: *mut LinearChecker,
    env: *mut LinearEnv,
    start: u32,
) throws (ResolveError) {
    if not env.terminated {
        for i in start..env.len {
            if linearBindingAvailable(env, i) {
                let sym = env.symbols[i] else panic "finishLinearScope: missing symbol";
                throw emitError(
                    checker.resolver,
                    sym.node,
                    ErrorKind::LinearNotConsumed(sym.name),
                );
            }
        }
    }
    set env.len = start;
}

/// Consume a tracked identifier exactly once.
fn consumeLinearIdent(
    checker: *mut LinearChecker,
    env: *mut LinearEnv,
    node: *ast::Node,
) throws (ResolveError) {
    let sym = symbolFor(checker.resolver, node) else return;
    let index = findLinearBinding(env, sym) else return;
    if not linearBindingAvailable(env, index) {
        throw emitError(
            checker.resolver,
            node,
            ErrorKind::LinearUseAfterConsume(sym.name),
        );
    }
    set env.available &= ~((1 as u64) << (index as u64));
}

/// Verify that two live branches agree on every outer binding.
fn joinLinearBranches(
    checker: *mut LinearChecker,
    env: *mut LinearEnv,
    left: LinearEnv,
    right: LinearEnv,
    node: *ast::Node,
) throws (ResolveError) {
    if left.terminated and right.terminated {
        set *env = left;
        set env.terminated = true;
        return;
    }
    if left.terminated {
        set *env = right;
        return;
    }
    if right.terminated {
        set *env = left;
        return;
    }
    assert left.len == right.len, "joinLinearBranches: scope mismatch";
    for i in 0..left.len {
        if linearBindingAvailable(&left, i) <> linearBindingAvailable(&right, i) {
            let sym = left.symbols[i] else panic "joinLinearBranches: missing symbol";
            throw emitError(
                checker.resolver,
                node,
                ErrorKind::LinearBranchMismatch(sym.name),
            );
        }
    }
    set *env = left;
}

/// Require all current bindings to be consumed at a function exit.
fn finishLinearExit(
    checker: *mut LinearChecker,
    env: *mut LinearEnv,
) throws (ResolveError) {
    for i in 0..env.len {
        if linearBindingAvailable(env, i) {
            let sym = env.symbols[i] else panic "finishLinearExit: missing symbol";
            throw emitError(
                checker.resolver,
                sym.node,
                ErrorKind::LinearNotConsumed(sym.name),
            );
        }
    }
    set env.terminated = true;
}

/// Find the local root borrowed or consumed by an argument expression.
fn linearRootSymbol(self: *mut Resolver, node: *ast::Node) -> ?*mut Symbol {
    match node.value {
        case ast::NodeValue::Ident(_) => return symbolFor(self, node),
        case ast::NodeValue::AddressOf(addr) => return linearRootSymbol(self, addr.target),
        case ast::NodeValue::FieldAccess(access) =>
            return linearRootSymbol(self, access.parent),
        case ast::NodeValue::Subscript { container, .. } =>
            return linearRootSymbol(self, container),
        case ast::NodeValue::GenericApply(_) => return nil,
        case ast::NodeValue::Deref(target) => return linearRootSymbol(self, target),
        else => return nil,
    }
}

/// Add the value identifiers introduced by a pattern.
fn addLinearPatternBindings(
    checker: *mut LinearChecker,
    env: *mut LinearEnv,
    pattern: *ast::Node,
) throws (ResolveError) {
    match pattern.value {
        case ast::NodeValue::Ident(_) => try addLinearBinding(checker, env, pattern),
        case ast::NodeValue::Call(call) => {
            for arg in call.args {
                try addLinearPatternBindings(checker, env, arg);
            }
        }
        case ast::NodeValue::RecordLit(lit) => {
            for fieldNode in lit.fields {
                let case ast::NodeValue::RecordLitField(field) = fieldNode.value
                    else panic "addLinearPatternBindings: expected field";
                try addLinearPatternBindings(checker, env, field.value);
            }
        }
        case ast::NodeValue::ArrayLit(items) => {
            for item in items {
                try addLinearPatternBindings(checker, env, item);
            }
        }
        else => {}
    }
}

/// Check a lexical block and exact-use of locals introduced in it.
fn checkLinearBlock(
    checker: *mut LinearChecker,
    env: *mut LinearEnv,
    node: *ast::Node,
) throws (ResolveError) {
    let start = env.len;
    let case ast::NodeValue::Block(block) = node.value
        else panic "checkLinearBlock: expected block";
    for stmt in block.statements {
        if env.terminated {
            break;
        }
        try checkLinearNode(checker, env, stmt, LinearUse::Discard);
    }
    try finishLinearScope(checker, env, start);
}

/// Push a repeated-control-flow boundary.
fn enterLinearLoop(checker: *mut LinearChecker, env: *LinearEnv) {
    assert checker.loopDepth < MAX_LINEAR_LOOP_DEPTH, "linear loop nesting overflow";
    let depth = checker.loopDepth;
    set checker.loopMarks[depth] = env.len;
    set checker.loopAvailable[depth] = env.available;
    set checker.loopExitAvailable[depth] = env.available;
    set checker.loopHasNaturalExit[depth] = false;
    set checker.loopBreakSeen[depth] = false;
    set checker.loopDepth += 1;
}

/// Require a repeated body's outer bindings to match its entry state.
fn checkLinearLoopBackEdge(
    checker: *mut LinearChecker,
    env: *LinearEnv,
    node: *ast::Node,
) throws (ResolveError) {
    if env.terminated {
        return;
    }
    assert checker.loopDepth > 0, "linear loop back edge outside loop";
    let depth = checker.loopDepth - 1;
    let mark = checker.loopMarks[depth];
    let entryAvailable = checker.loopAvailable[depth];
    for i in 0..mark {
        let bit = (1 as u64) << (i as u64);
        if (env.available & bit) <> (entryAvailable & bit) {
            let sym = env.symbols[i] else panic "checkLinearLoopBackEdge: missing symbol";
            throw emitError(
                checker.resolver,
                node,
                ErrorKind::LinearBranchMismatch(sym.name),
            );
        }
    }
}

/// Record the ownership state of a loop's condition-false exit.
fn setLinearLoopNaturalExit(checker: *mut LinearChecker, env: *LinearEnv) {
    assert checker.loopDepth > 0, "linear loop exit outside loop";
    let depth = checker.loopDepth - 1;
    set checker.loopExitAvailable[depth] = env.available;
    set checker.loopHasNaturalExit[depth] = true;
}

/// Require a break exit to agree with every other exit from this loop.
fn checkLinearLoopBreak(
    checker: *mut LinearChecker,
    env: *LinearEnv,
    node: *ast::Node,
) throws (ResolveError) {
    assert checker.loopDepth > 0, "linear loop break outside loop";
    let depth = checker.loopDepth - 1;
    let mark = checker.loopMarks[depth];
    if checker.loopHasNaturalExit[depth] or checker.loopBreakSeen[depth] {
        let expected = checker.loopExitAvailable[depth];
        for i in 0..mark {
            let bit = (1 as u64) << (i as u64);
            if (env.available & bit) <> (expected & bit) {
                let sym = env.symbols[i] else panic "checkLinearLoopBreak: missing symbol";
                throw emitError(
                    checker.resolver,
                    node,
                    ErrorKind::LinearBranchMismatch(sym.name),
                );
            }
        }
    } else {
        set checker.loopExitAvailable[depth] = env.available;
    }
    set checker.loopBreakSeen[depth] = true;
}

/// Pop a repeated-control-flow boundary.
fn exitLinearLoop(checker: *mut LinearChecker) {
    assert checker.loopDepth > 0, "exitLinearLoop: not in loop";
    set checker.loopDepth -= 1;
}

/// Check a conditional and merge its ownership states.
fn checkLinearIf(
    checker: *mut LinearChecker,
    env: *mut LinearEnv,
    node: *ast::Node,
    conditional: ast::If,
) throws (ResolveError) {
    try checkLinearNode(checker, env, conditional.condition, LinearUse::Consume);
    let base = *env;
    let mut thenEnv = base;
    try checkLinearNode(checker, &mut thenEnv, conditional.thenBranch, LinearUse::Discard);
    let mut elseEnv = base;
    if let branch = conditional.elseBranch {
        try checkLinearNode(checker, &mut elseEnv, branch, LinearUse::Discard);
    }
    try joinLinearBranches(checker, env, thenEnv, elseEnv, node);
}

/// Check an expression conditional and merge its ownership states.
fn checkLinearCondExpr(
    checker: *mut LinearChecker,
    env: *mut LinearEnv,
    node: *ast::Node,
    conditional: ast::CondExpr,
    usage: LinearUse,
) throws (ResolveError) {
    try checkLinearNode(checker, env, conditional.condition, LinearUse::Consume);
    let base = *env;
    let mut thenEnv = base;
    try checkLinearNode(checker, &mut thenEnv, conditional.thenExpr, usage);
    let mut elseEnv = base;
    try checkLinearNode(checker, &mut elseEnv, conditional.elseExpr, usage);
    try joinLinearBranches(checker, env, thenEnv, elseEnv, node);
}

/// Check a match expression, including ownership transferred into patterns.
fn checkLinearMatch(
    checker: *mut LinearChecker,
    env: *mut LinearEnv,
    node: *ast::Node,
    matchExpr: ast::Match,
) throws (ResolveError) {
    try checkLinearNode(checker, env, matchExpr.subject, LinearUse::Consume);
    let base = *env;
    let mut haveResult = false;
    let mut result = base;
    for prongNode in matchExpr.prongs {
        let case ast::NodeValue::MatchProng(prong) = prongNode.value
            else panic "checkLinearMatch: expected prong";
        let mut branch = base;
        let bindingsStart = branch.len;
        match prong.arm {
            case ast::ProngArm::Case(patterns) => {
                for pattern in patterns {
                    try addLinearPatternBindings(checker, &mut branch, pattern);
                }
            }
            case ast::ProngArm::Binding(binding) => {
                try addLinearPatternBindings(checker, &mut branch, binding);
            }
            case ast::ProngArm::Else => {}
        }
        if prong.guard <> nil and branch.len > bindingsStart {
            throw emitError(checker.resolver, prongNode, ErrorKind::LinearDiscard);
        }
        if let guard = prong.guard {
            try checkLinearNode(checker, &mut branch, guard, LinearUse::Consume);
        }
        try checkLinearNode(checker, &mut branch, prong.body, LinearUse::Discard);
        try finishLinearScope(checker, &mut branch, bindingsStart);
        if haveResult {
            try joinLinearBranches(checker, &mut result, result, branch, node);
        } else {
            set result = branch;
            set haveResult = true;
        }
    }
    if haveResult {
        set *env = result;
    }
}

/// Check call-scoped loans and argument ownership transfers.
fn checkLinearCall(
    checker: *mut LinearChecker,
    env: *mut LinearEnv,
    node: *ast::Node,
    call: ast::Call,
) throws (ResolveError) {
    try checkLinearNode(checker, env, call.callee, LinearUse::Observe);
    let calleeTy = typeFor(checker.resolver, call.callee) else {
        throw emitError(checker.resolver, call.callee, ErrorKind::Internal);
    };
    let case Type::Fn(info) = calleeTy else {
        for arg in call.args {
            try checkLinearNode(checker, env, arg, LinearUse::Consume);
        }
        return;
    };
    let mut roots: [?*mut Symbol; MAX_FN_PARAMS + 1] = undefined;
    let mut exclusive: [bool; MAX_FN_PARAMS + 1] = undefined;
    let mut rootsLen: u32 = 0;

    // Method function types exclude their implicit receiver. Account for it
    // explicitly so owning receivers are consumed and reference receivers
    // participate in call-scoped loan conflict checks.
    if let case ast::NodeValue::FieldAccess(access) = call.callee.value {
        let mut receiverClass = types::PointerClass::Unsafe;
        let mut receiverMutable = false;
        let mut haveReceiver = false;
        match checker.resolver.nodeData.entries[node.id].extra {
            case NodeExtra::TraitMethodCall { traitInfo, methodIndex } => {
                let method = &traitInfo.methods[methodIndex];
                set receiverClass = method.receiverClass;
                set receiverMutable = method.mutable;
                set haveReceiver = true;
            }
            case NodeExtra::GenericBoundMethodCall {
                traitInfo, methodIndex, explicitReceiver, ..
            } => {
                if not explicitReceiver {
                    let method = &traitInfo.methods[methodIndex];
                    set receiverClass = method.receiverClass;
                    set receiverMutable = method.mutable;
                    set haveReceiver = true;
                }
            }
            case NodeExtra::MethodCall { method } => {
                set receiverClass = method.receiverClass;
                set receiverMutable = method.mutable;
                set haveReceiver = true;
            }
            else => {}
        }
        if haveReceiver {
            if receiverClass <> types::PointerClass::Unsafe {
                let root = linearRootSymbol(checker.resolver, access.parent);
                if let rootSym = root {
                    set roots[rootsLen] = rootSym;
                    set exclusive[rootsLen] =
                        receiverClass == types::PointerClass::Owned or receiverMutable;
                    set rootsLen += 1;
                }
            }
            if receiverClass == types::PointerClass::Ref {
                try checkLinearNode(checker, env, access.parent, LinearUse::Borrow);
            } else if receiverClass == types::PointerClass::Owned {
                try checkLinearNode(checker, env, access.parent, LinearUse::Consume);
            }
        }
    }

    for arg, i in call.args {
        let expected = *info.paramTypes[i];
        let root = linearRootSymbol(checker.resolver, arg);
        let mut argExclusive = isLinear(expected);
        if let case Type::Pointer(PointerType { class: types::PointerClass::Ref, mutable, .. }) = expected {
            set argExclusive = mutable;
        } else if let case Type::Slice(SliceType {
            class: types::PointerClass::Ref, mutable, ..
        }) = expected {
            set argExclusive = mutable;
        } else if let case Type::TraitObject(TraitObjectType {
            class: types::PointerClass::Ref, mutable, ..
        }) = expected {
            set argExclusive = mutable;
        }
        if not isUnsafePointerType(expected) {
            if let rootSym = root {
                for j in 0..rootsLen {
                    if let previous = roots[j] {
                        if previous == rootSym and (exclusive[j] or argExclusive) {
                            throw emitError(
                                checker.resolver,
                                arg,
                                ErrorKind::BorrowConflict(rootSym.name),
                            );
                        }
                    }
                }
                set roots[rootsLen] = rootSym;
                set exclusive[rootsLen] = argExclusive;
                set rootsLen += 1;
            }
        }
        if isRefType(expected) {
            try checkLinearNode(checker, env, arg, LinearUse::Borrow);
        } else {
            try checkLinearNode(checker, env, arg, LinearUse::Consume);
        }
    }
}

/// Check a pattern conditional. Linear scrutinees require an exhaustive match.
fn checkLinearIfLet(
    checker: *mut LinearChecker,
    env: *mut LinearEnv,
    node: *ast::Node,
    conditional: ast::IfLet,
) throws (ResolveError) {
    if let subjectTy = typeFor(checker.resolver, conditional.pattern.scrutinee);
        isLinear(subjectTy)
    {
        throw emitError(
            checker.resolver,
            conditional.pattern.scrutinee,
            ErrorKind::LinearPartialMove,
        );
    }
    try checkLinearNode(
        checker,
        env,
        conditional.pattern.scrutinee,
        LinearUse::Consume,
    );
    let base = *env;
    let mut thenEnv = base;
    let bindingsStart = thenEnv.len;
    try addLinearPatternBindings(checker, &mut thenEnv, conditional.pattern.pattern);
    if let guard = conditional.pattern.guard {
        try checkLinearNode(checker, &mut thenEnv, guard, LinearUse::Consume);
    }
    try checkLinearNode(checker, &mut thenEnv, conditional.thenBranch, LinearUse::Discard);
    try finishLinearScope(checker, &mut thenEnv, bindingsStart);
    let mut elseEnv = base;
    if let branch = conditional.elseBranch {
        try checkLinearNode(checker, &mut elseEnv, branch, LinearUse::Discard);
    }
    try joinLinearBranches(checker, env, thenEnv, elseEnv, node);
}

/// Check one expression or statement under an ownership-use context.
fn checkLinearNode(
    checker: *mut LinearChecker,
    env: *mut LinearEnv,
    node: *ast::Node,
    usage: LinearUse,
) throws (ResolveError) {
    if env.terminated {
        return;
    }
    match node.value {
        case ast::NodeValue::Ident(_) => {
            if usage == LinearUse::Consume {
                try consumeLinearIdent(checker, env, node);
            }
        }
        case ast::NodeValue::ExprStmt(expr) => {
            if let exprTy = typeFor(checker.resolver, expr) {
                if isLinear(exprTy) {
                    throw emitError(checker.resolver, expr, ErrorKind::LinearDiscard);
                }
            }
            try checkLinearNode(checker, env, expr, LinearUse::Consume);
        }
        case ast::NodeValue::Block(_) => try checkLinearBlock(checker, env, node),
        case ast::NodeValue::Let(binding) => {
            if let case ast::NodeValue::Undef = binding.value.value {
                if let bindingTy = typeFor(checker.resolver, binding.ident);
                    isLinear(bindingTy)
                {
                    throw emitError(
                        checker.resolver,
                        binding.value,
                        ErrorKind::LinearUndefined,
                    );
                }
            }
            try checkLinearNode(checker, env, binding.value, LinearUse::Consume);
            try addLinearBinding(checker, env, node);
        }
        case ast::NodeValue::Assign(assign) => {
            let mut target: ?u32 = nil;
            if let leftTy = typeFor(checker.resolver, assign.left) {
                if isLinear(leftTy) {
                    if let case ast::NodeValue::Ident(_) = assign.left.value {
                        if let sym = symbolFor(checker.resolver, assign.left) {
                            set target = findLinearBinding(env, sym);
                        }
                    }
                    if target == nil {
                        throw emitError(
                            checker.resolver,
                            assign.left,
                            ErrorKind::LinearOverwrite,
                        );
                    }
                }
            }
            try checkLinearNode(checker, env, assign.left, LinearUse::Place);
            try checkLinearNode(checker, env, assign.right, LinearUse::Consume);
            if let index = target {
                if linearBindingAvailable(env, index) {
                    throw emitError(
                        checker.resolver,
                        assign.left,
                        ErrorKind::LinearOverwrite,
                    );
                }
                set env.available |= (1 as u64) << (index as u64);
            }
        }
        case ast::NodeValue::Call(call) => try checkLinearCall(checker, env, node, call),
        case ast::NodeValue::AddressOf(addr) => {
            try checkLinearNode(checker, env, addr.target, LinearUse::Borrow);
        }
        case ast::NodeValue::Deref(target) => {
            if let resultTy = typeFor(checker.resolver, node) {
                if isLinear(resultTy) and usage == LinearUse::Consume {
                    throw emitError(checker.resolver, node, ErrorKind::LinearPartialMove);
                }
            }
            try checkLinearNode(checker, env, target, LinearUse::Observe);
        }
        case ast::NodeValue::FieldAccess(access) => {
            if let resultTy = typeFor(checker.resolver, node) {
                if isLinear(resultTy) and usage == LinearUse::Consume {
                    throw emitError(checker.resolver, node, ErrorKind::LinearPartialMove);
                }
            }
            try checkLinearNode(checker, env, access.parent, LinearUse::Observe);
        }
        case ast::NodeValue::ScopeAccess(_) => {}
        case ast::NodeValue::Subscript { container, index } => {
            if let resultTy = typeFor(checker.resolver, node) {
                if isLinear(resultTy) and usage == LinearUse::Consume {
                    throw emitError(checker.resolver, node, ErrorKind::LinearPartialMove);
                }
            }
            try checkLinearNode(checker, env, container, LinearUse::Observe);
            try checkLinearNode(checker, env, index, LinearUse::Consume);
        }
        case ast::NodeValue::GenericApply(_) => {
            let extra = checker.resolver.nodeData.entries[node.id].extra;
            if let case NodeExtra::GenericFnCall(_) = extra {
                return;
            }
            if let case NodeExtra::GenericFnDependency(_) = extra {
                return;
            }
            throw emitError(checker.resolver, node, ErrorKind::Internal);
        }
        case ast::NodeValue::RecordLit(lit) => {
            for fieldNode in lit.fields {
                let case ast::NodeValue::RecordLitField(field) = fieldNode.value
                    else panic "checkLinearNode: expected field";
                try checkLinearNode(checker, env, field.value, LinearUse::Consume);
            }
        }
        case ast::NodeValue::ArrayLit(items) => {
            for item in items {
                try checkLinearNode(checker, env, item, LinearUse::Consume);
            }
        }
        case ast::NodeValue::ArrayRepeatLit(repeat) => {
            if let itemTy = typeFor(checker.resolver, repeat.item) {
                if isLinear(itemTy) {
                    throw emitError(
                        checker.resolver,
                        repeat.item,
                        ErrorKind::LinearDiscard,
                    );
                }
            }
            try checkLinearNode(checker, env, repeat.item, LinearUse::Consume);
            try checkLinearNode(checker, env, repeat.count, LinearUse::Consume);
        }
        case ast::NodeValue::BinOp(op) => {
            try checkLinearNode(checker, env, op.left, LinearUse::Consume);
            try checkLinearNode(checker, env, op.right, LinearUse::Consume);
        }
        case ast::NodeValue::UnOp(op) => {
            try checkLinearNode(checker, env, op.value, LinearUse::Consume);
        }
        case ast::NodeValue::As(expr) => {
            try checkLinearNode(checker, env, expr.value, LinearUse::Consume);
        }
        case ast::NodeValue::Range(range) => {
            if let start = range.start {
                try checkLinearNode(checker, env, start, LinearUse::Consume);
            }
            if let end = range.end {
                try checkLinearNode(checker, env, end, LinearUse::Consume);
            }
        }
        case ast::NodeValue::BuiltinCall { args, .. } => {
            for arg in args {
                try checkLinearNode(checker, env, arg, LinearUse::Consume);
            }
        }
        case ast::NodeValue::If(conditional) => {
            try checkLinearIf(checker, env, node, conditional);
        }
        case ast::NodeValue::CondExpr(conditional) => {
            try checkLinearCondExpr(checker, env, node, conditional, usage);
        }
        case ast::NodeValue::IfLet(conditional) => {
            try checkLinearIfLet(checker, env, node, conditional);
        }
        case ast::NodeValue::LetElse(binding) => {
            if let subjectTy = typeFor(checker.resolver, binding.pattern.scrutinee);
                isLinear(subjectTy)
            {
                throw emitError(
                    checker.resolver,
                    binding.pattern.scrutinee,
                    ErrorKind::LinearPartialMove,
                );
            }
            try checkLinearNode(
                checker,
                env,
                binding.pattern.scrutinee,
                LinearUse::Consume,
            );
            let base = *env;
            let mut guardedEnv = base;
            if let guard = binding.pattern.guard {
                try checkLinearNode(checker, &mut guardedEnv, guard, LinearUse::Consume);
            }
            let mut successEnv = guardedEnv;
            try addLinearPatternBindings(
                checker,
                &mut successEnv,
                binding.pattern.pattern,
            );
            let mut fallbackEnv = base;
            try checkLinearNode(
                checker,
                &mut fallbackEnv,
                binding.elseBranch,
                LinearUse::Consume,
            );
            if binding.pattern.guard <> nil {
                let mut guardFallbackEnv = guardedEnv;
                try checkLinearNode(
                    checker,
                    &mut guardFallbackEnv,
                    binding.elseBranch,
                    LinearUse::Consume,
                );
                try joinLinearBranches(
                    checker,
                    &mut fallbackEnv,
                    fallbackEnv,
                    guardFallbackEnv,
                    binding.elseBranch,
                );
            }
            if let case ast::PatternKind::Binding = binding.pattern.kind {
                try addLinearPatternBindings(
                    checker,
                    &mut fallbackEnv,
                    binding.pattern.pattern,
                );
            }
            try joinLinearBranches(checker, env, successEnv, fallbackEnv, node);
        }
        case ast::NodeValue::Match(matchExpr) => {
            try checkLinearMatch(checker, env, node, matchExpr);
        }
        case ast::NodeValue::Try(tryExpr) => {
            try checkLinearNode(checker, env, tryExpr.expr, usage);
            let success = *env;
            for catchNode in tryExpr.catches {
                let case ast::NodeValue::CatchClause(catchClause) = catchNode.value
                    else panic "checkLinearNode: expected catch";
                let mut branch = success;
                let start = branch.len;
                if let binding = catchClause.binding {
                    try addLinearBinding(checker, &mut branch, binding);
                }
                try checkLinearNode(checker, &mut branch, catchClause.body, usage);
                try finishLinearScope(checker, &mut branch, start);
                try joinLinearBranches(checker, env, *env, branch, node);
            }
        }
        case ast::NodeValue::While(whileStmt) => {
            enterLinearLoop(checker, env);
            try checkLinearNode(checker, env, whileStmt.condition, LinearUse::Consume);
            let conditionExit = *env;
            setLinearLoopNaturalExit(checker, &conditionExit);
            let mut bodyEnv = conditionExit;
            try checkLinearNode(checker, &mut bodyEnv, whileStmt.body, LinearUse::Discard);
            try checkLinearLoopBackEdge(checker, &bodyEnv, whileStmt.body);
            exitLinearLoop(checker);
            set *env = conditionExit;
            if let elseBranch = whileStmt.elseBranch {
                let mut elseEnv = conditionExit;
                try checkLinearNode(
                    checker,
                    &mut elseEnv,
                    elseBranch,
                    LinearUse::Discard,
                );
                try joinLinearBranches(checker, env, conditionExit, elseEnv, node);
            }
        }
        case ast::NodeValue::WhileLet(whileStmt) => {
            if let subjectTy = typeFor(checker.resolver, whileStmt.pattern.scrutinee);
                isLinear(subjectTy)
            {
                throw emitError(
                    checker.resolver,
                    whileStmt.pattern.scrutinee,
                    ErrorKind::LinearPartialMove,
                );
            }
            let base = *env;
            enterLinearLoop(checker, env);
            let mut bodyEnv = base;
            try checkLinearNode(
                checker,
                &mut bodyEnv,
                whileStmt.pattern.scrutinee,
                LinearUse::Consume,
            );
            let mut conditionExit = bodyEnv;
            let start = bodyEnv.len;
            try addLinearPatternBindings(checker, &mut bodyEnv, whileStmt.pattern.pattern);
            if let guard = whileStmt.pattern.guard {
                try checkLinearNode(checker, &mut bodyEnv, guard, LinearUse::Consume);
                let mut guardExit = bodyEnv;
                try finishLinearScope(checker, &mut guardExit, start);
                try joinLinearBranches(
                    checker,
                    &mut conditionExit,
                    conditionExit,
                    guardExit,
                    guard,
                );
            }
            setLinearLoopNaturalExit(checker, &conditionExit);
            try checkLinearNode(checker, &mut bodyEnv, whileStmt.body, LinearUse::Discard);
            try finishLinearScope(checker, &mut bodyEnv, start);
            try checkLinearLoopBackEdge(checker, &bodyEnv, whileStmt.body);
            exitLinearLoop(checker);
            set *env = conditionExit;
            if let elseBranch = whileStmt.elseBranch {
                let mut elseEnv = conditionExit;
                try checkLinearNode(
                    checker,
                    &mut elseEnv,
                    elseBranch,
                    LinearUse::Discard,
                );
                try joinLinearBranches(checker, env, conditionExit, elseEnv, node);
            }
        }
        case ast::NodeValue::For(forStmt) => {
            if let iterableTy = typeFor(checker.resolver, forStmt.iterable) {
                if isLinear(iterableTy) {
                    throw emitError(
                        checker.resolver,
                        forStmt.iterable,
                        ErrorKind::LinearPartialMove,
                    );
                }
            }
            try checkLinearNode(checker, env, forStmt.iterable, LinearUse::Consume);
            let base = *env;
            enterLinearLoop(checker, env);
            setLinearLoopNaturalExit(checker, &base);
            let mut bodyEnv = base;
            let start = bodyEnv.len;
            try addLinearBinding(checker, &mut bodyEnv, forStmt.binding);
            if let index = forStmt.index {
                try addLinearBinding(checker, &mut bodyEnv, index);
            }
            try checkLinearNode(checker, &mut bodyEnv, forStmt.body, LinearUse::Discard);
            try finishLinearScope(checker, &mut bodyEnv, start);
            try checkLinearLoopBackEdge(checker, &bodyEnv, forStmt.body);
            exitLinearLoop(checker);
            set *env = base;
            if let elseBranch = forStmt.elseBranch {
                let mut elseEnv = base;
                try checkLinearNode(
                    checker,
                    &mut elseEnv,
                    elseBranch,
                    LinearUse::Discard,
                );
                try joinLinearBranches(checker, env, base, elseEnv, node);
            }
        }
        case ast::NodeValue::Loop { body } => {
            let base = *env;
            enterLinearLoop(checker, env);
            let mut bodyEnv = base;
            try checkLinearNode(checker, &mut bodyEnv, body, LinearUse::Discard);
            try checkLinearLoopBackEdge(checker, &bodyEnv, body);
            let depth = checker.loopDepth - 1;
            let breakSeen = checker.loopBreakSeen[depth];
            let exitAvailable = checker.loopExitAvailable[depth];
            exitLinearLoop(checker);
            set *env = base;
            if breakSeen {
                set env.available = exitAvailable;
            } else {
                set env.terminated = true;
            }
        }
        case ast::NodeValue::Break => {
            assert checker.loopDepth > 0, "linear loop control outside loop";
            let start = checker.loopMarks[checker.loopDepth - 1];
            try finishLinearScope(checker, env, start);
            try checkLinearLoopBreak(checker, env, node);
            set env.terminated = true;
        }
        case ast::NodeValue::Continue => {
            assert checker.loopDepth > 0, "linear loop control outside loop";
            let start = checker.loopMarks[checker.loopDepth - 1];
            try finishLinearScope(checker, env, start);
            try checkLinearLoopBackEdge(checker, env, node);
            set env.terminated = true;
        }
        case ast::NodeValue::Return { value } => {
            if let expr = value {
                try checkLinearNode(checker, env, expr, LinearUse::Consume);
            }
            try finishLinearExit(checker, env);
        }
        case ast::NodeValue::Throw { expr } => {
            try checkLinearNode(checker, env, expr, LinearUse::Consume);
            try finishLinearExit(checker, env);
        }
        case ast::NodeValue::Panic { message } => {
            if let expr = message {
                try checkLinearNode(checker, env, expr, LinearUse::Consume);
            }
            set env.terminated = true;
        }
        case ast::NodeValue::Assert { condition, message } => {
            try checkLinearNode(checker, env, condition, LinearUse::Consume);
            if let expr = message {
                try checkLinearNode(checker, env, expr, LinearUse::Consume);
            }
        }
        else => {}
    }
}

/// Check exact-use ownership for one resolved function.
fn checkLinearFn(
    self: *mut Resolver,
    receiver: ?*ast::Node,
    params: *mut [*ast::Node],
    body: *ast::Node,
) throws (ResolveError) {
    let mut checker = LinearChecker {
        resolver: self,
        loopMarks: [0; MAX_LINEAR_LOOP_DEPTH],
        loopAvailable: [0; MAX_LINEAR_LOOP_DEPTH],
        loopExitAvailable: [0; MAX_LINEAR_LOOP_DEPTH],
        loopHasNaturalExit: [false; MAX_LINEAR_LOOP_DEPTH],
        loopBreakSeen: [false; MAX_LINEAR_LOOP_DEPTH],
        loopDepth: 0,
    };
    let mut env = LinearEnv {
        symbols: [nil; MAX_LINEAR_BINDINGS],
        available: 0,
        len: 0,
        terminated: false,
    };
    if let receiverNode = receiver {
        try addLinearBinding(&mut checker, &mut env, receiverNode);
    }
    for paramNode in params {
        let case ast::NodeValue::FnParam(_) = paramNode.value
            else panic "checkLinearFn: expected parameter";
        try addLinearBinding(&mut checker, &mut env, paramNode);
    }
    try checkLinearNode(&mut checker, &mut env, body, LinearUse::Discard);
    try finishLinearScope(&mut checker, &mut env, 0);
}

/// 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.
export fn resolve(self: *mut Resolver, graph: *module::ModuleGraph, packages: *[Pkg]) -> Diagnostics throws (ResolveError) {
    set 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;
        }
        try closeGenericFnSpecializations(self) catch {
            return Diagnostics { errors: self.errors };
        };
    }
    // Data roots are validated after every package has had a chance to provide
    // an explicit root for a shared specialization.
    try validateGenericDataRoots(self) catch {
        return Diagnostics { errors: self.errors };
    };
    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.
    set self.scope = scope;
    set self.currentMod = rootId;
    set self.genericRoots = 0;
    set self.genericSpecializationCount = 0;

    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 };
}