harn_parser/

typechecker.rs

use std::collections::BTreeMap;

use crate::ast::*;
use crate::builtin_signatures;
use harn_lexer::{FixEdit, Span};

/// An inlay hint produced during type checking.
#[derive(Debug, Clone)]
pub struct InlayHintInfo {
    /// Position (line, column) where the hint should be displayed (after the variable name).
    pub line: usize,
    pub column: usize,
    /// The type label to display (e.g. ": string").
    pub label: String,
}

/// A diagnostic produced by the type checker.
#[derive(Debug, Clone)]
pub struct TypeDiagnostic {
    pub message: String,
    pub severity: DiagnosticSeverity,
    pub span: Option<Span>,
    pub help: Option<String>,
    /// Machine-applicable fix edits.
    pub fix: Option<Vec<FixEdit>>,
}

#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum DiagnosticSeverity {
    Error,
    Warning,
}

/// Inferred type of an expression. None means unknown/untyped (gradual typing).
type InferredType = Option<TypeExpr>;

/// The polarity of a position in a type when checking subtyping.
///
/// Polarity propagates through compound types: `FnType` flips it on
/// its parameters; `Invariant` absorbs any further flip.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
enum Polarity {
    Covariant,
    Contravariant,
    Invariant,
}

impl Polarity {
    /// Compose the outer position polarity with the declared variance
    /// of a type parameter (or the hard-coded variance of a compound
    /// type constructor's slot).
    fn compose(self, child: Variance) -> Polarity {
        match (self, child) {
            (_, Variance::Invariant) | (Polarity::Invariant, _) => Polarity::Invariant,
            (p, Variance::Covariant) => p,
            (Polarity::Covariant, Variance::Contravariant) => Polarity::Contravariant,
            (Polarity::Contravariant, Variance::Contravariant) => Polarity::Covariant,
        }
    }
}

#[derive(Debug, Clone)]
struct EnumDeclInfo {
    type_params: Vec<TypeParam>,
    variants: Vec<EnumVariant>,
}

#[derive(Debug, Clone)]
struct StructDeclInfo {
    type_params: Vec<TypeParam>,
    fields: Vec<StructField>,
}

#[derive(Debug, Clone)]
struct InterfaceDeclInfo {
    type_params: Vec<TypeParam>,
    associated_types: Vec<(String, Option<TypeExpr>)>,
    methods: Vec<InterfaceMethod>,
}

/// Scope for tracking variable types.
#[derive(Debug, Clone)]
struct TypeScope {
    /// Variable name → inferred type.
    vars: BTreeMap<String, InferredType>,
    /// Function name → (param types, return type).
    functions: BTreeMap<String, FnSignature>,
    /// Named type aliases.
    type_aliases: BTreeMap<String, TypeExpr>,
    /// Enum declarations with generic and variant metadata.
    enums: BTreeMap<String, EnumDeclInfo>,
    /// Interface declarations with associated types and methods.
    interfaces: BTreeMap<String, InterfaceDeclInfo>,
    /// Struct declarations with generic and field metadata.
    structs: BTreeMap<String, StructDeclInfo>,
    /// Impl block methods: type_name → method signatures.
    impl_methods: BTreeMap<String, Vec<ImplMethodSig>>,
    /// Generic type parameter names in scope (treated as compatible with any type).
    generic_type_params: std::collections::BTreeSet<String>,
    /// Where-clause constraints: type_param → interface_bound.
    /// Used for definition-site checking of generic function bodies.
    where_constraints: BTreeMap<String, String>,
    /// Variables declared with `var` (mutable). Variables not in this set
    /// are immutable (`let`, function params, loop vars, etc.).
    mutable_vars: std::collections::BTreeSet<String>,
    /// Variables that have been narrowed by flow-sensitive refinement.
    /// Maps var name → pre-narrowing type (used to restore on reassignment).
    narrowed_vars: BTreeMap<String, InferredType>,
    /// Schema literals bound to variables, reduced to a TypeExpr subset so
    /// `schema_is(x, some_schema)` can participate in flow refinement.
    schema_bindings: BTreeMap<String, InferredType>,
    /// Variables holding unvalidated values from boundary APIs (json_parse, llm_call, etc.).
    /// Maps var name → source function name (e.g. "json_parse").
    /// Empty string = explicitly cleared (shadows parent scope entry).
    untyped_sources: BTreeMap<String, String>,
    /// Concrete `type_of` variants ruled out on the current flow path for each
    /// `unknown`-typed variable. Drives the exhaustive-narrowing warning at
    /// `unreachable()` / `throw` / `never`-returning calls.
    unknown_ruled_out: BTreeMap<String, Vec<String>>,
    parent: Option<Box<TypeScope>>,
}

/// Method signature extracted from an impl block (for interface checking).
#[derive(Debug, Clone)]
struct ImplMethodSig {
    name: String,
    /// Number of parameters excluding `self`.
    param_count: usize,
    /// Parameter types (excluding `self`), None means untyped.
    param_types: Vec<Option<TypeExpr>>,
    /// Return type, None means untyped.
    return_type: Option<TypeExpr>,
}

#[derive(Debug, Clone)]
struct FnSignature {
    params: Vec<(String, InferredType)>,
    return_type: InferredType,
    /// Generic type parameter names declared on the function.
    type_param_names: Vec<String>,
    /// Number of required parameters (those without defaults).
    required_params: usize,
    /// Where-clause constraints: (type_param_name, interface_bound).
    where_clauses: Vec<(String, String)>,
    /// True if the last parameter is a rest parameter.
    has_rest: bool,
}

impl TypeScope {
    fn new() -> Self {
        let mut scope = Self {
            vars: BTreeMap::new(),
            functions: BTreeMap::new(),
            type_aliases: BTreeMap::new(),
            enums: BTreeMap::new(),
            interfaces: BTreeMap::new(),
            structs: BTreeMap::new(),
            impl_methods: BTreeMap::new(),
            generic_type_params: std::collections::BTreeSet::new(),
            where_constraints: BTreeMap::new(),
            mutable_vars: std::collections::BTreeSet::new(),
            narrowed_vars: BTreeMap::new(),
            schema_bindings: BTreeMap::new(),
            untyped_sources: BTreeMap::new(),
            unknown_ruled_out: BTreeMap::new(),
            parent: None,
        };
        scope.enums.insert(
            "Result".into(),
            EnumDeclInfo {
                type_params: vec![
                    TypeParam {
                        name: "T".into(),
                        variance: Variance::Covariant,
                    },
                    TypeParam {
                        name: "E".into(),
                        variance: Variance::Covariant,
                    },
                ],
                variants: vec![
                    EnumVariant {
                        name: "Ok".into(),
                        fields: vec![TypedParam {
                            name: "value".into(),
                            type_expr: Some(TypeExpr::Named("T".into())),
                            default_value: None,
                            rest: false,
                        }],
                    },
                    EnumVariant {
                        name: "Err".into(),
                        fields: vec![TypedParam {
                            name: "error".into(),
                            type_expr: Some(TypeExpr::Named("E".into())),
                            default_value: None,
                            rest: false,
                        }],
                    },
                ],
            },
        );
        scope
    }

    fn child(&self) -> Self {
        Self {
            vars: BTreeMap::new(),
            functions: BTreeMap::new(),
            type_aliases: BTreeMap::new(),
            enums: BTreeMap::new(),
            interfaces: BTreeMap::new(),
            structs: BTreeMap::new(),
            impl_methods: BTreeMap::new(),
            generic_type_params: std::collections::BTreeSet::new(),
            where_constraints: BTreeMap::new(),
            mutable_vars: std::collections::BTreeSet::new(),
            narrowed_vars: BTreeMap::new(),
            schema_bindings: BTreeMap::new(),
            untyped_sources: BTreeMap::new(),
            unknown_ruled_out: BTreeMap::new(),
            parent: Some(Box::new(self.clone())),
        }
    }

    fn get_var(&self, name: &str) -> Option<&InferredType> {
        self.vars
            .get(name)
            .or_else(|| self.parent.as_ref()?.get_var(name))
    }

    /// Record that a concrete `type_of` variant has been ruled out for
    /// an `unknown`-typed variable on the current flow path.
    fn add_unknown_ruled_out(&mut self, var_name: &str, type_name: &str) {
        if !self.unknown_ruled_out.contains_key(var_name) {
            let inherited = self.lookup_unknown_ruled_out(var_name);
            self.unknown_ruled_out
                .insert(var_name.to_string(), inherited);
        }
        let entry = self
            .unknown_ruled_out
            .get_mut(var_name)
            .expect("just inserted");
        if !entry.iter().any(|t| t == type_name) {
            entry.push(type_name.to_string());
        }
    }

    /// Return the ruled-out concrete types recorded for `var_name` across
    /// the current scope chain (child entries mask parent entries).
    fn lookup_unknown_ruled_out(&self, var_name: &str) -> Vec<String> {
        if let Some(list) = self.unknown_ruled_out.get(var_name) {
            list.clone()
        } else if let Some(parent) = &self.parent {
            parent.lookup_unknown_ruled_out(var_name)
        } else {
            Vec::new()
        }
    }

    /// Collect every `unknown`-typed variable that has at least one ruled-out
    /// concrete type on the current flow path (merged across parent scopes).
    fn collect_unknown_ruled_out(&self) -> BTreeMap<String, Vec<String>> {
        let mut out: BTreeMap<String, Vec<String>> = BTreeMap::new();
        self.collect_unknown_ruled_out_inner(&mut out);
        out
    }

    fn collect_unknown_ruled_out_inner(&self, acc: &mut BTreeMap<String, Vec<String>>) {
        if let Some(parent) = &self.parent {
            parent.collect_unknown_ruled_out_inner(acc);
        }
        for (name, list) in &self.unknown_ruled_out {
            acc.insert(name.clone(), list.clone());
        }
    }

    /// Drop the ruled-out set for a variable (used on reassignment).
    fn clear_unknown_ruled_out(&mut self, var_name: &str) {
        // Shadow any parent entry with an empty list so lookups in this
        // scope (and its children) treat the variable as un-narrowed.
        self.unknown_ruled_out
            .insert(var_name.to_string(), Vec::new());
    }

    fn get_fn(&self, name: &str) -> Option<&FnSignature> {
        self.functions
            .get(name)
            .or_else(|| self.parent.as_ref()?.get_fn(name))
    }

    fn get_schema_binding(&self, name: &str) -> Option<&InferredType> {
        self.schema_bindings
            .get(name)
            .or_else(|| self.parent.as_ref()?.get_schema_binding(name))
    }

    fn resolve_type(&self, name: &str) -> Option<&TypeExpr> {
        self.type_aliases
            .get(name)
            .or_else(|| self.parent.as_ref()?.resolve_type(name))
    }

    fn is_generic_type_param(&self, name: &str) -> bool {
        self.generic_type_params.contains(name)
            || self
                .parent
                .as_ref()
                .is_some_and(|p| p.is_generic_type_param(name))
    }

    fn get_where_constraint(&self, type_param: &str) -> Option<&str> {
        self.where_constraints
            .get(type_param)
            .map(|s| s.as_str())
            .or_else(|| {
                self.parent
                    .as_ref()
                    .and_then(|p| p.get_where_constraint(type_param))
            })
    }

    fn get_enum(&self, name: &str) -> Option<&EnumDeclInfo> {
        self.enums
            .get(name)
            .or_else(|| self.parent.as_ref()?.get_enum(name))
    }

    fn get_interface(&self, name: &str) -> Option<&InterfaceDeclInfo> {
        self.interfaces
            .get(name)
            .or_else(|| self.parent.as_ref()?.get_interface(name))
    }

    fn get_struct(&self, name: &str) -> Option<&StructDeclInfo> {
        self.structs
            .get(name)
            .or_else(|| self.parent.as_ref()?.get_struct(name))
    }

    fn get_impl_methods(&self, name: &str) -> Option<&Vec<ImplMethodSig>> {
        self.impl_methods
            .get(name)
            .or_else(|| self.parent.as_ref()?.get_impl_methods(name))
    }

    /// Look up declared variance for each type parameter of a
    /// constructor (enum / struct / interface). Returns `None` if the
    /// name is not a known user-declared generic. Built-in type
    /// constructors that live outside `Applied` (list, dict, iter,
    /// FnType) are handled directly in the subtype match arms rather
    /// than via this table.
    fn variance_of(&self, name: &str) -> Option<Vec<Variance>> {
        if let Some(info) = self.get_enum(name) {
            return Some(info.type_params.iter().map(|tp| tp.variance).collect());
        }
        if let Some(info) = self.get_struct(name) {
            return Some(info.type_params.iter().map(|tp| tp.variance).collect());
        }
        if let Some(info) = self.get_interface(name) {
            return Some(info.type_params.iter().map(|tp| tp.variance).collect());
        }
        None
    }

    fn define_var(&mut self, name: &str, ty: InferredType) {
        self.vars.insert(name.to_string(), ty);
    }

    fn define_var_mutable(&mut self, name: &str, ty: InferredType) {
        self.vars.insert(name.to_string(), ty);
        self.mutable_vars.insert(name.to_string());
    }

    fn define_schema_binding(&mut self, name: &str, ty: InferredType) {
        self.schema_bindings.insert(name.to_string(), ty);
    }

    /// Check whether a variable holds an unvalidated boundary-API value.
    /// Returns the source function name (e.g. "json_parse") or `None`.
    fn is_untyped_source(&self, name: &str) -> Option<&str> {
        if let Some(source) = self.untyped_sources.get(name) {
            if source.is_empty() {
                return None; // explicitly cleared in this scope
            }
            return Some(source.as_str());
        }
        self.parent.as_ref()?.is_untyped_source(name)
    }

    fn mark_untyped_source(&mut self, name: &str, source: &str) {
        self.untyped_sources
            .insert(name.to_string(), source.to_string());
    }

    /// Clear the untyped-source flag for a variable, shadowing any parent entry.
    fn clear_untyped_source(&mut self, name: &str) {
        self.untyped_sources.insert(name.to_string(), String::new());
    }

    /// Check if a variable is mutable (declared with `var`).
    fn is_mutable(&self, name: &str) -> bool {
        self.mutable_vars.contains(name) || self.parent.as_ref().is_some_and(|p| p.is_mutable(name))
    }

    fn define_fn(&mut self, name: &str, sig: FnSignature) {
        self.functions.insert(name.to_string(), sig);
    }
}

/// Bidirectional type refinements extracted from a condition.
/// Each path contains a list of (variable_name, narrowed_type) pairs.
#[derive(Debug, Clone, Default)]
struct Refinements {
    /// Narrowings when the condition evaluates to true/truthy.
    truthy: Vec<(String, InferredType)>,
    /// Narrowings when the condition evaluates to false/falsy.
    falsy: Vec<(String, InferredType)>,
    /// Concrete `type_of` variants (var_name, type_name) to add to the
    /// ruled-out coverage set on the truthy branch. Only populated for
    /// `type_of(x) != "T"` patterns against `unknown`-typed values.
    truthy_ruled_out: Vec<(String, String)>,
    /// Same as `truthy_ruled_out` but applied on the falsy branch — the
    /// common case for `if type_of(x) == "T" { return }` exhaustiveness
    /// patterns.
    falsy_ruled_out: Vec<(String, String)>,
}

impl Refinements {
    fn empty() -> Self {
        Self::default()
    }

    /// Swap truthy and falsy (used for negation).
    fn inverted(self) -> Self {
        Self {
            truthy: self.falsy,
            falsy: self.truthy,
            truthy_ruled_out: self.falsy_ruled_out,
            falsy_ruled_out: self.truthy_ruled_out,
        }
    }

    /// Apply the truthy-branch narrowings and ruled-out additions to `scope`.
    fn apply_truthy(&self, scope: &mut TypeScope) {
        apply_refinements(scope, &self.truthy);
        for (var, ty) in &self.truthy_ruled_out {
            scope.add_unknown_ruled_out(var, ty);
        }
    }

    /// Apply the falsy-branch narrowings and ruled-out additions to `scope`.
    fn apply_falsy(&self, scope: &mut TypeScope) {
        apply_refinements(scope, &self.falsy);
        for (var, ty) in &self.falsy_ruled_out {
            scope.add_unknown_ruled_out(var, ty);
        }
    }
}

/// Known return types for builtin functions. Delegates to the shared
/// [`builtin_signatures`] registry — see that module for the full table.
fn builtin_return_type(name: &str) -> InferredType {
    builtin_signatures::builtin_return_type(name)
}

/// Check if a name is a known builtin. Delegates to the shared
/// [`builtin_signatures`] registry.
fn is_builtin(name: &str) -> bool {
    builtin_signatures::is_builtin(name)
}

/// The static type checker.
pub struct TypeChecker {
    diagnostics: Vec<TypeDiagnostic>,
    scope: TypeScope,
    source: Option<String>,
    hints: Vec<InlayHintInfo>,
    /// When true, flag unvalidated boundary-API values used in field access.
    strict_types: bool,
    /// Lexical depth of enclosing function-like bodies (fn/tool/pipeline/closure).
    /// `try*` requires `fn_depth > 0` so the rethrow has a body to live in.
    fn_depth: usize,
    /// Maps function name -> deprecation metadata `(since, use_hint)`. Populated
    /// when an `@deprecated` attribute is encountered on a top-level fn decl
    /// during the `check_inner` pre-pass; consulted at every `FunctionCall`
    /// site to emit a warning + help line.
    deprecated_fns: std::collections::HashMap<String, (Option<String>, Option<String>)>,
}

impl TypeChecker {
    fn wildcard_type() -> TypeExpr {
        TypeExpr::Named("_".into())
    }

    fn is_wildcard_type(ty: &TypeExpr) -> bool {
        matches!(ty, TypeExpr::Named(name) if name == "_")
    }

    fn base_type_name(ty: &TypeExpr) -> Option<&str> {
        match ty {
            TypeExpr::Named(name) => Some(name.as_str()),
            TypeExpr::Applied { name, .. } => Some(name.as_str()),
            _ => None,
        }
    }

    pub fn new() -> Self {
        Self {
            diagnostics: Vec::new(),
            scope: TypeScope::new(),
            source: None,
            hints: Vec::new(),
            strict_types: false,
            fn_depth: 0,
            deprecated_fns: std::collections::HashMap::new(),
        }
    }

    /// Create a type checker with strict types mode.
    /// When enabled, flags unvalidated boundary-API values used in field access.
    pub fn with_strict_types(strict: bool) -> Self {
        Self {
            diagnostics: Vec::new(),
            scope: TypeScope::new(),
            source: None,
            hints: Vec::new(),
            strict_types: strict,
            fn_depth: 0,
            deprecated_fns: std::collections::HashMap::new(),
        }
    }

    /// Check a program with source text for autofix generation.
    pub fn check_with_source(mut self, program: &[SNode], source: &str) -> Vec<TypeDiagnostic> {
        self.source = Some(source.to_string());
        self.check_inner(program).0
    }

    /// Check a program with strict types mode and source text.
    pub fn check_strict_with_source(
        mut self,
        program: &[SNode],
        source: &str,
    ) -> Vec<TypeDiagnostic> {
        self.source = Some(source.to_string());
        self.check_inner(program).0
    }

    /// Check a program and return diagnostics.
    pub fn check(self, program: &[SNode]) -> Vec<TypeDiagnostic> {
        self.check_inner(program).0
    }

    /// Check whether a function call value is a boundary source that produces
    /// unvalidated data.  Returns `None` if the value is type-safe
    /// (e.g. llm_call with a schema option, or a non-boundary function).
    fn detect_boundary_source(value: &SNode, scope: &TypeScope) -> Option<String> {
        match &value.node {
            Node::FunctionCall { name, args } => {
                if !builtin_signatures::is_untyped_boundary_source(name) {
                    return None;
                }
                // llm_call/llm_completion with a schema option are type-safe
                if (name == "llm_call" || name == "llm_completion")
                    && Self::llm_call_has_typed_schema_option(args, scope)
                {
                    return None;
                }
                Some(name.clone())
            }
            Node::Identifier(name) => scope.is_untyped_source(name).map(|s| s.to_string()),
            _ => None,
        }
    }

    /// True if an `llm_call` / `llm_completion` options dict names a
    /// resolvable output schema. Used by the strict-types boundary checks
    /// to suppress "unvalidated" warnings when the call site is typed.
    /// Actual return-type narrowing is driven by the generic-builtin
    /// dispatch path in `infer_type`, not this helper.
    fn llm_call_has_typed_schema_option(args: &[SNode], scope: &TypeScope) -> bool {
        let Some(opts) = args.get(2) else {
            return false;
        };
        let Node::DictLiteral(entries) = &opts.node else {
            return false;
        };
        entries.iter().any(|entry| {
            let key = match &entry.key.node {
                Node::StringLiteral(k) | Node::Identifier(k) => k.as_str(),
                _ => return false,
            };
            (key == "schema" || key == "output_schema")
                && schema_type_expr_from_node(&entry.value, scope).is_some()
        })
    }

    /// Check whether a type annotation is a concrete shape/struct type
    /// (as opposed to bare `dict` or no annotation).
    fn is_concrete_type(ty: &TypeExpr) -> bool {
        matches!(
            ty,
            TypeExpr::Shape(_)
                | TypeExpr::Applied { .. }
                | TypeExpr::FnType { .. }
                | TypeExpr::List(_)
                | TypeExpr::Iter(_)
                | TypeExpr::DictType(_, _)
        ) || matches!(ty, TypeExpr::Named(n) if n != "dict" && n != "any" && n != "_")
    }

    /// Check a program and return both diagnostics and inlay hints.
    pub fn check_with_hints(
        mut self,
        program: &[SNode],
        source: &str,
    ) -> (Vec<TypeDiagnostic>, Vec<InlayHintInfo>) {
        self.source = Some(source.to_string());
        self.check_inner(program)
    }

    fn check_inner(mut self, program: &[SNode]) -> (Vec<TypeDiagnostic>, Vec<InlayHintInfo>) {
        // First pass: collect declarations (type/enum/struct/interface) into scope
        // before type-checking bodies so forward references resolve.
        Self::register_declarations_into(&mut self.scope, program);
        for snode in program {
            if let Node::Pipeline { body, .. } = &snode.node {
                Self::register_declarations_into(&mut self.scope, body);
            }
        }

        // Pre-pass: index `@deprecated` attributes on top-level fn decls so
        // `check_call` (and the standalone deprecation visitor below) can
        // flag callers anywhere in the program.
        for snode in program {
            if let Node::AttributedDecl { attributes, inner } = &snode.node {
                if let Node::FnDecl { name, .. } = &inner.node {
                    for attr in attributes {
                        if attr.name == "deprecated" {
                            let since = attr.string_arg("since");
                            let use_hint = attr.string_arg("use");
                            self.deprecated_fns.insert(name.clone(), (since, use_hint));
                        }
                    }
                }
            }
        }

        // Walk every node looking for FunctionCalls of deprecated names.
        // This catches calls in contexts (e.g. `let x = old_fn()`) where
        // `check_node`'s FunctionCall arm doesn't fire because the value
        // is inferred rather than checked.
        if !self.deprecated_fns.is_empty() {
            for snode in program {
                self.visit_for_deprecation(snode);
            }
        }

        for snode in program {
            // Transparently process attributed wrappers around top-level
            // declarations. Attribute-specific semantics (deprecation,
            // unknown-attribute warnings) were already applied above and
            // by `check_attributes`.
            let inner_node = match &snode.node {
                Node::AttributedDecl { inner, .. } => inner.as_ref(),
                _ => snode,
            };
            match &inner_node.node {
                Node::Pipeline { params, body, .. } => {
                    let mut child = self.scope.child();
                    for p in params {
                        child.define_var(p, None);
                    }
                    self.fn_depth += 1;
                    self.check_block(body, &mut child);
                    self.fn_depth -= 1;
                }
                Node::FnDecl {
                    name,
                    type_params,
                    params,
                    return_type,
                    where_clauses,
                    body,
                    ..
                } => {
                    let required_params =
                        params.iter().filter(|p| p.default_value.is_none()).count();
                    let sig = FnSignature {
                        params: params
                            .iter()
                            .map(|p| (p.name.clone(), p.type_expr.clone()))
                            .collect(),
                        return_type: return_type.clone(),
                        type_param_names: type_params.iter().map(|tp| tp.name.clone()).collect(),
                        required_params,
                        where_clauses: where_clauses
                            .iter()
                            .map(|wc| (wc.type_name.clone(), wc.bound.clone()))
                            .collect(),
                        has_rest: params.last().is_some_and(|p| p.rest),
                    };
                    self.scope.define_fn(name, sig);
                    self.check_fn_body(type_params, params, return_type, body, where_clauses);
                }
                _ => {
                    let mut scope = self.scope.clone();
                    self.check_node(snode, &mut scope);
                    // Promote top-level definitions out of the temporary scope.
                    for (name, ty) in scope.vars {
                        self.scope.vars.entry(name).or_insert(ty);
                    }
                    for name in scope.mutable_vars {
                        self.scope.mutable_vars.insert(name);
                    }
                }
            }
        }

        (self.diagnostics, self.hints)
    }

    /// Register type, enum, interface, and struct declarations from AST nodes into a scope.
    fn register_declarations_into(scope: &mut TypeScope, nodes: &[SNode]) {
        for snode in nodes {
            match &snode.node {
                Node::TypeDecl {
                    name,
                    type_params: _,
                    type_expr,
                } => {
                    scope.type_aliases.insert(name.clone(), type_expr.clone());
                }
                Node::EnumDecl {
                    name,
                    type_params,
                    variants,
                    ..
                } => {
                    scope.enums.insert(
                        name.clone(),
                        EnumDeclInfo {
                            type_params: type_params.clone(),
                            variants: variants.clone(),
                        },
                    );
                }
                Node::InterfaceDecl {
                    name,
                    type_params,
                    associated_types,
                    methods,
                } => {
                    scope.interfaces.insert(
                        name.clone(),
                        InterfaceDeclInfo {
                            type_params: type_params.clone(),
                            associated_types: associated_types.clone(),
                            methods: methods.clone(),
                        },
                    );
                }
                Node::StructDecl {
                    name,
                    type_params,
                    fields,
                    ..
                } => {
                    scope.structs.insert(
                        name.clone(),
                        StructDeclInfo {
                            type_params: type_params.clone(),
                            fields: fields.clone(),
                        },
                    );
                }
                Node::ImplBlock {
                    type_name, methods, ..
                } => {
                    let sigs: Vec<ImplMethodSig> = methods
                        .iter()
                        .filter_map(|m| {
                            if let Node::FnDecl {
                                name,
                                params,
                                return_type,
                                ..
                            } = &m.node
                            {
                                let non_self: Vec<_> =
                                    params.iter().filter(|p| p.name != "self").collect();
                                let param_count = non_self.len();
                                let param_types: Vec<Option<TypeExpr>> =
                                    non_self.iter().map(|p| p.type_expr.clone()).collect();
                                Some(ImplMethodSig {
                                    name: name.clone(),
                                    param_count,
                                    param_types,
                                    return_type: return_type.clone(),
                                })
                            } else {
                                None
                            }
                        })
                        .collect();
                    scope.impl_methods.insert(type_name.clone(), sigs);
                }
                _ => {}
            }
        }
    }

    fn check_block(&mut self, stmts: &[SNode], scope: &mut TypeScope) {
        let mut definitely_exited = false;
        for stmt in stmts {
            if definitely_exited {
                self.warning_at("unreachable code".to_string(), stmt.span);
                break; // warn once per block
            }
            self.check_node(stmt, scope);
            if Self::stmt_definitely_exits(stmt) {
                definitely_exited = true;
            }
        }
    }

    /// Check whether a single statement definitely exits (delegates to the free function).
    fn stmt_definitely_exits(stmt: &SNode) -> bool {
        stmt_definitely_exits(stmt)
    }

    /// Define variables from a destructuring pattern in the given scope (as unknown type).
    fn define_pattern_vars(pattern: &BindingPattern, scope: &mut TypeScope, mutable: bool) {
        let define = |scope: &mut TypeScope, name: &str| {
            if mutable {
                scope.define_var_mutable(name, None);
            } else {
                scope.define_var(name, None);
            }
        };
        match pattern {
            BindingPattern::Identifier(name) => {
                define(scope, name);
            }
            BindingPattern::Dict(fields) => {
                for field in fields {
                    let name = field.alias.as_deref().unwrap_or(&field.key);
                    define(scope, name);
                }
            }
            BindingPattern::List(elements) => {
                for elem in elements {
                    define(scope, &elem.name);
                }
            }
            BindingPattern::Pair(a, b) => {
                define(scope, a);
                define(scope, b);
            }
        }
    }

    /// Type-check default value expressions within a destructuring pattern.
    fn check_pattern_defaults(&mut self, pattern: &BindingPattern, scope: &mut TypeScope) {
        match pattern {
            BindingPattern::Identifier(_) => {}
            BindingPattern::Dict(fields) => {
                for field in fields {
                    if let Some(default) = &field.default_value {
                        self.check_binops(default, scope);
                    }
                }
            }
            BindingPattern::List(elements) => {
                for elem in elements {
                    if let Some(default) = &elem.default_value {
                        self.check_binops(default, scope);
                    }
                }
            }
            BindingPattern::Pair(_, _) => {}
        }
    }

    fn check_node(&mut self, snode: &SNode, scope: &mut TypeScope) {
        let span = snode.span;
        match &snode.node {
            Node::LetBinding {
                pattern,
                type_ann,
                value,
            } => {
                self.check_binops(value, scope);
                let inferred = self.infer_type(value, scope);
                if let BindingPattern::Identifier(name) = pattern {
                    if let Some(expected) = type_ann {
                        if let Some(actual) = &inferred {
                            if !self.types_compatible(expected, actual, scope) {
                                let mut msg = format!(
                                    "'{}' declared as {}, but assigned {}",
                                    name,
                                    format_type(expected),
                                    format_type(actual)
                                );
                                if let Some(detail) = shape_mismatch_detail(expected, actual) {
                                    msg.push_str(&format!(" ({})", detail));
                                }
                                self.error_at(msg, span);
                            }
                        }
                    }
                    // Collect inlay hint when type is inferred (no annotation)
                    if type_ann.is_none() {
                        if let Some(ref ty) = inferred {
                            if !is_obvious_type(value, ty) {
                                self.hints.push(InlayHintInfo {
                                    line: span.line,
                                    column: span.column + "let ".len() + name.len(),
                                    label: format!(": {}", format_type(ty)),
                                });
                            }
                        }
                    }
                    let ty = type_ann.clone().or(inferred);
                    scope.define_var(name, ty);
                    scope.define_schema_binding(name, schema_type_expr_from_node(value, scope));
                    // Strict types: mark variables assigned from boundary APIs
                    if self.strict_types {
                        if let Some(boundary) = Self::detect_boundary_source(value, scope) {
                            let has_concrete_ann =
                                type_ann.as_ref().is_some_and(Self::is_concrete_type);
                            if !has_concrete_ann {
                                scope.mark_untyped_source(name, &boundary);
                            }
                        }
                    }
                } else {
                    self.check_pattern_defaults(pattern, scope);
                    Self::define_pattern_vars(pattern, scope, false);
                }
            }

            Node::VarBinding {
                pattern,
                type_ann,
                value,
            } => {
                self.check_binops(value, scope);
                let inferred = self.infer_type(value, scope);
                if let BindingPattern::Identifier(name) = pattern {
                    if let Some(expected) = type_ann {
                        if let Some(actual) = &inferred {
                            if !self.types_compatible(expected, actual, scope) {
                                let mut msg = format!(
                                    "'{}' declared as {}, but assigned {}",
                                    name,
                                    format_type(expected),
                                    format_type(actual)
                                );
                                if let Some(detail) = shape_mismatch_detail(expected, actual) {
                                    msg.push_str(&format!(" ({})", detail));
                                }
                                self.error_at(msg, span);
                            }
                        }
                    }
                    if type_ann.is_none() {
                        if let Some(ref ty) = inferred {
                            if !is_obvious_type(value, ty) {
                                self.hints.push(InlayHintInfo {
                                    line: span.line,
                                    column: span.column + "var ".len() + name.len(),
                                    label: format!(": {}", format_type(ty)),
                                });
                            }
                        }
                    }
                    let ty = type_ann.clone().or(inferred);
                    scope.define_var_mutable(name, ty);
                    scope.define_schema_binding(name, schema_type_expr_from_node(value, scope));
                    // Strict types: mark variables assigned from boundary APIs
                    if self.strict_types {
                        if let Some(boundary) = Self::detect_boundary_source(value, scope) {
                            let has_concrete_ann =
                                type_ann.as_ref().is_some_and(Self::is_concrete_type);
                            if !has_concrete_ann {
                                scope.mark_untyped_source(name, &boundary);
                            }
                        }
                    }
                } else {
                    self.check_pattern_defaults(pattern, scope);
                    Self::define_pattern_vars(pattern, scope, true);
                }
            }

            Node::FnDecl {
                name,
                type_params,
                params,
                return_type,
                where_clauses,
                body,
                ..
            } => {
                let required_params = params.iter().filter(|p| p.default_value.is_none()).count();
                let sig = FnSignature {
                    params: params
                        .iter()
                        .map(|p| (p.name.clone(), p.type_expr.clone()))
                        .collect(),
                    return_type: return_type.clone(),
                    type_param_names: type_params.iter().map(|tp| tp.name.clone()).collect(),
                    required_params,
                    where_clauses: where_clauses
                        .iter()
                        .map(|wc| (wc.type_name.clone(), wc.bound.clone()))
                        .collect(),
                    has_rest: params.last().is_some_and(|p| p.rest),
                };
                scope.define_fn(name, sig.clone());
                scope.define_var(name, None);
                self.check_fn_decl_variance(type_params, params, return_type.as_ref(), name, span);
                self.check_fn_body(type_params, params, return_type, body, where_clauses);
            }

            Node::ToolDecl {
                name,
                params,
                return_type,
                body,
                ..
            } => {
                // Register the tool like a function for type checking purposes
                let required_params = params.iter().filter(|p| p.default_value.is_none()).count();
                let sig = FnSignature {
                    params: params
                        .iter()
                        .map(|p| (p.name.clone(), p.type_expr.clone()))
                        .collect(),
                    return_type: return_type.clone(),
                    type_param_names: Vec::new(),
                    required_params,
                    where_clauses: Vec::new(),
                    has_rest: params.last().is_some_and(|p| p.rest),
                };
                scope.define_fn(name, sig);
                scope.define_var(name, None);
                self.check_fn_body(&[], params, return_type, body, &[]);
            }

            Node::FunctionCall { name, args } => {
                self.check_call(name, args, scope, span);
                // Strict types: schema_expect clears untyped source status
                if self.strict_types && name == "schema_expect" && args.len() >= 2 {
                    if let Node::Identifier(var_name) = &args[0].node {
                        scope.clear_untyped_source(var_name);
                        if let Some(schema_type) = schema_type_expr_from_node(&args[1], scope) {
                            scope.define_var(var_name, Some(schema_type));
                        }
                    }
                }
            }

            Node::IfElse {
                condition,
                then_body,
                else_body,
            } => {
                self.check_node(condition, scope);
                let refs = Self::extract_refinements(condition, scope);

                let mut then_scope = scope.child();
                refs.apply_truthy(&mut then_scope);
                // Strict types: schema_is/is_type in condition clears
                // untyped source in then-branch
                if self.strict_types {
                    if let Node::FunctionCall { name, args } = &condition.node {
                        if (name == "schema_is" || name == "is_type") && args.len() == 2 {
                            if let Node::Identifier(var_name) = &args[0].node {
                                then_scope.clear_untyped_source(var_name);
                            }
                        }
                    }
                }
                self.check_block(then_body, &mut then_scope);

                if let Some(else_body) = else_body {
                    let mut else_scope = scope.child();
                    refs.apply_falsy(&mut else_scope);
                    self.check_block(else_body, &mut else_scope);

                    // Post-branch narrowing: if one branch definitely exits,
                    // apply the other branch's refinements to the outer scope
                    if Self::block_definitely_exits(then_body)
                        && !Self::block_definitely_exits(else_body)
                    {
                        refs.apply_falsy(scope);
                    } else if Self::block_definitely_exits(else_body)
                        && !Self::block_definitely_exits(then_body)
                    {
                        refs.apply_truthy(scope);
                    }
                } else {
                    // No else: if then-body always exits, apply falsy after
                    if Self::block_definitely_exits(then_body) {
                        refs.apply_falsy(scope);
                    }
                }
            }

            Node::ForIn {
                pattern,
                iterable,
                body,
            } => {
                self.check_node(iterable, scope);
                let mut loop_scope = scope.child();
                let iter_type = self.infer_type(iterable, scope);
                if let BindingPattern::Identifier(variable) = pattern {
                    // Infer loop variable type from iterable
                    let elem_type = match iter_type {
                        Some(TypeExpr::List(inner)) => Some(*inner),
                        Some(TypeExpr::Iter(inner)) => Some(*inner),
                        Some(TypeExpr::Applied { ref name, ref args })
                            if name == "Iter" && args.len() == 1 =>
                        {
                            Some(args[0].clone())
                        }
                        Some(TypeExpr::Named(n)) if n == "string" => {
                            Some(TypeExpr::Named("string".into()))
                        }
                        // Iterating a range always yields ints.
                        Some(TypeExpr::Named(n)) if n == "range" => {
                            Some(TypeExpr::Named("int".into()))
                        }
                        _ => None,
                    };
                    loop_scope.define_var(variable, elem_type);
                } else if let BindingPattern::Pair(a, b) = pattern {
                    // Pair destructuring: `for (k, v) in iter` — extract K, V
                    // from the yielded Pair<K, V>.
                    let (ka, vb) = match &iter_type {
                        Some(TypeExpr::Iter(inner)) => {
                            if let TypeExpr::Applied { name, args } = inner.as_ref() {
                                if name == "Pair" && args.len() == 2 {
                                    (Some(args[0].clone()), Some(args[1].clone()))
                                } else {
                                    (None, None)
                                }
                            } else {
                                (None, None)
                            }
                        }
                        Some(TypeExpr::Applied { name, args })
                            if name == "Iter" && args.len() == 1 =>
                        {
                            if let TypeExpr::Applied { name: n2, args: a2 } = &args[0] {
                                if n2 == "Pair" && a2.len() == 2 {
                                    (Some(a2[0].clone()), Some(a2[1].clone()))
                                } else {
                                    (None, None)
                                }
                            } else {
                                (None, None)
                            }
                        }
                        _ => (None, None),
                    };
                    loop_scope.define_var(a, ka);
                    loop_scope.define_var(b, vb);
                } else {
                    self.check_pattern_defaults(pattern, &mut loop_scope);
                    Self::define_pattern_vars(pattern, &mut loop_scope, false);
                }
                self.check_block(body, &mut loop_scope);
            }

            Node::WhileLoop { condition, body } => {
                self.check_node(condition, scope);
                let refs = Self::extract_refinements(condition, scope);
                let mut loop_scope = scope.child();
                refs.apply_truthy(&mut loop_scope);
                self.check_block(body, &mut loop_scope);
            }

            Node::RequireStmt { condition, message } => {
                self.check_node(condition, scope);
                if let Some(message) = message {
                    self.check_node(message, scope);
                }
            }

            Node::TryCatch {
                body,
                error_var,
                error_type,
                catch_body,
                finally_body,
                ..
            } => {
                let mut try_scope = scope.child();
                self.check_block(body, &mut try_scope);
                let mut catch_scope = scope.child();
                if let Some(var) = error_var {
                    catch_scope.define_var(var, error_type.clone());
                }
                self.check_block(catch_body, &mut catch_scope);
                if let Some(fb) = finally_body {
                    let mut finally_scope = scope.child();
                    self.check_block(fb, &mut finally_scope);
                }
            }

            Node::TryExpr { body } => {
                let mut try_scope = scope.child();
                self.check_block(body, &mut try_scope);
            }

            Node::TryStar { operand } => {
                if self.fn_depth == 0 {
                    self.error_at(
                        "try* requires an enclosing function (fn, tool, or pipeline) so the rethrow has a target".to_string(),
                        span,
                    );
                }
                self.check_node(operand, scope);
            }

            Node::ReturnStmt {
                value: Some(val), ..
            } => {
                self.check_node(val, scope);
            }

            Node::Assignment {
                target, value, op, ..
            } => {
                self.check_node(value, scope);
                if let Node::Identifier(name) = &target.node {
                    // Compile-time immutability check
                    if scope.get_var(name).is_some() && !scope.is_mutable(name) {
                        self.warning_at(
                            format!(
                                "Cannot assign to '{}': variable is immutable (declared with 'let')",
                                name
                            ),
                            span,
                        );
                    }

                    if let Some(Some(var_type)) = scope.get_var(name) {
                        let value_type = self.infer_type(value, scope);
                        let assigned = if let Some(op) = op {
                            let var_inferred = scope.get_var(name).cloned().flatten();
                            infer_binary_op_type(op, &var_inferred, &value_type)
                        } else {
                            value_type
                        };
                        if let Some(actual) = &assigned {
                            // Check against the original (pre-narrowing) type if narrowed
                            let check_type = scope
                                .narrowed_vars
                                .get(name)
                                .and_then(|t| t.as_ref())
                                .unwrap_or(var_type);
                            if !self.types_compatible(check_type, actual, scope) {
                                self.error_at(
                                    format!(
                                        "can't assign {} to '{}' (declared as {})",
                                        format_type(actual),
                                        name,
                                        format_type(check_type)
                                    ),
                                    span,
                                );
                            }
                        }
                    }

                    // Invalidate narrowing on reassignment: restore original type
                    if let Some(original) = scope.narrowed_vars.remove(name) {
                        scope.define_var(name, original);
                    }
                    scope.define_schema_binding(name, None);
                    scope.clear_unknown_ruled_out(name);
                }
            }

            Node::TypeDecl {
                name,
                type_params,
                type_expr,
            } => {
                scope.type_aliases.insert(name.clone(), type_expr.clone());
                self.check_type_alias_decl_variance(type_params, type_expr, name, span);
            }

            Node::EnumDecl {
                name,
                type_params,
                variants,
                ..
            } => {
                scope.enums.insert(
                    name.clone(),
                    EnumDeclInfo {
                        type_params: type_params.clone(),
                        variants: variants.clone(),
                    },
                );
                self.check_enum_decl_variance(type_params, variants, name, span);
            }

            Node::StructDecl {
                name,
                type_params,
                fields,
                ..
            } => {
                scope.structs.insert(
                    name.clone(),
                    StructDeclInfo {
                        type_params: type_params.clone(),
                        fields: fields.clone(),
                    },
                );
                self.check_struct_decl_variance(type_params, fields, name, span);
            }

            Node::InterfaceDecl {
                name,
                type_params,
                associated_types,
                methods,
            } => {
                scope.interfaces.insert(
                    name.clone(),
                    InterfaceDeclInfo {
                        type_params: type_params.clone(),
                        associated_types: associated_types.clone(),
                        methods: methods.clone(),
                    },
                );
                self.check_interface_decl_variance(type_params, methods, name, span);
            }

            Node::ImplBlock {
                type_name, methods, ..
            } => {
                // Register impl methods for interface satisfaction checking
                let sigs: Vec<ImplMethodSig> = methods
                    .iter()
                    .filter_map(|m| {
                        if let Node::FnDecl {
                            name,
                            params,
                            return_type,
                            ..
                        } = &m.node
                        {
                            let non_self: Vec<_> =
                                params.iter().filter(|p| p.name != "self").collect();
                            let param_count = non_self.len();
                            let param_types: Vec<Option<TypeExpr>> =
                                non_self.iter().map(|p| p.type_expr.clone()).collect();
                            Some(ImplMethodSig {
                                name: name.clone(),
                                param_count,
                                param_types,
                                return_type: return_type.clone(),
                            })
                        } else {
                            None
                        }
                    })
                    .collect();
                scope.impl_methods.insert(type_name.clone(), sigs);
                for method_sn in methods {
                    self.check_node(method_sn, scope);
                }
            }

            Node::TryOperator { operand } => {
                self.check_node(operand, scope);
            }

            Node::MatchExpr { value, arms } => {
                self.check_node(value, scope);
                let value_type = self.infer_type(value, scope);
                for arm in arms {
                    self.check_node(&arm.pattern, scope);
                    // Check for incompatible literal pattern types
                    if let Some(ref vt) = value_type {
                        let value_type_name = format_type(vt);
                        let mismatch = match &arm.pattern.node {
                            Node::StringLiteral(_) => {
                                !self.types_compatible(vt, &TypeExpr::Named("string".into()), scope)
                            }
                            Node::IntLiteral(_) => {
                                !self.types_compatible(vt, &TypeExpr::Named("int".into()), scope)
                                    && !self.types_compatible(
                                        vt,
                                        &TypeExpr::Named("float".into()),
                                        scope,
                                    )
                            }
                            Node::FloatLiteral(_) => {
                                !self.types_compatible(vt, &TypeExpr::Named("float".into()), scope)
                                    && !self.types_compatible(
                                        vt,
                                        &TypeExpr::Named("int".into()),
                                        scope,
                                    )
                            }
                            Node::BoolLiteral(_) => {
                                !self.types_compatible(vt, &TypeExpr::Named("bool".into()), scope)
                            }
                            _ => false,
                        };
                        if mismatch {
                            let pattern_type = match &arm.pattern.node {
                                Node::StringLiteral(_) => "string",
                                Node::IntLiteral(_) => "int",
                                Node::FloatLiteral(_) => "float",
                                Node::BoolLiteral(_) => "bool",
                                _ => unreachable!(),
                            };
                            self.warning_at(
                                format!(
                                    "Match pattern type mismatch: matching {} against {} literal",
                                    value_type_name, pattern_type
                                ),
                                arm.pattern.span,
                            );
                        }
                    }
                    let mut arm_scope = scope.child();
                    // Narrow the matched value's type in each arm
                    if let Node::Identifier(var_name) = &value.node {
                        if let Some(Some(TypeExpr::Union(members))) = scope.get_var(var_name) {
                            let narrowed = match &arm.pattern.node {
                                Node::NilLiteral => narrow_to_single(members, "nil"),
                                Node::StringLiteral(_) => narrow_to_single(members, "string"),
                                Node::IntLiteral(_) => narrow_to_single(members, "int"),
                                Node::FloatLiteral(_) => narrow_to_single(members, "float"),
                                Node::BoolLiteral(_) => narrow_to_single(members, "bool"),
                                _ => None,
                            };
                            if let Some(narrowed_type) = narrowed {
                                arm_scope.define_var(var_name, Some(narrowed_type));
                            }
                        }
                    }
                    if let Some(ref guard) = arm.guard {
                        self.check_node(guard, &mut arm_scope);
                    }
                    self.check_block(&arm.body, &mut arm_scope);
                }
                self.check_match_exhaustiveness(value, arms, scope, span);
            }

            // Recurse into nested expressions + validate binary op types
            Node::BinaryOp { op, left, right } => {
                self.check_node(left, scope);
                self.check_node(right, scope);
                // Validate operator/type compatibility
                let lt = self.infer_type(left, scope);
                let rt = self.infer_type(right, scope);
                if let (Some(TypeExpr::Named(l)), Some(TypeExpr::Named(r))) = (&lt, &rt) {
                    match op.as_str() {
                        "-" | "/" | "%" | "**" => {
                            let numeric = ["int", "float"];
                            if !numeric.contains(&l.as_str()) || !numeric.contains(&r.as_str()) {
                                self.error_at(
                                    format!(
                                        "can't use '{}' on {} and {} (needs numeric operands)",
                                        op, l, r
                                    ),
                                    span,
                                );
                            }
                        }
                        "*" => {
                            let numeric = ["int", "float"];
                            let is_numeric =
                                numeric.contains(&l.as_str()) && numeric.contains(&r.as_str());
                            let is_string_repeat =
                                (l == "string" && r == "int") || (l == "int" && r == "string");
                            if !is_numeric && !is_string_repeat {
                                self.error_at(
                                    format!("can't multiply {} and {} (try string * int)", l, r),
                                    span,
                                );
                            }
                        }
                        "+" => {
                            let valid = matches!(
                                (l.as_str(), r.as_str()),
                                ("int" | "float", "int" | "float")
                                    | ("string", "string")
                                    | ("list", "list")
                                    | ("dict", "dict")
                            );
                            if !valid {
                                let msg = format!("can't add {} and {}", l, r);
                                // Offer interpolation fix when one side is string
                                let fix = if l == "string" || r == "string" {
                                    self.build_interpolation_fix(left, right, l == "string", span)
                                } else {
                                    None
                                };
                                if let Some(fix) = fix {
                                    self.error_at_with_fix(msg, span, fix);
                                } else {
                                    self.error_at(msg, span);
                                }
                            }
                        }
                        "<" | ">" | "<=" | ">=" => {
                            let comparable = ["int", "float", "string"];
                            if !comparable.contains(&l.as_str())
                                || !comparable.contains(&r.as_str())
                            {
                                self.warning_at(
                                    format!(
                                        "Comparison '{}' may not be meaningful for types {} and {}",
                                        op, l, r
                                    ),
                                    span,
                                );
                            } else if (l == "string") != (r == "string") {
                                self.warning_at(
                                    format!(
                                        "Comparing {} with {} using '{}' may give unexpected results",
                                        l, r, op
                                    ),
                                    span,
                                );
                            }
                        }
                        _ => {}
                    }
                }
            }
            Node::UnaryOp { operand, .. } => {
                self.check_node(operand, scope);
            }
            Node::MethodCall {
                object,
                method,
                args,
                ..
            }
            | Node::OptionalMethodCall {
                object,
                method,
                args,
                ..
            } => {
                self.check_node(object, scope);
                for arg in args {
                    self.check_node(arg, scope);
                }
                // Definition-site generic checking: if the object's type is a
                // constrained generic param (where T: Interface), verify the
                // method exists in the bound interface.
                if let Some(TypeExpr::Named(type_name)) = self.infer_type(object, scope) {
                    if scope.is_generic_type_param(&type_name) {
                        if let Some(iface_name) = scope.get_where_constraint(&type_name) {
                            if let Some(iface_methods) = scope.get_interface(iface_name) {
                                let has_method =
                                    iface_methods.methods.iter().any(|m| m.name == *method);
                                if !has_method {
                                    self.warning_at(
                                        format!(
                                            "Method '{}' not found in interface '{}' (constraint on '{}')",
                                            method, iface_name, type_name
                                        ),
                                        span,
                                    );
                                }
                            }
                        }
                    }
                }
            }
            Node::PropertyAccess { object, .. } | Node::OptionalPropertyAccess { object, .. } => {
                if self.strict_types {
                    // Direct property access on boundary function result
                    if let Node::FunctionCall { name, args } = &object.node {
                        if builtin_signatures::is_untyped_boundary_source(name) {
                            let has_schema = (name == "llm_call" || name == "llm_completion")
                                && Self::llm_call_has_typed_schema_option(args, scope);
                            if !has_schema {
                                self.warning_at_with_help(
                                    format!(
                                        "Direct property access on unvalidated `{}()` result",
                                        name
                                    ),
                                    span,
                                    "assign to a variable and validate with schema_expect() or a type annotation first".to_string(),
                                );
                            }
                        }
                    }
                    // Property access on known untyped variable
                    if let Node::Identifier(name) = &object.node {
                        if let Some(source) = scope.is_untyped_source(name) {
                            self.warning_at_with_help(
                                format!(
                                    "Accessing property on unvalidated value '{}' from `{}`",
                                    name, source
                                ),
                                span,
                                "validate with schema_expect(), schema_is() in an if-condition, or add a shape type annotation".to_string(),
                            );
                        }
                    }
                }
                self.check_node(object, scope);
            }
            Node::SubscriptAccess { object, index } => {
                if self.strict_types {
                    if let Node::FunctionCall { name, args } = &object.node {
                        if builtin_signatures::is_untyped_boundary_source(name) {
                            let has_schema = (name == "llm_call" || name == "llm_completion")
                                && Self::llm_call_has_typed_schema_option(args, scope);
                            if !has_schema {
                                self.warning_at_with_help(
                                    format!(
                                        "Direct subscript access on unvalidated `{}()` result",
                                        name
                                    ),
                                    span,
                                    "assign to a variable and validate with schema_expect() or a type annotation first".to_string(),
                                );
                            }
                        }
                    }
                    if let Node::Identifier(name) = &object.node {
                        if let Some(source) = scope.is_untyped_source(name) {
                            self.warning_at_with_help(
                                format!(
                                    "Subscript access on unvalidated value '{}' from `{}`",
                                    name, source
                                ),
                                span,
                                "validate with schema_expect(), schema_is() in an if-condition, or add a shape type annotation".to_string(),
                            );
                        }
                    }
                }
                self.check_node(object, scope);
                self.check_node(index, scope);
            }
            Node::SliceAccess { object, start, end } => {
                self.check_node(object, scope);
                if let Some(s) = start {
                    self.check_node(s, scope);
                }
                if let Some(e) = end {
                    self.check_node(e, scope);
                }
            }

            Node::Ternary {
                condition,
                true_expr,
                false_expr,
            } => {
                self.check_node(condition, scope);
                let refs = Self::extract_refinements(condition, scope);

                let mut true_scope = scope.child();
                refs.apply_truthy(&mut true_scope);
                self.check_node(true_expr, &mut true_scope);

                let mut false_scope = scope.child();
                refs.apply_falsy(&mut false_scope);
                self.check_node(false_expr, &mut false_scope);
            }

            Node::ThrowStmt { value } => {
                self.check_node(value, scope);
                // A `throw` in the tail of a `type_of`-narrowing chain claims
                // exhaustiveness on the enclosing `unknown`-typed variable.
                // Warn if the claim isn't actually complete.
                self.check_unknown_exhaustiveness(scope, snode.span, "throw");
            }

            Node::GuardStmt {
                condition,
                else_body,
            } => {
                self.check_node(condition, scope);
                let refs = Self::extract_refinements(condition, scope);

                let mut else_scope = scope.child();
                refs.apply_falsy(&mut else_scope);
                self.check_block(else_body, &mut else_scope);

                // After guard, condition is true — apply truthy refinements
                // to the OUTER scope (guard's else-body must exit)
                refs.apply_truthy(scope);
            }

            Node::SpawnExpr { body } => {
                let mut spawn_scope = scope.child();
                self.check_block(body, &mut spawn_scope);
            }

            Node::Parallel {
                mode,
                expr,
                variable,
                body,
                options,
            } => {
                self.check_node(expr, scope);
                for (key, value) in options {
                    // `max_concurrent` must resolve to `int`; other keys
                    // are rejected by the parser, so no need to match
                    // here. Still type-check the expression so bad
                    // references surface a diagnostic.
                    self.check_node(value, scope);
                    if key == "max_concurrent" {
                        if let Some(ty) = self.infer_type(value, scope) {
                            if !matches!(ty, TypeExpr::Named(ref n) if n == "int") {
                                self.error_at(
                                    format!(
                                        "`max_concurrent` on `parallel` must be int, got {ty:?}"
                                    ),
                                    value.span,
                                );
                            }
                        }
                    }
                }
                let mut par_scope = scope.child();
                if let Some(var) = variable {
                    let var_type = match mode {
                        ParallelMode::Count => Some(TypeExpr::Named("int".into())),
                        ParallelMode::Each | ParallelMode::Settle => {
                            match self.infer_type(expr, scope) {
                                Some(TypeExpr::List(inner)) => Some(*inner),
                                _ => None,
                            }
                        }
                    };
                    par_scope.define_var(var, var_type);
                }
                self.check_block(body, &mut par_scope);
            }

            Node::SelectExpr {
                cases,
                timeout,
                default_body,
            } => {
                for case in cases {
                    self.check_node(&case.channel, scope);
                    let mut case_scope = scope.child();
                    case_scope.define_var(&case.variable, None);
                    self.check_block(&case.body, &mut case_scope);
                }
                if let Some((dur, body)) = timeout {
                    self.check_node(dur, scope);
                    let mut timeout_scope = scope.child();
                    self.check_block(body, &mut timeout_scope);
                }
                if let Some(body) = default_body {
                    let mut default_scope = scope.child();
                    self.check_block(body, &mut default_scope);
                }
            }

            Node::DeadlineBlock { duration, body } => {
                self.check_node(duration, scope);
                let mut block_scope = scope.child();
                self.check_block(body, &mut block_scope);
            }

            Node::MutexBlock { body } | Node::DeferStmt { body } => {
                let mut block_scope = scope.child();
                self.check_block(body, &mut block_scope);
            }

            Node::Retry { count, body } => {
                self.check_node(count, scope);
                let mut retry_scope = scope.child();
                self.check_block(body, &mut retry_scope);
            }

            Node::Closure { params, body, .. } => {
                let mut closure_scope = scope.child();
                for p in params {
                    closure_scope.define_var(&p.name, p.type_expr.clone());
                }
                self.fn_depth += 1;
                self.check_block(body, &mut closure_scope);
                self.fn_depth -= 1;
            }

            Node::ListLiteral(elements) => {
                for elem in elements {
                    self.check_node(elem, scope);
                }
            }

            Node::DictLiteral(entries) => {
                for entry in entries {
                    self.check_node(&entry.key, scope);
                    self.check_node(&entry.value, scope);
                }
            }

            Node::RangeExpr { start, end, .. } => {
                self.check_node(start, scope);
                self.check_node(end, scope);
            }

            Node::Spread(inner) => {
                self.check_node(inner, scope);
            }

            Node::Block(stmts) => {
                let mut block_scope = scope.child();
                self.check_block(stmts, &mut block_scope);
            }

            Node::YieldExpr { value } => {
                if let Some(v) = value {
                    self.check_node(v, scope);
                }
            }

            Node::StructConstruct {
                struct_name,
                fields,
            } => {
                for entry in fields {
                    self.check_node(&entry.key, scope);
                    self.check_node(&entry.value, scope);
                }
                if let Some(struct_info) = scope.get_struct(struct_name).cloned() {
                    let type_bindings = self.infer_struct_bindings(&struct_info, fields, scope);
                    // Warn on unknown fields
                    for entry in fields {
                        if let Node::StringLiteral(key) | Node::Identifier(key) = &entry.key.node {
                            if !struct_info.fields.iter().any(|field| field.name == *key) {
                                self.warning_at(
                                    format!("Unknown field '{}' in struct '{}'", key, struct_name),
                                    entry.key.span,
                                );
                            }
                        }
                    }
                    // Warn on missing required fields
                    let provided: Vec<String> = fields
                        .iter()
                        .filter_map(|e| match &e.key.node {
                            Node::StringLiteral(k) | Node::Identifier(k) => Some(k.clone()),
                            _ => None,
                        })
                        .collect();
                    for field in &struct_info.fields {
                        if !field.optional && !provided.contains(&field.name) {
                            self.warning_at(
                                format!(
                                    "Missing field '{}' in struct '{}' construction",
                                    field.name, struct_name
                                ),
                                span,
                            );
                        }
                    }
                    for field in &struct_info.fields {
                        let Some(expected_type) = &field.type_expr else {
                            continue;
                        };
                        let Some(entry) = fields.iter().find(|entry| {
                            matches!(&entry.key.node, Node::StringLiteral(key) | Node::Identifier(key) if key == &field.name)
                        }) else {
                            continue;
                        };
                        let Some(actual_type) = self.infer_type(&entry.value, scope) else {
                            continue;
                        };
                        let expected = Self::apply_type_bindings(expected_type, &type_bindings);
                        if !self.types_compatible(&expected, &actual_type, scope) {
                            self.error_at(
                                format!(
                                    "Field '{}' in struct '{}' expects {}, got {}",
                                    field.name,
                                    struct_name,
                                    format_type(&expected),
                                    format_type(&actual_type)
                                ),
                                entry.value.span,
                            );
                        }
                    }
                }
            }

            Node::EnumConstruct {
                enum_name,
                variant,
                args,
            } => {
                for arg in args {
                    self.check_node(arg, scope);
                }
                if let Some(enum_info) = scope.get_enum(enum_name).cloned() {
                    let Some(enum_variant) = enum_info
                        .variants
                        .iter()
                        .find(|enum_variant| enum_variant.name == *variant)
                    else {
                        self.warning_at(
                            format!("Unknown variant '{}' in enum '{}'", variant, enum_name),
                            span,
                        );
                        return;
                    };
                    if args.len() != enum_variant.fields.len() {
                        self.warning_at(
                            format!(
                                "{}.{} expects {} argument(s), got {}",
                                enum_name,
                                variant,
                                enum_variant.fields.len(),
                                args.len()
                            ),
                            span,
                        );
                    }
                    let type_param_set: std::collections::BTreeSet<String> = enum_info
                        .type_params
                        .iter()
                        .map(|tp| tp.name.clone())
                        .collect();
                    let mut type_bindings = BTreeMap::new();
                    for (field, arg) in enum_variant.fields.iter().zip(args.iter()) {
                        let Some(expected_type) = &field.type_expr else {
                            continue;
                        };
                        let Some(actual_type) = self.infer_type(arg, scope) else {
                            continue;
                        };
                        if let Err(message) = Self::extract_type_bindings(
                            expected_type,
                            &actual_type,
                            &type_param_set,
                            &mut type_bindings,
                        ) {
                            self.error_at(message, arg.span);
                        }
                    }
                    for (field, arg) in enum_variant.fields.iter().zip(args.iter()) {
                        let Some(expected_type) = &field.type_expr else {
                            continue;
                        };
                        let Some(actual_type) = self.infer_type(arg, scope) else {
                            continue;
                        };
                        let expected = Self::apply_type_bindings(expected_type, &type_bindings);
                        if !self.types_compatible(&expected, &actual_type, scope) {
                            self.error_at(
                                format!(
                                    "{}.{} expects {}: {}, got {}",
                                    enum_name,
                                    variant,
                                    field.name,
                                    format_type(&expected),
                                    format_type(&actual_type)
                                ),
                                arg.span,
                            );
                        }
                    }
                }
            }

            Node::InterpolatedString(_) => {}

            Node::StringLiteral(_)
            | Node::RawStringLiteral(_)
            | Node::IntLiteral(_)
            | Node::FloatLiteral(_)
            | Node::BoolLiteral(_)
            | Node::NilLiteral
            | Node::Identifier(_)
            | Node::DurationLiteral(_)
            | Node::BreakStmt
            | Node::ContinueStmt
            | Node::ReturnStmt { value: None }
            | Node::ImportDecl { .. }
            | Node::SelectiveImport { .. } => {}

            // Declarations already handled above; catch remaining variants
            // that have no meaningful type-check behavior.
            Node::Pipeline { body, .. } | Node::OverrideDecl { body, .. } => {
                let mut decl_scope = scope.child();
                self.fn_depth += 1;
                self.check_block(body, &mut decl_scope);
                self.fn_depth -= 1;
            }
            Node::AttributedDecl { attributes, inner } => {
                self.check_attributes(attributes, inner);
                self.check_node(inner, scope);
            }
        }
    }

    /// Validate attribute usage and emit warnings for unknown attributes.
    /// Recognized attribute names: `deprecated`, `test`, `complexity`,
    /// `acp_tool`. All other names produce a warning so misspellings
    /// surface early without breaking compilation.
    fn check_attributes(&mut self, attributes: &[Attribute], inner: &SNode) {
        for attr in attributes {
            match attr.name.as_str() {
                "deprecated" | "test" | "complexity" | "acp_tool" => {}
                other => {
                    self.warning_at(format!("unknown attribute `@{}`", other), attr.span);
                }
            }
            // `@test` only applies to functions.
            if attr.name == "test" && !matches!(inner.node, Node::FnDecl { .. }) {
                self.warning_at(
                    "`@test` only applies to function declarations".to_string(),
                    attr.span,
                );
            }
            if attr.name == "acp_tool" && !matches!(inner.node, Node::FnDecl { .. }) {
                self.warning_at(
                    "`@acp_tool` only applies to function declarations".to_string(),
                    attr.span,
                );
            }
        }
    }

    fn check_fn_body(
        &mut self,
        type_params: &[TypeParam],
        params: &[TypedParam],
        return_type: &Option<TypeExpr>,
        body: &[SNode],
        where_clauses: &[WhereClause],
    ) {
        self.fn_depth += 1;
        self.check_fn_body_inner(type_params, params, return_type, body, where_clauses);
        self.fn_depth -= 1;
    }

    fn check_fn_body_inner(
        &mut self,
        type_params: &[TypeParam],
        params: &[TypedParam],
        return_type: &Option<TypeExpr>,
        body: &[SNode],
        where_clauses: &[WhereClause],
    ) {
        let mut fn_scope = self.scope.child();
        // Register generic type parameters so they are treated as compatible
        // with any concrete type during type checking.
        for tp in type_params {
            fn_scope.generic_type_params.insert(tp.name.clone());
        }
        // Store where-clause constraints for definition-site checking
        for wc in where_clauses {
            fn_scope
                .where_constraints
                .insert(wc.type_name.clone(), wc.bound.clone());
        }
        for param in params {
            fn_scope.define_var(&param.name, param.type_expr.clone());
            if let Some(default) = &param.default_value {
                self.check_node(default, &mut fn_scope);
            }
        }
        // Snapshot scope before main pass (which may mutate it with narrowing)
        // so that return-type checking starts from the original parameter types.
        let ret_scope_base = if return_type.is_some() {
            Some(fn_scope.child())
        } else {
            None
        };

        self.check_block(body, &mut fn_scope);

        // Check return statements against declared return type
        if let Some(ret_type) = return_type {
            let mut ret_scope = ret_scope_base.unwrap();
            for stmt in body {
                self.check_return_type(stmt, ret_type, &mut ret_scope);
            }
        }
    }

    fn check_return_type(&mut self, snode: &SNode, expected: &TypeExpr, scope: &mut TypeScope) {
        let span = snode.span;
        match &snode.node {
            Node::ReturnStmt { value: Some(val) } => {
                let inferred = self.infer_type(val, scope);
                if let Some(actual) = &inferred {
                    if !self.types_compatible(expected, actual, scope) {
                        self.error_at(
                            format!(
                                "return type doesn't match: expected {}, got {}",
                                format_type(expected),
                                format_type(actual)
                            ),
                            span,
                        );
                    }
                }
            }
            Node::IfElse {
                condition,
                then_body,
                else_body,
            } => {
                let refs = Self::extract_refinements(condition, scope);
                let mut then_scope = scope.child();
                refs.apply_truthy(&mut then_scope);
                for stmt in then_body {
                    self.check_return_type(stmt, expected, &mut then_scope);
                }
                if let Some(else_body) = else_body {
                    let mut else_scope = scope.child();
                    refs.apply_falsy(&mut else_scope);
                    for stmt in else_body {
                        self.check_return_type(stmt, expected, &mut else_scope);
                    }
                    // Post-branch narrowing for return type checking
                    if Self::block_definitely_exits(then_body)
                        && !Self::block_definitely_exits(else_body)
                    {
                        refs.apply_falsy(scope);
                    } else if Self::block_definitely_exits(else_body)
                        && !Self::block_definitely_exits(then_body)
                    {
                        refs.apply_truthy(scope);
                    }
                } else {
                    // No else: if then-body always exits, apply falsy after
                    if Self::block_definitely_exits(then_body) {
                        refs.apply_falsy(scope);
                    }
                }
            }
            _ => {}
        }
    }

    /// Check if a match expression on an enum's `.variant` property covers all variants.
    /// Extract narrowing info from nil-check conditions like `x != nil`.
    /// Returns (var_name, narrowed_type) where narrowed_type removes nil from a union.
    /// Check if a type satisfies an interface (Go-style implicit satisfaction).
    /// A type satisfies an interface if its impl block has all the required methods.
    fn satisfies_interface(
        &self,
        type_name: &str,
        interface_name: &str,
        interface_bindings: &BTreeMap<String, TypeExpr>,
        scope: &TypeScope,
    ) -> bool {
        self.interface_mismatch_reason(type_name, interface_name, interface_bindings, scope)
            .is_none()
    }

    /// Return a detailed reason why a type does not satisfy an interface, or None
    /// if it does satisfy it.  Used for producing actionable warning messages.
    fn interface_mismatch_reason(
        &self,
        type_name: &str,
        interface_name: &str,
        interface_bindings: &BTreeMap<String, TypeExpr>,
        scope: &TypeScope,
    ) -> Option<String> {
        let interface_info = match scope.get_interface(interface_name) {
            Some(info) => info,
            None => return Some(format!("interface '{}' not found", interface_name)),
        };
        let impl_methods = match scope.get_impl_methods(type_name) {
            Some(methods) => methods,
            None => {
                if interface_info.methods.is_empty() {
                    return None;
                }
                let names: Vec<_> = interface_info
                    .methods
                    .iter()
                    .map(|m| m.name.as_str())
                    .collect();
                return Some(format!("missing method(s): {}", names.join(", ")));
            }
        };
        let mut bindings = interface_bindings.clone();
        let associated_type_names: std::collections::BTreeSet<String> = interface_info
            .associated_types
            .iter()
            .map(|(name, _)| name.clone())
            .collect();
        for iface_method in &interface_info.methods {
            let iface_params: Vec<_> = iface_method
                .params
                .iter()
                .filter(|p| p.name != "self")
                .collect();
            let iface_param_count = iface_params.len();
            let matching_impl = impl_methods.iter().find(|im| im.name == iface_method.name);
            let impl_method = match matching_impl {
                Some(m) => m,
                None => {
                    return Some(format!("missing method '{}'", iface_method.name));
                }
            };
            if impl_method.param_count != iface_param_count {
                return Some(format!(
                    "method '{}' has {} parameter(s), expected {}",
                    iface_method.name, impl_method.param_count, iface_param_count
                ));
            }
            // Check parameter types where both sides specify them
            for (i, iface_param) in iface_params.iter().enumerate() {
                if let (Some(expected), Some(actual)) = (
                    &iface_param.type_expr,
                    impl_method.param_types.get(i).and_then(|t| t.as_ref()),
                ) {
                    if let Err(message) = Self::extract_type_bindings(
                        expected,
                        actual,
                        &associated_type_names,
                        &mut bindings,
                    ) {
                        return Some(message);
                    }
                    let expected = Self::apply_type_bindings(expected, &bindings);
                    if !self.types_compatible(&expected, actual, scope) {
                        return Some(format!(
                            "method '{}' parameter {} has type '{}', expected '{}'",
                            iface_method.name,
                            i + 1,
                            format_type(actual),
                            format_type(&expected),
                        ));
                    }
                }
            }
            // Check return type where both sides specify it
            if let (Some(expected_ret), Some(actual_ret)) =
                (&iface_method.return_type, &impl_method.return_type)
            {
                if let Err(message) = Self::extract_type_bindings(
                    expected_ret,
                    actual_ret,
                    &associated_type_names,
                    &mut bindings,
                ) {
                    return Some(message);
                }
                let expected_ret = Self::apply_type_bindings(expected_ret, &bindings);
                if !self.types_compatible(&expected_ret, actual_ret, scope) {
                    return Some(format!(
                        "method '{}' returns '{}', expected '{}'",
                        iface_method.name,
                        format_type(actual_ret),
                        format_type(&expected_ret),
                    ));
                }
            }
        }
        for (assoc_name, default_type) in &interface_info.associated_types {
            if let (Some(default_type), Some(actual)) = (default_type, bindings.get(assoc_name)) {
                let expected = Self::apply_type_bindings(default_type, &bindings);
                if !self.types_compatible(&expected, actual, scope) {
                    return Some(format!(
                        "associated type '{}' resolves to '{}', expected '{}'",
                        assoc_name,
                        format_type(actual),
                        format_type(&expected),
                    ));
                }
            }
        }
        None
    }

    fn bind_type_param(
        param_name: &str,
        concrete: &TypeExpr,
        bindings: &mut BTreeMap<String, TypeExpr>,
    ) -> Result<(), String> {
        if let Some(existing) = bindings.get(param_name) {
            if existing != concrete {
                return Err(format!(
                    "type parameter '{}' was inferred as both {} and {}",
                    param_name,
                    format_type(existing),
                    format_type(concrete)
                ));
            }
            return Ok(());
        }
        bindings.insert(param_name.to_string(), concrete.clone());
        Ok(())
    }

    /// Recursively extract type parameter bindings from matching param/arg types.
    /// E.g., param_type=list<T> + arg_type=list<Dog> → binds T=Dog.
    fn extract_type_bindings(
        param_type: &TypeExpr,
        arg_type: &TypeExpr,
        type_params: &std::collections::BTreeSet<String>,
        bindings: &mut BTreeMap<String, TypeExpr>,
    ) -> Result<(), String> {
        match (param_type, arg_type) {
            (TypeExpr::Named(param_name), concrete) if type_params.contains(param_name) => {
                Self::bind_type_param(param_name, concrete, bindings)
            }
            (TypeExpr::List(p_inner), TypeExpr::List(a_inner)) => {
                Self::extract_type_bindings(p_inner, a_inner, type_params, bindings)
            }
            (TypeExpr::DictType(pk, pv), TypeExpr::DictType(ak, av)) => {
                Self::extract_type_bindings(pk, ak, type_params, bindings)?;
                Self::extract_type_bindings(pv, av, type_params, bindings)
            }
            (
                TypeExpr::Applied {
                    name: p_name,
                    args: p_args,
                },
                TypeExpr::Applied {
                    name: a_name,
                    args: a_args,
                },
            ) if p_name == a_name && p_args.len() == a_args.len() => {
                for (param, arg) in p_args.iter().zip(a_args.iter()) {
                    Self::extract_type_bindings(param, arg, type_params, bindings)?;
                }
                Ok(())
            }
            (TypeExpr::Shape(param_fields), TypeExpr::Shape(arg_fields)) => {
                for param_field in param_fields {
                    if let Some(arg_field) = arg_fields
                        .iter()
                        .find(|field| field.name == param_field.name)
                    {
                        Self::extract_type_bindings(
                            &param_field.type_expr,
                            &arg_field.type_expr,
                            type_params,
                            bindings,
                        )?;
                    }
                }
                Ok(())
            }
            (
                TypeExpr::FnType {
                    params: p_params,
                    return_type: p_ret,
                },
                TypeExpr::FnType {
                    params: a_params,
                    return_type: a_ret,
                },
            ) => {
                for (param, arg) in p_params.iter().zip(a_params.iter()) {
                    Self::extract_type_bindings(param, arg, type_params, bindings)?;
                }
                Self::extract_type_bindings(p_ret, a_ret, type_params, bindings)
            }
            _ => Ok(()),
        }
    }

    /// Bind type parameters by walking a param [`TypeExpr`] against an
    /// argument AST node. Used by the generic-builtin dispatch path for
    /// `llm_call`, `schema_parse`, etc.
    ///
    /// Unlike [`extract_type_bindings`], which matches a param type against
    /// an inferred arg *type*, this walks the arg *node* so that
    /// `Schema<T>` in a param position can pull `T` from the structural
    /// value of the corresponding argument (e.g. a type alias identifier
    /// or an inline JSON-Schema dict literal). When the param is not a
    /// `Schema<_>` or shape marker, we fall back to standard type-based
    /// binding against the arg's inferred type.
    fn bind_from_arg_node(
        &self,
        param: &TypeExpr,
        arg: &SNode,
        type_params: &std::collections::BTreeSet<String>,
        bindings: &mut BTreeMap<String, TypeExpr>,
        scope: &TypeScope,
    ) -> Result<(), String> {
        match param {
            TypeExpr::Applied { name, args } if name == "Schema" && args.len() == 1 => {
                if let TypeExpr::Named(tp) = &args[0] {
                    if type_params.contains(tp) {
                        if let Some(resolved) = schema_type_expr_from_node(arg, scope) {
                            Self::bind_type_param(tp, &resolved, bindings)?;
                        }
                    }
                }
                Ok(())
            }
            TypeExpr::Shape(fields) => {
                if let Node::DictLiteral(entries) = &arg.node {
                    for field in fields {
                        let matching = entries.iter().find(|entry| match &entry.key.node {
                            Node::StringLiteral(key) | Node::Identifier(key) => key == &field.name,
                            _ => false,
                        });
                        if let Some(entry) = matching {
                            self.bind_from_arg_node(
                                &field.type_expr,
                                &entry.value,
                                type_params,
                                bindings,
                                scope,
                            )?;
                        }
                    }
                    return Ok(());
                }
                if let Some(arg_ty) = self.infer_type(arg, scope) {
                    Self::extract_type_bindings(param, &arg_ty, type_params, bindings)?;
                }
                Ok(())
            }
            _ => {
                if let Some(arg_ty) = self.infer_type(arg, scope) {
                    Self::extract_type_bindings(param, &arg_ty, type_params, bindings)?;
                }
                Ok(())
            }
        }
    }

    fn apply_type_bindings(ty: &TypeExpr, bindings: &BTreeMap<String, TypeExpr>) -> TypeExpr {
        match ty {
            TypeExpr::Named(name) => bindings
                .get(name)
                .cloned()
                .unwrap_or_else(|| TypeExpr::Named(name.clone())),
            TypeExpr::Union(items) => TypeExpr::Union(
                items
                    .iter()
                    .map(|item| Self::apply_type_bindings(item, bindings))
                    .collect(),
            ),
            TypeExpr::Shape(fields) => TypeExpr::Shape(
                fields
                    .iter()
                    .map(|field| ShapeField {
                        name: field.name.clone(),
                        type_expr: Self::apply_type_bindings(&field.type_expr, bindings),
                        optional: field.optional,
                    })
                    .collect(),
            ),
            TypeExpr::List(inner) => {
                TypeExpr::List(Box::new(Self::apply_type_bindings(inner, bindings)))
            }
            TypeExpr::Iter(inner) => {
                TypeExpr::Iter(Box::new(Self::apply_type_bindings(inner, bindings)))
            }
            TypeExpr::DictType(key, value) => TypeExpr::DictType(
                Box::new(Self::apply_type_bindings(key, bindings)),
                Box::new(Self::apply_type_bindings(value, bindings)),
            ),
            TypeExpr::Applied { name, args } => TypeExpr::Applied {
                name: name.clone(),
                args: args
                    .iter()
                    .map(|arg| Self::apply_type_bindings(arg, bindings))
                    .collect(),
            },
            TypeExpr::FnType {
                params,
                return_type,
            } => TypeExpr::FnType {
                params: params
                    .iter()
                    .map(|param| Self::apply_type_bindings(param, bindings))
                    .collect(),
                return_type: Box::new(Self::apply_type_bindings(return_type, bindings)),
            },
            TypeExpr::Never => TypeExpr::Never,
            TypeExpr::LitString(s) => TypeExpr::LitString(s.clone()),
            TypeExpr::LitInt(v) => TypeExpr::LitInt(*v),
        }
    }

    fn applied_type_or_name(name: &str, args: Vec<TypeExpr>) -> TypeExpr {
        if args.is_empty() {
            TypeExpr::Named(name.to_string())
        } else {
            TypeExpr::Applied {
                name: name.to_string(),
                args,
            }
        }
    }

    fn infer_struct_bindings(
        &self,
        struct_info: &StructDeclInfo,
        fields: &[DictEntry],
        scope: &TypeScope,
    ) -> BTreeMap<String, TypeExpr> {
        let type_param_set: std::collections::BTreeSet<String> = struct_info
            .type_params
            .iter()
            .map(|tp| tp.name.clone())
            .collect();
        let mut bindings = BTreeMap::new();
        for field in &struct_info.fields {
            let Some(expected_type) = &field.type_expr else {
                continue;
            };
            let Some(entry) = fields.iter().find(|entry| {
                matches!(&entry.key.node, Node::StringLiteral(key) | Node::Identifier(key) if key == &field.name)
            }) else {
                continue;
            };
            let Some(actual_type) = self.infer_type(&entry.value, scope) else {
                continue;
            };
            let _ = Self::extract_type_bindings(
                expected_type,
                &actual_type,
                &type_param_set,
                &mut bindings,
            );
        }
        bindings
    }

    fn infer_struct_type(
        &self,
        struct_name: &str,
        struct_info: &StructDeclInfo,
        fields: &[DictEntry],
        scope: &TypeScope,
    ) -> TypeExpr {
        let bindings = self.infer_struct_bindings(struct_info, fields, scope);
        let args = struct_info
            .type_params
            .iter()
            .map(|tp| {
                bindings
                    .get(&tp.name)
                    .cloned()
                    .unwrap_or_else(Self::wildcard_type)
            })
            .collect();
        Self::applied_type_or_name(struct_name, args)
    }

    fn infer_enum_type(
        &self,
        enum_name: &str,
        enum_info: &EnumDeclInfo,
        variant_name: &str,
        args: &[SNode],
        scope: &TypeScope,
    ) -> TypeExpr {
        let type_param_set: std::collections::BTreeSet<String> = enum_info
            .type_params
            .iter()
            .map(|tp| tp.name.clone())
            .collect();
        let mut bindings = BTreeMap::new();
        if let Some(variant) = enum_info
            .variants
            .iter()
            .find(|variant| variant.name == variant_name)
        {
            for (field, arg) in variant.fields.iter().zip(args.iter()) {
                let Some(expected_type) = &field.type_expr else {
                    continue;
                };
                let Some(actual_type) = self.infer_type(arg, scope) else {
                    continue;
                };
                let _ = Self::extract_type_bindings(
                    expected_type,
                    &actual_type,
                    &type_param_set,
                    &mut bindings,
                );
            }
        }
        let args = enum_info
            .type_params
            .iter()
            .map(|tp| {
                bindings
                    .get(&tp.name)
                    .cloned()
                    .unwrap_or_else(Self::wildcard_type)
            })
            .collect();
        Self::applied_type_or_name(enum_name, args)
    }

    fn infer_try_error_type(&self, stmts: &[SNode], scope: &TypeScope) -> InferredType {
        let mut inferred: Vec<TypeExpr> = Vec::new();
        for stmt in stmts {
            match &stmt.node {
                Node::ThrowStmt { value } => {
                    if let Some(ty) = self.infer_type(value, scope) {
                        inferred.push(ty);
                    }
                }
                Node::TryOperator { operand } => {
                    if let Some(TypeExpr::Applied { name, args }) = self.infer_type(operand, scope)
                    {
                        if name == "Result" && args.len() == 2 {
                            inferred.push(args[1].clone());
                        }
                    }
                }
                Node::IfElse {
                    then_body,
                    else_body,
                    ..
                } => {
                    if let Some(ty) = self.infer_try_error_type(then_body, scope) {
                        inferred.push(ty);
                    }
                    if let Some(else_body) = else_body {
                        if let Some(ty) = self.infer_try_error_type(else_body, scope) {
                            inferred.push(ty);
                        }
                    }
                }
                Node::Block(body)
                | Node::TryExpr { body }
                | Node::SpawnExpr { body }
                | Node::Retry { body, .. }
                | Node::WhileLoop { body, .. }
                | Node::DeferStmt { body }
                | Node::MutexBlock { body }
                | Node::DeadlineBlock { body, .. }
                | Node::Pipeline { body, .. }
                | Node::OverrideDecl { body, .. } => {
                    if let Some(ty) = self.infer_try_error_type(body, scope) {
                        inferred.push(ty);
                    }
                }
                _ => {}
            }
        }
        if inferred.is_empty() {
            None
        } else {
            Some(simplify_union(inferred))
        }
    }

    fn infer_list_literal_type(&self, items: &[SNode], scope: &TypeScope) -> TypeExpr {
        let mut inferred: Option<TypeExpr> = None;
        for item in items {
            let Some(item_type) = self.infer_type(item, scope) else {
                return TypeExpr::Named("list".into());
            };
            inferred = Some(match inferred {
                None => item_type,
                Some(current) if current == item_type => current,
                Some(TypeExpr::Union(mut members)) => {
                    if !members.contains(&item_type) {
                        members.push(item_type);
                    }
                    TypeExpr::Union(members)
                }
                Some(current) => TypeExpr::Union(vec![current, item_type]),
            });
        }
        inferred
            .map(|item_type| TypeExpr::List(Box::new(item_type)))
            .unwrap_or_else(|| TypeExpr::Named("list".into()))
    }

    /// Extract bidirectional type refinements from a condition expression.
    fn extract_refinements(condition: &SNode, scope: &TypeScope) -> Refinements {
        match &condition.node {
            Node::BinaryOp { op, left, right } if op == "!=" || op == "==" => {
                let nil_ref = Self::extract_nil_refinements(op, left, right, scope);
                if !nil_ref.truthy.is_empty() || !nil_ref.falsy.is_empty() {
                    return nil_ref;
                }
                let typeof_ref = Self::extract_typeof_refinements(op, left, right, scope);
                if !typeof_ref.truthy.is_empty() || !typeof_ref.falsy.is_empty() {
                    return typeof_ref;
                }
                Refinements::empty()
            }

            // Logical AND: both operands must be truthy, so truthy refinements compose.
            Node::BinaryOp { op, left, right } if op == "&&" => {
                let left_ref = Self::extract_refinements(left, scope);
                let right_ref = Self::extract_refinements(right, scope);
                let mut truthy = left_ref.truthy;
                truthy.extend(right_ref.truthy);
                let mut truthy_ruled_out = left_ref.truthy_ruled_out;
                truthy_ruled_out.extend(right_ref.truthy_ruled_out);
                Refinements {
                    truthy,
                    falsy: vec![],
                    truthy_ruled_out,
                    falsy_ruled_out: vec![],
                }
            }

            // Logical OR: both operands must be falsy for the whole to be falsy.
            Node::BinaryOp { op, left, right } if op == "||" => {
                let left_ref = Self::extract_refinements(left, scope);
                let right_ref = Self::extract_refinements(right, scope);
                let mut falsy = left_ref.falsy;
                falsy.extend(right_ref.falsy);
                let mut falsy_ruled_out = left_ref.falsy_ruled_out;
                falsy_ruled_out.extend(right_ref.falsy_ruled_out);
                Refinements {
                    truthy: vec![],
                    falsy,
                    truthy_ruled_out: vec![],
                    falsy_ruled_out,
                }
            }

            Node::UnaryOp { op, operand } if op == "!" => {
                Self::extract_refinements(operand, scope).inverted()
            }

            // Bare identifier in condition position: narrow `T | nil` to `T`.
            Node::Identifier(name) => {
                if let Some(Some(TypeExpr::Union(members))) = scope.get_var(name) {
                    if members
                        .iter()
                        .any(|m| matches!(m, TypeExpr::Named(n) if n == "nil"))
                    {
                        if let Some(narrowed) = remove_from_union(members, "nil") {
                            return Refinements {
                                truthy: vec![(name.clone(), Some(narrowed))],
                                falsy: vec![(name.clone(), Some(TypeExpr::Named("nil".into())))],
                                truthy_ruled_out: vec![],
                                falsy_ruled_out: vec![],
                            };
                        }
                    }
                }
                Refinements::empty()
            }

            Node::MethodCall {
                object,
                method,
                args,
            } if method == "has" && args.len() == 1 => {
                Self::extract_has_refinements(object, args, scope)
            }

            Node::FunctionCall { name, args }
                if (name == "schema_is" || name == "is_type") && args.len() == 2 =>
            {
                Self::extract_schema_refinements(args, scope)
            }

            _ => Refinements::empty(),
        }
    }

    /// Extract nil-check refinements from `x != nil` / `x == nil` patterns.
    fn extract_nil_refinements(
        op: &str,
        left: &SNode,
        right: &SNode,
        scope: &TypeScope,
    ) -> Refinements {
        let var_node = if matches!(right.node, Node::NilLiteral) {
            left
        } else if matches!(left.node, Node::NilLiteral) {
            right
        } else {
            return Refinements::empty();
        };

        if let Node::Identifier(name) = &var_node.node {
            let var_type = scope.get_var(name).cloned().flatten();
            match var_type {
                Some(TypeExpr::Union(ref members)) => {
                    if let Some(narrowed) = remove_from_union(members, "nil") {
                        let neq_refs = Refinements {
                            truthy: vec![(name.clone(), Some(narrowed))],
                            falsy: vec![(name.clone(), Some(TypeExpr::Named("nil".into())))],
                            ..Refinements::default()
                        };
                        return if op == "!=" {
                            neq_refs
                        } else {
                            neq_refs.inverted()
                        };
                    }
                }
                Some(TypeExpr::Named(ref n)) if n == "nil" => {
                    // Single nil type: == nil is always true, != nil narrows to never.
                    let eq_refs = Refinements {
                        truthy: vec![(name.clone(), Some(TypeExpr::Named("nil".into())))],
                        falsy: vec![(name.clone(), Some(TypeExpr::Never))],
                        ..Refinements::default()
                    };
                    return if op == "==" {
                        eq_refs
                    } else {
                        eq_refs.inverted()
                    };
                }
                _ => {}
            }
        }
        Refinements::empty()
    }

    /// Extract type_of refinements from `type_of(x) == "typename"` patterns.
    fn extract_typeof_refinements(
        op: &str,
        left: &SNode,
        right: &SNode,
        scope: &TypeScope,
    ) -> Refinements {
        let (var_name, type_name) = if let (Some(var), Node::StringLiteral(tn)) =
            (extract_type_of_var(left), &right.node)
        {
            (var, tn.clone())
        } else if let (Node::StringLiteral(tn), Some(var)) =
            (&left.node, extract_type_of_var(right))
        {
            (var, tn.clone())
        } else {
            return Refinements::empty();
        };

        const KNOWN_TYPES: &[&str] = &[
            "int", "string", "float", "bool", "nil", "list", "dict", "closure",
        ];
        if !KNOWN_TYPES.contains(&type_name.as_str()) {
            return Refinements::empty();
        }

        let var_type = scope.get_var(&var_name).cloned().flatten();
        match var_type {
            Some(TypeExpr::Union(ref members)) => {
                let narrowed = narrow_to_single(members, &type_name);
                let remaining = remove_from_union(members, &type_name);
                if narrowed.is_some() || remaining.is_some() {
                    let eq_refs = Refinements {
                        truthy: narrowed
                            .map(|n| vec![(var_name.clone(), Some(n))])
                            .unwrap_or_default(),
                        falsy: remaining
                            .map(|r| vec![(var_name.clone(), Some(r))])
                            .unwrap_or_default(),
                        ..Refinements::default()
                    };
                    return if op == "==" {
                        eq_refs
                    } else {
                        eq_refs.inverted()
                    };
                }
            }
            Some(TypeExpr::Named(ref n)) if n == &type_name => {
                // Single named type matches the typeof check:
                // truthy = same type, falsy = never (type is fully ruled out).
                let eq_refs = Refinements {
                    truthy: vec![(var_name.clone(), Some(TypeExpr::Named(type_name)))],
                    falsy: vec![(var_name.clone(), Some(TypeExpr::Never))],
                    ..Refinements::default()
                };
                return if op == "==" {
                    eq_refs
                } else {
                    eq_refs.inverted()
                };
            }
            Some(TypeExpr::Named(ref n)) if n == "unknown" => {
                // `unknown` narrows to the tested concrete type on the truthy
                // branch. The falsy branch keeps `unknown` — subtracting one
                // concrete type from an open top still leaves an open top —
                // but we remember which concrete variants have been ruled
                // out so `unreachable()` / `throw` can detect incomplete
                // exhaustive-narrowing chains.
                let eq_refs = Refinements {
                    truthy: vec![(var_name.clone(), Some(TypeExpr::Named(type_name.clone())))],
                    falsy: vec![],
                    truthy_ruled_out: vec![],
                    falsy_ruled_out: vec![(var_name.clone(), type_name)],
                };
                return if op == "==" {
                    eq_refs
                } else {
                    eq_refs.inverted()
                };
            }
            _ => {}
        }
        Refinements::empty()
    }

    /// Extract .has("key") refinements on shape types.
    fn extract_has_refinements(object: &SNode, args: &[SNode], scope: &TypeScope) -> Refinements {
        if let Node::Identifier(var_name) = &object.node {
            if let Node::StringLiteral(key) = &args[0].node {
                if let Some(Some(TypeExpr::Shape(fields))) = scope.get_var(var_name) {
                    if fields.iter().any(|f| f.name == *key && f.optional) {
                        let narrowed_fields: Vec<ShapeField> = fields
                            .iter()
                            .map(|f| {
                                if f.name == *key {
                                    ShapeField {
                                        name: f.name.clone(),
                                        type_expr: f.type_expr.clone(),
                                        optional: false,
                                    }
                                } else {
                                    f.clone()
                                }
                            })
                            .collect();
                        return Refinements {
                            truthy: vec![(
                                var_name.clone(),
                                Some(TypeExpr::Shape(narrowed_fields)),
                            )],
                            falsy: vec![],
                            ..Refinements::default()
                        };
                    }
                }
            }
        }
        Refinements::empty()
    }

    fn extract_schema_refinements(args: &[SNode], scope: &TypeScope) -> Refinements {
        let Node::Identifier(var_name) = &args[0].node else {
            return Refinements::empty();
        };
        let Some(schema_type) = schema_type_expr_from_node(&args[1], scope) else {
            return Refinements::empty();
        };
        let Some(Some(var_type)) = scope.get_var(var_name).cloned() else {
            return Refinements::empty();
        };

        let truthy = intersect_types(&var_type, &schema_type)
            .map(|ty| vec![(var_name.clone(), Some(ty))])
            .unwrap_or_default();
        let falsy = subtract_type(&var_type, &schema_type)
            .map(|ty| vec![(var_name.clone(), Some(ty))])
            .unwrap_or_default();

        Refinements {
            truthy,
            falsy,
            ..Refinements::default()
        }
    }

    /// Check whether a block definitely exits (delegates to the free function).
    fn block_definitely_exits(stmts: &[SNode]) -> bool {
        block_definitely_exits(stmts)
    }

    fn check_match_exhaustiveness(
        &mut self,
        value: &SNode,
        arms: &[MatchArm],
        scope: &TypeScope,
        span: Span,
    ) {
        // Detect pattern: match <expr>.variant { "VariantA" -> ... }
        let enum_name = match &value.node {
            Node::PropertyAccess { object, property } if property == "variant" => {
                // Infer the type of the object
                match self.infer_type(object, scope) {
                    Some(TypeExpr::Named(name)) => {
                        if scope.get_enum(&name).is_some() {
                            Some(name)
                        } else {
                            None
                        }
                    }
                    _ => None,
                }
            }
            _ => {
                // Direct match on an enum value: match <expr> { ... }
                match self.infer_type(value, scope) {
                    Some(TypeExpr::Named(name)) if scope.get_enum(&name).is_some() => Some(name),
                    _ => None,
                }
            }
        };

        let Some(enum_name) = enum_name else {
            // Try union type exhaustiveness instead
            self.check_match_exhaustiveness_union(value, arms, scope, span);
            return;
        };
        let Some(variants) = scope.get_enum(&enum_name) else {
            return;
        };

        // Collect variant names covered by match arms
        let mut covered: Vec<String> = Vec::new();
        let mut has_wildcard = false;

        for arm in arms {
            match &arm.pattern.node {
                // String literal pattern (matching on .variant): "VariantA"
                Node::StringLiteral(s) => covered.push(s.clone()),
                // Identifier pattern acts as a wildcard/catch-all
                Node::Identifier(name)
                    if name == "_"
                        || !variants
                            .variants
                            .iter()
                            .any(|variant| variant.name == *name) =>
                {
                    has_wildcard = true;
                }
                // Direct enum construct pattern: EnumName.Variant
                Node::EnumConstruct { variant, .. } => covered.push(variant.clone()),
                // PropertyAccess pattern: EnumName.Variant (no args)
                Node::PropertyAccess { property, .. } => covered.push(property.clone()),
                _ => {
                    // Unknown pattern shape — conservatively treat as wildcard
                    has_wildcard = true;
                }
            }
        }

        if has_wildcard {
            return;
        }

        let missing: Vec<&String> = variants
            .variants
            .iter()
            .map(|variant| &variant.name)
            .filter(|variant| !covered.contains(variant))
            .collect();
        if !missing.is_empty() {
            let missing_str = missing
                .iter()
                .map(|s| format!("\"{}\"", s))
                .collect::<Vec<_>>()
                .join(", ");
            self.warning_at(
                format!(
                    "Non-exhaustive match on enum {}: missing variants {}",
                    enum_name, missing_str
                ),
                span,
            );
        }
    }

    /// Check exhaustiveness for match on union types (e.g. `string | int | nil`).
    fn check_match_exhaustiveness_union(
        &mut self,
        value: &SNode,
        arms: &[MatchArm],
        scope: &TypeScope,
        span: Span,
    ) {
        let Some(TypeExpr::Union(members)) = self.infer_type(value, scope) else {
            return;
        };
        // Only check unions of named types (string, int, nil, bool, etc.)
        if !members.iter().all(|m| matches!(m, TypeExpr::Named(_))) {
            return;
        }

        let mut has_wildcard = false;
        let mut covered_types: Vec<String> = Vec::new();

        for arm in arms {
            match &arm.pattern.node {
                // type_of(x) == "string" style patterns are common but hard to detect here
                // Literal patterns cover specific types
                Node::NilLiteral => covered_types.push("nil".into()),
                Node::BoolLiteral(_) => {
                    if !covered_types.contains(&"bool".into()) {
                        covered_types.push("bool".into());
                    }
                }
                Node::IntLiteral(_) => {
                    if !covered_types.contains(&"int".into()) {
                        covered_types.push("int".into());
                    }
                }
                Node::FloatLiteral(_) => {
                    if !covered_types.contains(&"float".into()) {
                        covered_types.push("float".into());
                    }
                }
                Node::StringLiteral(_) => {
                    if !covered_types.contains(&"string".into()) {
                        covered_types.push("string".into());
                    }
                }
                Node::Identifier(name) if name == "_" => {
                    has_wildcard = true;
                }
                _ => {
                    has_wildcard = true;
                }
            }
        }

        if has_wildcard {
            return;
        }

        let type_names: Vec<&str> = members
            .iter()
            .filter_map(|m| match m {
                TypeExpr::Named(n) => Some(n.as_str()),
                _ => None,
            })
            .collect();
        let missing: Vec<&&str> = type_names
            .iter()
            .filter(|t| !covered_types.iter().any(|c| c == **t))
            .collect();
        if !missing.is_empty() {
            let missing_str = missing
                .iter()
                .map(|s| s.to_string())
                .collect::<Vec<_>>()
                .join(", ");
            self.warning_at(
                format!(
                    "Non-exhaustive match on union type: missing {}",
                    missing_str
                ),
                span,
            );
        }
    }

    /// Complete set of concrete variants that `type_of` may return, used as
    /// the reference for exhaustive-narrowing warnings on `unknown`.
    const UNKNOWN_CONCRETE_TYPES: &'static [&'static str] = &[
        "int", "string", "float", "bool", "nil", "list", "dict", "closure",
    ];

    /// Emit a warning if any `unknown`-typed variable in scope has been
    /// partially narrowed via `type_of(v) == "T"` checks but the current
    /// control-flow path reaches a never-returning site (`unreachable()`,
    /// a function with `Never` return, or a `throw`) without covering every
    /// concrete `type_of` variant.
    ///
    /// The ruled-out set must be non-empty — reaching `throw`/`unreachable`
    /// without any narrowing isn't an exhaustiveness claim, so it stays
    /// silent and avoids false positives on plain error paths.
    fn check_unknown_exhaustiveness(&mut self, scope: &TypeScope, span: Span, site_label: &str) {
        let entries = scope.collect_unknown_ruled_out();
        for (var_name, covered) in entries {
            if covered.is_empty() {
                continue;
            }
            // Only warn if `v` is still typed `unknown` at this point —
            // if it was fully narrowed elsewhere the ruled-out set is stale.
            if !matches!(
                scope.get_var(&var_name),
                Some(Some(TypeExpr::Named(n))) if n == "unknown"
            ) {
                continue;
            }
            let missing: Vec<&str> = Self::UNKNOWN_CONCRETE_TYPES
                .iter()
                .copied()
                .filter(|t| !covered.iter().any(|c| c == t))
                .collect();
            if missing.is_empty() {
                continue;
            }
            let missing_str = missing
                .iter()
                .map(|s| s.to_string())
                .collect::<Vec<_>>()
                .join(", ");
            self.warning_at(
                format!(
                    "`{site}` reached but `{var}: unknown` was not fully narrowed — uncovered concrete type(s): {missing}",
                    site = site_label,
                    var = var_name,
                    missing = missing_str,
                ),
                span,
            );
        }
    }

    /// Recursively scan an AST node for FunctionCalls whose name is in
    /// `self.deprecated_fns`, emitting a warning at each call site.
    /// Standalone from `check_call` so it works even in expression
    /// positions where `check_node` only triggers `infer_type`.
    fn visit_for_deprecation(&mut self, node: &SNode) {
        match &node.node {
            Node::FunctionCall { name, args } => {
                if let Some((since, use_hint)) = self.deprecated_fns.get(name).cloned() {
                    let mut msg = format!("`{name}` is deprecated");
                    if let Some(s) = since {
                        msg.push_str(&format!(" (since {s})"));
                    }
                    match use_hint {
                        Some(h) => {
                            self.warning_at_with_help(msg, node.span, format!("use `{h}` instead"))
                        }
                        None => self.warning_at(msg, node.span),
                    }
                }
                for a in args {
                    self.visit_for_deprecation(a);
                }
            }
            Node::MethodCall { object, args, .. }
            | Node::OptionalMethodCall { object, args, .. } => {
                self.visit_for_deprecation(object);
                for a in args {
                    self.visit_for_deprecation(a);
                }
            }
            Node::AttributedDecl { inner, .. } => self.visit_for_deprecation(inner),
            Node::Pipeline { body, .. }
            | Node::OverrideDecl { body, .. }
            | Node::FnDecl { body, .. }
            | Node::ToolDecl { body, .. }
            | Node::SpawnExpr { body }
            | Node::TryExpr { body }
            | Node::Block(body)
            | Node::Closure { body, .. }
            | Node::WhileLoop { body, .. }
            | Node::Retry { body, .. }
            | Node::DeferStmt { body }
            | Node::MutexBlock { body }
            | Node::Parallel { body, .. } => {
                for s in body {
                    self.visit_for_deprecation(s);
                }
            }
            Node::IfElse {
                condition,
                then_body,
                else_body,
            } => {
                self.visit_for_deprecation(condition);
                for s in then_body {
                    self.visit_for_deprecation(s);
                }
                if let Some(eb) = else_body {
                    for s in eb {
                        self.visit_for_deprecation(s);
                    }
                }
            }
            Node::ForIn { iterable, body, .. } => {
                self.visit_for_deprecation(iterable);
                for s in body {
                    self.visit_for_deprecation(s);
                }
            }
            Node::TryCatch {
                body,
                catch_body,
                finally_body,
                ..
            } => {
                for s in body {
                    self.visit_for_deprecation(s);
                }
                for s in catch_body {
                    self.visit_for_deprecation(s);
                }
                if let Some(fb) = finally_body {
                    for s in fb {
                        self.visit_for_deprecation(s);
                    }
                }
            }
            Node::DeadlineBlock { duration, body } => {
                self.visit_for_deprecation(duration);
                for s in body {
                    self.visit_for_deprecation(s);
                }
            }
            Node::MatchExpr { value, arms } => {
                self.visit_for_deprecation(value);
                for arm in arms {
                    if let Some(g) = &arm.guard {
                        self.visit_for_deprecation(g);
                    }
                    for s in &arm.body {
                        self.visit_for_deprecation(s);
                    }
                }
            }
            Node::LetBinding { value, .. } | Node::VarBinding { value, .. } => {
                self.visit_for_deprecation(value);
            }
            Node::Assignment { target, value, .. } => {
                self.visit_for_deprecation(target);
                self.visit_for_deprecation(value);
            }
            Node::ReturnStmt { value: Some(v) } | Node::YieldExpr { value: Some(v) } => {
                self.visit_for_deprecation(v);
            }
            Node::ThrowStmt { value }
            | Node::TryOperator { operand: value }
            | Node::TryStar { operand: value }
            | Node::Spread(value) => self.visit_for_deprecation(value),
            Node::UnaryOp { operand, .. } => self.visit_for_deprecation(operand),
            Node::BinaryOp { left, right, .. } => {
                self.visit_for_deprecation(left);
                self.visit_for_deprecation(right);
            }
            Node::Ternary {
                condition,
                true_expr,
                false_expr,
            } => {
                self.visit_for_deprecation(condition);
                self.visit_for_deprecation(true_expr);
                self.visit_for_deprecation(false_expr);
            }
            Node::PropertyAccess { object, .. } | Node::OptionalPropertyAccess { object, .. } => {
                self.visit_for_deprecation(object)
            }
            Node::SubscriptAccess { object, index } => {
                self.visit_for_deprecation(object);
                self.visit_for_deprecation(index);
            }
            Node::SliceAccess { object, start, end } => {
                self.visit_for_deprecation(object);
                if let Some(s) = start {
                    self.visit_for_deprecation(s);
                }
                if let Some(e) = end {
                    self.visit_for_deprecation(e);
                }
            }
            Node::EnumConstruct { args, .. } | Node::ListLiteral(args) => {
                for a in args {
                    self.visit_for_deprecation(a);
                }
            }
            Node::DictLiteral(entries)
            | Node::StructConstruct {
                fields: entries, ..
            } => {
                for e in entries {
                    self.visit_for_deprecation(&e.key);
                    self.visit_for_deprecation(&e.value);
                }
            }
            Node::GuardStmt {
                condition,
                else_body,
            } => {
                self.visit_for_deprecation(condition);
                for s in else_body {
                    self.visit_for_deprecation(s);
                }
            }
            Node::RequireStmt {
                condition, message, ..
            } => {
                self.visit_for_deprecation(condition);
                if let Some(m) = message {
                    self.visit_for_deprecation(m);
                }
            }
            Node::RangeExpr { start, end, .. } => {
                self.visit_for_deprecation(start);
                self.visit_for_deprecation(end);
            }
            Node::SelectExpr {
                cases,
                timeout,
                default_body,
            } => {
                for c in cases {
                    self.visit_for_deprecation(&c.channel);
                    for s in &c.body {
                        self.visit_for_deprecation(s);
                    }
                }
                if let Some((d, b)) = timeout {
                    self.visit_for_deprecation(d);
                    for s in b {
                        self.visit_for_deprecation(s);
                    }
                }
                if let Some(b) = default_body {
                    for s in b {
                        self.visit_for_deprecation(s);
                    }
                }
            }
            Node::ImplBlock { methods, .. } => {
                for m in methods {
                    self.visit_for_deprecation(m);
                }
            }
            // Terminals / decls without nested expressions of interest
            _ => {}
        }
    }

    fn check_call(&mut self, name: &str, args: &[SNode], scope: &mut TypeScope, span: Span) {
        // Deprecation: emit a warning at every call site of an `@deprecated`
        // function, including `since:` and `use:` hints when present.
        // (Also covered by the visit_for_deprecation pass; keep both so
        // callers reachable only through one path are still flagged.)
        if let Some((since, use_hint)) = self.deprecated_fns.get(name).cloned() {
            let mut msg = format!("`{name}` is deprecated");
            if let Some(s) = since {
                msg.push_str(&format!(" (since {s})"));
            }
            let help = use_hint.map(|h| format!("use `{h}` instead"));
            match help {
                Some(h) => self.warning_at_with_help(msg, span, h),
                None => self.warning_at(msg, span),
            }
        }
        // Special-case: unreachable(x) — when the argument is a variable,
        // verify it has been narrowed to `never` (exhaustiveness check).
        if name == "unreachable" {
            if let Some(arg) = args.first() {
                if matches!(&arg.node, Node::Identifier(_)) {
                    let arg_type = self.infer_type(arg, scope);
                    if let Some(ref ty) = arg_type {
                        if !matches!(ty, TypeExpr::Never) {
                            self.error_at(
                                format!(
                                    "unreachable() argument has type `{}` — not all cases are handled",
                                    format_type(ty)
                                ),
                                span,
                            );
                        }
                    }
                }
            }
            self.check_unknown_exhaustiveness(scope, span, "unreachable()");
            for arg in args {
                self.check_node(arg, scope);
            }
            return;
        }

        // Calls to user-defined functions with a `never` return type also
        // signal "this path claims exhaustiveness" — apply the same check.
        if let Some(sig) = scope.get_fn(name).cloned() {
            if matches!(sig.return_type, Some(TypeExpr::Never)) {
                self.check_unknown_exhaustiveness(scope, span, &format!("{}()", name));
            }
        }

        // Check against known function signatures
        let has_spread = args.iter().any(|a| matches!(&a.node, Node::Spread(_)));
        if let Some(sig) = scope.get_fn(name).cloned() {
            if !has_spread
                && !is_builtin(name)
                && !sig.has_rest
                && (args.len() < sig.required_params || args.len() > sig.params.len())
            {
                let expected = if sig.required_params == sig.params.len() {
                    format!("{}", sig.params.len())
                } else {
                    format!("{}-{}", sig.required_params, sig.params.len())
                };
                self.warning_at(
                    format!(
                        "Function '{}' expects {} arguments, got {}",
                        name,
                        expected,
                        args.len()
                    ),
                    span,
                );
            }
            // Build a scope that includes the function's generic type params
            // so they are treated as compatible with any concrete type.
            let call_scope = if sig.type_param_names.is_empty() {
                scope.clone()
            } else {
                let mut s = scope.child();
                for tp_name in &sig.type_param_names {
                    s.generic_type_params.insert(tp_name.clone());
                }
                s
            };
            let mut type_bindings: BTreeMap<String, TypeExpr> = BTreeMap::new();
            let type_param_set: std::collections::BTreeSet<String> =
                sig.type_param_names.iter().cloned().collect();
            for (arg, (_param_name, param_type)) in args.iter().zip(sig.params.iter()) {
                if let Some(param_ty) = param_type {
                    if let Err(message) = self.bind_from_arg_node(
                        param_ty,
                        arg,
                        &type_param_set,
                        &mut type_bindings,
                        scope,
                    ) {
                        self.error_at(message, arg.span);
                    }
                }
            }
            for (i, (arg, (param_name, param_type))) in
                args.iter().zip(sig.params.iter()).enumerate()
            {
                if let Some(expected) = param_type {
                    let actual = self.infer_type(arg, scope);
                    if let Some(actual) = &actual {
                        let expected = Self::apply_type_bindings(expected, &type_bindings);
                        if !self.types_compatible(&expected, actual, &call_scope) {
                            self.error_at(
                                format!(
                                    "Argument {} ('{}'): expected {}, got {}",
                                    i + 1,
                                    param_name,
                                    format_type(&expected),
                                    format_type(actual)
                                ),
                                arg.span,
                            );
                        }
                    }
                }
            }
            if !sig.where_clauses.is_empty() {
                for (type_param, bound) in &sig.where_clauses {
                    if let Some(concrete_type) = type_bindings.get(type_param) {
                        let concrete_name = format_type(concrete_type);
                        let Some(base_type_name) = Self::base_type_name(concrete_type) else {
                            self.error_at(
                                format!(
                                    "Type '{}' does not satisfy interface '{}': only named types can satisfy interfaces (required by constraint `where {}: {}`)",
                                    concrete_name, bound, type_param, bound
                                ),
                                span,
                            );
                            continue;
                        };
                        if let Some(reason) = self.interface_mismatch_reason(
                            base_type_name,
                            bound,
                            &BTreeMap::new(),
                            scope,
                        ) {
                            self.error_at(
                                format!(
                                    "Type '{}' does not satisfy interface '{}': {} \
                                     (required by constraint `where {}: {}`)",
                                    concrete_name, bound, reason, type_param, bound
                                ),
                                span,
                            );
                        }
                    }
                }
            }
        }
        // Check args recursively
        for arg in args {
            self.check_node(arg, scope);
        }
    }

    /// Infer the type of an expression.
    fn infer_type(&self, snode: &SNode, scope: &TypeScope) -> InferredType {
        match &snode.node {
            Node::IntLiteral(_) => Some(TypeExpr::Named("int".into())),
            Node::FloatLiteral(_) => Some(TypeExpr::Named("float".into())),
            Node::StringLiteral(_) | Node::InterpolatedString(_) => {
                Some(TypeExpr::Named("string".into()))
            }
            Node::BoolLiteral(_) => Some(TypeExpr::Named("bool".into())),
            Node::NilLiteral => Some(TypeExpr::Named("nil".into())),
            Node::ListLiteral(items) => Some(self.infer_list_literal_type(items, scope)),
            // `a to b` (and `a to b exclusive`) produce a lazy Range value.
            // Expose it as a named `range` type; for-in and method resolution
            // special-case this type where needed.
            Node::RangeExpr { .. } => Some(TypeExpr::Named("range".into())),
            Node::DictLiteral(entries) => {
                // Infer shape type when all keys are string literals
                let mut fields = Vec::new();
                for entry in entries {
                    let key = match &entry.key.node {
                        Node::StringLiteral(key) | Node::Identifier(key) => key.clone(),
                        _ => return Some(TypeExpr::Named("dict".into())),
                    };
                    let val_type = self
                        .infer_type(&entry.value, scope)
                        .unwrap_or(TypeExpr::Named("nil".into()));
                    fields.push(ShapeField {
                        name: key,
                        type_expr: val_type,
                        optional: false,
                    });
                }
                if !fields.is_empty() {
                    Some(TypeExpr::Shape(fields))
                } else {
                    Some(TypeExpr::Named("dict".into()))
                }
            }
            Node::Closure { params, body, .. } => {
                // If all params are typed and we can infer a return type, produce FnType
                let all_typed = params.iter().all(|p| p.type_expr.is_some());
                if all_typed && !params.is_empty() {
                    let param_types: Vec<TypeExpr> =
                        params.iter().filter_map(|p| p.type_expr.clone()).collect();
                    // Try to infer return type from last expression in body
                    let ret = body.last().and_then(|last| self.infer_type(last, scope));
                    if let Some(ret_type) = ret {
                        return Some(TypeExpr::FnType {
                            params: param_types,
                            return_type: Box::new(ret_type),
                        });
                    }
                }
                Some(TypeExpr::Named("closure".into()))
            }

            Node::Identifier(name) => scope.get_var(name).cloned().flatten(),

            Node::FunctionCall { name, args } => {
                // Struct constructor calls return the struct type
                if let Some(struct_info) = scope.get_struct(name) {
                    return Some(Self::applied_type_or_name(
                        name,
                        struct_info
                            .type_params
                            .iter()
                            .map(|_| Self::wildcard_type())
                            .collect(),
                    ));
                }
                if name == "Ok" {
                    let ok_type = args
                        .first()
                        .and_then(|arg| self.infer_type(arg, scope))
                        .unwrap_or_else(Self::wildcard_type);
                    return Some(TypeExpr::Applied {
                        name: "Result".into(),
                        args: vec![ok_type, Self::wildcard_type()],
                    });
                }
                if name == "Err" {
                    let err_type = args
                        .first()
                        .and_then(|arg| self.infer_type(arg, scope))
                        .unwrap_or_else(Self::wildcard_type);
                    return Some(TypeExpr::Applied {
                        name: "Result".into(),
                        args: vec![Self::wildcard_type(), err_type],
                    });
                }
                // Check user-defined function return types
                if let Some(sig) = scope.get_fn(name).cloned() {
                    let mut return_type = sig.return_type.clone();
                    if let Some(ty) = return_type.take() {
                        if sig.type_param_names.is_empty() {
                            return Some(ty);
                        }
                        let mut bindings = BTreeMap::new();
                        let type_param_set: std::collections::BTreeSet<String> =
                            sig.type_param_names.iter().cloned().collect();
                        for (arg, (_param_name, param_type)) in args.iter().zip(sig.params.iter()) {
                            if let Some(param_ty) = param_type {
                                let _ = self.bind_from_arg_node(
                                    param_ty,
                                    arg,
                                    &type_param_set,
                                    &mut bindings,
                                    scope,
                                );
                            }
                        }
                        return Some(Self::apply_type_bindings(&ty, &bindings));
                    }
                    return None;
                }
                // Generic builtins (llm_call, schema_parse/check/expect):
                // bind T by walking each arg node against the param
                // TypeExpr, then apply bindings to the declared return
                // type. Falls through to `builtin_return_type` when no T
                // could be bound (e.g. llm_call without an output_schema
                // option), preserving the historical `dict` return.
                if let Some(sig) = builtin_signatures::lookup_generic_builtin_sig(name) {
                    let type_param_set: std::collections::BTreeSet<String> =
                        sig.type_params.iter().cloned().collect();
                    let mut bindings: BTreeMap<String, TypeExpr> = BTreeMap::new();
                    for (arg, param_ty) in args.iter().zip(sig.params.iter()) {
                        let _ = self.bind_from_arg_node(
                            param_ty,
                            arg,
                            &type_param_set,
                            &mut bindings,
                            scope,
                        );
                    }
                    let all_bound = sig.type_params.iter().all(|tp| bindings.contains_key(tp));
                    if all_bound {
                        return Some(Self::apply_type_bindings(&sig.return_type, &bindings));
                    }
                }
                // Check builtin return types
                builtin_return_type(name)
            }

            Node::BinaryOp { op, left, right } => {
                let lt = self.infer_type(left, scope);
                let rt = self.infer_type(right, scope);
                infer_binary_op_type(op, &lt, &rt)
            }

            Node::UnaryOp { op, operand } => {
                let t = self.infer_type(operand, scope);
                match op.as_str() {
                    "!" => Some(TypeExpr::Named("bool".into())),
                    "-" => t, // negation preserves type
                    _ => None,
                }
            }

            Node::Ternary {
                condition,
                true_expr,
                false_expr,
            } => {
                let refs = Self::extract_refinements(condition, scope);

                let mut true_scope = scope.child();
                refs.apply_truthy(&mut true_scope);
                let tt = self.infer_type(true_expr, &true_scope);

                let mut false_scope = scope.child();
                refs.apply_falsy(&mut false_scope);
                let ft = self.infer_type(false_expr, &false_scope);

                match (&tt, &ft) {
                    (Some(a), Some(b)) if a == b => tt,
                    (Some(a), Some(b)) => Some(TypeExpr::Union(vec![a.clone(), b.clone()])),
                    (Some(_), None) => tt,
                    (None, Some(_)) => ft,
                    (None, None) => None,
                }
            }

            Node::EnumConstruct {
                enum_name,
                variant,
                args,
            } => {
                if let Some(enum_info) = scope.get_enum(enum_name) {
                    Some(self.infer_enum_type(enum_name, enum_info, variant, args, scope))
                } else {
                    Some(TypeExpr::Named(enum_name.clone()))
                }
            }

            Node::PropertyAccess { object, property } => {
                // EnumName.Variant → infer as the enum type
                if let Node::Identifier(name) = &object.node {
                    if let Some(enum_info) = scope.get_enum(name) {
                        return Some(self.infer_enum_type(name, enum_info, property, &[], scope));
                    }
                }
                // .variant on an enum value → string
                if property == "variant" {
                    let obj_type = self.infer_type(object, scope);
                    if let Some(name) = obj_type.as_ref().and_then(Self::base_type_name) {
                        if scope.get_enum(name).is_some() {
                            return Some(TypeExpr::Named("string".into()));
                        }
                    }
                }
                // Shape field access: obj.field → field type
                let obj_type = self.infer_type(object, scope);
                // Pair<K, V> has `.first` and `.second` accessors.
                if let Some(TypeExpr::Applied { name, args }) = &obj_type {
                    if name == "Pair" && args.len() == 2 {
                        if property == "first" {
                            return Some(args[0].clone());
                        } else if property == "second" {
                            return Some(args[1].clone());
                        }
                    }
                }
                if let Some(TypeExpr::Shape(fields)) = &obj_type {
                    if let Some(field) = fields.iter().find(|f| f.name == *property) {
                        return Some(field.type_expr.clone());
                    }
                }
                None
            }

            Node::SubscriptAccess { object, index } => {
                let obj_type = self.infer_type(object, scope);
                match &obj_type {
                    Some(TypeExpr::List(inner)) => Some(*inner.clone()),
                    Some(TypeExpr::DictType(_, v)) => Some(*v.clone()),
                    Some(TypeExpr::Shape(fields)) => {
                        // If index is a string literal, look up the field type
                        if let Node::StringLiteral(key) = &index.node {
                            fields
                                .iter()
                                .find(|f| &f.name == key)
                                .map(|f| f.type_expr.clone())
                        } else {
                            None
                        }
                    }
                    Some(TypeExpr::Named(n)) if n == "list" => None,
                    Some(TypeExpr::Named(n)) if n == "dict" => None,
                    Some(TypeExpr::Named(n)) if n == "string" => {
                        Some(TypeExpr::Named("string".into()))
                    }
                    _ => None,
                }
            }
            Node::SliceAccess { object, .. } => {
                // Slicing a list returns the same list type; slicing a string returns string
                let obj_type = self.infer_type(object, scope);
                match &obj_type {
                    Some(TypeExpr::List(_)) => obj_type,
                    Some(TypeExpr::Named(n)) if n == "list" => obj_type,
                    Some(TypeExpr::Named(n)) if n == "string" => {
                        Some(TypeExpr::Named("string".into()))
                    }
                    _ => None,
                }
            }
            Node::MethodCall {
                object,
                method,
                args,
            }
            | Node::OptionalMethodCall {
                object,
                method,
                args,
            } => {
                if let Node::Identifier(name) = &object.node {
                    if let Some(enum_info) = scope.get_enum(name) {
                        return Some(self.infer_enum_type(name, enum_info, method, args, scope));
                    }
                    if name == "Result" && (method == "Ok" || method == "Err") {
                        let ok_type = if method == "Ok" {
                            args.first()
                                .and_then(|arg| self.infer_type(arg, scope))
                                .unwrap_or_else(Self::wildcard_type)
                        } else {
                            Self::wildcard_type()
                        };
                        let err_type = if method == "Err" {
                            args.first()
                                .and_then(|arg| self.infer_type(arg, scope))
                                .unwrap_or_else(Self::wildcard_type)
                        } else {
                            Self::wildcard_type()
                        };
                        return Some(TypeExpr::Applied {
                            name: "Result".into(),
                            args: vec![ok_type, err_type],
                        });
                    }
                }
                let obj_type = self.infer_type(object, scope);
                // Iter<T> receiver: combinators preserve or transform T; sinks
                // materialize. This must come before the shared-method match
                // below so `.map` / `.filter` / etc. on an iter return Iter,
                // not list.
                let iter_elem_type: Option<TypeExpr> = match &obj_type {
                    Some(TypeExpr::Iter(inner)) => Some((**inner).clone()),
                    Some(TypeExpr::Named(n)) if n == "iter" => Some(TypeExpr::Named("any".into())),
                    _ => None,
                };
                if let Some(t) = iter_elem_type {
                    let pair = |k: TypeExpr, v: TypeExpr| TypeExpr::Applied {
                        name: "Pair".into(),
                        args: vec![k, v],
                    };
                    let iter_of = |ty: TypeExpr| TypeExpr::Iter(Box::new(ty));
                    match method.as_str() {
                        "iter" => return Some(iter_of(t)),
                        "map" | "flat_map" => {
                            // Closure-return inference is not threaded here;
                            // fall back to a coarse `iter<any>` — matches the
                            // list-return style the rest of the checker uses.
                            return Some(TypeExpr::Named("iter".into()));
                        }
                        "filter" | "take" | "skip" | "take_while" | "skip_while" => {
                            return Some(iter_of(t));
                        }
                        "zip" => {
                            return Some(iter_of(pair(t, TypeExpr::Named("any".into()))));
                        }
                        "enumerate" => {
                            return Some(iter_of(pair(TypeExpr::Named("int".into()), t)));
                        }
                        "chain" => return Some(iter_of(t)),
                        "chunks" | "windows" => {
                            return Some(iter_of(TypeExpr::List(Box::new(t))));
                        }
                        // Sinks
                        "to_list" => return Some(TypeExpr::List(Box::new(t))),
                        "to_set" => {
                            return Some(TypeExpr::Applied {
                                name: "set".into(),
                                args: vec![t],
                            })
                        }
                        "to_dict" => return Some(TypeExpr::Named("dict".into())),
                        "count" => return Some(TypeExpr::Named("int".into())),
                        "sum" => {
                            return Some(TypeExpr::Union(vec![
                                TypeExpr::Named("int".into()),
                                TypeExpr::Named("float".into()),
                            ]))
                        }
                        "min" | "max" | "first" | "last" | "find" => {
                            return Some(TypeExpr::Union(vec![t, TypeExpr::Named("nil".into())]));
                        }
                        "any" | "all" => return Some(TypeExpr::Named("bool".into())),
                        "for_each" => return Some(TypeExpr::Named("nil".into())),
                        "reduce" => return None,
                        _ => {}
                    }
                }
                // list<T> / dict / set / string .iter() → iter<T>. Other
                // combinator methods on list/dict/set/string keep their
                // existing eager typings (the runtime still materializes
                // them). Only the explicit .iter() bridge returns Iter.
                if method == "iter" {
                    match &obj_type {
                        Some(TypeExpr::List(inner)) => {
                            return Some(TypeExpr::Iter(Box::new((**inner).clone())));
                        }
                        Some(TypeExpr::DictType(k, v)) => {
                            return Some(TypeExpr::Iter(Box::new(TypeExpr::Applied {
                                name: "Pair".into(),
                                args: vec![(**k).clone(), (**v).clone()],
                            })));
                        }
                        Some(TypeExpr::Named(n))
                            if n == "list" || n == "dict" || n == "set" || n == "string" =>
                        {
                            return Some(TypeExpr::Named("iter".into()));
                        }
                        _ => {}
                    }
                }
                let is_dict = matches!(&obj_type, Some(TypeExpr::Named(n)) if n == "dict")
                    || matches!(&obj_type, Some(TypeExpr::DictType(..)))
                    || matches!(&obj_type, Some(TypeExpr::Shape(_)));
                match method.as_str() {
                    // Shared: bool-returning methods
                    "contains" | "starts_with" | "ends_with" | "empty" | "has" | "any" | "all" => {
                        Some(TypeExpr::Named("bool".into()))
                    }
                    // Shared: int-returning methods
                    "count" | "index_of" => Some(TypeExpr::Named("int".into())),
                    // String methods
                    "trim" | "lowercase" | "uppercase" | "reverse" | "replace" | "substring"
                    | "pad_left" | "pad_right" | "repeat" | "join" => {
                        Some(TypeExpr::Named("string".into()))
                    }
                    "split" | "chars" => Some(TypeExpr::Named("list".into())),
                    // filter returns dict for dicts, list for lists
                    "filter" => {
                        if is_dict {
                            Some(TypeExpr::Named("dict".into()))
                        } else {
                            Some(TypeExpr::Named("list".into()))
                        }
                    }
                    // List methods
                    "map" | "flat_map" | "sort" => Some(TypeExpr::Named("list".into())),
                    "window" | "each_cons" | "sliding_window" => match &obj_type {
                        Some(TypeExpr::List(inner)) => Some(TypeExpr::List(Box::new(
                            TypeExpr::List(Box::new((**inner).clone())),
                        ))),
                        _ => Some(TypeExpr::Named("list".into())),
                    },
                    "reduce" | "find" | "first" | "last" => None,
                    // Dict methods
                    "keys" | "values" | "entries" => Some(TypeExpr::Named("list".into())),
                    "merge" | "map_values" | "rekey" | "map_keys" => {
                        // Rekey/map_keys transform keys; resulting dict still keys-by-string.
                        // Preserve the value-type parameter when known so downstream code can
                        // still rely on dict<string, V> typing after a key-rename.
                        if let Some(TypeExpr::DictType(_, v)) = &obj_type {
                            Some(TypeExpr::DictType(
                                Box::new(TypeExpr::Named("string".into())),
                                v.clone(),
                            ))
                        } else {
                            Some(TypeExpr::Named("dict".into()))
                        }
                    }
                    // Conversions
                    "to_string" => Some(TypeExpr::Named("string".into())),
                    "to_int" => Some(TypeExpr::Named("int".into())),
                    "to_float" => Some(TypeExpr::Named("float".into())),
                    _ => None,
                }
            }

            // TryOperator on Result<T, E> produces T
            Node::TryOperator { operand } => match self.infer_type(operand, scope) {
                Some(TypeExpr::Applied { name, args }) if name == "Result" && args.len() == 2 => {
                    Some(args[0].clone())
                }
                Some(TypeExpr::Named(name)) if name == "Result" => None,
                _ => None,
            },

            // Exit expressions produce the bottom type.
            Node::ThrowStmt { .. }
            | Node::ReturnStmt { .. }
            | Node::BreakStmt
            | Node::ContinueStmt => Some(TypeExpr::Never),

            // If/else as expression: merge branch types.
            Node::IfElse {
                then_body,
                else_body,
                ..
            } => {
                let then_type = self.infer_block_type(then_body, scope);
                let else_type = else_body
                    .as_ref()
                    .and_then(|eb| self.infer_block_type(eb, scope));
                match (then_type, else_type) {
                    (Some(TypeExpr::Never), Some(TypeExpr::Never)) => Some(TypeExpr::Never),
                    (Some(TypeExpr::Never), Some(other)) | (Some(other), Some(TypeExpr::Never)) => {
                        Some(other)
                    }
                    (Some(t), Some(e)) if t == e => Some(t),
                    (Some(t), Some(e)) => Some(simplify_union(vec![t, e])),
                    (Some(t), None) => Some(t),
                    (None, _) => None,
                }
            }

            Node::TryExpr { body } => {
                let ok_type = self
                    .infer_block_type(body, scope)
                    .unwrap_or_else(Self::wildcard_type);
                let err_type = self
                    .infer_try_error_type(body, scope)
                    .unwrap_or_else(Self::wildcard_type);
                Some(TypeExpr::Applied {
                    name: "Result".into(),
                    args: vec![ok_type, err_type],
                })
            }

            // `try* EXPR` evaluates to EXPR's value on success; rethrow on
            // error never returns. Type is therefore EXPR's inferred type.
            Node::TryStar { operand } => self.infer_type(operand, scope),

            Node::StructConstruct {
                struct_name,
                fields,
            } => scope
                .get_struct(struct_name)
                .map(|struct_info| self.infer_struct_type(struct_name, struct_info, fields, scope))
                .or_else(|| Some(TypeExpr::Named(struct_name.clone()))),

            _ => None,
        }
    }

    /// Infer the type of a block (last expression, or `never` if the block definitely exits).
    fn infer_block_type(&self, stmts: &[SNode], scope: &TypeScope) -> InferredType {
        if Self::block_definitely_exits(stmts) {
            return Some(TypeExpr::Never);
        }
        stmts.last().and_then(|s| self.infer_type(s, scope))
    }

    /// Check if `actual` can be assigned to `expected` (covariant subtype).
    ///
    /// This is a thin wrapper over [`types_compatible_at`] that enters
    /// the relation at covariant polarity. Callers that want to check
    /// invariance or contravariance directly can use
    /// [`types_compatible_at`] with the appropriate [`Polarity`].
    fn types_compatible(&self, expected: &TypeExpr, actual: &TypeExpr, scope: &TypeScope) -> bool {
        self.types_compatible_at(Polarity::Covariant, expected, actual, scope)
    }

    /// Polarity-aware subtype check.
    ///
    /// - `Covariant`: `actual <: expected` under ordinary widening
    ///   (this is the public entry point behavior).
    /// - `Contravariant`: swaps the arguments and recurses covariantly.
    /// - `Invariant`: both directions must hold covariantly. This
    ///   disables the asymmetric numeric widening (`int <: float`)
    ///   that we rely on in covariant positions, so mutable container
    ///   slots do not accept a narrower element type.
    fn types_compatible_at(
        &self,
        polarity: Polarity,
        expected: &TypeExpr,
        actual: &TypeExpr,
        scope: &TypeScope,
    ) -> bool {
        match polarity {
            Polarity::Covariant => {}
            Polarity::Contravariant => {
                return self.types_compatible_at(Polarity::Covariant, actual, expected, scope);
            }
            Polarity::Invariant => {
                return self.types_compatible_at(Polarity::Covariant, expected, actual, scope)
                    && self.types_compatible_at(Polarity::Covariant, actual, expected, scope);
            }
        }

        // From here on we are in the covariant case.
        if Self::is_wildcard_type(expected) || Self::is_wildcard_type(actual) {
            return true;
        }
        // Generic type parameters match anything.
        if let TypeExpr::Named(name) = expected {
            if scope.is_generic_type_param(name) {
                return true;
            }
        }
        if let TypeExpr::Named(name) = actual {
            if scope.is_generic_type_param(name) {
                return true;
            }
        }
        let expected = self.resolve_alias(expected, scope);
        let actual = self.resolve_alias(actual, scope);

        // Interface satisfaction: if expected names an interface, check method compatibility.
        if let Some(iface_name) = Self::base_type_name(&expected) {
            if let Some(interface_info) = scope.get_interface(iface_name) {
                let mut interface_bindings = BTreeMap::new();
                if let TypeExpr::Applied { args, .. } = &expected {
                    for (type_param, arg) in interface_info.type_params.iter().zip(args.iter()) {
                        interface_bindings.insert(type_param.name.clone(), arg.clone());
                    }
                }
                if let Some(type_name) = Self::base_type_name(&actual) {
                    return self.satisfies_interface(
                        type_name,
                        iface_name,
                        &interface_bindings,
                        scope,
                    );
                }
                return false;
            }
        }

        match (&expected, &actual) {
            // never is the bottom type: assignable to any type.
            (_, TypeExpr::Never) => true,
            // Nothing is assignable to never (except never itself, handled above).
            (TypeExpr::Never, _) => false,
            // `any` is the top type (escape hatch): every type flows into `any`,
            // and `any` flows back out to any concrete type with no narrowing required.
            (TypeExpr::Named(n), _) if n == "any" => true,
            (_, TypeExpr::Named(n)) if n == "any" => true,
            // `unknown` is the safe top: every type flows into `unknown`, but
            // `unknown` only flows back out to `unknown` itself (or `any`, via the
            // arm above). Concrete uses require narrowing via `type_of` / `schema_is`.
            (TypeExpr::Named(n), _) if n == "unknown" => true,
            // Reverse direction: `unknown` is not assignable to anything concrete.
            // The `(_, Named("unknown"))` arm deliberately falls through to `=> false`
            // below, producing a "expected T, got unknown" diagnostic.
            (TypeExpr::Named(a), TypeExpr::Named(b)) => a == b || (a == "float" && b == "int"),
            (TypeExpr::Named(a), TypeExpr::Applied { name: b, .. })
            | (TypeExpr::Applied { name: a, .. }, TypeExpr::Named(b)) => a == b,
            (
                TypeExpr::Applied {
                    name: expected_name,
                    args: expected_args,
                },
                TypeExpr::Applied {
                    name: actual_name,
                    args: actual_args,
                },
            ) => {
                if expected_name != actual_name || expected_args.len() != actual_args.len() {
                    return false;
                }
                // Consult the declared variance for each type parameter
                // of this constructor. User-declared generics default
                // to `Invariant` for any parameter without a marker,
                // which is enforced by the per-TypeParam default set in
                // the parser and AST. Unknown constructors (e.g. an
                // inferred schema-driven wrapper whose decl has not
                // been registered yet) fall back to invariance — that
                // is strictly safer than the previous implicit
                // covariance.
                let variances = scope.variance_of(expected_name);
                for (idx, (expected_arg, actual_arg)) in
                    expected_args.iter().zip(actual_args.iter()).enumerate()
                {
                    let child_variance = variances
                        .as_ref()
                        .and_then(|v| v.get(idx).copied())
                        .unwrap_or(Variance::Invariant);
                    let arg_polarity = Polarity::Covariant.compose(child_variance);
                    if !self.types_compatible_at(arg_polarity, expected_arg, actual_arg, scope) {
                        return false;
                    }
                }
                true
            }
            // Union-to-Union: every member of actual must be compatible with
            // at least one member of expected.
            (TypeExpr::Union(exp_members), TypeExpr::Union(act_members)) => {
                act_members.iter().all(|am| {
                    exp_members
                        .iter()
                        .any(|em| self.types_compatible(em, am, scope))
                })
            }
            (TypeExpr::Union(members), actual_type) => members
                .iter()
                .any(|m| self.types_compatible(m, actual_type, scope)),
            (expected_type, TypeExpr::Union(members)) => members
                .iter()
                .all(|m| self.types_compatible(expected_type, m, scope)),
            (TypeExpr::Shape(_), TypeExpr::Named(n)) if n == "dict" => true,
            (TypeExpr::Named(n), TypeExpr::Shape(_)) if n == "dict" => true,
            (TypeExpr::Shape(ef), TypeExpr::Shape(af)) => ef.iter().all(|expected_field| {
                if expected_field.optional {
                    return true;
                }
                af.iter().any(|actual_field| {
                    actual_field.name == expected_field.name
                        && self.types_compatible(
                            &expected_field.type_expr,
                            &actual_field.type_expr,
                            scope,
                        )
                })
            }),
            // dict<K, V> expected, Shape actual → all field values must match V
            (TypeExpr::DictType(ek, ev), TypeExpr::Shape(af)) => {
                let keys_ok = matches!(ek.as_ref(), TypeExpr::Named(n) if n == "string");
                keys_ok
                    && af
                        .iter()
                        .all(|f| self.types_compatible(ev, &f.type_expr, scope))
            }
            // Shape expected, dict<K, V> actual → gradual: allow since dict may have the fields
            (TypeExpr::Shape(_), TypeExpr::DictType(_, _)) => true,
            // list<T> is invariant: the element type must match exactly
            // (no int→float widening) because lists are mutable
            // (`push`, index assignment). Covariant lists are unsound
            // on write — a `list<int>` flowing into a `list<float>`
            // slot would let a `float` be pushed and later observed
            // as an `int`.
            (TypeExpr::List(expected_inner), TypeExpr::List(actual_inner)) => {
                self.types_compatible_at(Polarity::Invariant, expected_inner, actual_inner, scope)
            }
            (TypeExpr::Named(n), TypeExpr::List(_)) if n == "list" => true,
            (TypeExpr::List(_), TypeExpr::Named(n)) if n == "list" => true,
            // iter<T> is covariant: it is a read-only sequence with no
            // mutating projection, so widening its element type is
            // sound.
            (TypeExpr::Iter(expected_inner), TypeExpr::Iter(actual_inner)) => {
                self.types_compatible(expected_inner, actual_inner, scope)
            }
            (TypeExpr::Named(n), TypeExpr::Iter(_)) if n == "iter" => true,
            (TypeExpr::Iter(_), TypeExpr::Named(n)) if n == "iter" => true,
            // dict<K, V> is invariant in both K and V: dicts are
            // mutable (key/value assignment). See the `list` comment
            // above for the soundness argument.
            (TypeExpr::DictType(ek, ev), TypeExpr::DictType(ak, av)) => {
                self.types_compatible_at(Polarity::Invariant, ek, ak, scope)
                    && self.types_compatible_at(Polarity::Invariant, ev, av, scope)
            }
            (TypeExpr::Named(n), TypeExpr::DictType(_, _)) if n == "dict" => true,
            (TypeExpr::DictType(_, _), TypeExpr::Named(n)) if n == "dict" => true,
            // FnType subtyping: parameters are contravariant (an
            // `fn(float)` can stand in for an expected `fn(int)`
            // because floats contain ints); return types remain
            // covariant. Previously params were checked covariantly,
            // which let `fn(int)` stand in for `fn(float)` — an
            // unsound callback substitution.
            (
                TypeExpr::FnType {
                    params: ep,
                    return_type: er,
                },
                TypeExpr::FnType {
                    params: ap,
                    return_type: ar,
                },
            ) => {
                ep.len() == ap.len()
                    && ep.iter().zip(ap.iter()).all(|(e, a)| {
                        self.types_compatible_at(Polarity::Contravariant, e, a, scope)
                    })
                    && self.types_compatible(er, ar, scope)
            }
            // FnType is compatible with Named("closure") for backward compat
            (TypeExpr::FnType { .. }, TypeExpr::Named(n)) if n == "closure" => true,
            (TypeExpr::Named(n), TypeExpr::FnType { .. }) if n == "closure" => true,
            // Literal types: identical literals match; a literal flows
            // into its base type (`"pass"` → `string`); and — as a gradual
            // concession — a base type flows into a literal-typed slot
            // (`string` → `"pass" | "fail"`) so that existing
            // string/int-typed data can populate discriminated unions
            // without per-call-site widening. Runtime schema validation
            // (emitted for typed params and `schema_is`/`schema_expect`
            // guards) catches values that violate the literal set.
            (TypeExpr::LitString(a), TypeExpr::LitString(b)) => a == b,
            (TypeExpr::LitInt(a), TypeExpr::LitInt(b)) => a == b,
            (TypeExpr::Named(n), TypeExpr::LitString(_)) if n == "string" => true,
            (TypeExpr::Named(n), TypeExpr::LitInt(_)) if n == "int" || n == "float" => true,
            (TypeExpr::LitString(_), TypeExpr::Named(n)) if n == "string" => true,
            (TypeExpr::LitInt(_), TypeExpr::Named(n)) if n == "int" => true,
            _ => false,
        }
    }

    fn resolve_alias<'a>(&self, ty: &'a TypeExpr, scope: &'a TypeScope) -> TypeExpr {
        match ty {
            TypeExpr::Named(name) => {
                if let Some(resolved) = scope.resolve_type(name) {
                    return self.resolve_alias(resolved, scope);
                }
                ty.clone()
            }
            TypeExpr::Union(types) => TypeExpr::Union(
                types
                    .iter()
                    .map(|ty| self.resolve_alias(ty, scope))
                    .collect(),
            ),
            TypeExpr::Shape(fields) => TypeExpr::Shape(
                fields
                    .iter()
                    .map(|field| ShapeField {
                        name: field.name.clone(),
                        type_expr: self.resolve_alias(&field.type_expr, scope),
                        optional: field.optional,
                    })
                    .collect(),
            ),
            TypeExpr::List(inner) => TypeExpr::List(Box::new(self.resolve_alias(inner, scope))),
            TypeExpr::Iter(inner) => TypeExpr::Iter(Box::new(self.resolve_alias(inner, scope))),
            TypeExpr::DictType(key, value) => TypeExpr::DictType(
                Box::new(self.resolve_alias(key, scope)),
                Box::new(self.resolve_alias(value, scope)),
            ),
            TypeExpr::FnType {
                params,
                return_type,
            } => TypeExpr::FnType {
                params: params
                    .iter()
                    .map(|param| self.resolve_alias(param, scope))
                    .collect(),
                return_type: Box::new(self.resolve_alias(return_type, scope)),
            },
            TypeExpr::Applied { name, args } => TypeExpr::Applied {
                name: name.clone(),
                args: args
                    .iter()
                    .map(|arg| self.resolve_alias(arg, scope))
                    .collect(),
            },
            TypeExpr::Never => TypeExpr::Never,
            TypeExpr::LitString(s) => TypeExpr::LitString(s.clone()),
            TypeExpr::LitInt(v) => TypeExpr::LitInt(*v),
        }
    }

    /// Check declared variance on a `fn` declaration. Parameter
    /// types are contravariant positions; the return type is a
    /// covariant position.
    fn check_fn_decl_variance(
        &mut self,
        type_params: &[TypeParam],
        params: &[TypedParam],
        return_type: Option<&TypeExpr>,
        name: &str,
        span: Span,
    ) {
        let mut positions: Vec<(&TypeExpr, Polarity)> = Vec::new();
        for p in params {
            if let Some(te) = &p.type_expr {
                positions.push((te, Polarity::Contravariant));
            }
        }
        if let Some(rt) = return_type {
            positions.push((rt, Polarity::Covariant));
        }
        let kind = format!("function '{name}'");
        self.check_decl_variance(&kind, type_params, &positions, span);
    }

    /// Check declared variance on a `type` alias. The alias body is
    /// treated as a covariant position (what the alias "produces").
    fn check_type_alias_decl_variance(
        &mut self,
        type_params: &[TypeParam],
        type_expr: &TypeExpr,
        name: &str,
        span: Span,
    ) {
        let positions = [(type_expr, Polarity::Covariant)];
        let kind = format!("type alias '{name}'");
        self.check_decl_variance(&kind, type_params, &positions, span);
    }

    /// Check declared variance on an `enum` declaration. Variant
    /// field types are covariant positions (enums are produced,
    /// not mutated in place).
    fn check_enum_decl_variance(
        &mut self,
        type_params: &[TypeParam],
        variants: &[EnumVariant],
        name: &str,
        span: Span,
    ) {
        let mut positions: Vec<(&TypeExpr, Polarity)> = Vec::new();
        for variant in variants {
            for field in &variant.fields {
                if let Some(te) = &field.type_expr {
                    positions.push((te, Polarity::Covariant));
                }
            }
        }
        let kind = format!("enum '{name}'");
        self.check_decl_variance(&kind, type_params, &positions, span);
    }

    /// Check declared variance on a `struct` declaration. Field
    /// types are invariant positions because struct fields are
    /// mutable in Harn. (If Harn ever gains read-only fields, those
    /// could be covariant.)
    fn check_struct_decl_variance(
        &mut self,
        type_params: &[TypeParam],
        fields: &[StructField],
        name: &str,
        span: Span,
    ) {
        let positions: Vec<(&TypeExpr, Polarity)> = fields
            .iter()
            .filter_map(|f| f.type_expr.as_ref().map(|te| (te, Polarity::Invariant)))
            .collect();
        let kind = format!("struct '{name}'");
        self.check_decl_variance(&kind, type_params, &positions, span);
    }

    /// Check declared variance on an `interface` declaration.
    /// Method parameter types are contravariant; method return types
    /// are covariant. Associated types are invariant positions.
    fn check_interface_decl_variance(
        &mut self,
        type_params: &[TypeParam],
        methods: &[InterfaceMethod],
        name: &str,
        span: Span,
    ) {
        let mut positions: Vec<(&TypeExpr, Polarity)> = Vec::new();
        for method in methods {
            for p in &method.params {
                if let Some(te) = &p.type_expr {
                    positions.push((te, Polarity::Contravariant));
                }
            }
            if let Some(rt) = &method.return_type {
                positions.push((rt, Polarity::Covariant));
            }
        }
        let kind = format!("interface '{name}'");
        self.check_decl_variance(&kind, type_params, &positions, span);
    }

    /// Declaration-site variance check.
    ///
    /// Given a set of declared type parameters (with their `Variance`
    /// annotations) and a list of positions in the declaration body
    /// where those parameters may appear, walk each position tracking
    /// polarity. A parameter declared `out T` (`Covariant`) may appear
    /// only in covariant positions; `in T` (`Contravariant`) only in
    /// contravariant positions; unannotated (`Invariant`) may appear
    /// anywhere.
    ///
    /// Callers pass each top-level expression together with its
    /// starting polarity. For example, a function's return type
    /// starts at `Covariant`, each parameter starts at `Contravariant`,
    /// an enum variant field starts at `Covariant`, etc.
    fn check_decl_variance(
        &mut self,
        decl_kind: &str,
        type_params: &[TypeParam],
        positions: &[(&TypeExpr, Polarity)],
        span: Span,
    ) {
        // Build a quick lookup: param name -> declared variance.
        // If no parameter has a non-invariant marker, skip the walk —
        // invariant params can appear in any polarity.
        if type_params
            .iter()
            .all(|tp| tp.variance == Variance::Invariant)
        {
            return;
        }
        let declared: BTreeMap<String, Variance> = type_params
            .iter()
            .map(|tp| (tp.name.clone(), tp.variance))
            .collect();
        for (ty, polarity) in positions {
            self.walk_variance(decl_kind, ty, *polarity, &declared, span);
        }
    }

    /// Recursive walker used by [`check_decl_variance`].
    #[allow(clippy::only_used_in_recursion)]
    fn walk_variance(
        &mut self,
        decl_kind: &str,
        ty: &TypeExpr,
        polarity: Polarity,
        declared: &BTreeMap<String, Variance>,
        span: Span,
    ) {
        match ty {
            TypeExpr::Named(name) => {
                if let Some(&declared_variance) = declared.get(name) {
                    let ok = matches!(
                        (declared_variance, polarity),
                        (Variance::Invariant, _)
                            | (Variance::Covariant, Polarity::Covariant)
                            | (Variance::Contravariant, Polarity::Contravariant)
                    );
                    if !ok {
                        let (marker, declared_word) = match declared_variance {
                            Variance::Covariant => ("out", "covariant"),
                            Variance::Contravariant => ("in", "contravariant"),
                            Variance::Invariant => unreachable!(),
                        };
                        let position_word = match polarity {
                            Polarity::Covariant => "covariant",
                            Polarity::Contravariant => "contravariant",
                            Polarity::Invariant => "invariant",
                        };
                        self.error_at(
                            format!(
                                "type parameter '{name}' is declared '{marker}' \
                                 ({declared_word}) but appears in a \
                                 {position_word} position in {decl_kind}"
                            ),
                            span,
                        );
                    }
                }
            }
            TypeExpr::List(inner) | TypeExpr::Iter(inner) => {
                // `list<T>` is invariant; `iter<T>` is covariant.
                let sub = match ty {
                    TypeExpr::List(_) => Polarity::Invariant,
                    TypeExpr::Iter(_) => polarity,
                    _ => unreachable!(),
                };
                self.walk_variance(decl_kind, inner, sub, declared, span);
            }
            TypeExpr::DictType(k, v) => {
                // dict<K, V> is invariant in both.
                self.walk_variance(decl_kind, k, Polarity::Invariant, declared, span);
                self.walk_variance(decl_kind, v, Polarity::Invariant, declared, span);
            }
            TypeExpr::Shape(fields) => {
                for f in fields {
                    self.walk_variance(decl_kind, &f.type_expr, polarity, declared, span);
                }
            }
            TypeExpr::Union(members) => {
                for m in members {
                    self.walk_variance(decl_kind, m, polarity, declared, span);
                }
            }
            TypeExpr::FnType {
                params,
                return_type,
            } => {
                // Parameters are contravariant; return is covariant,
                // composed with the outer polarity.
                let param_polarity = polarity.compose(Variance::Contravariant);
                for p in params {
                    self.walk_variance(decl_kind, p, param_polarity, declared, span);
                }
                self.walk_variance(decl_kind, return_type, polarity, declared, span);
            }
            TypeExpr::Applied { name, args } => {
                // Consult the declared variance of this constructor.
                // Built-in `Result` has covariant-covariant; user
                // generics carry their own variance annotations;
                // unknown constructors fall back to invariance (safe).
                let variances: Option<Vec<Variance>> = self
                    .scope
                    .get_enum(name)
                    .map(|info| info.type_params.iter().map(|tp| tp.variance).collect())
                    .or_else(|| {
                        self.scope
                            .get_struct(name)
                            .map(|info| info.type_params.iter().map(|tp| tp.variance).collect())
                    })
                    .or_else(|| {
                        self.scope
                            .get_interface(name)
                            .map(|info| info.type_params.iter().map(|tp| tp.variance).collect())
                    });
                for (idx, arg) in args.iter().enumerate() {
                    let child_variance = variances
                        .as_ref()
                        .and_then(|v| v.get(idx).copied())
                        .unwrap_or(Variance::Invariant);
                    let sub = polarity.compose(child_variance);
                    self.walk_variance(decl_kind, arg, sub, declared, span);
                }
            }
            TypeExpr::Never | TypeExpr::LitString(_) | TypeExpr::LitInt(_) => {}
        }
    }

    fn error_at(&mut self, message: String, span: Span) {
        self.diagnostics.push(TypeDiagnostic {
            message,
            severity: DiagnosticSeverity::Error,
            span: Some(span),
            help: None,
            fix: None,
        });
    }

    #[allow(dead_code)]
    fn error_at_with_help(&mut self, message: String, span: Span, help: String) {
        self.diagnostics.push(TypeDiagnostic {
            message,
            severity: DiagnosticSeverity::Error,
            span: Some(span),
            help: Some(help),
            fix: None,
        });
    }

    fn error_at_with_fix(&mut self, message: String, span: Span, fix: Vec<FixEdit>) {
        self.diagnostics.push(TypeDiagnostic {
            message,
            severity: DiagnosticSeverity::Error,
            span: Some(span),
            help: None,
            fix: Some(fix),
        });
    }

    fn warning_at(&mut self, message: String, span: Span) {
        self.diagnostics.push(TypeDiagnostic {
            message,
            severity: DiagnosticSeverity::Warning,
            span: Some(span),
            help: None,
            fix: None,
        });
    }

    #[allow(dead_code)]
    fn warning_at_with_help(&mut self, message: String, span: Span, help: String) {
        self.diagnostics.push(TypeDiagnostic {
            message,
            severity: DiagnosticSeverity::Warning,
            span: Some(span),
            help: Some(help),
            fix: None,
        });
    }

    /// Recursively validate binary operations in an expression tree.
    /// Unlike `check_node`, this only checks BinaryOp type compatibility
    /// without triggering other validations (e.g., function call arg checks).
    fn check_binops(&mut self, snode: &SNode, scope: &mut TypeScope) {
        match &snode.node {
            Node::BinaryOp { op, left, right } => {
                self.check_binops(left, scope);
                self.check_binops(right, scope);
                let lt = self.infer_type(left, scope);
                let rt = self.infer_type(right, scope);
                if let (Some(TypeExpr::Named(l)), Some(TypeExpr::Named(r))) = (&lt, &rt) {
                    let span = snode.span;
                    match op.as_str() {
                        "+" => {
                            let valid = matches!(
                                (l.as_str(), r.as_str()),
                                ("int" | "float", "int" | "float")
                                    | ("string", "string")
                                    | ("list", "list")
                                    | ("dict", "dict")
                            );
                            if !valid {
                                let msg = format!("can't add {} and {}", l, r);
                                let fix = if l == "string" || r == "string" {
                                    self.build_interpolation_fix(left, right, l == "string", span)
                                } else {
                                    None
                                };
                                if let Some(fix) = fix {
                                    self.error_at_with_fix(msg, span, fix);
                                } else {
                                    self.error_at(msg, span);
                                }
                            }
                        }
                        "-" | "/" | "%" | "**" => {
                            let numeric = ["int", "float"];
                            if !numeric.contains(&l.as_str()) || !numeric.contains(&r.as_str()) {
                                self.error_at(
                                    format!(
                                        "can't use '{}' on {} and {} (needs numeric operands)",
                                        op, l, r
                                    ),
                                    span,
                                );
                            }
                        }
                        "*" => {
                            let numeric = ["int", "float"];
                            let is_numeric =
                                numeric.contains(&l.as_str()) && numeric.contains(&r.as_str());
                            let is_string_repeat =
                                (l == "string" && r == "int") || (l == "int" && r == "string");
                            if !is_numeric && !is_string_repeat {
                                self.error_at(
                                    format!("can't multiply {} and {} (try string * int)", l, r),
                                    span,
                                );
                            }
                        }
                        _ => {}
                    }
                }
            }
            // Recurse into sub-expressions that might contain BinaryOps
            Node::UnaryOp { operand, .. } => self.check_binops(operand, scope),
            _ => {}
        }
    }

    /// Build a fix that converts `"str" + expr` or `expr + "str"` to string interpolation.
    fn build_interpolation_fix(
        &self,
        left: &SNode,
        right: &SNode,
        left_is_string: bool,
        expr_span: Span,
    ) -> Option<Vec<FixEdit>> {
        let src = self.source.as_ref()?;
        let (str_node, other_node) = if left_is_string {
            (left, right)
        } else {
            (right, left)
        };
        let str_text = src.get(str_node.span.start..str_node.span.end)?;
        let other_text = src.get(other_node.span.start..other_node.span.end)?;
        // Only handle simple double-quoted strings (not multiline/raw)
        let inner = str_text.strip_prefix('"')?.strip_suffix('"')?;
        // Skip if the expression contains characters that would break interpolation
        if other_text.contains('}') || other_text.contains('"') {
            return None;
        }
        let replacement = if left_is_string {
            format!("\"{inner}${{{other_text}}}\"")
        } else {
            format!("\"${{{other_text}}}{inner}\"")
        };
        Some(vec![FixEdit {
            span: expr_span,
            replacement,
        }])
    }
}

impl Default for TypeChecker {
    fn default() -> Self {
        Self::new()
    }
}

/// Infer the result type of a binary operation.
fn infer_binary_op_type(op: &str, left: &InferredType, right: &InferredType) -> InferredType {
    match op {
        "==" | "!=" | "<" | ">" | "<=" | ">=" | "&&" | "||" | "in" | "not_in" => {
            Some(TypeExpr::Named("bool".into()))
        }
        "+" => match (left, right) {
            (Some(TypeExpr::Named(l)), Some(TypeExpr::Named(r))) => {
                match (l.as_str(), r.as_str()) {
                    ("int", "int") => Some(TypeExpr::Named("int".into())),
                    ("float", _) | (_, "float") => Some(TypeExpr::Named("float".into())),
                    ("string", "string") => Some(TypeExpr::Named("string".into())),
                    ("list", "list") => Some(TypeExpr::Named("list".into())),
                    ("dict", "dict") => Some(TypeExpr::Named("dict".into())),
                    _ => None,
                }
            }
            _ => None,
        },
        "-" | "/" | "%" => match (left, right) {
            (Some(TypeExpr::Named(l)), Some(TypeExpr::Named(r))) => {
                match (l.as_str(), r.as_str()) {
                    ("int", "int") => Some(TypeExpr::Named("int".into())),
                    ("float", _) | (_, "float") => Some(TypeExpr::Named("float".into())),
                    _ => None,
                }
            }
            _ => None,
        },
        "**" => match (left, right) {
            (Some(TypeExpr::Named(l)), Some(TypeExpr::Named(r))) => {
                match (l.as_str(), r.as_str()) {
                    ("int", "int") => Some(TypeExpr::Named("int".into())),
                    ("float", _) | (_, "float") => Some(TypeExpr::Named("float".into())),
                    _ => None,
                }
            }
            _ => None,
        },
        "*" => match (left, right) {
            (Some(TypeExpr::Named(l)), Some(TypeExpr::Named(r))) => {
                match (l.as_str(), r.as_str()) {
                    ("string", "int") | ("int", "string") => Some(TypeExpr::Named("string".into())),
                    ("int", "int") => Some(TypeExpr::Named("int".into())),
                    ("float", _) | (_, "float") => Some(TypeExpr::Named("float".into())),
                    _ => None,
                }
            }
            _ => None,
        },
        "??" => match (left, right) {
            // Union containing nil: strip nil, use non-nil members
            (Some(TypeExpr::Union(members)), _) => {
                let non_nil: Vec<_> = members
                    .iter()
                    .filter(|m| !matches!(m, TypeExpr::Named(n) if n == "nil"))
                    .cloned()
                    .collect();
                if non_nil.len() == 1 {
                    Some(non_nil[0].clone())
                } else if non_nil.is_empty() {
                    right.clone()
                } else {
                    Some(TypeExpr::Union(non_nil))
                }
            }
            // Left is nil: result is always the right side
            (Some(TypeExpr::Named(n)), _) if n == "nil" => right.clone(),
            // Left is a known non-nil type: right is unreachable, preserve left
            (Some(l), _) => Some(l.clone()),
            // Unknown left: use right as best guess
            (None, _) => right.clone(),
        },
        "|>" => None,
        _ => None,
    }
}

/// Format a type expression for display in error messages.
/// Produce a detail string describing why a Shape type is incompatible with
/// another Shape type — e.g. "missing field 'age' (int)" or "field 'name'
/// has type int, expected string".  Returns `None` if both types are not shapes.
pub fn shape_mismatch_detail(expected: &TypeExpr, actual: &TypeExpr) -> Option<String> {
    if let (TypeExpr::Shape(ef), TypeExpr::Shape(af)) = (expected, actual) {
        let mut details = Vec::new();
        for field in ef {
            if field.optional {
                continue;
            }
            match af.iter().find(|f| f.name == field.name) {
                None => details.push(format!(
                    "missing field '{}' ({})",
                    field.name,
                    format_type(&field.type_expr)
                )),
                Some(actual_field) => {
                    let e_str = format_type(&field.type_expr);
                    let a_str = format_type(&actual_field.type_expr);
                    if e_str != a_str {
                        details.push(format!(
                            "field '{}' has type {}, expected {}",
                            field.name, a_str, e_str
                        ));
                    }
                }
            }
        }
        if details.is_empty() {
            None
        } else {
            Some(details.join("; "))
        }
    } else {
        None
    }
}

/// Returns true when the type is obvious from the RHS expression
/// (e.g. `let x = 42` is obviously int — no hint needed).
fn is_obvious_type(value: &SNode, _ty: &TypeExpr) -> bool {
    matches!(
        &value.node,
        Node::IntLiteral(_)
            | Node::FloatLiteral(_)
            | Node::StringLiteral(_)
            | Node::BoolLiteral(_)
            | Node::NilLiteral
            | Node::ListLiteral(_)
            | Node::DictLiteral(_)
            | Node::InterpolatedString(_)
    )
}

/// Check whether a single statement definitely exits (return/throw/break/continue
/// or an if/else where both branches exit).
pub fn stmt_definitely_exits(stmt: &SNode) -> bool {
    match &stmt.node {
        Node::ReturnStmt { .. } | Node::ThrowStmt { .. } | Node::BreakStmt | Node::ContinueStmt => {
            true
        }
        Node::IfElse {
            then_body,
            else_body: Some(else_body),
            ..
        } => block_definitely_exits(then_body) && block_definitely_exits(else_body),
        _ => false,
    }
}

/// Check whether a block definitely exits (contains a terminating statement).
pub fn block_definitely_exits(stmts: &[SNode]) -> bool {
    stmts.iter().any(stmt_definitely_exits)
}

pub fn format_type(ty: &TypeExpr) -> String {
    match ty {
        TypeExpr::Named(n) => n.clone(),
        TypeExpr::Union(types) => types
            .iter()
            .map(format_type)
            .collect::<Vec<_>>()
            .join(" | "),
        TypeExpr::Shape(fields) => {
            let inner: Vec<String> = fields
                .iter()
                .map(|f| {
                    let opt = if f.optional { "?" } else { "" };
                    format!("{}{opt}: {}", f.name, format_type(&f.type_expr))
                })
                .collect();
            format!("{{{}}}", inner.join(", "))
        }
        TypeExpr::List(inner) => format!("list<{}>", format_type(inner)),
        TypeExpr::Iter(inner) => format!("iter<{}>", format_type(inner)),
        TypeExpr::DictType(k, v) => format!("dict<{}, {}>", format_type(k), format_type(v)),
        TypeExpr::Applied { name, args } => {
            let args_str = args.iter().map(format_type).collect::<Vec<_>>().join(", ");
            format!("{name}<{args_str}>")
        }
        TypeExpr::FnType {
            params,
            return_type,
        } => {
            let params_str = params
                .iter()
                .map(format_type)
                .collect::<Vec<_>>()
                .join(", ");
            format!("fn({}) -> {}", params_str, format_type(return_type))
        }
        TypeExpr::Never => "never".to_string(),
        TypeExpr::LitString(s) => format!("\"{}\"", s.replace('\\', "\\\\").replace('"', "\\\"")),
        TypeExpr::LitInt(v) => v.to_string(),
    }
}

/// Simplify a union by removing `Never` members and collapsing.
fn simplify_union(members: Vec<TypeExpr>) -> TypeExpr {
    let filtered: Vec<TypeExpr> = members
        .into_iter()
        .filter(|m| !matches!(m, TypeExpr::Never))
        .collect();
    match filtered.len() {
        0 => TypeExpr::Never,
        1 => filtered.into_iter().next().unwrap(),
        _ => TypeExpr::Union(filtered),
    }
}

/// Remove a named type from a union, collapsing single-element unions.
/// Returns `Some(Never)` when all members are removed (exhausted).
fn remove_from_union(members: &[TypeExpr], to_remove: &str) -> InferredType {
    let remaining: Vec<TypeExpr> = members
        .iter()
        .filter(|m| !matches!(m, TypeExpr::Named(n) if n == to_remove))
        .cloned()
        .collect();
    match remaining.len() {
        0 => Some(TypeExpr::Never),
        1 => Some(remaining.into_iter().next().unwrap()),
        _ => Some(TypeExpr::Union(remaining)),
    }
}

/// Narrow a union to just one named type, if that type is a member.
fn narrow_to_single(members: &[TypeExpr], target: &str) -> InferredType {
    if members
        .iter()
        .any(|m| matches!(m, TypeExpr::Named(n) if n == target))
    {
        Some(TypeExpr::Named(target.to_string()))
    } else {
        None
    }
}

/// Extract the variable name from a `type_of(x)` call.
fn extract_type_of_var(node: &SNode) -> Option<String> {
    if let Node::FunctionCall { name, args } = &node.node {
        if name == "type_of" && args.len() == 1 {
            if let Node::Identifier(var) = &args[0].node {
                return Some(var.clone());
            }
        }
    }
    None
}

fn schema_type_expr_from_node(node: &SNode, scope: &TypeScope) -> Option<TypeExpr> {
    match &node.node {
        Node::Identifier(name) => {
            // Prefer schema bindings (runtime dicts), then fall back to a
            // declared `type` alias with the same name. This powers
            // `schema_is(x, T)` / `schema_expect(x, T)` narrowing when `T`
            // is a type alias rather than a schema-dict binding.
            if let Some(schema) = scope.get_schema_binding(name).cloned().flatten() {
                return Some(schema);
            }
            scope.resolve_type(name).cloned()
        }
        Node::DictLiteral(entries) => schema_type_expr_from_dict(entries, scope),
        // `schema_of(T)` is a runtime function that returns the JSON-Schema
        // dict for a type alias. When its result is passed into a position
        // typed `Schema<T>`, we resolve the underlying alias to its
        // TypeExpr so the generic binding can extract `T`.
        Node::FunctionCall { name, args } if name == "schema_of" && args.len() == 1 => {
            if let Node::Identifier(alias) = &args[0].node {
                return scope.resolve_type(alias).cloned();
            }
            None
        }
        _ => None,
    }
}

fn schema_type_expr_from_dict(entries: &[DictEntry], scope: &TypeScope) -> Option<TypeExpr> {
    let mut type_name: Option<String> = None;
    let mut properties: Option<&SNode> = None;
    let mut required: Option<Vec<String>> = None;
    let mut items: Option<&SNode> = None;
    let mut union: Option<&SNode> = None;
    let mut nullable = false;
    let mut additional_properties: Option<&SNode> = None;

    for entry in entries {
        let key = schema_entry_key(&entry.key)?;
        match key.as_str() {
            "type" => match &entry.value.node {
                Node::StringLiteral(text) | Node::RawStringLiteral(text) => {
                    type_name = Some(normalize_schema_type_name(text));
                }
                Node::ListLiteral(items_list) => {
                    let union_members = items_list
                        .iter()
                        .filter_map(|item| match &item.node {
                            Node::StringLiteral(text) | Node::RawStringLiteral(text) => {
                                Some(TypeExpr::Named(normalize_schema_type_name(text)))
                            }
                            _ => None,
                        })
                        .collect::<Vec<_>>();
                    if !union_members.is_empty() {
                        return Some(TypeExpr::Union(union_members));
                    }
                }
                _ => {}
            },
            "properties" => properties = Some(&entry.value),
            "required" => {
                required = schema_required_names(&entry.value);
            }
            "items" => items = Some(&entry.value),
            "union" | "oneOf" | "anyOf" => union = Some(&entry.value),
            "nullable" => {
                nullable = matches!(entry.value.node, Node::BoolLiteral(true));
            }
            "additional_properties" | "additionalProperties" => {
                additional_properties = Some(&entry.value);
            }
            _ => {}
        }
    }

    let mut schema_type = if let Some(union_node) = union {
        schema_union_type_expr(union_node, scope)?
    } else if let Some(properties_node) = properties {
        let property_entries = match &properties_node.node {
            Node::DictLiteral(entries) => entries,
            _ => return None,
        };
        let required_names = required.unwrap_or_default();
        let mut fields = Vec::new();
        for entry in property_entries {
            let field_name = schema_entry_key(&entry.key)?;
            let field_type = schema_type_expr_from_node(&entry.value, scope)?;
            fields.push(ShapeField {
                name: field_name.clone(),
                type_expr: field_type,
                optional: !required_names.contains(&field_name),
            });
        }
        TypeExpr::Shape(fields)
    } else if let Some(item_node) = items {
        TypeExpr::List(Box::new(schema_type_expr_from_node(item_node, scope)?))
    } else if let Some(type_name) = type_name {
        if type_name == "dict" {
            if let Some(extra_node) = additional_properties {
                let value_type = match &extra_node.node {
                    Node::BoolLiteral(_) => None,
                    _ => schema_type_expr_from_node(extra_node, scope),
                };
                if let Some(value_type) = value_type {
                    TypeExpr::DictType(
                        Box::new(TypeExpr::Named("string".into())),
                        Box::new(value_type),
                    )
                } else {
                    TypeExpr::Named(type_name)
                }
            } else {
                TypeExpr::Named(type_name)
            }
        } else {
            TypeExpr::Named(type_name)
        }
    } else {
        return None;
    };

    if nullable {
        schema_type = match schema_type {
            TypeExpr::Union(mut members) => {
                if !members
                    .iter()
                    .any(|member| matches!(member, TypeExpr::Named(name) if name == "nil"))
                {
                    members.push(TypeExpr::Named("nil".into()));
                }
                TypeExpr::Union(members)
            }
            other => TypeExpr::Union(vec![other, TypeExpr::Named("nil".into())]),
        };
    }

    Some(schema_type)
}

fn schema_union_type_expr(node: &SNode, scope: &TypeScope) -> Option<TypeExpr> {
    let Node::ListLiteral(items) = &node.node else {
        return None;
    };
    let members = items
        .iter()
        .filter_map(|item| schema_type_expr_from_node(item, scope))
        .collect::<Vec<_>>();
    match members.len() {
        0 => None,
        1 => members.into_iter().next(),
        _ => Some(TypeExpr::Union(members)),
    }
}

fn schema_required_names(node: &SNode) -> Option<Vec<String>> {
    let Node::ListLiteral(items) = &node.node else {
        return None;
    };
    Some(
        items
            .iter()
            .filter_map(|item| match &item.node {
                Node::StringLiteral(text) | Node::RawStringLiteral(text) => Some(text.clone()),
                Node::Identifier(text) => Some(text.clone()),
                _ => None,
            })
            .collect(),
    )
}

fn schema_entry_key(node: &SNode) -> Option<String> {
    match &node.node {
        Node::Identifier(name) => Some(name.clone()),
        Node::StringLiteral(name) | Node::RawStringLiteral(name) => Some(name.clone()),
        _ => None,
    }
}

fn normalize_schema_type_name(text: &str) -> String {
    match text {
        "object" => "dict".into(),
        "array" => "list".into(),
        "integer" => "int".into(),
        "number" => "float".into(),
        "boolean" => "bool".into(),
        "null" => "nil".into(),
        other => other.into(),
    }
}

fn intersect_types(current: &TypeExpr, schema_type: &TypeExpr) -> Option<TypeExpr> {
    match (current, schema_type) {
        // Literal intersections: two equal literals keep the literal.
        (TypeExpr::LitString(a), TypeExpr::LitString(b)) if a == b => {
            Some(TypeExpr::LitString(a.clone()))
        }
        (TypeExpr::LitInt(a), TypeExpr::LitInt(b)) if a == b => Some(TypeExpr::LitInt(*a)),
        // Intersecting a literal with its base type keeps the literal.
        (TypeExpr::LitString(s), TypeExpr::Named(n))
        | (TypeExpr::Named(n), TypeExpr::LitString(s))
            if n == "string" =>
        {
            Some(TypeExpr::LitString(s.clone()))
        }
        (TypeExpr::LitInt(v), TypeExpr::Named(n)) | (TypeExpr::Named(n), TypeExpr::LitInt(v))
            if n == "int" || n == "float" =>
        {
            Some(TypeExpr::LitInt(*v))
        }
        (TypeExpr::Union(members), other) => {
            let kept = members
                .iter()
                .filter_map(|member| intersect_types(member, other))
                .collect::<Vec<_>>();
            match kept.len() {
                0 => None,
                1 => kept.into_iter().next(),
                _ => Some(TypeExpr::Union(kept)),
            }
        }
        (other, TypeExpr::Union(members)) => {
            let kept = members
                .iter()
                .filter_map(|member| intersect_types(other, member))
                .collect::<Vec<_>>();
            match kept.len() {
                0 => None,
                1 => kept.into_iter().next(),
                _ => Some(TypeExpr::Union(kept)),
            }
        }
        (TypeExpr::Named(left), TypeExpr::Named(right)) if left == right => {
            Some(TypeExpr::Named(left.clone()))
        }
        (TypeExpr::Named(name), TypeExpr::Shape(fields)) if name == "dict" => {
            Some(TypeExpr::Shape(fields.clone()))
        }
        (TypeExpr::Shape(fields), TypeExpr::Named(name)) if name == "dict" => {
            Some(TypeExpr::Shape(fields.clone()))
        }
        (TypeExpr::Named(name), TypeExpr::List(inner)) if name == "list" => {
            Some(TypeExpr::List(inner.clone()))
        }
        (TypeExpr::List(inner), TypeExpr::Named(name)) if name == "list" => {
            Some(TypeExpr::List(inner.clone()))
        }
        (TypeExpr::Named(name), TypeExpr::DictType(key, value)) if name == "dict" => {
            Some(TypeExpr::DictType(key.clone(), value.clone()))
        }
        (TypeExpr::DictType(key, value), TypeExpr::Named(name)) if name == "dict" => {
            Some(TypeExpr::DictType(key.clone(), value.clone()))
        }
        (TypeExpr::Shape(_), TypeExpr::Shape(fields)) => Some(TypeExpr::Shape(fields.clone())),
        (TypeExpr::List(current_inner), TypeExpr::List(schema_inner)) => {
            intersect_types(current_inner, schema_inner)
                .map(|inner| TypeExpr::List(Box::new(inner)))
        }
        (
            TypeExpr::DictType(current_key, current_value),
            TypeExpr::DictType(schema_key, schema_value),
        ) => {
            let key = intersect_types(current_key, schema_key)?;
            let value = intersect_types(current_value, schema_value)?;
            Some(TypeExpr::DictType(Box::new(key), Box::new(value)))
        }
        _ => None,
    }
}

fn subtract_type(current: &TypeExpr, schema_type: &TypeExpr) -> Option<TypeExpr> {
    match current {
        TypeExpr::Union(members) => {
            let remaining = members
                .iter()
                .filter(|member| intersect_types(member, schema_type).is_none())
                .cloned()
                .collect::<Vec<_>>();
            match remaining.len() {
                0 => None,
                1 => remaining.into_iter().next(),
                _ => Some(TypeExpr::Union(remaining)),
            }
        }
        other if intersect_types(other, schema_type).is_some() => None,
        other => Some(other.clone()),
    }
}

/// Apply a list of refinements to a scope, tracking pre-narrowing types.
fn apply_refinements(scope: &mut TypeScope, refinements: &[(String, InferredType)]) {
    for (var_name, narrowed_type) in refinements {
        // Save the pre-narrowing type so we can restore it on reassignment
        if !scope.narrowed_vars.contains_key(var_name) {
            if let Some(original) = scope.get_var(var_name).cloned() {
                scope.narrowed_vars.insert(var_name.clone(), original);
            }
        }
        scope.define_var(var_name, narrowed_type.clone());
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::Parser;
    use harn_lexer::Lexer;

    fn check_source(source: &str) -> Vec<TypeDiagnostic> {
        let mut lexer = Lexer::new(source);
        let tokens = lexer.tokenize().unwrap();
        let mut parser = Parser::new(tokens);
        let program = parser.parse().unwrap();
        TypeChecker::new().check(&program)
    }

    fn errors(source: &str) -> Vec<String> {
        check_source(source)
            .into_iter()
            .filter(|d| d.severity == DiagnosticSeverity::Error)
            .map(|d| d.message)
            .collect()
    }

    #[test]
    fn test_no_errors_for_untyped_code() {
        let errs = errors("pipeline t(task) { let x = 42\nlog(x) }");
        assert!(errs.is_empty());
    }

    #[test]
    fn test_correct_typed_let() {
        let errs = errors("pipeline t(task) { let x: int = 42 }");
        assert!(errs.is_empty());
    }

    #[test]
    fn test_type_mismatch_let() {
        let errs = errors(r#"pipeline t(task) { let x: int = "hello" }"#);
        assert_eq!(errs.len(), 1);
        assert!(errs[0].contains("declared as int"));
        assert!(errs[0].contains("assigned string"));
    }

    #[test]
    fn test_correct_typed_fn() {
        let errs = errors(
            "pipeline t(task) { fn add(a: int, b: int) -> int { return a + b }\nadd(1, 2) }",
        );
        assert!(errs.is_empty());
    }

    #[test]
    fn test_fn_arg_type_mismatch() {
        let errs = errors(
            r#"pipeline t(task) { fn add(a: int, b: int) -> int { return a + b }
add("hello", 2) }"#,
        );
        assert_eq!(errs.len(), 1);
        assert!(errs[0].contains("Argument 1"));
        assert!(errs[0].contains("expected int"));
    }

    #[test]
    fn test_return_type_mismatch() {
        let errs = errors(r#"pipeline t(task) { fn get() -> int { return "hello" } }"#);
        assert_eq!(errs.len(), 1);
        assert!(errs[0].contains("return type doesn't match"));
    }

    #[test]
    fn test_union_type_compatible() {
        let errs = errors(r#"pipeline t(task) { let x: string | nil = nil }"#);
        assert!(errs.is_empty());
    }

    #[test]
    fn test_union_type_mismatch() {
        let errs = errors(r#"pipeline t(task) { let x: string | nil = 42 }"#);
        assert_eq!(errs.len(), 1);
        assert!(errs[0].contains("declared as"));
    }

    #[test]
    fn test_type_inference_propagation() {
        let errs = errors(
            r#"pipeline t(task) {
  fn add(a: int, b: int) -> int { return a + b }
  let result: string = add(1, 2)
}"#,
        );
        assert_eq!(errs.len(), 1);
        assert!(errs[0].contains("declared as"));
        assert!(errs[0].contains("string"));
        assert!(errs[0].contains("int"));
    }

    #[test]
    fn test_generic_return_type_instantiates_from_callsite() {
        let errs = errors(
            r#"pipeline t(task) {
  fn identity<T>(x: T) -> T { return x }
  fn first<T>(items: list<T>) -> T { return items[0] }
  let n: int = identity(42)
  let s: string = first(["a", "b"])
}"#,
        );
        assert!(errs.is_empty(), "unexpected type errors: {errs:?}");
    }

    #[test]
    fn test_generic_type_param_must_bind_consistently() {
        let errs = errors(
            r#"pipeline t(task) {
  fn keep<T>(a: T, b: T) -> T { return a }
  keep(1, "x")
}"#,
        );
        assert_eq!(errs.len(), 2, "expected 2 errors, got: {:?}", errs);
        assert!(
            errs.iter()
                .any(|err| err.contains("type parameter 'T' was inferred as both int and string")),
            "missing generic binding conflict error: {:?}",
            errs
        );
        assert!(
            errs.iter()
                .any(|err| err.contains("Argument 2 ('b'): expected int, got string")),
            "missing instantiated argument mismatch error: {:?}",
            errs
        );
    }

    #[test]
    fn test_generic_list_binding_propagates_element_type() {
        let errs = errors(
            r#"pipeline t(task) {
  fn first<T>(items: list<T>) -> T { return items[0] }
  let bad: string = first([1, 2, 3])
}"#,
        );
        assert_eq!(errs.len(), 1, "expected 1 error, got: {:?}", errs);
        assert!(errs[0].contains("declared as string, but assigned int"));
    }

    #[test]
    fn test_generic_struct_literal_instantiates_type_arguments() {
        let errs = errors(
            r#"pipeline t(task) {
  struct Pair<A, B> {
    first: A
    second: B
  }
  let pair: Pair<int, string> = Pair { first: 1, second: "two" }
}"#,
        );
        assert!(errs.is_empty(), "unexpected type errors: {errs:?}");
    }

    #[test]
    fn test_generic_enum_construct_instantiates_type_arguments() {
        let errs = errors(
            r#"pipeline t(task) {
  enum Option<T> {
    Some(value: T),
    None
  }
  let value: Option<int> = Option.Some(42)
}"#,
        );
        assert!(errs.is_empty(), "unexpected type errors: {errs:?}");
    }

    #[test]
    fn test_result_generic_type_compatibility() {
        let errs = errors(
            r#"pipeline t(task) {
  let ok: Result<int, string> = Result.Ok(42)
  let err: Result<int, string> = Result.Err("oops")
}"#,
        );
        assert!(errs.is_empty(), "unexpected type errors: {errs:?}");
    }

    #[test]
    fn test_result_generic_type_mismatch_reports_error() {
        let errs = errors(
            r#"pipeline t(task) {
  let bad: Result<int, string> = Result.Err(42)
}"#,
        );
        assert_eq!(errs.len(), 1, "expected 1 error, got: {errs:?}");
        assert!(errs[0].contains("Result<int, string>"));
        assert!(errs[0].contains("Result<_, int>"));
    }

    #[test]
    fn test_builtin_return_type_inference() {
        let errs = errors(r#"pipeline t(task) { let x: string = to_int("42") }"#);
        assert_eq!(errs.len(), 1);
        assert!(errs[0].contains("string"));
        assert!(errs[0].contains("int"));
    }

    #[test]
    fn test_workflow_and_transcript_builtins_are_known() {
        let errs = errors(
            r#"pipeline t(task) {
  let flow = workflow_graph({name: "demo", entry: "act", nodes: {act: {kind: "stage"}}})
  let report: dict = workflow_policy_report(flow, {tools: tool_registry(), capabilities: {workspace: ["read_text"]}})
  let run: dict = workflow_execute("task", flow, [], {})
  let tree: dict = load_run_tree("run.json")
  let fixture: dict = run_record_fixture(run?.run)
  let suite: dict = run_record_eval_suite([{run: run?.run, fixture: fixture}])
  let diff: dict = run_record_diff(run?.run, run?.run)
  let manifest: dict = eval_suite_manifest({cases: [{run_path: "run.json"}]})
  let suite_report: dict = eval_suite_run(manifest)
  let wf: dict = artifact_workspace_file("src/main.rs", "fn main() {}", {source: "host"})
  let snap: dict = artifact_workspace_snapshot(["src/main.rs"], "snapshot")
  let selection: dict = artifact_editor_selection("src/main.rs", "main")
  let verify: dict = artifact_verification_result("verify", "ok")
  let test_result: dict = artifact_test_result("tests", "pass")
  let cmd: dict = artifact_command_result("cargo test", {status: 0})
  let patch: dict = artifact_diff("src/main.rs", "old", "new")
  let git: dict = artifact_git_diff("diff --git a b")
  let review: dict = artifact_diff_review(patch, "review me")
  let decision: dict = artifact_review_decision(review, "accepted")
  let proposal: dict = artifact_patch_proposal(review, "*** Begin Patch")
  let bundle: dict = artifact_verification_bundle("checks", [{name: "fmt", ok: true}])
  let apply: dict = artifact_apply_intent(review, "apply")
  let transcript = transcript_reset({metadata: {source: "test"}})
  let visible: string = transcript_render_visible(transcript_archive(transcript))
  let events: list = transcript_events(transcript)
  let context: string = artifact_context([], {max_artifacts: 1})
  println(report)
  println(run)
  println(tree)
  println(fixture)
  println(suite)
  println(diff)
  println(manifest)
  println(suite_report)
  println(wf)
  println(snap)
  println(selection)
  println(verify)
  println(test_result)
  println(cmd)
  println(patch)
  println(git)
  println(review)
  println(decision)
  println(proposal)
  println(bundle)
  println(apply)
  println(visible)
  println(events)
  println(context)
}"#,
        );
        assert!(errs.is_empty(), "unexpected type errors: {errs:?}");
    }

    #[test]
    fn test_binary_op_type_inference() {
        let errs = errors("pipeline t(task) { let x: string = 1 + 2 }");
        assert_eq!(errs.len(), 1);
    }

    #[test]
    fn test_exponentiation_requires_numeric_operands() {
        let errs = errors(r#"pipeline t(task) { let x = "nope" ** 2 }"#);
        assert!(
            errs.iter().any(|err| err.contains("can't use '**'")),
            "missing exponentiation type error: {errs:?}"
        );
    }

    #[test]
    fn test_comparison_returns_bool() {
        let errs = errors("pipeline t(task) { let x: bool = 1 < 2 }");
        assert!(errs.is_empty());
    }

    #[test]
    fn test_int_float_promotion() {
        let errs = errors("pipeline t(task) { let x: float = 42 }");
        assert!(errs.is_empty());
    }

    #[test]
    fn test_untyped_code_no_errors() {
        let errs = errors(
            r#"pipeline t(task) {
  fn process(data) {
    let result = data + " processed"
    return result
  }
  log(process("hello"))
}"#,
        );
        assert!(errs.is_empty());
    }

    #[test]
    fn test_type_alias() {
        let errs = errors(
            r#"pipeline t(task) {
  type Name = string
  let x: Name = "hello"
}"#,
        );
        assert!(errs.is_empty());
    }

    #[test]
    fn test_type_alias_mismatch() {
        let errs = errors(
            r#"pipeline t(task) {
  type Name = string
  let x: Name = 42
}"#,
        );
        assert_eq!(errs.len(), 1);
    }

    #[test]
    fn test_assignment_type_check() {
        let errs = errors(
            r#"pipeline t(task) {
  var x: int = 0
  x = "hello"
}"#,
        );
        assert_eq!(errs.len(), 1);
        assert!(errs[0].contains("can't assign string"));
    }

    #[test]
    fn test_covariance_int_to_float_in_fn() {
        let errs = errors(
            "pipeline t(task) { fn scale(x: float) -> float { return x * 2.0 }\nscale(42) }",
        );
        assert!(errs.is_empty());
    }

    #[test]
    fn test_covariance_return_type() {
        let errs = errors("pipeline t(task) { fn get() -> float { return 42 } }");
        assert!(errs.is_empty());
    }

    #[test]
    fn test_no_contravariance_float_to_int() {
        let errs = errors("pipeline t(task) { fn add(a: int) -> int { return a + 1 }\nadd(3.14) }");
        assert_eq!(errs.len(), 1);
    }

    // --- Comprehensive variance (issue #34) --------------------------------

    #[test]
    fn test_fn_param_contravariance_positive() {
        // A closure that accepts a float (a supertype of int) can
        // stand in for an expected `fn(int) -> int`: anything the
        // caller hands in (an int) the closure can still accept.
        let errs = errors(
            r#"pipeline t(task) {
                let wide = fn(x: float) { return 0 }
                let cb: fn(int) -> int = wide
            }"#,
        );
        assert!(
            errs.is_empty(),
            "expected fn(float)->int to satisfy fn(int)->int, got: {errs:?}"
        );
    }

    #[test]
    fn test_fn_param_contravariance_negative() {
        // A closure that only accepts ints cannot stand in for an
        // expected `fn(float) -> int`: the caller may hand it a
        // float, which it is not prepared to receive.
        let errs = errors(
            r#"pipeline t(task) {
                let narrow = fn(x: int) { return 0 }
                let cb: fn(float) -> int = narrow
            }"#,
        );
        assert!(
            !errs.is_empty(),
            "expected fn(int)->int NOT to satisfy fn(float)->int, but type-check passed"
        );
    }

    #[test]
    fn test_list_invariant_int_to_float_rejected() {
        // `list<int>` must not flow into `list<float>` — lists are
        // mutable, so a covariant assignment is unsound.
        let errs = errors(
            r#"pipeline t(task) {
                let xs: list<int> = [1, 2, 3]
                let ys: list<float> = xs
            }"#,
        );
        assert!(
            !errs.is_empty(),
            "expected list<int> NOT to flow into list<float>, but type-check passed"
        );
    }

    #[test]
    fn test_iter_covariant_int_to_float_accepted() {
        // Iterators are read-only, so element-type widening is sound.
        let errs = errors(
            r#"pipeline t(task) {
                fn sink(ys: iter<float>) -> int { return 0 }
                fn pipe(xs: iter<int>) -> int { return sink(xs) }
            }"#,
        );
        assert!(
            errs.is_empty(),
            "expected iter<int> to flow into iter<float>, got: {errs:?}"
        );
    }

    #[test]
    fn test_decl_site_out_used_in_contravariant_position_rejected() {
        // `type Box<out T> = fn(T) -> ()` — T is declared covariant
        // but appears only as an input (contravariant). Must be
        // rejected at declaration time.
        let errs = errors(
            r#"pipeline t(task) {
                type Box<out T> = fn(T) -> int
            }"#,
        );
        assert!(
            errs.iter().any(|e| e.contains("declared 'out'")),
            "expected 'out T' misuse diagnostic, got: {errs:?}"
        );
    }

    #[test]
    fn test_decl_site_in_used_in_covariant_position_rejected() {
        // `interface Producer<in T> { fn next() -> T }` — T is declared
        // contravariant but appears only in output position.
        let errs = errors(
            r#"pipeline t(task) {
                interface Producer<in T> { fn next() -> T }
            }"#,
        );
        assert!(
            errs.iter().any(|e| e.contains("declared 'in'")),
            "expected 'in T' misuse diagnostic, got: {errs:?}"
        );
    }

    #[test]
    fn test_decl_site_out_in_covariant_position_ok() {
        // `type Reader<out T> = fn() -> T` — T appears in a covariant
        // position, consistent with `out T`.
        let errs = errors(
            r#"pipeline t(task) {
                type Reader<out T> = fn() -> T
            }"#,
        );
        assert!(
            errs.iter().all(|e| !e.contains("declared 'out'")),
            "unexpected variance diagnostic: {errs:?}"
        );
    }

    #[test]
    fn test_dict_invariant_int_to_float_rejected() {
        let errs = errors(
            r#"pipeline t(task) {
                let d: dict<string, int> = {"a": 1}
                let e: dict<string, float> = d
            }"#,
        );
        assert!(
            !errs.is_empty(),
            "expected dict<string, int> NOT to flow into dict<string, float>"
        );
    }

    fn warnings(source: &str) -> Vec<String> {
        check_source(source)
            .into_iter()
            .filter(|d| d.severity == DiagnosticSeverity::Warning)
            .map(|d| d.message)
            .collect()
    }

    #[test]
    fn test_exhaustive_match_no_warning() {
        let warns = warnings(
            r#"pipeline t(task) {
  enum Color { Red, Green, Blue }
  let c = Color.Red
  match c.variant {
    "Red" -> { log("r") }
    "Green" -> { log("g") }
    "Blue" -> { log("b") }
  }
}"#,
        );
        let exhaustive_warns: Vec<_> = warns
            .iter()
            .filter(|w| w.contains("Non-exhaustive"))
            .collect();
        assert!(exhaustive_warns.is_empty());
    }

    #[test]
    fn test_non_exhaustive_match_warning() {
        let warns = warnings(
            r#"pipeline t(task) {
  enum Color { Red, Green, Blue }
  let c = Color.Red
  match c.variant {
    "Red" -> { log("r") }
    "Green" -> { log("g") }
  }
}"#,
        );
        let exhaustive_warns: Vec<_> = warns
            .iter()
            .filter(|w| w.contains("Non-exhaustive"))
            .collect();
        assert_eq!(exhaustive_warns.len(), 1);
        assert!(exhaustive_warns[0].contains("Blue"));
    }

    #[test]
    fn test_non_exhaustive_multiple_missing() {
        let warns = warnings(
            r#"pipeline t(task) {
  enum Status { Active, Inactive, Pending }
  let s = Status.Active
  match s.variant {
    "Active" -> { log("a") }
  }
}"#,
        );
        let exhaustive_warns: Vec<_> = warns
            .iter()
            .filter(|w| w.contains("Non-exhaustive"))
            .collect();
        assert_eq!(exhaustive_warns.len(), 1);
        assert!(exhaustive_warns[0].contains("Inactive"));
        assert!(exhaustive_warns[0].contains("Pending"));
    }

    fn exhaustive_warns(source: &str) -> Vec<String> {
        warnings(source)
            .into_iter()
            .filter(|w| w.contains("was not fully narrowed"))
            .collect()
    }

    #[test]
    fn test_unknown_exhaustive_unreachable_happy_path() {
        // All eight concrete variants covered → no warning on unreachable().
        let source = r#"pipeline t(task) {
  fn describe(v: unknown) -> string {
    if type_of(v) == "string"  { return "s" }
    if type_of(v) == "int"     { return "i" }
    if type_of(v) == "float"   { return "f" }
    if type_of(v) == "bool"    { return "b" }
    if type_of(v) == "nil"     { return "n" }
    if type_of(v) == "list"    { return "l" }
    if type_of(v) == "dict"    { return "d" }
    if type_of(v) == "closure" { return "c" }
    unreachable("unknown type_of variant")
  }
  log(describe(1))
}"#;
        assert!(exhaustive_warns(source).is_empty());
    }

    #[test]
    fn test_unknown_exhaustive_unreachable_incomplete_warns() {
        let source = r#"pipeline t(task) {
  fn describe(v: unknown) -> string {
    if type_of(v) == "string" { return "s" }
    if type_of(v) == "int"    { return "i" }
    unreachable("unknown type_of variant")
  }
  log(describe(1))
}"#;
        let warns = exhaustive_warns(source);
        assert_eq!(warns.len(), 1, "expected one warning, got: {:?}", warns);
        let w = &warns[0];
        for missing in &["float", "bool", "nil", "list", "dict", "closure"] {
            assert!(w.contains(missing), "missing {missing} in: {w}");
        }
        assert!(!w.contains("int"));
        assert!(!w.contains("string"));
        assert!(w.contains("unreachable"));
        assert!(w.contains("v: unknown"));
    }

    #[test]
    fn test_unknown_incomplete_normal_return_no_warning() {
        // Normal `return` fallthrough is NOT an exhaustiveness claim.
        let source = r#"pipeline t(task) {
  fn describe(v: unknown) -> string {
    if type_of(v) == "string" { return "s" }
    if type_of(v) == "int"    { return "i" }
    return "other"
  }
  log(describe(1))
}"#;
        assert!(exhaustive_warns(source).is_empty());
    }

    #[test]
    fn test_unknown_exhaustive_throw_incomplete_warns() {
        let source = r#"pipeline t(task) {
  fn describe(v: unknown) -> string {
    if type_of(v) == "string" { return "s" }
    throw "unhandled"
  }
  log(describe("x"))
}"#;
        let warns = exhaustive_warns(source);
        assert_eq!(warns.len(), 1, "expected one warning, got: {:?}", warns);
        assert!(warns[0].contains("throw"));
        assert!(warns[0].contains("int"));
    }

    #[test]
    fn test_unknown_throw_without_narrowing_no_warning() {
        // A bare throw with no preceding `type_of` narrowing is not
        // an exhaustiveness claim — stay silent.
        let source = r#"pipeline t(task) {
  fn crash(v: unknown) -> string {
    throw "nope"
  }
  log(crash(1))
}"#;
        assert!(exhaustive_warns(source).is_empty());
    }

    #[test]
    fn test_unknown_exhaustive_nested_branch() {
        // Nested if inside a single branch: inner exhaustiveness doesn't
        // escape to the outer scope, and incomplete outer coverage warns.
        let source = r#"pipeline t(task) {
  fn describe(v: unknown, x: int) -> string {
    if type_of(v) == "string" {
      if x > 0 { return v.upper() } else { return "s" }
    }
    if type_of(v) == "int" { return "i" }
    unreachable("unknown type_of variant")
  }
  log(describe(1, 1))
}"#;
        let warns = exhaustive_warns(source);
        assert_eq!(warns.len(), 1, "expected one warning, got: {:?}", warns);
        assert!(warns[0].contains("float"));
    }

    #[test]
    fn test_unknown_exhaustive_negated_check() {
        // `type_of(v) != "T"` guards the happy path, so the then-branch
        // accumulates coverage on the truthy side via inversion.
        let source = r#"pipeline t(task) {
  fn describe(v: unknown) -> string {
    if type_of(v) != "string" {
      // v still unknown here, but "string" is NOT ruled out on this path
      return "non-string"
    }
    // v: string here
    return v.upper()
  }
  log(describe("x"))
}"#;
        // No unreachable/throw so no warning regardless.
        assert!(exhaustive_warns(source).is_empty());
    }

    #[test]
    fn test_enum_construct_type_inference() {
        let errs = errors(
            r#"pipeline t(task) {
  enum Color { Red, Green, Blue }
  let c: Color = Color.Red
}"#,
        );
        assert!(errs.is_empty());
    }

    #[test]
    fn test_nil_coalescing_strips_nil() {
        // After ??, nil should be stripped from the type
        let errs = errors(
            r#"pipeline t(task) {
  let x: string | nil = nil
  let y: string = x ?? "default"
}"#,
        );
        assert!(errs.is_empty());
    }

    #[test]
    fn test_shape_mismatch_detail_missing_field() {
        let errs = errors(
            r#"pipeline t(task) {
  let x: {name: string, age: int} = {name: "hello"}
}"#,
        );
        assert_eq!(errs.len(), 1);
        assert!(
            errs[0].contains("missing field 'age'"),
            "expected detail about missing field, got: {}",
            errs[0]
        );
    }

    #[test]
    fn test_shape_mismatch_detail_wrong_type() {
        let errs = errors(
            r#"pipeline t(task) {
  let x: {name: string, age: int} = {name: 42, age: 10}
}"#,
        );
        assert_eq!(errs.len(), 1);
        assert!(
            errs[0].contains("field 'name' has type int, expected string"),
            "expected detail about wrong type, got: {}",
            errs[0]
        );
    }

    #[test]
    fn test_match_pattern_string_against_int() {
        let warns = warnings(
            r#"pipeline t(task) {
  let x: int = 42
  match x {
    "hello" -> { log("bad") }
    42 -> { log("ok") }
  }
}"#,
        );
        let pattern_warns: Vec<_> = warns
            .iter()
            .filter(|w| w.contains("Match pattern type mismatch"))
            .collect();
        assert_eq!(pattern_warns.len(), 1);
        assert!(pattern_warns[0].contains("matching int against string literal"));
    }

    #[test]
    fn test_match_pattern_int_against_string() {
        let warns = warnings(
            r#"pipeline t(task) {
  let x: string = "hello"
  match x {
    42 -> { log("bad") }
    "hello" -> { log("ok") }
  }
}"#,
        );
        let pattern_warns: Vec<_> = warns
            .iter()
            .filter(|w| w.contains("Match pattern type mismatch"))
            .collect();
        assert_eq!(pattern_warns.len(), 1);
        assert!(pattern_warns[0].contains("matching string against int literal"));
    }

    #[test]
    fn test_match_pattern_bool_against_int() {
        let warns = warnings(
            r#"pipeline t(task) {
  let x: int = 42
  match x {
    true -> { log("bad") }
    42 -> { log("ok") }
  }
}"#,
        );
        let pattern_warns: Vec<_> = warns
            .iter()
            .filter(|w| w.contains("Match pattern type mismatch"))
            .collect();
        assert_eq!(pattern_warns.len(), 1);
        assert!(pattern_warns[0].contains("matching int against bool literal"));
    }

    #[test]
    fn test_match_pattern_float_against_string() {
        let warns = warnings(
            r#"pipeline t(task) {
  let x: string = "hello"
  match x {
    3.14 -> { log("bad") }
    "hello" -> { log("ok") }
  }
}"#,
        );
        let pattern_warns: Vec<_> = warns
            .iter()
            .filter(|w| w.contains("Match pattern type mismatch"))
            .collect();
        assert_eq!(pattern_warns.len(), 1);
        assert!(pattern_warns[0].contains("matching string against float literal"));
    }

    #[test]
    fn test_match_pattern_int_against_float_ok() {
        // int and float are compatible for match patterns
        let warns = warnings(
            r#"pipeline t(task) {
  let x: float = 3.14
  match x {
    42 -> { log("ok") }
    _ -> { log("default") }
  }
}"#,
        );
        let pattern_warns: Vec<_> = warns
            .iter()
            .filter(|w| w.contains("Match pattern type mismatch"))
            .collect();
        assert!(pattern_warns.is_empty());
    }

    #[test]
    fn test_match_pattern_float_against_int_ok() {
        // float and int are compatible for match patterns
        let warns = warnings(
            r#"pipeline t(task) {
  let x: int = 42
  match x {
    3.14 -> { log("close") }
    _ -> { log("default") }
  }
}"#,
        );
        let pattern_warns: Vec<_> = warns
            .iter()
            .filter(|w| w.contains("Match pattern type mismatch"))
            .collect();
        assert!(pattern_warns.is_empty());
    }

    #[test]
    fn test_match_pattern_correct_types_no_warning() {
        let warns = warnings(
            r#"pipeline t(task) {
  let x: int = 42
  match x {
    1 -> { log("one") }
    2 -> { log("two") }
    _ -> { log("other") }
  }
}"#,
        );
        let pattern_warns: Vec<_> = warns
            .iter()
            .filter(|w| w.contains("Match pattern type mismatch"))
            .collect();
        assert!(pattern_warns.is_empty());
    }

    #[test]
    fn test_match_pattern_wildcard_no_warning() {
        let warns = warnings(
            r#"pipeline t(task) {
  let x: int = 42
  match x {
    _ -> { log("catch all") }
  }
}"#,
        );
        let pattern_warns: Vec<_> = warns
            .iter()
            .filter(|w| w.contains("Match pattern type mismatch"))
            .collect();
        assert!(pattern_warns.is_empty());
    }

    #[test]
    fn test_match_pattern_untyped_no_warning() {
        // When value has no known type, no warning should be emitted
        let warns = warnings(
            r#"pipeline t(task) {
  let x = some_unknown_fn()
  match x {
    "hello" -> { log("string") }
    42 -> { log("int") }
  }
}"#,
        );
        let pattern_warns: Vec<_> = warns
            .iter()
            .filter(|w| w.contains("Match pattern type mismatch"))
            .collect();
        assert!(pattern_warns.is_empty());
    }

    fn iface_errors(source: &str) -> Vec<String> {
        errors(source)
            .into_iter()
            .filter(|message| message.contains("does not satisfy interface"))
            .collect()
    }

    #[test]
    fn test_interface_constraint_return_type_mismatch() {
        let warns = iface_errors(
            r#"pipeline t(task) {
  interface Sizable {
    fn size(self) -> int
  }
  struct Box { width: int }
  impl Box {
    fn size(self) -> string { return "nope" }
  }
  fn measure<T>(item: T) where T: Sizable { log(item.size()) }
  measure(Box({width: 3}))
}"#,
        );
        assert_eq!(warns.len(), 1, "expected 1 warning, got: {:?}", warns);
        assert!(
            warns[0].contains("method 'size' returns 'string', expected 'int'"),
            "unexpected message: {}",
            warns[0]
        );
    }

    #[test]
    fn test_interface_constraint_param_type_mismatch() {
        let warns = iface_errors(
            r#"pipeline t(task) {
  interface Processor {
    fn process(self, x: int) -> string
  }
  struct MyProc { name: string }
  impl MyProc {
    fn process(self, x: string) -> string { return x }
  }
  fn run_proc<T>(p: T) where T: Processor { log(p.process(42)) }
  run_proc(MyProc({name: "a"}))
}"#,
        );
        assert_eq!(warns.len(), 1, "expected 1 warning, got: {:?}", warns);
        assert!(
            warns[0].contains("method 'process' parameter 1 has type 'string', expected 'int'"),
            "unexpected message: {}",
            warns[0]
        );
    }

    #[test]
    fn test_interface_constraint_missing_method() {
        let warns = iface_errors(
            r#"pipeline t(task) {
  interface Sizable {
    fn size(self) -> int
  }
  struct Box { width: int }
  impl Box {
    fn area(self) -> int { return self.width }
  }
  fn measure<T>(item: T) where T: Sizable { log(item.size()) }
  measure(Box({width: 3}))
}"#,
        );
        assert_eq!(warns.len(), 1, "expected 1 warning, got: {:?}", warns);
        assert!(
            warns[0].contains("missing method 'size'"),
            "unexpected message: {}",
            warns[0]
        );
    }

    #[test]
    fn test_interface_constraint_param_count_mismatch() {
        let warns = iface_errors(
            r#"pipeline t(task) {
  interface Doubler {
    fn double(self, x: int) -> int
  }
  struct Bad { v: int }
  impl Bad {
    fn double(self) -> int { return self.v * 2 }
  }
  fn run_double<T>(d: T) where T: Doubler { log(d.double(3)) }
  run_double(Bad({v: 5}))
}"#,
        );
        assert_eq!(warns.len(), 1, "expected 1 warning, got: {:?}", warns);
        assert!(
            warns[0].contains("method 'double' has 0 parameter(s), expected 1"),
            "unexpected message: {}",
            warns[0]
        );
    }

    #[test]
    fn test_interface_constraint_satisfied() {
        let warns = iface_errors(
            r#"pipeline t(task) {
  interface Sizable {
    fn size(self) -> int
  }
  struct Box { width: int, height: int }
  impl Box {
    fn size(self) -> int { return self.width * self.height }
  }
  fn measure<T>(item: T) where T: Sizable { log(item.size()) }
  measure(Box({width: 3, height: 4}))
}"#,
        );
        assert!(warns.is_empty(), "expected no warnings, got: {:?}", warns);
    }

    #[test]
    fn test_interface_constraint_untyped_impl_compatible() {
        // Gradual typing: untyped impl return should not trigger warning
        let warns = iface_errors(
            r#"pipeline t(task) {
  interface Sizable {
    fn size(self) -> int
  }
  struct Box { width: int }
  impl Box {
    fn size(self) { return self.width }
  }
  fn measure<T>(item: T) where T: Sizable { log(item.size()) }
  measure(Box({width: 3}))
}"#,
        );
        assert!(warns.is_empty(), "expected no warnings, got: {:?}", warns);
    }

    #[test]
    fn test_interface_constraint_int_float_covariance() {
        // int is compatible with float (covariance)
        let warns = iface_errors(
            r#"pipeline t(task) {
  interface Measurable {
    fn value(self) -> float
  }
  struct Gauge { v: int }
  impl Gauge {
    fn value(self) -> int { return self.v }
  }
  fn read_val<T>(g: T) where T: Measurable { log(g.value()) }
  read_val(Gauge({v: 42}))
}"#,
        );
        assert!(warns.is_empty(), "expected no warnings, got: {:?}", warns);
    }

    #[test]
    fn test_interface_associated_type_constraint_satisfied() {
        let warns = iface_errors(
            r#"pipeline t(task) {
  interface Collection {
    type Item
    fn get(self, index: int) -> Item
  }
  struct Names {}
  impl Names {
    fn get(self, index: int) -> string { return "ada" }
  }
  fn first<C>(collection: C) where C: Collection {
    log(collection.get(0))
  }
  first(Names {})
}"#,
        );
        assert!(warns.is_empty(), "expected no warnings, got: {:?}", warns);
    }

    #[test]
    fn test_interface_associated_type_default_mismatch() {
        let warns = iface_errors(
            r#"pipeline t(task) {
  interface IntCollection {
    type Item = int
    fn get(self, index: int) -> Item
  }
  struct Labels {}
  impl Labels {
    fn get(self, index: int) -> string { return "oops" }
  }
  fn first<C>(collection: C) where C: IntCollection {
    log(collection.get(0))
  }
  first(Labels {})
}"#,
        );
        assert_eq!(warns.len(), 1, "expected 1 warning, got: {:?}", warns);
        assert!(
            warns[0].contains("associated type 'Item' resolves to 'string', expected 'int'"),
            "unexpected message: {}",
            warns[0]
        );
    }

    #[test]
    fn test_nil_narrowing_then_branch() {
        // Existing behavior: x != nil narrows to string in then-branch
        let errs = errors(
            r#"pipeline t(task) {
  fn greet(name: string | nil) {
    if name != nil {
      let s: string = name
    }
  }
}"#,
        );
        assert!(errs.is_empty(), "got: {:?}", errs);
    }

    #[test]
    fn test_nil_narrowing_else_branch() {
        // NEW: x != nil narrows to nil in else-branch
        let errs = errors(
            r#"pipeline t(task) {
  fn check(x: string | nil) {
    if x != nil {
      let s: string = x
    } else {
      let n: nil = x
    }
  }
}"#,
        );
        assert!(errs.is_empty(), "got: {:?}", errs);
    }

    #[test]
    fn test_nil_equality_narrows_both() {
        // x == nil narrows then to nil, else to non-nil
        let errs = errors(
            r#"pipeline t(task) {
  fn check(x: string | nil) {
    if x == nil {
      let n: nil = x
    } else {
      let s: string = x
    }
  }
}"#,
        );
        assert!(errs.is_empty(), "got: {:?}", errs);
    }

    #[test]
    fn test_truthiness_narrowing() {
        // Bare identifier in condition removes nil
        let errs = errors(
            r#"pipeline t(task) {
  fn check(x: string | nil) {
    if x {
      let s: string = x
    }
  }
}"#,
        );
        assert!(errs.is_empty(), "got: {:?}", errs);
    }

    #[test]
    fn test_negation_narrowing() {
        // !x swaps truthy/falsy
        let errs = errors(
            r#"pipeline t(task) {
  fn check(x: string | nil) {
    if !x {
      let n: nil = x
    } else {
      let s: string = x
    }
  }
}"#,
        );
        assert!(errs.is_empty(), "got: {:?}", errs);
    }

    #[test]
    fn test_typeof_narrowing() {
        // type_of(x) == "string" narrows to string
        let errs = errors(
            r#"pipeline t(task) {
  fn check(x: string | int) {
    if type_of(x) == "string" {
      let s: string = x
    }
  }
}"#,
        );
        assert!(errs.is_empty(), "got: {:?}", errs);
    }

    #[test]
    fn test_typeof_narrowing_else() {
        // else removes the tested type
        let errs = errors(
            r#"pipeline t(task) {
  fn check(x: string | int) {
    if type_of(x) == "string" {
      let s: string = x
    } else {
      let i: int = x
    }
  }
}"#,
        );
        assert!(errs.is_empty(), "got: {:?}", errs);
    }

    #[test]
    fn test_typeof_neq_narrowing() {
        // type_of(x) != "string" removes string in then, narrows to string in else
        let errs = errors(
            r#"pipeline t(task) {
  fn check(x: string | int) {
    if type_of(x) != "string" {
      let i: int = x
    } else {
      let s: string = x
    }
  }
}"#,
        );
        assert!(errs.is_empty(), "got: {:?}", errs);
    }

    #[test]
    fn test_and_combines_narrowing() {
        // && combines truthy refinements
        let errs = errors(
            r#"pipeline t(task) {
  fn check(x: string | int | nil) {
    if x != nil && type_of(x) == "string" {
      let s: string = x
    }
  }
}"#,
        );
        assert!(errs.is_empty(), "got: {:?}", errs);
    }

    #[test]
    fn test_or_falsy_narrowing() {
        // || combines falsy refinements
        let errs = errors(
            r#"pipeline t(task) {
  fn check(x: string | nil, y: int | nil) {
    if x || y {
      // conservative: can't narrow
    } else {
      let xn: nil = x
      let yn: nil = y
    }
  }
}"#,
        );
        assert!(errs.is_empty(), "got: {:?}", errs);
    }

    #[test]
    fn test_guard_narrows_outer_scope() {
        let errs = errors(
            r#"pipeline t(task) {
  fn check(x: string | nil) {
    guard x != nil else { return }
    let s: string = x
  }
}"#,
        );
        assert!(errs.is_empty(), "got: {:?}", errs);
    }

    #[test]
    fn test_while_narrows_body() {
        let errs = errors(
            r#"pipeline t(task) {
  fn check(x: string | nil) {
    while x != nil {
      let s: string = x
      break
    }
  }
}"#,
        );
        assert!(errs.is_empty(), "got: {:?}", errs);
    }

    #[test]
    fn test_early_return_narrows_after_if() {
        // if then-body returns, falsy refinements apply after
        let errs = errors(
            r#"pipeline t(task) {
  fn check(x: string | nil) -> string {
    if x == nil {
      return "default"
    }
    let s: string = x
    return s
  }
}"#,
        );
        assert!(errs.is_empty(), "got: {:?}", errs);
    }

    #[test]
    fn test_early_throw_narrows_after_if() {
        let errs = errors(
            r#"pipeline t(task) {
  fn check(x: string | nil) {
    if x == nil {
      throw "missing"
    }
    let s: string = x
  }
}"#,
        );
        assert!(errs.is_empty(), "got: {:?}", errs);
    }

    #[test]
    fn test_no_narrowing_unknown_type() {
        // Gradual typing: untyped vars don't get narrowed
        let errs = errors(
            r#"pipeline t(task) {
  fn check(x) {
    if x != nil {
      let s: string = x
    }
  }
}"#,
        );
        // No narrowing possible, so assigning untyped x to string should be fine
        // (gradual typing allows it)
        assert!(errs.is_empty(), "got: {:?}", errs);
    }

    #[test]
    fn test_reassignment_invalidates_narrowing() {
        // After reassigning a narrowed var, the original type should be restored
        let errs = errors(
            r#"pipeline t(task) {
  fn check(x: string | nil) {
    var y: string | nil = x
    if y != nil {
      let s: string = y
      y = nil
      let s2: string = y
    }
  }
}"#,
        );
        // s2 should fail because y was reassigned, invalidating the narrowing
        assert_eq!(errs.len(), 1, "expected 1 error, got: {:?}", errs);
        assert!(
            errs[0].contains("declared as"),
            "expected type mismatch, got: {}",
            errs[0]
        );
    }

    #[test]
    fn test_let_immutable_warning() {
        let all = check_source(
            r#"pipeline t(task) {
  let x = 42
  x = 43
}"#,
        );
        let warnings: Vec<_> = all
            .iter()
            .filter(|d| d.severity == DiagnosticSeverity::Warning)
            .collect();
        assert!(
            warnings.iter().any(|w| w.message.contains("immutable")),
            "expected immutability warning, got: {:?}",
            warnings
        );
    }

    #[test]
    fn test_nested_narrowing() {
        let errs = errors(
            r#"pipeline t(task) {
  fn check(x: string | int | nil) {
    if x != nil {
      if type_of(x) == "int" {
        let i: int = x
      }
    }
  }
}"#,
        );
        assert!(errs.is_empty(), "got: {:?}", errs);
    }

    #[test]
    fn test_match_narrows_arms() {
        let errs = errors(
            r#"pipeline t(task) {
  fn check(x: string | int) {
    match x {
      "hello" -> {
        let s: string = x
      }
      42 -> {
        let i: int = x
      }
      _ -> {}
    }
  }
}"#,
        );
        assert!(errs.is_empty(), "got: {:?}", errs);
    }

    #[test]
    fn test_has_narrows_optional_field() {
        let errs = errors(
            r#"pipeline t(task) {
  fn check(x: {name?: string, age: int}) {
    if x.has("name") {
      let n: {name: string, age: int} = x
    }
  }
}"#,
        );
        assert!(errs.is_empty(), "got: {:?}", errs);
    }

    // -----------------------------------------------------------------------
    // Autofix tests
    // -----------------------------------------------------------------------

    fn check_source_with_source(source: &str) -> Vec<TypeDiagnostic> {
        let mut lexer = Lexer::new(source);
        let tokens = lexer.tokenize().unwrap();
        let mut parser = Parser::new(tokens);
        let program = parser.parse().unwrap();
        TypeChecker::new().check_with_source(&program, source)
    }

    #[test]
    fn test_fix_string_plus_int_literal() {
        let source = "pipeline t(task) {\n  let x = \"hello \" + 42\n  log(x)\n}";
        let diags = check_source_with_source(source);
        let fixable: Vec<_> = diags.iter().filter(|d| d.fix.is_some()).collect();
        assert_eq!(fixable.len(), 1, "expected 1 fixable diagnostic");
        let fix = fixable[0].fix.as_ref().unwrap();
        assert_eq!(fix.len(), 1);
        assert_eq!(fix[0].replacement, "\"hello ${42}\"");
    }

    #[test]
    fn test_fix_int_plus_string_literal() {
        let source = "pipeline t(task) {\n  let x = 42 + \"hello\"\n  log(x)\n}";
        let diags = check_source_with_source(source);
        let fixable: Vec<_> = diags.iter().filter(|d| d.fix.is_some()).collect();
        assert_eq!(fixable.len(), 1, "expected 1 fixable diagnostic");
        let fix = fixable[0].fix.as_ref().unwrap();
        assert_eq!(fix[0].replacement, "\"${42}hello\"");
    }

    #[test]
    fn test_fix_string_plus_variable() {
        let source = "pipeline t(task) {\n  let n: int = 5\n  let x = \"count: \" + n\n  log(x)\n}";
        let diags = check_source_with_source(source);
        let fixable: Vec<_> = diags.iter().filter(|d| d.fix.is_some()).collect();
        assert_eq!(fixable.len(), 1, "expected 1 fixable diagnostic");
        let fix = fixable[0].fix.as_ref().unwrap();
        assert_eq!(fix[0].replacement, "\"count: ${n}\"");
    }

    #[test]
    fn test_no_fix_int_plus_int() {
        // int + float should error but no interpolation fix
        let source = "pipeline t(task) {\n  let x: int = 5\n  let y: float = 3.0\n  let z = x - y\n  log(z)\n}";
        let diags = check_source_with_source(source);
        let fixable: Vec<_> = diags.iter().filter(|d| d.fix.is_some()).collect();
        assert!(
            fixable.is_empty(),
            "no fix expected for numeric ops, got: {fixable:?}"
        );
    }

    #[test]
    fn test_no_fix_without_source() {
        let source = "pipeline t(task) {\n  let x = \"hello \" + 42\n  log(x)\n}";
        let diags = check_source(source);
        let fixable: Vec<_> = diags.iter().filter(|d| d.fix.is_some()).collect();
        assert!(
            fixable.is_empty(),
            "without source, no fix should be generated"
        );
    }

    #[test]
    fn test_union_exhaustive_match_no_warning() {
        let warns = warnings(
            r#"pipeline t(task) {
  let x: string | int | nil = nil
  match x {
    "hello" -> { log("s") }
    42 -> { log("i") }
    nil -> { log("n") }
  }
}"#,
        );
        let union_warns: Vec<_> = warns
            .iter()
            .filter(|w| w.contains("Non-exhaustive match on union"))
            .collect();
        assert!(union_warns.is_empty());
    }

    #[test]
    fn test_union_non_exhaustive_match_warning() {
        let warns = warnings(
            r#"pipeline t(task) {
  let x: string | int | nil = nil
  match x {
    "hello" -> { log("s") }
    42 -> { log("i") }
  }
}"#,
        );
        let union_warns: Vec<_> = warns
            .iter()
            .filter(|w| w.contains("Non-exhaustive match on union"))
            .collect();
        assert_eq!(union_warns.len(), 1);
        assert!(union_warns[0].contains("nil"));
    }

    #[test]
    fn test_nil_coalesce_non_union_preserves_left_type() {
        // When left is a known non-nil type, ?? should preserve it
        let errs = errors(
            r#"pipeline t(task) {
  let x: int = 42
  let y: int = x ?? 0
}"#,
        );
        assert!(errs.is_empty());
    }

    #[test]
    fn test_nil_coalesce_nil_returns_right_type() {
        let errs = errors(
            r#"pipeline t(task) {
  let x: string = nil ?? "fallback"
}"#,
        );
        assert!(errs.is_empty());
    }

    #[test]
    fn test_never_is_subtype_of_everything() {
        let tc = TypeChecker::new();
        let scope = TypeScope::new();
        assert!(tc.types_compatible(&TypeExpr::Named("string".into()), &TypeExpr::Never, &scope));
        assert!(tc.types_compatible(&TypeExpr::Named("int".into()), &TypeExpr::Never, &scope));
        assert!(tc.types_compatible(
            &TypeExpr::Union(vec![
                TypeExpr::Named("string".into()),
                TypeExpr::Named("nil".into()),
            ]),
            &TypeExpr::Never,
            &scope,
        ));
    }

    #[test]
    fn test_nothing_is_subtype_of_never() {
        let tc = TypeChecker::new();
        let scope = TypeScope::new();
        assert!(!tc.types_compatible(&TypeExpr::Never, &TypeExpr::Named("string".into()), &scope));
        assert!(!tc.types_compatible(&TypeExpr::Never, &TypeExpr::Named("int".into()), &scope));
    }

    #[test]
    fn test_never_never_compatible() {
        let tc = TypeChecker::new();
        let scope = TypeScope::new();
        assert!(tc.types_compatible(&TypeExpr::Never, &TypeExpr::Never, &scope));
    }

    #[test]
    fn test_any_is_top_type_bidirectional() {
        let tc = TypeChecker::new();
        let scope = TypeScope::new();
        let any = TypeExpr::Named("any".into());
        // Every concrete type flows into any.
        assert!(tc.types_compatible(&any, &TypeExpr::Named("string".into()), &scope));
        assert!(tc.types_compatible(&any, &TypeExpr::Named("int".into()), &scope));
        assert!(tc.types_compatible(&any, &TypeExpr::Named("nil".into()), &scope));
        assert!(tc.types_compatible(
            &any,
            &TypeExpr::List(Box::new(TypeExpr::Named("int".into()))),
            &scope
        ));
        // any flows back out to every concrete type (escape hatch).
        assert!(tc.types_compatible(&TypeExpr::Named("string".into()), &any, &scope));
        assert!(tc.types_compatible(&TypeExpr::Named("nil".into()), &any, &scope));
    }

    #[test]
    fn test_unknown_is_safe_top_one_way() {
        let tc = TypeChecker::new();
        let scope = TypeScope::new();
        let unknown = TypeExpr::Named("unknown".into());
        // Every concrete type flows into unknown.
        assert!(tc.types_compatible(&unknown, &TypeExpr::Named("string".into()), &scope));
        assert!(tc.types_compatible(&unknown, &TypeExpr::Named("nil".into()), &scope));
        assert!(tc.types_compatible(
            &unknown,
            &TypeExpr::List(Box::new(TypeExpr::Named("int".into()))),
            &scope
        ));
        // unknown does NOT flow back out to concrete types without narrowing.
        assert!(!tc.types_compatible(&TypeExpr::Named("string".into()), &unknown, &scope));
        assert!(!tc.types_compatible(&TypeExpr::Named("int".into()), &unknown, &scope));
        // unknown is compatible with itself.
        assert!(tc.types_compatible(&unknown, &unknown, &scope));
        // unknown flows into any (any accepts everything).
        assert!(tc.types_compatible(&TypeExpr::Named("any".into()), &unknown, &scope));
    }

    #[test]
    fn test_unknown_narrows_via_type_of() {
        // Concrete narrowing behavior is covered end-to-end by the conformance
        // test `unknown_narrowing.harn`; this unit test guards against the
        // refinement path silently regressing to "no narrowing" for named
        // unknown types.
        let errs = errors(
            r#"pipeline t(task) {
  fn f(v: unknown) -> string {
    if type_of(v) == "string" {
      return v
    }
    return "other"
  }
  log(f("hi"))
}"#,
        );
        assert!(
            errs.is_empty(),
            "unknown should narrow to string inside type_of guard: {errs:?}"
        );
    }

    #[test]
    fn test_unknown_without_narrowing_errors() {
        let errs = errors(
            r#"pipeline t(task) {
  let u: unknown = "hello"
  let s: string = u
}"#,
        );
        assert!(
            errs.iter().any(|e| e.contains("unknown")),
            "expected an error mentioning unknown, got: {errs:?}"
        );
    }

    #[test]
    fn test_simplify_union_removes_never() {
        assert_eq!(
            simplify_union(vec![TypeExpr::Never, TypeExpr::Named("string".into())]),
            TypeExpr::Named("string".into()),
        );
        assert_eq!(
            simplify_union(vec![TypeExpr::Never, TypeExpr::Never]),
            TypeExpr::Never,
        );
        assert_eq!(
            simplify_union(vec![
                TypeExpr::Named("string".into()),
                TypeExpr::Never,
                TypeExpr::Named("int".into()),
            ]),
            TypeExpr::Union(vec![
                TypeExpr::Named("string".into()),
                TypeExpr::Named("int".into()),
            ]),
        );
    }

    #[test]
    fn test_remove_from_union_exhausted_returns_never() {
        let result = remove_from_union(&[TypeExpr::Named("string".into())], "string");
        assert_eq!(result, Some(TypeExpr::Never));
    }

    #[test]
    fn test_if_else_one_branch_throws_infers_other() {
        // if/else where else throws — result should be int (from then-branch)
        let errs = errors(
            r#"pipeline t(task) {
  fn foo(x: bool) -> int {
    let result: int = if x { 42 } else { throw "err" }
    return result
  }
}"#,
        );
        assert!(errs.is_empty(), "unexpected errors: {errs:?}");
    }

    #[test]
    fn test_if_else_both_branches_throw_infers_never() {
        // Both branches exit — should infer never, which is assignable to anything
        let errs = errors(
            r#"pipeline t(task) {
  fn foo(x: bool) -> string {
    let result: string = if x { throw "a" } else { throw "b" }
    return result
  }
}"#,
        );
        assert!(errs.is_empty(), "unexpected errors: {errs:?}");
    }

    #[test]
    fn test_unreachable_after_return() {
        let warns = warnings(
            r#"pipeline t(task) {
  fn foo() -> int {
    return 1
    let x = 2
  }
}"#,
        );
        assert!(
            warns.iter().any(|w| w.contains("unreachable")),
            "expected unreachable warning: {warns:?}"
        );
    }

    #[test]
    fn test_unreachable_after_throw() {
        let warns = warnings(
            r#"pipeline t(task) {
  fn foo() {
    throw "err"
    let x = 2
  }
}"#,
        );
        assert!(
            warns.iter().any(|w| w.contains("unreachable")),
            "expected unreachable warning: {warns:?}"
        );
    }

    #[test]
    fn test_unreachable_after_composite_exit() {
        let warns = warnings(
            r#"pipeline t(task) {
  fn foo(x: bool) {
    if x { return 1 } else { throw "err" }
    let y = 2
  }
}"#,
        );
        assert!(
            warns.iter().any(|w| w.contains("unreachable")),
            "expected unreachable warning: {warns:?}"
        );
    }

    #[test]
    fn test_no_unreachable_warning_when_reachable() {
        let warns = warnings(
            r#"pipeline t(task) {
  fn foo(x: bool) {
    if x { return 1 }
    let y = 2
  }
}"#,
        );
        assert!(
            !warns.iter().any(|w| w.contains("unreachable")),
            "unexpected unreachable warning: {warns:?}"
        );
    }

    #[test]
    fn test_catch_typed_error_variable() {
        // When catch has a type annotation, the error var should be typed
        let errs = errors(
            r#"pipeline t(task) {
  enum AppError { NotFound, Timeout }
  try {
    throw AppError.NotFound
  } catch (e: AppError) {
    let x: AppError = e
  }
}"#,
        );
        assert!(errs.is_empty(), "unexpected errors: {errs:?}");
    }

    #[test]
    fn test_unreachable_with_never_arg_no_error() {
        // After exhaustive narrowing, unreachable(x) should pass
        let errs = errors(
            r#"pipeline t(task) {
  fn foo(x: string | int) {
    if type_of(x) == "string" { return }
    if type_of(x) == "int" { return }
    unreachable(x)
  }
}"#,
        );
        assert!(
            !errs.iter().any(|e| e.contains("unreachable")),
            "unexpected unreachable error: {errs:?}"
        );
    }

    #[test]
    fn test_unreachable_with_remaining_types_errors() {
        // Non-exhaustive narrowing — unreachable(x) should error
        let errs = errors(
            r#"pipeline t(task) {
  fn foo(x: string | int | nil) {
    if type_of(x) == "string" { return }
    unreachable(x)
  }
}"#,
        );
        assert!(
            errs.iter()
                .any(|e| e.contains("unreachable") && e.contains("not all cases")),
            "expected unreachable error about remaining types: {errs:?}"
        );
    }

    #[test]
    fn test_unreachable_no_args_no_compile_error() {
        let errs = errors(
            r#"pipeline t(task) {
  fn foo() {
    unreachable()
  }
}"#,
        );
        assert!(
            !errs
                .iter()
                .any(|e| e.contains("unreachable") && e.contains("not all cases")),
            "unreachable() with no args should not produce type error: {errs:?}"
        );
    }

    #[test]
    fn test_never_type_annotation_parses() {
        let errs = errors(
            r#"pipeline t(task) {
  fn foo() -> never {
    throw "always throws"
  }
}"#,
        );
        assert!(errs.is_empty(), "unexpected errors: {errs:?}");
    }

    #[test]
    fn test_format_type_never() {
        assert_eq!(format_type(&TypeExpr::Never), "never");
    }

    // ── Strict types mode tests ──────────────────────────────────────

    fn check_source_strict(source: &str) -> Vec<TypeDiagnostic> {
        let mut lexer = Lexer::new(source);
        let tokens = lexer.tokenize().unwrap();
        let mut parser = Parser::new(tokens);
        let program = parser.parse().unwrap();
        TypeChecker::with_strict_types(true).check(&program)
    }

    fn strict_warnings(source: &str) -> Vec<String> {
        check_source_strict(source)
            .into_iter()
            .filter(|d| d.severity == DiagnosticSeverity::Warning)
            .map(|d| d.message)
            .collect()
    }

    #[test]
    fn test_strict_types_json_parse_property_access() {
        let warns = strict_warnings(
            r#"pipeline t(task) {
  let data = json_parse("{}")
  log(data.name)
}"#,
        );
        assert!(
            warns.iter().any(|w| w.contains("unvalidated")),
            "expected unvalidated warning, got: {warns:?}"
        );
    }

    #[test]
    fn test_strict_types_direct_chain_access() {
        let warns = strict_warnings(
            r#"pipeline t(task) {
  log(json_parse("{}").name)
}"#,
        );
        assert!(
            warns.iter().any(|w| w.contains("Direct property access")),
            "expected direct access warning, got: {warns:?}"
        );
    }

    #[test]
    fn test_strict_types_schema_expect_clears() {
        let warns = strict_warnings(
            r#"pipeline t(task) {
  let my_schema = {type: "object", properties: {name: {type: "string"}}}
  let data = json_parse("{}")
  schema_expect(data, my_schema)
  log(data.name)
}"#,
        );
        assert!(
            !warns.iter().any(|w| w.contains("unvalidated")),
            "expected no unvalidated warning after schema_expect, got: {warns:?}"
        );
    }

    #[test]
    fn test_strict_types_schema_is_if_guard() {
        let warns = strict_warnings(
            r#"pipeline t(task) {
  let my_schema = {type: "object", properties: {name: {type: "string"}}}
  let data = json_parse("{}")
  if schema_is(data, my_schema) {
    log(data.name)
  }
}"#,
        );
        assert!(
            !warns.iter().any(|w| w.contains("unvalidated")),
            "expected no unvalidated warning inside schema_is guard, got: {warns:?}"
        );
    }

    #[test]
    fn test_strict_types_shape_annotation_clears() {
        let warns = strict_warnings(
            r#"pipeline t(task) {
  let data: {name: string, age: int} = json_parse("{}")
  log(data.name)
}"#,
        );
        assert!(
            !warns.iter().any(|w| w.contains("unvalidated")),
            "expected no warning with shape annotation, got: {warns:?}"
        );
    }

    #[test]
    fn test_strict_types_propagation() {
        let warns = strict_warnings(
            r#"pipeline t(task) {
  let data = json_parse("{}")
  let x = data
  log(x.name)
}"#,
        );
        assert!(
            warns
                .iter()
                .any(|w| w.contains("unvalidated") && w.contains("'x'")),
            "expected propagation warning for x, got: {warns:?}"
        );
    }

    #[test]
    fn test_strict_types_non_boundary_no_warning() {
        let warns = strict_warnings(
            r#"pipeline t(task) {
  let x = len("hello")
  log(x)
}"#,
        );
        assert!(
            !warns.iter().any(|w| w.contains("unvalidated")),
            "non-boundary function should not be flagged, got: {warns:?}"
        );
    }

    #[test]
    fn test_strict_types_subscript_access() {
        let warns = strict_warnings(
            r#"pipeline t(task) {
  let data = json_parse("{}")
  log(data["name"])
}"#,
        );
        assert!(
            warns.iter().any(|w| w.contains("unvalidated")),
            "expected subscript warning, got: {warns:?}"
        );
    }

    #[test]
    fn test_strict_types_disabled_by_default() {
        let diags = check_source(
            r#"pipeline t(task) {
  let data = json_parse("{}")
  log(data.name)
}"#,
        );
        assert!(
            !diags.iter().any(|d| d.message.contains("unvalidated")),
            "strict types should be off by default, got: {diags:?}"
        );
    }

    #[test]
    fn test_strict_types_llm_call_without_schema() {
        let warns = strict_warnings(
            r#"pipeline t(task) {
  let result = llm_call("prompt", "system")
  log(result.text)
}"#,
        );
        assert!(
            warns.iter().any(|w| w.contains("unvalidated")),
            "llm_call without schema should warn, got: {warns:?}"
        );
    }

    #[test]
    fn test_strict_types_llm_call_with_schema_clean() {
        let warns = strict_warnings(
            r#"pipeline t(task) {
  let result = llm_call("prompt", "system", {
    schema: {type: "object", properties: {name: {type: "string"}}}
  })
  log(result.data)
  log(result.text)
}"#,
        );
        assert!(
            !warns.iter().any(|w| w.contains("unvalidated")),
            "llm_call with schema should not warn, got: {warns:?}"
        );
    }

    #[test]
    fn test_strict_types_schema_expect_result_typed() {
        let warns = strict_warnings(
            r#"pipeline t(task) {
  let my_schema = {type: "object", properties: {name: {type: "string"}}}
  let validated = schema_expect(json_parse("{}"), my_schema)
  log(validated.name)
}"#,
        );
        assert!(
            !warns.iter().any(|w| w.contains("unvalidated")),
            "schema_expect result should be typed, got: {warns:?}"
        );
    }

    #[test]
    fn test_strict_types_realistic_orchestration() {
        let warns = strict_warnings(
            r#"pipeline t(task) {
  let payload_schema = {type: "object", properties: {
    name: {type: "string"},
    steps: {type: "list", items: {type: "string"}}
  }}

  // Good: schema-aware llm_call
  let result = llm_call("generate a workflow", "system", {
    schema: payload_schema
  })
  let workflow_name = result.data.name

  // Good: validate then access
  let raw = json_parse("{}")
  schema_expect(raw, payload_schema)
  let steps = raw.steps

  log(workflow_name)
  log(steps)
}"#,
        );
        assert!(
            !warns.iter().any(|w| w.contains("unvalidated")),
            "validated orchestration should be clean, got: {warns:?}"
        );
    }

    #[test]
    fn test_strict_types_llm_call_with_schema_via_variable() {
        let warns = strict_warnings(
            r#"pipeline t(task) {
  let my_schema = {type: "object", properties: {score: {type: "float"}}}
  let result = llm_call("rate this", "system", {
    schema: my_schema
  })
  log(result.data.score)
}"#,
        );
        assert!(
            !warns.iter().any(|w| w.contains("unvalidated")),
            "llm_call with schema variable should not warn, got: {warns:?}"
        );
    }
}